@satoshibits/functional 1.0.3 → 1.1.2

package/dist/reader.mjs

@@ -0,0 +1,456 @@
+"use strict";
+/**
+ * @module reader
+ * @description Reader represents a computation with access to a shared environment/context.
+ * The Reader monad provides a way to compose functions that all depend on some shared
+ * configuration or dependency injection context, without having to pass it explicitly
+ * through every function call.
+ *
+ * ### For Dummies
+ * - A Reader is just a function that expects a bag of dependencies and gives you a result.
+ * - You describe what to do with the bag now and hand the bag in later, keeping tests simple.
+ * - No async, no error handling—think "grab config once you finally call me".
+ *
+ * ### Decision Tree
+ * - Need a starting value that ignores the environment? Use `Reader.of(value)`.
+ * - Want the full environment? `Reader.ask()` gives it to you; need a slice? Use `Reader.asks(selector)`.
+ * - Transforming a computed value without changing dependencies? Use `Reader.map(fn)`.
+ * - Need the next step to access the environment again? Use `Reader.chain(nextReader)`.
+ * - Done describing the program? Call `Reader.run(env)(program)` when you finally have the dependencies.
+ *
+ * @example
+ * ```typescript
+ * import { Reader } from './reader.mts';
+ *
+ * // basic usage
+ * type Config = { apiUrl: string; timeout: number };
+ *
+ * const getApiUrl: Reader<Config, string> = config => config.apiUrl;
+ * const getTimeout: Reader<Config, number> = config => config.timeout;
+ *
+ * // composing readers
+ * const buildRequest = Reader.chain((url: string) =>
+ *   Reader.map((timeout: number) => ({ url, timeout }))(getTimeout)
+ * )(getApiUrl);
+ *
+ * // running readers
+ * const config: Config = { apiUrl: 'https://api.example.com', timeout: 5000 };
+ * const request = Reader.run(config)(buildRequest);
+ * // => { url: 'https://api.example.com', timeout: 5000 }
+ * ```
+ *
+ * @category Core
+ * @since 2025-09-18
+ */
+/**
+ * Reader utility functions for working with Reader types.
+ * @description Provides a functional API for creating, transforming, and composing Readers.
+ * All functions are curried to support functional composition and partial application.
+ *
+ * @category Utilities
+ * @since 2025-09-18
+ */
+export var Reader = {
+    /**
+     * Creates a Reader that returns the given value, ignoring the environment.
+     * @description Factory function for creating Readers from values. The resulting
+     * Reader will always return the provided value regardless of the environment.
+     *
+     * @template R - The type of the environment
+     * @template A - The type of the value
+     * @param {A} value - The value to wrap in a Reader
+     * @returns {Reader<R, A>} A Reader that returns the value
+     *
+     * @category Constructors
+     * @example
+     * ```typescript
+     * const reader = Reader.of<Config, number>(42);
+     * Reader.run(config)(reader); // => 42
+     *
+     * // Useful for starting chains
+     * const result = Reader.run(config)(
+     *   Reader.chain((n: number) => Reader.of<Config, number>(n * 2))(
+     *     Reader.of<Config, number>(21)
+     *   )
+     * ); // => 42
+     * ```
+     *
+     * @since 2025-09-18
+     */
+    of: function (value) { return function () { return value; }; },
+    /**
+     * Gets the current environment.
+     * @description Returns a Reader that provides access to the entire environment.
+     * This is the identity Reader for the environment type.
+     *
+     * @template R - The type of the environment
+     * @returns {Reader<R, R>} A Reader that returns the environment
+     *
+     * @category Environment
+     * @example
+     * ```typescript
+     * type Config = { port: number; host: string };
+     * const config: Config = { port: 3000, host: 'localhost' };
+     *
+     * const getConfig = Reader.ask<Config>();
+     * Reader.run(config)(getConfig); // => { port: 3000, host: 'localhost' }
+     * ```
+     *
+     * @since 2025-09-18
+     */
+    ask: function () { return function (deps) { return deps; }; },
+    /**
+     * Gets a value derived from the environment.
+     * @description Projects a value from the environment using a selector function.
+     * Useful for extracting specific parts of the environment.
+     *
+     * @template R - The type of the environment
+     * @template A - The type of the extracted value
+     * @param {function(R): A} f - Function to extract value from environment
+     * @returns {Reader<R, A>} A Reader that returns the extracted value
+     *
+     * @category Environment
+     * @example
+     * ```typescript
+     * type Config = { db: { host: string; port: number } };
+     *
+     * const getDbHost = Reader.asks<Config, string>(config => config.db.host);
+     * const config: Config = { db: { host: 'localhost', port: 5432 } };
+     * Reader.run(config)(getDbHost); // => 'localhost'
+     * ```
+     *
+     * @since 2025-09-18
+     */
+    asks: function (f) { return f; },
+    /**
+     * Transforms the value inside a Reader using the given function.
+     * @description Applies a pure function to the value produced by a Reader,
+     * creating a new Reader with the transformed value. This is the functor
+     * map operation for Reader types.
+     *
+     * @template R - The environment type
+     * @template A - The input type
+     * @template B - The output type
+     * @param {function(A): B} f - Function to transform the value
+     * @returns {function(Reader<R, A>): Reader<R, B>} A function that transforms Readers
+     *
+     * @category Transformations
+     * @example
+     * ```typescript
+     * type Config = { multiplier: number };
+     * const getValue: Reader<Config, number> = config => 10 * config.multiplier;
+     *
+     * const double = Reader.map((n: number) => n * 2);
+     * const doubled = double(getValue);
+     *
+     * const config: Config = { multiplier: 3 };
+     * Reader.run(config)(doubled); // => 60
+     * ```
+     *
+     * @since 2025-09-18
+     */
+    map: function (f) { return function (reader) {
+        return function (deps) { return f(reader(deps)); };
+    }; },
+    /**
+     * Chains Reader-returning operations.
+     * @description Sequences two Readers where the second depends on the result
+     * of the first. This is the monadic bind operation for Reader types.
+     *
+     * @template R - The environment type
+     * @template A - The input type
+     * @template B - The output type
+     * @param {function(A): Reader<R, B>} f - Function that returns a new Reader
+     * @returns {function(Reader<R, A>): Reader<R, B>} A function that chains Readers
+     *
+     * @category Combinators
+     * @example
+     * ```typescript
+     * type Config = { baseUrl: string; apiKey: string };
+     *
+     * const getBaseUrl: Reader<Config, string> = config => config.baseUrl;
+     * const buildEndpoint = (base: string): Reader<Config, string> =>
+     *   config => `${base}/api?key=${config.apiKey}`;
+     *
+     * const getEndpoint = Reader.chain(buildEndpoint)(getBaseUrl);
+     *
+     * const config: Config = { baseUrl: 'https://api.com', apiKey: 'secret' };
+     * Reader.run(config)(getEndpoint); // => 'https://api.com/api?key=secret'
+     * ```
+     *
+     * @since 2025-09-18
+     */
+    chain: function (f) { return function (reader) {
+        return function (deps) { return f(reader(deps))(deps); };
+    }; },
+    /**
+     * 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 (reader) {
+        return function (deps) { return f(reader(deps))(deps); };
+    }; },
+    /**
+     * Applies a Reader of a function to a Reader of a value.
+     * @description Enables applying functions wrapped in Readers to values wrapped
+     * in Readers. This is the applicative apply operation for Reader types.
+     *
+     * @template R - The environment type
+     * @template A - The input type
+     * @template B - The output type
+     * @param {Reader<R, A>} readerValue - Reader containing a value
+     * @returns {function(Reader<R, function(A): B>): Reader<R, B>} A function that applies Reader functions
+     *
+     * @category Combinators
+     * @example
+     * ```typescript
+     * type Config = { x: number; y: number };
+     *
+     * const add = (a: number) => (b: number) => a + b;
+     * const getX: Reader<Config, number> = config => config.x;
+     * const getY: Reader<Config, number> = config => config.y;
+     *
+     * const sum = Reader.ap(getY)(
+     *   Reader.map(add)(getX)
+     * );
+     *
+     * const config: Config = { x: 5, y: 3 };
+     * Reader.run(config)(sum); // => 8
+     * ```
+     *
+     * @since 2025-09-18
+     */
+    ap: function (readerValue) { return function (readerFn) {
+        return function (deps) { return readerFn(deps)(readerValue(deps)); };
+    }; },
+    /**
+     * Runs a Reader with the given environment.
+     * @description Executes a Reader by providing it with the required environment,
+     * returning the computed value.
+     *
+     * @template R - The type of the environment
+     * @template A - The type of the value
+     * @param {R} deps - The environment to provide
+     * @returns {function(Reader<R, A>): A} A function that runs Readers
+     *
+     * @category Execution
+     * @example
+     * ```typescript
+     * type Config = { name: string };
+     * const getName: Reader<Config, string> = config => config.name;
+     *
+     * const config: Config = { name: 'Alice' };
+     * const name = Reader.run(config)(getName); // => 'Alice'
+     * ```
+     *
+     * @since 2025-09-18
+     */
+    run: function (deps) { return function (reader) { return reader(deps); }; },
+    /**
+     * Modifies the environment before running a Reader.
+     * @description Transforms the environment using a function before passing it
+     * to the Reader. This is contravariant mapping on the environment.
+     *
+     * @template R - The new environment type
+     * @template S - The original environment type
+     * @param {function(R): S} f - Function to transform the environment
+     * @returns {function(Reader<S, A>): Reader<R, A>} A function that adapts Readers
+     *
+     * @category Transformations
+     * @example
+     * ```typescript
+     * type AppConfig = { db: DbConfig; api: ApiConfig };
+     * type DbConfig = { host: string; port: number };
+     *
+     * const getDbHost: Reader<DbConfig, string> = config => config.host;
+     * const getAppDbHost = Reader.local<AppConfig, DbConfig>(
+     *   app => app.db
+     * )(getDbHost);
+     *
+     * const appConfig: AppConfig = {
+     *   db: { host: 'localhost', port: 5432 },
+     *   api: { url: 'https://api.com' }
+     * };
+     * Reader.run(appConfig)(getAppDbHost); // => 'localhost'
+     * ```
+     *
+     * @since 2025-09-18
+     */
+    local: function (f) { return function (reader) {
+        return function (deps) { return reader(f(deps)); };
+    }; },
+    /**
+     * Converts an array of Readers into a Reader of an array.
+     * @description Sequences multiple Readers, collecting their results into an array.
+     *
+     * @template R - The environment type
+     * @template A - The type of values in the Readers
+     * @param {Reader<R, A>[]} readers - Array of Readers to sequence
+     * @returns {Reader<R, A[]>} A Reader containing an array of results
+     *
+     * @category Combinators
+     * @example
+     * ```typescript
+     * type Config = { x: number; y: number; z: number };
+     *
+     * const readers = [
+     *   (c: Config) => c.x,
+     *   (c: Config) => c.y,
+     *   (c: Config) => c.z
+     * ];
+     * const combined = Reader.sequence(readers);
+     *
+     * const config: Config = { x: 1, y: 2, z: 3 };
+     * Reader.run(config)(combined); // => [1, 2, 3]
+     * ```
+     *
+     * @since 2025-09-18
+     */
+    sequence: function (readers) {
+        return function (deps) { return readers.map(function (reader) { return reader(deps); }); };
+    },
+    /**
+     * Maps a function returning a Reader over an array and sequences the results.
+     * @description Applies a Reader-returning function to each element of an array
+     * and collects all results.
+     *
+     * @template R - The environment type
+     * @template A - The input type
+     * @template B - The output type
+     * @param {function(A): Reader<R, B>} f - Function that returns a Reader
+     * @returns {function(A[]): Reader<R, B[]>} A function that traverses arrays with Readers
+     *
+     * @category Combinators
+     * @example
+     * ```typescript
+     * type Config = { multiplier: number };
+     *
+     * const multiplyBy = (n: number): Reader<Config, number> =>
+     *   config => n * config.multiplier;
+     *
+     * const multiplyAll = Reader.traverse(multiplyBy);
+     * const results = multiplyAll([1, 2, 3]);
+     *
+     * const config: Config = { multiplier: 10 };
+     * Reader.run(config)(results); // => [10, 20, 30]
+     * ```
+     *
+     * @since 2025-09-18
+     */
+    traverse: function (f) { return function (as) {
+        return Reader.sequence(as.map(f));
+    }; },
+    /**
+     * Combines the results of a tuple of Readers into a Reader of a tuple.
+     * @description Takes multiple Readers and returns a Reader containing a tuple
+     * of their results.
+     *
+     * @template R - The environment type
+     * @template T - Tuple type of Readers
+     * @param {...T} readers - Readers to combine
+     * @returns {Reader<R, { [K in keyof T]: T[K] extends Reader<R, infer U> ? U : never }>} Reader of tuple
+     *
+     * @category Combinators
+     * @example
+     * ```typescript
+     * type Config = { name: string; age: number; active: boolean };
+     *
+     * const getName: Reader<Config, string> = c => c.name;
+     * const getAge: Reader<Config, number> = c => c.age;
+     * const getActive: Reader<Config, boolean> = c => c.active;
+     *
+     * const combined = Reader.sequenceT(getName, getAge, getActive);
+     *
+     * const config: Config = { name: 'Alice', age: 30, active: true };
+     * Reader.run(config)(combined); // => ['Alice', 30, true]
+     * ```
+     *
+     * @since 2025-09-18
+     */
+    sequenceT: function () {
+        var readers = [];
+        for (var _i = 0; _i < arguments.length; _i++) {
+            readers[_i] = arguments[_i];
+        }
+        return function (deps) { return readers.map(function (r) { return r(deps); }); };
+    },
+    /**
+     * Combines the results of a record of Readers into a Reader of a record.
+     * @description Takes an object with Reader values and returns a Reader containing
+     * an object with the results.
+     *
+     * @template R - The environment type
+     * @template S - Record type with Reader values
+     * @param {S} readers - Record of Readers to combine
+     * @returns {Reader<R, { [K in keyof S]: S[K] extends Reader<R, infer U> ? U : never }>} Reader of record
+     *
+     * @category Combinators
+     * @example
+     * ```typescript
+     * type Config = { user: string; host: string; port: number };
+     *
+     * const readers = {
+     *   username: (c: Config) => c.user,
+     *   server: (c: Config) => c.host,
+     *   portNumber: (c: Config) => c.port
+     * };
+     *
+     * const combined = Reader.sequenceS(readers);
+     *
+     * const config: Config = { user: 'admin', host: 'localhost', port: 3000 };
+     * Reader.run(config)(combined);
+     * // => { username: 'admin', server: 'localhost', portNumber: 3000 }
+     * ```
+     *
+     * @since 2025-09-18
+     */
+    sequenceS: function (readers) {
+        return function (deps) {
+            var result = {};
+            for (var key in readers) {
+                if (Object.prototype.hasOwnProperty.call(readers, key)) {
+                    result[key] = readers[key](deps);
+                }
+            }
+            return result;
+        };
+    },
+    /**
+     * Executes a Reader for its side effects, discarding the result.
+     * @description Runs a Reader-returning function but preserves the original value.
+     * Useful for logging or other side effects where the result isn't needed.
+     *
+     * @template R - The environment type
+     * @template A - The type of the value
+     * @param {function(A): Reader<R, any>} f - Function that returns a Reader (result discarded)
+     * @returns {function(Reader<R, A>): Reader<R, A>} A function that executes side effects
+     *
+     * @category Combinators
+     * @example
+     * ```typescript
+     * type Config = { logger: (msg: string) => void };
+     *
+     * const log = (msg: string): Reader<Config, void> =>
+     *   config => config.logger(msg);
+     *
+     * const getValue: Reader<Config, number> = () => 42;
+     * const logged = Reader.chainFirst((n: number) => log(`Got: ${n}`))(getValue);
+     *
+     * const config: Config = { logger: console.log };
+     * Reader.run(config)(logged); // logs "Got: 42", returns 42
+     * ```
+     *
+     * @since 2025-09-18
+     */
+    chainFirst: function (f) { return function (reader) {
+        return function (deps) {
+            var a = reader(deps);
+            f(a)(deps);
+            return a;
+        };
+    }; },
+};
+//# sourceMappingURL=reader.mjs.map

package/dist/reader.mjs.map

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

package/dist/reader.test.d.mts

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

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

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