@dxos/echo 0.8.4-main.bc674ce → 0.8.4-main.bcb3aa67d6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dxos/echo",
-  "version": "0.8.4-main.bc674ce",
+  "version": "0.8.4-main.bcb3aa67d6",
   "description": "ECHO API",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
@@ -48,6 +48,11 @@
       "types": "./dist/types/src/Err.d.ts",
       "default": "./dist/lib/neutral/Err.mjs"
     },
+    "./Feed": {
+      "source": "./src/Feed.ts",
+      "types": "./dist/types/src/Feed.d.ts",
+      "default": "./dist/lib/neutral/Feed.mjs"
+    },
     "./Filter": {
       "source": "./src/Filter.ts",
       "types": "./dist/types/src/Filter.d.ts",
@@ -112,6 +117,11 @@
       "source": "./src/Type.ts",
       "types": "./dist/types/src/Type.d.ts",
       "default": "./dist/lib/neutral/Type.mjs"
+    },
+    "./Extension": {
+      "source": "./src/Extension.ts",
+      "types": "./dist/types/src/Extension.d.ts",
+      "default": "./dist/lib/neutral/Extension.mjs"
     }
   },
   "files": [
@@ -119,19 +129,19 @@
     "src"
   ],
   "dependencies": {
-    "effect": "3.19.11",
-    "@dxos/context": "0.8.4-main.bc674ce",
-    "@dxos/debug": "0.8.4-main.bc674ce",
-    "@dxos/echo-protocol": "0.8.4-main.bc674ce",
-    "@dxos/effect": "0.8.4-main.bc674ce",
-    "@dxos/errors": "0.8.4-main.bc674ce",
-    "@dxos/invariant": "0.8.4-main.bc674ce",
-    "@dxos/log": "0.8.4-main.bc674ce",
-    "@dxos/keys": "0.8.4-main.bc674ce",
-    "@dxos/node-std": "0.8.4-main.bc674ce",
-    "@dxos/protocols": "0.8.4-main.bc674ce",
-    "@dxos/async": "0.8.4-main.bc674ce",
-    "@dxos/util": "0.8.4-main.bc674ce"
+    "effect": "3.20.0",
+    "@dxos/async": "0.8.4-main.bcb3aa67d6",
+    "@dxos/context": "0.8.4-main.bcb3aa67d6",
+    "@dxos/echo-protocol": "0.8.4-main.bcb3aa67d6",
+    "@dxos/debug": "0.8.4-main.bcb3aa67d6",
+    "@dxos/errors": "0.8.4-main.bcb3aa67d6",
+    "@dxos/effect": "0.8.4-main.bcb3aa67d6",
+    "@dxos/invariant": "0.8.4-main.bcb3aa67d6",
+    "@dxos/keys": "0.8.4-main.bcb3aa67d6",
+    "@dxos/log": "0.8.4-main.bcb3aa67d6",
+    "@dxos/util": "0.8.4-main.bcb3aa67d6",
+    "@dxos/node-std": "0.8.4-main.bcb3aa67d6",
+    "@dxos/protocols": "0.8.4-main.bcb3aa67d6"
   },
   "publishConfig": {
     "access": "public"

package/src/Annotation.ts

@@ -2,6 +2,8 @@
 // Copyright 2025 DXOS.org
 //
 
+// @import-as-namespace
+
 export {
   DescriptionAnnotation,
   FormInputAnnotation,
@@ -15,4 +17,32 @@ export {
   getTypeAnnotation,
   setDescriptionWithSchema,
   setLabelWithSchema,
-} from './internal/annotations';
+  IconAnnotation,
+} from './internal/Annotation';
+
+import type * as Schema from 'effect/Schema';
+
+import * as internalAnnotations from './internal/Annotation';
+
+interface MakeProps<T> {
+  id: string;
+  schema: Schema.Schema<T, any, never>;
+}
+
+/**
+ * Create a new schema annotation.
+ * Annotation can be assigned both to fields and to the schema itself.
+ * Annotation is serialized with the schema.
+ *
+ * @example
+ * ```ts
+ * const ColorAnnotation = Annotation.make({
+ *   id: 'org.dxos.annotation.color',
+ *   schema: Schema.String,
+ * });
+ *
+ * const schema = Schema.String.annotations(ColorAnnotation.set('red'));
+ * ```
+ */
+export const make: <T>(props: MakeProps<T>) => internalAnnotations.AnnotationHelper<T> =
+  internalAnnotations.makeUserAnnotation;

package/src/Collection.ts

@@ -0,0 +1,37 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+// @import-as-namespace
+
+import * as Schema from 'effect/Schema';
+
+import * as internal from './internal';
+import * as Annotation from './Annotation';
+import * as Obj from './Obj';
+import * as Ref from './Ref';
+import * as Type from './Type';
+
+/**
+ * A an ordered set of objects.
+ */
+export const Collection = Schema.Struct({
+  name: Schema.String.pipe(Schema.optional),
+  objects: Schema.Array(Ref.Ref(Obj.Unknown)).pipe(internal.FormInputAnnotation.set(false)),
+}).pipe(
+  Type.object({
+    typename: 'org.dxos.type.collection',
+    version: '0.1.0',
+  }),
+  Annotation.IconAnnotation.set({
+    icon: 'ph--folder--regular',
+    hue: 'neutral',
+  }),
+);
+
+export interface Collection extends Schema.Schema.Type<typeof Collection> {}
+
+export const make = (props: Partial<Obj.MakeProps<typeof Collection>> = {}): Collection =>
+  Obj.make(Collection, { objects: [], ...props });
+
+export const isCollection: (value: unknown) => value is Collection = Obj.instanceOf(Collection);

package/src/Database.ts

@@ -2,6 +2,8 @@
 // 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';
@@ -9,71 +11,30 @@ import * as Option from 'effect/Option';
 import * as Schema from 'effect/Schema';
 import type * as Types from 'effect/Types';
 
-import { type QueryAST } from '@dxos/echo-protocol';
 import { promiseWithCauseCapture } from '@dxos/effect';
 import { invariant } from '@dxos/invariant';
-import { DXN, type PublicKey, type SpaceId } from '@dxos/keys';
-import { type QueryOptions as QueryOptionsProto } from '@dxos/protocols/proto/dxos/echo/filter';
+import { DXN, type SpaceId } from '@dxos/keys';
 
 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/annotations';
-import type { Ref } from './internal/ref/ref';
-import { type AnyProperties } from './internal/types';
+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';
 
-/**
- * @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.QueryResult<Query.Type<Q>>;
-
-  <F extends Filter.Any>(
-    filter: F,
-    options?: (QueryAST.QueryOptions & QueryOptions) | undefined,
-  ): QueryResult.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>>;
 }
 
 /**
@@ -110,7 +71,7 @@ export type FlushOptions = {
 
   /**
    * Wait for pending index updates.
-   * @default false
+   * @default true
    */
   indexes?: boolean;
 
@@ -145,7 +106,10 @@ export interface Database extends Queryable {
   /**
    * Return object by local ID.
    */
-  getObjectById<T extends Obj.Unknown = Obj.Obj<AnyProperties>>(id: string, opts?: GetObjectByIdOptions): T | undefined;
+  getObjectById<T extends Obj.Unknown = Obj.OfShape<AnyProperties>>(
+    id: string,
+    opts?: GetObjectByIdOptions,
+  ): T | undefined;
 
   /**
    * Query objects.
@@ -186,151 +150,181 @@ export const isDatabase = (obj: unknown): obj is Database => {
 
 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;
   }
->() {
-  static notAvailable = Layer.succeed(Service, {
-    get db(): Database {
-      throw new Error('Database not available');
-    },
-  });
-
-  static make = (db: Database): Context.Tag.Service<Service> => {
-    return {
-      get db() {
-        return db;
-      },
-    };
-  };
+>() {}
+
+/**
+ * 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');
+  },
+});
 
-  static layer = (db: Database): Layer.Layer<Service> => {
-    return Layer.succeed(Service, Service.make(db));
+/**
+ * Creates a Database service instance from a Database.
+ */
+export const makeService = (db: Database): Context.Tag.Service<Service> => {
+  return {
+    get db() {
+      return db;
+    },
   };
+};
 
-  // TODO(dmaretskyi): Move all those to the top-level API of Database.ts module.
+/**
+ * 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.
-   */
-  static spaceId = Effect.gen(function* () {
-    const { db } = yield* Service;
-    return db.spaceId;
-  });
+/**
+ * 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.
-   */
-  static resolve: {
-    // No type check.
-    (ref: DXN | Ref<any>): Effect.Effect<Entity.Unknown, never, Service>;
-    // Check matches schema.
-    <S extends Type.Entity.Any>(
-      ref: DXN | Ref<any>,
-      schema: S,
-    ): Effect.Effect<Schema.Schema.Type<S>, Err.ObjectNotFoundError, Service>;
-  } = (<S extends Type.Entity.Any>(
+/**
+ * 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> =>
-    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;
+    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),
+    );
 
-  /**
-   * Loads an object reference.
-   */
-  static 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 yield* Effect.fail(new Err.ObjectNotFoundError(dxn));
     }
-    return object;
-  });
+    invariant(!schema || isInstanceOf(schema, object), 'Object type mismatch.');
+    return object as any;
+  })) as any;
 
-  /**
-   * Loads an object reference option.
-   */
-  // TODO(dmaretskyi): Do we need this -- you can just use `Effect.catchTag` in calling code instead.
-  static loadOption: <T>(ref: Ref<T>) => Effect.Effect<Option.Option<T>, never, never> = Effect.fn(function* (ref) {
-    const object = yield* Service.load(ref).pipe(
-      Effect.catchTag('ObjectNotFoundError', () => Effect.succeed(undefined)),
-    );
+/**
+ * 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;
+});
 
-    return Option.fromNullable(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)));
 
-  /**
-   * @link EchoDatabase.add
-   */
-  static add = <T extends Entity.Unknown>(obj: T): Effect.Effect<T, never, Service> =>
-    Service.pipe(Effect.map(({ db }) => db.add(obj)));
+  return Option.fromNullable(object);
+});
 
-  /**
-   * @link EchoDatabase.remove
-   */
-  static remove = <T extends Entity.Unknown>(obj: T): Effect.Effect<void, never, Service> =>
-    Service.pipe(Effect.map(({ db }) => db.remove(obj)));
+/**
+ * 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)));
 
-  /**
-   * @link EchoDatabase.flush
-   */
-  static flush = (opts?: FlushOptions) =>
-    Service.pipe(Effect.flatMap(({ db }) => promiseWithCauseCapture(() => db.flush(opts))));
+/**
+ * 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)));
 
-  /**
-   * Creates a `QueryResult` object that can be subscribed to.
-   */
-  static 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('Service.query'),
-    );
+/**
+ * Flushes pending changes to disk.
+ * @see {@link Database.flush}
+ */
+export const flush = (opts?: FlushOptions) =>
+  Service.pipe(Effect.flatMap(({ db }) => promiseWithCauseCapture(() => db.flush(opts))));
 
-  /**
-   * Executes the query once and returns the results.
-   */
-  static 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) =>
-    Service.query(queryOrFilter as any).pipe(
-      Effect.flatMap((queryResult) => promiseWithCauseCapture(() => queryResult.run())),
-    );
+/**
+ * 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'),
+  );
 
-  // TODO(dmaretskyi): Change API to `yield* Service.querySchema(...).first` and `yield* Service.querySchema(...).schema`.
+/**
+ * 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())));
 
-  static schemaQuery = <Q extends Types.NoExcessProperties<SchemaRegistry.Query, Q>>(
-    query?: Q & SchemaRegistry.Query,
-  ): Effect.Effect<QueryResult.QueryResult<SchemaRegistry.ExtractQueryResult<Q>>, never, Service> =>
-    Service.pipe(
-      Effect.map(({ db }) => db.schemaRegistry.query(query)),
-      Effect.withSpan('Service.schemaQuery'),
-    );
+/**
+ * Executes the query once and returns the first result as or None.
+ */
+export const runQueryFirst: {
+  <Q extends Query.Any>(query: Q): Effect.Effect<Option.Option<Query.Type<Q>>, never, Service>;
+  <F extends Filter.Any>(filter: F): Effect.Effect<Option.Option<Filter.Type<F>>, never, Service>;
+} = (queryOrFilter: Query.Any | Filter.Any) =>
+  query(queryOrFilter as any).pipe(
+    Effect.flatMap((queryResult) =>
+      promiseWithCauseCapture(async () => Option.fromNullable(await queryResult.firstOrUndefined())),
+    ),
+  );
 
-  static runSchemaQuery = <Q extends Types.NoExcessProperties<SchemaRegistry.Query, Q>>(
-    query?: Q & SchemaRegistry.Query,
-  ): Effect.Effect<SchemaRegistry.ExtractQueryResult<Q>[], never, Service> =>
-    Service.schemaQuery(query).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)),
+);