@adviser/cement 0.4.61 → 0.4.63

package/src/coerce-binary.ts

@@ -2,14 +2,32 @@ import { TxtEnDecoderSingleton } from "./txt-en-decoder.js";
 
 export type CoerceBinaryInput = string | ArrayBufferLike | ArrayBufferView | Uint8Array; // | SharedArrayBuffer
 
+/**
+ * Type guard to check if a value is an ArrayBuffer.
+ *
+ * @param value - The value to check
+ * @returns True if the value is an ArrayBuffer
+ */
 export function isArrayBuffer(value: unknown): value is ArrayBuffer {
   return value instanceof ArrayBuffer || Object.prototype.toString.call(value) === "[object ArrayBuffer]";
 }
 
+/**
+ * Type guard to check if a value is a Uint8Array.
+ *
+ * @param value - The value to check
+ * @returns True if the value is a Uint8Array
+ */
 export function isUint8Array(value: unknown): value is Uint8Array {
   return value instanceof Uint8Array || Object.prototype.toString.call(value) === "[object Uint8Array]";
 }
 
+/**
+ * Converts various binary input types (including Blob) to Uint8Array asynchronously.
+ *
+ * @param input - String, ArrayBuffer, ArrayBufferView, Uint8Array, or Blob to convert
+ * @returns Promise resolving to Uint8Array
+ */
 export async function top_uint8(input: CoerceBinaryInput | Blob): Promise<Uint8Array> {
   if (input instanceof Blob) {
     return new Uint8Array(await input.arrayBuffer());
@@ -17,6 +35,15 @@ export async function top_uint8(input: CoerceBinaryInput | Blob): Promise<Uint8A
   return to_uint8(input);
 }
 
+/**
+ * Converts various binary input types to Uint8Array synchronously.
+ *
+ * Handles strings (encoding with TextEncoder), ArrayBuffers, and ArrayBufferViews.
+ *
+ * @param input - String, ArrayBuffer, ArrayBufferView, or Uint8Array to convert
+ * @param encoder - Optional TextEncoder instance (uses singleton if not provided)
+ * @returns Uint8Array representation of the input
+ */
 export function to_uint8(input: CoerceBinaryInput, encoder?: TextEncoder): Uint8Array {
   if (typeof input === "string") {
     return (encoder ?? TxtEnDecoderSingleton()).encode(input);
@@ -32,6 +59,13 @@ export function to_uint8(input: CoerceBinaryInput, encoder?: TextEncoder): Uint8
   return new Uint8Array(input as unknown as ArrayBufferLike);
 }
 
+/**
+ * Converts various binary input types to Blob.
+ *
+ * @param input - String, ArrayBuffer, ArrayBufferView, Uint8Array, or Blob to convert
+ * @param encoder - Optional TextEncoder instance (uses singleton if not provided)
+ * @returns Blob representation of the input
+ */
 export function to_blob(input: CoerceBinaryInput | Blob, encoder?: TextEncoder): Blob {
   if (input instanceof Blob) {
     return input;
@@ -40,6 +74,13 @@ export function to_blob(input: CoerceBinaryInput | Blob, encoder?: TextEncoder):
   return new Blob([ab]);
 }
 
+/**
+ * Converts various binary input types to ArrayBuffer.
+ *
+ * @param input - String, ArrayBuffer, ArrayBufferView, or Uint8Array to convert
+ * @param encoder - Optional TextEncoder instance (uses singleton if not provided)
+ * @returns ArrayBuffer representation of the input
+ */
 export function to_arraybuf(input: CoerceBinaryInput, encoder?: TextEncoder): ArrayBuffer {
   if (input instanceof ArrayBuffer) {
     return input;

package/src/crypto.ts

@@ -123,6 +123,41 @@ function digestSHA256(crypto: typeof globalThis.crypto): (data: Uint8Array) => P
   };
 }
 
+/**
+ * Creates a CryptoRuntime abstraction with optional custom implementations.
+ *
+ * Provides a unified crypto interface that works across different JavaScript
+ * runtimes (browsers, Node.js, Deno, CF Workers). Automatically uses the global
+ * Web Crypto API when available, with fallback implementations that throw errors
+ * for unavailable operations. Allows overriding any method for testing or
+ * custom implementations.
+ *
+ * @param cryptoOpts - Optional custom implementations for crypto operations
+ * @returns CryptoRuntime instance with crypto operations
+ *
+ * @example
+ * ```typescript
+ * // Use default global crypto
+ * const crypto = toCryptoRuntime();
+ * const hash = await crypto.digestSHA256(new Uint8Array([1, 2, 3]));
+ * const randomData = crypto.randomBytes(16);
+ *
+ * // Override for testing
+ * const mockCrypto = toCryptoRuntime({
+ *   randomBytes: (size) => new Uint8Array(size).fill(42),
+ *   digestSHA256: async (data) => new ArrayBuffer(32)
+ * });
+ *
+ * // Encrypt/decrypt with AES-GCM
+ * const key = await crypto.importKey(
+ *   'raw',
+ *   new Uint8Array(32),
+ *   { name: 'AES-GCM' },
+ *   false,
+ *   ['encrypt', 'decrypt']
+ * );
+ * ```
+ */
 export function toCryptoRuntime(cryptoOpts: Partial<CryptoRuntime> = {}): CryptoRuntime {
   let crypto: typeof globalThis.crypto;
   if (!globalThis.crypto || !globalThis.crypto.subtle) {

package/src/future.ts

@@ -1,5 +1,30 @@
 import { Lazy } from "./resolve-once.js";
 
+/**
+ * A Promise that can be resolved or rejected externally after creation.
+ *
+ * Future provides a way to create a Promise whose resolution is controlled
+ * externally rather than in the executor function. This is useful for
+ * coordinating async operations, implementing custom async primitives,
+ * or bridging callback-based APIs to promises.
+ *
+ * @template T - The type of the resolved value
+ * @template CTX - Optional context type for additional data
+ *
+ * @example
+ * ```typescript
+ * const future = new Future<string>();
+ *
+ * // Later, resolve it from anywhere
+ * future.resolve('hello');
+ *
+ * // Or reject it
+ * future.reject(new Error('failed'));
+ *
+ * // Use it like a promise
+ * const result = await future.asPromise();
+ * ```
+ */
 export class Future<T, CTX = void> {
   // readonly id = Math.random();
   readonly #promise: Promise<T>;
@@ -19,16 +44,35 @@ export class Future<T, CTX = void> {
     });
   }
 
-  // the id is not cryptographically secure, but good enough for transaction id
+  /**
+   * Lazily-generated unique identifier for this Future.
+   * Not cryptographically secure, but suitable for transaction/debug tracking.
+   */
   readonly id: () => string = Lazy(() => Math.random().toString(36).substring(2) + Date.now().toString(36));
 
+  /**
+   * Returns the underlying Promise that will be resolved or rejected.
+   *
+   * @returns The Promise representation of this Future
+   */
   asPromise(): Promise<T> {
     return this.#promise;
   }
 
+  /**
+   * Resolves the Future with the given value.
+   *
+   * @param value - The value to resolve the Promise with
+   */
   resolve(value: T): void {
     this.#resolveFn(value);
   }
+
+  /**
+   * Rejects the Future with the given reason.
+   *
+   * @param reason - The reason for rejection (typically an Error)
+   */
   reject(reason: unknown): void {
     this.#rejectFn(reason);
   }

package/src/http_header.ts

@@ -84,9 +84,42 @@ function hasForEach(unk: unknown): unk is HeaderForeach {
   return typeof (unk as Headers).forEach == "function";
 }
 
+/**
+ * HTTP header container with multi-value support and type-safe operations.
+ *
+ * HttpHeader provides a comprehensive API for managing HTTP headers with
+ * support for multiple values per header name. All header names are normalized
+ * to lowercase for case-insensitive comparison. Supports conversion to/from
+ * various formats including native Headers, plain objects, and arrays.
+ *
+ * @example
+ * ```typescript
+ * const headers = new HttpHeader();
+ * headers.Add('Content-Type', 'application/json');
+ * headers.Add('Accept', ['application/json', 'text/html']);
+ *
+ * const value = headers.Get('content-type'); // Case-insensitive
+ * const allAccept = headers.Values('accept'); // ['application/json', 'text/html']
+ *
+ * // Merge multiple header sources
+ * const merged = HttpHeader.from(
+ *   { 'User-Agent': 'MyApp/1.0' },
+ *   new Headers({ 'Authorization': 'Bearer token' })
+ * );
+ * ```
+ */
 export class HttpHeader {
   readonly _headers: Map<string, Set<string>> = new Map<string, Set<string>>();
 
+  /**
+   * Converts various header formats to HttpHeader instance.
+   *
+   * Accepts Headers, arrays, objects, or existing HttpHeader instances.
+   * Automatically handles comma-separated values and normalizes header names.
+   *
+   * @param headers - Headers in any supported format
+   * @returns HttpHeader instance
+   */
   static coerce(headers: CoercedHeadersInit): HttpHeader {
     if (headers instanceof HttpHeader) {
       return headers;
@@ -123,6 +156,22 @@ export class HttpHeader {
     }
     return h;
   }
+
+  /**
+   * Creates HttpHeader by merging multiple header sources.
+   *
+   * @param headersArgs - One or more header sources to merge
+   * @returns New HttpHeader with all headers merged
+   *
+   * @example
+   * ```typescript
+   * const headers = HttpHeader.from(
+   *   { 'Content-Type': 'application/json' },
+   *   new Headers({ 'Authorization': 'Bearer token' }),
+   *   [['X-Custom', 'value']]
+   * );
+   * ```
+   */
   static from(...headersArgs: CoercedHeadersInit[]): HttpHeader {
     return headersArgs.map((headers) => HttpHeader.coerce(headers)).reduce((acc, cur) => acc.MergeInplace(cur), new HttpHeader());
   }
@@ -138,10 +187,24 @@ export class HttpHeader {
   _key(key: string): string {
     return key.toLowerCase();
   }
+
+  /**
+   * Gets all values for a header (case-insensitive).
+   *
+   * @param key - Header name
+   * @returns Array of all values for the header
+   */
   Values(key: string): string[] {
     const values = this._headers.get(this._key(key));
     return values ? Array.from(values) : [];
   }
+
+  /**
+   * Gets the first value for a header (case-insensitive).
+   *
+   * @param key - Header name
+   * @returns First value or undefined if not present
+   */
   Get(key: string): string | undefined {
     const values = this._headers.get(this._key(key));
     if (values === undefined || values.size === 0) {
@@ -149,6 +212,14 @@ export class HttpHeader {
     }
     return values.values().next().value as string;
   }
+
+  /**
+   * Sets a header, replacing any existing values.
+   *
+   * @param key - Header name
+   * @param valueOr - Single value or array of values
+   * @returns This HttpHeader instance for chaining
+   */
   Set(key: string, valueOr: string | string[]): HttpHeader {
     const value = new Set((Array.isArray(valueOr) ? valueOr : [valueOr]).map((v) => v.trim()).filter((v) => v !== ""));
     if (value.size > 0) {
@@ -158,6 +229,14 @@ export class HttpHeader {
     }
     return this;
   }
+
+  /**
+   * Adds value(s) to a header, preserving existing values.
+   *
+   * @param key - Header name
+   * @param value - Single value, array of values, or undefined
+   * @returns This HttpHeader instance for chaining
+   */
   Add(key: string, value: string | string[] | undefined): HttpHeader {
     if (typeof value === "undefined") {
       return this;
@@ -176,18 +255,88 @@ export class HttpHeader {
       }, values);
     return this;
   }
+
+  /**
+   * Deletes a header.
+   *
+   * @param ey - Header name to delete
+   * @returns This HttpHeader instance for chaining
+   */
   Del(ey: string): HttpHeader {
     this._headers.delete(this._key(ey));
     return this;
   }
+
+  /**
+   * Returns all headers as key-value array pairs.
+   *
+   * Each entry is a tuple of [headerName, values[]] where headerName is
+   * lowercase and values is an array of all values for that header.
+   * Headers with no values are excluded.
+   *
+   * @returns Array of [name, values] tuples
+   *
+   * @example
+   * ```typescript
+   * const headers = new HttpHeader();
+   * headers.Add('Accept', ['application/json', 'text/html']);
+   * headers.Add('Content-Type', 'application/json');
+   *
+   * const items = headers.Items();
+   * // [
+   * //   ['accept', ['application/json', 'text/html']],
+   * //   ['content-type', ['application/json']]
+   * // ]
+   * ```
+   */
   Items(): [string, string[]][] {
     return Array.from(this._headers)
       .filter(([_, vs]) => vs.size > 0)
       .map(([k, vs]) => [k, Array.from(vs)]);
   }
+
+  /**
+   * Returns all headers as sorted key-value array pairs.
+   *
+   * Same as Items() but sorted alphabetically by header name.
+   *
+   * @returns Array of [name, values] tuples sorted by name
+   *
+   * @example
+   * ```typescript
+   * const headers = new HttpHeader();
+   * headers.Add('Content-Type', 'application/json');
+   * headers.Add('Accept', 'text/html');
+   *
+   * const sorted = headers.SortItems();
+   * // [
+   * //   ['accept', ['text/html']],
+   * //   ['content-type', ['application/json']]
+   * // ]
+   * ```
+   */
   SortItems(): [string, string[]][] {
     return this.Items().sort(([[a]], [[b]]) => a.localeCompare(b));
   }
+
+  /**
+   * Creates a deep copy of the HttpHeader instance.
+   *
+   * @returns New HttpHeader with the same headers
+   *
+   * @example
+   * ```typescript
+   * const original = new HttpHeader();
+   * original.Add('Content-Type', 'application/json');
+   *
+   * const copy = original.Clone();
+   * copy.Add('Accept', 'text/html');
+   *
+   * // original is unchanged
+   * original.Get('Accept'); // undefined
+   * copy.Get('Accept'); // 'text/html'
+   * ```
+   */
   Clone(): HttpHeader {
     const clone = new HttpHeader();
     for (const [key, values] of this._headers.entries()) {
@@ -195,6 +344,27 @@ export class HttpHeader {
     }
     return clone;
   }
+  /**
+   * Converts headers to a plain object with string array values.
+   *
+   * Each header name maps to an array of all its values. Useful for
+   * serialization or when working with APIs that expect this format.
+   *
+   * @returns Object with header names as keys and string arrays as values
+   *
+   * @example
+   * ```typescript
+   * const headers = new HttpHeader();
+   * headers.Add('Accept', ['application/json', 'text/html']);
+   * headers.Add('Content-Type', 'application/json');
+   *
+   * const obj = headers.AsRecordStringStringArray();
+   * // {
+   * //   'accept': ['application/json', 'text/html'],
+   * //   'content-type': ['application/json']
+   * // }
+   * ```
+   */
   AsRecordStringStringArray(): Record<string, string[]> {
     const obj: Record<string, string[]> = {};
     for (const [key, values] of this._headers.entries()) {
@@ -202,6 +372,28 @@ export class HttpHeader {
     }
     return obj;
   }
+
+  /**
+   * Converts headers to a plain object with comma-separated string values.
+   *
+   * Multiple values for the same header are joined with ", ". Useful for
+   * compatibility with APIs that expect single string values per header.
+   *
+   * @returns Object with header names as keys and comma-separated strings as values
+   *
+   * @example
+   * ```typescript
+   * const headers = new HttpHeader();
+   * headers.Add('Accept', ['application/json', 'text/html']);
+   * headers.Add('Content-Type', 'application/json');
+   *
+   * const obj = headers.AsRecordStringString();
+   * // {
+   * //   'accept': 'application/json, text/html',
+   * //   'content-type': 'application/json'
+   * // }
+   * ```
+   */
   AsRecordStringString(): Record<string, string> {
     const obj: Record<string, string> = {};
     for (const [key, values] of this._headers.entries()) {
@@ -209,7 +401,29 @@ export class HttpHeader {
     }
     return obj;
   }
-  // Need for CF own HeadersInit type
+
+  /**
+   * Converts headers to HeadersInit format with only first value per header.
+   *
+   * Only the first value is used when multiple values exist for a header.
+   * Needed for Cloudflare Workers' HeadersInit type compatibility.
+   *
+   * @template H - HeadersInit type (for type compatibility)
+   * @returns Object compatible with HeadersInit
+   *
+   * @example
+   * ```typescript
+   * const headers = new HttpHeader();
+   * headers.Add('Accept', ['application/json', 'text/html']);
+   * headers.Add('Content-Type', 'application/json');
+   *
+   * const init = headers.AsHeaderInit();
+   * // {
+   * //   'accept': 'application/json',  // only first value
+   * //   'content-type': 'application/json'
+   * // }
+   * ```
+   */
   AsHeaderInit<H extends HeadersInit>(): H {
     const obj: Record<string, string> = {};
     for (const [key, values] of this._headers.entries()) {
@@ -220,9 +434,49 @@ export class HttpHeader {
     }
     return obj as H;
   }
+
+  /**
+   * Converts to native Headers implementation.
+   *
+   * Multiple values are joined with ", " as per HTTP spec.
+   *
+   * @returns HeadersImpl instance compatible with standard Headers interface
+   *
+   * @example
+   * ```typescript
+   * const headers = new HttpHeader();
+   * headers.Add('Content-Type', 'application/json');
+   *
+   * const nativeHeaders = headers.AsHeaders();
+   * nativeHeaders.get('content-type'); // 'application/json'
+   * ```
+   */
   AsHeaders(): HeadersImpl {
     return new HeadersImpl(this._asStringString());
   }
+
+  /**
+   * Merges other headers into this instance (in-place mutation).
+   *
+   * Adds all headers from the provided sources to this instance.
+   * If headers already exist, values are added (not replaced).
+   *
+   * @param other - One or more header sources to merge
+   * @returns This HttpHeader instance for chaining
+   *
+   * @example
+   * ```typescript
+   * const headers = new HttpHeader();
+   * headers.Add('Content-Type', 'application/json');
+   *
+   * headers.MergeInplace(
+   *   { 'Accept': 'text/html' },
+   *   new Headers({ 'Authorization': 'Bearer token' })
+   * );
+   *
+   * // headers now contains all three headers
+   * ```
+   */
   MergeInplace(...other: CoercedHeadersInit[]): HttpHeader {
     for (const h of other.map((h) => HttpHeader.coerce(h))) {
       for (const [key, values] of h.Items()) {
@@ -231,6 +485,28 @@ export class HttpHeader {
     }
     return this;
   }
+
+  /**
+   * Merges other headers, returning a new instance.
+   *
+   * Creates a clone of this instance and merges the provided headers into it.
+   * The original instance remains unchanged.
+   *
+   * @param other - One or more header sources to merge
+   * @returns New HttpHeader with merged headers
+   *
+   * @example
+   * ```typescript
+   * const headers1 = new HttpHeader();
+   * headers1.Add('Content-Type', 'application/json');
+   *
+   * const headers2 = headers1.Merge({ 'Accept': 'text/html' });
+   *
+   * // headers1 is unchanged
+   * headers1.Get('Accept'); // undefined
+   * headers2.Get('Accept'); // 'text/html'
+   * ```
+   */
   Merge(...other: CoercedHeadersInit[]): HttpHeader {
     return this.Clone().MergeInplace(...other);
   }

package/src/index.ts

@@ -31,9 +31,7 @@ export * from "./mutable-url.js";
 export * from "./poller.js";
 export * from "./on-func.js";
 export * from "./timeouted.js";
+export * from "./promise-sleep.js";
 
-// ugly
+// ugly not really esm but how could that work otherwise?
 export * as utils from "./utils/index.js";
-// import * as utils from "./utils/index.js";
-
-// export const param = utils.param;

package/src/is-json.ts

@@ -7,6 +7,27 @@ export interface IsJSONResult<T> {
   readonly parsed?: T;
 }
 
+/**
+ * Checks if a string contains valid JSON and optionally parses it.
+ *
+ * Uses a regex pre-check to quickly eliminate non-JSON strings before attempting
+ * to parse. Returns both a boolean flag and the parsed result if successful.
+ *
+ * @template T - The expected type of the parsed JSON (default: unknown)
+ * @param str - The string to check and parse
+ * @returns Object with isJSON boolean and optional parsed value
+ *
+ * @example
+ * ```typescript
+ * const result = isJSON<{ name: string }>('{"name": "Alice"}');
+ * if (result.isJSON) {
+ *   console.log(result.parsed.name); // "Alice"
+ * }
+ *
+ * const invalid = isJSON('not json');
+ * console.log(invalid.isJSON); // false
+ * ```
+ */
 export function isJSON<T = unknown>(str: string): IsJSONResult<T> {
   if (possibleJSONre.test(str)) {
     try {

package/src/is-promise.ts

@@ -7,6 +7,25 @@ export type Promisable<T> = T | Promise<T>;
 
 export type NonPromise<T> = T extends Promise<never> ? never : T;
 
+/**
+ * Type guard to check if a value is a Promise or Promise-like (thenable).
+ *
+ * Checks both for instanceof Promise and for objects with then/catch/finally methods,
+ * allowing it to work with Promise-like objects from different execution contexts.
+ *
+ * @template R - The Promise type
+ * @template T - The resolved value type
+ * @param a - The value to check
+ * @returns True if the value is a Promise or thenable
+ *
+ * @example
+ * ```typescript
+ * const value: unknown = fetchData();
+ * if (isPromise(value)) {
+ *   const result = await value;
+ * }
+ * ```
+ */
 export function isPromise<R extends Promise<T>, T>(a: unknown): a is R {
   const mayBe = a as { then: () => void; catch: () => void; finally: () => void };
   return (
@@ -21,6 +40,13 @@ export function isPromise<R extends Promise<T>, T>(a: unknown): a is R {
   );
 }
 
+/**
+ * Type guard to check if a value is NOT a Promise.
+ *
+ * @template T - The value type
+ * @param a - The value to check
+ * @returns The value cast to type T if it's not a Promise
+ */
 export function isNotPromise<T>(a: T): T {
   return !isPromise(a) as T;
 }

package/src/lru-map-set.ts

@@ -11,6 +11,25 @@ interface MutableLRUParam<T, K> {
 
 export type LRUParam<T = string, K = string> = Readonly<MutableLRUParam<T, K>>;
 
+/**
+ * A Set implementation with Least Recently Used (LRU) eviction policy.
+ *
+ * LRUSet maintains a set of values with automatic eviction of least recently
+ * accessed items when capacity limits are reached. Items are moved to the end
+ * of the access order when accessed.
+ *
+ * @template T - The type of values in the set
+ *
+ * @example
+ * ```typescript
+ * const cache = new LRUSet<string>({ maxEntries: 3 });
+ * cache.add('a');
+ * cache.add('b');
+ * cache.add('c');
+ * cache.add('d'); // 'a' is evicted
+ * console.log(cache.has('a')); // false
+ * ```
+ */
 export class LRUSet<T> {
   readonly #lruMap: LRUMap<T, T>;
 
@@ -84,6 +103,33 @@ function defaultRefresh<V, K>(param: LRUParam<V, K>, map: LRUMap<K, V>): void {
   }
 }
 
+/**
+ * A Map implementation with Least Recently Used (LRU) eviction policy.
+ *
+ * LRUMap maintains key-value pairs with automatic eviction of least recently
+ * accessed items when capacity limits are reached. Provides configurable
+ * eviction and refresh strategies, event callbacks, and access statistics.
+ *
+ * @template K - The type of keys in the map
+ * @template V - The type of values in the map
+ *
+ * @example
+ * ```typescript
+ * const cache = new LRUMap<string, number>({ maxEntries: 100 });
+ *
+ * // Add items
+ * cache.set('key1', 42);
+ * cache.set('key2', 100);
+ *
+ * // Get items (updates access order)
+ * const value = cache.get('key1');
+ *
+ * // Listen for evictions
+ * const unregister = cache.onDelete((key, value) => {
+ *   console.log(`Evicted: ${key} = ${value}`);
+ * });
+ * ```
+ */
 export class LRUMap<K, V> {
   private _map: Map<K, LRUItem<V>> = new Map<K, LRUItem<V>>();
   private param: MutableLRUParam<V, K>;