@dxos/echo 0.8.4-main.406dc2a → 0.8.4-main.4a85c3132b

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,102 +6,111 @@ import { inspect } from 'node:util';
 
 import { describe, expect, test } from 'vitest';
 
-import { registerSignalsRuntime } from '@dxos/echo-signals';
-import type { Live } from '@dxos/live-object';
-import { objectData } from '@dxos/live-object';
 import { isNode } from '@dxos/util';
 
-import { ATTR_META } from '..';
-import { Testing, updateCounter } from '../testing';
+import { TestSchema, updateCounter } from '../../testing';
+import { createObject } from '../object';
+import { ATTR_META } from '../types';
 
-import { live } from './reactive-object';
+import { makeObject } from './make-object';
+import { objectData } from './proxy-types';
+import { change } from './reactive';
 
-registerSignalsRuntime();
+describe('proxy', () => {
+  test.skipIf(!isNode())('inspect', ({ expect }) => {
+    const obj = createObject(TestSchema.Message, { timestamp: new Date().toISOString() });
+    const str = inspect(obj, { colors: true });
+    expect(str).to.exist;
+  });
+});
 
-const TEST_OBJECT: Testing.TestSchema = {
+const TEST_OBJECT: TestSchema.ExampleSchema = {
   string: 'foo',
   number: 42,
   boolean: true,
   null: null,
   stringArray: ['1', '2', '3'],
-  object: { field: 'bar' },
+  nested: {
+    field: 'bar',
+  },
 };
 
-for (const schema of [undefined, Testing.TestSchemaWithClass]) {
-  const createObject = (props: Partial<Testing.TestSchemaWithClass> = {}): Live<Testing.TestSchemaWithClass> => {
-    return schema == null ? (live(props) as Testing.TestSchemaWithClass) : live(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 Testing.TestClass();
-      obj.classInstance = classInstance;
+      const classInstance = new TestSchema.TestClass();
+      change(obj, (o) => {
+        o.classInstance = classInstance;
+      });
       expect(obj.classInstance!.field).to.eq('value');
-      expect(obj.classInstance instanceof Testing.TestClass).to.eq(true);
+      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');
     });
 
     describe('class instance equality', () => {
       test('toJSON', () => {
-        const original = { classInstance: new Testing.TestClass() };
+        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', () => {
-        const original = { classInstance: new Testing.TestClass() };
+        const original = { classInstance: new TestSchema.TestClass() };
         const reactive = createObject(original);
         expect(reactive).to.deep.eq(original);
         expect(reactive).to.not.deep.eq({ ...original, number: 11 });
       });
 
       test('jest deep equal works', () => {
-        const original = { classInstance: new Testing.TestClass() };
+        const original = { classInstance: new TestSchema.TestClass() };
         const reactive = createObject(original);
         expect(reactive).toEqual(original);
         expect(reactive).not.toEqual({ ...original, number: 11 });
       });
     });
 
-    describe('signal updates', () => {
-      test('not in nested class instances', () => {
-        const obj = createObject({ classInstance: new Testing.TestClass() });
-        using updates = updateCounter(() => {
-          obj.classInstance!.field;
-        });
+    describe('subscription updates', () => {
+      test('not triggered by nested class instance changes', () => {
+        const obj = createObject({ classInstance: new TestSchema.TestClass() });
+        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);
       });
@@ -109,55 +118,6 @@ for (const schema of [undefined, Testing.TestSchemaWithClass]) {
   });
 }
 
-describe('getters', () => {
-  test('add getter to object', () => {
-    let value = 'foo';
-    const obj = live({
-      get getter() {
-        return value;
-      },
-    });
-    expect(obj.getter).to.eq('foo');
-
-    value = 'bar';
-    expect(obj.getter).to.eq('bar');
-  });
-
-  test('signal updates', () => {
-    const innerObj = live({
-      string: 'bar',
-    });
-
-    const obj = live({
-      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 = live({
-      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

@@ -0,0 +1,17 @@
+//
+// 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

@@ -0,0 +1,106 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import type * as Schema from 'effect/Schema';
+
+import { ObjectId } from '@dxos/keys';
+
+import { getTypeAnnotation } from '../annotations';
+import { type AnyProperties, KindId, MetaId, type ObjectMeta, ObjectMetaSchema, ParentId } from '../types';
+
+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';
+
+/**
+ *
+ */
+// TODO(burdon): Make internal
+export type MakeObjectProps<T extends AnyProperties> = Omit<T, 'id' | KindId>;
+
+/**
+ * Creates a reactive object from a plain Javascript object.
+ * 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>(
+    schema: Schema.Schema<T, any, never>,
+    obj: NoInfer<MakeObjectProps<T>>,
+    meta?: ObjectMeta,
+  ): T;
+} = <T extends AnyProperties>(schema: Schema.Schema<T, any>, obj: MakeObjectProps<T>, meta?: ObjectMeta): T => {
+  // Use Object.assign to copy symbol properties (like ParentId) that spread operator doesn't copy.
+  return createReactiveObject<T>(Object.assign({}, obj) as T, meta, schema);
+};
+
+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) {
+    throw new Error('Schema is required for reactive objects. Use Atom for untyped reactive state.');
+  }
+
+  // Extract parent from props (can be set via [Obj.Parent]).
+  const parent = (obj as any)[ParentId];
+  if (parent !== undefined) {
+    delete (obj as any)[ParentId];
+  }
+
+  const annotation = getTypeAnnotation(schema);
+  if (annotation) {
+    setIdOnTarget(obj);
+    defineHiddenProperty(obj, KindId, annotation.kind);
+  }
+  initMeta(obj, meta);
+  if (parent !== undefined) {
+    defineHiddenProperty(obj, ParentId, parent);
+  }
+  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);
+    }
+  }
+
+  return proxy;
+};
+
+/**
+ * Set ID on ECHO object targets during creation.
+ * Used for objects with schema and the ones explicitly marked as Expando.
+ */
+const setIdOnTarget = (target: any) => {
+  // invariant(!('id' in target), 'Object already has an `id` field, which is reserved.');
+  if ('id' in target && target.id !== undefined && target.id !== null) {
+    if (!ObjectId.isValid(target.id)) {
+      throw new Error('Invalid object id format.');
+    }
+  } else {
+    target.id = ObjectId.random();
+  }
+};
+
+/**
+ * Set metadata on object.
+ */
+// TODO(dmaretskyi): Move to echo-schema.
+const initMeta = <T>(obj: T, meta: ObjectMeta = { keys: [] }) => {
+  prepareTypedTarget(meta, ObjectMetaSchema);
+  defineHiddenProperty(obj, MetaId, createProxy(meta, TypedReactiveHandler.instance as any));
+};