@dxos/effect 0.8.3 → 0.8.4-main.1068cf700f

package/src/errors.ts

@@ -0,0 +1,252 @@
+//
+// 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 o = new Error();
+      Error.captureStackTrace(o, causeToError);
+      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);
+};
+
+/**
+ * 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);

package/src/index.ts

@@ -3,5 +3,11 @@
 //
 
 export * from './ast';
-export * from './jsonPath';
+export * from './atom-kvs';
+export * from './context';
+export * as DynamicRuntime from './dynamic-runtime';
+export * from './errors';
+export * from './json-path';
+export * from './resource';
 export * from './url';
+export * as RuntimeProvider from './RuntimeProvider';

package/src/interrupt.test.ts

@@ -0,0 +1,35 @@
+//
+// 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';
+
+import { runAndForwardErrors } from './errors';
+
+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 runAndForwardErrors(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 → json-path.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, getValue, isJsonPath, setValue, splitJsonPath } from './json-path';
 
 describe('createJsonPath', () => {
   test('supported path subset', () => {
@@ -32,9 +32,9 @@ describe('createJsonPath', () => {
 
   test('path splitting', () => {
     const cases = [
-      ['foo.bar[0].baz', ['foo', 'bar', '0', 'baz']],
-      ['users[1].name', ['users', '1', 'name']],
-      ['data[0][1]', ['data', '0', '1']],
+      ['foo.bar[0].baz', ['foo', 'bar', 0, 'baz']],
+      ['users[1].name', ['users', 1, 'name']],
+      ['data[0][1]', ['data', 0, 1]],
       ['simple.path', ['simple', 'path']],
       ['root', ['root']],
     ] as const;
@@ -47,15 +47,15 @@ describe('createJsonPath', () => {
   test('path splitting - extended cases', () => {
     const cases = [
       // Multiple consecutive array indices.
-      ['matrix[0][1][2]', ['matrix', '0', '1', '2']],
+      ['matrix[0][1][2]', ['matrix', 0, 1, 2]],
       // Properties with underscores and $.
       ['$_foo.bar_baz', ['$_foo', 'bar_baz']],
       // Deep nesting.
-      ['very.deep.nested[0].property.path[5]', ['very', 'deep', 'nested', '0', 'property', 'path', '5']],
+      ['very.deep.nested[0].property.path[5]', ['very', 'deep', 'nested', 0, 'property', 'path', 5]],
       // Single character properties.
-      ['a[0].b.c', ['a', '0', 'b', 'c']],
+      ['a[0].b.c', ['a', 0, 'b', 'c']],
       // Properties containing numbers.
-      ['prop123.item456[7]', ['prop123', 'item456', '7']],
+      ['prop123.item456[7]', ['prop123', 'item456', 7]],
     ] as const;
 
     cases.forEach(([input, expected]) => {
@@ -99,3 +99,42 @@ describe('createJsonPath', () => {
     expect(getField({ a: 'foo' }, 'a' as JsonPath)).toBe('foo');
   });
 });
+
+describe('Types', () => {
+  test('checks sanity', async ({ expect }) => {
+    const obj = {};
+    expect(obj).to.exist;
+  });
+});
+
+describe('get/set deep', () => {
+  test('get/set operations', ({ expect }) => {
+    const obj = {
+      name: 'test',
+      items: ['a', 'b', 'c'],
+      nested: {
+        prop: 'value',
+        arr: [1, 2, 3],
+      },
+    };
+
+    // Basic property access.
+    expect(getValue(obj, 'name' as JsonPath)).toBe('test');
+
+    // Array index access.
+    expect(getValue(obj, 'items[1]' as JsonPath)).toBe('b');
+
+    // Nested property access.
+    expect(getValue(obj, 'nested.prop' as JsonPath)).toBe('value');
+
+    // Nested array access.
+    expect(getValue(obj, 'nested.arr[2]' as JsonPath)).toBe(3);
+
+    // Setting values.
+    const updated1 = setValue(obj, 'items[1]' as JsonPath, 'x');
+    expect(updated1.items[1]).toBe('x');
+
+    const updated2 = setValue(obj, 'nested.arr[0]' as JsonPath, 99);
+    expect(updated2.nested.arr[0]).toBe(99);
+  });
+});

package/src/{jsonPath.ts → json-path.ts}

@@ -2,20 +2,26 @@
 // Copyright 2025 DXOS.org
 //
 
-import { Schema, Option } from 'effect';
+import * as Option from 'effect/Option';
+import * as Schema from 'effect/Schema';
 import { JSONPath } from 'jsonpath-plus';
 
 import { invariant } from '@dxos/invariant';
+import { getDeep, setDeep } from '@dxos/util';
 
 export type JsonProp = string & { __JsonPath: true; __JsonProp: true };
 export type JsonPath = string & { __JsonPath: true };
 
+// TODO(burdon): Start with "$."?
+
 const PATH_REGEX = /^($|[a-zA-Z_$][\w$]*(?:\.[a-zA-Z_$][\w$]*|\[\d+\](?:\.)?)*$)/;
+
 const PROP_REGEX = /^\w+$/;
 
 /**
  * https://www.ietf.org/archive/id/draft-goessner-dispatch-jsonpath-00.html
  */
+// TODO(burdon): Keys could be arbitrary strings.
 export const JsonPath = Schema.String.pipe(Schema.pattern(PATH_REGEX)).annotations({
   title: 'JSON path',
   description: 'JSON path to a property',
@@ -49,7 +55,7 @@ export const isJsonPath = (value: unknown): value is JsonPath => {
  * @param path Array of string or number segments
  * @returns Valid JsonPath or undefined if invalid
  */
-export const createJsonPath = (path: (string | number)[]): JsonPath => {
+export const createJsonPath = (path: readonly (string | number)[]): JsonPath => {
   const candidatePath = path
     .map((p, i) => {
       if (typeof p === 'number') {
@@ -79,7 +85,7 @@ export const fromEffectValidationPath = (effectPath: string): JsonPath => {
  * Splits a JsonPath into its constituent parts.
  * Handles property access and array indexing.
  */
-export const splitJsonPath = (path: JsonPath): string[] => {
+export const splitJsonPath = (path: JsonPath): (string | number)[] => {
   if (!isJsonPath(path)) {
     return [];
   }
@@ -87,14 +93,33 @@ export const splitJsonPath = (path: JsonPath): string[] => {
   return (
     path
       .match(/[a-zA-Z_$][\w$]*|\[\d+\]/g)
-      ?.map((part) => (part.startsWith('[') ? part.replace(/[[\]]/g, '') : part)) ?? []
+      ?.map((part) => part.replace(/[[\]]/g, ''))
+      .map((part) => {
+        const parsed = Number.parseInt(part, 10);
+        return Number.isNaN(parsed) ? part : parsed;
+      }) ?? []
   );
 };
 
 /**
  * Applies a JsonPath to an object.
  */
+// TODO(burdon): Reconcile with getValue.
 export const getField = (object: any, path: JsonPath): any => {
   // By default, JSONPath returns an array of results.
   return JSONPath({ path, json: object })[0];
 };
+
+/**
+ * Get value from object using JsonPath.
+ */
+export const getValue = <T extends object>(obj: T, path: JsonPath): any => {
+  return getDeep(obj, splitJsonPath(path));
+};
+
+/**
+ * Set value on object using JsonPath.
+ */
+export const setValue = <T extends object>(obj: T, path: JsonPath, value: any): T => {
+  return setDeep(obj, splitJsonPath(path), value);
+};

package/src/layers.test.ts

@@ -0,0 +1,112 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { it } from '@effect/vitest';
+import * as Context from 'effect/Context';
+import * as Duration from 'effect/Duration';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import * as ManagedRuntime from 'effect/ManagedRuntime';
+import { test } from 'vitest';
+
+import { runAndForwardErrors } from './errors';
+
+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* (_) {
+      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 runAndForwardErrors(
+      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 runAndForwardErrors(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/otel.test.ts

@@ -0,0 +1,126 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { afterAll, beforeAll, it } from '@effect/vitest';
+import { SpanStatusCode, trace } from '@opentelemetry/api';
+import { type Logger, SeverityNumber, logs } from '@opentelemetry/api-logs';
+import { resourceFromAttributes } from '@opentelemetry/resources';
+import { ConsoleLogRecordExporter, LoggerProvider, SimpleLogRecordProcessor } from '@opentelemetry/sdk-logs';
+import { NodeSDK } from '@opentelemetry/sdk-node';
+import { ConsoleSpanExporter } from '@opentelemetry/sdk-trace-node';
+import {
+  ATTR_CODE_FILE_PATH,
+  ATTR_CODE_LINE_NUMBER,
+  ATTR_CODE_STACKTRACE,
+  ATTR_SERVICE_NAME,
+} from '@opentelemetry/semantic-conventions';
+import * as Duration from 'effect/Duration';
+import * as Effect from 'effect/Effect';
+import { beforeEach } from 'vitest';
+
+import { LogLevel, type LogProcessor, log } from '@dxos/log';
+
+import { layerOtel } from './otel';
+
+const resource = resourceFromAttributes({
+  [ATTR_SERVICE_NAME]: 'test',
+});
+
+const sdk = new NodeSDK({
+  traceExporter: new ConsoleSpanExporter(),
+  resource,
+});
+
+// and add a processor to export log record
+const loggerProvider = new LoggerProvider({
+  processors: [new SimpleLogRecordProcessor(new ConsoleLogRecordExporter())],
+  resource,
+});
+logs.setGlobalLoggerProvider(loggerProvider);
+
+// You can also use global singleton
+const logger = logs.getLogger('test');
+
+const makeOtelLogProcessor = (logger: Logger): LogProcessor => {
+  return (config, entry) => {
+    let severity: SeverityNumber = SeverityNumber.UNSPECIFIED;
+    switch (entry.level) {
+      case LogLevel.DEBUG:
+        severity = SeverityNumber.DEBUG;
+        break;
+      case LogLevel.INFO:
+        severity = SeverityNumber.INFO;
+        break;
+      case LogLevel.WARN:
+        severity = SeverityNumber.WARN;
+        break;
+      case LogLevel.ERROR:
+        severity = SeverityNumber.ERROR;
+        break;
+    }
+
+    logger.emit({
+      body: entry.error ? ('stack' in entry.error ? entry.error.stack : String(entry.error)) : entry.message,
+      severityNumber: severity,
+      attributes: {
+        [ATTR_CODE_FILE_PATH]: entry.meta?.F,
+        [ATTR_CODE_LINE_NUMBER]: entry.meta?.L,
+        [ATTR_CODE_STACKTRACE]: entry.error?.stack,
+        ...(typeof entry.context === 'object'
+          ? entry.context
+          : {
+              ctx: entry.context,
+            }),
+      },
+    });
+  };
+};
+
+log.addProcessor(makeOtelLogProcessor(logger));
+
+beforeAll(() => {
+  sdk.start();
+});
+
+afterAll(async () => {
+  await loggerProvider.shutdown();
+  await sdk.shutdown();
+});
+
+beforeEach((ctx) => {
+  const span = trace.getTracer('testing-framework').startSpan(ctx.task.name);
+  ctx.onTestFailed((ctx) => {
+    // TODO(dmaretskyi): Record result.
+    span.setStatus({ code: SpanStatusCode.ERROR });
+    span.end();
+  });
+  ctx.onTestFinished((ctx) => {
+    span.setStatus({ code: SpanStatusCode.OK });
+    span.end();
+  });
+});
+
+const foo = Effect.fn('foo')(function* () {
+  yield* Effect.sleep(Duration.millis(100));
+
+  log('log inside foo', { detail: 123 });
+});
+
+const bar = Effect.fn('bar')(function* () {
+  yield* foo();
+});
+
+const baz = Effect.fn('baz')(function* () {
+  yield* bar();
+});
+
+it.live(
+  'Test Suite One',
+  Effect.fnUntraced(
+    function* () {
+      yield* baz();
+    },
+    Effect.provide(layerOtel(Effect.succeed({}))),
+  ),
+);