@nlozgachev/pipekit 0.1.6

package/README.md

@@ -0,0 +1,182 @@
+# @nlozgachev/pipekit
+
+[![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)[![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 functional programming toolkit for TypeScript that speaks your language.
+
+## What is this?
+
+A collection of types and utilities that help you write safer, composition-centric, more predictable TypeScript. If you've ever dealt with `null` checks scattered across your codebase, nested `try/catch` blocks, or `{ data: T | null; loading: boolean; error: Error | null }` — this library gives you better tools for all of that.
+
+## Do I need to know functional programming to use this?
+
+No. The library avoids FP-specific jargon wherever possible. You won't find `Monad`, `Functor`, or `Applicative` in the API. Instead, you'll work with names that describe what they do:
+
+- `Option` — a value that might not exist
+- `Result` — an operation that can succeed or fail
+- `map` — transform a value inside a container
+- `chain` — sequence operations that might fail
+- `match` — handle each case explicitly
+
+You can start using these right away and learn the underlying concepts as you go.
+
+## What's included?
+
+### pipekit/Core
+
+Each of these is both a TypeScript type and a module of functions for working with values of that type — constructors, transformations, and ways to extract a value back out.
+
+- **`Option<A>`** — a value that might not exist. Replaces `T | null | undefined`. Key operations: `fromNullable`, `map`, `chain`, `filter`, `match`, `getOrElse`, `recover`.
+- **`Result<E, A>`** — an operation that succeeds with `A` or fails with `E`. Replaces `try/catch`. Key operations: `tryCatch`, `map`, `mapError`, `chain`, `match`, `getOrElse`, `recover`.
+- **`Validation<E, A>`** — like `Result`, but accumulates **all** errors instead of stopping at the first. Built for form validation. Key operations: `combine`, `combineAll`, `ap`, `map`, `match`.
+- **`Task<A>`** — a lazy async operation that doesn't run until called. Key operations: `from`, `map`, `chain`, `all`, `delay`.
+- **`TaskResult<E, A>`** — a lazy async operation that can fail. `Task` + `Result` combined. Key operations: `tryCatch`, `map`, `mapError`, `chain`, `match`, `recover`.
+- **`RemoteData<E, A>`** — models the four states of a data fetch: `NotAsked`, `Loading`, `Failure`, `Success`. Replaces `{ data, loading, error }` flag soup. Key operations: `notAsked`, `loading`, `failure`, `success`, `map`, `match`, `toResult`.
+- **`Arr`** — array operations that return `Option` instead of throwing or returning `undefined`. Operations: `head`, `last`, `findFirst`, `findLast`, `partition`, `groupBy`, `zip`, `traverse`, and more.
+- **`Rec`** — record/object operations. Operations: `lookup`, `map`, `filter`, `pick`, `omit`, `merge`, and more.
+
+### pipekit/Types
+
+- **`NonEmptyList<A>`** — an array guaranteed to have at least one element.
+
+### pipekit/Composition
+
+- **`pipe`** — pass a value through a series of functions, left to right.
+- **`flow`** — compose functions into a reusable pipeline (like `pipe` without an initial value).
+- **`compose`** — compose functions right to left (traditional mathematical composition).
+- **`curry` / `uncurry`** — convert between multi-argument and single-argument functions.
+- **`tap`** — run a side effect (like logging) without breaking the pipeline.
+- **`memoize`** — cache function results.
+- **`identity`**, **`constant`**, **`not`**, **`and`**, **`or`**, **`once`**, **`flip`** — common function utilities.
+
+## What does "composition-centric" mean?
+
+Everything in the library is designed to work with `pipe` — a function that passes a value through a series of transformations, top to bottom. The alternative is nesting calls inside each other, which reads inside-out:
+
+```ts
+import { Option } from "@nlozgachev/pipekit/Core";
+import { pipe } from "@nlozgachev/pipekit/Composition";
+
+// Without pipe: execution order is the reverse of reading order
+const userName = Option.getOrElse(
+  Option.map(
+    Option.fromNullable(users.get("123")),
+    u => u.name
+  ),
+  "Anonymous"
+);
+
+// With pipe: reads top to bottom, matches execution order
+const userName = pipe(
+  users.get("123"),              // User | undefined
+  Option.fromNullable,           // Option<User>
+  Option.map(u => u.name),       // Option<string>
+  Option.getOrElse("Anonymous")  // string
+);
+```
+
+No method chaining, no class hierarchies. Just functions that connect together.
+
+## What does "data-last" mean and why should I care?
+
+Every operation takes the data it operates on as the **last** argument. This means you can partially apply them — get a function back without providing data yet — which makes `flow` work naturally.
+
+```ts
+import { Option } from "@nlozgachev/pipekit/Core";
+import { flow } from "@nlozgachev/pipekit/Composition";
+
+// Data-first: can't partially apply, so you're stuck writing wrapper functions
+function formatName(user: User | null): string {
+  const opt = Option.fromNullable(user);
+  const name = Option.map(opt, u => u.name);
+  return Option.getOrElse(name, "Anonymous");
+}
+
+users.map(u => formatName(u)); // needs an arrow function wrapper
+
+// Data-last: operations are curried, so flow connects them directly
+const formatName = flow(
+  Option.fromNullable<User>,
+  Option.map(u => u.name),
+  Option.getOrElse("Anonymous")
+);
+
+users.map(formatName); // no wrapper — it's already a function of User
+```
+
+## How does this help me write safer code?
+
+The core types make invalid states unrepresentable. Instead of stacking null checks and hoping you handled every branch, the shape of the code reflects the shape of the data:
+
+```ts
+// Before: null handling that doesn't scale
+function getDisplayCity(userId: string): string {
+  const user = getUser(userId);
+  if (user === null) return "UNKNOWN";
+  if (user.address === null) return "UNKNOWN";
+  if (user.address.city === null) return "UNKNOWN";
+  return user.address.city.toUpperCase();
+}
+
+// After: flat, readable, same guarantees
+function getDisplayCity(userId: string): string {
+  return 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
+  );
+}
+```
+
+The same idea applies to error handling with `Result`, form validation with `Validation`, async operations with `Task` and `TaskResult`, and loading states with `RemoteData`.
+
+
+
+## How do I install it?
+
+```sh
+# Deno
+deno add jsr:@nlozgachev/pipekit
+
+# npm / pnpm / yarn / bun
+npm add @nlozgachev/pipekit
+```
+
+## How do I get started?
+
+Start with `pipe` and `Option`. These two cover the most common pain point — dealing with values that might not exist:
+
+```ts
+import { Option } from "@nlozgachev/pipekit/Core";
+import { pipe } from "@nlozgachev/pipekit/Composition";
+
+// Read a user's preferred language from their settings, fall back to the app default
+const language = pipe(
+  userSettings.get(userId),          // UserSettings | undefined
+  Option.fromNullable,               // Option<UserSettings>
+  Option.map(s => s.language),       // Option<string>
+  Option.getOrElse(DEFAULT_LANGUAGE) // string
+);
+```
+
+Once that feels natural, reach for `Result` when operations can fail with a meaningful error — parsing, network calls, database lookups:
+
+```ts
+import { Result } from "@nlozgachev/pipekit/Core";
+
+// Parse user input and look up the 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>
+);
+```
+
+And `Validation` when you need to collect multiple errors at once, like form validation.
+
+## License
+
+MIT

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/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.of(5),
+ *   Option.map(n => n * 2)
+ * ); // Some(10)
+ *
+ * // Flipped to data-first
+ * const mapFirst = flip(Option.map);
+ * mapFirst(Option.of(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.of(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,10 @@
+export * from "./compose.js";
+export * from "./curry.js";
+export * from "./flip.js";
+export * from "./fn.js";
+export * from "./flow.js";
+export * from "./memoize.js";
+export * from "./not.js";
+export * from "./pipe.js";
+export * from "./tap.js";
+export * from "./uncurry.js";

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/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.of(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);