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

package/src/Entity.ts

@@ -0,0 +1,234 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+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';
+
+// 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 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.change`.
+ */
+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.change` 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.change
+ * Entity.change(entity, (e) => {
+ *   e.name = 'Updated';
+ *   e.count = 42;
+ * });
+ *
+ * // Direct mutation throws
+ * entity.name = 'Bob'; // Error: Cannot modify outside Entity.change()
+ * ```
+ *
+ * Note: For type-specific operations, prefer `Obj.change` or `Relation.change`.
+ */
+export const change = <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.change`, `Obj.change`, or `Relation.change` 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.change`, `Obj.change`, or `Relation.change` callback.
+ */
+export const removeTag = (entity: Mutable<Unknown>, tag: string): void => internal.removeTag(entity, tag);

package/src/Err.ts

@@ -0,0 +1,38 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+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/Feed.ts

@@ -0,0 +1,254 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Context from 'effect/Context';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import type * as Option from 'effect/Option';
+import * as Schema from 'effect/Schema';
+
+import { DXN } from '@dxos/keys';
+
+import type * as Entity from './Entity';
+import type * as Filter from './Filter';
+import * as internal from './internal';
+import * as Obj from './Obj';
+import type * as Query from './Query';
+import type * as QueryResult from './QueryResult';
+import * as Type from './Type';
+
+/**
+ * Runtime schema for a Feed object.
+ *
+ * @example
+ * ```ts
+ * const feed = Obj.make(Feed.Feed, { name: 'notifications', kind: 'dxos.org/plugin/notifications/v1' });
+ * ```
+ */
+export const Feed = Schema.Struct({
+  /** User-facing display name. */
+  name: Schema.String.pipe(Schema.optional),
+  /** Identifier for the feed's kind (e.g., plugin id). */
+  kind: Schema.String.pipe(internal.FormInputAnnotation.set(false), Schema.optional),
+}).pipe(
+  Type.object({
+    typename: 'dxos.org/type/Feed',
+    version: '0.1.0',
+  }),
+);
+
+/**
+ * TypeScript instance type for a Feed object.
+ */
+export interface Feed extends Schema.Schema.Type<typeof Feed> {}
+
+//
+// Types
+//
+
+/**
+ * Meta key source for storing the backing DXN bound to a feed object.
+ */
+// TODO(dmaretskyi): Enforce that Feed ObjectId = feed storage ID. And remove this key.
+export const DXN_KEY = 'dxos.org/key/feed';
+
+/**
+ * Opaque cursor for iterating over feed items.
+ */
+// TODO(dmaretskyi): T needs to be referenced in the type structure for typescript to respect it during inference and type-checking.
+export interface Cursor<T = Obj.Snapshot> {
+  readonly _tag: 'Cursor';
+}
+
+/**
+ * Retention options for a feed.
+ */
+export interface RetentionOptions {
+  /** Retain items after this cursor position. */
+  // TODO(wittjosiah): Use FeedCursor from @dxos/feed?
+  cursor?: string;
+}
+
+//
+// Factory
+//
+
+/**
+ * Creates a new feed object.
+ *
+ * @example
+ * ```ts
+ * const feed = Feed.make({ name: 'notifications', kind: 'dxos.org/plugin/notifications/v1' });
+ * ```
+ */
+// TODO(wittjosiah): How to control the feed namespace (data/trace)? Why do feeds have namespaces?
+export const make = (props: Obj.MakeProps<typeof Feed>): Feed => Obj.make(Feed, props);
+
+/**
+ * Reads the queue DXN from feed metadata.
+ *
+ * @deprecated
+ */
+// TODO(wittjosiah): Align backing feed dxn's with object DXN.
+export const getQueueDxn = (feed: Feed): DXN | undefined => {
+  const keys = Obj.getKeys(feed, DXN_KEY);
+  return keys.length === 0 ? undefined : DXN.parse(keys[0].id);
+};
+
+//
+// Service
+//
+
+/**
+ * Effect service for feed operations.
+ * Provides the bridge to the underlying storage implementation.
+ * Must be provided by the application layer (e.g., echo-db).
+ */
+export class Service extends Context.Tag('@dxos/echo/Feed/Service')<
+  Service,
+  {
+    /**
+     * Appends items to a feed.
+     */
+    append(feed: Feed, items: Entity.Unknown[]): Promise<void>;
+
+    /**
+     * Removes items from a feed by ID.
+     */
+    // TODO(dmaretskyi): Change type to ObjectId.
+    remove(feed: Feed, ids: string[]): Promise<void>;
+
+    /**
+     * Queries items in a feed.
+     */
+    query: {
+      <Q extends Query.Any>(feed: Feed, query: Q): QueryResult.QueryResult<Query.Type<Q>>;
+      <F extends Filter.Any>(feed: Feed, filter: F): QueryResult.QueryResult<Filter.Type<F>>;
+    };
+  }
+>() {}
+
+/**
+ * Layer that provides a Feed service that throws when accessed.
+ * Useful as a default layer when no feed service is available.
+ */
+export const notAvailable: Layer.Layer<Service> = Layer.succeed(Service, {
+  append: () => {
+    throw new Error('Feed.Service not available');
+  },
+  remove: () => {
+    throw new Error('Feed.Service not available');
+  },
+  query: () => {
+    throw new Error('Feed.Service not available');
+  },
+} as Context.Tag.Service<Service>);
+
+//
+// Operations
+//
+
+/**
+ * Appends items to a feed.
+ *
+ * @example
+ * ```ts
+ * yield* Feed.append(feed, [Obj.make(Notification, { title: 'Hello' })]);
+ * ```
+ */
+export const append = (feed: Feed, items: Entity.Unknown[]): Effect.Effect<void, never, Service> =>
+  Effect.gen(function* () {
+    const service = yield* Service;
+    yield* Effect.promise(() => service.append(feed, items));
+  });
+
+/**
+ * Removes items from a feed.
+ *
+ * @example
+ * ```ts
+ * yield* Feed.remove(feed, [item]);
+ * ```
+ */
+// TODO(dmaretskyi): Should we allow snapshots here? - what does it mean to remove a snapshot?
+export const remove = (feed: Feed, items: (Entity.Unknown | Obj.Snapshot)[]): Effect.Effect<void, never, Service> =>
+  Effect.gen(function* () {
+    const service = yield* Service;
+    const ids = items.map((item) => item.id);
+    yield* Effect.promise(() => service.remove(feed, ids));
+  });
+
+/**
+ * Creates a reactive query over items in a feed.
+ *
+ * @example
+ * ```ts
+ * const result = yield* Feed.query(feed, Filter.type(Person));
+ * ```
+ */
+// TODO(dmaretskyi): Suport chained queries:
+//                   const result = yield* feed.pipe(Feed.query(Filter.type(Person))); result.subscribe(...)
+//                   const objects = yield* feed.pipe(Feed.query(Filter.type(Person))).run;
+//                   const object = yield* feed.pipe(Feed.query(Filter.type(Person))).first;
+// ... unify for Database and schema queries.
+export const query: {
+  <Q extends Query.Any>(feed: Feed, query: Q): Effect.Effect<QueryResult.QueryResult<Query.Type<Q>>, never, Service>;
+  <F extends Filter.Any>(feed: Feed, filter: F): Effect.Effect<QueryResult.QueryResult<Filter.Type<F>>, never, Service>;
+} = (feed: Feed, queryOrFilter: Query.Any | Filter.Any) =>
+  Service.pipe(Effect.map((service) => service.query(feed, queryOrFilter as any) as QueryResult.QueryResult<any>));
+
+/**
+ * Executes a feed query once and returns the results.
+ *
+ * @example
+ * ```ts
+ * const items = yield* Feed.runQuery(feed, Filter.type(Person));
+ * ```
+ */
+export const runQuery: {
+  <Q extends Query.Any>(feed: Feed, query: Q): Effect.Effect<Query.Type<Q>[], never, Service>;
+  <F extends Filter.Any>(feed: Feed, filter: F): Effect.Effect<Filter.Type<F>[], never, Service>;
+} = (feed: Feed, queryOrFilter: Query.Any | Filter.Any) =>
+  query(feed, queryOrFilter as any).pipe(Effect.flatMap((queryResult) => Effect.promise(() => queryResult.run())));
+
+/**
+ * Creates a cursor for iterating over feed items.
+ * Currently stubbed — cursor operations are not yet implemented.
+ *
+ * @example
+ * ```ts
+ * const cursor = yield* Feed.cursor<Person>(feed);
+ * const item = yield* Feed.next(cursor);
+ * ```
+ */
+// TODO(wittjosiah): Implement cursor operations. Use Effect streams?
+export const cursor = <T = Obj.Snapshot>(_feed: Feed): Effect.Effect<Cursor<T>, never, Service> =>
+  Effect.succeed({ _tag: 'Cursor' } as Cursor<T>);
+
+/**
+ * Returns the next item from a feed cursor.
+ * Currently stubbed — cursor operations are not yet implemented.
+ */
+export const next = <T = Obj.Snapshot>(_cursor: Cursor<T>): Effect.Effect<T, never, Service> =>
+  Effect.die('Feed.next is not yet implemented');
+
+/**
+ * Returns the next item from a feed cursor as an Option.
+ * Currently stubbed — cursor operations are not yet implemented.
+ */
+export const nextOption = <T = Obj.Snapshot>(_cursor: Cursor<T>): Effect.Effect<Option.Option<T>, never, Service> =>
+  Effect.die('Feed.nextOption is not yet implemented');
+
+/**
+ * Sets the local retention policy for a feed.
+ * Currently stubbed — queues do not yet support retention.
+ *
+ * @example
+ * ```ts
+ * yield* Feed.setRetention(feed, { count: 1000 });
+ * ```
+ */
+// TODO(feed): Implement when queue retention is supported.
+export const setRetention = (_feed: Feed, _options: RetentionOptions): Effect.Effect<void, never, Service> =>
+  Effect.void;