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

package/src/internal/object/expando.ts

@@ -1,21 +0,0 @@
-//
-// Copyright 2024 DXOS.org
-//
-
-import * as Schema from 'effect/Schema';
-
-import { EchoObject } from './entity';
-
-export const EXPANDO_TYPENAME = 'dxos.org/type/Expando';
-
-const ExpandoSchema = Schema.Struct({}, { key: Schema.String, value: Schema.Any }).pipe(
-  EchoObject({ typename: EXPANDO_TYPENAME, version: '0.1.0' }),
-);
-
-/**
- * Expando object is an object with an arbitrary set of properties.
- */
-// TODO(dmaretskyi): Can we consider expando a top-type, i.e. have a ref to expando potentially be a valid ref to any object?
-export interface Expando extends Schema.Schema.Type<typeof ExpandoSchema> {}
-
-export const Expando: Schema.Schema<Expando> = ExpandoSchema;

package/src/internal/object/index.ts

@@ -1,19 +0,0 @@
-//
-// Copyright 2024 DXOS.org
-//
-
-export * from './common';
-export * from './create';
-export * from './entity';
-export * from './expando';
-export * from './ids';
-export * from './json-serializer';
-export * from './meta';
-export type * from './relation';
-export * from './typed-object';
-export * from './typename';
-export * from './deleted';
-export * from './model';
-export * from './accessors';
-export * from './schema-validator';
-export * from './version';

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

@@ -1,99 +0,0 @@
-//
-// Copyright 2025 DXOS.org
-//
-
-import { describe, expect, test } from 'vitest';
-
-import { DXN } from '@dxos/keys';
-
-import { EntityKind, getSchemaDXN, getSchemaTypename } from '../ast';
-import { Ref, StaticRefResolver } from '../ref';
-import { Testing } from '../testing';
-
-import { getObjectDXN, getSchema } from './accessors';
-import { create } from './create';
-import { objectFromJSON, objectToJSON } from './json-serializer';
-import { getMeta } from './meta';
-import { ATTR_TYPE, EntityKindId, MetaId, RelationSourceId, RelationTargetId, TypeId } from './model';
-import { getType, getTypename } from './typename';
-
-describe('Object JSON serializer', () => {
-  test('should serialize and deserialize object', async () => {
-    const contact = create(Testing.Contact, {
-      name: 'John Doe',
-    });
-    getMeta(contact).keys.push({ id: '12345', source: 'crm.example.com' });
-
-    const task = create(Testing.Task, {
-      title: 'Polish my shoes',
-      assignee: Ref.make(contact),
-    });
-
-    const contactJson = objectToJSON(contact);
-    const taskJson = objectToJSON(task);
-
-    expect(contactJson.id).toBe(contact.id);
-    expect(contactJson[ATTR_TYPE]).toEqual(getSchemaDXN(Testing.Contact)!.toString());
-    expect(contactJson.name).toEqual('John Doe');
-
-    expect(taskJson.id).toBe(task.id);
-    expect(taskJson[ATTR_TYPE]).toEqual(getSchemaDXN(Testing.Task)!.toString());
-    expect(taskJson.title).toEqual('Polish my shoes');
-    expect(taskJson.assignee).toEqual({ '/': DXN.fromLocalObjectId(contact.id).toString() });
-
-    const refResolver = new StaticRefResolver()
-      .addSchema(Testing.Contact)
-      .addSchema(Testing.Task)
-      .addObject(contact)
-      .addObject(task);
-
-    const contactFromJson = (await objectFromJSON(contactJson, { refResolver })) as Testing.Contact;
-    const taskFromJson = (await objectFromJSON(taskJson, { refResolver })) as Testing.Task;
-
-    expect(contactFromJson.id).toBe(contact.id);
-    expect(contactFromJson.name).toBe('John Doe');
-    expect((contactFromJson as any)[TypeId]).toEqual(getSchemaDXN(Testing.Contact));
-    expect((contactFromJson as any)[EntityKindId]).toBe(EntityKind.Object);
-    expect((contactFromJson as any)[RelationSourceId]).toBeUndefined();
-    expect((contactFromJson as any)[RelationTargetId]).toBeUndefined();
-    expect((contactFromJson as any)[MetaId]).toEqual({
-      keys: [
-        {
-          id: '12345',
-          source: 'crm.example.com',
-        },
-      ],
-    });
-    expect(getType(contactFromJson)?.toString()).toBe(getSchemaDXN(Testing.Contact)!.toString());
-    expect(getTypename(contactFromJson)).toBe(getSchemaTypename(Testing.Contact));
-    expect(getObjectDXN(contactFromJson)?.toString()).toEqual(getObjectDXN(contact)?.toString());
-    expect(getSchema(contactFromJson)).toEqual(Testing.Contact);
-
-    expect(taskFromJson.id).toBe(task.id);
-    expect(taskFromJson.title).toBe('Polish my shoes');
-    expect(taskFromJson.assignee!.dxn).toEqual(DXN.fromLocalObjectId(contact.id));
-    expect(taskFromJson.assignee!.target).toEqual(contact);
-    expect(await taskFromJson.assignee!.load()).toEqual(contact);
-    expect((taskFromJson as any)[TypeId]).toEqual(getSchemaDXN(Testing.Task));
-    expect((taskFromJson as any)[EntityKindId]).toBe(EntityKind.Object);
-    expect((taskFromJson as any)[RelationSourceId]).toBeUndefined();
-    expect((taskFromJson as any)[RelationTargetId]).toBeUndefined();
-    expect((taskFromJson as any)[MetaId]).toEqual({ keys: [] });
-    expect(getSchema(taskFromJson)).toEqual(Testing.Task);
-  });
-
-  test('serialize with unresolved schema', async () => {
-    const contact = create(Testing.Contact, {
-      name: 'John Doe',
-    });
-    const contactJson = objectToJSON(contact);
-    const contactFromJson: any = await objectFromJSON(contactJson);
-
-    expect(contactFromJson.id).toBe(contact.id);
-    expect(contactFromJson.name).toBe('John Doe');
-    expect(getSchema(contactFromJson)).toBeUndefined();
-    expect(getTypename(contactFromJson)).toEqual(getSchemaTypename(Testing.Contact));
-    expect(getObjectDXN(contactFromJson)).toEqual(getObjectDXN(contact));
-    expect(getType(contactFromJson)).toEqual(getSchemaDXN(Testing.Contact));
-  });
-});

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

@@ -1,225 +0,0 @@
-//
-// Copyright 2025 DXOS.org
-//
-
-import * as Schema from 'effect/Schema';
-
-import { raise } from '@dxos/debug';
-import { type EncodedReference, type ObjectMeta, 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 {
-  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';
-
-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();
-  invariant(typename && typeof typename === 'string');
-  return typedJsonSerializer.call(obj);
-};
-
-/**
- * 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> => {
-  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');
-  assertArgument(typeof jsonData.id === 'string', 'jsonData.id', 'expected object to have an id');
-
-  const type = DXN.parse(jsonData[ATTR_TYPE]);
-  const schema = await refResolver?.resolveSchema(type);
-  invariant(schema === undefined || Schema.isSchema(schema));
-
-  let obj: any;
-  if (schema != null) {
-    obj = await schema.pipe(Schema.decodeUnknownPromise)(jsonData);
-    if (refResolver) {
-      setRefResolverOnData(obj, refResolver);
-    }
-  } else {
-    obj = decodeGeneric(jsonData, { refResolver });
-  }
-
-  invariant(ObjectId.isValid(obj.id), 'Invalid object id');
-
-  setTypename(obj, type);
-  if (schema) {
-    setSchema(obj, schema);
-  }
-
-  const isRelation =
-    typeof jsonData[ATTR_RELATION_SOURCE] === 'string' || typeof jsonData[ATTR_RELATION_TARGET] === 'string';
-  if (isRelation) {
-    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;
-
-    defineHiddenProperty(obj, EntityKindId, EntityKind.Relation);
-    defineHiddenProperty(obj, RelationSourceDXNId, sourceDxn);
-    defineHiddenProperty(obj, RelationTargetDXNId, targetDxn);
-    defineHiddenProperty(obj, RelationSourceId, source);
-    defineHiddenProperty(obj, RelationTargetId, target);
-  } else {
-    defineHiddenProperty(obj, EntityKindId, 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);
-  }
-
-  if (dxn) {
-    defineHiddenProperty(obj, SelfDXNId, dxn);
-  }
-
-  assertObjectModelShape(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_DELETED] === 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;
-};
-
-const decodeGeneric = (jsonData: unknown, options: { refResolver?: RefResolver }) => {
-  const {
-    [ATTR_TYPE]: _type,
-    [ATTR_META]: _meta,
-    [ATTR_DELETED]: _deleted,
-    [ATTR_RELATION_SOURCE]: _relationSource,
-    [ATTR_RELATION_TARGET]: _relationTarget,
-    [ATTR_SELF_DXN]: _selfDxn,
-    ...props
-  } = jsonData as any;
-
-  return deepMapValues(props, (value, recurse) => {
-    if (isEncodedReference(value)) {
-      return refFromEncodedReference(value, options.refResolver);
-    }
-    return recurse(value);
-  });
-};
-
-export const setRefResolverOnData = (obj: AnyEchoObject, refResolver: RefResolver) => {
-  const go = (value: unknown) => {
-    if (Ref.isRef(value)) {
-      setRefResolver(value, refResolver);
-    } else {
-      visitValues(value, go);
-    }
-  };
-
-  go(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,
-  };
-
-  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/meta.ts

@@ -1,61 +0,0 @@
-//
-// Copyright 2024 DXOS.org
-//
-
-import * as Schema from 'effect/Schema';
-
-import { ForeignKey } from '@dxos/echo-protocol';
-import { invariant } from '@dxos/invariant';
-import { type Comparator, intersection } from '@dxos/util';
-
-import { type BaseObject } from '../types';
-
-import { MetaId } from './model';
-
-//
-// ObjectMeta
-//
-
-// TODO(dmaretskyi): Rename to ObjectMeta
-export const ObjectMetaSchema = Schema.mutable(
-  Schema.Struct({
-    keys: Schema.mutable(Schema.Array(ForeignKey)),
-
-    /**
-     * A set of tags.
-     * Tags are arbitrary application-defined strings.
-     * ECHO makes no assumptions about the tag structure.
-     */
-    // TODO(dmaretskyi): Has to be optional for compatibility with old data.
-    // Defaulting to an empty array is possible but requires a bit more work.
-    tags: Schema.optional(Schema.mutable(Schema.Array(Schema.String))),
-  }),
-);
-export type ObjectMeta = Schema.Schema.Type<typeof ObjectMetaSchema>;
-
-export const foreignKey = (source: string, id: string): ForeignKey => ({ source, id });
-export const foreignKeyEquals = (a: ForeignKey, b: ForeignKey) => a.source === b.source && a.id === b.id;
-
-/**
- * Get metadata from object.
- * Only callable on the object root.
- * @deprecated Use {@link getMeta}.
- */
-// TODO(dmaretskyi): Remove.
-export const getObjectMeta = (obj: any): ObjectMeta => {
-  return getMeta(obj);
-};
-
-/*
- * Get metadata from object.
- * Only callable on the object root.
- */
-export const getMeta = (obj: BaseObject): ObjectMeta => {
-  const metadata = (obj as any)[MetaId];
-  invariant(metadata, 'ObjectMeta not found.');
-  return metadata;
-};
-
-// TODO(dmaretskyi): Move to echo-schema.
-export const compareForeignKeys: Comparator<BaseObject> = (a: BaseObject, b: BaseObject) =>
-  intersection(getMeta(a).keys, getMeta(b).keys, foreignKeyEquals).length > 0;

package/src/internal/object/model.ts

@@ -1,170 +0,0 @@
-//
-// Copyright 2025 DXOS.org
-//
-
-import type * as Schema from 'effect/Schema';
-
-import { type ForeignKey } from '@dxos/echo-protocol';
-import { invariant } from '@dxos/invariant';
-import { DXN, ObjectId } from '@dxos/keys';
-import { assumeType } from '@dxos/util';
-
-import { EntityKind } from '../ast';
-
-import { type ObjectMeta } from './meta';
-import type { Version } from './version';
-
-//
-// Defines the internal model of the echo object.
-//
-
-/**
- * Entity kind.
- */
-export const EntityKindId = Symbol('@dxos/echo/EntityKind');
-
-/**
- * DXN to the object itself.
- */
-export const SelfDXNId = Symbol('@dxos/echo/DXN');
-
-/**
- * Property name for self DXN when object is serialized to JSON.
- */
-export const ATTR_SELF_DXN = '@dxn';
-
-/**
- * DXN to the object type.
- */
-export const TypeId = Symbol('@dxos/echo/Type');
-
-/**
- * Property name for typename when object is serialized to JSON.
- */
-export const ATTR_TYPE = '@type';
-
-/**
- * Reference to the object schema.
- */
-export const SchemaId = Symbol('@dxos/echo/Schema');
-
-/**
- * Deletion marker.
- */
-export const DeletedId = Symbol('@dxos/echo/Deleted');
-
-/**
- * Property name for deleted when object is serialized to JSON.
- */
-export const ATTR_DELETED = '@deleted';
-
-/**
- * Metadata section.
- */
-export const MetaId = Symbol('@dxos/echo/Meta');
-
-/**
- * Property name for meta when object is serialized to JSON.
- */
-export const ATTR_META = '@meta';
-
-/**
- * Used to access relation source ref on live ECHO objects.
- * Reading this symbol must return `Live<EchoObject<any>>` or a DXN.
- */
-export const RelationSourceDXNId: unique symbol = Symbol('@dxos/echo/RelationSourceDXN');
-
-/**
- * Property name for relation source when object is serialized to JSON.
- */
-export const ATTR_RELATION_SOURCE = '@relationSource';
-
-/**
- * Used to access relation target ref on live ECHO objects.
- * Reading this symbol must return `Live<EchoObject<any>>` or a DXN.
- */
-export const RelationTargetDXNId: unique symbol = Symbol('@dxos/echo/RelationTargetDXN');
-
-/**
- * Property name for relation target when object is serialized to JSON.
- */
-export const ATTR_RELATION_TARGET = '@relationTarget';
-
-/**
- * Used to access relation source ref on live ECHO objects.
- * Reading this symbol must return `Live<EchoObject<any>>` or a DXN.
- */
-export const RelationSourceId: unique symbol = Symbol('@dxos/echo/RelationSource');
-
-/**
- * Used to access relation target ref on live ECHO objects.
- * Reading this symbol must return `Live<EchoObject<any>>` or a DXN.
- */
-export const RelationTargetId: unique symbol = Symbol('@dxos/echo/RelationTarget');
-
-/**
- * Getter to get object version.
- */
-export const ObjectVersionId: unique symbol = Symbol('@dxos/echo/ObjectVersion');
-
-/**
- * Internal runtime representation of an object.
- * The fields are accessed through getter functions.
- */
-export interface InternalObjectProps {
-  id: ObjectId;
-  readonly [SelfDXNId]?: DXN;
-
-  // Echo supports untyped objects O_O.
-  readonly [TypeId]?: DXN;
-
-  /**
-   * Returns the schema for the object.
-   */
-  readonly [SchemaId]?: Schema.Schema.AnyNoContext;
-  readonly [EntityKindId]: EntityKind;
-  readonly [DeletedId]?: boolean;
-  readonly [MetaId]?: ObjectMeta;
-  readonly [RelationSourceDXNId]?: DXN;
-  readonly [RelationTargetDXNId]?: DXN;
-  readonly [RelationSourceId]?: InternalObjectProps;
-  readonly [RelationTargetId]?: InternalObjectProps;
-  readonly [ObjectVersionId]?: Version;
-}
-
-/**
- * JSON representation of an object or relation.
- */
-export interface ObjectJSON {
-  id: string;
-  [ATTR_SELF_DXN]?: DXN.String;
-  [ATTR_TYPE]: DXN.String;
-  [ATTR_DELETED]?: boolean;
-  [ATTR_META]?: ObjectMetaJSON;
-  [ATTR_RELATION_SOURCE]?: DXN.String;
-  [ATTR_RELATION_TARGET]?: DXN.String;
-}
-
-export interface ObjectMetaJSON {
-  keys: ForeignKey[];
-  tags?: string[];
-}
-
-// NOTE: Keep as `function` to avoid type inference issues.
-// eslint-disable-next-line prefer-arrow-functions/prefer-arrow-functions
-export function assertObjectModelShape(obj: unknown): asserts obj is InternalObjectProps {
-  invariant(typeof obj === 'object' && obj !== null, 'Invalid object model: not an object');
-  assumeType<InternalObjectProps>(obj);
-  invariant(ObjectId.isValid(obj.id), 'Invalid object model: invalid id');
-  invariant(obj[TypeId] === undefined || obj[TypeId] instanceof DXN, 'Invalid object model: invalid type');
-  invariant(
-    obj[EntityKindId] === EntityKind.Object || obj[EntityKindId] === EntityKind.Relation,
-    'Invalid object model: invalid entity kind',
-  );
-  if (obj[EntityKindId] === EntityKind.Relation) {
-    invariant(obj[RelationSourceDXNId] instanceof DXN, 'Invalid object model: invalid relation source');
-    invariant(obj[RelationTargetDXNId] instanceof DXN, 'Invalid object model: invalid relation target');
-    invariant(!(obj[RelationSourceId] instanceof DXN), 'Invalid object model: source pointer is a DXN');
-    invariant(!(obj[RelationTargetId] instanceof DXN), 'Invalid object model: target pointer is a DXN');
-  }
-}

package/src/internal/object/relation.ts

@@ -1,24 +0,0 @@
-//
-// Copyright 2025 DXOS.org
-//
-
-import type { RelationSourceId, RelationTargetId } from './model';
-
-/**
- * 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;