@dxos/echo 0.8.4-main.2e9d522 → 0.8.4-main.3c1ae3b

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

@@ -0,0 +1,173 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { inspect } from 'node:util';
+
+import { describe, expect, test } from 'vitest';
+
+import { registerSignalsRuntime } from '@dxos/echo-signals';
+import { type Live, objectData } from '@dxos/live-object';
+import { isNode } from '@dxos/util';
+
+import { TestSchema, updateCounter } from '../../testing';
+import { createObject } from '../object';
+import { ATTR_META } from '../types';
+
+import { makeObject } from './make-object';
+
+registerSignalsRuntime();
+
+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',
+  },
+};
+
+for (const schema of [undefined, TestSchema.ExampleSchema]) {
+  const createObject = (props: Partial<TestSchema.ExampleSchema> = {}): Live<TestSchema.ExampleSchema> => {
+    return schema == null ? (makeObject(props) as TestSchema.ExampleSchema) : makeObject(schema, props);
+  };
+
+  describe(`Non-echo specific proxy properties${schema == null ? '' : ' with schema'}`, () => {
+    test.skipIf(!isNode())('inspect', () => {
+      const obj = createObject({ string: 'bar' });
+      const str = inspect(obj, { colors: false });
+      expect(str).to.eq(`${schema == null ? '' : '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': `${schema ? 'Typed' : ''}ReactiveObject`,
+        ...TEST_OBJECT,
+      });
+    });
+
+    test('can assign class instances', () => {
+      const obj = createObject();
+
+      const classInstance = new TestSchema.TestClass();
+      obj.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;
+
+      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);
+        if (!schema) {
+          expect(JSON.stringify(reactive)).to.eq(JSON.stringify(original));
+        } else {
+          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('signal updates', () => {
+      test('not in nested class instances', () => {
+        const obj = createObject({ classInstance: new TestSchema.TestClass() });
+        using updates = updateCounter(() => {
+          obj.classInstance!.field;
+        });
+        expect(updates.count, 'update count').to.eq(0);
+
+        obj.classInstance!.field = 'baz';
+        expect(updates.count, 'update count').to.eq(0);
+      });
+    });
+  });
+}
+
+describe('getters', () => {
+  test('add getter to object', () => {
+    let value = 'foo';
+    const obj = makeObject({
+      get getter() {
+        return value;
+      },
+    });
+    expect(obj.getter).to.eq('foo');
+
+    value = 'bar';
+    expect(obj.getter).to.eq('bar');
+  });
+
+  test('signal updates', () => {
+    const innerObj = makeObject({
+      string: 'bar',
+    });
+
+    const obj = makeObject({
+      field: 1,
+      get getter() {
+        return innerObj.string;
+      },
+    });
+
+    using updates = updateCounter(() => {
+      const value = obj.getter;
+      expect(value).to.exist;
+    });
+
+    innerObj.string = 'baz';
+    expect(obj.getter).to.eq('baz');
+    expect(updates.count, 'update count').to.eq(1);
+
+    obj.field = 2;
+    expect(updates.count, 'update count').to.eq(1);
+  });
+
+  test('getter for array', () => {
+    const value = [1];
+    const obj = makeObject({
+      get getter() {
+        return value;
+      },
+    });
+    expect(obj.getter).to.have.length(1);
+
+    value.push(2);
+    expect(obj.getter).to.have.length(2);
+  });
+});

package/src/internal/proxy/index.ts

@@ -0,0 +1,6 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export * from './make-object';
+export * from './typed-handler';

package/src/internal/proxy/make-object.ts

@@ -0,0 +1,113 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import type * as Schema from 'effect/Schema';
+
+import { ObjectId } from '@dxos/keys';
+import {
+  type Live,
+  UntypedReactiveHandler,
+  createProxy,
+  defineHiddenProperty,
+  isValidProxyTarget,
+} from '@dxos/live-object';
+
+import { getTypeAnnotation } from '../annotations';
+import { Expando } from '../entities';
+import { attachTypedJsonSerializer } from '../object';
+import { type AnyProperties, KindId, MetaId, type ObjectMeta, ObjectMetaSchema } from '../types';
+
+import { TypedReactiveHandler, prepareTypedTarget } 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.
+ * Optionally provides 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>(obj: T): Live<T>;
+  <T extends AnyProperties>(
+    schema: Schema.Schema<T, any, never>,
+    obj: NoInfer<MakeObjectProps<T>>,
+    meta?: ObjectMeta,
+  ): Live<T>;
+} = <T extends AnyProperties>(
+  objOrSchema: Schema.Schema<T, any> | T,
+  obj?: MakeObjectProps<T>,
+  meta?: ObjectMeta,
+): Live<T> => {
+  // TODO(dmaretskyi): Remove Expando special case.
+  if (obj && (objOrSchema as any) !== Expando) {
+    return createReactiveObject<T>({ ...obj } as T, meta, objOrSchema as Schema.Schema<T, any>);
+  } else if (obj && (objOrSchema as any) === Expando) {
+    return createReactiveObject<T>({ ...obj } as T, meta, undefined, { expando: true });
+  } else {
+    return createReactiveObject<T>(objOrSchema as T, meta);
+  }
+};
+
+const createReactiveObject = <T extends AnyProperties>(
+  obj: T,
+  meta?: ObjectMeta,
+  schema?: Schema.Schema<T>,
+  options?: { expando?: boolean },
+): Live<T> => {
+  if (!isValidProxyTarget(obj)) {
+    throw new Error('Value cannot be made into a reactive object.');
+  }
+
+  if (schema) {
+    const annotation = getTypeAnnotation(schema);
+    const shouldGenerateId = options?.expando || !!annotation;
+    if (shouldGenerateId) {
+      setIdOnTarget(obj);
+    }
+    if (annotation) {
+      defineHiddenProperty(obj, KindId, annotation.kind);
+    }
+    initMeta(obj, meta);
+    prepareTypedTarget(obj, schema);
+    attachTypedJsonSerializer(obj);
+    return createProxy<T>(obj, TypedReactiveHandler.instance);
+  } else {
+    if (options?.expando) {
+      setIdOnTarget(obj);
+    }
+    initMeta(obj, meta);
+    return createProxy<T>(obj, UntypedReactiveHandler.instance);
+  }
+};
+
+/**
+ * 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/schema.test.ts

@@ -0,0 +1,137 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+import * as SchemaAST from 'effect/SchemaAST';
+import { describe, expect, test } from 'vitest';
+
+import { createEchoSchema } from '../../testing';
+import { PropertyMeta, getPropertyMetaAnnotation, getTypeAnnotation } from '../annotations';
+import { TypedObject } from '../object';
+
+// TODO(dmaretskyi): Comment.
+class EmptySchemaType extends TypedObject({
+  typename: 'example.com/type/Empty',
+  version: '0.1.0',
+})({}) {}
+
+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',
+    })({
+      field1: Schema.String,
+      field2: Schema.Boolean,
+    }) {}
+
+    const registered = createEchoSchema(TestSchema);
+    expect(registered.getProperties().map((p) => [p.name, p.type])).to.deep.eq([
+      ['field1', SchemaAST.stringKeyword],
+      ['field2', SchemaAST.booleanKeyword],
+    ]);
+  });
+
+  test('addColumns', async () => {
+    class TestSchema extends TypedObject({
+      typename: 'example.com/type/Test',
+      version: '0.1.0',
+    })({
+      field1: Schema.String,
+    }) {}
+
+    const registered = createEchoSchema(TestSchema);
+    registered.addFields({ field2: Schema.Boolean });
+    expect(registered.getProperties().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(EmptySchemaType);
+    registered.addFields({ field1: Schema.String });
+    registered.addFields({ field2: Schema.Boolean });
+    registered.addFields({ field3: Schema.Number });
+    registered.updateFields({ field4: Schema.Boolean, field2: Schema.String });
+    expect(registered.getProperties().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(EmptySchemaType);
+    registered.addFields({ field1: Schema.String });
+    registered.addFields({ field2: Schema.Boolean });
+    registered.addFields({ field3: Schema.Number });
+    registered.removeFields(['field2']);
+    expect(registered.getProperties().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(EmptySchemaType);
+    registered.addFields({
+      field1: Schema.String.pipe(PropertyMeta(metaNamespace, metaInfo)),
+      field2: Schema.String,
+    });
+    registered.addFields({ field3: Schema.String });
+    registered.updateFields({ field3: Schema.Boolean });
+    registered.removeFields(['field2']);
+    expect(getTypeAnnotation(registered)).to.deep.contain({
+      typename: 'example.com/type/Empty',
+      version: '0.1.0',
+    });
+    expect(getPropertyMetaAnnotation(registered.getProperties()[0], metaNamespace)).to.deep.eq(metaInfo);
+  });
+
+  test('updates typename', async ({ expect }) => {
+    // Create schema with some fields and annotations.
+    const registered = createEchoSchema(EmptySchemaType);
+    const originalVersion = registered.persistentSchema.version;
+    registered.addFields({
+      name: Schema.String.pipe(PropertyMeta('test', { maxLength: 10 })),
+      age: Schema.Number,
+    });
+
+    // First update.
+    const newTypename1 = 'example.com/type/Individual';
+    registered.updateTypename(newTypename1);
+
+    // Basic typename update checks.
+    expect(registered.typename).toBe(newTypename1);
+    expect(registered.jsonSchema.$id).toBe(`dxn:type:${newTypename1}`);
+    expect(registered.jsonSchema.typename).toBe(newTypename1);
+
+    // Version preservation check.
+    expect(registered.persistentSchema.version).toBe(originalVersion);
+
+    // Field preservation check.
+    const properties = registered.getProperties();
+    expect(properties).toHaveLength(2);
+    expect(properties[0].name).toBe('name');
+
+    // Annotation preservation check.
+    const nameMeta = getPropertyMetaAnnotation(properties[0], 'test');
+    expect(nameMeta).toEqual({ maxLength: 10 });
+
+    // Second update to ensure multiple updates work.
+    const newTypename2 = 'example.com/type/Person';
+    registered.updateTypename(newTypename2);
+    expect(registered.typename).toBe(newTypename2);
+    expect(registered.jsonSchema.$id).toBe(`dxn:type:${newTypename2}`);
+    expect(registered.jsonSchema.typename).toBe(newTypename2);
+    expect(getTypeAnnotation(registered)).to.deep.contain({
+      typename: 'example.com/type/Person',
+      version: '0.1.0',
+    });
+  });
+});

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

@@ -0,0 +1,102 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+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 { Ref } from '../ref';
+import { foreignKey, getMeta, getSchema } from '../types';
+
+import { makeObject } from './make-object';
+
+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();
+  });
+
+  test('meta', () => {
+    const source = 'test';
+    const schema = Schema.Struct({ field: Schema.Number });
+    const object = makeObject(schema, { field: 42 }, { keys: [foreignKey(source, '123')] });
+    expect(getMeta(object).keys).to.deep.eq([foreignKey(source, '123')]);
+  });
+
+  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();
+  });
+
+  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 field = 'hello';
+    expect(() => makeObject(Bar, { fooRef: { id: '1', field } as any })).to.throw();
+    expect(() => makeObject(Bar, { fooRef: undefined as any })).to.throw(); // Unresolved reference.
+    const bar = makeObject(Bar, { fooRef: Ref.make(makeObject(Foo, { field })) });
+    expect(bar.fooRef.target?.field).to.eq(field);
+  });
+
+  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();
+  });
+
+  test('suspend', () => {
+    const schema = 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 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();
+  });
+
+  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);
+  });
+
+  test('creating an object with data from another object', () => {
+    const contact = makeObject(TestSchema.Person, {
+      name: 'Robert Smith',
+      email: 'robert@example.com',
+    });
+
+    const TempSchema = Schema.Struct({ value: Schema.Unknown });
+    const object = makeObject(TempSchema, {
+      value: contact,
+    });
+
+    expect((object.value as any).name).to.eq('Robert Smith');
+  });
+});