@adviser/cement 0.5.0 → 0.5.2

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

@@ -1,5 +1,11 @@
 import { TxtEnDecoderSingleton } from "../txt-en-decoder.js";
 
+/**
+ * WritableStreamDefaultWriter that writes to console with automatic JSON parsing.
+ *
+ * Decodes Uint8Array chunks to strings, attempts JSON parsing to extract log levels,
+ * and routes output to appropriate console methods (log, warn, error).
+ */
 export class ConsoleWriterStreamDefaultWriter implements WritableStreamDefaultWriter<Uint8Array> {
   readonly desiredSize: number | null = null;
   // readonly decoder: TextDecoder = new TextDecoder();
@@ -57,6 +63,34 @@ export interface ConsoleWriterStreamParams {
   warn(...args: unknown[]): void;
 }
 
+/**
+ * WritableStream that outputs to console with JSON log-level parsing.
+ *
+ * Decodes stream chunks and attempts to parse as JSON to extract log levels.
+ * Routes messages to console.log/warn/error based on parsed level field.
+ * Falls back to console.log for non-JSON content. Useful for structured logging.
+ *
+ * @example
+ * ```typescript
+ * const consoleStream = new ConsoleWriterStream();
+ * const writer = consoleStream.getWriter();
+ *
+ * // JSON with level field
+ * await writer.write(
+ *   new TextEncoder().encode('{"level":"error","msg":"Failed"}')
+ * ); // Outputs to console.error
+ *
+ * // Plain text
+ * await writer.write(
+ *   new TextEncoder().encode('Hello')
+ * ); // Outputs to console.log
+ *
+ * // Custom console methods
+ * const custom = new ConsoleWriterStream({
+ *   error: (msg) => saveToFile('error.log', msg)
+ * });
+ * ```
+ */
 export class ConsoleWriterStream implements WritableStream<Uint8Array> {
   locked = false;
   _writer?: WritableStreamDefaultWriter<Uint8Array>;

package/src/utils/consume.ts

@@ -1,5 +1,23 @@
-import { isPromise } from "../is-promise.js";
+import { isPromise } from "@adviser/cement";
 
+/**
+ * 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

@@ -1,9 +1,45 @@
-import { Result } from "../result.js";
-import { param } from "../types.js";
+import { Result, param } from "@adviser/cement";
 
 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/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,69 @@
-export function toSortedObjectArray<T>(set?: T): Record<string, unknown>[] {
+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).map(([k, v]) => ({ [k]: v }));
+  return toSortedArray(set, touchFn).map(([k, v]) => ({ [k]: v }));
 }
 
-export function toSortedArray<T>(set?: T): [string, unknown][] {
+/**
+ * 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(set).sort(([a], [b]) => a.localeCompare(b));
+  return Object.entries(toSorted(set, touchFn));
+  //set).sort(([a], [b]) => a.localeCompare(b));
 }
 
-export function toSortedObject<S, T extends NonNullable<S>>(set?: T): T | undefined {
+/**
+ * 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)) as T;
+  return Object.fromEntries(toSortedArray(set, touchFn)) as T;
   // return toSortedArray(set).reduce((acc, cur) => {
   //     acc[cur[0]] = cur[1];
   //     return acc

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();