@dxos/echo 0.8.4-main.2e9d522 → 0.8.4-main.3c1ae3b

package/src/internal/entities/index.ts

@@ -0,0 +1,9 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+export * from './expando';
+export * from './model'; // TODO(burdon): Rename.
+export * from './object';
+export * from './relation';
+export * from './util';

package/src/internal/entities/model.ts

@@ -0,0 +1,129 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import type * as Schema from 'effect/Schema';
+
+import { type ForeignKey } from '@dxos/echo-protocol';
+import { invariant } from '@dxos/invariant';
+import { DXN, ObjectId } from '@dxos/keys';
+import { assumeType } from '@dxos/util';
+
+import {
+  type ATTR_META,
+  type ATTR_TYPE,
+  EntityKind,
+  KindId,
+  type MetaId,
+  type ObjectMeta,
+  type SchemaId,
+  TypeId,
+  type Version,
+} from '../types';
+
+import {
+  type ATTR_RELATION_SOURCE,
+  type ATTR_RELATION_TARGET,
+  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');
+
+/**
+ * Object version accessor symbol.
+ */
+export const ObjectVersionId: unique symbol = Symbol.for('@dxos/echo/Version');
+
+/**
+ * Internal runtime representation of an object.
+ * The fields are accessed through getter functions.
+ */
+export interface InternalObjectProps {
+  id: ObjectId;
+
+  // Echo supports untyped objects O_O.
+  readonly [TypeId]?: DXN;
+
+  // TODO(burdon): ???
+  readonly [SelfDXNId]?: DXN;
+
+  /**
+   * Returns the schema for the object.
+   */
+  readonly [SchemaId]?: Schema.Schema.AnyNoContext;
+  readonly [KindId]: EntityKind;
+  readonly [MetaId]?: ObjectMeta;
+  readonly [ObjectDeletedId]?: boolean;
+  readonly [ObjectVersionId]?: Version;
+  readonly [RelationSourceDXNId]?: DXN;
+  readonly [RelationTargetDXNId]?: DXN;
+  readonly [RelationSourceId]?: InternalObjectProps;
+  readonly [RelationTargetId]?: InternalObjectProps;
+}
+
+/**
+ * Entity metadata.
+ */
+export interface ObjectMetaJSON {
+  keys: ForeignKey[];
+  tags?: string[];
+}
+
+/**
+ * JSON representation of an object or relation metadata.
+ */
+export interface ObjectJSON {
+  id: string;
+  [ATTR_TYPE]: DXN.String;
+  [ATTR_SELF_DXN]?: DXN.String;
+  [ATTR_DELETED]?: boolean;
+  [ATTR_META]?: ObjectMetaJSON;
+  [ATTR_RELATION_SOURCE]?: DXN.String;
+  [ATTR_RELATION_TARGET]?: DXN.String;
+}
+
+/**
+ * NOTE: Keep as `function` to avoid type inference issues.
+ */
+export function assertObjectModel(obj: unknown): asserts obj is InternalObjectProps {
+  invariant(typeof obj === 'object' && obj !== null, 'Invalid object model: not an object');
+  assumeType<InternalObjectProps>(obj);
+  invariant(ObjectId.isValid(obj.id), 'Invalid object model: invalid id');
+  invariant(obj[TypeId] === undefined || obj[TypeId] instanceof DXN, 'Invalid object model: invalid type');
+  invariant(
+    obj[KindId] === EntityKind.Object || obj[KindId] === EntityKind.Relation,
+    'Invalid object model: invalid entity kind',
+  );
+
+  if (obj[KindId] === EntityKind.Relation) {
+    invariant(obj[RelationSourceDXNId] instanceof DXN, 'Invalid object model: invalid relation source');
+    invariant(obj[RelationTargetDXNId] instanceof DXN, 'Invalid object model: invalid relation target');
+    invariant(!(obj[RelationSourceId] instanceof DXN), 'Invalid object model: source pointer is a DXN');
+    invariant(!(obj[RelationTargetId] instanceof DXN), 'Invalid object model: target pointer is a DXN');
+  }
+}

package/src/internal/entities/object.ts

@@ -0,0 +1,45 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+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 EchoTypeSchema, makeEchoTypeSchema } from './entity';
+
+/**
+ * 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>;
+} = ({ typename, version }) => {
+  return <Self extends Schema.Schema.Any>(self: Self): EchoTypeSchema<Self> => {
+    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 }));
+    const ast = SchemaAST.annotations(schemaWithId.ast, {
+      // TODO(dmaretskyi): `extend` kills the annotations.
+      ...self.ast.annotations,
+      [TypeAnnotationId]: { kind: EntityKind.Object, typename, version } satisfies TypeAnnotation,
+      // TODO(dmaretskyi): TypeIdentifierAnnotationId?
+      [SchemaAST.JSONSchemaAnnotationId]: makeTypeJsonSchemaAnnotation({
+        kind: EntityKind.Object,
+        typename,
+        version,
+      }),
+    });
+
+    return makeEchoTypeSchema<Self>(/* self.fields, */ ast, typename, version);
+  };
+};

package/src/internal/entities/relation.ts

@@ -0,0 +1,155 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+import * as SchemaAST from 'effect/SchemaAST';
+
+import { raise } from '@dxos/debug';
+import { assertArgument, invariant } from '@dxos/invariant';
+import { DXN } from '@dxos/keys';
+
+import {
+  type TypeAnnotation,
+  TypeAnnotationId,
+  type TypeMeta,
+  getEntityKind,
+  getSchemaTypename,
+  getTypeIdentifierAnnotation,
+  makeTypeJsonSchemaAnnotation,
+} from '../annotations';
+import { EntityKind } from '../types';
+
+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.
+ */
+// TODO(burdon): any?
+export type RelationSourceTargetRefs<Source = any, Target = any> = {
+  /**
+   * Source ECHO live object.
+   */
+  [RelationSourceId]: Source;
+
+  /**
+   * Target ECHO live object.
+   */
+  [RelationTargetId]: Target;
+};
+
+export type RelationSource<R> = R extends RelationSourceTargetRefs<infer Source, infer _Target> ? Source : never;
+export type RelationTarget<R> = R extends RelationSourceTargetRefs<infer _Source, infer Target> ? Target : never;
+
+export type EchoRelationSchemaOptions<
+  TSource extends Schema.Schema.AnyNoContext,
+  TTarget extends Schema.Schema.AnyNoContext,
+> = TypeMeta & {
+  source: TSource;
+  target: TTarget;
+};
+
+/**
+ * Schema for Relation entity types.
+ */
+export const EchoRelationSchema = <
+  Source extends Schema.Schema.AnyNoContext,
+  Target extends Schema.Schema.AnyNoContext,
+>({
+  source,
+  target,
+  typename,
+  version,
+}: EchoRelationSchemaOptions<Source, Target>) => {
+  assertArgument(Schema.isSchema(source), 'source');
+  assertArgument(Schema.isSchema(target), 'target');
+  const sourceDXN = getDXNForRelationSchemaRef(source);
+  const targetDXN = getDXNForRelationSchemaRef(target);
+  if (getEntityKind(source) !== EntityKind.Object) {
+    raise(new Error('Source schema must be an echo object schema.'));
+  }
+  if (getEntityKind(target) !== EntityKind.Object) {
+    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>>> => {
+    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 }));
+    const ast = SchemaAST.annotations(schemaWithId.ast, {
+      // TODO(dmaretskyi): `extend` kills the annotations.
+      ...self.ast.annotations,
+      [TypeAnnotationId]: {
+        kind: EntityKind.Relation,
+        typename,
+        version,
+        sourceSchema: sourceDXN,
+        targetSchema: targetDXN,
+      } satisfies TypeAnnotation,
+      // TODO(dmaretskyi): TypeIdentifierAnnotationId?
+
+      [SchemaAST.JSONSchemaAnnotationId]: makeTypeJsonSchemaAnnotation({
+        kind: EntityKind.Relation,
+        typename,
+        version,
+        relationSource: sourceDXN,
+        relationTarget: targetDXN,
+      }),
+    });
+
+    return makeEchoTypeSchema<Self>(/* self.fields, */ ast, typename, version);
+  };
+};
+
+const getDXNForRelationSchemaRef = (schema: Schema.Schema.Any): string => {
+  assertArgument(Schema.isSchema(schema), 'schema');
+  const identifier = getTypeIdentifierAnnotation(schema);
+  if (identifier) {
+    return identifier;
+  }
+
+  const typename = getSchemaTypename(schema);
+  if (!typename) {
+    throw new Error('Schema must have a typename');
+  }
+
+  return DXN.fromTypename(typename).toString();
+};

package/src/internal/entities/util.ts

@@ -0,0 +1,33 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+
+import { assertArgument, invariant } from '@dxos/invariant';
+import { DXN, ObjectId } from '@dxos/keys';
+import { assumeType } from '@dxos/util';
+
+import { type InternalObjectProps, SelfDXNId } from './model';
+
+/**
+ * Returns a DXN for an object or schema.
+ *
+ * @internal
+ */
+export const getObjectDXN = (object: any): DXN | undefined => {
+  invariant(!Schema.isSchema(object), 'schema not allowed in this function');
+  assertArgument(typeof object === 'object' && object != null, 'object', 'expected object');
+  assumeType<InternalObjectProps>(object);
+
+  if (object[SelfDXNId]) {
+    invariant(object[SelfDXNId] instanceof DXN, 'Invalid object model: invalid self dxn');
+    return object[SelfDXNId];
+  }
+
+  if (!ObjectId.isValid(object.id)) {
+    throw new TypeError('Object id is not valid.');
+  }
+
+  return DXN.fromLocalObjectId(object.id);
+};

package/src/internal/formats/date.test.ts

@@ -0,0 +1,56 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+import { describe, expect, test } from 'vitest';
+
+import { log } from '@dxos/log';
+
+import { toJsonSchema } from '../json-schema';
+
+import {
+  DateOnly,
+  DateTime,
+  type SimpleDate,
+  type SimpleDateTime,
+  type SimpleTime,
+  TimeOnly,
+  toSimpleDate,
+  toSimpleTime,
+} from './date';
+
+describe.skip('date', () => {
+  test('basic', () => {
+    const date = new Date('2024-12-31T23:59:59Z');
+    expect(toSimpleDate(date)).to.deep.eq({ year: 2024, month: 12, day: 31 });
+    expect(toSimpleTime(date)).to.deep.eq({ hours: 23, minutes: 59, seconds: 59 });
+  });
+
+  test('Date', ({ expect }) => {
+    const jsonSchema = toJsonSchema(DateOnly);
+    log('schema', { jsonSchema });
+    const v1: SimpleDate = { year: 1999, month: 12, day: 31 };
+    const str = Schema.encodeUnknownSync(DateOnly)(v1);
+    const v2 = Schema.decodeUnknownSync(DateOnly)(str);
+    expect(v1).to.deep.eq(v2);
+  });
+
+  test('Time', ({ expect }) => {
+    const jsonSchema = toJsonSchema(TimeOnly);
+    log('schema', { jsonSchema });
+    const v1: SimpleTime = { hours: 23, minutes: 59, seconds: 59 };
+    const str = Schema.encodeUnknownSync(TimeOnly)(v1);
+    const v2 = Schema.decodeUnknownSync(TimeOnly)(str);
+    expect(v1).to.deep.eq(v2);
+  });
+
+  test('DateTime', ({ expect }) => {
+    const jsonSchema = toJsonSchema(DateTime);
+    log('schema', { jsonSchema });
+    const v1: SimpleDateTime = { year: 1999, month: 12, day: 31, hours: 23, minutes: 59, seconds: 59 };
+    const str = Schema.encodeUnknownSync(DateTime)(v1);
+    const v2 = Schema.decodeUnknownSync(DateTime)(str);
+    expect(v1).to.deep.eq(v2);
+  });
+});

package/src/internal/formats/date.ts

@@ -0,0 +1,217 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+import * as SchemaAST from 'effect/SchemaAST';
+
+import { FormatAnnotation, TypeFormat } from './types';
+
+/**
+ * Datetime values should be stored as ISO strings or unix numbers (ms) in UTC.
+ *
+ * NOTE: HyperFormula uses Excel's time format (null date 1900/01/01)
+ * It can be configured to use a different parser via `parseDateTime`.
+ * https://hyperformula.handsontable.com/guide/date-and-time-handling.html#date-and-time-handling
+ * https://github.com/handsontable/hyperformula/blob/master/src/DateTimeHelper.ts
+ */
+
+// TODO(burdon): Annotations not present in JSON.
+// TODO(burdon): Timezone.
+// TODO(burdon): Format for timestamp (Unix UTC or ISO 8601)?
+// TODO(burdon): Refs
+//  - https://www.npmjs.com/package/numfmt
+//  - https://date-fns.org/docs/Getting-Started
+//  - https://github.com/date-fns/tz
+
+/**
+ * Simple date compatible with HF.
+ */
+export const SimpleDate = Schema.Struct({
+  year: Schema.Number.pipe(Schema.between(1900, 9999)),
+  month: Schema.Number.pipe(Schema.between(1, 12)),
+  day: Schema.Number.pipe(Schema.between(1, 31)),
+});
+
+export type SimpleDate = Schema.Schema.Type<typeof SimpleDate>;
+
+export const toSimpleDate = (date: Date): SimpleDate => ({
+  year: date.getUTCFullYear(),
+  month: date.getUTCMonth() + 1,
+  day: date.getUTCDate(),
+});
+
+/**
+ * Simple time compatible with HF.
+ */
+export const SimpleTime = Schema.Struct({
+  hours: Schema.Number.pipe(Schema.between(0, 23)),
+  minutes: Schema.Number.pipe(Schema.between(0, 59)),
+  seconds: Schema.Number.pipe(Schema.between(0, 59)),
+});
+
+export type SimpleTime = Schema.Schema.Type<typeof SimpleTime>;
+
+export const toSimpleTime = (date: Date): SimpleTime => ({
+  hours: date.getUTCHours(),
+  minutes: date.getUTCSeconds(),
+  seconds: date.getUTCSeconds(),
+});
+
+/**
+ * Simple date-time compatible with HF.
+ */
+export const SimpleDateTime = Schema.extend(SimpleDate, SimpleTime);
+
+export type SimpleDateTime = Schema.Schema.Type<typeof SimpleDateTime>;
+
+export const toSimpleDateTime = (date: Date): SimpleDateTime => ({
+  ...toSimpleDate(date),
+  ...toSimpleTime(date),
+});
+
+/**
+ * https://effect.website/docs/guides/schema/transformations#date-transformations
+ */
+
+// TODO(burdon): Consider if transformations should be supported with Automerge.
+
+/**
+ * Format: 2018-11-13
+ */
+export const DateOnly = /* Schema.transformOrFail(Schema.String, SimpleDate, {
+  strict: true,
+  decode: (str, _, ast) => {
+    if (!isValidDateFormat(str)) {
+      return ParseResult.fail(new ParseResult.Type(ast, str, 'Expected YYYY-MM-DD format'));
+    }
+    if (!isValidDate(str)) {
+      return ParseResult.fail(new ParseResult.Type(ast, str, 'Invalid date'));
+    }
+
+    const [year, month, day] = str.split('-').map(Number);
+    return ParseResult.succeed({ year, month, day });
+  },
+  encode: (date) => {
+    return ParseResult.succeed(
+      [
+        date.year.toString().padStart(4, '0'),
+        date.month.toString().padStart(2, '0'),
+        date.day.toString().padStart(2, '0'),
+      ].join('-'),
+    );
+  },
+}) */ Schema.String.pipe(
+  FormatAnnotation.set(TypeFormat.Date),
+  Schema.annotations({
+    title: 'Date',
+    description: 'Valid date in ISO format',
+  }),
+);
+
+/**
+ * Format: 20:20:39+00:00
+ */
+export const TimeOnly = /* Schema.transformOrFail(Schema.String, SimpleTime, {
+  strict: true,
+  decode: (str, _, ast) => {
+    if (!isValidTimeFormat(str)) {
+      return ParseResult.fail(new ParseResult.Type(ast, str, 'Expected HH:mm:ss format'));
+    }
+
+    const [hours, minutes, seconds] = str.split(':').map(Number);
+    return ParseResult.succeed({ hours, minutes, seconds });
+  },
+  encode: (time) => {
+    return ParseResult.succeed(
+      [
+        time.hours.toString().padStart(2, '0'),
+        time.minutes.toString().padStart(2, '0'),
+        time.seconds.toString().padStart(2, '0'),
+      ].join(':'),
+    );
+  },
+}) */ Schema.String.pipe(
+  FormatAnnotation.set(TypeFormat.Time),
+  Schema.annotations({
+    title: 'Time',
+    description: 'Valid time in ISO format',
+  }),
+);
+
+/**
+ * Format: 2018-11-13T20:20:39+00:00
+ */
+export const DateTime = /* Schema.transformOrFail(Schema.String, SimpleDateTime, {
+  strict: false,
+  decode: (str, _, ast) => {
+    const [date, time] = str.split('T');
+    if (!isValidDateFormat(date)) {
+      return ParseResult.fail(new ParseResult.Type(ast, date, 'Expected YYYY-MM-DD format'));
+    }
+    if (!isValidDate(date)) {
+      return ParseResult.fail(new ParseResult.Type(ast, date, 'Invalid date'));
+    }
+    if (!isValidTimeFormat(time)) {
+      return ParseResult.fail(new ParseResult.Type(ast, str, 'Expected HH:mm:ss format'));
+    }
+
+    const [year, month, day] = date.split('-').map(Number);
+    const [hours, minutes, seconds] = time.split(':').map(Number);
+    return ParseResult.succeed({ year, month, day, hours, minutes, seconds });
+  },
+  encode: (datetime) => {
+    return ParseResult.succeed(
+      [
+        [
+          datetime.year.toString().padStart(4, '0'),
+          datetime.month.toString().padStart(2, '0'),
+          datetime.day.toString().padStart(2, '0'),
+        ].join('-'),
+        [
+          datetime.hours.toString().padStart(2, '0'),
+          datetime.minutes.toString().padStart(2, '0'),
+          datetime.seconds.toString().padStart(2, '0'),
+        ].join(':'),
+      ].join('T'),
+    );
+  },
+}) */ Schema.String.pipe(
+  FormatAnnotation.set(TypeFormat.DateTime),
+  Schema.annotations({
+    title: 'DateTime',
+    description: 'Valid date and time in ISO format',
+  }),
+);
+
+/**
+ * https://datatracker.ietf.org/doc/html/rfc3339#appendix-A
+ */
+// TODO(burdon): Define duration type.
+export const Duration = Schema.String.pipe(
+  FormatAnnotation.set(TypeFormat.Duration),
+  Schema.annotations({
+    title: 'Duration',
+    description: 'Duration in ISO 8601 format',
+    [SchemaAST.ExamplesAnnotationId]: ['1h', '3D'],
+  }),
+);
+
+//
+// Utils
+//
+
+// YYYY-MM-DD
+const DATE_REGEX = /^\d{4}-\d{2}-\d{2}$/;
+
+const _isValidDateFormat = (str: string) => DATE_REGEX.test(str);
+
+const _isValidDate = (str: string) => {
+  const date = new Date(str);
+  return !isNaN(date.getTime()) && date.toISOString().startsWith(str);
+};
+
+// HH:mm:ss
+const TIME_REGEX = /^([01]\d|2[0-3]):([0-5]\d):([0-5]\d)$/;
+
+const _isValidTimeFormat = (str: string) => TIME_REGEX.test(str);