@dxos/context 0.4.10-main.fa5a270 → 0.4.10-main.fd4f2a3

package/dist/lib/browser/index.mjs

@@ -1,8 +1,9 @@
 // packages/common/context/src/context.ts
+import { inspect } from "@dxos/node-std/util";
 import { log } from "@dxos/log";
 import { safeInstanceof } from "@dxos/util";
 
-// packages/common/context/src/context-disposed.ts
+// packages/common/context/src/context-disposed-error.ts
 var ContextDisposedError = class extends Error {
   constructor() {
     super("Context disposed.");
@@ -22,6 +23,7 @@ function _ts_decorate(decorators, target, key, desc) {
 }
 var __dxlog_file = "/home/runner/work/dxos/dxos/packages/common/context/src/context.ts";
 var MAX_SAFE_DISPOSE_CALLBACKS = 300;
+var _a, _b;
 var Context = class _Context {
   constructor({ onError = (error) => {
     if (error instanceof ContextDisposedError) {
@@ -35,12 +37,20 @@ var Context = class _Context {
     this._disposePromise = void 0;
     this._parent = null;
     this.maxSafeDisposeCallbacks = MAX_SAFE_DISPOSE_CALLBACKS;
+    this[_a] = "Context";
+    this[_b] = () => this.toString();
     this._onError = onError;
     this._attributes = attributes;
     if (parent !== void 0) {
       this._parent = parent;
     }
   }
+  static {
+    _a = Symbol.toStringTag, _b = inspect.custom;
+  }
+  static default() {
+    return new _Context();
+  }
   get disposed() {
     return this._isDisposed;
   }
@@ -64,7 +74,7 @@ var Context = class _Context {
         } catch (error) {
           log.catch(error, void 0, {
             F: __dxlog_file,
-            L: 82,
+            L: 88,
             S: this,
             C: (f, a) => f(...a)
           });
@@ -78,7 +88,7 @@ var Context = class _Context {
         safeThreshold: this.maxSafeDisposeCallbacks
       }, {
         F: __dxlog_file,
-        L: 89,
+        L: 95,
         S: this,
         C: (f, a) => f(...a)
       });
@@ -116,7 +126,7 @@ var Context = class _Context {
         } catch (error) {
           log.catch(error, void 0, {
             F: __dxlog_file,
-            L: 132,
+            L: 138,
             S: this,
             C: (f, a) => f(...a)
           });
@@ -173,6 +183,9 @@ var Context = class _Context {
     }
     return void 0;
   }
+  toString() {
+    return `Context(${this._isDisposed ? "disposed" : "active"})`;
+  }
 };
 Context = _ts_decorate([
   safeInstanceof("Context")
@@ -191,10 +204,127 @@ var cancelWithContext = (ctx, promise) => {
     })
   ]).finally(() => clearDispose?.());
 };
+
+// packages/common/context/src/resource.ts
+import "@dxos/util";
+var LifecycleState;
+(function(LifecycleState2) {
+  LifecycleState2["CLOSED"] = "CLOSED";
+  LifecycleState2["OPEN"] = "OPEN";
+  LifecycleState2["ERROR"] = "ERROR";
+})(LifecycleState || (LifecycleState = {}));
+var Resource = class {
+  #lifecycleState = "CLOSED";
+  #openPromise = null;
+  #closePromise = null;
+  /**
+  * Managed internally by the resource.
+  * Recreated on close.
+  * Errors are propagated to the `_catch` method and the parent context.
+  */
+  #internalCtx = this.#createContext();
+  /**
+  * Context that is used to bubble up errors that are not handled by the resource.
+  * Provided in the open method.
+  */
+  #parentCtx = new Context();
+  get _lifecycleState() {
+    return this.#lifecycleState;
+  }
+  get _ctx() {
+    return this.#internalCtx;
+  }
+  /**
+  * To be overridden by subclasses.
+  */
+  async _open(ctx) {
+  }
+  /**
+  * To be overridden by subclasses.
+  */
+  async _close(ctx) {
+  }
+  /**
+  * Error handler for errors that are caught by the context.
+  * By default errors are bubbled up to the parent context which is passed to the open method.
+  */
+  async _catch(err) {
+    throw err;
+  }
+  /**
+  * Opens the resource.
+  * If the resource is already open, it does nothing.
+  * If the resource is in an error state, it throws an error.
+  * If the resource is closed, it waits for it to close and then opens it.
+  * @param ctx - Context to use for opening the resource. This context will receive errors that are not handled in `_catch`.
+  */
+  async open(ctx) {
+    switch (this.#lifecycleState) {
+      case "OPEN":
+        return this;
+      case "ERROR":
+        throw new Error(`Invalid state: ${this.#lifecycleState}`);
+      default:
+    }
+    await this.#closePromise;
+    await (this.#openPromise ??= this.#open(ctx));
+    return this;
+  }
+  /**
+  * Closes the resource.
+  * If the resource is already closed, it does nothing.
+  */
+  async close(ctx) {
+    if (this.#lifecycleState === "CLOSED") {
+      return this;
+    }
+    await this.#openPromise;
+    await (this.#closePromise ??= this.#close(ctx));
+    return this;
+  }
+  async [Symbol.asyncDispose]() {
+    await this.close();
+  }
+  async #open(ctx) {
+    this.#closePromise = null;
+    if (ctx) {
+      this.#parentCtx = ctx;
+    }
+    await this._open(this.#parentCtx);
+    this.#lifecycleState = "OPEN";
+  }
+  async #close(ctx = new Context()) {
+    this.#openPromise = null;
+    await this.#internalCtx.dispose();
+    await this._close(ctx);
+    this.#internalCtx = this.#createContext();
+    this.#lifecycleState = "CLOSED";
+  }
+  #createContext() {
+    return new Context({
+      onError: (error) => queueMicrotask(async () => {
+        try {
+          await this._catch(error);
+        } catch (err) {
+          this.#lifecycleState = "ERROR";
+          this.#parentCtx.raise(err);
+        }
+      })
+    });
+  }
+};
+var openInContext = async (ctx, resource) => {
+  await resource.open?.(ctx);
+  ctx.onDispose(() => resource.close?.());
+  return resource;
+};
 export {
   Context,
   ContextDisposedError,
+  LifecycleState,
+  Resource,
   cancelWithContext,
+  openInContext,
   rejectOnDispose
 };
 //# sourceMappingURL=index.mjs.map

package/dist/lib/browser/index.mjs.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
-  "sources": ["../../../src/context.ts", "../../../src/context-disposed.ts", "../../../src/promise-utils.ts"],
-  "sourcesContent": ["//\n// Copyright 2022 DXOS.org\n//\n\nimport { log } from '@dxos/log';\nimport { safeInstanceof } from '@dxos/util';\n\nimport { ContextDisposedError } from './context-disposed';\n\nexport type ContextErrorHandler = (error: Error) => void;\n\nexport type DisposeCallback = () => void | Promise<void>;\n\nexport type CreateContextParams = {\n  onError?: ContextErrorHandler;\n  attributes?: Record<string, any>;\n  parent?: Context;\n};\n\n/**\n * Maximum number of dispose callbacks before we start logging warnings.\n */\nconst MAX_SAFE_DISPOSE_CALLBACKS = 300;\n\n@safeInstanceof('Context')\nexport class Context {\n  private readonly _onError: ContextErrorHandler;\n  private readonly _disposeCallbacks: DisposeCallback[] = [];\n  private _isDisposed = false;\n  private _disposePromise?: Promise<void> = undefined;\n  private _parent: Context | null = null;\n\n  private _attributes: Record<string, any>;\n\n  public maxSafeDisposeCallbacks = MAX_SAFE_DISPOSE_CALLBACKS;\n\n  constructor({\n    onError = (error) => {\n      if (error instanceof ContextDisposedError) {\n        return;\n      }\n\n      void this.dispose();\n\n      // Will generate an unhandled rejection.\n      throw error;\n    },\n    attributes = {},\n    parent,\n  }: CreateContextParams = {}) {\n    this._onError = onError;\n    this._attributes = attributes;\n    if (parent !== undefined) {\n      this._parent = parent;\n    }\n  }\n\n  get disposed() {\n    return this._isDisposed;\n  }\n\n  get disposeCallbacksLength() {\n    return this._disposeCallbacks.length;\n  }\n\n  /**\n   * Schedules a callback to run when the context is disposed.\n   * May be async, in this case the disposer might choose to wait for all resource to released.\n   * Throwing an error inside the callback will result in the error being logged, but not re-thrown.\n   *\n   * NOTE: Will call the callback immediately if the context is already disposed.\n   *\n   * @returns A function that can be used to remove the callback from the dispose list.\n   */\n  onDispose(callback: DisposeCallback) {\n    if (this._isDisposed) {\n      // Call the callback immediately if the context is already disposed.\n      void (async () => {\n        try {\n          await callback();\n        } catch (error: any) {\n          log.catch(error);\n        }\n      })();\n    }\n\n    this._disposeCallbacks.push(callback);\n    if (this._disposeCallbacks.length > this.maxSafeDisposeCallbacks) {\n      log.warn('Context has a large number of dispose callbacks. This might be a memory leak.', {\n        count: this._disposeCallbacks.length,\n        safeThreshold: this.maxSafeDisposeCallbacks,\n      });\n    }\n\n    return () => {\n      const index = this._disposeCallbacks.indexOf(callback);\n      if (index !== -1) {\n        this._disposeCallbacks.splice(index, 1);\n      }\n    };\n  }\n\n  /**\n   * Runs all dispose callbacks.\n   * Sync callbacks are run in the reverse order they were added.\n   * Async callbacks are run in parallel.\n   * This function never throws.\n   * It is safe to ignore the returned promise if the caller does not wish to wait for callbacks to complete.\n   * Disposing context means that onDispose will throw an error and any errors raised will be logged and not propagated.\n   */\n  dispose(): Promise<void> {\n    if (this._disposePromise) {\n      return this._disposePromise;\n    }\n    this._isDisposed = true;\n\n    // Set the promise before running the callbacks.\n    let resolveDispose: () => void;\n    this._disposePromise = new Promise<void>((resolve) => {\n      resolveDispose = resolve;\n    });\n\n    const promises = [];\n    // Clone the array so that any mutations to the original array don't affect the dispose process.\n    const callbacks = Array.from(this._disposeCallbacks).reverse();\n    for (const callback of callbacks) {\n      promises.push(\n        (async () => {\n          try {\n            await callback();\n          } catch (error: any) {\n            log.catch(error);\n          }\n        })(),\n      );\n    }\n    this._disposeCallbacks.length = 0;\n\n    void Promise.all(promises).then(() => {\n      resolveDispose();\n    });\n\n    return this._disposePromise;\n  }\n\n  /**\n   * Raise the error inside the context.\n   * The error will be propagated to the error handler.\n   * IF the error handler is not set, the error will dispose the context and cause an unhandled rejection.\n   */\n  raise(error: Error): void {\n    if (this._isDisposed) {\n      // TODO(dmaretskyi): Don't log those.\n      // log.warn('Error in disposed context', error);\n      return;\n    }\n\n    try {\n      this._onError(error);\n    } catch (err) {\n      // Generate an unhandled rejection and stop the error propagation.\n      void Promise.reject(err);\n    }\n  }\n\n  derive({ onError, attributes }: CreateContextParams = {}): Context {\n    const newCtx = new Context({\n      // TODO(dmaretskyi): Optimize to not require allocating a new closure for every context.\n      onError: async (error) => {\n        if (!onError) {\n          this.raise(error);\n        } else {\n          try {\n            await onError(error);\n          } catch {\n            this.raise(error);\n          }\n        }\n      },\n      attributes,\n    });\n    const clearDispose = this.onDispose(() => newCtx.dispose());\n    newCtx.onDispose(clearDispose);\n    return newCtx;\n  }\n\n  getAttribute(key: string): any {\n    if (key in this._attributes) {\n      return this._attributes[key];\n    }\n    if (this._parent !== null) {\n      return this._parent.getAttribute(key);\n    }\n    return undefined;\n  }\n}\n", "//\n// Copyright 2023 DXOS.org\n//\n\nexport class ContextDisposedError extends Error {\n  constructor() {\n    super('Context disposed.');\n  }\n}\n", "//\n// Copyright 2023 DXOS.org\n//\n\nimport { type Context } from './context';\nimport { ContextDisposedError } from './context-disposed';\n\n/**\n * @returns A promise that rejects when the context is disposed.\n */\n// TODO(dmaretskyi): Memory leak.\nexport const rejectOnDispose = (ctx: Context, error = new ContextDisposedError()): Promise<never> =>\n  new Promise((resolve, reject) => {\n    ctx.onDispose(() => reject(error));\n  });\n\n/**\n * Rejects the promise if the context is disposed.\n */\nexport const cancelWithContext = <T>(ctx: Context, promise: Promise<T>): Promise<T> => {\n  let clearDispose: () => void;\n  return Promise.race([\n    promise,\n    new Promise<never>((resolve, reject) => {\n      // Will be called before .finally() handlers.\n      clearDispose = ctx.onDispose(() => reject(new ContextDisposedError()));\n    }),\n  ]).finally(() => clearDispose?.());\n};\n"],
-  "mappings": "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",
-  "names": ["log", "safeInstanceof", "ContextDisposedError", "Error", "constructor", "MAX_SAFE_DISPOSE_CALLBACKS", "Context", "constructor", "onError", "error", "ContextDisposedError", "dispose", "attributes", "parent", "_disposeCallbacks", "_isDisposed", "_disposePromise", "undefined", "_parent", "maxSafeDisposeCallbacks", "_onError", "_attributes", "disposed", "disposeCallbacksLength", "length", "onDispose", "callback", "log", "catch", "push", "warn", "count", "safeThreshold", "index", "indexOf", "splice", "resolveDispose", "Promise", "resolve", "promises", "callbacks", "Array", "from", "reverse", "all", "then", "raise", "err", "reject", "derive", "newCtx", "clearDispose", "getAttribute", "key", "safeInstanceof", "rejectOnDispose", "ctx", "error", "ContextDisposedError", "Promise", "resolve", "reject", "onDispose", "cancelWithContext", "promise", "clearDispose", "race", "finally"]
+  "sources": ["../../../src/context.ts", "../../../src/context-disposed-error.ts", "../../../src/promise-utils.ts", "../../../src/resource.ts"],
+  "sourcesContent": ["//\n// Copyright 2022 DXOS.org\n//\n\nimport { inspect } from 'node:util';\n\nimport { log } from '@dxos/log';\nimport { safeInstanceof } from '@dxos/util';\n\nimport { ContextDisposedError } from './context-disposed-error';\n\nexport type ContextErrorHandler = (error: Error) => void;\n\nexport type DisposeCallback = () => any | Promise<any>;\n\nexport type CreateContextParams = {\n  onError?: ContextErrorHandler;\n  attributes?: Record<string, any>;\n  parent?: Context;\n};\n\n/**\n * Maximum number of dispose callbacks before we start logging warnings.\n */\nconst MAX_SAFE_DISPOSE_CALLBACKS = 300;\n\n@safeInstanceof('Context')\nexport class Context {\n  static default() {\n    return new Context();\n  }\n\n  private readonly _onError: ContextErrorHandler;\n  private readonly _disposeCallbacks: DisposeCallback[] = [];\n  private _isDisposed = false;\n  private _disposePromise?: Promise<void> = undefined;\n  private _parent: Context | null = null;\n\n  private _attributes: Record<string, any>;\n\n  public maxSafeDisposeCallbacks = MAX_SAFE_DISPOSE_CALLBACKS;\n\n  constructor({\n    onError = (error) => {\n      if (error instanceof ContextDisposedError) {\n        return;\n      }\n\n      void this.dispose();\n\n      // Will generate an unhandled rejection.\n      throw error;\n    },\n    attributes = {},\n    parent,\n  }: CreateContextParams = {}) {\n    this._onError = onError;\n    this._attributes = attributes;\n    if (parent !== undefined) {\n      this._parent = parent;\n    }\n  }\n\n  get disposed() {\n    return this._isDisposed;\n  }\n\n  get disposeCallbacksLength() {\n    return this._disposeCallbacks.length;\n  }\n\n  /**\n   * Schedules a callback to run when the context is disposed.\n   * May be async, in this case the disposer might choose to wait for all resource to released.\n   * Throwing an error inside the callback will result in the error being logged, but not re-thrown.\n   *\n   * NOTE: Will call the callback immediately if the context is already disposed.\n   *\n   * @returns A function that can be used to remove the callback from the dispose list.\n   */\n  onDispose(callback: DisposeCallback) {\n    if (this._isDisposed) {\n      // Call the callback immediately if the context is already disposed.\n      void (async () => {\n        try {\n          await callback();\n        } catch (error: any) {\n          log.catch(error);\n        }\n      })();\n    }\n\n    this._disposeCallbacks.push(callback);\n    if (this._disposeCallbacks.length > this.maxSafeDisposeCallbacks) {\n      log.warn('Context has a large number of dispose callbacks. This might be a memory leak.', {\n        count: this._disposeCallbacks.length,\n        safeThreshold: this.maxSafeDisposeCallbacks,\n      });\n    }\n\n    return () => {\n      const index = this._disposeCallbacks.indexOf(callback);\n      if (index !== -1) {\n        this._disposeCallbacks.splice(index, 1);\n      }\n    };\n  }\n\n  /**\n   * Runs all dispose callbacks.\n   * Sync callbacks are run in the reverse order they were added.\n   * Async callbacks are run in parallel.\n   * This function never throws.\n   * It is safe to ignore the returned promise if the caller does not wish to wait for callbacks to complete.\n   * Disposing context means that onDispose will throw an error and any errors raised will be logged and not propagated.\n   */\n  dispose(): Promise<void> {\n    if (this._disposePromise) {\n      return this._disposePromise;\n    }\n    this._isDisposed = true;\n\n    // Set the promise before running the callbacks.\n    let resolveDispose: () => void;\n    this._disposePromise = new Promise<void>((resolve) => {\n      resolveDispose = resolve;\n    });\n\n    const promises = [];\n    // Clone the array so that any mutations to the original array don't affect the dispose process.\n    const callbacks = Array.from(this._disposeCallbacks).reverse();\n    for (const callback of callbacks) {\n      promises.push(\n        (async () => {\n          try {\n            await callback();\n          } catch (error: any) {\n            log.catch(error);\n          }\n        })(),\n      );\n    }\n    this._disposeCallbacks.length = 0;\n\n    void Promise.all(promises).then(() => {\n      resolveDispose();\n    });\n\n    return this._disposePromise;\n  }\n\n  /**\n   * Raise the error inside the context.\n   * The error will be propagated to the error handler.\n   * IF the error handler is not set, the error will dispose the context and cause an unhandled rejection.\n   */\n  raise(error: Error): void {\n    if (this._isDisposed) {\n      // TODO(dmaretskyi): Don't log those.\n      // log.warn('Error in disposed context', error);\n      return;\n    }\n\n    try {\n      this._onError(error);\n    } catch (err) {\n      // Generate an unhandled rejection and stop the error propagation.\n      void Promise.reject(err);\n    }\n  }\n\n  derive({ onError, attributes }: CreateContextParams = {}): Context {\n    const newCtx = new Context({\n      // TODO(dmaretskyi): Optimize to not require allocating a new closure for every context.\n      onError: async (error) => {\n        if (!onError) {\n          this.raise(error);\n        } else {\n          try {\n            await onError(error);\n          } catch {\n            this.raise(error);\n          }\n        }\n      },\n      attributes,\n    });\n    const clearDispose = this.onDispose(() => newCtx.dispose());\n    newCtx.onDispose(clearDispose);\n    return newCtx;\n  }\n\n  getAttribute(key: string): any {\n    if (key in this._attributes) {\n      return this._attributes[key];\n    }\n    if (this._parent !== null) {\n      return this._parent.getAttribute(key);\n    }\n    return undefined;\n  }\n\n  [Symbol.toStringTag] = 'Context';\n\n  [inspect.custom] = () => this.toString();\n\n  toString() {\n    return `Context(${this._isDisposed ? 'disposed' : 'active'})`;\n  }\n}\n", "//\n// Copyright 2023 DXOS.org\n//\n\nexport class ContextDisposedError extends Error {\n  constructor() {\n    super('Context disposed.');\n  }\n}\n", "//\n// Copyright 2023 DXOS.org\n//\n\nimport { type Context } from './context';\nimport { ContextDisposedError } from './context-disposed-error';\n\n/**\n * @returns A promise that rejects when the context is disposed.\n */\n// TODO(dmaretskyi): Memory leak.\nexport const rejectOnDispose = (ctx: Context, error = new ContextDisposedError()): Promise<never> =>\n  new Promise((resolve, reject) => {\n    ctx.onDispose(() => reject(error));\n  });\n\n/**\n * Rejects the promise if the context is disposed.\n */\nexport const cancelWithContext = <T>(ctx: Context, promise: Promise<T>): Promise<T> => {\n  let clearDispose: () => void;\n  return Promise.race([\n    promise,\n    new Promise<never>((resolve, reject) => {\n      // Will be called before .finally() handlers.\n      clearDispose = ctx.onDispose(() => reject(new ContextDisposedError()));\n    }),\n  ]).finally(() => clearDispose?.());\n};\n", "//\n// Copyright 2024 DXOS.org\n//\n\nimport '@dxos/util';\nimport { Context } from './context';\n\nexport interface Lifecycle {\n  open?(ctx?: Context): Promise<any> | any;\n  close?(): Promise<any> | any;\n}\n\nexport enum LifecycleState {\n  CLOSED = 'CLOSED',\n  OPEN = 'OPEN',\n  ERROR = 'ERROR',\n}\n\n/**\n * Base class for resources that need to be opened and closed.\n */\nexport class Resource implements Lifecycle {\n  #lifecycleState = LifecycleState.CLOSED;\n  #openPromise: Promise<void> | null = null;\n  #closePromise: Promise<void> | null = null;\n\n  /**\n   * Managed internally by the resource.\n   * Recreated on close.\n   * Errors are propagated to the `_catch` method and the parent context.\n   */\n  #internalCtx: Context = this.#createContext();\n\n  /**\n   * Context that is used to bubble up errors that are not handled by the resource.\n   * Provided in the open method.\n   */\n  #parentCtx: Context = new Context();\n\n  protected get _lifecycleState() {\n    return this.#lifecycleState;\n  }\n\n  protected get _ctx() {\n    return this.#internalCtx;\n  }\n\n  /**\n   * To be overridden by subclasses.\n   */\n  protected async _open(ctx: Context): Promise<void> {}\n\n  /**\n   * To be overridden by subclasses.\n   */\n  protected async _close(ctx: Context): Promise<void> {}\n\n  /**\n   * Error handler for errors that are caught by the context.\n   * By default errors are bubbled up to the parent context which is passed to the open method.\n   */\n  protected async _catch(err: Error): Promise<void> {\n    throw err;\n  }\n\n  /**\n   * Opens the resource.\n   * If the resource is already open, it does nothing.\n   * If the resource is in an error state, it throws an error.\n   * If the resource is closed, it waits for it to close and then opens it.\n   * @param ctx - Context to use for opening the resource. This context will receive errors that are not handled in `_catch`.\n   */\n  async open(ctx?: Context): Promise<this> {\n    switch (this.#lifecycleState) {\n      case LifecycleState.OPEN:\n        return this;\n      case LifecycleState.ERROR:\n        throw new Error(`Invalid state: ${this.#lifecycleState}`);\n      default:\n    }\n    await this.#closePromise;\n    await (this.#openPromise ??= this.#open(ctx));\n\n    return this;\n  }\n\n  /**\n   * Closes the resource.\n   * If the resource is already closed, it does nothing.\n   */\n  async close(ctx?: Context): Promise<this> {\n    if (this.#lifecycleState === LifecycleState.CLOSED) {\n      return this;\n    }\n    await this.#openPromise;\n    await (this.#closePromise ??= this.#close(ctx));\n\n    return this;\n  }\n\n  async [Symbol.asyncDispose]() {\n    await this.close();\n  }\n\n  async #open(ctx?: Context) {\n    this.#closePromise = null;\n    if (ctx) {\n      this.#parentCtx = ctx;\n    }\n    await this._open(this.#parentCtx);\n    this.#lifecycleState = LifecycleState.OPEN;\n  }\n\n  async #close(ctx = new Context()) {\n    this.#openPromise = null;\n    await this.#internalCtx.dispose();\n    await this._close(ctx);\n    this.#internalCtx = this.#createContext();\n    this.#lifecycleState = LifecycleState.CLOSED;\n  }\n\n  #createContext() {\n    return new Context({\n      onError: (error) =>\n        queueMicrotask(async () => {\n          try {\n            await this._catch(error);\n          } catch (err: any) {\n            this.#lifecycleState = LifecycleState.ERROR;\n            this.#parentCtx.raise(err);\n          }\n        }),\n    });\n  }\n}\n\nexport const openInContext = async <T extends Lifecycle>(ctx: Context, resource: T): Promise<T> => {\n  await resource.open?.(ctx);\n  ctx.onDispose(() => resource.close?.());\n\n  return resource;\n};\n"],
+  "mappings": "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",
+  "names": ["inspect", "log", "safeInstanceof", "ContextDisposedError", "Error", "constructor", "MAX_SAFE_DISPOSE_CALLBACKS", "Context", "constructor", "onError", "error", "ContextDisposedError", "dispose", "attributes", "parent", "_disposeCallbacks", "_isDisposed", "_disposePromise", "undefined", "_parent", "maxSafeDisposeCallbacks", "Symbol", "inspect", "toString", "_onError", "_attributes", "toStringTag", "custom", "default", "disposed", "disposeCallbacksLength", "length", "onDispose", "callback", "log", "catch", "push", "warn", "count", "safeThreshold", "index", "indexOf", "splice", "resolveDispose", "Promise", "resolve", "promises", "callbacks", "Array", "from", "reverse", "all", "then", "raise", "err", "reject", "derive", "newCtx", "clearDispose", "getAttribute", "key", "safeInstanceof", "rejectOnDispose", "ctx", "error", "ContextDisposedError", "Promise", "resolve", "reject", "onDispose", "cancelWithContext", "promise", "clearDispose", "race", "finally", "LifecycleState", "Resource", "Context", "_lifecycleState", "_ctx", "_open", "ctx", "_close", "_catch", "err", "open", "Error", "close", "Symbol", "asyncDispose", "dispose", "onError", "error", "queueMicrotask", "raise", "openInContext", "resource", "onDispose"]
 }

package/dist/lib/browser/meta.json

@@ -1 +1 @@
-{"inputs":{"packages/common/context/src/context-disposed.ts":{"bytes":803,"imports":[],"format":"esm"},"packages/common/context/src/context.ts":{"bytes":18716,"imports":[{"path":"@dxos/log","kind":"import-statement","external":true},{"path":"@dxos/util","kind":"import-statement","external":true},{"path":"packages/common/context/src/context-disposed.ts","kind":"import-statement","original":"./context-disposed"}],"format":"esm"},"packages/common/context/src/promise-utils.ts":{"bytes":3026,"imports":[{"path":"packages/common/context/src/context-disposed.ts","kind":"import-statement","original":"./context-disposed"}],"format":"esm"},"packages/common/context/src/index.ts":{"bytes":675,"imports":[{"path":"packages/common/context/src/context.ts","kind":"import-statement","original":"./context"},{"path":"packages/common/context/src/promise-utils.ts","kind":"import-statement","original":"./promise-utils"},{"path":"packages/common/context/src/context-disposed.ts","kind":"import-statement","original":"./context-disposed"}],"format":"esm"}},"outputs":{"packages/common/context/dist/lib/browser/index.mjs.map":{"imports":[],"exports":[],"inputs":{},"bytes":10416},"packages/common/context/dist/lib/browser/index.mjs":{"imports":[{"path":"@dxos/log","kind":"import-statement","external":true},{"path":"@dxos/util","kind":"import-statement","external":true}],"exports":["Context","ContextDisposedError","cancelWithContext","rejectOnDispose"],"entryPoint":"packages/common/context/src/index.ts","inputs":{"packages/common/context/src/context.ts":{"bytesInOutput":5217},"packages/common/context/src/context-disposed.ts":{"bytesInOutput":106},"packages/common/context/src/index.ts":{"bytesInOutput":0},"packages/common/context/src/promise-utils.ts":{"bytesInOutput":410}},"bytes":6040}}}
+{"inputs":{"packages/common/context/src/context-disposed-error.ts":{"bytes":817,"imports":[],"format":"esm"},"packages/common/context/src/context.ts":{"bytes":19782,"imports":[{"path":"@dxos/node-std/util","kind":"import-statement","external":true},{"path":"@dxos/log","kind":"import-statement","external":true},{"path":"@dxos/util","kind":"import-statement","external":true},{"path":"packages/common/context/src/context-disposed-error.ts","kind":"import-statement","original":"./context-disposed-error"}],"format":"esm"},"packages/common/context/src/promise-utils.ts":{"bytes":3040,"imports":[{"path":"packages/common/context/src/context-disposed-error.ts","kind":"import-statement","original":"./context-disposed-error"}],"format":"esm"},"packages/common/context/src/resource.ts":{"bytes":11723,"imports":[{"path":"@dxos/util","kind":"import-statement","external":true},{"path":"packages/common/context/src/context.ts","kind":"import-statement","original":"./context"}],"format":"esm"},"packages/common/context/src/index.ts":{"bytes":777,"imports":[{"path":"packages/common/context/src/context.ts","kind":"import-statement","original":"./context"},{"path":"packages/common/context/src/promise-utils.ts","kind":"import-statement","original":"./promise-utils"},{"path":"packages/common/context/src/context-disposed-error.ts","kind":"import-statement","original":"./context-disposed-error"},{"path":"packages/common/context/src/resource.ts","kind":"import-statement","original":"./resource"}],"format":"esm"}},"outputs":{"packages/common/context/dist/lib/browser/index.mjs.map":{"imports":[],"exports":[],"inputs":{},"bytes":16404},"packages/common/context/dist/lib/browser/index.mjs":{"imports":[{"path":"@dxos/node-std/util","kind":"import-statement","external":true},{"path":"@dxos/log","kind":"import-statement","external":true},{"path":"@dxos/util","kind":"import-statement","external":true},{"path":"@dxos/util","kind":"import-statement","external":true}],"exports":["Context","ContextDisposedError","LifecycleState","Resource","cancelWithContext","openInContext","rejectOnDispose"],"entryPoint":"packages/common/context/src/index.ts","inputs":{"packages/common/context/src/context.ts":{"bytesInOutput":5543},"packages/common/context/src/context-disposed-error.ts":{"bytesInOutput":106},"packages/common/context/src/index.ts":{"bytesInOutput":0},"packages/common/context/src/promise-utils.ts":{"bytesInOutput":410},"packages/common/context/src/resource.ts":{"bytesInOutput":2978}},"bytes":9441}}}

package/dist/lib/node/index.cjs

@@ -20,12 +20,17 @@ var node_exports = {};
 __export(node_exports, {
   Context: () => Context,
   ContextDisposedError: () => ContextDisposedError,
+  LifecycleState: () => LifecycleState,
+  Resource: () => Resource,
   cancelWithContext: () => cancelWithContext,
+  openInContext: () => openInContext,
   rejectOnDispose: () => rejectOnDispose
 });
 module.exports = __toCommonJS(node_exports);
+var import_node_util = require("node:util");
 var import_log = require("@dxos/log");
 var import_util = require("@dxos/util");
+var import_util2 = require("@dxos/util");
 var ContextDisposedError = class extends Error {
   constructor() {
     super("Context disposed.");
@@ -43,6 +48,7 @@ function _ts_decorate(decorators, target, key, desc) {
 }
 var __dxlog_file = "/home/runner/work/dxos/dxos/packages/common/context/src/context.ts";
 var MAX_SAFE_DISPOSE_CALLBACKS = 300;
+var _a, _b;
 var Context = class _Context {
   constructor({ onError = (error) => {
     if (error instanceof ContextDisposedError) {
@@ -56,12 +62,20 @@ var Context = class _Context {
     this._disposePromise = void 0;
     this._parent = null;
     this.maxSafeDisposeCallbacks = MAX_SAFE_DISPOSE_CALLBACKS;
+    this[_a] = "Context";
+    this[_b] = () => this.toString();
     this._onError = onError;
     this._attributes = attributes;
     if (parent !== void 0) {
       this._parent = parent;
     }
   }
+  static {
+    _a = Symbol.toStringTag, _b = import_node_util.inspect.custom;
+  }
+  static default() {
+    return new _Context();
+  }
   get disposed() {
     return this._isDisposed;
   }
@@ -85,7 +99,7 @@ var Context = class _Context {
         } catch (error) {
           import_log.log.catch(error, void 0, {
             F: __dxlog_file,
-            L: 82,
+            L: 88,
             S: this,
             C: (f, a) => f(...a)
           });
@@ -99,7 +113,7 @@ var Context = class _Context {
         safeThreshold: this.maxSafeDisposeCallbacks
       }, {
         F: __dxlog_file,
-        L: 89,
+        L: 95,
         S: this,
         C: (f, a) => f(...a)
       });
@@ -137,7 +151,7 @@ var Context = class _Context {
         } catch (error) {
           import_log.log.catch(error, void 0, {
             F: __dxlog_file,
-            L: 132,
+            L: 138,
             S: this,
             C: (f, a) => f(...a)
           });
@@ -194,6 +208,9 @@ var Context = class _Context {
     }
     return void 0;
   }
+  toString() {
+    return `Context(${this._isDisposed ? "disposed" : "active"})`;
+  }
 };
 Context = _ts_decorate([
   (0, import_util.safeInstanceof)("Context")
@@ -210,11 +227,125 @@ var cancelWithContext = (ctx, promise) => {
     })
   ]).finally(() => clearDispose?.());
 };
+var LifecycleState;
+(function(LifecycleState2) {
+  LifecycleState2["CLOSED"] = "CLOSED";
+  LifecycleState2["OPEN"] = "OPEN";
+  LifecycleState2["ERROR"] = "ERROR";
+})(LifecycleState || (LifecycleState = {}));
+var Resource = class {
+  #lifecycleState = "CLOSED";
+  #openPromise = null;
+  #closePromise = null;
+  /**
+  * Managed internally by the resource.
+  * Recreated on close.
+  * Errors are propagated to the `_catch` method and the parent context.
+  */
+  #internalCtx = this.#createContext();
+  /**
+  * Context that is used to bubble up errors that are not handled by the resource.
+  * Provided in the open method.
+  */
+  #parentCtx = new Context();
+  get _lifecycleState() {
+    return this.#lifecycleState;
+  }
+  get _ctx() {
+    return this.#internalCtx;
+  }
+  /**
+  * To be overridden by subclasses.
+  */
+  async _open(ctx) {
+  }
+  /**
+  * To be overridden by subclasses.
+  */
+  async _close(ctx) {
+  }
+  /**
+  * Error handler for errors that are caught by the context.
+  * By default errors are bubbled up to the parent context which is passed to the open method.
+  */
+  async _catch(err) {
+    throw err;
+  }
+  /**
+  * Opens the resource.
+  * If the resource is already open, it does nothing.
+  * If the resource is in an error state, it throws an error.
+  * If the resource is closed, it waits for it to close and then opens it.
+  * @param ctx - Context to use for opening the resource. This context will receive errors that are not handled in `_catch`.
+  */
+  async open(ctx) {
+    switch (this.#lifecycleState) {
+      case "OPEN":
+        return this;
+      case "ERROR":
+        throw new Error(`Invalid state: ${this.#lifecycleState}`);
+      default:
+    }
+    await this.#closePromise;
+    await (this.#openPromise ??= this.#open(ctx));
+    return this;
+  }
+  /**
+  * Closes the resource.
+  * If the resource is already closed, it does nothing.
+  */
+  async close(ctx) {
+    if (this.#lifecycleState === "CLOSED") {
+      return this;
+    }
+    await this.#openPromise;
+    await (this.#closePromise ??= this.#close(ctx));
+    return this;
+  }
+  async [Symbol.asyncDispose]() {
+    await this.close();
+  }
+  async #open(ctx) {
+    this.#closePromise = null;
+    if (ctx) {
+      this.#parentCtx = ctx;
+    }
+    await this._open(this.#parentCtx);
+    this.#lifecycleState = "OPEN";
+  }
+  async #close(ctx = new Context()) {
+    this.#openPromise = null;
+    await this.#internalCtx.dispose();
+    await this._close(ctx);
+    this.#internalCtx = this.#createContext();
+    this.#lifecycleState = "CLOSED";
+  }
+  #createContext() {
+    return new Context({
+      onError: (error) => queueMicrotask(async () => {
+        try {
+          await this._catch(error);
+        } catch (err) {
+          this.#lifecycleState = "ERROR";
+          this.#parentCtx.raise(err);
+        }
+      })
+    });
+  }
+};
+var openInContext = async (ctx, resource) => {
+  await resource.open?.(ctx);
+  ctx.onDispose(() => resource.close?.());
+  return resource;
+};
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   Context,
   ContextDisposedError,
+  LifecycleState,
+  Resource,
   cancelWithContext,
+  openInContext,
   rejectOnDispose
 });
 //# sourceMappingURL=index.cjs.map

package/dist/lib/node/index.cjs.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
-  "sources": ["../../../src/context.ts", "../../../src/context-disposed.ts", "../../../src/promise-utils.ts"],
-  "sourcesContent": ["//\n// Copyright 2022 DXOS.org\n//\n\nimport { log } from '@dxos/log';\nimport { safeInstanceof } from '@dxos/util';\n\nimport { ContextDisposedError } from './context-disposed';\n\nexport type ContextErrorHandler = (error: Error) => void;\n\nexport type DisposeCallback = () => void | Promise<void>;\n\nexport type CreateContextParams = {\n  onError?: ContextErrorHandler;\n  attributes?: Record<string, any>;\n  parent?: Context;\n};\n\n/**\n * Maximum number of dispose callbacks before we start logging warnings.\n */\nconst MAX_SAFE_DISPOSE_CALLBACKS = 300;\n\n@safeInstanceof('Context')\nexport class Context {\n  private readonly _onError: ContextErrorHandler;\n  private readonly _disposeCallbacks: DisposeCallback[] = [];\n  private _isDisposed = false;\n  private _disposePromise?: Promise<void> = undefined;\n  private _parent: Context | null = null;\n\n  private _attributes: Record<string, any>;\n\n  public maxSafeDisposeCallbacks = MAX_SAFE_DISPOSE_CALLBACKS;\n\n  constructor({\n    onError = (error) => {\n      if (error instanceof ContextDisposedError) {\n        return;\n      }\n\n      void this.dispose();\n\n      // Will generate an unhandled rejection.\n      throw error;\n    },\n    attributes = {},\n    parent,\n  }: CreateContextParams = {}) {\n    this._onError = onError;\n    this._attributes = attributes;\n    if (parent !== undefined) {\n      this._parent = parent;\n    }\n  }\n\n  get disposed() {\n    return this._isDisposed;\n  }\n\n  get disposeCallbacksLength() {\n    return this._disposeCallbacks.length;\n  }\n\n  /**\n   * Schedules a callback to run when the context is disposed.\n   * May be async, in this case the disposer might choose to wait for all resource to released.\n   * Throwing an error inside the callback will result in the error being logged, but not re-thrown.\n   *\n   * NOTE: Will call the callback immediately if the context is already disposed.\n   *\n   * @returns A function that can be used to remove the callback from the dispose list.\n   */\n  onDispose(callback: DisposeCallback) {\n    if (this._isDisposed) {\n      // Call the callback immediately if the context is already disposed.\n      void (async () => {\n        try {\n          await callback();\n        } catch (error: any) {\n          log.catch(error);\n        }\n      })();\n    }\n\n    this._disposeCallbacks.push(callback);\n    if (this._disposeCallbacks.length > this.maxSafeDisposeCallbacks) {\n      log.warn('Context has a large number of dispose callbacks. This might be a memory leak.', {\n        count: this._disposeCallbacks.length,\n        safeThreshold: this.maxSafeDisposeCallbacks,\n      });\n    }\n\n    return () => {\n      const index = this._disposeCallbacks.indexOf(callback);\n      if (index !== -1) {\n        this._disposeCallbacks.splice(index, 1);\n      }\n    };\n  }\n\n  /**\n   * Runs all dispose callbacks.\n   * Sync callbacks are run in the reverse order they were added.\n   * Async callbacks are run in parallel.\n   * This function never throws.\n   * It is safe to ignore the returned promise if the caller does not wish to wait for callbacks to complete.\n   * Disposing context means that onDispose will throw an error and any errors raised will be logged and not propagated.\n   */\n  dispose(): Promise<void> {\n    if (this._disposePromise) {\n      return this._disposePromise;\n    }\n    this._isDisposed = true;\n\n    // Set the promise before running the callbacks.\n    let resolveDispose: () => void;\n    this._disposePromise = new Promise<void>((resolve) => {\n      resolveDispose = resolve;\n    });\n\n    const promises = [];\n    // Clone the array so that any mutations to the original array don't affect the dispose process.\n    const callbacks = Array.from(this._disposeCallbacks).reverse();\n    for (const callback of callbacks) {\n      promises.push(\n        (async () => {\n          try {\n            await callback();\n          } catch (error: any) {\n            log.catch(error);\n          }\n        })(),\n      );\n    }\n    this._disposeCallbacks.length = 0;\n\n    void Promise.all(promises).then(() => {\n      resolveDispose();\n    });\n\n    return this._disposePromise;\n  }\n\n  /**\n   * Raise the error inside the context.\n   * The error will be propagated to the error handler.\n   * IF the error handler is not set, the error will dispose the context and cause an unhandled rejection.\n   */\n  raise(error: Error): void {\n    if (this._isDisposed) {\n      // TODO(dmaretskyi): Don't log those.\n      // log.warn('Error in disposed context', error);\n      return;\n    }\n\n    try {\n      this._onError(error);\n    } catch (err) {\n      // Generate an unhandled rejection and stop the error propagation.\n      void Promise.reject(err);\n    }\n  }\n\n  derive({ onError, attributes }: CreateContextParams = {}): Context {\n    const newCtx = new Context({\n      // TODO(dmaretskyi): Optimize to not require allocating a new closure for every context.\n      onError: async (error) => {\n        if (!onError) {\n          this.raise(error);\n        } else {\n          try {\n            await onError(error);\n          } catch {\n            this.raise(error);\n          }\n        }\n      },\n      attributes,\n    });\n    const clearDispose = this.onDispose(() => newCtx.dispose());\n    newCtx.onDispose(clearDispose);\n    return newCtx;\n  }\n\n  getAttribute(key: string): any {\n    if (key in this._attributes) {\n      return this._attributes[key];\n    }\n    if (this._parent !== null) {\n      return this._parent.getAttribute(key);\n    }\n    return undefined;\n  }\n}\n", "//\n// Copyright 2023 DXOS.org\n//\n\nexport class ContextDisposedError extends Error {\n  constructor() {\n    super('Context disposed.');\n  }\n}\n", "//\n// Copyright 2023 DXOS.org\n//\n\nimport { type Context } from './context';\nimport { ContextDisposedError } from './context-disposed';\n\n/**\n * @returns A promise that rejects when the context is disposed.\n */\n// TODO(dmaretskyi): Memory leak.\nexport const rejectOnDispose = (ctx: Context, error = new ContextDisposedError()): Promise<never> =>\n  new Promise((resolve, reject) => {\n    ctx.onDispose(() => reject(error));\n  });\n\n/**\n * Rejects the promise if the context is disposed.\n */\nexport const cancelWithContext = <T>(ctx: Context, promise: Promise<T>): Promise<T> => {\n  let clearDispose: () => void;\n  return Promise.race([\n    promise,\n    new Promise<never>((resolve, reject) => {\n      // Will be called before .finally() handlers.\n      clearDispose = ctx.onDispose(() => reject(new ContextDisposedError()));\n    }),\n  ]).finally(() => clearDispose?.());\n};\n"],
-  "mappings": "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",
-  "names": ["ContextDisposedError", "Error", "constructor", "MAX_SAFE_DISPOSE_CALLBACKS", "Context", "onError", "error", "dispose", "attributes", "parent", "_disposeCallbacks", "_isDisposed", "_disposePromise", "undefined", "_parent", "maxSafeDisposeCallbacks", "_onError", "_attributes", "disposed", "disposeCallbacksLength", "length", "onDispose", "callback", "log", "catch", "push", "warn", "count", "safeThreshold", "index", "indexOf", "splice", "resolveDispose", "Promise", "resolve", "promises", "callbacks", "Array", "from", "reverse", "all", "then", "raise", "err", "reject", "derive", "newCtx", "clearDispose", "getAttribute", "key", "safeInstanceof", "rejectOnDispose", "ctx", "cancelWithContext", "promise", "race", "finally"]
+  "sources": ["../../../src/context.ts", "../../../src/context-disposed-error.ts", "../../../src/promise-utils.ts", "../../../src/resource.ts"],
+  "sourcesContent": ["//\n// Copyright 2022 DXOS.org\n//\n\nimport { inspect } from 'node:util';\n\nimport { log } from '@dxos/log';\nimport { safeInstanceof } from '@dxos/util';\n\nimport { ContextDisposedError } from './context-disposed-error';\n\nexport type ContextErrorHandler = (error: Error) => void;\n\nexport type DisposeCallback = () => any | Promise<any>;\n\nexport type CreateContextParams = {\n  onError?: ContextErrorHandler;\n  attributes?: Record<string, any>;\n  parent?: Context;\n};\n\n/**\n * Maximum number of dispose callbacks before we start logging warnings.\n */\nconst MAX_SAFE_DISPOSE_CALLBACKS = 300;\n\n@safeInstanceof('Context')\nexport class Context {\n  static default() {\n    return new Context();\n  }\n\n  private readonly _onError: ContextErrorHandler;\n  private readonly _disposeCallbacks: DisposeCallback[] = [];\n  private _isDisposed = false;\n  private _disposePromise?: Promise<void> = undefined;\n  private _parent: Context | null = null;\n\n  private _attributes: Record<string, any>;\n\n  public maxSafeDisposeCallbacks = MAX_SAFE_DISPOSE_CALLBACKS;\n\n  constructor({\n    onError = (error) => {\n      if (error instanceof ContextDisposedError) {\n        return;\n      }\n\n      void this.dispose();\n\n      // Will generate an unhandled rejection.\n      throw error;\n    },\n    attributes = {},\n    parent,\n  }: CreateContextParams = {}) {\n    this._onError = onError;\n    this._attributes = attributes;\n    if (parent !== undefined) {\n      this._parent = parent;\n    }\n  }\n\n  get disposed() {\n    return this._isDisposed;\n  }\n\n  get disposeCallbacksLength() {\n    return this._disposeCallbacks.length;\n  }\n\n  /**\n   * Schedules a callback to run when the context is disposed.\n   * May be async, in this case the disposer might choose to wait for all resource to released.\n   * Throwing an error inside the callback will result in the error being logged, but not re-thrown.\n   *\n   * NOTE: Will call the callback immediately if the context is already disposed.\n   *\n   * @returns A function that can be used to remove the callback from the dispose list.\n   */\n  onDispose(callback: DisposeCallback) {\n    if (this._isDisposed) {\n      // Call the callback immediately if the context is already disposed.\n      void (async () => {\n        try {\n          await callback();\n        } catch (error: any) {\n          log.catch(error);\n        }\n      })();\n    }\n\n    this._disposeCallbacks.push(callback);\n    if (this._disposeCallbacks.length > this.maxSafeDisposeCallbacks) {\n      log.warn('Context has a large number of dispose callbacks. This might be a memory leak.', {\n        count: this._disposeCallbacks.length,\n        safeThreshold: this.maxSafeDisposeCallbacks,\n      });\n    }\n\n    return () => {\n      const index = this._disposeCallbacks.indexOf(callback);\n      if (index !== -1) {\n        this._disposeCallbacks.splice(index, 1);\n      }\n    };\n  }\n\n  /**\n   * Runs all dispose callbacks.\n   * Sync callbacks are run in the reverse order they were added.\n   * Async callbacks are run in parallel.\n   * This function never throws.\n   * It is safe to ignore the returned promise if the caller does not wish to wait for callbacks to complete.\n   * Disposing context means that onDispose will throw an error and any errors raised will be logged and not propagated.\n   */\n  dispose(): Promise<void> {\n    if (this._disposePromise) {\n      return this._disposePromise;\n    }\n    this._isDisposed = true;\n\n    // Set the promise before running the callbacks.\n    let resolveDispose: () => void;\n    this._disposePromise = new Promise<void>((resolve) => {\n      resolveDispose = resolve;\n    });\n\n    const promises = [];\n    // Clone the array so that any mutations to the original array don't affect the dispose process.\n    const callbacks = Array.from(this._disposeCallbacks).reverse();\n    for (const callback of callbacks) {\n      promises.push(\n        (async () => {\n          try {\n            await callback();\n          } catch (error: any) {\n            log.catch(error);\n          }\n        })(),\n      );\n    }\n    this._disposeCallbacks.length = 0;\n\n    void Promise.all(promises).then(() => {\n      resolveDispose();\n    });\n\n    return this._disposePromise;\n  }\n\n  /**\n   * Raise the error inside the context.\n   * The error will be propagated to the error handler.\n   * IF the error handler is not set, the error will dispose the context and cause an unhandled rejection.\n   */\n  raise(error: Error): void {\n    if (this._isDisposed) {\n      // TODO(dmaretskyi): Don't log those.\n      // log.warn('Error in disposed context', error);\n      return;\n    }\n\n    try {\n      this._onError(error);\n    } catch (err) {\n      // Generate an unhandled rejection and stop the error propagation.\n      void Promise.reject(err);\n    }\n  }\n\n  derive({ onError, attributes }: CreateContextParams = {}): Context {\n    const newCtx = new Context({\n      // TODO(dmaretskyi): Optimize to not require allocating a new closure for every context.\n      onError: async (error) => {\n        if (!onError) {\n          this.raise(error);\n        } else {\n          try {\n            await onError(error);\n          } catch {\n            this.raise(error);\n          }\n        }\n      },\n      attributes,\n    });\n    const clearDispose = this.onDispose(() => newCtx.dispose());\n    newCtx.onDispose(clearDispose);\n    return newCtx;\n  }\n\n  getAttribute(key: string): any {\n    if (key in this._attributes) {\n      return this._attributes[key];\n    }\n    if (this._parent !== null) {\n      return this._parent.getAttribute(key);\n    }\n    return undefined;\n  }\n\n  [Symbol.toStringTag] = 'Context';\n\n  [inspect.custom] = () => this.toString();\n\n  toString() {\n    return `Context(${this._isDisposed ? 'disposed' : 'active'})`;\n  }\n}\n", "//\n// Copyright 2023 DXOS.org\n//\n\nexport class ContextDisposedError extends Error {\n  constructor() {\n    super('Context disposed.');\n  }\n}\n", "//\n// Copyright 2023 DXOS.org\n//\n\nimport { type Context } from './context';\nimport { ContextDisposedError } from './context-disposed-error';\n\n/**\n * @returns A promise that rejects when the context is disposed.\n */\n// TODO(dmaretskyi): Memory leak.\nexport const rejectOnDispose = (ctx: Context, error = new ContextDisposedError()): Promise<never> =>\n  new Promise((resolve, reject) => {\n    ctx.onDispose(() => reject(error));\n  });\n\n/**\n * Rejects the promise if the context is disposed.\n */\nexport const cancelWithContext = <T>(ctx: Context, promise: Promise<T>): Promise<T> => {\n  let clearDispose: () => void;\n  return Promise.race([\n    promise,\n    new Promise<never>((resolve, reject) => {\n      // Will be called before .finally() handlers.\n      clearDispose = ctx.onDispose(() => reject(new ContextDisposedError()));\n    }),\n  ]).finally(() => clearDispose?.());\n};\n", "//\n// Copyright 2024 DXOS.org\n//\n\nimport '@dxos/util';\nimport { Context } from './context';\n\nexport interface Lifecycle {\n  open?(ctx?: Context): Promise<any> | any;\n  close?(): Promise<any> | any;\n}\n\nexport enum LifecycleState {\n  CLOSED = 'CLOSED',\n  OPEN = 'OPEN',\n  ERROR = 'ERROR',\n}\n\n/**\n * Base class for resources that need to be opened and closed.\n */\nexport class Resource implements Lifecycle {\n  #lifecycleState = LifecycleState.CLOSED;\n  #openPromise: Promise<void> | null = null;\n  #closePromise: Promise<void> | null = null;\n\n  /**\n   * Managed internally by the resource.\n   * Recreated on close.\n   * Errors are propagated to the `_catch` method and the parent context.\n   */\n  #internalCtx: Context = this.#createContext();\n\n  /**\n   * Context that is used to bubble up errors that are not handled by the resource.\n   * Provided in the open method.\n   */\n  #parentCtx: Context = new Context();\n\n  protected get _lifecycleState() {\n    return this.#lifecycleState;\n  }\n\n  protected get _ctx() {\n    return this.#internalCtx;\n  }\n\n  /**\n   * To be overridden by subclasses.\n   */\n  protected async _open(ctx: Context): Promise<void> {}\n\n  /**\n   * To be overridden by subclasses.\n   */\n  protected async _close(ctx: Context): Promise<void> {}\n\n  /**\n   * Error handler for errors that are caught by the context.\n   * By default errors are bubbled up to the parent context which is passed to the open method.\n   */\n  protected async _catch(err: Error): Promise<void> {\n    throw err;\n  }\n\n  /**\n   * Opens the resource.\n   * If the resource is already open, it does nothing.\n   * If the resource is in an error state, it throws an error.\n   * If the resource is closed, it waits for it to close and then opens it.\n   * @param ctx - Context to use for opening the resource. This context will receive errors that are not handled in `_catch`.\n   */\n  async open(ctx?: Context): Promise<this> {\n    switch (this.#lifecycleState) {\n      case LifecycleState.OPEN:\n        return this;\n      case LifecycleState.ERROR:\n        throw new Error(`Invalid state: ${this.#lifecycleState}`);\n      default:\n    }\n    await this.#closePromise;\n    await (this.#openPromise ??= this.#open(ctx));\n\n    return this;\n  }\n\n  /**\n   * Closes the resource.\n   * If the resource is already closed, it does nothing.\n   */\n  async close(ctx?: Context): Promise<this> {\n    if (this.#lifecycleState === LifecycleState.CLOSED) {\n      return this;\n    }\n    await this.#openPromise;\n    await (this.#closePromise ??= this.#close(ctx));\n\n    return this;\n  }\n\n  async [Symbol.asyncDispose]() {\n    await this.close();\n  }\n\n  async #open(ctx?: Context) {\n    this.#closePromise = null;\n    if (ctx) {\n      this.#parentCtx = ctx;\n    }\n    await this._open(this.#parentCtx);\n    this.#lifecycleState = LifecycleState.OPEN;\n  }\n\n  async #close(ctx = new Context()) {\n    this.#openPromise = null;\n    await this.#internalCtx.dispose();\n    await this._close(ctx);\n    this.#internalCtx = this.#createContext();\n    this.#lifecycleState = LifecycleState.CLOSED;\n  }\n\n  #createContext() {\n    return new Context({\n      onError: (error) =>\n        queueMicrotask(async () => {\n          try {\n            await this._catch(error);\n          } catch (err: any) {\n            this.#lifecycleState = LifecycleState.ERROR;\n            this.#parentCtx.raise(err);\n          }\n        }),\n    });\n  }\n}\n\nexport const openInContext = async <T extends Lifecycle>(ctx: Context, resource: T): Promise<T> => {\n  await resource.open?.(ctx);\n  ctx.onDispose(() => resource.close?.());\n\n  return resource;\n};\n"],
+  "mappings": "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",
+  "names": ["import_util", "ContextDisposedError", "Error", "constructor", "MAX_SAFE_DISPOSE_CALLBACKS", "Context", "onError", "error", "dispose", "attributes", "parent", "_disposeCallbacks", "_isDisposed", "_disposePromise", "undefined", "_parent", "maxSafeDisposeCallbacks", "Symbol", "inspect", "toString", "_onError", "_attributes", "toStringTag", "custom", "default", "disposed", "disposeCallbacksLength", "length", "onDispose", "callback", "log", "catch", "push", "warn", "count", "safeThreshold", "index", "indexOf", "splice", "resolveDispose", "Promise", "resolve", "promises", "callbacks", "Array", "from", "reverse", "all", "then", "raise", "err", "reject", "derive", "newCtx", "clearDispose", "getAttribute", "key", "safeInstanceof", "rejectOnDispose", "ctx", "cancelWithContext", "promise", "race", "finally", "LifecycleState", "Resource", "_lifecycleState", "_ctx", "_open", "_close", "_catch", "open", "close", "asyncDispose", "queueMicrotask", "openInContext", "resource"]
 }

package/dist/lib/node/meta.json

@@ -1 +1 @@
-{"inputs":{"packages/common/context/src/context-disposed.ts":{"bytes":803,"imports":[],"format":"esm"},"packages/common/context/src/context.ts":{"bytes":18716,"imports":[{"path":"@dxos/log","kind":"import-statement","external":true},{"path":"@dxos/util","kind":"import-statement","external":true},{"path":"packages/common/context/src/context-disposed.ts","kind":"import-statement","original":"./context-disposed"}],"format":"esm"},"packages/common/context/src/promise-utils.ts":{"bytes":3026,"imports":[{"path":"packages/common/context/src/context-disposed.ts","kind":"import-statement","original":"./context-disposed"}],"format":"esm"},"packages/common/context/src/index.ts":{"bytes":675,"imports":[{"path":"packages/common/context/src/context.ts","kind":"import-statement","original":"./context"},{"path":"packages/common/context/src/promise-utils.ts","kind":"import-statement","original":"./promise-utils"},{"path":"packages/common/context/src/context-disposed.ts","kind":"import-statement","original":"./context-disposed"}],"format":"esm"}},"outputs":{"packages/common/context/dist/lib/node/index.cjs.map":{"imports":[],"exports":[],"inputs":{},"bytes":10416},"packages/common/context/dist/lib/node/index.cjs":{"imports":[{"path":"@dxos/log","kind":"import-statement","external":true},{"path":"@dxos/util","kind":"import-statement","external":true}],"exports":["Context","ContextDisposedError","cancelWithContext","rejectOnDispose"],"entryPoint":"packages/common/context/src/index.ts","inputs":{"packages/common/context/src/context.ts":{"bytesInOutput":5217},"packages/common/context/src/context-disposed.ts":{"bytesInOutput":106},"packages/common/context/src/index.ts":{"bytesInOutput":0},"packages/common/context/src/promise-utils.ts":{"bytesInOutput":410}},"bytes":6040}}}
+{"inputs":{"packages/common/context/src/context-disposed-error.ts":{"bytes":817,"imports":[],"format":"esm"},"packages/common/context/src/context.ts":{"bytes":19782,"imports":[{"path":"node:util","kind":"import-statement","external":true},{"path":"@dxos/log","kind":"import-statement","external":true},{"path":"@dxos/util","kind":"import-statement","external":true},{"path":"packages/common/context/src/context-disposed-error.ts","kind":"import-statement","original":"./context-disposed-error"}],"format":"esm"},"packages/common/context/src/promise-utils.ts":{"bytes":3040,"imports":[{"path":"packages/common/context/src/context-disposed-error.ts","kind":"import-statement","original":"./context-disposed-error"}],"format":"esm"},"packages/common/context/src/resource.ts":{"bytes":11723,"imports":[{"path":"@dxos/util","kind":"import-statement","external":true},{"path":"packages/common/context/src/context.ts","kind":"import-statement","original":"./context"}],"format":"esm"},"packages/common/context/src/index.ts":{"bytes":777,"imports":[{"path":"packages/common/context/src/context.ts","kind":"import-statement","original":"./context"},{"path":"packages/common/context/src/promise-utils.ts","kind":"import-statement","original":"./promise-utils"},{"path":"packages/common/context/src/context-disposed-error.ts","kind":"import-statement","original":"./context-disposed-error"},{"path":"packages/common/context/src/resource.ts","kind":"import-statement","original":"./resource"}],"format":"esm"}},"outputs":{"packages/common/context/dist/lib/node/index.cjs.map":{"imports":[],"exports":[],"inputs":{},"bytes":16404},"packages/common/context/dist/lib/node/index.cjs":{"imports":[{"path":"node:util","kind":"import-statement","external":true},{"path":"@dxos/log","kind":"import-statement","external":true},{"path":"@dxos/util","kind":"import-statement","external":true},{"path":"@dxos/util","kind":"import-statement","external":true}],"exports":["Context","ContextDisposedError","LifecycleState","Resource","cancelWithContext","openInContext","rejectOnDispose"],"entryPoint":"packages/common/context/src/index.ts","inputs":{"packages/common/context/src/context.ts":{"bytesInOutput":5533},"packages/common/context/src/context-disposed-error.ts":{"bytesInOutput":106},"packages/common/context/src/index.ts":{"bytesInOutput":0},"packages/common/context/src/promise-utils.ts":{"bytesInOutput":410},"packages/common/context/src/resource.ts":{"bytesInOutput":2978}},"bytes":9431}}}

package/dist/types/src/{context-disposed.d.ts → context-disposed-error.d.ts}

@@ -1,4 +1,4 @@
 export declare class ContextDisposedError extends Error {
     constructor();
 }
-//# sourceMappingURL=context-disposed.d.ts.map
+//# sourceMappingURL=context-disposed-error.d.ts.map

package/dist/types/src/context-disposed-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-disposed-error.d.ts","sourceRoot":"","sources":["../../../src/context-disposed-error.ts"],"names":[],"mappings":"AAIA,qBAAa,oBAAqB,SAAQ,KAAK;;CAI9C"}

package/dist/types/src/context.d.ts

@@ -1,11 +1,14 @@
+/// <reference types="node" />
+import { inspect } from 'node:util';
 export type ContextErrorHandler = (error: Error) => void;
-export type DisposeCallback = () => void | Promise<void>;
+export type DisposeCallback = () => any | Promise<any>;
 export type CreateContextParams = {
     onError?: ContextErrorHandler;
     attributes?: Record<string, any>;
     parent?: Context;
 };
 export declare class Context {
+    static default(): Context;
     private readonly _onError;
     private readonly _disposeCallbacks;
     private _isDisposed;
@@ -43,5 +46,8 @@ export declare class Context {
     raise(error: Error): void;
     derive({ onError, attributes }?: CreateContextParams): Context;
     getAttribute(key: string): any;
+    [Symbol.toStringTag]: string;
+    [inspect.custom]: () => string;
+    toString(): string;
 }
 //# sourceMappingURL=context.d.ts.map

package/dist/types/src/context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../../src/context.ts"],"names":[],"mappings":"AASA,MAAM,MAAM,mBAAmB,GAAG,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;AAEzD,MAAM,MAAM,eAAe,GAAG,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAEzD,MAAM,MAAM,mBAAmB,GAAG;IAChC,OAAO,CAAC,EAAE,mBAAmB,CAAC;IAC9B,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IACjC,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB,CAAC;AAOF,qBACa,OAAO;IAClB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAsB;IAC/C,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAyB;IAC3D,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,eAAe,CAAC,CAA4B;IACpD,OAAO,CAAC,OAAO,CAAwB;IAEvC,OAAO,CAAC,WAAW,CAAsB;IAElC,uBAAuB,SAA8B;gBAEhD,EACV,OASC,EACD,UAAe,EACf,MAAM,GACP,GAAE,mBAAwB;IAQ3B,IAAI,QAAQ,YAEX;IAED,IAAI,sBAAsB,WAEzB;IAED;;;;;;;;OAQG;IACH,SAAS,CAAC,QAAQ,EAAE,eAAe;IA4BnC;;;;;;;OAOG;IACH,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAmCxB;;;;OAIG;IACH,KAAK,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI;IAezB,MAAM,CAAC,EAAE,OAAO,EAAE,UAAU,EAAE,GAAE,mBAAwB,GAAG,OAAO;IAqBlE,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG;CAS/B"}
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../../src/context.ts"],"names":[],"mappings":";AAIA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAOpC,MAAM,MAAM,mBAAmB,GAAG,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;AAEzD,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;AAEvD,MAAM,MAAM,mBAAmB,GAAG;IAChC,OAAO,CAAC,EAAE,mBAAmB,CAAC;IAC9B,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IACjC,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB,CAAC;AAOF,qBACa,OAAO;IAClB,MAAM,CAAC,OAAO;IAId,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAsB;IAC/C,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAyB;IAC3D,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,eAAe,CAAC,CAA4B;IACpD,OAAO,CAAC,OAAO,CAAwB;IAEvC,OAAO,CAAC,WAAW,CAAsB;IAElC,uBAAuB,SAA8B;gBAEhD,EACV,OASC,EACD,UAAe,EACf,MAAM,GACP,GAAE,mBAAwB;IAQ3B,IAAI,QAAQ,YAEX;IAED,IAAI,sBAAsB,WAEzB;IAED;;;;;;;;OAQG;IACH,SAAS,CAAC,QAAQ,EAAE,eAAe;IA4BnC;;;;;;;OAOG;IACH,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAmCxB;;;;OAIG;IACH,KAAK,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI;IAezB,MAAM,CAAC,EAAE,OAAO,EAAE,UAAU,EAAE,GAAE,mBAAwB,GAAG,OAAO;IAqBlE,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG;IAU9B,CAAC,MAAM,CAAC,WAAW,CAAC,SAAa;IAEjC,CAAC,OAAO,CAAC,MAAM,CAAC,eAAyB;IAEzC,QAAQ;CAGT"}

package/dist/types/src/index.d.ts

@@ -1,4 +1,5 @@
 export * from './context';
 export * from './promise-utils';
-export * from './context-disposed';
+export * from './context-disposed-error';
+export * from './resource';
 //# sourceMappingURL=index.d.ts.map

package/dist/types/src/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/index.ts"],"names":[],"mappings":"AAIA,cAAc,WAAW,CAAC;AAC1B,cAAc,iBAAiB,CAAC;AAChC,cAAc,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/index.ts"],"names":[],"mappings":"AAIA,cAAc,WAAW,CAAC;AAC1B,cAAc,iBAAiB,CAAC;AAChC,cAAc,0BAA0B,CAAC;AACzC,cAAc,YAAY,CAAC"}

package/dist/types/src/promise-utils.d.ts

@@ -1,5 +1,5 @@
 import { type Context } from './context';
-import { ContextDisposedError } from './context-disposed';
+import { ContextDisposedError } from './context-disposed-error';
 /**
  * @returns A promise that rejects when the context is disposed.
  */

package/dist/types/src/promise-utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"promise-utils.d.ts","sourceRoot":"","sources":["../../../src/promise-utils.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,KAAK,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAE1D;;GAEG;AAEH,eAAO,MAAM,eAAe,QAAS,OAAO,mCAAuC,QAAQ,KAAK,CAG5F,CAAC;AAEL;;GAEG;AACH,eAAO,MAAM,iBAAiB,WAAY,OAAO,oCAShD,CAAC"}
+{"version":3,"file":"promise-utils.d.ts","sourceRoot":"","sources":["../../../src/promise-utils.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,KAAK,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAEhE;;GAEG;AAEH,eAAO,MAAM,eAAe,QAAS,OAAO,mCAAuC,QAAQ,KAAK,CAG5F,CAAC;AAEL;;GAEG;AACH,eAAO,MAAM,iBAAiB,WAAY,OAAO,oCAShD,CAAC"}

package/dist/types/src/resource.d.ts

@@ -0,0 +1,48 @@
+import '@dxos/util';
+import { Context } from './context';
+export interface Lifecycle {
+    open?(ctx?: Context): Promise<any> | any;
+    close?(): Promise<any> | any;
+}
+export declare enum LifecycleState {
+    CLOSED = "CLOSED",
+    OPEN = "OPEN",
+    ERROR = "ERROR"
+}
+/**
+ * Base class for resources that need to be opened and closed.
+ */
+export declare class Resource implements Lifecycle {
+    #private;
+    protected get _lifecycleState(): LifecycleState;
+    protected get _ctx(): Context;
+    /**
+     * To be overridden by subclasses.
+     */
+    protected _open(ctx: Context): Promise<void>;
+    /**
+     * To be overridden by subclasses.
+     */
+    protected _close(ctx: Context): Promise<void>;
+    /**
+     * Error handler for errors that are caught by the context.
+     * By default errors are bubbled up to the parent context which is passed to the open method.
+     */
+    protected _catch(err: Error): Promise<void>;
+    /**
+     * Opens the resource.
+     * If the resource is already open, it does nothing.
+     * If the resource is in an error state, it throws an error.
+     * If the resource is closed, it waits for it to close and then opens it.
+     * @param ctx - Context to use for opening the resource. This context will receive errors that are not handled in `_catch`.
+     */
+    open(ctx?: Context): Promise<this>;
+    /**
+     * Closes the resource.
+     * If the resource is already closed, it does nothing.
+     */
+    close(ctx?: Context): Promise<this>;
+    [Symbol.asyncDispose](): Promise<void>;
+}
+export declare const openInContext: <T extends Lifecycle>(ctx: Context, resource: T) => Promise<T>;
+//# sourceMappingURL=resource.d.ts.map

package/dist/types/src/resource.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource.d.ts","sourceRoot":"","sources":["../../../src/resource.ts"],"names":[],"mappings":"AAIA,OAAO,YAAY,CAAC;AACpB,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,MAAM,WAAW,SAAS;IACxB,IAAI,CAAC,CAAC,GAAG,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,GAAG,GAAG,CAAC;IACzC,KAAK,CAAC,IAAI,OAAO,CAAC,GAAG,CAAC,GAAG,GAAG,CAAC;CAC9B;AAED,oBAAY,cAAc;IACxB,MAAM,WAAW;IACjB,IAAI,SAAS;IACb,KAAK,UAAU;CAChB;AAED;;GAEG;AACH,qBAAa,QAAS,YAAW,SAAS;;IAkBxC,SAAS,KAAK,eAAe,mBAE5B;IAED,SAAS,KAAK,IAAI,YAEjB;IAED;;OAEG;cACa,KAAK,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAElD;;OAEG;cACa,MAAM,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAEnD;;;OAGG;cACa,MAAM,CAAC,GAAG,EAAE,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC;IAIjD;;;;;;OAMG;IACG,IAAI,CAAC,GAAG,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAcxC;;;OAGG;IACG,KAAK,CAAC,GAAG,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAUnC,CAAC,MAAM,CAAC,YAAY,CAAC;CAkC5B;AAED,eAAO,MAAM,aAAa,6BAAoC,OAAO,4BAKpE,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dxos/context",
-  "version": "0.4.10-main.fa5a270",
+  "version": "0.4.10-main.fd4f2a3",
   "description": "Async utils.",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
@@ -16,8 +16,9 @@
     "src"
   ],
   "dependencies": {
-    "@dxos/log": "0.4.10-main.fa5a270",
-    "@dxos/util": "0.4.10-main.fa5a270"
+    "@dxos/log": "0.4.10-main.fd4f2a3",
+    "@dxos/util": "0.4.10-main.fd4f2a3",
+    "@dxos/node-std": "0.4.10-main.fd4f2a3"
   },
   "publishConfig": {
     "access": "public"

package/src/context.ts

@@ -2,14 +2,16 @@
 // Copyright 2022 DXOS.org
 //
 
+import { inspect } from 'node:util';
+
 import { log } from '@dxos/log';
 import { safeInstanceof } from '@dxos/util';
 
-import { ContextDisposedError } from './context-disposed';
+import { ContextDisposedError } from './context-disposed-error';
 
 export type ContextErrorHandler = (error: Error) => void;
 
-export type DisposeCallback = () => void | Promise<void>;
+export type DisposeCallback = () => any | Promise<any>;
 
 export type CreateContextParams = {
   onError?: ContextErrorHandler;
@@ -24,6 +26,10 @@ const MAX_SAFE_DISPOSE_CALLBACKS = 300;
 
 @safeInstanceof('Context')
 export class Context {
+  static default() {
+    return new Context();
+  }
+
   private readonly _onError: ContextErrorHandler;
   private readonly _disposeCallbacks: DisposeCallback[] = [];
   private _isDisposed = false;
@@ -193,4 +199,12 @@ export class Context {
     }
     return undefined;
   }
+
+  [Symbol.toStringTag] = 'Context';
+
+  [inspect.custom] = () => this.toString();
+
+  toString() {
+    return `Context(${this._isDisposed ? 'disposed' : 'active'})`;
+  }
 }

package/src/index.ts

@@ -4,4 +4,5 @@
 
 export * from './context';
 export * from './promise-utils';
-export * from './context-disposed';
+export * from './context-disposed-error';
+export * from './resource';

package/src/promise-utils.ts

@@ -3,7 +3,7 @@
 //
 
 import { type Context } from './context';
-import { ContextDisposedError } from './context-disposed';
+import { ContextDisposedError } from './context-disposed-error';
 
 /**
  * @returns A promise that rejects when the context is disposed.

package/src/resource.ts

@@ -0,0 +1,142 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import '@dxos/util';
+import { Context } from './context';
+
+export interface Lifecycle {
+  open?(ctx?: Context): Promise<any> | any;
+  close?(): Promise<any> | any;
+}
+
+export enum LifecycleState {
+  CLOSED = 'CLOSED',
+  OPEN = 'OPEN',
+  ERROR = 'ERROR',
+}
+
+/**
+ * Base class for resources that need to be opened and closed.
+ */
+export class Resource implements Lifecycle {
+  #lifecycleState = LifecycleState.CLOSED;
+  #openPromise: Promise<void> | null = null;
+  #closePromise: Promise<void> | null = null;
+
+  /**
+   * Managed internally by the resource.
+   * Recreated on close.
+   * Errors are propagated to the `_catch` method and the parent context.
+   */
+  #internalCtx: Context = this.#createContext();
+
+  /**
+   * Context that is used to bubble up errors that are not handled by the resource.
+   * Provided in the open method.
+   */
+  #parentCtx: Context = new Context();
+
+  protected get _lifecycleState() {
+    return this.#lifecycleState;
+  }
+
+  protected get _ctx() {
+    return this.#internalCtx;
+  }
+
+  /**
+   * To be overridden by subclasses.
+   */
+  protected async _open(ctx: Context): Promise<void> {}
+
+  /**
+   * To be overridden by subclasses.
+   */
+  protected async _close(ctx: Context): Promise<void> {}
+
+  /**
+   * Error handler for errors that are caught by the context.
+   * By default errors are bubbled up to the parent context which is passed to the open method.
+   */
+  protected async _catch(err: Error): Promise<void> {
+    throw err;
+  }
+
+  /**
+   * Opens the resource.
+   * If the resource is already open, it does nothing.
+   * If the resource is in an error state, it throws an error.
+   * If the resource is closed, it waits for it to close and then opens it.
+   * @param ctx - Context to use for opening the resource. This context will receive errors that are not handled in `_catch`.
+   */
+  async open(ctx?: Context): Promise<this> {
+    switch (this.#lifecycleState) {
+      case LifecycleState.OPEN:
+        return this;
+      case LifecycleState.ERROR:
+        throw new Error(`Invalid state: ${this.#lifecycleState}`);
+      default:
+    }
+    await this.#closePromise;
+    await (this.#openPromise ??= this.#open(ctx));
+
+    return this;
+  }
+
+  /**
+   * Closes the resource.
+   * If the resource is already closed, it does nothing.
+   */
+  async close(ctx?: Context): Promise<this> {
+    if (this.#lifecycleState === LifecycleState.CLOSED) {
+      return this;
+    }
+    await this.#openPromise;
+    await (this.#closePromise ??= this.#close(ctx));
+
+    return this;
+  }
+
+  async [Symbol.asyncDispose]() {
+    await this.close();
+  }
+
+  async #open(ctx?: Context) {
+    this.#closePromise = null;
+    if (ctx) {
+      this.#parentCtx = ctx;
+    }
+    await this._open(this.#parentCtx);
+    this.#lifecycleState = LifecycleState.OPEN;
+  }
+
+  async #close(ctx = new Context()) {
+    this.#openPromise = null;
+    await this.#internalCtx.dispose();
+    await this._close(ctx);
+    this.#internalCtx = this.#createContext();
+    this.#lifecycleState = LifecycleState.CLOSED;
+  }
+
+  #createContext() {
+    return new Context({
+      onError: (error) =>
+        queueMicrotask(async () => {
+          try {
+            await this._catch(error);
+          } catch (err: any) {
+            this.#lifecycleState = LifecycleState.ERROR;
+            this.#parentCtx.raise(err);
+          }
+        }),
+    });
+  }
+}
+
+export const openInContext = async <T extends Lifecycle>(ctx: Context, resource: T): Promise<T> => {
+  await resource.open?.(ctx);
+  ctx.onDispose(() => resource.close?.());
+
+  return resource;
+};

package/dist/types/src/context-disposed.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"context-disposed.d.ts","sourceRoot":"","sources":["../../../src/context-disposed.ts"],"names":[],"mappings":"AAIA,qBAAa,oBAAqB,SAAQ,KAAK;;CAI9C"}