@dxos/echo 0.8.4-main.e8ec1fe → 0.8.4-main.ef1bc66f44

package/package.json

@@ -1,9 +1,13 @@
 {
   "name": "@dxos/echo",
-  "version": "0.8.4-main.e8ec1fe",
+  "version": "0.8.4-main.ef1bc66f44",
   "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,
@@ -12,70 +16,102 @@
     ".": {
       "source": "./src/index.ts",
       "types": "./dist/types/src/index.d.ts",
-      "browser": "./dist/lib/browser/index.mjs",
-      "node": "./dist/lib/node-esm/index.mjs"
+      "default": "./dist/lib/neutral/index.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"
+    "./internal": {
+      "source": "./src/internal/index.ts",
+      "types": "./dist/types/src/internal/index.d.ts",
+      "default": "./dist/lib/neutral/internal/index.mjs"
+    },
+    "./testing": {
+      "source": "./src/testing/index.ts",
+      "types": "./dist/types/src/testing/index.d.ts",
+      "default": "./dist/lib/neutral/testing/index.mjs"
+    },
+    "./Annotation": {
+      "source": "./src/Annotation.ts",
+      "types": "./dist/types/src/Annotation.d.ts",
+      "default": "./dist/lib/neutral/Annotation.mjs"
+    },
+    "./Database": {
+      "source": "./src/Database.ts",
+      "types": "./dist/types/src/Database.d.ts",
+      "default": "./dist/lib/neutral/Database.mjs"
+    },
+    "./Entity": {
+      "source": "./src/Entity.ts",
+      "types": "./dist/types/src/Entity.d.ts",
+      "default": "./dist/lib/neutral/Entity.mjs"
+    },
+    "./Err": {
+      "source": "./src/Err.ts",
+      "types": "./dist/types/src/Err.d.ts",
+      "default": "./dist/lib/neutral/Err.mjs"
+    },
+    "./Filter": {
+      "source": "./src/Filter.ts",
+      "types": "./dist/types/src/Filter.d.ts",
+      "default": "./dist/lib/neutral/Filter.mjs"
+    },
+    "./Format": {
+      "source": "./src/Format.ts",
+      "types": "./dist/types/src/Format.d.ts",
+      "default": "./dist/lib/neutral/Format.mjs"
+    },
+    "./JsonSchema": {
+      "source": "./src/JsonSchema.ts",
+      "types": "./dist/types/src/JsonSchema.d.ts",
+      "default": "./dist/lib/neutral/JsonSchema.mjs"
+    },
+    "./Key": {
+      "source": "./src/Key.ts",
+      "types": "./dist/types/src/Key.d.ts",
+      "default": "./dist/lib/neutral/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"
+      "default": "./dist/lib/neutral/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",
+      "default": "./dist/lib/neutral/Order.mjs"
+    },
+    "./Query": {
+      "source": "./src/Query.ts",
+      "types": "./dist/types/src/Query.d.ts",
+      "default": "./dist/lib/neutral/Query.mjs"
+    },
+    "./QueryResult": {
+      "source": "./src/QueryResult.ts",
+      "types": "./dist/types/src/QueryResult.d.ts",
+      "default": "./dist/lib/neutral/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"
+      "default": "./dist/lib/neutral/Ref.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"
+    "./Relation": {
+      "source": "./src/Relation.ts",
+      "types": "./dist/types/src/Relation.d.ts",
+      "default": "./dist/lib/neutral/Relation.mjs"
     },
-    "./query": {
-      "source": "./src/query/index.ts",
-      "types": "./dist/types/src/query/index.d.ts",
-      "browser": "./dist/lib/browser/query/index.mjs",
-      "node": "./dist/lib/node-esm/query/index.mjs"
+    "./SchemaRegistry": {
+      "source": "./src/SchemaRegistry.ts",
+      "types": "./dist/types/src/SchemaRegistry.d.ts",
+      "default": "./dist/lib/neutral/SchemaRegistry.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"
-    }
-  },
-  "types": "dist/types/src/index.d.ts",
-  "typesVersions": {
-    "*": {
-      "Type": [
-        "dist/types/src/Type.d.ts"
-      ],
-      "Obj": [
-        "dist/types/src/Obj.d.ts"
-      ],
-      "Relation": [
-        "dist/types/src/Relation.d.ts"
-      ],
-      "Ref": [
-        "dist/types/src/Ref.d.ts"
-      ],
-      "testing": [
-        "dist/types/src/testing/index.d.ts"
-      ]
+    "./Tag": {
+      "source": "./src/Tag.ts",
+      "types": "./dist/types/src/Tag.d.ts",
+      "default": "./dist/lib/neutral/Tag.mjs"
+    },
+    "./Type": {
+      "source": "./src/Type.ts",
+      "types": "./dist/types/src/Type.d.ts",
+      "default": "./dist/lib/neutral/Type.mjs"
     }
   },
   "files": [
@@ -83,19 +119,19 @@
     "src"
   ],
   "dependencies": {
-    "@preact/signals-core": "^1.12.1",
-    "effect": "3.18.3",
-    "@dxos/debug": "0.8.4-main.e8ec1fe",
-    "@dxos/echo-protocol": "0.8.4-main.e8ec1fe",
-    "@dxos/echo-signals": "0.8.4-main.e8ec1fe",
-    "@dxos/errors": "0.8.4-main.e8ec1fe",
-    "@dxos/effect": "0.8.4-main.e8ec1fe",
-    "@dxos/invariant": "0.8.4-main.e8ec1fe",
-    "@dxos/keys": "0.8.4-main.e8ec1fe",
-    "@dxos/live-object": "0.8.4-main.e8ec1fe",
-    "@dxos/log": "0.8.4-main.e8ec1fe",
-    "@dxos/node-std": "0.8.4-main.e8ec1fe",
-    "@dxos/util": "0.8.4-main.e8ec1fe"
+    "effect": "3.19.16",
+    "@dxos/async": "0.8.4-main.ef1bc66f44",
+    "@dxos/debug": "0.8.4-main.ef1bc66f44",
+    "@dxos/context": "0.8.4-main.ef1bc66f44",
+    "@dxos/effect": "0.8.4-main.ef1bc66f44",
+    "@dxos/echo-protocol": "0.8.4-main.ef1bc66f44",
+    "@dxos/errors": "0.8.4-main.ef1bc66f44",
+    "@dxos/invariant": "0.8.4-main.ef1bc66f44",
+    "@dxos/log": "0.8.4-main.ef1bc66f44",
+    "@dxos/protocols": "0.8.4-main.ef1bc66f44",
+    "@dxos/keys": "0.8.4-main.ef1bc66f44",
+    "@dxos/node-std": "0.8.4-main.ef1bc66f44",
+    "@dxos/util": "0.8.4-main.ef1bc66f44"
   },
   "publishConfig": {
     "access": "public"

package/src/Annotation.ts

@@ -0,0 +1,45 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export {
+  DescriptionAnnotation,
+  FormInputAnnotation,
+  GeneratorAnnotation,
+  LabelAnnotation,
+  ReferenceAnnotation,
+  SystemTypeAnnotation,
+  TypeAnnotation,
+  getDescriptionWithSchema,
+  getLabelWithSchema,
+  getTypeAnnotation,
+  setDescriptionWithSchema,
+  setLabelWithSchema,
+} from './internal/annotations';
+
+import type * as Schema from 'effect/Schema';
+
+import * as internalAnnotations from './internal/annotations';
+
+interface MakeProps<T> {
+  id: string;
+  schema: Schema.Schema<T, any, never>;
+}
+
+/**
+ * Create a new schema annotation.
+ * Annotation can be assigned both to fields and to the schema itself.
+ * Annotation is serialized with the schema.
+ *
+ * @example
+ * ```ts
+ * const ColorAnnotation = Annotation.make({
+ *   id: 'dxos.org/annotation/Color',
+ *   schema: Schema.String,
+ * });
+ *
+ * const schema = Schema.String.annotations(ColorAnnotation.set('red'));
+ * ```
+ */
+export const make: <T>(props: MakeProps<T>) => internalAnnotations.AnnotationHelper<T> =
+  internalAnnotations.makeUserAnnotation;

package/src/Database.ts

@@ -0,0 +1,353 @@
+//
+// 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)));
+
+/**
+ * Effect service tag for Database dependency injection.
+ */
+export class Service extends Context.Tag('@dxos/echo/Database/Service')<
+  Service,
+  {
+    readonly db: Database;
+  }
+>() {}
+
+/**
+ * Layer that provides a Database service that throws when accessed.
+ * Useful as a default layer when no database is available.
+ */
+export const notAvailable = Layer.succeed(Service, {
+  get db(): Database {
+    throw new Error('Database not available');
+  },
+});
+
+/**
+ * Creates a Database service instance from a Database.
+ */
+export const makeService = (db: Database): Context.Tag.Service<Service> => {
+  return {
+    get db() {
+      return db;
+    },
+  };
+};
+
+/**
+ * Creates a Layer that provides the Database service.
+ */
+export const layer = (db: Database): Layer.Layer<Service> => {
+  return Layer.succeed(Service, makeService(db));
+};
+
+/**
+ * Returns the space ID of the database.
+ */
+export const spaceId = Effect.gen(function* () {
+  const { db } = yield* Service;
+  return db.spaceId;
+});
+
+/**
+ * Resolves an object by its DXN.
+ */
+export const 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.
+ */
+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;
+});
+
+/**
+ * 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) {
+  const object = yield* load(ref).pipe(Effect.catchTag('ObjectNotFoundError', () => Effect.succeed(undefined)));
+
+  return Option.fromNullable(object);
+});
+
+/**
+ * Adds an object to the database.
+ * @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)));
+
+/**
+ * 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)));
+
+/**
+ * Flushes pending changes to disk.
+ * @see {@link Database.flush}
+ */
+export const flush = (opts?: FlushOptions) =>
+  Service.pipe(Effect.flatMap(({ db }) => promiseWithCauseCapture(() => db.flush(opts))));
+
+/**
+ * Creates a `QueryResult` object that can be subscribed to.
+ */
+export const 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('Database.query'),
+  );
+
+/**
+ * Executes the query once and returns the results.
+ */
+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())));
+
+/**
+ * Creates a schema query result that can be subscribed to.
+ */
+// TODO(dmaretskyi): Change API to `yield* Database.querySchema(...).first` and `yield* Database.querySchema(...).schema`.
+export const schemaQuery = <Q extends Types.NoExcessProperties<SchemaRegistry.Query, Q>>(
+  schemaQueryOptions?: Q & SchemaRegistry.Query,
+): Effect.Effect<QueryResult.QueryResult<SchemaRegistry.ExtractQueryResult<Q>>, never, Service> =>
+  Service.pipe(
+    Effect.map(({ db }) => db.schemaRegistry.query(schemaQueryOptions)),
+    Effect.withSpan('Database.schemaQuery'),
+  );
+
+/**
+ * Executes a schema query once and returns the results.
+ */
+export const runSchemaQuery = <Q extends Types.NoExcessProperties<SchemaRegistry.Query, Q>>(
+  schemaQueryOptions?: Q & SchemaRegistry.Query,
+): Effect.Effect<SchemaRegistry.ExtractQueryResult<Q>[], never, Service> =>
+  schemaQuery(schemaQueryOptions).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);
+  });
+});