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

package/src/internal/{entities → Entity}/model.ts

@@ -9,75 +9,49 @@ import { invariant } from '@dxos/invariant';
 import { DXN, ObjectId } from '@dxos/keys';
 import { assumeType } from '@dxos/util';
 
+import type * as Database from '../../Database';
 import {
   type ATTR_META,
+  type ATTR_PARENT,
   type ATTR_TYPE,
+  ATTR_DELETED,
+  ATTR_RELATION_SOURCE,
+  ATTR_RELATION_TARGET,
+  ATTR_SELF_DXN,
   EntityKind,
   KindId,
   type MetaId,
+  ObjectDatabaseId,
+  ObjectDeletedId,
   type ObjectMeta,
-  type SchemaId,
-  TypeId,
-  type Version,
-} from '../types';
-
-import {
-  type ATTR_RELATION_SOURCE,
-  type ATTR_RELATION_TARGET,
+  ObjectVersionId,
+  type ParentId,
   RelationSourceDXNId,
   RelationSourceId,
   RelationTargetDXNId,
   RelationTargetId,
-} from './relation';
-
-//
-// Defines the internal model of the echo object.
-//
-
-/**
- * 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');
+  type SchemaId,
+  SelfDXNId,
+  TypeId,
+  type Version,
+} from '../common/types';
 
-/**
- * Object version accessor symbol.
- */
-export const ObjectVersionId: unique symbol = Symbol.for('@dxos/echo/Version');
+export { ATTR_DELETED, ATTR_SELF_DXN, ObjectDatabaseId, ObjectDeletedId, ObjectVersionId, SelfDXNId };
 
 /**
  * Internal runtime representation of an object.
  * The fields are accessed through getter functions.
  */
+// NOTE: Each symbol has a jsdoc describing its purpose.
 export interface InternalObjectProps {
-  id: ObjectId;
-
-  // Echo supports untyped objects O_O.
-  readonly [TypeId]?: DXN;
-
-  //
-  readonly [SelfDXNId]?: DXN;
-
-  /**
-   * Returns the schema for the object.
-   */
-  readonly [SchemaId]?: Schema.Schema.AnyNoContext;
+  readonly id: ObjectId;
+  readonly [SelfDXNId]: DXN;
   readonly [KindId]: EntityKind;
+  readonly [SchemaId]: Schema.Schema.AnyNoContext;
+  readonly [TypeId]: DXN;
   readonly [MetaId]?: ObjectMeta;
+  [ParentId]?: InternalObjectProps;
+  readonly [ObjectDatabaseId]?: Database.Database;
   readonly [ObjectDeletedId]?: boolean;
   readonly [ObjectVersionId]?: Version;
   readonly [RelationSourceDXNId]?: DXN;
@@ -101,10 +75,16 @@ export interface ObjectJSON {
   id: string;
   [ATTR_TYPE]: DXN.String;
   [ATTR_SELF_DXN]?: DXN.String;
+  [ATTR_PARENT]?: string; // Encoded reference
   [ATTR_DELETED]?: boolean;
   [ATTR_META]?: ObjectMetaJSON;
   [ATTR_RELATION_SOURCE]?: DXN.String;
   [ATTR_RELATION_TARGET]?: DXN.String;
+
+  /**
+   * Application-specific properties.
+   */
+  [key: string]: unknown;
 }
 
 /**

package/src/internal/{entities → Entity}/object.ts

@@ -7,27 +7,39 @@ import * as SchemaAST from 'effect/SchemaAST';
 
 import { invariant } from '@dxos/invariant';
 
-import { type TypeAnnotation, TypeAnnotationId, type TypeMeta, makeTypeJsonSchemaAnnotation } from '../annotations';
-import { EntityKind } from '../types';
-
+import { type TypeAnnotation, TypeAnnotationId, type TypeMeta, makeTypeJsonSchemaAnnotation } from '../Annotation';
+import { EntityKind } from '../common/types';
 import { type EchoTypeSchema, makeEchoTypeSchema } from './entity';
 
+/**
+ * Object schema type with kind marker.
+ */
+export type EchoObjectSchema<
+  Self extends Schema.Schema.Any,
+  Fields extends Schema.Struct.Fields = Schema.Struct.Fields,
+> = EchoTypeSchema<Self, {}, EntityKind.Object, Fields>;
+
 /**
  * Schema for Obj entity types.
  * Pipeable function to add ECHO object annotations to a schema.
  */
 export const EchoObjectSchema: {
-  // TODO(burdon): Tighten Self type to Schema.TypeLiteral or Schema.Struct to facilitate definition of `make` method.
-  // (meta: TypeMeta): <Self extends Schema.Struct<Fields>, Fields extends Schema.Struct.Fields>(self: Self) => EchoObjectSchema<Self, Fields>;
-  (meta: TypeMeta): <Self extends Schema.Schema.Any>(self: Self) => EchoTypeSchema<Self>;
+  (
+    meta: TypeMeta,
+  ): <Self extends Schema.Schema.Any, Fields extends Schema.Struct.Fields = Schema.Struct.Fields>(
+    self: Self & { fields?: Fields },
+  ) => EchoObjectSchema<Self, Fields>;
 } = ({ typename, version }) => {
-  return <Self extends Schema.Schema.Any>(self: Self): EchoTypeSchema<Self> => {
+  return <Self extends Schema.Schema.Any, Fields extends Schema.Struct.Fields = Schema.Struct.Fields>(
+    self: Self & { fields?: Fields },
+  ): EchoObjectSchema<Self, Fields> => {
     invariant(typeof TypeAnnotationId === 'symbol', 'Sanity.');
     invariant(SchemaAST.isTypeLiteral(self.ast), 'Schema must be a TypeLiteral.');
 
-    // TODO(dmaretskyi): Does `Schema.mutable` work for deep mutability here?
-    // TODO(dmaretskyi): Do not do mutable here.
-    const schemaWithId = Schema.extend(Schema.mutable(self), Schema.Struct({ id: Schema.String }));
+    // Extract fields from the schema if available (Struct schemas have .fields).
+    const fields = ((self as any).fields ?? {}) as Fields;
+
+    const schemaWithId = Schema.extend(self, Schema.Struct({ id: Schema.String }));
     const ast = SchemaAST.annotations(schemaWithId.ast, {
       // TODO(dmaretskyi): `extend` kills the annotations.
       ...self.ast.annotations,
@@ -40,6 +52,6 @@ export const EchoObjectSchema: {
       }),
     });
 
-    return makeEchoTypeSchema<Self>(/* self.fields, */ ast, typename, version);
+    return makeEchoTypeSchema<Self, EntityKind.Object, Fields>(fields, ast, typename, version, EntityKind.Object);
   };
 };

package/src/internal/{entities → Entity}/relation.ts

@@ -17,45 +17,28 @@ import {
   getSchemaTypename,
   getTypeIdentifierAnnotation,
   makeTypeJsonSchemaAnnotation,
-} from '../annotations';
-import { EntityKind } from '../types';
+} from '../Annotation';
+import {
+  ATTR_RELATION_SOURCE,
+  ATTR_RELATION_TARGET,
+  EntityKind,
+  RelationSourceDXNId,
+  RelationSourceId,
+  RelationTargetDXNId,
+  RelationTargetId,
+} from '../common/types';
+
+export {
+  ATTR_RELATION_SOURCE,
+  ATTR_RELATION_TARGET,
+  RelationSourceDXNId,
+  RelationSourceId,
+  RelationTargetDXNId,
+  RelationTargetId,
+};
 
 import { type EchoTypeSchema, makeEchoTypeSchema } from './entity';
 
-/**
- * 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.
- * Reading this symbol must return `Live<EchoObjectSchema<any>>` or a DXN.
- */
-export const RelationSourceId: unique symbol = Symbol.for('@dxos/echo/RelationSource');
-
-/**
- * Used to access relation source ref on live ECHO objects.
- * Reading this symbol must return `Live<EchoObjectSchema<any>>` or a DXN.
- */
-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.
- * Reading this symbol must return `Live<EchoObjectSchema<any>>` or a DXN.
- */
-export const RelationTargetId: unique symbol = Symbol.for('@dxos/echo/RelationTarget');
-
-/**
- * Used to access relation target ref on live ECHO objects.
- * Reading this symbol must return `Live<EchoObjectSchema<any>>` or a DXN.
- */
-export const RelationTargetDXNId: unique symbol = Symbol.for('@dxos/echo/RelationTargetDXN');
-
 /**
  * Source and target props on relations.
  */
@@ -83,6 +66,21 @@ export type EchoRelationSchemaOptions<
   target: TTarget;
 };
 
+/**
+ * Relation schema type with kind marker.
+ */
+export type EchoRelationSchema<
+  Self extends Schema.Schema.Any,
+  Source extends Schema.Schema.AnyNoContext,
+  Target extends Schema.Schema.AnyNoContext,
+  Fields extends Schema.Struct.Fields = Schema.Struct.Fields,
+> = EchoTypeSchema<
+  Self,
+  RelationSourceTargetRefs<Schema.Schema.Type<Source>, Schema.Schema.Type<Target>>,
+  EntityKind.Relation,
+  Fields
+>;
+
 /**
  * Schema for Relation entity types.
  */
@@ -106,14 +104,15 @@ export const EchoRelationSchema = <
     raise(new Error('Target schema must be an echo object schema.'));
   }
 
-  return <Self extends Schema.Schema.Any>(
-    self: Self,
-  ): EchoTypeSchema<Self, RelationSourceTargetRefs<Schema.Schema.Type<Source>, Schema.Schema.Type<Target>>> => {
+  return <Self extends Schema.Schema.Any, Fields extends Schema.Struct.Fields = Schema.Struct.Fields>(
+    self: Self & { fields?: Fields },
+  ): EchoRelationSchema<Self, Source, Target, Fields> => {
     invariant(SchemaAST.isTypeLiteral(self.ast), 'Schema must be a TypeLiteral.');
 
-    // TODO(dmaretskyi): Does `Schema.mutable` work for deep mutability here?
-    // TODO(dmaretskyi): Do not do mutable here.
-    const schemaWithId = Schema.extend(Schema.mutable(self), Schema.Struct({ id: Schema.String }));
+    // Extract fields from the schema if available (Struct schemas have .fields).
+    const fields = ((self as any).fields ?? {}) as Fields;
+
+    const schemaWithId = Schema.extend(self, Schema.Struct({ id: Schema.String }));
     const ast = SchemaAST.annotations(schemaWithId.ast, {
       // TODO(dmaretskyi): `extend` kills the annotations.
       ...self.ast.annotations,
@@ -135,7 +134,7 @@ export const EchoRelationSchema = <
       }),
     });
 
-    return makeEchoTypeSchema<Self>(/* self.fields, */ ast, typename, version);
+    return makeEchoTypeSchema<Self, EntityKind.Relation, Fields>(fields, ast, typename, version, EntityKind.Relation);
   };
 };
 

package/src/internal/Entity/version.ts

@@ -0,0 +1,96 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { assertArgument } from '@dxos/invariant';
+
+import { type AnyEntity, VersionTypeId } from '../common/types';
+import { ObjectVersionId } from './model';
+
+/**
+ * Represent entity version.
+ * May be backed by Automerge.
+ * Entities with no history are not versioned.
+ * Named EntityVersion to avoid conflict with types/version.ts.
+ */
+export interface EntityVersion {
+  [VersionTypeId]: {};
+
+  /**
+   * Whether the entity is versioned.
+   */
+  versioned: boolean;
+
+  /**
+   * Automerge heads.
+   */
+  automergeHeads?: string[];
+}
+
+const unversioned: EntityVersion = {
+  [VersionTypeId]: {},
+  versioned: false,
+};
+
+/**
+ * Checks that `obj` is a version object.
+ */
+export const isVersion = (entity: unknown): entity is EntityVersion => {
+  return entity != null && typeof entity === 'object' && VersionTypeId in entity;
+};
+
+/**
+ * Returns the version of an entity.
+ * Accepts both reactive entities and snapshots.
+ */
+export const version = (entity: AnyEntity): EntityVersion => {
+  const ver = (entity as any)[ObjectVersionId];
+  if (ver === undefined) {
+    return unversioned;
+  }
+  return ver;
+};
+
+/**
+ * Checks that `version` is a valid version object.
+ */
+export const versionValid = (ver: EntityVersion): boolean => {
+  assertArgument(isVersion(ver), 'version', 'Invalid version object');
+  return !!ver.versioned;
+};
+
+export type VersionCompareResult = 'unversioned' | 'equal' | 'different';
+
+/**
+ * Compares two versions.
+ * @param version1
+ * @param version2
+ * @returns 'unversioned' if either entity is unversioned, 'equal' if the versions are equal, 'different' if the versions are different.
+ */
+export const compareVersions = (version1: EntityVersion, version2: EntityVersion): VersionCompareResult => {
+  assertArgument(isVersion(version1), 'version1', 'Invalid version object');
+  assertArgument(isVersion(version2), 'version2', 'Invalid version object');
+
+  if (!versionValid(version1) || !versionValid(version2)) {
+    return 'unversioned';
+  }
+
+  if (version1.automergeHeads?.length !== version2.automergeHeads?.length) {
+    return 'different';
+  }
+  if (version1.automergeHeads?.some((head) => !version2.automergeHeads?.includes(head))) {
+    return 'different';
+  }
+
+  return 'equal';
+};
+
+export const encodeVersion = (ver: EntityVersion): string => {
+  return JSON.stringify(ver);
+};
+
+export const decodeVersion = (ver: string): EntityVersion => {
+  const parsed = JSON.parse(ver);
+  parsed[VersionTypeId] = {};
+  return parsed;
+};

package/src/internal/{formats → Format}/date.test.ts

@@ -7,8 +7,7 @@ import { describe, expect, test } from 'vitest';
 
 import { log } from '@dxos/log';
 
-import { toJsonSchema } from '../json-schema';
-
+import { toJsonSchema } from '../JsonSchema';
 import {
   DateOnly,
   DateTime,

package/src/internal/{formats → Format}/format.test.ts

@@ -5,8 +5,7 @@
 import * as Schema from 'effect/Schema';
 import { describe, test } from 'vitest';
 
-import { toJsonSchema } from '../json-schema';
-
+import { toJsonSchema } from '../JsonSchema';
 import { Format } from './format';
 import { TypeEnum, TypeFormat, getTypeEnum } from './types';
 
@@ -20,7 +19,7 @@ describe('formats', () => {
       birthday: Schema.optional(Format.Date),
       started: Schema.optional(Format.DateTime),
       active: Schema.optional(Schema.Boolean),
-    }).pipe(Schema.mutable);
+    });
 
     type TestType = Schema.Schema.Type<typeof TestSchema>;
 

package/src/internal/{formats → Format}/format.ts

@@ -10,11 +10,10 @@ import * as DateUtil from './date';
 import * as NumberUtil from './number';
 import * as ObjectUtil from './object';
 import * as StringUtil from './string';
-import { TypeFormat as TypeFormatEnum } from './types';
+import { TypeFormat as TypeFormat$ } from './types';
 
-// TODO(burdon): Consider factoring out to separate `@dxos/json-schema`
 // TODO(burdon): Media encoding.
-//  - https://json-schema.org/understanding-json-schema/reference/non_json_data
+// - https://json-schema.org/understanding-json-schema/reference/non_json_data
 
 /**
  * Formats.
@@ -23,9 +22,9 @@ import { TypeFormat as TypeFormatEnum } from './types';
  */
 // TODO(burdon): Add fields for `examples`, `message`, etc.
 export namespace Format {
-  export import TypeFormat = TypeFormatEnum;
+  export import TypeFormat = TypeFormat$;
 
-  // Strings
+  // String
   export const DXN = Keys.DXN.Schema;
   export const Email = StringUtil.Email;
   export const Formula = StringUtil.Formula;
@@ -44,12 +43,12 @@ export namespace Format {
   export const Timestamp = NumberUtil.Timestamp;
 
   // Dates and times
-  export const DateTime = DateUtil.DateTime;
   export const Date = DateUtil.DateOnly;
-  export const Time = DateUtil.TimeOnly;
+  export const DateTime = DateUtil.DateTime;
   export const Duration = DateUtil.Duration;
+  export const Time = DateUtil.TimeOnly;
 
   // Objects
   export const GeoPoint = ObjectUtil.GeoPoint;
-  export type GeoPoint = ObjectUtil.GeoPoint;
+  export type GeoPoint = ObjectUtil.GeoPoint; // TODO(burdon): Export types.
 }

package/src/internal/{formats → Format}/object.ts

@@ -21,8 +21,8 @@ import { FormatAnnotation, TypeFormat } from './types';
  * Note: optional third element for altitude.
  */
 export const GeoPoint = Schema.Tuple(
-  Schema.Number.pipe(Schema.annotations({ title: 'Longitude' }), Schema.clamp(-180, 180), Schema.multipleOf(0.00001)),
-  Schema.Number.pipe(Schema.annotations({ title: 'Latitude' }), Schema.clamp(-90, 90), Schema.multipleOf(0.00001)),
+  Schema.Number.pipe(Schema.annotations({ title: 'Longitude' }), Schema.clamp(-180, 180), Schema.multipleOf(0.000001)),
+  Schema.Number.pipe(Schema.annotations({ title: 'Latitude' }), Schema.clamp(-90, 90), Schema.multipleOf(0.000001)),
   Schema.optionalElement(Schema.Number).annotations({
     title: 'Height ASL (m)',
   }),

package/src/internal/{formats → Format}/select.ts

@@ -4,13 +4,15 @@
 
 import * as Schema from 'effect/Schema';
 
-/** Schema for a single select option. Used to define choices in a {single|multi}-select field. */
-export const SelectOptionSchema = Schema.Struct({
+/**
+ * Schema for a single select option. Used to define choices in a {single|multi}-select field.
+ */
+export const SelectOption = Schema.Struct({
   /** Stable identifier for the option. */
   id: Schema.NonEmptyString,
   title: Schema.String,
   /** Color palette used for visual styling. */
   color: Schema.String,
-}).pipe(Schema.mutable);
+});
 
-export type SelectOption = Schema.Schema.Type<typeof SelectOptionSchema>;
+export type SelectOption = Schema.Schema.Type<typeof SelectOption>;

package/src/internal/{formats → Format}/string.ts

@@ -52,6 +52,11 @@ export const Markdown = Schema.String.pipe(FormatAnnotation.set(TypeFormat.Markd
 // TODO(burdon): Implement.
 export const Regex = Schema.String.pipe(FormatAnnotation.set(TypeFormat.Regex));
 
+/**
+ * Multi-line text.
+ */
+export const Text = Schema.String.pipe(FormatAnnotation.set(TypeFormat.Text));
+
 /**
  * https://datatracker.ietf.org/doc/html/rfc3986#section-1.1.3
  */

package/src/internal/{formats → Format}/types.ts

@@ -7,8 +7,8 @@ import type * as JSONSchema from 'effect/JSONSchema';
 import * as Option from 'effect/Option';
 import * as SchemaAST from 'effect/SchemaAST';
 
-import { createAnnotationHelper } from '../annotations';
-import { type JsonSchemaType } from '../json-schema';
+import { createAnnotationHelper } from '../Annotation';
+import { type JsonSchemaType } from '../JsonSchema';
 
 // TODO(burdon): Rename PropertyType.
 export type ScalarType =
@@ -55,6 +55,7 @@ export const FormatAnnotationId = Symbol.for('@dxos/schema/annotation/Format');
 
 export const FormatAnnotation = createAnnotationHelper<TypeFormat>(FormatAnnotationId);
 
+/** @deprecated */
 export const getFormatAnnotation = (node: SchemaAST.AST): TypeFormat | undefined =>
   Function.pipe(SchemaAST.getAnnotation<TypeFormat>(FormatAnnotationId)(node), Option.getOrUndefined);
 
@@ -84,6 +85,7 @@ export enum TypeFormat {
   Markdown = 'markdown',
   Regex = 'regex',
   SingleSelect = 'single-select',
+  Text = 'text',
   MultiSelect = 'multi-select',
   URL = 'url',
   UUID = 'uuid',
@@ -133,7 +135,7 @@ export const typeToFormat: Partial<Record<TypeEnum, TypeFormat>> = {
  * Map of format to type.
  */
 export const formatToType: Record<TypeFormat, TypeEnum> = {
-  [TypeFormat.None]: undefined as any,
+  [TypeFormat.None]: TypeEnum.String,
   [TypeFormat.String]: TypeEnum.String,
   [TypeFormat.Number]: TypeEnum.Number,
   [TypeFormat.Boolean]: TypeEnum.Boolean,
@@ -151,6 +153,7 @@ export const formatToType: Record<TypeFormat, TypeEnum> = {
   [TypeFormat.URL]: TypeEnum.String,
   [TypeFormat.UUID]: TypeEnum.String,
   [TypeFormat.SingleSelect]: TypeEnum.String,
+  [TypeFormat.Text]: TypeEnum.String,
   [TypeFormat.MultiSelect]: TypeEnum.Object,
 
   // Dates
@@ -174,7 +177,10 @@ export const formatToType: Record<TypeFormat, TypeEnum> = {
  */
 export const OptionsAnnotationId = Symbol.for('@dxos/schema/annotation/Options');
 
-export const getOptionsAnnotation = (node: SchemaAST.AST): OptionsAnnotationType[] | undefined =>
-  Function.pipe(SchemaAST.getAnnotation<OptionsAnnotationType[]>(OptionsAnnotationId)(node), Option.getOrUndefined);
+// TODO(wittjosiah): Reconcile with `SelectOption`.
+export type Options = string | number;
+export const OptionsAnnotation = createAnnotationHelper<Options[]>(OptionsAnnotationId);
 
-export type OptionsAnnotationType = string | number;
+/** @deprecated */
+export const getOptionsAnnotation = (node: SchemaAST.AST): Options[] | undefined =>
+  Function.pipe(SchemaAST.getAnnotation<Options[]>(OptionsAnnotationId)(node), Option.getOrUndefined);

package/src/internal/{json-schema → JsonSchema}/annotations.ts

@@ -4,9 +4,9 @@
 
 import * as SchemaAST from 'effect/SchemaAST';
 
-import { GeneratorAnnotationId, LabelAnnotationId, PropertyMetaAnnotationId } from '../annotations';
-import { CurrencyAnnotationId, FormatAnnotationId } from '../formats';
-import { type JsonSchemaEchoAnnotations, type JsonSchemaType } from '../json-schema';
+import { GeneratorAnnotationId, LabelAnnotationId, PropertyMetaAnnotationId } from '../Annotation';
+import { CurrencyAnnotationId, FormatAnnotationId } from '../Format';
+import { type JsonSchemaEchoAnnotations, type JsonSchemaType } from '../JsonSchema';
 
 //
 // This file configures annotations for JSON encoding/decoding.

package/src/internal/{json-schema → JsonSchema}/json-schema-normalize.ts

@@ -2,6 +2,8 @@
 // Copyright 2025 DXOS.org
 //
 
+import type * as Types from 'effect/Types';
+
 import { JsonSchemaFields, type JsonSchemaType } from './json-schema-type';
 
 /**
@@ -9,12 +11,12 @@ import { JsonSchemaFields, type JsonSchemaType } from './json-schema-type';
  * Note: the input type does not necessarily match the {@link JsonSchemaType} type.
  */
 export const normalizeSchema = (schema: JsonSchemaType): JsonSchemaType => {
-  const copy = structuredClone(schema);
+  const copy = structuredClone(schema) as Types.DeepMutable<JsonSchemaType>;
   go(copy);
   return copy;
 };
 
-const go = (schema: JsonSchemaType) => {
+const go = (schema: Types.DeepMutable<JsonSchemaType>) => {
   if (typeof schema !== 'object' || schema === null) {
     return;
   }