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

package/src/internal/proxy/errors.ts

@@ -0,0 +1,42 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+/**
+ * Error thrown when attempting to mutate an object outside of an Obj.change() context.
+ */
+export class MutationOutsideChangeContextError extends Error {
+  constructor(operation: string, suggestion: string) {
+    super(
+      `Cannot ${operation} outside of Obj.change(). Use Obj.change(obj, (mutableObj) => { ${suggestion} }) instead.`,
+    );
+    this.name = 'MutationOutsideChangeContextError';
+  }
+}
+
+/**
+ * Create an error for attempting to set a property outside of a change context.
+ */
+export const createPropertySetError = (prop: string | symbol): MutationOutsideChangeContextError => {
+  return new MutationOutsideChangeContextError(
+    `modify object property "${String(prop)}"`,
+    `mutableObj.${String(prop)} = value;`,
+  );
+};
+
+/**
+ * Create an error for attempting to delete a property outside of a change context.
+ */
+export const createPropertyDeleteError = (prop: string | symbol): MutationOutsideChangeContextError => {
+  return new MutationOutsideChangeContextError(
+    `delete object property "${String(prop)}"`,
+    `delete mutableObj.${String(prop)};`,
+  );
+};
+
+/**
+ * Create an error for attempting to call an array method outside of a change context.
+ */
+export const createArrayMethodError = (method: string): MutationOutsideChangeContextError => {
+  return new MutationOutsideChangeContextError(`call array.${method}()`, `mutableObj.array.${method}(...);`);
+};

package/src/internal/proxy/event-batch.ts

@@ -0,0 +1,44 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { EventId } from './symbols';
+
+/**
+ * Simple batching mechanism for EventId emissions.
+ * When batch depth > 0, events are collected instead of emitted immediately.
+ * When batch depth returns to 0, pending events are emitted.
+ */
+let eventBatchDepth = 0;
+const pendingEventTargets = new Set<object>();
+
+/**
+ * Run a callback in a batched context for EventId emissions.
+ * Multiple mutations within the batch will only emit one event per target.
+ */
+export const batchEvents = (callback: () => void): void => {
+  eventBatchDepth++;
+  try {
+    callback();
+  } finally {
+    eventBatchDepth--;
+    if (eventBatchDepth === 0) {
+      // Emit pending events.
+      for (const target of pendingEventTargets) {
+        (target as any)[EventId]?.emit();
+      }
+      pendingEventTargets.clear();
+    }
+  }
+};
+
+/**
+ * Emit an event on a target, respecting batching.
+ */
+export const emitEvent = (target: object): void => {
+  if (eventBatchDepth > 0) {
+    pendingEventTargets.add(target);
+  } else {
+    (target as any)[EventId]?.emit();
+  }
+};

package/src/internal/proxy/handler.test.ts

@@ -6,8 +6,6 @@ import { inspect } from 'node:util';
 
 import { describe, expect, test } from 'vitest';
 
-import { registerSignalsRuntime } from '@dxos/echo-signals';
-import { type Live, objectData } from '@dxos/live-object';
 import { isNode } from '@dxos/util';
 
 import { TestSchema, updateCounter } from '../../testing';
@@ -15,8 +13,8 @@ import { createObject } from '../object';
 import { ATTR_META } from '../types';
 
 import { makeObject } from './make-object';
-
-registerSignalsRuntime();
+import { objectData } from './proxy-types';
+import { change } from './reactive';
 
 describe('proxy', () => {
   test.skipIf(!isNode())('inspect', ({ expect }) => {
@@ -37,36 +35,41 @@ const TEST_OBJECT: TestSchema.ExampleSchema = {
   },
 };
 
-for (const schema of [undefined, TestSchema.ExampleSchema]) {
-  const createObject = (props: Partial<TestSchema.ExampleSchema> = {}): Live<TestSchema.ExampleSchema> => {
-    return schema == null ? (makeObject(props) as TestSchema.ExampleSchema) : makeObject(schema, props);
+// Schema is now required for reactive objects.
+{
+  const createObject = (props: Partial<TestSchema.ExampleSchema> = {}): TestSchema.ExampleSchema => {
+    return makeObject(TestSchema.ExampleSchema, props);
   };
 
-  describe(`Non-echo specific proxy properties${schema == null ? '' : ' with schema'}`, () => {
+  describe('Non-echo specific proxy properties with schema', () => {
     test.skipIf(!isNode())('inspect', () => {
       const obj = createObject({ string: 'bar' });
       const str = inspect(obj, { colors: false });
-      expect(str).to.eq(`${schema == null ? '' : 'Typed '}{ string: 'bar' }`);
+      expect(str).to.eq("Typed { string: 'bar' }");
     });
 
     test('data symbol', async () => {
       const obj = createObject({ ...TEST_OBJECT });
       const objData: any = (obj as any)[objectData];
       expect(objData).to.deep.contain({
-        '@type': `${schema ? 'Typed' : ''}ReactiveObject`,
+        '@type': 'TypedReactiveObject',
         ...TEST_OBJECT,
       });
     });
 
+    // TODO(wittjosiah): Should we prevent this?
     test('can assign class instances', () => {
       const obj = createObject();
 
       const classInstance = new TestSchema.TestClass();
-      obj.classInstance = classInstance;
+      change(obj, (o) => {
+        o.classInstance = classInstance;
+      });
       expect(obj.classInstance!.field).to.eq('value');
       expect(obj.classInstance instanceof TestSchema.TestClass).to.eq(true);
       expect(obj.classInstance === classInstance).to.be.true;
 
+      // Class instances are not wrapped in proxies, so direct mutation works.
       obj.classInstance!.field = 'baz';
       expect(obj.classInstance!.field).to.eq('baz');
     });
@@ -75,18 +78,14 @@ for (const schema of [undefined, TestSchema.ExampleSchema]) {
       test('toJSON', () => {
         const original = { classInstance: new TestSchema.TestClass() };
         const reactive = createObject(original);
-        if (!schema) {
-          expect(JSON.stringify(reactive)).to.eq(JSON.stringify(original));
-        } else {
-          expect(JSON.stringify(reactive)).to.eq(
-            JSON.stringify({
-              [ATTR_META]: {
-                keys: [],
-              },
-              ...original,
-            }),
-          );
-        }
+        expect(JSON.stringify(reactive)).to.eq(
+          JSON.stringify({
+            [ATTR_META]: {
+              keys: [],
+            },
+            ...original,
+          }),
+        );
       });
 
       test('chai deep equal works', () => {
@@ -104,14 +103,14 @@ for (const schema of [undefined, TestSchema.ExampleSchema]) {
       });
     });
 
-    describe('signal updates', () => {
-      test('not in nested class instances', () => {
+    describe('subscription updates', () => {
+      test('not triggered by nested class instance changes', () => {
         const obj = createObject({ classInstance: new TestSchema.TestClass() });
-        using updates = updateCounter(() => {
-          obj.classInstance!.field;
-        });
+        using updates = updateCounter(obj);
         expect(updates.count, 'update count').to.eq(0);
 
+        // Changes to class instance fields don't trigger subscription updates
+        // because class instances aren't wrapped in live proxies.
         obj.classInstance!.field = 'baz';
         expect(updates.count, 'update count').to.eq(0);
       });
@@ -119,55 +118,6 @@ for (const schema of [undefined, TestSchema.ExampleSchema]) {
   });
 }
 
-describe('getters', () => {
-  test('add getter to object', () => {
-    let value = 'foo';
-    const obj = makeObject({
-      get getter() {
-        return value;
-      },
-    });
-    expect(obj.getter).to.eq('foo');
-
-    value = 'bar';
-    expect(obj.getter).to.eq('bar');
-  });
-
-  test('signal updates', () => {
-    const innerObj = makeObject({
-      string: 'bar',
-    });
-
-    const obj = makeObject({
-      field: 1,
-      get getter() {
-        return innerObj.string;
-      },
-    });
-
-    using updates = updateCounter(() => {
-      const value = obj.getter;
-      expect(value).to.exist;
-    });
-
-    innerObj.string = 'baz';
-    expect(obj.getter).to.eq('baz');
-    expect(updates.count, 'update count').to.eq(1);
-
-    obj.field = 2;
-    expect(updates.count, 'update count').to.eq(1);
-  });
-
-  test('getter for array', () => {
-    const value = [1];
-    const obj = makeObject({
-      get getter() {
-        return value;
-      },
-    });
-    expect(obj.getter).to.have.length(1);
-
-    value.push(2);
-    expect(obj.getter).to.have.length(2);
-  });
-});
+// NOTE: Getter tests with external variable references were removed.
+// These patterns only worked with untyped reactive objects, which are no longer supported.
+// For typed schemas, getters should be defined in the schema itself.

package/src/internal/proxy/index.ts

@@ -2,5 +2,16 @@
 // Copyright 2025 DXOS.org
 //
 
+export * from './change-context';
+export * from './define-hidden-property';
+export * from './errors';
+export * from './event-batch';
+export * from './json-serializer';
 export * from './make-object';
+export * from './proxy-types';
+export * from './proxy-utils';
+export * from './reactive';
+export * from './reactive-array';
+export * from './schema-validator';
+export * from './symbols';
 export * from './typed-handler';

package/src/internal/proxy/json-serializer.ts

@@ -0,0 +1,87 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type ObjectMeta } from '@dxos/echo-protocol';
+import { invariant } from '@dxos/invariant';
+import { DXN } from '@dxos/keys';
+import { deepMapValues } from '@dxos/util';
+
+import {
+  ATTR_RELATION_SOURCE,
+  ATTR_RELATION_TARGET,
+  ATTR_SELF_DXN,
+  RelationSourceDXNId,
+  RelationTargetDXNId,
+  SelfDXNId,
+} from '../entities';
+import { Ref } from '../ref';
+import { ATTR_META, ATTR_TYPE, MetaId, TypeId } from '../types';
+
+/**
+ * Attaches a toJSON method to the object for typed serialization.
+ */
+export const attachTypedJsonSerializer = (obj: any) => {
+  const descriptor = Object.getOwnPropertyDescriptor(obj, 'toJSON');
+  if (descriptor) {
+    return;
+  }
+
+  Object.defineProperty(obj, 'toJSON', {
+    value: typedJsonSerializer,
+    writable: false,
+    enumerable: false,
+    // Setting `configurable` to false breaks proxy invariants, should be fixable.
+    configurable: true,
+  });
+};
+
+// NOTE: KEEP as function.
+// Exported for use in objectToJSON.
+export const typedJsonSerializer = function (this: any) {
+  const { id, ...rest } = this;
+  const result: any = {
+    id,
+  };
+
+  if (this[TypeId]) {
+    result[ATTR_TYPE] = this[TypeId].toString();
+  }
+
+  if (this[MetaId]) {
+    result[ATTR_META] = serializeMeta(this[MetaId]);
+  }
+
+  if (this[SelfDXNId]) {
+    result[ATTR_SELF_DXN] = this[SelfDXNId].toString();
+  }
+
+  if (this[RelationSourceDXNId]) {
+    const sourceDXN = this[RelationSourceDXNId];
+    invariant(sourceDXN instanceof DXN);
+    result[ATTR_RELATION_SOURCE] = sourceDXN.toString();
+  }
+  if (this[RelationTargetDXNId]) {
+    const targetDXN = this[RelationTargetDXNId];
+    invariant(targetDXN instanceof DXN);
+    result[ATTR_RELATION_TARGET] = targetDXN.toString();
+  }
+
+  Object.assign(result, serializeData(rest));
+  return result;
+};
+
+const serializeData = (data: unknown) => {
+  return deepMapValues(data, (value, recurse) => {
+    if (Ref.isRef(value)) {
+      // TODO(dmaretskyi): Should this be configurable?
+      return value.noInline().encode();
+    }
+
+    return recurse(value);
+  });
+};
+
+const serializeMeta = (meta: ObjectMeta) => {
+  return deepMapValues(meta, (value, recurse) => recurse(value));
+};

package/src/internal/proxy/make-object.ts

@@ -5,20 +5,14 @@
 import type * as Schema from 'effect/Schema';
 
 import { ObjectId } from '@dxos/keys';
-import {
-  type Live,
-  UntypedReactiveHandler,
-  createProxy,
-  defineHiddenProperty,
-  isValidProxyTarget,
-} from '@dxos/live-object';
 
 import { getTypeAnnotation } from '../annotations';
-import { Expando } from '../entities';
-import { attachTypedJsonSerializer } from '../object';
 import { type AnyProperties, KindId, MetaId, type ObjectMeta, ObjectMetaSchema } from '../types';
 
-import { TypedReactiveHandler, prepareTypedTarget } from './typed-handler';
+import { defineHiddenProperty } from './define-hidden-property';
+import { attachTypedJsonSerializer } from './json-serializer';
+import { createProxy, getProxyTarget, isValidProxyTarget } from './proxy-utils';
+import { TypedReactiveHandler, prepareTypedTarget, setMetaOwner } from './typed-handler';
 
 /**
  *
@@ -28,64 +22,53 @@ export type MakeObjectProps<T extends AnyProperties> = Omit<T, 'id' | KindId>;
 
 /**
  * Creates a reactive object from a plain Javascript object.
- * Optionally provides a TS-effect schema.
+ * Requires a TS-effect schema.
  */
 // TODO(burdon): Make internal
 // TODO(dmaretskyi): Deep mutability.
 // TODO(dmaretskyi): Invert generics (generic over schema) to have better error messages.
 // TODO(dmaretskyi): Could mutate original object making it unusable.
 export const makeObject: {
-  <T extends AnyProperties>(obj: T): Live<T>;
   <T extends AnyProperties>(
     schema: Schema.Schema<T, any, never>,
     obj: NoInfer<MakeObjectProps<T>>,
     meta?: ObjectMeta,
-  ): Live<T>;
-} = <T extends AnyProperties>(
-  objOrSchema: Schema.Schema<T, any> | T,
-  obj?: MakeObjectProps<T>,
-  meta?: ObjectMeta,
-): Live<T> => {
-  // TODO(dmaretskyi): Remove Expando special case.
-  if (obj && (objOrSchema as any) !== Expando) {
-    return createReactiveObject<T>({ ...obj } as T, meta, objOrSchema as Schema.Schema<T, any>);
-  } else if (obj && (objOrSchema as any) === Expando) {
-    return createReactiveObject<T>({ ...obj } as T, meta, undefined, { expando: true });
-  } else {
-    return createReactiveObject<T>(objOrSchema as T, meta);
-  }
+  ): T;
+} = <T extends AnyProperties>(schema: Schema.Schema<T, any>, obj: MakeObjectProps<T>, meta?: ObjectMeta): T => {
+  return createReactiveObject<T>({ ...obj } as T, meta, schema);
 };
 
-const createReactiveObject = <T extends AnyProperties>(
-  obj: T,
-  meta?: ObjectMeta,
-  schema?: Schema.Schema<T>,
-  options?: { expando?: boolean },
-): Live<T> => {
+const createReactiveObject = <T extends AnyProperties>(obj: T, meta?: ObjectMeta, schema?: Schema.Schema<T>): T => {
   if (!isValidProxyTarget(obj)) {
     throw new Error('Value cannot be made into a reactive object.');
   }
 
-  if (schema) {
-    const annotation = getTypeAnnotation(schema);
-    const shouldGenerateId = options?.expando || !!annotation;
-    if (shouldGenerateId) {
-      setIdOnTarget(obj);
-    }
-    if (annotation) {
-      defineHiddenProperty(obj, KindId, annotation.kind);
-    }
-    initMeta(obj, meta);
-    prepareTypedTarget(obj, schema);
-    attachTypedJsonSerializer(obj);
-    return createProxy<T>(obj, TypedReactiveHandler.instance);
-  } else {
-    if (options?.expando) {
-      setIdOnTarget(obj);
+  if (!schema) {
+    throw new Error('Schema is required for reactive objects. Use Atom for untyped reactive state.');
+  }
+
+  const annotation = getTypeAnnotation(schema);
+  if (annotation) {
+    setIdOnTarget(obj);
+    defineHiddenProperty(obj, KindId, annotation.kind);
+  }
+  initMeta(obj, meta);
+  prepareTypedTarget(obj, schema);
+  attachTypedJsonSerializer(obj);
+  const proxy = createProxy<T>(obj, TypedReactiveHandler.instance);
+
+  // Set meta's owner to the main object so meta mutations respect the parent's change context.
+  // For non-database objects using TypedReactiveHandler, this links the meta to the main object's
+  // change context. For database objects, meta is handled by EchoReactiveHandler.getMeta().
+  const metaProxy = (obj as any)[MetaId];
+  if (metaProxy) {
+    const metaTarget = getProxyTarget(metaProxy);
+    if (metaTarget) {
+      setMetaOwner(metaTarget, obj);
     }
-    initMeta(obj, meta);
-    return createProxy<T>(obj, UntypedReactiveHandler.instance);
   }
+
+  return proxy;
 };
 
 /**