@adviser/cement 0.5.0 → 0.5.1

package/src/on-func.ts

@@ -0,0 +1,115 @@
+import { isPromise } from "./is-promise.js";
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+class OnFuncInstance<Args extends any[]> {
+  readonly #fns = new Set<(...a: Args) => unknown>();
+
+  addFunction(fn: (...a: Args) => unknown): () => void {
+    this.#fns.add(fn);
+    return () => {
+      this.unreg(OnFuncReturn.UNREGISTER, fn);
+    };
+  }
+
+  private unreg(ret: unknown, fn: (...a: Args) => unknown): unknown {
+    // console.log("unreg", ret, OnFuncReturn, OnFuncReturn[ret as keyof typeof OnFuncReturn]);
+    if (ret === OnFuncReturn.UNREGISTER || ret === OnFuncReturn.ONCE) {
+      this.#fns.delete(fn);
+      return undefined;
+    }
+    return ret;
+  }
+
+  public invoke(...a: Args): void {
+    for (const fn of this.#fns) {
+      try {
+        const couldByPlainOrPromise = fn(...a);
+        if (isPromise(couldByPlainOrPromise)) {
+          void couldByPlainOrPromise.then((ret) => {
+            this.unreg(ret, fn);
+          });
+        } else {
+          this.unreg(couldByPlainOrPromise, fn);
+        }
+      } catch (e) {
+        // ignore errors
+      }
+    }
+  }
+
+  public clear(): void {
+    this.#fns.clear();
+  }
+
+  public async invokeAsync(...a: Args): Promise<void> {
+    await Promise.allSettled(Array.from(this.#fns).map((fn) => Promise.resolve(fn(...a)).then((ret) => this.unreg(ret, fn))));
+  }
+}
+
+export const OnFuncReturn: {
+  readonly UNREGISTER: symbol;
+  readonly ONCE: symbol;
+} = {
+  UNREGISTER: Symbol("ONFUNC_UNREGISTER"),
+  ONCE: Symbol("ONFUNC_ONCE"),
+} as const;
+export type OnFuncReturn = (typeof OnFuncReturn)[keyof typeof OnFuncReturn];
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export interface ReturnOnFunc<Args extends any[], X = unknown> {
+  (fn: (...a: Args) => OnFuncReturn | X): () => unknown; // returns unregister function
+  invoke(...a: Args): void;
+  invokeAsync(...a: Args): Promise<void>;
+  clear(): void;
+}
+
+type ExtractArgs<T, X> = T extends (...args: infer A) => OnFuncReturn | X ? 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[]) => OnFuncReturn | X, X = unknown>(): ReturnOnFunc<ExtractArgs<Fn, X>> {
+  const instance = new OnFuncInstance<ExtractArgs<Fn, X>>();
+  const ret = instance.addFunction.bind(instance) as ReturnOnFunc<ExtractArgs<Fn, X>>;
+  ret.invoke = instance.invoke.bind(instance) as ReturnOnFunc<ExtractArgs<Fn, X>>["invoke"];
+  ret.invokeAsync = instance.invokeAsync.bind(instance) as ReturnOnFunc<ExtractArgs<Fn, X>>["invokeAsync"];
+  ret.clear = instance.clear.bind(instance) as ReturnOnFunc<ExtractArgs<Fn, X>>["clear"];
+  return ret;
+}

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

@@ -0,0 +1,269 @@
+import { Future } from "./future.js";
+import { sleep } from "./promise-sleep.js";
+import { Writable } from "ts-essentials";
+
+export interface PollerStats {
+  readonly attempts: number;
+  readonly lastIntervalMs: number;
+  readonly totalElapsedMs: number;
+}
+
+interface PollWithStats {
+  readonly stats: PollerStats;
+}
+
+export interface PurPollWaitingActionResult {
+  readonly state: "waiting";
+}
+
+export type PollWaitingActionResult = PurPollWaitingActionResult & PollWithStats;
+
+export interface PurPollSuccessActionResult<T> {
+  readonly state: "success";
+  readonly result: T;
+}
+
+export type PollSuccessActionResult<T> = PurPollSuccessActionResult<T> & PollWithStats;
+
+export interface PurPollErrorActionResult {
+  readonly state: "error";
+  readonly error: Error;
+}
+
+export type PollErrorActionResult = PurPollErrorActionResult & PollWithStats;
+
+export interface PurPollTimeoutActionResult {
+  readonly state: "timeout";
+}
+
+export type PollTimeoutActionResult = PurPollTimeoutActionResult & PollWithStats;
+
+export interface PurPollAbortActionResult {
+  readonly state: "aborted";
+  readonly reason: unknown;
+}
+export type PollAbortActionResult = PurPollAbortActionResult & PollWithStats;
+
+export type PollActionResult<T> =
+  | PurPollWaitingActionResult
+  | PurPollSuccessActionResult<T>
+  | PurPollErrorActionResult
+  | PurPollTimeoutActionResult
+  | PurPollAbortActionResult;
+
+export const FOREVER = 2147483647; // Maximum setTimeout delay
+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;
+  return {
+    attempts: stats.attempts,
+    lastIntervalMs: stats.lastIntervalMs,
+    totalElapsedMs: stats.totalElapsedMs,
+  };
+}
+
+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<R>> {
+  do {
+    // let result: PollActionResult<T>;
+    try {
+      stats.attempts += 1;
+
+      const abortCheck = new Future<PurPollAbortActionResult>();
+      function onAbort(): void {
+        abortCheck.resolve({
+          state: "aborted",
+          reason: abortController.signal.reason,
+        });
+      }
+      const fnAbortController = new AbortController();
+      fnAbortController.signal.addEventListener("abort", onAbort, { once: true });
+
+      const races: Promise<PollActionResult<R>>[] = [
+        fn({
+          ctx: options.ctx,
+          stats,
+          abortSignal: fnAbortController.signal,
+        }).finally(() => {
+          // abort all other waits
+          fnAbortController.abort("action: kill other waits");
+        }),
+        abortCheck.asPromise().finally(() => {
+          // abort all other waits
+          fnAbortController.abort("abortcheck: kill other waits");
+        }),
+      ];
+      if (options.actionTimeoutMs > 0) {
+        races.push(
+          sleep(options.actionTimeoutMs, fnAbortController.signal).then((res): PollActionResult<R> => {
+            // abort all other waits
+            fnAbortController.abort(new Error("poller action timeout"));
+            switch (res.state) {
+              case "sleeped":
+                // timeout occurred but we retry
+                return { state: "waiting" as const };
+              case "error":
+                return { state: "error" as const, error: res.error };
+              case "aborted":
+                return { state: "aborted" as const, reason: res.reason };
+            }
+            throw new Error("Unreachable code in poller action timeout");
+          }),
+        );
+      }
+      const result = await Promise.race<PollActionResult<R>>(races).finally(() => {
+        fnAbortController.signal.removeEventListener("abort", onAbort);
+      });
+      switch (result.state) {
+        case "waiting":
+          {
+            if (options.exponentialBackoff) {
+              options.intervalMs = Math.min(options.intervalMs * 2, FOREVER);
+            }
+            stats.lastIntervalMs = options.intervalMs;
+            const res = await sleep(options.intervalMs, abortController.signal);
+            switch (true) {
+              case res.isAborted:
+                return {
+                  state: "aborted" as const,
+                  reason: res.reason,
+                  stats: doneStats(stats),
+                };
+              case res.isOk:
+                break;
+              case res.isErr:
+                return {
+                  state: "error",
+                  error: res.error,
+                  stats: doneStats(stats),
+                };
+              default:
+                throw new Error("poller interrupted during sleep");
+            }
+          }
+          break;
+        case "aborted":
+          return {
+            state: "aborted" as const,
+            reason: result.reason,
+            stats: doneStats(stats),
+          };
+        case "success":
+          return { ...result, stats: doneStats(stats) };
+        case "error":
+          return { ...result, stats: doneStats(stats) };
+      }
+    } catch (err) {
+      return {
+        state: "error",
+        error: err as Error,
+        stats: doneStats(stats),
+      };
+    }
+    // eslint-disable-next-line no-constant-condition
+  } while (true);
+}
+
+/**
+ * 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,
+  };
+  const stats = {
+    attempts: 0,
+    startTime: Date.now(),
+    lastIntervalMs: 0,
+    totalElapsedMs: 0,
+  };
+  const abortController = new AbortController();
+  const toRemoveEventListeners: (() => void)[] = [];
+  if (options.abortSignal) {
+    if (options.abortSignal.aborted) {
+      abortController.abort(options.abortSignal.reason);
+    } else {
+      function dispatchAbort(): void {
+        abortController.abort(options.abortSignal?.reason);
+      }
+      toRemoveEventListeners.push(() => {
+        options.abortSignal?.removeEventListener("abort", dispatchAbort);
+      });
+      options.abortSignal.addEventListener("abort", dispatchAbort, { once: true });
+    }
+  }
+  const races = [interPoller<R, CTX>(fn, options, stats, abortController)];
+  if (options.timeoutMs > 0) {
+    races.push(
+      sleep(options.timeoutMs, abortController.signal)
+        .then(() => ({ state: "timeout" as const, stats: doneStats(stats) }))
+        .catch((e: Error) => ({ state: "error" as const, error: e, stats: doneStats(stats) })),
+    );
+  }
+  return Promise.race(races).finally(() => {
+    toRemoveEventListeners.forEach((fn) => fn());
+    toRemoveEventListeners.length = 0;
+  });
+}

package/src/promise-sleep.ts

@@ -0,0 +1,101 @@
+import { Future } from "./future.js";
+
+export interface SleepBase {
+  readonly state: "sleeped" | "error" | "aborted";
+  readonly isOk: boolean;
+  readonly isErr: boolean;
+  readonly isAborted: boolean;
+}
+
+export interface SleepOk extends SleepBase {
+  readonly state: "sleeped";
+  readonly isOk: true;
+  readonly isErr: false;
+  readonly isAborted: false;
+}
+
+export interface SleepErr extends SleepBase {
+  readonly state: "error";
+  readonly error: Error;
+  readonly isOk: false;
+  readonly isErr: true;
+  readonly isAborted: false;
+}
+
+export interface SleepAbort extends SleepBase {
+  readonly state: "aborted";
+  readonly reason: Error;
+  readonly isOk: false;
+  readonly isErr: false;
+  readonly isAborted: true;
+}
+
+export type SleepResult = SleepOk | SleepErr | SleepAbort;
+
+/**
+ * Pauses execution for a specified duration with optional abort support.
+ *
+ * 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.
+ *
+ * @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) {
+    return { state: "sleeped", isOk: true, isErr: false, isAborted: false };
+  }
+  if (signal?.aborted) {
+    const err = new Error("sleep aborted");
+    // (err as { name: string }).name = "AbortError";
+    return { state: "aborted", reason: err, isOk: false, isErr: false, isAborted: true };
+  }
+  const sleepFuture = new Future<SleepOk>();
+  const id = setTimeout(() => {
+    // cleanup();
+    sleepFuture.resolve({ state: "sleeped", isOk: true, isErr: false, isAborted: false });
+  }, ms);
+
+  const abortFuture = new Future<SleepAbort>();
+  function onAbort(): void {
+    abortFuture.resolve({
+      state: "aborted",
+      reason: new Error("sleep aborted"),
+      isOk: false,
+      isErr: false,
+      isAborted: true,
+    });
+  }
+  signal?.addEventListener("abort", onAbort, { once: true });
+  return Promise.race([abortFuture.asPromise(), sleepFuture.asPromise()]).finally(() => {
+    clearTimeout(id);
+    signal?.removeEventListener("abort", onAbort);
+  });
+}