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

package/src/internal/json-schema/json-schema-type.ts

@@ -0,0 +1,403 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+
+import { JsonPath, type JsonProp } from '@dxos/effect';
+
+import { EntityKindSchema } from '../ast';
+import { FormatAnnotation, FormatEnum } from '../formats';
+
+//
+// JSON Schema
+//
+
+// TODO(burdon): Reuse/reconcile with ScalarTypeEnum (handle arrays).
+const SimpleTypes = Schema.Literal('array', 'boolean', 'integer', 'null', 'number', 'object', 'string');
+
+const NonNegativeInteger = Schema.Number.pipe(Schema.greaterThanOrEqualTo(0));
+
+const StringArray = Schema.Array(Schema.String).pipe(Schema.mutable);
+
+const JsonSchemaOrBoolean = Schema.Union(
+  Schema.suspend(() => JsonSchemaType),
+  Schema.Boolean,
+);
+
+/**
+ * Go under the `annotations` property.
+ */
+export const JsonSchemaEchoAnnotations = Schema.Struct({
+  /**
+   * Label for this schema.
+   * Mapped from {@link LabelAnnotationId}.
+   */
+  labelProp: Schema.optional(Schema.Union(JsonPath, Schema.Array(JsonPath))),
+
+  /**
+   * Generator function for this schema.
+   * Mapped from {@link GeneratorAnnotationId}.
+   */
+  generator: Schema.optional(Schema.Union(Schema.String, Schema.Tuple(Schema.String, Schema.Number))),
+
+  /**
+   * {@link PropertyMeta} annotations get serialized here.
+   */
+  meta: Schema.optional(
+    Schema.Record({
+      key: Schema.String,
+      value: Schema.Any,
+    }).pipe(Schema.mutable),
+  ),
+
+  /**
+   * @deprecated
+   */
+  // TODO(dmaretskyi): We risk old schema not passing validation due to the extra fields. Remove when we are sure this is safe
+  type: Schema.optional(
+    Schema.Struct({
+      typename: Schema.String,
+      version: Schema.String,
+
+      // Not used.
+      schemaId: Schema.optional(Schema.String),
+    }).pipe(Schema.mutable),
+  ),
+
+  /**
+   * @deprecated Superseded by `meta`.
+   */
+  annotations: Schema.optional(
+    Schema.Record({
+      key: Schema.String,
+      value: Schema.Any,
+    }).pipe(Schema.mutable),
+  ),
+}).pipe(Schema.mutable);
+export type JsonSchemaEchoAnnotations = Schema.Schema.Type<typeof JsonSchemaEchoAnnotations>;
+
+/**
+ * Describes a schema for the JSON-schema objects stored in ECHO.
+ * Contains extensions for ECHO (e.g., references).
+ * Ref: https://json-schema.org/draft-07/schema
+ */
+// TODO(burdon): Integrate with Effect Serializable?
+// TODO(dmaretskyi): Update to latest draft: https://json-schema.org/draft/2020-12
+const _JsonSchemaType = Schema.Struct({
+  /**
+   * Identifier for this schema.
+   * This schema might be referenced by $ref clause in other schemas.
+   */
+  // TODO(dmaretskyi): Specify how the ids are generated.
+  // TODO(dmaretskyi): For type dxns, should this include the version?
+  $id: Schema.optional(Schema.String),
+
+  /**
+   * Schema of this schema.
+   * Set to "https://json-schema.org/draft-07/schema".
+   */
+  $schema: Schema.optional(Schema.String),
+
+  /**
+   * Reference to another schema.
+   */
+  $ref: Schema.optional(Schema.String),
+
+  /**
+   * Comments are ignored when interpreting the schema.
+   */
+  $comment: Schema.optional(Schema.String),
+
+  /**
+   * Defines whether this schema is an object schema or a relation schema.
+   */
+  entityKind: Schema.optional(EntityKindSchema),
+
+  /**
+   * Typename of this schema.
+   * Only on schema representing an ECHO object.
+   *
+   * @example 'example.com/type/MyType'
+   */
+  typename: Schema.optional(Schema.String),
+
+  /**
+   * Version of this schema.
+   * Custom dialect for ECHO.
+   */
+  version: Schema.optional(Schema.String),
+
+  /**
+   * Target of this relation.
+   * Only for relation schemas.
+   * The referenced schema must be an object schema.
+   */
+  relationTarget: Schema.optional(Schema.suspend(() => JsonSchemaType)),
+
+  /**
+   * Source of this relation.
+   * Only for relation schemas.
+   * The referenced schema must be an object schema.
+   */
+  relationSource: Schema.optional(Schema.suspend(() => JsonSchemaType)),
+
+  /**
+   * Title of this schema.
+   */
+  title: Schema.optional(Schema.String),
+
+  /**
+   * Description of this schema.
+   */
+  description: Schema.optional(Schema.String),
+
+  /**
+   * Whether this schema is read-only.
+   */
+  readOnly: Schema.optional(Schema.Boolean),
+
+  /**
+   * Whether this schema is write-only.
+   */
+  writeOnly: Schema.optional(Schema.Boolean),
+
+  /**
+   * Examples of instances of this schema.
+   */
+  examples: Schema.optional(Schema.Array(Schema.Any)),
+
+  /**
+   * Default value for this schema.
+   */
+  default: Schema.optional(Schema.Any),
+
+  /**
+   * This schema only matches values that are equal to this value.
+   */
+  const: Schema.optional(Schema.Any),
+
+  /**
+   * This schema only matches one of the values in this array.
+   */
+  enum: Schema.optional(Schema.Array(Schema.Any)),
+
+  /**
+   * Base type of the schema.
+   */
+  type: Schema.optional(Schema.Union(SimpleTypes, Schema.Array(SimpleTypes))),
+
+  //
+  // Numbers.
+  //
+
+  multipleOf: Schema.optional(Schema.Number.pipe(Schema.greaterThan(0))),
+  maximum: Schema.optional(Schema.Number),
+  exclusiveMaximum: Schema.optional(Schema.Number),
+  minimum: Schema.optional(Schema.Number),
+  exclusiveMinimum: Schema.optional(Schema.Number),
+
+  //
+  // Strings.
+  //
+
+  maxLength: Schema.optional(NonNegativeInteger),
+
+  /**
+   * Regex pattern for strings.
+   */
+  pattern: Schema.optional(Schema.String.pipe(FormatAnnotation.set(FormatEnum.Regex))),
+
+  /**
+   * Serialized from {@link FormatAnnotationId}.
+   */
+  format: Schema.optional(Schema.String),
+
+  //
+  // Arrays
+  //
+
+  minLength: Schema.optional(NonNegativeInteger),
+  items: Schema.optional(
+    Schema.Union(
+      Schema.suspend(() => JsonSchemaType),
+      Schema.Array(Schema.suspend(() => JsonSchemaType)),
+    ),
+  ),
+  additionalItems: Schema.optional(
+    Schema.Union(
+      Schema.suspend(() => JsonSchemaType),
+      Schema.Boolean,
+    ),
+  ),
+  maxItems: Schema.optional(NonNegativeInteger),
+  minItems: Schema.optional(NonNegativeInteger),
+  uniqueItems: Schema.optional(Schema.Boolean),
+  contains: Schema.optional(Schema.suspend(() => JsonSchemaType)),
+
+  //
+  // Objects
+  //
+
+  maxProperties: Schema.optional(NonNegativeInteger),
+  minProperties: Schema.optional(NonNegativeInteger),
+  required: Schema.optional(StringArray),
+
+  /**
+   * Non-standard JSON Schema extension.
+   * Defines the order of properties in the object.
+   * The unmentioned properties are placed at the end.
+   *
+   * Related: https://github.com/json-schema/json-schema/issues/119
+   */
+  propertyOrder: Schema.optional(StringArray),
+
+  additionalProperties: Schema.optional(JsonSchemaOrBoolean),
+  properties: Schema.optional(
+    Schema.Record({
+      key: Schema.String,
+      value: Schema.suspend(() => JsonSchemaType),
+    }).pipe(Schema.mutable),
+  ),
+  patternProperties: Schema.optional(
+    Schema.Record({
+      key: Schema.String,
+      value: Schema.suspend(() => JsonSchemaType),
+    }).pipe(Schema.mutable),
+  ),
+  propertyNames: Schema.optional(Schema.suspend(() => JsonSchemaType)),
+
+  definitions: Schema.optional(
+    Schema.mutable(
+      Schema.Record({
+        key: Schema.String,
+        value: Schema.suspend(() => JsonSchemaType),
+      }),
+    ),
+  ),
+  dependencies: Schema.optional(
+    Schema.Record({
+      key: Schema.String,
+      value: Schema.suspend(() => Schema.Union(Schema.String, StringArray, JsonSchemaType)).annotations({
+        identifier: 'dependency',
+        description: 'Dependency',
+      }),
+    }),
+  ),
+
+  contentMediaType: Schema.optional(Schema.String),
+  contentEncoding: Schema.optional(Schema.String),
+
+  if: Schema.optional(Schema.suspend(() => JsonSchemaType)),
+  then: Schema.optional(Schema.suspend(() => JsonSchemaType)),
+  else: Schema.optional(Schema.suspend(() => JsonSchemaType)),
+  allOf: Schema.optional(Schema.Array(Schema.suspend(() => JsonSchemaType))),
+  anyOf: Schema.optional(Schema.Array(Schema.suspend(() => JsonSchemaType))),
+  oneOf: Schema.optional(Schema.Array(Schema.suspend(() => JsonSchemaType))),
+  not: Schema.optional(Schema.suspend(() => JsonSchemaType)),
+  $defs: Schema.optional(
+    Schema.mutable(
+      Schema.Record({
+        key: Schema.String,
+        value: Schema.suspend(() => JsonSchemaType),
+      }),
+    ),
+  ),
+
+  //
+  // ECHO extensions.
+  //
+
+  currency: Schema.optional(Schema.String),
+
+  reference: Schema.optional(
+    Schema.mutable(
+      Schema.Struct({
+        schema: Schema.suspend(() => JsonSchemaType),
+        schemaVersion: Schema.optional(Schema.String),
+        schemaObject: Schema.optional(Schema.String),
+      }),
+    ),
+  ),
+
+  /**
+   * ECHO-specific annotations.
+   */
+  // TODO(dmaretskyi): Since we are adding a lot of new extensions to the JSON Schema, it is safer to namespace them here.
+  annotations: Schema.optional(Schema.mutable(JsonSchemaEchoAnnotations)),
+
+  /**
+   * @deprecated Use `annotations` instead.
+   */
+  echo: Schema.optional(Schema.mutable(JsonSchemaEchoAnnotations)),
+}).annotations({ identifier: 'jsonSchema', description: 'JSON Schema' });
+
+export const JsonSchemaFields = Object.keys(_JsonSchemaType.fields);
+
+/**
+ * https://json-schema.org/draft-07/schema
+ */
+export interface JsonSchemaType extends Schema.Schema.Type<Schema.mutable<typeof _JsonSchemaType>> {}
+
+export const JsonSchemaType: Schema.Schema<JsonSchemaType> = _JsonSchemaType.pipe(Schema.mutable);
+
+// TODO(burdon): Factor out JSON schema utils.
+
+export const getSchemaProperty = (schema: JsonSchemaType, property: JsonProp): JsonSchemaType | undefined => {
+  return schema.properties?.[property];
+};
+
+// TODO(burdon): Properties should be ordered.
+export const setSchemaProperty = (schema: JsonSchemaType, property: JsonProp, value: JsonSchemaType) => {
+  schema.properties ??= {};
+  schema.properties[property] = value;
+  return schema;
+};
+
+/**
+ * @internal
+ */
+export const ECHO_ANNOTATIONS_NS_DEPRECATED_KEY: keyof JsonSchemaType = 'echo';
+
+/**
+ * @internal
+ */
+export const ECHO_ANNOTATIONS_NS_KEY = 'annotations';
+
+/**
+ * @internal
+ * @returns ECHO annotations namespace object in its normalized form.
+ *
+ * `meta` holds PropertyMeta annotations.
+ * `annotations` holds other annotations.
+ */
+export const getNormalizedEchoAnnotations = (obj: JsonSchemaType): JsonSchemaEchoAnnotations | undefined => {
+  if (obj[ECHO_ANNOTATIONS_NS_KEY] != null && obj[ECHO_ANNOTATIONS_NS_DEPRECATED_KEY] != null) {
+    return normalizeEchoAnnotations({
+      ...obj[ECHO_ANNOTATIONS_NS_DEPRECATED_KEY],
+      ...obj[ECHO_ANNOTATIONS_NS_KEY],
+    });
+  } else if (obj[ECHO_ANNOTATIONS_NS_KEY] != null) {
+    return normalizeEchoAnnotations(obj[ECHO_ANNOTATIONS_NS_KEY]!);
+  } else if (obj[ECHO_ANNOTATIONS_NS_DEPRECATED_KEY] != null) {
+    return normalizeEchoAnnotations(obj[ECHO_ANNOTATIONS_NS_DEPRECATED_KEY]!);
+  } else {
+    return undefined;
+  }
+};
+
+const normalizeEchoAnnotations = (obj: JsonSchemaEchoAnnotations): JsonSchemaEchoAnnotations => {
+  if (!obj.annotations) {
+    return obj;
+  } else {
+    const res = {
+      ...obj,
+      meta: {
+        ...obj.annotations,
+        ...(obj.meta ?? {}),
+      },
+    };
+    delete res.annotations;
+    return res;
+  }
+};

package/src/internal/object/accessors.ts

@@ -0,0 +1,153 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Option from 'effect/Option';
+import * as Schema from 'effect/Schema';
+
+import { type JsonPath, getField } from '@dxos/effect';
+import { assertArgument, invariant } from '@dxos/invariant';
+import { DXN, ObjectId } from '@dxos/keys';
+import { assumeType } from '@dxos/util';
+
+import { DescriptionAnnotation, LabelAnnotation } from '../ast';
+
+import { type InternalObjectProps, SchemaId, SelfDXNId } from './model';
+
+//
+// Accessors based on model.
+//
+
+/**
+ * Returns a DXN for an object or schema.
+ * @deprecated Use `Obj.getDXN`.
+ */
+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);
+};
+
+/**
+ * Returns the schema for the given object if one is defined.
+ */
+// TODO(burdon): Reconcile with `getTypename`.
+// TODO(dmaretskyi): For echo objects, this always returns the root schema.
+export const getSchema = (obj: unknown | undefined): Schema.Schema.AnyNoContext | undefined => {
+  if (obj) {
+    return (obj as any)[SchemaId];
+  }
+};
+
+/**
+ * Internal use only.
+ */
+export const setSchema = (obj: any, schema: Schema.Schema.AnyNoContext) => {
+  Object.defineProperty(obj, SchemaId, {
+    value: schema,
+    writable: false,
+    enumerable: false,
+    configurable: false,
+  });
+};
+
+/**
+ * @deprecated Use {@link Obj.getLabel} instead.
+ * Returns the label for a given object based on {@link LabelAnnotationId}.
+ */
+export const getLabelForObject = (obj: unknown | undefined): string | undefined => {
+  const schema = getSchema(obj);
+  if (schema) {
+    return getLabel(schema, obj);
+  }
+};
+
+/**
+ * Returns the label for a given object based on {@link LabelAnnotationId}.
+ */
+// TODO(burdon): Convert to JsonPath?
+export const getLabel = <S extends Schema.Schema.Any>(schema: S, object: Schema.Schema.Type<S>): string | undefined => {
+  const annotation = LabelAnnotation.get(schema).pipe(Option.getOrElse(() => ['name']));
+  for (const accessor of annotation) {
+    assertArgument(
+      typeof accessor === 'string',
+      'accessor',
+      'Label annotation must be a string or an array of strings',
+    );
+    const value = getField(object, accessor as JsonPath);
+    switch (typeof value) {
+      case 'string':
+      case 'number':
+      case 'boolean':
+      case 'bigint':
+      case 'symbol':
+        return value.toString();
+      case 'undefined':
+      case 'object':
+      case 'function':
+        continue;
+    }
+  }
+
+  return undefined;
+};
+
+/**
+ * Sets the label for a given object based on {@link LabelAnnotationId}.
+ */
+export const setLabel = <S extends Schema.Schema.Any>(schema: S, object: Schema.Schema.Type<S>, label: string) => {
+  const annotation = LabelAnnotation.get(schema).pipe(
+    Option.map((field) => field[0]),
+    Option.getOrElse(() => 'name'),
+  );
+  object[annotation] = label;
+};
+
+/**
+ * Returns the label for a given object based on {@link LabelAnnotationId}.
+ */
+// TODO(burdon): Convert to JsonPath?
+export const getDescription = <S extends Schema.Schema.Any>(
+  schema: S,
+  object: Schema.Schema.Type<S>,
+): string | undefined => {
+  const accessor = DescriptionAnnotation.get(schema).pipe(Option.getOrElse(() => 'description'));
+  assertArgument(typeof accessor === 'string', 'accessor', 'Description annotation must be a string');
+  const value = getField(object, accessor as JsonPath);
+  switch (typeof value) {
+    case 'string':
+    case 'number':
+    case 'boolean':
+    case 'bigint':
+    case 'symbol':
+      return value.toString();
+    case 'undefined':
+    case 'object':
+    case 'function':
+    default:
+      return undefined;
+  }
+};
+
+/**
+ * Sets the description for a given object based on {@link DescriptionAnnotationId}.
+ */
+export const setDescription = <S extends Schema.Schema.Any>(
+  schema: S,
+  object: Schema.Schema.Type<S>,
+  description: string,
+) => {
+  const accessor = DescriptionAnnotation.get(schema).pipe(Option.getOrElse(() => 'description'));
+  object[accessor] = description;
+};

package/src/internal/object/common.ts

@@ -0,0 +1,76 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+
+import { type BaseObject } from '../types';
+
+import { getTypename } from './typename';
+
+// TODO(dmaretskyi): Rename to represent commonality between objects and relations (e.g. `entity`).
+export type TypedObjectOptions = {
+  // TODO(burdon): Document.
+  partial?: true;
+  // TODO(burdon): Document.
+  record?: true;
+};
+
+/**
+ *
+ */
+// TODO(burdon): Comment required.
+// TODO(dmaretskyi): Rename to represent commonality between objects and relations (e.g. `entity`).
+type SimplifiedSchemaFields<
+  SchemaFields extends Schema.Struct.Fields,
+  Options extends TypedObjectOptions,
+> = Options['partial'] extends boolean
+  ? Schema.SimplifyMutable<Partial<Schema.Struct.Type<SchemaFields>>>
+  : Schema.SimplifyMutable<Schema.Struct.Type<SchemaFields>>;
+
+/**
+ *
+ */
+// TODO(burdon): Comment required.
+// TODO(dmaretskyi): Rename to represent commonality between objects and relations (e.g. `entity`).
+export type TypedObjectFields<
+  SchemaFields extends Schema.Struct.Fields,
+  Options extends TypedObjectOptions,
+> = SimplifiedSchemaFields<SchemaFields, Options> & { id: string } & (Options['record'] extends boolean
+    ? Schema.SimplifyMutable<Schema.IndexSignature.Type<Schema.IndexSignature.Records>>
+    : {});
+
+export const makeTypedEntityClass = (
+  typename: string,
+  version: string,
+  baseSchema: Schema.Schema.AnyNoContext,
+): Schema.SchemaClass<any> => {
+  return class {
+    // Implement TypedObject properties.
+    static readonly typename = typename;
+    static readonly version = version;
+
+    // Implement Schema.Schema properties.
+    // TODO(burdon): Comment required.
+    static readonly [Schema.TypeId] = schemaVariance;
+    static readonly ast = baseSchema.ast;
+    static readonly annotations = baseSchema.annotations.bind(baseSchema);
+    static readonly pipe = baseSchema.pipe.bind(baseSchema);
+
+    // TODO(burdon): Comment required.
+    static [Symbol.hasInstance](obj: BaseObject) {
+      return obj != null && getTypename(obj) === typename;
+    }
+
+    // TODO(burdon): Throw APIError.
+    private constructor() {
+      throw new Error('Use live(Typename, { ...fields }) to instantiate an object.');
+    }
+  } as any;
+};
+
+const schemaVariance = {
+  _A: (_: any) => _,
+  _I: (_: any) => _,
+  _R: (_: never) => _,
+};