@dxos/echo 0.8.4-main.fd6878d → 0.8.4-staging.60fe92afc8

package/src/Annotation.ts

@@ -0,0 +1,202 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+// @import-as-namespace
+
+export {
+  DescriptionAnnotation,
+  FieldLookupAnnotationId,
+  FormInputAnnotation,
+  FormInlineAnnotation,
+  GeneratorAnnotation,
+  GeneratorAnnotationId,
+  type GeneratorAnnotationValue,
+  LabelAnnotation,
+  ReferenceAnnotation,
+  ReferenceAnnotationId,
+  type ReferenceAnnotationValue,
+  HiddenAnnotation,
+  TypeAnnotation,
+  getDescriptionWithSchema,
+  getLabelWithSchema,
+  getTypeAnnotation,
+  getTypeIdentifierAnnotation,
+  setDescriptionWithSchema,
+  setLabelWithSchema,
+  IconAnnotation,
+  IconFromRefAnnotation,
+} from './internal/Annotation';
+
+import * as Function from 'effect/Function';
+import * as Option from 'effect/Option';
+import * as Schema from 'effect/Schema';
+import * as SchemaAST from 'effect/SchemaAST';
+import * as Types from 'effect/Types';
+
+import * as Entity from './Entity';
+import * as internalAnnotations from './internal/Annotation';
+
+export const TypeId = '~@dxos/echo/Annotation' as const;
+export type TypeId = typeof TypeId;
+
+// TODO(dmaretskyi): Reconcile different get/set styles: mutate in-place, return.
+// TODO(dmaretskyi): Reconcile Annotation methods vs static functions.
+// TODO(dmaretskyi): Reconcile Annotation.Key vs DXN -- work-out approach to versioning.
+
+/**
+ * Annotation is a typed property that can be assigned to a schema or an entity instance.
+ */
+export interface Annotation<T> {
+  [TypeId]: {
+    _Type: T;
+  };
+
+  // TODO(dmaretskyi): Make this a DXN?
+  /**
+   * Unique fully-qualified identifier for the annotation.
+   * @example "org.dxos.annotation.color"
+   */
+  readonly key: Key;
+
+  /**
+   * Schema of the annotation value.
+   */
+  readonly schema: Schema.Schema<T, unknown, never>;
+
+  /**
+   * Get the annotation value from an Effect schema.
+   *
+   * Only accepts `Schema.Schema.Any` — to read an annotation off a `Type.Type`
+   * entity, unwrap it first with `Type.getSchema(entity)`. This keeps the
+   * annotation pipeline single-shaped and forces annotations to live on the
+   * source schema, not on the post-construction Type entity.
+   */
+  get: (schema: Schema.Schema.Any) => Option.Option<T>;
+  /**
+   * Get the annotation value from the AST.
+   */
+  getFromAst: (ast: SchemaAST.AST) => Option.Option<T>;
+  /**
+   * Set the annotation on an Effect schema.
+   *
+   * Only accepts `Schema.Schema.Any` — annotations must be applied to the
+   * source schema BEFORE wrapping it with `Type.makeObject` / `Type.makeRelation`.
+   * In a pipe, place every `Annotation.X.set(...)` before the `Type.make...` step.
+   */
+  set: (value: T) => <S extends Schema.Schema.Any>(schema: S) => S;
+}
+
+export const Key = internalAnnotations.Key;
+export type Key = Schema.Schema.Type<typeof Key>;
+
+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>) => Annotation<T> = internalAnnotations.makeUserAnnotation;
+
+/**
+ * Get the value of an annotation from an entity instance or snapshot.
+ * For schema-level reads use the annotation instance method (e.g. `ColorAnnotation.get(schema)`).
+ * For getting an annotation value from a dictionary, use `getDictionary`.
+ */
+export const get: {
+  <T>(annotation: Annotation<T>): (target: Entity.Unknown | Entity.Snapshot) => Option.Option<T>;
+  <T>(target: Entity.Unknown | Entity.Snapshot, annotation: Annotation<T>): Option.Option<T>;
+} = Function.dual<
+  <T>(annotation: Annotation<T>) => (target: Entity.Unknown | Entity.Snapshot) => Option.Option<T>,
+  <T>(target: Entity.Unknown | Entity.Snapshot, annotation: Annotation<T>) => Option.Option<T>
+>(2, (target, annotation) => {
+  return internalAnnotations.get(target, annotation);
+});
+
+/**
+ * Set the value of an annotation on an entity instance.
+ * For schema-level writes use the annotation instance method (e.g. `ColorAnnotation.set('red')`).
+ * For setting an annotation value on a dictionary, use `setDictionary`.
+ */
+export const set: {
+  <T>(annotation: Annotation<T>, value: T): (target: Entity.Mutable<Entity.Unknown>) => void;
+  <T>(target: Entity.Mutable<Entity.Unknown>, annotation: Annotation<T>, value: T): void;
+} = Function.dual<
+  <T>(annotation: Annotation<T>, value: T) => (target: Entity.Mutable<Entity.Unknown>) => void,
+  <T>(target: Entity.Mutable<Entity.Unknown>, annotation: Annotation<T>, value: T) => void
+>(3, (target, annotation, value) => {
+  return internalAnnotations.set(target, annotation, value);
+});
+
+export const getFromAst: {
+  <T>(annotation: Annotation<T>): (ast: SchemaAST.AST) => Option.Option<T>;
+  <T>(ast: SchemaAST.AST, annotation: Annotation<T>): Option.Option<T>;
+} = Function.dual<
+  <T>(annotation: Annotation<T>) => (ast: SchemaAST.AST) => Option.Option<T>,
+  <T>(ast: SchemaAST.AST, annotation: Annotation<T>) => Option.Option<T>
+>(2, (ast, annotation) => {
+  return internalAnnotations.getFromAst(ast, annotation);
+});
+
+/**
+ * Set of annotation values.
+ *
+ * Can be used inside an object/relation schema:
+ *
+ * ```ts
+ * const Person = Schema.Struct({
+ *   name: Schema.String,
+ *   extensions: Annotation.Dictionary,
+ * });
+ * ```
+ */
+export const Dictionary = internalAnnotations.Dictionary;
+export interface Dictionary extends Schema.Schema.Type<typeof Dictionary> {}
+
+/**
+ * Get the value of an annotation from a Dictionary.
+ */
+export const getDictionary: {
+  <T>(annotation: Annotation<T>): (values: Dictionary) => Option.Option<T>;
+  <T>(values: Dictionary, annotation: Annotation<T>): Option.Option<T>;
+} = Function.dual<
+  <T>(annotation: Annotation<T>) => (values: Dictionary) => Option.Option<T>,
+  <T>(values: Dictionary, annotation: Annotation<T>) => Option.Option<T>
+>(2, (values, annotation) => {
+  return internalAnnotations.getDictionary(values, annotation);
+});
+
+/**
+ * Set the value of an annotation in a Dictionary.
+ *
+ * Can also be used within Obj.update callback:
+ *
+ * ```ts
+ * Obj.update(obj, (obj) => {
+ *   Annotation.setDictionary(obj.annotations, ColorAnnotation, 'red');
+ * });
+ * ```
+ */
+export const setDictionary: {
+  <T>(annotation: Annotation<T>, value: T): (values: Dictionary) => void;
+  <T>(values: Types.Mutable<Dictionary>, annotation: Annotation<T>, value: T): void;
+} = Function.dual<
+  <T>(annotation: Annotation<T>, value: T) => (values: Dictionary) => void,
+  <T>(values: Types.Mutable<Dictionary>, annotation: Annotation<T>, value: T) => void
+>(3, (values, annotation, value) => {
+  return internalAnnotations.setDictionary(values, annotation, value);
+});

package/src/Collection.ts

@@ -0,0 +1,33 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+// @import-as-namespace
+
+import * as Schema from 'effect/Schema';
+
+import { DXN } from '@dxos/keys';
+
+import * as Annotation from './Annotation';
+import * as internal from './internal';
+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(
+  Annotation.IconAnnotation.set({ icon: 'ph--folder--regular', hue: 'amber' }),
+  Type.makeObject(DXN.make('org.dxos.type.collection', '0.1.0')),
+);
+
+export type Collection = Type.InstanceType<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

@@ -0,0 +1,345 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+// @import-as-namespace
+
+import * as Context from 'effect/Context';
+import * as Effect from 'effect/Effect';
+import * as Effectable from 'effect/Effectable';
+import * as Layer from 'effect/Layer';
+import * as Option from 'effect/Option';
+import * as Schema from 'effect/Schema';
+
+import { EffectEx } from '@dxos/effect';
+import { invariant } from '@dxos/invariant';
+import { type SpaceId, type URI } 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 { type AnyProperties, EntityKind, KindId } from './internal/common/types';
+// Deep import (not the `./internal/Entity` barrel) to avoid a cycle:
+// Database → internal/Entity → entity → JsonSchema → Ref → Database.
+import { isInstanceOf } from './internal/Entity/type-uri';
+import type { Ref } from './internal/Ref/ref';
+import type * as Obj from './Obj';
+import type * as Query from './Query';
+import type * as QueryResult from './QueryResult';
+import type * as Registry from './Registry';
+import type * as Type from './Type';
+
+/**
+ * `query` API function declaration.
+ */
+// TODO(burdon): Reconcile Query and Filter (should only have one root type).
+export interface QueryFn {
+  <Q extends Query.Any>(query: Q): QueryResult.QueryResult<Query.Type<Q>>;
+  <F extends Filter.Any>(filter: F): QueryResult.QueryResult<Filter.Type<F>>;
+}
+
+/**
+ * Common interface for Database, Feed, and Hypergraph.
+ */
+export interface Queryable {
+  query: QueryFn;
+}
+
+export type GetObjectByIdOptions = {
+  deleted?: boolean;
+};
+
+export type ObjectPlacement = 'root-doc' | 'linked-doc';
+
+export type AddOptions = {
+  /**
+   * Where to place the object in the Automerge document tree.
+   * Root document is always loaded with the space.
+   * Linked documents are loaded lazily.
+   * Placing large number of objects in the root document may slow down the initial load.
+   *
+   * @default 'linked-doc'
+   */
+  placeIn?: ObjectPlacement;
+};
+
+/**
+ * Rejects Type entities from {@link Database.add} at compile time via their `[KindId]` brand. Used
+ * as `T & RejectTypeEntity<T>` to preserve inference of `T`. Bounding `add` on
+ * `Obj.Unknown | Relation.Unknown` instead would reject broadly-typed instance adds (e.g.
+ * `Entity.Any`, `Obj.OfShape<T>`), forcing casts repo-wide.
+ */
+export type RejectTypeEntity<T> = T extends { readonly [KindId]: EntityKind.Type }
+  ? { __error: 'Type entities must be persisted via db.addType(), not db.add().' }
+  : T;
+
+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;
+
+  get graph(): Hypergraph.Hypergraph;
+
+  /**
+   * Registry for this database. Delegates type lookups to the shared hypergraph registry.
+   * To persist a schema so it replicates to other clients, add the type entity with
+   * {@link addType} (e.g. `await db.addType(Type.makeObjectFromJsonSchema(...))`).
+   */
+  readonly registry: Registry.Registry;
+
+  toJSON(): object;
+
+  /**
+   * Return object by local ID.
+   * @deprecated Use `db.query(Filter.id(id)).runSync()[0]` for a working-set lookup, or resolve via a {@link Ref}.
+   */
+  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.
+   *
+   * NOTE: The reference may be dangling if the object is not present in the database.
+   * NOTE: Difference from `Ref.fromURI`
+   * `Ref.fromURI(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>(uri: URI.URI): Ref<T>;
+
+  /**
+   * Adds an object or relation to the database.
+   *
+   * Only Object and Relation entities are accepted. To persist a Type definition use
+   * {@link addType} — passing a Type entity is rejected at compile time (and at runtime).
+   */
+  add<T extends Entity.Unknown = Entity.Unknown>(obj: T & RejectTypeEntity<T>, opts?: AddOptions): T;
+
+  /**
+   * Persists a Type definition (clones/forks the entity) so it replicates to other peers.
+   *
+   * Runs a conflict query first: if a type with the same typename + version already exists in
+   * this space, the existing persisted entity is returned and no duplicate is created. This is
+   * the only supported way to add Type entities — {@link add} rejects them.
+   */
+  addType<T extends Type.AnyEntity>(type: T): Promise<T>;
+
+  /**
+   * Removes object from the database.
+   */
+  // 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: URI.URI | Ref<any>): Effect.Effect<Entity.Unknown, never, Service>;
+  // Check matches schema.
+  <S extends Type.AnyEntity>(
+    ref: URI.URI | Ref<any>,
+    schema: S,
+  ): Effect.Effect<Type.InstanceType<S>, Err.EntityNotFoundError, Service>;
+} = (<S extends Type.AnyEntity>(
+  ref: URI.URI | Ref<any>,
+  schema?: S,
+): Effect.Effect<Type.InstanceType<S>, Err.EntityNotFoundError, Service> =>
+  Effect.gen(function* () {
+    const { db } = yield* Service;
+    const dxn = typeof ref === 'string' ? ref : ref.uri;
+    const object = yield* EffectEx.promiseWithCauseCapture(() =>
+      db.graph
+        .createRefResolver({
+          context: {
+            space: db.spaceId,
+          },
+        })
+        .resolve(dxn),
+    );
+
+    if (!object) {
+      return yield* Effect.fail(new Err.EntityNotFoundError(dxn));
+    }
+    // `isInstanceOf` uses a conditional generic that TS can't resolve through
+    // the local `S extends Type.AnyEntity` parameter — runtime accepts it fine.
+    invariant(!schema || isInstanceOf(schema as any, object), 'Object type mismatch.');
+    return object as any;
+  }).pipe(Effect.withSpan('Database.resolve'))) as any;
+
+/**
+ * Loads an object reference.
+ *
+ * Catching not found error:
+ *
+ * ```ts
+ * yield* load(ref).pipe(Effect.catchTag('EntityNotFoundError', () => Effect.succeed(undefined)));
+ * ```
+ *
+ */
+export const load: <T>(ref: Ref<T>) => Effect.Effect<T, Err.EntityNotFoundError, never> = Effect.fn('Database.load')(
+  function* (ref) {
+    const object = yield* EffectEx.promiseWithCauseCapture(() => ref.tryLoad());
+    if (!object) {
+      return yield* Effect.fail(new Err.EntityNotFoundError(ref.uri));
+    }
+    return object;
+  },
+);
+
+/**
+ * Adds an object or relation to the database.
+ * @see {@link Database.add}
+ */
+export const add = <T extends Entity.Unknown>(obj: T & RejectTypeEntity<T>): Effect.Effect<T, never, Service> =>
+  Service.pipe(Effect.map(({ db }) => db.add<T>(obj))).pipe(Effect.withSpan('Database.add'));
+
+/**
+ * Persists a Type definition to the database.
+ * @see {@link Database.addType}
+ */
+export const addType = <T extends Type.AnyEntity>(type: T): Effect.Effect<T, never, Service> =>
+  Service.pipe(Effect.flatMap(({ db }) => EffectEx.promiseWithCauseCapture(() => db.addType(type)))).pipe(
+    Effect.withSpan('Database.addType'),
+  );
+
+/**
+ * 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))).pipe(Effect.withSpan('Database.remove'));
+
+/**
+ * Flushes pending changes to disk.
+ * @see {@link Database.flush}
+ */
+export const flush = (opts?: FlushOptions) =>
+  Service.pipe(Effect.flatMap(({ db }) => EffectEx.promiseWithCauseCapture(() => db.flush(opts)))).pipe(
+    Effect.withSpan('Database.flush'),
+  );
+
+/**
+ * Creates a `QueryResult` object that can be subscribed to.
+ */
+export const query: {
+  <Q extends Query.Any>(query: Q): QueryResult.QueryResultEffect<Query.Type<Q>, never, Service>;
+  <F extends Filter.Any>(filter: F): QueryResult.QueryResultEffect<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'),
+    makeQueryResultEffect,
+  );
+
+const makeQueryResultEffect = <T>(
+  eff: Effect.Effect<QueryResult.QueryResult<T>, never, Service>,
+): QueryResult.QueryResultEffect<T, never, Service> => {
+  return {
+    run: Effect.flatMap(eff, (result) => EffectEx.promiseWithCauseCapture(() => result.run())),
+    first: Effect.flatMap(eff, (result) =>
+      EffectEx.promiseWithCauseCapture(async () => Option.fromNullable(await result.firstOrUndefined())),
+    ),
+
+    // Effect internals
+    ...Effectable.CommitPrototype,
+    commit() {
+      return eff;
+    },
+  } as any;
+};

package/src/Dataset.ts

@@ -0,0 +1,34 @@
+//
+// 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 Type from './Type';
+import * as View from './View';
+
+/**
+ * Abstract set of objects, represented by a view, feed, or collection.
+ * Schema-level union of the underlying type entities (rebuilt via
+ * `Type.getSchema`) so this can still be consumed by Schema-side APIs such
+ * as `Filter.type(...)` on a union.
+ */
+export type Dataset = Feed.Feed | Collection.Collection | View.View;
+export const Dataset = Schema.Union(
+  Type.getSchema(Feed.Feed),
+  Type.getSchema(Collection.Collection),
+  Type.getSchema(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)),
+);