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

package/src/Feed.ts

@@ -0,0 +1,335 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+// @import-as-namespace
+
+import * as Context from 'effect/Context';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import type * as Option from 'effect/Option';
+import * as Schema from 'effect/Schema';
+
+import { DXN } from '@dxos/keys';
+
+import * as Annotation from './Annotation';
+import type * as Entity from './Entity';
+import type * as Filter from './Filter';
+import * as internal from './internal';
+import * as Obj from './Obj';
+import type * as Query from './Query';
+import type * as QueryResult from './QueryResult';
+import * as Type from './Type';
+
+/**
+ * Runtime schema for a Feed object.
+ *
+ * @example
+ * ```ts
+ * 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),
+
+  /**
+   * 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(
+  Type.object({
+    typename: 'org.dxos.type.feed',
+    version: '0.1.0',
+  }),
+  internal.SystemTypeAnnotation.set(true),
+  Annotation.IconAnnotation.set({
+    icon: 'ph--rows--regular',
+    hue: 'yellow',
+  }),
+);
+
+/**
+ * TypeScript instance type for a Feed object.
+ */
+export interface Feed extends Schema.Schema.Type<typeof Feed> {}
+
+//
+// Types
+//
+
+/**
+ * Opaque cursor for iterating over feed items.
+ */
+// TODO(dmaretskyi): T needs to be referenced in the type structure for typescript to respect it during inference and type-checking.
+export interface Cursor<T = Obj.Snapshot> {
+  readonly _tag: 'Cursor';
+}
+
+/**
+ * Retention options for a feed.
+ */
+export interface RetentionOptions {
+  /** Retain items after this cursor position. */
+  // TODO(wittjosiah): Use FeedCursor from @dxos/feed?
+  cursor?: string;
+}
+
+/**
+ * Sync options for a feed.
+ */
+export interface SyncOptions {
+  /** Push local changes to the server. Defaults to true. */
+  shouldPush?: boolean;
+  /** Pull remote changes from the server. Defaults to true. */
+  shouldPull?: boolean;
+}
+
+//
+// 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);
+
+/**
+ * Derives the queue DXN from the feed object's DXN.
+ * Returns `undefined` when the feed is not stored in a space yet.
+ *
+ * Used internally by the feed service layer.
+ */
+export const getQueueDxn = (feed: Feed): DXN | undefined => {
+  const self = Obj.getDXN(feed).asEchoDXN();
+  if (!self || !self.spaceId) {
+    return undefined;
+  }
+  return new DXN(DXN.kind.QUEUE, [feed.namespace ?? 'data', self.spaceId, self.echoId]);
+};
+
+//
+// Service
+//
+
+/**
+ * Effect service for feed operations.
+ * Provides the bridge to the underlying storage implementation.
+ * Must be provided by the application layer (e.g., echo-db).
+ */
+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.
+     */
+    // TODO(dmaretskyi): Change type to ObjectId.
+    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>;
+  }
+>() {}
+
+/**
+ * @deprecated Use `FeedService` instead.
+ */
+export type Service = FeedService;
+
+/**
+ * @deprecated Use `FeedService` instead.
+ */
+export const Service = FeedService;
+
+/**
+ * Layer that provides a Feed service that throws when accessed.
+ * Useful as a default layer when no feed service is available.
+ */
+export const notAvailable: Layer.Layer<FeedService> = Layer.succeed(FeedService, {
+  append: () => {
+    throw new Error('Feed.FeedService not available');
+  },
+  remove: () => {
+    throw new Error('Feed.FeedService not available');
+  },
+  query: () => {
+    throw new Error('Feed.FeedService not available');
+  },
+  sync: () => {
+    throw new Error('Feed.FeedService not available');
+  },
+} as Context.Tag.Service<FeedService>);
+
+//
+// Context (per-call) service
+//
+
+/**
+ * Effect service exposing a single `Feed.Feed` as the "current" feed for a call site.
+ *
+ * @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 });
+}
+
+//
+// Operations
+//
+
+/**
+ * Appends items to a feed.
+ *
+ * @example
+ * ```ts
+ * 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));
+  });
+
+/**
+ * Removes items from a feed.
+ *
+ * @example
+ * ```ts
+ * yield* Feed.remove(feed, [item]);
+ * ```
+ */
+// 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));
+  });
+
+/**
+ * Creates a reactive query over items in a feed.
+ *
+ * @example
+ * ```ts
+ * const result = yield* Feed.query(feed, Filter.type(Person));
+ * ```
+ */
+// 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,
+  ): Effect.Effect<QueryResult.QueryResult<Query.Type<Q>>, never, FeedService>;
+  <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())));
+
+/**
+ * Syncs the feed with the server.
+ *
+ * @example
+ * ```ts
+ * yield* Feed.sync(feed);
+ * 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));
+  });
+
+/**
+ * Creates a cursor for iterating over feed items.
+ * Currently stubbed — cursor operations are not yet implemented.
+ *
+ * @example
+ * ```ts
+ * const cursor = yield* Feed.cursor<Person>(feed);
+ * const item = yield* Feed.next(cursor);
+ * ```
+ */
+// TODO(wittjosiah): Implement cursor operations. Use Effect streams?
+export const cursor = <T = Obj.Snapshot>(_feed: Feed): Effect.Effect<Cursor<T>, never, FeedService> =>
+  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> =>
+  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');
+
+/**
+ * Sets the local retention policy for a feed.
+ * Currently stubbed — feeds do not yet support retention.
+ *
+ * @example
+ * ```ts
+ * yield* Feed.setRetention(feed, { count: 1000 });
+ * ```
+ */
+// TODO(dmaretskyi): Implement when feed retention is supported.
+export const setRetention = (_feed: Feed, _options: RetentionOptions): Effect.Effect<void, never, FeedService> =>
+  Effect.void;

package/src/Filter.test.ts

@@ -0,0 +1,90 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, expect, test } from 'vitest';
+
+import * as Filter from './Filter';
+
+describe('Filter timestamp builders', () => {
+  test('updated({ after }) produces correct AST', () => {
+    const ts = 1700000000000;
+    const f = Filter.updated({ after: ts });
+    expect(f.ast).toEqual({ type: 'timestamp', field: 'updatedAt', operator: 'gte', value: ts });
+  });
+
+  test('updated({ before }) produces correct AST', () => {
+    const ts = 1700000000000;
+    const f = Filter.updated({ before: ts });
+    expect(f.ast).toEqual({ type: 'timestamp', field: 'updatedAt', operator: 'lte', value: ts });
+  });
+
+  test('created({ after }) produces correct AST', () => {
+    const ts = 1700000000000;
+    const f = Filter.created({ after: ts });
+    expect(f.ast).toEqual({ type: 'timestamp', field: 'createdAt', operator: 'gte', value: ts });
+  });
+
+  test('created({ before }) produces correct AST', () => {
+    const ts = 1700000000000;
+    const f = Filter.created({ before: ts });
+    expect(f.ast).toEqual({ type: 'timestamp', field: 'createdAt', operator: 'lte', value: ts });
+  });
+
+  test('updated() accepts Date objects', () => {
+    const date = new Date('2026-03-20T21:00:00Z');
+    const f = Filter.updated({ after: date });
+    expect(f.ast).toEqual({ type: 'timestamp', field: 'updatedAt', operator: 'gte', value: date.getTime() });
+  });
+
+  test('created() accepts Date objects', () => {
+    const date = new Date('2026-03-20T09:00:00Z');
+    const f = Filter.created({ before: date });
+    expect(f.ast).toEqual({ type: 'timestamp', field: 'createdAt', operator: 'lte', value: date.getTime() });
+  });
+
+  test('updated({ after, before }) produces AND of two timestamp nodes', () => {
+    const from = 1700000000000;
+    const to = 1700086400000;
+    const f = Filter.updated({ after: from, before: to });
+    expect(f.ast).toEqual({
+      type: 'and',
+      filters: [
+        { type: 'timestamp', field: 'updatedAt', operator: 'gte', value: from },
+        { type: 'timestamp', field: 'updatedAt', operator: 'lte', value: to },
+      ],
+    });
+  });
+
+  test('updated({ after, before }) accepts Date objects', () => {
+    const from = new Date('2026-03-19T00:00:00Z');
+    const to = new Date('2026-03-20T00:00:00Z');
+    const f = Filter.updated({ after: from, before: to });
+    expect(f.ast).toEqual({
+      type: 'and',
+      filters: [
+        { type: 'timestamp', field: 'updatedAt', operator: 'gte', value: from.getTime() },
+        { type: 'timestamp', field: 'updatedAt', operator: 'lte', value: to.getTime() },
+      ],
+    });
+  });
+
+  test('timestamp filters compose with and()', () => {
+    const typeFilter = Filter.everything();
+    const timeFilter = Filter.updated({ after: 1700000000000 });
+    const combined = Filter.and(typeFilter, timeFilter);
+    expect(combined.ast.type).toBe('and');
+    expect((combined.ast as any).filters).toHaveLength(2);
+    expect((combined.ast as any).filters[1]).toEqual({
+      type: 'timestamp',
+      field: 'updatedAt',
+      operator: 'gte',
+      value: 1700000000000,
+    });
+  });
+
+  test('timestamp filters pass the is() check', () => {
+    const f = Filter.updated({ after: Date.now() });
+    expect(Filter.is(f)).toBe(true);
+  });
+});

package/src/Filter.ts

@@ -2,20 +2,24 @@
 // Copyright 2025 DXOS.org
 //
 
+// @import-as-namespace
+
 import * as Match from 'effect/Match';
 import * as Schema from 'effect/Schema';
+import * as SchemaAST from 'effect/SchemaAST';
 import type * as Types from 'effect/Types';
 
 import { type ForeignKey, type QueryAST } from '@dxos/echo-protocol';
 import { assertArgument } from '@dxos/invariant';
 import { DXN, ObjectId } from '@dxos/keys';
 
-import { getTypeDXNFromSpecifier } from './internal';
+import * as internal from './internal';
+import type * as Obj from './Obj';
 import * as Ref from './Ref';
 
 export interface Filter<T> {
   // TODO(dmaretskyi): See new effect-schema approach to variance.
-  '~Filter': { value: Types.Contravariant<T> };
+  '~Filter': { value: Types.Covariant<T> };
 
   ast: QueryAST.Filter;
 }
@@ -30,7 +34,7 @@ export type Any = Filter<any>;
 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'];
+  private static 'variance': Any['~Filter'] = {} as Any['~Filter'];
 
   constructor(public readonly ast: QueryAST.Filter) {}
 
@@ -101,7 +105,19 @@ export const type = <S extends Schema.Schema.All>(
   schema: S | string,
   props?: Props<Schema.Schema.Type<S>>,
 ): Filter<Schema.Schema.Type<S>> => {
-  const dxn = getTypeDXNFromSpecifier(schema);
+  if (Schema.isSchema(schema) && SchemaAST.isUnion(schema.ast)) {
+    const typenames = schema.ast.types.map((type) => internal.getTypeDXNFromSpecifier(Schema.make(type)));
+    return new FilterClass({
+      type: 'or',
+      filters: typenames.map((typename) => ({
+        type: 'object',
+        typename: typename.toString(),
+        props: {},
+      })),
+    });
+  }
+
+  const dxn = internal.getTypeDXNFromSpecifier(schema);
   return new FilterClass({
     type: 'object',
     typename: dxn.toString(),
@@ -142,6 +158,37 @@ export const tag = (tag: string): Any => {
   });
 };
 
+/**
+ * Options for {@link key} filter.
+ */
+export type KeyFilterOptions = {
+  /**
+   * Optional semver range expression (e.g. `^1.2.3`, `~2.0.0`, `>=1.0.0 <2.0.0`).
+   * Matches the object's meta `version` field against the range.
+   * If omitted, matches any version (including objects with no version).
+   */
+  version?: string;
+};
+
+/**
+ * Filter by registry key stored in object meta.
+ *
+ * @example
+ * ```ts
+ * Filter.key('org.example.type.foo');
+ * Filter.key('org.example.type.foo', { version: '^1.2.3' });
+ * ```
+ */
+export const key = (key: string, options?: KeyFilterOptions): Any => {
+  return new FilterClass({
+    type: 'object',
+    typename: null,
+    props: {},
+    metaKey: key,
+    metaVersion: options?.version,
+  });
+};
+
 /**
  * Filter by properties.
  */
@@ -180,7 +227,7 @@ export const foreignKeys = <S extends Schema.Schema.All>(
   schema: S | string,
   keys: ForeignKey[],
 ): Filter<Schema.Schema.Type<S>> => {
-  const dxn = getTypeDXNFromSpecifier(schema);
+  const dxn = internal.getTypeDXNFromSpecifier(schema);
   return new FilterClass({
     type: 'object',
     typename: dxn.toString(),
@@ -263,7 +310,7 @@ export const lte = <T>(value: T): Filter<T | undefined> => {
  * Predicate for property to be in the provided array.
  * @param values - Values to check against.
  */
-const in$ = <T>(...values: T[]): Filter<T | undefined> => {
+const in$ = <T>(...values: T[]): Filter<T> => {
   return new FilterClass({
     type: 'in',
     values,
@@ -287,7 +334,7 @@ export const contains = <T>(value: T): Filter<readonly T[] | undefined> => {
  * @param from - Start of the range (inclusive).
  * @param to - End of the range (exclusive).
  */
-export const between = <T>(from: T, to: T): Filter<unknown> => {
+export const between = <T>(from: T, to: T): Filter<T> => {
   return new FilterClass({
     type: 'range',
     from,
@@ -295,6 +342,63 @@ export const between = <T>(from: T, to: T): Filter<unknown> => {
   });
 };
 
+type TimeRange = { after?: Date | number; before?: Date | number };
+
+const _toUnixMs = (date: Date | number): number => (typeof date === 'number' ? date : date.getTime());
+
+const _timeRangeFilter = (field: 'updatedAt' | 'createdAt', range: TimeRange): Any => {
+  const filters: Any[] = [];
+  if (range.after != null) {
+    filters.push(new FilterClass({ type: 'timestamp', field, operator: 'gte', value: _toUnixMs(range.after) }));
+  }
+  if (range.before != null) {
+    filters.push(new FilterClass({ type: 'timestamp', field, operator: 'lte', value: _toUnixMs(range.before) }));
+  }
+  if (filters.length === 0) {
+    return everything();
+  }
+  return filters.length === 1 ? filters[0] : and(...filters);
+};
+
+/**
+ * Filter objects by updatedAt timestamp.
+ */
+export const updated = (range: TimeRange): Any => _timeRangeFilter('updatedAt', range);
+
+/**
+ * Filter objects by createdAt timestamp.
+ */
+export const created = (range: TimeRange): Any => _timeRangeFilter('createdAt', range);
+
+export type ChildOfOptions = {
+  /** Whether to match transitively (grandchildren, etc.). Defaults to true. */
+  transitive?: boolean;
+};
+
+/**
+ * Filter objects that are children of the specified parent(s).
+ * Accepts ECHO objects, Refs, or arrays of either.
+ * Refs are resolved to DXNs without loading; objects use {@link Obj.getDXN}.
+ * With transitive=true (default), also matches grandchildren and beyond.
+ */
+export const childOf = (
+  parents: Obj.Unknown | Ref.Unknown | readonly (Obj.Unknown | Ref.Unknown)[],
+  options?: ChildOfOptions,
+): Any => {
+  const items = Array.isArray(parents) ? parents : [parents];
+  const dxns = items.map((item) => {
+    if (Ref.isRef(item)) {
+      return item.dxn.toString();
+    }
+    return internal.getDXN(item).toString();
+  });
+  return new FilterClass({
+    type: 'child-of',
+    parents: dxns,
+    transitive: options?.transitive ?? true,
+  });
+};
+
 /**
  * Negate the filter.
  */
@@ -374,3 +478,8 @@ const processPredicate = (predicate: any): QueryAST.Filter => {
     Match.orElse((value) => eq(value).ast),
   );
 };
+
+/**
+ * Returns a human-readable string representation of a Filter AST.
+ */
+export const pretty = (filter: Any): string => internal.prettyFilter(filter.ast);

package/src/Format.ts

@@ -2,8 +2,8 @@
 // Copyright 2025 DXOS.org
 //
 
-import { type TypeFormat as Format } from './internal';
+import type * as internal from './internal';
 
-export * from './internal/formats';
+export * from './internal/Format';
 
-export type { Format };
+export type Format = internal.TypeFormat;

package/src/Hypergraph.ts

@@ -6,7 +6,7 @@ import { type DXN } from '@dxos/keys';
 
 import type * as Database from './Database';
 import type * as Entity from './Entity';
-import { type AnyProperties } from './internal';
+import type * as internal from './internal';
 import type * as Key from './Key';
 import type * as Ref from './Ref';
 import type * as SchemaRegistry from './SchemaRegistry';
@@ -22,10 +22,10 @@ export interface RefResolutionContext {
   space?: Key.SpaceId;
 
   /**
-   * Queue that the resolution is happening from.
-   * This queue will be searched first, and then the space it belongs to.
+   * Feed that the resolution is happening from (as the underlying queue DXN).
+   * This feed will be searched first, and then the space it belongs to.
    */
-  queue?: DXN;
+  feed?: DXN;
 }
 
 export interface RefResolverOptions {
@@ -39,13 +39,12 @@ export interface RefResolverOptions {
    * Middleware to change the resolved object before returning it.
    * @deprecated On track to be removed.
    */
-  middleware?: (obj: AnyProperties) => AnyProperties;
+  middleware?: (obj: internal.AnyProperties) => internal.AnyProperties;
 }
 
 /**
- *
+ * Manages cross-space database interactions.
  */
-// TODO(burdon): Comment required.
 export interface Hypergraph extends Database.Queryable {
   get schemaRegistry(): SchemaRegistry.SchemaRegistry;
 
@@ -71,4 +70,10 @@ export interface Hypergraph extends Database.Queryable {
    */
   // TODO(dmaretskyi): Restructure API: Remove middleware.
   createRefResolver(options: RefResolverOptions): Ref.Resolver;
+
+  /**
+   * Get a database by space ID.
+   * @returns The database for the given space ID, or undefined if not found.
+   */
+  getDatabase(spaceId: Key.SpaceId): Database.Database | undefined;
 }