@dxos/effect 0.8.3 → 0.8.4-main.1da679c

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dxos/effect",
-  "version": "0.8.3",
+  "version": "0.8.4-main.1da679c",
   "description": "Effect utils.",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
@@ -9,6 +9,7 @@
   "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"
@@ -24,13 +25,14 @@
   ],
   "dependencies": {
     "jsonpath-plus": "10.2.0",
-    "@dxos/invariant": "0.8.3",
-    "@dxos/node-std": "0.8.3",
-    "@dxos/util": "0.8.3"
+    "@dxos/context": "0.8.4-main.1da679c",
+    "@dxos/invariant": "0.8.4-main.1da679c",
+    "@dxos/node-std": "0.8.4-main.1da679c",
+    "@dxos/util": "0.8.4-main.1da679c"
   },
   "devDependencies": {
-    "effect": "3.14.21",
-    "@dxos/log": "0.8.3"
+    "effect": "3.17.7",
+    "@dxos/log": "0.8.4-main.1da679c"
   },
   "peerDependencies": {
     "effect": "^3.13.3"

package/src/ast.test.ts

@@ -2,7 +2,7 @@
 // Copyright 2024 DXOS.org
 //
 
-import { SchemaAST, Schema } from 'effect';
+import { Schema, SchemaAST } from 'effect';
 import { describe, test } from 'vitest';
 
 import { invariant } from '@dxos/invariant';
@@ -12,9 +12,10 @@ import {
   findNode,
   findProperty,
   getAnnotation,
-  getDiscriminatingProps,
   getDiscriminatedType,
+  getDiscriminatingProps,
   getSimpleType,
+  isArrayType,
   isOption,
   isSimpleType,
   visit,
@@ -178,4 +179,20 @@ describe('AST', () => {
       );
     }
   });
+
+  test('Schema.pluck', ({ expect }) => {
+    const TestSchema = Schema.Struct({
+      name: Schema.String,
+    });
+
+    expect(TestSchema.pipe(Schema.pluck('name'), Schema.typeSchema).ast).toEqual(SchemaAST.stringKeyword);
+    expect(() => TestSchema.pipe(Schema.pluck('missing' as any), Schema.typeSchema)).to.throw();
+  });
+
+  test('isArray', ({ expect }) => {
+    expect(isArrayType(Schema.String.ast)).to.be.false;
+    expect(isArrayType(Schema.Array(Schema.String).ast)).to.be.true;
+    expect(isArrayType(findProperty(Schema.Struct({ a: Schema.Array(Schema.String) }), 'a' as JsonPath)!)).to.be.true;
+    expect(isArrayType(Schema.Union(Schema.String, Schema.Array(Schema.String)).ast)).to.be.false;
+  });
 });

package/src/ast.ts

@@ -2,7 +2,8 @@
 // Copyright 2024 DXOS.org
 //
 
-import { Option, pipe, SchemaAST, Schema } from 'effect';
+import { Option, Schema, SchemaAST, pipe } from 'effect';
+import { isUndefinedKeyword } from 'effect/SchemaAST';
 
 import { invariant } from '@dxos/invariant';
 import { isNonNullable } from '@dxos/util';
@@ -16,8 +17,14 @@ 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.
  */
@@ -26,6 +33,8 @@ export const getSimpleType = (node: SchemaAST.AST): SimpleType | undefined => {
     SchemaAST.isDeclaration(node) ||
     SchemaAST.isObjectKeyword(node) ||
     SchemaAST.isTypeLiteral(node) ||
+    // TODO(wittjosiah): Tuples are actually arrays.
+    isTupleType(node) ||
     isDiscriminatedUnion(node)
   ) {
     return 'object';
@@ -126,15 +135,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;
@@ -217,12 +226,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;
       }
     }
   }
@@ -454,3 +465,16 @@ 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)
+  );
+};

package/src/context.ts

@@ -0,0 +1,15 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { Effect, type Scope } from 'effect';
+
+import { Context } from '@dxos/context';
+
+// TODO(dmaretskyi): Error handling.
+export const contextFromScope = (): Effect.Effect<Context, never, Scope.Scope> =>
+  Effect.gen(function* () {
+    const ctx = new Context();
+    yield* Effect.addFinalizer(() => Effect.promise(() => ctx.dispose()));
+    return ctx;
+  });

package/src/errors.test.ts

@@ -0,0 +1,22 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { Data } from 'effect';
+import { test } from 'vitest';
+
+class MyError extends Data.TaggedError('MyError')<{
+  message: string;
+}> {
+  constructor() {
+    super({ message: 'My error message' });
+  }
+}
+
+// Experimenting with error formatting:
+// - If the error doesn't have the message set, vitest will print the error as a JS object.
+// - If the error has non-empty message, vitest will pretty-print the error.
+test.skip('Data error formatting', () => {
+  console.log(JSON.stringify(new MyError(), null, 2));
+  throw new MyError();
+});

package/src/errors.ts

@@ -0,0 +1,186 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { Cause, Chunk, Effect, Exit, GlobalValue, Option } from 'effect';
+import type { AnySpan, Span } 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;
+
+/**
+ * Adds effect spans.
+ * Removes effect internal functions.
+ * Unwraps error proxy.
+ */
+const prettyErrorStack = (error: any, appendStacks: string[] = []): any => {
+  const span = error[spanSymbol];
+
+  const lines = typeof error.stack === 'string' ? error.stack.split('\n') : [];
+  const out = [];
+
+  let atStack = 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;
+    }
+    out.push(
+      lines[i]
+        .replace(/at .*effect_instruction_i.*\((.*)\)/, 'at $1')
+        .replace(/EffectPrimitive\.\w+/, '<anonymous>')
+        .replace(/at Arguments\./, 'at '),
+    );
+  }
+
+  if (span) {
+    let current: Span | 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);
+
+  if (error[originalSymbol]) {
+    error = error[originalSymbol];
+  }
+  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[] => {
+      const o: { stack: string } = {} as any;
+      Error.captureStackTrace(o, getStackFrames);
+      return o.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);
+};
+
+/**
+ * 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

@@ -5,3 +5,7 @@
 export * from './ast';
 export * from './jsonPath';
 export * from './url';
+export * from './context';
+export * from './errors';
+export * from './testing';
+export * from './resource';

package/src/interrupt.test.ts

@@ -0,0 +1,34 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { it } from '@effect/vitest';
+import { Cause, Effect, Fiber } from 'effect';
+
+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* ({ expect: _ }) {
+      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);
+    }),
+  ),
+);

package/src/jsonPath.test.ts

@@ -4,7 +4,7 @@
 
 import { describe, expect, test } from 'vitest';
 
-import { createJsonPath, getField, isJsonPath, type JsonPath, splitJsonPath } from './jsonPath';
+import { type JsonPath, createJsonPath, getField, isJsonPath, splitJsonPath } from './jsonPath';
 
 describe('createJsonPath', () => {
   test('supported path subset', () => {

package/src/jsonPath.ts

@@ -2,7 +2,7 @@
 // Copyright 2025 DXOS.org
 //
 
-import { Schema, Option } from 'effect';
+import { Option, Schema } from 'effect';
 import { JSONPath } from 'jsonpath-plus';
 
 import { invariant } from '@dxos/invariant';

package/src/layers.test.ts

@@ -0,0 +1,106 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { it } from '@effect/vitest';
+import { Context, Duration, Effect, Layer, ManagedRuntime } from 'effect';
+import { test } from 'vitest';
+
+class ClientConfig extends Context.Tag('ClientConfig')<ClientConfig, { endpoint: string }>() {}
+
+class Client extends Context.Tag('Client')<Client, { call: () => Effect.Effect<void> }>() {
+  static layer = Layer.effect(
+    Client,
+    Effect.gen(function* () {
+      const config = yield* ClientConfig;
+      return {
+        call: () => {
+          console.log('called', config.endpoint);
+          return Effect.void;
+        },
+      };
+    }),
+  );
+}
+
+const ServerLive = Layer.scoped(
+  ClientConfig,
+  Effect.gen(function* () {
+    console.log('start server');
+
+    yield* Effect.sleep(Duration.millis(100));
+
+    yield* Effect.addFinalizer(
+      Effect.fn(function* () {
+        yield* Effect.sleep(Duration.millis(100));
+        console.log('stop server');
+      }),
+    );
+
+    return {
+      endpoint: 'http://localhost:8080',
+    };
+  }),
+);
+
+it.effect.skip(
+  'test',
+  Effect.fn(
+    function* ({ expect: _ }) {
+      const client = yield* Client;
+      yield* client.call();
+    },
+    Effect.provide(Layer.provide(Client.layer, ServerLive)),
+  ),
+);
+
+class ServerPlugin {
+  #runtime = ManagedRuntime.make(ServerLive);
+
+  readonly clientConfigLayer = Layer.effectContext(
+    this.#runtime.runtimeEffect.pipe(Effect.map((rt) => rt.context.pipe(Context.pick(ClientConfig)))),
+  );
+
+  async dispose() {
+    await this.#runtime.dispose();
+  }
+}
+
+class ClientPlugin {
+  constructor(private readonly _serverPlugin: ServerPlugin) {}
+
+  async run() {
+    const layer = Layer.provide(Client.layer, this._serverPlugin.clientConfigLayer);
+
+    await Effect.runPromise(
+      Effect.gen(function* () {
+        const client = yield* Client;
+        yield* client.call();
+      }).pipe(Effect.provide(layer)),
+    );
+  }
+}
+
+test.skip('plugins', async () => {
+  const serverPlugin = new ServerPlugin();
+  console.log('ServerPlugin created');
+
+  await Effect.runPromise(Effect.sleep(Duration.millis(500)));
+  console.log('wake up');
+
+  {
+    const clientPlugin1 = new ClientPlugin(serverPlugin);
+    console.log('ClientPlugin1 created');
+    await clientPlugin1.run();
+    console.log('client1 run');
+  }
+
+  {
+    const clientPlugin2 = new ClientPlugin(serverPlugin);
+    console.log('ClientPlugin2 created');
+    await clientPlugin2.run();
+    console.log('client2 run');
+  }
+
+  await serverPlugin.dispose();
+});

package/src/resource.test.ts

@@ -0,0 +1,32 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { it } from '@effect/vitest';
+import { Effect } from 'effect';
+
+import { accuireReleaseResource } from './resource';
+
+it.effect(
+  'acquire-release',
+  Effect.fn(function* ({ expect }) {
+    const events: string[] = [];
+    const makeResource = accuireReleaseResource(() => ({
+      open: () => {
+        events.push('open');
+      },
+      close: () => {
+        events.push('close');
+      },
+    }));
+
+    yield* Effect.gen(function* () {
+      events.push('1');
+      const _resource = yield* makeResource;
+      events.push('2');
+    }).pipe(Effect.scoped);
+
+    events.push('3');
+    expect(events).to.deep.equal(['1', 'open', '2', 'close', '3']);
+  }),
+);

package/src/resource.ts

@@ -0,0 +1,25 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { Effect } from 'effect';
+
+import type { Lifecycle } from '@dxos/context';
+
+// TODO(dmaretskyi): Extract to effect-utils.
+export const accuireReleaseResource = <T extends Lifecycle>(getResource: () => T) =>
+  Effect.acquireRelease(
+    Effect.gen(function* () {
+      const resource = getResource();
+      yield* Effect.promise(async () => {
+        resource.open?.();
+        return undefined;
+      });
+      return resource;
+    }),
+    (resource) =>
+      Effect.promise(async () => {
+        resource.close?.();
+        return undefined;
+      }),
+  );