@dxos/echo 0.8.4-main.5ad4a44 → 0.8.4-main.66e292d

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dxos/echo",
-  "version": "0.8.4-main.5ad4a44",
+  "version": "0.8.4-main.66e292d",
   "description": "ECHO API",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
@@ -15,11 +15,23 @@
       "browser": "./dist/lib/browser/index.mjs",
       "node": "./dist/lib/node-esm/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",
+      "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"
+    },
+    "./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"
     },
     "./Obj": {
       "source": "./src/Obj.ts",
@@ -39,30 +51,24 @@
       "browser": "./dist/lib/browser/Ref.mjs",
       "node": "./dist/lib/node-esm/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"
-    },
-    "./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"
-    },
-    "./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"
+    "./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"
+      ],
+      "Entity": [
+        "dist/types/src/Entity.d.ts"
       ],
       "Obj": [
         "dist/types/src/Obj.d.ts"
@@ -73,8 +79,8 @@
       "Ref": [
         "dist/types/src/Ref.d.ts"
       ],
-      "testing": [
-        "dist/types/src/testing/index.d.ts"
+      "Type": [
+        "dist/types/src/Type.d.ts"
       ]
     }
   },
@@ -85,17 +91,19 @@
   "dependencies": {
     "@preact/signals-core": "^1.12.1",
     "effect": "3.18.3",
-    "@dxos/debug": "0.8.4-main.5ad4a44",
-    "@dxos/echo-protocol": "0.8.4-main.5ad4a44",
-    "@dxos/echo-signals": "0.8.4-main.5ad4a44",
-    "@dxos/effect": "0.8.4-main.5ad4a44",
-    "@dxos/errors": "0.8.4-main.5ad4a44",
-    "@dxos/invariant": "0.8.4-main.5ad4a44",
-    "@dxos/keys": "0.8.4-main.5ad4a44",
-    "@dxos/live-object": "0.8.4-main.5ad4a44",
-    "@dxos/log": "0.8.4-main.5ad4a44",
-    "@dxos/node-std": "0.8.4-main.5ad4a44",
-    "@dxos/util": "0.8.4-main.5ad4a44"
+    "@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"
   },
   "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,189 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type CleanupFn } from '@dxos/async';
+import { type QueryAST } from '@dxos/echo-protocol';
+import { type 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;
+};
+
+/**
+ * @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<Query.Type<Q>>;
+
+  <F extends Filter.Any>(
+    filter: F,
+    options?: (QueryAST.QueryOptions & QueryOptions) | undefined,
+  ): 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;
+};
+
+/**
+ * ECHO Database interface.
+ */
+export interface Database extends Queryable {
+  get spaceId(): SpaceId;
+
+  // TODO(burdon): Move hypergraph def here.
+  // get graph(): Hypergraph;
+
+  /**
+   * 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>;
+
+  /**
+   * Query objects.
+   */
+  query: QueryFn;
+
+  /**
+   * 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;
+}

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/Format.ts

@@ -0,0 +1,11 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type TypeFormat as Format } from './internal';
+
+// TODO(burdon): Move Format implementaion to ./Ref folder here.
+
+export * from './internal/formats';
+
+export type { Format };

package/src/JsonSchema.ts

@@ -0,0 +1,16 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import type * as Schema from 'effect/Schema';
+
+import { JsonSchemaType } from './internal';
+
+export { toEffectSchema, toJsonSchema } from './internal';
+
+/**
+ * Serializable JsonSchema type definition.
+ */
+export type JsonSchema = JsonSchemaType;
+
+export const JsonSchema: Schema.Schema<JsonSchemaType> = JsonSchemaType;

package/src/Key.ts

@@ -2,4 +2,7 @@
 // Copyright 2025 DXOS.org
 //
 
+// TODO(wittjosiah): Should this be a subset of Type?
+
+export { ForeignKey } from '@dxos/echo-protocol';
 export { SpaceId, ObjectId } from '@dxos/keys';