@adviser/cement 0.4.62 → 0.4.64-dev

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

@@ -32,6 +32,7 @@ export * from "./poller.js";
 export * from "./on-func.js";
 export * from "./timeouted.js";
 export * from "./promise-sleep.js";
+export * from "./keyed-ng.js";
 
 // ugly not really esm but how could that work otherwise?
 export * as utils from "./utils/index.js";

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;
 }