@dxos/echo 0.8.4-main.7ace549 → 0.8.4-main.8360d9e660

package/src/Database.ts

@@ -2,129 +2,39 @@
 // 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-as-namespace
 
-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[];
+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';
 
-  /**
-   * Return only the first `limit` results.
-   */
-  limit?: number;
+import { promiseWithCauseCapture } from '@dxos/effect';
+import { invariant } from '@dxos/invariant';
+import { DXN, type SpaceId } from '@dxos/keys';
 
-  /**
-   * Query only local spaces, or remote on agent.
-   * @default `QueryOptions.DataLocation.LOCAL`
-   *
-   * Options:
-   *   - proto3_optional = true
-   */
-  // TODO(burdon): Remove?
-  dataLocation?: QueryOptionsProto.DataLocation;
-};
+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/Annotation';
+import type { Ref } from './internal/Ref/ref';
+import { type AnyProperties } from './internal/common/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';
 
 /**
  * `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>>;
+  <Q extends Query.Any>(query: Q): QueryResult.QueryResult<Query.Type<Q>>;
+  <F extends Filter.Any>(filter: F): QueryResult.QueryResult<Filter.Type<F>>;
 }
 
 /**
@@ -152,14 +62,59 @@ export type AddOptions = {
   placeIn?: ObjectPlacement;
 };
 
+export type FlushOptions = {
+  /**
+   * Write any pending changes to disk.
+   * @default true
+   */
+  disk?: boolean;
+
+  /**
+   * Wait for pending index updates.
+   * @default true
+   */
+  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.OfShape<AnyProperties>>(
+    id: string,
+    opts?: GetObjectByIdOptions,
+  ): T | undefined;
+
+  /**
+   * Query objects.
+   */
+  query: QueryFn;
 
   /**
    * Creates a reference to an existing object in the database.
@@ -169,12 +124,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 +136,182 @@ 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)));
+
+/**
+ * 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.AnyEntity>(
+    ref: DXN | Ref<any>,
+    schema: S,
+  ): Effect.Effect<Schema.Schema.Type<S>, Err.ObjectNotFoundError, Service>;
+} = (<S extends Type.AnyEntity>(
+  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/Dataset.ts

@@ -0,0 +1,26 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+// @import-as-namespace
+
+import { pipe } from 'effect/Function';
+import * as Predicate from 'effect/Predicate';
+import * as Schema from 'effect/Schema';
+
+import * as Collection from './Collection';
+import * as Feed from './Feed';
+import * as Obj from './Obj';
+import * as View from './View';
+
+/**
+ * Abstart set of objects, represented by a view, feed, or collection.
+ */
+export const Dataset = Schema.Union(Feed.Feed, Collection.Collection, View.View);
+export type Dataset = Feed.Feed | Collection.Collection | View.View;
+
+export const isDataset: (value: unknown) => value is Dataset = pipe(
+  Obj.instanceOf(Feed.Feed),
+  Predicate.or(Obj.instanceOf(Collection.Collection)),
+  Predicate.or(Obj.instanceOf(View.View)),
+);

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);
+  });
+});