@nlozgachev/pipelined 0.44.0 → 0.46.0

package/README.md

@@ -20,6 +20,11 @@ runtime states into simple, transparent data structures that compose. By represe
 `Maybe`, failures as `Result`, lazy asynchronous pipelines as `Task.Result`, and repeated stateful
 interactions as `Op`, the library helps disentangle business logic from control mechanics.
 
+To support these patterns without introducing bloat, the library is designed to be lightweight,
+zero-dependency, and fully tree-shakeable. The core module (`/core`) is under 14 KB gzipped, and the
+entire toolkit is under 21 KB gzipped, making it equally suitable for client and server
+environments.
+
 ## Documentation
 
 Full guides and API reference at **[pipelined.lozgachev.dev](https://pipelined.lozgachev.dev)**.
@@ -103,7 +108,7 @@ const controller = new AbortController();
 const fetchUserWithPosts = userWithPosts("42"); // build the lazy task
 const result = await fetchUserWithPosts(controller.signal); // run it — signal controls cancellation
 
-if (Result.isOk(result)) {
+if (Result.is.ok(result)) {
   render(result.value); // { ...User, posts: Post[] }
 } else {
   showError(result.error); // ApiError — typed, not unknown
@@ -140,7 +145,7 @@ const cheapestByCategory = (items: RawItem[]) =>
     items,
     Arr.filterMap(normalise), // parse + drop unparseable prices in one pass
     Arr.sortBy((a, b) => a.price - b.price), // ascending price
-    Arr.groupBy((item) => item.category), // Record<string, NonEmptyList<Item>>
+    Arr.groupBy((item) => item.category), // Record<string, Arr.NonEmpty<Item>>
     Rec.map((group) => Arr.head(group)), // cheapest per category — Maybe<Item>
   );
 ```
@@ -342,11 +347,12 @@ Functions are composed using `pipe` and `flow`, which are enriched with high-lev
 helpers like `when`, `unless`, `either`, `safe`, and `async` to support robust, expressive
 pipelines.
 
-### Nominal branding, durations, and non-empty lists
+### Nominal branding, durations, and non-empty collections
 
-Compile-time nominal typing with zero runtime overhead is provided by `Brand`, `Duration` safely
-models and converts time durations (seconds, milliseconds, etc.), and `NonEmptyList` guarantees that
-a list is never empty, eliminating defensive array length checks.
+Compile-time nominal typing with zero runtime overhead is provided by `Brand`. `Duration` safely
+models and converts time durations (seconds, milliseconds, etc.). `Arr.NonEmpty` and `Rec.NonEmpty`
+guarantee that an array or record is never empty, eliminating defensive length/emptiness checks at
+runtime.
 
 Every utility in the library is benchmarked against its native equivalent. The data-last currying
 adds a small function call overhead, which is the expected cost of composability. For operations

package/dist/{InternalTypes-BL23H8Qr.d.mts → InternalTypes-CLE7qlOc.d.mts}

@@ -7,7 +7,7 @@ declare const _deferred: unique symbol;
  * 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.
+ *   `Deferred.from.Promise` 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.
  *
@@ -16,7 +16,7 @@ declare const _deferred: unique symbol;
  *
  * @example
  * ```ts
- * const value = await Deferred.fromPromise(Promise.resolve(42));
+ * const value = await Deferred.from.Promise(Promise.resolve(42));
  * // value === 42
  * ```
  */
@@ -25,31 +25,35 @@ type Deferred<A> = {
     readonly then: (onfulfilled: (value: A) => unknown) => void;
 };
 declare namespace Deferred {
-    /**
-     * Wraps a `Promise` or `Deferred` into a `Deferred`, structurally excluding rejection handlers,
-     * `.catch()`, `.finally()`, and chainable `.then()`.
-     *
-     * **Precondition**: `p` must never reject. If `p` rejects, the returned `Deferred` will
-     * never resolve — `await`-ing it will hang indefinitely. Use `Task.Result.tryCatch` to
-     * handle operations that may fail before converting to a `Deferred`.
-     *
-     * @example
-     * ```ts
-     * const d = Deferred.fromPromise(Promise.resolve("hello"));
-     * const value = await d; // "hello"
-     * ```
-     */
-    const fromPromise: <A>(p: Thenable<A>) => Deferred<A>;
-    /**
-     * Converts a `Deferred` back into a `Promise`.
-     *
-     * @example
-     * ```ts
-     * const p = Deferred.toPromise(Deferred.fromPromise(Promise.resolve(42)));
-     * // p is Promise<42>
-     * ```
-     */
-    const toPromise: <A>(d: Deferred<A>) => Promise<A>;
+    namespace from {
+        /**
+         * Wraps a `Promise` or `Deferred` into a `Deferred`, structurally excluding rejection handlers,
+         * `.catch()`, `.finally()`, and chainable `.then()`.
+         *
+         * **Precondition**: `p` must never reject. If `p` rejects, the returned `Deferred` will
+         * never resolve — `await`-ing it will hang indefinitely. Use `Task.Result.tryCatch` to
+         * handle operations that may fail before converting to a `Deferred`.
+         *
+         * @example
+         * ```ts
+         * const d = Deferred.from.Promise(Promise.resolve("hello"));
+         * const value = await d; // "hello"
+         * ```
+         */
+        const Promise: <A>(p: Thenable<A>) => Deferred<A>;
+    }
+    namespace to {
+        /**
+         * Converts a `Deferred` back into a `Promise`.
+         *
+         * @example
+         * ```ts
+         * const p = Deferred.to.Promise(Deferred.from.Promise(Promise.resolve(42)));
+         * // p is Promise<42>
+         * ```
+         */
+        const Promise: <A>(d: Deferred<A>) => globalThis.Promise<A>;
+    }
 }
 
 /**
@@ -114,5 +118,6 @@ type WithCooldown = {
 type WithMinInterval = {
     readonly minInterval?: Duration;
 };
+type NonEmpty<T extends string> = `NonEmpty${T}`;
 
-export { type Awaitable as A, Deferred as D, type NonEmptyArr as N, type RetryOptions as R, type Thenable as T, type WithConcurrency as W, type TimeoutOptions as a, type WithCooldown as b, type WithDuration as c, type WithError as d, type WithErrors as e, type WithFirst as f, type WithKind as g, type WithLog as h, type WithMinInterval as i, type WithN as j, type WithSecond as k, type WithSize as l, type WithTimeout as m, type WithValue as n };
+export { type Awaitable as A, Deferred as D, type NonEmpty as N, type RetryOptions as R, type Thenable as T, type WithConcurrency as W, type NonEmptyArr as a, type TimeoutOptions as b, type WithCooldown as c, type WithDuration as d, type WithError as e, type WithErrors as f, type WithFirst as g, type WithKind as h, type WithLog as i, type WithMinInterval as j, type WithN as k, type WithSecond as l, type WithSize as m, type WithTimeout as n, type WithValue as o };

package/dist/{InternalTypes-7o9-yrHq.d.ts → InternalTypes-Mssktd7z.d.ts}

@@ -7,7 +7,7 @@ declare const _deferred: unique symbol;
  * 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.
+ *   `Deferred.from.Promise` 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.
  *
@@ -16,7 +16,7 @@ declare const _deferred: unique symbol;
  *
  * @example
  * ```ts
- * const value = await Deferred.fromPromise(Promise.resolve(42));
+ * const value = await Deferred.from.Promise(Promise.resolve(42));
  * // value === 42
  * ```
  */
@@ -25,31 +25,35 @@ type Deferred<A> = {
     readonly then: (onfulfilled: (value: A) => unknown) => void;
 };
 declare namespace Deferred {
-    /**
-     * Wraps a `Promise` or `Deferred` into a `Deferred`, structurally excluding rejection handlers,
-     * `.catch()`, `.finally()`, and chainable `.then()`.
-     *
-     * **Precondition**: `p` must never reject. If `p` rejects, the returned `Deferred` will
-     * never resolve — `await`-ing it will hang indefinitely. Use `Task.Result.tryCatch` to
-     * handle operations that may fail before converting to a `Deferred`.
-     *
-     * @example
-     * ```ts
-     * const d = Deferred.fromPromise(Promise.resolve("hello"));
-     * const value = await d; // "hello"
-     * ```
-     */
-    const fromPromise: <A>(p: Thenable<A>) => Deferred<A>;
-    /**
-     * Converts a `Deferred` back into a `Promise`.
-     *
-     * @example
-     * ```ts
-     * const p = Deferred.toPromise(Deferred.fromPromise(Promise.resolve(42)));
-     * // p is Promise<42>
-     * ```
-     */
-    const toPromise: <A>(d: Deferred<A>) => Promise<A>;
+    namespace from {
+        /**
+         * Wraps a `Promise` or `Deferred` into a `Deferred`, structurally excluding rejection handlers,
+         * `.catch()`, `.finally()`, and chainable `.then()`.
+         *
+         * **Precondition**: `p` must never reject. If `p` rejects, the returned `Deferred` will
+         * never resolve — `await`-ing it will hang indefinitely. Use `Task.Result.tryCatch` to
+         * handle operations that may fail before converting to a `Deferred`.
+         *
+         * @example
+         * ```ts
+         * const d = Deferred.from.Promise(Promise.resolve("hello"));
+         * const value = await d; // "hello"
+         * ```
+         */
+        const Promise: <A>(p: Thenable<A>) => Deferred<A>;
+    }
+    namespace to {
+        /**
+         * Converts a `Deferred` back into a `Promise`.
+         *
+         * @example
+         * ```ts
+         * const p = Deferred.to.Promise(Deferred.from.Promise(Promise.resolve(42)));
+         * // p is Promise<42>
+         * ```
+         */
+        const Promise: <A>(d: Deferred<A>) => globalThis.Promise<A>;
+    }
 }
 
 /**
@@ -114,5 +118,6 @@ type WithCooldown = {
 type WithMinInterval = {
     readonly minInterval?: Duration;
 };
+type NonEmpty<T extends string> = `NonEmpty${T}`;
 
-export { type Awaitable as A, Deferred as D, type NonEmptyArr as N, type RetryOptions as R, type Thenable as T, type WithConcurrency as W, type TimeoutOptions as a, type WithCooldown as b, type WithDuration as c, type WithError as d, type WithErrors as e, type WithFirst as f, type WithKind as g, type WithLog as h, type WithMinInterval as i, type WithN as j, type WithSecond as k, type WithSize as l, type WithTimeout as m, type WithValue as n };
+export { type Awaitable as A, Deferred as D, type NonEmpty as N, type RetryOptions as R, type Thenable as T, type WithConcurrency as W, type NonEmptyArr as a, type TimeoutOptions as b, type WithCooldown as c, type WithDuration as d, type WithError as e, type WithErrors as f, type WithFirst as g, type WithKind as h, type WithLog as i, type WithMinInterval as j, type WithN as k, type WithSecond as l, type WithSize as m, type WithTimeout as n, type WithValue as o };