@enbox/api 0.2.3 → 0.3.0

package/src/repository-types.ts

@@ -0,0 +1,249 @@
+/**
+ * Type-level machinery for the protocol repository pattern.
+ *
+ * These types produce a statically-typed CRUD API shape from a
+ * `ProtocolDefinition` + `SchemaMap`, with singleton detection
+ * (via `$recordLimit: { max: 1 }`) and nested-path awareness.
+ *
+ * All types are purely compile-time — they produce no runtime code.
+ *
+ * @module
+ */
+
+import type { SchemaMap } from './protocol-types.js';
+import type { TypedLiveQuery } from './typed-live-query.js';
+import type { TypedRecord } from './typed-record.js';
+import type {
+  DataForPath,
+  TypedCreateRequest,
+  TypedQueryRequest,
+  TypedSubscribeRequest,
+} from './typed-web5.js';
+import type { DwnPaginationCursor, DwnResponseStatus } from '@enbox/agent';
+import type { ProtocolDefinition, ProtocolRuleSet } from '@enbox/dwn-sdk-js';
+
+// ---------------------------------------------------------------------------
+// Structure navigation
+// ---------------------------------------------------------------------------
+
+/**
+ * Navigates a `ProtocolRuleSet` tree to the node at a slash-delimited path.
+ */
+type RuleSetAtPath<R, Path extends string> =
+  Path extends `${infer Head}/${infer Tail}`
+    ? Head extends keyof R
+      ? R[Head] extends ProtocolRuleSet
+        ? RuleSetAtPath<R[Head], Tail>
+        : never
+      : never
+    : Path extends keyof R
+      ? R[Path] extends ProtocolRuleSet
+        ? R[Path]
+        : never
+      : never;
+
+// ---------------------------------------------------------------------------
+// Singleton detection
+// ---------------------------------------------------------------------------
+
+/**
+ * Extracts the `$recordLimit` from a rule set node, if present.
+ */
+type RecordLimitAtRuleSet<RS> =
+  RS extends { $recordLimit: infer L } ? L : never;
+
+/**
+ * `true` when the rule set at `Path` has `$recordLimit: { max: 1 }`.
+ */
+export type IsSingleton<D extends ProtocolDefinition, Path extends string> =
+  RecordLimitAtRuleSet<RuleSetAtPath<D['structure'], Path>> extends { max: 1 }
+    ? true
+    : false;
+
+// ---------------------------------------------------------------------------
+// Data type resolution
+// ---------------------------------------------------------------------------
+
+/** Resolves the TypeScript data type for a given path. */
+type DataAt<
+  D extends ProtocolDefinition,
+  M extends SchemaMap,
+  Path extends string,
+> = DataForPath<D, M, Path>;
+
+// ---------------------------------------------------------------------------
+// Common option types
+// ---------------------------------------------------------------------------
+
+/**
+ * Write options for a collection `create()` call.
+ * Omits `data` (passed separately) and protocol-injected fields.
+ */
+export type CollectionCreateOptions<
+  D extends ProtocolDefinition,
+  M extends SchemaMap,
+  Path extends string,
+> = Omit<TypedCreateRequest<D, M, Path>, 'data' | 'parentContextId'> & {
+  data: DataAt<D, M, Path>;
+};
+
+/**
+ * Write options for a singleton `set()` call.
+ */
+export type SingletonSetOptions<
+  D extends ProtocolDefinition,
+  M extends SchemaMap,
+  Path extends string,
+> = Omit<TypedCreateRequest<D, M, Path>, 'data' | 'parentContextId'> & {
+  data: DataAt<D, M, Path>;
+};
+
+// ---------------------------------------------------------------------------
+// CRUD shapes
+// ---------------------------------------------------------------------------
+
+/** CRUD API for a root-level collection (unbounded or max > 1). */
+export type CollectionCRUD<
+  D extends ProtocolDefinition,
+  M extends SchemaMap,
+  Path extends string,
+> = {
+  create(options: CollectionCreateOptions<D, M, Path>): Promise<DwnResponseStatus & { record: TypedRecord<DataAt<D, M, Path>> }>;
+  query(options?: TypedQueryRequest): Promise<DwnResponseStatus & { records: TypedRecord<DataAt<D, M, Path>>[]; cursor?: DwnPaginationCursor }>;
+  get(recordId: string): Promise<TypedRecord<DataAt<D, M, Path>>>;
+  delete(recordId: string): Promise<DwnResponseStatus>;
+  subscribe(options?: TypedSubscribeRequest): Promise<TypedLiveQuery<DataAt<D, M, Path>> | undefined>;
+};
+
+/** CRUD API for a root-level singleton ($recordLimit max: 1). */
+export type SingletonCRUD<
+  D extends ProtocolDefinition,
+  M extends SchemaMap,
+  Path extends string,
+> = {
+  set(options: SingletonSetOptions<D, M, Path>): Promise<DwnResponseStatus & { record: TypedRecord<DataAt<D, M, Path>> }>;
+  get(): Promise<TypedRecord<DataAt<D, M, Path>> | undefined>;
+  delete(recordId: string): Promise<DwnResponseStatus>;
+};
+
+/** CRUD API for a nested collection (parent context required). */
+export type NestedCollectionCRUD<
+  D extends ProtocolDefinition,
+  M extends SchemaMap,
+  Path extends string,
+> = {
+  create(
+    parentContextId: string,
+    options: CollectionCreateOptions<D, M, Path>,
+  ): Promise<DwnResponseStatus & { record: TypedRecord<DataAt<D, M, Path>> }>;
+  query(
+    parentContextId: string,
+    options?: TypedQueryRequest,
+  ): Promise<DwnResponseStatus & { records: TypedRecord<DataAt<D, M, Path>>[]; cursor?: DwnPaginationCursor }>;
+  get(recordId: string): Promise<TypedRecord<DataAt<D, M, Path>>>;
+  delete(recordId: string): Promise<DwnResponseStatus>;
+  subscribe(
+    parentContextId: string,
+    options?: TypedSubscribeRequest,
+  ): Promise<TypedLiveQuery<DataAt<D, M, Path>> | undefined>;
+};
+
+/** CRUD API for a nested singleton ($recordLimit max: 1). */
+export type NestedSingletonCRUD<
+  D extends ProtocolDefinition,
+  M extends SchemaMap,
+  Path extends string,
+> = {
+  set(
+    parentContextId: string,
+    options: SingletonSetOptions<D, M, Path>,
+  ): Promise<DwnResponseStatus & { record: TypedRecord<DataAt<D, M, Path>> }>;
+  get(parentContextId: string): Promise<TypedRecord<DataAt<D, M, Path>> | undefined>;
+  delete(recordId: string): Promise<DwnResponseStatus>;
+};
+
+// ---------------------------------------------------------------------------
+// Recursive repository node
+// ---------------------------------------------------------------------------
+
+/**
+ * Extracts the child type names (non-`$`-prefixed keys that extend ProtocolRuleSet)
+ * from a rule set node.
+ */
+type ChildKeys<RS> = {
+  [K in Extract<keyof RS, string>]: K extends `$${string}`
+    ? never
+    : RS[K] extends ProtocolRuleSet
+      ? K
+      : never;
+}[Extract<keyof RS, string>];
+
+/**
+ * Builds nested repository nodes for all children of a given rule set.
+ */
+type ChildNodes<
+  D extends ProtocolDefinition,
+  M extends SchemaMap,
+  RS,
+  ParentPath extends string,
+> = {
+  [K in ChildKeys<RS>]: RepositoryNode<D, M, RS[K], `${ParentPath}/${K}`, true>;
+};
+
+/**
+ * A single node in the repository tree. Provides CRUD methods appropriate
+ * to whether the path is root/nested and singleton/collection, plus child
+ * nodes for further nesting.
+ */
+export type RepositoryNode<
+  D extends ProtocolDefinition,
+  M extends SchemaMap,
+  RS,
+  Path extends string,
+  IsNested extends boolean = false,
+> =
+  // Choose CRUD shape based on singleton + nested status
+  (IsNested extends true
+    ? (IsSingleton<D, Path> extends true
+      ? NestedSingletonCRUD<D, M, Path>
+      : NestedCollectionCRUD<D, M, Path>)
+    : (IsSingleton<D, Path> extends true
+      ? SingletonCRUD<D, M, Path>
+      : CollectionCRUD<D, M, Path>))
+  // Plus child nodes for deeper nesting
+  & ChildNodes<D, M, RS, Path>;
+
+// ---------------------------------------------------------------------------
+// Top-level repository type
+// ---------------------------------------------------------------------------
+
+/**
+ * The top-level repository type for a protocol definition.
+ *
+ * Maps each root-level type name in the protocol's `structure` to a
+ * `RepositoryNode` with the appropriate CRUD methods and nested children.
+ *
+ * @example
+ * ```ts
+ * const social: Repository<typeof SocialGraphDef, SocialGraphSchemaMap>;
+ *
+ * // Root collection
+ * await social.friend.create({ data: { did: '...' } });
+ * await social.friend.query();
+ *
+ * // Nested under group
+ * await social.group.member.create(groupCtxId, { data: { did: '...' } });
+ * ```
+ */
+export type Repository<
+  D extends ProtocolDefinition,
+  M extends SchemaMap,
+> = {
+  [K in Extract<keyof D['structure'], string> as K extends `$${string}` ? never : K]:
+    D['structure'][K] extends ProtocolRuleSet
+      ? RepositoryNode<D, M, D['structure'][K], K>
+      : never;
+} & {
+  /** Install (configure) the protocol. Idempotent — no-op if already installed. */
+  configure(options?: { encryption?: boolean }): Promise<DwnResponseStatus>;
+};

package/src/repository.ts

@@ -0,0 +1,391 @@
+/**
+ * Protocol-aware repository factory.
+ *
+ * `repository()` takes a `TypedWeb5` instance and returns a Proxy-backed
+ * object whose shape mirrors the protocol's `structure` tree with
+ * ergonomic CRUD methods on each node.
+ *
+ * - **Collections** (default): `create`, `query`, `get`, `delete`, `subscribe`
+ * - **Singletons** (`$recordLimit: { max: 1 }`): `set`, `get`, `delete`
+ * - **Nested types**: first argument is `parentContextId`
+ * - **`configure()`**: idempotent protocol installation
+ *
+ * @example
+ * ```ts
+ * const social = repository(web5.using(SocialGraphProtocol));
+ * await social.configure();
+ *
+ * // Root collection
+ * const { record } = await social.friend.create({
+ *   data: { did: 'did:example:alice' },
+ * });
+ *
+ * // Nested under group
+ * const members = await social.group.member.query(groupContextId);
+ * ```
+ *
+ * @module
+ */
+
+import type { DwnResponseStatus } from '@enbox/agent';
+import type { Repository } from './repository-types.js';
+import type { SchemaMap } from './protocol-types.js';
+import type { TypedWeb5 } from './typed-web5.js';
+import type { ProtocolDefinition, ProtocolRuleSet } from '@enbox/dwn-sdk-js';
+
+// ---------------------------------------------------------------------------
+// Runtime helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Checks whether a DWN response status indicates that the record limit
+ * has been exceeded. The DWN engine returns a 400 status with a detail
+ * message containing "record limit" when `$recordLimit` rejects a write.
+ */
+function isRecordLimitExceeded(status: { code: number; detail: string }): boolean {
+  return status.code === 400 && status.detail.includes('record limit');
+}
+
+/**
+ * Checks whether a protocol rule set at a given path is a singleton
+ * (has `$recordLimit: { max: 1 }`).
+ */
+function isSingletonPath(definition: ProtocolDefinition, path: string): boolean {
+  const segments = path.split('/');
+  let node: ProtocolRuleSet | undefined = definition.structure as unknown as ProtocolRuleSet;
+
+  for (const seg of segments) {
+    if (!node || typeof node !== 'object') { return false; }
+    node = (node as Record<string, ProtocolRuleSet>)[seg];
+  }
+
+  if (!node || typeof node !== 'object') { return false; }
+  const limit = (node as Record<string, unknown>)['$recordLimit'];
+  return limit !== undefined
+    && typeof limit === 'object'
+    && limit !== null
+    && (limit as Record<string, unknown>)['max'] === 1;
+}
+
+/**
+ * Returns the child type keys (non-`$`-prefixed) of a rule set node
+ * reached by the given path.
+ */
+function getChildKeys(definition: ProtocolDefinition, path: string): string[] {
+  const segments = path.split('/');
+  let node: Record<string, unknown> = definition.structure as unknown as Record<string, unknown>;
+
+  for (const seg of segments) {
+    if (!node || typeof node !== 'object') { return []; }
+    node = node[seg] as Record<string, unknown>;
+  }
+
+  if (!node || typeof node !== 'object') { return []; }
+  return Object.keys(node).filter((k) => !k.startsWith('$'));
+}
+
+// ---------------------------------------------------------------------------
+// CRUD method builders
+// ---------------------------------------------------------------------------
+
+/**
+ * Build collection CRUD methods for a root-level path.
+ */
+function buildRootCollectionMethods(
+  typed: TypedWeb5<ProtocolDefinition, SchemaMap>,
+  path: string,
+): Record<string, Function> {
+  return {
+    async create(options: Record<string, unknown>): Promise<unknown> {
+      const { status, record } = await typed.records.create(path, options as never);
+      return { status, record };
+    },
+
+    async query(options?: Record<string, unknown>): Promise<unknown> {
+      const { status, records, cursor } = await typed.records.query(path, options as never);
+      return { status, records, cursor };
+    },
+
+    async get(recordId: string): Promise<unknown> {
+      const { record } = await typed.records.read(path, {
+        filter: { recordId },
+      });
+      return record;
+    },
+
+    async delete(recordId: string): Promise<DwnResponseStatus> {
+      return typed.records.delete(path, { recordId });
+    },
+
+    async subscribe(options?: Record<string, unknown>): Promise<unknown> {
+      const { liveQuery } = await typed.records.subscribe(path, options as never);
+      return liveQuery;
+    },
+  };
+}
+
+/**
+ * Build singleton CRUD methods for a root-level path.
+ *
+ * Uses a create-first strategy: attempts to create a new record, and if the
+ * DWN rejects it because the record limit is reached, falls back to querying
+ * the existing record and updating it. This avoids the race condition inherent
+ * in query-then-create/update.
+ */
+function buildRootSingletonMethods(
+  typed: TypedWeb5<ProtocolDefinition, SchemaMap>,
+  path: string,
+): Record<string, Function> {
+  return {
+    async set(options: Record<string, unknown>): Promise<unknown> {
+      // Attempt to create — if limit not yet reached, this succeeds.
+      const createResult = await typed.records.create(path, options as never);
+
+      if (isRecordLimitExceeded(createResult.status)) {
+        // Record limit hit — query existing and update.
+        const { records } = await typed.records.query(path);
+        if (records.length > 0) {
+          const { status, record } = await records[0].update({
+            data: options.data,
+            ...(options.tags !== undefined ? { tags: options.tags } : {}),
+          } as never);
+          return { status, record };
+        }
+      }
+
+      return { status: createResult.status, record: createResult.record };
+    },
+
+    async get(): Promise<unknown> {
+      const { records } = await typed.records.query(path);
+      return records.length > 0 ? records[0] : undefined;
+    },
+
+    async delete(recordId: string): Promise<DwnResponseStatus> {
+      return typed.records.delete(path, { recordId });
+    },
+  };
+}
+
+/**
+ * Build collection CRUD methods for a nested path.
+ */
+function buildNestedCollectionMethods(
+  typed: TypedWeb5<ProtocolDefinition, SchemaMap>,
+  path: string,
+): Record<string, Function> {
+  return {
+    async create(parentContextId: string, options: Record<string, unknown>): Promise<unknown> {
+      const { status, record } = await typed.records.create(path, {
+        ...options,
+        parentContextId,
+      } as never);
+      return { status, record };
+    },
+
+    async query(parentContextId: string, options?: Record<string, unknown>): Promise<unknown> {
+      const { status, records, cursor } = await typed.records.query(path, {
+        ...options,
+        filter: {
+          ...(options as Record<string, Record<string, unknown>>)?.filter,
+          contextId: parentContextId,
+        },
+      } as never);
+      return { status, records, cursor };
+    },
+
+    async get(recordId: string): Promise<unknown> {
+      const { record } = await typed.records.read(path, {
+        filter: { recordId },
+      });
+      return record;
+    },
+
+    async delete(recordId: string): Promise<DwnResponseStatus> {
+      return typed.records.delete(path, { recordId });
+    },
+
+    async subscribe(parentContextId: string, options?: Record<string, unknown>): Promise<unknown> {
+      const { liveQuery } = await typed.records.subscribe(path, {
+        ...options,
+        filter: {
+          ...(options as Record<string, Record<string, unknown>>)?.filter,
+          contextId: parentContextId,
+        },
+      } as never);
+      return liveQuery;
+    },
+  };
+}
+
+/**
+ * Build singleton CRUD methods for a nested path.
+ *
+ * Uses the same create-first strategy as root singletons to avoid race
+ * conditions between concurrent set() calls.
+ */
+function buildNestedSingletonMethods(
+  typed: TypedWeb5<ProtocolDefinition, SchemaMap>,
+  path: string,
+): Record<string, Function> {
+  return {
+    async set(parentContextId: string, options: Record<string, unknown>): Promise<unknown> {
+      // Attempt to create under this parent — succeeds if no record exists yet.
+      const createResult = await typed.records.create(path, {
+        ...options,
+        parentContextId,
+      } as never);
+
+      if (isRecordLimitExceeded(createResult.status)) {
+        // Record limit hit — query existing under this parent and update.
+        const { records } = await typed.records.query(path, {
+          filter: { contextId: parentContextId },
+        } as never);
+
+        if (records.length > 0) {
+          const { status, record } = await records[0].update({
+            data: options.data,
+            ...(options.tags !== undefined ? { tags: options.tags } : {}),
+          } as never);
+          return { status, record };
+        }
+      }
+
+      return { status: createResult.status, record: createResult.record };
+    },
+
+    async get(parentContextId: string): Promise<unknown> {
+      const { records } = await typed.records.query(path, {
+        filter: { contextId: parentContextId },
+      } as never);
+      return records.length > 0 ? records[0] : undefined;
+    },
+
+    async delete(recordId: string): Promise<DwnResponseStatus> {
+      return typed.records.delete(path, { recordId });
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Node builder
+// ---------------------------------------------------------------------------
+
+/**
+ * Build a repository node for a given path, including CRUD methods
+ * and Proxy-based child nodes.
+ */
+function buildNode(
+  typed: TypedWeb5<ProtocolDefinition, SchemaMap>,
+  definition: ProtocolDefinition,
+  path: string,
+  isNested: boolean,
+): Record<string, unknown> {
+  const singleton = isSingletonPath(definition, path);
+
+  // Build CRUD methods based on root/nested and singleton/collection
+  let methods: Record<string, Function>;
+  if (isNested) {
+    methods = singleton
+      ? buildNestedSingletonMethods(typed, path)
+      : buildNestedCollectionMethods(typed, path);
+  } else {
+    methods = singleton
+      ? buildRootSingletonMethods(typed, path)
+      : buildRootCollectionMethods(typed, path);
+  }
+
+  // Use a Proxy to lazily build child nodes
+  const childKeys = getChildKeys(definition, path);
+  const childCache: Record<string, unknown> = {};
+
+  return new Proxy(methods, {
+    get(target: Record<string, unknown>, prop: string | symbol): unknown {
+      if (typeof prop !== 'string') { return undefined; }
+
+      // CRUD methods take priority
+      if (prop in target) { return target[prop]; }
+
+      // Lazily build child nodes
+      if (childKeys.includes(prop)) {
+        if (!(prop in childCache)) {
+          childCache[prop] = buildNode(typed, definition, `${path}/${prop}`, true);
+        }
+        return childCache[prop];
+      }
+
+      return undefined;
+    },
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Creates a protocol-aware repository from a `TypedWeb5` instance.
+ *
+ * The returned object provides domain-specific CRUD methods that mirror
+ * the protocol's structure tree:
+ *
+ * - Root types: `repo.friend.create()`, `repo.friend.query()`
+ * - Nested types: `repo.group.member.create(groupCtxId, { data })`
+ * - Singletons: `repo.profile.set()`, `repo.profile.get()`
+ * - Protocol install: `repo.configure()`
+ *
+ * @param typed - A `TypedWeb5` instance from `web5.using(protocol)`.
+ * @returns A typed repository object.
+ *
+ * @example
+ * ```ts
+ * const social = repository(web5.using(SocialGraphProtocol));
+ * await social.configure();
+ *
+ * const rec = await social.friend.create({
+ *   data: { did: 'did:example:alice' },
+ * });
+ * const friends = await social.friend.query();
+ * ```
+ */
+export function repository<
+  D extends ProtocolDefinition,
+  M extends SchemaMap,
+>(typed: TypedWeb5<D, M>): Repository<D, M> {
+  const definition = typed.definition as ProtocolDefinition;
+
+  // Get root-level type keys from the structure
+  const rootKeys = Object.keys(definition.structure).filter((k) => !k.startsWith('$'));
+  const nodeCache: Record<string, unknown> = {};
+
+  const proxy = new Proxy({} as Record<string, unknown>, {
+    get(_target: Record<string, unknown>, prop: string | symbol): unknown {
+      if (typeof prop !== 'string') { return undefined; }
+
+      // configure() method
+      if (prop === 'configure') {
+        return async (options?: { encryption?: boolean }): Promise<DwnResponseStatus> => {
+          const result = await typed.configure(options);
+          return result;
+        };
+      }
+
+      // Root-level type nodes
+      if (rootKeys.includes(prop)) {
+        if (!(prop in nodeCache)) {
+          nodeCache[prop] = buildNode(
+            typed as unknown as TypedWeb5<ProtocolDefinition, SchemaMap>,
+            definition,
+            prop,
+            false,
+          );
+        }
+        return nodeCache[prop];
+      }
+
+      return undefined;
+    },
+  });
+
+  return proxy as unknown as Repository<D, M>;
+}