@dxos/echo 0.8.4-main.84f28bd → 0.8.4-main.937b3ca

package/package.json

@@ -1,62 +1,195 @@
 {
   "name": "@dxos/echo",
-  "version": "0.8.4-main.84f28bd",
+  "version": "0.8.4-main.937b3ca",
   "description": "ECHO API",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dxos/dxos"
+  },
   "license": "MIT",
   "author": "info@dxos.org",
-  "sideEffects": true,
+  "sideEffects": false,
   "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"
     },
-    "./Type": {
-      "types": "./dist/types/src/Type.d.ts",
-      "browser": "./dist/lib/browser/Type.mjs",
-      "node": "./dist/lib/node-esm/Type.mjs"
+    "./internal": {
+      "source": "./src/internal/index.ts",
+      "types": "./dist/types/src/internal/index.d.ts",
+      "browser": "./dist/lib/browser/internal/index.mjs",
+      "node": "./dist/lib/node-esm/internal/index.mjs"
+    },
+    "./testing": {
+      "source": "./src/testing/index.ts",
+      "types": "./dist/types/src/testing/index.d.ts",
+      "browser": "./dist/lib/browser/testing/index.mjs",
+      "node": "./dist/lib/node-esm/testing/index.mjs"
+    },
+    "./Annotation": {
+      "source": "./src/Annotation.ts",
+      "types": "./dist/types/src/Annotation.d.ts",
+      "browser": "./dist/lib/browser/Annotation.mjs",
+      "node": "./dist/lib/node-esm/Annotation.mjs"
+    },
+    "./Database": {
+      "source": "./src/Database.ts",
+      "types": "./dist/types/src/Database.d.ts",
+      "browser": "./dist/lib/browser/Database.mjs",
+      "node": "./dist/lib/node-esm/Database.mjs"
+    },
+    "./Entity": {
+      "source": "./src/Entity.ts",
+      "types": "./dist/types/src/Entity.d.ts",
+      "browser": "./dist/lib/browser/Entity.mjs",
+      "node": "./dist/lib/node-esm/Entity.mjs"
+    },
+    "./Err": {
+      "source": "./src/Err.ts",
+      "types": "./dist/types/src/Err.d.ts",
+      "browser": "./dist/lib/browser/Err.mjs",
+      "node": "./dist/lib/node-esm/Err.mjs"
+    },
+    "./Filter": {
+      "source": "./src/Filter.ts",
+      "types": "./dist/types/src/Filter.d.ts",
+      "browser": "./dist/lib/browser/Filter.mjs",
+      "node": "./dist/lib/node-esm/Filter.mjs"
+    },
+    "./Format": {
+      "source": "./src/Format.ts",
+      "types": "./dist/types/src/Format.d.ts",
+      "browser": "./dist/lib/browser/Format.mjs",
+      "node": "./dist/lib/node-esm/Format.mjs"
+    },
+    "./JsonSchema": {
+      "source": "./src/JsonSchema.ts",
+      "types": "./dist/types/src/JsonSchema.d.ts",
+      "browser": "./dist/lib/browser/JsonSchema.mjs",
+      "node": "./dist/lib/node-esm/JsonSchema.mjs"
+    },
+    "./Key": {
+      "source": "./src/Key.ts",
+      "types": "./dist/types/src/Key.d.ts",
+      "browser": "./dist/lib/browser/Key.mjs",
+      "node": "./dist/lib/node-esm/Key.mjs"
     },
     "./Obj": {
+      "source": "./src/Obj.ts",
       "types": "./dist/types/src/Obj.d.ts",
       "browser": "./dist/lib/browser/Obj.mjs",
       "node": "./dist/lib/node-esm/Obj.mjs"
     },
-    "./Relation": {
-      "types": "./dist/types/src/Relation.d.ts",
-      "browser": "./dist/lib/browser/Relation.mjs",
-      "node": "./dist/lib/node-esm/Relation.mjs"
+    "./Order": {
+      "source": "./src/Order.ts",
+      "types": "./dist/types/src/Order.d.ts",
+      "browser": "./dist/lib/browser/Order.mjs",
+      "node": "./dist/lib/node-esm/Order.mjs"
+    },
+    "./Query": {
+      "source": "./src/Query.ts",
+      "types": "./dist/types/src/Query.d.ts",
+      "browser": "./dist/lib/browser/Query.mjs",
+      "node": "./dist/lib/node-esm/Query.mjs"
+    },
+    "./QueryResult": {
+      "source": "./src/QueryResult.ts",
+      "types": "./dist/types/src/QueryResult.d.ts",
+      "browser": "./dist/lib/browser/QueryResult.mjs",
+      "node": "./dist/lib/node-esm/QueryResult.mjs"
     },
     "./Ref": {
+      "source": "./src/Ref.ts",
       "types": "./dist/types/src/Ref.d.ts",
       "browser": "./dist/lib/browser/Ref.mjs",
       "node": "./dist/lib/node-esm/Ref.mjs"
     },
-    "./testing": {
-      "types": "./dist/types/src/testing/types.d.ts",
-      "browser": "./dist/lib/browser/testing/index.mjs",
-      "node": "./dist/lib/node-esm/testing/index.mjs"
+    "./Relation": {
+      "source": "./src/Relation.ts",
+      "types": "./dist/types/src/Relation.d.ts",
+      "browser": "./dist/lib/browser/Relation.mjs",
+      "node": "./dist/lib/node-esm/Relation.mjs"
+    },
+    "./SchemaRegistry": {
+      "source": "./src/SchemaRegistry.ts",
+      "types": "./dist/types/src/SchemaRegistry.d.ts",
+      "browser": "./dist/lib/browser/SchemaRegistry.mjs",
+      "node": "./dist/lib/node-esm/SchemaRegistry.mjs"
+    },
+    "./Tag": {
+      "source": "./src/Tag.ts",
+      "types": "./dist/types/src/Tag.d.ts",
+      "browser": "./dist/lib/browser/Tag.mjs",
+      "node": "./dist/lib/node-esm/Tag.mjs"
+    },
+    "./Type": {
+      "source": "./src/Type.ts",
+      "types": "./dist/types/src/Type.d.ts",
+      "browser": "./dist/lib/browser/Type.mjs",
+      "node": "./dist/lib/node-esm/Type.mjs"
     }
   },
   "types": "dist/types/src/index.d.ts",
   "typesVersions": {
     "*": {
-      "Type": [
-        "dist/types/src/Type.d.ts"
+      "internal": [
+        "dist/types/src/internal/index.d.ts"
+      ],
+      "testing": [
+        "dist/types/src/testing/index.d.ts"
+      ],
+      "Annotation": [
+        "dist/types/src/Annotation.d.ts"
+      ],
+      "Database": [
+        "dist/types/src/Database.d.ts"
+      ],
+      "Entity": [
+        "dist/types/src/Entity.d.ts"
+      ],
+      "Err": [
+        "dist/types/src/Err.d.ts"
+      ],
+      "Filter": [
+        "dist/types/src/Filter.d.ts"
+      ],
+      "Format": [
+        "dist/types/src/Format.d.ts"
+      ],
+      "JsonSchema": [
+        "dist/types/src/JsonSchema.d.ts"
+      ],
+      "Key": [
+        "dist/types/src/Key.d.ts"
       ],
       "Obj": [
         "dist/types/src/Obj.d.ts"
       ],
-      "Relation": [
-        "dist/types/src/Relation.d.ts"
+      "Order": [
+        "dist/types/src/Order.d.ts"
+      ],
+      "Query": [
+        "dist/types/src/Query.d.ts"
+      ],
+      "QueryResult": [
+        "dist/types/src/QueryResult.d.ts"
       ],
       "Ref": [
         "dist/types/src/Ref.d.ts"
       ],
-      "testing": [
-        "dist/types/src/testing/index.d.ts"
+      "Relation": [
+        "dist/types/src/Relation.d.ts"
+      ],
+      "Tag": [
+        "dist/types/src/Tag.d.ts"
+      ],
+      "Type": [
+        "dist/types/src/Type.d.ts"
       ]
     }
   },
@@ -65,19 +198,19 @@
     "src"
   ],
   "dependencies": {
-    "@preact/signals-core": "^1.9.0",
-    "effect": "3.16.13",
-    "@dxos/debug": "0.8.4-main.84f28bd",
-    "@dxos/echo-schema": "0.8.4-main.84f28bd",
-    "@dxos/echo-protocol": "0.8.4-main.84f28bd",
-    "@dxos/echo-signals": "0.8.4-main.84f28bd",
-    "@dxos/effect": "0.8.4-main.84f28bd",
-    "@dxos/invariant": "0.8.4-main.84f28bd",
-    "@dxos/keys": "0.8.4-main.84f28bd",
-    "@dxos/live-object": "0.8.4-main.84f28bd",
-    "@dxos/log": "0.8.4-main.84f28bd",
-    "@dxos/node-std": "0.8.4-main.84f28bd",
-    "@dxos/util": "0.8.4-main.84f28bd"
+    "effect": "3.19.11",
+    "@dxos/context": "0.8.4-main.937b3ca",
+    "@dxos/debug": "0.8.4-main.937b3ca",
+    "@dxos/async": "0.8.4-main.937b3ca",
+    "@dxos/echo-protocol": "0.8.4-main.937b3ca",
+    "@dxos/effect": "0.8.4-main.937b3ca",
+    "@dxos/errors": "0.8.4-main.937b3ca",
+    "@dxos/invariant": "0.8.4-main.937b3ca",
+    "@dxos/keys": "0.8.4-main.937b3ca",
+    "@dxos/log": "0.8.4-main.937b3ca",
+    "@dxos/node-std": "0.8.4-main.937b3ca",
+    "@dxos/protocols": "0.8.4-main.937b3ca",
+    "@dxos/util": "0.8.4-main.937b3ca"
   },
   "publishConfig": {
     "access": "public"

package/src/Annotation.ts

@@ -0,0 +1,18 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export {
+  DescriptionAnnotation,
+  FormInputAnnotation,
+  GeneratorAnnotation,
+  LabelAnnotation,
+  ReferenceAnnotation,
+  SystemTypeAnnotation,
+  TypeAnnotation,
+  getDescriptionWithSchema,
+  getLabelWithSchema,
+  getTypeAnnotation,
+  setDescriptionWithSchema,
+  setLabelWithSchema,
+} from './internal/annotations';

package/src/Database.ts

@@ -0,0 +1,336 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Context from 'effect/Context';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import * as Option from 'effect/Option';
+import * as Schema from 'effect/Schema';
+import type * as Types from 'effect/Types';
+
+import { type QueryAST } from '@dxos/echo-protocol';
+import { promiseWithCauseCapture } from '@dxos/effect';
+import { invariant } from '@dxos/invariant';
+import { DXN, type PublicKey, type SpaceId } from '@dxos/keys';
+import { type QueryOptions as QueryOptionsProto } from '@dxos/protocols/proto/dxos/echo/filter';
+
+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 type * as Obj from './Obj';
+import type * as Query from './Query';
+import type * as QueryResult from './QueryResult';
+import type * as SchemaRegistry from './SchemaRegistry';
+import type * as Type from './Type';
+
+/**
+ * @deprecated Use `QueryAST.QueryOptions` instead.
+ */
+export type QueryOptions = {
+  /**
+   * @deprecated Use `spaceIds` instead.
+   */
+  spaces?: PublicKey[];
+
+  /**
+   * Query only in specific spaces.
+   */
+  // TODO(dmaretskyi): Change this to SpaceId.
+  spaceIds?: string[];
+
+  /**
+   * Return only the first `limit` results.
+   */
+  limit?: number;
+
+  /**
+   * Query only local spaces, or remote on agent.
+   * @default `QueryOptions.DataLocation.LOCAL`
+   *
+   * Options:
+   *   - proto3_optional = true
+   */
+  // TODO(burdon): Remove?
+  dataLocation?: QueryOptionsProto.DataLocation;
+};
+
+/**
+ * `query` API function declaration.
+ */
+// TODO(burdon): Reconcile Query and Filter (should only have one root type).
+// TODO(dmaretskyi): Remove query options.
+export interface QueryFn {
+  <Q extends Query.Any>(
+    query: Q,
+    options?: (QueryAST.QueryOptions & QueryOptions) | undefined,
+  ): QueryResult.QueryResult<Query.Type<Q>>;
+
+  <F extends Filter.Any>(
+    filter: F,
+    options?: (QueryAST.QueryOptions & QueryOptions) | undefined,
+  ): QueryResult.QueryResult<Filter.Type<F>>;
+}
+
+/**
+ * Common interface for Database and Queue.
+ */
+export interface Queryable {
+  query: QueryFn;
+}
+
+export type GetObjectByIdOptions = {
+  deleted?: boolean;
+};
+
+export type ObjectPlacement = 'root-doc' | 'linked-doc';
+
+export type AddOptions = {
+  /**
+   * Where to place the object in the Automerge document tree.
+   * Root document is always loaded with the space.
+   * Linked documents are loaded lazily.
+   * Placing large number of objects in the root document may slow down the initial load.
+   *
+   * @default 'linked-doc'
+   */
+  placeIn?: ObjectPlacement;
+};
+
+export type FlushOptions = {
+  /**
+   * Write any pending changes to disk.
+   * @default true
+   */
+  disk?: boolean;
+
+  /**
+   * Wait for pending index updates.
+   * @default false
+   */
+  indexes?: boolean;
+
+  /**
+   * Flush pending updates to objects and queries.
+   * @default false
+   */
+  updates?: boolean;
+};
+
+/**
+ * Identifier denoting an ECHO Database.
+ */
+export const TypeId = Symbol.for('@dxos/echo/Database');
+export type TypeId = typeof TypeId;
+
+/**
+ * ECHO Database interface.
+ */
+export interface Database extends Queryable {
+  readonly [TypeId]: TypeId;
+
+  get spaceId(): SpaceId;
+
+  // TODO(burdon): Can we move this into graph?
+  get schemaRegistry(): SchemaRegistry.SchemaRegistry;
+
+  get graph(): Hypergraph.Hypergraph;
+
+  toJSON(): object;
+
+  /**
+   * Return object by local ID.
+   */
+  getObjectById<T extends Obj.Unknown = Obj.Obj<AnyProperties>>(id: string, opts?: GetObjectByIdOptions): T | undefined;
+
+  /**
+   * Query objects.
+   */
+  query: QueryFn;
+
+  /**
+   * Creates a reference to an existing object in the database.
+   *
+   * NOTE: The reference may be dangling if the object is not present in the database.
+   * NOTE: Difference from `Ref.fromDXN`
+   * `Ref.fromDXN(dxn)` returns an unhydrated reference. The `.load` and `.target` APIs will not work.
+   * `db.makeRef(dxn)` is preferable in cases with access to the database.
+   */
+  makeRef<T extends Entity.Unknown = Entity.Unknown>(dxn: DXN): Ref<T>;
+
+  /**
+   * Adds object to the database.
+   */
+  add<T extends Entity.Unknown = Entity.Unknown>(obj: T, opts?: AddOptions): T;
+
+  /**
+   * Removes object from the database.
+   */
+  // TODO(burdon): Return true if removed (currently throws if not present).
+  remove(obj: Entity.Unknown): void;
+
+  /**
+   * Wait for all pending changes to be saved to disk.
+   * Optionaly waits for changes to be propagated to indexes and event handlers.
+   */
+  flush(opts?: FlushOptions): Promise<void>;
+}
+
+export const isDatabase = (obj: unknown): obj is Database => {
+  return obj ? typeof obj === 'object' && TypeId in obj && obj[TypeId] === TypeId : false;
+};
+
+export const Database: Schema.Schema<Database> = Schema.Any.pipe(Schema.filter((space) => isDatabase(space)));
+
+export class Service extends Context.Tag('@dxos/echo/Database/Service')<
+  Service,
+  {
+    readonly db: Database;
+  }
+>() {
+  static notAvailable = Layer.succeed(Service, {
+    get db(): Database {
+      throw new Error('Database not available');
+    },
+  });
+
+  static make = (db: Database): Context.Tag.Service<Service> => {
+    return {
+      get db() {
+        return db;
+      },
+    };
+  };
+
+  static layer = (db: Database): Layer.Layer<Service> => {
+    return Layer.succeed(Service, Service.make(db));
+  };
+
+  // TODO(dmaretskyi): Move all those to the top-level API of Database.ts module.
+
+  /**
+   * Returns the space ID of the database.
+   */
+  static spaceId = Effect.gen(function* () {
+    const { db } = yield* Service;
+    return db.spaceId;
+  });
+
+  /**
+   * Resolves an object by its DXN.
+   */
+  static resolve: {
+    // No type check.
+    (ref: DXN | Ref<any>): Effect.Effect<Entity.Unknown, never, Service>;
+    // Check matches schema.
+    <S extends Type.Entity.Any>(
+      ref: DXN | Ref<any>,
+      schema: S,
+    ): Effect.Effect<Schema.Schema.Type<S>, Err.ObjectNotFoundError, Service>;
+  } = (<S extends Type.Entity.Any>(
+    ref: DXN | Ref<any>,
+    schema?: S,
+  ): Effect.Effect<Schema.Schema.Type<S>, Err.ObjectNotFoundError, Service> =>
+    Effect.gen(function* () {
+      const { db } = yield* Service;
+      const dxn = ref instanceof DXN ? ref : ref.dxn;
+      const object = yield* promiseWithCauseCapture(() =>
+        db.graph
+          .createRefResolver({
+            context: {
+              space: db.spaceId,
+            },
+          })
+          .resolve(dxn),
+      );
+
+      if (!object) {
+        return yield* Effect.fail(new Err.ObjectNotFoundError(dxn));
+      }
+      invariant(!schema || isInstanceOf(schema, object), 'Object type mismatch.');
+      return object as any;
+    })) as any;
+
+  /**
+   * Loads an object reference.
+   */
+  static 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;
+  });
+
+  /**
+   * Loads an object reference option.
+   */
+  // TODO(dmaretskyi): Do we need this -- you can just use `Effect.catchTag` in calling code instead.
+  static loadOption: <T>(ref: Ref<T>) => Effect.Effect<Option.Option<T>, never, never> = Effect.fn(function* (ref) {
+    const object = yield* Service.load(ref).pipe(
+      Effect.catchTag('ObjectNotFoundError', () => Effect.succeed(undefined)),
+    );
+
+    return Option.fromNullable(object);
+  });
+
+  /**
+   * @link EchoDatabase.add
+   */
+  static add = <T extends Entity.Unknown>(obj: T): Effect.Effect<T, never, Service> =>
+    Service.pipe(Effect.map(({ db }) => db.add(obj)));
+
+  /**
+   * @link EchoDatabase.remove
+   */
+  static remove = <T extends Entity.Unknown>(obj: T): Effect.Effect<void, never, Service> =>
+    Service.pipe(Effect.map(({ db }) => db.remove(obj)));
+
+  /**
+   * @link EchoDatabase.flush
+   */
+  static flush = (opts?: FlushOptions) =>
+    Service.pipe(Effect.flatMap(({ db }) => promiseWithCauseCapture(() => db.flush(opts))));
+
+  /**
+   * Creates a `QueryResult` object that can be subscribed to.
+   */
+  static query: {
+    <Q extends Query.Any>(query: Q): Effect.Effect<QueryResult.QueryResult<Query.Type<Q>>, never, Service>;
+    <F extends Filter.Any>(filter: F): Effect.Effect<QueryResult.QueryResult<Filter.Type<F>>, never, Service>;
+  } = (queryOrFilter: Query.Any | Filter.Any) =>
+    Service.pipe(
+      Effect.map(({ db }) => db.query(queryOrFilter as any) as QueryResult.QueryResult<any>),
+      Effect.withSpan('Service.query'),
+    );
+
+  /**
+   * Executes the query once and returns the results.
+   */
+  static 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) =>
+    Service.query(queryOrFilter as any).pipe(
+      Effect.flatMap((queryResult) => promiseWithCauseCapture(() => queryResult.run())),
+    );
+
+  // TODO(dmaretskyi): Change API to `yield* Service.querySchema(...).first` and `yield* Service.querySchema(...).schema`.
+
+  static schemaQuery = <Q extends Types.NoExcessProperties<SchemaRegistry.Query, Q>>(
+    query?: Q & SchemaRegistry.Query,
+  ): Effect.Effect<QueryResult.QueryResult<SchemaRegistry.ExtractQueryResult<Q>>, never, Service> =>
+    Service.pipe(
+      Effect.map(({ db }) => db.schemaRegistry.query(query)),
+      Effect.withSpan('Service.schemaQuery'),
+    );
+
+  static runSchemaQuery = <Q extends Types.NoExcessProperties<SchemaRegistry.Query, Q>>(
+    query?: Q & SchemaRegistry.Query,
+  ): Effect.Effect<SchemaRegistry.ExtractQueryResult<Q>[], never, Service> =>
+    Service.schemaQuery(query).pipe(Effect.flatMap((queryResult) => promiseWithCauseCapture(() => queryResult.run())));
+}

package/src/Entity.test.ts

@@ -0,0 +1,22 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, expect, test } from 'vitest';
+
+import type * as Entity from './Entity';
+import * as Obj from './Obj';
+import * as Relation from './Relation';
+import { TestSchema } from './testing';
+
+describe('Entity', () => {
+  test('Entity.Unknown accepts any object or relation', () => {
+    const obj = Obj.make(TestSchema.Person, { name: 'Test' });
+    const rel = Relation.make(TestSchema.HasManager, { [Relation.Source]: obj, [Relation.Target]: obj });
+    const doSomething = (entity: Entity.Unknown) => {
+      return entity;
+    };
+    expect(doSomething(obj)).toBe(obj);
+    expect(doSomething(rel)).toBe(rel);
+  });
+});