gamla v118.0.0

Gamla

gamla is a zero-deps functional programming library for JavaScript/TypeScript, denoo and nodejs.

Installation

nodejs: npm install gamla

deno: import { pipe } from "https://deno.land/x/gamla/src/index.ts";

Intro

This library allows you to write in typescript/javascript using composition.

It has three main advantages over the native functional APIs and similar libs (ramda and lodash):

1. It helps you combine async functions with regular ones, without having to change your code.
2. As opposed to ramda and lodash, It keeps typing information, so you get type safety when programming in pipelines.
3. As opposed to ramda and lodash, you get a stack trace that logs your compositions too, so you can debug as usual.

Use cases

Basic Example

type Person = { name: string; age: number };

const people: Person[] = [
  { name: "alice", age: 28 },
  { name: "bob", age: 22 },
  { name: "carroll", age: 76 },
];

const getNamesOfPeopleOlderThan25 = pipe(
  filter(({ age }) => age > 25),
  sideEffect(console.log), // Log mid pipeline.
  map(({ name }) => name), // Get people names only.
  join(", "),
);

console.log(getNamesOfPeopleOlderThan25(people)); // "alice, carroll"

Async programming

Now let's imagine you wanted to call a remote server for some information somewhere in this pipeline. Usually this means refactoring your entire program to async functions.

But pipe is smart and allows you to change one function without the ones around it. No collateral refactoring is needed.

// Call some remote server to get hobbies for a person.
const getHobbies = async (person: Person): string[] => {...} 

const isAnyoneUnder25InterestedInGolfing = pipe(
  filter(({ age }: Person) => age < 25),
  // Async function mid pipeline, even tho functions before and after are not.
  // Also flatten the result.
  mapCat(getHobbies),
  includes('golfing'),
);

console.log(await isAnyoneUnder25InterestedInGolfing(people)); // probably `false` :)

IO and multithreading

gamla also has a bunch of methods to facilitate parallel IO operations. Consider the following case:

• you have a list of 1000 items
• you have an async function process(item)
• you need to process all items
• it needs to be done concurrently, but not more than 25 at a time

This seemingly complex list of requirements is a simple readable one liner:

map(throttle(25, process))(items);

Here's another example, the OpenAI API has rate limitations, which will block your requests at some point. rateLimit can help you avoid these exceptions.

// This is how each request's weight is computed.
const weightFn = pipe(
  map(({ content }: ChatCompletionMessage) => (content || "").length),
  sum,
  divide(4), // For english, a token is around 4 characters.
);

const callAPI = (messages: ChatCompletionMessage[]) =>
  new OpenAI(assertString(OpenAIToken)).createChatCompletion({
    model: "gpt-4",
    messages,
  });

// 10KTPM-200RPM is the official limitation for GPT-4, this means maximum 200 requests per minute, and not more than 10000 tokens.
const callAPIWithRateLimiter = rateLimit(
  200, // Max requests in time window.
  10000, // Max total 'weight' in time window.
  60 * 1000, // Time window to apply the limitation.
  weightFn,
  callAPI,
);

Type safety

gamla preserves typing, so if you by accident you write something like this:

const typingMismatch = pipe(
  filter(({ age }: Person) => age < 25),
  (x: number) => x + 1, // The result of `filter` here is an array of `Person`, not a number!
);

You will get a typing error.

Debugging

gamla has a lot of utils for debugging. The most useful ones are sideLog, sideLogAfter and sideLogBefore. Their prpose is to allow logging without moving any code around.

E.g. you have a complex expression like so:

someCondition ? f(a + g(b)) : c;

And you want to log the value of g(b) without inteferring with the code. Usually that would require rewriting a bit, placing the value into a variable and using console.log. But with sideLog you can just do:

someCondition ? f(a + sideLog(g(b))) : c;

Similarly, if you're working with pipelines and want to log somewhere in the middle:

pipe(
  f,
  g,
  sideLog, // Would log the output of `g`.
  h,
);

If you want to keep typing information, use sideLogAfter or sideLogBefore:

pipe(f, sideLogAfter(g), h); // Would log the output of `g`.

pipe(f, g, sideLogBefore(h)); // Would log the input to `h`. So same.

anymap

anymap<X>(f: (x: X) => boolean): (xs: X[]) => boolean

The anymap function takes a predicate function f and returns a new function that takes an array xs and checks if any element in the array satisfies the predicate f. It returns a boolean value indicating the result.

Example

const numbers = [1, 2, 3, 4, 5];
const isEven = (x: number) => x % 2 === 0;

const anyEven = anymap(isEven);
const result = anyEven(numbers); // checks if any number in the array is even

console.log(result); // Output: true

In the example above, the anymap function is used to create a new function anyEven that checks if any number in an array is even. The result is true because there is at least one even number in the array [1, 2, 3, 4, 5].

allmap

(f: (x: X) => boolean) => (xs: X[]) => xs.every(f)

This function takes a predicate function f and returns a new function that takes an array xs and returns true if f returns true for every element in xs, or false otherwise.

Parameters:

• f: (x: X) => boolean - A predicate function that takes an element x of type X and returns a boolean value. It determines the condition to be checked for each element in the input array.

Returns:

• (xs: X[]) => boolean - A function that takes an array xs of type X and returns true if f returns true for every element in xs, or false otherwise.

Example

const isEven = (x: number) => x % 2 === 0;

const allNumbersEven = allmap(isEven);
const result = allNumbersEven([2, 4, 6, 8]);

console.log(result); // Output: true

In the above example, the allNumbersEven function is created by passing the isEven function to allmap. It checks if every element in the input array [2, 4, 6, 8] is even using the isEven function. The resulting value is true, as all numbers in the array are even.

join

Signature: (str: string) => (x: (string | number)[]) => string

This function takes a string parameter str as its first argument and returns a new function. The returned function takes an array x of string or number elements and joins them into a single string using the specified separator str.

Example

const numbers = [1, 2, 3, 4, 5];
const joinWithComma = join(",");
console.log(joinWithComma(numbers));

Output:

"1,2,3,4,5"

The function is curried, allowing you to partially apply the string separator before applying it to the array.

length

Returns the number of elements in an array.

Signature

length<T>(array: T[]): number

Parameters

• array: An array of type T[]. The array for which the length is to be determined.

Returns

The function returns a number representing the number of elements in the array.

Example

const array = [1, 2, 3, 4, 5];
const result = length(array);
console.log(result); // Output: 5

unique

unique<T>(key: (x: T) => Primitive): (array: T[]) => any[]

This function takes an array and a key function as parameters and returns a new array with unique items based on the key.

• key: A function that extracts a primitive value from each item in the array.

Example

const array = [
  { id: 1, name: "John" },
  { id: 2, name: "Jane" },
  { id: 1, name: "John" },
  { id: 3, name: "John" },
];

const uniqueById = unique((item) => item.id);
const uniqueArray = uniqueById(array);

console.log(uniqueArray);
// Output: [
//   { id: 1, name: 'John' },
//   { id: 2, name: 'Jane' },
//   { id: 3, name: 'John' },
// ]

In this example, the unique function is used to remove duplicates from the array of objects based on the id property. The resulting array only contains objects with unique id values.

concat

Concatenates an array of arrays into a single array.

Signature

(array: unknown[][]) => any[]

Parameters

• array: An array of arrays to be concatenated. Each sub-array can contain elements of any type.

Returns

• Returns a new array containing all elements from the input arrays.

Example

const result = concat([[1, 2], [3, 4], [5, 6]]);
console.log(result); // Output: [1, 2, 3, 4, 5, 6]

In the example above, the concat function is called with an input array [[1, 2], [3, 4], [5, 6]]. It returns a new array [1, 2, 3, 4, 5, 6] where the elements from the sub-arrays are concatenated into a single array.

reverse

Signature: reverse(array: Input): Reversed<Input>

Parameters:

• array - An array of unknown type.

Return Type: Reversed<Input>

The reverse function takes an array and returns a new array with the elements reversed.

Example

const arr = [1, 2, 3, 4];
const reversedArray = reverse(arr);
console.log(reversedArray); // Output: [4, 3, 2, 1]

tail

tail(x: unknown[]): unknown[]

The tail function takes an array x and returns a new array with all the elements except the first element.

Example

const arr = [1, 2, 3, 4, 5];
const result = tail(arr);
console.log(result);
// Output: [2, 3, 4, 5]

In the example above, the tail function is used to remove the first element of the arr array. The resulting array [2, 3, 4, 5] is then stored in the result variable and logged to the console.

head

Returns the first element of an array or string.

Signature

head<T extends (any[] | string)>(x: T): T[0]

Parameters

• x: The array or string from which to retrieve the first element.

Returns

The first element of the given array or string.

Example

const arr = [1, 2, 3, 4];
const str = "Hello";

const firstElementOfArr = head(arr); // 1
const firstCharacterOfStr = head(str); // "H"

init

init(x: unknown[]): unknown[]

This function takes an array x and returns a new array with all elements except the last one.

Parameters

• x: unknown[]: The array to be modified.

Returns

• unknown[]: A new array with all elements of x except the last one.

Example

const arr = [1, 2, 3, 4, 5];
const result = init(arr);
console.log(result); // Output: [1, 2, 3, 4]

In the above example, the init function is called with the arr array as an argument. The function returns a new array [1, 2, 3, 4], which contains all elements of the original array arr except the last one.

second

function second<T extends (unknown[] | string)>(x: T): T[1];

The second function takes an argument x of type T, where T is an array or a string. It returns the second element (index 1) of the array or string.

Example

console.log(second([1, 2, 3])); // Output: 2
console.log(second("hello")); // Output: 'e'

In the first example, the second function returns 2, which is the second element in the array [1, 2, 3]. In the second example, it returns 'e', which is the second character in the string 'hello'.

third

Signature: function third<T extends (unknown[] | string)>(x: T): T[2]

Returns the third element of the input array or string.

• T generic type that extends an array or string.
• x the input array or string.

Example

third([1, 2, 3, 4]); // returns 3
third("hello"); // returns 'l'

last

Signature: <T>(x: T[]) => x[x.length - 1]

The last function takes an array x of type T[] and returns the last element of the array.

Example

const numbers = [1, 2, 3, 4, 5];
const lastNumber = last(numbers);
console.log(lastNumber); // Output: 5

const names = ["Alice", "Bob", "Charlie", "David"];
const lastName = last(names);
console.log(lastName); // Output: "David"

empty

empty<T>(x: T[]): boolean

This function checks if an array is empty.

Parameters

• x: T[] - The array to check if it is empty.

Returns

• boolean - Returns true if the array is empty, false otherwise.

Example

const arr1 = [1, 2, 3];
const arr2 = [];

empty(arr1); // false
empty(arr2); // true

nonempty(x: T[]): boolean

This function checks if an array x is non-empty.

Parameters

• x: T[] - an array of any type T

Returns

• boolean - true if the array x is non-empty, false otherwise

Example

const arr1: number[] = [1, 2, 3];
const arr2: string[] = [];
const arr3: boolean[] = [true, false];

console.log(nonempty(arr1)); // Output: true
console.log(nonempty(arr2)); // Output: false
console.log(nonempty(arr3)); // Output: true

wrapArray

Signature: (x: T) => T[]

Description:

This function takes an input value x and returns an array containing x as its only element. It essentially wraps the given value in an array.

Example

wrapArray("hello"); // returns ["hello"]
wrapArray(42); // returns [42]
wrapArray({ name: "John", age: 25 }); // returns [{ name: "John", age: 25 }]

zip

zip<T extends unknown[][]>(
  ...args: T
): { [K in keyof T]: T[K] extends (infer V)[] ? V : never }[]

The zip function takes in multiple arrays as arguments (spread syntax) and returns a new array composed of the corresponding elements from each input array.

Parameters

• ...args: T: The arrays to zip together. The type T represents a tuple of arrays, where each array may have different element types.

Return Type

The return type is an array of tuples, where each tuple contains the corresponding elements from the input arrays. The element types of the tuples are inferred from the input arrays, and any arrays with different element types will result in a type of never for that position in the resulting tuple.

Example

const array1 = [1, 2, 3];
const array2 = ["a", "b", "c"];
const array3 = [true, false, true];

const zipped = zip(array1, array2, array3);
// zipped = [
//   [1, 'a', true],
//   [2, 'b', false],
//   [3, 'c', true],
// ]

In this example, the zip function is called with three arrays of different element types. The resulting zipped array contains tuples where the first element is a number, the second element is a string, and the third element is a boolean.

sortCompare

comparator:
((x: X, y: X) => number | boolean);

The sortCompare function is a higher-order function that takes a comparator function as input and returns a new function that can be used to sort an array.

Example

const numbers = [3, 1, 2];
const descendingComparator = (x: number, y: number) => y - x;
const sortedNumbers = sortCompare(descendingComparator)(numbers);
console.log(sortedNumbers); // [3, 2, 1]

In this example, the sortCompare function is used to sort an array of numbers in descending order using a custom comparator function. The resulting sorted array is then logged to the console.

sortKey

sortKey is a higher-order function that takes a key function as a parameter and returns a sortCompare function.

Signature

sortKey<X>(key: (_: X) => Comparable): (xs: X[]) => X[]

Parameters

• key : A function that takes an element of type X and returns a value of type Comparable. This value will be used to compare elements during sorting.

Return Type

• (xs: X[]) => X[] : A function that takes an array of type X and returns a sorted array of type X based on the key function.

Example

const sortByAge = sortKey((person) => person.age);
const people = [
  { name: "Alice", age: 25 },
  { name: "Bob", age: 30 },
  { name: "Charlie", age: 20 },
];
const sortedPeople = sortByAge(people);
console.log(sortedPeople);
// Output: [
//   { name: "Charlie", age: 20 },
//   { name: "Alice", age: 25 },
//   { name: "Bob", age: 30 }
// ]

In the example above, sortKey is used to create a sortByAge function that can sort an array of people based on their age. The key function is provided as a lambda function (person) => person.age. The sortByAge function is then used to sort the people array and the result is stored in the sortedPeople array. The sortedPeople array is then printed to the console showing the sorted order based on the age of the people.

range

range(start: number, end: number): any[]

Creates an array of numbers from start to end (exclusive).

Parameters

• start: The starting number of the range.
• end: The ending number of the range (exclusive).

Return Type

• any[]: An array of numbers.

Example

const numbers = range(1, 5);
console.log(numbers);
// Output: [1, 2, 3, 4]

In this example, range(1, 5) returns an array of numbers from 1 to 4 (exclusive). The resulting array is [1, 2, 3, 4].

contains

Signature: (x: T) => (array: T[]) => boolean

The contains function takes a value x of generic type T and returns a closure that takes an array array of type T[] and returns a boolean value indicating whether the array contains the given value or not.

Example

const checkForValue = contains(3);
console.log(checkForValue([1, 2, 3, 4])); // true
console.log(checkForValue([5, 6, 7])); // false

includedIn

Returns a function that checks if a given value is included in an array.

Signature

(<T>(array: T[]) => (x: T) => array.includes(x));

Parameters

• array: An array of values to check if the given value is included.

Returns

A function that takes a value (x) and returns true if the value is included in the array, otherwise false.

Example

const fruits = ["apple", "banana", "orange"];
const isIncluded = includedIn(fruits);

console.log(isIncluded("apple")); // true
console.log(isIncluded("grape")); // false

take

Signature: (n: number) => (xs: T[]) => T[]

This function takes a number n and returns a function that takes an array xs and returns a new array containing the first n elements of xs.

Example

const takeThree = take(3);
const numbers = [1, 2, 3, 4, 5];
console.log(takeThree(numbers)); // Output: [1, 2, 3]

drop

(n: number) => (xs: T[]) => T[]

This function takes a number n as its argument and returns another function that accepts an array xs. It returns a new array containing the elements of xs starting from index n onwards.

Example

const dropThree = drop(3);
const numbers = [1, 2, 3, 4, 5];
const result = dropThree(numbers); // [4, 5]

enumerate

enumerate<T>(xs: T[]): (number | T)[][]

The enumerate function takes an array xs and returns an array of arrays of pairs containing the index and value of each element in the original array.

Parameters

• xs: T[] : The input array.

Returns

(number | T)[][] : An array of arrays where each inner array contains the index and value of an element from the input array.

Example

const array = ["a", "b", "c"];
const result = enumerate(array);
// result is [[0, 'a'], [1, 'b'], [2, 'c']]

slidingWindow

(<T>(l: number) => (xs: T[]) =>
  xs.flatMap((_, i) => (i <= xs.length - l ? [xs.slice(i, i + l)] : [])));

Creates a function that returns a sliding window view of a given array.

Parameters

• l: number: The size of the sliding window.

Returns

• (xs: T[]) => any: A function that takes an array of type T and returns an array of sliding window views.

Example

const getWindowViews = slidingWindow(3);
const inputArray = [1, 2, 3, 4, 5];
const outputArray = getWindowViews(inputArray);
console.log(outputArray); // [[1, 2, 3], [2, 3, 4], [3, 4, 5]]

In the example above, the slidingWindow function is used to create a function getWindowViews that generates sliding window views of size 3. The inputArray is then passed to getWindowViews and the resulting outputArray contains all sliding window views: [[1, 2, 3], [2, 3, 4], [3, 4, 5]].

pipe

Creates a pipeline of functions by composing them together. The output of one function serves as the input to the next function in the pipeline.

Signature

pipe<Fs extends Func[]>(...fs: ValidPipe<Fs>): Pipeline<Fs>

Parameters

• ...fs: ValidPipe<Fs>: Rest parameter that accepts a series of functions to be piped together. Each function in the pipeline should have compatible input and output types.

Return Type

• Pipeline<Fs>: The type of the pipeline, which represents a function that takes multiple arguments and returns the final output after applying each function in the pipeline.

Example

const add = (a: number, b: number): number => a + b;
const double = (x: number): number => x * 2;
const subtract = (a: number, b: number): number => a - b;

const myPipeline = pipe(add, double, subtract);
const result = myPipeline(5, 2); // Result: ((5 + 2) * 2) - 2 = 12

In the example above, myPipeline is created by piping together the add, double, and subtract functions. When myPipeline is called with arguments 5 and 2, it applies each function in the pipeline sequentially and returns the final output 12.

compose

Signature:

compose<Fs extends Func[]>(...fs: Fs): Fs extends ValidPipe<Reversed<Fs>> ? Pipeline<Reversed<Fs>> : never

Compose takes in an array of functions and returns a new function that is the composition of these functions. The returned function takes in an initial input and passes it through each function in the array, applying them in reverse order.

If the array of functions is a valid pipe (i.e., each function's return type matches the argument type of the next function), the return type of the composed function is a pipeline of the reversed array of functions. Otherwise, it returns never.

Example:

const addOne = (num: number) => num + 1;
const double = (num: number) => num * 2;
const subtract = (num1: number, num2: number) => num1 - num2;

const composed = compose(addOne, double, subtract);
const result = composed(5, 2);

console.log(result); // Output: 16

In the example above, we have three functions: addOne, double, and subtract. We use compose to create a new function composed by composing these functions. When we invoke composed with the arguments 5 and 2, the composition is applied in reverse order: subtract is first called with the arguments 5 and 2, the result is then passed to double, and finally the output of double is passed to addOne. The final result is 16.

after

(<T>(f: UnaryFn<T, unknown>) => <L extends unknown[]>(g: (...args: L) => T) =>
  pipe(g, f));

The after function is a higher-order function that takes another function f as an argument and returns a new function. The returned function takes a generic function g as an argument and returns the result of piping g through f using the pipe function.

Example

const double = (value: number): number => value * 2;
const square = (value: number): number => value * value;

const calculate = after(square)(double);

console.log(calculate(3)); // Output: 18

In the above example, after(square)(double) returns a new function calculate. When calculate is called with the argument 3, it pipes the argument through square and then through double, resulting in the output 18 (3 3 2 = 18).

before

before<T>(f1: (...args: unknown[]) => T): (f2: (input: T) => unknown) => Pipeline<[(...args: unknown[]) => T, (input: T) => unknown]>

The before function takes in a function f1 and returns a higher-order function that takes in another function f2. It then returns a Pipeline that consists of f1 and f2, with f1 as the first function in the pipeline and f2 as the second function.

Example

const addOne = (num: number) => num + 1;
const double = (num: number) => num * 2;

const pipeline = before(addOne)(double);
const result = pipeline(5); // 12

In the above example, addOne is the first function in the pipeline, and double is the second function. When the pipeline is called with the input 5, it applies addOne first, resulting in 6, and then applies double, resulting in 12.

complement

Signature: complement(f: F): (...x: Parameters<F>) => boolean

The complement function takes a function f as input and returns a new function that is the logical complement of f. The returned function takes the same arguments as f and returns a boolean value based on the negation of the result of f.

Parameters:

• f: The function to be complemented.

Return Type: (...x: Parameters<F>) => boolean

Example

const greaterThanTen = (num: number) => num > 10;
const isLessThanOrEqualToTen = complement(greaterThanTen);

console.log(isLessThanOrEqualToTen(5)); // true
console.log(isLessThanOrEqualToTen(15)); // false

In the above example, the complement function is used to create a new function isLessThanOrEqualToTen that is the logical complement of the greaterThanTen function. When isLessThanOrEqualToTen is called with a number, it returns true if the number is less than or equal to 10, and false otherwise.

sideEffect

(<T>(f: (_: T) => void) => (x: T) => {
  f(x);
  return x;
});

The sideEffect function is a higher-order function that takes a function f as its parameter. The parameter f is a function that accepts a value of type T and has a return type of void. The sideEffect function returns another function that also takes a value of type T as its parameter and returns the same value.

The purpose of the sideEffect function is to enable side effects by executing the function f with a given value of type T, while still returning that value. This allows for the execution of side effects without losing the reference to the value being operated on.

Example

const printAndReturn = sideEffect(console.log);
const result = printAndReturn("Hello, World!");

// Output: Hello, World!
console.log(result); // 'Hello, World!'

In this example, the sideEffect function is used to wrap the console.log function, enabling it to print a message to the console and return the same message. The printAndReturn function is then used to execute console.log('Hello, World!'), and the result is stored in the result variable, which is then logged to the console.

wrapSideEffect

Signature:

(<Args extends unknown[], Result>(
  cleanup: (...args: Args) => void | Promise<void>,
) =>
(f: (...args: Args) => Result) =>
(...args: Args) => any);

Parameters:

• cleanup: A function that takes in any number of arguments Args and returns either void or Promise<void>. This function will be executed after the wrapped function f is called.

Return Type:

(f: (...args: Args) => Result) => (...args: Args) => any

Description:

The wrapSideEffect function takes in a cleanup function and returns a new function that wraps another function f. The returned function takes in any number of arguments Args and returns a function that will execute the cleanup function after executing the wrapped function f.

If the result of f is a Promise, the cleanup function will be executed after the promise resolves. If the cleanup function also returns a Promise, the final result will be the result of the wrapped function. Otherwise, the final result will be the result of the cleanup function.

Example

const cleanupFunction = (arg1: string, arg2: number) => {
  console.log(`Cleaning up with arguments ${arg1} and ${arg2}`);
};

const wrappedFunction = wrapSideEffect(cleanupFunction)(
  (arg1: string, arg2: number) => {
    console.log(
      `Executing wrapped function with arguments ${arg1} and ${arg2}`,
    );
    return arg1 + arg2;
  },
);

wrappedFunction("Hello", 123);
// Output:
// Executing wrapped function with arguments Hello and 123
// Cleaning up with arguments Hello and 123
// Result: Hello123

applyTo

applyTo(...args: A): (f: (...args: A) => unknown) => unknown

This higher-order function takes in a variable number of arguments args of type A, and returns another function that takes in a function f which accepts the same arguments args and returns a value of type unknown.

Parameters

• ...args: A: A variadic parameter representing a variable number of arguments of type A.

Return Type

(f: (...args: A) => unknown) => unknown: A function that accepts a function f and returns a value of type unknown.

Example

const addNumbers = (a: number, b: number) => a + b;
const applyToExample = applyTo(10, 20);
const result = applyToExample(addNumbers); // 30

always

Signature: always<T>(x: T) => () => T

Creates a function that always returns the same value.

• x: The value to be always returned.

Returns: A function that when called, always returns the provided value x.

Example

const constantFunc = always(42);
console.log(constantFunc()); // Output: 42

identity

Signature: (x: T) => T

The identity function takes in an argument x of type T and returns it as is, without any modifications.

Example

const result: number = identity(5);
console.log(result); // Output: 5

const result2: string = identity("hello");
console.log(result2); // Output: "hello"

ifElse

ifElse<Predicate, If, Else>(
  predicate: Predicate,
  fTrue: If,
  fFalse: Else,
): (...x: Parameters<Predicate>) => [Predicate, If, Else] extends import("/home/uri/uriva/gamlajs/src/typing").AnyAsync<[Predicate, If, Else]> ? Promise<Awaited<ReturnType<If>> | Awaited<ReturnType<Else>>> : ReturnType<If> | ReturnType<Else>

This function takes a predicate, a function to execute if the predicate is true, and a function to execute if the predicate is false. It returns a new function that accepts the same arguments as the predicate and invokes either fTrue or fFalse based on the result of the predicate.

Example

const isEven = (num: number): boolean => num % 2 === 0;

const multiplyByTwo = (num: number): number => num * 2;
const divideByTwo = (num: number): number => num / 2;

const conditionalFunction = ifElse(
  isEven,
  multiplyByTwo,
  divideByTwo,
);

console.log(conditionalFunction(4)); // Output: 8
console.log(conditionalFunction(5)); // Output: 2.5

In the example above, the ifElse function is used to create a new function called conditionalFunction. This function checks if a given number is even, and if it is, it multiplies it by two. If the number is odd, it divides it by two. The conditionalFunction is then invoked with different input numbers to test the conditional logic.

unless

unless<Predicate extends (
  | ((_: any) => BooleanEquivalent)
  | ((_: any) => Promise<BooleanEquivalent>)
)>(
  predicate: Predicate,
  fFalse: (_: Parameters<Predicate>[0]) => any,
): (...x: Parameters<Predicate>) => [Predicate, (...x: Parameters<Predicate>) => any, (_: Parameters<Predicate>[0]) => any] extends ([Predicate, (...x: Parameters<Predicate>) => any, (_: Parameters<Predicate>[0]) => any] extends [infer _1 extends import("/home/uri/uriva/gamlajs/src/typing").AsyncFunction, ...infer _2] ? any : any) ? Promise<any> : any

The unless function takes a predicate function and a fFalse function. It returns a function that takes any number of arguments and checks if the predicate is false. If the predicate is false, it calls the fFalse function with the arguments and returns the result. If the predicate is true, it returns the arguments.

Example

const isFalsey = (x: any) => !x;

const fFalse = (x: any) => `The value ${x} is false`;

const result = unless(isFalsey, fFalse)(false);

console.log(result); // The value false is false

In this example, the unless function is used to check if the value false is falsey. Since it is falsey, the fFalse function is called with the value false and the result is returned.

when

when<Predicate extends (
  | ((_: any) => BooleanEquivalent)
  | ((_: any) => Promise<BooleanEquivalent>)
)>(predicate: Predicate, fTrue: (_: Parameters<Predicate>[0]) => any): (...x: Parameters<Predicate>) => [Predicate, (_: Parameters<Predicate>[0]) => any, (...x: Parameters<Predicate>) => any] extends ([Predicate, (_: Parameters<Predicate>[0]) => any, (...x: Parameters<Predicate>) => any] extends [infer _1 extends import("/home/uri/uriva/gamlajs/src/typing").AsyncFunction, ...infer _2] ? any : any) ? Promise<any> : any

The when function is a higher-order function that takes a predicate function and a callback function. It returns a new function that checks if the predicate function returns true, and if so, calls the callback function.

Parameters

• predicate: Predicate - The predicate function that determines whether the callback function should be called.
• fTrue: (_: Parameters<Predicate>[0]) => any - The callback function to be called if the predicate function returns true.

Return Value

The return value of when depends on the types of the Predicate and fTrue parameters. If the Predicate is an AsyncFunction, the return value is a Promise<any>. Otherwise, it is any.

Example

const isEven = (num: number) => num % 2 === 0;

const callback = (num: number) => {
  console.log(`${num} is even`);
};

const whenIsEven = when(isEven, callback);

whenIsEven(10); // logs "10 is even"
whenIsEven(5); // does nothing

In this example, the isEven function is used as the predicate to check if a number is even. If the number is even, the callback function is called and logs a message. The whenIsEven function is created using the when function, and when called with an even number, it logs a message.

cond

CondElements extends CondElement<any[]>[]

cond(
  predicatesAndResolvers: CondElements,
): (
  ...x: Parameters<CondElements[0][0]>
) => any

The cond function takes an array of predicates and resolvers and returns a function that when called with arguments, runs each predicate on the arguments and returns the result of the first resolver that matches the predicate.

Example

const isEven = (x: number) => x % 2 === 0;
const double = (x: number) => x * 2;
const triple = (x: number) => x * 3;

const resolver = cond([
  [isEven, double],
  [() => true, triple],
]);

console.log(resolver(4)); // Output: 8
console.log(resolver(3)); // Output: 9

logWith

Signature: (x: any[]) => (y: T) => T

Description:

This function takes in any number of arguments, ...x, and returns a new function that takes in a value y. The returned function logs the arguments passed in as x, along with y, to the console, and then returns y.

Example

const log = logWith("Hello");
const result = log("World");
// Output: Hello World
// result: "World"

asyncTimeit

asyncTimeit<Args extends unknown[], R>(
  handler: (time: number, args: Args, result: R) => void,
  f: (..._: Args) => R,
): (...args: Args) => Promise<R>

The asyncTimeit function is a higher-order function that takes a handler function and another function f, and returns a new function that measures the execution time of f and invokes the handler with the elapsed time, arguments, and result of f. The returned function is asynchronous and returns a promise of the result.

Parameters

• handler: (time: number, args: Args, result: R) => void - The handler function to be invoked with the elapsed time, arguments, and result of f.
• f: (..._: Args) => R - The function to be measured.

Returns

A new function that is asynchronous and returns a promise of the result of f.

Example

const fetchData = async (url: string) => {
  const response = await fetch(url);
  const data = await response.json();
  return data;
};

const timeHandler = (time: number, args: [string], result: any) => {
  console.log(`Fetch from ${args[0]} took ${time} milliseconds`);
};

const timedFetchData = asyncTimeit(timeHandler, fetchData);
const data = await timedFetchData("https://example.com/api/data");
console.log(data);

In the example above, the timedFetchData function is created by passing the timeHandler and fetchData functions to asyncTimeit. When timedFetchData is called with a URL, it measures the execution time of fetchData and logs the elapsed time. The result of fetchData is returned and can be used further in the code.

timeit

Signature: (handler: (time: number, args: Args, result: R) => void, f: (..._: Args) => R) => (...args: Args) => R

This function is a higher-order function that takes two parameters:

• handler: A function that receives three parameters: time (duration in milliseconds), args (the arguments passed to the inner function), and result (the result returned by the inner function).
• f: The inner function that will be timed.

The timeit function returns a new function that has the same signature as the inner function ((...args: Args) => R). This new function will measure the execution time of the inner function and call the handler function with the measured time, arguments, and result.

Example

const logTime = (time: number, args: number[], result: number) => {
  console.log(`Execution time: ${time}ms`);
  console.log(`Arguments: ${args}`);
  console.log(`Result: ${result}`);
};

const add = (a: number, b: number) => a + b;
const timedAdd = timeit(logTime, add);

timedAdd(2, 3);
// Output:
// Execution time: <duration>ms
// Arguments: 2, 3
// Result: 5

In this example, the logTime function logs the execution time, arguments, and result. The add function adds two numbers. The timedAdd function is created using timeit, passing logTime as the handler and add as the inner function. When timedAdd is called with arguments 2 and 3, it measures the execution time of add and logs the time, arguments, and result.

assert

(<T>(condition: (_: T) => boolean, errorMessage: string) => (x: T) => T);

The assert function takes a condition and an error message as parameters and returns a function that takes a value of type T and returns that value if the condition is true. If the condition is false, it throws an error with the given error message.

Example usage:

const greaterThanZero = assert(
  (x: number) => x > 0,
  "Number must be greater than zero",
);
const result = greaterThanZero(5); // returns 5
const error = greaterThanZero(-2); // throws an error with the message "Number must be greater than zero"

filter

filter<F extends Predicate>(f: F): (
  _: ParamOf<F>[],
) => true extends IsAsync<F> ? Promise<ParamOf<F>[]> : ParamOf<F>[]

This function takes in a predicate function f and returns a new function that filters an array based on that predicate. The filtered array is returned as the result.

• f: The predicate function that determines whether an element should be included in the filtered array or not.

Example

const isEven = (num: number) => num % 2 === 0;

const numbers = [1, 2, 3, 4, 5];

const filteredNumbers = filter(isEven)(numbers);

console.log(filteredNumbers); // Output: [2, 4]

In the above example, the filter function is used to filter out the even numbers from the numbers array. The resulting filtered array contains only the even numbers 2, 4.

find

Signature

((Fn: Predicate) => Pipeline);

Description

The find function takes a predicate function as an argument and returns a pipeline that filters an array based on the given predicate and returns the first element of the filtered array.

Example

const animals = ["cat", "dog", "elephant", "bird"];

const startsWithC = (animal) => animal.startsWith("c");

const result = find(startsWithC)(animals);

console.log(result); // 'cat'

In the above example, the find function is used to filter the animals array based on the startsWithC predicate function and returns the first element that matches the predicate, which is 'cat'.

Return Type

Pipeline<
  [
    (
      _: ParamOf<Fn>[],
    ) => Fn extends AsyncFunction ? Promise<ParamOf<Fn>[]> : ParamOf<Fn>[],
    <T extends string | any[]>(x: T) => T[0],
  ]
>;

The find function returns a pipeline that takes an array as input and returns the first element of the filtered array based on the provided predicate function.

remove

remove<F extends Predicate>(f: F): (x: Parameters<F>[0][]) => Parameters<F>[0][]

The remove function takes a predicate f and returns a new function that removes elements from an array that satisfy the predicate.

Parameters

• f: F: The predicate function to test each element of the array. The function f should accept an argument of the same type as the elements in the array and return a boolean.

Returns

• (x: Parameters<F>[0][]) => Parameters<F>[0][]: A new function that accepts an array and returns a new array with elements removed based on the provided predicate.

Example

const numbers = [1, 2, 3, 4, 5];

const isEven = (n: number): boolean => n % 2 === 0;

const removeEven = remove(isEven);
const result = removeEven(numbers);

console.log(result);
// Output: [1, 3, 5]

In the example above, the remove function is used to create a new function removeEven that removes even numbers from an array. The result array contains only the odd numbers [1, 3, 5].

intersectBy

<T>(f: (x: T) => Primitive) => (arrays: T[][]) => T[]

The intersectBy function takes a function f that maps elements of type T to Primitive, and returns another function that takes an array of arrays of type T (arrays). It then intersects all the arrays in arrays based on the values of f, and returns an array containing the common elements.

Parameters:

• f: (x: T) => Primitive - A function that maps elements of type T to Primitive. This function will be used to determine the intersections.

Returns:

• (arrays: T[][]) => T[] - The function takes an array of arrays of type T and returns an array of type T containing the common elements.

Example

const numbers = [[1, 2, 3, 4, 5], [2, 4, 6, 8, 10], [3, 6, 9, 12, 15]];
const intersectByPrimitive = intersectBy((x) => x % 10);

console.log(intersectByPrimitive(numbers));
// Output: [2, 4, 6]

const strings = [
  ["apple", "banana", "cherry"],
  ["banana", "kiwi", "pineapple"],
  ["cherry", "kiwi", "orange"],
];
const intersectByLength = intersectBy((x) => x.length);

console.log(intersectByLength(strings));
// Output: ['banana', 'kiwi']

In the example above, we have two arrays numbers and strings. The intersectByPrimitive function is created by passing a function that maps numbers to their remainder when divided by 10. The resulting function is then used to intersect the arrays in numbers, resulting in an array [2, 4, 6], which are the elements common to all arrays in numbers.

Similarly, the intersectByLength function is created by passing a function that maps strings to their lengths. The resulting function is then used to intersect the arrays in strings, resulting in an array ['banana', 'kiwi'], which are the strings common to all arrays in strings based on their lengths.

batch

batch(
  keyFn: (_: TaskInput) => TaskKey,
  maxWaitMilliseconds: number,
  execute: Executor<TaskInput, Output>,
  condition: (_: TaskInput[]) => boolean,
): Pipeline<[(x: TaskInput) => JuxtOutput<[(x: TaskInput) => TaskInput, (_: TaskInput) => TaskKey]>, ([input, key]: [TaskInput, TaskKey]) => Promise<ElementOf<Output>>]>

The batch function takes in four parameters: keyFn, maxWaitMilliseconds, execute, and condition. It returns a pipeline that consists of two steps.

• keyFn is a function used to determine the key for each task. It takes in a TaskInput and returns a TaskKey.
• maxWaitMilliseconds is the maximum time to wait before executing the batched tasks.
• execute is the function responsible for executing the tasks. It takes in a TaskInput and returns an Output.
• condition is a function that determines whether the batched tasks should be executed or not. It takes in an array of TaskInput and returns a boolean.

The first step of the pipeline is a juxt, which combines two functions:

• The first function in the juxt is (x: TaskInput) => TaskInput, which simply returns the TaskInput.
• The second function in the juxt is (_: TaskInput) => TaskKey, which uses the keyFn to determine the key for the task.

The second step of the pipeline is a function that takes in [input, key], which is the output of the previous step. It returns a promise that resolves to the ElementOf<Output>.

Example

const keyFn = (input: string) => input.charAt(0);
const maxWaitMilliseconds = 1000;
const execute = (input: string) => input.toUpperCase();
const condition = (inputs: string[]) => inputs.length >= 3;

const batchedTask = batch(keyFn, maxWaitMilliseconds, execute, condition);
const promise = batchedTask("apple");

promise.then((result) => {
  console.log(result); // Output: "APPLE"
});

In this example, the batchedTask function is created with the provided keyFn, maxWaitMilliseconds, execute, and condition. When the batchedTask is called with the input "apple", it will wait for more tasks with the same key (in this case, the first character of the input) to be batched or wait for the maximum wait time before executing the batched tasks. Once executed, the promise will resolve with the output of the execute function, which in this case is "APPLE".

timeout

timeout is a function that takes in a timeout duration in milliseconds, a fallback function, and an asynchronous function. It returns a new function that incorporates the timeout functionality.

Signature

timeout<Args extends unknown[], Output>(
  ms: number,
  fallback: (..._: Args) => Output | Promise<Output>,
  f: (..._: Args) => Promise<Output>,
): (...args: Args) => Promise<Output>

Parameters

• ms: number: The duration for the timeout in milliseconds.
• fallback: (..._: Args) => Output | Promise<Output>: The fallback function to be called if the async function does not resolve within the timeout duration.
• f: (..._: Args) => Promise<Output>: The asynchronous function to be executed.

Return Type

(...args: Args) => Promise<Output>: The returned function takes the same arguments as the original asynchronous function and returns a promise that resolves to the output of the original function or the fallback function.

Example

const doSomethingAsync = async (arg: string) => {
  // ... some time-consuming asynchronous operation
  return arg.toUpperCase();
};

const timeoutDoSomething = timeout(2000, () => "Timeout", doSomethingAsync);

timeoutDoSomething("hello")
  .then(console.log)
  .catch(console.error);

In this example, the timeoutDoSomething function will execute the doSomethingAsync function. If doSomethingAsync takes longer than 2000 milliseconds to resolve, the fallback function () => "Timeout" will be called instead and its result will be returned.

juxt(...fs: Functions)

This function takes in an array of functions fs and returns a new function. The returned function takes the same parameters as the first function in fs and applies each function in fs to those parameters. The result is an array of the return values from each function in fs.

Example

const add = (a: number, b: number) => a + b;
const subtract = (a: number, b: number) => a - b;
const multiply = (a: number, b: number) => a * b;

const juxtFunc = juxt(add, subtract, multiply);

console.log(juxtFunc(5, 3)); // [8, 2, 15]

In this example, juxtFunc is a function that takes two parameters 5 and 3, and applies each of the three functions add, subtract, and multiply to those parameters. The result is an array [8, 2, 15].

pairRight

(pairRight: Function) => (x: Parameters<Function>[0]) => AwaitedResults<[<Parameters<Function>[0]>(x: Parameters<Function>[0]) => Parameters<Function>[0], Function]>

This function takes a Function as its parameter and returns a new function that takes an argument x of the same type as the parameter of the original function and returns a Promise that resolves to an array containing two functions.

The first function in the array takes the same argument x and returns x. The second function in the array takes the same argument x and applies it to the original function f, returning the result.

Example

const increment = (num: number) => num + 1;

const pair = pairRight(increment);

const result = pair(5);

console.log(result);
// Output: [5, 6]

In the above example, the pairRight function is used to create a new function pair by passing in the increment function. When pair is called with an argument of 5, it returns an array [5, 6] where 5 is the original argument and 6 is the result of applying increment to 5.

stack

/**
 * stack - Compose multiple functions together, passing the output of one function as the input to the next function.
 *
 * @param {...functions} - The functions to be composed.
 * @returns {(_: { [i in keyof Functions]: Parameters<Functions[i]>[0]; }) => JuxtOutput<Functions>} - A function that takes an object where each key corresponds to the input parameter of each function, and returns the output of the final composed function.
 */
stack<Functions extends Func[]>(
  ...functions: Functions
): (
  _: { [i in keyof Functions]: Parameters<Functions[i]>[0] },
) => JuxtOutput<Functions>

Example

const add = (a: number) => (b: number) => a + b;
const multiply = (a: number) => (b: number) => a * b;

const stackFunctions = stack(add(2), multiply(3));

const result = stackFunctions({ _: 4 });
console.log(result); // { _: 4, plus: 6, times: 12 }

In the example above, the stack function is used to compose two functions - add and multiply. The resulting composed function takes an object as input, where the key _ corresponds to the input for the first function (add in this case). The composed function returns an object with the same input key (_) and additional keys plus and times, representing the output of each function in the composition. The example demonstrates calling the composed function with an input of { _: 4 } and logging the output { _: 4, plus: 6, times: 12 }.

juxtCat

Signature

<Functions extends Func[]>(...fs: Functions): (..._: Parameters<Functions[0]>) => ReturnType<Functions[0]>

Description

juxtCat is a utility function that takes in multiple functions as arguments and returns a new function. This new function applies the arguments to each of the input functions and then concatenates the results together.

Parameters

• ...fs: Functions : A rest parameter that accepts an array of functions (Functions) as input.

Return Value

The return value of juxtCat is a new function that takes in the same arguments as the first function in the input Functions array, and returns the result type of the first function.

Example

const add = (a: number, b: number) => a + b;
const multiply = (a: number, b: number) => a * b;

const juxtMultipliedTotal = juxtCat(add, multiply);

console.log(juxtMultipliedTotal(2, 3)); // Output: [5, 6]

In the example above, juxtMultipliedTotal is a new function that takes two arguments (2 and 3) and applies them to both the add and multiply functions. The result is an array [5, 6], which is the concatenation of the results of the two functions.

alljuxt

Signature:

<Functions extends Func[]>(...fs: Functions): 
  (..._: Parameters<Functions[0]>) => 
    Functions extends AnyAsync<Functions> ? Promise<boolean> : boolean

The alljuxt function takes in an arbitrary number of functions as arguments (...fs: Functions) and returns a new function that accepts the same arguments as the first function (..._: Parameters<Functions[0]>). This new function then applies each of the input functions to the arguments and returns a boolean value indicating if all the functions returned true.

If the input functions contain at least one asynchronous function (Functions extends AnyAsync<Functions>), the returned function will be asynchronous and return a Promise<boolean>. Otherwise, it will be synchronous and return a boolean.

Example

const isEven = (n: number) => n % 2 === 0;
const greaterThanThree = (n: number) => n > 3;

const checkNumber = alljuxt(isEven, greaterThanThree);

console.log(checkNumber(6)); // Output: true
console.log(checkNumber(2)); // Output: false
console.log(checkNumber(5)); // Output: false

In the example above, the alljuxt function is used to create a new function checkNumber. checkNumber accepts a number as an argument and applies the isEven and greaterThanThree functions to the argument. It returns true if both functions return true, otherwise it returns false.

anyjuxt

anyjuxt<Functions extends Func[]>(...fs: Functions): (..._: Parameters<Functions[0]>) => Functions extends AnyAsync<Functions> ? Promise<boolean> : boolean

The anyjuxt function takes multiple functions as arguments and returns a new function. This new function takes the same arguments as the first function in the fs array.

If any of the functions in the fs array returns true when called with the provided arguments, then the anyjuxt function returns true. Otherwise, it returns false.

If any of the functions in the fs array is an asynchronous function, the anyjuxt function returns a promise that resolves to either true or false depending on the results of the asynchronous functions.

Example

const isEven = (n: number) => n % 2 === 0;
const isPositive = (n: number) => n > 0;

const hasEvenOrPositive = anyjuxt(isEven, isPositive);

console.log(hasEvenOrPositive(4)); // true
console.log(hasEvenOrPositive(-3)); // true
console.log(hasEvenOrPositive(7)); // false

In this example, the hasEvenOrPositive function checks if a number is even or positive. It uses the anyjuxt function to combine the isEven and isPositive functions. When called with 4, which is even, the anyjuxt function returns true. When called with -3, which is positive, the anyjuxt function also returns true. When called with 7, which is neither even nor positive, the anyjuxt function returns false.

withLock

withLock(
  lock: () => void | Promise<void>,
  unlock: () => void | Promise<void>,
  f: Function,
): (...args: Parameters<Function>) => Promise<Awaited<ReturnType<Function>>>

The withLock function takes in three parameters: lock, unlock, and f. It returns a new function that can be invoked with arguments. This new function wraps the execution of f inside a lock.

• lock: A function that acquires a lock. It can be either synchronous or asynchronous and should return void or Promise<void>.

• unlock: A function that releases the lock. It can be either synchronous or asynchronous and should return void or Promise<void>.

• f: The function that is being locked. It can be any asynchronous or synchronous function.

The returned function can be called with any number of arguments that f expects. The wrapped execution of f is guarded by the acquired lock. If an exception is thrown within f, the lock is still released before re-throwing the exception.

Example

const lock = () =>
  new Promise<void>((resolve) => {
    console.log("Acquiring lock...");
    setTimeout(resolve, 1000);
  });

const unlock = () => {
  console.log("Releasing lock...");
};

const processResource = async (resource: string) => {
  console.log(`Processing resource: ${resource}`);
  // Simulate some work being done
  await new Promise((resolve) => setTimeout(resolve, 2000));
  console.log(`Finished processing resource: ${resource}`);
};

const lockedProcessResource = withLock(lock, unlock, processResource);
lockedProcessResource("example.com");

// Output:
// Acquiring lock...
// Processing resource: example.com
// Finished processing resource: example.com
// Releasing lock...

In the example above, the withLock function is used to create a wrapped version of the processResource function. The lock is acquired before processResource is executed and released after it completes. This ensures that only one instance of processResource can be executing at a time, preventing race conditions when accessing shared resources.

retry(f: () => boolean | Promise): Promise

This function retries executing a given function until it returns a truthy value. It waits for 50 milliseconds between each execution.

Parameters

• f: A function that returns a boolean or a Promise that resolves to a boolean. This function is executed repeatedly until it returns a truthy value.

Return Value

A Promise that resolves to void.

Example

async function testFunction() {
  let counter = 0;

  const f = () => {
    counter++;
    return counter > 3;
  };

  await retry(f);

  console.log("Success!"); // Output: Success! after 4 retries
}

testFunction();

makeLockWithId

Creates a lock function that can be used to lock resources with a given ID.

Signature

(set: (_: Key) => boolean | Promise<boolean>) => (id: Key) => Promise<void>

Parameters

• set: (_: Key) => boolean | Promise<boolean>: A function that sets the lock status for a given ID. It should return true if the lock is successfully set, false otherwise, or a Promise resolving to either of these values.

Return Type

(id: Key) => Promise<void>: A function that locks a resource with the given ID.

Example

const setLock = (id) => {
  // Perform logic to set the lock for the given ID
  // Return true if the lock is successfully set, false otherwise
};

const lockResource = makeLockWithId(setLock);

const resourceId = 'resource1';
lockResource(resourceId)
  .then(() => {
    console.log(`Resource ${resourceId} locked`);
    // Perform actions with the locked resource
  })
  .catch((error) => {
    console.error(`Failed to lock resource ${resourceId}`, error);
  });

In the above example, we have a function setLock that sets the lock status for a given ID. We then use the makeLockWithId function to create a lockResource function that can be used to lock resources by their IDs. We pass the setLock function as the argument to makeLockWithId. We can then use the lockResource function to lock a specific resource by its ID, and perform actions with the locked resource once it is successfully locked.

withLockByInput

The withLockByInput function wraps an asynchronous function f with a lock using dynamic lock ID based on input arguments.

Signature

withLockByInput<Function extends AsyncFunction>(
  argsToLockId: (..._: Parameters<Function>) => string,
  lock: (_: string) => Promise<void>,
  unlock: (_: string) => Promise<void>,
  f: Function,
): (...args: Parameters<Function>) => Promise<Awaited<ReturnType<Function>>>;

Parameters

• argsToLockId - A function that takes input arguments of f and returns a string representing the lock ID.
• lock - A function that takes a lock ID and locks it.
• unlock - A function that takes a lock ID and unlocks it.
• f - The asynchronous function to be wrapped with a lock.

Return Value

A function that takes the same input arguments as f and returns a promise that resolves to the result of f after acquiring and releasing the lock.

Example

const argsToLockId = (x: number, y: number) => `lock-${x}-${y}`;

const lock = (lockId: string) => Promise.resolve();

const unlock = (lockId: string) => Promise.resolve();

const add = async (x: number, y: number) => {
  await new Promise((resolve) => setTimeout(resolve, 1000)); // Simulating asynchronous operation
  return x + y;
};

const wrappedAdd = withLockByInput(argsToLockId, lock, unlock, add);

wrappedAdd(2, 3).then(console.log); // Output: 5 (after a 1 second delay)

In the example above, the wrappedAdd function is created using withLockByInput by providing the lock ID generator function argsToLockId, the lock function lock, the unlock function unlock, and the async function add. When wrappedAdd is called with arguments (2, 3), it acquires a lock with the lock ID lock-2-3, executes the add function, waits for it to complete, releases the lock, and returns the result 5.

sequentialized

(<Function extends AsyncFunction>(f: Function) =>
(...args: Parameters<Function>) => any);

The sequentialized function takes an asynchronous function f and returns a new function that ensures that all invocations of f are processed in a sequential order. It achieves this by creating a queue of pending invocations and processing them one by one.

Example

async function asyncFunction(num: number): Promise<number> {
  return new Promise((resolve) => {
    setTimeout(() => {
      resolve(num * 2);
    }, 1000);
  });
}

const sequentializedAsyncFunction = sequentialized(asyncFunction);

sequentializedAsyncFunction(2); // Invokes asyncFunction(2)
sequentializedAsyncFunction(4); // Waits for the previous invocation to complete before invoking asyncFunction(4)
sequentializedAsyncFunction(6); // Waits for the previous invocation to complete before invoking asyncFunction(6)

In this example, asyncFunction is an asynchronous function that takes a number and returns a promise that resolves to the double of the number after a delay of 1 second.

The sequentializedAsyncFunction is obtained by calling the sequentialized function with asyncFunction. When called multiple times, it ensures that each invocation is added to a queue and processed sequentially.

In the example, sequentializedAsyncFunction(2) is called first, and it starts processing immediately. Then sequentializedAsyncFunction(4) is called while the first invocation is still running, so it is added to the queue. Finally, sequentializedAsyncFunction(6) is called while both previous invocations are still running, so it is also added to the queue.

Once the first invocation completes, the result is resolved and the second invocation is started. Similarly, when the second invocation completes, the result is resolved and the third invocation is started. This ensures that the invocations are processed in the order they were made, even though each invocation has a delay of 1 second.

throttle

throttle is a higher-order function that limits the maximum number of parallel invocations of an asynchronous function.

Signature

throttle<Function extends AsyncFunction>(maxParallelism: number, f: Function): (...args: Parameters<Function>) => Promise<Awaited<ReturnType<Function>>>

Parameters

• maxParallelism : number - The maximum number of parallel invocations allowed.
• f : Function - The asynchronous function to be throttled.

Returns

A throttled version of the function f. The throttled function has the same signature as f, and returns a promise that resolves to the result of invoking f.

Example

const asyncFunction = async (arg: number) => {
  // Simulating an asynchronous operation
  await new Promise((resolve) => setTimeout(resolve, 1000));
  return arg * 2;
};

const throttledFunction = throt