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

package/src/internal/object/schema-validator.ts

@@ -0,0 +1,241 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+import * as SchemaAST from 'effect/SchemaAST';
+
+import { invariant } from '@dxos/invariant';
+
+import { SchemaId } from './model';
+
+// TODO(burdon): Reconcile with @dxos/effect visit().
+
+export class SchemaValidator {
+  /**
+   * Recursively check that schema specifies constructions we can handle.
+   * Validates there are no ambiguous discriminated union types.
+   */
+  public static validateSchema(schema: Schema.Schema.AnyNoContext): void {
+    const visitAll = (nodes: SchemaAST.AST[]) => nodes.forEach((node) => this.validateSchema(Schema.make(node)));
+    if (SchemaAST.isUnion(schema.ast)) {
+      const typeAstList = schema.ast.types.filter((type) => SchemaAST.isTypeLiteral(type)) as SchemaAST.TypeLiteral[];
+      // Check we can handle a discriminated union.
+      if (typeAstList.length > 1) {
+        getTypeDiscriminators(typeAstList);
+      }
+      visitAll(typeAstList);
+    } else if (SchemaAST.isTupleType(schema.ast)) {
+      const positionalTypes = schema.ast.elements.map((t) => t.type);
+      const allTypes = positionalTypes.concat(schema.ast.rest.map((t) => t.type));
+      visitAll(allTypes);
+    } else if (SchemaAST.isTypeLiteral(schema.ast)) {
+      visitAll(SchemaAST.getPropertySignatures(schema.ast).map((p) => p.type));
+    }
+  }
+
+  public static hasTypeAnnotation(
+    rootObjectSchema: Schema.Schema.AnyNoContext,
+    property: string,
+    annotation: symbol,
+  ): boolean {
+    try {
+      let type = this.getPropertySchema(rootObjectSchema, [property]);
+      if (SchemaAST.isTupleType(type.ast)) {
+        type = this.getPropertySchema(rootObjectSchema, [property, '0']);
+      }
+
+      return type.ast.annotations[annotation] != null;
+    } catch (err) {
+      return false;
+    }
+  }
+
+  public static getPropertySchema(
+    rootObjectSchema: Schema.Schema.AnyNoContext,
+    propertyPath: KeyPath,
+    getProperty: (path: KeyPath) => any = () => null,
+  ): Schema.Schema.AnyNoContext {
+    let schema: Schema.Schema.AnyNoContext = rootObjectSchema;
+    for (let i = 0; i < propertyPath.length; i++) {
+      const propertyName = propertyPath[i];
+      const tupleAst = unwrapArray(schema.ast);
+      if (tupleAst != null) {
+        schema = getArrayElementSchema(tupleAst, propertyName);
+      } else {
+        const propertyType = getPropertyType(schema.ast, propertyName.toString(), (propertyName) =>
+          getProperty([...propertyPath.slice(0, i), propertyName]),
+        );
+        if (propertyType == null) {
+          throw new TypeError(`unknown property: ${String(propertyName)} on object. Path: ${propertyPath}`);
+        }
+
+        schema = Schema.make(propertyType).annotations(propertyType.annotations);
+      }
+    }
+
+    return schema;
+  }
+
+  public static getTargetPropertySchema(target: any, prop: string | symbol): Schema.Schema.AnyNoContext {
+    const schema: Schema.Schema.AnyNoContext | undefined = (target as any)[SchemaId];
+    invariant(schema, 'target has no schema');
+    const arrayAst = unwrapArray(schema.ast);
+    if (arrayAst != null) {
+      return getArrayElementSchema(arrayAst, prop);
+    }
+
+    const propertyType = getPropertyType(schema.ast, prop.toString(), (prop) => target[prop]);
+    if (propertyType == null) {
+      return Schema.Any; // TODO(burdon): HACK.
+    }
+
+    invariant(propertyType, `invalid property: ${prop.toString()}`);
+    return Schema.make(propertyType);
+  }
+}
+
+/**
+ * Tuple AST is used both for:
+ * fixed-length tuples ([string, number]) in which case AST will be { elements: [Schema.String, Schema.Number] }
+ * variable-length arrays (Array<string | number>) in which case AST will be { rest: [Schema.Union(Schema.String, Schema.Number)] }
+ */
+const getArrayElementSchema = (
+  tupleAst: SchemaAST.TupleType,
+  property: string | symbol | number,
+): Schema.Schema.AnyNoContext => {
+  const elementIndex = typeof property === 'string' ? parseInt(property, 10) : Number.NaN;
+  if (Number.isNaN(elementIndex)) {
+    invariant(property === 'length', `invalid array property: ${String(property)}`);
+    return Schema.Number;
+  }
+  if (elementIndex < tupleAst.elements.length) {
+    const elementType = tupleAst.elements[elementIndex].type;
+    return Schema.make(elementType).annotations(elementType.annotations);
+  }
+
+  const restType = tupleAst.rest;
+  return Schema.make(restType[0].type).annotations(restType[0].annotations);
+};
+
+const flattenUnion = (typeAst: SchemaAST.AST): SchemaAST.AST[] =>
+  SchemaAST.isUnion(typeAst) ? typeAst.types.flatMap(flattenUnion) : [typeAst];
+
+const getProperties = (
+  typeAst: SchemaAST.AST,
+  getTargetPropertyFn: (propertyName: string) => any,
+): SchemaAST.PropertySignature[] => {
+  const astCandidates = flattenUnion(typeAst);
+  const typeAstList = astCandidates.filter((type) => SchemaAST.isTypeLiteral(type)) as SchemaAST.TypeLiteral[];
+  if (typeAstList.length === 0) {
+    return [];
+  }
+  if (typeAstList.length === 1) {
+    return SchemaAST.getPropertySignatures(typeAstList[0]);
+  }
+
+  const typeDiscriminators = getTypeDiscriminators(typeAstList);
+  const targetPropertyValue = getTargetPropertyFn(String(typeDiscriminators[0].name));
+  const typeIndex = typeDiscriminators.findIndex((p) => targetPropertyValue === (p.type as SchemaAST.Literal).literal);
+  invariant(typeIndex !== -1, 'discriminator field not set on target');
+  return SchemaAST.getPropertySignatures(typeAstList[typeIndex]);
+};
+
+const getPropertyType = (
+  ast: SchemaAST.AST,
+  propertyName: string,
+  getTargetPropertyFn: (propertyName: string) => any,
+): SchemaAST.AST | null => {
+  const anyOrObject = unwrapAst(
+    ast,
+    (candidate) => SchemaAST.isAnyKeyword(candidate) || SchemaAST.isObjectKeyword(candidate),
+  );
+  if (anyOrObject != null) {
+    return ast;
+  }
+
+  const typeOrDiscriminatedUnion = unwrapAst(ast, (t) => {
+    return SchemaAST.isTypeLiteral(t) || (SchemaAST.isUnion(t) && t.types.some((t) => SchemaAST.isTypeLiteral(t)));
+  });
+  if (typeOrDiscriminatedUnion == null) {
+    return null;
+  }
+
+  const targetProperty = getProperties(typeOrDiscriminatedUnion, getTargetPropertyFn).find(
+    (p) => p.name === propertyName,
+  );
+  if (targetProperty != null) {
+    return unwrapAst(targetProperty.type);
+  }
+
+  const indexSignatureType = unwrapAst(ast, SchemaAST.isTypeLiteral);
+  if (
+    indexSignatureType &&
+    SchemaAST.isTypeLiteral(indexSignatureType) &&
+    indexSignatureType.indexSignatures.length > 0
+  ) {
+    return unwrapAst(indexSignatureType.indexSignatures[0].type);
+  }
+
+  return null;
+};
+
+const getTypeDiscriminators = (typeAstList: SchemaAST.TypeLiteral[]): SchemaAST.PropertySignature[] => {
+  const discriminatorPropCandidates = typeAstList
+    .flatMap(SchemaAST.getPropertySignatures)
+    .filter((p) => SchemaAST.isLiteral(p.type));
+  const propertyName = discriminatorPropCandidates[0].name;
+  const isValidDiscriminator = discriminatorPropCandidates.every((p) => p.name === propertyName && !p.isOptional);
+  const everyTypeHasDiscriminator = discriminatorPropCandidates.length === typeAstList.length;
+  const isDiscriminatedUnion = isValidDiscriminator && everyTypeHasDiscriminator;
+  invariant(isDiscriminatedUnion, 'type ambiguity: every type in a union must have a single unique-literal field');
+  return discriminatorPropCandidates;
+};
+
+/**
+ * Used to check that rootAst is for a type matching the provided predicate.
+ * That's not always straightforward because types of optionality and recursive types.
+ * const Task = Schema.Struct({
+ *   ...,
+ *   previous?: Schema.optional(Schema.suspend(() => Task)),
+ * });
+ * Here the AST for `previous` field is going to be Union(Suspend(Type), Undefined).
+ * SchemaAST.isTypeLiteral(field) will return false, but unwrapAst(field, (ast) => SchemaAST.isTypeLiteral(ast))
+ * will return true.
+ */
+const unwrapAst = (rootAst: SchemaAST.AST, predicate?: (ast: SchemaAST.AST) => boolean): SchemaAST.AST | null => {
+  let ast: SchemaAST.AST | undefined = rootAst;
+  while (ast != null) {
+    if (predicate?.(ast)) {
+      return ast;
+    }
+
+    if (SchemaAST.isUnion(ast)) {
+      const next: any = ast.types.find((t) => (predicate != null && predicate(t)) || SchemaAST.isSuspend(t));
+      if (next != null) {
+        ast = next;
+        continue;
+      }
+    }
+
+    if (SchemaAST.isSuspend(ast)) {
+      ast = ast.f();
+    } else {
+      return predicate == null ? ast : null;
+    }
+  }
+
+  return null;
+};
+
+const unwrapArray = (ast: SchemaAST.AST) => unwrapAst(ast, SchemaAST.isTupleType) as SchemaAST.TupleType | null;
+
+export const checkIdNotPresentOnSchema = (schema: Schema.Schema<any, any, any>) => {
+  invariant(SchemaAST.isTypeLiteral(schema.ast));
+  const idProperty = SchemaAST.getPropertySignatures(schema.ast).find((prop) => prop.name === 'id');
+  if (idProperty != null) {
+    throw new Error('"id" property name is reserved');
+  }
+};
+
+type KeyPath = readonly (string | number)[];

package/src/internal/object/typed-object.test.ts

@@ -0,0 +1,34 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+import * as SchemaAST from 'effect/SchemaAST';
+import { describe, expect, test } from 'vitest';
+
+import { TypedObject } from './typed-object';
+
+class Organization extends TypedObject({
+  typename: 'example.com/type/Organization',
+  version: '0.1.0',
+})({
+  name: Schema.String,
+}) {}
+
+describe('EchoObject class DSL', () => {
+  test('type is a valid schema', async () => {
+    expect(Schema.isSchema(Organization)).to.be.true;
+  });
+
+  test('static typename accessor', async () => {
+    expect(Organization.typename).to.eq('example.com/type/Organization');
+  });
+
+  test('expect constructor to throw', async () => {
+    expect(() => new Organization()).to.throw();
+  });
+
+  test('expect schema', async () => {
+    expect(SchemaAST.isTypeLiteral(Organization.ast)).to.be.true;
+  });
+});

package/src/internal/object/typed-object.ts

@@ -0,0 +1,81 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+
+import { invariant } from '@dxos/invariant';
+
+import { EntityKind, SchemaVersion, type TypeAnnotation, TypeAnnotationId, type TypeMeta, Typename } from '../ast';
+import { type HasId } from '../types';
+
+import { type TypedObjectFields, type TypedObjectOptions, makeTypedEntityClass } from './common';
+
+/**
+ * Definition for an object type that can be stored in an ECHO database.
+ * Implements effect schema to define object properties.
+ * Has a typename and version.
+ *
+ * In contrast to {@link EchoSchema} this definition is not recorded in the database.
+ */
+export interface TypedObject<A = any, I = any> extends TypeMeta, Schema.Schema<A, I> {}
+
+/**
+ * Typed object that could be used as a prototype in class definitions.
+ * This is an internal API type.
+ * Use {@link TypedObject} for the common use-cases.
+ */
+export interface TypedObjectPrototype<A = any, I = any> extends TypedObject<A, I> {
+  /** Type constructor. */
+  new (): HasId & A;
+}
+
+export type TypedObjectProps = TypeMeta & {
+  // TODO(dmaretskyi): Remove after all legacy types has been removed.
+  disableValidation?: boolean;
+};
+
+/**
+ * Base class factory for typed objects.
+ * @deprecated Use Function.pipe(Type.Obj) instead.
+ */
+export const TypedObject = ({
+  typename: typenameParam,
+  version: versionParam,
+  disableValidation,
+}: TypedObjectProps) => {
+  const typename = Typename.make(typenameParam, { disableValidation });
+  const version = SchemaVersion.make(versionParam, { disableValidation });
+
+  /**
+   * Return class definition factory.
+   */
+  return <SchemaFields extends Schema.Struct.Fields, Options extends TypedObjectOptions>(
+    fields: SchemaFields,
+    options?: Options,
+  ): TypedObjectPrototype<TypedObjectFields<SchemaFields, Options>, Schema.Struct.Encoded<SchemaFields>> => {
+    // Create schema from fields.
+    const schema: Schema.Schema.All = options?.record
+      ? Schema.Struct(fields, { key: Schema.String, value: Schema.Any })
+      : Schema.Struct(fields);
+
+    // Set ECHO object id property.
+    const typeSchema = Schema.extend(
+      Schema.mutable(options?.partial ? Schema.partial(schema) : schema),
+      Schema.Struct({ id: Schema.String }),
+    );
+
+    // Set ECHO annotations.
+    invariant(typeof EntityKind.Object === 'string');
+    const annotatedSchema = typeSchema.annotations({
+      [TypeAnnotationId]: { kind: EntityKind.Object, typename, version } satisfies TypeAnnotation,
+    });
+
+    /**
+     * Return class definition.
+     * NOTE: Actual reactive ECHO objects must be created via the `live(Type)` function.
+     */
+    // TODO(burdon): This is missing fields required by TypedObject (e.g., Type, Encoded, Context)?
+    return class TypedObject extends makeTypedEntityClass(typename, version, annotatedSchema as any) {} as any;
+  };
+};

package/src/internal/object/typed-relation.ts

@@ -0,0 +1,85 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+
+import { invariant } from '@dxos/invariant';
+
+import { EntityKind, SchemaVersion, type TypeAnnotation, TypeAnnotationId, type TypeMeta, Typename } from '../ast';
+import { type HasId } from '../types';
+
+import { type TypedObjectFields, type TypedObjectOptions, makeTypedEntityClass } from './common';
+import { type RelationSourceTargetRefs } from './relation';
+
+/**
+ * Definition for an object type that can be stored in an ECHO database.
+ * Implements effect schema to define object properties.
+ * Has a typename and version.
+ *
+ * In contrast to {@link EchoSchema} this definition is not recorded in the database.
+ */
+export interface TypedRelation<A = any, I = any> extends TypeMeta, Schema.Schema<A, I> {}
+
+/**
+ * Typed object that could be used as a prototype in class definitions.
+ * This is an internal API type.
+ * Use {@link TypedRelation} for the common use-cases.
+ */
+export interface TypedRelationPrototype<A = any, I = any> extends TypedRelation<A, I> {
+  /** Type constructor. */
+  new (): HasId & A;
+}
+
+export type TypedRelationProps = TypeMeta & {
+  // TODO(dmaretskyi): Remove after all legacy types has been removed.
+  disableValidation?: boolean;
+};
+
+/**
+ * Base class factory for typed objects.
+ * @deprecated Use {@link EchoRelation} instead.
+ */
+export const TypedRelation = ({
+  typename: typenameParam,
+  version: versionParam,
+  disableValidation,
+}: TypedRelationProps) => {
+  const typename = Typename.make(typenameParam, { disableValidation });
+  const version = SchemaVersion.make(versionParam, { disableValidation });
+
+  /**
+   * Return class definition factory.
+   */
+  return <SchemaFields extends Schema.Struct.Fields, Options extends TypedObjectOptions>(
+    fields: SchemaFields,
+    options?: Options,
+  ): TypedRelationPrototype<
+    TypedObjectFields<SchemaFields, Options> & RelationSourceTargetRefs,
+    Schema.Struct.Encoded<SchemaFields>
+  > => {
+    // Create schema from fields.
+    const schema: Schema.Schema.All = options?.record
+      ? Schema.Struct(fields, { key: Schema.String, value: Schema.Any })
+      : Schema.Struct(fields);
+
+    // Set ECHO object id property.
+    const typeSchema = Schema.extend(
+      Schema.mutable(options?.partial ? Schema.partial(schema) : schema),
+      Schema.Struct({ id: Schema.String }),
+    );
+
+    // Set ECHO annotations.
+    invariant(typeof EntityKind.Relation === 'string');
+    const annotatedSchema = typeSchema.annotations({
+      [TypeAnnotationId]: { kind: EntityKind.Relation, typename, version } satisfies TypeAnnotation,
+    });
+
+    /**
+     * Return class definition.
+     * NOTE: Actual reactive ECHO objects must be created via the `live(Type)` function.
+     */
+    // TODO(burdon): This is missing fields required by TypedRelation (e.g., Type, Encoded, Context)?
+    return class TypedRelation extends makeTypedEntityClass(typename, version, annotatedSchema as any) {} as any;
+  };
+};

package/src/internal/object/typename.ts

@@ -0,0 +1,61 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { invariant } from '@dxos/invariant';
+import { DXN } from '@dxos/keys';
+
+import { getSchemaTypename } from '../ast';
+import { type BaseObject } from '../types';
+
+import { getSchema } from './accessors';
+import { TypeId } from './model';
+
+/**
+ * Gets the typename of the object without the version.
+ * Returns only the name portion, not the DXN.
+ * @example "example.org/type/Contact"
+ */
+export const getTypename = (obj: BaseObject): string | undefined => {
+  const schema = getSchema(obj);
+  if (schema != null) {
+    // Try to extract typename from DXN.
+    return getSchemaTypename(schema);
+  } else {
+    const type = getType(obj);
+    return type?.asTypeDXN()?.type;
+  }
+};
+
+/**
+ * @internal
+ */
+// TODO(dmaretskyi): Rename setTypeDXN.
+export const setTypename = (obj: any, typename: DXN) => {
+  invariant(typename instanceof DXN, 'Invalid type.');
+  Object.defineProperty(obj, TypeId, {
+    value: typename,
+    writable: false,
+    enumerable: false,
+    configurable: false,
+  });
+};
+
+/**
+ * @returns Object type as {@link DXN}.
+ * @returns undefined if the object doesn't have a type.
+ * @example `dxn:example.com/type/Contact:1.0.0`
+ */
+export const getType = (obj: BaseObject): DXN | undefined => {
+  if (!obj) {
+    return undefined;
+  }
+
+  const type = (obj as any)[TypeId];
+  if (!type) {
+    return undefined;
+  }
+
+  invariant(type instanceof DXN, 'Invalid object.');
+  return type;
+};

package/src/internal/object/version.ts

@@ -0,0 +1,22 @@
+//
+// NOTE: Those types must match the ones defined at @dxos/echo. We duplicated them murely due to technical constrains.
+//
+
+/**
+ * Getter to get object version.
+ */
+//
+// Copyright 2025 DXOS.org
+//
+
+export const VersionTypeId: unique symbol = Symbol('@dxos/echo/Version');
+
+/**
+ * Represent object version.
+ * May be backed by Automerge.
+ * Objects with no history are not versioned.
+ */
+export interface Version {
+  [VersionTypeId]: {};
+  automergeHeads?: string[];
+}

package/src/internal/projection/compose.test.ts

@@ -0,0 +1,43 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+import { describe, test } from 'vitest';
+
+import { FieldPath } from '../ast';
+import { FormatAnnotation, FormatEnum } from '../formats';
+import { toJsonSchema } from '../json';
+import { ECHO_ANNOTATIONS_NS_KEY } from '../json-schema';
+import { TypedObject } from '../object';
+
+import { composeSchema } from './compose';
+
+describe('schema composition', () => {
+  test('schema composition', ({ expect }) => {
+    class BaseType extends TypedObject({ typename: 'example.com/Person', version: '0.1.0' })({
+      name: Schema.String,
+      email: Schema.String,
+    }) {}
+
+    const OverlaySchema = Schema.Struct({
+      email: Schema.String.pipe(FieldPath('$.email'), FormatAnnotation.set(FormatEnum.Email)),
+    });
+
+    const baseSchema = toJsonSchema(BaseType);
+    const overlaySchema = toJsonSchema(OverlaySchema);
+    const composedSchema = composeSchema(baseSchema, overlaySchema);
+    expect(composedSchema.properties).to.deep.eq({
+      email: {
+        type: 'string',
+        format: FormatEnum.Email,
+        // TODO(dmaretskyi): Should use the new field.
+        [ECHO_ANNOTATIONS_NS_KEY]: {
+          meta: {
+            path: '$.email',
+          },
+        },
+      },
+    });
+  });
+});

package/src/internal/projection/compose.ts

@@ -0,0 +1,36 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { invariant } from '@dxos/invariant';
+
+import { type JsonSchemaType } from '../json-schema';
+import { getSnapshot } from '../schema';
+
+/**
+ * Creates a composite schema from the source and projection schemas.
+ */
+// TODO(burdon): Use effect schema projections.
+// TODO(burdon): Can avoid having to call this every time we modify any property on the view?
+export const composeSchema = (source: JsonSchemaType, target: JsonSchemaType): JsonSchemaType => {
+  const result: JsonSchemaType = getSnapshot(target);
+  invariant('type' in result && result.type === 'object', 'source schema must be an object');
+  invariant('type' in source && source.type === 'object', 'target schema must be an object');
+
+  for (const prop in result.properties) {
+    const propSchema = source.properties![prop]; // TODO(dmaretskyi): Find by json-path instead.
+    const annotations = (propSchema as JsonSchemaType)?.annotations?.meta;
+    if (annotations) {
+      (result.properties[prop] as JsonSchemaType).annotations ??= {};
+      (result.properties[prop] as JsonSchemaType).annotations!.meta ??= {};
+      for (const key in annotations) {
+        (result.properties[prop] as JsonSchemaType).annotations!.meta![key] ??= {};
+        Object.assign((result.properties[prop] as JsonSchemaType).annotations!.meta![key], annotations[key], {
+          ...(result.properties[prop] as JsonSchemaType).annotations!.meta![key],
+        });
+      }
+    }
+  }
+
+  return result;
+};

package/src/internal/projection/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export * from './compose';