@dxos/echo 0.8.4-main.5ea62a8 → 0.8.4-main.66e292d

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

@@ -0,0 +1,233 @@
+//
+// 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 '../annotations';
+import { ObjectDeletedId } from '../entities';
+import { SchemaValidator } from '../object';
+import { SchemaId, TypeId } from '../types';
+
+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, ObjectDeletedId, 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) {
+      // TODO(burdon): Remove?
+      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.
+ */
+// TODO(burdon): Remove?
+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,105 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+import { describe, expect, test } from 'vitest';
+
+import { EchoObjectSchema } from '../entities';
+import { TypedObject } from '../object';
+import { getSchema } from '../types';
+
+import { makeObject } from './make-object';
+
+const Organization = Schema.Struct({
+  name: Schema.String,
+}).pipe(
+  EchoObjectSchema({
+    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,
+  EchoObjectSchema({
+    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('EchoObjectSchema class DSL', () => {
+  test('can get object schema', async () => {
+    const obj = makeObject(Organization, TEST_ORG);
+    expect(getSchema(obj)).to.deep.eq(Organization);
+  });
+
+  describe('class options', () => {
+    test('can assign undefined to partial fields', async () => {
+      const person = makeObject(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 = makeObject(schema, {});
+      (object.meta ??= {}).test = 100;
+      expect(object.meta.test).to.eq(100);
+    }
+
+    {
+      const object = makeObject(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 = makeObject(Test2, {});
+      (object.meta ??= {}).test = 100;
+      expect(object.meta.test).to.eq(100);
+    }
+  });
+});

package/src/internal/ref/index.ts

@@ -0,0 +1,6 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+export * from './ref';
+export * from './ref-array';

package/src/internal/ref/ref-array.ts

@@ -0,0 +1,39 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { type ObjectId } from '@dxos/keys';
+import { isNonNullable } from '@dxos/util';
+
+import { type AnyEchoObject } from '../types';
+
+import { Ref } from './ref';
+
+/**
+ * Helper functions for working with arrays of refs.
+ */
+export const RefArray = Object.freeze({
+  /**
+   * @returns all resolved targets.
+   */
+  targets: <T extends AnyEchoObject>(refs: readonly Ref<T>[]): T[] => {
+    return refs.map((ref) => ref.target).filter(isNonNullable);
+  },
+
+  /**
+   * Load all referenced objects.
+   */
+  loadAll: <T extends AnyEchoObject>(refs: readonly Ref<T>[]): Promise<T[]> => {
+    return Promise.all(refs.map((ref) => ref.load()));
+  },
+
+  /**
+   * Removes the ref with the given id.
+   */
+  removeById: (refs: Ref<AnyEchoObject>[], id: ObjectId) => {
+    const index = refs.findIndex(Ref.hasObjectId(id));
+    if (index >= 0) {
+      refs.splice(index, 1);
+    }
+  },
+});

package/src/internal/ref/ref.test.ts

@@ -0,0 +1,101 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+import { describe, expect, test } from 'vitest';
+
+import { DXN, ObjectId } from '@dxos/keys';
+
+import { EchoObjectSchema, getObjectDXN } from '../entities';
+import { createObject } from '../object';
+
+import { Ref, getReferenceAst } from './ref';
+
+const Task = Schema.Struct({
+  title: Schema.optional(Schema.String),
+}).pipe(
+  EchoObjectSchema({
+    typename: 'example.com/type/Task',
+    version: '0.1.0',
+  }),
+);
+
+type Task = Schema.Schema.Type<typeof Task>;
+
+const Contact = Schema.Struct({
+  name: Schema.String,
+  email: Schema.optional(Schema.String),
+  tasks: Schema.mutable(Schema.Array(Ref(Task))),
+}).pipe(
+  EchoObjectSchema({
+    typename: 'example.com/type/Person',
+    version: '0.1.0',
+  }),
+);
+
+type Contact = Schema.Schema.Type<typeof Contact>;
+
+describe('Ref', () => {
+  test('Schema is', () => {
+    Ref(Contact).pipe(Schema.is)(Ref.fromDXN(DXN.parse(`dxn:echo:@:${ObjectId.random()}`)));
+  });
+
+  test('ref ast', () => {
+    const ref = Ref(Task);
+    expect(ref.ast._tag).toEqual('Declaration');
+    const refAst = getReferenceAst(ref.ast);
+    expect(refAst).toEqual({ typename: Task.typename, version: Task.version });
+  });
+
+  // TODO(dmaretskyi): Figure out how to expose this in the API.
+  test.skip('encode with inlined target', () => {
+    const task = createObject(Task, { title: 'Fix bugs' });
+    const contact = createObject(Contact, { name: 'John Doe', tasks: [Ref.make(task)] });
+
+    const json = JSON.parse(JSON.stringify(contact));
+    expect(json).toEqual({
+      id: contact.id,
+      '@type': `dxn:type:${Contact.typename}:${Contact.version}`,
+      '@meta': {
+        keys: [],
+      },
+      name: 'John Doe',
+      tasks: [
+        {
+          '/': getObjectDXN(task as any)!.toString(),
+          target: JSON.parse(JSON.stringify(task)),
+        },
+      ],
+    });
+  });
+
+  test('encode without inlining target', () => {
+    const task = createObject(Task, { title: 'Fix bugs' });
+    const contact = createObject(Contact, { name: 'John Doe', tasks: [Ref.make(task).noInline()] });
+
+    const json = JSON.parse(JSON.stringify(contact));
+    expect(json).toEqual({
+      id: contact.id,
+      '@type': `dxn:type:${Contact.typename}:${Contact.version}`,
+      '@meta': {
+        keys: [],
+      },
+      name: 'John Doe',
+      tasks: [{ '/': getObjectDXN(task)!.toString() }],
+    });
+  });
+
+  test('decode object', () => {
+    const id = ObjectId.random();
+    const contactData = {
+      id: ObjectId.random(),
+      name: 'John Doe',
+      tasks: [{ '/': `dxn:echo:@:${id}` }],
+    };
+
+    const contact = Contact.pipe(Schema.decodeUnknownSync)(contactData);
+    expect(Ref.isRef(contact.tasks[0])).toEqual(true);
+    expect(contact.tasks[0].dxn.toString()).toEqual(`dxn:echo:@:${id}`);
+  });
+});