@lee-zg/melange 1.0.0

package/dist/fp/index.d.ts

@@ -0,0 +1,913 @@
+import { U as UnaryFunction, d as Ok, E as Err, e as Result, S as Some, f as None, g as Option, A as AnyFunction } from '../types-BtOUCLB-.js';
+
+/**
+ * @fileoverview 函数组合工具
+ * @module melange/fp/compose
+ * @description 提供组合和连接函数的工具，
+ * 实现无点风格编程和函数链式调用。
+ */
+
+/**
+ * 从右到左组合多个函数。
+ * 最右边的函数可以接受多个参数，其他所有函数必须是一元的。
+ *
+ * @description
+ * 函数组合是函数式编程中的基本概念。
+ * `compose(f, g, h)(x)` 等价于 `f(g(h(x)))`。
+ *
+ * @example
+ * ```typescript
+ * const addOne = (x: number) => x + 1;
+ * const double = (x: number) => x * 2;
+ * const square = (x: number) => x * x;
+ *
+ * const composed = compose(square, double, addOne);
+ * composed(2); // ((2 + 1) * 2)² = 36
+ * ```
+ *
+ * @param fns - 要组合的函数
+ * @returns 一个新函数，从右到左应用所有函数
+ */
+declare function compose<A, B>(fn1: UnaryFunction<A, B>): UnaryFunction<A, B>;
+declare function compose<A, B, C>(fn2: UnaryFunction<B, C>, fn1: UnaryFunction<A, B>): UnaryFunction<A, C>;
+declare function compose<A, B, C, D>(fn3: UnaryFunction<C, D>, fn2: UnaryFunction<B, C>, fn1: UnaryFunction<A, B>): UnaryFunction<A, D>;
+declare function compose<A, B, C, D, E>(fn4: UnaryFunction<D, E>, fn3: UnaryFunction<C, D>, fn2: UnaryFunction<B, C>, fn1: UnaryFunction<A, B>): UnaryFunction<A, E>;
+declare function compose<A, B, C, D, E, F>(fn5: UnaryFunction<E, F>, fn4: UnaryFunction<D, E>, fn3: UnaryFunction<C, D>, fn2: UnaryFunction<B, C>, fn1: UnaryFunction<A, B>): UnaryFunction<A, F>;
+declare function compose(...fns: UnaryFunction<unknown, unknown>[]): UnaryFunction<unknown, unknown>;
+/**
+ * 从左到右连接多个函数。
+ * 第一个函数可以接受多个参数，其他所有函数必须是一元的。
+ *
+ * @description
+ * Pipe 是 compose 的反向操作，从左到右应用函数。
+ * `pipe(f, g, h)(x)` 等价于 `h(g(f(x)))`。
+ * 这通常更易读，因为它遵循自然的阅读顺序。
+ *
+ * @example
+ * ```typescript
+ * const addOne = (x: number) => x + 1;
+ * const double = (x: number) => x * 2;
+ * const square = (x: number) => x * x;
+ *
+ * const piped = pipe(addOne, double, square);
+ * piped(2); // ((2 + 1) * 2)² = 36
+ * ```
+ *
+ * @param fns - 要连接的函数
+ * @returns 一个新函数，从左到右应用所有函数
+ */
+declare function pipe<A, B>(fn1: UnaryFunction<A, B>): UnaryFunction<A, B>;
+declare function pipe<A, B, C>(fn1: UnaryFunction<A, B>, fn2: UnaryFunction<B, C>): UnaryFunction<A, C>;
+declare function pipe<A, B, C, D>(fn1: UnaryFunction<A, B>, fn2: UnaryFunction<B, C>, fn3: UnaryFunction<C, D>): UnaryFunction<A, D>;
+declare function pipe<A, B, C, D, E>(fn1: UnaryFunction<A, B>, fn2: UnaryFunction<B, C>, fn3: UnaryFunction<C, D>, fn4: UnaryFunction<D, E>): UnaryFunction<A, E>;
+declare function pipe<A, B, C, D, E, F>(fn1: UnaryFunction<A, B>, fn2: UnaryFunction<B, C>, fn3: UnaryFunction<C, D>, fn4: UnaryFunction<D, E>, fn5: UnaryFunction<E, F>): UnaryFunction<A, F>;
+declare function pipe(...fns: UnaryFunction<unknown, unknown>[]): UnaryFunction<unknown, unknown>;
+/**
+ * 创建函数流，类似于 pipe 但立即返回最终结果。
+ * 适用于通过一系列函数转换值。
+ *
+ * @description
+ * Flow 类似于 pipe，但不是返回函数，
+ * 而是立即将值通过所有函数应用。
+ *
+ * @example
+ * ```typescript
+ * const result = flow(
+ *   5,
+ *   x => x + 1,
+ *   x => x * 2,
+ *   x => x.toString()
+ * );
+ * // result = "12"
+ * ```
+ *
+ * @param value - 初始值
+ * @param fns - 要应用的函数
+ * @returns 将所有函数应用于值的结果
+ */
+declare function flow<A>(value: A): A;
+declare function flow<A, B>(value: A, fn1: UnaryFunction<A, B>): B;
+declare function flow<A, B, C>(value: A, fn1: UnaryFunction<A, B>, fn2: UnaryFunction<B, C>): C;
+declare function flow<A, B, C, D>(value: A, fn1: UnaryFunction<A, B>, fn2: UnaryFunction<B, C>, fn3: UnaryFunction<C, D>): D;
+declare function flow<A, B, C, D, E>(value: A, fn1: UnaryFunction<A, B>, fn2: UnaryFunction<B, C>, fn3: UnaryFunction<C, D>, fn4: UnaryFunction<D, E>): E;
+declare function flow<A, B, C, D, E, F>(value: A, fn1: UnaryFunction<A, B>, fn2: UnaryFunction<B, C>, fn3: UnaryFunction<C, D>, fn4: UnaryFunction<D, E>, fn5: UnaryFunction<E, F>): F;
+
+/**
+ * @fileoverview 柯里化和部分应用工具
+ * @module melange/fp/curry
+ * @description 提供柯里化函数和部分应用的工具，
+ * 实现更灵活的函数组合和重用。
+ */
+/**
+ * 柯里化二元函数。
+ * 将接受两个参数的函数转换为接受一个参数并返回接受第二个参数的函数。
+ *
+ * @description
+ * 柯里化以数学家 Haskell Curry 命名。它将具有多个参数的函数转换为一系列函数，每个函数接受一个参数。
+ *
+ * @example
+ * ```typescript
+ * const add = (a: number, b: number) => a + b;
+ * const curriedAdd = curry(add);
+ *
+ * curriedAdd(1)(2); // 3
+ * const addFive = curriedAdd(5);
+ * addFive(10); // 15
+ * ```
+ *
+ * @template A - 第一个参数的类型
+ * @template B - 第二个参数的类型
+ * @template R - 返回类型
+ * @param fn - 要柯里化的二元函数
+ * @returns 函数的柯里化版本
+ */
+declare function curry<A, B, R>(fn: (a: A, b: B) => R): (a: A) => (b: B) => R;
+/**
+ * 柯里化三元函数。
+ *
+ * @template A - 第一个参数的类型
+ * @template B - 第二个参数的类型
+ * @template C - 第三个参数的类型
+ * @template R - 返回类型
+ * @param fn - 要柯里化的三元函数
+ * @returns 函数的柯里化版本
+ */
+declare function curry<A, B, C, R>(fn: (a: A, b: B, c: C) => R): (a: A) => (b: B) => (c: C) => R;
+/**
+ * 柯里化四元函数。
+ *
+ * @template A - 第一个参数的类型
+ * @template B - 第二个参数的类型
+ * @template C - 第三个参数的类型
+ * @template D - 第四个参数的类型
+ * @template R - 返回类型
+ * @param fn - 要柯里化的四元函数
+ * @returns 函数的柯里化版本
+ */
+declare function curry<A, B, C, D, R>(fn: (a: A, b: B, c: C, d: D) => R): (a: A) => (b: B) => (c: C) => (d: D) => R;
+/**
+ * 反柯里化函数。
+ * 将一元函数序列转换回接受多个参数的单个函数。
+ *
+ * @example
+ * ```typescript
+ * const curriedAdd = (a: number) => (b: number) => a + b;
+ * const add = uncurry(curriedAdd);
+ *
+ * add(1, 2); // 3
+ * ```
+ *
+ * @template A - 第一个参数的类型
+ * @template B - 第二个参数的类型
+ * @template R - 返回类型
+ * @param fn - 要反柯里化的函数
+ * @returns 函数的反柯里化版本
+ */
+declare function uncurry<A, B, R>(fn: (a: A) => (b: B) => R): (a: A, b: B) => R;
+declare function uncurry<A, B, C, R>(fn: (a: A) => (b: B) => (c: C) => R): (a: A, b: B, c: C) => R;
+/**
+ * 从左侧部分应用参数到函数。
+ * 返回一个接受剩余参数的新函数。
+ *
+ * @description
+ * 部分应用不同于柯里化。柯里化将函数转换为一元函数序列，
+ * 而部分应用固定一些参数并返回接受剩余参数的函数。
+ *
+ * @example
+ * ```typescript
+ * const greet = (greeting: string, name: string, punctuation: string) =>
+ *   `${greeting}, ${name}${punctuation}`;
+ *
+ * const sayHello = partial(greet, 'Hello');
+ * sayHello('World', '!'); // "Hello, World!"
+ *
+ * const sayHelloWorld = partial(greet, 'Hello', 'World');
+ * sayHelloWorld('!'); // "Hello, World!"
+ * ```
+ *
+ * @template T - 部分参数的元组类型
+ * @template R - 剩余参数的元组类型
+ * @template Result - 返回类型
+ * @param fn - 要部分应用的函数
+ * @param partialArgs - 要固定的参数
+ * @returns 接受剩余参数的新函数
+ */
+declare function partial<T extends unknown[], R extends unknown[], Result>(fn: (...args: [...T, ...R]) => Result, ...partialArgs: T): (...remainingArgs: R) => Result;
+/**
+ * 从右侧部分应用参数到函数。
+ * 返回一个接受剩余参数的新函数。
+ *
+ * @example
+ * ```typescript
+ * const greet = (greeting: string, name: string, punctuation: string) =>
+ *   `${greeting}, ${name}${punctuation}`;
+ *
+ * const greetExcitedly = partialRight(greet, '!');
+ * greetExcitedly('Hello', 'World'); // "Hello, World!"
+ * ```
+ *
+ * @template L - 前导参数的元组类型
+ * @template T - 部分参数的元组类型
+ * @template Result - 返回类型
+ * @param fn - 要部分应用的函数
+ * @param partialArgs - 从右侧固定的参数
+ * @returns 接受前导参数的新函数
+ */
+declare function partialRight<L extends unknown[], T extends unknown[], Result>(fn: (...args: [...L, ...T]) => Result, ...partialArgs: T): (...leadingArgs: L) => Result;
+
+/**
+ * @fileoverview 用于函数式错误处理的 Result 类型
+ * @module melange/fp/result
+ * @description 提供 Result 类型和工具，用于处理可能成功或失败的操作，
+ * 而无需抛出异常。
+ */
+
+/**
+ * 创建包含给定值的成功 Result。
+ *
+ * @example
+ * ```typescript
+ * const result = ok(42);
+ * // { _tag: 'Ok', value: 42 }
+ * ```
+ *
+ * @template T - 成功值的类型
+ * @param value - 成功值
+ * @returns 包含该值的 Ok Result
+ */
+declare function ok<T>(value: T): Ok<T>;
+/**
+ * 创建包含给定错误的失败 Result。
+ *
+ * @example
+ * ```typescript
+ * const result = err(new Error('出错了'));
+ * // { _tag: 'Err', error: Error('出错了') }
+ * ```
+ *
+ * @template E - 错误的类型
+ * @param error - 错误值
+ * @returns 包含该错误的 Err Result
+ */
+declare function err<E>(error: E): Err<E>;
+/**
+ * 类型守卫，用于检查 Result 是否为 Ok。
+ *
+ * @example
+ * ```typescript
+ * const result = ok(42);
+ * if (isOk(result)) {
+ *   console.log(result.value); // 42
+ * }
+ * ```
+ *
+ * @template T - 成功类型
+ * @template E - 错误类型
+ * @param result - 要检查的 Result
+ * @returns 如果 Result 是 Ok 则返回 true
+ */
+declare function isOk<T, E>(result: Result<T, E>): result is Ok<T>;
+/**
+ * 类型守卫，用于检查 Result 是否为 Err。
+ *
+ * @example
+ * ```typescript
+ * const result = err('error');
+ * if (isErr(result)) {
+ *   console.log(result.error); // 'error'
+ * }
+ * ```
+ *
+ * @template T - 成功类型
+ * @template E - 错误类型
+ * @param result - 要检查的 Result
+ * @returns 如果 Result 是 Err 则返回 true
+ */
+declare function isErr<T, E>(result: Result<T, E>): result is Err<E>;
+/**
+ * 在 Result 的成功值上映射函数。
+ * 如果 Result 是 Err，则错误将原样传递。
+ *
+ * @example
+ * ```typescript
+ * const result = ok(5);
+ * const doubled = mapResult(result, x => x * 2);
+ * // { _tag: 'Ok', value: 10 }
+ *
+ * const error = err('error');
+ * const still = mapResult(error, x => x * 2);
+ * // { _tag: 'Err', error: 'error' }
+ * ```
+ *
+ * @template T - 原始成功类型
+ * @template U - 映射后的成功类型
+ * @template E - 错误类型
+ * @param result - 要映射的 Result
+ * @param fn - 要应用于成功值的函数
+ * @returns 带有映射值的新 Result
+ */
+declare function mapResult<T, U, E>(result: Result<T, E>, fn: UnaryFunction<T, U>): Result<U, E>;
+/**
+ * 在 Result 的成功值上映射返回 Result 的函数。
+ * 在其他库中这也被称为 `chain` 或 `bind`。
+ *
+ * @example
+ * ```typescript
+ * const safeDivide = (a: number, b: number): Result<number, string> =>
+ *   b === 0 ? err('除零错误') : ok(a / b);
+ *
+ * const result = ok(10);
+ * const divided = flatMapResult(result, x => safeDivide(x, 2));
+ * // { _tag: 'Ok', value: 5 }
+ *
+ * const divideByZero = flatMapResult(result, x => safeDivide(x, 0));
+ * // { _tag: 'Err', error: '除零错误' }
+ * ```
+ *
+ * @template T - 原始成功类型
+ * @template U - 映射后的成功类型
+ * @template E - 错误类型
+ * @param result - 要 flatMap 的 Result
+ * @param fn - 应用的返回 Result 的函数
+ * @returns 展平后的 Result
+ */
+declare function flatMapResult<T, U, E>(result: Result<T, E>, fn: UnaryFunction<T, Result<U, E>>): Result<U, E>;
+/**
+ * 解包 Result，返回成功值或如果为 Err 则返回默认值。
+ *
+ * @example
+ * ```typescript
+ * const success = ok(42);
+ * unwrapOr(success, 0); // 42
+ *
+ * const failure = err('error');
+ * unwrapOr(failure, 0); // 0
+ * ```
+ *
+ * @template T - 成功类型
+ * @template E - 错误类型
+ * @param result - 要解包的 Result
+ * @param defaultValue - 如果为 Err 的默认值
+ * @returns 成功值或默认值
+ */
+declare function unwrapOr<T, E>(result: Result<T, E>, defaultValue: T): T;
+/**
+ * 解包 Result，返回成功值或如果为 Err 则调用函数。
+ *
+ * @example
+ * ```typescript
+ * const success = ok(42);
+ * unwrapOrElse(success, () => 0); // 42
+ *
+ * const failure = err('error');
+ * unwrapOrElse(failure, () => 0); // 0
+ * ```
+ *
+ * @template T - 成功类型
+ * @template E - 错误类型
+ * @param result - 要解包的 Result
+ * @param fn - 如果为 Err 要调用的函数
+ * @returns 成功值或函数的结果
+ */
+declare function unwrapOrElse<T, E>(result: Result<T, E>, fn: UnaryFunction<E, T>): T;
+/**
+ * 将 Result 与成功和错误处理程序匹配。
+ *
+ * @example
+ * ```typescript
+ * const result = ok(42);
+ * const message = match(result, {
+ *   ok: value => `得到 ${value}`,
+ *   err: error => `错误: ${error}`
+ * });
+ * // "得到 42"
+ * ```
+ *
+ * @template T - 成功类型
+ * @template E - 错误类型
+ * @template R - 返回类型
+ * @param result - 要匹配的 Result
+ * @param handlers - 带有 ok 和 err 处理程序的对象
+ * @returns 匹配处理程序的结果
+ */
+declare function matchResult<T, E, R>(result: Result<T, E>, handlers: {
+    ok: UnaryFunction<T, R>;
+    err: UnaryFunction<E, R>;
+}): R;
+/**
+ * 尝试执行函数并将结果包装在 Result 类型中。
+ *
+ * @example
+ * ```typescript
+ * const result = tryCatch(() => JSON.parse('{"a": 1}'));
+ * // { _tag: 'Ok', value: { a: 1 } }
+ *
+ * const error = tryCatch(() => JSON.parse('invalid'));
+ * // { _tag: 'Err', error: SyntaxError(...) }
+ * ```
+ *
+ * @template T - 函数的返回类型
+ * @param fn - 要执行的函数
+ * @returns 包含返回值或错误的 Result
+ */
+declare function tryCatch<T>(fn: () => T): Result<T, unknown>;
+/**
+ * 尝试执行异步函数并将结果包装在 Result 类型中。
+ *
+ * @example
+ * ```typescript
+ * const result = await tryCatchAsync(async () => {
+ *   const response = await fetch('/api/data');
+ *   return response.json();
+ * });
+ * ```
+ *
+ * @template T - 异步函数的返回类型
+ * @param fn - 要执行的异步函数
+ * @returns 包含返回值或错误的 Result 的 Promise
+ */
+declare function tryCatchAsync<T>(fn: () => Promise<T>): Promise<Result<T, unknown>>;
+
+/**
+ * @fileoverview 用于可空值处理的 Option 类型
+ * @module melange/fp/option
+ * @description 提供 Option 类型和工具，用于处理可能存在或不存在的值，
+ * 而不直接使用 null/undefined。
+ */
+
+/**
+ * 创建包含给定值的 Some Option。
+ *
+ * @example
+ * ```typescript
+ * const option = some(42);
+ * // { _tag: 'Some', value: 42 }
+ * ```
+ *
+ * @template T - 值的类型
+ * @param value - 要包装的值
+ * @returns 包含该值的 Some Option
+ */
+declare function some<T>(value: T): Some<T>;
+/**
+ * 创建表示缺失值的 None Option。
+ *
+ * @example
+ * ```typescript
+ * const option = none();
+ * // { _tag: 'None' }
+ * ```
+ *
+ * @returns None Option
+ */
+declare function none(): None;
+/**
+ * 类型守卫，用于检查 Option 是否为 Some。
+ *
+ * @example
+ * ```typescript
+ * const option = some(42);
+ * if (isSome(option)) {
+ *   console.log(option.value); // 42
+ * }
+ * ```
+ *
+ * @template T - 值的类型
+ * @param option - 要检查的 Option
+ * @returns 如果 Option 是 Some 则返回 true
+ */
+declare function isSome<T>(option: Option<T>): option is Some<T>;
+/**
+ * 类型守卫，用于检查 Option 是否为 None。
+ *
+ * @example
+ * ```typescript
+ * const option = none();
+ * if (isNone(option)) {
+ *   console.log('无值');
+ * }
+ * ```
+ *
+ * @template T - 值的类型
+ * @param option - 要检查的 Option
+ * @returns 如果 Option 是 None 则返回 true
+ */
+declare function isNone<T>(option: Option<T>): option is None;
+/**
+ * 从可空值创建 Option。
+ * 如果值为 null 或 undefined，返回 None；否则返回 Some。
+ *
+ * @example
+ * ```typescript
+ * fromNullable(42);       // Some(42)
+ * fromNullable(null);     // None
+ * fromNullable(undefined);// None
+ * ```
+ *
+ * @template T - 值的类型
+ * @param value - 可空值
+ * @returns 包装该值的 Option
+ */
+declare function fromNullable<T>(value: T | null | undefined): Option<T>;
+/**
+ * 在 Option 的值上映射函数。
+ * 如果 Option 是 None，则原样返回 None。
+ *
+ * @example
+ * ```typescript
+ * const option = some(5);
+ * const doubled = mapOption(option, x => x * 2);
+ * // Some(10)
+ *
+ * const empty = none();
+ * const still = mapOption(empty, x => x * 2);
+ * // None
+ * ```
+ *
+ * @template T - 原始值类型
+ * @template U - 映射后的值类型
+ * @param option - 要映射的 Option
+ * @param fn - 要应用于值的函数
+ * @returns 带有映射值的新 Option
+ */
+declare function mapOption<T, U>(option: Option<T>, fn: UnaryFunction<T, U>): Option<U>;
+/**
+ * 在 Option 的值上映射返回 Option 的函数。
+ * 在其他库中这也被称为 `chain` 或 `bind`。
+ *
+ * @example
+ * ```typescript
+ * const safeDivide = (n: number): Option<number> =>
+ *   n === 0 ? none() : some(100 / n);
+ *
+ * const option = some(10);
+ * const divided = flatMapOption(option, safeDivide);
+ * // Some(10)
+ *
+ * const zero = some(0);
+ * const divideByZero = flatMapOption(zero, safeDivide);
+ * // None
+ * ```
+ *
+ * @template T - 原始值类型
+ * @template U - 映射后的值类型
+ * @param option - 要 flatMap 的 Option
+ * @param fn - 应用的返回 Option 的函数
+ * @returns 展平后的 Option
+ */
+declare function flatMapOption<T, U>(option: Option<T>, fn: UnaryFunction<T, Option<U>>): Option<U>;
+/**
+ * 从 Option 获取值，如果为 None 则返回默认值。
+ *
+ * @example
+ * ```typescript
+ * const present = some(42);
+ * getOrElse(present, 0); // 42
+ *
+ * const absent = none();
+ * getOrElse(absent, 0); // 0
+ * ```
+ *
+ * @template T - 值的类型
+ * @param option - 要解包的 Option
+ * @param defaultValue - 如果为 None 的默认值
+ * @returns 值或默认值
+ */
+declare function getOrElse<T>(option: Option<T>, defaultValue: T): T;
+/**
+ * 从 Option 获取值，如果为 None 则调用函数。
+ *
+ * @example
+ * ```typescript
+ * const present = some(42);
+ * getOrElseL(present, () => 0); // 42
+ *
+ * const absent = none();
+ * getOrElseL(absent, () => computeDefault()); // computeDefault() 的结果
+ * ```
+ *
+ * @template T - 值的类型
+ * @param option - 要解包的 Option
+ * @param fn - 如果为 None 要调用的函数
+ * @returns 值或函数的结果
+ */
+declare function getOrElseL<T>(option: Option<T>, fn: () => T): T;
+/**
+ * 将 Option 与 Some 和 None 处理程序匹配。
+ *
+ * @example
+ * ```typescript
+ * const option = some(42);
+ * const message = matchOption(option, {
+ *   some: value => `得到 ${value}`,
+ *   none: () => '无'
+ * });
+ * // "得到 42"
+ * ```
+ *
+ * @template T - 值的类型
+ * @template R - 返回类型
+ * @param option - 要匹配的 Option
+ * @param handlers - 带有 some 和 none 处理程序的对象
+ * @returns 匹配处理程序的结果
+ */
+declare function matchOption<T, R>(option: Option<T>, handlers: {
+    some: UnaryFunction<T, R>;
+    none: () => R;
+}): R;
+/**
+ * 将 Option 转换为可空值。
+ *
+ * @example
+ * ```typescript
+ * toNullable(some(42)); // 42
+ * toNullable(none());   // null
+ * ```
+ *
+ * @template T - 值的类型
+ * @param option - 要转换的 Option
+ * @returns 值或 null
+ */
+declare function toNullable<T>(option: Option<T>): T | null;
+/**
+ * 基于谓词过滤 Option。
+ * 如果 Option 是 Some 且谓词返回 false，则返回 None。
+ *
+ * @example
+ * ```typescript
+ * const option = some(10);
+ * filter(option, x => x > 5);  // Some(10)
+ * filter(option, x => x > 15); // None
+ * ```
+ *
+ * @template T - 值的类型
+ * @param option - 要过滤的 Option
+ * @param predicate - 谓词函数
+ * @returns 如果谓词通过则返回 Option，否则返回 None
+ */
+declare function filterOption<T>(option: Option<T>, predicate: (value: T) => boolean): Option<T>;
+/**
+ * 返回第一个为 Some 的 Option，如果都是 None 则返回 None。
+ *
+ * @example
+ * ```typescript
+ * alt(none(), some(42)); // Some(42)
+ * alt(some(1), some(2)); // Some(1)
+ * alt(none(), none());   // None
+ * ```
+ *
+ * @template T - 值的类型
+ * @param first - 第一个 Option
+ * @param second - 第二个 Option
+ * @returns 第一个 Some Option，或 None
+ */
+declare function alt<T>(first: Option<T>, second: Option<T>): Option<T>;
+
+/**
+ * @fileoverview 高阶函数和工具
+ * @module melange/fp/hof
+ * @description 提供高阶函数用于记忆化、函数控制
+ * 和其他函数式编程工具。
+ */
+
+/**
+ * 创建函数的记忆化版本。
+ * 记忆化函数根据提供的参数缓存结果。
+ *
+ * @description
+ * 记忆化是一种优化技术，存储昂贵函数调用的结果，
+ * 当相同输入再次出现时返回缓存结果。
+ *
+ * @example
+ * ```typescript
+ * const expensiveCalculation = (n: number) => {
+ *   console.log('计算中...');
+ *   return n * n;
+ * };
+ *
+ * const memoized = memoize(expensiveCalculation);
+ * memoized(5); // 记录 '计算中...', 返回 25
+ * memoized(5); // 从缓存返回 25, 无记录
+ * memoized(3); // 记录 '计算中...', 返回 9
+ * ```
+ *
+ * @template T - 函数类型
+ * @param fn - 要记忆化的函数
+ * @param keyFn - 生成缓存键的可选函数
+ * @returns 函数的记忆化版本
+ */
+declare function memoize<T extends AnyFunction>(fn: T, keyFn?: (...args: Parameters<T>) => string): T;
+/**
+ * 创建只能调用一次的函数。
+ * 后续调用返回第一次调用的结果。
+ *
+ * @example
+ * ```typescript
+ * const initialize = once(() => {
+ *   console.log('初始化中...');
+ *   return { initialized: true };
+ * });
+ *
+ * initialize(); // 记录 '初始化中...', 返回 { initialized: true }
+ * initialize(); // 返回 { initialized: true }, 无记录
+ * ```
+ *
+ * @template T - 函数类型
+ * @param fn - 要包装的函数
+ * @returns 只能调用一次的函数
+ */
+declare function once<T extends AnyFunction>(fn: T): T;
+/**
+ * 创建调用原始函数然后执行副作用的函数，返回原始结果。
+ *
+ * @description
+ * Tap 适用于在管道中调试或记录日志
+ * 而不影响数据流。
+ *
+ * @example
+ * ```typescript
+ * const addOne = (x: number) => x + 1;
+ * const logValue = tap((x: number) => console.log('值:', x));
+ *
+ * pipe(
+ *   5,
+ *   addOne,
+ *   logValue, // 记录 '值: 6', 返回 6
+ *   x => x * 2
+ * ); // 返回 12
+ * ```
+ *
+ * @template T - 值类型
+ * @param effect - 要执行的副作用函数
+ * @returns 执行副作用并返回输入的函数
+ */
+declare function tap<T>(effect: (value: T) => void): (value: T) => T;
+/**
+ * 返回传入的值而不改变。
+ * 恒等函数作为默认转换器很有用。
+ *
+ * @example
+ * ```typescript
+ * identity(42);     // 42
+ * identity('hello'); // 'hello'
+ * [1, 2, 3].map(identity); // [1, 2, 3]
+ * ```
+ *
+ * @template T - 值类型
+ * @param value - 要返回的值
+ * @returns 相同的值
+ */
+declare function identity<T>(value: T): T;
+/**
+ * 创建总是返回相同值的函数。
+ * 适用于创建占位符函数。
+ *
+ * @example
+ * ```typescript
+ * const alwaysFive = constant(5);
+ * alwaysFive();  // 5
+ * alwaysFive(100); // 5
+ *
+ * [1, 2, 3].map(constant('x')); // ['x', 'x', 'x']
+ * ```
+ *
+ * @template T - 值类型
+ * @param value - 总是返回的值
+ * @returns 总是返回值的函数
+ */
+declare function constant<T>(value: T): () => T;
+/**
+ * 不执行任何操作并返回 undefined 的函数。
+ * 适合作为默认回调或占位符。
+ *
+ * @example
+ * ```typescript
+ * const callback = maybeCallback || noop;
+ * callback();
+ * ```
+ */
+declare function noop(): void;
+/**
+ * 否定谓词函数。
+ *
+ * @example
+ * ```typescript
+ * const isEven = (n: number) => n % 2 === 0;
+ * const isOdd = not(isEven);
+ *
+ * isOdd(3); // true
+ * isOdd(4); // false
+ * ```
+ *
+ * @template T - 参数类型
+ * @param predicate - 要否定的谓词
+ * @returns 否定的谓词
+ */
+declare function not<T>(predicate: (value: T) => boolean): (value: T) => boolean;
+/**
+ * 创建当所有谓词都返回 true 时返回 true 的函数。
+ *
+ * @example
+ * ```typescript
+ * const isPositive = (n: number) => n > 0;
+ * const isEven = (n: number) => n % 2 === 0;
+ * const isPositiveEven = allPass([isPositive, isEven]);
+ *
+ * isPositiveEven(4);  // true
+ * isPositiveEven(-4); // false
+ * isPositiveEven(3);  // false
+ * ```
+ *
+ * @template T - 参数类型
+ * @param predicates - 要检查的谓词数组
+ * @returns 当所有谓词都通过时返回 true 的函数
+ */
+declare function allPass<T>(predicates: Array<(value: T) => boolean>): (value: T) => boolean;
+/**
+ * 创建当任何谓词返回 true 时返回 true 的函数。
+ *
+ * @example
+ * ```typescript
+ * const isZero = (n: number) => n === 0;
+ * const isNegative = (n: number) => n < 0;
+ * const isNotPositive = anyPass([isZero, isNegative]);
+ *
+ * isNotPositive(0);  // true
+ * isNotPositive(-1); // true
+ * isNotPositive(1);  // false
+ * ```
+ *
+ * @template T - 参数类型
+ * @param predicates - 要检查的谓词数组
+ * @returns 当任何谓词通过时返回 true 的函数
+ */
+declare function anyPass<T>(predicates: Array<(value: T) => boolean>): (value: T) => boolean;
+/**
+ * 翻转二元函数的参数。
+ *
+ * @example
+ * ```typescript
+ * const divide = (a: number, b: number) => a / b;
+ * const flippedDivide = flip(divide);
+ *
+ * divide(10, 2);       // 5
+ * flippedDivide(10, 2); // 0.2
+ * ```
+ *
+ * @template A - 第一个参数类型
+ * @template B - 第二个参数类型
+ * @template R - 返回类型
+ * @param fn - 要翻转的函数
+ * @returns 参数翻转后的函数
+ */
+declare function flip<A, B, R>(fn: (a: A, b: B) => R): (b: B, a: A) => R;
+/**
+ * 将值应用到函数。
+ * 适用于无点编程。
+ *
+ * @example
+ * ```typescript
+ * const addOne = (x: number) => x + 1;
+ * apply(5, addOne); // 6
+ *
+ * const funcs = [x => x + 1, x => x * 2];
+ * funcs.map(f => apply(5, f)); // [6, 10]
+ * ```
+ *
+ * @template T - 值类型
+ * @template R - 返回类型
+ * @param value - 要应用的值
+ * @param fn - 要应用的函数
+ * @returns 将值应用到函数的结果
+ */
+declare function apply<T, R>(value: T, fn: (value: T) => R): R;
+/**
+ * 从值创建 thunk（延迟计算）。
+ *
+ * @example
+ * ```typescript
+ * const lazyValue = thunk(expensiveComputation);
+ * // ... 稍后
+ * const result = lazyValue(); // 计算在此处发生
+ * ```
+ *
+ * @template T - 返回类型
+ * @param fn - 要延迟的函数
+ * @returns 调用时执行函数的 thunk
+ */
+declare function thunk<T>(fn: () => T): () => T;
+/**
+ * 反转布尔值。
+ *
+ * @example
+ * ```typescript
+ * invert(true);  // false
+ * invert(false); // true
+ * ```
+ *
+ * @param value - 要反转的布尔值
+ * @returns 反转后的布尔值
+ */
+declare function invert(value: boolean): boolean;
+
+export { allPass, alt, anyPass, apply, compose, constant, curry, err, filterOption, flatMapOption, flatMapResult, flip, flow, fromNullable, getOrElse, getOrElseL, identity, invert, isErr, isNone, isOk, isSome, mapOption, mapResult, matchOption, matchResult, memoize, none, noop, not, ok, once, partial, partialRight, pipe, some, tap, thunk, toNullable, tryCatch, tryCatchAsync, uncurry, unwrapOr, unwrapOrElse };