@nlozgachev/pipekit 0.1.6

package/esm/src/Core/Arr.js

@@ -0,0 +1,461 @@
+import { Option } from "./Option.js";
+import { Result } from "./Result.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.toSome(data[0]) : Option.toNone();
+    /**
+     * 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.toSome(data[data.length - 1]) : Option.toNone();
+    /**
+     * 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.toSome(data.slice(1)) : Option.toNone();
+    /**
+     * 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.toSome(data.slice(0, -1)) : Option.toNone();
+    // --- 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.toSome(data[idx]) : Option.toNone();
+    };
+    /**
+     * 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.toSome(data[i]);
+        }
+        return Option.toNone();
+    };
+    /**
+     * 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.toSome(idx) : Option.toNone();
+    };
+    // --- 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.toNone() : Option.of(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.toNone();
+            result.push(mapped.value);
+        }
+        return Option.toSome(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.toOk(n) : Result.toErr("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.toOk(result);
+    };
+    /**
+     * Maps each element to a Task and runs all in parallel.
+     *
+     * @example
+     * ```ts
+     * pipe(
+     *   [1, 2, 3],
+     *   Arr.traverseTask(n => Task.of(n * 2))
+     * )(); // Promise<[2, 4, 6]>
+     * ```
+     */
+    Arr.traverseTask = (f) => (data) => () => Promise.all(data.map((a) => f(a)()));
+    /**
+     * Collects an array of Options into an Option of array.
+     * Returns None if any element is None.
+     *
+     * @example
+     * ```ts
+     * Arr.sequence([Option.of(1), Option.of(2)]); // Some([1, 2])
+     * Arr.sequence([Option.of(1), Option.toNone()]); // 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/InternalTypes.js

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

package/esm/src/Core/Option.js

@@ -0,0 +1,195 @@
+import { Result } from "./Result.js";
+export var Option;
+(function (Option) {
+    /**
+     * Wraps a value in a Some.
+     *
+     * @example
+     * ```ts
+     * Option.of(42); // Some(42)
+     * ```
+     */
+    Option.of = (value) => Option.toSome(value);
+    /**
+     * Creates a Some containing the given value.
+     */
+    Option.toSome = (value) => ({ kind: "Some", value });
+    /**
+     * Type guard that checks if a Option is Some.
+     */
+    Option.isSome = (data) => data.kind === "Some";
+    /**
+     * Creates a None (empty Option).
+     */
+    Option.toNone = () => ({ kind: "None" });
+    /**
+     * Type guard that checks if a Option is None.
+     */
+    Option.isNone = (data) => data.kind === "None";
+    /**
+     * Creates a Option from a nullable value.
+     * Returns None if the value is null or undefined, Some otherwise.
+     *
+     * @example
+     * ```ts
+     * Option.fromNullable(null); // None
+     * Option.fromNullable(42); // Some(42)
+     * ```
+     */
+    Option.fromNullable = (value) => value === null || value === undefined ? Option.toNone() : Option.toSome(value);
+    /**
+     * Extracts the value from a Option, returning null if None.
+     */
+    Option.toNullable = (data) => Option.isSome(data) ? data.value : null;
+    /**
+     * Extracts the value from a Option, returning undefined if None.
+     */
+    Option.toUndefined = (data) => Option.isSome(data) ? data.value : undefined;
+    /**
+     * Creates a Option from a possibly undefined value.
+     * Returns None if undefined, Some otherwise.
+     */
+    Option.fromUndefined = (value) => value === undefined ? Option.toNone() : Option.toSome(value);
+    /**
+     * Converts an Option to a Result.
+     * Some becomes Ok, None becomes Err with the provided error.
+     *
+     * @example
+     * ```ts
+     * pipe(
+     *   Option.of(42),
+     *   Option.toResult(() => "Value was missing")
+     * ); // Ok(42)
+     *
+     * pipe(
+     *   Option.toNone(),
+     *   Option.toResult(() => "Value was missing")
+     * ); // Err("Value was missing")
+     * ```
+     */
+    Option.toResult = (onNone) => (data) => Option.isSome(data) ? Result.toOk(data.value) : Result.toErr(onNone());
+    /**
+     * Creates an Option from a Result.
+     * Ok becomes Some, Err becomes None (the error is discarded).
+     *
+     * @example
+     * ```ts
+     * Option.fromResult(Result.toOk(42)); // Some(42)
+     * Option.fromResult(Result.toErr("oops")); // None
+     * ```
+     */
+    Option.fromResult = (data) => Result.isOk(data) ? Option.toSome(data.value) : Option.toNone();
+    /**
+     * Transforms the value inside a Option if it exists.
+     *
+     * @example
+     * ```ts
+     * pipe(Option.of(5), Option.map(n => n * 2)); // Some(10)
+     * pipe(Option.toNone(), Option.map(n => n * 2)); // None
+     * ```
+     */
+    Option.map = (f) => (data) => Option.isSome(data) ? Option.toSome(f(data.value)) : data;
+    /**
+     * Chains Option computations. If the first is Some, passes the value to f.
+     * If the first is None, propagates None.
+     *
+     * @example
+     * ```ts
+     * const parseNumber = (s: string): Option<number> => {
+     *   const n = parseInt(s, 10);
+     *   return isNaN(n) ? Option.toNone() : Option.of(n);
+     * };
+     *
+     * pipe(Option.of("42"), Option.chain(parseNumber)); // Some(42)
+     * pipe(Option.of("abc"), Option.chain(parseNumber)); // None
+     * ```
+     */
+    Option.chain = (f) => (data) => Option.isSome(data) ? f(data.value) : data;
+    /**
+     * Extracts the value from a Option by providing handlers for both cases.
+     *
+     * @example
+     * ```ts
+     * pipe(
+     *   Option.of(5),
+     *   Option.fold(
+     *     () => "No value",
+     *     n => `Value: ${n}`
+     *   )
+     * ); // "Value: 5"
+     * ```
+     */
+    Option.fold = (onNone, onSome) => (data) => Option.isSome(data) ? onSome(data.value) : onNone();
+    /**
+     * Pattern matches on a Option, returning the result of the matching case.
+     *
+     * @example
+     * ```ts
+     * pipe(
+     *   optionUser,
+     *   Option.match({
+     *     some: user => `Hello, ${user.name}`,
+     *     none: () => "Hello, stranger"
+     *   })
+     * );
+     * ```
+     */
+    Option.match = (cases) => (data) => Option.isSome(data) ? cases.some(data.value) : cases.none();
+    /**
+     * Returns the value inside a Option, or a default value if None.
+     *
+     * @example
+     * ```ts
+     * pipe(Option.of(5), Option.getOrElse(0)); // 5
+     * pipe(Option.toNone(), Option.getOrElse(0)); // 0
+     * ```
+     */
+    Option.getOrElse = (defaultValue) => (data) => Option.isSome(data) ? data.value : defaultValue;
+    /**
+     * Executes a side effect on the value without changing the Option.
+     * Useful for logging or debugging.
+     *
+     * @example
+     * ```ts
+     * pipe(
+     *   Option.of(5),
+     *   Option.tap(n => console.log("Value:", n)),
+     *   Option.map(n => n * 2)
+     * );
+     * ```
+     */
+    Option.tap = (f) => (data) => {
+        if (Option.isSome(data))
+            f(data.value);
+        return data;
+    };
+    /**
+     * Filters a Option based on a predicate.
+     * Returns None if the predicate returns false or if the Option is already None.
+     *
+     * @example
+     * ```ts
+     * pipe(Option.of(5), Option.filter(n => n > 3)); // Some(5)
+     * pipe(Option.of(2), Option.filter(n => n > 3)); // None
+     * ```
+     */
+    Option.filter = (predicate) => (data) => Option.isSome(data) && predicate(data.value) ? data : Option.toNone();
+    /**
+     * Recovers from a None by providing a fallback Option.
+     */
+    Option.recover = (fallback) => (data) => Option.isSome(data) ? data : fallback();
+    /**
+     * Applies a function wrapped in a Option to a value wrapped in a Option.
+     *
+     * @example
+     * ```ts
+     * const add = (a: number) => (b: number) => a + b;
+     * pipe(
+     *   Option.of(add),
+     *   Option.ap(Option.of(5)),
+     *   Option.ap(Option.of(3))
+     * ); // Some(8)
+     * ```
+     */
+    Option.ap = (arg) => (data) => Option.isSome(data) && Option.isSome(arg) ? Option.toSome(data.value(arg.value)) : Option.toNone();
+})(Option || (Option = {}));