@adviser/cement 0.4.62 → 0.4.64-dev

package/src/result.ts

@@ -1,5 +1,32 @@
 import { isPromise } from "./is-promise.js";
 
+/**
+ * Result type for representing success (Ok) or failure (Err) values.
+ *
+ * Result is a type-safe way to handle operations that can fail, similar to Rust's
+ * Result type. It forces explicit handling of both success and error cases without
+ * throwing exceptions.
+ *
+ * @template T - The type of the success value
+ * @template E - The type of the error (default: Error)
+ *
+ * @example
+ * ```typescript
+ * function divide(a: number, b: number): Result<number> {
+ *   if (b === 0) {
+ *     return Result.Err('Division by zero');
+ *   }
+ *   return Result.Ok(a / b);
+ * }
+ *
+ * const result = divide(10, 2);
+ * if (result.isOk()) {
+ *   console.log('Result:', result.unwrap());
+ * } else {
+ *   console.error('Error:', result.unwrap_err());
+ * }
+ * ```
+ */
 export abstract class Result<T, E = Error> {
   static Ok<T = void>(...args: T[]): Result<T, Error> {
     return args.length >= 1 ? new ResultOK<T>(args[0]) : new ResultOK<T>(undefined as unknown as T);
@@ -95,6 +122,29 @@ export type WithoutResult<T> = T extends Result<infer U> ? U : T;
 // type WithoutPromise<T> = T extends Promise<infer U> ? U : T;
 type WithResult<T> = T extends Promise<infer U> ? Promise<Result<U>> : Result<T>;
 
+/**
+ * Wraps a function to convert thrown exceptions into Result.Err values.
+ *
+ * Executes the provided function and returns Result.Ok on success or Result.Err
+ * on thrown exceptions. Supports both synchronous and asynchronous functions.
+ *
+ * @template FN - Function type that returns T or Promise<T>
+ * @template T - The return type of the function
+ * @param fn - Function to execute with exception handling
+ * @returns Result<T> for sync functions, Promise<Result<T>> for async functions
+ *
+ * @example
+ * ```typescript
+ * const result = exception2Result(() => {
+ *   return JSON.parse('invalid json');
+ * });
+ * // result is Result.Err with parse error
+ *
+ * const asyncResult = await exception2Result(async () => {
+ *   return await fetch('/api/data');
+ * });
+ * ```
+ */
 export function exception2Result<FN extends () => Promise<T> | T, T>(fn: FN): WithResult<ReturnType<FN>> {
   try {
     const res = fn();

package/src/runtime.ts

@@ -1,11 +1,51 @@
+/**
+ * Runtime environment detection result.
+ *
+ * Provides boolean flags indicating which JavaScript runtime environment
+ * the code is currently executing in. Only one flag should be true at a time,
+ * allowing for runtime-specific behavior and feature detection.
+ *
+ * @example
+ * ```typescript
+ * const runtime = runtimeFn();
+ * if (runtime.isNodeIsh) {
+ *   console.log('Running in Node.js or Bun');
+ * } else if (runtime.isBrowser) {
+ *   console.log('Running in a browser');
+ * }
+ * ```
+ */
 export interface Runtime {
+  /** True if running in Node.js or Node-compatible runtime (e.g., Bun) */
   isNodeIsh: boolean;
+  /** True if running in a web browser */
   isBrowser: boolean;
+  /** True if running in Deno */
   isDeno: boolean;
+  /** True if running in React Native */
   isReactNative: boolean;
+  /** True if running in Cloudflare Workers */
   isCFWorker: boolean;
 }
 
+/**
+ * Checks if a nested property path exists on an object.
+ *
+ * Recursively traverses dot-separated property paths to determine if they exist
+ * and are truthy. Used internally for runtime environment detection by checking
+ * for environment-specific global objects.
+ *
+ * @param value - Dot-separated property path to check (e.g., "process.versions.node")
+ * @param ref - Object to check properties on (defaults to globalThis)
+ * @returns True if the full path exists and all values are truthy
+ *
+ * @example
+ * ```typescript
+ * isSet("process.versions.node"); // true in Node.js
+ * isSet("Deno"); // true in Deno
+ * isSet("navigator.userAgent"); // true in browsers
+ * ```
+ */
 function isSet(value: string, ref: Record<string, unknown> = globalThis): boolean {
   const [head, ...tail] = value.split(".");
   if (["object", "function"].includes(typeof ref) && ref && ["object", "function"].includes(typeof ref[head]) && ref[head]) {
@@ -17,8 +57,41 @@ function isSet(value: string, ref: Record<string, unknown> = globalThis): boolea
   return false;
 }
 
-// caches.default or WebSocketPair
-
+/**
+ * Detects the current JavaScript runtime environment.
+ *
+ * Performs feature detection to identify which runtime environment the code
+ * is executing in. Checks for environment-specific global objects and APIs
+ * in priority order:
+ * 1. Cloudflare Workers (caches.default + WebSocketPair)
+ * 2. React Native (navigator.product === "ReactNative")
+ * 3. Deno (global Deno object)
+ * 4. Node.js (process.versions.node)
+ * 5. Browser (none of the above)
+ *
+ * The detection is mutually exclusive - only one environment flag will be true.
+ *
+ * @returns Runtime object with boolean flags for each environment
+ *
+ * @example
+ * ```typescript
+ * const runtime = runtimeFn();
+ *
+ * if (runtime.isNodeIsh) {
+ *   // Use Node.js APIs
+ *   const fs = require('fs');
+ * } else if (runtime.isBrowser) {
+ *   // Use browser APIs
+ *   console.log(window.location.href);
+ * } else if (runtime.isDeno) {
+ *   // Use Deno APIs
+ *   const file = await Deno.readTextFile('./config.json');
+ * } else if (runtime.isCFWorker) {
+ *   // Use Cloudflare Workers APIs
+ *   const cache = caches.default;
+ * }
+ * ```
+ */
 export function runtimeFn(): Runtime {
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   const gt: any = globalThis;

package/src/sys-env.ts

@@ -49,6 +49,26 @@ const envActions: { id: string; fn: EnvFactoryFn }[] = [
   { id: "browser", fn: (opts: Partial<EnvFactoryOpts>): EnvActions => BrowserEnvActions.new(opts) },
 ];
 
+/**
+ * Registers a custom environment action factory.
+ *
+ * Allows registration of platform-specific environment implementations.
+ * The factory is added to the beginning of the search list and will be
+ * tried first when creating new Env instances.
+ *
+ * @param fn - Factory function that creates EnvActions for a platform
+ * @returns Unregister function to remove the factory
+ *
+ * @example
+ * ```typescript
+ * const unregister = registerEnvAction((opts) => {
+ *   return new CustomEnvActions(opts);
+ * });
+ *
+ * // Later, remove the factory
+ * unregister();
+ * ```
+ */
 export function registerEnvAction(fn: EnvFactoryFn): () => void {
   const id = `id-${Math.random()}`;
   envActions.unshift({ id, fn });
@@ -63,6 +83,43 @@ export function registerEnvAction(fn: EnvFactoryFn): () => void {
 }
 
 const _envFactories = new KeyedResolvOnce<Env>();
+
+/**
+ * Creates a platform-appropriate environment variable interface.
+ *
+ * Automatically detects the runtime environment (Node.js, Deno, browser,
+ * Cloudflare Workers) and returns an Env instance with platform-specific
+ * implementations. Supports preset values, change notifications, and
+ * type-safe multi-key retrieval.
+ *
+ * @param opts - Optional configuration:
+ *   - symbol: Key for browser environment storage (default: "CP_ENV")
+ *   - presetEnv: Map of preset environment variables
+ *   - testPatchImportMetaEnv: Test values to patch into import.meta.env
+ *   - id: Identifier for caching/reinitialization
+ *
+ * @returns Env instance for the detected platform
+ * @throws Error if no compatible environment is detected
+ *
+ * @example
+ * ```typescript
+ * const env = envFactory();
+ *
+ * // Get single value
+ * const apiKey = env.get('API_KEY');
+ *
+ * // Get multiple values with Result
+ * const config = env.gets('DB_HOST', 'DB_PORT', 'DB_NAME');
+ * if (config.isOk()) {
+ *   const { DB_HOST, DB_PORT, DB_NAME } = config.unwrap();
+ * }
+ *
+ * // Listen for changes
+ * env.onSet((key, value) => {
+ *   console.log(`${key} changed to ${value}`);
+ * }, 'API_KEY'); // Optional: filter by specific keys
+ * ```
+ */
 export function envFactory(opts: Partial<EnvFactoryOpts> = {}): Env {
   const found = envActions.find((fi) => fi.fn(opts).active());
   if (!found) {

package/src/timeouted.ts

@@ -61,22 +61,58 @@ export interface TimeoutActionOptions<CTX> {
 // TYPE GUARDS
 // ============================================================================
 
+/**
+ * Type guard to check if a TimeoutResult represents a successful completion.
+ *
+ * @template T - The type of the result value
+ * @param result - The TimeoutResult to check
+ * @returns True if the result state is "success"
+ */
 export function isSuccess<T>(result: TimeoutResult<T>): result is TimeoutResultSuccess<T> {
   return result.state === "success";
 }
 
+/**
+ * Type guard to check if a TimeoutResult represents a timeout.
+ *
+ * @template T - The type of the result value
+ * @param result - The TimeoutResult to check
+ * @returns True if the result state is "timeout"
+ */
 export function isTimeout<T>(result: TimeoutResult<T>): result is TimeoutResultTimeout<T> {
   return result.state === "timeout";
 }
 
+/**
+ * Type guard to check if a TimeoutResult was aborted via AbortSignal.
+ *
+ * @template T - The type of the result value
+ * @param result - The TimeoutResult to check
+ * @returns True if the result state is "aborted"
+ */
 export function isAborted<T>(result: TimeoutResult<T>): result is TimeoutResultAborted<T> {
   return result.state === "aborted";
 }
 
+/**
+ * Type guard to check if a TimeoutResult represents an error during execution.
+ *
+ * @template T - The type of the result value
+ * @param result - The TimeoutResult to check
+ * @returns True if the result state is "error"
+ */
 export function isError<T>(result: TimeoutResult<T>): result is TimeoutResultError<T> {
   return result.state === "error";
 }
 
+/**
+ * Extracts the value from a successful TimeoutResult or throws an error.
+ *
+ * @template T - The type of the result value
+ * @param result - The TimeoutResult to unwrap
+ * @returns The success value
+ * @throws Error if the result is not in success state
+ */
 export function unwrap<T>(result: TimeoutResult<T>): T {
   if (isSuccess(result)) {
     return result.value;
@@ -84,10 +120,66 @@ export function unwrap<T>(result: TimeoutResult<T>): T {
   throw new Error(`TimeoutResult is not success: ${result.state}`);
 }
 
+/**
+ * Extracts the value from a successful TimeoutResult or returns a default value.
+ *
+ * @template T - The type of the result value
+ * @param result - The TimeoutResult to unwrap
+ * @param defaultValue - The value to return if result is not successful
+ * @returns The success value or the default value
+ */
 export function unwrapOr<T>(result: TimeoutResult<T>, defaultValue: T): T {
   return isSuccess(result) ? result.value : defaultValue;
 }
 
+/**
+ * Executes an action with comprehensive timeout and abort handling.
+ *
+ * Wraps a promise or async function with timeout, abort signal, and error handling capabilities.
+ * The action can be controlled via AbortController and will properly clean up resources.
+ *
+ * @template T - The type of the action's result value
+ * @template CTX - Optional context type passed through to callbacks
+ * @param action - Either a Promise or a function that receives an AbortController and returns a Promise
+ * @param options - Optional configuration:
+ *   - timeout: Timeout duration in milliseconds (default: 30000). Set to 0 or negative to disable.
+ *   - signal: External AbortSignal to link for cancellation
+ *   - controller: External AbortController to use instead of creating a new one
+ *   - ctx: Context object passed through in the result
+ *   - onTimeout: Callback invoked when timeout occurs
+ *   - onAbort: Callback invoked when aborted (with abort reason)
+ *   - onError: Callback invoked when action throws an error
+ *   - onAbortAction: Callback for cleanup when action needs to be aborted
+ *
+ * @returns Promise resolving to a TimeoutResult containing:
+ *   - state: "success" | "timeout" | "aborted" | "error"
+ *   - value (if success), error (if error), or reason (if aborted)
+ *   - duration: Elapsed time in milliseconds
+ *   - ctx: The context object if provided
+ *
+ * @example
+ * ```typescript
+ * // With a function that can be aborted
+ * const result = await timeouted(
+ *   async (controller) => {
+ *     return fetch(url, { signal: controller.signal });
+ *   },
+ *   { timeout: 5000 }
+ * );
+ *
+ * if (isSuccess(result)) {
+ *   console.log('Request completed:', result.value);
+ * } else if (isTimeout(result)) {
+ *   console.log('Request timed out after', result.duration, 'ms');
+ * }
+ *
+ * // With a direct promise
+ * const result2 = await timeouted(
+ *   fetch(url),
+ *   { timeout: 3000 }
+ * );
+ * ```
+ */
 export async function timeouted<T, CTX = void>(
   action: TimeoutAction<T>,
   options: Partial<TimeoutActionOptions<CTX>> = {},

package/src/tracer.ts

@@ -24,6 +24,24 @@ export type TraceCtxParam = {
 }> &
   Record<string, unknown>;
 
+/**
+ * Represents a single metric value that can be tracked and accumulated.
+ *
+ * Metrics can store any type of value and support addition operations
+ * for numbers and arrays. Used within the tracing system to collect
+ * performance data and custom measurements.
+ *
+ * @template T - The type of the metric value
+ *
+ * @example
+ * ```typescript
+ * const counter = new Metric<number>('/api/requests');
+ * counter.set(0);
+ * counter.add(1);
+ * counter.add(5);
+ * console.log(counter.value); // 6
+ * ```
+ */
 export class Metric<T> {
   value?: T;
   readonly path: string;
@@ -55,6 +73,29 @@ export class Metric<T> {
 
 export type MetricMap = Map<string, Metric<unknown>>;
 
+/**
+ * Container for managing multiple metrics within a trace span.
+ *
+ * Metrics provides hierarchical metric management with path-based access.
+ * Metrics can be defined at absolute paths (starting with /) or relative
+ * to the current trace span. Supports JSON serialization of all metrics.
+ *
+ * @example
+ * ```typescript
+ * const metrics = new Metrics(traceNode);
+ *
+ * // Absolute path
+ * const totalRequests = metrics.get<number>('/api/total_requests');
+ * totalRequests.set(100);
+ *
+ * // Relative path (uses trace node's root path)
+ * const spanRequests = metrics.get<number>('requests');
+ * spanRequests.add(1);
+ *
+ * // Export as JSON
+ * const data = metrics.toJSON();
+ * ```
+ */
 export class Metrics {
   readonly tracenode: TraceNode;
   private readonly map: MetricMap;

package/src/txt-en-decoder.ts

@@ -1,4 +1,4 @@
-import { ResolveOnce } from "./resolve-once.js";
+import { Lazy } from "./resolve-once.js";
 import { Result } from "./result.js";
 import { coerceIntoUint8, ToUInt8 } from "./utils/coerce-uint8.js";
 
@@ -50,7 +50,4 @@ class TxtOps implements TxtEnDecoder {
   }
 }
 
-const txtEnDecoder = new ResolveOnce<TxtEnDecoder>();
-export function TxtEnDecoderSingleton(): TxtEnDecoder {
-  return txtEnDecoder.once(() => new TxtOps());
-}
+export const TxtEnDecoderSingleton: () => TxtEnDecoder = Lazy((): TxtEnDecoder => new TxtOps());

package/src/uri.ts

@@ -16,9 +16,6 @@ export interface IsURIResult {
   readonly uri?: URI;
 }
 
-/** @xdeprecated use param from get-params-result */
-// export const key = param;
-
 /*
   if KeyParam is a Object
      if the right side is a string, it is the default value
@@ -172,6 +169,24 @@ function ensureURLWithDefaultProto<T>(
   }
 }
 
+/**
+ * Type guard to check if a value is a URL object.
+ *
+ * Checks both for instanceof URL and for objects with URL-like properties
+ * (searchParams object with sort method, hash string), allowing it to work
+ * with URL objects from different execution contexts.
+ *
+ * @param value - The value to check
+ * @returns True if the value is a URL or URL-like object
+ *
+ * @example
+ * ```typescript
+ * const value: unknown = new URL('https://example.com');
+ * if (isURL(value)) {
+ *   console.log(value.hostname); // "example.com"
+ * }
+ * ```
+ */
 export function isURL(value: unknown): value is URL {
   return (
     value instanceof URL ||
@@ -263,6 +278,31 @@ function setParams(
   return out.toString();
 }
 
+/**
+ * Mutable builder for constructing and manipulating URIs.
+ *
+ * BuildURI provides a fluent API for constructing URIs by chaining method calls.
+ * Unlike URI, BuildURI is mutable and allows modification of all URI components
+ * (protocol, hostname, port, pathname, search params, hash).
+ *
+ * @example
+ * ```typescript
+ * const uri = BuildURI.from('https://example.com')
+ *   .pathname('/api/users')
+ *   .setParam('page', '1')
+ *   .setParam('limit', '10')
+ *   .toString();
+ * // Result: "https://example.com/api/users?limit=10&page=1"
+ *
+ * // Building from scratch
+ * const uri2 = BuildURI.from()
+ *   .protocol('https')
+ *   .hostname('api.example.com')
+ *   .port('8080')
+ *   .pathname('/v1/data')
+ *   .URI(); // Convert to immutable URI
+ * ```
+ */
 export class BuildURI implements URIInterface<BuildURI> {
   _url: WritableURL; // pathname needs this
   private constructor(url: WritableURL) {
@@ -493,7 +533,39 @@ export const hasHostPartProtocols: Set<string> = new Set<string>(["http", "https
 const uriInstances = new KeyedResolvOnce<URI>({
   lru: { maxEntries: 1000 },
 });
-// non mutable URL Implementation
+
+/**
+ * Immutable URI representation with type-safe parameter handling.
+ *
+ * URI provides a read-only view of a URL with convenient methods for accessing
+ * components and query parameters. All URI instances are cached for performance.
+ * Use BuildURI for mutable construction and URI for immutable references.
+ *
+ * @example
+ * ```typescript
+ * const uri = URI.from('https://example.com/path?key=value&foo=bar');
+ *
+ * // Access components
+ * console.log(uri.protocol);  // "https:"
+ * console.log(uri.hostname);  // "example.com"
+ * console.log(uri.pathname);  // "/path"
+ *
+ * // Query parameters
+ * const key = uri.getParam('key');  // "value"
+ * const missing = uri.getParam('missing', 'default');  // "default"
+ *
+ * // Type-safe parameter extraction with Result
+ * const result = uri.getParamsResult('key', 'foo');
+ * if (result.isOk()) {
+ *   const { key, foo } = result.unwrap();
+ * }
+ *
+ * // Build a modified version
+ * const modified = uri.build()
+ *   .setParam('new', 'param')
+ *   .URI();
+ * ```
+ */
 export class URI implements URIInterface<URI> {
   static protocolHasHostpart(protocol: string): () => void {
     protocol = protocol.replace(/:$/, "");

package/src/utils/coerce-uint8.ts

@@ -18,6 +18,37 @@ export type ToUInt8Async = ToUInt8Plain | Blob;
 export type ToUInt8 = ToUInt8Plain | Result<ToUInt8Plain>;
 export type AsyncToUInt8 = ToUInt8Async | Result<ToUInt8Async> | Promise<ToUInt8Async> | Promise<Result<ToUInt8Async>>;
 
+/**
+ * Coerces various binary types into Uint8Array with Result-based error handling.
+ *
+ * Converts ArrayBuffer, ArrayBufferView, Node.js Buffer, or Result-wrapped values
+ * into Uint8Array. Returns Result.Err for unsupported types like Blob (use
+ * asyncCoerceIntoUint8 for Blobs). Handles Result-wrapped inputs by unwrapping
+ * and recursively coercing.
+ *
+ * @param raw - Binary data to coerce (ArrayBuffer, TypedArray, Buffer, or Result-wrapped)
+ * @returns Result.Ok with Uint8Array or Result.Err with error message
+ *
+ * @example
+ * ```typescript
+ * // ArrayBuffer
+ * const result1 = coerceIntoUint8(new ArrayBuffer(10));
+ * if (result1.isOk()) {
+ *   const bytes = result1.unwrap(); // Uint8Array
+ * }
+ *
+ * // TypedArray
+ * const result2 = coerceIntoUint8(new Int32Array([1, 2, 3]));
+ *
+ * // Result-wrapped input
+ * const wrapped = Result.Ok(new ArrayBuffer(5));
+ * const result3 = coerceIntoUint8(wrapped); // Unwraps and converts
+ *
+ * // Blob not supported (use asyncCoerceIntoUint8)
+ * const result4 = coerceIntoUint8(new Blob(['data']));
+ * // Returns Result.Err("Blob not supported")
+ * ```
+ */
 export function coerceIntoUint8(raw: ToUInt8): Result<Uint8Array> {
   if (raw instanceof ArrayBuffer) {
     return Result.Ok(new Uint8Array(raw));
@@ -43,6 +74,35 @@ export function coerceIntoUint8(raw: ToUInt8): Result<Uint8Array> {
   return Result.Err("Not a Uint8Array");
 }
 
+/**
+ * Asynchronously coerces various binary types including Blob into Uint8Array.
+ *
+ * Handles all types supported by coerceIntoUint8 plus async operations:
+ * - Promise-wrapped values
+ * - Blob (converts via arrayBuffer())
+ * - Result-wrapped Promises
+ *
+ * @param raw - Binary data or Promise thereof (including Blob)
+ * @returns Promise resolving to Result.Ok with Uint8Array or Result.Err
+ *
+ * @example
+ * ```typescript
+ * // Blob support
+ * const blob = new Blob(['Hello, World!']);
+ * const result1 = await asyncCoerceIntoUint8(blob);
+ * if (result1.isOk()) {
+ *   const bytes = result1.unwrap();
+ * }
+ *
+ * // Promise-wrapped
+ * const promise = fetch('/data').then(r => r.arrayBuffer());
+ * const result2 = await asyncCoerceIntoUint8(promise);
+ *
+ * // Result-wrapped Promise
+ * const wrapped = Promise.resolve(Result.Ok(new ArrayBuffer(10)));
+ * const result3 = await asyncCoerceIntoUint8(wrapped);
+ * ```
+ */
 export async function asyncCoerceIntoUint8(raw: AsyncToUInt8): Promise<Result<Uint8Array>> {
   let resolved = await raw;
   if (resolved instanceof Blob) {

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