@dxos/effect 0.8.4-main.3a94e84 → 0.8.4-main.3c1ae3b

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dxos/effect",
-  "version": "0.8.4-main.3a94e84",
+  "version": "0.8.4-main.3c1ae3b",
   "description": "Effect utils.",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
@@ -9,29 +9,48 @@
   "type": "module",
   "exports": {
     ".": {
+      "source": "./src/index.ts",
       "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": {
-    "*": {}
+    "*": {
+      "testing": [
+        "./dist/types/src/testing.d.ts"
+      ]
+    }
   },
   "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.3a94e84",
-    "@dxos/invariant": "0.8.4-main.3a94e84",
-    "@dxos/node-std": "0.8.4-main.3a94e84",
-    "@dxos/util": "0.8.4-main.3a94e84"
+    "@dxos/context": "0.8.4-main.3c1ae3b",
+    "@dxos/invariant": "0.8.4-main.3c1ae3b",
+    "@dxos/node-std": "0.8.4-main.3c1ae3b",
+    "@dxos/util": "0.8.4-main.3c1ae3b"
   },
   "devDependencies": {
-    "effect": "3.17.0",
-    "@dxos/log": "0.8.4-main.3a94e84"
+    "@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.3c1ae3b"
   },
   "peerDependencies": {
     "effect": "^3.13.3"

package/src/ast.test.ts

@@ -2,7 +2,8 @@
 // Copyright 2024 DXOS.org
 //
 
-import { SchemaAST, Schema } from 'effect';
+import * as Schema from 'effect/Schema';
+import * as SchemaAST from 'effect/SchemaAST';
 import { describe, test } from 'vitest';
 
 import { invariant } from '@dxos/invariant';
@@ -12,15 +13,14 @@ import {
   findNode,
   findProperty,
   getAnnotation,
-  getDiscriminatingProps,
   getDiscriminatedType,
-  getSimpleType,
+  getDiscriminatingProps,
+  isArrayType,
+  isDiscriminatedUnion,
   isOption,
-  isSimpleType,
   visit,
-  isArrayType,
 } 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}$/, {
@@ -64,10 +64,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 }) => {
@@ -136,7 +135,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 }) => {
@@ -151,7 +154,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

@@ -2,13 +2,15 @@
 // Copyright 2024 DXOS.org
 //
 
-import { Option, pipe, SchemaAST, Schema } 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,53 @@ 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';
-  }
-
-  if (SchemaAST.isStringKeyword(node)) {
-    return 'string';
-  }
-  if (SchemaAST.isNumberKeyword(node)) {
-    return 'number';
-  }
-  if (SchemaAST.isBooleanKeyword(node)) {
-    return 'boolean';
+const reduceRefinements = (
+  type: SchemaAST.AST,
+  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;
+    return reduceRefinements(nextType, [...refinements, filter]);
   }
 
-  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,
+): { 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'> & {
+  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) => ({
+    ...getBaseType(prop),
+    name: prop.name,
+    isOptional: prop.isOptional,
+    isReadonly: prop.isReadonly,
+  }));
+};
 
 //
 // Branded types
@@ -101,23 +89,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 +106,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 +183,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 +203,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;
       }
     }
   }
@@ -279,8 +266,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 +313,31 @@ 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);
 };
 
+/**
+ * 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 +417,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.
@@ -432,6 +454,7 @@ export const mapAst = (
             ),
         ),
         ast.indexSignatures,
+        ast.annotations,
       );
     }
     case 'Union': {
@@ -456,15 +479,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/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/errors.test.ts

@@ -2,7 +2,7 @@
 // Copyright 2025 DXOS.org
 //
 
-import { Data } from 'effect';
+import * as Data from 'effect/Data';
 import { test } from 'vitest';
 
 class MyError extends Data.TaggedError('MyError')<{

package/src/errors.ts

@@ -2,8 +2,13 @@
 // Copyright 2025 DXOS.org
 //
 
-import { Cause, Chunk, Effect, Exit, GlobalValue, Option } from 'effect';
-import type { AnySpan, Span } from 'effect/Tracer';
+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 type * as Tracer from 'effect/Tracer';
 
 const spanSymbol = Symbol.for('effect/SpanAnnotation');
 const originalSymbol = Symbol.for('effect/OriginalAnnotation');
@@ -48,7 +53,7 @@ const prettyErrorStack = (error: any, appendStacks: string[] = []): any => {
   }
 
   if (span) {
-    let current: Span | AnySpan | undefined = span;
+    let current: Tracer.Span | Tracer.AnySpan | undefined = span;
     let i = 0;
     while (current && current._tag === 'Span' && i < 10) {
       const stackFn = spanToTrace.get(current);
@@ -95,7 +100,7 @@ const prettyErrorStack = (error: any, appendStacks: string[] = []): any => {
 };
 
 /**
- * Runs the embedded effect asynchronously and throws any failures and defects as errors.
+ * 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.
@@ -104,21 +109,13 @@ const prettyErrorStack = (error: any, appendStacks: string[] = []): any => {
  *
  * @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);
-  if (Exit.isSuccess(exit)) {
-    return exit.value;
-  }
-
-  if (Cause.isEmpty(exit.cause)) {
-    throw new Error('Fiber failed without a cause');
-  } else if (Cause.isInterrupted(exit.cause)) {
-    throw new Error('Fiber was interrupted');
+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(exit.cause)), ...Chunk.toArray(Cause.defects(exit.cause))];
+    const errors = [...Chunk.toArray(Cause.failures(cause)), ...Chunk.toArray(Cause.defects(cause))];
 
     const getStackFrames = (): string[] => {
       const o: { stack: string } = {} as any;
@@ -130,9 +127,65 @@ export const runAndForwardErrors = async <A, E>(
     const newErrors = errors.map((error) => prettyErrorStack(error, stackFrames));
 
     if (newErrors.length === 1) {
-      throw newErrors[0];
+      return newErrors[0];
     } else {
-      throw new AggregateError(newErrors);
+      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);
+};
+
+/**
+ * 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);

package/src/index.ts

@@ -3,9 +3,8 @@
 //
 
 export * from './ast';
-export * from './jsonPath';
-export * from './url';
 export * from './context';
 export * from './errors';
-export * from './testing';
+export * from './json-path';
 export * from './resource';
+export * from './url';

package/src/interrupt.test.ts

@@ -0,0 +1,33 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { it } from '@effect/vitest';
+import * as Cause from 'effect/Cause';
+import * as Effect from 'effect/Effect';
+import * as Fiber from 'effect/Fiber';
+
+const doWork = Effect.fn('doWork')(function* () {
+  yield* Effect.sleep('1 minute');
+  return 'work done';
+});
+
+it.effect.skip(
+  'call a function to generate a research report',
+  Effect.fnUntraced(
+    function* (_) {
+      const resultFiber = yield* doWork().pipe(Effect.fork);
+      setTimeout(() => {
+        void Effect.runPromise(Fiber.interrupt(resultFiber));
+      }, 2_000);
+
+      const result = yield* resultFiber;
+      console.log({ result });
+    },
+    Effect.catchAllCause((cause) => {
+      // console.log(inspect(cause, { depth: null, colors: true }));
+      console.log(Cause.pretty(cause));
+      return Effect.failCause(cause);
+    }),
+  ),
+);