@dxos/echo 0.8.4-main.b97322e → 0.8.4-main.c4373fc

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 './ref';
+export * from './projection';
+export * from './schema';
+// TODO(dmaretskyi): Remove
+export { live } from './proxy/reactive-object';

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,
+};

package/src/internal/json/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/json/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+export * from './json-schema';