@dxos/echo 0.8.4-main.84f28bd → 0.8.4-main.937b3ca

package/src/internal/types/meta.ts

@@ -0,0 +1,66 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+
+import { ForeignKey } from '@dxos/echo-protocol';
+import { invariant } from '@dxos/invariant';
+import { type Comparator, intersection } from '@dxos/util';
+
+import { type AnyProperties } from './base';
+
+/**
+ * Property name for meta when object is serialized to JSON.
+ */
+export const ATTR_META = '@meta';
+
+/**
+ * Metadata section.
+ */
+export const MetaId = Symbol.for('@dxos/echo/Meta');
+
+//
+// ObjectMeta
+//
+
+// TODO(dmaretskyi): Rename to ObjectMeta
+export const ObjectMetaSchema = Schema.mutable(
+  Schema.Struct({
+    keys: Schema.mutable(Schema.Array(ForeignKey)),
+
+    /**
+     * A set of tags.
+     * Tags are arbitrary application-defined strings.
+     * ECHO makes no assumptions about the tag structure.
+     */
+    // TODO(dmaretskyi): Has to be optional for compatibility with old data.
+    // Defaulting to an empty array is possible but requires a bit more work.
+    tags: Schema.optional(Schema.mutable(Schema.Array(Schema.String))),
+  }),
+);
+export type ObjectMeta = Schema.Schema.Type<typeof ObjectMetaSchema>;
+
+/*
+ * Get metadata from object.
+ * Only callable on the object root.
+ *
+ * @internal (use Obj.getMeta or Relation.getMeta)
+ */
+// TODO(burdon): Refine type to BaseObj.
+export const getMeta = (obj: AnyProperties): ObjectMeta => {
+  const metadata = (obj as any)[MetaId];
+  invariant(metadata, 'ObjectMeta not found.');
+  return metadata;
+};
+
+//
+// Foreign keys
+//
+
+export const foreignKey = (source: string, id: string): ForeignKey => ({ source, id });
+export const foreignKeyEquals = (a: ForeignKey, b: ForeignKey) => a.source === b.source && a.id === b.id;
+
+// TODO(dmaretskyi): Move to echo-schema.
+export const compareForeignKeys: Comparator<AnyProperties> = (a: AnyProperties, b: AnyProperties) =>
+  intersection(getMeta(a).keys, getMeta(b).keys, foreignKeyEquals).length > 0;

package/src/internal/types/typename.ts

@@ -0,0 +1,45 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import type * as Schema from 'effect/Schema';
+
+/**
+ * Property name for typename when object is serialized to JSON.
+ */
+export const ATTR_TYPE = '@type';
+
+/**
+ * DXN to the object type.
+ */
+export const TypeId = Symbol.for('@dxos/echo/Type');
+
+/**
+ * Reference to the object schema.
+ */
+export const SchemaId = Symbol.for('@dxos/echo/Schema');
+
+/**
+ * Returns the schema for the given object if one is defined.
+ *
+ * @internal (Use Obj.getSchema)
+ */
+// TODO(burdon): Narrow type.
+// TODO(dmaretskyi): For echo objects, this always returns the root schema.
+export const getSchema = (obj: unknown | undefined): Schema.Schema.AnyNoContext | undefined => {
+  if (obj) {
+    return (obj as any)[SchemaId];
+  }
+};
+
+/**
+ * @internal
+ */
+export const setSchema = (obj: any, schema: Schema.Schema.AnyNoContext): void => {
+  Object.defineProperty(obj, SchemaId, {
+    value: schema,
+    writable: false,
+    enumerable: false,
+    configurable: false,
+  });
+};

package/src/internal/types/version.ts

@@ -0,0 +1,20 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+/**
+ * Version type symbol.
+ */
+export const VersionTypeId: unique symbol = Symbol.for('@dxos/echo/VersionTypeId');
+
+export type VersionTypeId = typeof VersionTypeId;
+
+/**
+ * Represents the object version.
+ * May be backed by Automerge.
+ * Objects with no history are not versioned.
+ */
+export interface Version {
+  [VersionTypeId]: {};
+  automergeHeads?: string[];
+}

package/src/testing/api.test.ts

@@ -0,0 +1,126 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+import { describe, test } from 'vitest';
+
+import { raise } from '@dxos/debug';
+
+import { Entity, Obj, Ref, Relation, Type } from '../index';
+
+import { TestSchema } from './test-schema';
+
+describe('Experimental API review', () => {
+  test('type checks', ({ expect }) => {
+    const contact = Obj.make(TestSchema.Person, { name: 'Test' });
+    const schema = Obj.getSchema(contact) ?? raise(new Error('No schema found'));
+
+    expect(Type.getDXN(schema)?.typename).to.eq(TestSchema.Person.typename);
+    expect(Type.getTypename(schema)).to.eq('example.com/type/Person');
+    expect(Type.getVersion(schema)).to.eq('0.1.0');
+    expect(Type.getMeta(schema)).to.deep.eq({
+      kind: Entity.Kind.Object,
+      typename: 'example.com/type/Person',
+      version: '0.1.0',
+    });
+  });
+
+  test('instance checks', ({ expect }) => {
+    const organization = Obj.make(TestSchema.Organization, { name: 'DXOS' });
+    const contact = Obj.make(TestSchema.Person, {
+      name: 'Test',
+      employer: Ref.make(organization),
+    });
+
+    expect(Schema.is(TestSchema.Person)(contact)).to.be.true;
+    expect(Obj.instanceOf(TestSchema.Person, contact)).to.be.true;
+    expect(Obj.instanceOf(TestSchema.Organization, organization)).to.be.true;
+
+    const isPerson = Obj.instanceOf(TestSchema.Person);
+    const x: any = {};
+    if (isPerson(x)) {
+      x.name;
+    }
+  });
+
+  test('default props', ({ expect }) => {
+    const message = Obj.make(TestSchema.Message, TestSchema.MessageStruct.make({}));
+    expect(message.timestamp).to.exist;
+  });
+
+  test('Obj.isObject', ({ expect }) => {
+    const guy = Obj.make(TestSchema.Person, { name: 'Test' });
+    expect(Obj.isObject(guy)).to.be.true;
+    expect(Obj.isObject(null)).to.be.false;
+    expect(Obj.isObject(undefined)).to.be.false;
+    expect(Obj.isObject(1)).to.be.false;
+    expect(Obj.isObject('string')).to.be.false;
+  });
+
+  test('create relation', ({ expect }) => {
+    const person = Obj.make(TestSchema.Person, { name: 'Test' });
+    const organization = Obj.make(TestSchema.Organization, { name: 'DXOS' });
+    const worksFor = Relation.make(TestSchema.EmployedBy, {
+      [Relation.Source]: person,
+      [Relation.Target]: organization,
+      role: 'CEO',
+    });
+    expect(Relation.getSource(worksFor)).to.eq(person);
+    expect(Relation.getTarget(worksFor)).to.eq(organization);
+  });
+
+  test('version', ({ expect }) => {
+    const person = Obj.make(TestSchema.Person, { name: 'Test' });
+    const version = Obj.version(person);
+    expect(Obj.isVersion(version)).to.be.true;
+    expect(Obj.versionValid(version)).to.be.false;
+  });
+
+  // TODO(burdon): Implement test.
+  test.skip('type narrowing', () => {
+    const any: Entity.Unknown = null as any;
+
+    {
+      if (Obj.isObject(any)) {
+        any;
+      } else {
+        any;
+      }
+    }
+
+    {
+      if (Relation.isRelation(any)) {
+        any;
+      } else {
+        any;
+      }
+    }
+  });
+
+  /**
+   * Test that Obj.make return types are clean and don't expose internal markers like OfKind.
+   * The return type of Obj.make(Schema, props) should be assignable to Obj.Obj<InstanceType>.
+   */
+  describe('Obj.make return type', () => {
+    test('Obj.make with custom schema should be assignable to Obj.Obj<Person>', ({ expect }) => {
+      {
+        const expando = Obj.make(TestSchema.Expando, { content: 'Test' });
+        expect(Obj.isObject(expando)).to.be.true;
+        expect(expando.content).to.eq('Test');
+
+        // This should work: assign to Obj.Obj of the schema's instance type
+        const _typed: Obj.Obj<TestSchema.Expando> = expando;
+      }
+
+      {
+        const person = Obj.make(TestSchema.Person, { name: 'Test' });
+        expect(Obj.isObject(person)).to.be.true;
+        expect(person.name).to.eq('Test');
+
+        // This should work: assign to Obj.Obj of the schema's instance type
+        const _typed: Obj.Obj<TestSchema.Person> = person;
+      }
+    });
+  });
+});

package/src/testing/index.ts

@@ -2,4 +2,6 @@
 // Copyright 2025 DXOS.org
 //
 
-export * from './types';
+export * from './test-data';
+export * from './test-schema';
+export * from './util';

package/src/testing/test-data.ts

@@ -0,0 +1,130 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { DatabaseDirectory, ObjectStructure } from '@dxos/echo-protocol';
+import { DXN, ObjectId, PublicKey } from '@dxos/keys';
+
+import { Type } from '../index';
+
+import { TestSchema } from './test-schema';
+
+const spaceKey = PublicKey.random();
+
+// TODO(burdon): Use Obj.make.
+
+export const PEOPLE = {
+  alice: DatabaseDirectory.make({
+    spaceKey: spaceKey.toHex(),
+    objects: {
+      [ObjectId.random()]: ObjectStructure.makeObject({
+        type: Type.getDXN(TestSchema.Person)!.toString(),
+        data: {
+          name: 'Alice',
+        },
+      }),
+    },
+  }),
+  bob: DatabaseDirectory.make({
+    spaceKey: spaceKey.toHex(),
+    objects: {
+      [ObjectId.random()]: ObjectStructure.makeObject({
+        type: Type.getDXN(TestSchema.Person)!.toString(),
+        data: {
+          name: 'Bob',
+        },
+      }),
+    },
+  }),
+};
+
+export const ORGS = {
+  dxos: DatabaseDirectory.make({
+    spaceKey: spaceKey.toHex(),
+    objects: {
+      [ObjectId.random()]: ObjectStructure.makeObject({
+        type: Type.getDXN(TestSchema.Organization)!.toString(),
+        data: {
+          name: 'DXOS',
+          founded: '2023',
+        },
+      }),
+    },
+  }),
+  cyberdyne: DatabaseDirectory.make({
+    spaceKey: spaceKey.toHex(),
+    objects: {
+      [ObjectId.random()]: ObjectStructure.makeObject({
+        type: Type.getDXN(TestSchema.Organization)!.toString(),
+        data: {
+          name: 'Cyberdyne Systems',
+          founded: '1984',
+        },
+      }),
+    },
+  }),
+};
+
+export const WORKS_FOR = {
+  fredWorksForCyberdyne: DatabaseDirectory.make({
+    spaceKey: spaceKey.toHex(),
+    objects: {
+      [ObjectId.random()]: ObjectStructure.makeRelation({
+        type: Type.getDXN(TestSchema.EmployedBy)!.toString(),
+        source: { '/': DXN.fromLocalObjectId(Object.keys(PEOPLE.bob.objects!)[0]).toString() },
+        target: { '/': DXN.fromLocalObjectId(Object.keys(ORGS.cyberdyne.objects!)[0]).toString() },
+        data: {
+          since: '2020',
+          position: 'Engineer',
+        },
+      }),
+    },
+  }),
+  aliceWorksForAperture: DatabaseDirectory.make({
+    spaceKey: spaceKey.toHex(),
+    objects: {
+      [ObjectId.random()]: ObjectStructure.makeRelation({
+        type: Type.getDXN(TestSchema.EmployedBy)!.toString(),
+        source: { '/': DXN.fromLocalObjectId(Object.keys(PEOPLE.alice.objects!)[0]).toString() },
+        target: { '/': DXN.fromLocalObjectId(Object.keys(ORGS.dxos.objects!)[0]).toString() },
+        data: {
+          since: '2018',
+          position: 'Research Scientist',
+        },
+      }),
+    },
+  }),
+};
+
+export const TASKS = {
+  task1: DatabaseDirectory.make({
+    spaceKey: spaceKey.toHex(),
+    objects: {
+      [ObjectId.random()]: ObjectStructure.makeObject({
+        type: Type.getDXN(TestSchema.Task)!.toString(),
+        data: {
+          title: 'Complete project documentation',
+          description: 'Write comprehensive documentation for the new system',
+          status: 'in-progress',
+          dueDate: '2023-12-31',
+          assignee: { '/': DXN.fromLocalObjectId(Object.keys(PEOPLE.bob.objects!)[0]).toString() },
+        },
+      }),
+    },
+  }),
+  task2: DatabaseDirectory.make({
+    spaceKey: spaceKey.toHex(),
+    objects: {
+      [ObjectId.random()]: ObjectStructure.makeObject({
+        type: Type.getDXN(TestSchema.Task)!.toString(),
+        data: {
+          title: 'Run experiments',
+          description: 'Conduct series of experiments on the portal device',
+          status: 'pending',
+          dueDate: '2023-11-15',
+          assignee: { '/': DXN.fromLocalObjectId(Object.keys(PEOPLE.alice.objects!)[0]).toString() },
+        },
+      }),
+    },
+  }),
+};

package/src/testing/test-schema.ts

@@ -0,0 +1,238 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+
+import * as Type from '../Type';
+
+export namespace TestSchema {
+  //
+  // Expando
+  //
+
+  /**
+   * Expando object is an object with an arbitrary set of properties.
+   * This is the test variant with example.com namespace.
+   */
+  export const Expando = Schema.Struct({}, { key: Schema.String, value: Schema.Any }).pipe(
+    Type.object({
+      typename: 'example.com/type/Expando',
+      version: '0.1.0',
+    }),
+  );
+
+  export interface Expando extends Schema.Schema.Type<typeof Expando> {}
+
+  //
+  // Example
+  //
+
+  const Nested = Schema.Struct({
+    field: Schema.String,
+  });
+
+  export class TestClass {
+    field = 'value';
+    toJSON() {
+      return { field: this.field };
+    }
+  }
+
+  /** @deprecated Use another test schema or create a specific local test schema. */
+  export const ExampleSchema = Schema.Struct({
+    string: Schema.String,
+    number: Schema.Number,
+    boolean: Schema.Boolean,
+    null: Schema.Null,
+    undefined: Schema.Undefined,
+    stringArray: Schema.Array(Schema.String),
+    twoDimNumberArray: Schema.Array(Schema.Array(Schema.Number)),
+    nested: Nested,
+    nestedArray: Schema.Array(Nested),
+    nestedNullableArray: Schema.Array(Schema.Union(Nested, Schema.Null)),
+    reference: Schema.suspend((): Type.Ref<Example> => Type.Ref(Example)),
+    referenceArray: Schema.Array(Schema.suspend((): Type.Ref<Example> => Type.Ref(Example))),
+    classInstance: Schema.instanceOf(TestClass),
+    other: Schema.Any,
+  }).pipe(Schema.partial);
+
+  /** @deprecated Use another test schema or create a specific local test schema. */
+  export interface ExampleSchema extends Schema.Schema.Type<typeof ExampleSchema> {}
+
+  /** @deprecated Use another test schema or create a specific local test schema. */
+  export const Example = ExampleSchema.pipe(
+    Type.object({
+      typename: 'example.com/type/Example',
+      version: '0.1.0',
+    }),
+  );
+
+  /** @deprecated Use another test schema or create a specific local test schema. */
+  export interface Example extends Schema.Schema.Type<typeof Example> {}
+
+  //
+  // Message
+  //
+
+  // TODO(burdon): Support defaults directly on Type: `make` is erased by `pipe(Type.Obj)`.
+  export const MessageStruct = Schema.Struct({
+    // TODO(burdon): Support S.Date; Custom Timestamp (with defaults).
+    // TODO(burdon): Support defaults (update create and create).
+    timestamp: Schema.String.pipe(
+      Schema.propertySignature,
+      Schema.withConstructorDefault(() => new Date().toISOString()),
+    ),
+  });
+
+  export const Message = MessageStruct.pipe(
+    Type.object({
+      typename: 'example.com/type/Message',
+      version: '0.1.0',
+    }),
+  );
+
+  export interface Message extends Schema.Schema.Type<typeof Message> {}
+
+  //
+  // Organization
+  //
+
+  export const Organization = Schema.Struct({
+    name: Schema.String,
+    properties: Schema.optional(
+      Schema.Record({
+        key: Schema.String,
+        value: Schema.String,
+      }),
+    ),
+  }).pipe(
+    Type.object({
+      typename: 'example.com/type/Organization',
+      version: '0.1.0',
+    }),
+  );
+
+  export interface Organization extends Schema.Schema.Type<typeof Organization> {}
+
+  //
+  // Person
+  //
+
+  export const Person = Schema.Struct({
+    name: Schema.String,
+    username: Schema.String,
+    email: Schema.String,
+    age: Schema.Number.pipe(Schema.optional),
+    tasks: Schema.Array(Schema.suspend((): Type.Ref<Task> => Type.Ref(Task))),
+    employer: Schema.optional(Type.Ref(Organization)),
+    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),
+      }),
+    }),
+    fields: Schema.Struct({
+      label: Schema.String,
+      value: Schema.String,
+    }).pipe(Schema.Array, Schema.optional),
+  }).pipe(
+    Schema.partial,
+    Type.object({
+      typename: 'example.com/type/Person',
+      version: '0.1.0',
+    }),
+  );
+
+  export interface Person extends Schema.Schema.Type<typeof Person> {}
+
+  //
+  // Task
+  //
+
+  export const Task = Schema.Struct({
+    title: Schema.optional(Schema.String),
+    deadline: Schema.optional(Schema.String),
+    completed: Schema.optional(Schema.Boolean),
+    assignee: Schema.optional(Type.Ref(Person)),
+    previous: Schema.optional(Schema.suspend((): Type.Ref<Task> => Type.Ref(Task))),
+    subTasks: Schema.optional(Schema.Array(Schema.suspend((): Type.Ref<Task> => Type.Ref(Task)))),
+    description: Schema.optional(Schema.String),
+  }).pipe(
+    Schema.partial,
+    Type.object({
+      typename: 'example.com/type/Task',
+      version: '0.1.0',
+    }),
+  );
+
+  export interface Task extends Schema.Schema.Type<typeof Task> {}
+
+  //
+  // HasManager
+  //
+
+  export const HasManager = Schema.Struct({}).pipe(
+    Type.relation({
+      typename: 'example.com/type/HasManager',
+      version: '0.1.0',
+      source: Person,
+      target: Person,
+    }),
+  );
+
+  export interface HasManager extends Schema.Schema.Type<typeof HasManager> {}
+
+  //
+  // EmployedBy
+  //
+
+  export const EmployedBy = Schema.Struct({
+    role: Schema.String,
+    since: Schema.optional(Schema.String),
+  }).pipe(
+    Type.relation({
+      typename: 'example.com/type/EmployedBy',
+      version: '0.1.0',
+      source: Person,
+      target: Organization,
+    }),
+  );
+
+  export interface EmployedBy extends Schema.Schema.Type<typeof EmployedBy> {}
+
+  //
+  // RecordType
+  //
+
+  export enum RecordType {
+    UNDEFINED = 0,
+    PERSONAL = 1,
+    WORK = 2,
+  }
+
+  export const Container = Schema.Struct({
+    objects: Schema.Array(Type.Ref(Type.Obj)),
+    records: Schema.Array(
+      Schema.partial(
+        Schema.Struct({
+          title: Schema.String,
+          description: Schema.String,
+          contacts: Schema.Array(Type.Ref(Person)),
+          type: Schema.Enums(RecordType),
+        }),
+      ),
+    ),
+  }).pipe(
+    Schema.partial,
+    Type.object({
+      typename: 'example.com/type/Container',
+      version: '0.1.0',
+    }),
+  );
+
+  export interface Container extends Schema.Schema.Type<typeof Container> {}
+}