@nlozgachev/pipelined 0.6.4

package/README.md

@@ -0,0 +1,85 @@
+# pipelined
+
+[![npm](https://img.shields.io/npm/v/@nlozgachev/pipelined?style=for-the-badge&color=000&logo=npm&label&logoColor=fff)](https://www.npmjs.com/package/@nlozgachev/pipelined)[![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/nlozgachev/pipelined/publish.yml?style=for-the-badge&color=000&logo=githubactions&label&logoColor=fff)](https://github.com/nlozgachev/pipelined/actions/workflows/publish.yml)[![Codecov](https://img.shields.io/codecov/c/github/nlozgachev/pipelined?style=for-the-badge&color=000&logo=codecov&label&logoColor=fff)](https://app.codecov.io/github/nlozgachev/pipelined)[![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)
+
+Opinionated functional abstractions for TypeScript.
+
+> **Note:** pipelined is pre-1.0. The API may change between minor versions until the 1.0 release.
+
+```sh
+npm add @nlozgachev/pipelined
+```
+
+## What is this?
+
+A toolkit for expressing uncertainty precisely. Instead of `T | null`, `try/catch`, and loading
+state flag soup, you get types that name every possible state and make invalid ones unrepresentable.
+Each type comes with a consistent set of operations — `map`, `chain`, `match`, `getOrElse` — that
+compose with `pipe` and `flow`.
+
+No FP jargon required. You won't find `Monad`, `Functor`, or `Applicative` in the API.
+
+## What's included?
+
+### pipelined/core
+
+- **`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, 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`, 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.
+
+### pipelined/types
+
+- **`Brand<K, T>`** — nominal typing at compile time, zero runtime cost.
+- **`NonEmptyList<A>`** — an array guaranteed to have at least one element.
+
+### pipelined/composition
+
+- **`pipe`**, **`flow`**, **`compose`** — function composition.
+- **`curry`** / **`uncurry`**, **`tap`**, **`memoize`**, and other function utilities.
+
+## Example
+
+```ts
+import { Option, Result } from "@nlozgachev/pipelined/core";
+import { pipe } from "@nlozgachev/pipelined/composition";
+
+// Chain nullable lookups without nested null checks
+const city = pipe(
+  getUser(userId), // User | null
+  Option.fromNullable, // Option<User>
+  Option.chain((u) => Option.fromNullable(u.address)), // Option<Address>
+  Option.chain((a) => Option.fromNullable(a.city)), // Option<string>
+  Option.map((c) => c.toUpperCase()), // Option<string>
+  Option.getOrElse("UNKNOWN"), // string
+);
+
+// Parse input and look up a record — both steps can fail
+const record = pipe(
+  parseId(rawInput), // Result<ParseError, number>
+  Result.chain((id) => db.find(id)), // Result<ParseError | NotFoundError, Record>
+  Result.map((r) => r.name), // Result<ParseError | NotFoundError, string>
+);
+```
+
+## Documentation
+
+Full guides and API reference at **[pipelined.lozgachev.dev](https://pipelined.lozgachev.dev)**.
+
+## License
+
+BSD-3-Clause

package/esm/mod.js

@@ -0,0 +1,3 @@
+export * from "./src/Composition/index.js";
+export * from "./src/Core/index.js";
+export * from "./src/Composition/index.js";

package/esm/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}

package/esm/src/Composition/compose.js

@@ -0,0 +1,3 @@
+export function compose(...fns) {
+    return (arg) => fns.reduceRight((acc, fn) => fn(acc), arg);
+}

package/esm/src/Composition/converge.js

@@ -0,0 +1,3 @@
+export function converge(f, transformers) {
+    return (a) => f(...transformers.map((t) => t(a)));
+}

package/esm/src/Composition/curry.js

@@ -0,0 +1,42 @@
+/**
+ * Converts a multi-argument function into a curried function.
+ * The inverse of `uncurry`.
+ *
+ * @example
+ * ```ts
+ * const add = (a: number, b: number) => a + b;
+ * const curriedAdd = curry(add);
+ * curriedAdd(1)(2); // 3
+ *
+ * // Partial application
+ * const addTen = curriedAdd(10);
+ * addTen(5); // 15
+ * ```
+ *
+ * @see {@link uncurry} for the inverse operation
+ * @see {@link curry3} for 3-argument functions
+ * @see {@link curry4} for 4-argument functions
+ */
+export const curry = (f) => (a) => (b) => f(a, b);
+/**
+ * Converts a 3-argument function into a curried function.
+ *
+ * @example
+ * ```ts
+ * const add3 = (a: number, b: number, c: number) => a + b + c;
+ * const curriedAdd3 = curry3(add3);
+ * curriedAdd3(1)(2)(3); // 6
+ * ```
+ */
+export const curry3 = (f) => (a) => (b) => (c) => f(a, b, c);
+/**
+ * Converts a 4-argument function into a curried function.
+ *
+ * @example
+ * ```ts
+ * const add4 = (a: number, b: number, c: number, d: number) => a + b + c + d;
+ * const curriedAdd4 = curry4(add4);
+ * curriedAdd4(1)(2)(3)(4); // 10
+ * ```
+ */
+export const curry4 = (f) => (a) => (b) => (c) => (d) => f(a, b, c, d);

package/esm/src/Composition/flip.js

@@ -0,0 +1,20 @@
+/**
+ * Flips the order of arguments for a curried binary function.
+ * Converts a data-last function to data-first.
+ *
+ * @example
+ * ```ts
+ * // Original data-last (for pipe)
+ * pipe(
+ *   Option.some(5),
+ *   Option.map(n => n * 2)
+ * ); // Some(10)
+ *
+ * // Flipped to data-first
+ * const mapFirst = flip(Option.map);
+ * mapFirst(Option.some(5))(n => n * 2); // Some(10)
+ * ```
+ *
+ * @see {@link uncurry} for converting curried functions to multi-argument functions
+ */
+export const flip = (f) => (b) => (a) => f(a)(b);

package/esm/src/Composition/flow.js

@@ -0,0 +1,8 @@
+export function flow(...fns) {
+    return (...args) => {
+        if (fns.length === 0)
+            return args[0];
+        const [first, ...rest] = fns;
+        return rest.reduce((acc, fn) => fn(acc), first(...args));
+    };
+}

package/esm/src/Composition/fn.js

@@ -0,0 +1,85 @@
+/**
+ * Returns the value unchanged. The identity function.
+ *
+ * @example
+ * ```ts
+ * identity(42); // 42
+ * pipe(Option.some(5), Option.fold(() => 0, identity)); // 5
+ * ```
+ */
+export const identity = (a) => a;
+/**
+ * Creates a function that always returns the given value, ignoring its argument.
+ *
+ * @example
+ * ```ts
+ * const always42 = constant(42);
+ * always42(); // 42
+ * [1, 2, 3].map(constant("x")); // ["x", "x", "x"]
+ * ```
+ */
+export const constant = (a) => () => a;
+/** Always returns `true`. */
+export const constTrue = () => true;
+/** Always returns `false`. */
+export const constFalse = () => false;
+/** Always returns `null`. */
+export const constNull = () => null;
+/** Always returns `undefined`. */
+export const constUndefined = () => undefined;
+/** Always returns `void`. */
+export const constVoid = () => { };
+/**
+ * Combines two predicates with logical AND.
+ *
+ * @example
+ * ```ts
+ * const isPositive = (n: number) => n > 0;
+ * const isEven = (n: number) => n % 2 === 0;
+ * const isPositiveEven = and(isPositive, isEven);
+ *
+ * isPositiveEven(4); // true
+ * isPositiveEven(-2); // false
+ * isPositiveEven(3); // false
+ * ```
+ */
+export const and = (p1, p2) => (...args) => p1(...args) && p2(...args);
+/**
+ * Combines two predicates with logical OR.
+ *
+ * @example
+ * ```ts
+ * const isNegative = (n: number) => n < 0;
+ * const isZero = (n: number) => n === 0;
+ * const isNonPositive = or(isNegative, isZero);
+ *
+ * isNonPositive(-1); // true
+ * isNonPositive(0); // true
+ * isNonPositive(1); // false
+ * ```
+ */
+export const or = (p1, p2) => (...args) => p1(...args) || p2(...args);
+/**
+ * Creates a function that executes at most once.
+ * Subsequent calls return the cached result from the first execution.
+ *
+ * @example
+ * ```ts
+ * let count = 0;
+ * const initOnce = once(() => { count++; return "initialized"; });
+ *
+ * initOnce(); // "initialized", count === 1
+ * initOnce(); // "initialized", count === 1 (not called again)
+ * ```
+ */
+export const once = (f) => {
+    let called = false;
+    let result;
+    return () => {
+        if (!called) {
+            result = f();
+            called = true;
+        }
+        return result;
+    };
+};

package/esm/src/Composition/index.js

@@ -0,0 +1,13 @@
+export * from "./compose.js";
+export * from "./converge.js";
+export * from "./curry.js";
+export * from "./flip.js";
+export * from "./fn.js";
+export * from "./flow.js";
+export * from "./juxt.js";
+export * from "./memoize.js";
+export * from "./not.js";
+export * from "./on.js";
+export * from "./pipe.js";
+export * from "./tap.js";
+export * from "./uncurry.js";

package/esm/src/Composition/juxt.js

@@ -0,0 +1,3 @@
+export function juxt(fns) {
+    return (a) => fns.map((f) => f(a));
+}

package/esm/src/Composition/memoize.js

@@ -0,0 +1,66 @@
+/**
+ * Creates a memoized version of a function that caches results.
+ * Subsequent calls with the same argument return the cached result.
+ *
+ * By default, uses the argument directly as the cache key.
+ * For complex arguments, provide a custom `keyFn` to generate cache keys.
+ *
+ * @example
+ * ```ts
+ * // Basic usage
+ * const expensive = memoize((n: number) => {
+ *   console.log("Computing...");
+ *   return n * 2;
+ * });
+ *
+ * expensive(5); // logs "Computing...", returns 10
+ * expensive(5); // returns 10 (cached, no log)
+ * expensive(3); // logs "Computing...", returns 6
+ *
+ * // With custom key function for objects
+ * const fetchUser = memoize(
+ *   (opts: { id: string }) => fetch(`/users/${opts.id}`),
+ *   opts => opts.id
+ * );
+ * ```
+ */
+export const memoize = (f, keyFn = (a) => a) => {
+    const cache = new Map();
+    return (a) => {
+        const key = keyFn(a);
+        if (cache.has(key)) {
+            return cache.get(key);
+        }
+        const result = f(a);
+        cache.set(key, result);
+        return result;
+    };
+};
+/**
+ * Creates a memoized version of a function using WeakMap.
+ * Only works with object arguments, but allows garbage collection
+ * of cached values when keys are no longer referenced.
+ *
+ * @example
+ * ```ts
+ * const processUser = memoizeWeak((user: User) => {
+ *   return expensiveOperation(user);
+ * });
+ *
+ * const user = { id: 1, name: "Alice" };
+ * processUser(user); // computed
+ * processUser(user); // cached
+ * // When `user` is garbage collected, cached result is too
+ * ```
+ */
+export const memoizeWeak = (f) => {
+    const cache = new WeakMap();
+    return (a) => {
+        if (cache.has(a)) {
+            return cache.get(a);
+        }
+        const result = f(a);
+        cache.set(a, result);
+        return result;
+    };
+};

package/esm/src/Composition/not.js

@@ -0,0 +1,25 @@
+/**
+ * Negates a predicate function.
+ * Returns a new predicate that returns true when the original returns false, and vice versa.
+ *
+ * @example
+ * ```ts
+ * const isEven = (n: number) => n % 2 === 0;
+ * const isOdd = not(isEven);
+ *
+ * isOdd(3); // true
+ * isOdd(4); // false
+ *
+ * // With array methods
+ * const numbers = [1, 2, 3, 4, 5];
+ * numbers.filter(not(isEven)); // [1, 3, 5]
+ *
+ * // In pipelines
+ * pipe(
+ *   users,
+ *   Array.filter(not(isAdmin)),
+ *   Array.map(u => u.name)
+ * );
+ * ```
+ */
+export const not = (predicate) => (...args) => !predicate(...args);

package/esm/src/Composition/on.js

@@ -0,0 +1,12 @@
+/**
+ * Applies a projection to both arguments of a binary function before calling it.
+ * Most useful for building comparators and equality checks over projected values.
+ *
+ * @example
+ * ```ts
+ * const byLength = on((a: number, b: number) => a - b, (s: string) => s.length);
+ *
+ * ["banana", "fig", "apple"].sort(byLength); // ["fig", "apple", "banana"]
+ * ```
+ */
+export const on = (f, g) => (a, b) => f(g(a), g(b));

package/esm/src/Composition/pipe.js

@@ -0,0 +1,3 @@
+export function pipe(a, ...fns) {
+    return fns.reduce((acc, fn) => fn(acc), a);
+}

package/esm/src/Composition/tap.js

@@ -0,0 +1,33 @@
+/**
+ * Executes a side effect function and returns the original value unchanged.
+ * Useful for logging, debugging, or other side effects within a pipeline.
+ *
+ * @example
+ * ```ts
+ * // Debugging a pipeline
+ * pipe(
+ *   Option.some(5),
+ *   tap(x => console.log("Before map:", x)),
+ *   Option.map(n => n * 2),
+ *   tap(x => console.log("After map:", x)),
+ *   Option.getOrElse(0)
+ * );
+ * // logs: "Before map: { kind: 'Some', value: 5 }"
+ * // logs: "After map: { kind: 'Some', value: 10 }"
+ * // returns: 10
+ *
+ * // Collecting intermediate values
+ * const values: number[] = [];
+ * pipe(
+ *   [1, 2, 3],
+ *   arr => arr.map(n => n * 2),
+ *   tap(arr => values.push(...arr))
+ * );
+ * ```
+ *
+ * @see {@link Option.tap} for Option-specific tap that only runs on Some
+ */
+export const tap = (f) => (a) => {
+    f(a);
+    return a;
+};

package/esm/src/Composition/uncurry.js

@@ -0,0 +1,32 @@
+// deno-lint-ignore no-explicit-any
+export function uncurry(f) {
+    // f.length determines the outer arity; inner.length determines the inner arity.
+    // The typed overloads guarantee these are 0, 1, or 2 total args.
+    // deno-lint-ignore no-explicit-any
+    return (...args) => {
+        const inner = f(...args.slice(0, f.length));
+        return inner.length === 0 ? inner() : inner(...args.slice(f.length));
+    };
+}
+/**
+ * Converts a curried 3-argument function into a multi-argument function.
+ *
+ * @example
+ * ```ts
+ * const curriedAdd3 = (a: number) => (b: number) => (c: number) => a + b + c;
+ * const add3 = uncurry3(curriedAdd3);
+ * add3(1, 2, 3); // 6
+ * ```
+ */
+export const uncurry3 = (f) => (a, b, c) => f(a)(b)(c);
+/**
+ * Converts a curried 4-argument function into a multi-argument function.
+ *
+ * @example
+ * ```ts
+ * const curriedAdd4 = (a: number) => (b: number) => (c: number) => (d: number) => a + b + c + d;
+ * const add4 = uncurry4(curriedAdd4);
+ * add4(1, 2, 3, 4); // 10
+ * ```
+ */
+export const uncurry4 = (f) => (a, b, c, d) => f(a)(b)(c)(d);