@nlozgachev/pipekit 0.4.1 → 0.5.0

package/README.md

@@ -4,6 +4,8 @@
 
 A TypeScript toolkit for writing code that means exactly what it says.
 
+> **Note:** pipekit is pre-1.0. The API may change between minor versions until the 1.0 release.
+
 ```sh
 # npm / pnpm / yarn / bun
 npm add @nlozgachev/pipekit
@@ -36,6 +38,10 @@ No FP jargon required. You won't find `Monad`, `Functor`, or `Applicative` in th
 - **`These<E, A>`** — an inclusive OR: holds an error, a value, or both at once.
 - **`RemoteData<E, A>`** — the four states of a data fetch: `NotAsked`, `Loading`, `Failure`,
   `Success`.
+- **`Lens<S, A>`** — focus on a required field in a nested structure. Read, set, and modify
+  immutably.
+- **`Optional<S, A>`** — like `Lens`, but the target may be absent (nullable fields, array indices).
+- **`Reader<R, A>`** — a computation that depends on an environment `R`, resolved later.
 - **`Arr`** — array utilities that return `Option` instead of `undefined`.
 - **`Rec`** — record/object utilities.
 

package/esm/src/Core/Arr.js

@@ -1,5 +1,7 @@
+import { Deferred } from "./Deferred.js";
 import { Option } from "./Option.js";
 import { Result } from "./Result.js";
+import { Task } from "./Task.js";
 import { isNonEmptyList } from "../Types/NonEmptyList.js";
 /**
  * Functional array utilities that compose well with pipe.
@@ -353,7 +355,7 @@ export var Arr;
      * )(); // Promise<[2, 4, 6]>
      * ```
      */
-    Arr.traverseTask = (f) => (data) => () => Promise.all(data.map((a) => f(a)()));
+    Arr.traverseTask = (f) => (data) => Task.from(() => Promise.all(data.map((a) => Deferred.toPromise(f(a)()))));
     /**
      * Collects an array of Options into an Option of array.
      * Returns None if any element is None.

package/esm/src/Core/Deferred.js

@@ -0,0 +1,28 @@
+export var Deferred;
+(function (Deferred) {
+    /**
+     * Wraps a `Promise` into a `Deferred`, hiding `.catch()`, `.finally()`,
+     * and chainable `.then()`.
+     *
+     * @example
+     * ```ts
+     * const d = Deferred.fromPromise(Promise.resolve("hello"));
+     * const value = await d; // "hello"
+     * ```
+     */
+    Deferred.fromPromise = (p) => ({
+        then: (f) => {
+            p.then(f);
+        },
+    });
+    /**
+     * Converts a `Deferred` back into a `Promise`.
+     *
+     * @example
+     * ```ts
+     * const p = Deferred.toPromise(Deferred.fromPromise(Promise.resolve(42)));
+     * // p is Promise<42>
+     * ```
+     */
+    Deferred.toPromise = (d) => new Promise((resolve) => d.then(resolve));
+})(Deferred || (Deferred = {}));

package/esm/src/Core/Optional.js

@@ -26,9 +26,7 @@ export var Optional;
      */
     Optional.prop = () => (key) => Optional.make((s) => {
         const val = s[key];
-        return val != null
-            ? Option.some(val)
-            : Option.none();
+        return val != null ? Option.some(val) : Option.none();
     }, (a) => (s) => ({ ...s, [key]: a }));
     /**
      * Creates an Optional that focuses on an element at a given index in an array.
@@ -154,9 +152,7 @@ export var Optional;
      */
     Optional.andThenLens = (inner) => (outer) => Optional.make((s) => {
         const mid = outer.get(s);
-        return mid.kind === "None"
-            ? Option.none()
-            : Option.some(inner.get(mid.value));
+        return mid.kind === "None" ? Option.none() : Option.some(inner.get(mid.value));
     }, (b) => (s) => {
         const mid = outer.get(s);
         return mid.kind === "None" ? s : outer.set(inner.set(b)(mid.value))(s);

package/esm/src/Core/Reader.js

@@ -0,0 +1,134 @@
+export var Reader;
+(function (Reader) {
+    /**
+     * Lifts a pure value into a Reader. The environment is ignored.
+     *
+     * @example
+     * ```ts
+     * const always42: Reader<Config, number> = Reader.resolve(42);
+     * always42(anyConfig); // 42
+     * ```
+     */
+    Reader.resolve = (value) => (_env) => value;
+    /**
+     * Returns the full environment as the result.
+     * The fundamental way to access the environment in a pipeline.
+     *
+     * @example
+     * ```ts
+     * pipe(
+     *   Reader.ask<Config>(),
+     *   Reader.map(config => config.baseUrl)
+     * )(appConfig); // "https://api.example.com"
+     * ```
+     */
+    Reader.ask = () => (env) => env;
+    /**
+     * Projects a value from the environment using a selector function.
+     * Equivalent to `pipe(Reader.ask(), Reader.map(f))` but more direct.
+     *
+     * @example
+     * ```ts
+     * const getBaseUrl: Reader<Config, string> = Reader.asks(c => c.baseUrl);
+     * getBaseUrl(appConfig); // "https://api.example.com"
+     * ```
+     */
+    Reader.asks = (f) => (env) => f(env);
+    /**
+     * Transforms the value produced by a Reader.
+     *
+     * @example
+     * ```ts
+     * pipe(
+     *   Reader.asks((c: Config) => c.baseUrl),
+     *   Reader.map(url => url.toUpperCase())
+     * )(appConfig); // "HTTPS://API.EXAMPLE.COM"
+     * ```
+     */
+    Reader.map = (f) => (data) => (env) => f(data(env));
+    /**
+     * Sequences two Readers. Both see the same environment.
+     * The output of the first is passed to `f`, which returns the next Reader.
+     *
+     * @example
+     * ```ts
+     * const buildUrl = (path: string): Reader<Config, string> =>
+     *   Reader.asks(c => `${c.baseUrl}${path}`);
+     *
+     * const addAuth = (url: string): Reader<Config, string> =>
+     *   Reader.asks(c => `${url}?key=${c.apiKey}`);
+     *
+     * pipe(
+     *   buildUrl("/items"),
+     *   Reader.chain(addAuth)
+     * )(appConfig); // "https://api.example.com/items?key=secret"
+     * ```
+     */
+    Reader.chain = (f) => (data) => (env) => f(data(env))(env);
+    /**
+     * Applies a function wrapped in a Reader to a value wrapped in a Reader.
+     * Both Readers see the same environment.
+     *
+     * @example
+     * ```ts
+     * const add = (a: number) => (b: number) => a + b;
+     * pipe(
+     *   Reader.resolve<Config, typeof add>(add),
+     *   Reader.ap(Reader.asks(c => c.timeout)),
+     *   Reader.ap(Reader.resolve(5))
+     * )(appConfig);
+     * ```
+     */
+    Reader.ap = (arg) => (data) => (env) => data(env)(arg(env));
+    /**
+     * Executes a side effect on the produced value without changing the Reader.
+     * Useful for logging or debugging inside a pipeline.
+     *
+     * @example
+     * ```ts
+     * pipe(
+     *   buildUrl("/users"),
+     *   Reader.tap(url => console.log("Requesting:", url)),
+     *   Reader.chain(addAuth)
+     * )(appConfig);
+     * ```
+     */
+    Reader.tap = (f) => (data) => (env) => {
+        const a = data(env);
+        f(a);
+        return a;
+    };
+    /**
+     * Adapts a Reader to work with a different (typically wider) environment
+     * by transforming the environment before passing it to the Reader.
+     * This lets you compose Readers that expect different environments.
+     *
+     * @example
+     * ```ts
+     * type AppEnv = { db: DbPool; config: Config; logger: Logger };
+     *
+     * // buildUrl only needs Config
+     * const buildUrl: Reader<Config, string> = Reader.asks(c => c.baseUrl);
+     *
+     * // Zoom in from AppEnv to Config
+     * const buildUrlFromApp: Reader<AppEnv, string> =
+     *   pipe(buildUrl, Reader.local((env: AppEnv) => env.config));
+     *
+     * buildUrlFromApp(appEnv); // works with the full AppEnv
+     * ```
+     */
+    Reader.local = (f) => (data) => (env) => data(f(env));
+    /**
+     * Runs a Reader by supplying the environment. Use this at the edge of your
+     * program where the environment is available.
+     *
+     * @example
+     * ```ts
+     * pipe(
+     *   buildEndpoint("/users"),
+     *   Reader.run(appConfig)
+     * ); // "https://api.example.com/users?key=secret"
+     * ```
+     */
+    Reader.run = (env) => (data) => data(env);
+})(Reader || (Reader = {}));

package/esm/src/Core/Task.js

@@ -1,4 +1,9 @@
+import { Deferred } from "./Deferred.js";
 import { Result } from "./Result.js";
+// Internal helper — not exported. Runs a Task and converts the result to a Promise
+// so that combinators can use Promise chaining (.then, Promise.all, Promise.race, etc.)
+// internally without leaking that primitive through the public API.
+const toPromise = (task) => Deferred.toPromise(task());
 export var Task;
 (function (Task) {
     /**
@@ -7,20 +12,19 @@ export var Task;
      * @example
      * ```ts
      * const task = Task.resolve(42);
-     * task().then(console.log); // 42
+     * const value = await task(); // 42
      * ```
      */
-    Task.resolve = (value) => () => Promise.resolve(value);
+    Task.resolve = (value) => () => Deferred.fromPromise(Promise.resolve(value));
     /**
      * Creates a Task from a function that returns a Promise.
-     * Alias for directly creating a Task.
      *
      * @example
      * ```ts
      * const getTimestamp = Task.from(() => Promise.resolve(Date.now()));
      * ```
      */
-    Task.from = (f) => f;
+    Task.from = (f) => () => Deferred.fromPromise(f());
     /**
      * Transforms the value inside a Task.
      *
@@ -29,25 +33,26 @@ export var Task;
      * pipe(
      *   Task.resolve(5),
      *   Task.map(n => n * 2)
-     * )(); // Promise<10>
+     * )(); // Deferred<10>
      * ```
      */
-    Task.map = (f) => (data) => () => data().then(f);
+    Task.map = (f) => (data) => Task.from(() => toPromise(data).then(f));
     /**
      * Chains Task computations. Passes the resolved value of the first Task to f.
      *
      * @example
      * ```ts
-     * const readUserId: Task<string> = () => Promise.resolve(session.userId);
-     * const loadPrefs = (id: string): Task<Preferences> => () => Promise.resolve(prefsCache.get(id));
+     * const readUserId: Task<string> = Task.resolve(session.userId);
+     * const loadPrefs = (id: string): Task<Preferences> =>
+     *   Task.resolve(prefsCache.get(id));
      *
      * pipe(
      *   readUserId,
      *   Task.chain(loadPrefs)
-     * )(); // Promise<Preferences>
+     * )(); // Deferred<Preferences>
      * ```
      */
-    Task.chain = (f) => (data) => () => data().then((a) => f(a)());
+    Task.chain = (f) => (data) => Task.from(() => toPromise(data).then((a) => toPromise(f(a))));
     /**
      * Applies a function wrapped in a Task to a value wrapped in a Task.
      * Both Tasks run in parallel.
@@ -59,10 +64,13 @@ export var Task;
      *   Task.resolve(add),
      *   Task.ap(Task.resolve(5)),
      *   Task.ap(Task.resolve(3))
-     * )(); // Promise<8>
+     * )(); // Deferred<8>
      * ```
      */
-    Task.ap = (arg) => (data) => () => Promise.all([data(), arg()]).then(([f, a]) => f(a));
+    Task.ap = (arg) => (data) => Task.from(() => Promise.all([
+        toPromise(data),
+        toPromise(arg),
+    ]).then(([f, a]) => f(a)));
     /**
      * Executes a side effect on the value without changing the Task.
      * Useful for logging or debugging.
@@ -76,20 +84,20 @@ export var Task;
      * );
      * ```
      */
-    Task.tap = (f) => (data) => () => data().then((a) => {
+    Task.tap = (f) => (data) => Task.from(() => toPromise(data).then((a) => {
         f(a);
         return a;
-    });
+    }));
     /**
      * Runs multiple Tasks in parallel and collects their results.
      *
      * @example
      * ```ts
      * Task.all([loadConfig, detectLocale, loadTheme])();
-     * // Promise<[Config, string, Theme]>
+     * // Deferred<[Config, string, Theme]>
      * ```
      */
-    Task.all = (tasks) => () => Promise.all(tasks.map((t) => t()));
+    Task.all = (tasks) => Task.from(() => Promise.all(tasks.map((t) => toPromise(t))));
     /**
      * Delays the execution of a Task by the specified milliseconds.
      * Useful for debouncing or rate limiting.
@@ -102,7 +110,7 @@ export var Task;
      * )(); // Resolves after 1 second
      * ```
      */
-    Task.delay = (ms) => (data) => () => new Promise((resolve, reject) => setTimeout(() => data().then(resolve, reject), ms));
+    Task.delay = (ms) => (data) => Task.from(() => new Promise((resolve) => setTimeout(() => toPromise(data).then(resolve), ms)));
     /**
      * Runs a Task a fixed number of times sequentially, collecting all results into an array.
      * An optional delay (ms) can be inserted between runs.
@@ -115,20 +123,20 @@ export var Task;
      * )(); // Task<Reading[]> — 5 readings, one per second
      * ```
      */
-    Task.repeat = (options) => (task) => () => {
+    Task.repeat = (options) => (task) => Task.from(() => {
         const { times, delay: ms } = options;
         if (times <= 0)
             return Promise.resolve([]);
         const results = [];
         const wait = () => ms !== undefined && ms > 0 ? new Promise((r) => setTimeout(r, ms)) : Promise.resolve();
-        const run = (left) => task().then((a) => {
+        const run = (left) => toPromise(task).then((a) => {
             results.push(a);
             if (left <= 1)
                 return results;
             return wait().then(() => run(left - 1));
         });
         return run(times);
-    };
+    });
     /**
      * Runs a Task repeatedly until the result satisfies a predicate, returning that result.
      * An optional delay (ms) can be inserted between runs.
@@ -141,16 +149,16 @@ export var Task;
      * )(); // polls every 500ms until status is "ready"
      * ```
      */
-    Task.repeatUntil = (options) => (task) => () => {
+    Task.repeatUntil = (options) => (task) => Task.from(() => {
         const { when: predicate, delay: ms } = options;
         const wait = () => ms !== undefined && ms > 0 ? new Promise((r) => setTimeout(r, ms)) : Promise.resolve();
-        const run = () => task().then((a) => {
+        const run = () => toPromise(task).then((a) => {
             if (predicate(a))
                 return a;
             return wait().then(run);
         });
         return run();
-    };
+    });
     /**
      * Converts a `Task<A>` into a `Task<Result<E, A>>`, resolving to `Err` if the
      * Task does not complete within the given time.
@@ -164,10 +172,10 @@ export var Task;
      * );
      * ```
      */
-    Task.timeout = (ms, onTimeout) => (task) => () => {
+    Task.timeout = (ms, onTimeout) => (task) => Task.from(() => {
         let timerId;
         return Promise.race([
-            task().then((a) => {
+            toPromise(task).then((a) => {
                 clearTimeout(timerId);
                 return Result.ok(a);
             }),
@@ -175,5 +183,5 @@ export var Task;
                 timerId = setTimeout(() => resolve(Result.err(onTimeout())), ms);
             }),
         ]);
-    };
+    });
 })(Task || (Task = {}));

package/esm/src/Core/TaskOption.js

@@ -1,3 +1,4 @@
+import { Deferred } from "./Deferred.js";
 import { Option } from "./Option.js";
 import { Task } from "./Task.js";
 export var TaskOption;
@@ -29,9 +30,9 @@ export var TaskOption;
      * );
      * ```
      */
-    TaskOption.tryCatch = (f) => () => f()
+    TaskOption.tryCatch = (f) => Task.from(() => f()
         .then(Option.some)
-        .catch(() => Option.none());
+        .catch(() => Option.none()));
     /**
      * Transforms the value inside a TaskOption.
      */
@@ -53,7 +54,10 @@ export var TaskOption;
      * Applies a function wrapped in a TaskOption to a value wrapped in a TaskOption.
      * Both Tasks run in parallel.
      */
-    TaskOption.ap = (arg) => (data) => () => Promise.all([data(), arg()]).then(([of_, oa]) => Option.ap(oa)(of_));
+    TaskOption.ap = (arg) => (data) => Task.from(() => Promise.all([
+        Deferred.toPromise(data()),
+        Deferred.toPromise(arg()),
+    ]).then(([of_, oa]) => Option.ap(oa)(of_)));
     /**
      * Extracts a value from a TaskOption by providing handlers for both cases.
      */

package/esm/src/Core/TaskResult.js

@@ -1,3 +1,4 @@
+import { Deferred } from "./Deferred.js";
 import { Result } from "./Result.js";
 import { Task } from "./Task.js";
 export var TaskResult;
@@ -23,9 +24,9 @@ export var TaskResult;
      *   );
      * ```
      */
-    TaskResult.tryCatch = (f, onError) => () => f()
+    TaskResult.tryCatch = (f, onError) => Task.from(() => f()
         .then(Result.ok)
-        .catch((e) => Result.err(onError(e)));
+        .catch((e) => Result.err(onError(e))));
     /**
      * Transforms the success value inside a TaskResult.
      */
@@ -82,10 +83,10 @@ export var TaskResult;
      * );
      * ```
      */
-    TaskResult.retry = (options) => (data) => () => {
+    TaskResult.retry = (options) => (data) => Task.from(() => {
         const { attempts, backoff, when: shouldRetry } = options;
         const getDelay = (n) => backoff === undefined ? 0 : typeof backoff === "function" ? backoff(n) : backoff;
-        const run = (left) => data().then((result) => {
+        const run = (left) => Deferred.toPromise(data()).then((result) => {
             if (Result.isOk(result))
                 return result;
             if (left <= 1)
@@ -97,7 +98,7 @@ export var TaskResult;
             return (ms > 0 ? new Promise((r) => setTimeout(r, ms)) : Promise.resolve()).then(() => run(left - 1));
         });
         return run(attempts);
-    };
+    });
     /**
      * Fails a TaskResult with a typed error if it does not resolve within the given time.
      *
@@ -109,10 +110,10 @@ export var TaskResult;
      * );
      * ```
      */
-    TaskResult.timeout = (ms, onTimeout) => (data) => () => {
+    TaskResult.timeout = (ms, onTimeout) => (data) => Task.from(() => {
         let timerId;
         return Promise.race([
-            data().then((result) => {
+            Deferred.toPromise(data()).then((result) => {
                 clearTimeout(timerId);
                 return result;
             }),
@@ -120,5 +121,5 @@ export var TaskResult;
                 timerId = setTimeout(() => resolve(Result.err(onTimeout())), ms);
             }),
         ]);
-    };
+    });
 })(TaskResult || (TaskResult = {}));

package/esm/src/Core/TaskValidation.js

@@ -1,3 +1,4 @@
+import { Deferred } from "./Deferred.js";
 import { Task } from "./Task.js";
 import { Validation } from "./Validation.js";
 export var TaskValidation;
@@ -31,9 +32,9 @@ export var TaskValidation;
      *   );
      * ```
      */
-    TaskValidation.tryCatch = (f, onError) => () => f()
+    TaskValidation.tryCatch = (f, onError) => Task.from(() => f()
         .then((Validation.valid))
-        .catch((e) => Validation.invalid(onError(e)));
+        .catch((e) => Validation.invalid(onError(e))));
     /**
      * Transforms the success value inside a TaskValidation.
      */
@@ -61,7 +62,10 @@ export var TaskValidation;
      * )();
      * ```
      */
-    TaskValidation.ap = (arg) => (data) => () => Promise.all([data(), arg()]).then(([vf, va]) => Validation.ap(va)(vf));
+    TaskValidation.ap = (arg) => (data) => Task.from(() => Promise.all([
+        Deferred.toPromise(data()),
+        Deferred.toPromise(arg()),
+    ]).then(([vf, va]) => Validation.ap(va)(vf)));
     /**
      * Extracts a value from a TaskValidation by providing handlers for both cases.
      */

package/esm/src/Core/index.js

@@ -1,6 +1,8 @@
 export * from "./Arr.js";
+export * from "./Deferred.js";
 export * from "./Lens.js";
 export * from "./Option.js";
+export * from "./Reader.js";
 export * from "./Optional.js";
 export * from "./Rec.js";
 export * from "./RemoteData.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nlozgachev/pipekit",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "Simple functional programming toolkit for TypeScript",
   "keywords": [
     "functional",

package/script/src/Core/Arr.js

@@ -1,8 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Arr = void 0;
+const Deferred_js_1 = require("./Deferred.js");
 const Option_js_1 = require("./Option.js");
 const Result_js_1 = require("./Result.js");
+const Task_js_1 = require("./Task.js");
 const NonEmptyList_js_1 = require("../Types/NonEmptyList.js");
 /**
  * Functional array utilities that compose well with pipe.
@@ -356,7 +358,7 @@ var Arr;
      * )(); // Promise<[2, 4, 6]>
      * ```
      */
-    Arr.traverseTask = (f) => (data) => () => Promise.all(data.map((a) => f(a)()));
+    Arr.traverseTask = (f) => (data) => Task_js_1.Task.from(() => Promise.all(data.map((a) => Deferred_js_1.Deferred.toPromise(f(a)()))));
     /**
      * Collects an array of Options into an Option of array.
      * Returns None if any element is None.

package/script/src/Core/Deferred.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Deferred = void 0;
+var Deferred;
+(function (Deferred) {
+    /**
+     * Wraps a `Promise` into a `Deferred`, hiding `.catch()`, `.finally()`,
+     * and chainable `.then()`.
+     *
+     * @example
+     * ```ts
+     * const d = Deferred.fromPromise(Promise.resolve("hello"));
+     * const value = await d; // "hello"
+     * ```
+     */
+    Deferred.fromPromise = (p) => ({
+        then: (f) => {
+            p.then(f);
+        },
+    });
+    /**
+     * Converts a `Deferred` back into a `Promise`.
+     *
+     * @example
+     * ```ts
+     * const p = Deferred.toPromise(Deferred.fromPromise(Promise.resolve(42)));
+     * // p is Promise<42>
+     * ```
+     */
+    Deferred.toPromise = (d) => new Promise((resolve) => d.then(resolve));
+})(Deferred || (exports.Deferred = Deferred = {}));

package/script/src/Core/Optional.js

@@ -29,9 +29,7 @@ var Optional;
      */
     Optional.prop = () => (key) => Optional.make((s) => {
         const val = s[key];
-        return val != null
-            ? Option_js_1.Option.some(val)
-            : Option_js_1.Option.none();
+        return val != null ? Option_js_1.Option.some(val) : Option_js_1.Option.none();
     }, (a) => (s) => ({ ...s, [key]: a }));
     /**
      * Creates an Optional that focuses on an element at a given index in an array.
@@ -157,9 +155,7 @@ var Optional;
      */
     Optional.andThenLens = (inner) => (outer) => Optional.make((s) => {
         const mid = outer.get(s);
-        return mid.kind === "None"
-            ? Option_js_1.Option.none()
-            : Option_js_1.Option.some(inner.get(mid.value));
+        return mid.kind === "None" ? Option_js_1.Option.none() : Option_js_1.Option.some(inner.get(mid.value));
     }, (b) => (s) => {
         const mid = outer.get(s);
         return mid.kind === "None" ? s : outer.set(inner.set(b)(mid.value))(s);