@dxos/echo 0.8.4-main.548089c → 0.8.4-main.59c2e9b

package/src/internal/proxy/typed-handler.ts

@@ -7,24 +7,35 @@ import { type InspectOptionsStylized } from 'node:util';
 import * as Schema from 'effect/Schema';
 import * as SchemaAST from 'effect/SchemaAST';
 
+import { Event } from '@dxos/async';
 import { inspectCustom } from '@dxos/debug';
-import { type GenericSignal, compositeRuntime } from '@dxos/echo-signals/runtime';
 import { invariant } from '@dxos/invariant';
-import {
-  ReactiveArray,
-  type ReactiveHandler,
-  createProxy,
-  defineHiddenProperty,
-  isValidProxyTarget,
-  objectData,
-  symbolIsProxy,
-} from '@dxos/live-object';
 
-import { getSchemaDXN } from '../ast';
-import { DeletedId, SchemaId, SchemaValidator, TypeId } from '../object';
+import { getSchemaDXN } from '../annotations';
+import { ObjectDeletedId } from '../entities';
+import { SchemaId, TypeId } from '../types';
 
-const symbolSignal = Symbol('signal');
-const symbolPropertySignal = Symbol('property-signal');
+import { executeChange, isInChangeContext, queueNotification } from './change-context';
+import { defineHiddenProperty } from './define-hidden-property';
+import { createPropertyDeleteError } from './errors';
+import { batchEvents } from './event-batch';
+import {
+  getEchoRoot,
+  getOwner,
+  getRawTarget,
+  hasForeignOwner,
+  notifyOwnerChain,
+  setOwnerRecursive,
+  wouldCreateCycle,
+} from './ownership';
+import { type ReactiveHandler, objectData } from './proxy-types';
+import { createProxy, isProxy, isValidProxyTarget, symbolIsProxy } from './proxy-utils';
+import { ReactiveArray } from './reactive-array';
+import { SchemaValidator } from './schema-validator';
+import { ChangeId, EventId } from './symbols';
+
+// Re-export for external consumers.
+export { getEchoRoot, setMetaOwner } from './ownership';
 
 type ProxyTarget = {
   /**
@@ -38,24 +49,97 @@ type ProxyTarget = {
   [SchemaId]: Schema.Schema.AnyNoContext;
 
   /**
-   * For get and set operations on value properties.
-   */
-  // TODO(dmaretskyi): Turn into a map of signals per-field.
-  [symbolSignal]: GenericSignal;
-
-  /**
-   * For modifying the structure of the object.
+   * For modifications.
    */
-  [symbolPropertySignal]: GenericSignal;
+  [EventId]: Event<void>;
 } & ({ [key: keyof any]: any } | any[]);
 
+/**
+ * Deep copy a value, handling arrays and nested objects.
+ * Preserves ReactiveArray type and hidden properties (SchemaId, TypeId).
+ * Does not copy class instances or functions (except ReactiveArray).
+ *
+ * Note: Cannot use structuredClone because we need to:
+ * - Unwrap proxies
+ * - Preserve ReactiveArray instances
+ * - Copy Symbol-keyed hidden properties (SchemaId, TypeId)
+ * - Convert plain arrays to ReactiveArray
+ *
+ * Performance: O(n) where n is the total number of nested objects/arrays.
+ * For large structures, consider using Refs for frequently reassigned subtrees.
+ */
+const deepCopy = <T>(value: T, visited = new Map<object, object>()): T => {
+  if (value == null || typeof value !== 'object') {
+    return value;
+  }
+
+  // Handle proxies - get the underlying target.
+  const actualValue = getRawTarget(value);
+
+  // Check for circular references in the copy.
+  if (visited.has(actualValue)) {
+    return visited.get(actualValue) as T;
+  }
+
+  // Handle ReactiveArray specially to preserve reactivity.
+  if (actualValue instanceof ReactiveArray) {
+    const copy = new ReactiveArray<any>();
+    visited.set(actualValue, copy);
+    for (const item of actualValue) {
+      copy.push(deepCopy(item, visited));
+    }
+    // Copy hidden properties.
+    copyHiddenProperties(actualValue, copy);
+    return copy as T;
+  }
+
+  // Don't copy other class instances (objects with non-Object prototype).
+  const proto = Object.getPrototypeOf(actualValue);
+  if (proto !== Object.prototype && proto !== Array.prototype && proto !== null) {
+    return value; // Return as-is, don't copy class instances.
+  }
+
+  if (Array.isArray(actualValue)) {
+    // Plain arrays become ReactiveArrays.
+    const copy = new ReactiveArray<any>();
+    visited.set(actualValue, copy);
+    for (const item of actualValue) {
+      copy.push(deepCopy(item, visited));
+    }
+    return copy as T;
+  }
+
+  const copy: Record<string, any> = {};
+  visited.set(actualValue, copy);
+  for (const key of Object.keys(actualValue)) {
+    copy[key] = deepCopy((actualValue as any)[key], visited);
+  }
+  // Copy hidden properties (SchemaId, TypeId).
+  copyHiddenProperties(actualValue, copy);
+  return copy as T;
+};
+
+/**
+ * Copy hidden properties (SchemaId, TypeId) from source to target.
+ */
+const copyHiddenProperties = (source: any, target: any): void => {
+  if (SchemaId in source) {
+    defineHiddenProperty(target, SchemaId, source[SchemaId]);
+  }
+  if (TypeId in source) {
+    defineHiddenProperty(target, TypeId, source[TypeId]);
+  }
+};
+
 /**
  * Typed in-memory reactive store (with Schema).
+ * Reactivity is based on Event subscriptions, not signals.
  */
 export class TypedReactiveHandler implements ReactiveHandler<ProxyTarget> {
   public static readonly instance: ReactiveHandler<any> = new TypedReactiveHandler();
 
   readonly _proxyMap = new WeakMap<object, any>();
+  private _inSet = false;
 
   private constructor() {}
 
@@ -63,21 +147,44 @@ export class TypedReactiveHandler implements ReactiveHandler<ProxyTarget> {
     invariant(typeof target === 'object' && target !== null);
     invariant(SchemaId in target, 'Schema is not defined for the target');
 
-    if (!(symbolSignal in target)) {
-      defineHiddenProperty(target, symbolSignal, compositeRuntime.createSignal());
-      defineHiddenProperty(target, symbolPropertySignal, compositeRuntime.createSignal());
+    // Only set EventId on root objects (those without an owner).
+    // Nested objects share their root's EventId for centralized reactivity.
+    const hasOwner = !!getOwner(target);
+    if (!(EventId in target) && !hasOwner) {
+      defineHiddenProperty(target, EventId, new Event());
     }
 
-    defineHiddenProperty(target, DeletedId, false);
+    defineHiddenProperty(target, ObjectDeletedId, false);
 
-    for (const key of Object.getOwnPropertyNames(target)) {
-      const descriptor = Object.getOwnPropertyDescriptor(target, key)!;
-      if (descriptor.get) {
-        // Ignore getters.
-        continue;
-      }
+    // Mark root objects as having a change handler.
+    // The actual handler is returned dynamically in get() to have access to the proxy.
+    if (!hasOwner && !(ChangeId in target)) {
+      defineHiddenProperty(target, ChangeId, true);
+    }
 
-      // Array reactivity is already handled by the schema validator.
+    // Only set owners if this is a root object (no existing owner).
+    // Nested objects already have owners set by their root's initialization.
+    // If we re-set owners here for nested objects, we'd incorrectly point
+    // array elements to the array instead of the true root ECHO object.
+    if (!hasOwner) {
+      // Set owner on all nested objects to this root ECHO object.
+      // All nested records point directly to this root for centralized reactivity.
+      for (const key in target) {
+        if ((target as any)[symbolIsProxy]) {
+          continue;
+        }
+        let value = (target as any)[key];
+        if (isValidProxyTarget(value) || isProxy(value)) {
+          // Deep copy values that have foreign owners (owned by a different object,
+          // or are root ECHO objects whose nested structures would be owned by them).
+          // This recursively checks all nested objects.
+          if (hasForeignOwner(value, target)) {
+            value = deepCopy(value);
+            (target as any)[key] = value;
+          }
+          setOwnerRecursive(value, target);
+        }
+      }
     }
 
     // Maybe have been set by `create`.
@@ -90,23 +197,26 @@ export class TypedReactiveHandler implements ReactiveHandler<ProxyTarget> {
 
   get(target: ProxyTarget, prop: string | symbol, receiver: any): any {
     switch (prop) {
+      // TODO(burdon): Remove?
       case objectData: {
-        target[symbolSignal].notifyRead();
         return toJSON(target);
       }
+      case ChangeId: {
+        // Return change handler only for root objects that have been marked with ChangeId.
+        if ((target as any)[ChangeId] !== true) {
+          return undefined;
+        }
+        // Return a function that allows mutations within a controlled context.
+        // Uses target as both the context key and event target for non-database objects.
+        return (callback: (obj: any) => void) => executeChange(target, target, receiver, callback);
+      }
     }
 
-    // Handle getter properties. Will not subscribe the value signal.
+    // Handle getter properties.
     if (Object.getOwnPropertyDescriptor(target, prop)?.get) {
-      target[symbolPropertySignal].notifyRead();
-
-      // TODO(dmaretskyi): Turn getters into computed fields.
       return Reflect.get(target, prop, receiver);
     }
 
-    target[symbolSignal].notifyRead();
-    target[symbolPropertySignal].notifyRead();
-
     const value = Reflect.get(target, prop, receiver);
     if (isValidProxyTarget(value)) {
       return createProxy(value, this);
@@ -116,43 +226,145 @@ export class TypedReactiveHandler implements ReactiveHandler<ProxyTarget> {
   }
 
   set(target: ProxyTarget, prop: string | symbol, value: any, receiver: any): boolean {
-    // Convert arrays to reactive arrays on write.
-    if (Array.isArray(value)) {
-      value = ReactiveArray.from(value);
+    const echoRoot = getEchoRoot(target);
+
+    // Check readonly enforcement - mutations only allowed within Obj.change().
+    // Skip check if the object is still being initialized (no ChangeId handler yet).
+    // Also skip for non-initialized root objects (those without EventId).
+    // Skip for symbol properties (internal infrastructure, not user data).
+    const isInitialized = ChangeId in echoRoot || EventId in echoRoot;
+    const isSymbolProp = typeof prop === 'symbol';
+    if (isInitialized && !isSymbolProp && !isInChangeContext(echoRoot)) {
+      throw new Error(
+        `Cannot modify object property "${String(prop)}" outside of Obj.change(). ` +
+          'Use Obj.change(obj, (mutableObj) => { mutableObj.property = value; }) instead.',
+      );
     }
 
     let result: boolean = false;
-    compositeRuntime.batch(() => {
-      const validatedValue = this._validateValue(target, prop, value);
-      result = Reflect.set(target, prop, validatedValue, receiver);
-      target[symbolSignal].notifyWrite();
-    });
+    this._inSet = true;
+    try {
+      batchEvents(() => {
+        const { echoRoot: _, preparedValue } = this._prepareValueForAssignment(target, prop, value);
+        result = Reflect.set(target, prop, preparedValue, receiver);
+        // Queue notification instead of emitting immediately (batched).
+        if (isInitialized) {
+          queueNotification(echoRoot);
+          // Also notify the owner chain so parent objects are updated when nested objects change.
+          notifyOwnerChain(target);
+        }
+      });
+    } finally {
+      this._inSet = false;
+    }
     return result;
   }
 
   ownKeys(target: ProxyTarget): ArrayLike<string | symbol> {
-    // Touch both signals since `set` and `delete` operations may create or remove properties.
-    target[symbolSignal].notifyRead();
-    target[symbolPropertySignal].notifyRead();
     return Reflect.ownKeys(target);
   }
 
+  deleteProperty(target: ProxyTarget, property: string | symbol): boolean {
+    const echoRoot = getEchoRoot(target);
+
+    // Check readonly enforcement - mutations only allowed within Obj.change().
+    // Skip for symbol properties (internal infrastructure, not user data).
+    const isInitialized = (echoRoot as any)[ChangeId] === true || EventId in echoRoot;
+    const isSymbolProp = typeof property === 'symbol';
+    if (isInitialized && !isSymbolProp && !isInChangeContext(echoRoot)) {
+      throw createPropertyDeleteError(property);
+    }
+
+    const result = Reflect.deleteProperty(target, property);
+    if (isInitialized) {
+      queueNotification(echoRoot);
+    }
+    return result;
+  }
+
   defineProperty(target: ProxyTarget, property: string | symbol, attributes: PropertyDescriptor): boolean {
-    const validatedValue = this._validateValue(target, property, attributes.value);
+    const echoRoot = getEchoRoot(target);
+
+    // Check readonly enforcement - mutations only allowed within Obj.change().
+    // Skip check if the object is still being initialized (no ChangeId handler yet).
+    // Skip for symbol properties (internal infrastructure, not user data).
+    const isInitialized = ChangeId in echoRoot || EventId in echoRoot;
+    const isSymbolProp = typeof property === 'symbol';
+    if (isInitialized && !isSymbolProp && !isInChangeContext(echoRoot)) {
+      throw new Error(
+        `Cannot modify object property "${String(property)}" outside of Obj.change(). ` +
+          'Use Obj.change(obj, (mutableObj) => { mutableObj.property = value; }) instead.',
+      );
+    }
+
+    const { echoRoot: _, preparedValue } = this._prepareValueForAssignment(target, property, attributes.value);
     const result = Reflect.defineProperty(target, property, {
       ...attributes,
-      value: validatedValue,
+      value: preparedValue,
     });
-    target[symbolPropertySignal].notifyWrite();
+    if (!this._inSet && isInitialized) {
+      // Queue notification instead of emitting immediately (batched).
+      queueNotification(echoRoot);
+    }
     return result;
   }
 
+  /**
+   * Prepare a value for assignment to a typed object property.
+   * Handles cycle detection, copy-on-assign, array conversion, validation, and ownership.
+   */
+  private _prepareValueForAssignment(
+    target: ProxyTarget,
+    prop: string | symbol,
+    value: any,
+  ): { echoRoot: object; preparedValue: any } {
+    const echoRoot = getEchoRoot(target);
+
+    // Check for cycles before assignment.
+    if (isValidProxyTarget(value) || isProxy(value)) {
+      if (wouldCreateCycle(echoRoot, value)) {
+        throw new Error('Cannot create cycles in typed object graph. Consider using Ref for circular references.');
+      }
+    }
+
+    // Prevent direct assignment of root ECHO objects (those created with Obj.make/Relation.make).
+    // These must be wrapped with Ref.make for proper reference handling.
+    // This matches database object behavior for consistency.
+    if (isValidProxyTarget(value) || isProxy(value)) {
+      const actualValue = getRawTarget(value);
+      const isRootEchoObject = EventId in actualValue;
+      if (isRootEchoObject) {
+        throw new Error('Object references must be wrapped with `Ref.make`');
+      }
+    }
+
+    // Copy-on-assign: If the value is a nested record owned by a different ECHO object, deep copy it.
+    if (isValidProxyTarget(value) || isProxy(value)) {
+      const actualValue = getRawTarget(value);
+      const existingOwner = getOwner(actualValue);
+      if (existingOwner != null && existingOwner !== echoRoot) {
+        value = deepCopy(value);
+      }
+    }
+
+    // Convert arrays to reactive arrays.
+    if (Array.isArray(value) && !(value instanceof ReactiveArray)) {
+      value = ReactiveArray.from(value);
+    }
+
+    const validatedValue = this._validateValue(target, prop, value);
+
+    // Set owner on new value to the root ECHO object.
+    if (isValidProxyTarget(validatedValue) || isProxy(validatedValue)) {
+      setOwnerRecursive(validatedValue, echoRoot);
+    }
+
+    return { echoRoot, preparedValue: validatedValue };
+  }
+
   private _validateValue(target: any, prop: string | symbol, value: any) {
     const schema = SchemaValidator.getTargetPropertySchema(target, prop);
     const _ = Schema.asserts(schema)(value);
-    if (Array.isArray(value)) {
-      value = new ReactiveArray(...value);
-    }
     if (isValidProxyTarget(value)) {
       setSchemaProperties(value, schema);
     }
@@ -165,18 +377,20 @@ export class TypedReactiveHandler implements ReactiveHandler<ProxyTarget> {
     options: InspectOptionsStylized,
     inspectFn: (value: any, options?: InspectOptionsStylized) => string,
   ): string {
-    return `Typed ${inspectFn(this, {
+    const inspected = inspectFn(this, {
       ...options,
-      compact: true,
       showHidden: false,
       customInspect: false,
-    })}`;
+    });
+
+    return `Typed ${inspected}`;
   }
 }
 
 /**
  * @deprecated Use `Obj.toJSON` instead.
  */
+// TODO(burdon): Remove?
 const toJSON = (target: ProxyTarget): any => {
   return { '@type': 'TypedReactiveObject', ...target };
 };

package/src/internal/proxy/typed-object.test.ts

@@ -5,14 +5,16 @@
 import * as Schema from 'effect/Schema';
 import { describe, expect, test } from 'vitest';
 
-import { EchoObject, TypedObject, getSchema } from '..';
+import { EchoObjectSchema } from '../entities';
+import { getSchema } from '../types';
 
-import { live } from './reactive-object';
+import { makeObject } from './make-object';
+import { change } from './reactive';
 
 const Organization = Schema.Struct({
   name: Schema.String,
 }).pipe(
-  EchoObject({
+  EchoObjectSchema({
     typename: 'example.com/type/Organization',
     version: '0.1.0',
   }),
@@ -24,10 +26,13 @@ const Contact = Schema.Struct(
   {
     name: Schema.String,
   },
-  { key: Schema.String, value: Schema.Any },
+  {
+    key: Schema.String,
+    value: Schema.Any,
+  },
 ).pipe(
   Schema.partial,
-  EchoObject({
+  EchoObjectSchema({
     typename: 'example.com/type/Person',
     version: '0.1.0',
   }),
@@ -37,17 +42,19 @@ interface Contact extends Schema.Schema.Type<typeof Contact> {}
 
 const TEST_ORG: Omit<Organization, 'id'> = { name: 'Test' };
 
-describe('EchoObject class DSL', () => {
+describe('EchoObjectSchema class DSL', () => {
   test('can get object schema', async () => {
-    const obj = live(Organization, TEST_ORG);
+    const obj = makeObject(Organization, TEST_ORG);
     expect(getSchema(obj)).to.deep.eq(Organization);
   });
 
   describe('class options', () => {
     test('can assign undefined to partial fields', async () => {
-      const person = live(Contact, { name: 'John' });
-      person.name = undefined;
-      person.recordField = 'hello';
+      const person = makeObject(Contact, { name: 'John' });
+      change(person, (p) => {
+        p.name = undefined;
+        p.recordField = 'hello';
+      });
       expect(person.name).to.be.undefined;
       expect(person.recordField).to.eq('hello');
     });
@@ -65,36 +72,45 @@ describe('EchoObject class DSL', () => {
     );
 
     {
-      const object = live(schema, {});
-      (object.meta ??= {}).test = 100;
-      expect(object.meta.test).to.eq(100);
+      const object = makeObject(schema, {});
+      change(object, (o) => {
+        (o.meta ??= {}).test = 100;
+      });
+      expect(object.meta!.test).to.eq(100);
     }
 
     {
-      const object = live(schema, {});
-      object.meta = { test: { value: 300 } };
-      expect(object.meta.test.value).to.eq(300);
+      const object = makeObject(schema, {});
+      change(object, (o) => {
+        o.meta = { test: { value: 300 } };
+      });
+      expect(object.meta!.test.value).to.eq(300);
     }
 
     {
+      // Plain object (not a reactive proxy) - doesn't need Obj.change.
       type Test1 = Schema.Schema.Type<typeof schema>;
 
       const object: Test1 = {};
       (object.meta ??= {}).test = 100;
-      expect(object.meta.test).to.eq(100);
+      expect(object.meta!.test).to.eq(100);
     }
 
     {
-      class Test2 extends TypedObject({
-        typename: 'dxos.org/type/FunctionTrigger',
-        version: '0.1.0',
-      })({
+      const Test2 = Schema.Struct({
         meta: Schema.optional(Schema.mutable(Schema.Record({ key: Schema.String, value: Schema.Any }))),
-      }) {}
-
-      const object = live(Test2, {});
-      (object.meta ??= {}).test = 100;
-      expect(object.meta.test).to.eq(100);
+      }).pipe(
+        EchoObjectSchema({
+          typename: 'dxos.org/type/FunctionTrigger',
+          version: '0.1.0',
+        }),
+      );
+
+      const object = makeObject(Test2, {});
+      change(object, (o) => {
+        (o.meta ??= {}).test = 100;
+      });
+      expect(object.meta!.test).to.eq(100);
     }
   });
 });

package/src/internal/ref/ref-array.ts

@@ -5,7 +5,7 @@
 import { type ObjectId } from '@dxos/keys';
 import { isNonNullable } from '@dxos/util';
 
-import { type AnyEchoObject } from '../types';
+import { type AnyEntity } from '../types';
 
 import { Ref } from './ref';
 
@@ -16,21 +16,21 @@ export const RefArray = Object.freeze({
   /**
    * @returns all resolved targets.
    */
-  targets: <T extends AnyEchoObject>(refs: readonly Ref<T>[]): T[] => {
+  targets: <T extends AnyEntity>(refs: readonly Ref<T>[]): T[] => {
     return refs.map((ref) => ref.target).filter(isNonNullable);
   },
 
   /**
    * Load all referenced objects.
    */
-  loadAll: <T extends AnyEchoObject>(refs: readonly Ref<T>[]): Promise<T[]> => {
+  loadAll: <T extends AnyEntity>(refs: readonly Ref<T>[]): Promise<T[]> => {
     return Promise.all(refs.map((ref) => ref.load()));
   },
 
   /**
    * Removes the ref with the given id.
    */
-  removeById: (refs: Ref<AnyEchoObject>[], id: ObjectId) => {
+  removeById: (refs: Ref<AnyEntity>[], id: ObjectId) => {
     const index = refs.findIndex(Ref.hasObjectId(id));
     if (index >= 0) {
       refs.splice(index, 1);

package/src/internal/ref/ref.test.ts

@@ -7,14 +7,15 @@ import { describe, expect, test } from 'vitest';
 
 import { DXN, ObjectId } from '@dxos/keys';
 
-import { EchoObject, create, getObjectDXN } from '../object';
+import { EchoObjectSchema, getObjectDXN } from '../entities';
+import { createObject } from '../object';
 
 import { Ref, getReferenceAst } from './ref';
 
 const Task = Schema.Struct({
   title: Schema.optional(Schema.String),
 }).pipe(
-  EchoObject({
+  EchoObjectSchema({
     typename: 'example.com/type/Task',
     version: '0.1.0',
   }),
@@ -27,7 +28,7 @@ const Contact = Schema.Struct({
   email: Schema.optional(Schema.String),
   tasks: Schema.mutable(Schema.Array(Ref(Task))),
 }).pipe(
-  EchoObject({
+  EchoObjectSchema({
     typename: 'example.com/type/Person',
     version: '0.1.0',
   }),
@@ -49,8 +50,8 @@ describe('Ref', () => {
 
   // TODO(dmaretskyi): Figure out how to expose this in the API.
   test.skip('encode with inlined target', () => {
-    const task = create(Task, { title: 'Fix bugs' });
-    const contact = create(Contact, { name: 'John Doe', tasks: [Ref.make(task)] });
+    const task = createObject(Task, { title: 'Fix bugs' });
+    const contact = createObject(Contact, { name: 'John Doe', tasks: [Ref.make(task)] });
 
     const json = JSON.parse(JSON.stringify(contact));
     expect(json).toEqual({
@@ -70,8 +71,8 @@ describe('Ref', () => {
   });
 
   test('encode without inlining target', () => {
-    const task = create(Task, { title: 'Fix bugs' });
-    const contact = create(Contact, { name: 'John Doe', tasks: [Ref.make(task).noInline()] });
+    const task = createObject(Task, { title: 'Fix bugs' });
+    const contact = createObject(Contact, { name: 'John Doe', tasks: [Ref.make(task).noInline()] });
 
     const json = JSON.parse(JSON.stringify(contact));
     expect(json).toEqual({