@enbox/api 0.2.3 → 0.3.0

package/src/typed-live-query.ts

@@ -0,0 +1,200 @@
+/**
+ * A type-safe wrapper around {@link LiveQuery} that carries the data type `T`
+ * through initial snapshot records and real-time change events.
+ *
+ * `TypedLiveQuery<T>` wraps a `LiveQuery` so that:
+ * - `.records` returns `TypedRecord<T>[]` instead of `Record[]`.
+ * - `.on('create', handler)` provides `TypedRecord<T>` in the callback.
+ * - `.on('change', handler)` provides `TypedRecordChange<T>` in the callback.
+ * - `.on('disconnected' | 'reconnecting' | 'reconnected' | 'eose', handler)`
+ *   forwards transport lifecycle events from the underlying `LiveQuery`.
+ *
+ * @example
+ * ```ts
+ * const { liveQuery } = await typed.records.subscribe('friend');
+ * // liveQuery is TypedLiveQuery<FriendData>
+ *
+ * for (const record of liveQuery.records) {
+ *   const data = await record.data.json(); // FriendData
+ * }
+ *
+ * liveQuery.on('create', async (record) => {
+ *   const data = await record.data.json(); // FriendData
+ * });
+ *
+ * // Connection lifecycle events
+ * liveQuery.on('disconnected', () => showOfflineIndicator());
+ * liveQuery.on('reconnected', () => hideOfflineIndicator());
+ * liveQuery.on('eose', () => console.log('catch-up complete'));
+ * ```
+ */
+
+import type { PaginationCursor } from '@enbox/dwn-sdk-js';
+import type { LiveQuery, RecordChange } from './live-query.js';
+
+import { TypedRecord } from './typed-record.js';
+
+// ---------------------------------------------------------------------------
+// Typed change event
+// ---------------------------------------------------------------------------
+
+/**
+ * Describes a change to a record in a {@link TypedLiveQuery}.
+ *
+ * Same shape as {@link RecordChange} but with the record wrapped
+ * in a {@link TypedRecord}.
+ */
+export type TypedRecordChange<T> = {
+  /** Whether the record was created, updated, or deleted. */
+  type: RecordChange['type'];
+
+  /** The typed record affected by the change. */
+  record: TypedRecord<T>;
+};
+
+// ---------------------------------------------------------------------------
+// TypedLiveQuery class
+// ---------------------------------------------------------------------------
+
+/**
+ * A type-safe wrapper around {@link LiveQuery} that preserves the data type `T`
+ * through the initial snapshot and all subsequent change events.
+ *
+ * Obtain instances through `TypedWeb5.records.subscribe()` — never construct
+ * directly.
+ */
+export class TypedLiveQuery<T> {
+  /** The underlying untyped LiveQuery instance. */
+  private _liveQuery: LiveQuery;
+
+  /** Cached typed record array, built lazily from the underlying records. */
+  private _typedRecords?: TypedRecord<T>[];
+
+  constructor(liveQuery: LiveQuery) {
+    this._liveQuery = liveQuery;
+  }
+
+  // -------------------------------------------------------------------------
+  // Escape hatch
+  // -------------------------------------------------------------------------
+
+  /** Access the underlying untyped {@link LiveQuery} for advanced use cases. */
+  public get rawLiveQuery(): LiveQuery {
+    return this._liveQuery;
+  }
+
+  // -------------------------------------------------------------------------
+  // Typed initial snapshot
+  // -------------------------------------------------------------------------
+
+  /** The initial snapshot of matching records, typed as `TypedRecord<T>[]`. */
+  public get records(): TypedRecord<T>[] {
+    if (!this._typedRecords) {
+      this._typedRecords = this._liveQuery.records.map(
+        (record) => new TypedRecord<T>(record),
+      );
+    }
+    return this._typedRecords;
+  }
+
+  /**
+   * Pagination cursor for fetching the next page of initial results.
+   *
+   * `undefined` when there are no more results.
+   */
+  public get cursor(): PaginationCursor | undefined {
+    return this._liveQuery.cursor;
+  }
+
+  /**
+   * Whether the transport connection is currently active.
+   * Delegates to the underlying `LiveQuery.isConnected`.
+   */
+  public get isConnected(): boolean {
+    return this._liveQuery.isConnected;
+  }
+
+  // -------------------------------------------------------------------------
+  // Typed event handlers
+  // -------------------------------------------------------------------------
+
+  /**
+   * Register a typed event handler. Returns an unsubscribe function.
+   *
+   * Supports both record change events (`change`, `create`, `update`, `delete`)
+   * and transport lifecycle events (`disconnected`, `reconnecting`,
+   * `reconnected`, `eose`).
+   *
+   * @param event - The event type to listen for.
+   * @param handler - The handler function with typed record(s) or lifecycle data.
+   * @returns A function that removes the handler when called.
+   *
+   * @example
+   * ```ts
+   * const off = liveQuery.on('create', (record) => {
+   *   // record is TypedRecord<T>
+   * });
+   * off(); // stop listening
+   *
+   * liveQuery.on('disconnected', () => showOfflineIndicator());
+   * liveQuery.on('reconnected', () => hideOfflineIndicator());
+   * ```
+   */
+  public on(event: 'change', handler: (change: TypedRecordChange<T>) => void): () => void;
+  public on(event: 'create', handler: (record: TypedRecord<T>) => void): () => void;
+  public on(event: 'update', handler: (record: TypedRecord<T>) => void): () => void;
+  public on(event: 'delete', handler: (record: TypedRecord<T>) => void): () => void;
+  public on(event: 'disconnected', handler: () => void): () => void;
+  public on(event: 'reconnecting', handler: (detail: { attempt: number }) => void): () => void;
+  public on(event: 'reconnected', handler: () => void): () => void;
+  public on(event: 'eose', handler: () => void): () => void;
+  public on(
+    event: 'change' | 'create' | 'update' | 'delete' | 'disconnected' | 'reconnecting' | 'reconnected' | 'eose',
+    handler: ((change: TypedRecordChange<T>) => void)
+      | ((record: TypedRecord<T>) => void)
+      | ((detail: { attempt: number }) => void)
+      | (() => void),
+  ): () => void {
+    // Lifecycle events: delegate directly to the underlying LiveQuery.
+    if (event === 'disconnected') {
+      return this._liveQuery.on('disconnected', handler as () => void);
+    }
+    if (event === 'reconnected') {
+      return this._liveQuery.on('reconnected', handler as () => void);
+    }
+    if (event === 'eose') {
+      return this._liveQuery.on('eose', handler as () => void);
+    }
+    if (event === 'reconnecting') {
+      return this._liveQuery.on('reconnecting', handler as (detail: { attempt: number }) => void);
+    }
+
+    // Record change events: wrap records in TypedRecord.
+    if (event === 'change') {
+      return this._liveQuery.on('change', (change: RecordChange): void => {
+        (handler as (change: TypedRecordChange<T>) => void)({
+          type   : change.type,
+          record : new TypedRecord<T>(change.record),
+        });
+      });
+    }
+
+    // For create/update/delete, the underlying LiveQuery handler receives a Record.
+    // Cast event to 'create' to satisfy the overload resolver — the actual value
+    // is always one of 'create' | 'update' | 'delete' at this point.
+    return this._liveQuery.on(event as 'create', (record): void => {
+      (handler as (record: TypedRecord<T>) => void)(new TypedRecord<T>(record));
+    });
+  }
+
+  // -------------------------------------------------------------------------
+  // Lifecycle
+  // -------------------------------------------------------------------------
+
+  /**
+   * Close the underlying subscription and stop dispatching events.
+   */
+  public async close(): Promise<void> {
+    return this._liveQuery.close();
+  }
+}

package/src/typed-record.ts

@@ -0,0 +1,309 @@
+/**
+ * A type-safe wrapper around {@link Record} that carries the data type `T`
+ * through its entire lifecycle — from write to read, query, update, and
+ * subscribe.
+ *
+ * `TypedRecord<T>` uses composition (not inheritance) to wrap the underlying
+ * untyped `Record` class. All read-only getters and lifecycle methods are
+ * forwarded, while data-access and mutation methods are enhanced with the
+ * generic `T`:
+ *
+ * - `.data.json()` returns `Promise<T>` instead of `Promise<unknown>`.
+ * - `.update({ data })` accepts `Partial<T>` for the data payload.
+ *
+ * @example
+ * ```ts
+ * const { record } = await typed.records.write('friend', {
+ *   data: { did: 'did:example:alice', alias: 'Alice' },
+ * });
+ *
+ * // record is TypedRecord<FriendData>
+ * const data = await record.data.json(); // FriendData — no manual cast
+ * ```
+ */
+
+import type { Record } from './record.js';
+import type { RecordData } from './record-data.js';
+import type { DwnDateSort, DwnMessage, DwnPaginationCursor, DwnResponseStatus } from '@enbox/agent';
+import type { RecordDeleteParams, RecordModel, RecordUpdateParams } from './record-types.js';
+
+import type { DwnInterface } from '@enbox/agent';
+
+// ---------------------------------------------------------------------------
+// Typed data accessor
+// ---------------------------------------------------------------------------
+
+/**
+ * A data accessor that preserves the record's type parameter `T` on
+ * the `json()` method.
+ *
+ * All other methods (`blob`, `bytes`, `text`, `stream`, `then`, `catch`)
+ * are forwarded unchanged from the underlying {@link RecordData}.
+ */
+export type TypedRecordData<T> = Omit<RecordData, 'json'> & {
+  /** Parse the data as JSON, returning the typed data shape `T`. */
+  json: () => Promise<T>;
+};
+
+// ---------------------------------------------------------------------------
+// Typed update params
+// ---------------------------------------------------------------------------
+
+/**
+ * Update parameters for a {@link TypedRecord}.
+ *
+ * Extends the base `RecordUpdateParams` but narrows `data` from `unknown`
+ * to `Partial<T>`.
+ */
+export type TypedRecordUpdateParams<T> = Omit<RecordUpdateParams, 'data'> & {
+  /** The new data for the record. Type-checked against the schema map. */
+  data?: Partial<T>;
+};
+
+// ---------------------------------------------------------------------------
+// Typed update / delete results
+// ---------------------------------------------------------------------------
+
+/**
+ * Result of a {@link TypedRecord.update} operation.
+ */
+export type TypedRecordUpdateResult<T> = DwnResponseStatus & {
+  /** The updated record, carrying the same type parameter. */
+  record: TypedRecord<T>;
+};
+
+/**
+ * Result of a {@link TypedRecord.delete} operation.
+ */
+export type TypedRecordDeleteResult<T> = DwnResponseStatus & {
+  /** The deleted record, carrying the same type parameter. */
+  record: TypedRecord<T>;
+};
+
+// ---------------------------------------------------------------------------
+// TypedRecord class
+// ---------------------------------------------------------------------------
+
+/**
+ * A type-safe wrapper around {@link Record} that preserves the data type `T`.
+ *
+ * Obtain instances through `TypedWeb5.records.write()`, `.query()`, `.read()`,
+ * or `.subscribe()` — never construct directly.
+ */
+export class TypedRecord<T> {
+  /** The underlying untyped Record instance. */
+  private _record: Record;
+
+  constructor(record: Record) {
+    this._record = record;
+  }
+
+  // -------------------------------------------------------------------------
+  // Escape hatch
+  // -------------------------------------------------------------------------
+
+  /** Access the underlying untyped {@link Record} for advanced use cases. */
+  public get rawRecord(): Record {
+    return this._record;
+  }
+
+  // -------------------------------------------------------------------------
+  // Typed data accessor
+  // -------------------------------------------------------------------------
+
+  /**
+   * Returns the data of the current record with type-safe accessors.
+   *
+   * The `json()` method returns `Promise<T>` — no manual generic needed.
+   *
+   * @throws `Error` if the record has been deleted.
+   */
+  public get data(): TypedRecordData<T> {
+    const underlying = this._record.data;
+    return {
+      blob   : (): Promise<Blob> => underlying.blob(),
+      bytes  : (): Promise<Uint8Array> => underlying.bytes(),
+      json   : (): Promise<T> => underlying.json<T>(),
+      text   : (): Promise<string> => underlying.text(),
+      stream : (): Promise<ReadableStream> => underlying.stream(),
+      then   : underlying.then.bind(underlying),
+      catch  : underlying.catch.bind(underlying),
+    };
+  }
+
+  // -------------------------------------------------------------------------
+  // Typed mutation methods
+  // -------------------------------------------------------------------------
+
+  /**
+   * Update the current record on the DWN.
+   *
+   * @param params - Parameters including the typed `data` payload.
+   * @returns The status and an updated {@link TypedRecord}.
+   * @throws `Error` if the record has been deleted.
+   */
+  public async update(params: TypedRecordUpdateParams<T>): Promise<TypedRecordUpdateResult<T>> {
+    const { status, record } = await this._record.update(params as RecordUpdateParams);
+    return { status, record: new TypedRecord<T>(record) };
+  }
+
+  /**
+   * Delete the current record on the DWN.
+   *
+   * @param params - Delete parameters.
+   * @returns The status and a {@link TypedRecord} reflecting the deleted state.
+   */
+  public async delete(params?: RecordDeleteParams): Promise<TypedRecordDeleteResult<T>> {
+    const { status, record } = await this._record.delete(params);
+    return { status, record: new TypedRecord<T>(record) };
+  }
+
+  // -------------------------------------------------------------------------
+  // Forwarded lifecycle methods
+  // -------------------------------------------------------------------------
+
+  /**
+   * Stores the current record state to the owner's DWN.
+   *
+   * @param importRecord - If true, sign as owner before storing. Defaults to false.
+   */
+  public async store(importRecord: boolean = false): Promise<DwnResponseStatus> {
+    return this._record.store(importRecord);
+  }
+
+  /**
+   * Signs and optionally stores the record to the owner's DWN.
+   * Useful when importing a record signed by someone else.
+   *
+   * @param store - If true, store after signing. Defaults to true.
+   */
+  public async import(store: boolean = true): Promise<DwnResponseStatus> {
+    return this._record.import(store);
+  }
+
+  /**
+   * Send the current record to a remote DWN.
+   *
+   * @param target - Optional DID of the target DWN. Defaults to the connected DID.
+   */
+  public async send(target?: string): Promise<DwnResponseStatus> {
+    return this._record.send(target);
+  }
+
+  /**
+   * Returns a JSON representation of the Record instance.
+   */
+  public toJSON(): RecordModel {
+    return this._record.toJSON();
+  }
+
+  /**
+   * Returns a string representation of the Record instance.
+   */
+  public toString(): string {
+    return this._record.toString();
+  }
+
+  /**
+   * Returns a pagination cursor for the current record given a sort order.
+   */
+  public async paginationCursor(sort: DwnDateSort): Promise<DwnPaginationCursor | undefined> {
+    return this._record.paginationCursor(sort);
+  }
+
+  // -------------------------------------------------------------------------
+  // Forwarded immutable property getters
+  // -------------------------------------------------------------------------
+
+  /** Record's ID. */
+  public get id(): string { return this._record.id; }
+
+  /** Record's context ID. */
+  public get contextId(): string | undefined { return this._record.contextId; }
+
+  /** Record's creation date. */
+  public get dateCreated(): string { return this._record.dateCreated; }
+
+  /** Record's parent ID. */
+  public get parentId(): string | undefined { return this._record.parentId; }
+
+  /** Record's protocol. */
+  public get protocol(): string | undefined { return this._record.protocol; }
+
+  /** Record's protocol path. */
+  public get protocolPath(): string | undefined { return this._record.protocolPath; }
+
+  /** Record's recipient. */
+  public get recipient(): string | undefined { return this._record.recipient; }
+
+  /** Record's schema. */
+  public get schema(): string | undefined { return this._record.schema; }
+
+  // -------------------------------------------------------------------------
+  // Forwarded mutable property getters
+  // -------------------------------------------------------------------------
+
+  /** Record's data format. */
+  public get dataFormat(): string | undefined { return this._record.dataFormat; }
+
+  /** Record's data CID. */
+  public get dataCid(): string | undefined { return this._record.dataCid; }
+
+  /** Record's data size. */
+  public get dataSize(): number | undefined { return this._record.dataSize; }
+
+  /** Record's published date. */
+  public get datePublished(): string | undefined { return this._record.datePublished; }
+
+  /** Record's published status. */
+  public get published(): boolean | undefined { return this._record.published; }
+
+  /** Tags of the record. */
+  public get tags(): DwnMessage[DwnInterface.RecordsWrite]['descriptor']['tags'] | undefined {
+    return this._record.tags;
+  }
+
+  // -------------------------------------------------------------------------
+  // Forwarded state-dependent property getters
+  // -------------------------------------------------------------------------
+
+  /** DID that is the logical author of the Record. */
+  public get author(): string { return this._record.author; }
+
+  /** DID that is the original creator of the Record. */
+  public get creator(): string { return this._record.creator; }
+
+  /** Record's message timestamp. */
+  public get timestamp(): string { return this._record.timestamp; }
+
+  /** Record's encryption details. */
+  public get encryption(): DwnMessage[DwnInterface.RecordsWrite]['encryption'] {
+    return this._record.encryption;
+  }
+
+  /** Record's authorization. */
+  public get authorization(): DwnMessage[DwnInterface.RecordsWrite | DwnInterface.RecordsDelete]['authorization'] {
+    return this._record.authorization;
+  }
+
+  /** Record's attestation. */
+  public get attestation(): DwnMessage[DwnInterface.RecordsWrite]['attestation'] | undefined {
+    return this._record.attestation;
+  }
+
+  /** Role under which the author is writing the record. */
+  public get protocolRole(): string | undefined { return this._record.protocolRole; }
+
+  /** Record's deleted state. */
+  public get deleted(): boolean { return this._record.deleted; }
+
+  /** Record's initial write if the record has been updated. */
+  public get initialWrite(): DwnMessage[DwnInterface.RecordsWrite] | undefined {
+    return this._record.initialWrite;
+  }
+
+  /** The raw DWN message backing this record. */
+  public get rawMessage(): DwnMessage[DwnInterface.RecordsWrite] | DwnMessage[DwnInterface.RecordsDelete] {
+    return this._record.rawMessage;
+  }
+}