Koadz Platform - JSON Reference Manager

The RefManager class is a core utility in the Koadz Platform for managing JSON references. It provides functionality to load, resolve, and manipulate references within JSON files.

Features

• Load and parse JSON files.
• Resolve references within JSON objects.
• Manage and emit events for reference updates.
• Retrieve all references as a map.
• Save all changes to references.
• Plugins for customizing behavior.

Installation

To use the RefManager class, install the @koadz/ref-manager package using npm or yarn:

npm install @koadz/ref-manager
Copy

Usage Examples

API Usage

import { RefManager } from "@koadz/ref-manager";

const jsonDoc = {
  $ref: "/api/v1/assets/schema/project.json",
};

const options = {
  type: "api",
  baseUrl: "https://example.com",
};

const refManager = new RefManager(jsonDoc);

// Note: The `init` method must be called before using the `RefManager` instance
await refManager.init();

// Output: Resolved JSON document with references replaced
const document = refManager.resolvedDocument;
console.log(document);

await refManager.updatePropertyByRefId("<pass $ref>", ["address", "street"], "456 Elm St");
console.log(refManager.getDocumentByRefId("<pass $ref>"));
Copy

File Usage

import { RefManager } from "@koadz/ref-manager";

const jsonDoc = {
  properties: {
    name: {
      $ref: "/file/path/schema.json",
    },
  },
};

const refOptions = {
  resolver: {
    type: "file",
    basePath: "/base/path",
  },
  maxDepth: 5,
};

const refManager = await new RefManager(jsonDoc, refOptions).init();
const document = await refManager.resolvedDocument;
const refMap = await refManager.getAllRefsMap();
const refIds = refMap.keys();

// Output: Resolved JSON document with references replaced
console.log(refIds);
console.log(document);
Copy

Saving Changes

const updatedDocument = await refManager.saveAllChanges();
console.log("All changes saved:", updatedDocument);
Copy

Retrieving All References

const references = refManager.getAllRefsMap();
console.log(references); // A map of all references and their details
Copy

API Documentation

RefManager Class

• constructor(document: any, options?: RefManagerConfig): Creates a new instance of the RefManager class.

• init(): Initializes the RefManager instance and returns a promise with the instance once initialized.

  Must be called before performing operations that depend on resolved references.

• resolveAllRefs(maxDepth?: number): Resolves all references in the document and returns a promise with the resolved document.

• updateRef(refId: string, newValue: any): Updates the value of a reference and emits a refUpdated event.

• updatePropertyByRefId(refId: string, propertyPath: string[], newValue: any): Updates a nested property within a reference and returns a promise with the updated value.

• getDocumentByRefId(refId: string): Retrieves the resolved document for a specific reference ID.

• getAllRefsMap(): Returns a map of all references and their details.

• saveAllChanges(): Saves all dirty references and returns the updated document.

RefManagerConfig

• resolver: IResolverAdapter: The resolver adapter to use for resolving references.
• maxDepth?: number: The maximum depth to resolve references.
• concurrency?: number: The concurrency level for resolving references.
• onDocumentChanged?: (document: Document) => void: Callback triggered when the document changes.
• onDocumentSave?: (document: Document) => Promise<void>: Callback triggered when the document is saved.
• onRefSave?: (refId: string, value: any) => Promise<void>: Callback triggered when a reference is saved.
• cache?: RefManagerCacheOptions: Options for the cache manager.

Resolvers

Resolvers Documentation

Plugins

Plugins Documentation