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

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');

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

@@ -0,0 +1,150 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { invariant } from '@dxos/invariant';
+
+import { type ReactiveHandler } from './proxy-types';
+
+export const symbolIsProxy = Symbol.for('@dxos/schema/Proxy');
+
+/**
+ * Internal api.
+ */
+export const isProxy = (value: unknown) => !!(value as any)?.[symbolIsProxy];
+
+export const isValidProxyTarget = (value: any): value is object => {
+  if (value == null || value[symbolIsProxy]) {
+    return false;
+  }
+  if (Array.isArray(value)) {
+    return true;
+  }
+
+  return typeof value === 'object' && Object.getPrototypeOf(value) === Object.prototype;
+};
+
+/**
+ * @deprecated
+ */
+export const getProxySlot = <T extends object>(proxy: any): ProxyHandlerSlot<T> => {
+  const value = (proxy as any)[symbolIsProxy];
+  invariant(value instanceof ProxyHandlerSlot);
+  return value;
+};
+
+export const getProxyTarget = <T extends object>(proxy: any): T => {
+  return getProxySlot<T>(proxy).target;
+};
+
+export const getProxyHandler = <T extends object>(proxy: any): ReactiveHandler<T> => {
+  return getProxySlot<T>(proxy).handler;
+};
+
+/**
+ * Unsafe method to override id for debugging/testing and migration purposes.
+ * @deprecated
+ */
+export const dangerouslySetProxyId = <T>(obj: T, id: string) => {
+  (getProxySlot(obj).target as any).id = id;
+};
+
+/**
+ * Create a reactive proxy object.
+ * https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy
+ *
+ * @param target Object or array. Passing in array will enable array methods.
+ * @param handler ReactiveHandler instance.
+ */
+// TODO(burdon): Document.
+// TODO(burdon): Tests for low-level functions.
+export const createProxy = <T extends object>(target: T, handler: ReactiveHandler<T>): T => {
+  const existingProxy = handler._proxyMap.get(target);
+  if (existingProxy) {
+    return existingProxy;
+  }
+
+  // TODO(dmaretskyi): In the future this should be mutable to allow replacing the handler on-the-fly while maintaining the proxy identity.
+  const proxy = new Proxy(target, new ProxyHandlerSlot<T>(target, handler));
+  handler.init(target);
+
+  // TODO(dmaretskyi): Check if this will actually work; maybe a global WeakMap is better?
+  handler._proxyMap.set(target, proxy);
+  return proxy;
+};
+
+/**
+ * Passed as the handler to the Proxy constructor.
+ * Maintains a mutable slot for the actual handler.
+ */
+class ProxyHandlerSlot<T extends object> implements ProxyHandler<T> {
+  /**
+   * @param target Original object.
+   * @param _handler Handles intercepted operations.
+   */
+  constructor(
+    readonly target: T,
+    private _handler: ReactiveHandler<T>,
+  ) {}
+
+  get handler() {
+    invariant(this._handler);
+    return this._handler;
+  }
+
+  // TODO(burdon): Requires comment.
+  setHandler(handler: ReactiveHandler<T>): void {
+    this._handler = handler;
+  }
+
+  /**
+   * Get value.
+   */
+  get(target: T, prop: string | symbol, receiver: any): any {
+    if (prop === symbolIsProxy) {
+      return this;
+    }
+
+    if (!this._handler || !this._handler.get) {
+      return Reflect.get(target, prop, receiver);
+    }
+
+    return this._handler.get(target, prop, receiver);
+  }
+
+  static {
+    const TRAPS: (keyof ProxyHandler<any>)[] = [
+      'apply',
+      'construct',
+      'defineProperty',
+      'deleteProperty',
+      'get',
+      'getOwnPropertyDescriptor',
+      'getPrototypeOf',
+      'has',
+      'isExtensible',
+      'ownKeys',
+      'preventExtensions',
+      'set',
+      'setPrototypeOf',
+    ];
+
+    for (const trap of TRAPS) {
+      if (trap === 'get') {
+        continue;
+      }
+
+      Object.defineProperty(this.prototype, trap, {
+        enumerable: false,
+        value: function (this: ProxyHandlerSlot<any>, ...args: any[]) {
+          // log.info('trap', { trap, args });
+          if (!this._handler || !this._handler[trap]) {
+            return (Reflect[trap] as Function)(...args);
+          }
+
+          return (this._handler[trap] as Function).apply(this._handler, args);
+        },
+      });
+    }
+  }
+}

package/src/internal/proxy/reactive-array.ts

@@ -0,0 +1,71 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { isInChangeContext } from './change-context';
+import { createArrayMethodError } from './errors';
+import { batchEvents } from './event-batch';
+import { getEchoRoot } from './ownership';
+import { getProxyTarget, isProxy } from './proxy-utils';
+import { ChangeId, EventId } from './symbols';
+
+/**
+ * Check if array mutation is allowed (inside a change context).
+ * Throws a descriptive error if not.
+ */
+const checkArrayMutationAllowed = (arr: any, method: string): void => {
+  // Get the raw target - if arr is a proxy, get its underlying target.
+  const target = isProxy(arr) ? getProxyTarget(arr) : arr;
+
+  // Find the root ECHO object.
+  const echoRoot = getEchoRoot(target);
+
+  // Check if initialized (has ChangeId marker or EventId).
+  const isInitialized = (echoRoot as any)[ChangeId] === true || EventId in echoRoot;
+  if (!isInitialized) {
+    // Array is still being initialized, allow mutations.
+    return;
+  }
+
+  if (!isInChangeContext(echoRoot)) {
+    throw createArrayMethodError(method);
+  }
+};
+
+/**
+ * Extends the native array to make sure that arrays methods are correctly reactive.
+ * Enforces that mutations only happen within Obj.change() context.
+ */
+export class ReactiveArray<T> extends Array<T> {
+  static override get [Symbol.species]() {
+    return Array;
+  }
+
+  static {
+    /**
+     * These methods will trigger proxy traps like `set` and `defineProperty` and emit event notifications.
+     * We wrap them in a batch to avoid unnecessary event notifications.
+     * Change context is checked before allowing mutations.
+     *
+     * Note: When called on a proxy, `this` will be the proxy, so array mutations
+     * go through the proxy's set trap which handles event emission.
+     */
+    const BATCHED_METHODS = ['push', 'pop', 'shift', 'unshift', 'splice', 'sort', 'reverse'] as const;
+
+    for (const method of BATCHED_METHODS) {
+      Object.defineProperty(this.prototype, method, {
+        enumerable: false,
+        value: function (this: ReactiveArray<any>, ...args: any[]) {
+          // Check change context before allowing mutation.
+          checkArrayMutationAllowed(this, method);
+
+          let result!: any;
+          batchEvents(() => {
+            result = Array.prototype[method].apply(this, args);
+          });
+          return result;
+        },
+      });
+    }
+  }
+}

package/src/internal/proxy/reactive.ts

@@ -0,0 +1,69 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type RefTypeId } from '../ref/ref';
+
+import { getProxyTarget } from './proxy-utils';
+import { ChangeId, EventId } from './symbols';
+
+/**
+ * Subscribe to changes on a reactive object.
+ * @param obj - The reactive object to subscribe to.
+ * @param callback - Called when the object changes.
+ * @returns Unsubscribe function.
+ */
+// TODO(wittjosiah): Consider throwing if obj doesn't have EventId instead of returning no-op.
+export const subscribe = (obj: unknown, callback: () => void): (() => void) => {
+  const target = getProxyTarget(obj as any);
+  if (target && EventId in target) {
+    return (target as any)[EventId].on(callback);
+  }
+  return () => {};
+};
+
+/**
+ * Deeply removes readonly modifiers from all properties of T.
+ * Inside Obj.change, all properties are fully mutable regardless of schema definition.
+ * Ref types are preserved as-is since they are value-like objects that are replaced, not mutated.
+ * Primitive types (including branded primitives) are preserved as-is.
+ */
+export type Mutable<T> = T extends string | number | boolean | bigint | symbol | null | undefined
+  ? T // Primitives (including branded primitives like JsonPath) stay as-is.
+  : T extends { [RefTypeId]: any }
+    ? T // Keep Ref types as-is (they're value-like, not mutated in place).
+    : T extends object
+      ? T extends readonly (infer U)[]
+        ? Mutable<U>[]
+        : { -readonly [K in keyof T]: Mutable<T[K]> }
+      : T;
+
+/**
+ * Callback type for the change function.
+ */
+export type ChangeCallback<T> = (mutableObj: Mutable<T>) => void;
+
+/**
+ * Perform mutations on a reactive object within a change context.
+ *
+ * If the object has a change handler (via ChangeId), it will be called with the callback.
+ * This allows handlers to implement features like:
+ * - Readonly enforcement (mutations only allowed within change context)
+ * - Batched notifications (single notification for all mutations in the callback)
+ * - Transaction semantics
+ *
+ * If the object doesn't have a change handler, the callback is called directly.
+ *
+ * @param obj - The reactive object to mutate.
+ * @param callback - Callback that receives a mutable view of the object.
+ */
+export const change = <T>(obj: T, callback: ChangeCallback<T>): void => {
+  // Check proxy first (allows handler to intercept), then fall back to target.
+  // This order is important for EchoReactiveHandler which handles ChangeId in the proxy trap.
+  const changeFn = (obj as any)[ChangeId];
+  if (changeFn) {
+    changeFn(callback);
+  } else {
+    callback(obj as Mutable<T>);
+  }
+};