Add comments

Author: max-lt

README.md

@@ -23,6 +23,8 @@ Add to your `tsconfig.json`:
 Or use a triple-slash directive:
 
 ```typescript
+/// <reference no-default-lib="true" />
+/// <reference lib="esnext" />
 /// <reference types="@openworkers/workers-types" />
 ```
 

types/abort.d.ts

@@ -1,12 +1,31 @@
 // AbortController API types
 
+/**
+ * A signal object that allows you to communicate with an async operation
+ * and abort it if required via an AbortController.
+ */
 interface AbortSignal extends EventTarget {
+  /** Returns true if the signal has been aborted. */
   readonly aborted: boolean;
+  /** The reason for aborting, if any. */
   readonly reason: unknown;
+  /** Throws the abort reason if the signal has been aborted. */
   throwIfAborted(): void;
 }
 
+/**
+ * A controller object that allows you to abort one or more async operations.
+ *
+ * @example
+ * ```ts
+ * const controller = new AbortController();
+ * fetch(url, { signal: controller.signal });
+ * controller.abort(); // Cancels the fetch
+ * ```
+ */
 declare class AbortController {
+  /** The AbortSignal associated with this controller. */
   readonly signal: AbortSignal;
+  /** Aborts the associated signal with an optional reason. */
   abort(reason?: unknown): void;
 }

types/bindings.d.ts

@@ -1,52 +1,199 @@
 // OpenWorkers Bindings types
 
+/**
+ * Static asset binding for serving files from the worker bundle.
+ *
+ * @example
+ * ```ts
+ * export default {
+ *   async fetch(request, env) {
+ *     return env.ASSETS.fetch('/index.html');
+ *   }
+ * }
+ * ```
+ */
 interface BindingAssets {
+  /**
+   * Fetches a static asset from the bundle.
+   * @param path The asset path (e.g., "/index.html").
+   * @param options Optional request options.
+   */
   fetch(path: string, options?: RequestInit): Promise<Response>;
 }
 
+/**
+ * Result of a storage head operation.
+ */
 interface StorageHeadResult {
+  /** The size of the object in bytes. */
   size: number;
+
+  /** The ETag of the object, if available. */
   etag?: string;
 }
 
+/**
+ * Options for listing storage objects.
+ */
 interface StorageListOptions {
+  /** Only return keys starting with this prefix. */
   prefix?: string;
+
+  /** Maximum number of keys to return. */
   limit?: number;
 }
 
+/**
+ * Result of a storage list operation.
+ */
 interface StorageListResult {
+  /** The matching keys. */
   keys: string[];
+
+  /** Whether there are more keys beyond the limit. */
   truncated: boolean;
 }
 
+/**
+ * Object storage binding for storing binary data.
+ * Suitable for files, images, and large data.
+ *
+ * @example
+ * ```ts
+ * // Store data
+ * await env.STORAGE.put('file.txt', 'Hello, World!');
+ *
+ * // Retrieve data
+ * const data = await env.STORAGE.get('file.txt');
+ * ```
+ */
 interface BindingStorage {
+  /**
+   * Retrieves a value by key.
+   * @returns The value as a string, or null if not found.
+   */
   get(key: string): Promise<string | null>;
+
+  /**
+   * Stores a value.
+   * @param key The storage key.
+   * @param value The value to store.
+   */
   put(key: string, value: string | Uint8Array): Promise<void>;
+
+  /**
+   * Gets metadata about an object without retrieving its contents.
+   */
   head(key: string): Promise<StorageHeadResult>;
+
+  /**
+   * Lists keys in storage.
+   */
   list(options?: StorageListOptions): Promise<StorageListResult>;
+
+  /**
+   * Deletes a key.
+   */
   delete(key: string): Promise<void>;
 }
 
+/**
+ * Options for KV put operations.
+ */
 interface KVPutOptions {
+  /** Time-to-live in seconds. After this time, the key expires. */
   expiresIn?: number;
 }
 
+/**
+ * Options for KV list operations.
+ */
 interface KVListOptions {
+  /** Only return keys starting with this prefix. */
   prefix?: string;
+
+  /** Maximum number of keys to return. */
   limit?: number;
 }
 
+/**
+ * Key-Value storage binding for fast, low-latency data access.
+ * Ideal for configuration, sessions, and small data.
+ *
+ * @example
+ * ```ts
+ * // Store with expiration
+ * await env.KV.put('session:abc', userData, { expiresIn: 3600 });
+ *
+ * // Retrieve
+ * const session = await env.KV.get('session:abc');
+ * ```
+ */
 interface BindingKV {
+  /**
+   * Retrieves a value by key.
+   * @returns The value as a string, or null if not found.
+   */
   get(key: string): Promise<string | null>;
+
+  /**
+   * Stores a value with optional expiration.
+   * @param key The storage key.
+   * @param value The value to store.
+   * @param options Optional settings like TTL.
+   */
   put(key: string, value: string, options?: KVPutOptions): Promise<void>;
+
+  /**
+   * Deletes a key.
+   */
   delete(key: string): Promise<void>;
+
+  /**
+   * Lists keys with optional filtering.
+   */
   list(options?: KVListOptions): Promise<string[]>;
 }
 
+/**
+ * SQL database binding for relational data.
+ *
+ * @example
+ * ```ts
+ * const users = await env.DB.query<User>(
+ *   'SELECT * FROM users WHERE active = ?',
+ *   [true]
+ * );
+ * ```
+ */
 interface BindingDatabase {
+  /**
+   * Executes a SQL query.
+   * @param sql The SQL query with ? placeholders.
+   * @param params Parameter values to bind.
+   * @returns An array of result rows.
+   */
   query<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<T[]>;
 }
 
+/**
+ * Service binding for calling other workers.
+ *
+ * @example
+ * ```ts
+ * const response = await env.AUTH_SERVICE.fetch(
+ *   new Request('https://internal/validate', {
+ *     method: 'POST',
+ *     body: JSON.stringify({ token })
+ *   })
+ * );
+ * ```
+ */
 interface BindingWorker {
+  /**
+   * Calls another worker with a request.
+   * @param request The request to send.
+   * @param init Optional request options (when using string URL).
+   */
   fetch(request: Request | string, init?: RequestInit): Promise<Response>;
 }

types/blob.d.ts

@@ -1,36 +1,118 @@
 // Blob & FormData API types
 
+/**
+ * A file-like object of immutable, raw data.
+ * Can be read as text, ArrayBuffer, or streamed.
+ *
+ * @example
+ * ```ts
+ * const blob = new Blob(['Hello, World!'], { type: 'text/plain' });
+ * const text = await blob.text(); // "Hello, World!"
+ * ```
+ */
 declare class Blob {
+  /**
+   * Creates a new Blob.
+   * @param blobParts Array of data to include in the blob.
+   * @param options Optional settings like MIME type.
+   */
   constructor(
     blobParts?: (ArrayBuffer | Uint8Array | Blob | string)[],
     options?: { type?: string }
   );
+
+  /** The size of the blob in bytes. */
   readonly size: number;
+
+  /** The MIME type of the blob. */
   readonly type: string;
+
+  /** Returns a promise that resolves with an ArrayBuffer containing the blob's data. */
   arrayBuffer(): Promise<ArrayBuffer>;
+
+  /**
+   * Returns a new Blob containing a subset of this blob's data.
+   * @param start Starting byte index (inclusive).
+   * @param end Ending byte index (exclusive).
+   * @param contentType MIME type for the new blob.
+   */
   slice(start?: number, end?: number, contentType?: string): Blob;
+
+  /** Returns a ReadableStream for reading the blob's contents. */
   stream(): ReadableStream<Uint8Array>;
+
+  /** Returns a promise that resolves with the blob's contents as a string. */
   text(): Promise<string>;
 }
 
+/**
+ * A File is a Blob with a name and last modified timestamp.
+ * Typically obtained from FormData or file uploads.
+ */
 interface File extends Blob {
+  /** The last modified timestamp in milliseconds since Unix epoch. */
   readonly lastModified: number;
+
+  /** The name of the file. */
   readonly name: string;
 }
 
+/**
+ * A set of key/value pairs representing form fields and their values.
+ * Used for building multipart/form-data requests.
+ *
+ * @example
+ * ```ts
+ * const form = new FormData();
+ * form.append('name', 'John');
+ * form.append('file', new Blob(['content']), 'file.txt');
+ * await fetch('/upload', { method: 'POST', body: form });
+ * ```
+ */
 declare class FormData {
   constructor();
+
+  /**
+   * Appends a new value to an existing key, or adds the key if it doesn't exist.
+   * @param name The field name.
+   * @param value The field value.
+   * @param filename Optional filename for Blob values.
+   */
   append(name: string, value: string | Blob, filename?: string): void;
+
+  /** Deletes all values associated with a given key. */
   delete(name: string): void;
+
+  /** Returns the first value associated with a given key. */
   get(name: string): string | File | null;
+
+  /** Returns all values associated with a given key. */
   getAll(name: string): (string | File)[];
+
+  /** Returns whether a given key exists. */
   has(name: string): boolean;
+
+  /**
+   * Sets a value for a key, replacing any existing values.
+   * @param name The field name.
+   * @param value The field value.
+   * @param filename Optional filename for Blob values.
+   */
   set(name: string, value: string | Blob, filename?: string): void;
+
+  /** Executes a callback for each key/value pair. */
   forEach(
     callback: (value: string | File, key: string, parent: FormData) => void
   ): void;
+
+  /** Returns an iterator of all key/value pairs. */
   entries(): IterableIterator<[string, string | File]>;
+
+  /** Returns an iterator of all keys. */
   keys(): IterableIterator<string>;
+
+  /** Returns an iterator of all values. */
   values(): IterableIterator<string | File>;
+
   [Symbol.iterator](): IterableIterator<[string, string | File]>;
 }