@satoshibits/functional 1.0.3 → 1.1.2

package/dist/task.mjs

@@ -0,0 +1,386 @@
+"use strict";
+/**
+ * @module task
+ * @description Task represents a lazy asynchronous computation.
+ * A Task is simply a thunk that returns a Promise. This provides a lazy, composable
+ * wrapper around async operations, ensuring referential transparency and making
+ * async code more predictable and testable. Note that Tasks can reject - for
+ * explicit error handling, consider using Task<Result<T, E>> pattern.
+ *
+ * ### For Dummies
+ * - A `Task<T>` is `() => Promise<T>`—build your async pipeline today, execute tomorrow.
+ * - Nothing runs until you call `Task.run(task)` (or call the function yourself).
+ * - Great for retries, composition, and testing because you control when effects fire.
+ *
+ * ### Decision Tree
+ * - Have a value already? Start with `Task.of(value)`.
+ * - Need to wrap an async function? Use `Task.fromPromise(() => promise)`.
+ * - Transforming results? Apply `Task.map(fn)`.
+ * - Next step returns another Task? Chain with `Task.chain(nextTask)`.
+ * - Working with multiple tasks together? Use helpers like `Task.ap`, `Task.sequence`, etc., inside the module.
+ * - When it’s go time, run with `await Task.run(task)`.
+ *
+ * @example
+ * ```typescript
+ * import { Task } from './task.mts';
+ *
+ * // basic usage
+ * const readFile = (path: string): Task<string> =>
+ *   () => fs.promises.readFile(path, 'utf-8');
+ *
+ * // composing tasks
+ * const processFile = Task.chain((content: string) =>
+ *   Task.of(content.toUpperCase())
+ * )(readFile('data.txt'));
+ *
+ * // running tasks
+ * const result = await Task.run(processFile);
+ * ```
+ *
+ * @category Core
+ * @since 2025-09-18
+ */
+/**
+ * Task utility functions for working with Task types.
+ * @description Provides a functional API for creating, transforming, and composing Tasks.
+ * All functions are curried to support functional composition and partial application.
+ *
+ * @category Utilities
+ * @since 2025-09-18
+ */
+export var Task = {
+    /**
+     * Creates a Task that immediately resolves with the given value.
+     * @description Factory function for creating tasks from values. The resulting
+     * task will always succeed with the provided value.
+     *
+     * @template A - The type of the value
+     * @param {A} value - The value to wrap in a Task
+     * @returns {Task<A>} A Task that resolves to the value
+     *
+     * @category Constructors
+     * @example
+     * ```typescript
+     * const task = Task.of(42);
+     * await Task.run(task); // => 42
+     *
+     * // Useful for starting chains
+     * const result = await Task.run(
+     *   Task.chain((n: number) => Task.of(n * 2))(
+     *     Task.of(21)
+     *   )
+     * ); // => 42
+     * ```
+     *
+     * @since 2025-09-18
+     */
+    of: function (value) { return function () { return Promise.resolve(value); }; },
+    /**
+     * Creates a Task from a Promise.
+     * @description Wraps a Promise in a Task, making it lazy. The Promise
+     * won't execute until the Task is run.
+     *
+     * @template A - The type of the value the Promise resolves to
+     * @param {() => Promise<A>} f - A function that returns a Promise
+     * @returns {Task<A>} A Task wrapping the Promise
+     *
+     * @category Constructors
+     * @example
+     * ```typescript
+     * const fetchData = Task.fromPromise(() =>
+     *   fetch('/api/data').then(r => r.json())
+     * );
+     *
+     * // Promise doesn't execute until run
+     * const result = await Task.run(fetchData);
+     * ```
+     *
+     * @since 2025-09-18
+     */
+    fromPromise: function (f) { return f; },
+    /**
+     * Transforms the value inside a Task using the given function.
+     * @description Applies a pure function to the eventual value of a Task,
+     * creating a new Task with the transformed value. This is the functor
+     * map operation for Task types.
+     *
+     * @template A - The input type
+     * @template B - The output type
+     * @param {function(A): B} f - Function to transform the value
+     * @returns {function(Task<A>): Task<B>} A function that transforms Tasks
+     *
+     * @category Transformations
+     * @example
+     * ```typescript
+     * const double = Task.map((n: number) => n * 2);
+     * const task = Task.of(21);
+     * const doubled = double(task);
+     * await Task.run(doubled); // => 42
+     * ```
+     *
+     * @since 2025-09-18
+     */
+    map: function (f) { return function (task) {
+        return function () { return task().then(f); };
+    }; },
+    /**
+     * Chains Task-returning operations.
+     * @description Sequences two Tasks where the second depends on the result
+     * of the first. This is the monadic bind operation for Task types.
+     *
+     * @template A - The input type
+     * @template B - The output type
+     * @param {function(A): Task<B>} f - Function that returns a new Task
+     * @returns {function(Task<A>): Task<B>} A function that chains Tasks
+     *
+     * @category Combinators
+     * @example
+     * ```typescript
+     * const readFile = (path: string): Task<string> =>
+     *   () => fs.promises.readFile(path, 'utf-8');
+     *
+     * const parseJson = <T>(content: string): Task<T> =>
+     *   Task.of(JSON.parse(content));
+     *
+     * const loadConfig = Task.chain(parseJson<Config>)(
+     *   readFile('config.json')
+     * );
+     * ```
+     *
+     * @since 2025-09-18
+     */
+    chain: function (f) { return function (task) {
+        return function () { return task().then(function (a) { return f(a)(); }); };
+    }; },
+    /**
+     * Alias for chain to match fp-ts naming.
+     * @description See {@link chain} for details.
+     *
+     * @category Combinators
+     * @since 2025-09-18
+     */
+    flatMap: function (f) { return function (task) {
+        return function () { return task().then(function (a) { return f(a)(); }); };
+    }; },
+    /**
+     * Applies a Task of a function to a Task of a value.
+     * @description Enables applying functions wrapped in Tasks to values wrapped
+     * in Tasks. This is the applicative apply operation for Task types.
+     *
+     * @template A - The input type
+     * @template B - The output type
+     * @param {Task<A>} taskValue - Task containing a value
+     * @returns {function(Task<function(A): B>): Task<B>} A function that applies Task functions
+     *
+     * @category Combinators
+     * @example
+     * ```typescript
+     * const add = (a: number) => (b: number) => a + b;
+     * const taskAdd = Task.of(add);
+     * const task5 = Task.of(5);
+     * const task3 = Task.of(3);
+     *
+     * const result = await Task.run(
+     *   Task.ap(task3)(
+     *     Task.ap(task5)(
+     *       Task.map(add)(Task.of(10))
+     *     )
+     *   )
+     * ); // => 18
+     * ```
+     *
+     * @since 2025-09-18
+     */
+    ap: function (taskValue) { return function (taskFn) {
+        return function () { return Promise.all([taskFn(), taskValue()]).then(function (_a) {
+            var f = _a[0], a = _a[1];
+            return f(a);
+        }); };
+    }; },
+    /**
+     * Runs a Task to completion and returns its Promise.
+     * @description Executes a Task, triggering the async computation and
+     * returning the resulting Promise.
+     *
+     * @template A - The type of the value
+     * @param {Task<A>} task - The Task to run
+     * @returns {Promise<A>} The result of running the Task
+     *
+     * @category Execution
+     * @example
+     * ```typescript
+     * const task = Task.of(42);
+     * const result = await Task.run(task); // => 42
+     * ```
+     *
+     * @since 2025-09-18
+     */
+    run: function (task) { return task(); },
+    /**
+     * Converts an array of Tasks into a Task of an array.
+     * @description Runs all Tasks in parallel and collects their results.
+     * All Tasks must succeed for the resulting Task to succeed.
+     *
+     * @template A - The type of values in the Tasks
+     * @param {Task<A>[]} tasks - Array of Tasks to sequence
+     * @returns {Task<A[]>} A Task containing an array of results
+     *
+     * @category Combinators
+     * @example
+     * ```typescript
+     * const tasks = [
+     *   Task.of(1),
+     *   Task.of(2),
+     *   Task.of(3)
+     * ];
+     * const combined = Task.sequence(tasks);
+     * await Task.run(combined); // => [1, 2, 3]
+     * ```
+     *
+     * @since 2025-09-18
+     */
+    sequence: function (tasks) {
+        return function () { return Promise.all(tasks.map(function (t) { return t(); })); };
+    },
+    /**
+     * Maps a function returning a Task over an array and sequences the results.
+     * @description Applies a Task-returning function to each element of an array
+     * and runs all resulting Tasks in parallel.
+     *
+     * @template A - The input type
+     * @template B - The output type
+     * @param {function(A): Task<B>} f - Function that returns a Task
+     * @returns {function(A[]): Task<B[]>} A function that traverses arrays with Tasks
+     *
+     * @category Combinators
+     * @example
+     * ```typescript
+     * const fetchUser = (id: string): Task<User> =>
+     *   () => fetch(`/api/users/${id}`).then(r => r.json());
+     *
+     * const fetchAllUsers = Task.traverse(fetchUser);
+     * const users = await Task.run(
+     *   fetchAllUsers(['1', '2', '3'])
+     * );
+     * ```
+     *
+     * @since 2025-09-18
+     */
+    traverse: function (f) { return function (as) {
+        return Task.sequence(as.map(f));
+    }; },
+    /**
+     * Creates a Task that delays for the specified milliseconds.
+     * @description Returns a Task that waits for the given duration before
+     * resolving with void.
+     *
+     * @param {number} ms - Number of milliseconds to delay
+     * @returns {Task<void>} A Task that delays
+     *
+     * @category Utilities
+     * @example
+     * ```typescript
+     * const delayed = Task.chain(() => Task.of('done'))(
+     *   Task.delay(1000)
+     * );
+     * await Task.run(delayed); // => 'done' (after 1 second)
+     * ```
+     *
+     * @since 2025-09-18
+     */
+    delay: function (ms) {
+        return function () { return new Promise(function (resolve) { return setTimeout(resolve, ms); }); };
+    },
+    /**
+     * Combines the results of a tuple of Tasks into a Task of a tuple.
+     * @description Takes multiple Tasks and returns a Task containing a tuple
+     * of their results. All Tasks run in parallel.
+     *
+     * @template T - Tuple type of Tasks
+     * @param {...T} tasks - Tasks to combine
+     * @returns {Task<{ [K in keyof T]: T[K] extends Task<infer U> ? U : never }>} Task of tuple
+     *
+     * @category Combinators
+     * @example
+     * ```typescript
+     * const task1 = Task.of(1);
+     * const task2 = Task.of('hello');
+     * const task3 = Task.of(true);
+     *
+     * const combined = Task.sequenceT(task1, task2, task3);
+     * await Task.run(combined); // => [1, 'hello', true]
+     * ```
+     *
+     * @since 2025-09-18
+     */
+    sequenceT: function () {
+        var tasks = [];
+        for (var _i = 0; _i < arguments.length; _i++) {
+            tasks[_i] = arguments[_i];
+        }
+        return function () { return Promise.all(tasks.map(function (t) { return t(); })); };
+    },
+    /**
+     * Combines the results of a record of Tasks into a Task of a record.
+     * @description Takes an object with Task values and returns a Task containing
+     * an object with the results. All Tasks run in parallel.
+     *
+     * @template R - Record type with Task values
+     * @param {R} tasks - Record of Tasks to combine
+     * @returns {Task<{ [K in keyof R]: R[K] extends Task<infer U> ? U : never }>} Task of record
+     *
+     * @category Combinators
+     * @example
+     * ```typescript
+     * const tasks = {
+     *   user: Task.of({ name: 'Alice' }),
+     *   count: Task.of(42),
+     *   enabled: Task.of(true)
+     * };
+     *
+     * const combined = Task.sequenceS(tasks);
+     * await Task.run(combined);
+     * // => { user: { name: 'Alice' }, count: 42, enabled: true }
+     * ```
+     *
+     * @since 2025-09-18
+     */
+    sequenceS: function (tasks) {
+        return function () {
+            var keys = Object.keys(tasks);
+            return Promise.all(keys.map(function (k) { return tasks[k](); })).then(function (values) {
+                return keys.reduce(function (acc, k, i) {
+                    acc[k] = values[i];
+                    return acc;
+                }, {});
+            });
+        };
+    },
+    /**
+     * Executes a Task for its side effects, discarding the result.
+     * @description Runs a Task but returns void, useful for Tasks that
+     * perform side effects where the result isn't needed.
+     *
+     * @template A - The type of the value (discarded)
+     * @param {function(A): Task<unknown>} f - Function that returns a Task (result discarded)
+     * @returns {function(Task<A>): Task<A>} A function that executes side effects
+     *
+     * @category Combinators
+     * @example
+     * ```typescript
+     * const log = (msg: string): Task<void> =>
+     *   () => Promise.resolve(console.log(msg));
+     *
+     * const task = Task.chainFirst((n: number) => log(`Got: ${n}`))(
+     *   Task.of(42)
+     * );
+     * await Task.run(task); // logs "Got: 42", returns 42
+     * ```
+     *
+     * @since 2025-09-18
+     */
+    chainFirst: function (f) { return function (task) {
+        return function () { return task().then(function (a) { return f(a)().then(function () { return a; }); }); };
+    }; },
+};
+//# sourceMappingURL=task.mjs.map

package/dist/task.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"task.mjs","sourceRoot":"","sources":["../src/task.mts"],"names":[],"mappings":"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"}

package/dist/task.test.d.mts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=task.test.d.mts.map

package/dist/task.test.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"task.test.d.mts","sourceRoot":"","sources":["../src/task.test.mts"],"names":[],"mappings":""}