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

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

@@ -0,0 +1,244 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+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 '../types';
+
+// TODO(burdon): Reconcile with @dxos/effect visit().
+
+export class SchemaValidator {
+  /**
+   * Recursively check that schema specifies constructions we can handle.
+   * Validates there are no ambiguous discriminated union types.
+   */
+  public static validateSchema(schema: Schema.Schema.AnyNoContext): void {
+    const visitAll = (nodes: SchemaAST.AST[]) => nodes.forEach((node) => this.validateSchema(Schema.make(node)));
+    if (SchemaAST.isUnion(schema.ast)) {
+      const typeAstList = schema.ast.types.filter((type) => SchemaAST.isTypeLiteral(type)) as SchemaAST.TypeLiteral[];
+      // Check we can handle a discriminated union.
+      if (typeAstList.length > 1) {
+        getTypeDiscriminators(typeAstList);
+      }
+      visitAll(typeAstList);
+    } else if (SchemaAST.isTupleType(schema.ast)) {
+      const positionalTypes = schema.ast.elements.map((t) => t.type);
+      const allTypes = positionalTypes.concat(schema.ast.rest.map((t) => t.type));
+      visitAll(allTypes);
+    } else if (SchemaAST.isTypeLiteral(schema.ast)) {
+      visitAll(SchemaAST.getPropertySignatures(schema.ast).map((p) => p.type));
+    }
+  }
+
+  public static hasTypeAnnotation(
+    rootObjectSchema: Schema.Schema.AnyNoContext,
+    property: string,
+    annotation: symbol,
+  ): boolean {
+    try {
+      let type = this.getPropertySchema(rootObjectSchema, [property]);
+      if (SchemaAST.isTupleType(type.ast)) {
+        type = this.getPropertySchema(rootObjectSchema, [property, '0']);
+      }
+
+      return type.ast.annotations[annotation] != null;
+    } catch {
+      return false;
+    }
+  }
+
+  public static getPropertySchema(
+    rootObjectSchema: Schema.Schema.AnyNoContext,
+    propertyPath: KeyPath,
+    getProperty: (path: KeyPath) => any = () => null,
+  ): Schema.Schema.AnyNoContext {
+    let schema: Schema.Schema.AnyNoContext = rootObjectSchema;
+    for (let i = 0; i < propertyPath.length; i++) {
+      const propertyName = propertyPath[i];
+      const tupleAst = unwrapArray(schema.ast);
+      if (tupleAst != null) {
+        schema = getArrayElementSchema(tupleAst, propertyName);
+      } else {
+        const propertyType = getPropertyType(schema.ast, propertyName.toString(), (propertyName) =>
+          getProperty([...propertyPath.slice(0, i), propertyName]),
+        );
+        if (propertyType == null) {
+          log.warn('unknown property', { path: propertyPath, property: propertyName });
+          continue;
+        }
+
+        schema = Schema.make(propertyType).annotations(propertyType.annotations);
+      }
+    }
+
+    return schema;
+  }
+
+  public static getTargetPropertySchema(target: any, prop: string | symbol): Schema.Schema.AnyNoContext {
+    const schema: Schema.Schema.AnyNoContext | undefined = (target as any)[SchemaId];
+    invariant(schema, 'target has no schema');
+    const arrayAst = unwrapArray(schema.ast);
+    if (arrayAst != null) {
+      return getArrayElementSchema(arrayAst, prop);
+    }
+
+    const propertyType = getPropertyType(schema.ast, prop.toString(), (prop) => target[prop]);
+    if (propertyType == null) {
+      return Schema.Any; // TODO(burdon): HACK.
+    }
+
+    invariant(propertyType, `invalid property: ${prop.toString()}`);
+    return Schema.make(propertyType);
+  }
+}
+
+/**
+ * Tuple AST is used both for:
+ * fixed-length tuples ([string, number]) in which case AST will be { elements: [Schema.String, Schema.Number] }
+ * variable-length arrays (Array<string | number>) in which case AST will be { rest: [Schema.Union(Schema.String, Schema.Number)] }
+ */
+const getArrayElementSchema = (
+  tupleAst: SchemaAST.TupleType,
+  property: string | symbol | number,
+): Schema.Schema.AnyNoContext => {
+  const elementIndex = typeof property === 'string' ? parseInt(property, 10) : Number.NaN;
+  if (Number.isNaN(elementIndex)) {
+    invariant(property === 'length', `invalid array property: ${String(property)}`);
+    return Schema.Number;
+  }
+  if (elementIndex < tupleAst.elements.length) {
+    const elementType = tupleAst.elements[elementIndex].type;
+    return Schema.make(elementType).annotations(elementType.annotations);
+  }
+
+  const restType = tupleAst.rest;
+  return Schema.make(restType[0].type).annotations(restType[0].annotations);
+};
+
+const flattenUnion = (typeAst: SchemaAST.AST): SchemaAST.AST[] =>
+  SchemaAST.isUnion(typeAst) ? typeAst.types.flatMap(flattenUnion) : [typeAst];
+
+const getProperties = (
+  typeAst: SchemaAST.AST,
+  getTargetPropertyFn: (propertyName: string) => any,
+): SchemaAST.PropertySignature[] => {
+  const astCandidates = flattenUnion(typeAst);
+  const typeAstList = astCandidates.filter((type) => SchemaAST.isTypeLiteral(type)) as SchemaAST.TypeLiteral[];
+  if (typeAstList.length === 0) {
+    return [];
+  }
+  if (typeAstList.length === 1) {
+    return SchemaAST.getPropertySignatures(typeAstList[0]);
+  }
+
+  const typeDiscriminators = getTypeDiscriminators(typeAstList);
+  const targetPropertyValue = getTargetPropertyFn(String(typeDiscriminators[0].name));
+  const typeIndex = typeDiscriminators.findIndex((p) => targetPropertyValue === (p.type as SchemaAST.Literal).literal);
+  invariant(typeIndex !== -1, 'discriminator field not set on target');
+  return SchemaAST.getPropertySignatures(typeAstList[typeIndex]);
+};
+
+const getPropertyType = (
+  ast: SchemaAST.AST,
+  propertyName: string,
+  getTargetPropertyFn: (propertyName: string) => any,
+): SchemaAST.AST | null => {
+  const anyOrObject = unwrapAst(
+    ast,
+    (candidate) => SchemaAST.isAnyKeyword(candidate) || SchemaAST.isObjectKeyword(candidate),
+  );
+  if (anyOrObject != null) {
+    return ast;
+  }
+
+  const typeOrDiscriminatedUnion = unwrapAst(ast, (t) => {
+    return SchemaAST.isTypeLiteral(t) || (SchemaAST.isUnion(t) && t.types.some((t) => SchemaAST.isTypeLiteral(t)));
+  });
+  if (typeOrDiscriminatedUnion == null) {
+    return null;
+  }
+
+  const targetProperty = getProperties(typeOrDiscriminatedUnion, getTargetPropertyFn).find(
+    (p) => p.name === propertyName,
+  );
+  if (targetProperty != null) {
+    return unwrapAst(targetProperty.type);
+  }
+
+  const indexSignatureType = unwrapAst(ast, SchemaAST.isTypeLiteral);
+  if (
+    indexSignatureType &&
+    SchemaAST.isTypeLiteral(indexSignatureType) &&
+    indexSignatureType.indexSignatures.length > 0
+  ) {
+    return unwrapAst(indexSignatureType.indexSignatures[0].type);
+  }
+
+  return null;
+};
+
+const getTypeDiscriminators = (typeAstList: SchemaAST.TypeLiteral[]): SchemaAST.PropertySignature[] => {
+  const discriminatorPropCandidates = typeAstList
+    .flatMap(SchemaAST.getPropertySignatures)
+    .filter((p) => SchemaAST.isLiteral(p.type));
+  const propertyName = discriminatorPropCandidates[0].name;
+  const isValidDiscriminator = discriminatorPropCandidates.every((p) => p.name === propertyName && !p.isOptional);
+  const everyTypeHasDiscriminator = discriminatorPropCandidates.length === typeAstList.length;
+  const isDiscriminatedUnion = isValidDiscriminator && everyTypeHasDiscriminator;
+  invariant(isDiscriminatedUnion, 'type ambiguity: every type in a union must have a single unique-literal field');
+  return discriminatorPropCandidates;
+};
+
+/**
+ * Used to check that rootAst is for a type matching the provided predicate.
+ * That's not always straightforward because types of optionality and recursive types.
+ * const Task = Schema.Struct({
+ *   ...,
+ *   previous?: Schema.optional(Schema.suspend(() => Task)),
+ * });
+ * Here the AST for `previous` field is going to be Union(Suspend(Type), Undefined).
+ * SchemaAST.isTypeLiteral(field) will return false, but unwrapAst(field, (ast) => SchemaAST.isTypeLiteral(ast))
+ * will return true.
+ */
+const unwrapAst = (rootAst: SchemaAST.AST, predicate?: (ast: SchemaAST.AST) => boolean): SchemaAST.AST | null => {
+  let ast: SchemaAST.AST | undefined = rootAst;
+  while (ast != null) {
+    if (predicate?.(ast)) {
+      return ast;
+    }
+
+    if (SchemaAST.isUnion(ast)) {
+      const next: any = ast.types.find((t) => (predicate != null && predicate(t)) || SchemaAST.isSuspend(t));
+      if (next != null) {
+        ast = next;
+        continue;
+      }
+    }
+
+    if (SchemaAST.isSuspend(ast)) {
+      ast = ast.f();
+    } else {
+      return predicate == null ? ast : null;
+    }
+  }
+
+  return null;
+};
+
+const unwrapArray = (ast: SchemaAST.AST) => unwrapAst(ast, SchemaAST.isTupleType) as SchemaAST.TupleType | null;
+
+export const checkIdNotPresentOnSchema = (schema: Schema.Schema<any, any, any>) => {
+  invariant(SchemaAST.isTypeLiteral(schema.ast));
+  const idProperty = SchemaAST.getPropertySignatures(schema.ast).find((prop) => prop.name === 'id');
+  if (idProperty != null) {
+    throw new Error('"id" property name is reserved');
+  }
+};
+
+// TODO(burdon): Reconcile with JsonPath.
+type KeyPath = readonly (string | number)[];

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

@@ -8,23 +8,29 @@ import { describe, expect, test } from 'vitest';
 
 import { createEchoSchema } from '../../testing';
 import { PropertyMeta, getPropertyMetaAnnotation, getTypeAnnotation } from '../annotations';
-import { TypedObject } from '../object';
+import { EchoObjectSchema } from '../entities';
 
 // TODO(dmaretskyi): Comment.
-class EmptySchemaType extends TypedObject({
-  typename: 'example.com/type/Empty',
-  version: '0.1.0',
-})({}) {}
+const EmptySchemaType = Schema.Struct({}).pipe(
+  EchoObjectSchema({
+    typename: 'example.com/type/Empty',
+    version: '0.1.0',
+  }),
+);
+
+interface EmptySchemaType extends Schema.Schema.Type<typeof EmptySchemaType> {}
 
 describe('dynamic schema', () => {
   test('getProperties filters out id and unwraps optionality', async () => {
-    class TestSchema extends TypedObject({
-      typename: 'example.com/type/Test',
-      version: '0.1.0',
-    })({
+    const TestSchema = Schema.Struct({
       field1: Schema.String,
       field2: Schema.Boolean,
-    }) {}
+    }).pipe(
+      EchoObjectSchema({
+        typename: 'example.com/type/Test',
+        version: '0.1.0',
+      }),
+    );
 
     const registered = createEchoSchema(TestSchema);
     expect(registered.getProperties().map((p) => [p.name, p.type])).to.deep.eq([
@@ -34,12 +40,14 @@ describe('dynamic schema', () => {
   });
 
   test('addColumns', async () => {
-    class TestSchema extends TypedObject({
-      typename: 'example.com/type/Test',
-      version: '0.1.0',
-    })({
+    const TestSchema = Schema.Struct({
       field1: Schema.String,
-    }) {}
+    }).pipe(
+      EchoObjectSchema({
+        typename: 'example.com/type/Test',
+        version: '0.1.0',
+      }),
+    );
 
     const registered = createEchoSchema(TestSchema);
     registered.addFields({ field2: Schema.Boolean });

package/src/internal/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');

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

@@ -6,22 +6,21 @@ import * as Schema from 'effect/Schema';
 import { describe, expect, test } from 'vitest';
 
 import { TestSchema } from '../../testing';
-import { isInstanceOf } from '../annotations';
-import { TypedObject, createObject } from '../object';
+import { EchoObjectSchema } from '../entities';
+import { setValue } from '../object';
 import { Ref } from '../ref';
-import { foreignKey, getMeta, getSchema } from '../types';
+import { foreignKey, getMeta } from '../types';
 
 import { makeObject } from './make-object';
+import { change, subscribe } from './reactive';
 
 describe('complex schema validations', () => {
-  const setValue = (target: any, prop: string, value: any) => {
-    target[prop] = value;
-  };
-
   test('any', () => {
     const schema = Schema.Struct({ field: Schema.Any });
     const object = makeObject(schema, { field: { nested: { value: 100 } } });
-    expect(() => setValue(object, 'field', { any: 'value' })).not.to.throw();
+    change(object, (o) => {
+      expect(() => (o.field = { any: 'value' })).not.to.throw();
+    });
   });
 
   test('meta', () => {
@@ -34,12 +33,18 @@ describe('complex schema validations', () => {
   test('object', () => {
     const schema = Schema.Struct({ field: Schema.optional(Schema.Object) });
     const object = makeObject(schema, { field: { nested: { value: 100 } } });
-    expect(() => setValue(object, 'field', { any: 'value' })).not.to.throw();
+    change(object, (o) => {
+      expect(() => (o.field = { any: 'value' })).not.to.throw();
+    });
   });
 
   test('references', () => {
-    class Foo extends TypedObject({ typename: 'example.com/type/Foo', version: '0.1.0' })({ field: Schema.String }) {}
-    class Bar extends TypedObject({ typename: 'example.com/type/Bar', version: '0.1.0' })({ fooRef: Ref(Foo) }) {}
+    const Foo = Schema.Struct({ field: Schema.String }).pipe(
+      EchoObjectSchema({ typename: 'example.com/type/Foo', version: '0.1.0' }),
+    );
+    const Bar = Schema.Struct({ fooRef: Ref(Foo) }).pipe(
+      EchoObjectSchema({ typename: 'example.com/type/Bar', version: '0.1.0' }),
+    );
     const field = 'hello';
     expect(() => makeObject(Bar, { fooRef: { id: '1', field } as any })).to.throw();
     expect(() => makeObject(Bar, { fooRef: undefined as any })).to.throw(); // Unresolved reference.
@@ -50,8 +55,10 @@ describe('complex schema validations', () => {
   test('index signatures', () => {
     const schema = Schema.Struct({}, { key: Schema.String, value: Schema.Number });
     const object = makeObject(schema, { unknownField: 1 });
-    expect(() => setValue(object, 'field', '42')).to.throw();
-    expect(() => setValue(object, 'unknown_field', 42)).not.to.throw();
+    change(object, (o) => {
+      expect(() => setValue(o, ['field'], '42')).to.throw();
+      expect(() => setValue(o, ['unknown_field'], 42)).not.to.throw();
+    });
   });
 
   test('suspend', () => {
@@ -61,30 +68,16 @@ describe('complex schema validations', () => {
     });
 
     const object = makeObject(schema, { array: [1, 2, null], object: { field: 3 } });
-    expect(() => setValue(object, 'object', { field: 4 })).not.to.throw();
-    expect(() => setValue(object.object, 'field', 4)).not.to.throw();
-    expect(() => setValue(object.array, '0', 4)).not.to.throw();
-    expect(() => setValue(object.array, '0', '4')).to.throw();
+    change(object, (o) => {
+      expect(() => (o.object = { field: 4 })).not.to.throw();
+      expect(() => setValue(o, ['object', 'field'], 4)).not.to.throw();
+      expect(() => setValue(o, ['array', 0], 4)).not.to.throw();
+      expect(() => setValue(o, ['array', 0], '4')).to.throw();
+    });
   });
 
-  test('nesting static objects with schema in the live object', () => {
-    const contact1 = createObject(TestSchema.Person, {
-      name: 'Robert Smith',
-      email: 'robert@example.com',
-    } as any);
-    const contact2 = createObject(TestSchema.Person, {
-      name: 'Katy Perry',
-      email: 'katy@example.com',
-    } as any);
-
-    const network = makeObject({ contacts: [contact1] });
-    expect(isInstanceOf(TestSchema.Person, network.contacts[0])).to.eq(true);
-    expect(getSchema(network.contacts[0])).to.eq(TestSchema.Person);
-
-    network.contacts.push(contact2);
-    expect(isInstanceOf(TestSchema.Person, network.contacts[1])).to.eq(true);
-    expect(getSchema(network.contacts[1])).to.eq(TestSchema.Person);
-  });
+  // NOTE: Test for nesting typed objects in untyped containers was removed.
+  // Untyped reactive objects are no longer supported - use Atoms for untyped reactive state.
 
   test('creating an object with data from another object', () => {
     const contact = makeObject(TestSchema.Person, {
@@ -99,4 +92,227 @@ describe('complex schema validations', () => {
 
     expect((object.value as any).name).to.eq('Robert Smith');
   });
+
+  test('subscribe', () => {
+    const TestSchema = Schema.mutable(Schema.Struct({ field: Schema.String })).pipe(
+      EchoObjectSchema({ typename: 'Test', version: '0.1.0' }),
+    );
+    const object = makeObject(TestSchema, { field: 'value' });
+    let called = 0;
+    const unsubscribe = subscribe(object as any, () => {
+      called++;
+    });
+
+    change(object, (o) => {
+      o.field = 'value2';
+    });
+    expect(called).to.eq(1);
+
+    unsubscribe();
+    change(object, (o) => {
+      o.field = 'value3';
+    });
+    expect(called).to.eq(1);
+  });
+});
+
+describe('object structure restrictions', () => {
+  const NestedSchema = Schema.mutable(
+    Schema.Struct({
+      data: Schema.optional(Schema.Any),
+      nested: Schema.optional(Schema.Any),
+    }),
+  );
+
+  test('prevents direct cycles', () => {
+    const obj = makeObject(NestedSchema, { data: null });
+    change(obj, (o) => {
+      expect(() => {
+        o.data = obj;
+      }).to.throw('Cannot create cycles');
+    });
+  });
+
+  test('prevents indirect cycles via nested objects', () => {
+    const obj = makeObject(NestedSchema, {
+      nested: { value: 1 },
+    });
+    change(obj, (o) => {
+      expect(() => {
+        o.nested.parent = obj;
+      }).to.throw('Cannot create cycles');
+    });
+  });
+
+  test('copy-on-assign for cross-proxy assignment', () => {
+    const obj1 = makeObject(NestedSchema, {
+      data: { shared: 'original' },
+    });
+    const obj2 = makeObject(NestedSchema, {});
+
+    // Assign obj1's nested data to obj2.
+    change(obj2, (o) => {
+      o.data = obj1.data;
+    });
+
+    // Should be a copy, not the same reference.
+    expect(obj2.data).to.deep.eq({ shared: 'original' });
+
+    // Modifying obj2.data should not affect obj1.data.
+    change(obj2, (o) => {
+      o.data.shared = 'modified';
+    });
+    expect(obj1.data.shared).to.eq('original');
+    expect(obj2.data.shared).to.eq('modified');
+  });
+
+  test('allows assigning within same typed object', () => {
+    const obj = makeObject(NestedSchema, {
+      data: { value: 1 },
+      nested: null,
+    });
+
+    // Moving data within the same typed object should work without copying.
+    change(obj, (o) => {
+      o.nested = o.data;
+      o.data = null;
+    });
+
+    expect(obj.nested).to.deep.eq({ value: 1 });
+  });
+
+  test('allows assigning plain objects (not owned by any typed object)', () => {
+    const obj = makeObject(NestedSchema, {});
+    const plainData = { value: 'plain' };
+
+    change(obj, (o) => {
+      o.data = plainData;
+    });
+    expect(obj.data).to.deep.eq({ value: 'plain' });
+
+    // Modifying the original plain object should not affect the typed object
+    // (since it's been claimed by the typed object).
+    plainData.value = 'changed';
+    // The value in obj.data depends on when ownership is claimed.
+    // After assignment, the typed object owns it.
+  });
+
+  test('deeply nested objects are owned by root ECHO object', () => {
+    const obj = makeObject(NestedSchema, {
+      data: {
+        level1: {
+          level2: {
+            value: 'deep',
+          },
+        },
+      },
+    });
+
+    // All nested objects should be owned.
+    // Assigning any of them to another ECHO object should trigger copy.
+    const obj2 = makeObject(NestedSchema, {});
+    change(obj2, (o) => {
+      o.data = obj.data.level1;
+    });
+
+    // Should be a copy.
+    expect(obj2.data).to.deep.eq({ level2: { value: 'deep' } });
+
+    // Modifying should not affect original.
+    change(obj2, (o) => {
+      o.data.level2.value = 'modified';
+    });
+    expect(obj.data.level1.level2.value).to.eq('deep');
+  });
+
+  test('array elements are owned by root ECHO object', () => {
+    const ArraySchema = Schema.mutable(
+      Schema.Struct({
+        items: Schema.mutable(Schema.Array(Schema.Any)),
+      }),
+    );
+
+    const obj1 = makeObject(ArraySchema, {
+      items: [{ id: 1 }, { id: 2 }, { id: 3 }],
+    });
+
+    const obj2 = makeObject(ArraySchema, { items: [] });
+
+    // Assign an array element from obj1 to obj2.
+    change(obj2, (o) => {
+      o.items.push(obj1.items[0]);
+    });
+
+    // Should be a copy.
+    expect(obj2.items[0]).to.deep.eq({ id: 1 });
+
+    // Modifying should not affect original.
+    change(obj2, (o) => {
+      o.items[0].id = 100;
+    });
+    expect(obj1.items[0].id).to.eq(1);
+  });
+
+  test('centralized reactivity - direct property mutation triggers event', () => {
+    const obj = makeObject(NestedSchema, {
+      data: { value: 1 },
+    });
+
+    let notificationCount = 0;
+    const unsubscribe = subscribe(obj as any, () => {
+      notificationCount++;
+    });
+
+    // Mutate direct property.
+    change(obj, (o) => {
+      o.data = { value: 2 };
+    });
+    expect(notificationCount).to.eq(1);
+
+    unsubscribe();
+  });
+
+  test('centralized reactivity - nested mutation triggers event on root', () => {
+    const obj = makeObject(NestedSchema, {
+      data: { level1: { value: 1 } },
+    });
+
+    let notificationCount = 0;
+    const unsubscribe = subscribe(obj as any, () => {
+      notificationCount++;
+    });
+
+    // Mutate deeply nested property - should trigger event on root.
+    change(obj, (o) => {
+      o.data.level1.value = 2;
+    });
+    expect(notificationCount).to.eq(1);
+
+    // Another nested mutation.
+    change(obj, (o) => {
+      o.data.level1 = { value: 3 };
+    });
+    expect(notificationCount).to.eq(2);
+
+    unsubscribe();
+  });
+
+  test('reassigning owned object to same root does not copy', () => {
+    const obj = makeObject(NestedSchema, {
+      data: { original: true },
+      nested: null,
+    });
+
+    // Get reference to the nested data.
+    const originalData = obj.data;
+
+    // Move within same ECHO object.
+    change(obj, (o) => {
+      o.nested = o.data;
+      o.data = null;
+    });
+
+    // Should be the same object (no copy).
+    expect(obj.nested).to.eq(originalData);
+  });
 });