@dxos/echo 0.8.4-main.84f28bd → 0.8.4-main.937b3ca

package/src/internal/annotations/util.ts

@@ -0,0 +1,72 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import type * as Option from 'effect/Option';
+import type * as Schema from 'effect/Schema';
+import * as SchemaAST from 'effect/SchemaAST';
+
+import { assertArgument } from '@dxos/invariant';
+import { DXN } from '@dxos/keys';
+
+import { EntityKind } from '../types';
+
+export interface AnnotationHelper<T> {
+  get: (schema: Schema.Schema.Any) => Option.Option<T>;
+  getFromAst: (ast: SchemaAST.AST) => Option.Option<T>;
+  set: (value: T) => <S extends Schema.Schema.Any>(schema: S) => S;
+}
+
+export const createAnnotationHelper = <T>(id: symbol): AnnotationHelper<T> => {
+  return {
+    get: (schema) => SchemaAST.getAnnotation(schema.ast, id),
+    getFromAst: (ast) => SchemaAST.getAnnotation(ast, id),
+    set:
+      (value) =>
+      <S extends Schema.Schema.Any>(schema: S) =>
+        schema.annotations({ [id]: value }) as S,
+  };
+};
+
+/**
+ * If property is optional returns the nested property, otherwise returns the property.
+ */
+// TODO(wittjosiah): Is there a way to do this as a generic?
+export const unwrapOptional = (property: SchemaAST.PropertySignature) => {
+  if (!property.isOptional || !SchemaAST.isUnion(property.type)) {
+    return property;
+  }
+
+  return property.type.types[0];
+};
+
+/**
+ * @see JSONSchemaAnnotationId
+ * @returns JSON-schema annotation so that the schema can be serialized with correct parameters.
+ */
+// TODO(burdon): Required type.
+export const makeTypeJsonSchemaAnnotation = (options: {
+  identifier?: string;
+  kind: EntityKind;
+  typename: string;
+  version: string;
+  relationSource?: string;
+  relationTarget?: string;
+}) => {
+  assertArgument(!!options.relationSource === (options.kind === EntityKind.Relation), 'relationSource');
+  assertArgument(!!options.relationTarget === (options.kind === EntityKind.Relation), 'relationTarget');
+
+  const obj = {
+    // TODO(dmaretskyi): Should this include the version?
+    $id: options.identifier ?? DXN.fromTypename(options.typename).toString(),
+    entityKind: options.kind,
+    version: options.version,
+    typename: options.typename,
+  } as any;
+  if (options.kind === EntityKind.Relation) {
+    obj.relationSource = { $ref: options.relationSource };
+    obj.relationTarget = { $ref: options.relationTarget };
+  }
+
+  return obj;
+};

package/src/internal/api/annotations.ts

@@ -0,0 +1,60 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+/**
+ * Common annotation helpers shared by Obj and Relation modules.
+ */
+
+import {
+  getDescriptionWithSchema,
+  getLabelWithSchema,
+  setDescriptionWithSchema,
+  setLabelWithSchema,
+} from '../annotations';
+import { type Mutable } from '../proxy';
+import { type AnyProperties, getSchema as getSchema$ } from '../types';
+
+/**
+ * Get the label of an entity.
+ * Accepts both reactive entities and snapshots.
+ */
+export const getLabel = (entity: AnyProperties): string | undefined => {
+  const schema = getSchema$(entity);
+  if (schema != null) {
+    return getLabelWithSchema(schema, entity);
+  }
+};
+
+/**
+ * Set the label of an entity.
+ * Must be called within an Obj.change or Relation.change callback.
+ */
+export const setLabel = (entity: Mutable<AnyProperties>, label: string) => {
+  const schema = getSchema$(entity);
+  if (schema != null) {
+    setLabelWithSchema(schema, entity, label);
+  }
+};
+
+/**
+ * Get the description of an entity.
+ * Accepts both reactive entities and snapshots.
+ */
+export const getDescription = (entity: AnyProperties): string | undefined => {
+  const schema = getSchema$(entity);
+  if (schema != null) {
+    return getDescriptionWithSchema(schema, entity);
+  }
+};
+
+/**
+ * Set the description of an entity.
+ * Must be called within an Obj.change or Relation.change callback.
+ */
+export const setDescription = (entity: Mutable<AnyProperties>, description: string) => {
+  const schema = getSchema$(entity);
+  if (schema != null) {
+    setDescriptionWithSchema(schema, entity, description);
+  }
+};

package/src/internal/api/entity.ts

@@ -0,0 +1,29 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { invariant } from '@dxos/invariant';
+import { type DXN } from '@dxos/keys';
+import { assumeType } from '@dxos/util';
+
+import { type InternalObjectProps, ObjectDatabaseId, getObjectDXN } from '../entities';
+import type { AnyEntity } from '../types';
+
+/**
+ * Get the DXN of an entity.
+ * Accepts both reactive entities and snapshots.
+ */
+export const getDXN = (entity: AnyEntity): DXN => {
+  const dxn = getObjectDXN(entity);
+  invariant(dxn != null, 'Invalid entity.');
+  return dxn;
+};
+
+/**
+ * Get the database the entity belongs to.
+ * Accepts both reactive entities and snapshots.
+ */
+export const getDatabase = (entity: AnyEntity): any | undefined => {
+  assumeType<InternalObjectProps>(entity);
+  return entity[ObjectDatabaseId];
+};

package/src/internal/api/index.ts

@@ -0,0 +1,19 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+/**
+ * Shared API helpers for Obj and Relation modules.
+ * These implementations use generic Entity types.
+ * Obj and Relation modules re-export with strongly-typed signatures.
+ *
+ * TODO(wittjosiah): Could this become the new "internal" where we slowly refactor
+ * existing internal modules into here? This would provide a cleaner boundary
+ * and prevent external packages from using internals directly.
+ */
+
+export * from './annotations';
+export * from './entity';
+export * from './meta';
+export * from './sorting';
+export * from './version';

package/src/internal/api/meta.ts

@@ -0,0 +1,88 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import type { ForeignKey } from '@dxos/echo-protocol';
+import { assertArgument, invariant } from '@dxos/invariant';
+import type { DeepReadonly } from '@dxos/util';
+
+import { type Mutable } from '../proxy';
+import { type AnyProperties, type ObjectMeta, getMeta as getMeta$ } from '../types';
+
+/**
+ * Deeply read-only version of ObjectMeta.
+ */
+export type ReadonlyMeta = DeepReadonly<ObjectMeta>;
+
+/**
+ * Mutable meta type received in meta mutation callbacks.
+ */
+export type Meta = ObjectMeta;
+
+/**
+ * Get the metadata for an entity with validation.
+ * Returns mutable meta when passed a mutable entity (inside change callback).
+ * Returns read-only meta when passed a regular entity or snapshot.
+ *
+ * TODO(burdon): When passed a Snapshot, should return a snapshot of meta, not the live meta proxy.
+ */
+export function getMetaChecked(entity: Mutable<AnyProperties>): ObjectMeta;
+export function getMetaChecked(entity: AnyProperties): ReadonlyMeta;
+export function getMetaChecked(entity: AnyProperties): ObjectMeta | ReadonlyMeta {
+  assertArgument(entity, 'entity', 'Should be an entity.');
+  const meta = getMeta$(entity);
+  invariant(meta != null, 'Invalid entity.');
+  return meta;
+}
+
+/**
+ * @returns Foreign keys for the entity from the specified source.
+ * Accepts both reactive entities and snapshots.
+ */
+export const getKeys = (entity: AnyProperties, source: string): ForeignKey[] => {
+  assertArgument(entity, 'entity', 'Should be an entity.');
+  const meta = getMetaChecked(entity);
+  invariant(meta != null, 'Invalid entity.');
+  return meta.keys.filter((key) => key.source === source);
+};
+
+/**
+ * Delete all keys from the entity for the specified source.
+ * Must be called within an Obj.change or Relation.change callback.
+ */
+export const deleteKeys = (entity: Mutable<AnyProperties>, source: string) => {
+  const meta = getMetaChecked(entity);
+  for (let i = 0; i < meta.keys.length; i++) {
+    if (meta.keys[i].source === source) {
+      meta.keys.splice(i, 1);
+      i--;
+    }
+  }
+};
+
+/**
+ * Add a tag to the entity.
+ * Must be called within an Obj.change or Relation.change callback.
+ */
+export const addTag = (entity: Mutable<AnyProperties>, tag: string) => {
+  const meta = getMetaChecked(entity);
+  meta.tags ??= [];
+  meta.tags.push(tag);
+};
+
+/**
+ * Remove a tag from the entity.
+ * Must be called within an Obj.change or Relation.change callback.
+ */
+export const removeTag = (entity: Mutable<AnyProperties>, tag: string) => {
+  const meta = getMetaChecked(entity);
+  if (!meta.tags) {
+    return;
+  }
+  for (let i = 0; i < meta.tags.length; i++) {
+    if (meta.tags[i] === tag) {
+      meta.tags.splice(i, 1);
+      i--;
+    }
+  }
+};

package/src/internal/api/sorting.ts

@@ -0,0 +1,53 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { getTypename } from '../annotations';
+import type { AnyEntity } from '../types';
+
+import { getLabel } from './annotations';
+
+/**
+ * String comparison helper for sorting.
+ */
+export const compare = (a?: string, b?: string): number => {
+  if (a == null) {
+    return b == null ? 0 : 1;
+  }
+  if (b == null) {
+    return -1;
+  }
+  return a.localeCompare(b);
+};
+
+/**
+ * Comparator function type for sorting entities.
+ * Accepts both reactive entities and snapshots.
+ */
+export type Comparator<T extends AnyEntity = AnyEntity> = (a: T, b: T) => number;
+
+/**
+ * Sort entities by label.
+ */
+export const sortByLabel: Comparator = (a: AnyEntity, b: AnyEntity) => compare(getLabel(a), getLabel(b));
+
+/**
+ * Sort entities by typename.
+ */
+export const sortByTypename: Comparator = (a: AnyEntity, b: AnyEntity) => compare(getTypename(a), getTypename(b));
+
+/**
+ * Compose multiple comparators into one.
+ * Applies comparators in order until one returns non-zero.
+ */
+export const sort = <T extends AnyEntity>(...comparators: Comparator<T>[]): Comparator<T> => {
+  return (a: T, b: T) => {
+    for (const comparator of comparators) {
+      const result = comparator(a, b);
+      if (result !== 0) {
+        return result;
+      }
+    }
+    return 0;
+  };
+};

package/src/internal/api/version.ts

@@ -0,0 +1,96 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { assertArgument } from '@dxos/invariant';
+
+import { ObjectVersionId } from '../entities';
+import { type AnyEntity, VersionTypeId } from '../types';
+
+/**
+ * Represent entity version.
+ * May be backed by Automerge.
+ * Entities with no history are not versioned.
+ * Named EntityVersion to avoid conflict with types/version.ts.
+ */
+export interface EntityVersion {
+  [VersionTypeId]: {};
+
+  /**
+   * Whether the entity is versioned.
+   */
+  versioned: boolean;
+
+  /**
+   * Automerge heads.
+   */
+  automergeHeads?: string[];
+}
+
+const unversioned: EntityVersion = {
+  [VersionTypeId]: {},
+  versioned: false,
+};
+
+/**
+ * Checks that `obj` is a version object.
+ */
+export const isVersion = (entity: unknown): entity is EntityVersion => {
+  return entity != null && typeof entity === 'object' && VersionTypeId in entity;
+};
+
+/**
+ * Returns the version of an entity.
+ * Accepts both reactive entities and snapshots.
+ */
+export const version = (entity: AnyEntity): EntityVersion => {
+  const ver = (entity as any)[ObjectVersionId];
+  if (ver === undefined) {
+    return unversioned;
+  }
+  return ver;
+};
+
+/**
+ * Checks that `version` is a valid version object.
+ */
+export const versionValid = (ver: EntityVersion): boolean => {
+  assertArgument(isVersion(ver), 'version', 'Invalid version object');
+  return !!ver.versioned;
+};
+
+export type VersionCompareResult = 'unversioned' | 'equal' | 'different';
+
+/**
+ * Compares two versions.
+ * @param version1
+ * @param version2
+ * @returns 'unversioned' if either entity is unversioned, 'equal' if the versions are equal, 'different' if the versions are different.
+ */
+export const compareVersions = (version1: EntityVersion, version2: EntityVersion): VersionCompareResult => {
+  assertArgument(isVersion(version1), 'version1', 'Invalid version object');
+  assertArgument(isVersion(version2), 'version2', 'Invalid version object');
+
+  if (!versionValid(version1) || !versionValid(version2)) {
+    return 'unversioned';
+  }
+
+  if (version1.automergeHeads?.length !== version2.automergeHeads?.length) {
+    return 'different';
+  }
+  if (version1.automergeHeads?.some((head) => !version2.automergeHeads?.includes(head))) {
+    return 'different';
+  }
+
+  return 'equal';
+};
+
+export const encodeVersion = (ver: EntityVersion): string => {
+  return JSON.stringify(ver);
+};
+
+export const decodeVersion = (ver: string): EntityVersion => {
+  const parsed = JSON.parse(ver);
+  parsed[VersionTypeId] = {};
+  return parsed;
+};

package/src/internal/entities/entity.ts

@@ -0,0 +1,126 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+import type * as SchemaAST from 'effect/SchemaAST';
+import type * as Types from 'effect/Types';
+
+import { type ToMutable } from '@dxos/util';
+
+import { type TypeMeta } from '../annotations';
+import { type AnyEntity, type EntityKind, SchemaKindId } from '../types';
+
+// 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];
+export type EchoTypeSchemaProps<T, ExtraFields = {}> = Types.Simplify<AnyEntity & ToMutable<T> & ExtraFields>;
+
+// TODO(burdon): Rename EchoEntitySchema.
+export interface EchoTypeSchema<
+  Self extends Schema.Schema.Any,
+  ExtraFields = {},
+  K extends EntityKind = EntityKind,
+  Fields extends Schema.Struct.Fields = Schema.Struct.Fields,
+> extends TypeMeta,
+    Schema.AnnotableClass<
+      EchoTypeSchema<Self, ExtraFields, K, Fields>,
+      EchoTypeSchemaProps<Schema.Schema.Type<Self>, ExtraFields>,
+      EchoTypeSchemaProps<Schema.Schema.Encoded<Self>, ExtraFields>,
+      Schema.Schema.Context<Self>
+    > {
+  /**
+   * Schema kind key that marks this as an ECHO schema and indicates its kind.
+   * Makes EchoTypeSchema satisfy the Type.Obj.Any or Type.Relation.Any type.
+   */
+  readonly [SchemaKindId]: K;
+
+  /**
+   * The fields defined in the original struct schema.
+   * Allows accessing field definitions for introspection.
+   */
+  readonly fields: Fields;
+
+  instanceOf(value: unknown): boolean;
+}
+
+// type MakeProps =
+//   | 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: MakeProps | undefined): boolean =>
+//   Predicate.isBoolean(options) ? options : options?.disableValidation ?? false;
+
+/**
+ * @internal
+ */
+export const makeEchoTypeSchema = <
+  Self extends Schema.Schema.Any,
+  K extends EntityKind = EntityKind,
+  // TODO(wittjosiah): Can this be inferred from the schema?
+  Fields extends Schema.Struct.Fields = Schema.Struct.Fields,
+>(
+  fields: Fields,
+  ast: SchemaAST.AST,
+  typename: string,
+  version: string,
+  kind: K,
+): EchoTypeSchema<Self, {}, K, Fields> => {
+  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 readonly [SchemaKindId] = kind;
+    static readonly fields = fields;
+
+    static override annotations(
+      annotations: Schema.Annotations.GenericSchema<EchoTypeSchemaProps<Schema.Schema.Type<Self>>>,
+    ): EchoTypeSchema<Self, {}, K, Fields> {
+      const schema = Schema.make<EchoTypeSchemaProps<Schema.Schema.Type<Self>>>(ast).annotations(annotations);
+      return makeEchoTypeSchema<Self, K, Fields>(fields, schema.ast, typename, version, kind);
+    }
+
+    // static make(
+    //   props: RequiredKeys<Schema.TypeLiteral.Constructor<Fields, []>> extends never
+    //     ? void | Simplify<Schema.TypeLiteral.Constructor<Fields, []>>
+    //     : Simplify<Schema.TypeLiteral.Constructor<Fields, []>>,
+    //   options?: MakeProps,
+    // ): 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/entities/index.ts

@@ -0,0 +1,9 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+export * from './entity';
+export * from './model'; // TODO(burdon): Rename.
+export * from './object';
+export * from './relation';
+export * from './util';

package/src/internal/entities/model.ts

@@ -0,0 +1,134 @@
+//
+// 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 type * as Database from '../../Database';
+import {
+  type ATTR_META,
+  type ATTR_TYPE,
+  EntityKind,
+  KindId,
+  type MetaId,
+  type ObjectMeta,
+  type SchemaId,
+  TypeId,
+  type Version,
+} from '../types';
+
+import {
+  type ATTR_RELATION_SOURCE,
+  type ATTR_RELATION_TARGET,
+  RelationSourceDXNId,
+  RelationSourceId,
+  RelationTargetDXNId,
+  RelationTargetId,
+} from './relation';
+
+//
+// Defines the internal model of the echo object.
+//
+
+/**
+ * Property name for self DXN when object is serialized to JSON.
+ */
+export const ATTR_SELF_DXN = '@dxn';
+
+/**
+ * DXN to the object itself.
+ */
+export const SelfDXNId = Symbol.for('@dxos/echo/DXN');
+
+/**
+ * Property name for deleted when object is serialized to JSON.
+ */
+export const ATTR_DELETED = '@deleted';
+
+/**
+ * Deletion marker.
+ */
+export const ObjectDeletedId = Symbol.for('@dxos/echo/Deleted');
+
+/**
+ * Object version accessor symbol.
+ */
+export const ObjectVersionId: unique symbol = Symbol.for('@dxos/echo/Version');
+
+/**
+ * Object database accessor symbol.
+ */
+export const ObjectDatabaseId = Symbol.for('@dxos/echo/Database');
+
+/**
+ * Internal runtime representation of an object.
+ * The fields are accessed through getter functions.
+ */
+// NOTE: Each symbol has a jsdoc describing its purpose.
+export interface InternalObjectProps {
+  readonly id: ObjectId;
+  readonly [SelfDXNId]: DXN;
+  readonly [KindId]: EntityKind;
+  readonly [SchemaId]: Schema.Schema.AnyNoContext;
+  readonly [TypeId]: DXN;
+  readonly [MetaId]?: ObjectMeta;
+  readonly [ObjectDatabaseId]?: Database.Database;
+  readonly [ObjectDeletedId]?: boolean;
+  readonly [ObjectVersionId]?: Version;
+  readonly [RelationSourceDXNId]?: DXN;
+  readonly [RelationTargetDXNId]?: DXN;
+  readonly [RelationSourceId]?: InternalObjectProps;
+  readonly [RelationTargetId]?: InternalObjectProps;
+}
+
+/**
+ * Entity metadata.
+ */
+export interface ObjectMetaJSON {
+  keys: ForeignKey[];
+  tags?: string[];
+}
+
+/**
+ * JSON representation of an object or relation metadata.
+ */
+export interface ObjectJSON {
+  id: string;
+  [ATTR_TYPE]: DXN.String;
+  [ATTR_SELF_DXN]?: DXN.String;
+  [ATTR_DELETED]?: boolean;
+  [ATTR_META]?: ObjectMetaJSON;
+  [ATTR_RELATION_SOURCE]?: DXN.String;
+  [ATTR_RELATION_TARGET]?: DXN.String;
+
+  /**
+   * Application-specific properties.
+   */
+  [key: string]: unknown;
+}
+
+/**
+ * NOTE: Keep as `function` to avoid type inference issues.
+ */
+export function assertObjectModel(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[KindId] === EntityKind.Object || obj[KindId] === EntityKind.Relation,
+    'Invalid object model: invalid entity kind',
+  );
+
+  if (obj[KindId] === 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');
+  }
+}