@dxos/echo 0.8.4-main.66e292d → 0.8.4-main.69d29f4

package/package.json

@@ -1,9 +1,13 @@
 {
   "name": "@dxos/echo",
-  "version": "0.8.4-main.66e292d",
+  "version": "0.8.4-main.69d29f4",
   "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": false,
@@ -27,23 +31,77 @@
       "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": {
-      "source": "./src/Relation.ts",
-      "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",
@@ -51,6 +109,24 @@
       "browser": "./dist/lib/browser/Ref.mjs",
       "node": "./dist/lib/node-esm/Ref.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",
@@ -67,18 +143,51 @@
       "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"
       ],
+      "Relation": [
+        "dist/types/src/Relation.d.ts"
+      ],
+      "Tag": [
+        "dist/types/src/Tag.d.ts"
+      ],
       "Type": [
         "dist/types/src/Type.d.ts"
       ]
@@ -89,21 +198,19 @@
     "src"
   ],
   "dependencies": {
-    "@preact/signals-core": "^1.12.1",
-    "effect": "3.18.3",
-    "@dxos/context": "0.8.4-main.66e292d",
-    "@dxos/echo-protocol": "0.8.4-main.66e292d",
-    "@dxos/debug": "0.8.4-main.66e292d",
-    "@dxos/echo-signals": "0.8.4-main.66e292d",
-    "@dxos/errors": "0.8.4-main.66e292d",
-    "@dxos/invariant": "0.8.4-main.66e292d",
-    "@dxos/effect": "0.8.4-main.66e292d",
-    "@dxos/keys": "0.8.4-main.66e292d",
-    "@dxos/live-object": "0.8.4-main.66e292d",
-    "@dxos/util": "0.8.4-main.66e292d",
-    "@dxos/log": "0.8.4-main.66e292d",
-    "@dxos/node-std": "0.8.4-main.66e292d",
-    "@dxos/protocols": "0.8.4-main.66e292d"
+    "effect": "3.19.11",
+    "@dxos/async": "0.8.4-main.69d29f4",
+    "@dxos/context": "0.8.4-main.69d29f4",
+    "@dxos/debug": "0.8.4-main.69d29f4",
+    "@dxos/echo-protocol": "0.8.4-main.69d29f4",
+    "@dxos/effect": "0.8.4-main.69d29f4",
+    "@dxos/errors": "0.8.4-main.69d29f4",
+    "@dxos/keys": "0.8.4-main.69d29f4",
+    "@dxos/invariant": "0.8.4-main.69d29f4",
+    "@dxos/log": "0.8.4-main.69d29f4",
+    "@dxos/node-std": "0.8.4-main.69d29f4",
+    "@dxos/protocols": "0.8.4-main.69d29f4",
+    "@dxos/util": "0.8.4-main.69d29f4"
   },
   "publishConfig": {
     "access": "public"

package/src/Annotation.ts

@@ -7,11 +7,12 @@ export {
   FormInputAnnotation,
   GeneratorAnnotation,
   LabelAnnotation,
+  ReferenceAnnotation,
   SystemTypeAnnotation,
   TypeAnnotation,
-  getDescription,
-  getLabel,
+  getDescriptionWithSchema,
+  getLabelWithSchema,
   getTypeAnnotation,
-  setDescription,
-  setLabel,
+  setDescriptionWithSchema,
+  setLabelWithSchema,
 } from './internal/annotations';

package/src/Database.ts

@@ -2,82 +2,31 @@
 // Copyright 2025 DXOS.org
 //
 
-import { type CleanupFn } from '@dxos/async';
+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 { type DXN, type PublicKey, type SpaceId } from '@dxos/keys';
+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 type { Filter, Query } from './query';
-import type * as Ref from './Ref';
-
-// TODO(burdon): Create QueryResult namespace.
-
-/**
- * Individual query result entry.
- */
-export type QueryResultEntry<T extends Entity.Unknown = Entity.Unknown> = {
-  id: string;
-
-  spaceId: SpaceId;
-
-  /**
-   * May not be present for remote results.
-   */
-  object?: T;
-
-  match?: {
-    // TODO(dmaretskyi): text positional info.
-
-    /**
-     * Higher means better match.
-     */
-    rank: number;
-  };
-
-  /**
-   * Query resolution metadata.
-   */
-  // TODO(dmaretskyi): Rename to meta?
-  resolution?: {
-    // TODO(dmaretskyi): Make this more generic.
-    source: 'remote' | 'local' | 'index';
-
-    /**
-     * Query resolution time in milliseconds.
-     */
-    time: number;
-  };
-};
-
-export type OneShotQueryResult<T extends Entity.Unknown = Entity.Unknown> = {
-  results: QueryResultEntry<T>[];
-  objects: T[];
-};
-
-export type QuerySubscriptionOptions = {
-  /**
-   * Fire the callback immediately.
-   */
-  fire?: boolean;
-};
-
-// TODO(burdon): Narrow types.
-export interface QueryResult<T extends Entity.Unknown = Entity.Unknown> {
-  readonly query: Query<T>;
-  readonly results: QueryResultEntry<T>[];
-  readonly objects: T[];
-
-  run(opts?: QueryRunOptions): Promise<OneShotQueryResult<T>>;
-  runSync(): QueryResultEntry<T>[];
-  first(opts?: QueryRunOptions): Promise<T>;
-
-  subscribe(callback?: (query: QueryResult<T>) => void, opts?: QuerySubscriptionOptions): CleanupFn;
-}
-
-export type QueryRunOptions = {
-  timeout?: number;
-};
+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.
@@ -119,12 +68,12 @@ export interface QueryFn {
   <Q extends Query.Any>(
     query: Q,
     options?: (QueryAST.QueryOptions & QueryOptions) | undefined,
-  ): QueryResult<Query.Type<Q>>;
+  ): QueryResult.QueryResult<Query.Type<Q>>;
 
   <F extends Filter.Any>(
     filter: F,
     options?: (QueryAST.QueryOptions & QueryOptions) | undefined,
-  ): QueryResult<Filter.Type<F>>;
+  ): QueryResult.QueryResult<Filter.Type<F>>;
 }
 
 /**
@@ -152,14 +101,56 @@ export type AddOptions = {
   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): Move hypergraph def here.
-  // get graph(): Hypergraph;
+  // 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.
@@ -169,12 +160,7 @@ export interface Database extends Queryable {
    * `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.Ref<T>;
-
-  /**
-   * Query objects.
-   */
-  query: QueryFn;
+  makeRef<T extends Entity.Unknown = Entity.Unknown>(dxn: DXN): Ref<T>;
 
   /**
    * Adds object to the database.
@@ -186,4 +172,165 @@ export interface Database extends Queryable {
    */
   // 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);
+  });
+});