@adviser/cement 0.4.62 → 0.4.64-dev

package/src/on-func.ts

@@ -38,6 +38,44 @@ interface ReturnOnFunc<Args extends any[]> {
 
 type ExtractArgs<T> = T extends (...args: infer A) => unknown ? A : never;
 
+/**
+ * Creates a type-safe event emitter for a specific function signature.
+ *
+ * OnFunc provides a simple pub/sub pattern where multiple listeners can be
+ * registered for a specific function signature. All listeners are invoked
+ * when the event is triggered, with errors caught and ignored. Supports
+ * both synchronous and asynchronous invocation.
+ *
+ * @template Fn - The function signature that listeners must match
+ * @returns Event emitter with register, invoke, invokeAsync, and clear methods
+ *
+ * @example
+ * ```typescript
+ * // Create emitter for specific function signature
+ * const onUserLogin = OnFunc<(userId: string, timestamp: Date) => void>();
+ *
+ * // Register listeners (returns unregister function)
+ * const unsubscribe1 = onUserLogin((userId, timestamp) => {
+ *   console.log(`User ${userId} logged in at ${timestamp}`);
+ * });
+ *
+ * const unsubscribe2 = onUserLogin((userId) => {
+ *   trackAnalytics('login', userId);
+ * });
+ *
+ * // Trigger all listeners
+ * onUserLogin.invoke('user123', new Date());
+ *
+ * // Async invocation
+ * await onUserLogin.invokeAsync('user456', new Date());
+ *
+ * // Unregister specific listener
+ * unsubscribe1();
+ *
+ * // Clear all listeners
+ * onUserLogin.clear();
+ * ```
+ */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export function OnFunc<Fn extends (...args: any[]) => unknown>(): ReturnOnFunc<ExtractArgs<Fn>> {
   const instance = new OnFuncInstance<ExtractArgs<Fn>>();

package/src/option.ts

@@ -1,3 +1,30 @@
+/**
+ * Option type for representing values that may or may not exist.
+ *
+ * Option is a type-safe way to handle nullable values, similar to Rust's Option type.
+ * It forces explicit handling of both present (Some) and absent (None) cases without
+ * using null or undefined.
+ *
+ * @template T - The type of the value when present
+ *
+ * @example
+ * ```typescript
+ * function findUser(id: string): Option<User> {
+ *   const user = users.find(u => u.id === id);
+ *   return user ? Option.Some(user) : Option.None();
+ * }
+ *
+ * const result = findUser('123');
+ * if (result.IsSome()) {
+ *   console.log('Found user:', result.Unwrap());
+ * } else {
+ *   console.log('User not found');
+ * }
+ *
+ * // Or use From to convert from nullable
+ * const maybeUser = Option.From(users[0]); // Some if exists, None if undefined
+ * ```
+ */
 export abstract class Option<T> {
   static Some<T>(t: T): Option<T> {
     return new Some(t);

package/src/poller.ts

@@ -52,15 +52,23 @@ export type PollActionResult<T> =
   | PurPollAbortActionResult;
 
 export const FOREVER = 2147483647; // Maximum setTimeout delay
-export interface PollerOptions {
+export interface PollerOptions<CTX> {
   readonly intervalMs: number;
   readonly actionTimeoutMs: number; // not -1 it means if a timeout occures the action is retried in the next interval
   readonly timeoutMs: number;
   readonly exponentialBackoff: boolean;
   readonly abortSignal?: AbortSignal;
+  readonly ctx: CTX;
 }
 
 export type PollerResult<T> = PollSuccessActionResult<T> | PollErrorActionResult | PollTimeoutActionResult | PollAbortActionResult;
+export interface PollerCtx<CTX> {
+  readonly ctx: CTX;
+  readonly stats: PollerStats;
+  readonly abortSignal: AbortSignal;
+}
+
+export type PollerFunc<T, CTX> = (state: PollerCtx<CTX>) => Promise<PollActionResult<T>>;
 
 function doneStats(stats: Writable<PollerStats> & { startTime: number }): PollerStats {
   stats.totalElapsedMs = Date.now() - stats.startTime;
@@ -71,12 +79,12 @@ function doneStats(stats: Writable<PollerStats> & { startTime: number }): Poller
   };
 }
 
-async function interPoller<T>(
-  fn: (abortSignal?: AbortSignal) => Promise<PollActionResult<T>>,
-  options: Writable<Omit<PollerOptions, "abortSignal">>,
+async function interPoller<R, CTX>(
+  fn: PollerFunc<R, CTX>,
+  options: Writable<Omit<PollerOptions<CTX>, "abortSignal">>,
   stats: Writable<PollerStats> & { readonly startTime: number },
   abortController: AbortController,
-): Promise<PollerResult<T>> {
+): Promise<PollerResult<R>> {
   do {
     // let result: PollActionResult<T>;
     try {
@@ -92,19 +100,23 @@ async function interPoller<T>(
       const fnAbortController = new AbortController();
       fnAbortController.signal.addEventListener("abort", onAbort, { once: true });
 
-      const races = [
-        fn(fnAbortController.signal).finally(() => {
+      const races: Promise<PollActionResult<R>>[] = [
+        fn({
+          ctx: options.ctx,
+          stats,
+          abortSignal: fnAbortController.signal,
+        }).finally(() => {
           // abort all other waits
-          fnAbortController.abort();
+          fnAbortController.abort("action: kill other waits");
         }),
         abortCheck.asPromise().finally(() => {
           // abort all other waits
-          fnAbortController.abort();
+          fnAbortController.abort("abortcheck: kill other waits");
         }),
       ];
       if (options.actionTimeoutMs > 0) {
         races.push(
-          sleep(options.actionTimeoutMs, fnAbortController.signal).then((res): PollActionResult<T> => {
+          sleep(options.actionTimeoutMs, fnAbortController.signal).then((res): PollActionResult<R> => {
             // abort all other waits
             fnAbortController.abort(new Error("poller action timeout"));
             switch (res.state) {
@@ -120,7 +132,7 @@ async function interPoller<T>(
           }),
         );
       }
-      const result = await Promise.race<PollActionResult<T>>(races).finally(() => {
+      const result = await Promise.race<PollActionResult<R>>(races).finally(() => {
         fnAbortController.signal.removeEventListener("abort", onAbort);
       });
       switch (result.state) {
@@ -173,14 +185,50 @@ async function interPoller<T>(
   } while (true);
 }
 
-export async function poller<T>(
-  fn: () => Promise<PollActionResult<T>>,
-  ioptions: Partial<PollerOptions> = {},
-): Promise<PollerResult<T>> {
-  const options = {
+/**
+ * Repeatedly polls an asynchronous function until a terminal state is reached.
+ *
+ * The poller executes the provided function at regular intervals and supports:
+ * - Exponential backoff for retry intervals
+ * - Timeouts for individual actions and overall polling
+ * - Abort signal for cancellation
+ * - Detailed statistics tracking (attempts, intervals, elapsed time)
+ *
+ * @template R - The type of the successful result value
+ * @param fn - Function to poll that returns a PollActionResult indicating whether to continue waiting, succeed, error, timeout, or abort
+ * @param ioptions - Optional configuration:
+ *   - intervalMs: Time between poll attempts in milliseconds (default: 1000)
+ *   - timeoutMs: Total timeout in milliseconds, -1 for forever (default: 30000)
+ *   - actionTimeoutMs: Timeout for each individual action attempt, -1 for forever (default: -1)
+ *   - exponentialBackoff: Whether to double the interval after each attempt (default: auto-enabled if timeoutMs is FOREVER)
+ *   - abortSignal: Optional AbortSignal to cancel polling
+ *
+ * @returns Promise resolving to a PollerResult with state, statistics, and result/error/reason depending on the outcome
+ *
+ * @example
+ * ```typescript
+ * const result = await poller(async () => {
+ *   const status = await checkStatus();
+ *   if (status.ready) {
+ *     return { state: 'success', result: status.data };
+ *   }
+ *   return { state: 'waiting' };
+ * }, { intervalMs: 2000, timeoutMs: 60000 });
+ *
+ * if (result.state === 'success') {
+ *   console.log('Got result:', result.result);
+ * }
+ * ```
+ */
+export async function poller<R, CTX = void>(
+  fn: PollerFunc<R, CTX>,
+  ioptions: Partial<PollerOptions<CTX>> = {},
+): Promise<PollerResult<R>> {
+  const options: PollerOptions<CTX> = {
     intervalMs: 1000,
     timeoutMs: 30000, // -1 means forever
     actionTimeoutMs: -1, // forever
+    ctx: undefined as unknown as CTX,
     ...ioptions,
     exponentialBackoff:
       typeof ioptions.exponentialBackoff === "boolean" ? ioptions.exponentialBackoff : ioptions.timeoutMs === FOREVER,
@@ -206,7 +254,7 @@ export async function poller<T>(
       options.abortSignal.addEventListener("abort", dispatchAbort, { once: true });
     }
   }
-  const races = [interPoller(fn, options, stats, abortController)];
+  const races = [interPoller<R, CTX>(fn, options, stats, abortController)];
   if (options.timeoutMs > 0) {
     races.push(
       sleep(options.timeoutMs, abortController.signal)

package/src/promise-sleep.ts

@@ -33,12 +33,40 @@ export interface SleepAbort extends SleepBase {
 export type SleepResult = SleepOk | SleepErr | SleepAbort;
 
 /**
- * Pause execution for the given number of milliseconds.
+ * Pauses execution for a specified duration with optional abort support.
  *
- * Example:
- *   await sleep(500);
+ * Returns a SleepResult discriminated union indicating success, error, or abort.
+ * Unlike a plain setTimeout promise, this provides detailed state information
+ * through the result object. Negative durations resolve immediately as success.
+ * When aborted via AbortSignal, cleans up the timer and returns abort state.
  *
- * Optionally accepts an AbortSignal to cancel the sleep (will resolve with Result.Err on abort).
+ * @param ms - Duration to sleep in milliseconds (negative values resolve immediately)
+ * @param signal - Optional AbortSignal to cancel the sleep early
+ * @returns Promise resolving to SleepResult with state information
+ *
+ * @example
+ * ```typescript
+ * // Basic sleep
+ * const result = await sleep(500);
+ * if (result.isOk) {
+ *   console.log('Slept for 500ms');
+ * }
+ *
+ * // With abort signal
+ * const controller = new AbortController();
+ * setTimeout(() => controller.abort(), 100);
+ *
+ * const result = await sleep(1000, controller.signal);
+ * if (result.isAborted) {
+ *   console.log('Sleep was aborted:', result.reason);
+ * }
+ *
+ * // Check if already aborted
+ * const aborted = new AbortController();
+ * aborted.abort();
+ * const result = await sleep(1000, aborted.signal);
+ * // Immediately returns with isAborted: true
+ * ```
  */
 export async function sleep(ms: number, signal?: AbortSignal): Promise<SleepResult> {
   if (ms < 0) {