@dxos/echo 0.8.4-main.7ace549 → 0.8.4-main.937b3ca

package/src/Relation.ts

@@ -2,61 +2,110 @@
 // Copyright 2025 DXOS.org
 //
 
-import * as Schema from 'effect/Schema';
+import type * as Schema from 'effect/Schema';
 
 import { raise } from '@dxos/debug';
+import type { ForeignKey } from '@dxos/echo-protocol';
+import { createJsonPath, getValue as getValue$ } from '@dxos/effect';
 import { assertArgument, invariant } from '@dxos/invariant';
 import { DXN, type ObjectId } from '@dxos/keys';
-import { type Live } from '@dxos/live-object';
 import { assumeType } from '@dxos/util';
 
+import type * as Database from './Database';
 import * as Entity from './Entity';
 import {
+  type ObjectJSON as APIJSON,
   ATTR_RELATION_SOURCE,
   ATTR_RELATION_TARGET,
-  type AnyEchoObject,
+  type AnyEntity,
+  type Comparator as ApiComparator,
+  type Meta as ApiMeta,
+  type ReadonlyMeta as ApiReadonlyMeta,
+  type EntityVersion as ApiVersion,
+  type ChangeCallback,
   EntityKind,
   type InternalObjectProps,
+  type KindId,
   MetaId,
+  type Mutable,
   type ObjectMeta,
   RelationSourceDXNId,
   RelationSourceId,
   RelationTargetDXNId,
   RelationTargetId,
+  SnapshotKindId,
+  VersionTypeId,
+  addTag as addTag$,
+  change as change$,
+  deleteKeys as deleteKeys$,
+  getDXN as getDXN$,
+  getDatabase as getDatabase$,
+  getDescription as getDescription$,
+  getKeys as getKeys$,
+  getLabel as getLabel$,
+  getMetaChecked as getMeta$,
   getObjectDXN,
+  getSchema as getSchema$,
+  getSnapshot as getSnapshot$,
   getTypeAnnotation,
+  getTypeDXN as getTypeDXN$,
+  getTypename as getTypename$,
+  isDeleted as isDeleted$,
+  isVersion,
   makeObject,
+  removeTag as removeTag$,
+  setDescription as setDescription$,
+  setLabel as setLabel$,
+  setValue as setValue$,
+  sort as sort$,
+  sortByLabel as sortByLabel$,
+  sortByTypename as sortByTypename$,
+  subscribe as subscribe$,
+  objectToJSON as toJSON$,
+  version as version$,
 } from './internal';
-import * as Obj from './Obj';
-import * as Type from './Type';
+import type * as Obj from './Obj';
+import type * as Type from './Type';
 
 /**
  * Base type for all ECHO relations.
  * @private
  */
 interface BaseRelation<Source, Target>
-  extends AnyEchoObject,
+  extends AnyEntity,
     Type.Relation.Endpoints<Source, Target>,
     Entity.OfKind<EntityKind.Relation> {}
 
 /**
- * Base type for all Relations objects.
+ * Relation with no known properties beyond id, kind, source, and target.
+ * Use this when the relation's schema/properties are not known.
+ *
+ * NOTE: This is a TypeScript type only, not a schema.
+ * To validate that a value is an ECHO relation, use `Relation.isRelation`.
  */
-export interface Any extends BaseRelation<Obj.Any, Obj.Any> {}
-
-export const Any = Schema.Struct({}).pipe(
-  Type.Relation({
-    typename: 'dxos.org/type/Any',
-    version: '0.1.0',
-    source: Obj.Any,
-    target: Obj.Any,
-  }),
-);
+export interface Unknown extends BaseRelation<Obj.Unknown, Obj.Unknown> {}
 
 /**
  * Relation type with specific source and target types.
  */
-export type Relation<Source extends Obj.Any, Target extends Obj.Any, Props> = BaseRelation<Source, Target> & Props;
+export type Relation<Source extends Obj.Unknown, Target extends Obj.Unknown, Props> = BaseRelation<Source, Target> &
+  Props;
+
+/**
+ * Base type for snapshot relations (has SnapshotKindId instead of KindId).
+ */
+interface BaseRelationSnapshot<Source, Target> extends AnyEntity, Type.Relation.Endpoints<Source, Target> {
+  readonly [SnapshotKindId]: EntityKind.Relation;
+  readonly id: ObjectId;
+}
+
+/**
+ * Immutable snapshot of an ECHO relation.
+ * Branded with SnapshotKindId (not KindId).
+ * Property values are frozen at the time the snapshot was created.
+ * Returned by getSnapshot() and hooks.
+ */
+export type Snapshot<T extends Unknown = Unknown> = Omit<T, KindId> & BaseRelationSnapshot<Obj.Unknown, Obj.Unknown>;
 
 export const Source: unique symbol = RelationSourceId as any;
 export type Source = typeof Source;
@@ -64,13 +113,22 @@ export type Source = typeof Source;
 export const Target: unique symbol = RelationTargetId as any;
 export type Target = typeof Target;
 
-type MakeProps<T extends Any> = {
+/**
+ * Internal props type for relation instance creation.
+ */
+type RelationMakeProps<T extends Unknown> = {
   id?: ObjectId;
   [MetaId]?: ObjectMeta;
   [Source]: T[Source];
   [Target]: T[Target];
 } & Type.Properties<T>;
 
+/**
+ * Props type for relation creation with a given schema.
+ * Takes a schema type (created with Type.Relation) and extracts the props type.
+ */
+export type MakeProps<S extends Type.Relation.Any> = RelationMakeProps<Schema.Schema.Type<S>>;
+
 /**
  * Creates new relation.
  * @param schema - Relation schema.
@@ -82,9 +140,9 @@ type MakeProps<T extends Any> = {
 // TODO(dmaretskyi): Move meta into props.
 export const make = <S extends Type.Relation.Any>(
   schema: S,
-  props: NoInfer<MakeProps<Schema.Schema.Type<S>>>,
+  props: NoInfer<RelationMakeProps<Schema.Schema.Type<S>>>,
   meta?: ObjectMeta,
-): Live<Schema.Schema.Type<S> & Entity.OfKind<typeof Entity.Kind.Relation>> => {
+): Schema.Schema.Type<S> & Entity.OfKind<typeof Entity.Kind.Relation> => {
   assertArgument(getTypeAnnotation(schema)?.kind === EntityKind.Relation, 'schema', 'Expected a relation schema');
 
   if (props[MetaId] != null) {
@@ -101,7 +159,11 @@ export const make = <S extends Type.Relation.Any>(
   return makeObject<Schema.Schema.Type<S>>(schema, props as any, meta);
 };
 
-export const isRelation = (value: unknown): value is Any => {
+/**
+ * Type guard for relations.
+ * Returns true for both reactive relations and relation snapshots.
+ */
+export const isRelation = (value: unknown): value is Unknown => {
   if (typeof value !== 'object' || value === null) {
     return false;
   }
@@ -109,15 +171,17 @@ export const isRelation = (value: unknown): value is Any => {
     return true;
   }
 
-  const kind = (value as any)[Entity.KindId];
+  // Check for reactive relation (KindId) or snapshot (SnapshotKindId).
+  const kind = (value as any)[Entity.KindId] ?? (value as any)[SnapshotKindId];
   return kind === EntityKind.Relation;
 };
 
 /**
  * @returns Relation source DXN.
+ * Accepts both reactive relations and snapshots.
  * @throws If the object is not a relation.
  */
-export const getSourceDXN = (value: Any): DXN => {
+export const getSourceDXN = (value: Unknown | Snapshot): DXN => {
   assertArgument(isRelation(value), 'Expected a relation');
   assumeType<InternalObjectProps>(value);
   const dxn = (value as InternalObjectProps)[RelationSourceDXNId];
@@ -127,9 +191,10 @@ export const getSourceDXN = (value: Any): DXN => {
 
 /**
  * @returns Relation target DXN.
+ * Accepts both reactive relations and snapshots.
  * @throws If the object is not a relation.
  */
-export const getTargetDXN = (value: Any): DXN => {
+export const getTargetDXN = (value: Unknown | Snapshot): DXN => {
   assertArgument(isRelation(value), 'Expected a relation');
   assumeType<InternalObjectProps>(value);
   const dxn = (value as InternalObjectProps)[RelationTargetDXNId];
@@ -139,9 +204,10 @@ export const getTargetDXN = (value: Any): DXN => {
 
 /**
  * @returns Relation source.
+ * Accepts both reactive relations and snapshots.
  * @throws If the object is not a relation.
  */
-export const getSource = <T extends Any>(relation: T): Type.Relation.Source<T> => {
+export const getSource = <T extends Unknown | Snapshot>(relation: T): Type.Relation.Source<T> => {
   assertArgument(isRelation(relation), 'Expected a relation');
   assumeType<InternalObjectProps>(relation);
   const obj = (relation as InternalObjectProps)[RelationSourceId];
@@ -151,12 +217,283 @@ export const getSource = <T extends Any>(relation: T): Type.Relation.Source<T> =
 
 /**
  * @returns Relation target.
+ * Accepts both reactive relations and snapshots.
  * @throws If the object is not a relation.
  */
-export const getTarget = <T extends Any>(relation: T): Type.Relation.Target<T> => {
+export const getTarget = <T extends Unknown | Snapshot>(relation: T): Type.Relation.Target<T> => {
   assertArgument(isRelation(relation), 'Expected a relation');
   assumeType<InternalObjectProps>(relation);
   const obj = (relation as InternalObjectProps)[RelationTargetId];
   invariant(obj !== undefined, `Invalid target: ${relation.id}`);
   return obj as Type.Relation.Target<T>;
 };
+
+//
+// Change
+//
+
+/**
+ * Makes all properties mutable recursively.
+ * Used to provide a mutable view of a relation within `Relation.change`.
+ */
+export type { Mutable };
+
+/**
+ * Perform mutations on an echo relation within a controlled context.
+ *
+ * All mutations within the callback are batched and trigger a single notification
+ * when the callback completes. Direct mutations outside of `Relation.change` will throw
+ * an error for echo relations.
+ *
+ * @param relation - The echo relation to mutate. Use `Obj.change` for objects.
+ * @param callback - The callback that performs mutations on the relation.
+ *
+ * @example
+ * ```ts
+ * const worksFor = Relation.make(EmployedBy, {
+ *   [Relation.Source]: person,
+ *   [Relation.Target]: company,
+ *   role: 'Engineer',
+ * });
+ *
+ * // Mutate within Relation.change
+ * Relation.change(worksFor, (r) => {
+ *   r.role = 'Senior Engineer';
+ * });
+ * ```
+ *
+ * Note: Only accepts relations. Use `Obj.change` for objects.
+ */
+export const change = <T extends Unknown>(relation: T, callback: ChangeCallback<T>): void => {
+  change$(relation, callback);
+};
+
+//
+// Snapshot
+//
+
+/**
+ * Returns an immutable snapshot of a relation.
+ * The snapshot is branded with SnapshotKindId instead of KindId,
+ * making it distinguishable from the reactive relation at the type level.
+ */
+export const getSnapshot: <T extends Unknown>(rel: T) => Snapshot<T> = getSnapshot$ as any;
+
+//
+// Subscribe
+//
+
+/**
+ * Subscribe to relation updates.
+ * The callback is called synchronously when the relation is modified.
+ * Only accepts reactive relations (not snapshots).
+ * @returns Unsubscribe function.
+ */
+export const subscribe = (rel: Unknown, callback: () => void): (() => void) => {
+  return subscribe$(rel, callback);
+};
+
+//
+// Property Access
+//
+
+/**
+ * Get a deeply nested property from a relation.
+ * Accepts both reactive relations and snapshots.
+ */
+export const getValue = (rel: Unknown | Snapshot, path: readonly (string | number)[]): any => {
+  return getValue$(rel, createJsonPath(path));
+};
+
+/**
+ * Set a deeply nested property on a relation.
+ * Must be called within a `Relation.change` callback.
+ *
+ * NOTE: TypeScript's structural typing allows readonly objects to be passed to `Mutable<T>`
+ * parameters, so there is no compile-time error. Enforcement is runtime-only.
+ */
+export const setValue: (rel: Mutable<Unknown>, path: readonly (string | number)[], value: any) => void =
+  setValue$ as any;
+
+//
+// Type
+//
+
+/**
+ * Get the DXN of the relation.
+ * Accepts both reactive relations and snapshots.
+ */
+export const getDXN = (entity: Unknown | Snapshot): DXN => getDXN$(entity);
+
+/**
+ * @returns The DXN of the relation's type.
+ */
+export const getTypeDXN = getTypeDXN$;
+
+/**
+ * Get the schema of the relation.
+ * Returns the branded ECHO schema used to create the relation.
+ */
+export const getSchema: (rel: unknown | undefined) => Type.Entity.Any | undefined = getSchema$ as any;
+
+/**
+ * @returns The typename of the relation's type.
+ * Accepts both reactive relations and snapshots.
+ */
+export const getTypename = (entity: Unknown | Snapshot): string | undefined => getTypename$(entity);
+
+//
+// Database
+//
+
+/**
+ * Get the database the relation belongs to.
+ * Accepts both reactive relations and snapshots.
+ */
+export const getDatabase = (entity: Unknown | Snapshot): Database.Database | undefined => getDatabase$(entity);
+
+//
+// Meta
+//
+
+/**
+ * Deeply read-only version of ObjectMeta.
+ */
+export type ReadonlyMeta = ApiReadonlyMeta;
+
+/**
+ * Mutable meta type returned by `Relation.getMeta` inside a `Relation.change` callback.
+ */
+export type Meta = ApiMeta;
+
+/**
+ * Get the metadata for a relation.
+ * Returns mutable meta when passed a mutable relation (inside `Relation.change` callback).
+ * Returns read-only meta when passed a regular relation or snapshot.
+ */
+// TODO(wittjosiah): When passed a Snapshot, should return a snapshot of meta, not the live meta proxy.
+export function getMeta(entity: Mutable<Unknown>): ObjectMeta;
+export function getMeta(entity: Unknown | Snapshot): ReadonlyMeta;
+export function getMeta(entity: Unknown | Snapshot | Mutable<Unknown>): ObjectMeta | ReadonlyMeta {
+  return getMeta$(entity);
+}
+
+/**
+ * @returns Foreign keys for the relation from the specified source.
+ * Accepts both reactive relations and snapshots.
+ */
+export const getKeys = (entity: Unknown | Snapshot, source: string): ForeignKey[] => getKeys$(entity, source);
+
+/**
+ * Delete all keys from the relation for the specified source.
+ * Must be called within a `Relation.change` callback.
+ *
+ * NOTE: TypeScript's structural typing allows readonly objects to be passed to `Mutable<T>`
+ * parameters, so there is no compile-time error. Enforcement is runtime-only.
+ */
+export const deleteKeys = (entity: Mutable<Unknown>, source: string): void => deleteKeys$(entity, source);
+
+/**
+ * Add a tag to the relation.
+ * Must be called within a `Relation.change` callback.
+ *
+ * NOTE: TypeScript's structural typing allows readonly objects to be passed to `Mutable<T>`
+ * parameters, so there is no compile-time error. Enforcement is runtime-only.
+ */
+export const addTag = (entity: Mutable<Unknown>, tag: string): void => addTag$(entity, tag);
+
+/**
+ * Remove a tag from the relation.
+ * Must be called within a `Relation.change` callback.
+ *
+ * NOTE: TypeScript's structural typing allows readonly objects to be passed to `Mutable<T>`
+ * parameters, so there is no compile-time error. Enforcement is runtime-only.
+ */
+export const removeTag = (entity: Mutable<Unknown>, tag: string): void => removeTag$(entity, tag);
+
+/**
+ * Check if the relation is deleted.
+ * Accepts both reactive relations and snapshots.
+ */
+export const isDeleted = (entity: Unknown | Snapshot): boolean => isDeleted$(entity);
+
+//
+// Annotations
+//
+
+/**
+ * Get the label of the relation.
+ * Accepts both reactive relations and snapshots.
+ */
+export const getLabel = (entity: Unknown | Snapshot): string | undefined => getLabel$(entity);
+
+/**
+ * Set the label of the relation.
+ * Must be called within a `Relation.change` callback.
+ *
+ * NOTE: TypeScript's structural typing allows readonly objects to be passed to `Mutable<T>`
+ * parameters, so there is no compile-time error. Enforcement is runtime-only.
+ */
+export const setLabel = (entity: Mutable<Unknown>, label: string): void => setLabel$(entity, label);
+
+/**
+ * Get the description of the relation.
+ * Accepts both reactive relations and snapshots.
+ */
+export const getDescription = (entity: Unknown | Snapshot): string | undefined => getDescription$(entity);
+
+/**
+ * Set the description of the relation.
+ * Must be called within a `Relation.change` callback.
+ *
+ * NOTE: TypeScript's structural typing allows readonly objects to be passed to `Mutable<T>`
+ * parameters, so there is no compile-time error. Enforcement is runtime-only.
+ */
+export const setDescription = (entity: Mutable<Unknown>, description: string): void =>
+  setDescription$(entity, description);
+
+//
+// JSON
+//
+
+/**
+ * JSON representation of a relation.
+ */
+export type JSON = APIJSON;
+
+/**
+ * Converts relation to its JSON representation.
+ * Accepts both reactive relations and snapshots.
+ */
+export const toJSON = (entity: Unknown | Snapshot): JSON => toJSON$(entity);
+
+//
+// Sorting
+//
+
+/**
+ * Comparator function type for sorting relations.
+ * Accepts both reactive relations and snapshots.
+ */
+export type Comparator = ApiComparator<Unknown | Snapshot>;
+
+export const sortByLabel: Comparator = sortByLabel$ as Comparator;
+export const sortByTypename: Comparator = sortByTypename$ as Comparator;
+export const sort = (...comparators: Comparator[]): Comparator => sort$(...comparators) as Comparator;
+
+//
+// Version
+//
+
+export { VersionTypeId, isVersion };
+
+/**
+ * Represent relation version.
+ */
+export type Version = ApiVersion;
+
+/**
+ * Returns the version of the relation.
+ * Accepts both reactive relations and snapshots.
+ */
+export const version = (entity: Unknown | Snapshot): Version => version$(entity);

package/src/SchemaRegistry.ts

@@ -0,0 +1,105 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import type * as Types from 'effect/Types';
+
+import type * as JsonSchema from './JsonSchema';
+import type * as Key from './Key';
+import type * as QueryResult from './QueryResult';
+import type * as Type from './Type';
+
+// TODO(wittjosiah): Replace w/ Query.Query.
+export type Query = {
+  /**
+   * Filter by schema ID.
+   * Schema id is a DXN with `echo` or `type` kind.
+   */
+  id?: string | string[];
+
+  /**
+   * Id of the backing ECHO object.
+   */
+  backingObjectId?: Key.ObjectId | Key.ObjectId[];
+
+  /**
+   * One or more typenames to filter by.
+   */
+  typename?: string | string[];
+
+  /**
+   * [Semver Range](https://docs.npmjs.com/cli/v6/using-npm/semver#ranges) for the schema version.
+   */
+  version?: string;
+
+  /**
+   * Where to look for the schema.
+   *
+   * Database schema are stored in the database of the current space.
+   * Runtime schema are registered in the runtime.
+   *
+   * @default ['database']
+   */
+  location?: ('database' | 'runtime')[];
+
+  /**
+   * Include system schemas.
+   * @default false
+   *
+   * The system schema include but are not limited to:
+   *  - dxos.org/type/Schema
+   */
+  includeSystem?: boolean;
+};
+
+/**
+ * Input for schema registration.
+ * The typename, version and schema mutability metadata is read from the schema annotations.
+ *
+ * Accepts:
+ * - Branded ECHO schemas created with Type.Obj() or Type.Relation()
+ * - JSON schema with typename and version
+ */
+export type RegisterSchemaInput =
+  | Type.Entity.Any
+  | {
+      typename: string;
+      version: string;
+      jsonSchema: JsonSchema.JsonSchema;
+      /**
+       * Display name of the schema.
+       */
+      name?: string;
+    };
+
+export type ExtractQueryResult<Query> = Query extends { location: ('database' | 'runtime')[] }
+  ? Type.Entity.Any
+  : Type.RuntimeType;
+
+export interface SchemaRegistry {
+  /**
+   * Checks if the provided schema is registered.
+   */
+  // TODO(burdon): Type?
+  hasSchema(schema: Type.Entity.Any): boolean;
+
+  /**
+   * Registers the provided schema.
+   *
+   * @returns Mutable runtime instances of schemas that were registered.
+   *
+   * The behavior of this method depends on the state of the database.
+   * The general principle is that the schema will be upserted into the space.
+   * If an equivalent schema with the same name and version already exists, the method does nothing.
+   * If a different schema with the same name and version exists, the method throws an error.
+   * If no schema with the same name and version exists, a new schema will be inserted based on semantic versioning rules.
+   */
+  register(input: RegisterSchemaInput[]): Promise<Type.RuntimeType[]>;
+
+  /**
+   *
+   */
+  query<Q extends Types.NoExcessProperties<Query, Q>>(
+    query?: Q & Query,
+  ): QueryResult.QueryResult<ExtractQueryResult<Q>>;
+}

package/src/Tag.ts

@@ -12,7 +12,7 @@ export const Tag = Schema.Struct({
   label: Schema.String,
   hue: Schema.optional(Schema.String), // TODO(burdon): Color name?
 }).pipe(
-  Type.Obj({
+  Type.object({
     typename: 'dxos.org/type/Tag',
     version: '0.1.0',
   }),

package/src/Type.test.ts

@@ -0,0 +1,52 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+import { describe, test } from 'vitest';
+
+import * as Obj from './Obj';
+import * as Relation from './Relation';
+import { TestSchema } from './testing';
+import * as Type from './Type';
+
+describe('Type', () => {
+  describe('Type.Obj', () => {
+    test('has SchemaKindId for schema type checking', ({ expect }) => {
+      // Type.isObjectSchema uses SchemaKindId to check if a schema is an object schema.
+      expect(Type.isObjectSchema(Type.Obj)).toBe(true);
+      expect(Type.isObjectSchema(TestSchema.Person)).toBe(true);
+      expect(Type.isObjectSchema(Type.Relation)).toBe(false);
+    });
+
+    test('Schema.is validates structural compatibility only', ({ expect }) => {
+      // Schema.is does structural validation (has id field).
+      // It accepts both ECHO objects and plain objects with compatible structure.
+      expect(Schema.is(Type.Obj)({ id: 'plain-object' })).toBe(true);
+      const obj = Obj.make(TestSchema.Person, { name: 'Test' });
+      expect(Schema.is(Type.Obj)(obj)).toBe(true);
+    });
+  });
+
+  describe('Type.Relation', () => {
+    test('has SchemaKindId for schema type checking', ({ expect }) => {
+      // Type.isRelationSchema uses SchemaKindId to check if a schema is a relation schema.
+      expect(Type.isRelationSchema(Type.Relation)).toBe(true);
+      expect(Type.isRelationSchema(TestSchema.HasManager)).toBe(true);
+      expect(Type.isRelationSchema(Type.Obj)).toBe(false);
+    });
+
+    test('Schema.is validates structural compatibility only', ({ expect }) => {
+      // Schema.is does structural validation (has id field).
+      // It accepts both ECHO relations and plain objects with compatible structure.
+      expect(Schema.is(Type.Relation)({ id: 'plain-object' })).toBe(true);
+      const obj1 = Obj.make(TestSchema.Person, { name: 'Alice' });
+      const obj2 = Obj.make(TestSchema.Person, { name: 'Bob' });
+      const rel = Relation.make(TestSchema.HasManager, {
+        [Relation.Source]: obj1,
+        [Relation.Target]: obj2,
+      });
+      expect(Schema.is(Type.Relation)(rel)).toBe(true);
+    });
+  });
+});