@satoshibits/functional 1.0.3 → 1.1.2

package/dist/io.mjs

@@ -0,0 +1,389 @@
+"use strict";
+/**
+ * @module io
+ * @description IO represents a synchronous computation that may have side effects.
+ * An IO is a thunk (a function with no arguments) that performs a computation when called.
+ * This provides a way to make side effects referentially transparent by wrapping them
+ * in a function, delaying their execution until explicitly requested.
+ *
+ * ### For Dummies
+ * - An `IO<T>` is just `() => T`; you keep side effects in a box until you open it.
+ * - Build the pipeline now, run it later—great for tests and deterministic wiring.
+ * - No promises here: everything happens synchronously once you call `IO.run` or the IO itself.
+ *
+ * ### Decision Tree
+ * - Got a plain value? Wrap it with `IO.of(value)` to start a chain.
+ * - Need to transform without running? Use `IO.map(fn)(io)`.
+ * - Want the next step to also be an IO? Use `IO.chain(nextStep)(io)` (aka `flatMap`).
+ * - Collecting side-effect functions? Compose them with `IO.ap`, `IO.map`, or `IO.chain`.
+ * - Ready to execute? Either call the thunk directly or use `IO.run(io)` for clarity.
+ *
+ * @example
+ * ```typescript
+ * import { IO } from './io.mts';
+ *
+ * // basic usage
+ * const getCurrentTime: IO<number> = () => Date.now();
+ * const randomNumber: IO<number> = () => Math.random();
+ *
+ * // composing IO operations
+ * const program = IO.chain((time: number) =>
+ *   IO.map((rand: number) => `Time: ${time}, Random: ${rand}`)(
+ *     randomNumber
+ *   )
+ * )(getCurrentTime);
+ *
+ * // running IO
+ * const result = IO.run(program);
+ * ```
+ *
+ * @category Core
+ * @since 2025-09-18
+ */
+var __assign = (this && this.__assign) || function () {
+    __assign = Object.assign || function(t) {
+        for (var s, i = 1, n = arguments.length; i < n; i++) {
+            s = arguments[i];
+            for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
+                t[p] = s[p];
+        }
+        return t;
+    };
+    return __assign.apply(this, arguments);
+};
+/**
+ * IO utility functions for working with IO types.
+ * @description Provides a functional API for creating, transforming, and composing IOs.
+ * All functions are curried to support functional composition and partial application.
+ *
+ * @category Utilities
+ * @since 2025-09-18
+ */
+export var IO = {
+    /**
+     * Creates an IO that returns the given value.
+     * @description Factory function for creating IOs from values. The resulting
+     * IO will always return the provided value when run.
+     *
+     * @template A - The type of the value
+     * @param {A} value - The value to wrap in an IO
+     * @returns {IO<A>} An IO that returns the value
+     *
+     * @category Constructors
+     * @example
+     * ```typescript
+     * const io = IO.of(42);
+     * IO.run(io); // => 42
+     *
+     * // Useful for starting chains
+     * const result = IO.run(
+     *   IO.chain((n: number) => IO.of(n * 2))(
+     *     IO.of(21)
+     *   )
+     * ); // => 42
+     * ```
+     *
+     * @since 2025-09-18
+     */
+    of: function (value) {
+        return function () {
+            return value;
+        };
+    },
+    /**
+     * Transforms the value inside an IO using the given function.
+     * @description Applies a pure function to the value produced by an IO,
+     * creating a new IO with the transformed value. This is the functor
+     * map operation for IO types.
+     *
+     * @template A - The input type
+     * @template B - The output type
+     * @param {function(A): B} f - Function to transform the value
+     * @returns {function(IO<A>): IO<B>} A function that transforms IOs
+     *
+     * @category Transformations
+     * @example
+     * ```typescript
+     * const double = IO.map((n: number) => n * 2);
+     * const io = IO.of(21);
+     * const doubled = double(io);
+     * IO.run(doubled); // => 42
+     *
+     * // With side effects
+     * const random = () => Math.random();
+     * const percent = IO.map((n: number) => Math.round(n * 100))(random);
+     * IO.run(percent); // => random number 0-100
+     * ```
+     *
+     * @since 2025-09-18
+     */
+    map: function (f) {
+        return function (io) {
+            return function () {
+                return f(io());
+            };
+        };
+    },
+    /**
+     * Chains IO-returning operations.
+     * @description Sequences two IOs where the second depends on the result
+     * of the first. This is the monadic bind operation for IO types.
+     *
+     * @template A - The input type
+     * @template B - The output type
+     * @param {function(A): IO<B>} f - Function that returns a new IO
+     * @returns {function(IO<A>): IO<B>} A function that chains IOs
+     *
+     * @category Combinators
+     * @example
+     * ```typescript
+     * const readLine: IO<string> = () => prompt('Enter text:') || '';
+     * const toUpper = (s: string): IO<string> => IO.of(s.toUpperCase());
+     *
+     * const program = IO.chain(toUpper)(readLine);
+     * IO.run(program); // prompts user, returns uppercase input
+     * ```
+     *
+     * @since 2025-09-18
+     */
+    chain: function (f) {
+        return function (io) {
+            return function () {
+                return f(io())();
+            };
+        };
+    },
+    /**
+     * 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 (io) {
+            return function () {
+                return f(io())();
+            };
+        };
+    },
+    /**
+     * Applies an IO of a function to an IO of a value.
+     * @description Enables applying functions wrapped in IOs to values wrapped
+     * in IOs. This is the applicative apply operation for IO types.
+     *
+     * @template A - The input type
+     * @template B - The output type
+     * @param {IO<A>} ioValue - IO containing a value
+     * @returns {function(IO<function(A): B>): IO<B>} A function that applies IO functions
+     *
+     * @category Combinators
+     * @example
+     * ```typescript
+     * const add = (a: number) => (b: number) => a + b;
+     * const ioAdd = IO.of(add);
+     * const io5 = IO.of(5);
+     * const io3 = IO.of(3);
+     *
+     * const result = IO.run(
+     *   IO.ap(io3)(
+     *     IO.ap(io5)(
+     *       IO.map(add)(IO.of(10))
+     *     )
+     *   )
+     * ); // => 18
+     * ```
+     *
+     * @since 2025-09-18
+     */
+    ap: function (ioValue) {
+        return function (ioFn) {
+            return function () {
+                return ioFn()(ioValue());
+            };
+        };
+    },
+    /**
+     * Runs an IO to completion and returns its value.
+     * @description Executes an IO, triggering the computation and returning
+     * the result. This is where side effects actually occur.
+     *
+     * @template A - The type of the value
+     * @param {IO<A>} io - The IO to run
+     * @returns {A} The result of running the IO
+     *
+     * @category Execution
+     * @example
+     * ```typescript
+     * const io = IO.of(42);
+     * const result = IO.run(io); // => 42
+     *
+     * const sideEffect = () => {
+     *   console.log('Side effect!');
+     *   return 'done';
+     * };
+     * IO.run(sideEffect); // logs "Side effect!", returns 'done'
+     * ```
+     *
+     * @since 2025-09-18
+     */
+    run: function (io) { return io(); },
+    /**
+     * Converts an array of IOs into an IO of an array.
+     * @description Sequences multiple IOs, running them in order and collecting
+     * their results.
+     *
+     * @template A - The type of values in the IOs
+     * @param {IO<A>[]} ios - Array of IOs to sequence
+     * @returns {IO<A[]>} An IO containing an array of results
+     *
+     * @category Combinators
+     * @example
+     * ```typescript
+     * const ios = [
+     *   IO.of(1),
+     *   IO.of(2),
+     *   IO.of(3)
+     * ];
+     * const combined = IO.sequence(ios);
+     * IO.run(combined); // => [1, 2, 3]
+     * ```
+     *
+     * @since 2025-09-18
+     */
+    sequence: function (ios) {
+        return function () {
+            return ios.map(function (io) { return io(); });
+        };
+    },
+    /**
+     * Maps a function returning an IO over an array and sequences the results.
+     * @description Applies an IO-returning function to each element of an array
+     * and runs all resulting IOs in sequence.
+     *
+     * @template A - The input type
+     * @template B - The output type
+     * @param {function(A): IO<B>} f - Function that returns an IO
+     * @returns {function(A[]): IO<B[]>} A function that traverses arrays with IOs
+     *
+     * @category Combinators
+     * @example
+     * ```typescript
+     * const log = (msg: string): IO<string> => () => {
+     *   console.log(msg);
+     *   return msg;
+     * };
+     *
+     * const logAll = IO.traverse(log);
+     * const messages = IO.run(
+     *   logAll(['Hello', 'World'])
+     * ); // logs each message, returns ['Hello', 'World']
+     * ```
+     *
+     * @since 2025-09-18
+     */
+    traverse: function (f) {
+        return function (as) {
+            return IO.sequence(as.map(f));
+        };
+    },
+    /**
+     * Combines the results of a tuple of IOs into an IO of a tuple.
+     * @description Takes multiple IOs and returns an IO containing a tuple
+     * of their results.
+     *
+     * @template T - Tuple type of IOs
+     * @param {...T} ios - IOs to combine
+     * @returns {IO<{ [K in keyof T]: T[K] extends IO<infer U> ? U : never }>} IO of tuple
+     *
+     * @category Combinators
+     * @example
+     * ```typescript
+     * const io1 = IO.of(1);
+     * const io2 = IO.of('hello');
+     * const io3 = IO.of(true);
+     *
+     * const combined = IO.sequenceT(io1, io2, io3);
+     * IO.run(combined); // => [1, 'hello', true]
+     * ```
+     *
+     * @since 2025-09-18
+     */
+    sequenceT: function () {
+        var ios = [];
+        for (var _i = 0; _i < arguments.length; _i++) {
+            ios[_i] = arguments[_i];
+        }
+        return function () {
+            return ios.map(function (io) { return io(); });
+        };
+    },
+    /**
+     * Combines the results of a record of IOs into an IO of a record.
+     * @description Takes an object with IO values and returns an IO containing
+     * an object with the results.
+     *
+     * @template R - Record type with IO values
+     * @param {R} ios - Record of IOs to combine
+     * @returns {IO<{ [K in keyof R]: R[K] extends IO<infer U> ? U : never }>} IO of record
+     *
+     * @category Combinators
+     * @example
+     * ```typescript
+     * const ios = {
+     *   user: IO.of({ name: 'Alice' }),
+     *   count: IO.of(42),
+     *   enabled: IO.of(true)
+     * };
+     *
+     * const combined = IO.sequenceS(ios);
+     * IO.run(combined);
+     * // => { user: { name: 'Alice' }, count: 42, enabled: true }
+     * ```
+     *
+     * @since 2025-09-18
+     */
+    sequenceS: function (ios) {
+        return function () {
+            var entries = Object.entries(ios);
+            var result = entries.reduce(function (acc, _a) {
+                var _b;
+                var key = _a[0], io = _a[1];
+                return (__assign(__assign({}, acc), (_b = {}, _b[key] = io(), _b)));
+            }, {});
+            return result;
+        };
+    },
+    /**
+     * Executes an IO for its side effects, discarding the result.
+     * @description Runs an IO but returns the original value, useful for IOs
+     * that perform side effects where the result isn't needed.
+     *
+     * @template A - The type of the value
+     * @param {function(A): IO<unknown>} f - Function that returns an IO (result discarded)
+     * @returns {function(IO<A>): IO<A>} A function that executes side effects
+     *
+     * @category Combinators
+     * @example
+     * ```typescript
+     * const log = (msg: string): IO<void> => () => console.log(msg);
+     *
+     * const io = IO.chainFirst((n: number) => log(`Got: ${n}`))(
+     *   IO.of(42)
+     * );
+     * IO.run(io); // logs "Got: 42", returns 42
+     * ```
+     *
+     * @since 2025-09-18
+     */
+    chainFirst: function (f) {
+        return function (io) {
+            return function () {
+                var a = io();
+                f(a)();
+                return a;
+            };
+        };
+    },
+};
+//# sourceMappingURL=io.mjs.map

package/dist/io.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"io.mjs","sourceRoot":"","sources":["../src/io.mts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;;;;;;;;;;;;AA0BH;;;;;;;GAOG;AACH,MAAM,CAAC,IAAM,EAAE,GAAG;IAChB;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,EAAE,EACA,UAAK,KAAQ;QACb,OAAA;YACE,OAAA,KAAK;QAAL,CAAK;IADP,CACO;IAET;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACH,GAAG,EACD,UAAO,CAAkB;QACzB,OAAA,UAAC,EAAS;YACV,OAAA;gBACE,OAAA,CAAC,CAAC,EAAE,EAAE,CAAC;YAAP,CAAO;QADT,CACS;IAFT,CAES;IAEX;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,KAAK,EACH,UAAO,CAAsB;QAC7B,OAAA,UAAC,EAAS;YACV,OAAA;gBACE,OAAA,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE;YAAT,CAAS;QADX,CACW;IAFX,CAEW;IAEb;;;;;;OAMG;IACH,OAAO,EACL,UAAO,CAAsB;QAC7B,OAAA,UAAC,EAAS;YACV,OAAA;gBACE,OAAA,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE;YAAT,CAAS;QADX,CACW;IAFX,CAEW;IAEb;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACH,EAAE,EACA,UAAO,OAAc;QACrB,OAAA,UAAC,IAAqB;YACtB,OAAA;gBACE,OAAA,IAAI,EAAE,CAAC,OAAO,EAAE,CAAC;YAAjB,CAAiB;QADnB,CACmB;IAFnB,CAEmB;IAErB;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,GAAG,EAAE,UAAK,EAAS,IAAQ,OAAA,EAAE,EAAE,EAAJ,CAAI;IAE/B;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,QAAQ,EACN,UAAK,GAAY;QACjB,OAAA;YACE,OAAA,GAAG,CAAC,GAAG,CAAC,UAAC,EAAE,IAAK,OAAA,EAAE,EAAE,EAAJ,CAAI,CAAC;QAArB,CAAqB;IADvB,CACuB;IAEzB;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,QAAQ,EACN,UAAO,CAAkB;QACzB,OAAA,UAAC,EAAO;YACN,OAAA,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QAAtB,CAAsB;IADxB,CACwB;IAE1B;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,SAAS,EACP;QACE,aAAS;aAAT,UAAS,EAAT,qBAAS,EAAT,IAAS;YAAT,wBAAS;;QAEX,OAAA;YACE,OAAA,GAAG,CAAC,GAAG,CAAC,UAAC,EAAE,IAAK,OAAA,EAAE,EAAE,EAAJ,CAAI,CAEnB;QAFD,CAEC;IAHH,CAGG;IAEL;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,SAAS,EACP,UACE,GAAM;QAER,OAAA;YACE,IAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,GAAG,CAA4B,CAAC;YAC/D,IAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAC3B,UAAC,GAAG,EAAE,EAAS;;oBAAR,GAAG,QAAA,EAAE,EAAE,QAAA;gBAAM,OAAA,uBACf,GAAG,gBACL,GAAG,IAAG,EAAE,EAAE,OACX;YAHkB,CAGlB,EACF,EAA8D,CAC/D,CAAC;YACF,OAAO,MAAM,CAAC;QAChB,CAAC;IAVD,CAUC;IAEH;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,UAAU,EACR,UAAK,CAAwB;QAC7B,OAAA,UAAC,EAAS;YACV,OAAA;gBACE,IAAM,CAAC,GAAG,EAAE,EAAE,CAAC;gBACf,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;gBACP,OAAO,CAAC,CAAC;YACX,CAAC;QAJD,CAIC;IALD,CAKC;CACJ,CAAC"}

package/dist/io.test.d.mts

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

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

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