@nlozgachev/pipelined 0.10.0 → 0.12.0

package/script/src/Utils/Num.js

@@ -0,0 +1,127 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Num = void 0;
+const Option_js_1 = require("../Core/Option.js");
+/**
+ * Number utilities for common operations. All transformation functions are data-last
+ * and curried so they compose naturally with `pipe` and `Arr.map`.
+ *
+ * @example
+ * ```ts
+ * import { Num } from "@nlozgachev/pipelined/utils";
+ * import { pipe } from "@nlozgachev/pipelined/composition";
+ *
+ * pipe(
+ *   Num.range(1, 6),
+ *   Arr.map(Num.multiply(2)),
+ *   Arr.filter(Num.between(4, 8))
+ * ); // [4, 6, 8]
+ * ```
+ */
+var Num;
+(function (Num) {
+    /**
+     * Generates an array of numbers from `from` to `to` (both inclusive),
+     * stepping by `step` (default `1`). If `step` is negative or zero, or `from > to`,
+     * returns an empty array. When `step` does not land exactly on `to`, the last value
+     * is the largest reachable value that does not exceed `to`.
+     *
+     * @example
+     * ```ts
+     * Num.range(0, 5);       // [0, 1, 2, 3, 4, 5]
+     * Num.range(0, 10, 2);   // [0, 2, 4, 6, 8, 10]
+     * Num.range(0, 9, 2);    // [0, 2, 4, 6, 8]
+     * Num.range(5, 0);       // []
+     * Num.range(3, 3);       // [3]
+     * ```
+     */
+    Num.range = (from, to, step = 1) => {
+        if (step <= 0 || from > to)
+            return [];
+        const count = Math.floor((to - from) / step) + 1;
+        const result = new Array(count);
+        for (let i = 0; i < count; i++) {
+            result[i] = from + i * step;
+        }
+        return result;
+    };
+    /**
+     * Clamps a number between `min` and `max` (both inclusive).
+     *
+     * @example
+     * ```ts
+     * pipe(150, Num.clamp(0, 100)); // 100
+     * pipe(-5, Num.clamp(0, 100));  // 0
+     * pipe(42, Num.clamp(0, 100));  // 42
+     * ```
+     */
+    Num.clamp = (min, max) => (n) => Math.min(Math.max(n, min), max);
+    /**
+     * Returns `true` when the number is between `min` and `max` (both inclusive).
+     *
+     * @example
+     * ```ts
+     * pipe(5, Num.between(1, 10));  // true
+     * pipe(0, Num.between(1, 10));  // false
+     * pipe(10, Num.between(1, 10)); // true
+     * ```
+     */
+    Num.between = (min, max) => (n) => n >= min && n <= max;
+    /**
+     * Parses a string as a number. Returns `None` when the result is `NaN`.
+     *
+     * @example
+     * ```ts
+     * Num.parse("42");   // Some(42)
+     * Num.parse("3.14"); // Some(3.14)
+     * Num.parse("abc");  // None
+     * Num.parse("");     // None
+     * ```
+     */
+    Num.parse = (s) => {
+        if (s.trim() === "")
+            return Option_js_1.Option.none();
+        const n = Number(s);
+        return isNaN(n) ? Option_js_1.Option.none() : Option_js_1.Option.some(n);
+    };
+    /**
+     * Adds `b` to a number. Data-last: use in `pipe` or `Arr.map`.
+     *
+     * @example
+     * ```ts
+     * pipe(5, Num.add(3));                   // 8
+     * pipe([1, 2, 3], Arr.map(Num.add(10))); // [11, 12, 13]
+     * ```
+     */
+    Num.add = (b) => (a) => a + b;
+    /**
+     * Subtracts `b` from a number. Data-last: `subtract(b)(a)` = `a - b`.
+     *
+     * @example
+     * ```ts
+     * pipe(10, Num.subtract(3));                  // 7
+     * pipe([5, 10, 15], Arr.map(Num.subtract(2))); // [3, 8, 13]
+     * ```
+     */
+    Num.subtract = (b) => (a) => a - b;
+    /**
+     * Multiplies a number by `b`. Data-last: use in `pipe` or `Arr.map`.
+     *
+     * @example
+     * ```ts
+     * pipe(6, Num.multiply(7));                    // 42
+     * pipe([1, 2, 3], Arr.map(Num.multiply(100))); // [100, 200, 300]
+     * ```
+     */
+    Num.multiply = (b) => (a) => a * b;
+    /**
+     * Divides a number by `b`. Data-last: `divide(b)(a)` = `a / b`.
+     *
+     * @example
+     * ```ts
+     * pipe(20, Num.divide(4));                      // 5
+     * pipe([10, 20, 30], Arr.map(Num.divide(10)));  // [1, 2, 3]
+     * ```
+     */
+    Num.divide = (b) => (a) => a / b;
+})(Num || (exports.Num = Num = {}));

package/script/src/{Core → Utils}/Rec.js

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Rec = void 0;
-const Option_js_1 = require("./Option.js");
+const Option_js_1 = require("../Core/Option.js");
 /**
  * Functional record/object utilities that compose well with pipe.
  * All functions are data-last and curried where applicable.
@@ -26,9 +26,11 @@ var Rec;
      * ```
      */
     Rec.map = (f) => (data) => {
+        const keys = Object.keys(data);
+        const vals = Object.values(data);
         const result = {};
-        for (const key of Object.keys(data)) {
-            result[key] = f(data[key]);
+        for (let i = 0; i < keys.length; i++) {
+            result[keys[i]] = f(vals[i]);
         }
         return result;
     };
@@ -42,9 +44,11 @@ var Rec;
      * ```
      */
     Rec.mapWithKey = (f) => (data) => {
+        const keys = Object.keys(data);
+        const vals = Object.values(data);
         const result = {};
-        for (const key of Object.keys(data)) {
-            result[key] = f(key, data[key]);
+        for (let i = 0; i < keys.length; i++) {
+            result[keys[i]] = f(keys[i], vals[i]);
         }
         return result;
     };
@@ -57,10 +61,12 @@ var Rec;
      * ```
      */
     Rec.filter = (predicate) => (data) => {
+        const keys = Object.keys(data);
+        const vals = Object.values(data);
         const result = {};
-        for (const key of Object.keys(data)) {
-            if (predicate(data[key]))
-                result[key] = data[key];
+        for (let i = 0; i < keys.length; i++) {
+            if (predicate(vals[i]))
+                result[keys[i]] = vals[i];
         }
         return result;
     };
@@ -74,10 +80,12 @@ var Rec;
      * ```
      */
     Rec.filterWithKey = (predicate) => (data) => {
+        const keys = Object.keys(data);
+        const vals = Object.values(data);
         const result = {};
-        for (const key of Object.keys(data)) {
-            if (predicate(key, data[key]))
-                result[key] = data[key];
+        for (let i = 0; i < keys.length; i++) {
+            if (predicate(keys[i], vals[i]))
+                result[keys[i]] = vals[i];
         }
         return result;
     };
@@ -112,6 +120,32 @@ var Rec;
      * ```
      */
     Rec.fromEntries = (data) => Object.fromEntries(data);
+    /**
+     * Groups elements of an array into a record keyed by the result of `keyFn`. Each key maps to
+     * the array of elements that produced it, in insertion order.
+     *
+     * Unlike `Dict.groupBy`, keys are always strings. Use `Dict.groupBy` when you need non-string
+     * keys or want to avoid the plain-object prototype chain.
+     *
+     * @example
+     * ```ts
+     * pipe(
+     *   ["apple", "avocado", "banana", "blueberry"],
+     *   Rec.groupBy(s => s[0]),
+     * ); // { a: ["apple", "avocado"], b: ["banana", "blueberry"] }
+     * ```
+     */
+    Rec.groupBy = (keyFn) => (items) => {
+        const result = {};
+        for (const item of items) {
+            const key = keyFn(item);
+            if (key in result)
+                result[key].push(item);
+            else
+                result[key] = [item];
+        }
+        return result;
+    };
     /**
      * Picks specific keys from a record.
      *
@@ -167,4 +201,44 @@ var Rec;
      * Returns the number of keys in a record.
      */
     Rec.size = (data) => Object.keys(data).length;
+    /**
+     * Transforms each key while preserving values.
+     * If two keys map to the same new key, the last one wins.
+     *
+     * @example
+     * ```ts
+     * pipe({ firstName: "Alice", lastName: "Smith" }, Rec.mapKeys(k => k.toUpperCase()));
+     * // { FIRSTNAME: "Alice", LASTNAME: "Smith" }
+     * ```
+     */
+    Rec.mapKeys = (f) => (data) => {
+        const keys = Object.keys(data);
+        const vals = Object.values(data);
+        const result = {};
+        for (let i = 0; i < keys.length; i++) {
+            result[f(keys[i])] = vals[i];
+        }
+        return result;
+    };
+    /**
+     * Removes all `None` values from a `Record<string, Option<A>>`, returning a plain `Record<string, A>`.
+     * Useful when building records from fallible lookups.
+     *
+     * @example
+     * ```ts
+     * Rec.compact({ a: Option.some(1), b: Option.none(), c: Option.some(3) });
+     * // { a: 1, c: 3 }
+     * ```
+     */
+    Rec.compact = (data) => {
+        const keys = Object.keys(data);
+        const vals = Object.values(data);
+        const result = {};
+        for (let i = 0; i < keys.length; i++) {
+            const v = vals[i];
+            if (v.kind === "Some")
+                result[keys[i]] = v.value;
+        }
+        return result;
+    };
 })(Rec || (exports.Rec = Rec = {}));

package/script/src/Utils/Str.js

@@ -0,0 +1,137 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Str = void 0;
+const Option_js_1 = require("../Core/Option.js");
+/**
+ * String utilities. All transformation functions are data-last and curried so they
+ * compose naturally with `pipe`. Safe parsers return `Option` instead of `NaN`.
+ *
+ * @example
+ * ```ts
+ * import { Str } from "@nlozgachev/pipelined/utils";
+ * import { pipe } from "@nlozgachev/pipelined/composition";
+ *
+ * pipe("  Hello, World!  ", Str.trim, Str.toLowerCase); // "hello, world!"
+ * ```
+ */
+var Str;
+(function (Str) {
+    /**
+     * Splits a string by a separator. Data-last: use in `pipe`.
+     *
+     * @example
+     * ```ts
+     * pipe("a,b,c", Str.split(",")); // ["a", "b", "c"]
+     * ```
+     */
+    Str.split = (separator) => (s) => s.split(separator);
+    /**
+     * Removes leading and trailing whitespace from a string.
+     *
+     * @example
+     * ```ts
+     * pipe("  hello  ", Str.trim); // "hello"
+     * ```
+     */
+    Str.trim = (s) => s.trim();
+    /**
+     * Returns `true` when the string contains the given substring.
+     *
+     * @example
+     * ```ts
+     * pipe("hello world", Str.includes("world")); // true
+     * pipe("hello world", Str.includes("xyz"));   // false
+     * ```
+     */
+    Str.includes = (substring) => (s) => s.includes(substring);
+    /**
+     * Returns `true` when the string starts with the given prefix.
+     *
+     * @example
+     * ```ts
+     * pipe("hello world", Str.startsWith("hello")); // true
+     * pipe("hello world", Str.startsWith("world")); // false
+     * ```
+     */
+    Str.startsWith = (prefix) => (s) => s.startsWith(prefix);
+    /**
+     * Returns `true` when the string ends with the given suffix.
+     *
+     * @example
+     * ```ts
+     * pipe("hello world", Str.endsWith("world")); // true
+     * pipe("hello world", Str.endsWith("hello")); // false
+     * ```
+     */
+    Str.endsWith = (suffix) => (s) => s.endsWith(suffix);
+    /**
+     * Converts a string to uppercase.
+     *
+     * @example
+     * ```ts
+     * pipe("hello", Str.toUpperCase); // "HELLO"
+     * ```
+     */
+    Str.toUpperCase = (s) => s.toUpperCase();
+    /**
+     * Converts a string to lowercase.
+     *
+     * @example
+     * ```ts
+     * pipe("HELLO", Str.toLowerCase); // "hello"
+     * ```
+     */
+    Str.toLowerCase = (s) => s.toLowerCase();
+    /**
+     * Splits a string into lines, normalising `\r\n` and `\r` line endings.
+     *
+     * @example
+     * ```ts
+     * Str.lines("one\ntwo\nthree"); // ["one", "two", "three"]
+     * Str.lines("a\r\nb");         // ["a", "b"]
+     * ```
+     */
+    Str.lines = (s) => s.split(/\r?\n|\r/);
+    /**
+     * Splits a string into words on any whitespace boundary, filtering out empty strings.
+     *
+     * @example
+     * ```ts
+     * Str.words("  hello   world  "); // ["hello", "world"]
+     * ```
+     */
+    Str.words = (s) => s.trim().split(/\s+/).filter(Boolean);
+    /**
+     * Safe number parsers that return `Option` instead of `NaN`.
+     */
+    Str.parse = {
+        /**
+         * Parses a string as an integer (base 10). Returns `None` if the result is `NaN`.
+         *
+         * @example
+         * ```ts
+         * Str.parse.int("42");   // Some(42)
+         * Str.parse.int("3.7");  // Some(3)
+         * Str.parse.int("abc");  // None
+         * ```
+         */
+        int: (s) => {
+            const n = parseInt(s, 10);
+            return isNaN(n) ? Option_js_1.Option.none() : Option_js_1.Option.some(n);
+        },
+        /**
+         * Parses a string as a floating-point number. Returns `None` if the result is `NaN`.
+         *
+         * @example
+         * ```ts
+         * Str.parse.float("3.14"); // Some(3.14)
+         * Str.parse.float("42");   // Some(42)
+         * Str.parse.float("abc");  // None
+         * ```
+         */
+        float: (s) => {
+            const n = parseFloat(s);
+            return isNaN(n) ? Option_js_1.Option.none() : Option_js_1.Option.some(n);
+        },
+    };
+})(Str || (exports.Str = Str = {}));

package/script/src/Utils/Uniq.js

@@ -0,0 +1,268 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Uniq = void 0;
+/**
+ * Functional utilities for unique-value collections (`ReadonlySet<A>`). All functions are pure
+ * and data-last — they compose naturally with `pipe`.
+ *
+ * Every "mutating" operation returns a new set; the original is never changed.
+ *
+ * @example
+ * ```ts
+ * import { Uniq } from "@nlozgachev/pipelined/utils";
+ * import { pipe } from "@nlozgachev/pipelined/composition";
+ *
+ * const active = pipe(
+ *   Uniq.fromArray(["alice", "bob", "alice", "carol"]),
+ *   Uniq.remove("bob"),
+ *   Uniq.map(name => name.toUpperCase()),
+ * );
+ * // ReadonlySet { "ALICE", "CAROL" }
+ * ```
+ */
+var Uniq;
+(function (Uniq) {
+    // ---------------------------------------------------------------------------
+    // Constructors
+    // ---------------------------------------------------------------------------
+    /**
+     * Creates an empty unique collection.
+     *
+     * @example
+     * ```ts
+     * Uniq.empty<number>(); // ReadonlySet {}
+     * ```
+     */
+    Uniq.empty = () => new globalThis.Set();
+    /**
+     * Creates a unique collection containing a single item.
+     *
+     * @example
+     * ```ts
+     * Uniq.singleton(42); // ReadonlySet { 42 }
+     * ```
+     */
+    Uniq.singleton = (item) => new globalThis.Set([item]);
+    /**
+     * Creates a unique collection from an array, automatically discarding duplicates.
+     *
+     * @example
+     * ```ts
+     * Uniq.fromArray([1, 2, 2, 3, 3, 3]); // ReadonlySet { 1, 2, 3 }
+     * Uniq.fromArray([]);                  // ReadonlySet {}
+     * ```
+     */
+    Uniq.fromArray = (arr) => new globalThis.Set(arr);
+    // ---------------------------------------------------------------------------
+    // Query
+    // ---------------------------------------------------------------------------
+    /**
+     * Returns `true` if the collection contains the given item.
+     *
+     * @example
+     * ```ts
+     * pipe(Uniq.fromArray([1, 2, 3]), Uniq.has(2)); // true
+     * pipe(Uniq.fromArray([1, 2, 3]), Uniq.has(4)); // false
+     * ```
+     */
+    Uniq.has = (item) => (s) => s.has(item);
+    /**
+     * Returns the number of items in the collection.
+     *
+     * @example
+     * ```ts
+     * Uniq.size(Uniq.fromArray([1, 2, 3])); // 3
+     * ```
+     */
+    Uniq.size = (s) => s.size;
+    /**
+     * Returns `true` if the collection has no items.
+     *
+     * @example
+     * ```ts
+     * Uniq.isEmpty(Uniq.empty()); // true
+     * ```
+     */
+    Uniq.isEmpty = (s) => s.size === 0;
+    /**
+     * Returns `true` if every item in `set` also exists in `other`.
+     *
+     * @example
+     * ```ts
+     * pipe(Uniq.fromArray([1, 2]), Uniq.isSubsetOf(Uniq.fromArray([1, 2, 3]))); // true
+     * pipe(Uniq.fromArray([1, 4]), Uniq.isSubsetOf(Uniq.fromArray([1, 2, 3]))); // false
+     * pipe(Uniq.empty<number>(), Uniq.isSubsetOf(Uniq.fromArray([1, 2, 3])));   // true
+     * ```
+     */
+    Uniq.isSubsetOf = (other) => (s) => {
+        const set = s;
+        if (typeof set.isSubsetOf === "function")
+            return set.isSubsetOf(other);
+        for (const item of s)
+            if (!other.has(item))
+                return false;
+        return true;
+    };
+    // ---------------------------------------------------------------------------
+    // Modification
+    // ---------------------------------------------------------------------------
+    /**
+     * Returns a new collection with the item added. If the item is already present, returns the
+     * original collection unchanged.
+     *
+     * @example
+     * ```ts
+     * pipe(Uniq.fromArray([1, 2]), Uniq.insert(3)); // ReadonlySet { 1, 2, 3 }
+     * pipe(Uniq.fromArray([1, 2]), Uniq.insert(2)); // ReadonlySet { 1, 2 } — unchanged
+     * ```
+     */
+    Uniq.insert = (item) => (s) => {
+        if (s.has(item))
+            return s;
+        const result = new globalThis.Set(s);
+        result.add(item);
+        return result;
+    };
+    /**
+     * Returns a new collection with the item removed. If the item is not present, returns the
+     * original collection unchanged.
+     *
+     * @example
+     * ```ts
+     * pipe(Uniq.fromArray([1, 2, 3]), Uniq.remove(2)); // ReadonlySet { 1, 3 }
+     * pipe(Uniq.fromArray([1, 2, 3]), Uniq.remove(4)); // ReadonlySet { 1, 2, 3 } — unchanged
+     * ```
+     */
+    Uniq.remove = (item) => (s) => {
+        if (!s.has(item))
+            return s;
+        const result = new globalThis.Set(s);
+        result.delete(item);
+        return result;
+    };
+    // ---------------------------------------------------------------------------
+    // Transform
+    // ---------------------------------------------------------------------------
+    /**
+     * Applies `f` to each item, returning a new collection of the results. Duplicate results are
+     * automatically merged.
+     *
+     * @example
+     * ```ts
+     * pipe(Uniq.fromArray([1, 2, 3, 4]), Uniq.map(n => n % 3)); // ReadonlySet { 1, 2, 0 }
+     * ```
+     */
+    Uniq.map = (f) => (s) => {
+        const result = new globalThis.Set();
+        for (const item of s) {
+            result.add(f(item));
+        }
+        return result;
+    };
+    /**
+     * Returns a new collection containing only the items for which the predicate returns `true`.
+     *
+     * @example
+     * ```ts
+     * pipe(Uniq.fromArray([1, 2, 3, 4, 5]), Uniq.filter(n => n % 2 === 0));
+     * // ReadonlySet { 2, 4 }
+     * ```
+     */
+    Uniq.filter = (predicate) => (s) => {
+        const result = new globalThis.Set();
+        for (const item of s) {
+            if (predicate(item))
+                result.add(item);
+        }
+        return result;
+    };
+    // ---------------------------------------------------------------------------
+    // Set operations
+    // ---------------------------------------------------------------------------
+    /**
+     * Returns a new collection containing all items from both collections.
+     *
+     * @example
+     * ```ts
+     * pipe(Uniq.fromArray([1, 2, 3]), Uniq.union(Uniq.fromArray([2, 3, 4])));
+     * // ReadonlySet { 1, 2, 3, 4 }
+     * ```
+     */
+    Uniq.union = (other) => (s) => {
+        const set = s;
+        if (typeof set.union === "function")
+            return set.union(other);
+        const result = new globalThis.Set(s);
+        for (const item of other)
+            result.add(item);
+        return result;
+    };
+    /**
+     * Returns a new collection containing only the items that appear in both collections.
+     *
+     * @example
+     * ```ts
+     * pipe(Uniq.fromArray([1, 2, 3]), Uniq.intersection(Uniq.fromArray([2, 3, 4])));
+     * // ReadonlySet { 2, 3 }
+     * ```
+     */
+    Uniq.intersection = (other) => (s) => {
+        const set = s;
+        if (typeof set.intersection === "function")
+            return set.intersection(other);
+        const result = new globalThis.Set();
+        for (const item of s)
+            if (other.has(item))
+                result.add(item);
+        return result;
+    };
+    /**
+     * Returns a new collection containing only the items from `set` that do not appear in `other`.
+     *
+     * @example
+     * ```ts
+     * pipe(Uniq.fromArray([1, 2, 3, 4]), Uniq.difference(Uniq.fromArray([2, 4])));
+     * // ReadonlySet { 1, 3 }
+     * ```
+     */
+    Uniq.difference = (other) => (s) => {
+        const set = s;
+        if (typeof set.difference === "function")
+            return set.difference(other);
+        const result = new globalThis.Set();
+        for (const item of s)
+            if (!other.has(item))
+                result.add(item);
+        return result;
+    };
+    // ---------------------------------------------------------------------------
+    // Fold
+    // ---------------------------------------------------------------------------
+    /**
+     * Folds the collection into a single value by applying `f` to each item in insertion order.
+     *
+     * @example
+     * ```ts
+     * Uniq.reduce(0, (acc, n) => acc + n)(Uniq.fromArray([1, 2, 3])); // 6
+     * ```
+     */
+    Uniq.reduce = (init, f) => (s) => {
+        let acc = init;
+        for (const item of s) {
+            acc = f(acc, item);
+        }
+        return acc;
+    };
+    // ---------------------------------------------------------------------------
+    // Convert
+    // ---------------------------------------------------------------------------
+    /**
+     * Converts the collection to a readonly array in insertion order.
+     *
+     * @example
+     * ```ts
+     * Uniq.toArray(Uniq.fromArray([3, 1, 2])); // [3, 1, 2]
+     * ```
+     */
+    Uniq.toArray = (s) => [...s];
+})(Uniq || (exports.Uniq = Uniq = {}));

package/script/src/Utils/index.js

@@ -0,0 +1,22 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./Arr.js"), exports);
+__exportStar(require("./Rec.js"), exports);
+__exportStar(require("./Num.js"), exports);
+__exportStar(require("./Str.js"), exports);
+__exportStar(require("./Dict.js"), exports);
+__exportStar(require("./Uniq.js"), exports);