@dxos/context 0.8.4-main.dedc0f3 → 0.8.4-main.e00bdcdb52

package/package.json

@@ -1,12 +1,16 @@
 {
   "name": "@dxos/context",
-  "version": "0.8.4-main.dedc0f3",
+  "version": "0.8.4-main.e00bdcdb52",
   "description": "Async utils.",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dxos/dxos"
+  },
   "license": "MIT",
   "author": "DXOS.org",
-  "sideEffects": true,
+  "sideEffects": false,
   "type": "module",
   "exports": {
     ".": {
@@ -19,18 +23,16 @@
     }
   },
   "types": "dist/types/src/index.d.ts",
-  "typesVersions": {
-    "*": {}
-  },
   "files": [
     "dist",
     "src"
   ],
   "dependencies": {
-    "@dxos/debug": "0.8.4-main.dedc0f3",
-    "@dxos/log": "0.8.4-main.dedc0f3",
-    "@dxos/util": "0.8.4-main.dedc0f3",
-    "@dxos/node-std": "0.8.4-main.dedc0f3"
+    "@hazae41/symbol-dispose-polyfill": "^1.0.2",
+    "@dxos/debug": "0.8.4-main.e00bdcdb52",
+    "@dxos/log": "0.8.4-main.e00bdcdb52",
+    "@dxos/util": "0.8.4-main.e00bdcdb52",
+    "@dxos/node-std": "0.8.4-main.e00bdcdb52"
   },
   "publishConfig": {
     "access": "public"

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 } });
+  }
+}