@dxos/echo 0.9.1-main.c7dcc2e112 → 0.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dxos/echo",
-  "version": "0.9.1-main.c7dcc2e112",
+  "version": "0.10.0",
   "description": "ECHO API",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
@@ -123,6 +123,11 @@
       "types": "./dist/types/src/Tag.d.ts",
       "default": "./dist/lib/neutral/Tag.mjs"
     },
+    "./Text": {
+      "source": "./src/Text.ts",
+      "types": "./dist/types/src/Text.d.ts",
+      "default": "./dist/lib/neutral/Text.mjs"
+    },
     "./Type": {
       "source": "./src/Type.ts",
       "types": "./dist/types/src/Type.d.ts",
@@ -135,20 +140,22 @@
   ],
   "dependencies": {
     "@effect-atom/atom": "^0.5.3",
-    "effect": "3.21.3",
-    "@dxos/async": "0.9.1-main.c7dcc2e112",
-    "@dxos/echo-protocol": "0.9.1-main.c7dcc2e112",
-    "@dxos/effect": "0.9.1-main.c7dcc2e112",
-    "@dxos/errors": "0.9.1-main.c7dcc2e112",
-    "@dxos/keys": "0.9.1-main.c7dcc2e112",
-    "@dxos/invariant": "0.9.1-main.c7dcc2e112",
-    "@dxos/log": "0.9.1-main.c7dcc2e112",
-    "@dxos/node-std": "0.9.1-main.c7dcc2e112",
-    "@dxos/util": "0.9.1-main.c7dcc2e112",
-    "@dxos/debug": "0.9.1-main.c7dcc2e112"
+    "effect": "3.21.4",
+    "semver": "^7.7.4",
+    "@dxos/async": "0.10.0",
+    "@dxos/debug": "0.10.0",
+    "@dxos/echo-protocol": "0.10.0",
+    "@dxos/effect": "0.10.0",
+    "@dxos/errors": "0.10.0",
+    "@dxos/keys": "0.10.0",
+    "@dxos/invariant": "0.10.0",
+    "@dxos/util": "0.10.0",
+    "@dxos/log": "0.10.0",
+    "@dxos/node-std": "0.10.0"
   },
   "devDependencies": {
-    "@types/node": "22.10.2"
+    "@types/node": "22.10.2",
+    "@types/semver": "^7.7.1"
   },
   "publishConfig": {
     "access": "public"

package/src/Annotation.test.ts

@@ -2,6 +2,7 @@
 // Copyright 2026 DXOS.org
 //
 
+import * as Registry from '@effect-atom/atom/Registry';
 import * as Option from 'effect/Option';
 import * as Schema from 'effect/Schema';
 import * as SchemaAST from 'effect/SchemaAST';
@@ -11,6 +12,7 @@ import { DXN } from '@dxos/keys';
 
 import * as Annotation from './Annotation';
 import * as Obj from './Obj';
+import * as Ref from './Ref';
 import * as Type from './Type';
 
 describe('Annotation', () => {
@@ -347,11 +349,11 @@ describe('Annotation', () => {
         schema: Schema.String,
       });
 
-      const TaggedPerson = Schema.Struct({
-        name: Schema.String,
-      })
-        .pipe(ColorAnnotation.set('teal'))
-        .pipe(Type.makeObject(DXN.make('com.example.type.taggedperson', '0.1.0')));
+      const TaggedPerson = Type.makeObject(DXN.make('com.example.type.taggedperson', '0.1.0'))(
+        Schema.Struct({
+          name: Schema.String,
+        }).pipe(ColorAnnotation.set('teal')),
+      );
 
       const schema = Type.getSchema(TaggedPerson);
       const result = ColorAnnotation.get(schema);
@@ -366,11 +368,11 @@ describe('Annotation', () => {
       id: 'org.dxos.annotation.color',
       schema: Schema.String,
     });
-    const Person = Schema.Struct({
-      name: Schema.String,
-    })
-      .pipe(ColorAnnotation.set('schema-teal'))
-      .pipe(Type.makeObject(DXN.make('com.example.type.taggedperson', '0.1.0')));
+    const Person = Type.makeObject(DXN.make('com.example.type.taggedperson', '0.1.0'))(
+      Schema.Struct({
+        name: Schema.String,
+      }).pipe(ColorAnnotation.set('schema-teal')),
+    );
 
     test('set and get on Obj.make instance', ({ expect }) => {
       const person = Obj.make(Person, { name: 'Alice' });
@@ -436,4 +438,249 @@ describe('Annotation', () => {
       expect(Option.getOrThrow(Annotation.get(snapshot, ColorAnnotation))).toBe('snapshot-color');
     });
   });
+
+  describe('atom', () => {
+    // Record-valued annotation mirroring a per-key ordering (e.g. SectionOrderAnnotation).
+    const OrderAnnotation = Annotation.make({
+      id: 'org.dxos.test.order',
+      schema: Schema.Record({ key: Schema.String, value: Schema.Array(Schema.String) }),
+    });
+    const Container = Type.makeObject(DXN.make('com.example.type.container', '0.1.0'))(
+      Schema.Struct({ name: Schema.String }),
+    );
+
+    const setOrder = (obj: Obj.Unknown, order: Record<string, string[]>) =>
+      Obj.update(obj, (obj) => {
+        Annotation.set(obj, OrderAnnotation, order);
+      });
+
+    test('atomProperty reads the typed slice for a key', ({ expect }) => {
+      const registry = Registry.make();
+      const obj = Obj.make(Container, { name: 'A' });
+      setOrder(obj, { typeA: ['x', 'y'], typeB: ['m'] });
+
+      const atomA = Annotation.atomProperty(obj, OrderAnnotation, 'typeA');
+      expect(registry.get(atomA)).toEqual(['x', 'y']);
+    });
+
+    test('atomProperty returns undefined for a missing key or annotation', ({ expect }) => {
+      const registry = Registry.make();
+      const obj = Obj.make(Container, { name: 'A' });
+
+      const missingAnnotation = Annotation.atomProperty(obj, OrderAnnotation, 'typeA');
+      expect(registry.get(missingAnnotation)).toBeUndefined();
+
+      setOrder(obj, { typeA: ['x'] });
+      const missingKey = Annotation.atomProperty(obj, OrderAnnotation, 'typeZ');
+      expect(registry.get(missingKey)).toBeUndefined();
+    });
+
+    test('atomProperty updates when its own key changes', ({ expect }) => {
+      const registry = Registry.make();
+      const obj = Obj.make(Container, { name: 'A' });
+      setOrder(obj, { typeA: ['x', 'y'] });
+
+      const atomA = Annotation.atomProperty(obj, OrderAnnotation, 'typeA');
+      let fires = 0;
+      registry.subscribe(atomA, () => {
+        fires++;
+      });
+      expect(registry.get(atomA)).toEqual(['x', 'y']);
+
+      setOrder(obj, { typeA: ['y', 'x'] });
+      expect(registry.get(atomA)).toEqual(['y', 'x']);
+      expect(fires).toBeGreaterThan(0);
+    });
+
+    test('atomProperty reflects only its own key', ({ expect }) => {
+      const registry = Registry.make();
+      const obj = Obj.make(Container, { name: 'A' });
+      setOrder(obj, { typeA: ['x', 'y'], typeB: ['m'] });
+
+      const atomA = Annotation.atomProperty(obj, OrderAnnotation, 'typeA');
+      expect(registry.get(atomA)).toEqual(['x', 'y']);
+
+      // Changing a different key leaves typeA's value content unchanged.
+      setOrder(obj, { typeA: ['x', 'y'], typeB: ['m', 'n'] });
+      expect(registry.get(atomA)).toEqual(['x', 'y']);
+    });
+
+    test('atom exposes the whole annotation value as an Option', ({ expect }) => {
+      const registry = Registry.make();
+      const obj = Obj.make(Container, { name: 'A' });
+
+      const wholeAtom = Annotation.atom(obj, OrderAnnotation);
+      expect(Option.isNone(registry.get(wholeAtom))).toBe(true);
+
+      setOrder(obj, { typeA: ['x'] });
+      expect(Option.getOrThrow(registry.get(wholeAtom))).toEqual({ typeA: ['x'] });
+    });
+  });
+
+  describe('reactive in-place mutation', () => {
+    const OrderAnnotation = Annotation.make({
+      id: 'org.dxos.test.mutable-order',
+      schema: Schema.Record({ key: Schema.String, value: Schema.Array(Schema.String) }),
+    });
+    const RefOrderAnnotation = Annotation.make({
+      id: 'org.dxos.test.mutable-ref-order',
+      schema: Schema.Record({ key: Schema.String, value: Schema.Array(Ref.Ref(Obj.Unknown)) }),
+    });
+    const Item = Type.makeObject(DXN.make('com.example.type.mutableItem', '0.1.0'))(
+      Schema.Struct({ name: Schema.String }),
+    );
+    const Container = Type.makeObject(DXN.make('com.example.type.mutableContainer', '0.1.0'))(
+      Schema.Struct({ name: Schema.String }),
+    );
+
+    test('push to an annotation array in place without Annotation.set', ({ expect }) => {
+      const registry = Registry.make();
+      const obj = Obj.make(Container, { name: 'A' });
+      Obj.update(obj, (obj) => Annotation.set(obj, OrderAnnotation, { typeA: ['x', 'y'] }));
+
+      const atomA = Annotation.atomProperty(obj, OrderAnnotation, 'typeA');
+      expect(registry.get(atomA)).toEqual(['x', 'y']);
+
+      Annotation.update(obj, OrderAnnotation, (order) => {
+        order.typeA.push('z');
+      });
+
+      expect(registry.get(atomA)).toEqual(['x', 'y', 'z']);
+    });
+
+    test('splice an annotation array in place reorders the value', ({ expect }) => {
+      const registry = Registry.make();
+      const obj = Obj.make(Container, { name: 'A' });
+      Obj.update(obj, (obj) => Annotation.set(obj, OrderAnnotation, { typeA: ['x', 'y', 'z'] }));
+
+      const atomA = Annotation.atomProperty(obj, OrderAnnotation, 'typeA');
+
+      Annotation.update(obj, OrderAnnotation, (order) => {
+        order.typeA.splice(0, order.typeA.length, 'z', 'x', 'y');
+      });
+
+      expect(registry.get(atomA)).toEqual(['z', 'x', 'y']);
+    });
+
+    test('in-place mutation of one key leaves other keys untouched', ({ expect }) => {
+      const obj = Obj.make(Container, { name: 'A' });
+      Obj.update(obj, (obj) => Annotation.set(obj, OrderAnnotation, { typeA: ['x'], typeB: ['m'] }));
+
+      Annotation.update(obj, OrderAnnotation, (order) => {
+        order.typeA.push('y');
+      });
+
+      expect(Option.getOrThrow(Annotation.get(obj, OrderAnnotation))).toEqual({ typeA: ['x', 'y'], typeB: ['m'] });
+    });
+
+    test('push a Ref to an annotation array in place', ({ expect }) => {
+      const obj = Obj.make(Container, { name: 'A' });
+      const a = Obj.make(Item, { name: 'a' });
+      const b = Obj.make(Item, { name: 'b' });
+      Obj.update(obj, (obj) => Annotation.set(obj, RefOrderAnnotation, { typeA: [Ref.make(a)] }));
+
+      Annotation.update(obj, RefOrderAnnotation, (order) => {
+        order.typeA.push(Ref.make(b));
+      });
+
+      const result = Annotation.get(obj, RefOrderAnnotation).pipe(Option.getOrThrow);
+      expect(result.typeA.map((ref) => ref.target?.id)).toEqual([a.id, b.id]);
+    });
+
+    test('atomProperty notifies subscribers when a Ref array is reordered in place', ({ expect }) => {
+      const registry = Registry.make();
+      const obj = Obj.make(Container, { name: 'A' });
+      const a = Obj.make(Item, { name: 'a' });
+      const b = Obj.make(Item, { name: 'b' });
+      const c = Obj.make(Item, { name: 'c' });
+      Obj.update(obj, (obj) =>
+        Annotation.set(obj, RefOrderAnnotation, { typeA: [Ref.make(a), Ref.make(b), Ref.make(c)] }),
+      );
+
+      const atomA = Annotation.atomProperty(obj, RefOrderAnnotation, 'typeA');
+      let fires = 0;
+      registry.subscribe(atomA, () => {
+        fires++;
+      });
+      registry.get(atomA);
+
+      Annotation.update(obj, RefOrderAnnotation, (order) => {
+        order.typeA.splice(0, order.typeA.length, Ref.make(c), Ref.make(a), Ref.make(b));
+      });
+
+      expect(fires).toBeGreaterThan(0);
+      // The atom emits a shallow snapshot of the ref array (refs kept intact).
+      expect(registry.get(atomA)?.map((ref) => ref.target?.id)).toEqual([c.id, a.id, b.id]);
+    });
+
+    test('reorder snapshot does not touch ref targets (tolerates cyclic targets)', ({ expect }) => {
+      const registry = Registry.make();
+      const obj = Obj.make(Container, { name: 'A' });
+      const a = Obj.make(Item, { name: 'a' });
+      // The annotation on `obj` holds a ref back to `obj`, so a loaded target forms a cycle —
+      // the shallow snapshot copies the array without dereferencing its ref elements, so it tolerates this.
+      Obj.update(obj, (obj) => Annotation.set(obj, RefOrderAnnotation, { typeA: [Ref.make(a), Ref.make(obj)] }));
+
+      const atomA = Annotation.atomProperty(obj, RefOrderAnnotation, 'typeA');
+      let fires = 0;
+      registry.subscribe(atomA, () => {
+        fires++;
+      });
+      registry.get(atomA);
+
+      Annotation.update(obj, RefOrderAnnotation, (order) => {
+        order.typeA.splice(0, order.typeA.length, Ref.make(obj), Ref.make(a));
+      });
+
+      expect(fires).toBeGreaterThan(0);
+    });
+
+    test('Annotation.update mutates in place (wraps its own change)', ({ expect }) => {
+      const registry = Registry.make();
+      const obj = Obj.make(Container, { name: 'A' });
+      Obj.update(obj, (obj) => Annotation.set(obj, OrderAnnotation, { typeA: ['x', 'y'] }));
+
+      const atomA = Annotation.atomProperty(obj, OrderAnnotation, 'typeA');
+
+      // No surrounding Obj.update — Annotation.update opens its own change transaction.
+      Annotation.update(obj, OrderAnnotation, (order) => {
+        order.typeA.push('z');
+      });
+
+      expect(registry.get(atomA)).toEqual(['x', 'y', 'z']);
+    });
+
+    test('Annotation.update is a no-op when the annotation is absent', ({ expect }) => {
+      const obj = Obj.make(Container, { name: 'A' });
+      let called = false;
+      Annotation.update(obj, OrderAnnotation, () => {
+        called = true;
+      });
+
+      expect(called).toBe(false);
+      expect(Option.isNone(Annotation.get(obj, OrderAnnotation))).toBe(true);
+    });
+
+    test('Annotation.update validates the mutated value against the annotation schema', ({ expect }) => {
+      const obj = Obj.make(Container, { name: 'A' });
+      Obj.update(obj, (obj) => Annotation.set(obj, OrderAnnotation, { typeA: ['x'] }));
+
+      expect(() =>
+        Annotation.update(obj, OrderAnnotation, (order) => {
+          // Pushing a number into a string array violates the annotation schema.
+          // @ts-expect-error intentional type violation to exercise runtime validation
+          order.typeA.push(42);
+        }),
+      ).toThrow();
+    });
+
+    test('set validates the value against the annotation schema', ({ expect }) => {
+      const obj = Obj.make(Container, { name: 'A' });
+      Obj.update(obj, (obj) => {
+        // OrderAnnotation values must be string arrays; a number element violates the schema.
+        // @ts-expect-error intentional type violation to exercise runtime validation
+        expect(() => Annotation.set(obj, OrderAnnotation, { typeA: [1] })).toThrow();
+      });
+    });
+  });
 });

package/src/Annotation.ts

@@ -5,23 +5,27 @@
 // @import-as-namespace
 
 export {
+  DEFAULT_LAYOUT_NAME,
   DescriptionAnnotation,
   FieldLookupAnnotationId,
-  FormInputAnnotation,
+  FormCreateAnnotation,
+  FormCreateAnnotationId,
   FormInlineAnnotation,
-  FormOrderedAnnotation,
+  FormInputAnnotation,
   FormLayoutAnnotation,
   FormLayoutAnnotationId,
   type FormLayoutMap,
-  DEFAULT_LAYOUT_NAME,
+  FormOrderedAnnotation,
   GeneratorAnnotation,
   GeneratorAnnotationId,
   type GeneratorAnnotationValue,
+  HiddenAnnotation,
+  IconAnnotation,
+  IconFromRefAnnotation,
   LabelAnnotation,
   ReferenceAnnotation,
   ReferenceAnnotationId,
   type ReferenceAnnotationValue,
-  HiddenAnnotation,
   TypeAnnotation,
   getDescriptionWithSchema,
   getLabelWithSchema,
@@ -29,8 +33,6 @@ export {
   getTypeIdentifierAnnotation,
   setDescriptionWithSchema,
   setLabelWithSchema,
-  IconAnnotation,
-  IconFromRefAnnotation,
 } from './internal/Annotation';
 
 import * as Function from 'effect/Function';
@@ -41,6 +43,7 @@ import * as Types from 'effect/Types';
 
 import * as Entity from './Entity';
 import * as internalAnnotations from './internal/Annotation';
+import * as annotationAtoms from './internal/Annotation/atoms';
 
 export const TypeId = '~@dxos/echo/Annotation' as const;
 export type TypeId = typeof TypeId;
@@ -121,6 +124,11 @@ export const make: <T>(props: MakeProps<T>) => Annotation<T> = internalAnnotatio
  * Get the value of an annotation from an entity instance or snapshot.
  * For schema-level reads use the annotation instance method (e.g. `ColorAnnotation.get(schema)`).
  * For getting an annotation value from a dictionary, use `getDictionary`.
+ *
+ * The value is read-only (schema types are readonly by default): to mutate an annotation (including
+ * in-place array splices) use `Annotation.update` or `Annotation.set`, which open a change transaction.
+ * A read-only return is sound regardless of context — the reactive proxy rejects mutation outside an
+ * `Obj.update`.
  */
 export const get: {
   <T>(annotation: Annotation<T>): (target: Entity.Unknown | Entity.Snapshot) => Option.Option<T>;
@@ -147,6 +155,18 @@ export const set: {
   return internalAnnotations.set(target, annotation, value);
 });
 
+/**
+ * Mutate an existing annotation value in place via a callback, wrapping the mutation in a change
+ * transaction (like `Obj.update`). The result is validated against the annotation's schema. Use when
+ * only an annotation needs to change; to mutate it alongside other changes (unvalidated), call
+ * `Annotation.get` inside an existing `Obj.update` instead. No-op when absent.
+ */
+export const update = <T>(
+  target: Entity.Unknown,
+  annotation: Annotation<T>,
+  mutator: (value: Entity.Mutable<T>) => void,
+): void => internalAnnotations.update(target, annotation, mutator);
+
 export const getFromAst: {
   <T>(annotation: Annotation<T>): (ast: SchemaAST.AST) => Option.Option<T>;
   <T>(ast: SchemaAST.AST, annotation: Annotation<T>): Option.Option<T>;
@@ -157,6 +177,18 @@ export const getFromAst: {
   return internalAnnotations.getFromAst(ast, annotation);
 });
 
+/**
+ * Reactive atom for an annotation value on an entity instance.
+ * Fires only when the annotation value changes (mirrors `Obj.atom`, scoped to one annotation).
+ */
+export const atom = annotationAtoms.makeAtom;
+
+/**
+ * Reactive atom for a single key of a record-valued annotation on an entity instance.
+ * Reactivity is scoped to that key, and the value type is preserved (mirrors `Obj.atomProperty`).
+ */
+export const atomProperty = annotationAtoms.makeProperty;
+
 /**
  * Set of annotation values.
  *
@@ -205,3 +237,20 @@ export const setDictionary: {
 >(3, (values, annotation, value) => {
   return internalAnnotations.setDictionary(values, annotation, value);
 });
+
+/**
+ * Build a dictionary by mutating it in a callback.
+ *
+ * @example
+ * ```ts
+ * const dictionary = Annotation.buildDictionary((dictionary) => {
+ *   Annotation.setDictionary(dictionary, ColorAnnotation, 'red');
+ *   Annotation.setDictionary(dictionary, SizeAnnotation, '10px');
+ * });
+ * ```
+ */
+export const buildDictionary = (build: (dictionary: Types.Mutable<Dictionary>) => void): Dictionary => {
+  const dictionary = Schema.encodeSync(Dictionary)({});
+  build(dictionary);
+  return dictionary;
+};

package/src/Collection.ts

@@ -17,17 +17,15 @@ import * as Type from './Type';
 /**
  * A an ordered set of objects.
  */
-export const Collection = Schema.Struct({
-  name: Schema.String.pipe(Schema.optional),
-  objects: Schema.Array(Ref.Ref(Obj.Unknown)).pipe(internal.FormInputAnnotation.set(false)),
-}).pipe(
-  Annotation.IconAnnotation.set({ icon: 'ph--folder--regular', hue: 'amber' }),
-  Type.makeObject(DXN.make('org.dxos.type.collection', '0.1.0')),
-);
-
-export type Collection = Type.InstanceType<typeof Collection>;
-
-export const make = (props: Partial<Obj.MakeProps<typeof Collection>> = {}): Collection =>
+export class Collection extends Type.makeObject<Collection>(DXN.make('org.dxos.type.collection', '0.1.0'))(
+  Schema.Struct({
+    name: Schema.String.pipe(Schema.optional),
+    objects: Schema.Array(Ref.Ref(Obj.Unknown)).pipe(internal.FormInputAnnotation.set(false)),
+  }).pipe(Annotation.IconAnnotation.set({ icon: 'ph--folder--regular', hue: 'indigo' })),
+) {}
+
+export const make = (props: Partial<Obj.MakeProps<typeof Collection>> = {}): Type.InstanceType<typeof Collection> =>
   Obj.make(Collection, { objects: [], ...props });
 
-export const isCollection: (value: unknown) => value is Collection = Obj.instanceOf(Collection);
+export const isCollection: (value: unknown) => value is Type.InstanceType<typeof Collection> =
+  Obj.instanceOf(Collection);

package/src/Database.ts

@@ -6,9 +6,7 @@
 
 import * as Context from 'effect/Context';
 import * as Effect from 'effect/Effect';
-import * as Effectable from 'effect/Effectable';
 import * as Layer from 'effect/Layer';
-import * as Option from 'effect/Option';
 import * as Schema from 'effect/Schema';
 
 import { EffectEx } from '@dxos/effect';
@@ -24,6 +22,7 @@ import { type AnyProperties, EntityKind, KindId } from './internal/common/types'
 // Deep import (not the `./internal/Entity` barrel) to avoid a cycle:
 // Database → internal/Entity → entity → JsonSchema → Ref → Database.
 import { isInstanceOf } from './internal/Entity/type-uri';
+import * as queryInternal from './internal/Query';
 import type { Ref } from './internal/Ref/ref';
 import type * as Obj from './Obj';
 import type * as Query from './Query';
@@ -185,6 +184,26 @@ export interface Database extends Queryable {
    * Optionaly waits for changes to be propagated to indexes and event handlers.
    */
   flush(opts?: FlushOptions): Promise<void>;
+
+  /**
+   * Removes feed items by ID.
+   */
+  removeFeedItemsByIds(feed: Feed.Feed, ids: string[]): Promise<void>;
+
+  /**
+   * Queries items in a feed associated with this database.
+   */
+  queryFeed(feed: Feed.Feed, queryOrFilter: Query.Any | Filter.Any): QueryResult.QueryResult<any>;
+
+  /**
+   * Syncs a feed with the server.
+   */
+  syncFeed(feed: Feed.Feed, options?: Feed.SyncOptions): Promise<void>;
+
+  /**
+   * Returns queue replication backlog for the feed's namespace.
+   */
+  getFeedSyncState(feed: Feed.Feed): Promise<Feed.SyncState>;
 }
 
 export const isDatabase = (obj: unknown): obj is Database => {
@@ -356,22 +375,5 @@ export const query: {
   Service.pipe(
     Effect.map(({ db }) => db.query(queryOrFilter as any) as QueryResult.QueryResult<any>),
     Effect.withSpan('Database.query'),
-    makeQueryResultEffect,
+    queryInternal.makeQueryResultEffect,
   );
-
-const makeQueryResultEffect = <T>(
-  eff: Effect.Effect<QueryResult.QueryResult<T>, never, Service>,
-): QueryResult.QueryResultEffect<T, never, Service> => {
-  return {
-    run: Effect.flatMap(eff, (result) => EffectEx.promiseWithCauseCapture(() => result.run())),
-    first: Effect.flatMap(eff, (result) =>
-      EffectEx.promiseWithCauseCapture(async () => Option.fromNullable(await result.firstOrUndefined())),
-    ),
-
-    // Effect internals
-    ...Effectable.CommitPrototype,
-    commit() {
-      return eff;
-    },
-  } as any;
-};

package/src/Err.ts

@@ -19,6 +19,28 @@ export class EntityNotFoundError extends BaseError.extend('EntityNotFoundError',
   }
 }
 
+/**
+ * Thrown when a `Text` mutation is attempted on an object whose reactive handler does not implement
+ * string CRDT editing (e.g. a snapshot or a non-reactive value).
+ */
+export class TextNotSupportedError extends BaseError.extend(
+  'TextNotSupportedError',
+  'Text operation is not supported for this object',
+) {
+  constructor(operation: string, options?: BaseErrorOptions) {
+    super({ context: { operation }, ...options });
+  }
+}
+
+/**
+ * Thrown by `Text.apply` when a non-`replaceAll` edit's `oldString` is not found in the text.
+ */
+export class TextEditNotFoundError extends BaseError.extend('TextEditNotFoundError', 'Edit text not found') {
+  constructor(oldString: string, options?: BaseErrorOptions) {
+    super({ context: { oldString }, ...options });
+  }
+}
+
 /**
  * Reason why getting a reactive object from a snapshot failed.
  * - `no-database`: The snapshot is not associated with a database.