@buildkitchen/context 0.0.0-stage → 0.0.8

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kwasi A. Mensah
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,48 @@
-# Temporary Holding Version
+# 📦 @buildkitchen/context
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Library for maintaining context across MaybePromises.
+
+## Installation
+
+Install the package via your preferred package manager:
+
+```bash
+npm install @buildkitchen/context
+```
+
+Or using yarn/pnpm:
+
+```bash
+yarn add @buildkitchen/context
+pnpm add @buildkitchen/context
+```
+
+## Usage
+
+```typescript
+const context = Context.root("root");
+
+const a = context.withChildContext((context) => {
+  // do some asynchrounous work.
+});
+
+const b = context.withChildContext((context) => {
+  // some where in this work we accidentally add a dependency that causes a cycle.
+  // We'll get an informative error instead of a hang.
+  a.addDependency(context);
+});
+```
+
+We use this most with `PromiseCache` classes to make sure cycles aren't introduced. Can be used similarly to `async_hooks.executionAsyncId` but does require some manual tracking.
+
+## API Reference
+
+[Full documentation on Codeberg](https://codeberg.org/buildkitchen/context/src/branch/main/docs)
+
+## Contributing
+
+We're not actively soliticing contributions but please let us know of any bugs/issues you find in this code and we'll try to resolve them in a timely manner.
+
+## License
+
+Distributed under the MIT License. See `LICENSE` for more information.

package/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @module
+ * @mergeModuleWith <project>
+ */
+import { type ContextJSON } from "./src/common.js";
+import { Context, type ContextProgressReporter } from "./src/context.js";
+import { ReadonlyContext } from "./src/readonly_context.js";
+export type { ContextProgressReporter };
+export { type ContextJSON, ReadonlyContext, Context };
+//# sourceMappingURL=index.d.ts.map

package/index.js

@@ -0,0 +1,4 @@
+import { Context } from "./src/context.js";
+import { ReadonlyContext } from "./src/readonly_context.js";
+export { ReadonlyContext, Context }; //
+//# sourceMappingURL=index.js.map

package/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["index.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,OAAO,EAAgC,MAAM,kBAAkB,CAAC;AACzE,OAAO,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAG5D,OAAO,EAAoB,eAAe,EAAE,OAAO,EAAE,CAAC,CAAC,EAAE","sourcesContent":["/**\n * @module\n * @mergeModuleWith <project>\n */\nimport { type ContextJSON } from \"./src/common.js\";\nimport { Context, type ContextProgressReporter } from \"./src/context.js\";\nimport { ReadonlyContext } from \"./src/readonly_context.js\";\n\nexport type { ContextProgressReporter };\nexport { type ContextJSON, ReadonlyContext, Context }; //\n"]}

package/package.json

@@ -1,6 +1,27 @@
 {
+  "description": "Library for maintaining context across MaybePromises",
+  "homepage": "https://codeberg.org/buildkitchen/context",
+  "bugs": {
+    "url": "https://codeberg.org/buildkitchen/context"
+  },
+  "license": "MIT",
+  "author": {
+    "name": "Kwasi Mensah",
+    "email": "kwasi.mensah@gmail.com"
+  },
+  "keywords": [
+    "asynccontext",
+    "maybepromise",
+    "promise"
+  ],
   "name": "@buildkitchen/context",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "bin": {},
+  "private": false,
+  "version": "0.0.8",
+  "__buildkitchen": "Generated by buildkitchen",
+  "type": "module",
+  "bundledDependencies": [],
+  "dependencies": {
+    "@buildkitchen/validation": "^0.0.8"
+  }
 }

package/src/common.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @module
+ * @mergeModuleWith <project>
+ */
+import { type JSONObject } from "@buildkitchen/validation";
+export interface ContextJSON extends JSONObject {
+    readonly rootID: string;
+    readonly ids: ReadonlyArray<number>;
+}
+//# sourceMappingURL=common.d.ts.map

package/src/common.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=common.js.map

package/src/common.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"common.js","sourceRoot":"","sources":["common.ts"],"names":[],"mappings":"","sourcesContent":["/**\n * @module\n * @mergeModuleWith <project>\n */\nimport { type JSONObject } from \"@buildkitchen/validation\";\n\nexport interface ContextJSON extends JSONObject {\n  readonly rootID: string;\n  readonly ids: ReadonlyArray<number>;\n} //\n"]}

package/src/context.d.ts

@@ -0,0 +1,32 @@
+/**
+ * @module
+ * @mergeModuleWith <project>
+ */
+import { type Unvalidated } from "@buildkitchen/validation";
+import { type ContextJSON } from "./common.js";
+export interface ContextProgressReporter {
+    newContext(): void;
+    newCompletedContext(): void;
+}
+export declare class Context {
+    readonly rootID: string;
+    private readonly ids;
+    private readonly progressReporter?;
+    private _hash;
+    private nextChildID;
+    private readonly dependencies;
+    private state;
+    static root(rootID: string, progressReporter?: ContextProgressReporter): Context;
+    private constructor();
+    cachedHash(): string;
+    isParentOf(other: Context): boolean;
+    private checkForCycles;
+    addDependency(context: Context): void;
+    withChildContext<T>(behavior: (context: Context) => PromiseLike<T>): PromiseLike<T>;
+    withChildContextSync<T>(behavior: (context: Context) => T): T;
+    static fromJSON(context: Unvalidated<ContextJSON>): Context;
+    withJSON<T>(behavior: (context: ContextJSON) => T): T;
+    toJSON(): ContextJSON;
+    private setFinished;
+}
+//# sourceMappingURL=context.d.ts.map

package/src/context.js

@@ -0,0 +1,167 @@
+/**
+ * @module
+ * @mergeModuleWith <project>
+ */
+import { validateArray, validateNumber, validateString } from "@buildkitchen/validation";
+var ContextState;
+(function (ContextState) {
+    ContextState[ContextState["kInProgess"] = 0] = "kInProgess";
+    ContextState[ContextState["kFinished"] = 1] = "kFinished";
+})(ContextState || (ContextState = {}));
+export class Context {
+    static root(rootID, progressReporter) {
+        return new Context(rootID, [], progressReporter);
+    }
+    constructor(rootID, ids, progressReporter) {
+        this.rootID = rootID;
+        this.ids = ids;
+        this.progressReporter = progressReporter;
+        this.nextChildID = 0;
+        this.dependencies = new Map();
+        this.state = ContextState.kInProgess;
+        progressReporter?.newContext();
+    }
+    cachedHash() {
+        this._hash ?? (this._hash = `root: ${this.rootID} ids: [${this.ids.join(",")}]`);
+        return this._hash;
+    }
+    isParentOf(other) {
+        if (this.rootID !== other.rootID) {
+            return false;
+        }
+        if (this.ids.length >= other.ids.length) {
+            return false;
+        }
+        for (let i = 0; i < this.ids.length; ++i) {
+            if (this.ids[i] !== other.ids[i]) {
+                return false;
+            }
+        }
+        return true;
+    }
+    checkForCycles() {
+        const stack = new Array();
+        let CycleContextState;
+        (function (CycleContextState) {
+            CycleContextState[CycleContextState["kVisited"] = 0] = "kVisited";
+            CycleContextState[CycleContextState["kSafe"] = 1] = "kSafe";
+        })(CycleContextState || (CycleContextState = {}));
+        const contextStates = new Map();
+        stack.push({
+            context: this,
+            markAsSafe: () => {
+                // marking as safe doesn't do anything at the top level
+            }
+        });
+        while (true) {
+            const stackItem = stack.pop();
+            if (stackItem === undefined) {
+                return;
+            }
+            const { context, markAsSafe } = stackItem;
+            const state = contextStates.get(context.cachedHash());
+            if (state === CycleContextState.kSafe) {
+                markAsSafe();
+                continue;
+            }
+            if (state === CycleContextState.kVisited) {
+                //debugger;
+                throw new Error(`Cycle detected in context dependency graph`);
+            }
+            if (context.dependencies.size === 0) {
+                contextStates.set(context.cachedHash(), CycleContextState.kSafe);
+                markAsSafe();
+                continue;
+            }
+            contextStates.set(context.cachedHash(), CycleContextState.kVisited);
+            let depCounter = 1;
+            const resolvedDep = () => {
+                if (--depCounter === 0) {
+                    contextStates.set(context.cachedHash(), CycleContextState.kSafe);
+                    markAsSafe();
+                }
+            };
+            for (const dep of context.dependencies.values()) {
+                ++depCounter;
+                stack.push({
+                    context: dep,
+                    markAsSafe: resolvedDep
+                });
+            }
+            resolvedDep();
+        }
+    }
+    addDependency(context) {
+        if (!this.dependencies.has(context.cachedHash())) {
+            this.dependencies.set(context.cachedHash(), context);
+            context.checkForCycles();
+        }
+    }
+    withChildContext(behavior) {
+        if (this.state === ContextState.kFinished) {
+            return Promise.reject(new Error("Cannot add more children to a finished context"));
+        }
+        const childContext = new Context(this.rootID, [...this.ids, this.nextChildID++], this.progressReporter);
+        this.dependencies.set(childContext.cachedHash(), childContext);
+        try {
+            return behavior(childContext).then((value) => {
+                this.dependencies.delete(childContext.cachedHash());
+                childContext.setFinished();
+                return value;
+            }, (e) => {
+                this.dependencies.delete(childContext.cachedHash());
+                throw e;
+            });
+        }
+        catch (e) {
+            this.dependencies.delete(childContext.cachedHash());
+            return Promise.reject(e);
+        }
+    }
+    withChildContextSync(behavior) {
+        if (this.state === ContextState.kFinished) {
+            throw new Error("Cannot add more children to a finished context");
+        }
+        const childContext = new Context(this.rootID, [...this.ids, this.nextChildID++], this.progressReporter);
+        this.dependencies.set(childContext.cachedHash(), childContext);
+        const value = behavior(childContext);
+        this.dependencies.delete(childContext.cachedHash());
+        childContext.setFinished();
+        return value;
+    }
+    static fromJSON(context) {
+        return new Context(validateString(context.get("rootID")), validateArray(context.get("ids"), validateNumber));
+    }
+    // force you to create a new context in order to get JSON to make sure you don't JSON-infy a context shared by others.
+    withJSON(behavior) {
+        return this.withChildContextSync((context) => {
+            const contextJSON = {
+                rootID: context.rootID,
+                ids: [...context.ids]
+            };
+            return behavior(contextJSON);
+        });
+    }
+    toJSON() {
+        return {
+            rootID: this.rootID,
+            ids: [...this.ids]
+        };
+    }
+    setFinished() {
+        if (this.state === ContextState.kFinished) {
+            // Don't hard error. Promises allow for resolve/reject to both be called.
+            return;
+        }
+        //all of your dependencies should be finished too.
+        this.dependencies.forEach((dep) => {
+            if (dep.state !== ContextState.kFinished) {
+                throw new Error("Child context outlives its parent");
+            }
+        });
+        this.progressReporter?.newCompletedContext();
+        this.dependencies.clear();
+        this.state = ContextState.kFinished;
+    }
+}
+//# sourceMappingURL=context.js.map

package/src/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["context.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * @module\n * @mergeModuleWith <project>\n */\nimport {\n  type Unvalidated,\n  validateArray,\n  validateNumber,\n  validateString\n} from \"@buildkitchen/validation\";\nimport { type ContextJSON } from \"./common.js\";\n\nenum ContextState {\n  kInProgess,\n  kFinished\n}\n\nexport interface ContextProgressReporter {\n  newContext(): void;\n  newCompletedContext(): void;\n}\n\nexport class Context {\n  private _hash: string | undefined;\n  private nextChildID = 0;\n  private readonly dependencies = new Map<string, Context>();\n  private state = ContextState.kInProgess;\n\n  static root(rootID: string, progressReporter?: ContextProgressReporter) {\n    return new Context(rootID, [], progressReporter);\n  }\n  private constructor(\n    public readonly rootID: string,\n    private readonly ids: ReadonlyArray<number>,\n    private readonly progressReporter?: ContextProgressReporter\n  ) {\n    progressReporter?.newContext();\n  }\n\n  cachedHash() {\n    this._hash ??= `root: ${this.rootID} ids: [${this.ids.join(\",\")}]`;\n    return this._hash;\n  }\n\n  isParentOf(other: Context) {\n    if (this.rootID !== other.rootID) {\n      return false;\n    }\n    if (this.ids.length >= other.ids.length) {\n      return false;\n    }\n\n    for (let i = 0; i < this.ids.length; ++i) {\n      if (this.ids[i] !== other.ids[i]) {\n        return false;\n      }\n    }\n\n    return true;\n  }\n\n  private checkForCycles() {\n    const stack = new Array<{\n      readonly context: Context;\n      readonly markAsSafe: () => void;\n    }>();\n\n    enum CycleContextState {\n      kVisited,\n      kSafe\n    }\n\n    const contextStates = new Map<string, CycleContextState>();\n\n    stack.push({\n      context: this,\n      markAsSafe: () => {\n        // marking as safe doesn't do anything at the top level\n      }\n    });\n\n    while (true) {\n      const stackItem = stack.pop();\n      if (stackItem === undefined) {\n        return;\n      }\n      const { context, markAsSafe } = stackItem;\n\n      const state = contextStates.get(context.cachedHash());\n      if (state === CycleContextState.kSafe) {\n        markAsSafe();\n        continue;\n      }\n\n      if (state === CycleContextState.kVisited) {\n        //debugger;\n        throw new Error(`Cycle detected in context dependency graph`);\n      }\n\n      if (context.dependencies.size === 0) {\n        contextStates.set(context.cachedHash(), CycleContextState.kSafe);\n        markAsSafe();\n        continue;\n      }\n\n      contextStates.set(context.cachedHash(), CycleContextState.kVisited);\n\n      let depCounter = 1;\n      const resolvedDep = () => {\n        if (--depCounter === 0) {\n          contextStates.set(context.cachedHash(), CycleContextState.kSafe);\n          markAsSafe();\n        }\n      };\n\n      for (const dep of context.dependencies.values()) {\n        ++depCounter;\n        stack.push({\n          context: dep,\n          markAsSafe: resolvedDep\n        });\n      }\n\n      resolvedDep();\n    }\n  }\n\n  addDependency(context: Context) {\n    if (!this.dependencies.has(context.cachedHash())) {\n      this.dependencies.set(context.cachedHash(), context);\n      context.checkForCycles();\n    }\n  }\n\n  withChildContext<T>(\n    behavior: (context: Context) => PromiseLike<T>\n  ): PromiseLike<T> {\n    if (this.state === ContextState.kFinished) {\n      return Promise.reject(\n        new Error(\"Cannot add more children to a finished context\")\n      );\n    }\n    const childContext = new Context(\n      this.rootID,\n      [...this.ids, this.nextChildID++],\n      this.progressReporter\n    );\n    this.dependencies.set(childContext.cachedHash(), childContext);\n    try {\n      return behavior(childContext).then(\n        (value) => {\n          this.dependencies.delete(childContext.cachedHash());\n          childContext.setFinished();\n          return value;\n        },\n        (e: unknown) => {\n          this.dependencies.delete(childContext.cachedHash());\n          throw e;\n        }\n      );\n    } catch (e) {\n      this.dependencies.delete(childContext.cachedHash());\n      return Promise.reject(e);\n    }\n  }\n\n  withChildContextSync<T>(behavior: (context: Context) => T): T {\n    if (this.state === ContextState.kFinished) {\n      throw new Error(\"Cannot add more children to a finished context\");\n    }\n    const childContext = new Context(\n      this.rootID,\n      [...this.ids, this.nextChildID++],\n      this.progressReporter\n    );\n    this.dependencies.set(childContext.cachedHash(), childContext);\n\n    const value = behavior(childContext);\n    this.dependencies.delete(childContext.cachedHash());\n    childContext.setFinished();\n    return value;\n  }\n\n  static fromJSON(context: Unvalidated<ContextJSON>) {\n    return new Context(\n      validateString(context.get(\"rootID\")),\n      validateArray(context.get(\"ids\"), validateNumber)\n    );\n  }\n\n  // force you to create a new context in order to get JSON to make sure you don't JSON-infy a context shared by others.\n  withJSON<T>(behavior: (context: ContextJSON) => T) {\n    return this.withChildContextSync((context) => {\n      const contextJSON: ContextJSON = {\n        rootID: context.rootID,\n        ids: [...context.ids]\n      };\n      return behavior(contextJSON);\n    });\n  }\n\n  toJSON(): ContextJSON {\n    return {\n      rootID: this.rootID,\n      ids: [...this.ids]\n    };\n  }\n\n  private setFinished() {\n    if (this.state === ContextState.kFinished) {\n      // Don't hard error. Promises allow for resolve/reject to both be called.\n      return;\n    }\n\n    //all of your dependencies should be finished too.\n    this.dependencies.forEach((dep) => {\n      if (dep.state !== ContextState.kFinished) {\n        throw new Error(\"Child context outlives its parent\");\n      }\n    });\n\n    this.progressReporter?.newCompletedContext();\n    this.dependencies.clear();\n    this.state = ContextState.kFinished;\n  }\n}\n"]}

package/src/readonly_context.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @module
+ * @mergeModuleWith <project>
+ */
+import { type Unvalidated } from "@buildkitchen/validation";
+import { type ContextJSON } from "./common.js";
+export declare class ReadonlyContext {
+    readonly rootID: string;
+    private readonly ids;
+    private _cachedHash;
+    constructor(rootID: string, ids: ReadonlyArray<number>);
+    cachedHash(): string;
+    static hash(context: ContextJSON): string;
+    parent(): ReadonlyContext | undefined;
+    toJSON(): ContextJSON;
+    static fromJSON(json: Unvalidated<ContextJSON>): ReadonlyContext;
+}
+//# sourceMappingURL=readonly_context.d.ts.map

package/src/readonly_context.js

@@ -0,0 +1,34 @@
+/**
+ * @module
+ * @mergeModuleWith <project>
+ */
+import { validateArray, validateNumber, validateString } from "@buildkitchen/validation";
+export class ReadonlyContext {
+    constructor(rootID, ids) {
+        this.rootID = rootID;
+        this.ids = ids;
+    }
+    cachedHash() {
+        this._cachedHash ?? (this._cachedHash = ReadonlyContext.hash(this.toJSON()));
+        return this._cachedHash;
+    }
+    static hash(context) {
+        return `root: ${context.rootID} ids: [${context.ids.join(",")}]`;
+    }
+    parent() {
+        if (this.ids.length === 0) {
+            return undefined;
+        }
+        return new ReadonlyContext(this.rootID, this.ids.slice(0, -1));
+    }
+    toJSON() {
+        return {
+            rootID: this.rootID,
+            ids: this.ids
+        };
+    }
+    static fromJSON(json) {
+        return new ReadonlyContext(validateString(json.get("rootID")), validateArray(json.get("ids"), validateNumber));
+    }
+}
+//# sourceMappingURL=readonly_context.js.map

package/src/readonly_context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"readonly_context.js","sourceRoot":"","sources":["readonly_context.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAEL,aAAa,EACb,cAAc,EACd,cAAc,EACf,MAAM,0BAA0B,CAAC;AAGlC,MAAM,OAAO,eAAe;IAG1B,YACkB,MAAc,EACb,GAA0B;QAD3B,WAAM,GAAN,MAAM,CAAQ;QACb,QAAG,GAAH,GAAG,CAAuB;IAC1C,CAAC;IAEJ,UAAU;QACR,IAAI,CAAC,WAAW,KAAhB,IAAI,CAAC,WAAW,GAAK,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,EAAC;QACzD,OAAO,IAAI,CAAC,WAAW,CAAC;IAC1B,CAAC;IAED,MAAM,CAAC,IAAI,CAAC,OAAoB;QAC9B,OAAO,SAAS,OAAO,CAAC,MAAM,UAAU,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;IACnE,CAAC;IAED,MAAM;QACJ,IAAI,IAAI,CAAC,GAAG,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC1B,OAAO,SAAS,CAAC;QACnB,CAAC;QAED,OAAO,IAAI,eAAe,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;IACjE,CAAC;IAED,MAAM;QACJ,OAAO;YACL,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,GAAG,EAAE,IAAI,CAAC,GAAG;SACd,CAAC;IACJ,CAAC;IAED,MAAM,CAAC,QAAQ,CAAC,IAA8B;QAC5C,OAAO,IAAI,eAAe,CACxB,cAAc,CAAC,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,EAClC,aAAa,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,cAAc,CAAC,CAC/C,CAAC;IACJ,CAAC;CACF","sourcesContent":["/**\n * @module\n * @mergeModuleWith <project>\n */\nimport {\n  type Unvalidated,\n  validateArray,\n  validateNumber,\n  validateString\n} from \"@buildkitchen/validation\";\nimport { type ContextJSON } from \"./common.js\";\n\nexport class ReadonlyContext {\n  private _cachedHash: string | undefined;\n\n  constructor(\n    public readonly rootID: string,\n    private readonly ids: ReadonlyArray<number>\n  ) {}\n\n  cachedHash() {\n    this._cachedHash ??= ReadonlyContext.hash(this.toJSON());\n    return this._cachedHash;\n  }\n\n  static hash(context: ContextJSON) {\n    return `root: ${context.rootID} ids: [${context.ids.join(\",\")}]`;\n  }\n\n  parent(): ReadonlyContext | undefined {\n    if (this.ids.length === 0) {\n      return undefined;\n    }\n\n    return new ReadonlyContext(this.rootID, this.ids.slice(0, -1));\n  }\n\n  toJSON(): ContextJSON {\n    return {\n      rootID: this.rootID,\n      ids: this.ids\n    };\n  }\n\n  static fromJSON(json: Unvalidated<ContextJSON>) {\n    return new ReadonlyContext(\n      validateString(json.get(\"rootID\")),\n      validateArray(json.get(\"ids\"), validateNumber)\n    );\n  }\n}\n"]}