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

package/src/internal/common/types/meta.ts

@@ -0,0 +1,79 @@
+//
+// 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 * as Entity from '../../../Entity';
+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: Entity.Meta = Symbol.for('@dxos/echo/Meta') as any;
+
+//
+// ObjectMeta
+//
+
+// TODO(dmaretskyi): Rename to ObjectMeta
+export const ObjectMetaSchema = Schema.Struct({
+  keys: 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.
+  // TODO(dmaretskyi): In automerge this should be a map of { [tag]: boolean } for uniqueness and conflict resolution.
+  tags: Schema.optional(Schema.Array(Schema.String)),
+
+  /**
+   * Fully-qualified registry key for the object (FQN format, e.g. `org.example.type.foo`).
+   * Identifies the canonical registry entry the object instance was created from.
+   */
+  key: Schema.optional(Schema.String),
+
+  /**
+   * Semantic version of the registry entry the object was created from.
+   * Must be a valid semver string (e.g. `1.2.3`).
+   */
+  version: Schema.optional(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/common/types/model-symbols.ts

@@ -0,0 +1,69 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+/**
+ * Internal symbol/string constants for the echo object model.
+ * Defined in common/ so proxy/ can use them without importing from Entity/.
+ * Entity/ re-exports these for external consumers.
+ */
+
+/**
+ * Property name for self DXN when object is serialized to JSON.
+ */
+export const ATTR_SELF_DXN = '@dxn';
+
+/**
+ * DXN to the object itself.
+ */
+export const SelfDXNId = Symbol.for('@dxos/echo/DXN');
+
+/**
+ * Property name for deleted when object is serialized to JSON.
+ */
+export const ATTR_DELETED = '@deleted';
+
+/**
+ * Deletion marker.
+ */
+export const ObjectDeletedId = Symbol.for('@dxos/echo/Deleted');
+
+/**
+ * Object version accessor symbol.
+ */
+export const ObjectVersionId: unique symbol = Symbol.for('@dxos/echo/Version');
+
+/**
+ * Object database accessor symbol.
+ */
+export const ObjectDatabaseId = Symbol.for('@dxos/echo/Database');
+
+/**
+ * Property name for relation source when object is serialized to JSON.
+ */
+export const ATTR_RELATION_SOURCE = '@relationSource';
+
+/**
+ * Used to access relation source ref on live ECHO objects.
+ */
+export const RelationSourceId: unique symbol = Symbol.for('@dxos/echo/RelationSource');
+
+/**
+ * Used to access relation source DXN on live ECHO objects.
+ */
+export const RelationSourceDXNId: unique symbol = Symbol.for('@dxos/echo/RelationSourceDXN');
+
+/**
+ * Property name for relation target when object is serialized to JSON.
+ */
+export const ATTR_RELATION_TARGET = '@relationTarget';
+
+/**
+ * Used to access relation target ref on live ECHO objects.
+ */
+export const RelationTargetId: unique symbol = Symbol.for('@dxos/echo/RelationTarget');
+
+/**
+ * Used to access relation target DXN on live ECHO objects.
+ */
+export const RelationTargetDXNId: unique symbol = Symbol.for('@dxos/echo/RelationTargetDXN');

package/src/internal/common/types/typename.ts

@@ -0,0 +1,55 @@
+//
+// 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');
+
+/**
+ * Property name for parent when object is serialized to JSON.
+ */
+export const ATTR_PARENT = '@parent';
+
+/**
+ * Reference to the object parent.
+ */
+export const ParentId = Symbol.for('@dxos/echo/Parent');
+
+/**
+ * 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/common/types/version.ts

@@ -0,0 +1,19 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+/**
+ * Version type identifier.
+ */
+export const VersionTypeId = '~@dxos/echo/VersionTypeId' as const;
+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/internal/index.ts

@@ -2,21 +2,16 @@
 // Copyright 2024 DXOS.org
 //
 
-export { JsonPath, splitJsonPath, JsonProp } from '@dxos/effect';
+// TODO(burdon): Import directly (not part of ECHO API).
+export { JsonPath, JsonProp, getValue, splitJsonPath } from '@dxos/effect';
 
-// TODO(dmaretskyi): Remove.
-export { ObjectId } from '@dxos/keys';
-export { ForeignKey } from '@dxos/echo-protocol';
-
-export * from './ast';
-export * from './formats';
-export * from './json';
-export * from './json-schema';
-export * from './object';
-export * from './types';
-export { defineHiddenProperty } from '@dxos/live-object';
-export * from './ref';
-export * from './projection';
-export * from './schema';
-// TODO(dmaretskyi): Remove
-export { live } from './proxy/reactive-object';
+export * from './Annotation';
+export * from './common';
+export * from './Entity';
+export * from './Format';
+export * from './JsonSchema';
+// TODO(wittjosiah): Required to ensure types are portable (need to export all types required for downstream inference).
+export * from './Obj';
+export * from './Query';
+export * from './Ref';
+export * from './Type';

package/src/testing/api.test.ts

@@ -0,0 +1,125 @@
+//
+// 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('com.example.type.person');
+    expect(Type.getVersion(schema)).to.eq('0.1.0');
+    expect(Type.getMeta(schema)).to.deep.eq({
+      kind: Entity.Kind.Object,
+      typename: 'com.example.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.OfShape<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.OfShape<TestSchema.Person> = person;
+      }
+    });
+  });
+});

package/src/testing/index.ts

@@ -2,6 +2,6 @@
 // Copyright 2025 DXOS.org
 //
 
-export { prepareAstForCompare, Testing as TestingDeprecated, updateCounter } from '../internal/testing';
-export * from './types';
-export * from './echo-schema';
+export * from './test-data';
+export * from './test-schema';
+export * from './util';

package/src/testing/test-data.ts

@@ -0,0 +1,189 @@
+//
+// 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';
+
+// Lazy init: Cloudflare workers disallow non-determinism at module scope (e.g. random keys).
+let cachedSpaceKeyHex: string | undefined;
+const getSpaceKeyHex = (): string => {
+  if (cachedSpaceKeyHex === undefined) {
+    cachedSpaceKeyHex = PublicKey.random().toHex();
+  }
+  return cachedSpaceKeyHex;
+};
+
+let cachedPeopleAlice: DatabaseDirectory | undefined;
+let cachedPeopleBob: DatabaseDirectory | undefined;
+let cachedOrgsDxos: DatabaseDirectory | undefined;
+let cachedOrgsCyberdyne: DatabaseDirectory | undefined;
+let cachedWorksFredCyberdyne: DatabaseDirectory | undefined;
+let cachedWorksAliceAperture: DatabaseDirectory | undefined;
+let cachedTasksTask1: DatabaseDirectory | undefined;
+let cachedTasksTask2: DatabaseDirectory | undefined;
+
+// TODO(burdon): Use Obj.make.
+
+export const PEOPLE = {
+  get alice(): DatabaseDirectory {
+    if (cachedPeopleAlice === undefined) {
+      cachedPeopleAlice = DatabaseDirectory.make({
+        spaceKey: getSpaceKeyHex(),
+        objects: {
+          [ObjectId.random()]: ObjectStructure.makeObject({
+            type: Type.getDXN(TestSchema.Person)!.toString(),
+            data: {
+              name: 'Alice',
+            },
+          }),
+        },
+      });
+    }
+    return cachedPeopleAlice;
+  },
+
+  get bob(): DatabaseDirectory {
+    if (cachedPeopleBob === undefined) {
+      cachedPeopleBob = DatabaseDirectory.make({
+        spaceKey: getSpaceKeyHex(),
+        objects: {
+          [ObjectId.random()]: ObjectStructure.makeObject({
+            type: Type.getDXN(TestSchema.Person)!.toString(),
+            data: {
+              name: 'Bob',
+            },
+          }),
+        },
+      });
+    }
+    return cachedPeopleBob;
+  },
+};
+
+export const ORGS = {
+  get dxos(): DatabaseDirectory {
+    if (cachedOrgsDxos === undefined) {
+      cachedOrgsDxos = DatabaseDirectory.make({
+        spaceKey: getSpaceKeyHex(),
+        objects: {
+          [ObjectId.random()]: ObjectStructure.makeObject({
+            type: Type.getDXN(TestSchema.Organization)!.toString(),
+            data: {
+              name: 'DXOS',
+              founded: '2023',
+            },
+          }),
+        },
+      });
+    }
+    return cachedOrgsDxos;
+  },
+
+  get cyberdyne(): DatabaseDirectory {
+    if (cachedOrgsCyberdyne === undefined) {
+      cachedOrgsCyberdyne = DatabaseDirectory.make({
+        spaceKey: getSpaceKeyHex(),
+        objects: {
+          [ObjectId.random()]: ObjectStructure.makeObject({
+            type: Type.getDXN(TestSchema.Organization)!.toString(),
+            data: {
+              name: 'Cyberdyne Systems',
+              founded: '1984',
+            },
+          }),
+        },
+      });
+    }
+    return cachedOrgsCyberdyne;
+  },
+};
+
+export const WORKS_FOR = {
+  get fredWorksForCyberdyne(): DatabaseDirectory {
+    if (cachedWorksFredCyberdyne === undefined) {
+      cachedWorksFredCyberdyne = DatabaseDirectory.make({
+        spaceKey: getSpaceKeyHex(),
+        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',
+            },
+          }),
+        },
+      });
+    }
+    return cachedWorksFredCyberdyne;
+  },
+
+  get aliceWorksForAperture(): DatabaseDirectory {
+    if (cachedWorksAliceAperture === undefined) {
+      cachedWorksAliceAperture = DatabaseDirectory.make({
+        spaceKey: getSpaceKeyHex(),
+        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',
+            },
+          }),
+        },
+      });
+    }
+    return cachedWorksAliceAperture;
+  },
+};
+
+export const TASKS = {
+  get task1(): DatabaseDirectory {
+    if (cachedTasksTask1 === undefined) {
+      cachedTasksTask1 = DatabaseDirectory.make({
+        spaceKey: getSpaceKeyHex(),
+        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() },
+            },
+          }),
+        },
+      });
+    }
+    return cachedTasksTask1;
+  },
+
+  get task2(): DatabaseDirectory {
+    if (cachedTasksTask2 === undefined) {
+      cachedTasksTask2 = DatabaseDirectory.make({
+        spaceKey: getSpaceKeyHex(),
+        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() },
+            },
+          }),
+        },
+      });
+    }
+    return cachedTasksTask2;
+  },
+};