@dxos/echo 0.8.4-main.ead640a → 0.8.4-main.effb148878

package/src/internal/common/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/common/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.update() 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/common/proxy/reactive.test.ts

@@ -0,0 +1,54 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, expect, test } from 'vitest';
+
+import * as Obj from '../../../Obj';
+import { TestSchema } from '../../../testing';
+
+describe('Obj.subscribe', () => {
+  test('subscribes and fires for reactive proxies', () => {
+    const obj = Obj.make(TestSchema.Person, { name: 'Test' });
+    let calls = 0;
+    const unsubscribe = Obj.subscribe(obj, () => {
+      calls++;
+    });
+
+    Obj.update(obj, (obj) => {
+      obj.name = 'Updated';
+    });
+    expect(calls).toBeGreaterThan(0);
+
+    unsubscribe();
+    const seen = calls;
+    Obj.update(obj, (obj) => {
+      obj.name = 'After unsubscribe';
+    });
+    expect(calls).toBe(seen);
+  });
+
+  // Regression: queue-stored typed objects (e.g. AiContext.Binding) and other Obj-shaped values
+  // satisfy `Obj.isObject` (KindId is set) but are not wrapped in a reactive Proxy. Earlier
+  // versions invariant'd inside `getProxyTarget` when an atom body did `Obj.subscribe(obj)` on
+  // such an input. The contract is "no-op for non-reactive inputs"; verify the function
+  // returns gracefully instead of throwing.
+  test('returns a no-op unsubscribe for non-proxy inputs', () => {
+    const queueShaped: any = {
+      id: '01KQ5NKXJWSKMRPVTVG2GHV8V3',
+      blueprints: { added: [], removed: [] },
+      objects: { added: [], removed: [] },
+    };
+    const unsubscribe = Obj.subscribe(queueShaped, () => {});
+    expect(typeof unsubscribe).toBe('function');
+    expect(() => unsubscribe()).not.toThrow();
+  });
+
+  test('returns a no-op unsubscribe for primitives, null, and undefined', () => {
+    for (const value of [null, undefined, 42, 'string', true]) {
+      const unsubscribe = Obj.subscribe(value as any, () => {});
+      expect(typeof unsubscribe).toBe('function');
+      expect(() => unsubscribe()).not.toThrow();
+    }
+  });
+});

package/src/internal/common/proxy/reactive.ts

@@ -0,0 +1,77 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type RefTypeId } from '../../Ref/ref';
+import { getProxyTarget, isProxy } 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) => {
+  // Guard against non-reactive inputs (queue-stored typed objects, snapshots, plain shapes
+  // with branded symbols) before `getProxyTarget`'s `ProxyHandlerSlot` invariant kicks in.
+  // `Obj.isObject` (KindId-based) is satisfied by these inputs, so callers like
+  // `Atom.family((obj) => Atom.make((get) => Obj.subscribe(obj, ...)))` legitimately reach
+  // here with a non-proxy. Falling back to a no-op preserves the documented contract that
+  // values without subscription support get a no-op unsubscribe.
+  if (!isProxy(obj)) {
+    return () => {};
+  }
+  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.update, 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>);
+  }
+};

package/src/internal/{object → common/proxy}/schema-validator.ts

@@ -6,8 +6,9 @@ import * as Schema from 'effect/Schema';
 import * as SchemaAST from 'effect/SchemaAST';
 
 import { invariant } from '@dxos/invariant';
+import { log } from '@dxos/log';
 
-import { SchemaId } from './model';
+import { SchemaId } from '../types';
 
 // TODO(burdon): Reconcile with @dxos/effect visit().
 
@@ -46,7 +47,7 @@ export class SchemaValidator {
       }
 
       return type.ast.annotations[annotation] != null;
-    } catch (err) {
+    } catch {
       return false;
     }
   }
@@ -67,7 +68,8 @@ export class SchemaValidator {
           getProperty([...propertyPath.slice(0, i), propertyName]),
         );
         if (propertyType == null) {
-          throw new TypeError(`unknown property: ${String(propertyName)} on object. Path: ${propertyPath}`);
+          log.warn('unknown property', { path: propertyPath, property: propertyName });
+          continue;
         }
 
         schema = Schema.make(propertyType).annotations(propertyType.annotations);
@@ -238,4 +240,5 @@ export const checkIdNotPresentOnSchema = (schema: Schema.Schema<any, any, any>)
   }
 };
 
+// TODO(burdon): Reconcile with JsonPath.
 type KeyPath = readonly (string | number)[];

package/src/internal/common/proxy/schema.test.ts

@@ -0,0 +1,107 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+import * as SchemaAST from 'effect/SchemaAST';
+import { describe, expect, test } from 'vitest';
+
+import { invariant } from '@dxos/invariant';
+import { DXN } from '@dxos/keys';
+
+import { createEchoSchema } from '../../../testing';
+import * as Type from '../../../Type';
+import { PropertyMeta, getPropertyMetaAnnotation, getTypeAnnotation } from '../../Annotation';
+import { EchoObjectSchema } from '../../Entity';
+
+// Test-local: introspect a Type.Type entity's properties via its rebuilt Effect
+// Schema, filter the implicit `id` field, and unwrap `T | undefined` optionality.
+const getProperties = (type: Type.Type): SchemaAST.PropertySignature[] => {
+  const ast = Type.getSchema(type).ast;
+  invariant(SchemaAST.isTypeLiteral(ast));
+  return [...ast.propertySignatures]
+    .filter((p) => p.name !== 'id')
+    .map((p) => {
+      if (!SchemaAST.isUnion(p.type)) {
+        return p;
+      }
+      const nonUndefined = p.type.types.find((t) => !SchemaAST.isUndefinedKeyword(t))!;
+      return { ...p, type: nonUndefined } as SchemaAST.PropertySignature;
+    });
+};
+
+const EmptySchemaType = Schema.Struct({}).pipe(EchoObjectSchema(DXN.make('com.example.type.empty', '0.1.0')));
+
+type EmptySchemaType = Type.InstanceType<typeof EmptySchemaType>;
+
+describe('dynamic schema', () => {
+  test('getProperties filters out id and unwraps optionality', async () => {
+    const TestSchema = Schema.Struct({
+      field1: Schema.String,
+      field2: Schema.Boolean,
+    }).pipe(EchoObjectSchema(DXN.make('com.example.type.test', '0.1.0')));
+
+    const registered = createEchoSchema(Type.getSchema(TestSchema));
+    expect(getProperties(registered).map((p) => [p.name, p.type])).to.deep.eq([
+      ['field1', SchemaAST.stringKeyword],
+      ['field2', SchemaAST.booleanKeyword],
+    ]);
+  });
+
+  test('addColumns', async () => {
+    const TestSchema = Schema.Struct({
+      field1: Schema.String,
+    }).pipe(EchoObjectSchema(DXN.make('com.example.type.test', '0.1.0')));
+
+    const registered = createEchoSchema(Type.getSchema(TestSchema));
+    Type.addFields(registered, { field2: Schema.Boolean });
+    expect(getProperties(registered).map((p) => [p.name, p.type])).to.deep.eq([
+      ['field1', SchemaAST.stringKeyword],
+      ['field2', SchemaAST.booleanKeyword],
+    ]);
+  });
+
+  test('updateColumns preserves order of existing and appends new fields', async () => {
+    const registered = createEchoSchema(Type.getSchema(EmptySchemaType));
+    Type.addFields(registered, { field1: Schema.String });
+    Type.addFields(registered, { field2: Schema.Boolean });
+    Type.addFields(registered, { field3: Schema.Number });
+    Type.updateFields(registered, { field4: Schema.Boolean, field2: Schema.String });
+    expect(getProperties(registered).map((p) => [p.name, p.type])).to.deep.eq([
+      ['field1', SchemaAST.stringKeyword],
+      ['field2', SchemaAST.stringKeyword],
+      ['field3', SchemaAST.numberKeyword],
+      ['field4', SchemaAST.booleanKeyword],
+    ]);
+  });
+
+  test('removeColumns', async () => {
+    const registered = createEchoSchema(Type.getSchema(EmptySchemaType));
+    Type.addFields(registered, { field1: Schema.String });
+    Type.addFields(registered, { field2: Schema.Boolean });
+    Type.addFields(registered, { field3: Schema.Number });
+    Type.removeFields(registered, ['field2']);
+    expect(getProperties(registered).map((p) => [p.name, p.type])).to.deep.eq([
+      ['field1', SchemaAST.stringKeyword],
+      ['field3', SchemaAST.numberKeyword],
+    ]);
+  });
+
+  test('schema manipulations preserve annotations', async () => {
+    const metaNamespace = 'dxos.test';
+    const metaInfo = { maxLength: 10 };
+    const registered = createEchoSchema(Type.getSchema(EmptySchemaType));
+    Type.addFields(registered, {
+      field1: Schema.String.pipe(PropertyMeta(metaNamespace, metaInfo)),
+      field2: Schema.String,
+    });
+    Type.addFields(registered, { field3: Schema.String });
+    Type.updateFields(registered, { field3: Schema.Boolean });
+    Type.removeFields(registered, ['field2']);
+    expect(getTypeAnnotation(Type.getSchema(registered))).to.deep.contain({
+      typename: 'com.example.type.empty',
+      version: '0.1.0',
+    });
+    expect(getPropertyMetaAnnotation(getProperties(registered)[0], metaNamespace)).to.deep.eq(metaInfo);
+  });
+});

package/src/internal/common/proxy/symbols.ts

@@ -0,0 +1,7 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+// TODO(dmaretskyi): Rename all symbols that are props to end with *Key.
+export const EventId = Symbol.for('@dxos/live-object/EventId');
+export const ChangeId = Symbol.for('@dxos/live-object/ChangeId');