@dxos/echo 0.8.4-main.67995b8 → 0.8.4-main.69d29f4

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

@@ -0,0 +1,123 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { inspect } from 'node:util';
+
+import { describe, expect, test } from 'vitest';
+
+import { isNode } from '@dxos/util';
+
+import { TestSchema, updateCounter } from '../../testing';
+import { createObject } from '../object';
+import { ATTR_META } from '../types';
+
+import { makeObject } from './make-object';
+import { objectData } from './proxy-types';
+import { change } from './reactive';
+
+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: TestSchema.ExampleSchema = {
+  string: 'foo',
+  number: 42,
+  boolean: true,
+  null: null,
+  stringArray: ['1', '2', '3'],
+  nested: {
+    field: 'bar',
+  },
+};
+
+// 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 with schema', () => {
+    test.skipIf(!isNode())('inspect', () => {
+      const obj = createObject({ string: 'bar' });
+      const str = inspect(obj, { colors: false });
+      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': 'TypedReactiveObject',
+        ...TEST_OBJECT,
+      });
+    });
+
+    // TODO(wittjosiah): Should we prevent this?
+    test('can assign class instances', () => {
+      const obj = createObject();
+
+      const classInstance = new TestSchema.TestClass();
+      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');
+    });
+
+    describe('class instance equality', () => {
+      test('toJSON', () => {
+        const original = { classInstance: new TestSchema.TestClass() };
+        const reactive = createObject(original);
+        expect(JSON.stringify(reactive)).to.eq(
+          JSON.stringify({
+            [ATTR_META]: {
+              keys: [],
+            },
+            ...original,
+          }),
+        );
+      });
+
+      test('chai deep equal works', () => {
+        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 TestSchema.TestClass() };
+        const reactive = createObject(original);
+        expect(reactive).toEqual(original);
+        expect(reactive).not.toEqual({ ...original, number: 11 });
+      });
+    });
+
+    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);
+      });
+    });
+  });
+}
+
+// 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,96 @@
+//
+// 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 } 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 => {
+  return createReactiveObject<T>({ ...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.');
+  }
+
+  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);
+    }
+  }
+
+  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));
+};

package/src/internal/proxy/ownership.ts

@@ -0,0 +1,253 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { invariant } from '@dxos/invariant';
+
+import { KindId } from '../types';
+
+import { queueOwnerNotification } from './change-context';
+import { defineHiddenProperty } from './define-hidden-property';
+import { getProxyTarget, isProxy, isValidProxyTarget } from './proxy-utils';
+import { EventId } from './symbols';
+
+/**
+ * Symbol to store the owning ECHO object reference on nested JS objects (records).
+ * Every nested record is attributed to exactly one ECHO object.
+ * This achieves:
+ * - No cycles in the object graph (cyclical Refs are still allowed).
+ * - No multiple inbound pointers to one record.
+ * - Centralized reactivity for entire ECHO object.
+ */
+const EchoOwner = Symbol.for('@dxos/echo/Owner');
+
+/**
+ * Get the raw target from a value, unwrapping proxy if needed.
+ */
+export const getRawTarget = (value: any): any => {
+  return isProxy(value) ? getProxyTarget(value) : value;
+};
+
+/**
+ * Get the ECHO object that owns this nested record.
+ *
+ * The owner is always the raw target object (not a proxy) of the root ECHO object.
+ * For example, if you have `echoObject.nested.deep`, both `nested` and `deep`
+ * will have their owner set to the raw target of `echoObject`.
+ *
+ * @param value - The nested record to check (can be a proxy or raw target).
+ * @returns The raw target of the owning root ECHO object, or undefined if not owned.
+ */
+export const getOwner = (value: object | null | undefined): object | undefined => {
+  return (value as any)?.[EchoOwner];
+};
+
+/**
+ * Set the owner of a meta object to its parent.
+ * This allows meta mutations to respect the parent's change context.
+ * @internal
+ */
+export const setMetaOwner = (metaTarget: object, parent: object): void => {
+  defineHiddenProperty(metaTarget, EchoOwner, parent);
+};
+
+/**
+ * Set the ECHO object owner on a value and all its nested records.
+ * All nested JS objects point directly to the root ECHO object.
+ *
+ * @param value - The value to set ownership on (can be a proxy or raw target).
+ * @param owner - The raw target of the root ECHO object that will own this value.
+ * @param options.visited - Set of already-visited objects to avoid infinite loops.
+ * @param options.depth - Current recursion depth (unused, kept for debugging).
+ * @param options.allowedPreviousOwner - When reassigning a root ECHO object, its nested structures
+ *   are allowed to have this as their previous owner without triggering the invariant.
+ */
+export const setOwnerRecursive = (
+  value: any,
+  owner: object,
+  options: {
+    visited?: Set<object>;
+    depth?: number;
+    allowedPreviousOwner?: object;
+  } = {},
+): void => {
+  const { visited = new Set<object>(), depth = 0, allowedPreviousOwner } = options;
+  if (value == null || typeof value !== 'object') {
+    return;
+  }
+
+  const actualValue = getRawTarget(value);
+  if (visited.has(actualValue)) {
+    return;
+  }
+  visited.add(actualValue);
+
+  // Check that we're not stealing a nested record owned by a different ECHO object.
+  // Root ECHO objects (those with EventId) can be reassigned - they maintain their own
+  // identity and choosing to embed them in another object is a valid operation.
+  // When reassigning a root, its nested records (owned by that root) are also allowed.
+  const existingOwner = getOwner(actualValue);
+  const isRootEchoObject = EventId in actualValue;
+
+  // Track if this is a root being assigned - its nested structures are allowed to transfer.
+  let newAllowedPreviousOwner = allowedPreviousOwner;
+  if (isRootEchoObject && depth === 0) {
+    // This is the top-level root being assigned; allow its nested structures to transfer.
+    newAllowedPreviousOwner = actualValue;
+  }
+
+  if (!isRootEchoObject) {
+    const ownershipAllowed =
+      existingOwner == null || existingOwner === owner || existingOwner === newAllowedPreviousOwner;
+    invariant(
+      ownershipAllowed,
+      'Cannot reassign ownership of a nested record to a different ECHO object. Use deep copy first.',
+    );
+  }
+
+  // Set owner directly to the root ECHO object.
+  defineHiddenProperty(actualValue, EchoOwner, owner);
+
+  // Recursively set owner on nested objects and array elements.
+  const recursiveOptions = {
+    visited,
+    depth: depth + 1,
+    allowedPreviousOwner: newAllowedPreviousOwner,
+  };
+  if (Array.isArray(actualValue)) {
+    for (const item of actualValue) {
+      if (isValidProxyTarget(item) || isProxy(item)) {
+        setOwnerRecursive(item, owner, recursiveOptions);
+      }
+    }
+  } else {
+    for (const key in actualValue) {
+      if (Object.prototype.hasOwnProperty.call(actualValue, key)) {
+        const nested = actualValue[key];
+        if (isValidProxyTarget(nested) || isProxy(nested)) {
+          setOwnerRecursive(nested, owner, recursiveOptions);
+        }
+      }
+    }
+  }
+};
+
+/**
+ * Traverse an object graph, calling the visitor on each object.
+ * Handles proxy unwrapping and cycle detection.
+ *
+ * @param value - The value to traverse (can be a proxy or raw target).
+ * @param visitor - Called for each object. Return true to stop traversal (early exit).
+ * @returns true if the visitor returns true for any object.
+ */
+export const traverseObjectGraph = (
+  value: any,
+  visitor: (actualValue: any) => boolean,
+  visited = new Set<object>(),
+): boolean => {
+  if (value == null || typeof value !== 'object') {
+    return false;
+  }
+
+  const actualValue = getRawTarget(value);
+
+  if (visited.has(actualValue)) {
+    return false;
+  }
+  visited.add(actualValue);
+
+  if (visitor(actualValue)) {
+    return true;
+  }
+
+  if (Array.isArray(actualValue)) {
+    for (const item of actualValue) {
+      if (traverseObjectGraph(item, visitor, visited)) {
+        return true;
+      }
+    }
+  } else {
+    for (const key in actualValue) {
+      if (Object.prototype.hasOwnProperty.call(actualValue, key)) {
+        if (traverseObjectGraph(actualValue[key], visitor, visited)) {
+          return true;
+        }
+      }
+    }
+  }
+
+  return false;
+};
+
+/**
+ * Check if a value would create a cycle when assigned to a target ECHO object.
+ * Returns true if the value (or any nested object) IS the target root.
+ */
+export const wouldCreateCycle = (targetRoot: object, value: any): boolean =>
+  traverseObjectGraph(value, (v) => v === targetRoot);
+
+/**
+ * Check if a value or any of its nested objects has an owner different from the target.
+ * Used to determine if deep copy is needed during init.
+ */
+export const hasForeignOwner = (value: any, target: object): boolean =>
+  traverseObjectGraph(value, (v) => {
+    const owner = getOwner(v);
+    if (owner != null && owner !== target) {
+      return true;
+    }
+    // Root ECHO objects (with EventId) have their nested structures owned by them.
+    if (EventId in v && v !== target) {
+      return true;
+    }
+    return false;
+  });
+
+/**
+ * Maximum depth for owner chain traversal.
+ * This is a defensive measure against malformed circular ownership.
+ * Primary cycle detection is handled by wouldCreateCycle() before assignment.
+ */
+const MAX_OWNER_DEPTH = 100;
+
+/**
+ * Get the root ECHO object for a target.
+ * Follows the owner chain to find the ultimate root.
+ * An object may have EventId (from being created standalone) but if it now
+ * has an owner, it's nested and we should use its owner's root instead.
+ * @internal
+ */
+export const getEchoRoot = (target: object, depth = 0): object => {
+  invariant(depth < MAX_OWNER_DEPTH, 'Owner chain too deep - possible circular ownership');
+
+  // Root ECHO objects (those created with Obj.make or Relation.make) have KindId set.
+  // They maintain their own change context identity even when nested inside another object.
+  // Nested helper objects like ObjectMeta don't have KindId and should follow their owner.
+  if (KindId in target) {
+    return target;
+  }
+
+  // For non-root objects (nested records, ObjectMeta, etc.), follow the owner chain.
+  const owner = getOwner(target);
+  if (owner) {
+    return getEchoRoot(owner, depth + 1);
+  }
+
+  // No owner means this is an unowned object (e.g., during initialization).
+  return target;
+};
+
+/**
+ * Notify all owners in the ownership chain.
+ * When a nested object changes, its parent should also be notified.
+ * This handles the case where a root ECHO object is nested inside another object.
+ */
+export const notifyOwnerChain = (target: object): void => {
+  const owner = getOwner(target);
+  if (owner) {
+    // Queue notification for the owner's root (which has EventId).
+    queueOwnerNotification(getEchoRoot(owner));
+    // Continue up the chain (owner might also be nested).
+    notifyOwnerChain(owner);
+  }
+};

package/src/internal/proxy/proxy-types.ts

@@ -0,0 +1,23 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+/**
+ * Reactive object proxy.
+ */
+export interface ReactiveHandler<T extends object> extends ProxyHandler<T> {
+  /**
+   * Target to Proxy mapping.
+   */
+  readonly _proxyMap: WeakMap<object, any>;
+
+  /**
+   * Called when a proxy is created for this target.
+   */
+  init(target: T): void;
+}
+
+/**
+ * For debug-dumping the data of the object.
+ */
+export const objectData = Symbol.for('@dxos/live-object/objectData');