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

package/src/internal/object/schema-validator.test.ts

@@ -0,0 +1,182 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+import { describe, expect, test } from 'vitest';
+
+import { getDeep } from '@dxos/util';
+
+import { SchemaValidator } from './schema-validator';
+
+describe('schema-validator', () => {
+  describe('validateSchema', () => {
+    test('throws on ambiguous discriminated type union', () => {
+      const TestSchema = Schema.Struct({
+        union: Schema.Union(Schema.Struct({ a: Schema.Number }), Schema.Struct({ b: Schema.String })),
+      });
+
+      expect(() => SchemaValidator.validateSchema(TestSchema)).to.throw();
+    });
+  });
+
+  describe('hasPropertyAnnotation', () => {
+    test('has annotation', () => {
+      const annotationId = Symbol('foo');
+      const annotationValue = 'bar';
+      const TestSchema: Schema.Schema.AnyNoContext = Schema.Struct({
+        name: Schema.String.annotations({ [annotationId]: annotationValue }),
+        parent: Schema.optional(Schema.suspend(() => TestSchema.annotations({ [annotationId]: annotationValue }))),
+        friends: Schema.suspend(() => Schema.Array(TestSchema.annotations({ [annotationId]: annotationValue }))),
+      });
+      expect(SchemaValidator.hasTypeAnnotation(TestSchema, 'name', annotationId)).to.be.true;
+      expect(SchemaValidator.hasTypeAnnotation(TestSchema, 'parent', annotationId)).to.be.true;
+      expect(SchemaValidator.hasTypeAnnotation(TestSchema, 'friends', annotationId)).to.be.true;
+    });
+
+    test('no annotation', () => {
+      const annotationId = Symbol('foo');
+      const Person: Schema.Schema.AnyNoContext = Schema.Struct({
+        name: Schema.String,
+        parent: Schema.optional(Schema.suspend(() => Person)),
+        friends: Schema.suspend(() => Schema.Array(Person)),
+      });
+      expect(SchemaValidator.hasTypeAnnotation(Person, 'name', annotationId)).to.be.false;
+      expect(SchemaValidator.hasTypeAnnotation(Person, 'parent', annotationId)).to.be.false;
+      expect(SchemaValidator.hasTypeAnnotation(Person, 'friends', annotationId)).to.be.false;
+    });
+  });
+
+  describe('getPropertySchema', () => {
+    const validateValueToAssign = (args: {
+      schema: Schema.Schema.AnyNoContext;
+      target: any;
+      path: string[];
+      valueToAssign: any;
+      expectToThrow?: boolean;
+    }) => {
+      const expectation = expect(() => {
+        const nestedSchema = SchemaValidator.getPropertySchema(args.schema, args.path, (path) => {
+          return getDeep(args.target, path);
+        });
+        Schema.validateSync(nestedSchema)(args.valueToAssign);
+      });
+      if (args.expectToThrow) {
+        expectation.to.throw();
+      } else {
+        expectation.not.to.throw();
+      }
+    };
+
+    test('basic', () => {
+      for (const value of [42, '42']) {
+        validateValueToAssign({
+          schema: Schema.Struct({ object: Schema.Struct({ field: Schema.Number }) }),
+          target: {},
+          path: ['object', 'field'],
+          valueToAssign: value,
+          expectToThrow: typeof value !== 'number',
+        });
+      }
+    });
+
+    test('preserves annotations', () => {
+      const annotationId = Symbol('foo');
+      const annotationValue = 'bar';
+      const Person: Schema.Schema.AnyNoContext = Schema.Struct({
+        parent: Schema.optional(Schema.suspend(() => Person.annotations({ [annotationId]: annotationValue }))),
+        friends: Schema.suspend(() => Schema.Array(Person.annotations({ [annotationId]: annotationValue }))),
+      });
+      expect(SchemaValidator.getPropertySchema(Person, ['parent']).ast.annotations[annotationId]).to.eq(
+        annotationValue,
+      );
+      expect(SchemaValidator.getPropertySchema(Person, ['friends', '0']).ast.annotations[annotationId]).to.eq(
+        annotationValue,
+      );
+    });
+
+    test('discriminated union', () => {
+      const square = Schema.Struct({ type: Schema.Literal('square'), side: Schema.Number });
+      const circle = Schema.Struct({ type: Schema.Literal('circle'), radius: Schema.Number });
+      const shape = Schema.Union(square, circle);
+      validateValueToAssign({
+        schema: shape,
+        target: { type: 'square' },
+        path: ['side'],
+        valueToAssign: 1,
+      });
+      validateValueToAssign({
+        schema: shape,
+        target: { type: 'circle' },
+        path: ['side'],
+        valueToAssign: 1,
+        expectToThrow: true,
+      });
+      validateValueToAssign({
+        schema: shape,
+        target: { type: 'square' },
+        path: ['radius'],
+        valueToAssign: 1,
+        expectToThrow: true,
+      });
+    });
+
+    test('any', () => {
+      validateValueToAssign({
+        schema: Schema.Any,
+        target: { field: { nested: { value: Schema.Number } } },
+        path: ['field', 'nested'],
+        valueToAssign: { any: 'value' },
+      });
+    });
+    test('index signatures', () => {
+      for (const value of [42, '42']) {
+        validateValueToAssign({
+          schema: Schema.Struct({ field: Schema.String }, { key: Schema.String, value: Schema.Number }),
+          target: {},
+          path: ['unknownField'],
+          valueToAssign: value,
+          expectToThrow: typeof value !== 'number',
+        });
+      }
+    });
+
+    test('index signature from optional record', () => {
+      for (const value of [42, '42']) {
+        validateValueToAssign({
+          schema: Schema.Struct({
+            field: Schema.optional(Schema.Record({ key: Schema.String, value: Schema.Number })),
+          }),
+          target: {},
+          path: ['field', 'unknownField'],
+          valueToAssign: value,
+          expectToThrow: typeof value !== 'number',
+        });
+      }
+    });
+
+    test('suspend', () => {
+      const schemaWithSuspend = Schema.Struct({
+        array: Schema.optional(Schema.suspend(() => Schema.Array(Schema.Union(Schema.Null, Schema.Number)))),
+        object: Schema.optional(
+          Schema.suspend(() => Schema.Union(Schema.Null, Schema.Struct({ field: Schema.Number }))),
+        ),
+      });
+      const target: any = { array: [1, 2, null], object: { field: 3 } };
+      for (const value of [42, '42']) {
+        for (const path of [
+          ['array', '0'],
+          ['object', 'field'],
+        ]) {
+          validateValueToAssign({
+            schema: schemaWithSuspend,
+            target,
+            path,
+            valueToAssign: value,
+            expectToThrow: typeof value !== 'number',
+          });
+        }
+      }
+    });
+  });
+});

package/src/internal/object/schema-validator.ts

@@ -0,0 +1,6 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+// Re-export from proxy for backward compatibility.
+export { SchemaValidator, checkIdNotPresentOnSchema } from '../proxy';

package/src/internal/object/set-value.test.ts

@@ -0,0 +1,281 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+import { describe, test } from 'vitest';
+
+import * as Obj from '../../Obj';
+import { TestSchema } from '../../testing';
+import * as Type from '../../Type';
+
+describe('Obj.setValue', () => {
+  test('sets simple nested object property', ({ expect }) => {
+    const person = Obj.make(TestSchema.Person, {
+      name: 'John',
+      username: 'john',
+      email: 'john@example.com',
+    });
+
+    Obj.change(person, (p) => Obj.setValue(p, ['address', 'city'], 'NYC'));
+
+    expect(person.address).toBeDefined();
+    expect(person.address?.city).toBe('NYC');
+  });
+
+  test('sets array element by initializing array', ({ expect }) => {
+    const person = Obj.make(TestSchema.Person, {
+      name: 'John',
+      username: 'john',
+      email: 'john@example.com',
+    });
+
+    Obj.change(person, (p) => Obj.setValue(p, ['fields', 0, 'label'], 'Phone'));
+
+    expect(Array.isArray(person.fields)).toBe(true);
+    expect(person.fields?.[0].label).toBe('Phone');
+    // The 'value' field is required, so it should be initialized with default.
+    expect(person.fields?.[0].value).toBe('');
+  });
+
+  test('sets deeply nested array in object', ({ expect }) => {
+    const person = Obj.make(TestSchema.Person, {
+      name: 'John',
+      username: 'john',
+      email: 'john@example.com',
+    });
+
+    Obj.change(person, (p) => Obj.setValue(p, ['address', 'coordinates', 'lat'], 40.7128));
+
+    expect(person.address).toBeDefined();
+    expect(person.address?.coordinates).toBeDefined();
+    expect(person.address?.coordinates?.lat).toBe(40.7128);
+  });
+
+  test('sets multiple nested array elements', ({ expect }) => {
+    const Item = Schema.Struct({
+      value: Schema.optional(Schema.Number),
+    });
+
+    const Container = Schema.Struct({
+      name: Schema.String,
+      items: Schema.optional(Schema.Array(Item)),
+    }).pipe(
+      Type.object({
+        typename: 'test.com/Container',
+        version: '0.1.0',
+      }),
+    );
+
+    const container = Obj.make(Container, { name: 'box' });
+
+    Obj.change(container, (c) => {
+      Obj.setValue(c, ['items', 0, 'value'], 10);
+      Obj.setValue(c, ['items', 1, 'value'], 20);
+      Obj.setValue(c, ['items', 2, 'value'], 30);
+    });
+
+    expect(container.items).toHaveLength(3);
+    expect(container.items?.[0].value).toBe(10);
+    expect(container.items?.[1].value).toBe(20);
+    expect(container.items?.[2].value).toBe(30);
+  });
+
+  test('handles optional fields', ({ expect }) => {
+    const person = Obj.make(TestSchema.Person, {
+      name: 'John',
+      username: 'john',
+      email: 'john@example.com',
+    });
+
+    Obj.change(person, (p) => Obj.setValue(p, ['age'], 25));
+
+    expect(person.age).toBe(25);
+  });
+
+  test('handles nested optional objects', ({ expect }) => {
+    const person = Obj.make(TestSchema.Person, {
+      name: 'John',
+      username: 'john',
+      email: 'john@example.com',
+    });
+
+    Obj.change(person, (p) => Obj.setValue(p, ['address', 'city'], 'NYC'));
+
+    expect(person.address).toBeDefined();
+    expect(person.address?.city).toBe('NYC');
+  });
+
+  test('returns the set value', ({ expect }) => {
+    const person = Obj.make(TestSchema.Person, {
+      name: 'John',
+      username: 'john',
+      email: 'john@example.com',
+    });
+
+    let result: any;
+    Obj.change(person, (p) => {
+      result = Obj.setValue(p, ['age'], 30);
+    });
+
+    expect(result).toBe(30);
+  });
+
+  test('overwrites existing values', ({ expect }) => {
+    const person = Obj.make(TestSchema.Person, {
+      name: 'John',
+      username: 'john',
+      email: 'john@example.com',
+      age: 25,
+    });
+
+    Obj.change(person, (p) => Obj.setValue(p, ['age'], 30));
+
+    expect(person.age).toBe(30);
+  });
+
+  test('sets nested value in existing object', ({ expect }) => {
+    const person = Obj.make(TestSchema.Person, {
+      name: 'John',
+      username: 'john',
+      email: 'john@example.com',
+      address: { city: 'Boston', state: 'MA', coordinates: {} },
+    });
+
+    Obj.change(person, (p) => Obj.setValue(p, ['address', 'city'], 'NYC'));
+
+    expect(person.address?.city).toBe('NYC');
+    expect(person.address?.state).toBe('MA');
+  });
+
+  test('handles two-dimensional arrays', ({ expect }) => {
+    const Matrix = Schema.Struct({
+      values: Schema.optional(Schema.Array(Schema.Array(Schema.Number))),
+    }).pipe(
+      Type.object({
+        typename: 'test.com/Matrix',
+        version: '0.1.0',
+      }),
+    );
+
+    const matrix = Obj.make(Matrix, {});
+
+    Obj.change(matrix, (m) => {
+      Obj.setValue(m, ['values', 0, 0], 1);
+      Obj.setValue(m, ['values', 0, 1], 2);
+      Obj.setValue(m, ['values', 1, 0], 3);
+      Obj.setValue(m, ['values', 1, 1], 4);
+    });
+
+    expect(matrix.values?.[0][0]).toBe(1);
+    expect(matrix.values?.[0][1]).toBe(2);
+    expect(matrix.values?.[1][0]).toBe(3);
+    expect(matrix.values?.[1][1]).toBe(4);
+  });
+
+  test('throws error for empty path', ({ expect }) => {
+    const person = Obj.make(TestSchema.Person, {
+      name: 'John',
+      username: 'john',
+      email: 'john@example.com',
+    });
+
+    Obj.change(person, (p) => {
+      expect(() => Obj.setValue(p, [], 'value')).toThrow('Path must not be empty');
+    });
+  });
+
+  test('sets value with single-element path', ({ expect }) => {
+    const person = Obj.make(TestSchema.Person, {
+      name: 'John',
+      username: 'john',
+      email: 'john@example.com',
+    });
+
+    Obj.change(person, (p) => Obj.setValue(p, ['age'], 30));
+
+    expect(person.age).toBe(30);
+  });
+
+  test('handles numeric keys as strings', ({ expect }) => {
+    const Item = Schema.Struct({
+      value: Schema.optional(Schema.Number),
+    });
+
+    const Container = Schema.Struct({
+      name: Schema.String,
+      items: Schema.optional(Schema.Array(Item)),
+    }).pipe(
+      Type.object({
+        typename: 'test.com/Container',
+        version: '0.1.0',
+      }),
+    );
+
+    const container = Obj.make(Container, { name: 'box' });
+
+    // Using string '0' for array index.
+    Obj.change(container, (c) => Obj.setValue(c, ['items', '0', 'value'], 42));
+
+    expect(container.items?.[0].value).toBe(42);
+  });
+
+  test('handles array with object with required field', ({ expect }) => {
+    // This test demonstrates the problematic scenario:
+    // An array containing objects that have required fields.
+    const Task = Schema.Struct({
+      id: Schema.String, // Required field.
+      title: Schema.optional(Schema.String),
+      completed: Schema.optional(Schema.Boolean),
+    });
+
+    const TodoList = Schema.Struct({
+      name: Schema.String,
+      tasks: Schema.optional(Schema.Array(Task)),
+    }).pipe(
+      Type.object({
+        typename: 'test.com/TodoList',
+        version: '0.1.0',
+      }),
+    );
+
+    const todoList = Obj.make(TodoList, { name: 'My Tasks' });
+
+    // This should work: setting a nested property on an array element.
+    // The required 'id' field should be initialized with a default value.
+    Obj.change(todoList, (t) => Obj.setValue(t, ['tasks', 0, 'title'], 'Buy groceries'));
+
+    expect(todoList.tasks?.[0].id).toBe(''); // Default value for required String
+    expect(todoList.tasks?.[0].title).toBe('Buy groceries');
+    expect(todoList.tasks?.[0].completed).toBeUndefined(); // Optional field not set
+  });
+
+  test('initializes multiple required primitive fields with defaults', ({ expect }) => {
+    const Item = Schema.Struct({
+      id: Schema.String, // Required - should default to ""
+      count: Schema.Number, // Required - should default to 0
+      active: Schema.Boolean, // Required - should default to false
+      label: Schema.optional(Schema.String), // Optional - should not be initialized
+    });
+
+    const Container = Schema.Struct({
+      name: Schema.String,
+      items: Schema.optional(Schema.Array(Item)),
+    }).pipe(
+      Type.object({
+        typename: 'test.com/Container',
+        version: '0.1.0',
+      }),
+    );
+
+    const container = Obj.make(Container, { name: 'box' });
+
+    Obj.change(container, (c) => Obj.setValue(c, ['items', 0, 'label'], 'First Item'));
+
+    // All required primitive fields should have default values.
+    expect(container.items?.[0].id).toBe('');
+    expect(container.items?.[0].count).toBe(0);
+    expect(container.items?.[0].active).toBe(false);
+    expect(container.items?.[0].label).toBe('First Item');
+  });
+});

package/src/internal/object/set-value.ts

@@ -0,0 +1,165 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Match from 'effect/Match';
+import * as Option from 'effect/Option';
+import * as SchemaAST from 'effect/SchemaAST';
+
+import {
+  type SchemaProperty,
+  getArrayElementType,
+  getBaseType,
+  getProperties,
+  isArrayType,
+  isNestedType,
+} from '@dxos/effect';
+import { invariant } from '@dxos/invariant';
+
+import { type Mutable } from '../proxy';
+import { getSchema } from '../types';
+
+/**
+ * Set a deeply nested property on an object.
+ * Must be called within an Obj.change or Relation.change callback.
+ */
+export const setValue = (obj: Mutable<any>, path: readonly (string | number)[], value: any): void => {
+  invariant(path.length > 0, 'Path must not be empty');
+
+  const schema = getSchema(obj);
+  invariant(schema != null, 'Object must have a schema');
+
+  let parent = obj;
+  let currentAST: SchemaAST.AST | undefined = schema.ast;
+
+  // Navigate to the parent of the target property.
+  for (let i = 0; i < path.length - 1; i++) {
+    const part = path[i];
+    const key = typeof part === 'number' ? part : String(part);
+    if (parent[key] === undefined) {
+      const propertyAST = getPropertyAST(currentAST, String(part));
+      const shouldBeArray = propertyAST ? isArrayType(propertyAST) : false;
+
+      if (shouldBeArray) {
+        // Create array.
+        parent[key] = [];
+      } else {
+        // TODO(wittjosiah): Is there a better way to handle this than creating an object with defaults?
+        //   Perhaps properties on objects should be optional by default?
+        // Create object with defaults for required fields.
+        const objWithDefaults = createObjectWithDefaults(propertyAST);
+        parent[key] = objWithDefaults;
+      }
+    }
+
+    parent = parent[key];
+    currentAST = getPropertyAST(currentAST, String(part));
+  }
+
+  const finalKey = path[path.length - 1];
+  parent[finalKey] = value;
+
+  return value;
+};
+
+/**
+ * Helper to get the AST of a nested property.
+ * @param ast - Current schema AST.
+ * @param propertyName - Name of the property to get.
+ * @returns The AST of the nested property, or undefined if not found.
+ */
+const getPropertyAST = (ast: SchemaAST.AST | undefined, propertyName: string): SchemaAST.AST | undefined => {
+  if (!ast) {
+    return undefined;
+  }
+
+  if (isNestedType(ast)) {
+    const properties = getProperties(ast);
+    const property = properties.find((p) => p.name.toString() === propertyName);
+    if (property) {
+      return getBaseType(property).type;
+    }
+  }
+
+  if (isArrayType(ast)) {
+    const elementType = getArrayElementType(ast);
+    return elementType;
+  }
+
+  return undefined;
+};
+
+/**
+ * Get all required properties from a schema AST.
+ * A property is required if it's not optional.
+ *
+ * @param ast - Schema AST to inspect.
+ * @returns Array of required properties with their types.
+ */
+const getRequiredProperties = (ast: SchemaAST.AST | undefined): SchemaProperty[] => {
+  if (!ast) {
+    return [];
+  }
+
+  // Only objects/structs have properties with optional/required distinction.
+  if (!isNestedType(ast)) {
+    return [];
+  }
+
+  const properties = getProperties(ast);
+
+  // Filter to only required properties (where isOptional === false).
+  return properties.filter((p) => !p.isOptional);
+};
+
+/**
+ * Get the default value for a primitive type.
+ * Returns undefined for non-primitive or unsupported types.
+ *
+ * @param ast - Type AST.
+ * @returns Default value for the type, or undefined.
+ */
+const getDefaultValueForType = (ast: SchemaAST.AST | undefined): any => {
+  if (!ast) {
+    return undefined;
+  }
+
+  const defaultValue = SchemaAST.getDefaultAnnotation(ast);
+  if (Option.isSome(defaultValue)) {
+    return defaultValue.value;
+  }
+
+  return Match.value(ast).pipe(
+    Match.when({ _tag: 'StringKeyword' }, () => ''),
+    Match.when({ _tag: 'NumberKeyword' }, () => 0),
+    Match.when({ _tag: 'BooleanKeyword' }, () => false),
+    Match.orElse(() => undefined),
+  );
+};
+
+/**
+ * Create an object with default values for all required properties.
+ * Handles primitive types (String, Number, Boolean) and recursively initializes required nested objects.
+ *
+ * @param ast - Schema AST describing the object structure.
+ * @returns Object with required fields populated with defaults.
+ */
+const createObjectWithDefaults = (ast: SchemaAST.AST | undefined): any => {
+  if (!ast) {
+    return {};
+  }
+
+  const requiredProps = getRequiredProperties(ast);
+  const obj: any = {};
+
+  for (const prop of requiredProps) {
+    const defaultValue = getDefaultValueForType(prop.type);
+    if (defaultValue !== undefined) {
+      obj[prop.name] = defaultValue;
+    } else if (isNestedType(prop.type)) {
+      obj[prop.name] = createObjectWithDefaults(prop.type);
+    }
+  }
+
+  return obj;
+};

package/src/internal/object/snapshot.ts

@@ -0,0 +1,70 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { deepMapValues } from '@dxos/util';
+
+import { RelationSourceDXNId, RelationSourceId, RelationTargetDXNId, RelationTargetId } from '../entities/relation';
+import { KindId, SnapshotKindId } from '../types/entity';
+import { MetaId } from '../types/meta';
+import { SchemaId, TypeId } from '../types/typename';
+
+/**
+ * Copy a Symbol-keyed property from source to target if it exists.
+ */
+const copySymbolProperty = (source: any, target: any, symbol: symbol): void => {
+  if (symbol in source) {
+    Object.defineProperty(target, symbol, {
+      value: source[symbol],
+      writable: false,
+      enumerable: false,
+      configurable: false,
+    });
+  }
+};
+
+/**
+ * Returns an immutable snapshot of the reactive object.
+ * The snapshot is branded with SnapshotKindId (not KindId).
+ */
+export const getSnapshot = <T extends object>(obj: T): T => {
+  const snapshot = deepMapValues(obj, (value, recurse) => {
+    // Do not recurse on references (but do recurse on arrays).
+    if (
+      typeof value === 'object' &&
+      value !== null &&
+      Object.getPrototypeOf(value) !== Object.prototype &&
+      !Array.isArray(value)
+    ) {
+      return value;
+    }
+
+    return recurse(value);
+  }) as any;
+
+  // Add SnapshotKindId brand based on original KindId.
+  if (obj != null && typeof obj === 'object' && KindId in obj) {
+    snapshot[SnapshotKindId] = (obj as any)[KindId];
+  }
+
+  // Preserve Symbol-keyed properties that are important for type introspection.
+  // These are not copied by deepMapValues since Object.keys() doesn't include symbols.
+  if (obj != null && typeof obj === 'object') {
+    const source = obj as any;
+
+    // Type introspection symbols.
+    copySymbolProperty(source, snapshot, TypeId);
+    copySymbolProperty(source, snapshot, SchemaId);
+
+    // Metadata symbol.
+    copySymbolProperty(source, snapshot, MetaId);
+
+    // Relation endpoint symbols.
+    copySymbolProperty(source, snapshot, RelationSourceDXNId);
+    copySymbolProperty(source, snapshot, RelationTargetDXNId);
+    copySymbolProperty(source, snapshot, RelationSourceId);
+    copySymbolProperty(source, snapshot, RelationTargetId);
+  }
+
+  return Object.freeze(snapshot) as T;
+};