@dxos/echo 0.8.4-main.9735255 → 0.8.4-main.9be5663bfe

package/src/internal/{proxy → common/proxy}/schema.test.ts

@@ -6,14 +6,14 @@ import * as Schema from 'effect/Schema';
 import * as SchemaAST from 'effect/SchemaAST';
 import { describe, expect, test } from 'vitest';
 
-import { createEchoSchema } from '../../testing';
-import { PropertyMeta, getPropertyMetaAnnotation, getTypeAnnotation } from '../annotations';
-import { EchoObjectSchema } from '../entities';
+import { createEchoSchema } from '../../../testing';
+import { PropertyMeta, getPropertyMetaAnnotation, getTypeAnnotation } from '../../Annotation';
+import { EchoObjectSchema } from '../../Entity';
 
 // TODO(dmaretskyi): Comment.
 const EmptySchemaType = Schema.Struct({}).pipe(
   EchoObjectSchema({
-    typename: 'example.com/type/Empty',
+    typename: 'com.example.type.empty',
     version: '0.1.0',
   }),
 );
@@ -27,7 +27,7 @@ describe('dynamic schema', () => {
       field2: Schema.Boolean,
     }).pipe(
       EchoObjectSchema({
-        typename: 'example.com/type/Test',
+        typename: 'com.example.type.test',
         version: '0.1.0',
       }),
     );
@@ -44,7 +44,7 @@ describe('dynamic schema', () => {
       field1: Schema.String,
     }).pipe(
       EchoObjectSchema({
-        typename: 'example.com/type/Test',
+        typename: 'com.example.type.test',
         version: '0.1.0',
       }),
     );
@@ -95,7 +95,7 @@ describe('dynamic schema', () => {
     registered.updateFields({ field3: Schema.Boolean });
     registered.removeFields(['field2']);
     expect(getTypeAnnotation(registered)).to.deep.contain({
-      typename: 'example.com/type/Empty',
+      typename: 'com.example.type.empty',
       version: '0.1.0',
     });
     expect(getPropertyMetaAnnotation(registered.getProperties()[0], metaNamespace)).to.deep.eq(metaInfo);
@@ -111,7 +111,7 @@ describe('dynamic schema', () => {
     });
 
     // First update.
-    const newTypename1 = 'example.com/type/Individual';
+    const newTypename1 = 'com.example.type.individual';
     registered.updateTypename(newTypename1);
 
     // Basic typename update checks.
@@ -132,13 +132,13 @@ describe('dynamic schema', () => {
     expect(nameMeta).toEqual({ maxLength: 10 });
 
     // Second update to ensure multiple updates work.
-    const newTypename2 = 'example.com/type/Person';
+    const newTypename2 = 'com.example.type.person';
     registered.updateTypename(newTypename2);
     expect(registered.typename).toBe(newTypename2);
     expect(registered.jsonSchema.$id).toBe(`dxn:type:${newTypename2}`);
     expect(registered.jsonSchema.typename).toBe(newTypename2);
     expect(getTypeAnnotation(registered)).to.deep.contain({
-      typename: 'example.com/type/Person',
+      typename: 'com.example.type.person',
       version: '0.1.0',
     });
   });

package/src/internal/{proxy → common/proxy}/typed-handler.test.ts

@@ -5,12 +5,11 @@
 import * as Schema from 'effect/Schema';
 import { describe, expect, test } from 'vitest';
 
-import { TestSchema } from '../../testing';
-import { EchoObjectSchema } from '../entities';
-import { setValue } from '../object';
-import { Ref } from '../ref';
+import { TestSchema } from '../../../testing';
+import { EchoObjectSchema } from '../../Entity';
+import { setValue } from '../../Obj';
+import { Ref } from '../../Ref';
 import { foreignKey, getMeta } from '../types';
-
 import { makeObject } from './make-object';
 import { change, subscribe } from './reactive';
 
@@ -40,10 +39,10 @@ describe('complex schema validations', () => {
 
   test('references', () => {
     const Foo = Schema.Struct({ field: Schema.String }).pipe(
-      EchoObjectSchema({ typename: 'example.com/type/Foo', version: '0.1.0' }),
+      EchoObjectSchema({ typename: 'com.example.type.foo', version: '0.1.0' }),
     );
     const Bar = Schema.Struct({ fooRef: Ref(Foo) }).pipe(
-      EchoObjectSchema({ typename: 'example.com/type/Bar', version: '0.1.0' }),
+      EchoObjectSchema({ typename: 'com.example.type.bar', version: '0.1.0' }),
     );
     const field = 'hello';
     expect(() => makeObject(Bar, { fooRef: { id: '1', field } as any })).to.throw();

package/src/internal/{proxy → common/proxy}/typed-handler.ts

@@ -2,19 +2,16 @@
 // Copyright 2024 DXOS.org
 //
 
-import { type InspectOptionsStylized } from 'node:util';
-
 import * as Schema from 'effect/Schema';
 import * as SchemaAST from 'effect/SchemaAST';
+import { type InspectOptionsStylized } from 'node:util';
 
 import { Event } from '@dxos/async';
 import { inspectCustom } from '@dxos/debug';
 import { invariant } from '@dxos/invariant';
 
-import { getSchemaDXN } from '../annotations';
-import { ObjectDeletedId } from '../entities';
-import { SchemaId, TypeId } from '../types';
-
+import { getSchemaDXN } from '../../Annotation';
+import { ObjectDeletedId, ParentId, SchemaId, TypeId } from '../types';
 import { executeChange, isInChangeContext, queueNotification } from './change-context';
 import { defineHiddenProperty } from './define-hidden-property';
 import { createPropertyDeleteError } from './errors';
@@ -47,6 +44,7 @@ type ProxyTarget = {
    * Schema for the root.
    */
   [SchemaId]: Schema.Schema.AnyNoContext;
+  [ParentId]?: any;
 
   /**
    * For modifications.
@@ -320,6 +318,10 @@ export class TypedReactiveHandler implements ReactiveHandler<ProxyTarget> {
   ): { echoRoot: object; preparedValue: any } {
     const echoRoot = getEchoRoot(target);
 
+    if (prop === ParentId) {
+      return { echoRoot, preparedValue: value }; // Short-circuit for parent assignment.
+    }
+
     // Check for cycles before assignment.
     if (isValidProxyTarget(value) || isProxy(value)) {
       if (wouldCreateCycle(echoRoot, value)) {
@@ -363,6 +365,9 @@ export class TypedReactiveHandler implements ReactiveHandler<ProxyTarget> {
   }
 
   private _validateValue(target: any, prop: string | symbol, value: any) {
+    if (prop === ParentId) {
+      return value;
+    }
     const schema = SchemaValidator.getTargetPropertySchema(target, prop);
     const _ = Schema.asserts(schema)(value);
     if (isValidProxyTarget(value)) {

package/src/internal/{proxy → common/proxy}/typed-object.test.ts

@@ -6,9 +6,8 @@ import * as Schema from 'effect/Schema';
 import type * as Types from 'effect/Types';
 import { describe, expect, test } from 'vitest';
 
-import { EchoObjectSchema } from '../entities';
+import { EchoObjectSchema } from '../../Entity';
 import { getSchema } from '../types';
-
 import { makeObject } from './make-object';
 import { change } from './reactive';
 
@@ -16,7 +15,7 @@ const Organization = Schema.Struct({
   name: Schema.String,
 }).pipe(
   EchoObjectSchema({
-    typename: 'example.com/type/Organization',
+    typename: 'com.example.type.organization',
     version: '0.1.0',
   }),
 );
@@ -34,7 +33,7 @@ const Contact = Schema.Struct(
 ).pipe(
   Schema.partial,
   EchoObjectSchema({
-    typename: 'example.com/type/Person',
+    typename: 'com.example.type.person',
     version: '0.1.0',
   }),
 );
@@ -101,7 +100,7 @@ describe('EchoObjectSchema class DSL', () => {
         meta: Schema.optional(Schema.Record({ key: Schema.String, value: Schema.Any })),
       }).pipe(
         EchoObjectSchema({
-          typename: 'dxos.org/type/FunctionTrigger',
+          typename: 'org.dxos.type.functionTrigger',
           version: '0.1.0',
         }),
       );

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

@@ -14,12 +14,12 @@ import { type ATTR_META, type ObjectMeta } from './meta';
  * 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).
+ * @depreacted Remove, use Entity.Unknown instead.
  */
 // TODO(wittjosiah): Remove. Prefer higher level types (e.g. Entity.Unknown).
 export interface AnyEntity {

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

@@ -43,10 +43,10 @@ export enum EntityKind {
 export const EntityKindSchema = Schema.Enums(EntityKind);
 
 /**
- * Typename for generic object references (Type.Obj / Type.Ref(Type.Obj)).
+ * Typename for generic object references (Type.Obj / Ref.Ref(Obj.Unknown)).
  * Used when referencing any object without a specific schema.
  */
-export const ANY_OBJECT_TYPENAME = 'dxos.org/schema/AnyObject';
+export const ANY_OBJECT_TYPENAME = 'org.dxos.schema.anyObject';
 
 /**
  * Version for generic object references.

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

@@ -5,5 +5,6 @@
 export * from './base';
 export * from './entity';
 export * from './meta';
+export * from './model-symbols';
 export * from './typename';
 export * from './version';

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

@@ -8,6 +8,7 @@ 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';
 
 /**
@@ -18,7 +19,7 @@ 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
@@ -35,6 +36,7 @@ export const ObjectMetaSchema = Schema.Struct({
    */
   // 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)),
 });
 

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

@@ -5,35 +5,13 @@
 // TODO(burdon): Import directly (not part of ECHO API).
 export { JsonPath, JsonProp, getValue, splitJsonPath } from '@dxos/effect';
 
-export * from './annotations';
-export * from './api';
-export * from './entities';
-export * from './formats';
-export * from './json-schema';
-export * from './ref';
-export * from './types';
-
+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,7 +8,6 @@ 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', () => {
@@ -17,11 +16,11 @@ describe('Experimental API review', () => {
     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.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',
     });
   });
@@ -110,7 +109,7 @@ describe('Experimental API review', () => {
         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 _typed: Obj.OfShape<TestSchema.Expando> = expando;
       }
 
       {
@@ -119,7 +118,7 @@ describe('Experimental API review', () => {
         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;
+        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

@@ -4,6 +4,8 @@
 
 import * as Schema from 'effect/Schema';
 
+import * as Obj from '../Obj';
+import * as Ref from '../Ref';
 import * as Type from '../Type';
 
 export namespace TestSchema {
@@ -17,7 +19,7 @@ export namespace TestSchema {
    */
   export const Expando = Schema.Struct({}, { key: Schema.String, value: Schema.Any }).pipe(
     Type.object({
-      typename: 'example.com/type/Expando',
+      typename: 'com.example.type.expando',
       version: '0.1.0',
     }),
   );
@@ -51,8 +53,8 @@ export namespace TestSchema {
     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))),
+    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);
@@ -63,7 +65,7 @@ export namespace TestSchema {
   /** @deprecated Use another test schema or create a specific local test schema. */
   export const Example = ExampleSchema.pipe(
     Type.object({
-      typename: 'example.com/type/Example',
+      typename: 'com.example.type.example',
       version: '0.1.0',
     }),
   );
@@ -87,7 +89,7 @@ export namespace TestSchema {
 
   export const Message = MessageStruct.pipe(
     Type.object({
-      typename: 'example.com/type/Message',
+      typename: 'com.example.type.message',
       version: '0.1.0',
     }),
   );
@@ -108,7 +110,7 @@ export namespace TestSchema {
     ),
   }).pipe(
     Type.object({
-      typename: 'example.com/type/Organization',
+      typename: 'com.example.type.organization',
       version: '0.1.0',
     }),
   );
@@ -124,8 +126,8 @@ export namespace TestSchema {
     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)),
+    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),
@@ -142,7 +144,7 @@ export namespace TestSchema {
   }).pipe(
     Schema.partial,
     Type.object({
-      typename: 'example.com/type/Person',
+      typename: 'com.example.type.person',
       version: '0.1.0',
     }),
   );
@@ -157,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.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.object({
-      typename: 'example.com/type/Task',
+      typename: 'com.example.type.task',
       version: '0.1.0',
     }),
   );
@@ -177,7 +179,7 @@ export namespace TestSchema {
 
   export const HasManager = Schema.Struct({}).pipe(
     Type.relation({
-      typename: 'example.com/type/HasManager',
+      typename: 'com.example.type.has-manager',
       version: '0.1.0',
       source: Person,
       target: Person,
@@ -195,7 +197,7 @@ export namespace TestSchema {
     since: Schema.optional(Schema.String),
   }).pipe(
     Type.relation({
-      typename: 'example.com/type/EmployedBy',
+      typename: 'com.example.type.employed-by',
       version: '0.1.0',
       source: Person,
       target: Organization,
@@ -215,13 +217,13 @@ export namespace TestSchema {
   }
 
   export const Container = Schema.Struct({
-    objects: Schema.Array(Type.Ref(Type.Obj)),
+    objects: Schema.Array(Ref.Ref(Obj.Unknown)),
     records: Schema.Array(
       Schema.partial(
         Schema.Struct({
           title: Schema.String,
           description: Schema.String,
-          contacts: Schema.Array(Type.Ref(Person)),
+          contacts: Schema.Array(Ref.Ref(Person)),
           type: Schema.Enums(RecordType),
         }),
       ),
@@ -229,7 +231,7 @@ export namespace TestSchema {
   }).pipe(
     Schema.partial,
     Type.object({
-      typename: 'example.com/type/Container',
+      typename: 'com.example.type.container',
       version: '0.1.0',
     }),
   );