dotnet-json-refs

TypeScript utility to resolve .NET System.Text.Json circular references ($id/$ref format) into actual JavaScript circular references.

Problem

When .NET's System.Text.Json serializes objects with circular references using ReferenceHandler.Preserve, it produces JSON with $id and $ref metadata:

{
  "$id": "1",
  "name": "Parent",
  "children": {
    "$id": "2",
    "$values": [
      {
        "$id": "3",
        "name": "Child",
        "parent": { "$ref": "1" }
      }
    ]
  }
}

JavaScript cannot natively deserialize this format into proper circular references.

Solution

This library resolves $id/$ref references into actual JavaScript object references, restoring the circular structure.

Installation

npm install dotnet-json-refs

Usage

Direct resolution

import { resolveRefs } from 'dotnet-json-refs';

const response = await fetch('/api/posts');
const data = await response.json();
const resolved = resolveRefs(data);

With promise wrapper

import { withRefResolution } from 'dotnet-json-refs';

const posts = await withRefResolution(
  fetch('/api/posts').then(r => r.json())
);

With generated API client

import { resolveRefs } from 'dotnet-json-refs';

const posts = await postsClient.getPosts();
const resolved = resolveRefs(posts);

Features

• ✅ Resolves $id and $ref circular references
• ✅ Handles $values array wrapper from System.Text.Json
• ✅ Type-safe with TypeScript generics
• ✅ Zero dependencies
• ✅ Works with any HTTP client

License

MIT