modern-ts 0.8.0

package/dist/types/Reactive/flow.d.ts

@@ -0,0 +1,180 @@
+import { MaybePromise } from '../Utils/type-tool';
+/**
+ * Symbol indicating the flow should continue processing.
+ * When a controller returns this symbol, the flow keeps waiting for the next value.
+ */
+export declare const FlowContinue: unique symbol;
+/**
+ * Stops the flow with the given return value.
+ * When a controller returns this, the flow completes and resolves with the value.
+ * @template T - The type of the return value.
+ * @param value - The value to return.
+ * @returns The same value passed in.
+ */
+export declare const FlowStop: <T>(value: T) => T;
+type FlowController<T, R> = (value: T, iteration: number, signal: AbortSignal | undefined) => MaybePromise<R | typeof FlowContinue>;
+type SwitchFlowController<T, R> = (value: T, iteration: number, signal: AbortSignal) => MaybePromise<R | typeof FlowContinue>;
+/**
+ * Options for consuming a Flow.
+ * @template R - The return type of the consume operation.
+ */
+interface ConsumeOptions<R> {
+    /** Callback invoked when the flow completes normally. */
+    on_complete?: () => MaybePromise<R>;
+    /** Callback invoked when the flow errors. */
+    on_error?: (err: unknown) => MaybePromise<R>;
+    /** Optional AbortSignal to cancel the consume operation. */
+    signal?: AbortSignal;
+}
+interface PendingItem<R = unknown> {
+    resolve: (value: R) => void;
+    reject: (err: unknown) => void;
+    on_complete?: () => MaybePromise<R>;
+    on_error?: (err: unknown) => MaybePromise<R>;
+    queue_index: number;
+}
+export interface Observer<T> {
+    next?: (value: T) => void;
+    error?: (err: unknown) => void;
+    complete?: () => void;
+}
+export type Unsubscribable = Readonly<{
+    unsubscribe: () => void;
+    [Symbol.dispose](): void;
+}>;
+/**
+ * A reactive stream that emits values to subscribers.
+ * Supports both push-based (observer pattern) and pull-based (async iterator) consumption.
+ * @template T - The type of values emitted by this flow.
+ */
+export declare class Flow<T> {
+    protected observers: Set<Observer<T>>;
+    protected teardowns: (() => void)[];
+    protected has_error: boolean;
+    protected is_completed: boolean;
+    protected thrown_error: unknown;
+    protected pending_items: (PendingItem<unknown> | null)[];
+    protected queue_head: number;
+    protected broadcast(value: T): void;
+    protected broadcastError(err: unknown): void;
+    protected broadcastComplete(): void;
+    protected disposeInternal(): void;
+    protected shouldCompact(): boolean;
+    protected compactQueue(): void;
+    protected removePendingItem(item: PendingItem): void;
+    /** Returns true if the flow has errored or completed. */
+    get closed(): boolean;
+    /**
+     * Registers a teardown function to be called when the flow completes or errors.
+     * If the flow is already closed, the teardown is called immediately.
+     */
+    addTeardown(teardown: () => void): void;
+    /**
+     * Subscribes to the flow with an observer or callback.
+     * @param observerOrNext - An Observer object or a callback function for next values.
+     * @returns An Unsubscribable that can be used to unsubscribe.
+     */
+    subscribe(observerOrNext: Observer<T> | ((v: T) => void)): Unsubscribable;
+    /** Emits a value to all subscribers. */
+    next(value: T): void;
+    /** Signals an error to all subscribers and completes the flow. */
+    error(err: unknown): void;
+    /** Signals completion to all subscribers. */
+    complete(): void;
+    protected createPendingItem<R>(): PendingItem<R>;
+    /**
+     * Consumes values from the flow until the controller returns a value.
+     * Each emitted value is passed to the controller, which can return:
+     * - FlowContinue: keep waiting for more values
+     * - Any other value: resolve the promise with that value
+     * @template R - The return type of the consume operation.
+     * @param controller - Function called for each emitted value.
+     * @param options - Optional callbacks for completion/error and abort signal.
+     * @returns Promise that resolves when the controller returns a value.
+     */
+    consume<R>(controller: FlowController<T, R>, options?: ConsumeOptions<R>): Promise<R>;
+    /**
+     * Similar to consume, but cancels the previous controller call when a new value arrives.
+     * Useful for scenarios like search-as-you-type where only the latest input matters.
+     * @template R - The return type of the consume operation.
+     * @param controller - Function called for each emitted value with an AbortSignal.
+     * @param options - Optional callbacks for completion/error and abort signal.
+     * @returns Promise that resolves when the controller returns a value.
+     */
+    switchConsume<R>(controller: SwitchFlowController<T, R>, options?: ConsumeOptions<R>): Promise<R>;
+    /** Returns an async iterator for the flow, enabling for-await-of syntax. */
+    [Symbol.asyncIterator](): AsyncIterator<T>;
+}
+/**
+ * A Flow variant that processes values sequentially.
+ * Unlike the base Flow, SerialFlow ensures each value is fully processed
+ * before the next one is handled, preventing concurrent controller executions.
+ * @template T - The type of values emitted by this flow.
+ */
+export declare class SerialFlow<T> extends Flow<T> {
+    protected pending_queue: T[];
+    protected queue_read_index: number;
+    protected is_consuming: boolean;
+    switchConsume(): never;
+    /**
+     * Consumes values sequentially, ensuring each value is fully processed before the next.
+     * Values emitted during processing are queued and processed in order.
+     */
+    consume<R>(controller: FlowController<T, R>, options?: ConsumeOptions<R>): Promise<R>;
+}
+/**
+ * A Flow that always has a current value and emits it to new subscribers immediately.
+ * Similar to RxJS's BehaviorSubject.
+ * @template T - The type of the current value.
+ */
+export declare class BehaviorFlow<T> extends Flow<T> {
+    private _value;
+    constructor(initialValue: T);
+    /** Returns the current value. */
+    get value(): T;
+    /**
+     * Subscribes to the flow and immediately receives the current value.
+     * @param observerOrNext - An Observer object or a callback function.
+     * @returns An Unsubscribable that can be used to unsubscribe.
+     */
+    subscribe(observerOrNext: Observer<T> | ((v: T) => void)): Unsubscribable;
+    /** Updates the current value and emits it to all subscribers. */
+    next(value: T): void;
+}
+/** Function type that produces values into a Flow. */
+export type FlowProducer<T> = (flow: Flow<T>) => (() => void) | void;
+/**
+ * A Flow that starts producing values only when subscribed (cold stream).
+ * Each subscription triggers the producer function.
+ * @template T - The type of values emitted by this flow.
+ */
+export declare class ColdFlow<T> extends Flow<T> {
+    private producer;
+    constructor(producer: FlowProducer<T>);
+    /**
+     * Subscribes to the flow and starts the producer.
+     * The producer is called once per subscription.
+     */
+    subscribe(observerOrNext: Observer<T> | ((v: T) => void)): Unsubscribable;
+}
+/** Creates a Flow from a producer function. */
+export declare function fromProducer<T>(producer: FlowProducer<T>): Flow<T>;
+/** Creates a SerialFlow from a producer function. */
+export declare function fromSerialProducer<T>(producer: FlowProducer<T>): SerialFlow<T>;
+/** Creates a Flow that emits the given values and completes. */
+export declare function of<T>(...values: T[]): Flow<T>;
+export declare function from<T>(source: Iterable<T>): Flow<T>;
+export declare function from<T>(source: AsyncIterable<T>): Flow<T>;
+export declare function from<T>(source: Promise<T>): Flow<T>;
+export declare function from<T>(source: ArrayLike<T>): Flow<T>;
+/**
+ * A SerialFlow that starts producing values only when subscribed.
+ * Combines cold stream behavior with sequential processing.
+ * @template T - The type of values emitted by this flow.
+ */
+export declare class SerialColdFlow<T> extends SerialFlow<T> {
+    private producer;
+    constructor(producer: FlowProducer<T>);
+    subscribe(observerOrNext: Observer<T> | ((v: T) => void)): Unsubscribable;
+}
+export {};

package/dist/types/Reactive/pace.d.ts

@@ -0,0 +1,80 @@
+import { Result } from '../Result/types';
+import { MaybePromise } from '../Utils/type-tool';
+type NextAction<R> = {
+    readonly value: R;
+} | {
+    readonly delay: number;
+};
+/**
+ * @template R1 - The input result type from the executed function
+ * @template R2 - The output result type after pacing logic
+ */
+type PaceFunction<R1, R2> = (output: Result<R1, unknown>, iteration: number, interval: number) => MaybePromise<NextAction<R2>>;
+/**
+ * Signals the pacer to stop and return a value.
+ * @template T - The type of value to return
+ */
+export declare const Stop: <T>(value: T) => {
+    value: T;
+};
+/**
+ * Signals the pacer to continue waiting with the specified delay.
+ */
+export declare const Continue: (delay: number) => {
+    delay: number;
+};
+/**
+ * Calculates exponential backoff delay.
+ * @param attempt - Current attempt number (0-indexed)
+ * @param base - Base delay in milliseconds (default: 1000)
+ * @param max - Maximum delay cap in milliseconds (default: 30000)
+ */
+export declare const expBackoff: (attempt: number, base?: number, max?: number) => number;
+/**
+ * Exponential backoff with jitter strategies to prevent thundering herd.
+ * @param attempt - Current attempt number (0-indexed)
+ * @param base - Base delay in milliseconds (default: 1000)
+ * @param max - Maximum delay cap in milliseconds (default: 30000)
+ * @param jitter - Jitter strategy: 'full' | 'equal' | 'decorrelated' (default: 'full')
+ */
+export declare const expJitter: (attempt: number, base?: number, max?: number, jitter?: "full" | "equal" | "decorrelated") => number;
+/**
+ * Executes a function repeatedly with custom pacing logic.
+ *
+ * The pace function controls when to stop and what to return based on
+ * each iteration's result. Useful for implementing retry logic, polling,
+ * or any iterative async operation with custom backoff strategies.
+ *
+ * @template R1 - The return type of the executed function
+ * @template R2 - The final output type after pacing logic completes
+ * @param fn - The function to execute on each iteration
+ * @param pace - Controls iteration flow; return `Stop(value)` to complete or `Continue(ms)` to retry
+ * @param signal - Optional AbortSignal for cancellation
+ * @returns The value passed to `Stop()` when pacing completes
+ */
+export declare function pacer<R1, R2>(fn: () => MaybePromise<R1>, pace: PaceFunction<R1, R2>, signal?: AbortSignal): Promise<R2>;
+/**
+ * Options for retry operations with exponential backoff.
+ */
+interface PaceRetryOptions {
+    /** Maximum number of retry attempts (default: 5) */
+    readonly maxRetries?: number;
+    /** Base delay in milliseconds for exponential backoff (default: 1000) */
+    readonly baseDelayMs?: number;
+    /** Maximum delay cap in milliseconds (default: 30000) */
+    readonly maxBackoffMs?: number;
+    /** Optional AbortSignal for cancellation */
+    signal?: AbortSignal;
+}
+/**
+ * Retries an async task with exponential backoff and jitter.
+ *
+ * @template T - The return type of the task
+ * @param task - The async function to retry
+ * @param options - Retry configuration options
+ * @param signal - Optional AbortSignal for cancellation
+ * @returns The result of the successful task execution
+ * @throws Last error if all retry attempts fail
+ */
+export declare function retry<T>(task: () => MaybePromise<T>, options?: PaceRetryOptions): Promise<T>;
+export {};

package/dist/types/Reactive.d.ts

@@ -0,0 +1,2 @@
+export * from './Reactive/__export__'
+export {}

package/dist/types/Reader/__export-readerT__.d.ts

@@ -0,0 +1,4 @@
+export * from './types';
+export * from './readerT';
+export * from './readerT-async';
+export * from './local';

package/dist/types/Reader/__export-reader__.d.ts

@@ -0,0 +1,4 @@
+export * from './types';
+export * from './reader';
+export * from './reader-async';
+export * from './local';

package/dist/types/Reader/local.d.ts

@@ -0,0 +1,39 @@
+import { Reader, AsyncReader, ReaderT, AsyncReaderT } from './types';
+/**
+ * Implements the local function for ReaderT type.
+ * @typeParam R - Environment type
+ * @typeParam E - Error type
+ * @typeParam A - Result type
+ * @param reader - Original ReaderT
+ * @param f_mod - Environment modification function that takes the current environment and returns a modified one
+ * @returns A new ReaderT that executes with the modified environment
+ */
+export declare function local<R, E, A>(reader: ReaderT<R, E, A>, f_mod: (env: R) => R): ReaderT<R, E, A>;
+/**
+ * Implements the local function for AsyncReaderT type.
+ * @typeParam R - Environment type
+ * @typeParam E - Error type
+ * @typeParam A - Result type
+ * @param reader - Original AsyncReaderT
+ * @param f_mod - Environment modification function that takes the current environment and returns a modified one
+ * @returns A new AsyncReaderT that executes with the modified environment
+ */
+export declare function local<R, E, A>(reader: AsyncReaderT<R, E, A>, f_mod: (env: R) => R): AsyncReaderT<R, E, A>;
+/**
+ * Implements the local function for Reader type.
+ * @typeParam R - Environment type
+ * @typeParam A - Result type
+ * @param reader - Original Reader
+ * @param f_mod - Environment modification function that takes the current environment and returns a modified one
+ * @returns A new Reader that executes with the modified environment
+ */
+export declare function local<R, A>(reader: Reader<R, A>, f_mod: (env: R) => R): Reader<R, A>;
+/**
+ * Implements the local function for AsyncReader type.
+ * @typeParam R - Environment type
+ * @typeParam A - Result type
+ * @param reader - Original AsyncReader
+ * @param f_mod - Environment modification function that takes the current environment and returns a modified one
+ * @returns A new AsyncReader that executes with the modified environment
+ */
+export declare function local<R, A>(reader: AsyncReader<R, A>, f_mod: (env: R) => R): AsyncReader<R, A>;

package/dist/types/Reader/reader-async.d.ts

@@ -0,0 +1,84 @@
+import { AsyncReader } from './types';
+/**
+ * Creates an AsyncReader that ignores the environment (R) and resolves immediately
+ * with the given value (A). This is the 'return' or 'pure' operation.
+ * @typeParam R - The Environment type.
+ * @typeParam A - The type of the value to wrap.
+ * @param a - The value to be wrapped in AsyncReader.
+ * @returns AsyncReader<R, A> that resolves to 'a'.
+ */
+export declare const ofAsync: <R, A>(a: A) => AsyncReader<R, A>;
+/**
+ * Creates an AsyncReader that retrieves the environment (R) and resolves with it.
+ * This is the 'ask' operation in Reader Monad.
+ * @typeParam R - The Environment type.
+ * @returns AsyncReader<R, R> that resolves to the environment 'R'.
+ */
+export declare const askAsync: <R>() => AsyncReader<R, R>;
+/**
+ * Applies a function (A) => B to the value inside the AsyncReader, maintaining the
+ * environment context. This is the 'map' operation (Functor).
+ * @typeParam R - The Environment type.
+ * @typeParam A - The type of the input value.
+ * @typeParam B - The type of the output value.
+ * @param reader - The source AsyncReader<R, A>.
+ * @param f - The mapping function (A) => B.
+ * @returns AsyncReader<R, B> containing the mapped value.
+ */
+export declare const mapAsync: <R, A, B>(reader: AsyncReader<R, A>, f: (a: A) => B) => AsyncReader<R, B>;
+/**
+ * Chains two AsyncReader computations. The result of the first reader (A) is used to
+ * produce the second reader (AsyncReader<R, B>). This is the 'flatMap' or 'bind' operation (Monad).
+ * @typeParam R - The Environment type.
+ * @typeParam A - The type of the input value of the first reader.
+ * @typeParam B - The type of the final output value.
+ * @param reader - The initial AsyncReader<R, A>.
+ * @param f - A function that takes the result of 'reader' and returns the next AsyncReader<R, B>.
+ * @returns AsyncReader<R, B> containing the final result.
+ */
+export declare const anThenAsync: <R, A, B>(reader: AsyncReader<R, A>, f: (a: A) => AsyncReader<R, B>) => AsyncReader<R, B>;
+/**
+ * Applies a function contained within an AsyncReader (R, (A) => B) to a value
+ * contained within another AsyncReader (R, A), preserving the environment. This is the 'ap' operation (Applicative Functor).
+ * @typeParam R - The Environment type.
+ * @typeParam A - The type of the input value.
+ * @typeParam B - The type of the output value.
+ * @param reader_fab - AsyncReader containing the function (A) => B.
+ * @param reader_a - AsyncReader containing the input value A.
+ * @returns AsyncReader<R, B> containing the result of applying the function.
+ */
+export declare const apAsync: <R, A, B>(reader_fab: AsyncReader<R, (a: A) => B>, reader_a: AsyncReader<R, A>) => AsyncReader<R, B>;
+/**
+ * Performs a side effect using the result of the first AsyncReader, and then returns
+ * the original result, ignoring the side effect's return value.
+ * Note: The side effect function must return an AsyncReader.
+ * @typeParam R - The Environment type.
+ * @typeParam A - The type of the original value to be passed through.
+ * @param reader - The source AsyncReader<R, A>.
+ * @param f - A function that takes A and returns an AsyncReader<R, unknown> (the side effect).
+ * @returns AsyncReader<R, A> containing the original value.
+ */
+export declare const tapAsync: <R, A>(reader: AsyncReader<R, A>, f: (a: A) => AsyncReader<R, unknown>) => AsyncReader<R, A>;
+/**
+ * Asynchronously lifts a binary function (A, B) => C into the AsyncReader context.
+ * It combines two AsyncReaders using the Applicative 'ap' operation.
+ * @typeParam R - The Environment type
+ * @typeParam A - The type of the first input value
+ * @typeParam B - The type of the second input value
+ * @typeParam C - The type of the output value
+ * @param f_abc - The binary function (A, B) => C
+ * @returns A function that takes two AsyncReaders and returns an AsyncReader<R, C>
+ */
+export declare const liftA2Async: <R, A, B, C>(f_abc: (a: A, b: B) => C) => (reader_a: AsyncReader<R, A>, reader_b: AsyncReader<R, B>) => AsyncReader<R, C>;
+/**
+ * Asynchronously lifts a ternary function (A, B, C) => D into the AsyncReader context.
+ * It combines three AsyncReaders using the Applicative 'ap' operation.
+ * @typeParam R - The Environment type
+ * @typeParam A - The type of the first input value
+ * @typeParam B - The type of the second input value
+ * @typeParam C - The type of the third input value
+ * @typeParam D - The type of the output value
+ * @param f_abcd - The ternary function (A, B, C) => D
+ * @returns A function that takes three AsyncReaders and returns an AsyncReader<R, D>
+ */
+export declare const liftA3Async: <R, A, B, C, D>(f_abcd: (a: A, b: B, c: C) => D) => (reader_a: AsyncReader<R, A>, reader_b: AsyncReader<R, B>, reader_c: AsyncReader<R, C>) => AsyncReader<R, D>;

package/dist/types/Reader/reader.d.ts

@@ -0,0 +1,96 @@
+import { Reader } from './types';
+/**
+ * Creates a Reader that ignores the environment (R) and returns the given value (A).
+ * This is the 'return' or 'pure' operation (Applicative/Monad).
+ *
+ * @typeParam R - The Environment type.
+ * @typeParam A - The type of the value to wrap.
+ * @param a - The value to be wrapped in Reader.
+ * @returns Reader<R, A> that returns 'a'.
+ */
+export declare const of: <R, A>(a: A) => Reader<R, A>;
+/**
+ * Applies a function contained within a Reader (R, (A) => B) to a value
+ * contained within another Reader (R, A), preserving the environment.
+ * This is the 'ap' operation (Applicative Functor).
+ *
+ * @typeParam R - The Environment type.
+ * @typeParam A - The type of the input value.
+ * @typeParam B - The type of the output value.
+ * @param reader_fab - Reader containing the function (A) => B.
+ * @param reader_a - Reader containing the input value A.
+ * @returns Reader<R, B> containing the result of applying the function.
+ */
+export declare const ap: <R, A, B>(reader_fab: Reader<R, (a: A) => B>, reader_a: Reader<R, A>) => Reader<R, B>;
+/**
+ * Creates a Reader that retrieves the environment (R) and returns it.
+ * This is the 'ask' operation in Reader Monad.
+ *
+ * @typeParam R - The Environment type.
+ * @returns Reader<R, R> that returns the environment 'R'.
+ */
+export declare const ask: <R>() => Reader<R, R>;
+/**
+ * Applies a function (A) => B to the value inside the Reader, maintaining the
+ * environment context. This is the 'map' operation (Functor).
+ *
+ * @typeParam R - The Environment type.
+ * @typeParam A - The type of the input value.
+ * @typeParam B - The type of the output value.
+ * @param reader - The source Reader<R, A>.
+ * @param f - The mapping function (A) => B.
+ * @returns Reader<R, B> containing the mapped value.
+ */
+export declare const map: <R, A, B>(reader: Reader<R, A>, f: (a: A) => B) => Reader<R, B>;
+/**
+ * Chains two Reader computations. The result of the first reader (A) is used to
+ * produce the second reader (Reader<R, B>).
+ * This is the 'flatMap' or 'bind' operation (Monad).
+ *
+ * @typeParam R - The Environment type.
+ * @typeParam A - The type of the input value of the first reader.
+ * @typeParam B - The type of the final output value.
+ * @param reader - The initial Reader<R, A>.
+ * @param f - A function that takes the result of 'reader' and returns the next Reader<R, B>.
+ * @returns Reader<R, B> containing the final result.
+ */
+export declare const anThen: <R, A, B>(reader: Reader<R, A>, f: (a: A) => Reader<R, B>) => Reader<R, B>;
+/**
+ * Performs a side effect using the result of the first Reader, and then returns
+ * the original result, ignoring the side effect's return value.
+ * Note: The side effect function must return a Reader.
+ *
+ * @typeParam R - The Environment type.
+ * @typeParam A - The type of the original value to be passed through.
+ * @param reader - The source Reader<R, A>.
+ * @param f - A function that takes A and returns a Reader<R, unknown> (the side effect).
+ * @returns Reader<R, A> containing the original value.
+ */
+export declare const tap: <R, A>(reader: Reader<R, A>, f: (a: A) => Reader<R, unknown>) => Reader<R, A>;
+/**
+ * Lifts a binary function (A, B) => C into the Reader context.
+ * It takes a standard two-argument function and two Readers, and returns a new Reader
+ * that applies the function to the values within the Readers. This is achieved via Currying and 'ap'.
+ *
+ * @typeParam R - The Environment type
+ * @typeParam A - The type of the first input value
+ * @typeParam B - The type of the second input value
+ * @typeParam C - The type of the output value
+ * @param f_abc - The binary function (A, B) => C
+ * @returns A function that takes two Readers and returns a Reader<R, C>
+ */
+export declare const liftA2: <R, A, B, C>(f_abc: (a: A, b: B) => C) => (reader_a: Reader<R, A>, reader_b: Reader<R, B>) => Reader<R, C>;
+/**
+ * Lifts a ternary function (A, B, C) => D into the Reader context.
+ * It takes a standard three-argument function and three Readers, and returns a new Reader
+ * that applies the function to the values within the Readers. This is built upon liftA2 and 'ap'.
+ *
+ * @typeParam R - The Environment type
+ * @typeParam A - The type of the first input value
+ * @typeParam B - The type of the second input value
+ * @typeParam C - The type of the third input value
+ * @typeParam D - The type of the output value
+ * @param f_abcd - The ternary function (A, B, C) => D
+ * @returns A function that takes three Readers and returns a Reader<R, D>
+ */
+export declare const liftA3: <R, A, B, C, D>(f_abcd: (a: A, b: B, c: C) => D) => (reader_a: Reader<R, A>, reader_b: Reader<R, B>, reader_c: Reader<R, C>) => Reader<R, D>;