@dxos/echo 0.8.4-main.3a94e84 → 0.8.4-main.3c1ae3b

package/package.json

@@ -1,62 +1,191 @@
 {
   "name": "@dxos/echo",
-  "version": "0.8.4-main.3a94e84",
+  "version": "0.8.4-main.3c1ae3b",
   "description": "ECHO API",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
   "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 +194,21 @@
     "src"
   ],
   "dependencies": {
-    "@preact/signals-core": "^1.9.0",
-    "effect": "3.17.0",
-    "@dxos/debug": "0.8.4-main.3a94e84",
-    "@dxos/echo-schema": "0.8.4-main.3a94e84",
-    "@dxos/echo-signals": "0.8.4-main.3a94e84",
-    "@dxos/echo-protocol": "0.8.4-main.3a94e84",
-    "@dxos/effect": "0.8.4-main.3a94e84",
-    "@dxos/invariant": "0.8.4-main.3a94e84",
-    "@dxos/keys": "0.8.4-main.3a94e84",
-    "@dxos/live-object": "0.8.4-main.3a94e84",
-    "@dxos/log": "0.8.4-main.3a94e84",
-    "@dxos/node-std": "0.8.4-main.3a94e84",
-    "@dxos/util": "0.8.4-main.3a94e84"
+    "@preact/signals-core": "^1.12.1",
+    "effect": "3.18.3",
+    "@dxos/context": "0.8.4-main.3c1ae3b",
+    "@dxos/debug": "0.8.4-main.3c1ae3b",
+    "@dxos/echo-protocol": "0.8.4-main.3c1ae3b",
+    "@dxos/echo-signals": "0.8.4-main.3c1ae3b",
+    "@dxos/effect": "0.8.4-main.3c1ae3b",
+    "@dxos/errors": "0.8.4-main.3c1ae3b",
+    "@dxos/invariant": "0.8.4-main.3c1ae3b",
+    "@dxos/keys": "0.8.4-main.3c1ae3b",
+    "@dxos/live-object": "0.8.4-main.3c1ae3b",
+    "@dxos/log": "0.8.4-main.3c1ae3b",
+    "@dxos/node-std": "0.8.4-main.3c1ae3b",
+    "@dxos/protocols": "0.8.4-main.3c1ae3b",
+    "@dxos/util": "0.8.4-main.3c1ae3b"
   },
   "publishConfig": {
     "access": "public"

package/src/Annotation.ts

@@ -0,0 +1,17 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export {
+  DescriptionAnnotation,
+  FormInputAnnotation,
+  GeneratorAnnotation,
+  LabelAnnotation,
+  SystemTypeAnnotation,
+  TypeAnnotation,
+  getDescription,
+  getLabel,
+  getTypeAnnotation,
+  setDescription,
+  setLabel,
+} from './internal/annotations';

package/src/Database.ts

@@ -0,0 +1,308 @@
+//
+// 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 type * 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 { type DXN, type PublicKey, type SpaceId } from '@dxos/keys';
+import { type Live } from '@dxos/live-object';
+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';
+import type * as Query from './Query';
+import type * as QueryResult from './QueryResult';
+import type * as Ref from './Ref';
+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;
+};
+
+/**
+ * ECHO Database interface.
+ */
+export interface Database extends Queryable {
+  get spaceId(): SpaceId;
+
+  // TODO(burdon): Can we move this into graph?
+  get schemaRegistry(): SchemaRegistry.SchemaRegistry;
+
+  /**
+   *
+   */
+  // TODO(burdon): Comment required.
+  get graph(): Hypergraph.Hypergraph;
+
+  /**
+   * 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.Ref<T>;
+
+  /**
+   * Adds object to the database.
+   */
+  // TODO(burdon): Add batch.
+  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 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));
+  };
+
+  /**
+   * Resolves an object by its DXN.
+   */
+  static resolve: {
+    // No type check.
+    (dxn: DXN): Effect.Effect<Entity.Unknown, never, Service>;
+    // Check matches schema.
+    <S extends Type.Entity.Any>(
+      dxn: DXN,
+      schema: S,
+    ): Effect.Effect<Schema.Schema.Type<S>, Err.ObjectNotFoundError, Service>;
+  } = (<S extends Type.Entity.Any>(
+    dxn: DXN,
+    schema?: S,
+  ): Effect.Effect<Schema.Schema.Type<S>, Err.ObjectNotFoundError, Service> =>
+    Effect.gen(function* () {
+      const { db } = yield* Service;
+      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.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(burdon): Option?
+  static loadOption: <T>(ref: Ref.Ref<T>) => Effect.Effect<Option.Option<T>, never, never> = Effect.fn(function* (ref) {
+    const object = yield* Service.load(ref).pipe(Effect.catchTag('OBJECT_NOT_FOUND', () => Effect.succeed(undefined)));
+    return Option.fromNullable(object);
+  });
+
+  // TODO(burdon): Can we create a proxy for the following methods on Database? Use @inheritDoc?
+  // TODO(burdon): Figure out how to chain query().run();
+
+  /**
+   * @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<Live<Query.Type<Q>>>, never, Service>;
+    <F extends Filter.Any>(filter: F): Effect.Effect<QueryResult.QueryResult<Live<Filter.Type<F>>>, never, Service>;
+  } = (queryOrFilter: Query.Any | Filter.Any) =>
+    Service.pipe(
+      Effect.map(({ db }) => db.query(queryOrFilter as any) as QueryResult.QueryResult<Live<any>>),
+      Effect.withSpan('Service.query'),
+    );
+
+  /**
+   * Executes the query once and returns the results.
+   */
+  static runQuery: {
+    <Q extends Query.Any>(query: Q): Effect.Effect<Live<Query.Type<Q>>[], never, Service>;
+    <F extends Filter.Any>(filter: F): Effect.Effect<Live<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.ts

@@ -0,0 +1,51 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import type { ObjectId } from '@dxos/keys';
+
+import { EntityKind, EntityKindSchema, KindId, getEntityKind } from './internal';
+
+export { KindId };
+
+// NOTE: Relation does not extend Obj so that, for example, we can prevent Relations from being used as source and target objects.
+//  However, we generally refer to Obj and Relation instances as "objects",
+//  and many API methods accept both Obj.Any and Relation.Any (i.e., Entity.Unknown) instances.
+
+export const Kind = EntityKind;
+export type Kind = EntityKind;
+export const KindSchema = EntityKindSchema;
+
+/**
+ * Assigns a kind to an Object or Relation instance.
+ */
+// NOTE: Needed to make `isRelation` and `isObject` checks work.
+export interface OfKind<K extends Kind> {
+  readonly [KindId]: K;
+  readonly id: ObjectId;
+}
+
+/**
+ * Obj or Relation with a specific set of properties.
+ */
+export type Entity<Props> = OfKind<Kind> & Props;
+
+/**
+ * Unknown Obj or Relation.
+ */
+export interface Unknown extends OfKind<Kind> {}
+
+/**
+ * Object with arbitrary properties.
+ *
+ * NOTE: Due to how typescript works, this type is not assignable to a specific schema type.
+ * In that case, use `Obj.instanceOf` to check if an object is of a specific type.
+ *
+ * This type is very permissive and allows accessing any property on the object.
+ * We should move to Obj.Any that is not permissive and requires explicit instanceof checks..
+ */
+export interface Any extends OfKind<Kind> {
+  [key: string]: unknown;
+}
+
+export const getKind = getEntityKind;

package/src/Err.ts

@@ -0,0 +1,18 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { BaseError, type BaseErrorOptions } from '@dxos/errors';
+import { type DXN } from '@dxos/keys';
+
+export class SchemaNotFoundError extends BaseError.extend('SCHEMA_NOT_FOUND', 'Schema not found') {
+  constructor(schema: string, options?: BaseErrorOptions) {
+    super({ context: { schema }, ...options });
+  }
+}
+
+export class ObjectNotFoundError extends BaseError.extend('OBJECT_NOT_FOUND', 'Object not found') {
+  constructor(dxn: DXN, options?: BaseErrorOptions) {
+    super({ context: { dxn }, ...options });
+  }
+}