@dxos/context 0.8.3 → 0.8.4-main.16b68245aa

package/src/context.ts

@@ -14,7 +14,7 @@ export type ContextErrorHandler = (error: Error, ctx: Context) => void;
 
 export type DisposeCallback = () => any | Promise<any>;
 
-export type CreateContextParams = {
+export type CreateContextProps = {
   name?: string;
   parent?: Context;
   attributes?: Record<string, any>;
@@ -67,9 +67,11 @@ export class Context {
   #flags: ContextFlags = 0;
   #disposePromise?: Promise<boolean> = undefined;
 
+  #signal: AbortSignal | undefined = undefined;
+
   public maxSafeDisposeCallbacks = MAX_SAFE_DISPOSE_CALLBACKS;
 
-  constructor(params: CreateContextParams = {}, callMeta?: Partial<CallMetadata>) {
+  constructor(params: CreateContextProps = {}, callMeta?: Partial<CallMetadata>) {
     this.#name = getContextName(params, callMeta);
     this.#parent = params.parent;
     this.#attributes = params.attributes ?? {};
@@ -100,6 +102,16 @@ export class Context {
     return this.#disposeCallbacks.length;
   }
 
+  get signal(): AbortSignal {
+    if (this.#signal) {
+      return this.#signal;
+    }
+    const controller = new AbortController();
+    this.#signal = controller.signal;
+    this.onDispose(() => controller.abort());
+    return this.#signal;
+  }
+
   /**
    * Schedules a callback to run when the context is disposed.
    * May be async, in this case the disposer might choose to wait for all resource to released.
@@ -222,8 +234,9 @@ export class Context {
     }
   }
 
-  derive({ onError, attributes }: CreateContextParams = {}): Context {
+  derive({ onError, attributes }: CreateContextProps = {}): Context {
     const newCtx = new Context({
+      parent: this,
       // TODO(dmaretskyi): Optimize to not require allocating a new closure for every context.
       onError: async (error) => {
         if (!onError) {
@@ -267,7 +280,7 @@ export class Context {
   }
 }
 
-const getContextName = (params: CreateContextParams, callMeta?: Partial<CallMetadata>): string | undefined => {
+const getContextName = (params: CreateContextProps, callMeta?: Partial<CallMetadata>): string | undefined => {
   if (params.name) {
     return params.name;
   }

package/src/index.ts

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

package/src/resource.ts

@@ -2,6 +2,8 @@
 // Copyright 2024 DXOS.org
 //
 
+import '@hazae41/symbol-dispose-polyfill';
+
 import { throwUnhandledError } from '@dxos/util';
 
 import { Context } from './context';
@@ -25,6 +27,7 @@ const CLOSE_RESOURCE_ON_UNHANDLED_ERROR = false;
  */
 export abstract class Resource implements Lifecycle {
   #lifecycleState = LifecycleState.CLOSED;
+
   #openPromise: Promise<void> | null = null;
   #closePromise: Promise<void> | null = null;
 
@@ -41,6 +44,17 @@ export abstract class Resource implements Lifecycle {
    */
   #parentCtx: Context = this.#createParentContext();
 
+  /**
+   * ```ts
+   * await using resource = new Resource();
+   * await resource.open();
+   * ```
+   * https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/using
+   */
+  async [Symbol.asyncDispose](): Promise<void> {
+    await this.close();
+  }
+
   get #name() {
     return Object.getPrototypeOf(this).constructor.name;
   }
@@ -60,12 +74,12 @@ export abstract class Resource implements Lifecycle {
   /**
    * To be overridden by subclasses.
    */
-  protected async _open(ctx: Context): Promise<void> {}
+  protected async _open(_ctx: Context): Promise<void> {}
 
   /**
    * To be overridden by subclasses.
    */
-  protected async _close(ctx: Context): Promise<void> {}
+  protected async _close(_ctx: Context): Promise<void> {}
 
   /**
    * Error handler for errors that are caught by the context.
@@ -82,6 +96,20 @@ export abstract class Resource implements Lifecycle {
     throw err;
   }
 
+  /**
+   * Calls the provided function, opening and closing the resource.
+   * NOTE: Consider using `using` instead.
+   * https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/using
+   */
+  async use<T>(fn: (resource: this) => Promise<T>): Promise<T> {
+    try {
+      await this.open();
+      return await fn(this);
+    } finally {
+      await this.close();
+    }
+  }
+
   /**
    * Opens the resource.
    * If the resource is already open, it does nothing.
@@ -100,7 +128,6 @@ export abstract class Resource implements Lifecycle {
 
     await this.#closePromise;
     await (this.#openPromise ??= this.#open(ctx));
-
     return this;
   }
 
@@ -114,7 +141,6 @@ export abstract class Resource implements Lifecycle {
     }
     await this.#openPromise;
     await (this.#closePromise ??= this.#close(ctx));
-
     return this;
   }
 
@@ -135,13 +161,10 @@ export abstract class Resource implements Lifecycle {
     await this.#openPromise;
   }
 
-  async [Symbol.asyncDispose](): Promise<void> {
-    await this.close();
-  }
-
   async #open(ctx?: Context): Promise<void> {
     this.#closePromise = null;
     this.#parentCtx = ctx?.derive({ name: this.#name }) ?? this.#createParentContext();
+    this.#internalCtx = this.#createContext(this.#parentCtx);
     await this._open(this.#parentCtx);
     this.#lifecycleState = LifecycleState.OPEN;
   }
@@ -154,9 +177,10 @@ export abstract class Resource implements Lifecycle {
     this.#lifecycleState = LifecycleState.CLOSED;
   }
 
-  #createContext(): Context {
+  #createContext(attributeParent?: Context): Context {
     return new Context({
       name: this.#name,
+      parent: attributeParent,
       onError: (error) =>
         queueMicrotask(async () => {
           try {

package/src/trace-context.ts

@@ -0,0 +1,72 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { Context } from './context';
+
+/**
+ * Context attribute key for trace context data.
+ * Stores {@link TraceContextData} (W3C traceparent/tracestate strings).
+ */
+export const TRACE_SPAN_ATTRIBUTE = 'dxos.trace-span';
+
+/**
+ * W3C Trace Context wire format for propagating trace identity.
+ * Stored on DXOS {@link Context} attributes and carried across RPC boundaries.
+ *
+ * Because these are plain strings (not live runtime objects), they remain valid
+ * after the originating span ends — enabling long-lived contexts (`this._ctx`)
+ * to serve as parents for later child spans without a retention cache.
+ *
+ * @see https://www.w3.org/TR/trace-context/
+ */
+export type TraceContextData = {
+  /**
+   * W3C `traceparent` header value.
+   * Format: `{version}-{traceId}-{spanId}-{traceFlags}` (e.g., `00-abc...def-012...789-01`).
+   */
+  traceparent: string;
+  /** Optional W3C `tracestate` header value carrying vendor-specific trace data. */
+  tracestate?: string;
+};
+
+/**
+ * Codec for propagating trace identity across RPC boundaries.
+ *
+ * Hardcoded in `RpcPeer` — every outgoing request calls {@link encode} to
+ * extract W3C trace context from the DXOS `Context`, and every incoming
+ * request calls {@link decode} to reconstruct a DXOS `Context` carrying the
+ * caller's trace context.
+ *
+ * This works because `TRACE_SPAN_ATTRIBUTE` stores serializable
+ * {@link TraceContextData} strings, not opaque runtime objects.
+ */
+export class ContextRpcCodec {
+  /**
+   * Read the W3C trace context from a DXOS `Context` for an outgoing RPC.
+   *
+   * @returns `TraceContextData` to attach to the wire message, or `undefined`
+   *          if the context has no active trace.
+   */
+  static encode(ctx: Context): TraceContextData | undefined {
+    const traceCtx = ctx.getAttribute(TRACE_SPAN_ATTRIBUTE);
+    if (traceCtx == null || typeof traceCtx.traceparent !== 'string') {
+      return undefined;
+    }
+    return traceCtx as TraceContextData;
+  }
+
+  /**
+   * Reconstruct a DXOS `Context` from W3C trace context received in an
+   * incoming RPC request.
+   *
+   * @returns A `Context` carrying the trace context, or `Context.default()`
+   *          if the data is missing/invalid.
+   */
+  static decode(traceContext: TraceContextData): Context {
+    if (typeof traceContext.traceparent !== 'string' || traceContext.traceparent.length === 0) {
+      return Context.default();
+    }
+    return new Context({ attributes: { [TRACE_SPAN_ATTRIBUTE]: traceContext } });
+  }
+}

package/dist/lib/node/index.cjs

@@ -1,454 +0,0 @@
-"use strict";
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, { get: all[name], enumerable: true });
-};
-var __copyProps = (to, from, except, desc) => {
-  if (from && typeof from === "object" || typeof from === "function") {
-    for (let key of __getOwnPropNames(from))
-      if (!__hasOwnProp.call(to, key) && key !== except)
-        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
-  }
-  return to;
-};
-var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-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_debug = require("@dxos/debug");
-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.");
-  }
-};
-function _ts_decorate(decorators, target, key, desc) {
-  var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
-  if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
-  else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
-  return c > 3 && r && Object.defineProperty(target, key, r), r;
-}
-var __dxlog_file = "/home/runner/work/dxos/dxos/packages/common/context/src/context.ts";
-var DEBUG_LOG_DISPOSE = false;
-var MAX_SAFE_DISPOSE_CALLBACKS = 300;
-var DEFAULT_ERROR_HANDLER = (error, ctx) => {
-  if (error instanceof ContextDisposedError) {
-    return;
-  }
-  void ctx.dispose();
-  throw error;
-};
-var CONTEXT_FLAG_IS_DISPOSED = 1 << 0;
-var CONTEXT_FLAG_LEAK_DETECTED = 1 << 1;
-var _a, _b;
-var Context = class _Context {
-  constructor(params = {}, callMeta) {
-    this.#disposeCallbacks = [];
-    this.#name = void 0;
-    this.#parent = void 0;
-    this.#flags = 0;
-    this.#disposePromise = void 0;
-    this.maxSafeDisposeCallbacks = MAX_SAFE_DISPOSE_CALLBACKS;
-    this[_b] = "Context";
-    this[_a] = () => this.toString();
-    this.#name = getContextName(params, callMeta);
-    this.#parent = params.parent;
-    this.#attributes = params.attributes ?? {};
-    this.#onError = params.onError ?? DEFAULT_ERROR_HANDLER;
-  }
-  static default() {
-    return new _Context();
-  }
-  #disposeCallbacks;
-  #name;
-  #parent;
-  #attributes;
-  #onError;
-  #flags;
-  #disposePromise;
-  get #isDisposed() {
-    return !!(this.#flags & CONTEXT_FLAG_IS_DISPOSED);
-  }
-  set #isDisposed(value) {
-    this.#flags = value ? this.#flags | CONTEXT_FLAG_IS_DISPOSED : this.#flags & ~CONTEXT_FLAG_IS_DISPOSED;
-  }
-  get #leakDetected() {
-    return !!(this.#flags & CONTEXT_FLAG_LEAK_DETECTED);
-  }
-  set #leakDetected(value) {
-    this.#flags = value ? this.#flags | CONTEXT_FLAG_LEAK_DETECTED : this.#flags & ~CONTEXT_FLAG_LEAK_DETECTED;
-  }
-  get disposed() {
-    return this.#isDisposed;
-  }
-  get disposeCallbacksLength() {
-    return this.#disposeCallbacks.length;
-  }
-  /**
-  * Schedules a callback to run when the context is disposed.
-  * May be async, in this case the disposer might choose to wait for all resource to released.
-  * Throwing an error inside the callback will result in the error being logged, but not re-thrown.
-  *
-  * NOTE: Will call the callback immediately if the context is already disposed.
-  *
-  * @returns A function that can be used to remove the callback from the dispose list.
-  */
-  onDispose(callback) {
-    if (this.#isDisposed) {
-      void (async () => {
-        try {
-          await callback();
-        } catch (error) {
-          import_log.log.catch(error, {
-            context: this.#name
-          }, {
-            F: __dxlog_file,
-            L: 119,
-            S: this,
-            C: (f, a) => f(...a)
-          });
-        }
-      })();
-    }
-    this.#disposeCallbacks.push(callback);
-    if (this.#disposeCallbacks.length > this.maxSafeDisposeCallbacks && !this.#leakDetected) {
-      this.#leakDetected = true;
-      const callSite = new import_debug.StackTrace().getStackArray(1)[0].trim();
-      import_log.log.warn("Context has a large number of dispose callbacks (this might be a memory leak).", {
-        context: this.#name,
-        callSite,
-        count: this.#disposeCallbacks.length
-      }, {
-        F: __dxlog_file,
-        L: 128,
-        S: this,
-        C: (f, a) => f(...a)
-      });
-    }
-    return () => {
-      const index = this.#disposeCallbacks.indexOf(callback);
-      if (index !== -1) {
-        this.#disposeCallbacks.splice(index, 1);
-      }
-    };
-  }
-  /**
-  * Runs all dispose callbacks.
-  * Callbacks are run in the reverse order they were added.
-  * This function never throws.
-  * It is safe to ignore the returned promise if the caller does not wish to wait for callbacks to complete.
-  * Disposing context means that onDispose will throw an error and any errors raised will be logged and not propagated.
-  * @returns true if there were no errors during the dispose process.
-  */
-  async dispose(throwOnError = false) {
-    if (this.#disposePromise) {
-      return this.#disposePromise;
-    }
-    this.#isDisposed = true;
-    let resolveDispose;
-    const promise = new Promise((resolve) => {
-      resolveDispose = resolve;
-    });
-    this.#disposePromise = promise;
-    const callbacks = Array.from(this.#disposeCallbacks).reverse();
-    this.#disposeCallbacks.length = 0;
-    if (DEBUG_LOG_DISPOSE) {
-      (0, import_log.log)("disposing", {
-        context: this.#name,
-        count: callbacks.length
-      }, {
-        F: __dxlog_file,
-        L: 173,
-        S: this,
-        C: (f, a) => f(...a)
-      });
-    }
-    let i = 0;
-    let clean = true;
-    const errors = [];
-    for (const callback of callbacks) {
-      try {
-        await callback();
-        i++;
-      } catch (err) {
-        clean = false;
-        if (throwOnError) {
-          errors.push(err);
-        } else {
-          import_log.log.catch(err, {
-            context: this.#name,
-            callback: i,
-            count: callbacks.length
-          }, {
-            F: __dxlog_file,
-            L: 188,
-            S: this,
-            C: (f, a) => f(...a)
-          });
-        }
-      }
-    }
-    if (errors.length > 0) {
-      throw new AggregateError(errors);
-    }
-    resolveDispose(clean);
-    if (DEBUG_LOG_DISPOSE) {
-      (0, import_log.log)("disposed", {
-        context: this.#name
-      }, {
-        F: __dxlog_file,
-        L: 199,
-        S: this,
-        C: (f, a) => f(...a)
-      });
-    }
-    return clean;
-  }
-  /**
-  * Raise the error inside the context.
-  * The error will be propagated to the error handler.
-  * IF the error handler is not set, the error will dispose the context and cause an unhandled rejection.
-  */
-  raise(error) {
-    if (this.#isDisposed) {
-      return;
-    }
-    try {
-      this.#onError(error, this);
-    } catch (err) {
-      void Promise.reject(err);
-    }
-  }
-  derive({ onError, attributes } = {}) {
-    const newCtx = new _Context({
-      // TODO(dmaretskyi): Optimize to not require allocating a new closure for every context.
-      onError: async (error) => {
-        if (!onError) {
-          this.raise(error);
-        } else {
-          try {
-            await onError(error, this);
-          } catch {
-            this.raise(error);
-          }
-        }
-      },
-      attributes
-    });
-    const clearDispose = this.onDispose(() => newCtx.dispose());
-    newCtx.onDispose(clearDispose);
-    return newCtx;
-  }
-  getAttribute(key) {
-    if (key in this.#attributes) {
-      return this.#attributes[key];
-    }
-    if (this.#parent) {
-      return this.#parent.getAttribute(key);
-    }
-    return void 0;
-  }
-  toString() {
-    return `Context(${this.#isDisposed ? "disposed" : "active"})`;
-  }
-  async [(_b = Symbol.toStringTag, _a = import_node_util.inspect.custom, Symbol.asyncDispose)]() {
-    await this.dispose();
-  }
-};
-Context = _ts_decorate([
-  (0, import_util.safeInstanceof)("Context")
-], Context);
-var getContextName = (params, callMeta) => {
-  if (params.name) {
-    return params.name;
-  }
-  if (callMeta?.F?.length) {
-    const pathSegments = callMeta?.F.split("/");
-    return `${pathSegments[pathSegments.length - 1]}#${callMeta?.L ?? 0}`;
-  }
-  return void 0;
-};
-var rejectOnDispose = (ctx, error = new ContextDisposedError()) => new Promise((resolve, reject) => {
-  ctx.onDispose(() => reject(error));
-});
-var cancelWithContext = (ctx, promise) => {
-  let clearDispose;
-  return Promise.race([
-    promise,
-    new Promise((resolve, reject) => {
-      clearDispose = ctx.onDispose(() => reject(new ContextDisposedError()));
-    })
-  ]).finally(() => clearDispose?.());
-};
-var LifecycleState = /* @__PURE__ */ function(LifecycleState2) {
-  LifecycleState2["CLOSED"] = "CLOSED";
-  LifecycleState2["OPEN"] = "OPEN";
-  LifecycleState2["ERROR"] = "ERROR";
-  return LifecycleState2;
-}({});
-var CLOSE_RESOURCE_ON_UNHANDLED_ERROR = false;
-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 = this.#createParentContext();
-  get #name() {
-    return Object.getPrototypeOf(this).constructor.name;
-  }
-  get isOpen() {
-    return this.#lifecycleState === "OPEN" && this.#closePromise == null;
-  }
-  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) {
-    if (CLOSE_RESOURCE_ON_UNHANDLED_ERROR) {
-      try {
-        await this.close();
-      } catch (doubleErr) {
-        (0, import_util2.throwUnhandledError)(doubleErr);
-      }
-    }
-    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;
-  }
-  /**
-  * Waits until the resource is open.
-  */
-  async waitUntilOpen() {
-    switch (this.#lifecycleState) {
-      case "OPEN":
-        return;
-      case "ERROR":
-        throw new Error(`Invalid state: ${this.#lifecycleState}`);
-    }
-    if (!this.#openPromise) {
-      throw new Error("Resource is not being opened");
-    }
-    await this.#openPromise;
-  }
-  async [Symbol.asyncDispose]() {
-    await this.close();
-  }
-  async #open(ctx) {
-    this.#closePromise = null;
-    this.#parentCtx = ctx?.derive({
-      name: this.#name
-    }) ?? this.#createParentContext();
-    await this._open(this.#parentCtx);
-    this.#lifecycleState = "OPEN";
-  }
-  async #close(ctx = Context.default()) {
-    this.#openPromise = null;
-    await this.#internalCtx.dispose();
-    await this._close(ctx);
-    this.#internalCtx = this.#createContext();
-    this.#lifecycleState = "CLOSED";
-  }
-  #createContext() {
-    return new Context({
-      name: this.#name,
-      onError: (error) => queueMicrotask(async () => {
-        try {
-          await this._catch(error);
-        } catch (err) {
-          this.#lifecycleState = "ERROR";
-          this.#parentCtx.raise(err);
-        }
-      })
-    });
-  }
-  #createParentContext() {
-    return new Context({
-      name: this.#name
-    });
-  }
-};
-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