@enbox/api 0.2.3 → 0.3.0

package/src/typed-web5.ts

@@ -6,6 +6,10 @@
  * and schema into every operation, and provides compile-time path
  * autocompletion plus typed data payloads via the schema map.
  *
+ * All record-returning methods wrap the underlying `Record` instances in
+ * {@link TypedRecord} so that type information flows through reads, queries,
+ * updates, and subscriptions without manual casts.
+ *
  * @example
  * ```ts
  * const social = web5.using(SocialProtocol);
@@ -13,29 +17,36 @@
  * // Install the protocol
  * await social.configure();
  *
- * // Write — path and data type are checked at compile time
- * const { record } = await social.records.write('thread', {
+ * // Create — path and data type are checked at compile time
+ * const { record } = await social.records.create('thread', {
  *   data: { title: 'Hello World', body: '...' },
  * });
+ * // record is TypedRecord<ThreadData>
+ *
+ * const data = await record.data.json(); // ThreadData — no cast needed
  *
  * // Query — protocol and protocolPath are auto-injected
  * const { records } = await social.records.query('thread');
+ * // records is TypedRecord<ThreadData>[]
  *
- * // Subscribe — real-time changes via LiveQuery
+ * // Subscribe — real-time changes via TypedLiveQuery
  * const { liveQuery } = await social.records.subscribe('thread/reply');
- * liveQuery.on('create', (record) => { ... });
+ * liveQuery.on('create', (record) => {
+ *   // record is TypedRecord<ReplyData>
+ * });
  * ```
  */
 
 import type { DwnApi } from './dwn-api.js';
-import type { LiveQuery } from './live-query.js';
 import type { Protocol } from './protocol.js';
-import type { Record } from './record.js';
 
 import type { DateSort, ProtocolDefinition, ProtocolType, RecordsFilter } from '@enbox/dwn-sdk-js';
 import type { DwnPaginationCursor, DwnResponseStatus } from '@enbox/agent';
 import type { ProtocolPaths, SchemaMap, TypedProtocol, TypeNameAtPath } from './protocol-types.js';
 
+import { TypedLiveQuery } from './typed-live-query.js';
+import { TypedRecord } from './typed-record.js';
+
 // ---------------------------------------------------------------------------
 // Helper types
 // ---------------------------------------------------------------------------
@@ -46,7 +57,7 @@ import type { ProtocolPaths, SchemaMap, TypedProtocol, TypeNameAtPath } from './
  * If the schema map contains a mapping for the type name at the given path,
  * that type is returned. Otherwise falls back to `unknown`.
  */
-type DataForPath<
+export type DataForPath<
   _D extends ProtocolDefinition,
   M extends SchemaMap,
   Path extends string,
@@ -80,8 +91,8 @@ type DataFormatForPath<
 // Request / response types
 // ---------------------------------------------------------------------------
 
-/** Options for {@link TypedWeb5} `records.write()`. */
-export type TypedWriteRequest<
+/** Options for {@link TypedWeb5} `records.create()`. */
+export type TypedCreateRequest<
   D extends ProtocolDefinition,
   M extends SchemaMap,
   Path extends string,
@@ -104,9 +115,9 @@ export type TypedWriteRequest<
   encryption?: boolean;
 };
 
-/** Response from {@link TypedWeb5} `records.write()`. */
-export type TypedWriteResponse = DwnResponseStatus & {
-  record: Record;
+/** Response from {@link TypedWeb5} `records.create()`. */
+export type TypedCreateResponse<T = unknown> = DwnResponseStatus & {
+  record: TypedRecord<T>;
 };
 
 /** Filter options for {@link TypedWeb5} `records.query()`. */
@@ -130,8 +141,8 @@ export type TypedQueryRequest = {
 };
 
 /** Response from {@link TypedWeb5} `records.query()`. */
-export type TypedQueryResponse = DwnResponseStatus & {
-  records: Record[];
+export type TypedQueryResponse<T = unknown> = DwnResponseStatus & {
+  records: TypedRecord<T>[];
   cursor?: DwnPaginationCursor;
 };
 
@@ -148,8 +159,8 @@ export type TypedReadRequest = {
 };
 
 /** Response from {@link TypedWeb5} `records.read()`. */
-export type TypedReadResponse = DwnResponseStatus & {
-  record: Record;
+export type TypedReadResponse<T = unknown> = DwnResponseStatus & {
+  record: TypedRecord<T>;
 };
 
 /** Options for {@link TypedWeb5} `records.delete()`. */
@@ -172,9 +183,9 @@ export type TypedSubscribeRequest = {
 };
 
 /** Response from {@link TypedWeb5} `records.subscribe()`. */
-export type TypedSubscribeResponse = DwnResponseStatus & {
-  /** The live query instance, or `undefined` if the request failed. */
-  liveQuery?: LiveQuery;
+export type TypedSubscribeResponse<T = unknown> = DwnResponseStatus & {
+  /** The typed live query instance, or `undefined` if the request failed. */
+  liveQuery?: TypedLiveQuery<T>;
 };
 
 // ---------------------------------------------------------------------------
@@ -185,6 +196,10 @@ export type TypedSubscribeResponse = DwnResponseStatus & {
  * A protocol-scoped API that auto-injects `protocol`, `protocolPath`, and
  * `schema` into every DWN operation.
  *
+ * All record-returning methods wrap results in {@link TypedRecord} so that
+ * the data type `T` (resolved from the schema map) flows end-to-end — from
+ * write through read, query, update, and subscribe — without manual casts.
+ *
  * Obtain an instance via `web5.using(typedProtocol)`.
  *
  * @example
@@ -193,13 +208,17 @@ export type TypedSubscribeResponse = DwnResponseStatus & {
  *
  * await social.configure();
  *
- * const { record } = await social.records.write('friend', {
+ * const { record } = await social.records.create('friend', {
  *   data: { did: 'did:example:alice', alias: 'Alice' },
  * });
+ * const data = await record.data.json(); // FriendData — no cast
  *
  * const { records } = await social.records.query('friend', {
  *   filter: { tags: { did: 'did:example:alice' } },
  * });
+ * for (const r of records) {
+ *   const d = await r.data.json(); // FriendData
+ * }
  * ```
  */
 export class TypedWeb5<
@@ -208,10 +227,14 @@ export class TypedWeb5<
 > {
   private _dwn: DwnApi;
   private _definition: D;
+  private _configured: boolean = false;
+  private _validPaths: Set<string>;
+  private _records?: TypedWeb5<D, M>['records'];
 
   constructor(dwn: DwnApi, protocol: TypedProtocol<D, M>) {
     this._dwn = dwn;
     this._definition = protocol.definition;
+    this._validPaths = collectPaths(this._definition.structure);
   }
 
   /** The protocol URI. */
@@ -244,15 +267,47 @@ export class TypedWeb5<
     if (protocols.length > 0) {
       const existing = protocols[0];
       if (definitionsEqual(existing.definition, this._definition)) {
+        this._configured = true;
         return { status: { code: 200, detail: 'OK' }, protocol: existing };
       }
     }
 
     // Not installed or definition has changed — configure the new version.
-    return this._dwn.protocols.configure({
+    const result = await this._dwn.protocols.configure({
       definition : this._definition,
       encryption : options?.encryption,
     });
+
+    if (result.status.code === 202) {
+      this._configured = true;
+    }
+
+    return result;
+  }
+
+  /** Whether the protocol has been configured (installed) on the local DWN. */
+  public get isConfigured(): boolean {
+    return this._configured;
+  }
+
+  /**
+   * Validates that the protocol has been configured and that the path is
+   * recognized. Throws a descriptive error if either check fails.
+   */
+  private _assertReady(path: string): void {
+    if (!this._configured) {
+      throw new Error(
+        `TypedWeb5: protocol '${this._definition.protocol}' has not been configured. ` +
+        'Call configure() before performing record operations.',
+      );
+    }
+
+    if (!this._validPaths.has(path)) {
+      throw new Error(
+        `TypedWeb5: invalid protocol path '${path}'. ` +
+        `Valid paths are: ${[...this._validPaths].join(', ')}.`,
+      );
+    }
   }
 
   /**
@@ -261,29 +316,57 @@ export class TypedWeb5<
    * Every method auto-injects the protocol URI, protocolPath, and schema
    * from the protocol definition. Path parameters provide compile-time
    * autocompletion via `ProtocolPaths<D>`.
+   *
+   * All methods return {@link TypedRecord} or {@link TypedLiveQuery} instances
+   * that carry the resolved data type from the schema map.
    */
   public get records(): {
-    write: <Path extends ProtocolPaths<D> & string>(path: Path, request: TypedWriteRequest<D, M, Path>) => Promise<TypedWriteResponse>;
-    query: <Path extends ProtocolPaths<D> & string>(path: Path, request?: TypedQueryRequest) => Promise<TypedQueryResponse>;
-    read: <Path extends ProtocolPaths<D> & string>(path: Path, request: TypedReadRequest) => Promise<TypedReadResponse>;
-    delete: <Path extends ProtocolPaths<D> & string>(path: Path, request: TypedDeleteRequest) => Promise<DwnResponseStatus>;
-    subscribe: <Path extends ProtocolPaths<D> & string>(path: Path, request?: TypedSubscribeRequest) => Promise<TypedSubscribeResponse>;
+    create: <Path extends ProtocolPaths<D> & string>(
+      path: Path,
+      request: TypedCreateRequest<D, M, Path>,
+    ) => Promise<TypedCreateResponse<DataForPath<D, M, Path>>>;
+
+    query: <Path extends ProtocolPaths<D> & string>(
+      path: Path,
+      request?: TypedQueryRequest,
+    ) => Promise<TypedQueryResponse<DataForPath<D, M, Path>>>;
+
+    read: <Path extends ProtocolPaths<D> & string>(
+      path: Path,
+      request: TypedReadRequest,
+    ) => Promise<TypedReadResponse<DataForPath<D, M, Path>>>;
+
+    delete: <Path extends ProtocolPaths<D> & string>(
+      path: Path,
+      request: TypedDeleteRequest,
+    ) => Promise<DwnResponseStatus>;
+
+    subscribe: <Path extends ProtocolPaths<D> & string>(
+      path: Path,
+      request?: TypedSubscribeRequest,
+    ) => Promise<TypedSubscribeResponse<DataForPath<D, M, Path>>>;
     } {
-    return {
+    if (this._records !== undefined) {
+      return this._records;
+    }
+
+    const cached = {
       /**
-       * Write a record at the given protocol path.
+       * Create a new record at the given protocol path.
        *
        * @param path - The protocol path (e.g. `'friend'`, `'group/member'`).
-       * @param request - Write options including typed `data`.
+       * @param request - Create options including typed `data`.
        */
-      write: async <Path extends ProtocolPaths<D> & string>(
+      create: async <Path extends ProtocolPaths<D> & string>(
         path: Path,
-        request: TypedWriteRequest<D, M, Path>,
-      ): Promise<TypedWriteResponse> => {
-        const typeName = lastSegment(path);
+        request: TypedCreateRequest<D, M, Path>,
+      ): Promise<TypedCreateResponse<DataForPath<D, M, Path>>> => {
+        const normalizedPath = normalizePath(path);
+        this._assertReady(normalizedPath);
+        const typeName = lastSegment(normalizedPath);
         const typeEntry = this._definition.types[typeName] as ProtocolType | undefined;
 
-        return this._dwn.records.write({
+        const { status, record } = await this._dwn.records.write({
           data            : request.data,
           store           : request.store,
           encryption      : request.encryption,
@@ -294,10 +377,15 @@ export class TypedWeb5<
           protocolRole    : request.protocolRole,
           tags            : request.tags,
           protocol        : this._definition.protocol,
-          protocolPath    : path,
+          protocolPath    : normalizedPath,
           ...(typeEntry?.schema !== undefined ? { schema: typeEntry.schema } : {}),
           dataFormat      : request.dataFormat ?? typeEntry?.dataFormats?.[0],
         });
+
+        return {
+          status,
+          record: new TypedRecord<DataForPath<D, M, Path>>(record),
+        };
       },
 
       /**
@@ -309,23 +397,31 @@ export class TypedWeb5<
       query: async <Path extends ProtocolPaths<D> & string>(
         path: Path,
         request?: TypedQueryRequest,
-      ): Promise<TypedQueryResponse> => {
-        const typeName = lastSegment(path);
+      ): Promise<TypedQueryResponse<DataForPath<D, M, Path>>> => {
+        const normalizedPath = normalizePath(path);
+        this._assertReady(normalizedPath);
+        const typeName = lastSegment(normalizedPath);
         const typeEntry = this._definition.types[typeName] as ProtocolType | undefined;
 
-        return this._dwn.records.query({
+        const { status, records, cursor } = await this._dwn.records.query({
           from       : request?.from,
           encryption : request?.encryption,
           filter     : {
             ...request?.filter,
             protocol     : this._definition.protocol,
-            protocolPath : path,
+            protocolPath : normalizedPath,
             ...(typeEntry?.schema !== undefined ? { schema: typeEntry.schema } : {}),
           },
           dateSort     : request?.dateSort,
           pagination   : request?.pagination,
           protocolRole : request?.protocolRole,
         });
+
+        return {
+          status,
+          records: records.map((r) => new TypedRecord<DataForPath<D, M, Path>>(r)),
+          cursor,
+        };
       },
 
       /**
@@ -337,21 +433,28 @@ export class TypedWeb5<
       read: async <Path extends ProtocolPaths<D> & string>(
         path: Path,
         request: TypedReadRequest,
-      ): Promise<TypedReadResponse> => {
-        const typeName = lastSegment(path);
+      ): Promise<TypedReadResponse<DataForPath<D, M, Path>>> => {
+        const normalizedPath = normalizePath(path);
+        this._assertReady(normalizedPath);
+        const typeName = lastSegment(normalizedPath);
         const typeEntry = this._definition.types[typeName] as ProtocolType | undefined;
 
-        return this._dwn.records.read({
+        const { status, record } = await this._dwn.records.read({
           from       : request.from,
           encryption : request.encryption,
           protocol   : this._definition.protocol,
           filter     : {
             ...request.filter,
             protocol     : this._definition.protocol,
-            protocolPath : path,
+            protocolPath : normalizedPath,
             ...(typeEntry?.schema !== undefined ? { schema: typeEntry.schema } : {}),
           },
         });
+
+        return {
+          status,
+          record: new TypedRecord<DataForPath<D, M, Path>>(record),
+        };
       },
 
       /**
@@ -364,6 +467,7 @@ export class TypedWeb5<
         _path: Path,
         request: TypedDeleteRequest,
       ): Promise<DwnResponseStatus> => {
+        this._assertReady(normalizePath(_path));
         return this._dwn.records.delete({
           from     : request.from,
           protocol : this._definition.protocol,
@@ -374,8 +478,9 @@ export class TypedWeb5<
       /**
        * Subscribe to records at the given protocol path.
        *
-       * Returns a {@link LiveQuery} that atomically provides an initial snapshot
-       * and a real-time stream of deduplicated change events.
+       * Returns a {@link TypedLiveQuery} that atomically provides an initial
+       * snapshot and a real-time stream of deduplicated change events, with
+       * all records typed as `TypedRecord<T>`.
        *
        * @param path - The protocol path to subscribe to.
        * @param request - Optional filter and role.
@@ -383,22 +488,32 @@ export class TypedWeb5<
       subscribe: async <Path extends ProtocolPaths<D> & string>(
         path: Path,
         request?: TypedSubscribeRequest,
-      ): Promise<TypedSubscribeResponse> => {
-        const typeName = lastSegment(path);
+      ): Promise<TypedSubscribeResponse<DataForPath<D, M, Path>>> => {
+        const normalizedPath = normalizePath(path);
+        this._assertReady(normalizedPath);
+        const typeName = lastSegment(normalizedPath);
         const typeEntry = this._definition.types[typeName] as ProtocolType | undefined;
 
-        return this._dwn.records.subscribe({
+        const { status, liveQuery } = await this._dwn.records.subscribe({
           from   : request?.from,
           filter : {
             ...request?.filter,
             protocol     : this._definition.protocol,
-            protocolPath : path,
+            protocolPath : normalizedPath,
             ...(typeEntry?.schema !== undefined ? { schema: typeEntry.schema } : {}),
           },
           protocolRole: request?.protocolRole,
         });
+
+        return {
+          status,
+          liveQuery: liveQuery ? new TypedLiveQuery<DataForPath<D, M, Path>>(liveQuery) : undefined,
+        };
       },
     };
+
+    this._records = cached;
+    return cached;
   }
 }
 
@@ -417,6 +532,15 @@ function definitionsEqual(a: unknown, b: unknown): boolean {
   return stableStringify(a) === stableStringify(b);
 }
 
+/**
+ * Strips leading and trailing slashes from a path.
+ *
+ * `'friend/'` → `'friend'`, `'/group/member/'` → `'group/member'`.
+ */
+function normalizePath(path: string): string {
+  return path.replace(/^\/+|\/+$/g, '');
+}
+
 /**
  * Returns the last segment of a slash-delimited path.
  */
@@ -425,6 +549,35 @@ function lastSegment(path: string): string {
   return parts[parts.length - 1];
 }
 
+/**
+ * Recursively collects all valid protocol path strings from a structure object.
+ *
+ * Given `{ foo: { bar: { $actions: [...] } } }`, returns `Set(['foo', 'foo/bar'])`.
+ * Keys starting with `$` are skipped.
+ */
+function collectPaths(
+  structure: Record<string, unknown>,
+  prefix: string = '',
+): Set<string> {
+  const paths = new Set<string>();
+
+  for (const key of Object.keys(structure)) {
+    if (key.startsWith('$')) { continue; }
+
+    const fullPath = prefix ? `${prefix}/${key}` : key;
+    paths.add(fullPath);
+
+    const child = structure[key];
+    if (child !== null && typeof child === 'object') {
+      for (const nested of collectPaths(child as Record<string, unknown>, fullPath)) {
+        paths.add(nested);
+      }
+    }
+  }
+
+  return paths;
+}
+
 /**
  * Deterministic JSON serialization with sorted keys.
  */