@nlozgachev/pipekit 0.5.0 → 0.5.1

package/README.md

@@ -2,7 +2,7 @@
 
 [![npm](https://img.shields.io/npm/v/@nlozgachev/pipekit?style=for-the-badge&color=000&logo=npm&label&logoColor=fff)](https://www.npmjs.com/package/@nlozgachev/pipekit)[![JSR Version](https://img.shields.io/jsr/v/@nlozgachev/pipekit?style=for-the-badge&color=000&logo=jsr&label&logoColor=fff)](https://jsr.io/@nlozgachev/pipekit)[![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/nlozgachev/pipekit/publish.yml?style=for-the-badge&color=000&logo=githubactions&label&logoColor=fff)](https://github.com/nlozgachev/pipekit/actions/workflows/publish.yml)[![Codecov](https://img.shields.io/codecov/c/github/nlozgachev/pipekit?style=for-the-badge&color=000&logo=codecov&label&logoColor=fff)](https://app.codecov.io/github/nlozgachev/pipekit)[![TypeScript](https://img.shields.io/badge/-0?style=for-the-badge&color=000&logo=typescript&label&logoColor=fff)](https://www.typescriptlang.org)[![Deno](https://img.shields.io/badge/-0?style=for-the-badge&color=000&logo=Deno&label&logoColor=fff)](https://deno.com)
 
-A TypeScript toolkit for writing code that means exactly what it says.
+Opinionated functional abstractions for TypeScript.
 
 > **Note:** pipekit is pre-1.0. The API may change between minor versions until the 1.0 release.
 
@@ -27,23 +27,24 @@ No FP jargon required. You won't find `Monad`, `Functor`, or `Applicative` in th
 
 ### pipekit/Core
 
-- **`Option<A>`** — a value that might not exist. Replaces `T | null | undefined`.
-- **`Result<E, A>`** — an operation that succeeds or fails. Replaces `try/catch`.
-- **`Validation<E, A>`** — like `Result`, but accumulates all errors instead of stopping at the
+- **`Option<A>`** — a value that may not exist; propagates absence without null checks.
+- **`Result<E, A>`** — an operation that succeeds or fails with a typed error.
+- **`Validation<E, A>`** — like `Result`, but accumulates every failure instead of stopping at the
   first.
-- **`Task<A>`** — a lazy async operation that doesn't run until called.
-- **`TaskResult<E, A>`** — `Task` + `Result`. A lazy async operation that can fail.
-- **`TaskOption<A>`** — `Task` + `Option`. Replaces `Promise<T | null>`.
-- **`TaskValidation<E, A>`** — `Task` + `Validation`. For async checks that all need to run.
+- **`Task<A>`** — a lazy, infallible async operation; nothing runs until called.
+- **`TaskResult<E, A>`** — a lazy async operation that can fail with a typed error.
+- **`TaskOption<A>`** — a lazy async operation that may produce nothing.
+- **`TaskValidation<E, A>`** — a lazy async operation that accumulates validation errors.
 - **`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.
+- **`Reader<R, A>`** — a computation that depends on an environment `R`, supplied once at the
+  boundary.
+- **`Arr`** — array utilities, data-last, returning `Option` instead of `undefined`.
+- **`Rec`** — record utilities, data-last, with `Option`-returning key lookup.
 
 ### pipekit/Types
 

package/esm/src/Core/Deferred.js

@@ -1,8 +1,8 @@
 export var Deferred;
 (function (Deferred) {
     /**
-     * Wraps a `Promise` into a `Deferred`, hiding `.catch()`, `.finally()`,
-     * and chainable `.then()`.
+     * Wraps a `Promise` into a `Deferred`, structurally excluding rejection handlers,
+     * `.catch()`, `.finally()`, and chainable `.then()`.
      *
      * @example
      * ```ts
@@ -11,9 +11,7 @@ export var Deferred;
      * ```
      */
     Deferred.fromPromise = (p) => ({
-        then: (f) => {
-            p.then(f);
-        },
+        then: ((f) => p.then(f)),
     });
     /**
      * Converts a `Deferred` back into a `Promise`.

package/package.json

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

package/script/src/Core/Deferred.js

@@ -4,8 +4,8 @@ exports.Deferred = void 0;
 var Deferred;
 (function (Deferred) {
     /**
-     * Wraps a `Promise` into a `Deferred`, hiding `.catch()`, `.finally()`,
-     * and chainable `.then()`.
+     * Wraps a `Promise` into a `Deferred`, structurally excluding rejection handlers,
+     * `.catch()`, `.finally()`, and chainable `.then()`.
      *
      * @example
      * ```ts
@@ -14,9 +14,7 @@ var Deferred;
      * ```
      */
     Deferred.fromPromise = (p) => ({
-        then: (f) => {
-            p.then(f);
-        },
+        then: ((f) => p.then(f)),
     });
     /**
      * Converts a `Deferred` back into a `Promise`.

package/types/src/Core/Deferred.d.ts

@@ -1,9 +1,16 @@
+declare const _deferred: unique symbol;
 /**
- * A one-shot async value that supports `await` but nothing else.
+ * A nominally typed, one-shot async value that supports `await` but enforces infallibility.
  *
- * Unlike `Promise`, `Deferred` has no `.catch()` or `.finally()`, and its
- * `.then()` returns `void` — so it cannot be chained. This makes it the
- * natural return type for `Task`, which is guaranteed to never reject.
+ * Two design choices work together to make the guarantee structural rather than documentary:
+ *
+ * - The phantom `[_deferred]` symbol makes the type **nominal**: only values produced by
+ *   `Deferred.fromPromise` satisfy it. A plain object `{ then: ... }` does not.
+ * - The single-parameter `.then()` **excludes rejection handlers** by construction. There is
+ *   no second argument to pass, so chaining and `.catch()` are impossible.
+ *
+ * This makes `Deferred<A>` the natural return type for `Task<A>`, which is guaranteed to
+ * never reject.
  *
  * @example
  * ```ts
@@ -12,12 +19,13 @@
  * ```
  */
 export type Deferred<A> = {
+    readonly [_deferred]: A;
     readonly then: (onfulfilled: (value: A) => void) => void;
 };
 export declare namespace Deferred {
     /**
-     * Wraps a `Promise` into a `Deferred`, hiding `.catch()`, `.finally()`,
-     * and chainable `.then()`.
+     * Wraps a `Promise` into a `Deferred`, structurally excluding rejection handlers,
+     * `.catch()`, `.finally()`, and chainable `.then()`.
      *
      * @example
      * ```ts
@@ -37,4 +45,5 @@ export declare namespace Deferred {
      */
     const toPromise: <A>(d: Deferred<A>) => Promise<A>;
 }
+export {};
 //# sourceMappingURL=Deferred.d.ts.map

package/types/src/Core/Deferred.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Deferred.d.ts","sourceRoot":"","sources":["../../../src/src/Core/Deferred.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,QAAQ,CAAC,CAAC,IAAI;IACxB,QAAQ,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,KAAK,IAAI,CAAC;CAC1D,CAAC;AAEF,yBAAiB,QAAQ,CAAC;IACxB;;;;;;;;;OASG;IACI,MAAM,WAAW,GAAI,CAAC,EAAE,GAAG,OAAO,CAAC,CAAC,CAAC,KAAG,QAAQ,CAAC,CAAC,CAIvD,CAAC;IAEH;;;;;;;;OAQG;IACI,MAAM,SAAS,GAAI,CAAC,EAAE,GAAG,QAAQ,CAAC,CAAC,CAAC,KAAG,OAAO,CAAC,CAAC,CACZ,CAAC;CAC7C"}
+{"version":3,"file":"Deferred.d.ts","sourceRoot":"","sources":["../../../src/src/Core/Deferred.ts"],"names":[],"mappings":"AAAA,OAAO,CAAC,MAAM,SAAS,EAAE,OAAO,MAAM,CAAC;AAEvC;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,MAAM,QAAQ,CAAC,CAAC,IAAI;IACxB,QAAQ,CAAC,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,KAAK,IAAI,CAAC;CAC1D,CAAC;AAEF,yBAAiB,QAAQ,CAAC;IACxB;;;;;;;;;OASG;IACI,MAAM,WAAW,GAAI,CAAC,EAAE,GAAG,OAAO,CAAC,CAAC,CAAC,KAAG,QAAQ,CAAC,CAAC,CAGtC,CAAC;IAEpB;;;;;;;;OAQG;IACI,MAAM,SAAS,GAAI,CAAC,EAAE,GAAG,QAAQ,CAAC,CAAC,CAAC,KAAG,OAAO,CAAC,CAAC,CACZ,CAAC;CAC7C"}