chore: document public api

Author: zebp

package.json

@@ -15,6 +15,7 @@
   },
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
+    "build:watch": "tsc -p tsconfig.build.json -w",
     "format": "biome format ./src ./test --write",
     "check:lint": "biome lint ./src ./test",
     "check:format": "biome format ./src ./test",

src/decorator.ts

@@ -16,15 +16,76 @@ type DiffableArgs =
   | [_: any, { kind: string; name: string }];
 
 type DiffableOpts = {
+  /**
+   * The name of the state, typically the name of the field.
+   */
   name?: string;
+  /**
+   * Diffable-objects will automatically snapshot the state perodically based on this policy to minimize
+   * the number of diffs that must be applied to restore the state when the Durable Object is restarted.
+   */
   snapshotPolicy?: SnapshotPolicy;
 };
 
+/**
+ * Dynamically create a state object that persists changes to durable storage using Proxy and SQLite.
+ * 
+ * ```
+ * import { DurableObject } from "cloudflare:workers";
+ * import { diffable } from "diffable-objects";
+ * 
+ * class Counter extends DurableObject {
+ *   @diffable
+ *   #state = { count: 0 };
+ * 
+ *   async fetch(request) {
+ *     this.#state.count += 1;
+ *     return new Response(`Count: ${this.#state.count}`);
+ *   }
+ * }
+ * ```
+ */
 export function diffable(
   _: any,
   { kind, name }: { kind: string; name: string },
 ): FieldDecoratorReturn<any>;
+/**
+ * Dynamically create a state object that persists changes to durable storage using Proxy and SQLite.
+ * 
+ * ```
+ * import { DurableObject } from "cloudflare:workers";
+ * import { diffable } from "diffable-objects";
+ * 
+ * class Counter extends DurableObject {
+ *   @diffable("counter")
+ *   #state = { count: 0 };
+ * 
+ *   async fetch(request) {
+ *     this.#state.count += 1;
+ *     return new Response(`Count: ${this.#state.count}`);
+ *   }
+ * }
+ * ```
+ */
 export function diffable(name?: string): FieldDecoratorFactoryReturn<any>;
+/**
+ * Dynamically create a state object that persists changes to durable storage using Proxy and SQLite.
+ * 
+ * ```
+ * import { DurableObject } from "cloudflare:workers";
+ * import { diffable } from "diffable-objects";
+ * 
+ * class Counter extends DurableObject {
+ *   @diffable({ name: "counter", snapshotPolicy: "never" })
+ *   #state = { count: 0 };
+ * 
+ *   async fetch(request) {
+ *     this.#state.count += 1;
+ *     return new Response(`Count: ${this.#state.count}`);
+ *   }
+ * }
+ * ```
+ */
 export function diffable(
   options: DiffableOpts,
 ): FieldDecoratorFactoryReturn<any>;

src/index.ts

@@ -7,9 +7,37 @@ export * from "./decorator.js";
 export type SnapshotPolicy = "never" | "every-change" | { changes: number };
 
 export type StateOptions = {
+  /**
+   * Diffable-objects will automatically snapshot the state perodically based on this policy to minimize the
+   * number of diffs that must be applied to restore the state when the Durable Object is restarted.
+   */
   snapshotPolicy?: SnapshotPolicy;
 };
 
+/**
+ * Dynamically create a state object that persists changes to durable storage using Proxy and SQLite.
+ * 
+ * @example
+ * ```
+ * import { DurableObject } from "cloudflare:workers";
+ * import { state } from "diffable-objects";
+ * 
+ * class Counter extends DurableObject {
+ *   #state = state(this, "counter", { count: 0 });
+ * 
+ *   async fetch(request) {
+ *     this.#state.count += 1;
+ *     return new Response(`Count: ${this.#state.count}`);
+ *   }
+ * }
+ * ```
+ * 
+ * @param ctx the DurableObject state.
+ * @param name the name of the state, typically the name of the field.
+ * @param initialState the initial state of this object, this must be the same every time the DO is created.
+ * @param options options for configuring how the state is persisted.
+ * @returns a copy of state that will persist changes.
+ */
 export function state<T extends object>(
   ctx: DurableObjectState,
   name: string,