@dxos/echo 0.8.4-main.5ea62a8 → 0.8.4-main.66e292d

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);

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

@@ -0,0 +1,77 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+import { describe, test } from 'vitest';
+
+import { toJsonSchema } from '../json-schema';
+
+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),
+    }).pipe(Schema.mutable);
+
+    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/formats/format.ts

@@ -0,0 +1,55 @@
+//
+// 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 TypeFormatEnum } 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
+
+/**
+ * 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 = TypeFormatEnum;
+
+  // Strings
+  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 DateTime = DateUtil.DateTime;
+  export const Date = DateUtil.DateOnly;
+  export const Time = DateUtil.TimeOnly;
+  export const Duration = DateUtil.Duration;
+
+  // Objects
+  export const GeoPoint = ObjectUtil.GeoPoint;
+  export type GeoPoint = ObjectUtil.GeoPoint;
+}

package/src/internal/formats/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/formats/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/formats/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.00001)),
+  Schema.Number.pipe(Schema.annotations({ title: 'Latitude' }), Schema.clamp(-90, 90), Schema.multipleOf(0.00001)),
+  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/formats/select.ts

@@ -0,0 +1,16 @@
+//
+// 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 SelectOptionSchema = 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>;

package/src/internal/formats/string.ts

@@ -0,0 +1,76 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+import * as SchemaAST from 'effect/SchemaAST';
+
+import { FormatAnnotation, TypeFormat } from './types';
+
+/**
+ * Email address (RFC 5321)
+ * https://datatracker.ietf.org/doc/html/rfc5321#section-4.1.2
+ */
+export const Email = Schema.String.pipe(
+  Schema.pattern(/^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$/),
+  FormatAnnotation.set(TypeFormat.Email),
+  Schema.annotations({
+    title: 'Email',
+    description: 'Email address',
+  }),
+);
+
+/**
+ *
+ */
+// TODO(burdon): Implement.
+export const Formula = Schema.String.pipe(FormatAnnotation.set(TypeFormat.Formula));
+
+/**
+ *
+ */
+// TODO(burdon): Implement.
+export const Hostname = Schema.String.pipe(FormatAnnotation.set(TypeFormat.Hostname));
+
+/**
+ *
+ */
+// TODO(burdon): Implement.
+export const JSON = Schema.String.pipe(FormatAnnotation.set(TypeFormat.JSON));
+
+/**
+ *
+ */
+// TODO(burdon): Implement.
+export const Markdown = Schema.String.pipe(FormatAnnotation.set(TypeFormat.Markdown));
+
+/**
+ * Regex
+ * https://json-schema.org/understanding-json-schema/reference/regular_expressions
+ * https://ecma-international.org/publications-and-standards/standards/ecma-262
+ */
+// TODO(burdon): Implement.
+export const Regex = Schema.String.pipe(FormatAnnotation.set(TypeFormat.Regex));
+
+/**
+ * https://datatracker.ietf.org/doc/html/rfc3986#section-1.1.3
+ */
+export const URL = Schema.String.pipe(
+  Schema.pattern(/^(\w+?:\/\/)?([\da-z.-]+)\.([a-z.]{2,6})([/\w .-]*)*\/?$/i),
+  FormatAnnotation.set(TypeFormat.URL),
+  Schema.annotations({
+    title: 'URL',
+    description: 'URL',
+  }),
+);
+
+/**
+ * UUID (RFC 4122)
+ * https://datatracker.ietf.org/doc/html/rfc4122
+ */
+export const UUID = Schema.UUID.pipe(
+  FormatAnnotation.set(TypeFormat.UUID),
+  Schema.annotations({
+    [SchemaAST.ExamplesAnnotationId]: ['3e4666bf-d5e5-4aa7-b8ce-cefe41c7568a'],
+  }),
+);