Polish backfill public API docs

Replace the package README's VitePress-only installation block with
plain Markdown, document the new public API surface with since tags,
and mark exported option and result properties as readonly.

Export the request-budget error class so callers can identify it when
it escapes traversal internals.

Assisted-by: Codex:gpt-5

Author: sij411

packages/backfill/README.md

@@ -27,30 +27,14 @@ or `OrderedCollectionPage`.
 Installation
 ------------
 
-::: code-group
-
-~~~~ sh [Deno]
+~~~~ sh
 deno add jsr:@fedify/backfill
+npm  add     @fedify/backfill
+pnpm add     @fedify/backfill
+yarn add     @fedify/backfill
+bun  add     @fedify/backfill
 ~~~~
 
-~~~~ sh [npm]
-npm add @fedify/backfill
-~~~~
-
-~~~~ sh [pnpm]
-pnpm add @fedify/backfill
-~~~~
-
-~~~~ sh [Yarn]
-yarn add @fedify/backfill
-~~~~
-
-~~~~ sh [Bun]
-bun add @fedify/backfill
-~~~~
-
-:::
-
 
 Usage
 -----

packages/backfill/src/backfill.test.ts

@@ -1,6 +1,6 @@
 import { deepStrictEqual, ok, rejects, strictEqual } from "node:assert/strict";
 import test, { describe } from "node:test";
-import { backfill, type BackfillContext } from "./mod.ts";
+import { backfill, type BackfillContext, MaxRequestsExceeded } from "./mod.ts";
 import { Collection, Create, Note } from "@fedify/vocab";
 
 async function collect(
@@ -14,6 +14,7 @@ async function collect(
 describe("backfill", () => {
   test("package exports backfill", () => {
     strictEqual(typeof backfill, "function");
+    strictEqual(typeof MaxRequestsExceeded, "function");
   });
 
   test("context missing yields nothing", async () => {

packages/backfill/src/backfill.ts

@@ -14,7 +14,12 @@ import type {
   BackfillOptions,
 } from "./types.ts";
 
-class MaxRequestsExceeded extends Error {}
+/**
+ * Thrown when backfill traversal exceeds the configured request budget.
+ *
+ * @since 2.3.0
+ */
+export class MaxRequestsExceeded extends Error {}
 
 interface RequestBudget {
   readonly signal?: AbortSignal;
@@ -26,6 +31,8 @@ interface RequestBudget {
  *
  * The seed object is not yielded by default, but its ID is treated as already
  * seen so it will not be yielded again if the collection contains it.
+ *
+ * @since 2.3.0
  */
 export async function* backfill<
   TObject extends APObject = APObject,

packages/backfill/src/mod.ts

@@ -6,7 +6,7 @@
  *
  * @module
  */
-export { backfill } from "./backfill.ts";
+export { backfill, MaxRequestsExceeded } from "./backfill.ts";
 export type {
   BackfillContext,
   BackfillDocumentLoader,

packages/backfill/src/types.ts

@@ -2,26 +2,34 @@ import type { Object as APObject } from "@fedify/vocab";
 
 /**
  * Backfill traversal strategy used to discover the returned object.
+ *
+ * @since 2.3.0
  */
 export type BackfillStrategy = "context-posts";
 
 /**
  * Source relation that produced a backfilled object.
+ *
+ * @since 2.3.0
  */
 export type BackfillOrigin = "context" | "collection";
 
 /**
  * Options passed to {@link BackfillDocumentLoader}.
+ *
+ * @since 2.3.0
  */
 export interface BackfillDocumentLoaderOptions {
   /**
    * Cancellation signal for the current dereference operation.
    */
-  signal?: AbortSignal;
+  readonly signal?: AbortSignal;
 }
 
 /**
  * Dereferences an ActivityPub object or collection IRI.
+ *
+ * @since 2.3.0
  */
 export type BackfillDocumentLoader = (
   iri: URL,
@@ -30,83 +38,89 @@ export type BackfillDocumentLoader = (
 
 /**
  * Dependencies used by backfill traversal.
+ *
+ * @since 2.3.0
  */
 export interface BackfillContext {
   /**
    * Dereferences context collections and collection item IRIs.
    */
-  documentLoader: BackfillDocumentLoader;
+  readonly documentLoader: BackfillDocumentLoader;
 }
 
 /**
  * Controls direct context collection backfill traversal.
+ *
+ * @since 2.3.0
  */
 export interface BackfillOptions<
   TObject extends APObject = APObject,
 > {
   /**
    * Maximum number of items to yield.  Skipped duplicates do not count.
    */
-  maxItems?: number;
+  readonly maxItems?: number;
 
   /**
    * Maximum traversal depth.  This is reserved for future reply-tree traversal;
    */
-  maxDepth?: number;
+  readonly maxDepth?: number;
 
   /**
    * Maximum number of calls to {@link BackfillContext.documentLoader}.
    *
    * Dereferencing the note context, collection item IRIs, and future page IRIs
    * all count as requests.  Embedded collection items do not count.
    */
-  maxRequests?: number;
+  readonly maxRequests?: number;
 
   /**
    * Delay between `documentLoader` requests.
    *
    * When a callback is provided, `iteration` is the zero-based request index.
    */
-  interval?:
+  readonly interval?:
     | Temporal.DurationLike
     | string
     | ((iteration: number) => Temporal.DurationLike | string);
 
   /**
    * Cancels traversal before requests and before yields.
    */
-  signal?: AbortSignal;
+  readonly signal?: AbortSignal;
 }
 
 /**
  * A single object discovered by backfill traversal.
+ *
+ * @since 2.3.0
  */
 export interface BackfillItem<
   TObject extends APObject = APObject,
 > {
   /**
    * The discovered ActivityPub object.
    */
-  object: TObject;
+  readonly object: TObject;
 
   /**
    * The object's ActivityPub ID, when present.
    */
-  id?: URL;
+  readonly id?: URL;
 
   /**
    * The traversal strategy that produced this item.
    */
-  strategy: BackfillStrategy;
+  readonly strategy: BackfillStrategy;
 
   /**
    * The source relation that produced this item.
    */
-  origin: BackfillOrigin;
+  readonly origin: BackfillOrigin;
 
   /**
    * Traversal depth.  Direct context collection items are depth 0; deeper
    * values are reserved for future reply-tree traversal.
    */
-  depth?: number;
+  readonly depth?: number;
 }