@dxos/echo 0.8.4-main.e098934 → 0.8.4-main.e8ec1fe

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

@@ -0,0 +1,108 @@
+//
+// 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 '../ast';
+import { EntityKindId, Expando, MetaId, type ObjectMeta, ObjectMetaSchema, attachTypedJsonSerializer } from '../object';
+import type { BaseObject, CreationProps } from '../types';
+
+import { TypedReactiveHandler, prepareTypedTarget } from './typed-handler';
+
+/**
+ * Creates a reactive object from a plain Javascript object.
+ * Optionally provides a TS-effect schema.
+ *
+ * @depreacted Use `Obj.make`.
+ */
+// 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.
+// TODO(burdon): Use Schema.make() to handle defaults?
+export const live: {
+  <T extends BaseObject>(obj: T): Live<T>;
+  <T extends BaseObject>(
+    schema: Schema.Schema<T, any, never>,
+    obj: NoInfer<CreationProps<T>>,
+    meta?: ObjectMeta,
+  ): Live<T>;
+} = <T extends BaseObject>(
+  objOrSchema: Schema.Schema<T, any> | T,
+  obj?: CreationProps<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 BaseObject>(
+  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, EntityKindId, 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,136 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+import * as SchemaAST from 'effect/SchemaAST';
+import { describe, expect, test } from 'vitest';
+
+import { PropertyMeta, TypedObject, getPropertyMetaAnnotation, getTypeAnnotation } from '..';
+import { createEchoSchema } from '../../testing/echo-schema';
+
+// 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.storedSchema.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.storedSchema.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 { Ref, TypedObject, create, foreignKey, getMeta, getSchema, isInstanceOf } from '..';
+import { Testing } from '../testing';
+
+import { live } from './reactive-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 = live(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 = live(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 = live(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(() => live(Bar, { fooRef: { id: '1', field } as any })).to.throw();
+    expect(() => live(Bar, { fooRef: undefined as any })).to.throw(); // Unresolved reference.
+    const bar = live(Bar, { fooRef: Ref.make(live(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 = live(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 = live(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 = create(Testing.Person, {
+      name: 'Robert Smith',
+      email: 'robert@example.com',
+    } as any);
+    const contact2 = create(Testing.Person, {
+      name: 'Katy Perry',
+      email: 'katy@example.com',
+    } as any);
+
+    const contactBook = live({
+      contacts: [contact1],
+    });
+
+    expect(isInstanceOf(Testing.Person, contactBook.contacts[0])).to.eq(true);
+    expect(getSchema(contactBook.contacts[0])).to.eq(Testing.Person);
+
+    contactBook.contacts.push(contact2);
+    expect(isInstanceOf(Testing.Person, contactBook.contacts[1])).to.eq(true);
+    expect(getSchema(contactBook.contacts[1])).to.eq(Testing.Person);
+  });
+
+  test('creating an object with data from another object', () => {
+    const contact = live(Testing.Person, {
+      name: 'Robert Smith',
+      email: 'robert@example.com',
+    });
+    const TestSchema = Schema.Struct({
+      value: Schema.Unknown,
+    });
+    const data = live(TestSchema, {
+      value: contact,
+    });
+    expect((data.value as any).name).to.eq('Robert Smith');
+  });
+});

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

@@ -0,0 +1,228 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { type InspectOptionsStylized } from 'node:util';
+
+import * as Schema from 'effect/Schema';
+import * as SchemaAST from 'effect/SchemaAST';
+
+import { inspectCustom } from '@dxos/debug';
+import { type GenericSignal, compositeRuntime } from '@dxos/echo-signals/runtime';
+import { invariant } from '@dxos/invariant';
+import {
+  ReactiveArray,
+  type ReactiveHandler,
+  createProxy,
+  defineHiddenProperty,
+  isValidProxyTarget,
+  objectData,
+  symbolIsProxy,
+} from '@dxos/live-object';
+
+import { getSchemaDXN } from '../ast';
+import { DeletedId, SchemaId, SchemaValidator, TypeId } from '../object';
+
+const symbolSignal = Symbol('signal');
+const symbolPropertySignal = Symbol('property-signal');
+
+type ProxyTarget = {
+  /**
+   * Typename or type DXN.
+   */
+  [TypeId]: string;
+
+  /**
+   * Schema for the root.
+   */
+  [SchemaId]: Schema.Schema.AnyNoContext;
+
+  /**
+   * For get and set operations on value properties.
+   */
+  // TODO(dmaretskyi): Turn into a map of signals per-field.
+  [symbolSignal]: GenericSignal;
+
+  /**
+   * For modifying the structure of the object.
+   */
+  [symbolPropertySignal]: GenericSignal;
+} & ({ [key: keyof any]: any } | any[]);
+
+/**
+ * Typed in-memory reactive store (with Schema).
+ */
+export class TypedReactiveHandler implements ReactiveHandler<ProxyTarget> {
+  public static readonly instance: ReactiveHandler<any> = new TypedReactiveHandler();
+
+  readonly _proxyMap = new WeakMap<object, any>();
+
+  private constructor() {}
+
+  init(target: ProxyTarget): void {
+    invariant(typeof target === 'object' && target !== null);
+    invariant(SchemaId in target, 'Schema is not defined for the target');
+
+    if (!(symbolSignal in target)) {
+      defineHiddenProperty(target, symbolSignal, compositeRuntime.createSignal());
+      defineHiddenProperty(target, symbolPropertySignal, compositeRuntime.createSignal());
+    }
+
+    defineHiddenProperty(target, DeletedId, false);
+
+    for (const key of Object.getOwnPropertyNames(target)) {
+      const descriptor = Object.getOwnPropertyDescriptor(target, key)!;
+      if (descriptor.get) {
+        // Ignore getters.
+        continue;
+      }
+
+      // Array reactivity is already handled by the schema validator.
+    }
+
+    // Maybe have been set by `create`.
+    Object.defineProperty(target, inspectCustom, {
+      enumerable: false,
+      configurable: true,
+      value: this._inspect.bind(target),
+    });
+  }
+
+  get(target: ProxyTarget, prop: string | symbol, receiver: any): any {
+    switch (prop) {
+      case objectData: {
+        target[symbolSignal].notifyRead();
+        return toJSON(target);
+      }
+    }
+
+    // Handle getter properties. Will not subscribe the value signal.
+    if (Object.getOwnPropertyDescriptor(target, prop)?.get) {
+      target[symbolPropertySignal].notifyRead();
+
+      // TODO(dmaretskyi): Turn getters into computed fields.
+      return Reflect.get(target, prop, receiver);
+    }
+
+    target[symbolSignal].notifyRead();
+    target[symbolPropertySignal].notifyRead();
+
+    const value = Reflect.get(target, prop, receiver);
+    if (isValidProxyTarget(value)) {
+      return createProxy(value, this);
+    }
+
+    return value;
+  }
+
+  set(target: ProxyTarget, prop: string | symbol, value: any, receiver: any): boolean {
+    // Convert arrays to reactive arrays on write.
+    if (Array.isArray(value)) {
+      value = ReactiveArray.from(value);
+    }
+
+    let result: boolean = false;
+    compositeRuntime.batch(() => {
+      const validatedValue = this._validateValue(target, prop, value);
+      result = Reflect.set(target, prop, validatedValue, receiver);
+      target[symbolSignal].notifyWrite();
+    });
+    return result;
+  }
+
+  ownKeys(target: ProxyTarget): ArrayLike<string | symbol> {
+    // Touch both signals since `set` and `delete` operations may create or remove properties.
+    target[symbolSignal].notifyRead();
+    target[symbolPropertySignal].notifyRead();
+    return Reflect.ownKeys(target);
+  }
+
+  defineProperty(target: ProxyTarget, property: string | symbol, attributes: PropertyDescriptor): boolean {
+    const validatedValue = this._validateValue(target, property, attributes.value);
+    const result = Reflect.defineProperty(target, property, {
+      ...attributes,
+      value: validatedValue,
+    });
+    target[symbolPropertySignal].notifyWrite();
+    return result;
+  }
+
+  private _validateValue(target: any, prop: string | symbol, value: any) {
+    const schema = SchemaValidator.getTargetPropertySchema(target, prop);
+    const _ = Schema.asserts(schema)(value);
+    if (Array.isArray(value)) {
+      value = new ReactiveArray(...value);
+    }
+    if (isValidProxyTarget(value)) {
+      setSchemaProperties(value, schema);
+    }
+
+    return value;
+  }
+
+  private _inspect(
+    _: number,
+    options: InspectOptionsStylized,
+    inspectFn: (value: any, options?: InspectOptionsStylized) => string,
+  ): string {
+    const inspected = inspectFn(this, {
+      ...options,
+      showHidden: false,
+      customInspect: false,
+    });
+    return `Typed ${inspected}`;
+  }
+}
+
+/**
+ * @deprecated Use `Obj.toJSON` instead.
+ */
+const toJSON = (target: ProxyTarget): any => {
+  return { '@type': 'TypedReactiveObject', ...target };
+};
+
+/**
+ * Recursively set AST on all potential proxy targets.
+ */
+const setSchemaProperties = (obj: any, schema: Schema.Schema.AnyNoContext) => {
+  const schemaType = getSchemaDXN(schema);
+  if (schemaType != null) {
+    defineHiddenProperty(obj, TypeId, schemaType);
+  }
+
+  defineHiddenProperty(obj, SchemaId, schema);
+  for (const key in obj) {
+    if (isValidProxyTarget(obj[key])) {
+      const elementSchema = SchemaValidator.getTargetPropertySchema(obj, key);
+      if (elementSchema != null) {
+        setSchemaProperties(obj[key], elementSchema);
+      }
+    }
+  }
+};
+
+export const prepareTypedTarget = <T>(target: T, schema: Schema.Schema<T>) => {
+  // log.info('prepareTypedTarget', { target, schema });
+  if (!SchemaAST.isTypeLiteral(schema.ast)) {
+    throw new Error('schema has to describe an object type');
+  }
+
+  SchemaValidator.validateSchema(schema);
+  const _ = Schema.asserts(schema)(target);
+  makeArraysReactive(target);
+  setSchemaProperties(target, schema);
+};
+
+const makeArraysReactive = (target: any) => {
+  for (const key in target) {
+    if (target[symbolIsProxy]) {
+      continue;
+    }
+    if (Array.isArray(target[key])) {
+      target[key] = ReactiveArray.from(target[key]);
+    }
+    if (typeof target[key] === 'object') {
+      makeArraysReactive(target[key]);
+    }
+  }
+};

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

@@ -0,0 +1,100 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+import { describe, expect, test } from 'vitest';
+
+import { EchoObject, TypedObject, getSchema } from '..';
+
+import { live } from './reactive-object';
+
+const Organization = Schema.Struct({
+  name: Schema.String,
+}).pipe(
+  EchoObject({
+    typename: 'example.com/type/Organization',
+    version: '0.1.0',
+  }),
+);
+
+interface Organization extends Schema.Schema.Type<typeof Organization> {}
+
+const Contact = Schema.Struct(
+  {
+    name: Schema.String,
+  },
+  { key: Schema.String, value: Schema.Any },
+).pipe(
+  Schema.partial,
+  EchoObject({
+    typename: 'example.com/type/Person',
+    version: '0.1.0',
+  }),
+);
+
+interface Contact extends Schema.Schema.Type<typeof Contact> {}
+
+const TEST_ORG: Omit<Organization, 'id'> = { name: 'Test' };
+
+describe('EchoObject class DSL', () => {
+  test('can get object schema', async () => {
+    const obj = live(Organization, TEST_ORG);
+    expect(getSchema(obj)).to.deep.eq(Organization);
+  });
+
+  describe('class options', () => {
+    test('can assign undefined to partial fields', async () => {
+      const person = live(Contact, { name: 'John' });
+      person.name = undefined;
+      person.recordField = 'hello';
+      expect(person.name).to.be.undefined;
+      expect(person.recordField).to.eq('hello');
+    });
+  });
+
+  test('record', () => {
+    const schema = Schema.mutable(
+      Schema.Struct({
+        meta: Schema.optional(Schema.mutable(Schema.Any)),
+        // NOTE: Schema.Record only supports shallow values.
+        // https://www.npmjs.com/package/@effect/schema#mutable-records
+        // meta: Schema.optional(Schema.mutable(Schema.Record({ key: Schema.String, value: Schema.Any }))),
+        // meta: Schema.optional(Schema.mutable(Schema.object)),
+      }),
+    );
+
+    {
+      const object = live(schema, {});
+      (object.meta ??= {}).test = 100;
+      expect(object.meta.test).to.eq(100);
+    }
+
+    {
+      const object = live(schema, {});
+      object.meta = { test: { value: 300 } };
+      expect(object.meta.test.value).to.eq(300);
+    }
+
+    {
+      type Test1 = Schema.Schema.Type<typeof schema>;
+
+      const object: Test1 = {};
+      (object.meta ??= {}).test = 100;
+      expect(object.meta.test).to.eq(100);
+    }
+
+    {
+      class Test2 extends TypedObject({
+        typename: 'dxos.org/type/FunctionTrigger',
+        version: '0.1.0',
+      })({
+        meta: Schema.optional(Schema.mutable(Schema.Record({ key: Schema.String, value: Schema.Any }))),
+      }) {}
+
+      const object = live(Test2, {});
+      (object.meta ??= {}).test = 100;
+      expect(object.meta.test).to.eq(100);
+    }
+  });
+});

package/src/internal/query/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export * from './query';