@dxos/effect 0.8.4-main.fbb7a13 → 0.8.4-main.fcc0d83b33

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dxos/effect",
-  "version": "0.8.4-main.fbb7a13",
+  "version": "0.8.4-main.fcc0d83b33",
   "description": "Effect utils.",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
@@ -26,40 +26,36 @@
     }
   },
   "types": "dist/types/src/index.d.ts",
-  "typesVersions": {
-    "*": {
-      "testing": [
-        "./dist/types/src/testing.d.ts"
-      ]
-    }
-  },
   "files": [
     "dist",
     "src"
   ],
   "dependencies": {
-    "@effect-atom/atom-react": "^0.4.6",
-    "@effect/opentelemetry": "^0.59.2",
-    "@effect/platform-browser": "0.73.0",
+    "@effect-atom/atom-react": "^0.5.0",
+    "@effect/opentelemetry": "^0.61.0",
     "@opentelemetry/api": "^1.9.0",
-    "jsonpath-plus": "10.2.0",
-    "@dxos/invariant": "0.8.4-main.fbb7a13",
-    "@dxos/node-std": "0.8.4-main.fbb7a13",
-    "@dxos/util": "0.8.4-main.fbb7a13",
-    "@dxos/context": "0.8.4-main.fbb7a13"
+    "jsonpath-plus": "^10.3.0",
+    "@dxos/invariant": "0.8.4-main.fcc0d83b33",
+    "@dxos/node-std": "0.8.4-main.fcc0d83b33",
+    "@dxos/util": "0.8.4-main.fcc0d83b33",
+    "@dxos/context": "0.8.4-main.fcc0d83b33"
   },
   "devDependencies": {
+    "@effect/platform": "0.94.4",
+    "@effect/platform-browser": "0.74.0",
     "@opentelemetry/api-logs": "^0.203.0",
     "@opentelemetry/resources": "^2.1.0",
     "@opentelemetry/sdk-logs": "^0.203.0",
     "@opentelemetry/sdk-node": "^0.203.0",
     "@opentelemetry/sdk-trace-node": "^2.1.0",
     "@opentelemetry/semantic-conventions": "^1.37.0",
-    "effect": "3.19.11",
-    "@dxos/log": "0.8.4-main.fbb7a13"
+    "effect": "3.20.0",
+    "@dxos/log": "0.8.4-main.fcc0d83b33"
   },
   "peerDependencies": {
-    "effect": "3.19.11"
+    "@effect/platform": "0.94.4",
+    "@effect/platform-browser": "0.74.0",
+    "effect": "3.20.0"
   },
   "publishConfig": {
     "access": "public"

package/src/Performance.ts

@@ -0,0 +1,45 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+import type * as Exit from 'effect/Exit';
+
+export interface AddTrackEntryOptions {
+  name: string;
+  devtools?: {
+    /**
+     * @example 'track-entry'
+     */
+    dataType: string;
+    track: string;
+    trackGroup: string;
+    /**
+     * @example 'tertiary-dark'
+     */
+    color: string;
+    properties?: [string, any][];
+    tooltipText?: string;
+  };
+  detail?: Record<string, unknown>;
+}
+
+/**
+ * Puts the effect span on the performance timeline in DevTools.
+ */
+export const addTrackEntry =
+  <A, E>(options: AddTrackEntryOptions | ((exit: Exit.Exit<A, E>) => AddTrackEntryOptions)) =>
+  <R>(effect: Effect.Effect<A, E, R>): Effect.Effect<A, E, R> =>
+    Effect.gen(function* () {
+      const start = performance.now();
+      const exit = yield* Effect.exit(effect);
+      const resolvedOptions = typeof options === 'function' ? options(exit) : options;
+      performance.measure(resolvedOptions.name, {
+        start: start,
+        detail: {
+          ...resolvedOptions.detail,
+          devtools: resolvedOptions.devtools,
+        },
+      });
+      return yield* exit;
+    });

package/src/ast.test.ts

@@ -15,6 +15,7 @@ import {
   getAnnotation,
   getDiscriminatedType,
   getDiscriminatingProps,
+  getProperties,
   isArrayType,
   isDiscriminatedUnion,
   isOption,
@@ -90,6 +91,30 @@ describe('AST', () => {
     }
   });
 
+  test('getProperties preserves annotation on property type after refinements', ({ expect }) => {
+    // When a property is e.g. Format.Text.pipe(nonEmptyString(), maxLength(), Schema.annotations({ title, description })),
+    // the form uses getProperties(schema.ast) and then Format.FormatAnnotation.getFromAst(property.type).
+    // Custom title and description from the outer Schema.annotations() must not be lost.
+    const WithRefinements = Schema.Struct({
+      message: Schema.String.annotations({ title: 'Feedback' }).pipe(
+        Schema.minLength(1),
+        Schema.maxLength(4096),
+        Schema.annotations({
+          title: 'Feedback label',
+          description: 'Feedback placeholder',
+        }),
+      ),
+    });
+    const properties = getProperties(WithRefinements.ast);
+    const messageProp = properties.find((p) => p.name === 'message');
+    invariant(messageProp);
+    const title = findAnnotation(messageProp.type, SchemaAST.TitleAnnotationId);
+    const description = findAnnotation(messageProp.type, SchemaAST.DescriptionAnnotationId);
+    // Outer Schema.annotations() wins so form labels/placeholders are preserved.
+    expect(title).to.eq('Feedback label');
+    expect(description).to.eq('Feedback placeholder');
+  });
+
   test('findAnnotation', ({ expect }) => {
     const TestSchema = Schema.NonEmptyString.pipe(Schema.pattern(/^\d{5}$/)).annotations({
       title: 'original title',

package/src/ast.ts

@@ -27,9 +27,11 @@ const reduceRefinements = (
   refinements: SchemaAST.Refinement['filter'][] = [],
 ): { type: SchemaAST.AST; refinements: SchemaAST.Refinement['filter'][] } => {
   if (SchemaAST.isRefinement(type)) {
-    const annotations = type.annotations;
     const filter = type.filter;
-    const nextType = { ...type.from, annotations: { ...type.annotations, ...annotations } } as SchemaAST.AST;
+    const nextType = {
+      ...type.from,
+      annotations: { ...type.from.annotations, ...type.annotations },
+    } as SchemaAST.AST;
     return reduceRefinements(nextType, [...refinements, filter]);
   }
 
@@ -60,12 +62,22 @@ export type SchemaProperty = Pick<SchemaAST.PropertySignature, 'name' | 'type' |
  */
 export const getProperties = (ast: SchemaAST.AST): SchemaProperty[] => {
   const properties = SchemaAST.getPropertySignatures(ast);
-  return properties.map((prop) => ({
-    ...getBaseType(prop),
-    name: prop.name,
-    isOptional: prop.isOptional,
-    isReadonly: prop.isReadonly,
-  }));
+  return properties.map((prop) => {
+    const { type, refinements } = getBaseType(prop);
+    // Merge PropertySignature-level annotations (e.g., title, description set via .annotations())
+    // onto the unwrapped base type so downstream consumers see them.
+    const mergedType =
+      prop.annotations && Reflect.ownKeys(prop.annotations).length > 0
+        ? ({ ...type, annotations: { ...type.annotations, ...prop.annotations } } as SchemaAST.AST)
+        : type;
+    return {
+      type: mergedType,
+      refinements,
+      name: prop.name,
+      isOptional: prop.isOptional,
+      isReadonly: prop.isReadonly,
+    };
+  });
 };
 
 //
@@ -252,10 +264,10 @@ export const findProperty = (
 //
 
 const defaultAnnotations: Record<string, SchemaAST.Annotated> = {
-  ['ObjectKeyword' as const]: SchemaAST.objectKeyword,
-  ['StringKeyword' as const]: SchemaAST.stringKeyword,
-  ['NumberKeyword' as const]: SchemaAST.numberKeyword,
-  ['BooleanKeyword' as const]: SchemaAST.booleanKeyword,
+  ObjectKeyword: SchemaAST.objectKeyword,
+  StringKeyword: SchemaAST.stringKeyword,
+  NumberKeyword: SchemaAST.numberKeyword,
+  BooleanKeyword: SchemaAST.booleanKeyword,
 };
 
 /**
@@ -318,6 +330,20 @@ export const isLiteralUnion = (node: SchemaAST.AST): node is SchemaAST.Union<Sch
   return SchemaAST.isUnion(node) && node.types.every(SchemaAST.isLiteral);
 };
 
+/**
+ * Extracts the literal values from a schema that is a union of literals
+ * (e.g. `Schema.Literal('a', 'b')` or `Schema.Union(Schema.Literal('a'), Schema.Literal('b'))`).
+ * Returns an empty array if the schema is not a literal union.
+ */
+export const getLiteralValues = <S extends Schema.Schema<any, any, any>>(
+  schema: S,
+): ReadonlyArray<Schema.Schema.Type<S>> => {
+  if (!isLiteralUnion(schema.ast)) {
+    return [];
+  }
+  return schema.ast.types.map((node) => node.literal as Schema.Schema.Type<S>);
+};
+
 /**
  * Determines if the node is an array type.
  */

package/src/async-task-tagging.ts

@@ -0,0 +1,51 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Context from 'effect/Context';
+import * as Effect from 'effect/Effect';
+import { pipe } from 'effect/Function';
+import * as Layer from 'effect/Layer';
+import * as Predicate from 'effect/Predicate';
+import * as Tracer from 'effect/Tracer';
+
+const runInTask = Symbol('runInTask');
+
+/**
+ * Traces effect frames using console.createTask so that the proper stack-trace is visible in Chrome Devtools debugger.
+ */
+export const asyncTaskTaggingLayer = () => {
+  if (Predicate.hasProperty(console, 'createTask') === false) {
+    return Layer.empty;
+  }
+
+  const makeTracer = Effect.gen(function* () {
+    const oldTracer = yield* Effect.tracer;
+    return Tracer.make({
+      span: (name, ...args) => {
+        const span = oldTracer.span(name, ...args);
+        const trace = (console as any).createTask(name);
+        (span as any)[runInTask] = (f: any) => trace.run(f);
+        return span;
+      },
+      context: (f, fiber) => {
+        const maybeParentSpan = Context.getOption(Tracer.ParentSpan)(fiber.currentContext);
+
+        if (maybeParentSpan._tag === 'None') {
+          return oldTracer.context(f, fiber);
+        }
+        const parentSpan = maybeParentSpan.value;
+        if (parentSpan._tag === 'ExternalSpan') {
+          return oldTracer.context(f, fiber);
+        }
+        const span = parentSpan;
+        if (runInTask in span && typeof span[runInTask] === 'function') {
+          return span[runInTask](() => oldTracer.context(f, fiber));
+        }
+
+        return oldTracer.context(f, fiber);
+      },
+    });
+  });
+  return pipe(makeTracer, Effect.map(Layer.setTracer), Layer.unwrapEffect);
+};

package/src/atom-kvs.ts

@@ -2,8 +2,8 @@
 // Copyright 2025 DXOS.org
 //
 
-import * as BrowserKeyValueStore from '@effect/platform-browser/BrowserKeyValueStore';
 import { Atom } from '@effect-atom/atom-react';
+import * as BrowserKeyValueStore from '@effect/platform-browser/BrowserKeyValueStore';
 import type * as Schema from 'effect/Schema';
 
 // TODO(wittjosiah): This is currently provided for convenience but maybe should be removed.

package/src/errors.ts

@@ -12,7 +12,6 @@ import * as Runtime from 'effect/Runtime';
 import type * as Tracer from 'effect/Tracer';
 
 const spanSymbol = Symbol.for('effect/SpanAnnotation');
-const originalSymbol = Symbol.for('effect/OriginalAnnotation');
 const spanToTrace = GlobalValue.globalValue('effect/Tracer/spanToTrace', () => new WeakMap());
 const locationRegex = /\((.*)\)/g;
 
@@ -31,7 +30,10 @@ const prettyErrorStack = (error: any, appendStacks: string[] = []): any => {
   const lines = typeof error.stack === 'string' ? error.stack.split('\n') : [];
   const out = [];
 
-  let atStack = false;
+  // Very hacky way to remove effect runtime internal stack frames.
+  let atStack = false,
+    inCore = false,
+    passedScheduler = false;
   for (let i = 0; i < lines.length; i++) {
     if (!atStack && !lines[i].startsWith('    at ')) {
       out.push(lines[i]);
@@ -49,6 +51,26 @@ const prettyErrorStack = (error: any, appendStacks: string[] = []): any => {
     if (lines[i].includes('effect_internal_function')) {
       break;
     }
+
+    const filename = lines[i].match(/\/([a-zA-Z0-9_\-.]+):\d+:\d+\)$/)?.[1];
+
+    if (!inCore && ['core-effect.ts'].includes(filename)) {
+      inCore = true;
+    }
+
+    if (inCore && !passedScheduler && ['Scheduler.ts'].includes(filename)) {
+      passedScheduler = true;
+      continue;
+    }
+
+    if (passedScheduler && !['Scheduler.ts'].includes(filename)) {
+      inCore = false;
+    }
+
+    if (inCore) {
+      continue;
+    }
+
     out.push(
       lines[i]
         .replace(/at .*effect_instruction_i.*\((.*)\)/, 'at $1')
@@ -87,9 +109,7 @@ const prettyErrorStack = (error: any, appendStacks: string[] = []): any => {
 
   out.push(...appendStacks);
 
-  if (error[originalSymbol]) {
-    error = error[originalSymbol];
-  }
+  error = Cause.originalError(error);
   if (error.cause) {
     error.cause = prettyErrorStack(error.cause);
   }
@@ -125,7 +145,7 @@ export const causeToError = (cause: Cause.Cause<any>): Error => {
     const getStackFrames = (): string[] => {
       // Bun requies the target object for `captureStackTrace` to be an Error.
       const o = new Error();
-      Error.captureStackTrace(o, getStackFrames);
+      Error.captureStackTrace(o, causeToError);
       return o.stack!.split('\n').slice(1);
     };
 
@@ -180,13 +200,39 @@ export const runAndForwardErrors = async <A, E>(
   return unwrapExit(exit);
 };
 
-export const runInRuntime = async <A, E, R>(
-  runtime: Runtime.Runtime<R>,
-  effect: Effect.Effect<A, E, R>,
-  options?: { signal?: AbortSignal },
-): Promise<A> => {
-  const exit = await Runtime.runPromiseExit(runtime, effect, options);
-  return unwrapExit(exit);
+/**
+ * Runs the embedded effect asynchronously and throws any failures and defects as errors.
+ */
+export const runInRuntime: {
+  <R>(
+    runtime: Runtime.Runtime<R>,
+  ): <A, E>(effect: Effect.Effect<A, E, R>, options?: { signal?: AbortSignal } | undefined) => Promise<A>;
+  <R, A, E>(
+    runtime: Runtime.Runtime<R>,
+    effect: Effect.Effect<A, E, R>,
+    options?: { signal?: AbortSignal } | undefined,
+  ): Promise<A>;
+} = (...args: any[]): any => {
+  if (args.length === 1) {
+    const [runtime] = args as [Runtime.Runtime<any>];
+    return async (
+      effect: Effect.Effect<any, any, any>,
+      options?: { signal?: AbortSignal } | undefined,
+    ): Promise<any> => {
+      const exit = await Runtime.runPromiseExit(runtime, effect, options);
+      return unwrapExit(exit);
+    };
+  } else {
+    const [runtime, effect, options] = args as [
+      Runtime.Runtime<any>,
+      Effect.Effect<any, any, any>,
+      { signal?: AbortSignal } | undefined,
+    ];
+    return (async () => {
+      const exit = await Runtime.runPromiseExit(runtime, effect, options);
+      return unwrapExit(exit);
+    })();
+  }
 };
 
 /**

package/src/index.ts

@@ -9,5 +9,8 @@ export * as DynamicRuntime from './dynamic-runtime';
 export * from './errors';
 export * from './json-path';
 export * from './resource';
+export * from './types';
 export * from './url';
 export * as RuntimeProvider from './RuntimeProvider';
+export * as Performance from './Performance';
+export * from './async-task-tagging';

package/src/testing.ts

@@ -6,17 +6,11 @@ import * as Context from 'effect/Context';
 import * as Effect from 'effect/Effect';
 import type { TestContext } from 'vitest';
 
-// TODO(dmaretskyi): Add all different test tags here.
-export type TestTag =
-  | 'flaky' // Flaky tests.
-  | 'llm' // Tests with AI.
-  | 'sync'; // Sync with external services.
-
 export namespace TestHelpers {
   /**
    * Skip the test if the condition is false.
    *
-   * Exmaple:
+   * Example:
    * ```ts
    * it.effect(
    *   'should process an agentic loop using Claude',
@@ -41,7 +35,7 @@ export namespace TestHelpers {
   /**
    * Skip the test if the condition is true.
    *
-   * Exmaple:
+   * Example:
    * ```ts
    * it.effect(
    *   'should process an agentic loop using Claude',
@@ -63,28 +57,10 @@ export namespace TestHelpers {
         }
       });
 
-  /**
-   * Skips this test if the tag is not in the list of tags to run.
-   * Tags are specified in the `DX_TEST_TAGS` environment variable.
-   *
-   * @param tag
-   * @returns
-   */
-  export const taggedTest =
-    (tag: TestTag) =>
-    <A, E, R>(effect: Effect.Effect<A, E, R>, ctx: TestContext): Effect.Effect<A, E, R> =>
-      Effect.gen(function* () {
-        if (!process.env.DX_TEST_TAGS?.includes(tag)) {
-          ctx.skip();
-        } else {
-          return yield* effect;
-        }
-      });
-
   /**
    * Provide TestContext from test parameters.
    *
-   * Exmaple:
+   * Example:
    * ```ts
    * it.effect(
    *   'with context',

package/src/types.ts

@@ -0,0 +1,11 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+/**
+ * Flat intersection of up to five types. Behaves like `A & B & C & ...` but
+ * formats as a comma-separated tuple, which fits multi-line layouts more
+ * cleanly than chained `&` operators. Unused slots default to `unknown`,
+ * which is inert under intersection (`T & unknown = T`).
+ */
+export type Merge<A, B = unknown, C = unknown, D = unknown, E = unknown> = A & B & C & D & E;