@dxos/echo 0.8.4-main.21d9917 → 0.8.4-main.2244d791bb

package/src/Obj.ts

@@ -2,7 +2,9 @@
 // Copyright 2025 DXOS.org
 //
 
+import * as Effect from 'effect/Effect';
 import * as Function from 'effect/Function';
+import * as Option from 'effect/Option';
 import * as Schema from 'effect/Schema';
 
 import type { ForeignKey } from '@dxos/echo-protocol';
@@ -13,6 +15,7 @@ import { assumeType } from '@dxos/util';
 
 import type * as Database from './Database';
 import * as Entity from './Entity';
+import * as Err from './Err';
 import {
   type ObjectJSON as APIJSON,
   type AnyEntity,
@@ -27,7 +30,9 @@ import {
   MetaId,
   type Mutable,
   type ObjectMeta,
-  type SnapshotKindId,
+  // TODO(dmaretskyi): Export ParentId?
+  ParentId,
+  SnapshotKindId,
   type VersionCompareResult,
   VersionTypeId,
   addTag as addTag$,
@@ -133,6 +138,7 @@ type Props<T = any> = {
 export type MakeProps<S extends Schema.Schema.AnyNoContext> = {
   id?: ObjectId;
   [Meta]?: Partial<ObjectMeta>;
+  [Parent]?: Unknown;
 } & NoInfer<Props<Schema.Schema.Type<S>>>;
 
 /**
@@ -169,8 +175,16 @@ export const make: {
     delete props[MetaId];
   }
 
-  // Filter undefined values.
-  const filterUndefined = Object.fromEntries(Object.entries(props).filter(([_, v]) => v !== undefined));
+  // Filter undefined values (Object.entries only returns string-keyed properties).
+  const filterUndefined: any = Object.fromEntries(Object.entries(props).filter(([_, v]) => v !== undefined));
+
+  // Copy symbol properties (like ParentId) that Object.entries doesn't include.
+  for (const sym of Object.getOwnPropertySymbols(props)) {
+    const value = (props as any)[sym];
+    if (value !== undefined) {
+      filterUndefined[sym] = value;
+    }
+  }
 
   return makeObject<Schema.Schema.Type<S>>(schema, filterUndefined as any, {
     ...defaultMeta,
@@ -207,6 +221,60 @@ export const subscribe = (obj: Unknown, callback: () => void): (() => void) => {
  */
 export const getSnapshot: <T extends Unknown>(obj: T) => Snapshot<T> = getSnapshot$ as any;
 
+/**
+ * Returns the reactive version of an object from the database, given its snapshot.
+ * Inverse of `Obj.getSnapshot`.
+ *
+ * Uses `Obj.getDatabase` internally to get the database from the snapshot,
+ * then resolves the reactive object by ID.
+ *
+ * @param snapshot - A snapshot of the object (from `Obj.getSnapshot`).
+ * @returns Effect that succeeds with the reactive object, or fails with `GetReactiveError`.
+ * @example
+ * ```ts
+ * const snapshot = Obj.getSnapshot(obj);
+ * const reactive = Obj.getReactive(snapshot).pipe(
+ *   Effect.runSync
+ * );
+ * ```
+ */
+export const getReactive = <T extends Unknown>(snapshot: Snapshot<T>): Effect.Effect<T, Err.GetReactiveError> =>
+  Effect.gen(function* () {
+    const db = getDatabase$(snapshot);
+    if (!db) {
+      return yield* Effect.fail(new Err.GetReactiveError({ reason: 'no-database', snapshotId: snapshot.id }));
+    }
+    const obj = db.getObjectById(snapshot.id);
+    if (!obj) {
+      return yield* Effect.fail(new Err.GetReactiveError({ reason: 'object-not-found', snapshotId: snapshot.id }));
+    }
+    return obj as T;
+  });
+
+/**
+ * Like `Obj.getReactive` but returns `Option.none()` instead of failing when the object
+ * cannot be resolved (no database, object not found).
+ *
+ * @param snapshot - A snapshot of the object (from `Obj.getSnapshot`).
+ * @returns Effect that succeeds with `Option.some(reactive)` or `Option.none()`.
+ */
+export const getReactiveOption = <T extends Unknown>(snapshot: Snapshot<T>): Effect.Effect<Option.Option<T>, never> =>
+  getReactive(snapshot).pipe(
+    Effect.map(Option.some),
+    Effect.catchAll(() => Effect.succeed(Option.none())),
+  );
+
+/**
+ * Synchronous version of `Obj.getReactive`. Returns the reactive object or throws
+ * `GetReactiveError` when the object cannot be resolved (no database, object not found).
+ *
+ * @param snapshot - A snapshot of the object (from `Obj.getSnapshot`).
+ * @returns The reactive object.
+ * @throws {Err.GetReactiveError} When the object cannot be resolved.
+ */
+export const getReactiveOrThrow = <T extends Unknown>(snapshot: Snapshot<T>): T =>
+  Effect.runSync(getReactive(snapshot));
+
 export type CloneOptions = {
   /**
    * Retain the original object's ID.
@@ -316,7 +384,7 @@ export const getValue = (obj: Unknown | Snapshot, path: readonly (string | numbe
  * @example
  * ```ts
  * const person = Obj.make(Person, { name: 'John' });
- * // Person schema has: addresses: Schema.mutable(Schema.Array(Address))
+ * // Person schema has: addresses: Schema.Array(Address)
  * Obj.change(person, (p) => {
  *   Obj.setValue(p, ['addresses', 0, 'street'], '123 Main St');
  * });
@@ -357,6 +425,33 @@ export const instanceOf: {
   return isInstanceOf(args[0], args[1]);
 }) as any;
 
+/**
+ * Test if a snapshot is an instance of a schema.
+ * Mirrors `instanceOf` but only accepts values branded with SnapshotKindId.
+ * Use when the value is known to be a snapshot (e.g. from `getSnapshot` or `useObject`).
+ *
+ * @example
+ * ```ts
+ * const snapshot = Obj.getSnapshot(person);
+ * if (Obj.snapshotOf(Person, snapshot)) {
+ *   // snapshot is Obj.Snapshot<Person>
+ * }
+ * ```
+ */
+export const snapshotOf: {
+  <S extends Type.Entity.Any>(schema: S): (value: unknown) => value is Snapshot<Schema.Schema.Type<S>>;
+  <S extends Type.Entity.Any>(schema: S, value: unknown): value is Snapshot<Schema.Schema.Type<S>>;
+} = ((...args: [schema: Type.Entity.Any, value: unknown] | [schema: Type.Entity.Any]) => {
+  const check = (entity: unknown) =>
+    entity != null && typeof entity === 'object' && SnapshotKindId in entity && isInstanceOf(args[0], entity);
+
+  if (args.length === 1) {
+    return (entity: unknown) => check(entity);
+  }
+
+  return check(args[1]);
+}) as any;
+
 // TODO(dmaretskyi): Allow returning undefined.
 /**
  * Get the DXN of the object.
@@ -396,7 +491,8 @@ export const getTypename = (entity: Unknown | Snapshot): string | undefined => g
  * Get the database the object belongs to.
  * Accepts both reactive objects and snapshots.
  */
-export const getDatabase = (entity: Unknown | Snapshot): Database.Database | undefined => getDatabase$(entity);
+export const getDatabase = (entity: Entity.Unknown | Entity.Snapshot): Database.Database | undefined =>
+  getDatabase$(entity);
 
 //
 // Meta
@@ -436,9 +532,9 @@ export type Meta = ApiMeta;
  * ```
  */
 // 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: Mutable<Unknown>): Meta;
 export function getMeta(entity: Unknown | Snapshot): ReadonlyMeta;
-export function getMeta(entity: Unknown | Snapshot | Mutable<Unknown>): ObjectMeta | ReadonlyMeta {
+export function getMeta(entity: Unknown | Snapshot | Mutable<Unknown>): Meta | ReadonlyMeta {
   return getMeta$(entity);
 }
 
@@ -520,6 +616,43 @@ export const getDescription = (entity: Unknown | Snapshot): string | undefined =
 export const setDescription = (entity: Mutable<Unknown>, description: string): void =>
   setDescription$(entity, description);
 
+/**
+ * Symbol to set parent when creating objects with `Obj.make`.
+ * @example
+ * ```ts
+ * Obj.make(TestSchema.Person, {
+ *   [Obj.Parent]: parentObject,
+ *   name: 'John',
+ * })
+ * ```
+ */
+export const Parent: unique symbol = ParentId as any;
+
+/**
+ * Get the parent of an object.
+ * The parent is always loaded together with the object.
+ * Only objects are allowed to have a parent
+ * @returns The parent object, or undefined if the object has no parent.
+ */
+export const getParent = (entity: Unknown | Snapshot): Unknown | undefined => {
+  assertArgument(isObject(entity), 'Expected an object');
+  assumeType<InternalObjectProps>(entity);
+  return entity[ParentId] as Unknown | undefined;
+};
+
+/**
+ * Sets the parent of an object.
+ * If a parent (or any transitive parent) is deleted, the object will be deleted.
+ * Only objects are allowed to have a parent.
+ */
+export const setParent = (entity: Unknown, parent: Any | undefined) => {
+  assertArgument(isObject(entity), 'Expected an object');
+  assertArgument(parent === undefined || isObject(parent), 'Expected an object');
+  assumeType<InternalObjectProps>(entity);
+  assumeType<InternalObjectProps | undefined>(parent);
+  entity[ParentId] = parent;
+};
+
 //
 // JSON
 //
@@ -549,10 +682,6 @@ export const toJSON = (entity: Unknown | Snapshot): JSON => toJSON$(entity);
 export const fromJSON: (json: unknown, options?: { refResolver?: Ref.Resolver; dxn?: DXN }) => Promise<Unknown> =
   objectFromJSON as any;
 
-//
-// Sorting
-//
-
 /**
  * Comparator function type for sorting objects.
  * Accepts both reactive objects and snapshots.

package/src/Query.ts

@@ -102,6 +102,18 @@ export interface Query<T> {
    */
   target(): Query<Type$.Relation.Target<T>>;
 
+  /**
+   * Get the parent object of the current selection.
+   * @returns Query for the parent objects.
+   */
+  parent(): Query<any>;
+
+  /**
+   * Get all child objects of the current selection.
+   * @returns Query for the child objects.
+   */
+  children(): Query<any>;
+
   /**
    * Order the query results.
    * Orders are specified in priority order. The first order will be applied first, etc.
@@ -202,6 +214,22 @@ class QueryClass implements Any {
     });
   }
 
+  parent(): Any {
+    return new QueryClass({
+      type: 'hierarchy-traversal',
+      anchor: this.ast,
+      direction: 'to-parent',
+    });
+  }
+
+  children(): Any {
+    return new QueryClass({
+      type: 'hierarchy-traversal',
+      anchor: this.ast,
+      direction: 'to-children',
+    });
+  }
+
   orderBy(...order: Order.Order<any>[]): Any {
     return new QueryClass({
       type: 'order',

package/src/Relation.ts

@@ -29,6 +29,7 @@ import {
   MetaId,
   type Mutable,
   type ObjectMeta,
+  ParentId,
   RelationSourceDXNId,
   RelationSourceId,
   RelationTargetDXNId,
@@ -133,7 +134,7 @@ export type MakeProps<S extends Type.Relation.Any> = RelationMakeProps<Schema.Sc
  * Creates new relation.
  * @param schema - Relation schema.
  * @param props - Relation properties. Endpoints are passed as [Relation.Source] and [Relation.Target] keys.
- * @param meta - Relation metadata.
+ * @param meta - Relation metadata. (deprecated; use [Obj.Meta] instead)
  * @returns
  */
 // NOTE: Writing the definition this way (with generic over schema) makes typescript perfer to infer the type from the first param (this schema) rather than the second param (the props).
@@ -144,6 +145,7 @@ export const make = <S extends Type.Relation.Any>(
   meta?: ObjectMeta,
 ): Schema.Schema.Type<S> & Entity.OfKind<typeof Entity.Kind.Relation> => {
   assertArgument(getTypeAnnotation(schema)?.kind === EntityKind.Relation, 'schema', 'Expected a relation schema');
+  assertArgument(props[ParentId] === undefined, 'props', 'Parent is not allowed for relations');
 
   if (props[MetaId] != null) {
     meta = props[MetaId] as any;
@@ -372,9 +374,9 @@ export type Meta = ApiMeta;
  * 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: Mutable<Unknown>): Meta;
 export function getMeta(entity: Unknown | Snapshot): ReadonlyMeta;
-export function getMeta(entity: Unknown | Snapshot | Mutable<Unknown>): ObjectMeta | ReadonlyMeta {
+export function getMeta(entity: Unknown | Snapshot | Mutable<Unknown>): Meta | ReadonlyMeta {
   return getMeta$(entity);
 }
 

package/src/hierarchy.test.ts

@@ -0,0 +1,33 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { describe, expect, test } from 'vitest';
+
+import * as Obj from './Obj';
+import { TestSchema } from './testing';
+
+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/internal/annotations/annotations.ts

@@ -15,7 +15,7 @@ import { type Primitive } from '@dxos/util';
 
 import { type AnyProperties, EntityKind, TypeId, getSchema } from '../types';
 
-import { createAnnotationHelper } from './util';
+import { type AnnotationHelper, createAnnotationHelper } from './util';
 
 /**
  * @internal
@@ -458,3 +458,30 @@ export type GeneratorAnnotationValue =
     };
 
 export const GeneratorAnnotation = createAnnotationHelper<GeneratorAnnotationValue>(GeneratorAnnotationId);
+
+interface MakeAnnoationsProps<T> {
+  id: string;
+  schema: Schema.Schema<T, any, never>;
+}
+
+// TODO(wittjosiah): Comment.
+export const makeUserAnnotation = <T>(props: MakeAnnoationsProps<T>): AnnotationHelper<T> => {
+  assertArgument(
+    /[a-zA-Z0-9]+\.[a-zA-Z.]+\/[a-zA-Z/]+/.test(props.id),
+    'id',
+    'Annotation id must be in the FQN format (dxos.org/annotation/Example).',
+  );
+
+  const getFromAst = (ast: SchemaAST.AST) =>
+    SchemaAST.getAnnotation<PropertyMetaAnnotation>(PropertyMetaAnnotationId)(ast).pipe(
+      Option.map((meta) => meta[props.id] as unknown),
+      Option.map(Schema.decodeUnknownSync(props.schema)),
+    );
+
+  return {
+    get: (schema) => getFromAst(schema.ast),
+    getFromAst: (ast) => getFromAst(ast),
+    set: (value) =>
+      PropertyMeta(props.id, Schema.encodeSync(props.schema)(value)) as <S extends Schema.Schema.Any>(schema: S) => S,
+  };
+};

package/src/internal/annotations/util.ts

@@ -12,11 +12,24 @@ import { DXN } from '@dxos/keys';
 import { EntityKind } from '../types';
 
 export interface AnnotationHelper<T> {
+  /**
+   * Get the annotation value from the schema.
+   */
   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 value on the schema.
+   */
   set: (value: T) => <S extends Schema.Schema.Any>(schema: S) => S;
 }
 
+/**
+ * Note: only for system annotations.
+ */
+// TODO(dmaretskyi): Rename to createSystemAnnotationHelper.
 export const createAnnotationHelper = <T>(id: symbol): AnnotationHelper<T> => {
   return {
     get: (schema) => SchemaAST.getAnnotation(schema.ast, id),

package/src/internal/api/meta.ts

@@ -17,7 +17,7 @@ export type ReadonlyMeta = DeepReadonly<ObjectMeta>;
 /**
  * Mutable meta type received in meta mutation callbacks.
  */
-export type Meta = ObjectMeta;
+export type Meta = Mutable<ObjectMeta>;
 
 /**
  * Get the metadata for an entity with validation.
@@ -26,9 +26,9 @@ export type Meta = ObjectMeta;
  *
  * TODO(burdon): When passed a Snapshot, should return a snapshot of meta, not the live meta proxy.
  */
-export function getMetaChecked(entity: Mutable<AnyProperties>): ObjectMeta;
+export function getMetaChecked(entity: Mutable<AnyProperties>): Meta;
 export function getMetaChecked(entity: AnyProperties): ReadonlyMeta;
-export function getMetaChecked(entity: AnyProperties): ObjectMeta | ReadonlyMeta {
+export function getMetaChecked(entity: AnyProperties): Meta | ReadonlyMeta {
   assertArgument(entity, 'entity', 'Should be an entity.');
   const meta = getMeta$(entity);
   invariant(meta != null, 'Invalid entity.');

package/src/internal/entities/model.ts

@@ -12,11 +12,13 @@ import { assumeType } from '@dxos/util';
 import type * as Database from '../../Database';
 import {
   type ATTR_META,
+  type ATTR_PARENT,
   type ATTR_TYPE,
   EntityKind,
   KindId,
   type MetaId,
   type ObjectMeta,
+  type ParentId,
   type SchemaId,
   TypeId,
   type Version,
@@ -77,6 +79,7 @@ export interface InternalObjectProps {
   readonly [SchemaId]: Schema.Schema.AnyNoContext;
   readonly [TypeId]: DXN;
   readonly [MetaId]?: ObjectMeta;
+  [ParentId]?: InternalObjectProps;
   readonly [ObjectDatabaseId]?: Database.Database;
   readonly [ObjectDeletedId]?: boolean;
   readonly [ObjectVersionId]?: Version;
@@ -101,6 +104,7 @@ export interface ObjectJSON {
   id: string;
   [ATTR_TYPE]: DXN.String;
   [ATTR_SELF_DXN]?: DXN.String;
+  [ATTR_PARENT]?: string; // Encoded reference
   [ATTR_DELETED]?: boolean;
   [ATTR_META]?: ObjectMetaJSON;
   [ATTR_RELATION_SOURCE]?: DXN.String;

package/src/internal/entities/object.ts

@@ -40,9 +40,7 @@ export const EchoObjectSchema: {
     // Extract fields from the schema if available (Struct schemas have .fields).
     const fields = ((self as any).fields ?? {}) as Fields;
 
-    // TODO(dmaretskyi): Does `Schema.mutable` work for deep mutability here?
-    // TODO(dmaretskyi): Do not do mutable here.
-    const schemaWithId = Schema.extend(Schema.mutable(self), Schema.Struct({ id: Schema.String }));
+    const schemaWithId = Schema.extend(self, Schema.Struct({ id: Schema.String }));
     const ast = SchemaAST.annotations(schemaWithId.ast, {
       // TODO(dmaretskyi): `extend` kills the annotations.
       ...self.ast.annotations,

package/src/internal/entities/relation.ts

@@ -129,9 +129,7 @@ export const EchoRelationSchema = <
     // Extract fields from the schema if available (Struct schemas have .fields).
     const fields = ((self as any).fields ?? {}) as Fields;
 
-    // TODO(dmaretskyi): Does `Schema.mutable` work for deep mutability here?
-    // TODO(dmaretskyi): Do not do mutable here.
-    const schemaWithId = Schema.extend(Schema.mutable(self), Schema.Struct({ id: Schema.String }));
+    const schemaWithId = Schema.extend(self, Schema.Struct({ id: Schema.String }));
     const ast = SchemaAST.annotations(schemaWithId.ast, {
       // TODO(dmaretskyi): `extend` kills the annotations.
       ...self.ast.annotations,

package/src/internal/formats/format.test.ts

@@ -20,7 +20,7 @@ describe('formats', () => {
       birthday: Schema.optional(Format.Date),
       started: Schema.optional(Format.DateTime),
       active: Schema.optional(Schema.Boolean),
-    }).pipe(Schema.mutable);
+    });
 
     type TestType = Schema.Schema.Type<typeof TestSchema>;
 

package/src/internal/formats/select.ts

@@ -13,6 +13,6 @@ export const SelectOption = Schema.Struct({
   title: Schema.String,
   /** Color palette used for visual styling. */
   color: Schema.String,
-}).pipe(Schema.mutable);
+});
 
 export type SelectOption = Schema.Schema.Type<typeof SelectOption>;

package/src/internal/formats/types.ts

@@ -135,7 +135,7 @@ export const typeToFormat: Partial<Record<TypeEnum, TypeFormat>> = {
  * Map of format to type.
  */
 export const formatToType: Record<TypeFormat, TypeEnum> = {
-  [TypeFormat.None]: undefined as any,
+  [TypeFormat.None]: TypeEnum.String,
   [TypeFormat.String]: TypeEnum.String,
   [TypeFormat.Number]: TypeEnum.Number,
   [TypeFormat.Boolean]: TypeEnum.Boolean,

package/src/internal/json-schema/json-schema-normalize.ts

@@ -2,6 +2,8 @@
 // Copyright 2025 DXOS.org
 //
 
+import type * as Types from 'effect/Types';
+
 import { JsonSchemaFields, type JsonSchemaType } from './json-schema-type';
 
 /**
@@ -9,12 +11,12 @@ import { JsonSchemaFields, type JsonSchemaType } from './json-schema-type';
  * Note: the input type does not necessarily match the {@link JsonSchemaType} type.
  */
 export const normalizeSchema = (schema: JsonSchemaType): JsonSchemaType => {
-  const copy = structuredClone(schema);
+  const copy = structuredClone(schema) as Types.DeepMutable<JsonSchemaType>;
   go(copy);
   return copy;
 };
 
-const go = (schema: JsonSchemaType) => {
+const go = (schema: Types.DeepMutable<JsonSchemaType>) => {
   if (typeof schema !== 'object' || schema === null) {
     return;
   }