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

package/package.json

@@ -1,10 +1,14 @@
 {
   "name": "@dxos/effect",
-  "version": "0.8.4-main.fd6878d",
+  "version": "0.8.4-staging.60fe92afc8",
   "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,29 +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": {
-    "jsonpath-plus": "10.2.0",
-    "@dxos/context": "0.8.4-main.fd6878d",
-    "@dxos/invariant": "0.8.4-main.fd6878d",
-    "@dxos/node-std": "0.8.4-main.fd6878d",
-    "@dxos/util": "0.8.4-main.fd6878d"
+    "@effect-atom/atom-react": "^0.5.0",
+    "@effect/opentelemetry": "^0.63.0",
+    "@opentelemetry/api": "^1.9.1",
+    "jsonpath-plus": "^10.3.0",
+    "@dxos/node-std": "0.8.4-staging.60fe92afc8",
+    "@dxos/context": "0.8.4-staging.60fe92afc8",
+    "@dxos/util": "0.8.4-staging.60fe92afc8",
+    "@dxos/invariant": "0.8.4-staging.60fe92afc8"
   },
   "devDependencies": {
-    "effect": "3.17.7",
-    "@dxos/log": "0.8.4-main.fd6878d"
+    "@effect/platform": "0.96.1",
+    "@effect/platform-browser": "0.76.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.21.3",
+    "@dxos/log": "0.8.4-staging.60fe92afc8"
   },
   "peerDependencies": {
-    "effect": "^3.13.3"
+    "@effect/platform": "0.96.1",
+    "@effect/platform-browser": "0.76.0",
+    "effect": "3.21.3"
   },
   "publishConfig": {
     "access": "public"

package/src/EffectEx.ts

@@ -0,0 +1,18 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+// @import-as-namespace
+
+export { asyncTaskTaggingLayer } from './internal/async-task-tagging';
+export { contextFromScope } from './internal/context';
+export {
+  causeToError,
+  throwCause,
+  unwrapExit,
+  runAndForwardErrors,
+  runPromise,
+  runInRuntime,
+  promiseWithCauseCapture,
+} from './internal/errors';
+export { acquireReleaseResource } from './internal/resource';

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 './internal/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/SchemaEx.ts

@@ -0,0 +1,46 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+// @import-as-namespace
+
+export {
+  getBaseType,
+  type SchemaProperty,
+  getProperties,
+  VisitResult,
+  type Path,
+  type TestFn,
+  type VisitorFn,
+  visit,
+  findNode,
+  findProperty,
+  getAnnotation,
+  findAnnotation,
+  isOption,
+  isLiteralUnion,
+  getLiteralValues,
+  isArrayType,
+  getArrayElementType,
+  isTupleType,
+  isDiscriminatedUnion,
+  getDiscriminatingProps,
+  getDiscriminatedType,
+  isNestedType,
+  mapAst,
+  unwrapOptional,
+} from './internal/ast';
+
+export {
+  JsonPath,
+  JsonProp,
+  isJsonPath,
+  createJsonPath,
+  fromEffectValidationPath,
+  splitJsonPath,
+  getField,
+  getValue,
+  setValue,
+} from './internal/json-path';
+
+export { getParamKeyAnnotation, ParamKeyAnnotation, UrlParser } from './internal/url';

package/src/ast.test.ts

@@ -2,7 +2,8 @@
 // Copyright 2024 DXOS.org
 //
 
-import { Schema, SchemaAST } from 'effect';
+import * as Schema from 'effect/Schema';
+import * as SchemaAST from 'effect/SchemaAST';
 import { describe, test } from 'vitest';
 
 import { invariant } from '@dxos/invariant';
@@ -14,13 +15,13 @@ import {
   getAnnotation,
   getDiscriminatedType,
   getDiscriminatingProps,
-  getSimpleType,
+  getProperties,
   isArrayType,
+  isDiscriminatedUnion,
   isOption,
-  isSimpleType,
   visit,
-} from './ast';
-import { type JsonPath, type JsonProp } from './jsonPath';
+} from './internal/ast';
+import { type JsonPath, type JsonProp } from './internal/json-path';
 
 const ZipCode = Schema.String.pipe(
   Schema.pattern(/^\d{5}$/, {
@@ -64,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 }) => {
@@ -91,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',
@@ -136,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 }) => {
@@ -151,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/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);
+};