@dxos/effect 0.8.4-main.ead640a → 0.8.4-main.f466a3d56e

package/package.json

@@ -1,10 +1,14 @@
 {
   "name": "@dxos/effect",
-  "version": "0.8.4-main.ead640a",
+  "version": "0.8.4-main.f466a3d56e",
   "description": "Effect utils.",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
-  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dxos/dxos"
+  },
+  "license": "FSL-1.1-Apache-2.0",
   "author": "info@dxos.org",
   "type": "module",
   "exports": {
@@ -13,37 +17,45 @@
       "types": "./dist/types/src/index.d.ts",
       "browser": "./dist/lib/browser/index.mjs",
       "node": "./dist/lib/node-esm/index.mjs"
+    },
+    "./testing": {
+      "source": "./src/testing.ts",
+      "types": "./dist/types/src/testing.d.ts",
+      "browser": "./dist/lib/browser/testing.mjs",
+      "node": "./dist/lib/node-esm/testing.mjs"
     }
   },
   "types": "dist/types/src/index.d.ts",
-  "typesVersions": {
-    "*": {}
-  },
   "files": [
     "dist",
     "src"
   ],
   "dependencies": {
-    "@effect/opentelemetry": "^0.58.0",
-    "@opentelemetry/api": "^1.9.0",
-    "jsonpath-plus": "10.2.0",
-    "@dxos/context": "0.8.4-main.ead640a",
-    "@dxos/invariant": "0.8.4-main.ead640a",
-    "@dxos/node-std": "0.8.4-main.ead640a",
-    "@dxos/util": "0.8.4-main.ead640a"
+    "@effect-atom/atom-react": "^0.5.0",
+    "@effect/opentelemetry": "^0.61.0",
+    "@opentelemetry/api": "^1.9.1",
+    "jsonpath-plus": "^10.3.0",
+    "@dxos/context": "0.8.4-main.f466a3d56e",
+    "@dxos/invariant": "0.8.4-main.f466a3d56e",
+    "@dxos/util": "0.8.4-main.f466a3d56e",
+    "@dxos/node-std": "0.8.4-main.f466a3d56e"
   },
   "devDependencies": {
-    "@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.18.3",
-    "@dxos/log": "0.8.4-main.ead640a"
+    "@effect/platform": "0.94.4",
+    "@effect/platform-browser": "0.74.0",
+    "@opentelemetry/api-logs": "^0.218.0",
+    "@opentelemetry/resources": "^2.7.1",
+    "@opentelemetry/sdk-logs": "^0.218.0",
+    "@opentelemetry/sdk-node": "^0.218.0",
+    "@opentelemetry/sdk-trace-node": "^2.7.1",
+    "@opentelemetry/semantic-conventions": "^1.41.1",
+    "effect": "3.20.0",
+    "@dxos/log": "0.8.4-main.f466a3d56e"
   },
   "peerDependencies": {
-    "effect": "^3.13.3"
+    "@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/RuntimeProvider.ts

@@ -0,0 +1,35 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+import * as Runtime from 'effect/Runtime';
+
+import { runAndForwardErrors, unwrapExit } from './errors';
+
+/**
+ * Provides effect runtime with services to run effects.
+ */
+export type RuntimeProvider<R> = Effect.Effect<Runtime.Runtime<R>>;
+
+/**
+ * @returns Runtime provider from the current context.
+ */
+export const currentRuntime = <R = never>() => Effect.runtime<R>().pipe(Effect.map(Effect.succeed));
+
+/**
+ * Run effect, within runitme, clean errors and fix stack-traces.
+ */
+export const runPromise =
+  <R>(provider: RuntimeProvider<R>) =>
+  async <A>(effect: Effect.Effect<A, any, R>): Promise<A> => {
+    const runtime = await runAndForwardErrors(provider);
+    return unwrapExit(await effect.pipe(Runtime.runPromiseExit(runtime)));
+  };
+
+/**
+ * Provide services from runtime provider to effect.
+ */
+export const provide: {
+  <R2>(runtime: RuntimeProvider<R2>): <A, E, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<A, E, Exclude<R, R2>>;
+} = (runtimeProvider) => (effect) => Effect.flatMap(runtimeProvider, (runtime) => Effect.provide(effect, runtime));

package/src/ast.test.ts

@@ -15,13 +15,13 @@ import {
   getAnnotation,
   getDiscriminatedType,
   getDiscriminatingProps,
-  getSimpleType,
+  getProperties,
   isArrayType,
+  isDiscriminatedUnion,
   isOption,
-  isSimpleType,
   visit,
 } from './ast';
-import { type JsonPath, type JsonProp } from './jsonPath';
+import { type JsonPath, type JsonProp } from './json-path';
 
 const ZipCode = Schema.String.pipe(
   Schema.pattern(/^\d{5}$/, {
@@ -65,10 +65,9 @@ describe('AST', () => {
 
     const prop = findProperty(TestSchema, 'name' as JsonProp);
     invariant(prop);
-    const node = findNode(prop, isSimpleType);
+    const node = findNode(prop, (node) => node._tag === 'StringKeyword');
     invariant(node);
-    const type = getSimpleType(node);
-    expect(type).to.eq('string');
+    expect(node._tag).to.eq('StringKeyword');
   });
 
   test('findProperty', ({ expect }) => {
@@ -92,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',
@@ -137,7 +160,11 @@ describe('AST', () => {
     });
 
     const props: string[] = [];
-    visit(TestSchema.ast, (_, path) => props.push(path.join('.')));
+    visit(
+      TestSchema.ast,
+      (_, path) => props.push(path.join('.')),
+      (node, path, depth) => depth < 3,
+    );
   });
 
   test('discriminated unions', ({ expect }) => {
@@ -152,7 +179,7 @@ describe('AST', () => {
       expect(isOption(TestUnionSchema.ast)).to.be.false;
       expect(getDiscriminatingProps(TestUnionSchema.ast)).to.deep.eq(['kind']);
 
-      const node = findNode(TestUnionSchema.ast, isSimpleType);
+      const node = findNode(TestUnionSchema.ast, isDiscriminatedUnion);
       expect(node).to.eq(TestUnionSchema.ast);
     }
 

package/src/ast.ts

@@ -10,7 +10,7 @@ import * as SchemaAST from 'effect/SchemaAST';
 import { invariant } from '@dxos/invariant';
 import { isNonNullable } from '@dxos/util';
 
-import { type JsonPath, type JsonProp } from './jsonPath';
+import { type JsonPath, type JsonProp } from './json-path';
 
 //
 // Refs
@@ -19,75 +19,66 @@ import { type JsonPath, type JsonProp } from './jsonPath';
 // https://effect-ts.github.io/effect/schema/SchemaAST.ts.html
 //
 
-// TODO(wittjosiah): What is a "simple type"?
-export type SimpleType = 'object' | 'string' | 'number' | 'boolean' | 'enum' | 'literal';
-
-const isTupleType = (node: SchemaAST.AST): boolean => {
-  // NOTE: Arrays are represented as tuples with no elements and a rest part.
-  return SchemaAST.isTupleType(node) && node.elements.length > 0;
-};
-
 /**
- * Get the base type; e.g., traverse through refinements.
+ * Unwraps and collects refinement filters.
  */
-export const getSimpleType = (node: SchemaAST.AST): SimpleType | undefined => {
-  if (
-    SchemaAST.isDeclaration(node) ||
-    SchemaAST.isObjectKeyword(node) ||
-    SchemaAST.isTypeLiteral(node) ||
-    // TODO(wittjosiah): Tuples are actually arrays.
-    isTupleType(node) ||
-    isDiscriminatedUnion(node)
-  ) {
-    return 'object';
+const reduceRefinements = (
+  type: SchemaAST.AST,
+  refinements: SchemaAST.Refinement['filter'][] = [],
+): { type: SchemaAST.AST; refinements: SchemaAST.Refinement['filter'][] } => {
+  if (SchemaAST.isRefinement(type)) {
+    const filter = type.filter;
+    const nextType = {
+      ...type.from,
+      annotations: { ...type.from.annotations, ...type.annotations },
+    } as SchemaAST.AST;
+    return reduceRefinements(nextType, [...refinements, filter]);
   }
 
-  if (SchemaAST.isStringKeyword(node)) {
-    return 'string';
-  }
-  if (SchemaAST.isNumberKeyword(node)) {
-    return 'number';
-  }
-  if (SchemaAST.isBooleanKeyword(node)) {
-    return 'boolean';
-  }
-
-  if (SchemaAST.isEnums(node)) {
-    return 'enum';
-  }
+  return { type, refinements };
+};
 
-  if (SchemaAST.isLiteral(node)) {
-    return 'literal';
-  }
+/**
+ * Get the base type of a property.
+ *
+ * Unwraps refinements and optional unions.
+ */
+export const getBaseType = (
+  prop: SchemaAST.PropertySignature | SchemaProperty,
+): { type: SchemaAST.AST; refinements: SchemaAST.Refinement['filter'][] } => {
+  const encoded = SchemaAST.encodedBoundAST(prop.type);
+  // Extract property ast from optional union.
+  const unwrapped = prop.isOptional && encoded._tag === 'Union' ? encoded.types[0] : encoded;
+  return reduceRefinements(unwrapped);
 };
 
-export const isSimpleType = (node: SchemaAST.AST): boolean => !!getSimpleType(node);
+export type SchemaProperty = Pick<SchemaAST.PropertySignature, 'name' | 'type' | 'isOptional' | 'isReadonly'> & {
+  /** Can be used to validate the property to the spec of the initial AST. */
+  refinements: SchemaAST.Refinement['filter'][];
+};
 
-export namespace SimpleType {
-  /**
-   * Returns the default empty value for a given SimpleType.
-   * Used for initializing new array values etc.
-   */
-  export const getDefaultValue = (type: SimpleType): any => {
-    switch (type) {
-      case 'string': {
-        return '';
-      }
-      case 'number': {
-        return 0;
-      }
-      case 'boolean': {
-        return false;
-      }
-      case 'object': {
-        return {};
-      }
-      default: {
-        throw new Error(`Unsupported type for default value: ${type}`);
-      }
-    }
-  };
-}
+/**
+ * Get the property types of an AST.
+ */
+export const getProperties = (ast: SchemaAST.AST): SchemaProperty[] => {
+  const properties = SchemaAST.getPropertySignatures(ast);
+  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,
+    };
+  });
+};
 
 //
 // Branded types
@@ -111,23 +102,14 @@ export type TestFn = (node: SchemaAST.AST, path: Path, depth: number) => VisitRe
 
 export type VisitorFn = (node: SchemaAST.AST, path: Path, depth: number) => void;
 
-const defaultTest: TestFn = isSimpleType;
-
 /**
  * Visit leaf nodes.
  * Refs:
  * - https://github.com/syntax-tree/unist-util-visit?tab=readme-ov-file#visitor
  * - https://github.com/syntax-tree/unist-util-is?tab=readme-ov-file#test
  */
-export const visit: {
-  (node: SchemaAST.AST, visitor: VisitorFn): void;
-  (node: SchemaAST.AST, test: TestFn, visitor: VisitorFn): void;
-} = (node: SchemaAST.AST, testOrVisitor: TestFn | VisitorFn, visitor?: VisitorFn): void => {
-  if (!visitor) {
-    visitNode(node, defaultTest, testOrVisitor);
-  } else {
-    visitNode(node, testOrVisitor as TestFn, visitor);
-  }
+export const visit = (node: SchemaAST.AST, testOrVisitor: TestFn | VisitorFn, visitor: VisitorFn): void => {
+  visitNode(node, testOrVisitor as TestFn, visitor);
 };
 
 const visitNode = (
@@ -214,6 +196,12 @@ export const findNode = (node: SchemaAST.AST, test: (node: SchemaAST.AST) => boo
         return child;
       }
     }
+    for (const prop of getIndexSignatures(node)) {
+      const child = findNode(prop.type, test);
+      if (child) {
+        return child;
+      }
+    }
   }
 
   // Tuple.
@@ -276,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,
 };
 
 /**
@@ -338,10 +326,45 @@ export const isOption = (node: SchemaAST.AST): boolean => {
 /**
  * Determines if the node is a union of literal types.
  */
-export const isLiteralUnion = (node: SchemaAST.AST): boolean => {
+export const isLiteralUnion = (node: SchemaAST.AST): node is SchemaAST.Union<SchemaAST.Literal> => {
   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.
+ */
+export const isArrayType = (node: SchemaAST.AST): node is SchemaAST.TupleType => {
+  return SchemaAST.isTupleType(node) && node.elements.length === 0 && node.rest.length === 1;
+};
+
+/**
+ * Get the type of the array elements.
+ */
+export const getArrayElementType = (node: SchemaAST.AST): SchemaAST.AST | undefined => {
+  return isArrayType(node) ? node.rest.at(0)?.type : undefined;
+};
+
+/**
+ * Determines if the node is a tuple type.
+ */
+export const isTupleType = (node: SchemaAST.AST): boolean => {
+  return SchemaAST.isTupleType(node) && node.elements.length > 0;
+};
+
 /**
  * Determines if the node is a discriminated union.
  */
@@ -421,6 +444,20 @@ export const getDiscriminatedType = (
   return schema.ast;
 };
 
+/**
+ * Determines if the node is a nested object type.
+ */
+export const isNestedType = (node: SchemaAST.AST): boolean => {
+  return (
+    SchemaAST.isDeclaration(node) ||
+    SchemaAST.isObjectKeyword(node) ||
+    SchemaAST.isTypeLiteral(node) ||
+    // TODO(wittjosiah): Tuples are actually arrays.
+    isTupleType(node) ||
+    isDiscriminatedUnion(node)
+  );
+};
+
 /**
  * Maps AST nodes.
  * The user is responsible for recursively calling {@link mapAst} on the SchemaAST.
@@ -469,15 +506,18 @@ export const mapAst = (
   }
 };
 
-/**
- * @returns true if AST is for Array(T) or optional(Array(T)).
- */
-export const isArrayType = (node: SchemaAST.AST): boolean => {
-  return (
-    SchemaAST.isTupleType(node) ||
-    (SchemaAST.isUnion(node) &&
-      node.types.some(isArrayType) &&
-      node.types.some(SchemaAST.isUndefinedKeyword) &&
-      node.types.length === 2)
-  );
+const getIndexSignatures = (ast: SchemaAST.AST): Array<SchemaAST.IndexSignature> => {
+  const annotation = SchemaAST.getSurrogateAnnotation(ast);
+  if (Option.isSome(annotation)) {
+    return getIndexSignatures(annotation.value);
+  }
+  switch (ast._tag) {
+    case 'TypeLiteral':
+      return ast.indexSignatures.slice();
+    case 'Suspend':
+      return getIndexSignatures(ast.f());
+    case 'Refinement':
+      return getIndexSignatures(ast.from);
+  }
+  return [];
 };

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

@@ -0,0 +1,35 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+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.
+const defaultRuntime = Atom.runtime(BrowserKeyValueStore.layerLocalStorage);
+
+/**
+ * Creates a KVS-backed atom for structured settings using Atom.kvs.
+ * The entire object is stored as a single localStorage key with JSON serialization.
+ *
+ * @param options.key - The localStorage key to store the value under.
+ * @param options.schema - Effect Schema for the value type.
+ * @param options.defaultValue - Function returning the default value.
+ * @param options.runtime - Optional custom Atom runtime (defaults to localStorage).
+ * @returns A writable atom that persists to localStorage.
+ */
+export const createKvsStore = <T extends Record<string, any>>(options: {
+  key: string;
+  schema: Schema.Schema<T>;
+  defaultValue: () => T;
+  runtime?: ReturnType<typeof Atom.runtime>;
+}): Atom.Writable<T> => {
+  const runtime = options.runtime ?? defaultRuntime;
+  return Atom.kvs({
+    runtime,
+    key: options.key,
+    schema: options.schema,
+    defaultValue: options.defaultValue,
+  }).pipe(Atom.keepAlive);
+};