@dxos/echo 0.8.4-main.c85a9c8dae → 0.8.4-main.d05539e30a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dxos/echo",
-  "version": "0.8.4-main.c85a9c8dae",
+  "version": "0.8.4-main.d05539e30a",
   "description": "ECHO API",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
@@ -8,7 +8,7 @@
     "type": "git",
     "url": "https://github.com/dxos/dxos"
   },
-  "license": "MIT",
+  "license": "FSL-1.1-Apache-2.0",
   "author": "info@dxos.org",
   "sideEffects": false,
   "type": "module",
@@ -73,6 +73,11 @@
       "types": "./dist/types/src/Key.d.ts",
       "default": "./dist/lib/neutral/Key.mjs"
     },
+    "./Migration": {
+      "source": "./src/Migration.ts",
+      "types": "./dist/types/src/Migration.d.ts",
+      "default": "./dist/lib/neutral/Migration.mjs"
+    },
     "./Obj": {
       "source": "./src/Obj.ts",
       "types": "./dist/types/src/Obj.d.ts",
@@ -117,6 +122,11 @@
       "source": "./src/Type.ts",
       "types": "./dist/types/src/Type.d.ts",
       "default": "./dist/lib/neutral/Type.mjs"
+    },
+    "./Extension": {
+      "source": "./src/Extension.ts",
+      "types": "./dist/types/src/Extension.d.ts",
+      "default": "./dist/lib/neutral/Extension.mjs"
     }
   },
   "files": [
@@ -124,19 +134,19 @@
     "src"
   ],
   "dependencies": {
-    "effect": "3.19.16",
-    "@dxos/async": "0.8.4-main.c85a9c8dae",
-    "@dxos/context": "0.8.4-main.c85a9c8dae",
-    "@dxos/echo-protocol": "0.8.4-main.c85a9c8dae",
-    "@dxos/debug": "0.8.4-main.c85a9c8dae",
-    "@dxos/errors": "0.8.4-main.c85a9c8dae",
-    "@dxos/effect": "0.8.4-main.c85a9c8dae",
-    "@dxos/invariant": "0.8.4-main.c85a9c8dae",
-    "@dxos/keys": "0.8.4-main.c85a9c8dae",
-    "@dxos/node-std": "0.8.4-main.c85a9c8dae",
-    "@dxos/protocols": "0.8.4-main.c85a9c8dae",
-    "@dxos/util": "0.8.4-main.c85a9c8dae",
-    "@dxos/log": "0.8.4-main.c85a9c8dae"
+    "effect": "3.20.0",
+    "@dxos/async": "0.8.4-main.d05539e30a",
+    "@dxos/context": "0.8.4-main.d05539e30a",
+    "@dxos/echo-protocol": "0.8.4-main.d05539e30a",
+    "@dxos/effect": "0.8.4-main.d05539e30a",
+    "@dxos/invariant": "0.8.4-main.d05539e30a",
+    "@dxos/debug": "0.8.4-main.d05539e30a",
+    "@dxos/keys": "0.8.4-main.d05539e30a",
+    "@dxos/log": "0.8.4-main.d05539e30a",
+    "@dxos/node-std": "0.8.4-main.d05539e30a",
+    "@dxos/protocols": "0.8.4-main.d05539e30a",
+    "@dxos/util": "0.8.4-main.d05539e30a",
+    "@dxos/errors": "0.8.4-main.d05539e30a"
   },
   "publishConfig": {
     "access": "public"

package/src/Annotation.ts

@@ -2,6 +2,8 @@
 // Copyright 2025 DXOS.org
 //
 
+// @import-as-namespace
+
 export {
   DescriptionAnnotation,
   FormInputAnnotation,
@@ -16,11 +18,12 @@ export {
   setDescriptionWithSchema,
   setLabelWithSchema,
   IconAnnotation,
-} from './internal/annotations';
+  IconFromRefAnnotation,
+} from './internal/Annotation';
 
 import type * as Schema from 'effect/Schema';
 
-import * as internalAnnotations from './internal/annotations';
+import * as internalAnnotations from './internal/Annotation';
 
 interface MakeProps<T> {
   id: string;
@@ -35,7 +38,7 @@ interface MakeProps<T> {
  * @example
  * ```ts
  * const ColorAnnotation = Annotation.make({
- *   id: 'dxos.org/annotation/Color',
+ *   id: 'org.dxos.annotation.color',
  *   schema: Schema.String,
  * });
  *

package/src/Collection.ts

@@ -2,8 +2,11 @@
 // Copyright 2024 DXOS.org
 //
 
+// @import-as-namespace
+
 import * as Schema from 'effect/Schema';
 
+import * as Annotation from './Annotation';
 import * as internal from './internal';
 import * as Obj from './Obj';
 import * as Ref from './Ref';
@@ -17,9 +20,13 @@ export const Collection = Schema.Struct({
   objects: Schema.Array(Ref.Ref(Obj.Unknown)).pipe(internal.FormInputAnnotation.set(false)),
 }).pipe(
   Type.object({
-    typename: 'dxos.org/type/Collection',
+    typename: 'org.dxos.type.collection',
     version: '0.1.0',
   }),
+  Annotation.IconAnnotation.set({
+    icon: 'ph--folder--regular',
+    hue: 'amber',
+  }),
 );
 
 export interface Collection extends Schema.Schema.Type<typeof Collection> {}

package/src/Database.ts

@@ -2,6 +2,8 @@
 // Copyright 2025 DXOS.org
 //
 
+// @import-as-namespace
+
 import * as Context from 'effect/Context';
 import * as Effect from 'effect/Effect';
 import * as Layer from 'effect/Layer';
@@ -17,9 +19,9 @@ import type * as Entity from './Entity';
 import * as Err from './Err';
 import type * as Filter from './Filter';
 import type * as Hypergraph from './Hypergraph';
-import { isInstanceOf } from './internal/annotations';
-import type { Ref } from './internal/ref/ref';
-import { type AnyProperties } from './internal/types';
+import { isInstanceOf } from './internal/Annotation';
+import { type AnyProperties } from './internal/common/types';
+import type { Ref } from './internal/Ref/ref';
 import type * as Obj from './Obj';
 import type * as Query from './Query';
 import type * as QueryResult from './QueryResult';
@@ -36,7 +38,7 @@ export interface QueryFn {
 }
 
 /**
- * Common interface for Database and Queue.
+ * Common interface for Database, Feed, and Hypergraph.
  */
 export interface Queryable {
   query: QueryFn;
@@ -69,7 +71,7 @@ export type FlushOptions = {
 
   /**
    * Wait for pending index updates.
-   * @default false
+   * @default true
    */
   indexes?: boolean;
 
@@ -227,24 +229,28 @@ export const resolve: {
     }
     invariant(!schema || isInstanceOf(schema, object), 'Object type mismatch.');
     return object as any;
-  })) as any;
+  }).pipe(Effect.withSpan('Database.resolve'))) as any;
 
 /**
  * Loads an object reference.
  */
-export const load: <T>(ref: Ref<T>) => Effect.Effect<T, Err.ObjectNotFoundError, never> = Effect.fn(function* (ref) {
-  const object = yield* promiseWithCauseCapture(() => ref.tryLoad());
-  if (!object) {
-    return yield* Effect.fail(new Err.ObjectNotFoundError(ref.dxn));
-  }
-  return object;
-});
+export const load: <T>(ref: Ref<T>) => Effect.Effect<T, Err.ObjectNotFoundError, never> = Effect.fn('Database.load')(
+  function* (ref) {
+    const object = yield* promiseWithCauseCapture(() => ref.tryLoad());
+    if (!object) {
+      return yield* Effect.fail(new Err.ObjectNotFoundError(ref.dxn));
+    }
+    return object;
+  },
+);
 
 /**
  * Loads an object reference option.
  */
 // TODO(dmaretskyi): Do we need this -- you can just use `Effect.catchTag` in calling code instead.
-export const loadOption: <T>(ref: Ref<T>) => Effect.Effect<Option.Option<T>, never, never> = Effect.fn(function* (ref) {
+export const loadOption: <T>(ref: Ref<T>) => Effect.Effect<Option.Option<T>, never, never> = Effect.fn(
+  'Database.loadOption',
+)(function* (ref) {
   const object = yield* load(ref).pipe(Effect.catchTag('ObjectNotFoundError', () => Effect.succeed(undefined)));
 
   return Option.fromNullable(object);
@@ -255,21 +261,23 @@ export const loadOption: <T>(ref: Ref<T>) => Effect.Effect<Option.Option<T>, nev
  * @see {@link Database.add}
  */
 export const add = <T extends Entity.Unknown>(obj: T): Effect.Effect<T, never, Service> =>
-  Service.pipe(Effect.map(({ db }) => db.add(obj)));
+  Service.pipe(Effect.map(({ db }) => db.add(obj))).pipe(Effect.withSpan('Database.add'));
 
 /**
  * Removes an object from the database.
  * @see {@link Database.remove}
  */
 export const remove = <T extends Entity.Unknown>(obj: T): Effect.Effect<void, never, Service> =>
-  Service.pipe(Effect.map(({ db }) => db.remove(obj)));
+  Service.pipe(Effect.map(({ db }) => db.remove(obj))).pipe(Effect.withSpan('Database.remove'));
 
 /**
  * Flushes pending changes to disk.
  * @see {@link Database.flush}
  */
 export const flush = (opts?: FlushOptions) =>
-  Service.pipe(Effect.flatMap(({ db }) => promiseWithCauseCapture(() => db.flush(opts))));
+  Service.pipe(Effect.flatMap(({ db }) => promiseWithCauseCapture(() => db.flush(opts)))).pipe(
+    Effect.withSpan('Database.flush'),
+  );
 
 /**
  * Creates a `QueryResult` object that can be subscribed to.
@@ -290,7 +298,36 @@ export const runQuery: {
   <Q extends Query.Any>(query: Q): Effect.Effect<Query.Type<Q>[], never, Service>;
   <F extends Filter.Any>(filter: F): Effect.Effect<Filter.Type<F>[], never, Service>;
 } = (queryOrFilter: Query.Any | Filter.Any) =>
-  query(queryOrFilter as any).pipe(Effect.flatMap((queryResult) => promiseWithCauseCapture(() => queryResult.run())));
+  query(queryOrFilter as any).pipe(
+    Effect.flatMap((queryResult) => promiseWithCauseCapture(() => queryResult.run())),
+    Effect.withSpan('Database.runQuery'),
+  );
+
+/**
+ * Executes the query once and returns the first result as or None.
+ */
+export const runQueryFirst: {
+  <Q extends Query.Any>(query: Q): Effect.Effect<Option.Option<Query.Type<Q>>, never, Service>;
+  <F extends Filter.Any>(filter: F): Effect.Effect<Option.Option<Filter.Type<F>>, never, Service>;
+} = (queryOrFilter: Query.Any | Filter.Any) =>
+  query(queryOrFilter as any).pipe(
+    Effect.flatMap((queryResult) =>
+      promiseWithCauseCapture(async () => Option.fromNullable(await queryResult.firstOrUndefined())),
+    ),
+    Effect.withSpan('Database.runQueryFirst'),
+  );
+
+/**
+ * Persists schemas in the database so they replicate to other clients.
+ * @see {@link SchemaRegistry.SchemaRegistry.register}
+ */
+export const registerSchema = (
+  input: SchemaRegistry.RegisterSchemaInput[],
+): Effect.Effect<Type.RuntimeType[], never, Service> =>
+  Service.pipe(
+    Effect.flatMap(({ db }) => promiseWithCauseCapture(() => db.schemaRegistry.register(input))),
+    Effect.withSpan('Database.registerSchema'),
+  );
 
 /**
  * Creates a schema query result that can be subscribed to.

package/src/Dataset.ts

@@ -2,6 +2,8 @@
 // Copyright 2026 DXOS.org
 //
 
+// @import-as-namespace
+
 import { pipe } from 'effect/Function';
 import * as Predicate from 'effect/Predicate';
 import * as Schema from 'effect/Schema';

package/src/Entity.ts

@@ -2,11 +2,14 @@
 // Copyright 2025 DXOS.org
 //
 
+// @import-as-namespace
+
 import type { ForeignKey } from '@dxos/echo-protocol';
 import type { DXN, ObjectId } from '@dxos/keys';
 
 import * as internal from './internal';
 import type * as Relation from './Relation';
+import type * as Type from './Type';
 
 // Re-export KindId and SnapshotKindId from internal.
 export const KindId = internal.KindId;
@@ -129,6 +132,12 @@ export const getDXN = (entity: Unknown | Snapshot): DXN => internal.getDXN(entit
  */
 export const getTypeDXN = internal.getTypeDXN;
 
+/**
+ * Get the schema of an entity.
+ * Returns the branded ECHO schema used to create the entity.
+ */
+export const getSchema: (entity: Unknown | Snapshot) => Type.AnyEntity | undefined = internal.getSchema as any;
+
 /**
  * Get the typename of an entity's type.
  */
@@ -189,7 +198,7 @@ export const subscribe = (entity: Unknown, callback: () => void): (() => void) =
 //
 
 /**
- * Used to provide a mutable view of an entity within `Entity.change`.
+ * Used to provide a mutable view of an entity within `Entity.update`.
  */
 export type Mutable<T> = internal.Mutable<T>;
 
@@ -197,7 +206,7 @@ export type Mutable<T> = internal.Mutable<T>;
  * Perform mutations on an entity (object or relation) within a change context.
  *
  * Entities are read-only by default. Mutations are batched and notifications fire
- * when the callback completes. Direct mutations outside of `Entity.change` will throw
+ * when the callback completes. Direct mutations outside of `Entity.update` will throw
  * at runtime.
  *
  * @param entity - The echo entity (object or relation) to mutate.
@@ -205,30 +214,30 @@ export type Mutable<T> = internal.Mutable<T>;
  *
  * @example
  * ```typescript
- * // Mutate within Entity.change
- * Entity.change(entity, (e) => {
- *   e.name = 'Updated';
- *   e.count = 42;
+ * // Mutate within Entity.update
+ * Entity.update(entity, (obj) => {
+ *   obj.name = 'Updated';
+ *   obj.count = 42;
  * });
  *
  * // Direct mutation throws
- * entity.name = 'Bob'; // Error: Cannot modify outside Entity.change()
+ * entity.name = 'Bob'; // Error: Cannot modify outside Entity.update()
  * ```
  *
- * Note: For type-specific operations, prefer `Obj.change` or `Relation.change`.
+ * Note: For type-specific operations, prefer `Obj.update` or `Relation.update`.
  */
-export const change = <T extends Unknown>(entity: T, callback: internal.ChangeCallback<T>): void => {
+export const update = <T extends Unknown>(entity: T, callback: internal.ChangeCallback<T>): void => {
   internal.change(entity, callback);
 };
 
 /**
  * Add a tag to an entity.
- * Must be called within an `Entity.change`, `Obj.change`, or `Relation.change` callback.
+ * Must be called within an `Entity.update`, `Obj.update`, or `Relation.update` callback.
  */
 export const addTag = (entity: Mutable<Unknown>, tag: string): void => internal.addTag(entity, tag);
 
 /**
  * Remove a tag from an entity.
- * Must be called within an `Entity.change`, `Obj.change`, or `Relation.change` callback.
+ * Must be called within an `Entity.update`, `Obj.update`, or `Relation.update` callback.
  */
 export const removeTag = (entity: Mutable<Unknown>, tag: string): void => internal.removeTag(entity, tag);

package/src/Err.ts

@@ -2,6 +2,8 @@
 // Copyright 2025 DXOS.org
 //
 
+// @import-as-namespace
+
 import { BaseError, type BaseErrorOptions } from '@dxos/errors';
 import { type DXN } from '@dxos/keys';
 

package/src/Extension.test.ts

@@ -0,0 +1,235 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Option from 'effect/Option';
+import * as Schema from 'effect/Schema';
+import { describe, test } from 'vitest';
+
+import * as Extension from './Extension';
+
+describe('Extension', () => {
+  describe('make', () => {
+    test('creates an extension with a string schema', ({ expect }) => {
+      const ColorExtension = Extension.make('color', Schema.String);
+
+      expect(ColorExtension.key).toBe('color');
+      expect(ColorExtension.valueSchema).toBe(Schema.String);
+      expect(ColorExtension[Extension.TypeId]).toBeDefined();
+    });
+
+    test('creates an extension with a number schema', ({ expect }) => {
+      const PriorityExtension = Extension.make('priority', Schema.Number);
+
+      expect(PriorityExtension.key).toBe('priority');
+      expect(PriorityExtension.valueSchema).toBe(Schema.Number);
+    });
+
+    test('creates an extension with a complex schema', ({ expect }) => {
+      const MetadataSchema = Schema.Struct({
+        author: Schema.String,
+        version: Schema.Number,
+        tags: Schema.Array(Schema.String),
+      });
+      const MetadataExtension = Extension.make('metadata', MetadataSchema);
+
+      expect(MetadataExtension.key).toBe('metadata');
+      expect(MetadataExtension.valueSchema).toBe(MetadataSchema);
+    });
+  });
+
+  describe('get and set', () => {
+    test('set and get a string value', ({ expect }) => {
+      const ColorExtension = Extension.make('color', Schema.String);
+      const values: Extension.Values = {};
+
+      Extension.set(values, ColorExtension, 'red');
+      const result = Extension.get(values, ColorExtension);
+
+      expect(Option.isSome(result)).toBe(true);
+      expect(Option.getOrThrow(result)).toBe('red');
+    });
+
+    test('set and get a number value', ({ expect }) => {
+      const PriorityExtension = Extension.make('priority', Schema.Number);
+      const values: Extension.Values = {};
+
+      Extension.set(values, PriorityExtension, 42);
+      const result = Extension.get(values, PriorityExtension);
+
+      expect(Option.isSome(result)).toBe(true);
+      expect(Option.getOrThrow(result)).toBe(42);
+    });
+
+    test('set and get a boolean value', ({ expect }) => {
+      const EnabledExtension = Extension.make('enabled', Schema.Boolean);
+      const values: Extension.Values = {};
+
+      Extension.set(values, EnabledExtension, true);
+      const result = Extension.get(values, EnabledExtension);
+
+      expect(Option.isSome(result)).toBe(true);
+      expect(Option.getOrThrow(result)).toBe(true);
+    });
+
+    test('set and get a complex object value', ({ expect }) => {
+      const ConfigSchema = Schema.Struct({
+        theme: Schema.String,
+        fontSize: Schema.Number,
+        darkMode: Schema.Boolean,
+      });
+      const ConfigExtension = Extension.make('config', ConfigSchema);
+      const values: Extension.Values = {};
+
+      const config = { theme: 'modern', fontSize: 14, darkMode: true };
+      Extension.set(values, ConfigExtension, config);
+      const result = Extension.get(values, ConfigExtension);
+
+      expect(Option.isSome(result)).toBe(true);
+      expect(Option.getOrThrow(result)).toEqual(config);
+    });
+
+    test('set and get an array value', ({ expect }) => {
+      const TagsExtension = Extension.make('tags', Schema.Array(Schema.String));
+      const values: Extension.Values = {};
+
+      const tags = ['important', 'urgent', 'review'];
+      Extension.set(values, TagsExtension, tags);
+      const result = Extension.get(values, TagsExtension);
+
+      expect(Option.isSome(result)).toBe(true);
+      expect(Option.getOrThrow(result)).toEqual(tags);
+    });
+
+    test('get returns None for missing extension', ({ expect }) => {
+      const ColorExtension = Extension.make('color', Schema.String);
+      const values: Extension.Values = {};
+
+      const result = Extension.get(values, ColorExtension);
+
+      expect(Option.isNone(result)).toBe(true);
+    });
+
+    test('overwriting an extension value', ({ expect }) => {
+      const ColorExtension = Extension.make('color', Schema.String);
+      const values: Extension.Values = {};
+
+      Extension.set(values, ColorExtension, 'red');
+      Extension.set(values, ColorExtension, 'blue');
+      const result = Extension.get(values, ColorExtension);
+
+      expect(Option.isSome(result)).toBe(true);
+      expect(Option.getOrThrow(result)).toBe('blue');
+    });
+
+    test('multiple extensions on the same values object', ({ expect }) => {
+      const ColorExtension = Extension.make('color', Schema.String);
+      const PriorityExtension = Extension.make('priority', Schema.Number);
+      const EnabledExtension = Extension.make('enabled', Schema.Boolean);
+      const values: Extension.Values = {};
+
+      Extension.set(values, ColorExtension, 'green');
+      Extension.set(values, PriorityExtension, 5);
+      Extension.set(values, EnabledExtension, false);
+
+      expect(Option.getOrThrow(Extension.get(values, ColorExtension))).toBe('green');
+      expect(Option.getOrThrow(Extension.get(values, PriorityExtension))).toBe(5);
+      expect(Option.getOrThrow(Extension.get(values, EnabledExtension))).toBe(false);
+    });
+  });
+
+  describe('curried forms', () => {
+    test('get curried form', ({ expect }) => {
+      const ColorExtension = Extension.make('color', Schema.String);
+      const values: Extension.Values = {};
+      Extension.set(values, ColorExtension, 'purple');
+
+      const getColor = Extension.get(ColorExtension);
+      const result = getColor(values);
+
+      expect(Option.isSome(result)).toBe(true);
+      expect(Option.getOrThrow(result)).toBe('purple');
+    });
+
+    test('set curried form', ({ expect }) => {
+      const ColorExtension = Extension.make('color', Schema.String);
+      const values: Extension.Values = {};
+
+      const setOrange = Extension.set(ColorExtension, 'orange');
+      setOrange(values);
+      const result = Extension.get(values, ColorExtension);
+
+      expect(Option.isSome(result)).toBe(true);
+      expect(Option.getOrThrow(result)).toBe('orange');
+    });
+
+    test('curried forms work in pipelines', ({ expect }) => {
+      const ColorExtension = Extension.make('color', Schema.String);
+      const values: Extension.Values = {};
+
+      Extension.set(ColorExtension, 'cyan')(values);
+      const result = Extension.get(ColorExtension)(values);
+
+      expect(Option.isSome(result)).toBe(true);
+      expect(Option.getOrThrow(result)).toBe('cyan');
+    });
+  });
+
+  describe('Key', () => {
+    test('Key.make creates a branded key', ({ expect }) => {
+      const key = Extension.Key.make('my-extension');
+
+      expect(key).toBe('my-extension');
+      expect(typeof key).toBe('string');
+    });
+  });
+
+  describe('Values schema', () => {
+    test('Values can be used as a schema', ({ expect }) => {
+      const PersonWithExtensions = Schema.Struct({
+        name: Schema.String,
+        extensions: Extension.Values,
+      });
+
+      const person = Schema.decodeUnknownSync(PersonWithExtensions)({
+        name: 'Alice',
+        extensions: {},
+      });
+
+      expect(person.name).toBe('Alice');
+      expect(person.extensions).toEqual({});
+    });
+
+    test('Values schema accepts extension data', ({ expect }) => {
+      const ColorExtension = Extension.make('color', Schema.String);
+      const values: Extension.Values = {};
+      Extension.set(values, ColorExtension, 'red');
+
+      const PersonWithExtensions = Schema.Struct({
+        name: Schema.String,
+        extensions: Extension.Values,
+      });
+
+      const person = Schema.decodeUnknownSync(PersonWithExtensions)({
+        name: 'Bob',
+        extensions: values,
+      });
+
+      expect(person.name).toBe('Bob');
+      const color = Extension.get(person.extensions, ColorExtension);
+      expect(Option.getOrThrow(color)).toBe('red');
+    });
+  });
+
+  describe('TypeId', () => {
+    test('TypeId is a unique symbol-like string', ({ expect }) => {
+      expect(Extension.TypeId).toBe('~@dxos/echo/Extension');
+    });
+
+    test('extensions have TypeId property', ({ expect }) => {
+      const ColorExtension = Extension.make('color', Schema.String);
+
+      expect(Extension.TypeId in ColorExtension).toBe(true);
+    });
+  });
+});