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

package/src/internal/ast/entity-kind.ts

@@ -1,15 +0,0 @@
-//
-// Copyright 2025 DXOS.org
-//
-
-import * as Schema from 'effect/Schema';
-
-/**
- * Kinds of entities stored in ECHO: objects and relations.
- */
-export enum EntityKind {
-  Object = 'object',
-  Relation = 'relation',
-}
-
-export const EntityKindSchema = Schema.Enums(EntityKind);

package/src/internal/ast/index.ts

@@ -1,8 +0,0 @@
-//
-// Copyright 2024 DXOS.org
-//
-
-export * from './annotations';
-export * from './annotation-helper';
-export * from './types';
-export * from './entity-kind';

package/src/internal/ast/types.ts

@@ -1,17 +0,0 @@
-//
-// Copyright 2024 DXOS.org
-//
-
-import { PropertyMeta } from './annotations';
-
-/**
- * @internal
- */
-export const FIELD_PATH_ANNOTATION = 'path';
-
-/**
- * Sets the path for the field.
- * @param path Data source path in the json path format. This is the field path in the source object.
- */
-// TODO(burdon): Field, vs. path vs. property.
-export const FieldPath = (path: string) => PropertyMeta(FIELD_PATH_ANNOTATION, path);

package/src/internal/json/index.ts

@@ -1,5 +0,0 @@
-//
-// Copyright 2024 DXOS.org
-//
-
-export * from './json-schema';

package/src/internal/object/accessors.ts

@@ -1,115 +0,0 @@
-//
-// 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 { 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;
-};

package/src/internal/object/deleted.ts

@@ -1,19 +0,0 @@
-//
-// Copyright 2025 DXOS.org
-//
-
-import type { BaseObject } from '../types';
-
-import { DeletedId } from './model';
-
-/**
- * @returns `true` if the object has been marked as deleted.
- */
-export const isDeleted = (obj: BaseObject): boolean => {
-  if ((obj as any)[DeletedId] === undefined) {
-    // TODO(dmaretskyi): Return to prior behavior of throwing.
-    // throw new Error('Object does not support deletion marker');
-    return false;
-  }
-  return (obj as any)[DeletedId] ?? false;
-};

package/src/internal/object/entity.ts

@@ -1,204 +0,0 @@
-//
-// Copyright 2024 DXOS.org
-//
-
-import * as Schema from 'effect/Schema';
-import * as SchemaAST from 'effect/SchemaAST';
-import type * as Types from 'effect/Types';
-
-import { raise } from '@dxos/debug';
-import { invariant } from '@dxos/invariant';
-import { DXN } from '@dxos/keys';
-
-import {
-  EntityKind,
-  type TypeAnnotation,
-  TypeAnnotationId,
-  type TypeMeta,
-  getEntityKind,
-  getSchemaTypename,
-  getTypeIdentifierAnnotation,
-} from '../ast';
-import { type HasId, type ToMutable } from '../types';
-
-import { type RelationSourceTargetRefs } from './relation';
-
-// TODO(burdon): Define Schema type for `typename` and use consistently for all DXN-like properties.
-
-// type RequiredKeys<T> = { [K in keyof T]-?: {} extends Pick<T, K> ? never : K }[keyof T];
-type EchoTypeSchemaProps<T, ExtraFields = {}> = Types.Simplify<HasId & ToMutable<T> & ExtraFields>;
-
-export interface EchoTypeSchema<Self extends Schema.Schema.Any, ExtraFields = {}>
-  extends TypeMeta,
-    Schema.AnnotableClass<
-      EchoTypeSchema<Self, ExtraFields>,
-      EchoTypeSchemaProps<Schema.Schema.Type<Self>, ExtraFields>,
-      EchoTypeSchemaProps<Schema.Schema.Encoded<Self>, ExtraFields>,
-      Schema.Schema.Context<Self>
-    > {
-  // make(
-  //   props: RequiredKeys<Schema.TypeLiteral.Constructor<Fields, []>> extends never
-  //     ? void | Simplify<Schema.TypeLiteral.Constructor<Fields, []>>
-  //     : Simplify<Schema.TypeLiteral.Constructor<Fields, []>>,
-  //   options?: MakeOptions,
-  // ): Simplify<Schema.TypeLiteral.Type<Fields, []>>;
-
-  instanceOf(value: unknown): boolean;
-}
-
-/**
- * Pipeable function to add ECHO object annotations to a schema.
- */
-// TODO(dmaretskyi): Rename EchoObjectSchema.
-export const EchoObject: {
-  // TODO(burdon): Tighten Self type to Schema.TypeLiteral or Schema.Struct to facilitate definition of `make` method.
-  // (meta: TypeMeta): <Self extends Schema.Struct<Fields>, Fields extends Schema.Struct.Fields>(self: Self) => EchoObjectSchema<Self, Fields>;
-  (meta: TypeMeta): <Self extends Schema.Schema.Any>(self: Self) => EchoTypeSchema<Self>;
-} = ({ typename, version }) => {
-  return <Self extends Schema.Schema.Any>(self: Self): EchoTypeSchema<Self> => {
-    invariant(typeof TypeAnnotationId === 'symbol', 'Sanity.');
-    invariant(SchemaAST.isTypeLiteral(self.ast), 'Schema must be a TypeLiteral.');
-
-    // TODO(dmaretskyi): Does `Schema.mutable` work for deep mutability here?
-    // TODO(dmaretskyi): Do not do mutable here.
-    const schemaWithId = Schema.extend(Schema.mutable(self), Schema.Struct({ id: Schema.String }));
-    const ast = SchemaAST.annotations(schemaWithId.ast, {
-      // TODO(dmaretskyi): `extend` kills the annotations.
-      ...self.ast.annotations,
-      [TypeAnnotationId]: { kind: EntityKind.Object, typename, version } satisfies TypeAnnotation,
-      // TODO(dmaretskyi): TypeIdentifierAnnotationId?
-    });
-
-    return makeEchoObjectSchema<Self>(/* self.fields, */ ast, typename, version);
-  };
-};
-
-export type EchoRelationOptions<
-  TSource extends Schema.Schema.AnyNoContext,
-  TTarget extends Schema.Schema.AnyNoContext,
-> = TypeMeta & {
-  source: TSource;
-  target: TTarget;
-};
-
-// TODO(dmaretskyi): Rename EchoRelationSchema.
-export const EchoRelation = <Source extends Schema.Schema.AnyNoContext, Target extends Schema.Schema.AnyNoContext>(
-  options: EchoRelationOptions<Source, Target>,
-) => {
-  const sourceDXN = getDXNForRelationSchemaRef(options.source);
-  const targetDXN = getDXNForRelationSchemaRef(options.target);
-  if (getEntityKind(options.source) !== EntityKind.Object) {
-    raise(new Error('Source schema must be an echo object schema.'));
-  }
-  if (getEntityKind(options.target) !== EntityKind.Object) {
-    raise(new Error('Target schema must be an echo object schema.'));
-  }
-
-  return <Self extends Schema.Schema.Any>(
-    self: Self,
-  ): EchoTypeSchema<Self, RelationSourceTargetRefs<Schema.Schema.Type<Source>, Schema.Schema.Type<Target>>> => {
-    invariant(SchemaAST.isTypeLiteral(self.ast), 'Schema must be a TypeLiteral.');
-
-    // TODO(dmaretskyi): Does `Schema.mutable` work for deep mutability here?
-    // TODO(dmaretskyi): Do not do mutable here.
-    const schemaWithId = Schema.extend(Schema.mutable(self), Schema.Struct({ id: Schema.String }));
-    const ast = SchemaAST.annotations(schemaWithId.ast, {
-      // TODO(dmaretskyi): `extend` kills the annotations.
-      ...self.ast.annotations,
-      [TypeAnnotationId]: {
-        kind: EntityKind.Relation,
-        typename: options.typename,
-        version: options.version,
-        sourceSchema: sourceDXN,
-        targetSchema: targetDXN,
-      } satisfies TypeAnnotation,
-      // TODO(dmaretskyi): TypeIdentifierAnnotationId?
-    });
-
-    return makeEchoObjectSchema<Self>(/* self.fields, */ ast, options.typename, options.version);
-  };
-};
-
-const getDXNForRelationSchemaRef = (schema: Schema.Schema.Any): string => {
-  const identifier = getTypeIdentifierAnnotation(schema);
-  if (identifier) {
-    return identifier;
-  }
-
-  const typename = getSchemaTypename(schema);
-  if (!typename) {
-    throw new Error('Schema must have a typename');
-  }
-
-  return DXN.fromTypename(typename).toString();
-};
-
-// type MakeOptions =
-//   | boolean
-//   | {
-//       readonly disableValidation?: boolean;
-//     };
-
-// NOTE: Utils copied from Effect `Schema.ts`.
-// const _ownKeys = (o: object): Array<PropertyKey> =>
-//   (Object.keys(o) as Array<PropertyKey>).concat(Object.getOwnPropertySymbols(o));
-
-// const _lazilyMergeDefaults = (
-//   fields: Schema.Struct.Fields,
-//   out: Record<PropertyKey, unknown>,
-// ): { [x: string | symbol]: unknown } => {
-//   const ownKeys = _ownKeys(fields);
-//   for (const key of ownKeys) {
-//     const field = fields[key];
-//     if (out[key] === undefined && Schema.isPropertySignature(field)) {
-//       const ast = field.ast;
-//       const defaultValue = ast._tag === 'PropertySignatureDeclaration' ? ast.defaultValue : ast.to.defaultValue;
-//       if (defaultValue !== undefined) {
-//         out[key] = defaultValue();
-//       }
-//     }
-//   }
-//   return out;
-// };
-
-// const _getDisableValidationMakeOption = (options: MakeOptions | undefined): boolean =>
-//   Predicate.isBoolean(options) ? options : options?.disableValidation ?? false;
-
-const makeEchoObjectSchema = <Self extends Schema.Schema.Any>(
-  // fields: Fields,
-  ast: SchemaAST.AST,
-  typename: string,
-  version: string,
-): EchoTypeSchema<Self> => {
-  return class EchoObjectSchemaClass extends Schema.make<
-    EchoTypeSchemaProps<Schema.Schema.Type<Self>>,
-    EchoTypeSchemaProps<Schema.Schema.Encoded<Self>>,
-    Schema.Schema.Context<Self>
-  >(ast) {
-    static readonly typename = typename;
-    static readonly version = version;
-
-    static override annotations(
-      annotations: Schema.Annotations.GenericSchema<EchoTypeSchemaProps<Schema.Schema.Type<Self>>>,
-    ): EchoTypeSchema<Self> {
-      const schema = Schema.make<EchoTypeSchemaProps<Schema.Schema.Type<Self>>>(ast).annotations(annotations);
-      return makeEchoObjectSchema<Self>(/* fields, */ schema.ast, typename, version);
-    }
-
-    // static make(
-    //   props: RequiredKeys<Schema.TypeLiteral.Constructor<Fields, []>> extends never
-    //     ? void | Simplify<Schema.TypeLiteral.Constructor<Fields, []>>
-    //     : Simplify<Schema.TypeLiteral.Constructor<Fields, []>>,
-    //   options?: MakeOptions,
-    // ): Simplify<Schema.TypeLiteral.Type<Fields, []>> {
-    //   const propsWithDefaults: any = _lazilyMergeDefaults(fields, { ...(props as any) });
-    //   return _getDisableValidationMakeOption(options)
-    //     ? propsWithDefaults
-    //     : ParseResult.validateSync(this)(propsWithDefaults);
-    // }
-
-    static instanceOf(value: unknown): boolean {
-      return Schema.is(this)(value);
-    }
-  };
-};

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,20 +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 './typed-relation';
-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/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;