@dxos/echo 0.9.0 → 0.9.1-staging.ee54ba693a

package/src/Feed.ts

@@ -6,6 +6,7 @@
 
 import * as Context from 'effect/Context';
 import * as Effect from 'effect/Effect';
+import * as Function from 'effect/Function';
 import * as Layer from 'effect/Layer';
 import type * as Option from 'effect/Option';
 import * as Schema from 'effect/Schema';
@@ -13,9 +14,11 @@ import * as Schema from 'effect/Schema';
 import { DXN, EID } from '@dxos/keys';
 
 import * as Annotation from './Annotation';
+import * as Database from './Database';
 import type * as Entity from './Entity';
 import type * as Filter from './Filter';
 import * as internal from './internal';
+import * as queryInternal from './internal/Query';
 import * as Obj from './Obj';
 import type * as Query from './Query';
 import type * as QueryResult from './QueryResult';
@@ -29,29 +32,25 @@ import * as Type from './Type';
  * const feed = Obj.make(Feed.Feed, { name: 'notifications', kind: 'org.dxos.plugin.notifications.v1' });
  * ```
  */
-export const Feed = Schema.Struct({
-  /** User-facing display name. */
-  name: Schema.String.pipe(Schema.optional),
-  /** Identifier for the feed's kind (e.g., plugin id). */
-  kind: Schema.String.pipe(internal.FormInputAnnotation.set(false), Schema.optional),
+export class Feed extends Type.makeObject<Feed>(DXN.make('org.dxos.type.feed', '0.1.0'))(
+  Schema.Struct({
+    /** User-facing display name. */
+    name: Schema.String.pipe(Schema.optional),
+    /** Identifier for the feed's kind (e.g., plugin id). */
+    kind: Schema.String.pipe(internal.FormInputAnnotation.set(false), Schema.optional),
 
-  /**
-   * Feed namespace.
-   * Controls how feed data is stored and replicated.
-   * - `data`: Data feed (default).
-   * - `trace`: Trace feed.
-   */
-  namespace: Schema.optional(Schema.Literal('data', 'trace')),
-}).pipe(
-  internal.HiddenAnnotation.set(true),
-  Annotation.IconAnnotation.set({ icon: 'ph--rows--regular', hue: 'yellow' }),
-  Type.makeObject(DXN.make('org.dxos.type.feed', '0.1.0')),
-);
-
-/**
- * TypeScript instance type for a Feed object.
- */
-export type Feed = Type.InstanceType<typeof Feed>;
+    /**
+     * Feed namespace.
+     * Controls how feed data is stored and replicated.
+     * - `data`: Data feed (default).
+     * - `trace`: Trace feed.
+     */
+    namespace: Schema.optional(Schema.Literal('data', 'trace')),
+  }).pipe(
+    internal.HiddenAnnotation.set(true),
+    Annotation.IconAnnotation.set({ icon: 'ph--rows--regular', hue: 'yellow' }),
+  ),
+) {}
 
 //
 // Types
@@ -97,27 +96,19 @@ export interface SyncState {
   totalBlocks: number;
 }
 
-//
-// Factory
-//
-
 /**
- * Creates a new feed object.
- *
- * @example
- * ```ts
- * const feed = Feed.make({ name: 'notifications', kind: 'org.dxos.plugin.notifications.v1' });
- * ```
- */
-// TODO(wittjosiah): How to control the feed namespace (data/trace)? Why do feeds have namespaces?
-export const make = (props: Obj.MakeProps<typeof Feed> = {}): Feed => Obj.make(Feed, props);
-
-/**
- * Returns the feed object's EID when the feed is stored in a space.
- *
- * Used internally by the feed service layer.
+ * Effect service tag for injecting a Feed into effect operations.
+ * Used to provide a specific feed to operations that operate on it without threading
+ * the feed as an explicit parameter through every call site.
  */
-export const getQueueUri = (feed: Feed): EID.EID | undefined => EID.tryParse(Obj.getURI(feed));
+export class ContextFeedService extends Context.Tag('@dxos/echo/Feed/ContextFeedService')<
+  ContextFeedService,
+  {
+    readonly feed: Feed;
+  }
+>() {
+  static layer = (feed: Feed) => Layer.succeed(ContextFeedService, { feed });
+}
 
 //
 // Service
@@ -125,70 +116,25 @@ export const getQueueUri = (feed: Feed): EID.EID | undefined => EID.tryParse(Obj
 
 /**
  * Effect service for feed operations.
- * Provides the bridge to the underlying storage implementation.
- * Must be provided by the application layer (e.g., echo-db).
+ * @deprecated Use `Database.Service` instead — feed operations now run directly on the database.
  */
 export class FeedService extends Context.Tag('@dxos/echo/Feed/FeedService')<
   FeedService,
   {
-    /**
-     * Appends items to a feed.
-     */
     append(feed: Feed, items: Entity.Unknown[]): Promise<void>;
-
-    /**
-     * Removes items from a feed by ID.
-     */
     remove(feed: Feed, ids: string[]): Promise<void>;
-
-    /**
-     * Queries items in a feed.
-     */
     query: {
       <Q extends Query.Any>(feed: Feed, query: Q): QueryResult.QueryResult<Query.Type<Q>>;
       <F extends Filter.Any>(feed: Feed, filter: F): QueryResult.QueryResult<Filter.Type<F>>;
     };
-
-    /**
-     * Syncs the feed with the server.
-     */
     sync(feed: Feed, options?: SyncOptions): Promise<void>;
-
-    /**
-     * Returns queue replication backlog for the feed's namespace.
-     */
     getSyncState(feed: Feed): Promise<SyncState>;
   }
 >() {}
 
 /**
- * @deprecated Use `FeedService` instead.
- */
-export type Service = FeedService;
-
-/**
- * @deprecated Use `FeedService` instead.
- */
-export const Service = FeedService;
-
-/**
- * Effect context service that holds the current feed for a scoped operation.
- *
- * @deprecated Prefer threading a `Feed.Feed` explicitly through function signatures
- * over hiding it behind a context service.
- */
-export class ContextFeedService extends Context.Tag('@dxos/echo/Feed/ContextFeedService')<
-  ContextFeedService,
-  {
-    readonly feed: Feed;
-  }
->() {
-  static layer = (feed: Feed): Layer.Layer<ContextFeedService> => Layer.succeed(ContextFeedService, { feed });
-}
-
-/**
- * Layer that provides a Feed service that throws when accessed.
- * Useful as a default layer when no feed service is available.
+ * Layer that provides a `FeedService` that throws when accessed.
+ * @deprecated Use `Database.layer(db)` instead.
  */
 export const notAvailable: Layer.Layer<FeedService> = Layer.succeed(FeedService, {
   append: () => {
@@ -198,7 +144,7 @@ export const notAvailable: Layer.Layer<FeedService> = Layer.succeed(FeedService,
     throw new Error('Feed.FeedService not available');
   },
   query: () => {
-    throw new Error('Feed.FeedService not available');
+    throw new Error('Feed.FeedService not available') as never;
   },
   sync: () => {
     throw new Error('Feed.FeedService not available');
@@ -208,6 +154,28 @@ export const notAvailable: Layer.Layer<FeedService> = Layer.succeed(FeedService,
   },
 } as Context.Tag.Service<FeedService>);
 
+//
+// Factory
+//
+
+/**
+ * Creates a new feed object.
+ *
+ * @example
+ * ```ts
+ * const feed = Feed.make({ name: 'notifications', kind: 'org.dxos.plugin.notifications.v1' });
+ * ```
+ */
+// TODO(wittjosiah): How to control the feed namespace (data/trace)? Why do feeds have namespaces?
+export const make = (props: Obj.MakeProps<typeof Feed> = {}): Feed => Obj.make(Feed, props);
+
+/**
+ * Returns the feed object's EID when the feed is stored in a space.
+ *
+ * Used internally by the feed service layer.
+ */
+export const getQueueUri = (feed: Feed): EID.EID | undefined => EID.tryParse(Obj.getURI(feed));
+
 //
 // Operations
 //
@@ -220,11 +188,10 @@ export const notAvailable: Layer.Layer<FeedService> = Layer.succeed(FeedService,
  * yield* Feed.append(feed, [Obj.make(Notification, { title: 'Hello' })]);
  * ```
  */
-export const append = (feed: Feed, items: Entity.Unknown[]): Effect.Effect<void, never, FeedService> =>
-  Effect.gen(function* () {
-    const service = yield* FeedService;
-    yield* Effect.promise(() => service.append(feed, items));
-  });
+export const append = (feed: Feed, items: Entity.Unknown[]): Effect.Effect<void, never, Database.Service> =>
+  Database.Service.pipe(Effect.flatMap(({ db }) => Effect.promise(() => db.appendToFeed(feed, items)))).pipe(
+    Effect.withSpan('Feed.append'),
+  );
 
 /**
  * Removes items from a feed.
@@ -235,51 +202,61 @@ export const append = (feed: Feed, items: Entity.Unknown[]): Effect.Effect<void,
  * ```
  */
 // TODO(dmaretskyi): Should we allow snapshots here? - what does it mean to remove a snapshot?
-export const remove = (feed: Feed, items: (Entity.Unknown | Obj.Snapshot)[]): Effect.Effect<void, never, FeedService> =>
-  Effect.gen(function* () {
-    const service = yield* FeedService;
-    const ids = items.map((item) => item.id);
-    yield* Effect.promise(() => service.remove(feed, ids));
-  });
+export const remove = (
+  feed: Feed,
+  items: (Entity.Unknown | Obj.Snapshot)[],
+): Effect.Effect<void, never, Database.Service> =>
+  Database.Service.pipe(
+    Effect.flatMap(({ db }) =>
+      Effect.promise(() =>
+        db.removeFeedItemsByIds(
+          feed,
+          items.map((item) => item.id),
+        ),
+      ),
+    ),
+  ).pipe(Effect.withSpan('Feed.remove'));
 
 /**
  * Creates a reactive query over items in a feed.
  *
+ * Returns a {@link QueryResult.QueryResultEffect}: yielding it produces a subscribable
+ * `QueryResult`, while its `.run` / `.first` shorthands execute the query once. This mirrors
+ * `Database.query` so feed and database queries chain identically.
+ *
+ * Supports both data-first and data-last (curried) forms; the latter composes with `pipe`.
+ *
+ * In non-Effect code, query a feed directly through the database with a feed scope:
+ * `db.query(Query.select(filter).from(Scope.feed(Feed.getQueueUri(feed))))`.
+ *
  * @example
  * ```ts
  * const result = yield* Feed.query(feed, Filter.type(Person));
+ * result.subscribe(...);
+ *
+ * const objects = yield* Feed.query(feed, Filter.type(Person)).run;
+ * const object = yield* Feed.query(feed, Filter.type(Person)).first;
+ *
+ * // Data-last (curried) form composes with `pipe`:
+ * const objects = yield* pipe(feed, Feed.query(Filter.type(Person))).run;
  * ```
  */
-// TODO(dmaretskyi): Suport chained queries:
-//                   const result = yield* feed.pipe(Feed.query(Filter.type(Person))); result.subscribe(...)
-//                   const objects = yield* feed.pipe(Feed.query(Filter.type(Person))).run;
-//                   const object = yield* feed.pipe(Feed.query(Filter.type(Person))).first;
-// ... unify for Database and schema queries.
 export const query: {
+  <Q extends Query.Any>(feed: Feed, query: Q): QueryResult.QueryResultEffect<Query.Type<Q>, never, Database.Service>;
+  <F extends Filter.Any>(feed: Feed, filter: F): QueryResult.QueryResultEffect<Filter.Type<F>, never, Database.Service>;
   <Q extends Query.Any>(
-    feed: Feed,
     query: Q,
-  ): Effect.Effect<QueryResult.QueryResult<Query.Type<Q>>, never, FeedService>;
+  ): (feed: Feed) => QueryResult.QueryResultEffect<Query.Type<Q>, never, Database.Service>;
   <F extends Filter.Any>(
-    feed: Feed,
     filter: F,
-  ): Effect.Effect<QueryResult.QueryResult<Filter.Type<F>>, never, FeedService>;
-} = (feed: Feed, queryOrFilter: Query.Any | Filter.Any) =>
-  FeedService.pipe(Effect.map((service) => service.query(feed, queryOrFilter as any) as QueryResult.QueryResult<any>));
-
-/**
- * Executes a feed query once and returns the results.
- *
- * @example
- * ```ts
- * const items = yield* Feed.runQuery(feed, Filter.type(Person));
- * ```
- */
-export const runQuery: {
-  <Q extends Query.Any>(feed: Feed, query: Q): Effect.Effect<Query.Type<Q>[], never, FeedService>;
-  <F extends Filter.Any>(feed: Feed, filter: F): Effect.Effect<Filter.Type<F>[], never, FeedService>;
-} = (feed: Feed, queryOrFilter: Query.Any | Filter.Any) =>
-  query(feed, queryOrFilter as any).pipe(Effect.flatMap((queryResult) => Effect.promise(() => queryResult.run())));
+  ): (feed: Feed) => QueryResult.QueryResultEffect<Filter.Type<F>, never, Database.Service>;
+} = Function.dual(2, (feed: Feed, queryOrFilter: Query.Any | Filter.Any) =>
+  Database.Service.pipe(
+    Effect.map(({ db }) => db.queryFeed(feed, queryOrFilter)),
+    Effect.withSpan('Feed.query'),
+    queryInternal.makeQueryResultEffect,
+  ),
+);
 
 /**
  * Syncs the feed with the server.
@@ -290,11 +267,10 @@ export const runQuery: {
  * yield* Feed.sync(feed, { shouldPush: false });
  * ```
  */
-export const sync = (feed: Feed, options?: SyncOptions): Effect.Effect<void, never, FeedService> =>
-  Effect.gen(function* () {
-    const service = yield* FeedService;
-    yield* Effect.promise(() => service.sync(feed, options));
-  });
+export const sync = (feed: Feed, options?: SyncOptions): Effect.Effect<void, never, Database.Service> =>
+  Database.Service.pipe(Effect.flatMap(({ db }) => Effect.promise(() => db.syncFeed(feed, options)))).pipe(
+    Effect.withSpan('Feed.sync'),
+  );
 
 /**
  * Returns queue replication backlog for the feed's namespace.
@@ -304,11 +280,10 @@ export const sync = (feed: Feed, options?: SyncOptions): Effect.Effect<void, nev
  * const { blocksToPull, blocksToPush } = yield* Feed.getSyncState(feed);
  * ```
  */
-export const getSyncState = (feed: Feed): Effect.Effect<SyncState, never, FeedService> =>
-  Effect.gen(function* () {
-    const service = yield* FeedService;
-    return yield* Effect.promise(() => service.getSyncState(feed));
-  });
+export const getSyncState = (feed: Feed): Effect.Effect<SyncState, never, Database.Service> =>
+  Database.Service.pipe(Effect.flatMap(({ db }) => Effect.promise(() => db.getFeedSyncState(feed)))).pipe(
+    Effect.withSpan('Feed.getSyncState'),
+  );
 
 /**
  * Creates a cursor for iterating over feed items.
@@ -321,22 +296,23 @@ export const getSyncState = (feed: Feed): Effect.Effect<SyncState, never, FeedSe
  * ```
  */
 // TODO(wittjosiah): Implement cursor operations. Use Effect streams?
-export const cursor = <T = Obj.Snapshot>(_feed: Feed): Effect.Effect<Cursor<T>, never, FeedService> =>
+export const cursor = <T = Obj.Snapshot>(_feed: Feed): Effect.Effect<Cursor<T>, never, Database.Service> =>
   Effect.succeed({ _tag: 'Cursor' } as Cursor<T>);
 
 /**
  * Returns the next item from a feed cursor.
  * Currently stubbed — cursor operations are not yet implemented.
  */
-export const next = <T = Obj.Snapshot>(_cursor: Cursor<T>): Effect.Effect<T, never, FeedService> =>
+export const next = <T = Obj.Snapshot>(_cursor: Cursor<T>): Effect.Effect<T, never, Database.Service> =>
   Effect.die('Feed.next is not yet implemented');
 
 /**
  * Returns the next item from a feed cursor as an Option.
  * Currently stubbed — cursor operations are not yet implemented.
  */
-export const nextOption = <T = Obj.Snapshot>(_cursor: Cursor<T>): Effect.Effect<Option.Option<T>, never, FeedService> =>
-  Effect.die('Feed.nextOption is not yet implemented');
+export const nextOption = <T = Obj.Snapshot>(
+  _cursor: Cursor<T>,
+): Effect.Effect<Option.Option<T>, never, Database.Service> => Effect.die('Feed.nextOption is not yet implemented');
 
 /**
  * Sets the local retention policy for a feed.
@@ -348,5 +324,5 @@ export const nextOption = <T = Obj.Snapshot>(_cursor: Cursor<T>): Effect.Effect<
  * ```
  */
 // TODO(dmaretskyi): Implement when feed retention is supported.
-export const setRetention = (_feed: Feed, _options: RetentionOptions): Effect.Effect<void, never, FeedService> =>
+export const setRetention = (_feed: Feed, _options: RetentionOptions): Effect.Effect<void, never, Database.Service> =>
   Effect.void;

package/src/Filter.test.ts

@@ -4,7 +4,11 @@
 
 import { describe, expect, test } from 'vitest';
 
+import { DXN } from '@dxos/keys';
+
 import * as Filter from './Filter';
+import * as Obj from './Obj';
+import { TestSchema } from './testing/test-schema';
 
 describe('Filter timestamp builders', () => {
   test('updated({ after }) produces correct AST', () => {
@@ -88,3 +92,37 @@ describe('Filter timestamp builders', () => {
     expect(Filter.is(f)).toBe(true);
   });
 });
+
+describe('toPredicate', () => {
+  test('matches by type', () => {
+    const expando = Obj.make(TestSchema.Expando, { title: 'test' });
+    const match = Filter.toPredicate(Filter.type(TestSchema.Expando));
+    expect(match(expando)).toBe(true);
+  });
+
+  test('rejects wrong type', () => {
+    const person = Obj.make(TestSchema.Person, { name: 'Alice' });
+    const match = Filter.toPredicate(Filter.type(TestSchema.Expando));
+    expect(match(person)).toBe(false);
+  });
+
+  test('matches property constraints', () => {
+    const expando = Obj.make(TestSchema.Expando, { title: 'test', value: 100 });
+    const match = Filter.toPredicate(Filter.type(TestSchema.Expando, { title: 'test' }));
+    expect(match(expando)).toBe(true);
+    expect(Filter.toPredicate(Filter.type(TestSchema.Expando, { value: 200 }))(expando)).toBe(false);
+  });
+
+  test('matches or filters', () => {
+    const chat = DXN.make('org.dxos.type.assistant.chat', '0.1.0');
+    const agent = DXN.make('org.dxos.type.agent', '0.1.0');
+    const expando = Obj.make(TestSchema.Expando, {});
+    const match = Filter.toPredicate(Filter.or(Filter.type(chat), Filter.type(agent), Filter.type(TestSchema.Expando)));
+    expect(match(expando)).toBe(true);
+  });
+
+  test('dual form', () => {
+    const expando = Obj.make(TestSchema.Expando, {});
+    expect(Filter.toPredicate(expando, Filter.type(TestSchema.Expando))).toBe(true);
+  });
+});

package/src/Filter.ts

@@ -4,6 +4,7 @@
 
 // @import-as-namespace
 
+import * as Function from 'effect/Function';
 import * as Match from 'effect/Match';
 import * as Schema from 'effect/Schema';
 import * as SchemaAST from 'effect/SchemaAST';
@@ -13,17 +14,17 @@ import { type ForeignKey, type QueryAST } from '@dxos/echo-protocol';
 import { assertArgument } from '@dxos/invariant';
 import { EID, EntityId, type URI } from '@dxos/keys';
 
+import type * as Entity from './Entity';
 import * as internal from './internal';
 import type * as Obj from './Obj';
 import * as Ref from './Ref';
 // eslint-disable-next-line @dxos/rules/import-as-namespace
 import type * as Type$ from './Type';
-
 export interface Filter<T> {
   // TODO(dmaretskyi): See new effect-schema approach to variance.
   '~Filter': { value: Types.Covariant<T> };
 
-  ast: QueryAST.Filter;
+  'ast': QueryAST.Filter;
 }
 
 export type Props<T> = {
@@ -38,7 +39,7 @@ export type Type<F extends Any> = F extends Filter<infer T> ? T : never;
 class FilterClass implements Any {
   private static 'variance': Any['~Filter'] = {} as Any['~Filter'];
 
-  constructor(public readonly ast: QueryAST.Filter) {}
+  'constructor'(public readonly ast: QueryAST.Filter) {}
 
   '~Filter' = FilterClass.variance;
 }
@@ -482,3 +483,16 @@ const processPredicate = (predicate: any): QueryAST.Filter => {
  * Returns a human-readable string representation of a Filter AST.
  */
 export const pretty = (filter: Any): string => internal.prettyFilter(filter.ast);
+
+/**
+ * Create a predicate from a filter.
+ */
+export const toPredicate: {
+  <T extends Entity.Unknown>(filter: Filter<T>): (entity: Entity.Unknown) => entity is T;
+  <T extends Entity.Unknown>(entity: Entity.Unknown, filter: Filter<T>): entity is T;
+} = Function.dual<
+  <T extends Entity.Unknown>(filter: Filter<T>) => (entity: Entity.Unknown) => entity is T,
+  <T extends Entity.Unknown>(entity: Entity.Unknown, filter: Filter<T>) => entity is T
+>(2, <T extends Entity.Unknown>(entity: Entity.Unknown, filter: Filter<T>): entity is T =>
+  internal.filterMatchEntity(filter.ast, entity),
+);

package/src/Hypergraph.ts

@@ -6,7 +6,6 @@ import { type URI } from '@dxos/keys';
 
 import type * as Database from './Database';
 import type * as Entity from './Entity';
-import type * as internal from './internal';
 import type * as Key from './Key';
 import type * as Ref from './Ref';
 import type * as Registry from './Registry';
@@ -34,12 +33,6 @@ export interface RefResolverOptions {
    * Affects how non-absolute DXNs are resolved.
    */
   context?: RefResolutionContext;
-
-  /**
-   * Middleware to change the resolved object before returning it.
-   * @deprecated On track to be removed.
-   */
-  middleware?: (obj: internal.AnyProperties) => internal.AnyProperties;
 }
 
 /**
@@ -69,11 +62,9 @@ export interface Hypergraph extends Database.Queryable {
   makeRef<T extends Entity.Unknown = Entity.Unknown>(uri: URI.URI): Ref.Ref<T>;
 
   /**
-   * @param hostDb Host database for reference resolution.
-   * @param middleware Called with the loaded object. The caller may change the object.
-   * @returns Result of `onLoad`.
+   * Create a resolver that dereferences `Ref`s against this graph. Persisted schema objects are
+   * surfaced as their registered `Type.Type` entity.
    */
-  // TODO(dmaretskyi): Restructure API: Remove middleware.
   createRefResolver(options: RefResolverOptions): Ref.Resolver;
 
   /**

package/src/Migration.ts

@@ -10,7 +10,7 @@ import { type URI } from '@dxos/keys';
 
 import type * as Database from './Database';
 import type * as Entity from './Entity';
-import { MetaId, type EntityMeta, getSchemaURI } from './internal';
+import { type EntityMeta, MetaId, getSchemaURI } from './internal';
 import * as Type from './Type';
 
 /**