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

package/src/internal/object/json-serializer.ts

@@ -5,48 +5,60 @@
 import * as Schema from 'effect/Schema';
 
 import { raise } from '@dxos/debug';
-import { type EncodedReference, type ObjectMeta, isEncodedReference } from '@dxos/echo-protocol';
+import { type EncodedReference, ObjectStructure, isEncodedReference } from '@dxos/echo-protocol';
 import { assertArgument, invariant } from '@dxos/invariant';
 import { DXN, ObjectId } from '@dxos/keys';
-import { defineHiddenProperty } from '@dxos/live-object';
 import { assumeType, deepMapValues, visitValues } from '@dxos/util';
 
-import { EntityKind } from '../ast';
-import { Ref, type RefResolver, refFromEncodedReference, setRefResolver } from '../ref';
-import { type AnyEchoObject } from '../types';
-
-import { setSchema } from './accessors';
-import { ObjectMetaSchema } from './meta';
+import type * as Obj from '../../Obj';
+import { getTypeDXN, setTypename } from '../annotations';
 import {
   ATTR_DELETED,
-  ATTR_META,
   ATTR_RELATION_SOURCE,
   ATTR_RELATION_TARGET,
   ATTR_SELF_DXN,
-  ATTR_TYPE,
-  EntityKindId,
-  MetaId,
   type ObjectJSON,
   RelationSourceDXNId,
   RelationSourceId,
   RelationTargetDXNId,
   RelationTargetId,
   SelfDXNId,
-  TypeId,
-  assertObjectModelShape,
-} from './model';
-import { getType, setTypename } from './typename';
+  assertObjectModel,
+} from '../entities';
+import { attachTypedJsonSerializer, defineHiddenProperty, typedJsonSerializer } from '../proxy';
+import { Ref, type RefResolver, refFromEncodedReference, setRefResolver } from '../ref';
+import {
+  ATTR_META,
+  ATTR_TYPE,
+  type AnyEntity,
+  EntityKind,
+  KindId,
+  MetaId,
+  ObjectMetaSchema,
+  setSchema,
+} from '../types';
 
-type DeepReplaceRef<T> =
-  T extends Ref<any> ? EncodedReference : T extends object ? { [K in keyof T]: DeepReplaceRef<T[K]> } : T;
+// Re-export for backward compatibility.
+export { attachTypedJsonSerializer };
 
-type SerializedObject<T extends { id: string }> = { [K in keyof T]: DeepReplaceRef<T[K]> } & ObjectJSON;
+type DeepReplaceRef<T> =
+  T extends Ref<any>
+    ? EncodedReference
+    : T extends object
+      ? {
+          [K in keyof T]: DeepReplaceRef<T[K]>;
+        }
+      : T;
+
+type SerializedObject<T extends { id: string }> = {
+  [K in keyof T]: DeepReplaceRef<T[K]>;
+} & ObjectJSON;
 
 /**
  * Converts object to it's JSON representation.
  */
-export const objectToJSON = <T extends AnyEchoObject>(obj: T): SerializedObject<T> => {
-  const typename = getType(obj)?.toString();
+export const objectToJSON = <T extends AnyEntity>(obj: T): SerializedObject<T> => {
+  const typename = getTypeDXN(obj)?.toString();
   invariant(typename && typeof typename === 'string');
   return typedJsonSerializer.call(obj);
 };
@@ -55,13 +67,12 @@ export const objectToJSON = <T extends AnyEchoObject>(obj: T): SerializedObject<
  * Creates an object from it's json representation.
  * Performs schema validation.
  * References and schema will be resolvable if the `refResolver` is provided.
- *
  * The function need to be async to support resolving the schema as well as the relation endpoints.
  */
 export const objectFromJSON = async (
   jsonData: unknown,
   { refResolver, dxn }: { refResolver?: RefResolver; dxn?: DXN } = {},
-): Promise<AnyEchoObject> => {
+): Promise<AnyEntity> => {
   assumeType<ObjectJSON>(jsonData);
   assertArgument(typeof jsonData === 'object' && jsonData !== null, 'jsonData', 'expect object');
   assertArgument(typeof jsonData[ATTR_TYPE] === 'string', 'jsonData[ATTR_TYPE]', 'expected object to have a type');
@@ -82,7 +93,6 @@ export const objectFromJSON = async (
   }
 
   invariant(ObjectId.isValid(obj.id), 'Invalid object id');
-
   setTypename(obj, type);
   if (schema) {
     setSchema(obj, schema);
@@ -94,39 +104,39 @@ export const objectFromJSON = async (
     const sourceDxn: DXN = DXN.parse(jsonData[ATTR_RELATION_SOURCE] ?? raise(new TypeError('Missing relation source')));
     const targetDxn: DXN = DXN.parse(jsonData[ATTR_RELATION_TARGET] ?? raise(new TypeError('Missing relation target')));
 
-    // TODO(dmaretskyi): Async!
-    const source = (await refResolver?.resolve(sourceDxn)) as AnyEchoObject | undefined;
-    const target = (await refResolver?.resolve(targetDxn)) as AnyEchoObject | undefined;
+    const source = (await refResolver?.resolve(sourceDxn)) as AnyEntity | undefined;
+    const target = (await refResolver?.resolve(targetDxn)) as AnyEntity | undefined;
 
-    defineHiddenProperty(obj, EntityKindId, EntityKind.Relation);
+    defineHiddenProperty(obj, KindId, EntityKind.Relation);
     defineHiddenProperty(obj, RelationSourceDXNId, sourceDxn);
     defineHiddenProperty(obj, RelationTargetDXNId, targetDxn);
     defineHiddenProperty(obj, RelationSourceId, source);
     defineHiddenProperty(obj, RelationTargetId, target);
   } else {
-    defineHiddenProperty(obj, EntityKindId, EntityKind.Object);
+    defineHiddenProperty(obj, KindId, EntityKind.Object);
   }
 
   if (typeof jsonData[ATTR_META] === 'object') {
     const meta = await ObjectMetaSchema.pipe(Schema.decodeUnknownPromise)(jsonData[ATTR_META]);
-
-    // Defensive programming.
     invariant(Array.isArray(meta.keys));
-
     defineHiddenProperty(obj, MetaId, meta);
+  } else {
+    defineHiddenProperty(obj, MetaId, {
+      keys: [],
+    });
   }
 
   if (dxn) {
     defineHiddenProperty(obj, SelfDXNId, dxn);
   }
 
-  assertObjectModelShape(obj);
+  assertObjectModel(obj);
   invariant((obj as any)[ATTR_TYPE] === undefined, 'Invalid object model');
-  invariant((obj as any)[ATTR_SELF_DXN] === undefined, 'Invalid object model');
+  invariant((obj as any)[ATTR_META] === undefined, 'Invalid object model');
   invariant((obj as any)[ATTR_DELETED] === undefined, 'Invalid object model');
+  invariant((obj as any)[ATTR_SELF_DXN] === undefined, 'Invalid object model');
   invariant((obj as any)[ATTR_RELATION_SOURCE] === undefined, 'Invalid object model');
   invariant((obj as any)[ATTR_RELATION_TARGET] === undefined, 'Invalid object model');
-  invariant((obj as any)[ATTR_META] === undefined, 'Invalid object model');
   return obj;
 };
 
@@ -135,91 +145,44 @@ const decodeGeneric = (jsonData: unknown, options: { refResolver?: RefResolver }
     [ATTR_TYPE]: _type,
     [ATTR_META]: _meta,
     [ATTR_DELETED]: _deleted,
+    [ATTR_SELF_DXN]: _selfDxn,
     [ATTR_RELATION_SOURCE]: _relationSource,
     [ATTR_RELATION_TARGET]: _relationTarget,
-    [ATTR_SELF_DXN]: _selfDxn,
     ...props
   } = jsonData as any;
 
-  return deepMapValues(props, (value, recurse) => {
+  return deepMapValues(props, (value, visitor) => {
     if (isEncodedReference(value)) {
       return refFromEncodedReference(value, options.refResolver);
     }
-    return recurse(value);
+
+    return visitor(value);
   });
 };
 
-export const setRefResolverOnData = (obj: AnyEchoObject, refResolver: RefResolver) => {
-  const go = (value: unknown) => {
+export const setRefResolverOnData = (obj: AnyEntity, refResolver: RefResolver) => {
+  const visitor = (value: unknown) => {
     if (Ref.isRef(value)) {
       setRefResolver(value, refResolver);
     } else {
-      visitValues(value, go);
+      visitValues(value, visitor);
     }
   };
 
-  go(obj);
+  visitor(obj);
 };
 
-export const attachTypedJsonSerializer = (obj: any) => {
-  const descriptor = Object.getOwnPropertyDescriptor(obj, 'toJSON');
-  if (descriptor) {
-    return;
-  }
-
-  Object.defineProperty(obj, 'toJSON', {
-    value: typedJsonSerializer,
-    writable: false,
-    enumerable: false,
-    // Setting `configurable` to false breaks proxy invariants, should be fixable.
-    configurable: true,
-  });
-};
-
-// NOTE: KEEP as function.
-const typedJsonSerializer = function (this: any) {
-  const { id, ...rest } = this;
-  const result: any = {
-    id,
+/**
+ * Convert ObjectStructure to JSON data for indexing.
+ * Different from {@link objectToJSON} as it takes the internal {@link ObjectStructure} representation directly
+ */
+export const objectStructureToJson = (objectId: string, structure: ObjectStructure): Obj.JSON => {
+  return {
+    ...structure.data,
+    id: objectId,
+    [ATTR_TYPE]: (ObjectStructure.getTypeReference(structure)?.['/'] ?? '') as DXN.String,
+    [ATTR_DELETED]: ObjectStructure.isDeleted(structure),
+    [ATTR_RELATION_SOURCE]: ObjectStructure.getRelationSource(structure)?.['/'] as DXN.String | undefined,
+    [ATTR_RELATION_TARGET]: ObjectStructure.getRelationTarget(structure)?.['/'] as DXN.String | undefined,
   };
-
-  if (this[TypeId]) {
-    result[ATTR_TYPE] = this[TypeId].toString();
-  }
-
-  if (this[SelfDXNId]) {
-    result[ATTR_SELF_DXN] = this[SelfDXNId].toString();
-  }
-
-  if (this[RelationSourceDXNId]) {
-    const sourceDXN = this[RelationSourceDXNId];
-    invariant(sourceDXN instanceof DXN);
-    result[ATTR_RELATION_SOURCE] = sourceDXN.toString();
-  }
-  if (this[RelationTargetDXNId]) {
-    const targetDXN = this[RelationTargetDXNId];
-    invariant(targetDXN instanceof DXN);
-    result[ATTR_RELATION_TARGET] = targetDXN.toString();
-  }
-
-  if (this[MetaId]) {
-    result[ATTR_META] = serializeMeta(this[MetaId]);
-  }
-
-  Object.assign(result, serializeData(rest));
-  return result;
-};
-
-const serializeData = (data: unknown) => {
-  return deepMapValues(data, (value, recurse) => {
-    if (Ref.isRef(value)) {
-      // TODO(dmaretskyi): Should this be configurable?
-      return value.noInline().encode();
-    }
-    return recurse(value);
-  });
-};
-
-const serializeMeta = (meta: ObjectMeta) => {
-  return deepMapValues(meta, (value, recurse) => recurse(value));
 };

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

@@ -2,240 +2,5 @@
 // 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)[];
+// Re-export from proxy for backward compatibility.
+export { SchemaValidator, checkIdNotPresentOnSchema } from '../proxy';