@dxos/echo 0.8.4-main.a4bbb77 → 0.8.4-main.abd8ff62ef

package/src/Entity.test.ts

@@ -0,0 +1,22 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, expect, test } from 'vitest';
+
+import type * as Entity from './Entity';
+import * as Obj from './Obj';
+import * as Relation from './Relation';
+import { TestSchema } from './testing';
+
+describe('Entity', () => {
+  test('Entity.Unknown accepts any object or relation', () => {
+    const obj = Obj.make(TestSchema.Person, { name: 'Test' });
+    const rel = Relation.make(TestSchema.HasManager, { [Relation.Source]: obj, [Relation.Target]: obj });
+    const doSomething = (entity: Entity.Unknown) => {
+      return entity;
+    };
+    expect(doSomething(obj)).toBe(obj);
+    expect(doSomething(rel)).toBe(rel);
+  });
+});

package/src/Entity.ts

@@ -0,0 +1,243 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+// @import-as-namespace
+
+import type { ForeignKey } from '@dxos/echo-protocol';
+import type { DXN, ObjectId } from '@dxos/keys';
+
+import * as internal from './internal';
+import type * as Relation from './Relation';
+import type * as Type from './Type';
+
+// Re-export KindId and SnapshotKindId from internal.
+export const KindId = internal.KindId;
+export type KindId = typeof internal.KindId;
+export const SnapshotKindId = internal.SnapshotKindId;
+export type SnapshotKindId = typeof internal.SnapshotKindId;
+
+// NOTE: Relation does not extend Obj so that, for example, we can prevent Relations from being used as source and target objects.
+//  However, we generally refer to Obj and Relation instances as "objects",
+//  and many API methods accept both Obj.Unknown and Relation.Unknown (i.e., Entity.Unknown) instances.
+
+export const Kind = internal.EntityKind;
+export type Kind = internal.EntityKind;
+export const KindSchema = internal.EntityKindSchema;
+
+/**
+ * Assigns a kind to an Object or Relation instance.
+ * NOTE: Needed to make `isRelation` and `isObject` checks work.
+ */
+export interface OfKind<K extends Kind> {
+  readonly [KindId]: K;
+  readonly id: ObjectId;
+}
+
+/**
+ * Assigns a snapshot kind to an Object or Relation snapshot.
+ */
+export interface SnapshotOfKind<K extends Kind> {
+  readonly [SnapshotKindId]: K;
+  readonly id: ObjectId;
+}
+
+/**
+ * Obj or Relation with a specific set of properties.
+ */
+export type Entity<Props> = OfKind<Kind> & Props;
+
+/**
+ * Unknown Obj or Relation (reactive).
+ */
+export interface Unknown extends OfKind<Kind> {}
+
+/**
+ * Snapshot of an Obj or Relation.
+ * Branded with SnapshotKindId instead of KindId.
+ */
+export interface Snapshot extends SnapshotOfKind<Kind> {}
+
+/**
+ * Object with arbitrary properties.
+ *
+ * NOTE: Due to how typescript works, this type is not assignable to a specific schema type.
+ * In that case, use `Obj.instanceOf` to check if an object is of a specific type.
+ *
+ * This type is very permissive and allows accessing any property on the object.
+ * We should move to Obj.Unknown that is not permissive and requires explicit instanceof checks..
+ */
+export interface Any extends OfKind<Kind> {
+  [key: string]: unknown;
+}
+
+/**
+ * Returns all properties of an object or relation except for the id and kind.
+ */
+export type Properties<T> = Omit<T, 'id' | KindId | Relation.Source | Relation.Target>;
+
+/**
+ * Check if a value is an ECHO entity (object or relation).
+ * Returns `false` for snapshots.
+ */
+export const isEntity = (value: unknown): value is Unknown => {
+  if (typeof value !== 'object' || value === null) {
+    return false;
+  }
+  return (value as any)[KindId] !== undefined;
+};
+
+/**
+ * Check if a value is an ECHO entity snapshot.
+ * Returns `false` for entities.
+ */
+export const isSnapshot = (value: unknown): value is Snapshot => {
+  if (typeof value !== 'object' || value === null) {
+    return false;
+  }
+  return (value as any)[SnapshotKindId] !== undefined;
+};
+
+// TODO(dmaretskyi): Type introspection -- move to kind.
+export const getKind = internal.getEntityKind;
+
+/**
+ * Property that accesses metadata for an entity.
+ */
+export const Meta: unique symbol = internal.MetaId as any;
+
+/**
+ * Property that accesses metadata for an entity.
+ */
+export type Meta = typeof Meta;
+
+//
+// Entity-level functions that work on any entity (object or relation).
+// Use these when you don't know or care about the specific entity kind.
+// For kind-specific functions, use Obj.* or Relation.*.
+//
+
+/**
+ * JSON representation of an entity.
+ */
+export type JSON = internal.ObjectJSON;
+
+/**
+ * Get the DXN of an entity (object or relation).
+ */
+export const getDXN = (entity: Unknown | Snapshot): DXN => internal.getDXN(entity);
+
+/**
+ * Get the DXN of an entity's type.
+ */
+export const getTypeDXN = internal.getTypeDXN;
+
+/**
+ * Get the schema of an entity.
+ * Returns the branded ECHO schema used to create the entity.
+ */
+export const getSchema: (entity: Unknown | Snapshot) => Type.AnyEntity | undefined = internal.getSchema as any;
+
+/**
+ * Get the typename of an entity's type.
+ */
+export const getTypename = (entity: Unknown | Snapshot): string | undefined => internal.getTypename(entity);
+
+/**
+ * Get the database an entity belongs to.
+ */
+export const getDatabase = (entity: Unknown | Snapshot): any | undefined => internal.getDatabase(entity);
+
+/**
+ * Get the metadata for an entity.
+ * Returns mutable meta when passed a mutable entity (inside change callback).
+ * Returns read-only meta when passed a regular entity or snapshot.
+ */
+// TODO(wittjosiah): When passed a Snapshot, should return a snapshot of meta, not the live meta proxy.
+export function getMeta(entity: Mutable<Unknown>): internal.ObjectMeta;
+export function getMeta(entity: Unknown | Snapshot): internal.ReadonlyMeta;
+export function getMeta(entity: Unknown | Snapshot | Mutable<Unknown>): internal.ObjectMeta | internal.ReadonlyMeta {
+  return internal.getMetaChecked(entity);
+}
+
+/**
+ * Get foreign keys for an entity from the specified source.
+ */
+export const getKeys = (entity: Unknown | Snapshot, source: string): ForeignKey[] => internal.getKeys(entity, source);
+
+/**
+ * Check if an entity is deleted.
+ */
+export const isDeleted = (entity: Unknown | Snapshot): boolean => internal.isDeleted(entity);
+
+/**
+ * Get the label of an entity.
+ */
+export const getLabel = (entity: Unknown | Snapshot): string | undefined => internal.getLabel(entity);
+
+/**
+ * Get the description of an entity.
+ */
+export const getDescription = (entity: Unknown | Snapshot): string | undefined => internal.getDescription(entity);
+
+/**
+ * Convert an entity to its JSON representation.
+ */
+export const toJSON = (entity: Unknown | Snapshot): JSON => internal.objectToJSON(entity);
+
+/**
+ * Subscribe to changes on an entity (object or relation).
+ * @returns Unsubscribe function.
+ */
+export const subscribe = (entity: Unknown, callback: () => void): (() => void) => {
+  return internal.subscribe(entity, callback);
+};
+
+//
+// Change
+//
+
+/**
+ * Used to provide a mutable view of an entity within `Entity.update`.
+ */
+export type Mutable<T> = internal.Mutable<T>;
+
+/**
+ * Perform mutations on an entity (object or relation) within a change context.
+ *
+ * Entities are read-only by default. Mutations are batched and notifications fire
+ * when the callback completes. Direct mutations outside of `Entity.update` will throw
+ * at runtime.
+ *
+ * @param entity - The echo entity (object or relation) to mutate.
+ * @param callback - Receives a mutable view of the entity. All mutations must occur here.
+ *
+ * @example
+ * ```typescript
+ * // Mutate within Entity.update
+ * Entity.update(entity, (obj) => {
+ *   obj.name = 'Updated';
+ *   obj.count = 42;
+ * });
+ *
+ * // Direct mutation throws
+ * entity.name = 'Bob'; // Error: Cannot modify outside Entity.update()
+ * ```
+ *
+ * Note: For type-specific operations, prefer `Obj.update` or `Relation.update`.
+ */
+export const update = <T extends Unknown>(entity: T, callback: internal.ChangeCallback<T>): void => {
+  internal.change(entity, callback);
+};
+
+/**
+ * Add a tag to an entity.
+ * Must be called within an `Entity.update`, `Obj.update`, or `Relation.update` callback.
+ */
+export const addTag = (entity: Mutable<Unknown>, tag: string): void => internal.addTag(entity, tag);
+
+/**
+ * Remove a tag from an entity.
+ * Must be called within an `Entity.update`, `Obj.update`, or `Relation.update` callback.
+ */
+export const removeTag = (entity: Mutable<Unknown>, tag: string): void => internal.removeTag(entity, tag);

package/src/Err.ts

@@ -0,0 +1,40 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+// @import-as-namespace
+
+import { BaseError, type BaseErrorOptions } from '@dxos/errors';
+import { type DXN } from '@dxos/keys';
+
+export class SchemaNotFoundError extends BaseError.extend('SchemaNotFoundError', 'Schema not found') {
+  constructor(schema: string, options?: BaseErrorOptions) {
+    super({ context: { schema }, ...options });
+  }
+}
+
+export class ObjectNotFoundError extends BaseError.extend('ObjectNotFoundError', 'Object not found') {
+  constructor(dxn: DXN, options?: BaseErrorOptions) {
+    super({ context: { dxn }, ...options });
+  }
+}
+
+/**
+ * Reason why getting a reactive object from a snapshot failed.
+ * - `no-database`: The snapshot is not associated with a database.
+ * - `object-not-found`: The object was removed or does not exist in the database.
+ */
+export type GetReactiveErrorReason = 'no-database' | 'object-not-found';
+
+/**
+ * Error thrown when a reactive object cannot be resolved from a snapshot.
+ * Extends `BaseError` with a `reason` and optional `snapshotId` in its context.
+ */
+export class GetReactiveError extends BaseError.extend(
+  'GetReactiveError',
+  'Failed to get reactive object from snapshot',
+) {
+  constructor(options: { reason: GetReactiveErrorReason; snapshotId?: string } & BaseErrorOptions) {
+    super({ context: { reason: options.reason, snapshotId: options.snapshotId }, ...options });
+  }
+}

package/src/Extension.test.ts

@@ -0,0 +1,235 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Option from 'effect/Option';
+import * as Schema from 'effect/Schema';
+import { describe, test } from 'vitest';
+
+import * as Extension from './Extension';
+
+describe('Extension', () => {
+  describe('make', () => {
+    test('creates an extension with a string schema', ({ expect }) => {
+      const ColorExtension = Extension.make('color', Schema.String);
+
+      expect(ColorExtension.key).toBe('color');
+      expect(ColorExtension.valueSchema).toBe(Schema.String);
+      expect(ColorExtension[Extension.TypeId]).toBeDefined();
+    });
+
+    test('creates an extension with a number schema', ({ expect }) => {
+      const PriorityExtension = Extension.make('priority', Schema.Number);
+
+      expect(PriorityExtension.key).toBe('priority');
+      expect(PriorityExtension.valueSchema).toBe(Schema.Number);
+    });
+
+    test('creates an extension with a complex schema', ({ expect }) => {
+      const MetadataSchema = Schema.Struct({
+        author: Schema.String,
+        version: Schema.Number,
+        tags: Schema.Array(Schema.String),
+      });
+      const MetadataExtension = Extension.make('metadata', MetadataSchema);
+
+      expect(MetadataExtension.key).toBe('metadata');
+      expect(MetadataExtension.valueSchema).toBe(MetadataSchema);
+    });
+  });
+
+  describe('get and set', () => {
+    test('set and get a string value', ({ expect }) => {
+      const ColorExtension = Extension.make('color', Schema.String);
+      const values: Extension.Values = {};
+
+      Extension.set(values, ColorExtension, 'red');
+      const result = Extension.get(values, ColorExtension);
+
+      expect(Option.isSome(result)).toBe(true);
+      expect(Option.getOrThrow(result)).toBe('red');
+    });
+
+    test('set and get a number value', ({ expect }) => {
+      const PriorityExtension = Extension.make('priority', Schema.Number);
+      const values: Extension.Values = {};
+
+      Extension.set(values, PriorityExtension, 42);
+      const result = Extension.get(values, PriorityExtension);
+
+      expect(Option.isSome(result)).toBe(true);
+      expect(Option.getOrThrow(result)).toBe(42);
+    });
+
+    test('set and get a boolean value', ({ expect }) => {
+      const EnabledExtension = Extension.make('enabled', Schema.Boolean);
+      const values: Extension.Values = {};
+
+      Extension.set(values, EnabledExtension, true);
+      const result = Extension.get(values, EnabledExtension);
+
+      expect(Option.isSome(result)).toBe(true);
+      expect(Option.getOrThrow(result)).toBe(true);
+    });
+
+    test('set and get a complex object value', ({ expect }) => {
+      const ConfigSchema = Schema.Struct({
+        theme: Schema.String,
+        fontSize: Schema.Number,
+        darkMode: Schema.Boolean,
+      });
+      const ConfigExtension = Extension.make('config', ConfigSchema);
+      const values: Extension.Values = {};
+
+      const config = { theme: 'modern', fontSize: 14, darkMode: true };
+      Extension.set(values, ConfigExtension, config);
+      const result = Extension.get(values, ConfigExtension);
+
+      expect(Option.isSome(result)).toBe(true);
+      expect(Option.getOrThrow(result)).toEqual(config);
+    });
+
+    test('set and get an array value', ({ expect }) => {
+      const TagsExtension = Extension.make('tags', Schema.Array(Schema.String));
+      const values: Extension.Values = {};
+
+      const tags = ['important', 'urgent', 'review'];
+      Extension.set(values, TagsExtension, tags);
+      const result = Extension.get(values, TagsExtension);
+
+      expect(Option.isSome(result)).toBe(true);
+      expect(Option.getOrThrow(result)).toEqual(tags);
+    });
+
+    test('get returns None for missing extension', ({ expect }) => {
+      const ColorExtension = Extension.make('color', Schema.String);
+      const values: Extension.Values = {};
+
+      const result = Extension.get(values, ColorExtension);
+
+      expect(Option.isNone(result)).toBe(true);
+    });
+
+    test('overwriting an extension value', ({ expect }) => {
+      const ColorExtension = Extension.make('color', Schema.String);
+      const values: Extension.Values = {};
+
+      Extension.set(values, ColorExtension, 'red');
+      Extension.set(values, ColorExtension, 'blue');
+      const result = Extension.get(values, ColorExtension);
+
+      expect(Option.isSome(result)).toBe(true);
+      expect(Option.getOrThrow(result)).toBe('blue');
+    });
+
+    test('multiple extensions on the same values object', ({ expect }) => {
+      const ColorExtension = Extension.make('color', Schema.String);
+      const PriorityExtension = Extension.make('priority', Schema.Number);
+      const EnabledExtension = Extension.make('enabled', Schema.Boolean);
+      const values: Extension.Values = {};
+
+      Extension.set(values, ColorExtension, 'green');
+      Extension.set(values, PriorityExtension, 5);
+      Extension.set(values, EnabledExtension, false);
+
+      expect(Option.getOrThrow(Extension.get(values, ColorExtension))).toBe('green');
+      expect(Option.getOrThrow(Extension.get(values, PriorityExtension))).toBe(5);
+      expect(Option.getOrThrow(Extension.get(values, EnabledExtension))).toBe(false);
+    });
+  });
+
+  describe('curried forms', () => {
+    test('get curried form', ({ expect }) => {
+      const ColorExtension = Extension.make('color', Schema.String);
+      const values: Extension.Values = {};
+      Extension.set(values, ColorExtension, 'purple');
+
+      const getColor = Extension.get(ColorExtension);
+      const result = getColor(values);
+
+      expect(Option.isSome(result)).toBe(true);
+      expect(Option.getOrThrow(result)).toBe('purple');
+    });
+
+    test('set curried form', ({ expect }) => {
+      const ColorExtension = Extension.make('color', Schema.String);
+      const values: Extension.Values = {};
+
+      const setOrange = Extension.set(ColorExtension, 'orange');
+      setOrange(values);
+      const result = Extension.get(values, ColorExtension);
+
+      expect(Option.isSome(result)).toBe(true);
+      expect(Option.getOrThrow(result)).toBe('orange');
+    });
+
+    test('curried forms work in pipelines', ({ expect }) => {
+      const ColorExtension = Extension.make('color', Schema.String);
+      const values: Extension.Values = {};
+
+      Extension.set(ColorExtension, 'cyan')(values);
+      const result = Extension.get(ColorExtension)(values);
+
+      expect(Option.isSome(result)).toBe(true);
+      expect(Option.getOrThrow(result)).toBe('cyan');
+    });
+  });
+
+  describe('Key', () => {
+    test('Key.make creates a branded key', ({ expect }) => {
+      const key = Extension.Key.make('my-extension');
+
+      expect(key).toBe('my-extension');
+      expect(typeof key).toBe('string');
+    });
+  });
+
+  describe('Values schema', () => {
+    test('Values can be used as a schema', ({ expect }) => {
+      const PersonWithExtensions = Schema.Struct({
+        name: Schema.String,
+        extensions: Extension.Values,
+      });
+
+      const person = Schema.decodeUnknownSync(PersonWithExtensions)({
+        name: 'Alice',
+        extensions: {},
+      });
+
+      expect(person.name).toBe('Alice');
+      expect(person.extensions).toEqual({});
+    });
+
+    test('Values schema accepts extension data', ({ expect }) => {
+      const ColorExtension = Extension.make('color', Schema.String);
+      const values: Extension.Values = {};
+      Extension.set(values, ColorExtension, 'red');
+
+      const PersonWithExtensions = Schema.Struct({
+        name: Schema.String,
+        extensions: Extension.Values,
+      });
+
+      const person = Schema.decodeUnknownSync(PersonWithExtensions)({
+        name: 'Bob',
+        extensions: values,
+      });
+
+      expect(person.name).toBe('Bob');
+      const color = Extension.get(person.extensions, ColorExtension);
+      expect(Option.getOrThrow(color)).toBe('red');
+    });
+  });
+
+  describe('TypeId', () => {
+    test('TypeId is a unique symbol-like string', ({ expect }) => {
+      expect(Extension.TypeId).toBe('~@dxos/echo/Extension');
+    });
+
+    test('extensions have TypeId property', ({ expect }) => {
+      const ColorExtension = Extension.make('color', Schema.String);
+
+      expect(Extension.TypeId in ColorExtension).toBe(true);
+    });
+  });
+});

package/src/Extension.ts

@@ -0,0 +1,122 @@
+// @import-as-namespace
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Function from 'effect/Function';
+import * as Option from 'effect/Option';
+import * as Schema from 'effect/Schema';
+import type * as Types from 'effect/Types';
+
+// @import-as-namespace
+
+/**
+ * Extensions allow objects to contain typed properties that are not part of the schema.
+ */
+
+export const TypeId = '~@dxos/echo/Extension' as const;
+export type TypeId = typeof TypeId;
+
+export interface Extension<T> extends Record<
+  TypeId,
+  {
+    _Type: T;
+  }
+> {
+  readonly [TypeId]: {
+    _Type: T;
+  };
+
+  readonly key: Key;
+  readonly valueSchema: Schema.Schema<T>;
+}
+
+/**
+ * Create a new typed extension.
+ *
+ * ```ts
+ * const ColorExtension = Extension.make('color', Schema.String);
+ *
+ * const obj = Obj.make(Person, {
+ *   [Obj.Meta]: { keys: [{ source: 'external', id: '123' }] },
+ *   name: 'John',
+ *   email: 'john@example.com',
+ * });
+ *
+ * Obj.update(obj, (obj) => {
+ *   Extension.set(obj.extensions, ColorExtension, 'red');
+ * });
+ *
+ * console.log(Extension.get(obj.extensions, ColorExtension)); // 'red'
+ * ```
+ */
+export const make = <S extends Schema.Schema.AnyNoContext>(
+  key: string,
+  valueSchema: S,
+): Extension<Schema.Schema.Type<S>> => {
+  return {
+    [TypeId]: {} as any,
+    key: Key.make(key),
+    valueSchema,
+  };
+};
+
+/**
+ * Unique identifier for an extension.
+ */
+// TODO(dmaretskyi): filter to be fully qualified: (e.g., org.dxos.extension.color)
+export const Key = Schema.String.pipe(Schema.brand('~@dxos/echo/ExtensionKey'));
+export type Key = Schema.Schema.Type<typeof Key>;
+
+/**
+ * Set of extension values.
+ *
+ * Can be used inside an object/relation schema:
+ *
+ * ```ts
+ * const Person = Schema.Struct({
+ *   name: Schema.String,
+ *   extensions: Extension.Values,
+ * });
+ * ```
+ */
+export const Values = Schema.Record({ key: Key, value: Schema.Unknown });
+export interface Values extends Schema.Schema.Type<typeof Values> {}
+
+/**
+ * Get the value of an extension from a set of values.
+ */
+export const get: {
+  <T>(extension: Extension<T>): (values: Values) => Option.Option<T>;
+  <T>(values: Values, extension: Extension<T>): Option.Option<T>;
+} = Function.dual<
+  <T>(extension: Extension<T>) => (values: Values) => Option.Option<T>,
+  <T>(values: Values, extension: Extension<T>) => Option.Option<T>
+>(2, (values, extension) => {
+  if (!(extension.key in values)) {
+    return Option.none();
+  }
+
+  return Function.pipe(values[extension.key], Schema.decodeUnknownSync(extension.valueSchema), Option.some);
+});
+
+/**
+ * Set the value of an extension in a set of values.
+ *
+ * Can also be used within Obj.update callback:
+ *
+ * ```ts
+ * Obj.update(obj, (obj) => {
+ *   Extension.set(obj.extensions, ColorExtension, 'red');
+ * });
+ * ```
+ */
+export const set: {
+  <T>(extension: Extension<T>, value: T): (values: Values) => void;
+  <T>(values: Types.Mutable<Values>, extension: Extension<T>, value: T): void;
+} = Function.dual<
+  <T>(extension: Extension<T>, value: T) => (values: Values) => void,
+  <T>(values: Types.Mutable<Values>, extension: Extension<T>, value: T) => void
+>(3, (values, extension, value) => {
+  values[extension.key] = Schema.encodeSync(extension.valueSchema)(value);
+});