@dxos/echo 0.8.4-main.69d29f4 → 0.8.4-main.6fa680abb7

package/src/Feed.ts

@@ -0,0 +1,257 @@
+//
+// 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 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),
+}).pipe(
+  Type.object({
+    typename: 'org.dxos.type.feed',
+    version: '0.1.0',
+  }),
+  internal.SystemTypeAnnotation.set(true),
+);
+
+/**
+ * TypeScript instance type for a Feed object.
+ */
+export interface Feed extends Schema.Schema.Type<typeof Feed> {}
+
+//
+// Types
+//
+
+/**
+ * Meta key source for storing the backing DXN bound to a feed object.
+ */
+// TODO(dmaretskyi): Enforce that Feed ObjectId = feed storage ID. And remove this key.
+export const DXN_KEY = 'org.dxos.key.feed';
+
+/**
+ * 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;
+}
+
+//
+// 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);
+
+/**
+ * Reads the queue DXN from feed metadata.
+ *
+ * @deprecated
+ */
+// TODO(wittjosiah): Align backing feed dxn's with object DXN.
+export const getQueueDxn = (feed: Feed): DXN | undefined => {
+  const keys = Obj.getKeys(feed, DXN_KEY);
+  return keys.length === 0 ? undefined : DXN.parse(keys[0].id);
+};
+
+//
+// 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 Service extends Context.Tag('@dxos/echo/Feed/Service')<
+  Service,
+  {
+    /**
+     * 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>>;
+    };
+  }
+>() {}
+
+/**
+ * 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<Service> = Layer.succeed(Service, {
+  append: () => {
+    throw new Error('Feed.Service not available');
+  },
+  remove: () => {
+    throw new Error('Feed.Service not available');
+  },
+  query: () => {
+    throw new Error('Feed.Service not available');
+  },
+} as Context.Tag.Service<Service>);
+
+//
+// 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, Service> =>
+  Effect.gen(function* () {
+    const service = yield* Service;
+    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, Service> =>
+  Effect.gen(function* () {
+    const service = yield* Service;
+    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, Service>;
+  <F extends Filter.Any>(feed: Feed, filter: F): Effect.Effect<QueryResult.QueryResult<Filter.Type<F>>, never, Service>;
+} = (feed: Feed, queryOrFilter: Query.Any | Filter.Any) =>
+  Service.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, Service>;
+  <F extends Filter.Any>(feed: Feed, filter: F): Effect.Effect<Filter.Type<F>[], never, Service>;
+} = (feed: Feed, queryOrFilter: Query.Any | Filter.Any) =>
+  query(feed, queryOrFilter as any).pipe(Effect.flatMap((queryResult) => Effect.promise(() => queryResult.run())));
+
+/**
+ * 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, 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, 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, Service> =>
+  Effect.die('Feed.nextOption is not yet implemented');
+
+/**
+ * Sets the local retention policy for a feed.
+ * Currently stubbed — queues do not yet support retention.
+ *
+ * @example
+ * ```ts
+ * yield* Feed.setRetention(feed, { count: 1000 });
+ * ```
+ */
+// TODO(feed): Implement when queue retention is supported.
+export const setRetention = (_feed: Feed, _options: RetentionOptions): Effect.Effect<void, never, Service> =>
+  Effect.void;

package/src/Filter.ts

@@ -2,15 +2,18 @@
 // 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 * as Ref from './Ref';
 
 export interface Filter<T> {
@@ -30,7 +33,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 +104,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(),
@@ -180,7 +195,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(),

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';
@@ -39,7 +39,7 @@ 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;
 }
 
 /**

package/src/JsonSchema.ts

@@ -2,15 +2,25 @@
 // Copyright 2025 DXOS.org
 //
 
+// @import-as-namespace
+
 import type * as Schema from 'effect/Schema';
 
-import { JsonSchemaType } from './internal';
+import * as jsonSchemaInternal from './internal/JsonSchema';
+
+/**
+ * Decode JSON Schema to Effect Schema.
+ */
+export const toEffectSchema = jsonSchemaInternal.toEffectSchema;
 
-export { toEffectSchema, toJsonSchema } from './internal';
+/**
+ * Encode Effect Schema to JSON Schema.
+ */
+export const toJsonSchema = jsonSchemaInternal.toJsonSchema;
 
 /**
  * Serializable JsonSchema type definition.
  */
-export type JsonSchema = JsonSchemaType;
+export type JsonSchema = jsonSchemaInternal.JsonSchemaType;
 
-export const JsonSchema: Schema.Schema<JsonSchemaType> = JsonSchemaType;
+export const JsonSchema: Schema.Schema<jsonSchemaInternal.JsonSchemaType> = jsonSchemaInternal.JsonSchemaType;

package/src/Obj.test.ts

@@ -8,6 +8,7 @@ import * as Entity from './Entity';
 import { SnapshotKindId } from './internal';
 import * as Obj from './Obj';
 import * as Ref from './Ref';
+import * as Relation from './Relation';
 import { TestSchema } from './testing';
 
 describe('Obj', () => {
@@ -19,6 +20,10 @@ describe('Obj', () => {
       // Snapshot has SnapshotKindId, not KindId.
       expect(snapshot[SnapshotKindId]).toBe(Entity.Kind.Object);
       expect((snapshot as any)[Entity.KindId]).toBeUndefined();
+      expect(Obj.isSnapshot(snapshot)).toBe(true);
+      expect(Relation.isSnapshot(snapshot)).toBe(false);
+      expect(Entity.isEntity(snapshot)).toBe(false);
+      expect(Entity.isSnapshot(snapshot)).toBe(true);
 
       // Snapshot has same id and properties.
       expect(snapshot.id).toBe(obj.id);
@@ -41,8 +46,8 @@ describe('Obj', () => {
       expect(Obj.getDXN(snapshot)).toBeDefined();
 
       // getTypename - works with both.
-      expect(Obj.getTypename(obj)).toBe('example.com/type/Person');
-      expect(Obj.getTypename(snapshot)).toBe('example.com/type/Person');
+      expect(Obj.getTypename(obj)).toBe('com.example.type.person');
+      expect(Obj.getTypename(snapshot)).toBe('com.example.type.person');
 
       // getMeta - works with both.
       expect(Obj.getMeta(obj)).toBeDefined();
@@ -77,6 +82,62 @@ describe('Obj', () => {
     });
   });
 
+  describe('snapshotOf', () => {
+    test('returns true for snapshot of matching schema', ({ expect }) => {
+      const obj = Obj.make(TestSchema.Person, { name: 'Test' });
+      const snapshot = Obj.getSnapshot(obj);
+
+      expect(Obj.snapshotOf(TestSchema.Person, snapshot)).toBe(true);
+      expect(Obj.snapshotOf(TestSchema.Organization, snapshot)).toBe(false);
+    });
+
+    test('returns false for reactive object', ({ expect }) => {
+      const obj = Obj.make(TestSchema.Person, { name: 'Test' });
+
+      expect(Obj.snapshotOf(TestSchema.Person, obj)).toBe(false);
+    });
+
+    test('returns false for plain object with matching shape', ({ expect }) => {
+      const plain = { id: 'test', name: 'Test' };
+
+      expect(Obj.snapshotOf(TestSchema.Person, plain)).toBe(false);
+    });
+
+    test('curried form works', ({ expect }) => {
+      const snapshot = Obj.getSnapshot(Obj.make(TestSchema.Person, { name: 'Test' }));
+      const isPersonSnapshot = Obj.snapshotOf(TestSchema.Person);
+
+      expect(isPersonSnapshot(snapshot)).toBe(true);
+      expect(isPersonSnapshot({})).toBe(false);
+    });
+  });
+
+  describe('getKeys', () => {
+    const SOURCE = 'test-source';
+
+    test('returns keys from reactive object and snapshot', ({ expect }) => {
+      const obj = Obj.make(TestSchema.Person, { name: 'Test' });
+      Obj.change(obj, (o) => {
+        const meta = Obj.getMeta(o);
+        meta.keys.push({ source: SOURCE, id: 'key-1' });
+        meta.keys.push({ source: SOURCE, id: 'key-2' });
+        meta.keys.push({ source: 'other', id: 'key-3' });
+      });
+
+      expect(Obj.getKeys(obj, SOURCE)).toHaveLength(2);
+      expect(Obj.getKeys(obj, SOURCE).map((k) => k.id)).toEqual(['key-1', 'key-2']);
+
+      const snapshot = Obj.getSnapshot(obj);
+      expect(Obj.getKeys(snapshot, SOURCE)).toHaveLength(2);
+      expect(Obj.getKeys(snapshot, SOURCE).map((k) => k.id)).toEqual(['key-1', 'key-2']);
+    });
+
+    test('throws for plain object without metadata', ({ expect }) => {
+      const plain = { id: 'plain-1', name: 'Plain' };
+      expect(() => Obj.getKeys(plain as any, SOURCE)).toThrow(/ObjectMeta not found/);
+    });
+  });
+
   describe('clone', () => {
     test('clones object with same properties', ({ expect }) => {
       const original = Obj.make(TestSchema.Person, {