@dxos/echo 0.8.4-main.70d3990 → 0.8.4-main.74a063c4e0

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

@@ -8,7 +8,8 @@ import { ForeignKey } from '@dxos/echo-protocol';
 import { invariant } from '@dxos/invariant';
 import { type Comparator, intersection } from '@dxos/util';
 
-import { type AnyProperties, type WithMeta } from './base';
+import type * as Entity from '../../../Entity';
+import { type AnyProperties } from './base';
 
 /**
  * Property name for meta when object is serialized to JSON.
@@ -18,27 +19,27 @@ export const ATTR_META = '@meta';
 /**
  * Metadata section.
  */
-export const MetaId = Symbol.for('@dxos/echo/Meta');
+export const MetaId: Entity.Meta = Symbol.for('@dxos/echo/Meta') as any;
 
 //
 // ObjectMeta
 //
 
 // TODO(dmaretskyi): Rename to ObjectMeta
-export const ObjectMetaSchema = Schema.mutable(
-  Schema.Struct({
-    keys: Schema.mutable(Schema.Array(ForeignKey)),
+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)),
+});
 
-    /**
-     * 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>;
 
 /*
@@ -54,16 +55,6 @@ export const getMeta = (obj: AnyProperties): ObjectMeta => {
   return metadata;
 };
 
-/**
- * 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 };
-};
-
 //
 // Foreign keys
 //

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/{types → common/types}/typename.ts

@@ -19,6 +19,16 @@ export const TypeId = Symbol.for('@dxos/echo/Type');
  */
 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.
  *

package/src/internal/{types → common/types}/version.ts

@@ -3,10 +3,9 @@
 //
 
 /**
- * Version type symbol.
+ * Version type identifier.
  */
-export const VersionTypeId: unique symbol = Symbol.for('@dxos/echo/VersionTypeId');
-
+export const VersionTypeId = '~@dxos/echo/VersionTypeId' as const;
 export type VersionTypeId = typeof VersionTypeId;
 
 /**

package/src/internal/index.ts

@@ -3,36 +3,15 @@
 //
 
 // TODO(burdon): Import directly (not part of ECHO API).
-export { JsonPath, JsonProp, getValue, setValue, splitJsonPath } from '@dxos/effect';
-
-export * from './annotations';
-export * from './entities';
-export * from './formats';
-export * from './json-schema';
-export * from './ref';
-export * from './types';
+export { JsonPath, JsonProp, getValue, splitJsonPath } from '@dxos/effect';
 
+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 './object';
-export * from './proxy';
-export * from './schema';
-
-// export {
-//   createObject,
-//   createQueueDXN,
-//   isDeleted,
-//   objectFromJSON,
-//   objectToJSON,
-//   setRefResolverOnData,
-//   SchemaValidator,
-//   TypedObject,
-// } from './object';
-// export { makeObject } from './proxy';
-// export {
-//   type BaseSchema,
-//   EchoSchema,
-//   ImmutableSchema,
-//   RuntimeSchemaRegistry,
-//   PersistentSchema,
-//   isMutable,
-// } from './schema';
+export * from './Obj';
+export * from './Query';
+export * from './Ref';
+export * from './Type';

package/src/testing/api.test.ts

@@ -8,20 +8,19 @@ 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 type: Schema.Schema<TestSchema.Person> = Obj.getSchema(contact) ?? raise(new Error('No schema found'));
+    const schema = Obj.getSchema(contact) ?? raise(new Error('No schema found'));
 
-    expect(Type.getDXN(type)?.typename).to.eq(TestSchema.Person.typename);
-    expect(Type.getTypename(type)).to.eq('example.com/type/Person');
-    expect(Type.getVersion(type)).to.eq('0.1.0');
-    expect(Type.getMeta(type)).to.deep.eq({
+    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: 'example.com/type/Person',
+      typename: 'com.example.type.person',
       version: '0.1.0',
     });
   });
@@ -97,4 +96,30 @@ describe('Experimental API review', () => {
       }
     }
   });
+
+  /**
+   * 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/test-data.ts

@@ -6,7 +6,6 @@ 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();

package/src/testing/test-schema.ts

@@ -5,16 +5,34 @@
 import * as Schema from 'effect/Schema';
 
 import * as Obj from '../Obj';
+import * as Ref from '../Ref';
 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: 'com.example.type.expando',
+      version: '0.1.0',
+    }),
+  );
+
+  export interface Expando extends Schema.Schema.Type<typeof Expando> {}
+
   //
   // Example
   //
 
   const Nested = Schema.Struct({
     field: Schema.String,
-  }).pipe(Schema.mutable);
+  });
 
   export class TestClass {
     field = 'value';
@@ -30,24 +48,24 @@ export namespace TestSchema {
     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)))),
-    nested: Schema.mutable(Nested),
-    nestedArray: Schema.mutable(Schema.Array(Nested)),
-    nestedNullableArray: Schema.mutable(Schema.Array(Schema.Union(Nested, Schema.Null))),
-    reference: Schema.suspend((): Type.Ref<Example> => Type.Ref(Example)),
-    referenceArray: Schema.mutable(Schema.Array(Schema.suspend((): Type.Ref<Example> => Type.Ref(Example)))),
+    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((): Ref.RefSchema<Example> => Ref.Ref(Example)),
+    referenceArray: Schema.Array(Schema.suspend((): Ref.RefSchema<Example> => Ref.Ref(Example))),
     classInstance: Schema.instanceOf(TestClass),
     other: Schema.Any,
-  }).pipe(Schema.partial, Schema.mutable);
+  }).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.Obj({
-      typename: 'example.com/type/Example',
+    Type.object({
+      typename: 'com.example.type.example',
       version: '0.1.0',
     }),
   );
@@ -70,8 +88,8 @@ export namespace TestSchema {
   });
 
   export const Message = MessageStruct.pipe(
-    Type.Obj({
-      typename: 'example.com/type/Message',
+    Type.object({
+      typename: 'com.example.type.message',
       version: '0.1.0',
     }),
   );
@@ -84,9 +102,15 @@ export namespace TestSchema {
 
   export const Organization = Schema.Struct({
     name: Schema.String,
+    properties: Schema.optional(
+      Schema.Record({
+        key: Schema.String,
+        value: Schema.String,
+      }),
+    ),
   }).pipe(
-    Type.Obj({
-      typename: 'example.com/type/Organization',
+    Type.object({
+      typename: 'com.example.type.organization',
       version: '0.1.0',
     }),
   );
@@ -101,8 +125,9 @@ export namespace TestSchema {
     name: Schema.String,
     username: Schema.String,
     email: Schema.String,
-    tasks: Schema.mutable(Schema.Array(Schema.suspend((): Type.Ref<Task> => Type.Ref(Task)))),
-    employer: Schema.optional(Type.Ref(Organization)),
+    age: Schema.Number.pipe(Schema.optional),
+    tasks: Schema.Array(Schema.suspend((): Ref.RefSchema<Task> => Ref.Ref(Task))),
+    employer: Schema.optional(Ref.Ref(Organization)),
     address: Schema.Struct({
       city: Schema.optional(Schema.String),
       state: Schema.optional(Schema.String),
@@ -112,10 +137,14 @@ export namespace TestSchema {
         lng: Schema.optional(Schema.Number),
       }),
     }),
+    fields: Schema.Struct({
+      label: Schema.String,
+      value: Schema.String,
+    }).pipe(Schema.Array, Schema.optional),
   }).pipe(
     Schema.partial,
-    Type.Obj({
-      typename: 'example.com/type/Person',
+    Type.object({
+      typename: 'com.example.type.person',
       version: '0.1.0',
     }),
   );
@@ -130,14 +159,14 @@ export namespace TestSchema {
     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.mutable(Schema.Array(Schema.suspend((): Type.Ref<Task> => Type.Ref(Task))))),
+    assignee: Schema.optional(Ref.Ref(Person)),
+    previous: Schema.optional(Schema.suspend((): Ref.RefSchema<Task> => Ref.Ref(Task))),
+    subTasks: Schema.optional(Schema.Array(Schema.suspend((): Ref.RefSchema<Task> => Ref.Ref(Task)))),
     description: Schema.optional(Schema.String),
   }).pipe(
     Schema.partial,
-    Type.Obj({
-      typename: 'example.com/type/Task',
+    Type.object({
+      typename: 'com.example.type.task',
       version: '0.1.0',
     }),
   );
@@ -149,8 +178,8 @@ export namespace TestSchema {
   //
 
   export const HasManager = Schema.Struct({}).pipe(
-    Type.Relation({
-      typename: 'example.com/type/HasManager',
+    Type.relation({
+      typename: 'com.example.type.has-manager',
       version: '0.1.0',
       source: Person,
       target: Person,
@@ -167,8 +196,8 @@ export namespace TestSchema {
     role: Schema.String,
     since: Schema.optional(Schema.String),
   }).pipe(
-    Type.Relation({
-      typename: 'example.com/type/EmployedBy',
+    Type.relation({
+      typename: 'com.example.type.employed-by',
       version: '0.1.0',
       source: Person,
       target: Organization,
@@ -188,23 +217,21 @@ export namespace TestSchema {
   }
 
   export const Container = Schema.Struct({
-    objects: Schema.mutable(Schema.Array(Type.Ref(Obj.Any))),
-    records: Schema.mutable(
-      Schema.Array(
-        Schema.partial(
-          Schema.Struct({
-            title: Schema.String,
-            description: Schema.String,
-            contacts: Schema.mutable(Schema.Array(Type.Ref(Person))),
-            type: Schema.Enums(RecordType),
-          }),
-        ),
+    objects: Schema.Array(Ref.Ref(Obj.Unknown)),
+    records: Schema.Array(
+      Schema.partial(
+        Schema.Struct({
+          title: Schema.String,
+          description: Schema.String,
+          contacts: Schema.Array(Ref.Ref(Person)),
+          type: Schema.Enums(RecordType),
+        }),
       ),
     ),
   }).pipe(
     Schema.partial,
-    Type.Obj({
-      typename: 'example.com/type/Container',
+    Type.object({
+      typename: 'com.example.type.container',
       version: '0.1.0',
     }),
   );

package/src/testing/util.ts

@@ -2,17 +2,13 @@
 // Copyright 2024 DXOS.org
 //
 
-import { effect } from '@preact/signals-core';
 import type * as Schema from 'effect/Schema';
 import type * as SchemaAST from 'effect/SchemaAST';
 
-import { registerSignalsRuntime } from '@dxos/echo-signals';
 import { assertArgument } from '@dxos/invariant';
 import { deepMapValues } from '@dxos/util';
 
-import { EchoSchema, PersistentSchema, getSchemaTypename, makeObject, toJsonSchema } from '../internal';
-
-registerSignalsRuntime();
+import { EchoSchema, PersistentSchema, getSchemaTypename, makeObject, subscribe, toJsonSchema } from '../internal';
 
 /**
  * Create a reactive mutable schema that updates when the JSON schema is updated.
@@ -25,8 +21,7 @@ export const createEchoSchema = (schema: Schema.Schema.AnyNoContext, version = '
   const echoSchema = new EchoSchema(makeObject(PersistentSchema, { typename, version, jsonSchema }));
 
   // TODO(burdon): Unsubscribe is never called.
-  effect(() => {
-    const _ = echoSchema.jsonSchema;
+  subscribe(echoSchema.persistentSchema, () => {
     echoSchema._invalidate();
   });
 
@@ -60,17 +55,29 @@ export const prepareAstForCompare = (obj: SchemaAST.AST): any =>
     return recurse(value);
   });
 
-// TODO(burdon): Use @dxos/util.
-export const updateCounter = (touch: () => void) => {
-  let updateCount = -1;
-  const unsubscribe = effect(() => {
-    touch();
-    updateCount++;
-  });
+/**
+ * Creates an update counter that tracks changes to reactive objects.
+ * @param objects - Reactive objects to subscribe to.
+ * @returns An object with a count property and Symbol.dispose for cleanup.
+ */
+export const updateCounter = (...objects: object[]) => {
+  let updateCount = 0;
+
+  const unsubscribes = objects.map((obj) =>
+    subscribe(obj, () => {
+      updateCount++;
+    }),
+  );
+
+  const unsubscribeAll = () => {
+    for (const unsub of unsubscribes) {
+      unsub();
+    }
+  };
 
   return {
     // https://github.com/tc39/proposal-explicit-resource-management
-    [Symbol.dispose]: unsubscribe,
+    [Symbol.dispose]: unsubscribeAll,
     get count() {
       return updateCount;
     },