chore: switch package manager to bun and create docs for codebase

src/_shared/async-queue.ts

@@ -1,3 +1,11 @@
+/**
+ * Small async iterator queue used to bridge callback-based streams to generators.
+ *
+ * Producers call {@link push}, {@link end}, or {@link fail}; consumers iterate the
+ * queue with `for await` or call {@link next} directly.
+ *
+ * @template T - Event type yielded by the queue.
+ */
 export class AsyncQueue<T> implements AsyncIterableIterator<T> {
 	private readonly values: T[] = [];
 	private readonly waiters: Array<{
@@ -7,10 +15,16 @@ export class AsyncQueue<T> implements AsyncIterableIterator<T> {
 	private closed = false;
 	private error: unknown;
 
+	/** Returns this queue as its own async iterator. */
 	[Symbol.asyncIterator](): AsyncIterableIterator<T> {
 		return this;
 	}
 
+	/**
+	 * Reads the next queued value, waits for one, or completes when the queue ends.
+	 *
+	 * @returns Next async iterator result.
+	 */
 	next(): Promise<IteratorResult<T>> {
 		if (this.values.length) {
 			return Promise.resolve({ done: false, value: this.values.shift() as T });
@@ -23,16 +37,32 @@ export class AsyncQueue<T> implements AsyncIterableIterator<T> {
 		});
 	}
 
+	/**
+	 * Ends the queue when a consumer stops iteration early.
+	 *
+	 * @returns Completed async iterator result.
+	 */
 	return(): Promise<IteratorResult<T>> {
 		this.end();
 		return Promise.resolve({ done: true, value: undefined });
 	}
 
+	/**
+	 * Fails the queue when a consumer throws into the iterator.
+	 *
+	 * @param error - Error to propagate to waiting consumers.
+	 * @returns Rejected promise containing the provided error.
+	 */
 	throw(error?: unknown): Promise<IteratorResult<T>> {
 		this.fail(error);
 		return Promise.reject(error);
 	}
 
+	/**
+	 * Pushes a value to the next waiting consumer or buffers it for later reads.
+	 *
+	 * @param value - Value to yield from the iterator.
+	 */
 	push(value: T): void {
 		if (this.closed) return;
 		const waiter = this.waiters.shift();
@@ -43,6 +73,7 @@ export class AsyncQueue<T> implements AsyncIterableIterator<T> {
 		this.values.push(value);
 	}
 
+	/** Completes the queue and resolves all waiting consumers as done. */
 	end(): void {
 		if (this.closed) return;
 		this.closed = true;
@@ -51,6 +82,11 @@ export class AsyncQueue<T> implements AsyncIterableIterator<T> {
 		}
 	}
 
+	/**
+	 * Fails the queue and rejects all waiting consumers.
+	 *
+	 * @param error - Error to propagate through the iterator.
+	 */
 	fail(error: unknown): void {
 		if (this.closed) return;
 		this.closed = true;

src/_shared/http.ts

@@ -1,5 +1,6 @@
 import { TimeoutError, throwErrorFromResponse } from "../exceptions.js";
 
+/** Configuration for the low-level HTTP client. */
 export interface HttpClientConfig {
 	/** API origin used for all relative request paths. */
 	baseUrl: string;
@@ -60,27 +61,70 @@ export class HttpClient {
 		}
 	}
 
-	/** Sends a GET request and parses the JSON response. */
+	/**
+	 * Sends a GET request and parses the JSON response.
+	 *
+	 * @param path - API path relative to the configured base URL.
+	 * @param opts - Optional query, header, auth, timeout, and cancellation settings.
+	 * @returns Parsed JSON response.
+	 * @throws TimeoutError when the configured timeout aborts the request.
+	 * @throws WrennError subclasses for unsuccessful responses.
+	 */
 	get<T>(path: string, opts?: RequestOptions): Promise<T> {
 		return this.request<T>("GET", path, undefined, opts);
 	}
 
-	/** Sends a POST request with an optional JSON body. */
+	/**
+	 * Sends a POST request with an optional JSON body.
+	 *
+	 * @param path - API path relative to the configured base URL.
+	 * @param body - Optional JSON request body.
+	 * @param opts - Optional query, header, auth, timeout, and cancellation settings.
+	 * @returns Parsed JSON response.
+	 * @throws TimeoutError when the configured timeout aborts the request.
+	 * @throws WrennError subclasses for unsuccessful responses.
+	 */
 	post<T>(path: string, body?: unknown, opts?: RequestOptions): Promise<T> {
 		return this.request<T>("POST", path, body, opts);
 	}
 
-	/** Sends a PATCH request with an optional JSON body. */
+	/**
+	 * Sends a PATCH request with an optional JSON body.
+	 *
+	 * @param path - API path relative to the configured base URL.
+	 * @param body - Optional JSON request body.
+	 * @param opts - Optional query, header, auth, timeout, and cancellation settings.
+	 * @returns Parsed JSON response.
+	 * @throws TimeoutError when the configured timeout aborts the request.
+	 * @throws WrennError subclasses for unsuccessful responses.
+	 */
 	patch<T>(path: string, body?: unknown, opts?: RequestOptions): Promise<T> {
 		return this.request<T>("PATCH", path, body, opts);
 	}
 
-	/** Sends a PUT request with an optional JSON body. */
+	/**
+	 * Sends a PUT request with an optional JSON body.
+	 *
+	 * @param path - API path relative to the configured base URL.
+	 * @param body - Optional JSON request body.
+	 * @param opts - Optional query, header, auth, timeout, and cancellation settings.
+	 * @returns Parsed JSON response.
+	 * @throws TimeoutError when the configured timeout aborts the request.
+	 * @throws WrennError subclasses for unsuccessful responses.
+	 */
 	put<T>(path: string, body?: unknown, opts?: RequestOptions): Promise<T> {
 		return this.request<T>("PUT", path, body, opts);
 	}
 
-	/** Sends a DELETE request and expects no response body. */
+	/**
+	 * Sends a DELETE request and expects no response body.
+	 *
+	 * @param path - API path relative to the configured base URL.
+	 * @param opts - Optional query, header, auth, timeout, and cancellation settings.
+	 * @returns Resolves when the response succeeds.
+	 * @throws TimeoutError when the configured timeout aborts the request.
+	 * @throws WrennError subclasses for unsuccessful responses.
+	 */
 	delete(path: string, opts?: RequestOptions): Promise<void> {
 		return this.request<void>("DELETE", path, undefined, opts);
 	}