@dxos/echo 0.8.4-main.5ea62a8 → 0.8.4-main.72ec0f3

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';
+
+import { Format } from './format';
+import { FormatEnum, TypeEnum, 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: FormatEnum.Email,
+        title: 'Email',
+      });
+    }
+
+    {
+      const prop = jsonSchema.properties!['salary' as const];
+      expect(getTypeEnum(prop)).to.eq(TypeEnum.Number);
+      expect(prop).includes({
+        type: TypeEnum.Number,
+        format: FormatEnum.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: FormatEnum.Date,
+      });
+    }
+  });
+});

package/src/internal/formats/format.ts

@@ -0,0 +1,52 @@
+//
+// 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';
+
+// 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 {
+  // 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, FormatEnum } 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(FormatEnum.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(FormatEnum.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(FormatEnum.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(FormatEnum.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, FormatEnum } 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(FormatEnum.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, FormatEnum } 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(FormatEnum.Email),
+  Schema.annotations({
+    title: 'Email',
+    description: 'Email address',
+  }),
+);
+
+/**
+ *
+ */
+// TODO(burdon): Implement.
+export const Formula = Schema.String.pipe(FormatAnnotation.set(FormatEnum.Formula));
+
+/**
+ *
+ */
+// TODO(burdon): Implement.
+export const Hostname = Schema.String.pipe(FormatAnnotation.set(FormatEnum.Hostname));
+
+/**
+ *
+ */
+// TODO(burdon): Implement.
+export const JSON = Schema.String.pipe(FormatAnnotation.set(FormatEnum.JSON));
+
+/**
+ *
+ */
+// TODO(burdon): Implement.
+export const Markdown = Schema.String.pipe(FormatAnnotation.set(FormatEnum.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(FormatEnum.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(FormatEnum.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(FormatEnum.UUID),
+  Schema.annotations({
+    [SchemaAST.ExamplesAnnotationId]: ['3e4666bf-d5e5-4aa7-b8ce-cefe41c7568a'],
+  }),
+);

package/src/internal/formats/types.ts

@@ -0,0 +1,175 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import * as Function from 'effect/Function';
+import type * as JSONSchema from 'effect/JSONSchema';
+import * as Option from 'effect/Option';
+import * as SchemaAST from 'effect/SchemaAST';
+
+import { createAnnotationHelper } from '../ast';
+import { type JsonSchemaType } from '../json-schema';
+
+// TODO(burdon): Rename PropertyType.
+export type ScalarType =
+  | JSONSchema.JsonSchema7Object
+  | JSONSchema.JsonSchema7String
+  | JSONSchema.JsonSchema7Number
+  | JSONSchema.JsonSchema7Boolean
+  | JSONSchema.JsonSchema7Ref;
+
+// TODO(burdon): Rename ValueType and change to disciminated union.
+// export type ValueType = 'array' | 'object' | 'string' | 'number' | 'boolean' | 'ref';
+export enum TypeEnum {
+  Array = 'array', // TODO(burdon): Remove?
+  Object = 'object',
+  String = 'string',
+  Number = 'number',
+  Boolean = 'boolean',
+  Ref = 'ref',
+}
+
+// TODO(burdon): Ref?
+export const getTypeEnum = (property: JsonSchemaType): TypeEnum | undefined => {
+  switch (property.type) {
+    case 'array':
+      return TypeEnum.Array;
+    case 'object':
+      return TypeEnum.Object;
+    case 'string':
+      return TypeEnum.String;
+    case 'number':
+      return TypeEnum.Number;
+    case 'boolean':
+      return TypeEnum.Boolean;
+    default:
+      return undefined;
+  }
+};
+
+/**
+ * https://json-schema.org/understanding-json-schema/reference/schema
+ * https://json-schema.org/understanding-json-schema/reference/string#built-in-formats
+ */
+export const FormatAnnotationId = Symbol.for('@dxos/schema/annotation/Format');
+
+export const FormatAnnotation = createAnnotationHelper<FormatEnum>(FormatAnnotationId);
+
+export const getFormatAnnotation = (node: SchemaAST.AST): FormatEnum | undefined =>
+  Function.pipe(SchemaAST.getAnnotation<FormatEnum>(FormatAnnotationId)(node), Option.getOrUndefined);
+
+// TODO(burdon): Rename to FormatType and change to discriminated union.
+export enum FormatEnum {
+  None = 'none',
+  String = 'string',
+  Number = 'number',
+  Boolean = 'boolean',
+  Ref = 'ref',
+
+  //
+  // { type: 'string' }
+  //
+
+  DID = 'did', // Users, etc.
+  DXN = 'dxn',
+  Email = 'email',
+  Formula = 'formula', // Spreadsheet formula.
+  Hostname = 'hostname',
+  JSON = 'json',
+  Markdown = 'markdown',
+  Regex = 'regex',
+  SingleSelect = 'single-select',
+  MultiSelect = 'multi-select',
+  URL = 'url',
+  UUID = 'uuid',
+
+  //
+  // { type: 'number' }
+  //
+
+  Currency = 'currency',
+  Integer = 'integer',
+  Percent = 'percent',
+  Timestamp = 'timestamp',
+
+  //
+  // { type: 'date' }
+  //
+
+  DateTime = 'date-time',
+  Date = 'date',
+  Time = 'time',
+  Duration = 'duration',
+
+  //
+  // { type: 'object' }
+  //
+
+  GeoPoint = 'lnglat',
+}
+
+export const FormatEnums = Object.values(FormatEnum).sort();
+
+export const PropertyKind = {
+  type: TypeEnum,
+  format: FormatEnum,
+};
+
+/**
+ * Default formats
+ */
+export const typeToFormat: Partial<Record<TypeEnum, FormatEnum>> = {
+  [TypeEnum.String]: FormatEnum.String,
+  [TypeEnum.Number]: FormatEnum.Number,
+  [TypeEnum.Boolean]: FormatEnum.Boolean,
+};
+
+/**
+ * Map of format to type.
+ */
+export const formatToType: Record<FormatEnum, TypeEnum> = {
+  [FormatEnum.None]: undefined as any,
+  [FormatEnum.String]: TypeEnum.String,
+  [FormatEnum.Number]: TypeEnum.Number,
+  [FormatEnum.Boolean]: TypeEnum.Boolean,
+  [FormatEnum.Ref]: TypeEnum.Ref,
+
+  // Strings
+  [FormatEnum.DID]: TypeEnum.String,
+  [FormatEnum.DXN]: TypeEnum.String,
+  [FormatEnum.Email]: TypeEnum.String,
+  [FormatEnum.Formula]: TypeEnum.String,
+  [FormatEnum.Hostname]: TypeEnum.String,
+  [FormatEnum.JSON]: TypeEnum.String,
+  [FormatEnum.Markdown]: TypeEnum.String,
+  [FormatEnum.Regex]: TypeEnum.String,
+  [FormatEnum.URL]: TypeEnum.String,
+  [FormatEnum.UUID]: TypeEnum.String,
+  [FormatEnum.SingleSelect]: TypeEnum.String,
+  [FormatEnum.MultiSelect]: TypeEnum.Object,
+
+  // Dates
+  [FormatEnum.Date]: TypeEnum.String,
+  [FormatEnum.DateTime]: TypeEnum.String,
+  [FormatEnum.Duration]: TypeEnum.String,
+  [FormatEnum.Time]: TypeEnum.String,
+
+  // Numbers
+  [FormatEnum.Currency]: TypeEnum.Number,
+  [FormatEnum.Integer]: TypeEnum.Number,
+  [FormatEnum.Percent]: TypeEnum.Number,
+  [FormatEnum.Timestamp]: TypeEnum.Number,
+
+  // Objects
+  [FormatEnum.GeoPoint]: TypeEnum.Array,
+};
+
+/**
+ * Allowed value options for select.
+ */
+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);
+
+export type OptionsAnnotationType = string | number;

package/src/internal/index.ts

@@ -0,0 +1,22 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+export { JsonPath, splitJsonPath, JsonProp } from '@dxos/effect';
+
+// TODO(dmaretskyi): Remove.
+export { ObjectId } from '@dxos/keys';
+export { ForeignKey } from '@dxos/echo-protocol';
+
+export * from './ast';
+export * from './formats';
+export * from './json';
+export * from './json-schema';
+export * from './object';
+export * from './types';
+export { defineHiddenProperty } from '@dxos/live-object';
+export * from './projection';
+// TODO(dmaretskyi): Remove
+export { live } from './proxy/reactive-object';
+export * from './ref';
+export * from './schema';

package/src/internal/json/annotations.ts

@@ -0,0 +1,50 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as SchemaAST from 'effect/SchemaAST';
+
+import { GeneratorAnnotationId, LabelAnnotationId, PropertyMetaAnnotationId } from '../ast';
+import { CurrencyAnnotationId, FormatAnnotationId } from '../formats';
+import { type JsonSchemaEchoAnnotations, type JsonSchemaType } from '../json-schema';
+
+//
+// This file configures annotations for JSON encoding/decoding.
+//
+
+// Go on the root level.
+type RootJsonSchemaProperty = keyof JsonSchemaType;
+
+// Go on the namespaced `annotations` property.
+type NamespacedJsonSchemaProperty = keyof JsonSchemaEchoAnnotations;
+
+/**
+ * List of annotations for JSON encoding/decoding.
+ * Omits default effect-schema annotations since they are encoded with default serializer.
+ */
+// TODO(burdon): Reconcile with `EchoAnnotations`.
+export const CustomAnnotations: Partial<Record<RootJsonSchemaProperty, symbol>> = {
+  format: FormatAnnotationId,
+  currency: CurrencyAnnotationId,
+};
+
+/**
+ * List of annotations for JSON decoding only.
+ * Includes default effect annotations.
+ */
+export const DecodedAnnotations: Partial<Record<RootJsonSchemaProperty, symbol>> = {
+  title: SchemaAST.TitleAnnotationId,
+  description: SchemaAST.DescriptionAnnotationId,
+};
+
+/**
+ * Annotations that go into ECHO namespace in json-schema.
+ */
+// TODO(dmaretskyi): Consider removing ECHO namespace and putting them at the top level.
+// TODO(dmaretskyi): Move to format.ts when circular imports are solved
+export const EchoAnnotations: Partial<Record<NamespacedJsonSchemaProperty, symbol>> = {
+  // TODO(dmaretskyi): `FieldLookupAnnotationId` might go here, but lets remove it entirely and use LabelAnnotation instead.
+  meta: PropertyMetaAnnotationId,
+  generator: GeneratorAnnotationId,
+  labelProp: LabelAnnotationId,
+};