@dxos/effect 0.8.4-main.fd6878d → 0.8.4-staging.60fe92afc8

package/src/{ast.ts → internal/ast.ts}

@@ -2,13 +2,15 @@
 // Copyright 2024 DXOS.org
 //
 
-import { Option, Schema, SchemaAST, pipe } from 'effect';
-import { isUndefinedKeyword } from 'effect/SchemaAST';
+import * as Function from 'effect/Function';
+import * as Option from 'effect/Option';
+import * as Schema from 'effect/Schema';
+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
@@ -17,67 +19,66 @@ import { type JsonPath, type JsonProp } from './jsonPath';
 // https://effect-ts.github.io/effect/schema/SchemaAST.ts.html
 //
 
-export type SimpleType = 'object' | 'string' | 'number' | 'boolean' | 'enum' | 'literal';
-
 /**
- * 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) ||
-    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
@@ -101,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 = (
@@ -127,15 +119,15 @@ const visitNode = (
   path: Path = [],
   depth = 0,
 ): VisitResult | undefined => {
-  const _result = test?.(node, path, depth);
+  const $result = test?.(node, path, depth);
   const result: VisitResult =
-    _result === undefined
+    $result === undefined
       ? VisitResult.CONTINUE
-      : typeof _result === 'boolean'
-        ? _result
+      : typeof $result === 'boolean'
+        ? $result
           ? VisitResult.CONTINUE
           : VisitResult.SKIP
-        : _result;
+        : $result;
 
   if (result === VisitResult.EXIT) {
     return result;
@@ -204,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.
@@ -218,12 +216,14 @@ export const findNode = (node: SchemaAST.AST, test: (node: SchemaAST.AST) => boo
 
   // Branching union (e.g., optional, discriminated unions).
   else if (SchemaAST.isUnion(node)) {
-    if (isOption(node)) {
-      for (const type of node.types) {
-        const child = findNode(type, test);
-        if (child) {
-          return child;
-        }
+    if (isLiteralUnion(node)) {
+      return undefined;
+    }
+
+    for (const type of node.types) {
+      const child = findNode(type, test);
+      if (child) {
+        return child;
       }
     }
   }
@@ -264,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,
 };
 
 /**
@@ -279,8 +279,8 @@ export const getAnnotation =
   <T>(annotationId: symbol, noDefault = true) =>
   (node: SchemaAST.AST): T | undefined => {
     // Title fallback seems to be the identifier.
-    const id = pipe(SchemaAST.getIdentifierAnnotation(node), Option.getOrUndefined);
-    const value = pipe(SchemaAST.getAnnotation<T>(annotationId)(node), Option.getOrUndefined);
+    const id = Function.pipe(SchemaAST.getIdentifierAnnotation(node), Option.getOrUndefined);
+    const value = Function.pipe(SchemaAST.getAnnotation<T>(annotationId)(node), Option.getOrUndefined);
     if (noDefault && (value === defaultAnnotations[node._tag]?.annotations[annotationId] || value === id)) {
       return undefined;
     }
@@ -326,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.
  */
@@ -409,6 +444,32 @@ export const getDiscriminatedType = (
   return schema.ast;
 };
 
+/**
+ * If a property signature is optional (T | undefined), returns the inner non-undefined AST node.
+ * Otherwise returns the property signature unchanged, preserving its annotations.
+ */
+export const unwrapOptional = (property: SchemaAST.PropertySignature): SchemaAST.PropertySignature | SchemaAST.AST => {
+  if (!property.isOptional || !SchemaAST.isUnion(property.type) || !isOption(property.type)) {
+    return property;
+  }
+
+  return property.type.types[0];
+};
+
+/**
+ * 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.
@@ -432,6 +493,7 @@ export const mapAst = (
             ),
         ),
         ast.indexSignatures,
+        ast.annotations,
       );
     }
     case 'Union': {
@@ -456,15 +518,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(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/internal/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/{context.ts → internal/context.ts}

@@ -2,7 +2,8 @@
 // Copyright 2025 DXOS.org
 //
 
-import { Effect, type Scope } from 'effect';
+import * as Effect from 'effect/Effect';
+import type * as Scope from 'effect/Scope';
 
 import { Context } from '@dxos/context';
 

package/src/internal/errors.ts

@@ -0,0 +1,255 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Cause from 'effect/Cause';
+import * as Chunk from 'effect/Chunk';
+import * as Effect from 'effect/Effect';
+import * as Exit from 'effect/Exit';
+import * as GlobalValue from 'effect/GlobalValue';
+import * as Option from 'effect/Option';
+import * as Runtime from 'effect/Runtime';
+import type * as Tracer from 'effect/Tracer';
+
+const spanSymbol = Symbol.for('effect/SpanAnnotation');
+const spanToTrace = GlobalValue.globalValue('effect/Tracer/spanToTrace', () => new WeakMap());
+const locationRegex = /\((.*)\)/g;
+
+/**
+ * Adds effect spans.
+ * Removes effect internal functions.
+ * Unwraps error proxy.
+ */
+const prettyErrorStack = (error: any, appendStacks: string[] = []): any => {
+  if (typeof error !== 'object' || error === null) {
+    return error;
+  }
+
+  const span = error[spanSymbol];
+
+  const lines = typeof error.stack === 'string' ? error.stack.split('\n') : [];
+  const out = [];
+
+  // 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]);
+      continue;
+    }
+    atStack = true;
+
+    if (lines[i].includes(' at new BaseEffectError') || lines[i].includes(' at new YieldableError')) {
+      i++;
+      continue;
+    }
+    if (lines[i].includes('Generator.next')) {
+      break;
+    }
+    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')
+        .replace(/EffectPrimitive\.\w+/, '<anonymous>')
+        .replace(/at Arguments\./, 'at '),
+    );
+  }
+
+  if (span) {
+    let current: Tracer.Span | Tracer.AnySpan | undefined = span;
+    let i = 0;
+    while (current && current._tag === 'Span' && i < 10) {
+      const stackFn = spanToTrace.get(current);
+      if (typeof stackFn === 'function') {
+        const stack = stackFn();
+        if (typeof stack === 'string') {
+          const locationMatchAll = stack.matchAll(locationRegex);
+          let match = false;
+          for (const [, location] of locationMatchAll) {
+            match = true;
+            out.push(`    at ${current.name} (${location})`);
+          }
+          if (!match) {
+            out.push(`    at ${current.name} (${stack.replace(/^at /, '')})`);
+          }
+        } else {
+          out.push(`    at ${current.name}`);
+        }
+      } else {
+        out.push(`    at ${current.name}`);
+      }
+      current = Option.getOrUndefined(current.parent);
+      i++;
+    }
+  }
+
+  out.push(...appendStacks);
+
+  error = Cause.originalError(error);
+  if (error.cause) {
+    error.cause = prettyErrorStack(error.cause);
+  }
+
+  Object.defineProperty(error, 'stack', {
+    value: out.join('\n'),
+    writable: true,
+    enumerable: false,
+    configurable: true,
+  });
+
+  return error;
+};
+
+/**
+ * Converts a cause to an error.
+ * Inserts effect spans as stack frames.
+ * The error will have stack frames of where the effect was run (if stack trace limit allows).
+ * Removes effect runtime internal stack frames.
+ *
+ * To be used in place of `Effect.runPromise`.
+ *
+ * @throws AggregateError if there are multiple errors.
+ */
+export const causeToError = (cause: Cause.Cause<any>): Error => {
+  if (Cause.isEmpty(cause)) {
+    return new Error('Fiber failed without a cause');
+  } else if (Cause.isInterruptedOnly(cause)) {
+    return new Error('Fiber was interrupted');
+  } else {
+    const errors = [...Chunk.toArray(Cause.failures(cause)), ...Chunk.toArray(Cause.defects(cause))];
+
+    const getStackFrames = (): string[] => {
+      // Bun requies the target object for `captureStackTrace` to be an Error.
+      const err = new Error();
+      Error.captureStackTrace(err, causeToError);
+      return err.stack!.split('\n').slice(1);
+    };
+
+    const stackFrames = getStackFrames();
+    const newErrors = errors.map((error) => prettyErrorStack(error, stackFrames));
+
+    if (newErrors.length === 1) {
+      return newErrors[0];
+    } else {
+      return new AggregateError(newErrors);
+    }
+  }
+};
+
+/**
+ * Throws an error based on the cause.
+ * Inserts effect spans as stack frames.
+ * The error will have stack frames of where the effect was run (if stack trace limit allows).
+ * Removes effect runtime internal stack frames.
+ *
+ * To be used in place of `Effect.runPromise`.
+ *
+ * @throws AggregateError if there are multiple errors.
+ */
+export const throwCause = (cause: Cause.Cause<any>): never => {
+  throw causeToError(cause);
+};
+
+export const unwrapExit = <A>(exit: Exit.Exit<A, any>): A => {
+  if (Exit.isSuccess(exit)) {
+    return exit.value;
+  }
+
+  return throwCause(exit.cause);
+};
+
+/**
+ * Runs the embedded effect asynchronously and throws any failures and defects as errors.
+ * Inserts effect spans as stack frames.
+ * The error will have stack frames of where the effect was run (if stack trace limit allows).
+ * Removes effect runtime internal stack frames.
+ *
+ * To be used in place of `Effect.runPromise`.
+ *
+ * @throws AggregateError if there are multiple errors.
+ */
+export const runAndForwardErrors = async <A, E>(
+  effect: Effect.Effect<A, E, never>,
+  options?: { signal?: AbortSignal },
+): Promise<A> => {
+  const exit = await Effect.runPromiseExit(effect, options);
+  return unwrapExit(exit);
+};
+
+/** Alias for {@link runAndForwardErrors} — preferred name when accessed via `EffectEx.runPromise`. */
+export const runPromise = runAndForwardErrors;
+
+/**
+ * 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);
+    })();
+  }
+};
+
+/**
+ * Like `Effect.promise` but also caputes spans for defects.
+ * Workaround for: https://github.com/Effect-TS/effect/issues/5436
+ */
+export const promiseWithCauseCapture: <A>(evaluate: (signal: AbortSignal) => PromiseLike<A>) => Effect.Effect<A> = (
+  evaluate,
+) =>
+  Effect.promise(async (signal) => {
+    try {
+      const result = await evaluate(signal);
+      return Effect.succeed(result);
+    } catch (err) {
+      return Effect.die(err);
+    }
+  }).pipe(Effect.flatten);