@dxos/echo 0.9.1-main.c7dcc2e112 → 0.9.1-staging.ee54ba693a

package/src/Obj.test.ts

@@ -2,7 +2,7 @@
 // Copyright 2026 DXOS.org
 //
 
-import { describe, expectTypeOf, test, expect } from 'vitest';
+import { describe, expect, expectTypeOf, test } from 'vitest';
 
 import { EID } from '@dxos/keys';
 
@@ -12,6 +12,7 @@ import * as Obj from './Obj';
 import * as Ref from './Ref';
 import * as Relation from './Relation';
 import { TestSchema } from './testing';
+import type * as Type from './Type';
 
 describe('Obj', () => {
   describe('make', () => {
@@ -137,11 +138,11 @@ describe('Obj', () => {
 
     test("prefer: 'named' returns dxn: URI when meta.key is set", ({ expect }) => {
       const obj = Obj.make(TestSchema.Person, {
-        [Obj.Meta]: { key: 'org.dxos.blueprint.webSearch' },
+        [Obj.Meta]: { key: 'org.dxos.skill.webSearch' },
         name: 'Alice',
       });
       const uri = Obj.getURI(obj, { prefer: 'named' });
-      expect(uri).toBe('dxn:org.dxos.blueprint.webSearch');
+      expect(uri).toBe('dxn:org.dxos.skill.webSearch');
     });
 
     test("prefer: 'named' falls back to EID when meta.key is absent", ({ expect }) => {
@@ -152,12 +153,12 @@ describe('Obj', () => {
 
     test("prefer: 'named' handles key with hyphens (falls back to raw key URI)", ({ expect }) => {
       const obj = Obj.make(TestSchema.Person, {
-        [Obj.Meta]: { key: 'org.dxos.blueprint.web-search' },
+        [Obj.Meta]: { key: 'org.dxos.skill.web-search' },
         name: 'Alice',
       });
       // Hyphens in the final DXN segment are invalid; falls back to the raw key as URI.
       const uri = Obj.getURI(obj, { prefer: 'named' });
-      expect(uri).toBe('org.dxos.blueprint.web-search');
+      expect(uri).toBe('org.dxos.skill.web-search');
     });
 
     test("prefer: 'absolute' falls back to current EID when object has no database", ({ expect }) => {
@@ -328,7 +329,7 @@ describe('Obj', () => {
         employer: Ref.make(employer),
       });
 
-      const cloned = Obj.clone(person, { deep: true });
+      const cloned = Obj.clone(person, { deep: 'all' });
 
       expect(cloned.employer).not.toBe(person.employer);
       expect(cloned.employer?.target).not.toBe(employer);
@@ -363,7 +364,7 @@ describe('Obj', () => {
         tasks: [Ref.make(task1), Ref.make(task2)],
       });
 
-      const cloned = Obj.clone(person, { deep: true });
+      const cloned = Obj.clone(person, { deep: 'all' });
 
       expect(cloned.tasks).not.toBe(person.tasks);
       expect(cloned.tasks?.length).toBe(2);
@@ -393,7 +394,7 @@ describe('Obj', () => {
         employer: Ref.make(employer),
       });
 
-      const cloned = Obj.clone(person, { deep: true });
+      const cloned = Obj.clone(person, { deep: 'all' });
 
       expect(cloned.employer).toBeDefined();
       expect(cloned.employer?.target).toBeDefined();
@@ -406,7 +407,7 @@ describe('Obj', () => {
         username: 'bob',
       });
 
-      const clonedWithoutEmployer = Obj.clone(personWithoutEmployer, { deep: true });
+      const clonedWithoutEmployer = Obj.clone(personWithoutEmployer, { deep: 'all' });
       expect(clonedWithoutEmployer.employer).toBeUndefined();
     });
 
@@ -426,7 +427,7 @@ describe('Obj', () => {
         },
       });
 
-      const cloned = Obj.clone(person, { deep: true });
+      const cloned = Obj.clone(person, { deep: 'all' });
 
       expect(cloned.address?.city).toBe('San Francisco');
       expect(cloned.address?.state).toBe('CA');
@@ -455,7 +456,7 @@ describe('Obj', () => {
         tasks: [Ref.make(task1), Ref.make(task2), Ref.make(task3)],
       });
 
-      const cloned = Obj.clone(person, { deep: true });
+      const cloned = Obj.clone(person, { deep: 'all' });
 
       expect(cloned.tasks?.length).toBe(3);
       expect(cloned.tasks?.[0]?.target?.title).toBe('Task 1');
@@ -488,7 +489,7 @@ describe('Obj', () => {
         employer: Ref.make(employer),
       });
 
-      const cloned = Obj.clone(person, { deep: true, retainId: true });
+      const cloned = Obj.clone(person, { deep: 'all', retainId: true });
 
       expect(cloned.id).toBe(person.id);
       expect(cloned.employer?.target).not.toBe(employer);
@@ -509,6 +510,48 @@ describe('Obj', () => {
       expect(Obj.instanceOf(TestSchema.Person, cloned)).toBe(true);
       expect(Obj.getType(cloned)).toBe(Obj.getType(person));
     });
+
+    test("deep: 'parent' clones owned children but shares unowned refs", ({ expect }) => {
+      // An owned task (parented to the person) is cloned; a shared task (no parent link) is referenced as-is.
+      const ownedTask = Obj.make(TestSchema.Task, { title: 'Owned' });
+      const sharedTask = Obj.make(TestSchema.Task, { title: 'Shared' });
+      const person = Obj.make(TestSchema.Person, {
+        name: 'Alice',
+        email: 'alice@example.com',
+        username: 'alice',
+        tasks: [Ref.make(ownedTask), Ref.make(sharedTask)],
+      });
+      Obj.setParent(ownedTask, person);
+
+      const cloned = Obj.clone(person, { deep: 'parent' });
+
+      // Owned child is a fresh copy.
+      expect(cloned.tasks?.[0]?.target).not.toBe(ownedTask);
+      expect(cloned.tasks?.[0]?.target?.id).not.toBe(ownedTask.id);
+      expect(cloned.tasks?.[0]?.target?.title).toBe('Owned');
+      // Unowned (shared) ref points at the original object.
+      expect(cloned.tasks?.[1]?.target).toBe(sharedTask);
+    });
+
+    test("deep: 'parent' follows transitive ownership", ({ expect }) => {
+      // grandchild ← child ← root: both are cloned because their parent chain reaches the clone root.
+      const grandchild = Obj.make(TestSchema.Task, { title: 'Grandchild' });
+      const child = Obj.make(TestSchema.Task, { title: 'Child', previous: Ref.make(grandchild) });
+      const person = Obj.make(TestSchema.Person, {
+        name: 'Alice',
+        email: 'alice@example.com',
+        username: 'alice',
+        tasks: [Ref.make(child)],
+      });
+      Obj.setParent(child, person);
+      Obj.setParent(grandchild, child);
+
+      const cloned = Obj.clone(person, { deep: 'parent' });
+
+      expect(cloned.tasks?.[0]?.target).not.toBe(child);
+      expect(cloned.tasks?.[0]?.target?.previous?.target).not.toBe(grandchild);
+      expect(cloned.tasks?.[0]?.target?.previous?.target?.title).toBe('Grandchild');
+    });
   });
 
   describe('type-level tests', () => {
@@ -638,4 +681,41 @@ describe('Obj', () => {
       expect(target.properties).toEqual({ x: '2' });
     });
   });
+
+  describe('exemplars', () => {
+    test('factory', ({ expect }) => {
+      const factory = <S extends Type.AnyObj>(schema: S) => {
+        return (props: Obj.MakeProps<S>) => Obj.make(schema, props);
+      };
+
+      const makePerson = factory(TestSchema.Person);
+      const person = makePerson({ name: 'John Doe' });
+      expect(person.name).toBe('John Doe');
+    });
+  });
+
+  describe('Hierarchy', () => {
+    test('setParent and getParent', async () => {
+      const parent = Obj.make(TestSchema.Organization, { name: 'parent' });
+      const child = Obj.make(TestSchema.Person, { name: 'child' });
+      expect(Obj.getParent(child)).toBeUndefined();
+
+      Obj.setParent(child, parent);
+      expect(Obj.getParent(child)).toBe(parent);
+
+      Obj.setParent(child, undefined);
+      expect(Obj.getParent(child)).toBeUndefined();
+    });
+
+    test('create object with Obj.Parent in props', () => {
+      const parent = Obj.make(TestSchema.Organization, { name: 'DXOS' });
+      const child = Obj.make(TestSchema.Person, {
+        [Obj.Parent]: parent,
+        name: 'John',
+      });
+
+      expect(child.name).toBe('John');
+      expect(Obj.getParent(child)).toBe(parent);
+    });
+  });
 });

package/src/Obj.ts

@@ -6,6 +6,7 @@
 
 import * as Effect from 'effect/Effect';
 import * as Equal from 'effect/Equal';
+import * as Exit from 'effect/Exit';
 import * as Function from 'effect/Function';
 import * as Option from 'effect/Option';
 import * as Schema from 'effect/Schema';
@@ -63,9 +64,9 @@ export interface Unknown extends BaseObj {}
  * if (Obj.isObject(unknownValue)) { ... }
  *
  * // Reference to any object type
- * const Collection = Schema.Struct({
- *   objects: Schema.Array(Ref.Ref(Obj.Unknown)),
- * }).pipe(Type.makeObject(DXN.make('com.example.type.collection', '0.1.0')));
+ * class Collection extends Type.makeObject<Collection>(DXN.make('com.example.type.collection', '0.1.0'))(
+ *   Schema.Struct({ objects: Schema.Array(Ref.Ref(Obj.Unknown)) }),
+ * ) {}
  * ```
  */
 // TODO(wittjosiah): Investigate if Schema.filter can validate KindId on ECHO instances.
@@ -299,6 +300,22 @@ export const getReactiveOption = <T extends Unknown>(snapshot: Snapshot<T>): Eff
 export const getReactiveOrThrow = <T extends Unknown>(snapshot: Snapshot<T>): T =>
   Effect.runSync(getReactive(snapshot));
 
+/**
+ * Synchronous version of `Obj.getReactive` that returns `undefined` instead of throwing.
+ * Accepts `undefined` input so callers can pass the result of `useObject` directly.
+ *
+ * @param snapshot - A snapshot of the object (from `Obj.getSnapshot` or `useObject`), or `undefined`.
+ * @returns The reactive object, or `undefined` if the snapshot is `undefined` or unresolvable.
+ */
+export const getReactiveOrUndefined = <T extends Unknown>(snapshot: Snapshot<T> | undefined): T | undefined => {
+  if (snapshot === undefined) {
+    return undefined;
+  }
+  return Effect.runSyncExit(getReactive(snapshot)).pipe(
+    Exit.match({ onSuccess: (value) => value, onFailure: () => undefined }),
+  );
+};
+
 export type CloneOptions = {
   /**
    * Retain the original object's ID.
@@ -308,9 +325,12 @@ export type CloneOptions = {
 
   /**
    * Recursively clone referenced objects.
-   * @default false
+   * - `'parent'`: clone only refs whose target is transitively parented under the clone root (children
+   *   that cascade-delete with it); shared refs (registry operations, context objects, …) are copied as-is.
+   * - `'all'`: clone every referenced object recursively.
+   * Omit for a shallow clone (refs copied as-is).
    */
-  deep?: boolean;
+  deep?: 'parent' | 'all';
 };
 
 /**
@@ -923,6 +943,17 @@ export const version = (entity: Unknown | Snapshot): Version => internal.version
 // Atoms
 //
 
+/**
+ * Create a reactive snapshot atom for an ECHO object or ref.
+ * Use inside atom computations (e.g. `Atom.make((get) => get(Obj.atom(ref)))`) to subscribe
+ * to a ref's target — the atom re-fires when the target loads or changes.
+ *
+ * @idiom org.dxos.echo.objAtomReactive
+ *   applies: Subscribing to a ref's target inside an atom computation or a non-React reactive context
+ *   instead-of: `ref.target` — synchronous and not reactive; returns `undefined` when the target isn't loaded yet and never notifies when it becomes available
+ *   uses: {@link atom}
+ *   related: org.dxos.echo-react.useObjectReactive
+ */
 export const atom = objInternal.makeAtom;
 export const atomReactive = objInternal.makeWithReactive;
 export const atomProperty = objInternal.makeProperty;

package/src/Order.ts

@@ -10,7 +10,7 @@ export interface Order<T> {
   // TODO(dmaretskyi): See new effect-schema approach to variance.
   '~Order': { value: T };
 
-  ast: QueryAST.Order;
+  'ast': QueryAST.Order;
 }
 
 export type Any = Order<any>;
@@ -18,11 +18,11 @@ export type Any = Order<any>;
 class OrderClass implements Order<any> {
   private static 'variance': Order<any>['~Order'] = {} as Order<any>['~Order'];
 
-  static is(value: unknown): value is Order<any> {
+  static 'is'(value: unknown): value is Order<any> {
     return typeof value === 'object' && value !== null && '~Order' in value;
   }
 
-  constructor(public readonly ast: QueryAST.Order) {}
+  'constructor'(public readonly ast: QueryAST.Order) {}
 
   '~Order' = OrderClass.variance;
 }

package/src/Query.test.ts

@@ -582,8 +582,8 @@ describe('query api', () => {
       const feed = (await Obj.fromJSON(
         {
           '@type': 'dxn:org.dxos.type.feed:0.1.0',
-          id: feedId,
-          name: 'test-feed',
+          'id': feedId,
+          'name': 'test-feed',
         },
         { uri: feedDxn },
       )) as Feed.Feed;

package/src/Query.ts

@@ -50,7 +50,7 @@ export interface Query<T> {
   // TODO(dmaretskyi): See new effect-schema approach to variance.
   '~Query': { value: T };
 
-  ast: QueryAST.Query;
+  'ast': QueryAST.Query;
 
   /**
    * Filter the current selection based on a filter.
@@ -238,11 +238,11 @@ export type Type<Q extends Any> = Q extends Query<infer T> ? T : never;
 class QueryClass implements Any {
   private static 'variance': Any['~Query'] = {} as Any['~Query'];
 
-  constructor(public readonly ast: QueryAST.Query) {}
+  'constructor'(public readonly ast: QueryAST.Query) {}
 
   '~Query' = QueryClass.variance;
 
-  select(filter: Filter.Any | Filter.Props<any>): Any {
+  'select'(filter: Filter.Any | Filter.Props<any>): Any {
     if (Filter.is(filter)) {
       return new QueryClass({
         type: 'filter',
@@ -258,7 +258,7 @@ class QueryClass implements Any {
     }
   }
 
-  reference(key: string): Any {
+  'reference'(key: string): Any {
     return new QueryClass({
       type: 'reference-traversal',
       anchor: this.ast,
@@ -266,7 +266,7 @@ class QueryClass implements Any {
     });
   }
 
-  referencedBy(target?: Type$.AnyEntity | URI.URI, key?: string): Any {
+  'referencedBy'(target?: Type$.AnyEntity | URI.URI, key?: string): Any {
     const uri = target !== undefined ? internal.getTypeURIFromSpecifier(target) : null;
     return new QueryClass({
       type: 'incoming-references',
@@ -276,7 +276,7 @@ class QueryClass implements Any {
     });
   }
 
-  sourceOf(relation?: Type$.AnyRelation | URI.URI, predicates?: Filter.Props<unknown> | undefined): Any {
+  'sourceOf'(relation?: Type$.AnyRelation | URI.URI, predicates?: Filter.Props<unknown> | undefined): Any {
     return new QueryClass({
       type: 'relation',
       anchor: this.ast,
@@ -285,7 +285,7 @@ class QueryClass implements Any {
     });
   }
 
-  targetOf(relation?: Type$.AnyRelation | URI.URI, predicates?: Filter.Props<unknown> | undefined): Any {
+  'targetOf'(relation?: Type$.AnyRelation | URI.URI, predicates?: Filter.Props<unknown> | undefined): Any {
     return new QueryClass({
       type: 'relation',
       anchor: this.ast,
@@ -294,7 +294,7 @@ class QueryClass implements Any {
     });
   }
 
-  source(): Any {
+  'source'(): Any {
     return new QueryClass({
       type: 'relation-traversal',
       anchor: this.ast,
@@ -302,7 +302,7 @@ class QueryClass implements Any {
     });
   }
 
-  target(): Any {
+  'target'(): Any {
     return new QueryClass({
       type: 'relation-traversal',
       anchor: this.ast,
@@ -310,7 +310,7 @@ class QueryClass implements Any {
     });
   }
 
-  parent(): Any {
+  'parent'(): Any {
     return new QueryClass({
       type: 'hierarchy-traversal',
       anchor: this.ast,
@@ -318,7 +318,7 @@ class QueryClass implements Any {
     });
   }
 
-  children(): Any {
+  'children'(): Any {
     return new QueryClass({
       type: 'hierarchy-traversal',
       anchor: this.ast,
@@ -326,7 +326,7 @@ class QueryClass implements Any {
     });
   }
 
-  orderBy(...order: Order.Order<any>[]): Any {
+  'orderBy'(...order: Order.Order<any>[]): Any {
     return new QueryClass({
       type: 'order',
       query: this.ast,
@@ -334,7 +334,7 @@ class QueryClass implements Any {
     });
   }
 
-  limit(limit: number): Any {
+  'limit'(limit: number): Any {
     return new QueryClass({
       type: 'limit',
       query: this.ast,
@@ -342,7 +342,7 @@ class QueryClass implements Any {
     });
   }
 
-  from(
+  'from'(
     ...args:
       | [
           (
@@ -478,7 +478,7 @@ class QueryClass implements Any {
     });
   }
 
-  options(options: QueryAST.QueryOptions): Any {
+  'options'(options: QueryAST.QueryOptions): Any {
     return new QueryClass({
       type: 'options',
       query: this.ast,
@@ -486,7 +486,7 @@ class QueryClass implements Any {
     });
   }
 
-  debugLabel(label: string): Any {
+  'debugLabel'(label: string): Any {
     if (this.ast.type === 'options') {
       return new QueryClass({
         type: 'options',

package/src/QueryResult.ts

@@ -3,8 +3,8 @@
 //
 
 import type * as Atom from '@effect-atom/atom/Atom';
-import * as Effect from 'effect/Effect';
-import * as Option from 'effect/Option';
+import type * as Effect from 'effect/Effect';
+import type * as Option from 'effect/Option';
 
 import { type CleanupFn } from '@dxos/async';
 

package/src/Ref.ts

@@ -15,6 +15,7 @@ import type * as internal from './internal';
 import * as refInternal from './internal/Ref';
 import type * as JsonSchema from './JsonSchema';
 import type * as Obj from './Obj';
+import type * as Relation from './Relation';
 // eslint-disable-next-line @dxos/rules/import-as-namespace
 import type * as Type$ from './Type';
 
@@ -45,13 +46,20 @@ export type Unknown = refInternal.Ref<Obj.Unknown>;
  *
  * @example
  * ```ts
- * const Task = Schema.Struct({
- *   assignee: Ref.Ref(Person),  // Creates a Ref schema
- * }).pipe(Type.makeObject(DXN.make('com.example.type.task', '0.1.0')));
+ * class Task extends Type.makeObject<Task>(DXN.make('com.example.type.task', '0.1.0'))(
+ *   Schema.Struct({
+ *     assignee: Ref.Ref(Person),  // Creates a Ref schema
+ *   }),
+ * ) {}
  * ```
  */
 export const Ref: {
-  <S extends Type$.AnyObj | Type$.AnyRelation>(type: S): RefSchema<Type$.InstanceType<S> & Obj.Unknown>;
+  <S extends Type$.AnyObj>(type: S): RefSchema<Type$.InstanceType<S> & Obj.Unknown>;
+
+  // Relations are entities too and can be referenced. The instance type already
+  // carries the relation kind brand, so intersect with `Relation.Unknown` (not
+  // `Obj.Unknown`, whose object kind brand conflicts and collapses to `never`).
+  <S extends Type$.AnyRelation>(type: S): RefSchema<Type$.InstanceType<S> & Relation.Unknown>;
 
   // `Type.Type` entities (the meta-schema kind) can be referenced too — e.g. a
   // trigger that points to a stored function/workflow definition.

package/src/Registry.ts

@@ -25,7 +25,7 @@ export type TypeId = typeof TypeId;
  * A registry may delegate to an optional upstream registry: results from the local
  * registry take precedence and upstream results fill in anything not found locally.
  *
- * Intended use cases include caches of schemas, operations, blueprints, routines, plugins,
+ * Intended use cases include caches of schemas, operations, skills, routines, plugins,
  * etc., sourced from 3rd-party plugins, local code, or local space objects.
  *
  * Types (schema-definition entities produced by `Type.makeObject` / `Type.makeRelation`) are

package/src/Relation.ts

@@ -10,7 +10,7 @@ import { raise } from '@dxos/debug';
 import type { ForeignKey } from '@dxos/echo-protocol';
 import { SchemaEx } from '@dxos/effect';
 import { assertArgument, invariant } from '@dxos/invariant';
-import { EID, type EntityId, type URI, DXN } from '@dxos/keys';
+import { DXN, EID, type EntityId, type URI } from '@dxos/keys';
 import { assumeType } from '@dxos/util';
 
 import type * as Database from './Database';

package/src/Tag.ts

@@ -14,30 +14,26 @@ import * as internal from './internal';
 import * as Obj from './Obj';
 import * as Type from './Type';
 
-export const Tag = Schema.Struct({
-  label: Schema.String,
-  hue: Schema.optional(Schema.String), // TODO(burdon): Color name?
-}).pipe(
-  internal.LabelAnnotation.set(['label']),
-  internal.HiddenAnnotation.set(true),
-  // Shared DXN so `meta.tags` (the `Ref<Tag>` schema) and this type stay in sync.
-  Type.makeObject(internal.TagTypeDXN),
-);
-
-export type Tag = Type.InstanceType<typeof Tag>;
+export class Tag extends Type.makeObject<Tag>(internal.TagTypeDXN)(
+  Schema.Struct({
+    label: Schema.String,
+    hue: Schema.optional(Schema.String), // TODO(burdon): Color name?
+  }).pipe(internal.LabelAnnotation.set(['label']), internal.HiddenAnnotation.set(true)),
+) {}
 
 export const make = (props: Obj.MakeProps<typeof Tag>) => Obj.make(Tag, props);
 
-export type Map = Record<string, Tag>;
+export type Map = Record<string, Type.InstanceType<typeof Tag>>;
 
-export const sortTags = ({ label: a }: Tag, { label: b }: Tag) => a.localeCompare(b);
+export const sortTags = ({ label: a }: Type.InstanceType<typeof Tag>, { label: b }: Type.InstanceType<typeof Tag>) =>
+  a.localeCompare(b);
 
-export const createTagList = (tags: Map): Tag[] =>
+export const createTagList = (tags: Map): Type.InstanceType<typeof Tag>[] =>
   Object.entries(tags)
     .map(([id, tag]) => ({ ...tag, id }))
     .sort(sortTags);
 
-export const findTagByLabel = (tags: Map | undefined, name: string): Tag | undefined => {
+export const findTagByLabel = (tags: Map | undefined, name: string): Type.InstanceType<typeof Tag> | undefined => {
   const entry = Object.entries(tags ?? {}).find(([_, tag]) => tag.label.toLowerCase() === name.toLowerCase());
   return entry ? { ...entry[1], id: entry[0] } : undefined;
 };
@@ -54,7 +50,7 @@ export const findTagByLabel = (tags: Map | undefined, name: string): Tag | undef
 export const findOrCreate = async (
   db: Pick<Database.Database, 'query' | 'add'>,
   options: { label: string; hue?: string; key?: ForeignKey },
-): Promise<Tag> => {
+): Promise<Type.InstanceType<typeof Tag>> => {
   const { label, hue, key } = options;
   const withHue = hue ? { hue } : {};
   if (key) {