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

package/src/internal/Format/string.ts

@@ -0,0 +1,81 @@
+//
+// 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));
+
+/**
+ * Multi-line text.
+ */
+export const Text = Schema.String.pipe(FormatAnnotation.set(TypeFormat.Text));
+
+/**
+ * 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'],
+  }),
+);

package/src/internal/Format/types.ts

@@ -0,0 +1,186 @@
+//
+// 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 '../Annotation';
+import { type JsonSchemaType } from '../JsonSchema';
+
+// 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<TypeFormat>(FormatAnnotationId);
+
+/** @deprecated */
+export const getFormatAnnotation = (node: SchemaAST.AST): TypeFormat | undefined =>
+  Function.pipe(SchemaAST.getAnnotation<TypeFormat>(FormatAnnotationId)(node), Option.getOrUndefined);
+
+// TODO(burdon): Rename Format; Change to discriminated union?
+export enum TypeFormat {
+  None = 'none',
+
+  //
+  // Scalar
+  //
+
+  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',
+  Text = 'text',
+  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(TypeFormat).sort();
+
+export const PropertyKind = {
+  type: TypeEnum,
+  format: TypeFormat,
+};
+
+/**
+ * Default formats
+ */
+export const typeToFormat: Partial<Record<TypeEnum, TypeFormat>> = {
+  [TypeEnum.String]: TypeFormat.String,
+  [TypeEnum.Number]: TypeFormat.Number,
+  [TypeEnum.Boolean]: TypeFormat.Boolean,
+};
+
+/**
+ * Map of format to type.
+ */
+export const formatToType: Record<TypeFormat, TypeEnum> = {
+  [TypeFormat.None]: TypeEnum.String,
+  [TypeFormat.String]: TypeEnum.String,
+  [TypeFormat.Number]: TypeEnum.Number,
+  [TypeFormat.Boolean]: TypeEnum.Boolean,
+  [TypeFormat.Ref]: TypeEnum.Ref,
+
+  // Strings
+  [TypeFormat.DID]: TypeEnum.String,
+  [TypeFormat.DXN]: TypeEnum.String,
+  [TypeFormat.Email]: TypeEnum.String,
+  [TypeFormat.Formula]: TypeEnum.String,
+  [TypeFormat.Hostname]: TypeEnum.String,
+  [TypeFormat.JSON]: TypeEnum.String,
+  [TypeFormat.Markdown]: TypeEnum.String,
+  [TypeFormat.Regex]: TypeEnum.String,
+  [TypeFormat.URL]: TypeEnum.String,
+  [TypeFormat.UUID]: TypeEnum.String,
+  [TypeFormat.SingleSelect]: TypeEnum.String,
+  [TypeFormat.Text]: TypeEnum.String,
+  [TypeFormat.MultiSelect]: TypeEnum.Object,
+
+  // Dates
+  [TypeFormat.Date]: TypeEnum.String,
+  [TypeFormat.DateTime]: TypeEnum.String,
+  [TypeFormat.Duration]: TypeEnum.String,
+  [TypeFormat.Time]: TypeEnum.String,
+
+  // Numbers
+  [TypeFormat.Currency]: TypeEnum.Number,
+  [TypeFormat.Integer]: TypeEnum.Number,
+  [TypeFormat.Percent]: TypeEnum.Number,
+  [TypeFormat.Timestamp]: TypeEnum.Number,
+
+  // Objects
+  [TypeFormat.GeoPoint]: TypeEnum.Array,
+};
+
+/**
+ * Allowed value options for select.
+ */
+export const OptionsAnnotationId = Symbol.for('@dxos/schema/annotation/Options');
+
+// TODO(wittjosiah): Reconcile with `SelectOption`.
+export type Options = string | number;
+export const OptionsAnnotation = createAnnotationHelper<Options[]>(OptionsAnnotationId);
+
+/** @deprecated */
+export const getOptionsAnnotation = (node: SchemaAST.AST): Options[] | undefined =>
+  Function.pipe(SchemaAST.getAnnotation<Options[]>(OptionsAnnotationId)(node), Option.getOrUndefined);

package/src/internal/JsonSchema/annotations.ts

@@ -0,0 +1,50 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as SchemaAST from 'effect/SchemaAST';
+
+import { GeneratorAnnotationId, LabelAnnotationId, PropertyMetaAnnotationId } from '../Annotation';
+import { CurrencyAnnotationId, FormatAnnotationId } from '../Format';
+import { type JsonSchemaEchoAnnotations, type JsonSchemaType } from '../JsonSchema';
+
+//
+// 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,
+};

package/src/internal/JsonSchema/effect-schema.test.ts

@@ -0,0 +1,143 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import * as JSONSchema from 'effect/JSONSchema';
+import * as Option from 'effect/Option';
+import * as Schema from 'effect/Schema';
+import * as SchemaAST from 'effect/SchemaAST';
+import { expect, test } from 'vitest';
+
+import { log } from '@dxos/log';
+
+test('json-schema annotations for filter refinement get combined', () => {
+  const type = Schema.Number.annotations({
+    jsonSchema: { foo: 'foo' },
+  }).pipe(Schema.filter(() => true, { jsonSchema: { bar: 'bar' } }));
+
+  const jsonSchema = JSONSchema.make(type);
+  expect(jsonSchema).toEqual({
+    $schema: 'http://json-schema.org/draft-07/schema#',
+    foo: 'foo',
+    bar: 'bar',
+    type: 'number',
+  });
+});
+
+test('json-schema annotations on types do not override the default serialization', () => {
+  const type = Schema.Number.annotations({
+    jsonSchema: { foo: 'foo' },
+  });
+
+  const jsonSchema = JSONSchema.make(type);
+  expect(jsonSchema).toEqual({
+    $schema: 'http://json-schema.org/draft-07/schema#',
+    foo: 'foo',
+    type: 'number',
+  });
+});
+
+// pass
+test('number with title and description annotations', () => {
+  const number = Schema.Number.annotations({
+    title: 'My Title',
+    description: 'My Description',
+  });
+
+  expect(JSONSchema.make(number)).toEqual({
+    $schema: 'http://json-schema.org/draft-07/schema#',
+    type: 'number',
+    title: 'My Title',
+    description: 'My Description',
+  });
+});
+
+// pass
+test('date with title and description annotations', () => {
+  const date = Schema.Date.annotations({
+    title: 'My Title',
+    description: 'My Description',
+  });
+
+  expect(JSONSchema.make(date)).toEqual({
+    $schema: 'http://json-schema.org/draft-07/schema#',
+    $defs: {
+      DateFromString: {
+        description: 'a string to be decoded into a Date',
+        type: 'string',
+      },
+    },
+    $ref: '#/$defs/DateFromString',
+  });
+});
+
+// fail
+test('declare', () => {
+  class MyType {}
+  const type = Schema.declare<MyType>((x) => x instanceof MyType, {
+    jsonSchema: {
+      type: 'my-type',
+    },
+  });
+
+  expect(JSONSchema.make(type)).toEqual({
+    $schema: 'http://json-schema.org/draft-07/schema#',
+    type: 'my-type',
+  });
+
+  expect(type.pipe(Schema.is)(new MyType())).toBe(true);
+  expect(type.pipe(Schema.is)({})).toBe(false);
+
+  const withAnnotations = type.annotations({
+    title: 'My Title',
+    description: 'My Description',
+  });
+
+  expect(JSONSchema.make(withAnnotations)).toEqual({
+    $schema: 'http://json-schema.org/draft-07/schema#',
+    type: 'my-type',
+    title: 'My Title',
+    description: 'My Description',
+  });
+});
+
+// pass
+test('declare with refinement', () => {
+  class MyType {}
+  const type = Schema.declare<MyType>((x) => x instanceof MyType, {
+    jsonSchema: {
+      type: 'my-type',
+    },
+  }).pipe(Schema.filter(() => true, { jsonSchema: {} }));
+
+  const named = type.annotations({
+    title: 'My Title',
+    description: 'My Description',
+  });
+
+  expect(JSONSchema.make(named)).toEqual({
+    $schema: 'http://json-schema.org/draft-07/schema#',
+    type: 'my-type',
+    title: 'My Title',
+    description: 'My Description',
+  });
+});
+
+test("default title annotations don't get serialized", () => {
+  const schema = Schema.String;
+
+  expect(SchemaAST.getTitleAnnotation(schema.ast).pipe(Option.getOrUndefined)).toEqual('string');
+  expect(SchemaAST.getDescriptionAnnotation(schema.ast).pipe(Option.getOrUndefined)).toEqual('a string');
+
+  expect(JSONSchema.make(schema)).toEqual({
+    $schema: 'http://json-schema.org/draft-07/schema#',
+    type: 'string',
+  });
+});
+
+test.skip('ast comparison', () => {
+  log.info('ast', {
+    default: Schema.String.ast,
+    annotated: Schema.String.annotations({ title: 'Custom title', description: 'Custom description' }).ast,
+  });
+});

package/src/internal/JsonSchema/index.ts

@@ -0,0 +1,8 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+export * from './annotations';
+export * from './json-schema-normalize';
+export * from './json-schema-type';
+export * from './json-schema';

package/src/internal/JsonSchema/json-schema-normalize.ts

@@ -0,0 +1,111 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import type * as Types from 'effect/Types';
+
+import { JsonSchemaFields, type JsonSchemaType } from './json-schema-type';
+
+/**
+ * Normalize schema to to draft-07 format.
+ * Note: the input type does not necessarily match the {@link JsonSchemaType} type.
+ */
+export const normalizeSchema = (schema: JsonSchemaType): JsonSchemaType => {
+  const copy = structuredClone(schema) as Types.DeepMutable<JsonSchemaType>;
+  go(copy);
+  return copy;
+};
+
+const go = (schema: Types.DeepMutable<JsonSchemaType>) => {
+  if (typeof schema !== 'object' || schema === null) {
+    return;
+  }
+
+  if ((schema as any).exclusiveMaximum === true) {
+    schema.exclusiveMaximum = schema.maximum;
+    delete (schema as any).exclusiveMaximum;
+  } else if ((schema as any).exclusiveMaximum === false) {
+    delete (schema as any).exclusiveMaximum;
+  }
+
+  if ((schema as any).exclusiveMinimum === true) {
+    schema.exclusiveMinimum = schema.minimum;
+    delete (schema as any).exclusiveMinimum;
+  } else if ((schema as any).exclusiveMinimum === false) {
+    delete (schema as any).exclusiveMinimum;
+  }
+
+  // Delete all properties that are not in the JsonSchemaFields.
+  for (const key of Object.keys(schema)) {
+    if (!JsonSchemaFields.includes(key)) {
+      delete (schema as any)[key];
+    }
+  }
+
+  // Recursively normalize the schema.
+  // Recursively normalize the schema.
+  if (schema.properties) {
+    goOnRecord(schema.properties);
+  }
+  if (schema.patternProperties) {
+    goOnRecord(schema.patternProperties);
+  }
+  if (schema.propertyNames) {
+    go(schema.propertyNames);
+  }
+  if (schema.definitions) {
+    goOnRecord(schema.definitions);
+  }
+  if (schema.items) {
+    maybeGoOnArray(schema.items);
+  }
+  if (schema.additionalItems) {
+    maybeGoOnArray(schema.additionalItems);
+  }
+  if (schema.contains) {
+    go(schema.contains);
+  }
+  if (schema.if) {
+    go(schema.if);
+  }
+  if (schema.then) {
+    go(schema.then);
+  }
+  if (schema.else) {
+    go(schema.else);
+  }
+  if (schema.allOf) {
+    maybeGoOnArray(schema.allOf);
+  }
+  if (schema.anyOf) {
+    maybeGoOnArray(schema.anyOf);
+  }
+  if (schema.oneOf) {
+    maybeGoOnArray(schema.oneOf);
+  }
+  if (schema.not) {
+    go(schema.not);
+  }
+  if (schema.$defs) {
+    goOnRecord(schema.$defs);
+  }
+  if (schema.reference) {
+    go(schema.reference.schema);
+  }
+};
+
+const maybeGoOnArray = (value: any) => {
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      go(item);
+    }
+  } else if (typeof value === 'object' && value !== null) {
+    go(value);
+  }
+};
+
+const goOnRecord = (record: Record<string, any>) => {
+  for (const key of Object.keys(record)) {
+    go(record[key]);
+  }
+};