@dxos/echo 0.8.4-main.406dc2a → 0.8.4-main.59c2e9b

package/src/internal/entities/object.ts

@@ -0,0 +1,60 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+import * as SchemaAST from 'effect/SchemaAST';
+
+import { invariant } from '@dxos/invariant';
+
+import { type TypeAnnotation, TypeAnnotationId, type TypeMeta, makeTypeJsonSchemaAnnotation } from '../annotations';
+import { EntityKind } from '../types';
+
+import { type EchoTypeSchema, makeEchoTypeSchema } from './entity';
+
+/**
+ * Object schema type with kind marker.
+ */
+export type EchoObjectSchema<
+  Self extends Schema.Schema.Any,
+  Fields extends Schema.Struct.Fields = Schema.Struct.Fields,
+> = EchoTypeSchema<Self, {}, EntityKind.Object, Fields>;
+
+/**
+ * Schema for Obj entity types.
+ * Pipeable function to add ECHO object annotations to a schema.
+ */
+export const EchoObjectSchema: {
+  (
+    meta: TypeMeta,
+  ): <Self extends Schema.Schema.Any, Fields extends Schema.Struct.Fields = Schema.Struct.Fields>(
+    self: Self & { fields?: Fields },
+  ) => EchoObjectSchema<Self, Fields>;
+} = ({ typename, version }) => {
+  return <Self extends Schema.Schema.Any, Fields extends Schema.Struct.Fields = Schema.Struct.Fields>(
+    self: Self & { fields?: Fields },
+  ): EchoObjectSchema<Self, Fields> => {
+    invariant(typeof TypeAnnotationId === 'symbol', 'Sanity.');
+    invariant(SchemaAST.isTypeLiteral(self.ast), 'Schema must be a TypeLiteral.');
+
+    // Extract fields from the schema if available (Struct schemas have .fields).
+    const fields = ((self as any).fields ?? {}) as Fields;
+
+    // TODO(dmaretskyi): Does `Schema.mutable` work for deep mutability here?
+    // TODO(dmaretskyi): Do not do mutable here.
+    const schemaWithId = Schema.extend(Schema.mutable(self), Schema.Struct({ id: Schema.String }));
+    const ast = SchemaAST.annotations(schemaWithId.ast, {
+      // TODO(dmaretskyi): `extend` kills the annotations.
+      ...self.ast.annotations,
+      [TypeAnnotationId]: { kind: EntityKind.Object, typename, version } satisfies TypeAnnotation,
+      // TODO(dmaretskyi): TypeIdentifierAnnotationId?
+      [SchemaAST.JSONSchemaAnnotationId]: makeTypeJsonSchemaAnnotation({
+        kind: EntityKind.Object,
+        typename,
+        version,
+      }),
+    });
+
+    return makeEchoTypeSchema<Self, EntityKind.Object, Fields>(fields, ast, typename, version, EntityKind.Object);
+  };
+};

package/src/internal/entities/relation.ts

@@ -0,0 +1,173 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+import * as SchemaAST from 'effect/SchemaAST';
+
+import { raise } from '@dxos/debug';
+import { assertArgument, invariant } from '@dxos/invariant';
+import { DXN } from '@dxos/keys';
+
+import {
+  type TypeAnnotation,
+  TypeAnnotationId,
+  type TypeMeta,
+  getEntityKind,
+  getSchemaTypename,
+  getTypeIdentifierAnnotation,
+  makeTypeJsonSchemaAnnotation,
+} from '../annotations';
+import { EntityKind } from '../types';
+
+import { type EchoTypeSchema, makeEchoTypeSchema } from './entity';
+
+/**
+ * Property name for relation source when object is serialized to JSON.
+ */
+export const ATTR_RELATION_SOURCE = '@relationSource';
+
+/**
+ * Used to access relation source ref on live ECHO objects.
+ * Reading this symbol must return `Live<EchoObjectSchema<any>>` or a DXN.
+ */
+export const RelationSourceId: unique symbol = Symbol.for('@dxos/echo/RelationSource');
+
+/**
+ * Used to access relation source ref on live ECHO objects.
+ * Reading this symbol must return `Live<EchoObjectSchema<any>>` or a DXN.
+ */
+export const RelationSourceDXNId: unique symbol = Symbol.for('@dxos/echo/RelationSourceDXN');
+
+/**
+ * Property name for relation target when object is serialized to JSON.
+ */
+export const ATTR_RELATION_TARGET = '@relationTarget';
+
+/**
+ * Used to access relation target ref on live ECHO objects.
+ * Reading this symbol must return `Live<EchoObjectSchema<any>>` or a DXN.
+ */
+export const RelationTargetId: unique symbol = Symbol.for('@dxos/echo/RelationTarget');
+
+/**
+ * Used to access relation target ref on live ECHO objects.
+ * Reading this symbol must return `Live<EchoObjectSchema<any>>` or a DXN.
+ */
+export const RelationTargetDXNId: unique symbol = Symbol.for('@dxos/echo/RelationTargetDXN');
+
+/**
+ * Source and target props on relations.
+ */
+// TODO(burdon): any?
+export type RelationSourceTargetRefs<Source = any, Target = any> = {
+  /**
+   * Source ECHO live object.
+   */
+  [RelationSourceId]: Source;
+
+  /**
+   * Target ECHO live object.
+   */
+  [RelationTargetId]: Target;
+};
+
+export type RelationSource<R> = R extends RelationSourceTargetRefs<infer Source, infer _Target> ? Source : never;
+export type RelationTarget<R> = R extends RelationSourceTargetRefs<infer _Source, infer Target> ? Target : never;
+
+export type EchoRelationSchemaOptions<
+  TSource extends Schema.Schema.AnyNoContext,
+  TTarget extends Schema.Schema.AnyNoContext,
+> = TypeMeta & {
+  source: TSource;
+  target: TTarget;
+};
+
+/**
+ * Relation schema type with kind marker.
+ */
+export type EchoRelationSchema<
+  Self extends Schema.Schema.Any,
+  Source extends Schema.Schema.AnyNoContext,
+  Target extends Schema.Schema.AnyNoContext,
+  Fields extends Schema.Struct.Fields = Schema.Struct.Fields,
+> = EchoTypeSchema<
+  Self,
+  RelationSourceTargetRefs<Schema.Schema.Type<Source>, Schema.Schema.Type<Target>>,
+  EntityKind.Relation,
+  Fields
+>;
+
+/**
+ * Schema for Relation entity types.
+ */
+export const EchoRelationSchema = <
+  Source extends Schema.Schema.AnyNoContext,
+  Target extends Schema.Schema.AnyNoContext,
+>({
+  source,
+  target,
+  typename,
+  version,
+}: EchoRelationSchemaOptions<Source, Target>) => {
+  assertArgument(Schema.isSchema(source), 'source');
+  assertArgument(Schema.isSchema(target), 'target');
+  const sourceDXN = getDXNForRelationSchemaRef(source);
+  const targetDXN = getDXNForRelationSchemaRef(target);
+  if (getEntityKind(source) !== EntityKind.Object) {
+    raise(new Error('Source schema must be an echo object schema.'));
+  }
+  if (getEntityKind(target) !== EntityKind.Object) {
+    raise(new Error('Target schema must be an echo object schema.'));
+  }
+
+  return <Self extends Schema.Schema.Any, Fields extends Schema.Struct.Fields = Schema.Struct.Fields>(
+    self: Self & { fields?: Fields },
+  ): EchoRelationSchema<Self, Source, Target, Fields> => {
+    invariant(SchemaAST.isTypeLiteral(self.ast), 'Schema must be a TypeLiteral.');
+
+    // Extract fields from the schema if available (Struct schemas have .fields).
+    const fields = ((self as any).fields ?? {}) as Fields;
+
+    // TODO(dmaretskyi): Does `Schema.mutable` work for deep mutability here?
+    // TODO(dmaretskyi): Do not do mutable here.
+    const schemaWithId = Schema.extend(Schema.mutable(self), Schema.Struct({ id: Schema.String }));
+    const ast = SchemaAST.annotations(schemaWithId.ast, {
+      // TODO(dmaretskyi): `extend` kills the annotations.
+      ...self.ast.annotations,
+      [TypeAnnotationId]: {
+        kind: EntityKind.Relation,
+        typename,
+        version,
+        sourceSchema: sourceDXN,
+        targetSchema: targetDXN,
+      } satisfies TypeAnnotation,
+      // TODO(dmaretskyi): TypeIdentifierAnnotationId?
+
+      [SchemaAST.JSONSchemaAnnotationId]: makeTypeJsonSchemaAnnotation({
+        kind: EntityKind.Relation,
+        typename,
+        version,
+        relationSource: sourceDXN,
+        relationTarget: targetDXN,
+      }),
+    });
+
+    return makeEchoTypeSchema<Self, EntityKind.Relation, Fields>(fields, ast, typename, version, EntityKind.Relation);
+  };
+};
+
+const getDXNForRelationSchemaRef = (schema: Schema.Schema.Any): string => {
+  assertArgument(Schema.isSchema(schema), 'schema');
+  const identifier = getTypeIdentifierAnnotation(schema);
+  if (identifier) {
+    return identifier;
+  }
+
+  const typename = getSchemaTypename(schema);
+  if (!typename) {
+    throw new Error('Schema must have a typename');
+  }
+
+  return DXN.fromTypename(typename).toString();
+};

package/src/internal/entities/util.ts

@@ -0,0 +1,33 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+
+import { assertArgument, invariant } from '@dxos/invariant';
+import { DXN, ObjectId } from '@dxos/keys';
+import { assumeType } from '@dxos/util';
+
+import { type InternalObjectProps, SelfDXNId } from './model';
+
+/**
+ * Returns a DXN for an object or schema.
+ *
+ * @internal
+ */
+export const getObjectDXN = (object: any): DXN | undefined => {
+  invariant(!Schema.isSchema(object), 'schema not allowed in this function');
+  assertArgument(typeof object === 'object' && object != null, 'object', 'expected object');
+  assumeType<InternalObjectProps>(object);
+
+  if (object[SelfDXNId]) {
+    invariant(object[SelfDXNId] instanceof DXN, 'Invalid object model: invalid self dxn');
+    return object[SelfDXNId];
+  }
+
+  if (!ObjectId.isValid(object.id)) {
+    throw new TypeError('Object id is not valid.');
+  }
+
+  return DXN.fromLocalObjectId(object.id);
+};

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

@@ -7,7 +7,7 @@ import { describe, expect, test } from 'vitest';
 
 import { log } from '@dxos/log';
 
-import { toJsonSchema } from '../json';
+import { toJsonSchema } from '../json-schema';
 
 import {
   DateOnly,

package/src/internal/formats/date.ts

@@ -5,7 +5,7 @@
 import * as Schema from 'effect/Schema';
 import * as SchemaAST from 'effect/SchemaAST';
 
-import { FormatAnnotation, FormatEnum } from './types';
+import { FormatAnnotation, TypeFormat } from './types';
 
 /**
  * Datetime values should be stored as ISO strings or unix numbers (ms) in UTC.
@@ -102,7 +102,7 @@ export const DateOnly = /* Schema.transformOrFail(Schema.String, SimpleDate, {
     );
   },
 }) */ Schema.String.pipe(
-  FormatAnnotation.set(FormatEnum.Date),
+  FormatAnnotation.set(TypeFormat.Date),
   Schema.annotations({
     title: 'Date',
     description: 'Valid date in ISO format',
@@ -132,7 +132,7 @@ export const TimeOnly = /* Schema.transformOrFail(Schema.String, SimpleTime, {
     );
   },
 }) */ Schema.String.pipe(
-  FormatAnnotation.set(FormatEnum.Time),
+  FormatAnnotation.set(TypeFormat.Time),
   Schema.annotations({
     title: 'Time',
     description: 'Valid time in ISO format',
@@ -177,7 +177,7 @@ export const DateTime = /* Schema.transformOrFail(Schema.String, SimpleDateTime,
     );
   },
 }) */ Schema.String.pipe(
-  FormatAnnotation.set(FormatEnum.DateTime),
+  FormatAnnotation.set(TypeFormat.DateTime),
   Schema.annotations({
     title: 'DateTime',
     description: 'Valid date and time in ISO format',
@@ -189,7 +189,7 @@ export const DateTime = /* Schema.transformOrFail(Schema.String, SimpleDateTime,
  */
 // TODO(burdon): Define duration type.
 export const Duration = Schema.String.pipe(
-  FormatAnnotation.set(FormatEnum.Duration),
+  FormatAnnotation.set(TypeFormat.Duration),
   Schema.annotations({
     title: 'Duration',
     description: 'Duration in ISO 8601 format',

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

@@ -5,10 +5,10 @@
 import * as Schema from 'effect/Schema';
 import { describe, test } from 'vitest';
 
-import { toJsonSchema } from '../json';
+import { toJsonSchema } from '../json-schema';
 
 import { Format } from './format';
-import { FormatEnum, TypeEnum, getTypeEnum } from './types';
+import { TypeEnum, TypeFormat, getTypeEnum } from './types';
 
 describe('formats', () => {
   test('annotations', ({ expect }) => {
@@ -48,7 +48,7 @@ describe('formats', () => {
       expect(getTypeEnum(prop)).to.eq(TypeEnum.String);
       expect(prop).includes({
         type: TypeEnum.String,
-        format: FormatEnum.Email,
+        format: TypeFormat.Email,
         title: 'Email',
       });
     }
@@ -58,7 +58,7 @@ describe('formats', () => {
       expect(getTypeEnum(prop)).to.eq(TypeEnum.Number);
       expect(prop).includes({
         type: TypeEnum.Number,
-        format: FormatEnum.Currency,
+        format: TypeFormat.Currency,
         title: 'Currency',
         multipleOf: 0.01,
         currency: 'USD',
@@ -70,7 +70,7 @@ describe('formats', () => {
       expect(getTypeEnum(prop)).to.eq(TypeEnum.String);
       expect(prop).includes({
         type: TypeEnum.String,
-        format: FormatEnum.Date,
+        format: TypeFormat.Date,
       });
     }
   });

package/src/internal/formats/format.ts

@@ -10,10 +10,10 @@ import * as DateUtil from './date';
 import * as NumberUtil from './number';
 import * as ObjectUtil from './object';
 import * as StringUtil from './string';
+import { TypeFormat as TypeFormat$ } 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
+// - https://json-schema.org/understanding-json-schema/reference/non_json_data
 
 /**
  * Formats.
@@ -22,7 +22,9 @@ import * as StringUtil from './string';
  */
 // TODO(burdon): Add fields for `examples`, `message`, etc.
 export namespace Format {
-  // Strings
+  export import TypeFormat = TypeFormat$;
+
+  // String
   export const DXN = Keys.DXN.Schema;
   export const Email = StringUtil.Email;
   export const Formula = StringUtil.Formula;
@@ -41,12 +43,12 @@ export namespace Format {
   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 DateTime = DateUtil.DateTime;
   export const Duration = DateUtil.Duration;
+  export const Time = DateUtil.TimeOnly;
 
   // Objects
   export const GeoPoint = ObjectUtil.GeoPoint;
-  export type GeoPoint = ObjectUtil.GeoPoint;
+  export type GeoPoint = ObjectUtil.GeoPoint; // TODO(burdon): Export types.
 }

package/src/internal/formats/number.ts

@@ -4,7 +4,7 @@
 
 import * as Schema from 'effect/Schema';
 
-import { FormatAnnotation, FormatEnum } from './types';
+import { FormatAnnotation, TypeFormat } from './types';
 
 const encodeMultipleOf = (divisor: number) => 1 / Math.pow(10, divisor);
 
@@ -37,7 +37,7 @@ export type CurrencyAnnotation = {
 export const Currency = ({ decimals, code }: CurrencyAnnotation = { decimals: 2 }) =>
   Schema.Number.pipe(
     encodeMultiple(decimals),
-    FormatAnnotation.set(FormatEnum.Currency),
+    FormatAnnotation.set(TypeFormat.Currency),
     Schema.annotations({
       title: 'Currency',
       description: 'Currency value',
@@ -55,7 +55,7 @@ export type PercentAnnotation = {
 export const Integer = () =>
   Schema.Number.pipe(
     Schema.int(),
-    FormatAnnotation.set(FormatEnum.Integer),
+    FormatAnnotation.set(TypeFormat.Integer),
     Schema.annotations({
       title: 'Integer',
       description: 'Integer value',
@@ -69,7 +69,7 @@ export const Integer = () =>
 export const Percent = ({ decimals }: PercentAnnotation = { decimals: 2 }) =>
   Schema.Number.pipe(
     encodeMultiple(decimals),
-    FormatAnnotation.set(FormatEnum.Percent),
+    FormatAnnotation.set(TypeFormat.Percent),
     Schema.annotations({
       title: 'Percent',
       description: 'Percentage value',
@@ -81,7 +81,7 @@ export const Percent = ({ decimals }: PercentAnnotation = { decimals: 2 }) =>
  * https://en.wikipedia.org/wiki/Unix_time
  */
 export const Timestamp = Schema.Number.pipe(
-  FormatAnnotation.set(FormatEnum.Timestamp),
+  FormatAnnotation.set(TypeFormat.Timestamp),
   Schema.annotations({
     title: 'Timestamp',
     description: 'Unix timestamp',

package/src/internal/formats/object.ts

@@ -6,7 +6,7 @@ import * as Schema from 'effect/Schema';
 
 import { clamp } from '@dxos/util';
 
-import { FormatAnnotation, FormatEnum } from './types';
+import { FormatAnnotation, TypeFormat } from './types';
 
 /**
  * GeoJSON Format
@@ -21,13 +21,13 @@ import { FormatAnnotation, FormatEnum } from './types';
  * 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.Number.pipe(Schema.annotations({ title: 'Longitude' }), Schema.clamp(-180, 180), Schema.multipleOf(0.000001)),
+  Schema.Number.pipe(Schema.annotations({ title: 'Latitude' }), Schema.clamp(-90, 90), Schema.multipleOf(0.000001)),
   Schema.optionalElement(Schema.Number).annotations({
     title: 'Height ASL (m)',
   }),
 ).pipe(
-  FormatAnnotation.set(FormatEnum.GeoPoint),
+  FormatAnnotation.set(TypeFormat.GeoPoint),
   Schema.annotations({
     title: 'GeoPoint',
     description: 'GeoJSON Position',

package/src/internal/formats/select.ts

@@ -4,8 +4,10 @@
 
 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({
+/**
+ * Schema for a single select option. Used to define choices in a {single|multi}-select field.
+ */
+export const SelectOption = Schema.Struct({
   /** Stable identifier for the option. */
   id: Schema.NonEmptyString,
   title: Schema.String,
@@ -13,4 +15,4 @@ export const SelectOptionSchema = Schema.Struct({
   color: Schema.String,
 }).pipe(Schema.mutable);
 
-export type SelectOption = Schema.Schema.Type<typeof SelectOptionSchema>;
+export type SelectOption = Schema.Schema.Type<typeof SelectOption>;

package/src/internal/formats/string.ts

@@ -5,7 +5,7 @@
 import * as Schema from 'effect/Schema';
 import * as SchemaAST from 'effect/SchemaAST';
 
-import { FormatAnnotation, FormatEnum } from './types';
+import { FormatAnnotation, TypeFormat } from './types';
 
 /**
  * Email address (RFC 5321)
@@ -13,7 +13,7 @@ import { FormatAnnotation, FormatEnum } from './types';
  */
 export const Email = Schema.String.pipe(
   Schema.pattern(/^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$/),
-  FormatAnnotation.set(FormatEnum.Email),
+  FormatAnnotation.set(TypeFormat.Email),
   Schema.annotations({
     title: 'Email',
     description: 'Email address',
@@ -24,25 +24,25 @@ export const Email = Schema.String.pipe(
  *
  */
 // TODO(burdon): Implement.
-export const Formula = Schema.String.pipe(FormatAnnotation.set(FormatEnum.Formula));
+export const Formula = Schema.String.pipe(FormatAnnotation.set(TypeFormat.Formula));
 
 /**
  *
  */
 // TODO(burdon): Implement.
-export const Hostname = Schema.String.pipe(FormatAnnotation.set(FormatEnum.Hostname));
+export const Hostname = Schema.String.pipe(FormatAnnotation.set(TypeFormat.Hostname));
 
 /**
  *
  */
 // TODO(burdon): Implement.
-export const JSON = Schema.String.pipe(FormatAnnotation.set(FormatEnum.JSON));
+export const JSON = Schema.String.pipe(FormatAnnotation.set(TypeFormat.JSON));
 
 /**
  *
  */
 // TODO(burdon): Implement.
-export const Markdown = Schema.String.pipe(FormatAnnotation.set(FormatEnum.Markdown));
+export const Markdown = Schema.String.pipe(FormatAnnotation.set(TypeFormat.Markdown));
 
 /**
  * Regex
@@ -50,14 +50,19 @@ export const Markdown = Schema.String.pipe(FormatAnnotation.set(FormatEnum.Markd
  * https://ecma-international.org/publications-and-standards/standards/ecma-262
  */
 // TODO(burdon): Implement.
-export const Regex = Schema.String.pipe(FormatAnnotation.set(FormatEnum.Regex));
+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(FormatEnum.URL),
+  FormatAnnotation.set(TypeFormat.URL),
   Schema.annotations({
     title: 'URL',
     description: 'URL',
@@ -69,7 +74,7 @@ export const URL = Schema.String.pipe(
  * https://datatracker.ietf.org/doc/html/rfc4122
  */
 export const UUID = Schema.UUID.pipe(
-  FormatAnnotation.set(FormatEnum.UUID),
+  FormatAnnotation.set(TypeFormat.UUID),
   Schema.annotations({
     [SchemaAST.ExamplesAnnotationId]: ['3e4666bf-d5e5-4aa7-b8ce-cefe41c7568a'],
   }),