@dxos/echo 0.8.4-main.e098934 → 0.8.4-main.ead640a

package/src/internal/ast/annotations.ts

@@ -0,0 +1,219 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import * as Function from 'effect/Function';
+import * as Option from 'effect/Option';
+import * as Schema from 'effect/Schema';
+import * as SchemaAST from 'effect/SchemaAST';
+
+import { assertArgument } from '@dxos/invariant';
+import { DXN } from '@dxos/keys';
+import { type Primitive } from '@dxos/util';
+
+import { createAnnotationHelper } from './annotation-helper';
+import { EntityKind } from './entity-kind';
+
+/**
+ * If property is optional returns the nested property, otherwise returns the property.
+ */
+// TODO(wittjosiah): Is there a way to do this as a generic?
+export const unwrapOptional = (property: SchemaAST.PropertySignature) => {
+  if (!property.isOptional || !SchemaAST.isUnion(property.type)) {
+    return property;
+  }
+
+  return property.type.types[0];
+};
+
+/**
+ * ECHO identifier (for a stored schema).
+ * Must be a `dxn:echo:` URI.
+ */
+export const TypeIdentifierAnnotationId = Symbol.for('@dxos/schema/annotation/TypeIdentifier');
+
+export const getTypeIdentifierAnnotation = (schema: Schema.Schema.All) =>
+  Function.flow(
+    SchemaAST.getAnnotation<string>(TypeIdentifierAnnotationId),
+    Option.getOrElse(() => undefined),
+  )(schema.ast);
+
+/**
+ * ECHO type.
+ */
+export const TypeAnnotationId = Symbol.for('@dxos/schema/annotation/Type');
+
+// TODO(burdon): Create echo-schema Format types.
+// TODO(burdon): Reconcile with "short" DXN.
+export const Typename = Schema.String.pipe(Schema.pattern(/^[a-zA-Z]\w+\.[a-zA-Z]\w{1,}\/[\w/_-]+$/));
+export const SchemaVersion = Schema.String.pipe(Schema.pattern(/^\d+.\d+.\d+$/));
+
+/**
+ * Payload stored under {@link TypeAnnotationId}.
+ */
+// TODO(dmaretskyi): Rename getTypeAnnotation to represent commonality between objects and relations (e.g. `entity`).
+export const TypeAnnotation = Schema.Struct({
+  kind: Schema.Enums(EntityKind),
+  typename: Typename,
+  version: SchemaVersion,
+
+  /**
+   * If this is a relation, the schema of the source object.
+   * Must be present if entity kind is {@link EntityKind.Relation}.
+   */
+  sourceSchema: Schema.optional(DXN.Schema),
+
+  /**
+   * If this is a relation, the schema of the target object.
+   * Must be present if entity kind is {@link EntityKind.Relation}.
+   */
+  targetSchema: Schema.optional(DXN.Schema),
+});
+
+export interface TypeAnnotation extends Schema.Schema.Type<typeof TypeAnnotation> {}
+
+export type TypeMeta = Pick<TypeAnnotation, 'typename' | 'version'>;
+
+/**
+ * @returns {@link TypeAnnotation} from a schema.
+ * Schema must have been created with {@link TypedObject} or {@link TypedLink} or manually assigned an appropriate annotation.
+ */
+export const getTypeAnnotation = (schema: Schema.Schema.All): TypeAnnotation | undefined => {
+  assertArgument(schema != null && schema.ast != null, 'schema', 'invalid schema');
+  return Function.flow(
+    SchemaAST.getAnnotation<TypeAnnotation>(TypeAnnotationId),
+    Option.getOrElse(() => undefined),
+  )(schema.ast);
+};
+
+/**
+ * @returns {@link EntityKind} from a schema.
+ */
+export const getEntityKind = (schema: Schema.Schema.All): EntityKind | undefined => getTypeAnnotation(schema)?.kind;
+
+/**
+ * @deprecated Use {@link Type.getTypename} instead.
+ * @returns Schema typename (without dxn: prefix or version number).
+ */
+export const getSchemaTypename = (schema: Schema.Schema.All): string | undefined => getTypeAnnotation(schema)?.typename;
+
+/**
+ * @deprecated Use {@link Type.getVersion} instead.
+ * @returns Schema version in semver format.
+ */
+export const getSchemaVersion = (schema: Schema.Schema.All): string | undefined => getTypeAnnotation(schema)?.version;
+
+/**
+ * PropertyMeta (metadata for dynamic schema properties).
+ * For user-defined annotations.
+ */
+export const PropertyMetaAnnotationId = Symbol.for('@dxos/schema/annotation/PropertyMeta');
+
+export type PropertyMetaValue = Primitive | Record<string, Primitive> | Primitive[];
+
+export type PropertyMetaAnnotation = {
+  [name: string]: PropertyMetaValue;
+};
+
+export const PropertyMeta = (name: string, value: PropertyMetaValue) => {
+  return <A, I, R>(self: Schema.Schema<A, I, R>): Schema.Schema<A, I, R> => {
+    const existingMeta = self.ast.annotations[PropertyMetaAnnotationId] as PropertyMetaAnnotation;
+    return self.annotations({
+      [PropertyMetaAnnotationId]: {
+        ...existingMeta,
+        [name]: value,
+      },
+    });
+  };
+};
+
+export const getPropertyMetaAnnotation = <T>(prop: SchemaAST.PropertySignature, name: string) =>
+  Function.pipe(
+    SchemaAST.getAnnotation<PropertyMetaAnnotation>(PropertyMetaAnnotationId)(prop.type),
+    Option.map((meta) => meta[name] as T),
+    Option.getOrElse(() => undefined),
+  );
+
+/**
+ * Schema reference.
+ */
+export const ReferenceAnnotationId = Symbol.for('@dxos/schema/annotation/Reference');
+
+export type ReferenceAnnotationValue = TypeAnnotation;
+
+export const getReferenceAnnotation = (schema: Schema.Schema.AnyNoContext) =>
+  Function.pipe(
+    SchemaAST.getAnnotation<ReferenceAnnotationValue>(ReferenceAnnotationId)(schema.ast),
+    Option.getOrElse(() => undefined),
+  );
+
+/**
+ * SchemaMeta.
+ */
+export const SchemaMetaSymbol = Symbol.for('@dxos/schema/SchemaMeta');
+
+export type SchemaMeta = TypeMeta & { id: string };
+
+/**
+ * Identifies a schema as a view.
+ */
+export const ViewAnnotationId = Symbol.for('@dxos/schema/annotation/View');
+export const ViewAnnotation = createAnnotationHelper<boolean>(ViewAnnotationId);
+
+/**
+ * Identifies label property or JSON path expression.
+ * Either a string or an array of strings representing field accessors each matched in priority order.
+ */
+export const LabelAnnotationId = Symbol.for('@dxos/schema/annotation/Label');
+export const LabelAnnotation = createAnnotationHelper<string[]>(LabelAnnotationId);
+
+/**
+ * Identifies description property or JSON path expression.
+ * A string representing field accessor.
+ */
+export const DescriptionAnnotationId = Symbol.for('@dxos/schema/annotation/Description');
+export const DescriptionAnnotation = createAnnotationHelper<string>(DescriptionAnnotationId);
+
+/**
+ * Default field to be used on referenced schema to lookup the value.
+ */
+export const FieldLookupAnnotationId = Symbol.for('@dxos/schema/annotation/FieldLookup');
+
+/**
+ * Generate test data.
+ */
+export const GeneratorAnnotationId = Symbol.for('@dxos/schema/annotation/Generator');
+
+export type GeneratorAnnotationValue =
+  | string
+  | {
+      generator: string;
+      args?: any[];
+      probability?: number;
+    };
+
+export const GeneratorAnnotation = createAnnotationHelper<GeneratorAnnotationValue>(GeneratorAnnotationId);
+
+/**
+ * @returns DXN of the schema.
+ *
+ * For non-stored schema returns `dxn:type:`.
+ * For stored schema returns `dxn:echo:`.
+ * @deprecated Use `Type.getDXN`.
+ */
+export const getSchemaDXN = (schema: Schema.Schema.All): DXN | undefined => {
+  assertArgument(Schema.isSchema(schema), 'schema', 'invalid schema');
+
+  const id = getTypeIdentifierAnnotation(schema);
+  if (id) {
+    return DXN.parse(id);
+  }
+
+  // TODO(dmaretskyi): Add support for dynamic schema.
+  const objectAnnotation = getTypeAnnotation(schema);
+  if (!objectAnnotation) {
+    return undefined;
+  }
+
+  return DXN.fromTypenameAndVersion(objectAnnotation.typename, objectAnnotation.version);
+};

package/src/internal/ast/entity-kind.ts

@@ -0,0 +1,15 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+
+/**
+ * Kinds of entities stored in ECHO: objects and relations.
+ */
+export enum EntityKind {
+  Object = 'object',
+  Relation = 'relation',
+}
+
+export const EntityKindSchema = Schema.Enums(EntityKind);

package/src/internal/ast/index.ts

@@ -0,0 +1,8 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+export * from './annotations';
+export * from './annotation-helper';
+export * from './types';
+export * from './entity-kind';

package/src/internal/ast/types.ts

@@ -0,0 +1,17 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { PropertyMeta } from './annotations';
+
+/**
+ * @internal
+ */
+export const FIELD_PATH_ANNOTATION = 'path';
+
+/**
+ * Sets the path for the field.
+ * @param path Data source path in the json path format. This is the field path in the source object.
+ */
+// TODO(burdon): Field, vs. path vs. property.
+export const FieldPath = (path: string) => PropertyMeta(FIELD_PATH_ANNOTATION, path);

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';
+
+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, FormatEnum } 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(FormatEnum.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(FormatEnum.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(FormatEnum.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(FormatEnum.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';
+
+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';