@carbonenginejs/runtime-resource 0.9.2 → 0.10.0

package/dist/CjsResManFetchProvider.js

@@ -0,0 +1,94 @@
+import { Operation } from './worker/protocol.js';
+
+const FETCH_OPTION_KEYS = Object.freeze(["body", "cache", "credentials", "duplex", "headers", "integrity", "keepalive", "method", "mode", "priority", "redirect", "referrer", "referrerPolicy", "window"]);
+
+/**
+ * `CjsResMan` provider that fetches an already-resolved URL on the caller
+ * thread or through the resource worker.
+ */
+class CjsResManFetchProvider {
+  /** Creates a CjsResManFetchProvider with caller-provided fetch policy. */
+  constructor(options = {}) {
+    this.fetch = options.fetch || globalThis.fetch;
+    this.fetchOptions = options.fetchOptions || null;
+    this.workerEnabled = options.worker !== false && (options.fetch === undefined || options.worker === true);
+  }
+
+  /**
+   * Fetches bytes for a URL already resolved by CjsResMan.
+   *
+   * @param {string} url Resolved source URL.
+   * @param {object} [options={}] Resource and fetch options.
+   * @returns {Promise<ArrayBuffer>} Response bytes.
+   */
+  async Read(url, options = {}) {
+    if (typeof this.fetch !== "function") {
+      throw new TypeError("CjsResManFetchProvider requires a fetch implementation.");
+    }
+    const fetchOptions = getCloneableFetchOptions(this.fetchOptions, options.fetchOptions || options);
+    if (options.signal) fetchOptions.signal = options.signal;
+    const response = await this.fetch(url, fetchOptions);
+    if (!response.ok) {
+      const error = new Error(`Resource fetch failed: ${response.status} ${response.statusText}`);
+      error.code = "CJS_RESOURCE_FETCH_FAILED";
+      error.path = options.resourcePath || url;
+      error.url = url;
+      error.status = response.status;
+      throw error;
+    }
+    return response.arrayBuffer();
+  }
+
+  /**
+   * Describe the equivalent cloneable worker fetch operation.
+   *
+   * An injected fetch implementation stays on the caller thread unless the
+   * source explicitly opts into worker fetch with `{ worker: true }`.
+   *
+   * @param {string} url URL already resolved by CjsResMan.
+   * @param {object} [options={}] Resource and fetch options.
+   * @returns {object|null} Worker operation, or `null` when worker fetch is disabled.
+   */
+  CreateWorkerRequest(url, options = {}) {
+    if (!this.workerEnabled) return null;
+    return {
+      operation: Operation.FETCH,
+      payload: {
+        url,
+        path: options.resourcePath || url,
+        responseType: "arraybuffer",
+        options: getCloneableFetchOptions(this.fetchOptions, options.fetchOptions || options)
+      },
+      signal: options.signal || null
+    };
+  }
+
+  /** Signals that CjsResMan must resolve resource paths before provider reads. */
+  static requiresUrl = true;
+}
+function getCloneableFetchOptions(defaults, options) {
+  const result = {};
+  for (const source of [defaults, options]) {
+    if (!source || typeof source !== "object") continue;
+    for (const key of FETCH_OPTION_KEYS) {
+      if (source[key] === undefined) continue;
+      result[key] = key === "headers" ? normalizeFetchHeaders(source[key]) : source[key];
+    }
+  }
+  return result;
+}
+function normalizeFetchHeaders(value) {
+  if (!value || typeof value !== "object") return value;
+  if (Array.isArray(value)) {
+    return value.map(entry => Array.isArray(entry) ? [...entry] : entry);
+  }
+  if (typeof value.entries === "function") {
+    return [...value.entries()];
+  }
+  return {
+    ...value
+  };
+}
+
+export { CjsResManFetchProvider };
+//# sourceMappingURL=CjsResManFetchProvider.js.map

package/dist/CjsResManFetchProvider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CjsResManFetchProvider.js","sources":["../../src/CjsResManFetchProvider.js"],"sourcesContent":["import { Operation } from \"./worker/protocol.js\";\n\nconst FETCH_OPTION_KEYS = Object.freeze([\n  \"body\",\n  \"cache\",\n  \"credentials\",\n  \"duplex\",\n  \"headers\",\n  \"integrity\",\n  \"keepalive\",\n  \"method\",\n  \"mode\",\n  \"priority\",\n  \"redirect\",\n  \"referrer\",\n  \"referrerPolicy\",\n  \"window\"\n]);\n\n/**\n * `CjsResMan` provider that fetches an already-resolved URL on the caller\n * thread or through the resource worker.\n */\nexport class CjsResManFetchProvider\n{\n  /** Creates a CjsResManFetchProvider with caller-provided fetch policy. */\n  constructor(options = {})\n  {\n    this.fetch = options.fetch || globalThis.fetch;\n    this.fetchOptions = options.fetchOptions || null;\n    this.workerEnabled = options.worker !== false\n      && (options.fetch === undefined || options.worker === true);\n  }\n\n  /**\n   * Fetches bytes for a URL already resolved by CjsResMan.\n   *\n   * @param {string} url Resolved source URL.\n   * @param {object} [options={}] Resource and fetch options.\n   * @returns {Promise<ArrayBuffer>} Response bytes.\n   */\n  async Read(url, options = {})\n  {\n    if (typeof this.fetch !== \"function\")\n    {\n      throw new TypeError(\"CjsResManFetchProvider requires a fetch implementation.\");\n    }\n\n    const fetchOptions = getCloneableFetchOptions(\n      this.fetchOptions,\n      options.fetchOptions || options\n    );\n    if (options.signal) fetchOptions.signal = options.signal;\n    const response = await this.fetch(url, fetchOptions);\n    if (!response.ok)\n    {\n      const error = new Error(`Resource fetch failed: ${response.status} ${response.statusText}`);\n      error.code = \"CJS_RESOURCE_FETCH_FAILED\";\n      error.path = options.resourcePath || url;\n      error.url = url;\n      error.status = response.status;\n      throw error;\n    }\n\n    return response.arrayBuffer();\n  }\n\n  /**\n   * Describe the equivalent cloneable worker fetch operation.\n   *\n   * An injected fetch implementation stays on the caller thread unless the\n   * source explicitly opts into worker fetch with `{ worker: true }`.\n   *\n   * @param {string} url URL already resolved by CjsResMan.\n   * @param {object} [options={}] Resource and fetch options.\n   * @returns {object|null} Worker operation, or `null` when worker fetch is disabled.\n   */\n  CreateWorkerRequest(url, options = {})\n  {\n    if (!this.workerEnabled) return null;\n    return {\n      operation: Operation.FETCH,\n      payload: {\n        url,\n        path: options.resourcePath || url,\n        responseType: \"arraybuffer\",\n        options: getCloneableFetchOptions(this.fetchOptions, options.fetchOptions || options)\n      },\n      signal: options.signal || null\n    };\n  }\n\n  /** Signals that CjsResMan must resolve resource paths before provider reads. */\n  static requiresUrl = true;\n}\n\nfunction getCloneableFetchOptions(defaults, options) {\n  const result = {};\n  for (const source of [ defaults, options ]) {\n    if (!source || typeof source !== \"object\") continue;\n    for (const key of FETCH_OPTION_KEYS) {\n      if (source[key] === undefined) continue;\n      result[key] = key === \"headers\"\n        ? normalizeFetchHeaders(source[key])\n        : source[key];\n    }\n  }\n  return result;\n}\n\nfunction normalizeFetchHeaders(value) {\n  if (!value || typeof value !== \"object\") return value;\n  if (Array.isArray(value)) {\n    return value.map(entry => Array.isArray(entry) ? [ ...entry ] : entry);\n  }\n  if (typeof value.entries === \"function\") {\n    return [ ...value.entries() ];\n  }\n  return { ...value };\n}\n"],"names":["FETCH_OPTION_KEYS","Object","freeze","CjsResManFetchProvider","constructor","options","fetch","globalThis","fetchOptions","workerEnabled","worker","undefined","Read","url","TypeError","getCloneableFetchOptions","signal","response","ok","error","Error","status","statusText","code","path","resourcePath","arrayBuffer","CreateWorkerRequest","operation","Operation","FETCH","payload","responseType","requiresUrl","defaults","result","source","key","normalizeFetchHeaders","value","Array","isArray","map","entry","entries"],"mappings":"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"}

package/dist/{CjsResManQueue.js → CjsResManWorkQueue.js}

@@ -4,25 +4,13 @@ const CjsResManQueue = Object.freeze({
   PREPARE: "main",
   LOAD: "background"
 });
-function NormalizeCjsResManQueue(value) {
-  const name = String(value ?? "").trim().toLowerCase();
-  if (name === "main" || name === "prepare") return CjsResManQueue.MAIN;
-  if (name === "background" || name === "load") return CjsResManQueue.BACKGROUND;
-  throw new TypeError(`Unknown CjsResMan queue: ${value}`);
-}
-function CjsResManQueueCancelledError(queue, id, reason = "") {
-  const error = new Error(`CjsResMan ${queue} queue item ${id} was cancelled.${reason ? ` ${reason}` : ""}`);
-  error.code = "CJS_RESMAN_QUEUE_CANCELLED";
-  error.queue = queue;
-  error.id = id;
-  return error;
-}
 
 /**
- * Small FIFO executor used internally by CjsResMan.
+ * Small FIFO executor used inside `CjsResMan` that tracks item ids, pause
+ * state, concurrency, cancellation, and sync/async completion while queue
+ * policy stays in the manager.
  *
- * Queue policy stays in the manager. This class only tracks ids, pause state,
- * concurrency, cancellation, and sync/async completion.
+ * The queue deliberately does not choose task priority or resource policy.
  */
 class CjsResManWorkQueue {
   #active = new Map();
@@ -34,11 +22,18 @@ class CjsResManWorkQueue {
   #onReady;
   #paused = false;
   #queued = new Map();
+
+  /** Creates a CjsResManWorkQueue with caller-provided initial state. */
   constructor(name, options = {}) {
-    this.#name = NormalizeCjsResManQueue(name);
+    this.#name = CjsResManWorkQueue.normalizeName(name);
     this.#onReady = typeof options.onReady === "function" ? options.onReady : null;
     this.SetConcurrency(options.concurrency ?? 1);
   }
+
+  /**
+   * Updates the maximum number of tasks that may run together for the resource
+   * work queue.
+   */
   SetConcurrency(value) {
     if (!Number.isInteger(value) || value < 1) {
       throw new TypeError("CjsResMan queue concurrency must be a positive integer.");
@@ -47,24 +42,53 @@ class CjsResManWorkQueue {
     this.#NotifyReady();
     return this;
   }
+
+  /**
+   * Returns the maximum number of tasks allowed to run together for the resource
+   * work queue.
+   */
   GetConcurrency() {
     return this.#concurrency;
   }
+
+  /**
+   * Allocates the next monotonically increasing task identifier for the resource
+   * work queue.
+   */
   GetNextId() {
     return this.#nextId;
   }
+
+  /** Returns the number of tasks waiting to start for the resource work queue. */
   GetQueuedCount() {
     return this.#queued.size;
   }
+
+  /** Returns the number of tasks currently executing for the resource work queue. */
   GetActiveCount() {
     return this.#active.size;
   }
+
+  /**
+   * Returns the combined number of waiting and active tasks for the resource
+   * work queue.
+   */
   GetPendingCount() {
     return this.#queued.size + this.#active.size;
   }
+
+  /**
+   * Reports whether the queue is prevented from starting work for the resource
+   * work queue.
+   */
   IsPaused() {
     return this.#paused;
   }
+
+  /**
+   * Enqueues one task and returns its cancellation-aware promise for the
+   * resource work queue.
+   */
   Add(callback, context = null, metadata = null) {
     if (typeof callback !== "function") {
       throw new TypeError("CjsResMan queue items require a callback.");
@@ -92,35 +116,51 @@ class CjsResManWorkQueue {
     this.#NotifyReady();
     return item;
   }
+
+  /**
+   * Cancels a queued task selected by its identifier for the resource work
+   * queue.
+   */
   Cancel(id, reason = "") {
     const item = this.#queued.get(id);
     if (!item) return false;
     this.#queued.delete(id);
     item.state = "cancelled";
-    item.reject(CjsResManQueueCancelledError(this.#name, id, reason));
+    item.reject(CjsResManWorkQueue.createCancelledError(this.#name, id, reason));
     this.#Compact();
     return true;
   }
+
+  /**
+   * Prevents queued tasks from starting until resumed for the resource work
+   * queue.
+   */
   Pause() {
     this.#paused = true;
     return this;
   }
+
+  /** Allows queued tasks to start after a pause for the resource work queue. */
   Resume() {
     if (!this.#paused) return this;
     this.#paused = false;
     this.#NotifyReady();
     return this;
   }
+
+  /** Cancels every task that has not started for the resource work queue. */
   Clear(reason = "Queue cleared.") {
     const ids = [...this.#queued.keys()];
     for (const id of ids) this.Cancel(id, reason);
     this.#Compact(true);
     return ids.length;
   }
+
+  /** Starts queued work while concurrency permits for the resource work queue. */
   Pump(options = {}) {
-    const maxItems = NormalizeLimit(options.maxItems);
-    const maxTime = NormalizeLimit(options.maxTime);
-    const now = typeof options.now === "function" ? options.now : DefaultNow;
+    const maxItems = normalizeLimit(options.maxItems);
+    const maxTime = normalizeLimit(options.maxTime);
+    const now = typeof options.now === "function" ? options.now : defaultNow;
     const startedAt = now();
     let processed = 0;
     if (!this.#paused) {
@@ -141,6 +181,11 @@ class CjsResManWorkQueue {
       paused: this.#paused
     });
   }
+
+  /**
+   * Returns an immutable snapshot of queue counts and policy for the resource
+   * work queue.
+   */
   GetStats() {
     return Object.freeze({
       name: this.#name,
@@ -152,6 +197,8 @@ class CjsResManWorkQueue {
       paused: this.#paused
     });
   }
+
+  /** Removes and returns the next runnable work item for the resource work queue. */
   #TakeNext() {
     while (this.#head < this.#items.length) {
       const item = this.#items[this.#head++];
@@ -161,6 +208,8 @@ class CjsResManWorkQueue {
     }
     return null;
   }
+
+  /** Starts one queued work item for the resource work queue. */
   #Start(item) {
     item.state = "active";
     this.#active.set(item.id, item);
@@ -181,34 +230,72 @@ class CjsResManWorkQueue {
     }
     this.#Settle(item, true, result);
   }
+
+  /**
+   * Settles one active work item and advances the queue for the resource work
+   * queue.
+   */
   #Settle(item, didResolve, value) {
     if (!this.#active.delete(item.id)) return;
     item.state = didResolve ? "resolved" : "rejected";
     if (didResolve) item.resolve(value);else item.reject(value);
     this.#NotifyReady();
   }
+
+  /** Removes settled work items from the queue for the resource work queue. */
   #Compact(force = false) {
     if (force || this.#head > 256 && this.#head > this.#items.length * 0.5) {
       this.#items = this.#items.slice(this.#head);
       this.#head = 0;
     }
   }
+
+  /** Notifies waiters when the queue becomes ready for the resource work queue. */
   #NotifyReady() {
     if (this.#onReady && !this.#paused && this.GetQueuedCount() > 0) {
       this.#onReady(this);
     }
   }
+
+  /**
+   * Resolves a queue name or alias to its canonical execution lane.
+   *
+   * @param {*} value
+   * @returns {string}
+   */
+  static normalizeName(value) {
+    const name = String(value ?? "").trim().toLowerCase();
+    if (name === "main" || name === "prepare") return CjsResManQueue.MAIN;
+    if (name === "background" || name === "load") return CjsResManQueue.BACKGROUND;
+    throw new TypeError(`Unknown CjsResMan queue: ${value}`);
+  }
+
+  /**
+   * Creates the structured error used when queued work is cancelled.
+   *
+   * @param {string} queue
+   * @param {number} id
+   * @param {string} reason
+   * @returns {Error}
+   */
+  static createCancelledError(queue, id, reason = "") {
+    const error = new Error(`CjsResMan ${queue} queue item ${id} was cancelled.${reason ? ` ${reason}` : ""}`);
+    error.code = "CJS_RESMAN_QUEUE_CANCELLED";
+    error.queue = queue;
+    error.id = id;
+    return error;
+  }
 }
-function NormalizeLimit(value) {
+function normalizeLimit(value) {
   if (value === undefined || value === null || value === 0) return Number.POSITIVE_INFINITY;
   if (typeof value !== "number" || Number.isNaN(value) || value < 0) {
     throw new TypeError("CjsResMan queue limits must be non-negative numbers.");
   }
   return value;
 }
-function DefaultNow() {
+function defaultNow() {
   return globalThis.performance?.now?.() ?? Date.now();
 }
 
-export { CjsResManQueue, CjsResManQueueCancelledError, CjsResManWorkQueue, NormalizeCjsResManQueue };
-//# sourceMappingURL=CjsResManQueue.js.map
+export { CjsResManQueue, CjsResManWorkQueue };
+//# sourceMappingURL=CjsResManWorkQueue.js.map

package/dist/CjsResManWorkQueue.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CjsResManWorkQueue.js","sources":["../../src/CjsResManWorkQueue.js"],"sourcesContent":["export const CjsResManQueue = Object.freeze({\n  MAIN: \"main\",\n  BACKGROUND: \"background\",\n  PREPARE: \"main\",\n  LOAD: \"background\"\n});\n\n/**\n * Small FIFO executor used inside `CjsResMan` that tracks item ids, pause\n * state, concurrency, cancellation, and sync/async completion while queue\n * policy stays in the manager.\n *\n * The queue deliberately does not choose task priority or resource policy.\n */\nexport class CjsResManWorkQueue\n{\n  #active = new Map();\n  #concurrency = 1;\n  #head = 0;\n  #items = [];\n  #name;\n  #nextId = 1;\n  #onReady;\n  #paused = false;\n  #queued = new Map();\n\n  /** Creates a CjsResManWorkQueue with caller-provided initial state. */\n  constructor(name, options = {}) {\n    this.#name = CjsResManWorkQueue.normalizeName(name);\n    this.#onReady = typeof options.onReady === \"function\" ? options.onReady : null;\n    this.SetConcurrency(options.concurrency ?? 1);\n  }\n\n  /**\n   * Updates the maximum number of tasks that may run together for the resource\n   * work queue.\n   */\n  SetConcurrency(value) {\n    if (!Number.isInteger(value) || value < 1) {\n      throw new TypeError(\"CjsResMan queue concurrency must be a positive integer.\");\n    }\n    this.#concurrency = value;\n    this.#NotifyReady();\n    return this;\n  }\n\n  /**\n   * Returns the maximum number of tasks allowed to run together for the resource\n   * work queue.\n   */\n  GetConcurrency() {\n    return this.#concurrency;\n  }\n\n  /**\n   * Allocates the next monotonically increasing task identifier for the resource\n   * work queue.\n   */\n  GetNextId() {\n    return this.#nextId;\n  }\n\n  /** Returns the number of tasks waiting to start for the resource work queue. */\n  GetQueuedCount() {\n    return this.#queued.size;\n  }\n\n  /** Returns the number of tasks currently executing for the resource work queue. */\n  GetActiveCount() {\n    return this.#active.size;\n  }\n\n  /**\n   * Returns the combined number of waiting and active tasks for the resource\n   * work queue.\n   */\n  GetPendingCount() {\n    return this.#queued.size + this.#active.size;\n  }\n\n  /**\n   * Reports whether the queue is prevented from starting work for the resource\n   * work queue.\n   */\n  IsPaused() {\n    return this.#paused;\n  }\n\n  /**\n   * Enqueues one task and returns its cancellation-aware promise for the\n   * resource work queue.\n   */\n  Add(callback, context = null, metadata = null) {\n    if (typeof callback !== \"function\") {\n      throw new TypeError(\"CjsResMan queue items require a callback.\");\n    }\n\n    const id = this.#nextId++;\n    let resolve;\n    let reject;\n    const promise = new Promise((onResolve, onReject) => {\n      resolve = onResolve;\n      reject = onReject;\n    });\n    const item = {\n      id,\n      queue: this.#name,\n      callback,\n      context,\n      metadata,\n      promise,\n      resolve,\n      reject,\n      state: \"queued\"\n    };\n\n    this.#items.push(item);\n    this.#queued.set(id, item);\n    this.#NotifyReady();\n    return item;\n  }\n\n  /**\n   * Cancels a queued task selected by its identifier for the resource work\n   * queue.\n   */\n  Cancel(id, reason = \"\") {\n    const item = this.#queued.get(id);\n    if (!item) return false;\n    this.#queued.delete(id);\n    item.state = \"cancelled\";\n    item.reject(CjsResManWorkQueue.createCancelledError(this.#name, id, reason));\n    this.#Compact();\n    return true;\n  }\n\n  /**\n   * Prevents queued tasks from starting until resumed for the resource work\n   * queue.\n   */\n  Pause() {\n    this.#paused = true;\n    return this;\n  }\n\n  /** Allows queued tasks to start after a pause for the resource work queue. */\n  Resume() {\n    if (!this.#paused) return this;\n    this.#paused = false;\n    this.#NotifyReady();\n    return this;\n  }\n\n  /** Cancels every task that has not started for the resource work queue. */\n  Clear(reason = \"Queue cleared.\") {\n    const ids = [ ...this.#queued.keys() ];\n    for (const id of ids) this.Cancel(id, reason);\n    this.#Compact(true);\n    return ids.length;\n  }\n\n  /** Starts queued work while concurrency permits for the resource work queue. */\n  Pump(options = {}) {\n    const maxItems = normalizeLimit(options.maxItems);\n    const maxTime = normalizeLimit(options.maxTime);\n    const now = typeof options.now === \"function\" ? options.now : defaultNow;\n    const startedAt = now();\n    let processed = 0;\n\n    if (!this.#paused) {\n      while (this.#active.size < this.#concurrency && processed < maxItems) {\n        const item = this.#TakeNext();\n        if (!item) break;\n        this.#Start(item);\n        processed++;\n        if (processed > 0 && now() - startedAt >= maxTime) break;\n      }\n    }\n\n    this.#Compact();\n    return Object.freeze({\n      processed,\n      queued: this.GetQueuedCount(),\n      active: this.GetActiveCount(),\n      pending: this.GetPendingCount(),\n      paused: this.#paused\n    });\n  }\n\n  /**\n   * Returns an immutable snapshot of queue counts and policy for the resource\n   * work queue.\n   */\n  GetStats() {\n    return Object.freeze({\n      name: this.#name,\n      nextId: this.#nextId,\n      concurrency: this.#concurrency,\n      queued: this.GetQueuedCount(),\n      active: this.GetActiveCount(),\n      pending: this.GetPendingCount(),\n      paused: this.#paused\n    });\n  }\n\n  /** Removes and returns the next runnable work item for the resource work queue. */\n  #TakeNext() {\n    while (this.#head < this.#items.length) {\n      const item = this.#items[this.#head++];\n      if (item.state !== \"queued\") continue;\n      this.#queued.delete(item.id);\n      return item;\n    }\n    return null;\n  }\n\n  /** Starts one queued work item for the resource work queue. */\n  #Start(item) {\n    item.state = \"active\";\n    this.#active.set(item.id, item);\n\n    let result;\n    try {\n      result = item.callback.call(item.context, Object.freeze({\n        id: item.id,\n        queue: item.queue,\n        metadata: item.metadata\n      }));\n    } catch (error) {\n      this.#Settle(item, false, error);\n      return;\n    }\n\n    if (result && typeof result.then === \"function\") {\n      Promise.resolve(result).then(\n        value => this.#Settle(item, true, value),\n        error => this.#Settle(item, false, error)\n      );\n      return;\n    }\n    this.#Settle(item, true, result);\n  }\n\n  /**\n   * Settles one active work item and advances the queue for the resource work\n   * queue.\n   */\n  #Settle(item, didResolve, value) {\n    if (!this.#active.delete(item.id)) return;\n    item.state = didResolve ? \"resolved\" : \"rejected\";\n    if (didResolve) item.resolve(value);\n    else item.reject(value);\n    this.#NotifyReady();\n  }\n\n  /** Removes settled work items from the queue for the resource work queue. */\n  #Compact(force = false) {\n    if (force || (this.#head > 256 && this.#head > this.#items.length * 0.5)) {\n      this.#items = this.#items.slice(this.#head);\n      this.#head = 0;\n    }\n  }\n\n  /** Notifies waiters when the queue becomes ready for the resource work queue. */\n  #NotifyReady() {\n    if (this.#onReady && !this.#paused && this.GetQueuedCount() > 0) {\n      this.#onReady(this);\n    }\n  }\n\n  /**\n   * Resolves a queue name or alias to its canonical execution lane.\n   *\n   * @param {*} value\n   * @returns {string}\n   */\n  static normalizeName(value)\n  {\n    const name = String(value ?? \"\").trim().toLowerCase();\n    if (name === \"main\" || name === \"prepare\") return CjsResManQueue.MAIN;\n    if (name === \"background\" || name === \"load\") return CjsResManQueue.BACKGROUND;\n    throw new TypeError(`Unknown CjsResMan queue: ${value}`);\n  }\n\n  /**\n   * Creates the structured error used when queued work is cancelled.\n   *\n   * @param {string} queue\n   * @param {number} id\n   * @param {string} reason\n   * @returns {Error}\n   */\n  static createCancelledError(queue, id, reason = \"\")\n  {\n    const error = new Error(`CjsResMan ${queue} queue item ${id} was cancelled.${reason ? ` ${reason}` : \"\"}`);\n    error.code = \"CJS_RESMAN_QUEUE_CANCELLED\";\n    error.queue = queue;\n    error.id = id;\n    return error;\n  }\n}\n\nfunction normalizeLimit(value) {\n  if (value === undefined || value === null || value === 0) return Number.POSITIVE_INFINITY;\n  if (typeof value !== \"number\" || Number.isNaN(value) || value < 0) {\n    throw new TypeError(\"CjsResMan queue limits must be non-negative numbers.\");\n  }\n  return value;\n}\n\nfunction defaultNow() {\n  return globalThis.performance?.now?.() ?? Date.now();\n}\n"],"names":["CjsResManQueue","Object","freeze","MAIN","BACKGROUND","PREPARE","LOAD","CjsResManWorkQueue","Map","constructor","name","options","normalizeName","onReady","SetConcurrency","concurrency","value","Number","isInteger","TypeError","GetConcurrency","GetNextId","GetQueuedCount","size","GetActiveCount","GetPendingCount","IsPaused","Add","callback","context","metadata","id","resolve","reject","promise","Promise","onResolve","onReject","item","queue","state","push","set","Cancel","reason","get","delete","createCancelledError","Pause","Resume","Clear","ids","keys","length","Pump","maxItems","normalizeLimit","maxTime","now","defaultNow","startedAt","processed","queued","active","pending","paused","GetStats","nextId","#TakeNext","#Start","result","call","error","then","#Settle","didResolve","#Compact","force","slice","#NotifyReady","String","trim","toLowerCase","Error","code","undefined","POSITIVE_INFINITY","isNaN","globalThis","performance","Date"],"mappings":"MAAaA,cAAc,GAAGC,MAAM,CAACC,MAAM,CAAC;AAC1CC,EAAAA,IAAI,EAAE,MAAM;AACZC,EAAAA,UAAU,EAAE,YAAY;AACxBC,EAAAA,OAAO,EAAE,MAAM;AACfC,EAAAA,IAAI,EAAE;AACR,CAAC;;AAED;AACA;AACA;AACA;AACA;AACA;AACA;AACO,MAAMC,kBAAkB,CAC/B;AACE,EAAA,OAAO,GAAG,IAAIC,GAAG,EAAE;EACnB,YAAY,GAAG,CAAC;EAChB,KAAK,GAAG,CAAC;EACT,MAAM,GAAG,EAAE;AACX,EAAA,KAAK;EACL,OAAO,GAAG,CAAC;AACX,EAAA,QAAQ;EACR,OAAO,GAAG,KAAK;AACf,EAAA,OAAO,GAAG,IAAIA,GAAG,EAAE;;AAEnB;AACAC,EAAAA,WAAWA,CAACC,IAAI,EAAEC,OAAO,GAAG,EAAE,EAAE;IAC9B,IAAI,CAAC,KAAK,GAAGJ,kBAAkB,CAACK,aAAa,CAACF,IAAI,CAAC;AACnD,IAAA,IAAI,CAAC,QAAQ,GAAG,OAAOC,OAAO,CAACE,OAAO,KAAK,UAAU,GAAGF,OAAO,CAACE,OAAO,GAAG,IAAI;IAC9E,IAAI,CAACC,cAAc,CAACH,OAAO,CAACI,WAAW,IAAI,CAAC,CAAC;AAC/C,EAAA;;AAEA;AACF;AACA;AACA;EACED,cAAcA,CAACE,KAAK,EAAE;IACpB,IAAI,CAACC,MAAM,CAACC,SAAS,CAACF,KAAK,CAAC,IAAIA,KAAK,GAAG,CAAC,EAAE;AACzC,MAAA,MAAM,IAAIG,SAAS,CAAC,yDAAyD,CAAC;AAChF,IAAA;AACA,IAAA,IAAI,CAAC,YAAY,GAAGH,KAAK;AACzB,IAAA,IAAI,CAAC,YAAY,EAAE;AACnB,IAAA,OAAO,IAAI;AACb,EAAA;;AAEA;AACF;AACA;AACA;AACEI,EAAAA,cAAcA,GAAG;IACf,OAAO,IAAI,CAAC,YAAY;AAC1B,EAAA;;AAEA;AACF;AACA;AACA;AACEC,EAAAA,SAASA,GAAG;IACV,OAAO,IAAI,CAAC,OAAO;AACrB,EAAA;;AAEA;AACAC,EAAAA,cAAcA,GAAG;AACf,IAAA,OAAO,IAAI,CAAC,OAAO,CAACC,IAAI;AAC1B,EAAA;;AAEA;AACAC,EAAAA,cAAcA,GAAG;AACf,IAAA,OAAO,IAAI,CAAC,OAAO,CAACD,IAAI;AAC1B,EAAA;;AAEA;AACF;AACA;AACA;AACEE,EAAAA,eAAeA,GAAG;AAChB,IAAA,OAAO,IAAI,CAAC,OAAO,CAACF,IAAI,GAAG,IAAI,CAAC,OAAO,CAACA,IAAI;AAC9C,EAAA;;AAEA;AACF;AACA;AACA;AACEG,EAAAA,QAAQA,GAAG;IACT,OAAO,IAAI,CAAC,OAAO;AACrB,EAAA;;AAEA;AACF;AACA;AACA;EACEC,GAAGA,CAACC,QAAQ,EAAEC,OAAO,GAAG,IAAI,EAAEC,QAAQ,GAAG,IAAI,EAAE;AAC7C,IAAA,IAAI,OAAOF,QAAQ,KAAK,UAAU,EAAE;AAClC,MAAA,MAAM,IAAIT,SAAS,CAAC,2CAA2C,CAAC;AAClE,IAAA;AAEA,IAAA,MAAMY,EAAE,GAAG,IAAI,CAAC,OAAO,EAAE;AACzB,IAAA,IAAIC,OAAO;AACX,IAAA,IAAIC,MAAM;IACV,MAAMC,OAAO,GAAG,IAAIC,OAAO,CAAC,CAACC,SAAS,EAAEC,QAAQ,KAAK;AACnDL,MAAAA,OAAO,GAAGI,SAAS;AACnBH,MAAAA,MAAM,GAAGI,QAAQ;AACnB,IAAA,CAAC,CAAC;AACF,IAAA,MAAMC,IAAI,GAAG;MACXP,EAAE;AACFQ,MAAAA,KAAK,EAAE,IAAI,CAAC,KAAK;MACjBX,QAAQ;MACRC,OAAO;MACPC,QAAQ;MACRI,OAAO;MACPF,OAAO;MACPC,MAAM;AACNO,MAAAA,KAAK,EAAE;KACR;AAED,IAAA,IAAI,CAAC,MAAM,CAACC,IAAI,CAACH,IAAI,CAAC;IACtB,IAAI,CAAC,OAAO,CAACI,GAAG,CAACX,EAAE,EAAEO,IAAI,CAAC;AAC1B,IAAA,IAAI,CAAC,YAAY,EAAE;AACnB,IAAA,OAAOA,IAAI;AACb,EAAA;;AAEA;AACF;AACA;AACA;AACEK,EAAAA,MAAMA,CAACZ,EAAE,EAAEa,MAAM,GAAG,EAAE,EAAE;IACtB,MAAMN,IAAI,GAAG,IAAI,CAAC,OAAO,CAACO,GAAG,CAACd,EAAE,CAAC;AACjC,IAAA,IAAI,CAACO,IAAI,EAAE,OAAO,KAAK;AACvB,IAAA,IAAI,CAAC,OAAO,CAACQ,MAAM,CAACf,EAAE,CAAC;IACvBO,IAAI,CAACE,KAAK,GAAG,WAAW;AACxBF,IAAAA,IAAI,CAACL,MAAM,CAAC1B,kBAAkB,CAACwC,oBAAoB,CAAC,IAAI,CAAC,KAAK,EAAEhB,EAAE,EAAEa,MAAM,CAAC,CAAC;AAC5E,IAAA,IAAI,CAAC,QAAQ,EAAE;AACf,IAAA,OAAO,IAAI;AACb,EAAA;;AAEA;AACF;AACA;AACA;AACEI,EAAAA,KAAKA,GAAG;AACN,IAAA,IAAI,CAAC,OAAO,GAAG,IAAI;AACnB,IAAA,OAAO,IAAI;AACb,EAAA;;AAEA;AACAC,EAAAA,MAAMA,GAAG;AACP,IAAA,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,OAAO,IAAI;AAC9B,IAAA,IAAI,CAAC,OAAO,GAAG,KAAK;AACpB,IAAA,IAAI,CAAC,YAAY,EAAE;AACnB,IAAA,OAAO,IAAI;AACb,EAAA;;AAEA;AACAC,EAAAA,KAAKA,CAACN,MAAM,GAAG,gBAAgB,EAAE;AAC/B,IAAA,MAAMO,GAAG,GAAG,CAAE,GAAG,IAAI,CAAC,OAAO,CAACC,IAAI,EAAE,CAAE;AACtC,IAAA,KAAK,MAAMrB,EAAE,IAAIoB,GAAG,EAAE,IAAI,CAACR,MAAM,CAACZ,EAAE,EAAEa,MAAM,CAAC;AAC7C,IAAA,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC;IACnB,OAAOO,GAAG,CAACE,MAAM;AACnB,EAAA;;AAEA;AACAC,EAAAA,IAAIA,CAAC3C,OAAO,GAAG,EAAE,EAAE;AACjB,IAAA,MAAM4C,QAAQ,GAAGC,cAAc,CAAC7C,OAAO,CAAC4C,QAAQ,CAAC;AACjD,IAAA,MAAME,OAAO,GAAGD,cAAc,CAAC7C,OAAO,CAAC8C,OAAO,CAAC;AAC/C,IAAA,MAAMC,GAAG,GAAG,OAAO/C,OAAO,CAAC+C,GAAG,KAAK,UAAU,GAAG/C,OAAO,CAAC+C,GAAG,GAAGC,UAAU;AACxE,IAAA,MAAMC,SAAS,GAAGF,GAAG,EAAE;IACvB,IAAIG,SAAS,GAAG,CAAC;AAEjB,IAAA,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE;AACjB,MAAA,OAAO,IAAI,CAAC,OAAO,CAACtC,IAAI,GAAG,IAAI,CAAC,YAAY,IAAIsC,SAAS,GAAGN,QAAQ,EAAE;AACpE,QAAA,MAAMjB,IAAI,GAAG,IAAI,CAAC,SAAS,EAAE;QAC7B,IAAI,CAACA,IAAI,EAAE;AACX,QAAA,IAAI,CAAC,MAAM,CAACA,IAAI,CAAC;AACjBuB,QAAAA,SAAS,EAAE;QACX,IAAIA,SAAS,GAAG,CAAC,IAAIH,GAAG,EAAE,GAAGE,SAAS,IAAIH,OAAO,EAAE;AACrD,MAAA;AACF,IAAA;AAEA,IAAA,IAAI,CAAC,QAAQ,EAAE;IACf,OAAOxD,MAAM,CAACC,MAAM,CAAC;MACnB2D,SAAS;AACTC,MAAAA,MAAM,EAAE,IAAI,CAACxC,cAAc,EAAE;AAC7ByC,MAAAA,MAAM,EAAE,IAAI,CAACvC,cAAc,EAAE;AAC7BwC,MAAAA,OAAO,EAAE,IAAI,CAACvC,eAAe,EAAE;MAC/BwC,MAAM,EAAE,IAAI,CAAC;AACf,KAAC,CAAC;AACJ,EAAA;;AAEA;AACF;AACA;AACA;AACEC,EAAAA,QAAQA,GAAG;IACT,OAAOjE,MAAM,CAACC,MAAM,CAAC;AACnBQ,MAAAA,IAAI,EAAE,IAAI,CAAC,KAAK;AAChByD,MAAAA,MAAM,EAAE,IAAI,CAAC,OAAO;AACpBpD,MAAAA,WAAW,EAAE,IAAI,CAAC,YAAY;AAC9B+C,MAAAA,MAAM,EAAE,IAAI,CAACxC,cAAc,EAAE;AAC7ByC,MAAAA,MAAM,EAAE,IAAI,CAACvC,cAAc,EAAE;AAC7BwC,MAAAA,OAAO,EAAE,IAAI,CAACvC,eAAe,EAAE;MAC/BwC,MAAM,EAAE,IAAI,CAAC;AACf,KAAC,CAAC;AACJ,EAAA;;AAEA;EACA,SAASG,GAAG;IACV,OAAO,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,MAAM,CAACf,MAAM,EAAE;AACtC,MAAA,MAAMf,IAAI,GAAG,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC;AACtC,MAAA,IAAIA,IAAI,CAACE,KAAK,KAAK,QAAQ,EAAE;MAC7B,IAAI,CAAC,OAAO,CAACM,MAAM,CAACR,IAAI,CAACP,EAAE,CAAC;AAC5B,MAAA,OAAOO,IAAI;AACb,IAAA;AACA,IAAA,OAAO,IAAI;AACb,EAAA;;AAEA;EACA,MAAM+B,CAAC/B,IAAI,EAAE;IACXA,IAAI,CAACE,KAAK,GAAG,QAAQ;IACrB,IAAI,CAAC,OAAO,CAACE,GAAG,CAACJ,IAAI,CAACP,EAAE,EAAEO,IAAI,CAAC;AAE/B,IAAA,IAAIgC,MAAM;IACV,IAAI;AACFA,MAAAA,MAAM,GAAGhC,IAAI,CAACV,QAAQ,CAAC2C,IAAI,CAACjC,IAAI,CAACT,OAAO,EAAE5B,MAAM,CAACC,MAAM,CAAC;QACtD6B,EAAE,EAAEO,IAAI,CAACP,EAAE;QACXQ,KAAK,EAAED,IAAI,CAACC,KAAK;QACjBT,QAAQ,EAAEQ,IAAI,CAACR;AACjB,OAAC,CAAC,CAAC;IACL,CAAC,CAAC,OAAO0C,KAAK,EAAE;MACd,IAAI,CAAC,OAAO,CAAClC,IAAI,EAAE,KAAK,EAAEkC,KAAK,CAAC;AAChC,MAAA;AACF,IAAA;IAEA,IAAIF,MAAM,IAAI,OAAOA,MAAM,CAACG,IAAI,KAAK,UAAU,EAAE;AAC/CtC,MAAAA,OAAO,CAACH,OAAO,CAACsC,MAAM,CAAC,CAACG,IAAI,CAC1BzD,KAAK,IAAI,IAAI,CAAC,OAAO,CAACsB,IAAI,EAAE,IAAI,EAAEtB,KAAK,CAAC,EACxCwD,KAAK,IAAI,IAAI,CAAC,OAAO,CAAClC,IAAI,EAAE,KAAK,EAAEkC,KAAK,CAC1C,CAAC;AACD,MAAA;AACF,IAAA;IACA,IAAI,CAAC,OAAO,CAAClC,IAAI,EAAE,IAAI,EAAEgC,MAAM,CAAC;AAClC,EAAA;;AAEA;AACF;AACA;AACA;AACE,EAAA,OAAOI,CAACpC,IAAI,EAAEqC,UAAU,EAAE3D,KAAK,EAAE;AAC/B,IAAA,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC8B,MAAM,CAACR,IAAI,CAACP,EAAE,CAAC,EAAE;AACnCO,IAAAA,IAAI,CAACE,KAAK,GAAGmC,UAAU,GAAG,UAAU,GAAG,UAAU;AACjD,IAAA,IAAIA,UAAU,EAAErC,IAAI,CAACN,OAAO,CAAChB,KAAK,CAAC,CAAC,KAC/BsB,IAAI,CAACL,MAAM,CAACjB,KAAK,CAAC;AACvB,IAAA,IAAI,CAAC,YAAY,EAAE;AACrB,EAAA;;AAEA;AACA,EAAA,QAAQ4D,CAACC,KAAK,GAAG,KAAK,EAAE;IACtB,IAAIA,KAAK,IAAK,IAAI,CAAC,KAAK,GAAG,GAAG,IAAI,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,MAAM,CAACxB,MAAM,GAAG,GAAI,EAAE;AACxE,MAAA,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAACyB,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC;AAC3C,MAAA,IAAI,CAAC,KAAK,GAAG,CAAC;AAChB,IAAA;AACF,EAAA;;AAEA;EACA,YAAYC,GAAG;AACb,IAAA,IAAI,IAAI,CAAC,QAAQ,IAAI,CAAC,IAAI,CAAC,OAAO,IAAI,IAAI,CAACzD,cAAc,EAAE,GAAG,CAAC,EAAE;AAC/D,MAAA,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC;AACrB,IAAA;AACF,EAAA;;AAEA;AACF;AACA;AACA;AACA;AACA;EACE,OAAOV,aAAaA,CAACI,KAAK,EAC1B;AACE,IAAA,MAAMN,IAAI,GAAGsE,MAAM,CAAChE,KAAK,IAAI,EAAE,CAAC,CAACiE,IAAI,EAAE,CAACC,WAAW,EAAE;IACrD,IAAIxE,IAAI,KAAK,MAAM,IAAIA,IAAI,KAAK,SAAS,EAAE,OAAOV,cAAc,CAACG,IAAI;IACrE,IAAIO,IAAI,KAAK,YAAY,IAAIA,IAAI,KAAK,MAAM,EAAE,OAAOV,cAAc,CAACI,UAAU;AAC9E,IAAA,MAAM,IAAIe,SAAS,CAAC,CAAA,yBAAA,EAA4BH,KAAK,EAAE,CAAC;AAC1D,EAAA;;AAEA;AACF;AACA;AACA;AACA;AACA;AACA;AACA;EACE,OAAO+B,oBAAoBA,CAACR,KAAK,EAAER,EAAE,EAAEa,MAAM,GAAG,EAAE,EAClD;AACE,IAAA,MAAM4B,KAAK,GAAG,IAAIW,KAAK,CAAC,CAAA,UAAA,EAAa5C,KAAK,CAAA,YAAA,EAAeR,EAAE,CAAA,eAAA,EAAkBa,MAAM,GAAG,CAAA,CAAA,EAAIA,MAAM,EAAE,GAAG,EAAE,EAAE,CAAC;IAC1G4B,KAAK,CAACY,IAAI,GAAG,4BAA4B;IACzCZ,KAAK,CAACjC,KAAK,GAAGA,KAAK;IACnBiC,KAAK,CAACzC,EAAE,GAAGA,EAAE;AACb,IAAA,OAAOyC,KAAK;AACd,EAAA;AACF;AAEA,SAAShB,cAAcA,CAACxC,KAAK,EAAE;AAC7B,EAAA,IAAIA,KAAK,KAAKqE,SAAS,IAAIrE,KAAK,KAAK,IAAI,IAAIA,KAAK,KAAK,CAAC,EAAE,OAAOC,MAAM,CAACqE,iBAAiB;AACzF,EAAA,IAAI,OAAOtE,KAAK,KAAK,QAAQ,IAAIC,MAAM,CAACsE,KAAK,CAACvE,KAAK,CAAC,IAAIA,KAAK,GAAG,CAAC,EAAE;AACjE,IAAA,MAAM,IAAIG,SAAS,CAAC,sDAAsD,CAAC;AAC7E,EAAA;AACA,EAAA,OAAOH,KAAK;AACd;AAEA,SAAS2C,UAAUA,GAAG;AACpB,EAAA,OAAO6B,UAAU,CAACC,WAAW,EAAE/B,GAAG,IAAI,IAAIgC,IAAI,CAAChC,GAAG,EAAE;AACtD;;;;"}

package/dist/format/CjsBlueReader.js

@@ -14,6 +14,10 @@ import { CjsReader } from './CjsReader.js';
  * path yet and retains its lenient named-field behavior.
  */
 class CjsBlueReader extends CjsReader {
+  /**
+   * Creates a CjsBlueReader over caller-provided resource bytes and reader
+   * options.
+   */
   constructor(options = {}, config = {}) {
     super({
       ...options
@@ -37,15 +41,24 @@ class CjsBlueReader extends CjsReader {
     };
     this.ResetBlueReadState();
   }
+
+  /** Clears blue read state before reusing the current Blue graph reader. */
   ResetBlueReadState() {
     this.reports = [];
     this.runtimeInstances = [];
   }
+
+  /**
+   * Finalizes runtime instances after the current Blue graph reader has been
+   * read.
+   */
   FinalizeRuntimeInstances() {
     for (const record of this.runtimeInstances) {
       this.adapter.finalize(record.instance, this.CreateRuntimeContext(record.kind, record.shape, false));
     }
   }
+
+  /** Creates runtime target for the current Blue graph reader. */
   CreateRuntimeTarget(kind, shape = null) {
     const built = this.adapter.construct(kind, this.CreateRuntimeContext(kind, shape, true, this.options));
     if (built !== undefined) return built;
@@ -53,6 +66,8 @@ class CjsBlueReader extends CjsReader {
     if (ClassConstructor) return new ClassConstructor();
     return this.CreateRuntimeFallback(kind, shape);
   }
+
+  /** Creates runtime fallback for the current Blue graph reader. */
   CreateRuntimeFallback(kind, shape = null) {
     const target = {
       _sourceClassName: this.includeSourceShape ? kind : kind || null
@@ -60,6 +75,8 @@ class CjsBlueReader extends CjsReader {
     if (this.includeSourceShape) target._sourceShape = shape || null;
     return target;
   }
+
+  /** Applies runtime values to the current Blue graph reader. */
   ApplyRuntimeValues(target, values, kind, shape = null) {
     this.adapter.applyValues(target, values, this.CreateRuntimeContext(kind, shape, true, this.hydrationOptions));
     this.runtimeInstances.push({
@@ -68,6 +85,8 @@ class CjsBlueReader extends CjsReader {
       shape
     });
   }
+
+  /** Creates runtime context for the current Blue graph reader. */
   CreateRuntimeContext(kind, shape, includeOptions, options = null) {
     const context = {
       kind
@@ -76,12 +95,16 @@ class CjsBlueReader extends CjsReader {
     if (includeOptions) context.options = options;
     return context;
   }
+
+  /** Creates payload target for the current Blue graph reader. */
   CreatePayloadTarget(kind) {
     const typeField = this.GetPayloadTypeField();
     return typeField && (kind || this.includeEmptyPayloadType) ? {
       [typeField]: kind
     } : {};
   }
+
+  /** Creates payload reference for the current Blue graph reader. */
   CreatePayloadReference(targetObject, referenceId) {
     const idField = this.GetPayloadIdField();
     const referenceField = this.GetPayloadReferenceField();
@@ -94,18 +117,28 @@ class CjsBlueReader extends CjsReader {
       [referenceField]: referenceId
     } : targetObject;
   }
+
+  /** Returns payload type field from the current Blue graph reader. */
   GetPayloadTypeField() {
     return this.GetPayloadField("payloadTypeField", "_type");
   }
+
+  /** Returns payload ID field from the current Blue graph reader. */
   GetPayloadIdField() {
     return this.GetPayloadField("payloadIdField", "_id");
   }
+
+  /** Returns payload reference field from the current Blue graph reader. */
   GetPayloadReferenceField() {
     return this.GetPayloadField("payloadReferenceField", "_reference");
   }
+
+  /** Returns payload values field from the current Blue graph reader. */
   GetPayloadValuesField() {
     return this.GetPayloadField("payloadValuesField", "_values");
   }
+
+  /** Returns payload field from the current Blue graph reader. */
   GetPayloadField(name, fallback) {
     const value = this.options[name];
     if (!this.validatePayloadReservedFields) {
@@ -116,6 +149,11 @@ class CjsBlueReader extends CjsReader {
     if (typeof value === "string" && value) return value;
     throw this.PayloadError("PAYLOAD_MARKER_CONFIGURATION", `${name} must be a non-empty string or false`);
   }
+
+  /**
+   * Validates payload configuration against Blue graph reader constraints and
+   * throws on failure.
+   */
   ValidatePayloadConfiguration() {
     if (!this.validatePayloadReservedFields) {
       this.payloadReservedFields = null;
@@ -142,6 +180,11 @@ class CjsBlueReader extends CjsReader {
     }
     this.payloadReservedFields = reserved;
   }
+
+  /**
+   * Validates payload field available against Blue graph reader constraints
+   * and throws on failure.
+   */
   AssertPayloadFieldAvailable(field) {
     if (!this.validatePayloadReservedFields) return;
     if (!this.payloadReservedFields) this.ValidatePayloadConfiguration();
@@ -149,12 +192,22 @@ class CjsBlueReader extends CjsReader {
     if (!role) return;
     throw this.PayloadError("PAYLOAD_RESERVED_FIELD_COLLISION", `payload field "${field}" is reserved for the ${role} marker`);
   }
+
+  /**
+   * Assigns payload values while preserving the current Blue graph reader
+   * contract.
+   */
   AssignPayloadValues(targetObject, values) {
     for (const [field, value] of Object.entries(values)) {
       this.AssertPayloadFieldAvailable(field);
       this.DefinePayloadProperty(targetObject, field, value);
     }
   }
+
+  /**
+   * Assigns payload reference ID while preserving the current Blue graph
+   * reader contract.
+   */
   AssignPayloadReferenceId(targetObject, idField, referenceId) {
     if (!Object.hasOwn(targetObject, idField)) {
       this.DefinePayloadProperty(targetObject, idField, referenceId);
@@ -164,11 +217,18 @@ class CjsBlueReader extends CjsReader {
     if (targetObject[idField] === referenceId) return;
     throw this.PayloadError("PAYLOAD_RESERVED_FIELD_COLLISION", `payload ID field "${idField}" conflicts with reference ${referenceId}`);
   }
+
+  /**
+   * Creates a payload error annotated with the current graph context for the
+   * Blue graph reader.
+   */
   PayloadError(code, message) {
     const error = new TypeError(`${code}: ${message}`);
     error.code = code;
     return error;
   }
+
+  /** Defines payload property on the current Blue graph reader result. */
   DefinePayloadProperty(targetObject, field, value) {
     Object.defineProperty(targetObject, field, {
       value,
@@ -177,6 +237,11 @@ class CjsBlueReader extends CjsReader {
       writable: true
     });
   }
+
+  /**
+   * Assigns runtime field value while preserving the current Blue graph reader
+   * contract.
+   */
   AssignRuntimeFieldValue(targetObject, target, value) {
     if (target.unknown) {
       targetObject[target.wireName] = value;
@@ -193,6 +258,11 @@ class CjsBlueReader extends CjsReader {
     }
     targetObject[target.field.name] = this.NormalizeRuntimeFieldValue(value, target.field);
   }
+
+  /**
+   * Assigns payload field value while preserving the current Blue graph reader
+   * contract.
+   */
   AssignPayloadFieldValue(targetObject, target, value) {
     this.AssertPayloadFieldAvailable(target.unknown ? target.wireName : target.field.name);
     if (target.unknown) {
@@ -222,6 +292,11 @@ class CjsBlueReader extends CjsReader {
       targetObject[target.field.name] = value;
     }
   }
+
+  /**
+   * Converts runtime field value into the canonical Blue graph reader
+   * representation.
+   */
   NormalizeRuntimeFieldValue(value, field) {
     if (!field) return value;
 
@@ -236,6 +311,8 @@ class CjsBlueReader extends CjsReader {
     if (CjsBlueReader.isShapeIncompatibleMathArray(value, descriptor)) return value;
     return normalizeCarbonValue(value, field);
   }
+
+  /** Resolves source shape against the current Blue graph reader. */
   ResolveSourceShape(kind) {
     const registry = this.options.registry || null;
     if (registry?.GetSourceShape) return registry.GetSourceShape(kind);
@@ -249,16 +326,28 @@ class CjsBlueReader extends CjsReader {
     }
     return this.schemaShapes.get(kind) || null;
   }
+
+  /** Resolves class against the current Blue graph reader. */
   ResolveClass(kind) {
     if (!kind) return null;
     const classes = this.options.classes || {};
     const Registry = this.options.registry || this.defaultRegistry;
     return classes[kind] || (Registry ? Registry.GetConstructor(kind) : null);
   }
+
+  /**
+   * Applies the configured resource-path transform to a decoded field value
+   * for the Blue graph reader.
+   */
   TransformPath(value) {
     const handler = this.options.pathHandler;
     return typeof handler === "function" ? handler(value) : value;
   }
+
+  /**
+   * Reports whether the current Blue graph reader satisfies shape incompatible
+   * math array.
+   */
   static isShapeIncompatibleMathArray(value, descriptor) {
     const expectedLength = descriptor?.length;
     return Array.isArray(value) && Number.isInteger(expectedLength) && value.length !== expectedLength;