@adviser/cement 0.4.61 → 0.4.63

package/src/utils/consume.ts

@@ -1,5 +1,23 @@
 import { isPromise } from "../is-promise.js";
 
+/**
+ * Consumes a ReadableStream, applying a callback to each chunk and collecting results.
+ *
+ * Processes each chunk through the callback and returns an array of all results.
+ * Waits for async callbacks to complete before processing the next chunk.
+ *
+ * @template E - Stream element type
+ * @template R - Callback return type
+ * @param stream - The ReadableStream to consume
+ * @param cb - Callback function applied to each chunk
+ * @returns Promise resolving to array of all callback results
+ *
+ * @example
+ * ```typescript
+ * const results = await consumeStream(numberStream, (n) => n * 2);
+ * console.log(results); // [2, 4, 6, 8, ...]
+ * ```
+ */
 export function consumeStream<E, R>(stream: ReadableStream<E>, cb: (msg: E) => R): Promise<R[]> {
   const ret: R[] = [];
   return processStream(stream, (msg) =>
@@ -9,6 +27,27 @@ export function consumeStream<E, R>(stream: ReadableStream<E>, cb: (msg: E) => R
   ).then(() => ret);
 }
 
+/**
+ * Processes a ReadableStream with a callback function and optional context.
+ *
+ * Similar to consumeStream but doesn't collect results - just processes each
+ * chunk sequentially. Useful for side effects like logging, writing to files, etc.
+ *
+ * @template E - Stream element type
+ * @template CTX - Context type passed to callback
+ * @param stream - The ReadableStream to process
+ * @param cb - Callback function applied to each chunk (receives chunk and context)
+ * @param ctx - Optional context object passed to each callback invocation
+ * @returns Promise that resolves when stream is fully processed
+ *
+ * @example
+ * ```typescript
+ * await processStream(logStream, (entry, ctx) => {
+ *   ctx.count++;
+ *   console.log(`[${ctx.count}]`, entry);
+ * }, { count: 0 });
+ * ```
+ */
 export function processStream<E, CTX = object>(
   stream: ReadableStream<E>,
   cb: (msg: E, ctx: CTX) => Promise<void> | void,
@@ -67,6 +106,35 @@ function step<I extends IterableIterator<E> | AsyncIterableIterator<E>, R, E>(ar
   });
 }
 
+/**
+ * Consumes an iterator, applying a callback to each item and collecting results.
+ *
+ * Processes sync or async iterators, calling the callback for each item and
+ * returning an array of all results. Supports chunked processing with configurable
+ * chunk size to yield control back to the event loop periodically.
+ *
+ * @template T - Iterator element type
+ * @template R - Callback return type
+ * @param iter - Iterator or async iterator to consume
+ * @param cb - Callback function applied to each item
+ * @param params - Optional configuration (chunkSize, setTimeoutFn, ctx)
+ * @returns Promise resolving to array of all callback results
+ *
+ * @example
+ * ```typescript
+ * function* numbers() {
+ *   yield 1; yield 2; yield 3;
+ * }
+ *
+ * const results = await consumeIterator(numbers(), (n) => n * 2);
+ * console.log(results); // [2, 4, 6]
+ *
+ * // Async iterator with custom chunk size
+ * const data = await consumeIterator(asyncIterator, processItem, {
+ *   chunkSize: 32 // Yield to event loop every 32 items
+ * });
+ * ```
+ */
 export function consumeIterator<T, R>(
   iter: IterableIterator<T> | AsyncIterableIterator<T>,
   cb: (msg: T) => R,
@@ -83,6 +151,44 @@ export function consumeIterator<T, R>(
   ).then(() => ret);
 }
 
+/**
+ * Processes an iterator with a callback function for side effects.
+ *
+ * Similar to consumeIterator but doesn't collect results - just processes each
+ * item sequentially. Supports chunked processing to avoid blocking the event loop
+ * during long-running iterations. Useful for side effects like logging, writing
+ * to files, or updating UI.
+ *
+ * @template T - Iterator element type
+ * @template CTX - Context type passed to callback
+ * @param iter - Iterator or async iterator to process
+ * @param cb - Callback function applied to each item
+ * @param params - Optional configuration (chunkSize, setTimeoutFn, ctx)
+ * @returns Promise that resolves when iteration is complete
+ *
+ * @example
+ * ```typescript
+ * function* logs() {
+ *   yield 'Starting...';
+ *   yield 'Processing...';
+ *   yield 'Complete!';
+ * }
+ *
+ * await processIterator(logs(), (msg) => console.log(msg));
+ *
+ * // With context and chunked processing
+ * const ctx = { count: 0 };
+ * await processIterator(
+ *   largeDataIterator,
+ *   (item, ctx) => {
+ *     ctx.count++;
+ *     processItem(item);
+ *   },
+ *   { ctx, chunkSize: 100 } // Yield every 100 items
+ * );
+ * console.log(`Processed ${ctx.count} items`);
+ * ```
+ */
 export function processIterator<T, CTX = object>(
   iter: IterableIterator<T> | AsyncIterableIterator<T>,
   cb: (msg: T) => Promise<void> | void,

package/src/utils/fanout-write-stream.ts

@@ -1,3 +1,48 @@
+/**
+ * WritableStreamDefaultWriter that multiplexes writes to multiple underlying writers.
+ *
+ * FanoutWriteStream broadcasts all write operations to an array of writers simultaneously.
+ * All operations (write, close, abort, releaseLock) are applied to all underlying writers.
+ * Useful for scenarios like logging to multiple destinations, streaming to multiple
+ * consumers, or maintaining redundant copies of stream data.
+ *
+ * @example
+ * ```typescript
+ * // Write to both file and console simultaneously
+ * const fileStream = new WritableStream({ ... });
+ * const consoleStream = new ConsoleWriterStream();
+ *
+ * const fanout = new FanoutWriteStream([
+ *   fileStream.getWriter(),
+ *   consoleStream.getWriter()
+ * ]);
+ *
+ * // This writes to both destinations
+ * await fanout.write(new TextEncoder().encode('Log message'));
+ *
+ * // Close all writers
+ * await fanout.close();
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Mirror stream data to multiple endpoints
+ * const backupWriter = backupStream.getWriter();
+ * const primaryWriter = primaryStream.getWriter();
+ * const metricsWriter = metricsStream.getWriter();
+ *
+ * const fanout = new FanoutWriteStream([
+ *   primaryWriter,
+ *   backupWriter,
+ *   metricsWriter
+ * ]);
+ *
+ * // All three streams receive the data
+ * for (const chunk of dataChunks) {
+ *   await fanout.write(chunk);
+ * }
+ * ```
+ */
 export class FanoutWriteStream implements WritableStreamDefaultWriter<Uint8Array> {
   readonly _writers: WritableStreamDefaultWriter<Uint8Array>[];
   readonly ready: Promise<never>;

package/src/utils/get-params-result.ts

@@ -4,6 +4,43 @@ import { param } from "../types.js";
 export type MsgFn = (...keys: string[]) => string;
 export type KeysParam = (string | MsgFn | Record<string, param | number | string | boolean | undefined | null>)[];
 
+/**
+ * Retrieves multiple parameters with type-safe Result handling and defaults.
+ *
+ * Extracts multiple parameters from an object with getParam method (like URI),
+ * supporting required params, optional params, and default values. Returns
+ * Result.Err if any required parameters are missing.
+ *
+ * @param keys - Array of parameter specifications:
+ *   - string: Required parameter
+ *   - { key: "defaultValue" }: Parameter with default
+ *   - { key: param.OPTIONAL }: Optional parameter
+ *   - Function: Custom error message generator
+ * @param getParam - Object with getParam method (e.g., URI instance)
+ * @returns Result.Ok with all parameters or Result.Err with missing params message
+ *
+ * @example
+ * ```typescript
+ * const uri = URI.from('https://api.com?user=alice&page=1');
+ *
+ * // Required and optional params with defaults
+ * const result = getParamsResult(
+ *   ['user', { page: '1' }, { limit: param.OPTIONAL }],
+ *   uri
+ * );
+ *
+ * if (result.isOk()) {
+ *   const { user, page, limit } = result.unwrap();
+ *   // user: 'alice', page: '1', limit: undefined
+ * }
+ *
+ * // Custom error message
+ * const result2 = getParamsResult(
+ *   ['apiKey', 'secret', (...missing) => `Auth failed: missing ${missing.join(', ')}`],
+ *   uri
+ * );
+ * ```
+ */
 export function getParamsResult(
   keys: KeysParam,
   getParam: { getParam: (key: string) => string | undefined },

package/src/utils/index.ts

@@ -11,4 +11,3 @@ export * from "./uint8array-equal.js";
 export * from "./coerce-uint8.js";
 export * from "./consume.js";
 export * from "./to-sorted.js";
-export * from "./promise-sleep.js";

package/src/utils/rebuffer.ts

@@ -5,6 +5,26 @@ interface ReChunkResult {
   readonly chunk: Uint8Array;
 }
 
+/**
+ * Rebuffers an array of Uint8Arrays to a specific chunk size.
+ *
+ * Convenience wrapper around rebuffer stream for array inputs/outputs.
+ *
+ * @param a - Array of Uint8Arrays to rebuffer
+ * @param chunkSize - Target size for output chunks
+ * @returns Promise resolving to array of rebuffered chunks
+ *
+ * @example
+ * ```typescript
+ * const chunks = [
+ *   new Uint8Array([1, 2]),
+ *   new Uint8Array([3, 4, 5]),
+ *   new Uint8Array([6])
+ * ];
+ * const rebuffered = await rebufferArray(chunks, 3);
+ * // [Uint8Array([1,2,3]), Uint8Array([4,5,6])]
+ * ```
+ */
 export async function rebufferArray(a: Uint8Array[], chunkSize: number): Promise<Uint8Array[]> {
   return stream2array(rebuffer(array2stream(a), chunkSize));
 }
@@ -64,6 +84,28 @@ function pump(ps: pumpState, controller: ReadableStreamDefaultController<Uint8Ar
     });
 }
 
+/**
+ * Transforms a stream of Uint8Arrays into fixed-size chunks.
+ *
+ * Rebuffers variable-sized chunks from the input stream into consistent
+ * chunk sizes. The final chunk may be smaller if there's insufficient data.
+ * Useful for network protocols, file formats, or APIs requiring specific
+ * chunk sizes.
+ *
+ * @param a - Input ReadableStream with variable-sized Uint8Array chunks
+ * @param chunkSize - Target size for output chunks in bytes
+ * @returns ReadableStream emitting fixed-size chunks
+ *
+ * @example
+ * ```typescript
+ * // Stream has chunks: [10 bytes], [25 bytes], [5 bytes]
+ * const fixedChunks = rebuffer(inputStream, 16);
+ * // Output chunks: [16 bytes], [16 bytes], [8 bytes]
+ *
+ * // Useful for protocol framing
+ * const framedStream = rebuffer(rawStream, 1024); // 1KB chunks
+ * ```
+ */
 export function rebuffer(a: ReadableStream<Uint8Array>, chunkSize: number): ReadableStream<Uint8Array> {
   const state: pumpState = {
     reader: a.getReader(),

package/src/utils/relative-path.ts

@@ -1,3 +1,12 @@
+/**
+ * Path component type constants for representing special path elements.
+ *
+ * Uses bit flags to identify different path components:
+ * - Slash: Path separator (/)
+ * - Root: Absolute path root (/)
+ * - Up: Parent directory (..)
+ * - Noop: Current directory (.)
+ */
 export const PartType = {
   Slash: 0x1,
   Root: 0x3,
@@ -10,12 +19,29 @@ export type PartType = (typeof PartType)[keyof typeof PartType];
 
 export type PathItem = string | PartType;
 
+/**
+ * Path builder for constructing and manipulating filesystem paths.
+ *
+ * Represents a path as an array of parts (strings and special PartType tokens).
+ * Provides methods for adding path components and converting to string representation.
+ */
 export class Path {
   readonly parts: PathItem[];
   constructor(parts: PathItem[] = []) {
     this.parts = parts;
   }
 
+  /**
+   * Converts the path parts to a string representation.
+   *
+   * @returns Path as a string with proper separators
+   *
+   * @example
+   * ```typescript
+   * const path = new Path([PartType.Root, 'home', PartType.Slash, 'user']);
+   * path.toString(); // '/home/user'
+   * ```
+   */
   toString(): string {
     return this.parts
       .map((part) => {
@@ -36,6 +62,23 @@ export class Path {
       .join("");
   }
 
+  /**
+   * Adds a path component to the path.
+   *
+   * Handles special cases like duplicate slashes, "." and ".." segments.
+   *
+   * @param part - Path component to add (string or PartType)
+   * @throws Error if adding absolute part to absolute path
+   *
+   * @example
+   * ```typescript
+   * const path = new Path();
+   * path.add(PartType.Root);
+   * path.add('home');
+   * path.add(PartType.Slash);
+   * path.add('..');
+   * ```
+   */
   add(part: PathItem): void {
     if (this.parts.includes(PartType.Root) && part === PartType.Root) {
       throw new Error("Cannot add absolute part to absolute path");
@@ -66,6 +109,24 @@ export class Path {
   }
 }
 
+/**
+ * Parses a path string into a Path object with structured parts.
+ *
+ * Splits the path into components, identifying root, slashes, and segments.
+ * Consecutive slashes are collapsed into single separators.
+ *
+ * @param path - Path string to parse
+ * @returns Path object with structured components
+ *
+ * @example
+ * ```typescript
+ * const path = splitPath('/home/user/docs');
+ * // Path with parts: [Root, 'home', Slash, 'user', Slash, 'docs']
+ *
+ * const relative = splitPath('../config/app.json');
+ * // Path with parts: [Up, Slash, 'config', Slash, 'app.json']
+ * ```
+ */
 export function splitPath(path: string): Path {
   const p = new Path();
   if (path === "") {
@@ -89,6 +150,27 @@ export function splitPath(path: string): Path {
   return p;
 }
 
+/**
+ * Joins multiple path segments into a single path string.
+ *
+ * Intelligently handles slashes between segments, avoiding duplicates while
+ * ensuring proper separation. Empty segments are skipped.
+ *
+ * @param paths - Path segments to join
+ * @returns Joined path string
+ *
+ * @example
+ * ```typescript
+ * pathJoin('/home', 'user', 'docs');
+ * // '/home/user/docs'
+ *
+ * pathJoin('/api/', '/users/', 'profile');
+ * // '/api//users/profile'
+ *
+ * pathJoin('src', 'utils', 'path.ts');
+ * // 'src/utils/path.ts'
+ * ```
+ */
 export function pathJoin(...paths: string[]): string {
   let prev = "";
   const res: string[] = [];
@@ -112,6 +194,32 @@ export function pathJoin(...paths: string[]): string {
   return res.join("");
 }
 
+/**
+ * Resolves a relative path against a base path and normalizes the result.
+ *
+ * If the relative path is absolute, returns it directly. Otherwise, joins
+ * the base and relative paths, then normalizes by resolving ".." (parent)
+ * and "." (current) directory references.
+ *
+ * @param path - Base path to resolve against
+ * @param relative - Relative path to resolve (or absolute path)
+ * @returns Normalized resolved path
+ *
+ * @example
+ * ```typescript
+ * relativePath('/home/user', 'docs/file.txt');
+ * // '/home/user/docs/file.txt'
+ *
+ * relativePath('/home/user/project', '../config.json');
+ * // '/home/user/config.json'
+ *
+ * relativePath('/home/user', '/etc/hosts');
+ * // '/etc/hosts' (absolute path takes precedence)
+ *
+ * relativePath('/a/b/c', '../../d');
+ * // '/a/d'
+ * ```
+ */
 export function relativePath(path: string, relative: string): string {
   const relativeParts = splitPath(relative);
   let result: string;

package/src/utils/sorted-object.ts

@@ -1,16 +1,66 @@
 import { toSorted, TouchFn } from "./to-sorted.js";
 
+/**
+ * Converts an object to an array of single-key objects, sorted by key.
+ *
+ * Each entry becomes its own object with one key-value pair, useful for
+ * serialization formats that need objects instead of tuples.
+ *
+ * @template T - The input object type
+ * @param set - The object to convert
+ * @param touchFn - Optional function to transform values during sorting
+ * @returns Array of objects, each with a single key-value pair, sorted by key
+ *
+ * @example
+ * ```typescript
+ * const sorted = toSortedObjectArray({ z: 3, a: 1, m: 2 });
+ * // [{ a: 1 }, { m: 2 }, { z: 3 }]
+ * ```
+ */
 export function toSortedObjectArray<T>(set?: T, touchFn?: TouchFn): Record<string, unknown>[] {
   if (!set) return [];
   return toSortedArray(set, touchFn).map(([k, v]) => ({ [k]: v }));
 }
 
+/**
+ * Converts an object to a sorted array of [key, value] tuples.
+ *
+ * @template T - The input object type
+ * @param set - The object to convert
+ * @param touchFn - Optional function to transform values during sorting
+ * @returns Array of [key, value] tuples sorted by key
+ *
+ * @example
+ * ```typescript
+ * const sorted = toSortedArray({ z: 3, a: 1, m: 2 });
+ * // [['a', 1], ['m', 2], ['z', 3]]
+ * ```
+ */
 export function toSortedArray<T>(set?: T, touchFn?: TouchFn): [string, unknown][] {
   if (!set) return [];
   return Object.entries(toSorted(set, touchFn));
   //set).sort(([a], [b]) => a.localeCompare(b));
 }
 
+/**
+ * Returns a new object with keys sorted alphabetically.
+ *
+ * Creates a shallow copy of the object with keys in sorted order.
+ * Useful for deterministic serialization or comparison.
+ *
+ * @template T - The input object type
+ * @template S - Base type for non-null assertion
+ * @param set - The object to sort
+ * @param touchFn - Optional function to transform values during sorting
+ * @returns New object with sorted keys, or undefined if input is null/undefined
+ *
+ * @example
+ * ```typescript
+ * const sorted = toSortedObject({ z: 3, a: 1, m: 2 });
+ * // { a: 1, m: 2, z: 3 }
+ * Object.keys(sorted); // ['a', 'm', 'z']
+ * ```
+ */
 export function toSortedObject<T extends NonNullable<S>, S>(set?: T, touchFn?: TouchFn): T | undefined {
   if (!set) return set; // as T;
   return Object.fromEntries(toSortedArray(set, touchFn)) as T;

package/src/utils/stream-map.ts

@@ -4,6 +4,36 @@ export interface StreamMap<T, U> {
   Map(s: T, idx: number): U | Promise<U>;
   readonly Close?: () => void;
 }
+
+/**
+ * Transforms a ReadableStream by applying a mapping function to each chunk.
+ *
+ * Similar to Array.map() but for streams. Supports both sync and async
+ * mapping functions. Calls optional Close callback when stream ends.
+ *
+ * @template T - Input chunk type
+ * @template U - Output chunk type
+ * @param s - The input ReadableStream
+ * @param sm - StreamMap object with Map function and optional Close callback
+ * @returns ReadableStream with transformed chunks
+ *
+ * @example
+ * ```typescript
+ * const numberStream = getNumberStream();
+ * const doubled = streamMap(numberStream, {
+ *   Map: (n) => n * 2,
+ *   Close: () => console.log('Stream ended')
+ * });
+ *
+ * // Async transformation
+ * const enriched = streamMap(userStream, {
+ *   Map: async (user) => {
+ *     const details = await fetchUserDetails(user.id);
+ *     return { ...user, ...details };
+ *   }
+ * });
+ * ```
+ */
 export function streamMap<T, U>(s: ReadableStream<T>, sm: StreamMap<T, U>): ReadableStream<U> {
   const state = { reader: s.getReader(), streamMap: sm, idx: 0 };
   return new ReadableStream<U>({
@@ -28,6 +58,29 @@ export function streamMap<T, U>(s: ReadableStream<T>, sm: StreamMap<T, U>): Read
   });
 }
 
+/**
+ * Consumes a ReadableStream without processing, counting the number of chunks.
+ *
+ * Reads and discards all chunks from the stream, returning only the count.
+ * Useful for testing, benchmarking, or draining streams when you only need
+ * to know how many items were produced.
+ *
+ * @template T - Stream element type
+ * @param a - ReadableStream to consume
+ * @returns Promise resolving to the number of chunks read
+ *
+ * @example
+ * ```typescript
+ * const stream = createDataStream();
+ * const count = await devnull(stream);
+ * console.log(`Stream produced ${count} chunks`);
+ *
+ * // Useful for benchmarking stream production
+ * const start = Date.now();
+ * const chunks = await devnull(dataGenerator());
+ * console.log(`Generated ${chunks} chunks in ${Date.now() - start}ms`);
+ * ```
+ */
 export async function devnull<T>(a: ReadableStream<T>): Promise<number> {
   const reader = a.getReader();
   let cnt = 0;
@@ -41,6 +94,22 @@ export async function devnull<T>(a: ReadableStream<T>): Promise<number> {
   return cnt;
 }
 
+/**
+ * Converts an array to a ReadableStream.
+ *
+ * Each array element becomes a stream chunk. Useful for testing or
+ * converting in-memory data to streaming format.
+ *
+ * @template T - The type of array elements
+ * @param a - The array to convert
+ * @returns ReadableStream emitting each array element
+ *
+ * @example
+ * ```typescript
+ * const stream = array2stream([1, 2, 3, 4, 5]);
+ * await processStream(stream, (n) => console.log(n));
+ * ```
+ */
 export function array2stream<T>(a: T[]): ReadableStream<T> {
   let i = 0;
   return new ReadableStream<T>({
@@ -55,6 +124,27 @@ export function array2stream<T>(a: T[]): ReadableStream<T> {
   });
 }
 
+/**
+ * Converts a ReadableStream to an array by collecting all chunks.
+ *
+ * Reads the entire stream into memory, collecting all chunks into an array.
+ * Use with caution on large or infinite streams as it loads everything into memory.
+ *
+ * @template T - Stream element type
+ * @param a - ReadableStream to convert
+ * @returns Promise resolving to array of all stream chunks
+ *
+ * @example
+ * ```typescript
+ * const stream = fetchDataStream();
+ * const items = await stream2array(stream);
+ * console.log(`Received ${items.length} items`);
+ *
+ * // Process stream as array
+ * const numbers = await stream2array(numberStream);
+ * const sum = numbers.reduce((a, b) => a + b, 0);
+ * ```
+ */
 export async function stream2array<T>(a: ReadableStream<T>): Promise<T[]> {
   const ret: T[] = [];
   const reader = a.getReader();

package/src/utils/stream2string.ts

@@ -1,3 +1,23 @@
+/**
+ * Converts a ReadableStream of Uint8Array chunks to a string.
+ *
+ * Reads the entire stream (or up to maxSize bytes) and decodes it as UTF-8 text.
+ * Useful for consuming response bodies, file streams, etc.
+ *
+ * @param stream - The ReadableStream to convert (returns empty string if null/undefined)
+ * @param maxSize - Optional maximum bytes to read before stopping
+ * @returns Promise resolving to the decoded string
+ *
+ * @example
+ * ```typescript
+ * const response = await fetch('/api/data');
+ * const text = await stream2string(response.body);
+ * console.log(text);
+ *
+ * // With size limit
+ * const preview = await stream2string(response.body, 1000); // First 1KB
+ * ```
+ */
 export async function stream2string(stream?: ReadableStream<Uint8Array> | null, maxSize?: number): Promise<string> {
   if (!stream) {
     return Promise.resolve("");
@@ -25,6 +45,21 @@ export async function stream2string(stream?: ReadableStream<Uint8Array> | null,
   return Promise.resolve(res);
 }
 
+/**
+ * Converts a ReadableStream of Uint8Array chunks to a single Uint8Array.
+ *
+ * Reads and concatenates all chunks from the stream into a single buffer.
+ * Useful for loading binary data from streams.
+ *
+ * @param stream - The ReadableStream to convert (returns empty Uint8Array if null/undefined)
+ * @returns Promise resolving to the concatenated Uint8Array
+ *
+ * @example
+ * ```typescript
+ * const response = await fetch('/image.png');
+ * const bytes = await stream2uint8array(response.body);
+ * ```
+ */
 export async function stream2uint8array(stream?: ReadableStream<Uint8Array> | null): Promise<Uint8Array> {
   if (!stream) {
     return Promise.resolve(new Uint8Array());