@nlozgachev/pipelined 0.6.4

package/esm/src/Core/Arr.js

@@ -0,0 +1,463 @@
+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.
+ * All functions are data-last and curried where applicable.
+ * Safe access functions return Option instead of throwing or returning undefined.
+ *
+ * @example
+ * ```ts
+ * pipe(
+ *   [1, 2, 3, 4, 5],
+ *   Arr.filter(n => n > 2),
+ *   Arr.map(n => n * 10),
+ *   Arr.head
+ * ); // Some(30)
+ * ```
+ */
+export var Arr;
+(function (Arr) {
+    // --- Safe access ---
+    /**
+     * Returns the first element of an array, or None if the array is empty.
+     *
+     * @example
+     * ```ts
+     * Arr.head([1, 2, 3]); // Some(1)
+     * Arr.head([]); // None
+     * ```
+     */
+    Arr.head = (data) => data.length > 0 ? Option.some(data[0]) : Option.none();
+    /**
+     * Returns the last element of an array, or None if the array is empty.
+     *
+     * @example
+     * ```ts
+     * Arr.last([1, 2, 3]); // Some(3)
+     * Arr.last([]); // None
+     * ```
+     */
+    Arr.last = (data) => data.length > 0 ? Option.some(data[data.length - 1]) : Option.none();
+    /**
+     * Returns all elements except the first, or None if the array is empty.
+     *
+     * @example
+     * ```ts
+     * Arr.tail([1, 2, 3]); // Some([2, 3])
+     * Arr.tail([]); // None
+     * ```
+     */
+    Arr.tail = (data) => data.length > 0 ? Option.some(data.slice(1)) : Option.none();
+    /**
+     * Returns all elements except the last, or None if the array is empty.
+     *
+     * @example
+     * ```ts
+     * Arr.init([1, 2, 3]); // Some([1, 2])
+     * Arr.init([]); // None
+     * ```
+     */
+    Arr.init = (data) => data.length > 0 ? Option.some(data.slice(0, -1)) : Option.none();
+    // --- Search ---
+    /**
+     * Returns the first element matching the predicate, or None.
+     *
+     * @example
+     * ```ts
+     * pipe([1, 2, 3, 4], Arr.findFirst(n => n > 2)); // Some(3)
+     * ```
+     */
+    Arr.findFirst = (predicate) => (data) => {
+        const idx = data.findIndex(predicate);
+        return idx >= 0 ? Option.some(data[idx]) : Option.none();
+    };
+    /**
+     * Returns the last element matching the predicate, or None.
+     *
+     * @example
+     * ```ts
+     * pipe([1, 2, 3, 4], Arr.findLast(n => n > 2)); // Some(4)
+     * ```
+     */
+    Arr.findLast = (predicate) => (data) => {
+        for (let i = data.length - 1; i >= 0; i--) {
+            if (predicate(data[i]))
+                return Option.some(data[i]);
+        }
+        return Option.none();
+    };
+    /**
+     * Returns the index of the first element matching the predicate, or None.
+     *
+     * @example
+     * ```ts
+     * pipe([1, 2, 3, 4], Arr.findIndex(n => n > 2)); // Some(2)
+     * ```
+     */
+    Arr.findIndex = (predicate) => (data) => {
+        const idx = data.findIndex(predicate);
+        return idx >= 0 ? Option.some(idx) : Option.none();
+    };
+    // --- Transform ---
+    /**
+     * Transforms each element of an array.
+     *
+     * @example
+     * ```ts
+     * pipe([1, 2, 3], Arr.map(n => n * 2)); // [2, 4, 6]
+     * ```
+     */
+    Arr.map = (f) => (data) => data.map(f);
+    /**
+     * Filters elements that satisfy the predicate.
+     *
+     * @example
+     * ```ts
+     * pipe([1, 2, 3, 4], Arr.filter(n => n % 2 === 0)); // [2, 4]
+     * ```
+     */
+    Arr.filter = (predicate) => (data) => data.filter(predicate);
+    /**
+     * Splits an array into two groups based on a predicate.
+     * First group contains elements that satisfy the predicate,
+     * second group contains the rest.
+     *
+     * @example
+     * ```ts
+     * pipe([1, 2, 3, 4], Arr.partition(n => n % 2 === 0)); // [[2, 4], [1, 3]]
+     * ```
+     */
+    Arr.partition = (predicate) => (data) => {
+        const pass = [];
+        const fail = [];
+        for (const a of data) {
+            (predicate(a) ? pass : fail).push(a);
+        }
+        return [pass, fail];
+    };
+    /**
+     * Groups elements by a key function.
+     *
+     * @example
+     * ```ts
+     * pipe(
+     *   ["apple", "avocado", "banana"],
+     *   Arr.groupBy(s => s[0])
+     * ); // { a: ["apple", "avocado"], b: ["banana"] }
+     * ```
+     */
+    Arr.groupBy = (f) => (data) => {
+        const result = {};
+        for (const a of data) {
+            const key = f(a);
+            if (!result[key])
+                result[key] = [];
+            result[key].push(a);
+        }
+        return result;
+    };
+    /**
+     * Removes duplicate elements using strict equality.
+     *
+     * @example
+     * ```ts
+     * Arr.uniq([1, 2, 2, 3, 1]); // [1, 2, 3]
+     * ```
+     */
+    Arr.uniq = (data) => [
+        ...new Set(data),
+    ];
+    /**
+     * Removes duplicate elements by comparing the result of a key function.
+     *
+     * @example
+     * ```ts
+     * pipe(
+     *   [{id: 1, name: "a"}, {id: 1, name: "b"}, {id: 2, name: "c"}],
+     *   Arr.uniqBy(x => x.id)
+     * ); // [{id: 1, name: "a"}, {id: 2, name: "c"}]
+     * ```
+     */
+    Arr.uniqBy = (f) => (data) => {
+        const seen = new Set();
+        const result = [];
+        for (const a of data) {
+            const key = f(a);
+            if (!seen.has(key)) {
+                seen.add(key);
+                result.push(a);
+            }
+        }
+        return result;
+    };
+    /**
+     * Sorts an array using a comparison function. Returns a new array.
+     *
+     * @example
+     * ```ts
+     * pipe([3, 1, 2], Arr.sortBy((a, b) => a - b)); // [1, 2, 3]
+     * ```
+     */
+    Arr.sortBy = (compare) => (data) => [...data].sort(compare);
+    // --- Combine ---
+    /**
+     * Pairs up elements from two arrays. Stops at the shorter array.
+     *
+     * @example
+     * ```ts
+     * pipe([1, 2, 3], Arr.zip(["a", "b"])); // [[1, "a"], [2, "b"]]
+     * ```
+     */
+    Arr.zip = (other) => (data) => {
+        const len = Math.min(data.length, other.length);
+        const result = [];
+        for (let i = 0; i < len; i++) {
+            result.push([data[i], other[i]]);
+        }
+        return result;
+    };
+    /**
+     * Combines elements from two arrays using a function. Stops at the shorter array.
+     *
+     * @example
+     * ```ts
+     * pipe([1, 2], Arr.zipWith((a, b) => a + b, ["a", "b"])); // ["1a", "2b"]
+     * ```
+     */
+    Arr.zipWith = (f, other) => (data) => {
+        const len = Math.min(data.length, other.length);
+        const result = [];
+        for (let i = 0; i < len; i++) {
+            result.push(f(data[i], other[i]));
+        }
+        return result;
+    };
+    /**
+     * Inserts a separator between every element.
+     *
+     * @example
+     * ```ts
+     * pipe([1, 2, 3], Arr.intersperse(0)); // [1, 0, 2, 0, 3]
+     * ```
+     */
+    Arr.intersperse = (sep) => (data) => {
+        if (data.length <= 1)
+            return data;
+        const result = [data[0]];
+        for (let i = 1; i < data.length; i++) {
+            result.push(sep, data[i]);
+        }
+        return result;
+    };
+    /**
+     * Splits an array into chunks of the given size.
+     *
+     * @example
+     * ```ts
+     * pipe([1, 2, 3, 4, 5], Arr.chunksOf(2)); // [[1, 2], [3, 4], [5]]
+     * ```
+     */
+    Arr.chunksOf = (n) => (data) => {
+        if (n <= 0)
+            return [];
+        const result = [];
+        for (let i = 0; i < data.length; i += n) {
+            result.push(data.slice(i, i + n));
+        }
+        return result;
+    };
+    /**
+     * Flattens a nested array by one level.
+     *
+     * @example
+     * ```ts
+     * Arr.flatten([[1, 2], [3], [4, 5]]); // [1, 2, 3, 4, 5]
+     * ```
+     */
+    Arr.flatten = (data) => [].concat(...data);
+    /**
+     * Maps each element to an array and flattens the result.
+     *
+     * @example
+     * ```ts
+     * pipe([1, 2, 3], Arr.flatMap(n => [n, n * 10])); // [1, 10, 2, 20, 3, 30]
+     * ```
+     */
+    Arr.flatMap = (f) => (data) => [].concat(...data.map(f));
+    /**
+     * Reduces an array from the left.
+     *
+     * @example
+     * ```ts
+     * pipe([1, 2, 3], Arr.reduce(0, (acc, n) => acc + n)); // 6
+     * ```
+     */
+    Arr.reduce = (initial, f) => (data) => data.reduce(f, initial);
+    // --- Traverse / Sequence ---
+    /**
+     * Maps each element to an Option and collects the results.
+     * Returns None if any mapping returns None.
+     *
+     * @example
+     * ```ts
+     * const parseNum = (s: string): Option<number> => {
+     *   const n = Number(s);
+     *   return isNaN(n) ? Option.none() : Option.some(n);
+     * };
+     *
+     * pipe(["1", "2", "3"], Arr.traverse(parseNum)); // Some([1, 2, 3])
+     * pipe(["1", "x", "3"], Arr.traverse(parseNum)); // None
+     * ```
+     */
+    Arr.traverse = (f) => (data) => {
+        const result = [];
+        for (const a of data) {
+            const mapped = f(a);
+            if (Option.isNone(mapped))
+                return Option.none();
+            result.push(mapped.value);
+        }
+        return Option.some(result);
+    };
+    /**
+     * Maps each element to a Result and collects the results.
+     * Returns the first Err if any mapping fails.
+     *
+     * @example
+     * ```ts
+     * pipe(
+     *   [1, 2, 3],
+     *   Arr.traverseResult(n => n > 0 ? Result.ok(n) : Result.err("negative"))
+     * ); // Ok([1, 2, 3])
+     * ```
+     */
+    Arr.traverseResult = (f) => (data) => {
+        const result = [];
+        for (const a of data) {
+            const mapped = f(a);
+            if (Result.isErr(mapped))
+                return mapped;
+            result.push(mapped.value);
+        }
+        return Result.ok(result);
+    };
+    /**
+     * Maps each element to a Task and runs all in parallel.
+     *
+     * @example
+     * ```ts
+     * pipe(
+     *   [1, 2, 3],
+     *   Arr.traverseTask(n => Task.resolve(n * 2))
+     * )(); // Promise<[2, 4, 6]>
+     * ```
+     */
+    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.
+     *
+     * @example
+     * ```ts
+     * Arr.sequence([Option.some(1), Option.some(2)]); // Some([1, 2])
+     * Arr.sequence([Option.some(1), Option.none()]); // None
+     * ```
+     */
+    Arr.sequence = (data) => Arr.traverse((a) => a)(data);
+    /**
+     * Collects an array of Results into a Result of array.
+     * Returns the first Err if any element is Err.
+     */
+    Arr.sequenceResult = (data) => Arr.traverseResult((a) => a)(data);
+    /**
+     * Collects an array of Tasks into a Task of array. Runs in parallel.
+     */
+    Arr.sequenceTask = (data) => Arr.traverseTask((a) => a)(data);
+    /**
+     * Returns true if the array is non-empty (type guard).
+     */
+    Arr.isNonEmpty = (data) => isNonEmptyList(data);
+    /**
+     * Returns the length of an array.
+     */
+    Arr.size = (data) => data.length;
+    /**
+     * Returns true if any element satisfies the predicate.
+     *
+     * @example
+     * ```ts
+     * pipe([1, 2, 3], Arr.some(n => n > 2)); // true
+     * ```
+     */
+    Arr.some = (predicate) => (data) => data.some(predicate);
+    /**
+     * Returns true if all elements satisfy the predicate.
+     *
+     * @example
+     * ```ts
+     * pipe([1, 2, 3], Arr.every(n => n > 0)); // true
+     * ```
+     */
+    Arr.every = (predicate) => (data) => data.every(predicate);
+    /**
+     * Reverses an array. Returns a new array.
+     *
+     * @example
+     * ```ts
+     * Arr.reverse([1, 2, 3]); // [3, 2, 1]
+     * ```
+     */
+    Arr.reverse = (data) => [...data].reverse();
+    /**
+     * Takes the first n elements from an array.
+     *
+     * @example
+     * ```ts
+     * pipe([1, 2, 3, 4], Arr.take(2)); // [1, 2]
+     * ```
+     */
+    Arr.take = (n) => (data) => n <= 0 ? [] : data.slice(0, n);
+    /**
+     * Drops the first n elements from an array.
+     *
+     * @example
+     * ```ts
+     * pipe([1, 2, 3, 4], Arr.drop(2)); // [3, 4]
+     * ```
+     */
+    Arr.drop = (n) => (data) => data.slice(n);
+    /**
+     * Takes elements from the start while the predicate holds.
+     *
+     * @example
+     * ```ts
+     * pipe([1, 2, 3, 1], Arr.takeWhile(n => n < 3)); // [1, 2]
+     * ```
+     */
+    Arr.takeWhile = (predicate) => (data) => {
+        const result = [];
+        for (const a of data) {
+            if (!predicate(a))
+                break;
+            result.push(a);
+        }
+        return result;
+    };
+    /**
+     * Drops elements from the start while the predicate holds.
+     *
+     * @example
+     * ```ts
+     * pipe([1, 2, 3, 1], Arr.dropWhile(n => n < 3)); // [3, 1]
+     * ```
+     */
+    Arr.dropWhile = (predicate) => (data) => {
+        let i = 0;
+        while (i < data.length && predicate(data[i]))
+            i++;
+        return data.slice(i);
+    };
+})(Arr || (Arr = {}));

package/esm/src/Core/Deferred.js

@@ -0,0 +1,26 @@
+export var Deferred;
+(function (Deferred) {
+    /**
+     * Wraps a `Promise` into a `Deferred`, structurally excluding rejection handlers,
+     * `.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/InternalTypes.js

@@ -0,0 +1 @@
+export {};

package/esm/src/Core/Lens.js

@@ -0,0 +1,98 @@
+export var Lens;
+(function (Lens) {
+    /**
+     * Constructs a Lens from a getter and a setter.
+     *
+     * @example
+     * ```ts
+     * const nameLens = Lens.make(
+     *   (user: User) => user.name,
+     *   (name) => (user) => ({ ...user, name }),
+     * );
+     * ```
+     */
+    Lens.make = (get, set) => ({ get, set });
+    /**
+     * Creates a Lens that focuses on a property of an object.
+     * Call with the structure type first, then the key.
+     *
+     * @example
+     * ```ts
+     * const nameLens = Lens.prop<User>()("name");
+     * ```
+     */
+    Lens.prop = () => (key) => Lens.make((s) => s[key], (a) => (s) => ({ ...s, [key]: a }));
+    /**
+     * Reads the focused value from a structure.
+     *
+     * @example
+     * ```ts
+     * pipe(user, Lens.get(nameLens)); // "Alice"
+     * ```
+     */
+    Lens.get = (lens) => (s) => lens.get(s);
+    /**
+     * Replaces the focused value within a structure, returning a new structure.
+     *
+     * @example
+     * ```ts
+     * pipe(user, Lens.set(nameLens)("Bob")); // new User with name "Bob"
+     * ```
+     */
+    Lens.set = (lens) => (a) => (s) => lens.set(a)(s);
+    /**
+     * Applies a function to the focused value, returning a new structure.
+     *
+     * @example
+     * ```ts
+     * pipe(user, Lens.modify(nameLens)(n => n.toUpperCase())); // "ALICE"
+     * ```
+     */
+    Lens.modify = (lens) => (f) => (s) => lens.set(f(lens.get(s)))(s);
+    /**
+     * Composes two Lenses: focuses through the outer, then through the inner.
+     * Use in a pipe chain to build up a deep focus step by step.
+     *
+     * @example
+     * ```ts
+     * const userCityLens = pipe(
+     *   Lens.prop<User>()("address"),
+     *   Lens.andThen(Lens.prop<Address>()("city")),
+     * );
+     * ```
+     */
+    Lens.andThen = (inner) => (outer) => Lens.make((s) => inner.get(outer.get(s)), (b) => (s) => outer.set(inner.set(b)(outer.get(s)))(s));
+    /**
+     * Composes a Lens with an Optional, producing an Optional.
+     * Use when the next step in the focus is optional (may be absent).
+     *
+     * @example
+     * ```ts
+     * const userBioOpt = pipe(
+     *   Lens.prop<User>()("profile"),
+     *   Lens.andThenOptional(Optional.prop<Profile>()("bio")),
+     * );
+     * ```
+     */
+    Lens.andThenOptional = (inner) => (outer) => ({
+        get: (s) => inner.get(outer.get(s)),
+        set: (b) => (s) => outer.set(inner.set(b)(outer.get(s)))(s),
+    });
+    /**
+     * Converts a Lens to an Optional. Every Lens is a valid Optional
+     * whose get always returns Some.
+     *
+     * @example
+     * ```ts
+     * pipe(
+     *   Lens.prop<User>()("address"),
+     *   Lens.toOptional,
+     *   Optional.andThen(Optional.prop<Address>()("landmark")),
+     * );
+     * ```
+     */
+    Lens.toOptional = (lens) => ({
+        get: (s) => ({ kind: "Some", value: lens.get(s) }),
+        set: lens.set,
+    });
+})(Lens || (Lens = {}));