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

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/meta.ts

@@ -1,62 +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;

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

@@ -1,81 +0,0 @@
-//
-// 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

@@ -1,85 +0,0 @@
-//
-// 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

@@ -1,61 +0,0 @@
-//
-// 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

@@ -1,22 +0,0 @@
-//
-// 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/index.ts

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