@adviser/cement 0.5.0 → 0.5.2

package/src/timeouted.ts

@@ -0,0 +1,355 @@
+import { Future } from "./future.js";
+import { isPromise } from "./is-promise.js";
+import { sleep } from "./promise-sleep.js";
+
+export interface IsTimeouted {
+  isSuccess(): this is TimeoutResultSuccess<unknown>;
+  isTimeout(): this is TimeoutResultTimeout<unknown>;
+  isAborted(): this is TimeoutResultAborted<unknown>;
+  isError(): this is TimeoutResultError<unknown>;
+}
+
+const IsTimeoutedImpl: IsTimeouted = {
+  isSuccess(): this is TimeoutResultSuccess<unknown> {
+    return (this as TimeoutResult<unknown>).state === "success";
+  },
+  isTimeout(): this is TimeoutResultTimeout<unknown> {
+    return (this as TimeoutResult<unknown>).state === "timeout";
+  },
+  isAborted(): this is TimeoutResultAborted<unknown> {
+    return (this as TimeoutResult<unknown>).state === "aborted";
+  },
+  isError(): this is TimeoutResultError<unknown> {
+    return (this as TimeoutResult<unknown>).state === "error";
+  },
+};
+
+export interface PurTimeoutState {
+  readonly state: "success" | "timeout" | "aborted" | "error";
+}
+
+export interface PurTimeoutResultSuccess<T> extends IsTimeouted, PurTimeoutState {
+  readonly state: "success";
+  readonly value: T;
+}
+
+export interface PurTimeoutResultTimeout extends IsTimeouted, PurTimeoutState {
+  readonly state: "timeout";
+}
+export interface PurTimeoutResultAborted extends IsTimeouted, PurTimeoutState {
+  readonly state: "aborted";
+  readonly reason: unknown;
+}
+export interface PurTimeoutResultError extends IsTimeouted, PurTimeoutState {
+  readonly state: "error";
+  readonly error: Error;
+}
+
+export interface TimeoutState<CTX> {
+  readonly duration: number;
+  readonly ctx: CTX;
+}
+
+type PurTimeoutResult<T> = PurTimeoutResultSuccess<T> | PurTimeoutResultTimeout | PurTimeoutResultAborted | PurTimeoutResultError;
+
+export type TimeoutResultSuccess<T, CTX = unknown> = PurTimeoutResultSuccess<T> & TimeoutState<CTX>;
+export type TimeoutResultTimeout<CTX = unknown> = PurTimeoutResultTimeout & TimeoutState<CTX>;
+export type TimeoutResultAborted<CTX = unknown> = PurTimeoutResultAborted & TimeoutState<CTX>;
+export type TimeoutResultError<CTX = unknown> = PurTimeoutResultError & TimeoutState<CTX>;
+
+export type TimeoutResult<T, CTX = unknown> =
+  | TimeoutResultSuccess<T, CTX>
+  | TimeoutResultTimeout<CTX>
+  | TimeoutResultAborted<CTX>
+  | TimeoutResultError<CTX>;
+
+export type ObjTimeoutResultSuccess<T, CTX> = Omit<
+  PurTimeoutResultSuccess<T>,
+  "isSuccess" | "isTimeout" | "isAborted" | "isError"
+> &
+  Partial<IsTimeouted> &
+  Partial<TimeoutState<CTX>>;
+export type ObjTimeoutResultTimeout<CTX> = Omit<PurTimeoutResultTimeout, "isSuccess" | "isTimeout" | "isAborted" | "isError"> &
+  Partial<IsTimeouted> &
+  Partial<TimeoutState<CTX>>;
+export type ObjTimeoutResultAborted<CTX> = Omit<PurTimeoutResultAborted, "isSuccess" | "isTimeout" | "isAborted" | "isError"> &
+  Partial<IsTimeouted> &
+  Partial<TimeoutState<CTX>>;
+export type ObjTimeoutResultError<CTX> = Omit<PurTimeoutResultError, "isSuccess" | "isTimeout" | "isAborted" | "isError"> &
+  Partial<IsTimeouted> &
+  Partial<TimeoutState<CTX>>;
+type PurTimeoutResultObj<T, CTX = unknown> =
+  | ObjTimeoutResultSuccess<T, CTX>
+  | ObjTimeoutResultTimeout<CTX>
+  | ObjTimeoutResultAborted<CTX>
+  | ObjTimeoutResultError<CTX>;
+
+export function createTimeoutResult<T, CTX = unknown, TR extends PurTimeoutResultObj<T, CTX> = PurTimeoutResultObj<T, CTX>>(
+  t: TR,
+): TimeoutResult<T, CTX> {
+  return { ...IsTimeoutedImpl, duration: 0, ...t } as TimeoutResult<T, CTX>;
+}
+
+export type ActionFunc<T> = (controller: AbortController) => Promise<T>;
+
+// Action item in arrays - can be function or promise
+export type ActionItem<T> = ActionFunc<T> | Promise<T>;
+
+// Main action type - function, promise, or mixed array
+export type TimeoutAction<T> = ActionItem<T>;
+
+// Configuration options
+export interface TimeoutActionOptions<CTX> {
+  readonly timeout: number;
+  readonly signal: AbortSignal;
+  readonly controller: AbortController;
+  readonly ctx: CTX;
+  onTimeout: () => void;
+  onAbort: (reason: unknown) => void;
+  onError: (error: Error) => void;
+  // onAbortAction: (reason: unknown) => void;
+}
+
+// ============================================================================
+// 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;
+  }
+  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>> = {},
+): Promise<TimeoutResult<T>> {
+  const { timeout = 30000, signal, controller: externalController, ctx, onTimeout, onAbort, onError } = options;
+
+  const controller = externalController || new AbortController();
+  const startTime = Date.now();
+
+  const toRemoveEventListeners: (() => void)[] = [];
+
+  // Link external signal to internal controller
+  if (signal) {
+    function abortAction(): void {
+      controller.abort(signal?.reason);
+    }
+    toRemoveEventListeners.push(() => {
+      signal?.removeEventListener("abort", abortAction);
+    });
+    signal.addEventListener("abort", abortAction);
+  }
+  function cleanup<X extends PurTimeoutResult<T>>(result: X, skipCleanupAction = false): TimeoutResult<T, CTX> {
+    for (const evtFn of toRemoveEventListeners) {
+      evtFn();
+    }
+    toRemoveEventListeners.length = 0;
+    if (!skipCleanupAction) {
+      // void onAbortAction?.(signal?.reason);
+      controller.abort(new Error("Timeouted Abort Action"));
+    }
+    return {
+      ...result,
+      duration: Date.now() - startTime,
+      ctx: ctx as CTX,
+    } as TimeoutResult<T, CTX>;
+  }
+
+  let toAwait: Promise<T>;
+  if (isPromise(action)) {
+    toAwait = action;
+  } else {
+    try {
+      toAwait = action(controller);
+    } catch (error) {
+      return cleanup({
+        state: "error",
+        error: error instanceof Error ? error : new Error(error as string),
+        ...IsTimeoutedImpl,
+      });
+    }
+  }
+
+  const abortToAwait = new Future<TimeoutResult<T, CTX>>();
+  function onAbortHandler(): void {
+    abortToAwait.resolve(
+      createTimeoutResult<T, CTX>({
+        state: "aborted" as const,
+        reason: controller.signal.reason as unknown,
+        duration: Date.now() - startTime,
+        ctx: ctx as CTX,
+      }),
+    );
+  }
+  controller.signal.addEventListener("abort", onAbortHandler);
+  toRemoveEventListeners.push(() => {
+    controller.signal.removeEventListener("abort", onAbortHandler);
+  });
+
+  const toRace: Promise<PurTimeoutResult<T>>[] = [
+    toAwait
+      .then((value) =>
+        createTimeoutResult<T, CTX>({ state: "success" as const, value, duration: Date.now() - startTime, ctx: ctx as CTX }),
+      )
+      .catch((error: Error) =>
+        createTimeoutResult<T, CTX>({ state: "error" as const, error, duration: Date.now() - startTime, ctx: ctx as CTX }),
+      ),
+    abortToAwait.asPromise(),
+  ];
+  if (timeout > 0) {
+    toRace.push(
+      sleep(timeout, controller.signal).then((r): PurTimeoutResult<T> => {
+        switch (true) {
+          case r.isOk:
+            return createTimeoutResult<T, CTX>({ state: "timeout" as const, duration: Date.now() - startTime, ctx: ctx as CTX });
+          case r.isErr:
+            return createTimeoutResult<T, CTX>({
+              state: "error" as const,
+              error: r.error,
+              duration: Date.now() - startTime,
+              ctx: ctx as CTX,
+            });
+          case r.isAborted:
+            return createTimeoutResult<T, CTX>({
+              state: "aborted" as const,
+              reason: r.reason,
+              duration: Date.now() - startTime,
+              ctx: ctx as CTX,
+            });
+        }
+        throw new Error("Unreachable code in timeoutAction");
+      }),
+    );
+  }
+
+  const res = await Promise.race(toRace);
+  switch (true) {
+    case res.state === "success":
+      return cleanup(res);
+    case res.state === "aborted":
+      onAbort?.(res.reason);
+      return cleanup(res, true);
+    case res.state === "error":
+      onError?.(res.error);
+      return cleanup(res);
+    case res.state === "timeout":
+      onTimeout?.();
+      return cleanup(res, true);
+  }
+  throw new Error("Unreachable code in timeoutAction");
+}

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;
@@ -141,7 +182,7 @@ export class TraceNode {
     delete cleanCtx.time;
     delete cleanCtx.logger;
     delete cleanCtx.metrics;
-    const spanRefs = this.metrics.toJSON.call({ map: this.metrics.spanRefs }) as Record<string, unknown>;
+    const spanRefs = this.metrics.toJSON.call({ map: this.metrics.spanRefs });
     const metricsRefs = Object.keys(spanRefs).length > 0 ? { metricRefs: spanRefs } : {};
     return {
       ctx: cleanCtx,

package/src/txt-en-decoder.ts

@@ -1,6 +1,6 @@
-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";
+import { ToUInt8, coerceIntoUint8 } from "./utils/coerce-uint8.js";
 
 export type ToDecoder = ToUInt8 | string | Result<string>;
 export type AsyncToDecoder = ToDecoder | Blob | Promise<ToDecoder | Blob>;
@@ -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/types.ts

@@ -17,3 +17,49 @@ export const param: {
   OPTIONAL: new _Optional(),
 };
 export type param = (typeof param)[keyof typeof param];
+
+export type WithCement<T> = T & {
+  readonly cement: {
+    readonly runtimeFn: typeof import("./runtime.js").runtimeFn;
+    // readonly WrapperBasicSysAbstractionFactory: typeof import("./base-sys-abstraction.js").WrapperBasicSysAbstractionFactory;
+    readonly WrapperBasicSysAbstraction: typeof import("./base-sys-abstraction.js").WrapperBasicSysAbstraction;
+    readonly WrapperRuntimeSysAbstraction: typeof import("./base-sys-abstraction.js").WrapperRuntimeSysAbstraction;
+    readonly TxtEnDecoderSingleton: typeof import("./txt-en-decoder.js").TxtEnDecoderSingleton;
+    readonly ConsoleWriterStream: typeof import("./utils/console-write-stream.js").ConsoleWriterStream;
+    readonly envFactory: typeof import("./sys-env.js").envFactory;
+    readonly BaseBasicSysAbstraction: typeof import("./base-sys-abstraction.js").BaseBasicSysAbstraction;
+    readonly BaseSysAbstraction: typeof import("./base-sys-abstraction.js").BaseSysAbstraction;
+    readonly NodeBasicSysAbstraction: typeof import("./node-env/index.js").NodeBasicSysAbstraction;
+  };
+};
+
+export const hasHostPartProtocols: Set<string> = new Set<string>(["http", "https", "ws", "wss"]);
+
+export const Level = {
+  WARN: "warn",
+  DEBUG: "debug",
+  INFO: "info",
+  ERROR: "error",
+};
+
+export type Level = (typeof Level)[keyof typeof Level];
+
+export type Serialized = string | number | boolean;
+export type FnSerialized = () => Serialized | Serialized[];
+
+export class LogValue {
+  constructor(readonly fn: FnSerialized) {}
+  value(): Serialized | Serialized[] {
+    try {
+      // console.log("LogValue.value", this.fn.toString());
+      return this.fn();
+    } catch (e) {
+      return `LogValue:${(e as Error).message}`;
+    }
+  }
+  toJSON(): Serialized | Serialized[] {
+    return this.value();
+  }
+}
+
+export type LogSerializable = Record<string, LogValue | Promise<LogValue>>;

package/src/uri.ts

@@ -1,10 +1,10 @@
 import type { DeepWritable } from "ts-essentials";
 import { exception2Result, Result } from "./result.js";
-import { getParamsResult, KeysParam } from "./utils/get-params-result.js";
-import { relativePath } from "./utils/relative-path.js";
-import { StripCommand, stripper } from "./utils/stripper.js";
 import { ReadonlyURL, URLSearchParamsEntries, WritableURL } from "./mutable-url.js";
 import { KeyedResolvOnce } from "./resolve-once.js";
+import { KeysParam, getParamsResult, hasHostPartProtocols } from "./index.js";
+import { relativePath } from "./utils/relative-path.js";
+import { StripCommand, stripper } from "./utils/stripper.js";
 // import { param } from "./types.js";
 
 type NullOrUndef = null | undefined;
@@ -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) {
@@ -488,12 +528,42 @@ export function isCoerceURI(value: unknown): value is CoerceURI {
   return false;
 }
 
-export const hasHostPartProtocols: Set<string> = new Set<string>(["http", "https", "ws", "wss"]);
-
 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

@@ -1,4 +1,4 @@
-import { Result } from "../result.js";
+import { Result } from "@adviser/cement";
 
 // Tested in txt-en-decoder.test.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) {