@dxos/echo 0.8.4-main.dedc0f3 → 0.8.4-main.e00bdcdb52

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/Format/date.test.ts

@@ -0,0 +1,55 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+import { describe, expect, test } from 'vitest';
+
+import { log } from '@dxos/log';
+
+import { toJsonSchema } from '../JsonSchema';
+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/Format/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);

package/src/internal/Format/format.test.ts

@@ -0,0 +1,76 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+import { describe, test } from 'vitest';
+
+import { toJsonSchema } from '../JsonSchema';
+import { Format } from './format';
+import { TypeEnum, TypeFormat, getTypeEnum } from './types';
+
+describe('formats', () => {
+  test('annotations', ({ expect }) => {
+    const TestSchema = Schema.Struct({
+      name: Schema.String,
+      email: Schema.optional(Format.Email),
+      salary: Schema.optional(Format.Currency({ decimals: 2, code: 'usd' })),
+      website: Schema.optional(Format.URL),
+      birthday: Schema.optional(Format.Date),
+      started: Schema.optional(Format.DateTime),
+      active: Schema.optional(Schema.Boolean),
+    });
+
+    type TestType = Schema.Schema.Type<typeof TestSchema>;
+
+    const jsonSchema = toJsonSchema(TestSchema);
+
+    const data: TestType = {
+      name: 'Alice',
+      email: 'alice@example.com',
+      birthday: '1999-06-11',
+    };
+
+    const validate = Schema.validateSync(TestSchema);
+    validate(data);
+
+    {
+      const prop = jsonSchema.properties!['active' as const];
+      expect(getTypeEnum(prop)).to.eq(TypeEnum.Boolean);
+      expect(prop).includes({
+        type: TypeEnum.Boolean,
+      });
+    }
+
+    {
+      const prop = jsonSchema.properties!['email' as const];
+      expect(getTypeEnum(prop)).to.eq(TypeEnum.String);
+      expect(prop).includes({
+        type: TypeEnum.String,
+        format: TypeFormat.Email,
+        title: 'Email',
+      });
+    }
+
+    {
+      const prop = jsonSchema.properties!['salary' as const];
+      expect(getTypeEnum(prop)).to.eq(TypeEnum.Number);
+      expect(prop).includes({
+        type: TypeEnum.Number,
+        format: TypeFormat.Currency,
+        title: 'Currency',
+        multipleOf: 0.01,
+        currency: 'USD',
+      });
+    }
+
+    {
+      const prop = jsonSchema.properties!['birthday' as const];
+      expect(getTypeEnum(prop)).to.eq(TypeEnum.String);
+      expect(prop).includes({
+        type: TypeEnum.String,
+        format: TypeFormat.Date,
+      });
+    }
+  });
+});

package/src/internal/Format/format.ts

@@ -0,0 +1,54 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+
+import * as Keys from '@dxos/keys';
+
+import * as DateUtil from './date';
+import * as NumberUtil from './number';
+import * as ObjectUtil from './object';
+import * as StringUtil from './string';
+import { TypeFormat as TypeFormat$ } from './types';
+
+// TODO(burdon): Media encoding.
+// - https://json-schema.org/understanding-json-schema/reference/non_json_data
+
+/**
+ * Formats.
+ * https://json-schema.org/understanding-json-schema/reference/string#built-in-formats
+ * NOTE: A JSON Schema validator will ignore any format type that it does not understand.
+ */
+// TODO(burdon): Add fields for `examples`, `message`, etc.
+export namespace Format {
+  export import TypeFormat = TypeFormat$;
+
+  // String
+  export const DXN = Keys.DXN.Schema;
+  export const Email = StringUtil.Email;
+  export const Formula = StringUtil.Formula;
+  export const Hostname = StringUtil.Hostname;
+  export const JSON = StringUtil.JSON;
+  export const Markdown = StringUtil.Markdown;
+  export const Regex = StringUtil.Regex;
+  export const URL = StringUtil.URL;
+  export const UUID = Schema.UUID;
+
+  // Numbers
+  // TODO(burdon): BigInt.
+  export const Currency = NumberUtil.Currency;
+  export const Integer = NumberUtil.Integer;
+  export const Percent = NumberUtil.Percent;
+  export const Timestamp = NumberUtil.Timestamp;
+
+  // Dates and times
+  export const Date = DateUtil.DateOnly;
+  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; // TODO(burdon): Export types.
+}

package/src/internal/Format/index.ts

@@ -0,0 +1,12 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export type { SimpleDate, SimpleDateTime, SimpleTime } from './date';
+export { CurrencyAnnotationId, DecimalPrecision, Currency } from './number';
+export { GeoPoint, GeoLocation } from './object';
+
+export * from './format';
+export * from './select';
+export * from './string';
+export * from './types';

package/src/internal/Format/number.ts

@@ -0,0 +1,89 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+
+import { FormatAnnotation, TypeFormat } from './types';
+
+const encodeMultipleOf = (divisor: number) => 1 / Math.pow(10, divisor);
+
+const encodeMultiple =
+  <A extends number>(divisor?: number) =>
+  <I, R>(self: Schema.Schema<A, I, R>) =>
+    divisor === undefined || divisor === 0 ? self : self.pipe(Schema.multipleOf(encodeMultipleOf(divisor)));
+
+/**
+ * Convert number of digits to multipleOf annotation.
+ */
+export const DecimalPrecision = Schema.transform(Schema.Number, Schema.Number, {
+  strict: true,
+  encode: (value) => encodeMultipleOf(value),
+  decode: (value) => Math.log10(1 / value),
+}).annotations({
+  title: 'Number of digits',
+});
+
+export const CurrencyAnnotationId = Symbol.for('@dxos/schema/annotation/Currency');
+
+export type CurrencyAnnotation = {
+  decimals?: number;
+  code?: string;
+};
+
+/**
+ * ISO 4217 currency code.
+ */
+export const Currency = ({ decimals, code }: CurrencyAnnotation = { decimals: 2 }) =>
+  Schema.Number.pipe(
+    encodeMultiple(decimals),
+    FormatAnnotation.set(TypeFormat.Currency),
+    Schema.annotations({
+      title: 'Currency',
+      description: 'Currency value',
+      ...(code ? { [CurrencyAnnotationId]: code.toUpperCase() } : {}),
+    }),
+  );
+
+export type PercentAnnotation = {
+  decimals?: number;
+};
+
+/**
+ * Integer.
+ */
+export const Integer = () =>
+  Schema.Number.pipe(
+    Schema.int(),
+    FormatAnnotation.set(TypeFormat.Integer),
+    Schema.annotations({
+      title: 'Integer',
+      description: 'Integer value',
+    }),
+  );
+
+/**
+ * Percent.
+ */
+// TODO(burdon): Define min/max (e.g., 0, 1).
+export const Percent = ({ decimals }: PercentAnnotation = { decimals: 2 }) =>
+  Schema.Number.pipe(
+    encodeMultiple(decimals),
+    FormatAnnotation.set(TypeFormat.Percent),
+    Schema.annotations({
+      title: 'Percent',
+      description: 'Percentage value',
+    }),
+  );
+
+/**
+ * Unix timestamp.
+ * https://en.wikipedia.org/wiki/Unix_time
+ */
+export const Timestamp = Schema.Number.pipe(
+  FormatAnnotation.set(TypeFormat.Timestamp),
+  Schema.annotations({
+    title: 'Timestamp',
+    description: 'Unix timestamp',
+  }),
+);

package/src/internal/Format/object.ts

@@ -0,0 +1,80 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+
+import { clamp } from '@dxos/util';
+
+import { FormatAnnotation, TypeFormat } from './types';
+
+/**
+ * GeoJSON Format
+ * https://datatracker.ietf.org/doc/html/rfc7946
+ * https://datatracker.ietf.org/doc/html/rfc7946#section-3.1.1
+ * https://en.wikipedia.org/wiki/Geographic_coordinate_system
+ * https://geojson.org
+ * {
+ *   "type": "Point",
+ *   "coordinates": [0, 51.47] // [longitude, latitude]
+ * }
+ * 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.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)',
+  }),
+).pipe(
+  FormatAnnotation.set(TypeFormat.GeoPoint),
+  Schema.annotations({
+    title: 'GeoPoint',
+    description: 'GeoJSON Position',
+  }),
+);
+
+export type GeoPoint = Schema.Schema.Type<typeof GeoPoint>;
+
+export type GeoLocation = {
+  longitude: number;
+  latitude: number;
+  height?: number;
+};
+
+/**
+ * Geolocation utilities for working with GeoPoint format.
+ */
+export namespace GeoLocation {
+  /**
+   * Convert latitude and longitude to GeoPoint (GeoJSON format [longitude, latitude, height?]).
+   * Clamps values to valid ranges: latitude [-90, 90], longitude [-180, 180].
+   */
+  export const toGeoPoint = ({ longitude, latitude, height }: GeoLocation): GeoPoint => {
+    // TODO(ZaymonFC): Use schema validation instead of doing this manually.
+    const clampedLongitude = clamp(longitude, -180, 180);
+    const clampedLatitude = clamp(latitude, -90, 90);
+    return height !== undefined ? [clampedLongitude, clampedLatitude, height] : [clampedLongitude, clampedLatitude];
+  };
+
+  /**
+   * Extract latitude and longitude from GeoPoint (GeoJSON format [longitude, latitude, height?]).
+   */
+  export const fromGeoPoint = (geoPoint: GeoPoint | undefined): GeoLocation => {
+    if (!geoPoint) {
+      return { longitude: 0, latitude: 0 };
+    }
+
+    const result: GeoLocation = {
+      longitude: geoPoint[0],
+      latitude: geoPoint[1],
+    };
+
+    // Add height if defined.
+    if (geoPoint[2] !== undefined) {
+      result.height = geoPoint[2];
+    }
+
+    return result;
+  };
+}

package/src/internal/Format/select.ts

@@ -0,0 +1,18 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+
+/**
+ * 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,
+});
+
+export type SelectOption = Schema.Schema.Type<typeof SelectOption>;