@dxos/echo 0.8.4-main.548089c → 0.8.4-main.59c2e9b

package/src/internal/schema/persistent-schema.ts

@@ -0,0 +1,27 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+
+import { TypenameSchema, VersionSchema } from '../annotations';
+import { EchoObjectSchema } from '../entities';
+import { JsonSchemaType } from '../json-schema';
+
+/**
+ * Persistent representation of a schema.
+ */
+// TODO(burdon): Move.
+export const PersistentSchema = Schema.Struct({
+  name: Schema.optional(Schema.String),
+  typename: TypenameSchema,
+  version: VersionSchema,
+  jsonSchema: JsonSchemaType,
+}).pipe(
+  EchoObjectSchema({
+    typename: 'dxos.org/type/Schema',
+    version: '0.1.0',
+  }),
+);
+
+export interface PersistentSchema extends Schema.Schema.Type<typeof PersistentSchema> {}

package/src/internal/types/base.ts

@@ -0,0 +1,43 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+import * as SchemaAST from 'effect/SchemaAST';
+
+import { type ObjectId } from '@dxos/keys';
+
+import { type ATTR_META, type ObjectMeta } from './meta';
+
+/**
+ * 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(burdon): Make internal.
+// TODO(burdon): Prefer Record<string, unknown>.
+export type AnyProperties = Record<string, any>;
+
+/**
+ * Canonical type for all ECHO entities (objects and relations).
+ */
+// TODO(wittjosiah): Remove. Prefer higher level types (e.g. Entity.Unknown).
+export interface AnyEntity {
+  readonly id: ObjectId;
+}
+
+export type ExcludeId<T extends AnyProperties> = Omit<T, 'id'>;
+
+export type PropertyKey<T extends AnyProperties> = Extract<keyof ExcludeId<T>, string>;
+
+// TODO(dmaretskyi): Remove. This should be using the symbol type.
+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']));
+};

package/src/internal/types/entity.ts

@@ -0,0 +1,54 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+
+// NOTE: String literals are used instead of unique symbols for both KindId and SchemaKindId.
+//   Unique symbols cause TS4023 "cannot be named" errors when external packages
+//   try to export types that reference this key (e.g., `export const Graph = ...`).
+//   TypeScript cannot emit declaration files that reference unique symbols from
+//   external modules. Using a string literal allows the type to be inlined in
+//   declaration files, making the API portable across package boundaries.
+
+/**
+ * String key used to identify the kind of an entity instance (object or relation).
+ */
+export const KindId = '~@dxos/echo/Kind' as const;
+export type KindId = typeof KindId;
+
+/**
+ * String key used to identify the kind of a schema (object schema or relation schema).
+ * Parallels KindId which identifies instance kinds.
+ */
+export const SchemaKindId = '~@dxos/echo/SchemaKind' as const;
+export type SchemaKindId = typeof SchemaKindId;
+
+/**
+ * String key used to brand snapshot types.
+ * Snapshots have SnapshotKindId instead of KindId, making them
+ * distinguishable from reactive objects at the type level.
+ */
+export const SnapshotKindId = '~@dxos/echo/SnapshotKind' as const;
+export type SnapshotKindId = typeof SnapshotKindId;
+
+/**
+ * Kinds of entities stored in ECHO: objects and relations.
+ */
+export enum EntityKind {
+  Object = 'object',
+  Relation = 'relation',
+}
+
+export const EntityKindSchema = Schema.Enums(EntityKind);
+
+/**
+ * Typename for generic object references (Type.Obj / Type.Ref(Type.Obj)).
+ * Used when referencing any object without a specific schema.
+ */
+export const ANY_OBJECT_TYPENAME = 'dxos.org/schema/AnyObject';
+
+/**
+ * Version for generic object references.
+ */
+export const ANY_OBJECT_VERSION = '0.0.0';

package/src/internal/types/index.ts

@@ -2,5 +2,8 @@
 // Copyright 2024 DXOS.org
 //
 
-export * from './types';
-export type * from './util';
+export * from './base';
+export * from './entity';
+export * from './meta';
+export * from './typename';
+export * from './version';

package/src/internal/{object → types}/meta.ts

@@ -8,9 +8,17 @@ import { ForeignKey } from '@dxos/echo-protocol';
 import { invariant } from '@dxos/invariant';
 import { type Comparator, intersection } from '@dxos/util';
 
-import { type BaseObject } from '../types';
+import { type AnyProperties } from './base';
 
-import { MetaId } from './model';
+/**
+ * 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
@@ -33,29 +41,26 @@ export const ObjectMetaSchema = Schema.mutable(
 );
 export type ObjectMeta = Schema.Schema.Type<typeof ObjectMetaSchema>;
 
-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;
-
-/**
- * Get metadata from object.
- * Only callable on the object root.
- * @deprecated Use {@link getMeta}.
- */
-// TODO(dmaretskyi): Remove.
-export const getObjectMeta = (obj: any): ObjectMeta => {
-  return getMeta(obj);
-};
-
 /*
  * Get metadata from object.
  * Only callable on the object root.
+ *
+ * @internal (use Obj.getMeta or Relation.getMeta)
  */
-export const getMeta = (obj: BaseObject): ObjectMeta => {
+// 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<BaseObject> = (a: BaseObject, b: BaseObject) =>
+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,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,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() },
+        },
+      }),
+    },
+  }),
+};