@dxos/echo 0.8.4-main.dedc0f3 → 0.8.4-main.ead640a

package/src/internal/testing/types.ts

@@ -0,0 +1,211 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+
+import { EchoObject, EchoRelation, Expando, TypedObject } from '../object';
+import { Ref, type Ref$ } from '../ref';
+
+// TODO(burdon): These are non-canonical test types, so we really shouldn't export and use in other classes (compare with @dxos/sdk/testing).
+export namespace Testing {
+  //
+  // Primitives
+  //
+
+  const Circle = Schema.Struct({ type: Schema.Literal('circle'), radius: Schema.Number });
+  const Square = Schema.Struct({ type: Schema.Literal('square'), side: Schema.Number });
+  const Shape = Schema.Union(Circle, Square);
+
+  //
+  // Simple types
+  //
+
+  const TestNestedSchema = Schema.mutable(Schema.Struct({ field: Schema.String }));
+  export type TestNestedSchema = Schema.Schema.Type<typeof TestNestedSchema>;
+  export const TestNestedType = TestNestedSchema.pipe(
+    EchoObject({ typename: 'example.com/type/TestNested', version: '0.1.0' }),
+  );
+
+  //
+  // Complex types
+  // TODO(burdon): Change to Type.Obj.
+  //
+
+  export class EmptySchemaType extends TypedObject({
+    typename: 'example.com/type/Empty',
+    version: '0.1.0',
+  })({}) {}
+
+  const fields = {
+    string: Schema.String,
+    number: Schema.Number,
+    nullableShapeArray: Schema.mutable(Schema.Array(Schema.Union(Shape, Schema.Null))),
+    boolean: Schema.Boolean,
+    null: Schema.Null,
+    undefined: Schema.Undefined,
+    stringArray: Schema.mutable(Schema.Array(Schema.String)),
+    twoDimNumberArray: Schema.mutable(Schema.Array(Schema.mutable(Schema.Array(Schema.Number)))),
+    object: TestNestedSchema,
+    objectArray: Schema.mutable(Schema.Array(TestNestedSchema)),
+    nested: Schema.optional(Ref(TestNestedType)),
+    other: Schema.Any,
+  };
+
+  export const TestSchema = Schema.mutable(Schema.partial(Schema.Struct(fields)));
+  export type TestSchema = Schema.Schema.Type<typeof TestSchema>;
+
+  export class TestSchemaType extends TypedObject({
+    typename: 'example.com/type/Test',
+    version: '0.1.0',
+  })(fields, { partial: true }) {} // TODO(burdon): Partial?
+
+  // TODO(burdon): Why do we use need this rather then TestSchemaType?
+  export const TestType = TestSchema.pipe(
+    EchoObject({
+      typename: 'example.com/type/Test',
+      version: '0.1.0',
+    }),
+  );
+
+  export class TestClass {
+    field = 'value';
+    toJSON() {
+      return { field: this.field };
+    }
+  }
+
+  // TODO(dmaretskyi): Another top-level Schema.mutable call as a workaround for the regression in the last minor.
+  export const TestSchemaWithClass = Schema.mutable(
+    Schema.extend(
+      TestSchema,
+      Schema.mutable(
+        Schema.Struct({
+          classInstance: Schema.optional(Schema.instanceOf(TestClass)),
+        }),
+      ),
+    ),
+  );
+
+  export type TestSchemaWithClass = Schema.Schema.Type<typeof TestSchemaWithClass>;
+
+  export class Contact extends TypedObject({
+    typename: 'example.com/type/Contact',
+    version: '0.1.0',
+  })(
+    {
+      name: Schema.String,
+      username: Schema.String,
+      email: Schema.String,
+      phoneNumbers: Schema.optional(Schema.Array(Schema.Struct({ label: Schema.String, number: Schema.String }))),
+      tasks: Schema.suspend((): Schema.mutable<Schema.Array$<Ref$<Task>>> => Schema.mutable(Schema.Array(Ref(Task)))),
+      address: Schema.Struct({
+        city: Schema.optional(Schema.String),
+        state: Schema.optional(Schema.String),
+        zip: Schema.optional(Schema.String),
+        coordinates: Schema.Struct({
+          lat: Schema.optional(Schema.Number),
+          lng: Schema.optional(Schema.Number),
+        }),
+      }),
+    },
+    { partial: true },
+  ) {}
+
+  export class Task extends TypedObject({
+    typename: 'example.com/type/Task',
+    version: '0.1.0',
+  })(
+    {
+      title: Schema.optional(Schema.String),
+      completed: Schema.optional(Schema.Boolean),
+      assignee: Schema.optional(Ref(Contact)),
+      previous: Schema.optional(Schema.suspend((): Ref$<Task> => Ref(Task))),
+      subTasks: Schema.optional(Schema.mutable(Schema.Array(Schema.suspend((): Ref$<Task> => Ref(Task))))),
+      description: Schema.optional(Schema.String),
+    },
+    { partial: true },
+  ) {}
+
+  // TOOD(burdon): Ref$ breaks if using new syntax (since ID is not declared).
+
+  // export const Task = Schema.Struct({
+  //   title: Schema.String,
+  //   completed: Schema.Boolean,
+  //   assignee: Schema.optional(Ref(Schema.suspend((): Ref$<Contact> => Ref(Contact)))),
+  //   previous: Schema.optional(Ref(Schema.suspend((): Ref$<Task> => Ref(Task)))),
+  //   subTasks: Schema.optional(Schema.Array(Ref(Schema.suspend((): Ref$<Task> => Ref(Task))))),
+  //   description: Schema.optional(Schema.String),
+  // }).pipe(
+  //   EchoObject({
+  //     typename: 'example.com/type/Task',
+  //     version: '0.1.0',
+  //   }),
+  // );
+
+  // export type Task = Schema.Schema.Type<typeof Task>;
+
+  // export const Contact = Schema.Struct({
+  //   name: Schema.String,
+  //   username: Schema.String,
+  //   email: Schema.String,
+  //   // TOOD(burdon): Should model via relations?
+  //   // tasks: Schema.mutable(Schema.Array(Ref(Task))),
+  //   address: Schema.Struct({
+  //     city: Schema.optional(Schema.String),
+  //     state: Schema.optional(Schema.String),
+  //     zip: Schema.optional(Schema.String),
+  //     coordinates: Schema.Struct({
+  //       lat: Schema.optional(Schema.Number),
+  //       lng: Schema.optional(Schema.Number),
+  //     }),
+  //   }),
+  // }).pipe(
+  //   EchoObject({
+  //     typename: 'example.com/type/Contact',
+  //     version: '0.1.0',
+  //   }),
+  // );
+
+  // export type Contact = Schema.Schema.Type<typeof Contact>;
+
+  export enum RecordType {
+    UNDEFINED = 0,
+    PERSONAL = 1,
+    WORK = 2,
+  }
+
+  export class Container extends TypedObject({
+    typename: 'example.com/type/Container',
+    version: '0.1.0',
+  })(
+    {
+      objects: Schema.mutable(Schema.Array(Ref(Expando))),
+      records: Schema.mutable(
+        Schema.Array(
+          Schema.partial(
+            Schema.Struct({
+              title: Schema.String,
+              description: Schema.String,
+              contacts: Schema.mutable(Schema.Array(Ref(Contact))),
+              type: Schema.Enums(RecordType),
+            }),
+          ),
+        ),
+      ),
+    },
+    { partial: true },
+  ) {}
+
+  export const HasManager = Schema.Struct({
+    since: Schema.optional(Schema.String),
+  }).pipe(
+    EchoRelation({
+      typename: 'example.com/type/HasManager',
+      version: '0.1.0',
+      source: Contact,
+      target: Contact,
+    }),
+  );
+  export interface HasManager extends Schema.Schema.Type<typeof HasManager> {}
+}

package/src/internal/testing/utils.ts

@@ -0,0 +1,54 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { effect } from '@preact/signals-core';
+import type * as SchemaAST from 'effect/SchemaAST';
+
+import { registerSignalsRuntime } from '@dxos/echo-signals';
+import { deepMapValues } from '@dxos/util';
+
+registerSignalsRuntime();
+
+// TODO(burdon): Move to util.
+export const updateCounter = (touch: () => void) => {
+  let updateCount = -1;
+  const unsubscribe = effect(() => {
+    touch();
+    updateCount++;
+  });
+
+  return {
+    // https://github.com/tc39/proposal-explicit-resource-management
+    [Symbol.dispose]: unsubscribe,
+    get count() {
+      return updateCount;
+    },
+  };
+};
+
+/**
+ * Converts AST to a format that can be compared with test matchers.
+ */
+export const prepareAstForCompare = (obj: SchemaAST.AST): any =>
+  deepMapValues(obj, (value: any, recurse, key) => {
+    if (typeof value === 'function') {
+      return null;
+    }
+
+    if (value instanceof RegExp) {
+      return value;
+    }
+
+    // Convert symbols to strings.
+    if (typeof value === 'object') {
+      const clone = { ...value };
+      for (const sym of Object.getOwnPropertySymbols(clone as any)) {
+        clone[sym.toString()] = clone[sym];
+        delete clone[sym];
+      }
+      return recurse(clone);
+    }
+
+    return recurse(value);
+  });

package/src/internal/types/index.ts

@@ -0,0 +1,6 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+export * from './types';
+export type * from './util';

package/src/internal/types/types.test.ts

@@ -0,0 +1,48 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { describe, test } from 'vitest';
+
+import { type JsonPath } from '@dxos/effect';
+
+import { type BaseObject, getValue, setValue } from './types';
+
+describe('Types', () => {
+  test('checks sanity', async ({ expect }) => {
+    const obj: BaseObject = {};
+    expect(obj).to.exist;
+  });
+});
+
+describe('get/set deep', () => {
+  test('get/set operations', ({ expect }) => {
+    const obj = {
+      name: 'test',
+      items: ['a', 'b', 'c'],
+      nested: {
+        prop: 'value',
+        arr: [1, 2, 3],
+      },
+    };
+
+    // Basic property access.
+    expect(getValue(obj, 'name' as JsonPath)).toBe('test');
+
+    // Array index access.
+    expect(getValue(obj, 'items[1]' as JsonPath)).toBe('b');
+
+    // Nested property access.
+    expect(getValue(obj, 'nested.prop' as JsonPath)).toBe('value');
+
+    // Nested array access.
+    expect(getValue(obj, 'nested.arr[2]' as JsonPath)).toBe(3);
+
+    // Setting values.
+    const updated1 = setValue(obj, 'items[1]' as JsonPath, 'x');
+    expect(updated1.items[1]).toBe('x');
+
+    const updated2 = setValue(obj, 'nested.arr[0]' as JsonPath, 99);
+    expect(updated2.nested.arr[0]).toBe(99);
+  });
+});

package/src/internal/types/types.ts

@@ -0,0 +1,176 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+import * as SchemaAST from 'effect/SchemaAST';
+
+import { Reference } from '@dxos/echo-protocol';
+import { type JsonPath, splitJsonPath } from '@dxos/effect';
+import { DXN, type ObjectId } from '@dxos/keys';
+import { getDeep, setDeep } from '@dxos/util';
+
+import { getSchemaDXN } from '../ast';
+import { type EntityKindId, type ObjectMeta, getType, getTypename } from '../object';
+import { ATTR_META } from '../object/model';
+
+/**
+ * Base type for all data objects (reactive, ECHO, and other raw objects).
+ * NOTE: This describes the base type for all database objects.
+ * It is stricter than `T extends {}` or `T extends object`.
+ */
+// TODO(dmaretskyi): Rename AnyProperties.
+// TODO(dmaretskyi): Prefer `Record<string, unknown>` over `any`.
+/**
+ * @deprecated use Obj.Any
+ */
+export type BaseObject = Record<string, any>;
+
+/**
+ * Marker interface for object with an `id`.
+ */
+export interface HasId {
+  readonly id: ObjectId;
+}
+
+// TODO(dmaretskyi): Remove; this type effectively disables type safety due to `any`.
+export type WithId<T extends BaseObject = BaseObject> = T & HasId;
+
+export type ExcludeId<T extends BaseObject> = Omit<T, 'id'>;
+
+/**
+ * Properties that are required for object creation.
+ */
+// TODO(dmaretskyi): Rename `MakeProps`?
+export type CreationProps<T extends BaseObject> = Omit<T, 'id' | typeof EntityKindId>;
+
+export type PropertyKey<T extends BaseObject> = Extract<keyof ExcludeId<T>, string>;
+
+// TODO(dmaretskyi): Remove. This should be using the symbol type.
+export type WithMeta = { [ATTR_META]?: ObjectMeta };
+
+/**
+ * The raw object should not include the ECHO id, but may include metadata.
+ */
+export const RawObject = <S extends Schema.Schema.AnyNoContext>(
+  schema: S,
+): Schema.Schema<ExcludeId<Schema.Schema.Type<S>> & WithMeta, Schema.Schema.Encoded<S>> => {
+  return Schema.make(SchemaAST.omit(schema.ast, ['id']));
+};
+
+//
+// Utils
+//
+
+/**
+ * Utility to split meta property from raw object.
+ * @deprecated Bad API.
+ */
+export const splitMeta = <T>(object: T & WithMeta): { object: T; meta?: ObjectMeta } => {
+  const meta = object[ATTR_META];
+  delete object[ATTR_META];
+  return { meta, object };
+};
+
+// TODO(burdon): Move to `@dxos/util`.
+export const getValue = <T extends object>(obj: T, path: JsonPath): any => {
+  return getDeep(
+    obj,
+    splitJsonPath(path).map((p) => p.replace(/[[\]]/g, '')),
+  );
+};
+
+// TODO(burdon): Move to `@dxos/util`.
+export const setValue = <T extends object>(obj: T, path: JsonPath, value: any): T => {
+  return setDeep(
+    obj,
+    splitJsonPath(path).map((p) => p.replace(/[[\]]/g, '')),
+    value,
+  );
+};
+
+/**
+ * Returns a reference that will be used to point to a schema.
+ * @deprecated Use {@link getSchemaDXN} instead.
+ */
+export const getTypeReference = (schema: Schema.Schema.All | undefined): Reference | undefined => {
+  if (!schema) {
+    return undefined;
+  }
+
+  const schemaDXN = getSchemaDXN(schema);
+  if (!schemaDXN) {
+    return undefined;
+  }
+  return Reference.fromDXN(schemaDXN);
+};
+
+/**
+ * Returns a reference that will be used to point to a schema.
+ * @throws If it is not possible to reference this schema.
+ *
+ * @deprecated Use {@link getSchemaDXN} instead.
+ */
+export const requireTypeReference = (schema: Schema.Schema.AnyNoContext): Reference => {
+  const typeReference = getTypeReference(schema);
+  if (typeReference == null) {
+    // TODO(burdon): Catalog user-facing errors (this is too verbose).
+    throw new Error('Schema must be defined via TypedObject.');
+  }
+
+  return typeReference;
+};
+
+// TODO(burdon): Can we use `Schema.is`?
+/**
+ * Checks if the object is an instance of the schema.
+ * Only typename is compared, the schema version is ignored.
+ *
+ * The following cases are considered to mean that the object is an instance of the schema:
+ *  - Object was created with this exact schema.
+ *  - Object was created with a different version of this schema.
+ *  - Object was created with a different schema (maybe dynamic) that has the same typename.
+ */
+export const isInstanceOf = <Schema extends Schema.Schema.AnyNoContext>(
+  schema: Schema,
+  object: any,
+): object is Schema.Schema.Type<Schema> => {
+  if (object == null) {
+    return false;
+  }
+
+  const schemaDXN = getSchemaDXN(schema);
+  if (!schemaDXN) {
+    throw new Error('Schema must have an object annotation.');
+  }
+
+  const type = getType(object);
+  if (type && DXN.equals(type, schemaDXN)) {
+    return true;
+  }
+
+  const typename = getTypename(object);
+  if (!typename) {
+    return false;
+  }
+
+  const typeDXN = schemaDXN.asTypeDXN();
+  if (!typeDXN) {
+    return false;
+  }
+
+  return typeDXN.type === typename;
+};
+
+/**
+ * Object that has an associated typename.
+ * The typename is retrievable using {@link getTypename}.
+ * The object can be used with {@link isInstanceOf} to check if it is an instance of a schema.
+ */
+export type HasTypename = {};
+
+/**
+ * Canonical type for all ECHO objects.
+ */
+// TODO(burdon): Reconcile with Obj.Any, Relation.Any.
+export interface AnyEchoObject extends HasId, HasTypename {}

package/src/internal/types/util.ts

@@ -0,0 +1,9 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type BaseObject } from './types';
+
+export type ToMutable<T> = T extends BaseObject
+  ? { -readonly [K in keyof T]: T[K] extends readonly (infer U)[] ? U[] : T[K] }
+  : T;

package/src/query/index.ts

@@ -2,4 +2,5 @@
 // Copyright 2024 DXOS.org
 //
 
-export * from './dsl';
+export * from './query';
+export * as Tag from './tag';