@nlozgachev/pipelined 0.10.0 → 0.12.0

package/esm/src/Utils/Str.js

@@ -0,0 +1,134 @@
+import { Option } from "../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!"
+ * ```
+ */
+export 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.none() : 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.none() : Option.some(n);
+        },
+    };
+})(Str || (Str = {}));

package/esm/src/Utils/Uniq.js

@@ -0,0 +1,265 @@
+/**
+ * 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" }
+ * ```
+ */
+export 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 || (Uniq = {}));

package/esm/src/Utils/index.js

@@ -0,0 +1,6 @@
+export * from "./Arr.js";
+export * from "./Rec.js";
+export * from "./Num.js";
+export * from "./Str.js";
+export * from "./Dict.js";
+export * from "./Uniq.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nlozgachev/pipelined",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "description": "Simple functional programming toolkit for TypeScript",
   "keywords": [
     "functional",
@@ -37,6 +37,16 @@
         "default": "./script/src/Core/index.js"
       }
     },
+    "./utils": {
+      "import": {
+        "types": "./types/src/Utils/index.d.ts",
+        "default": "./esm/src/Utils/index.js"
+      },
+      "require": {
+        "types": "./types/src/Utils/index.d.ts",
+        "default": "./script/src/Utils/index.js"
+      }
+    },
     "./types": {
       "import": {
         "types": "./types/src/Types/index.d.ts",

package/script/src/Core/Option.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Option = void 0;
 const Result_js_1 = require("./Result.js");
+const _none = { kind: "None" };
 var Option;
 (function (Option) {
     /**
@@ -15,7 +16,7 @@ var Option;
     /**
      * Creates a None (empty Option).
      */
-    Option.none = () => ({ kind: "None" });
+    Option.none = () => _none;
     /**
      * Type guard that checks if a Option is None.
      */

package/script/src/Core/RemoteData.js

@@ -3,16 +3,18 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.RemoteData = void 0;
 const Option_js_1 = require("./Option.js");
 const Result_js_1 = require("./Result.js");
+const _notAsked = { kind: "NotAsked" };
+const _loading = { kind: "Loading" };
 var RemoteData;
 (function (RemoteData) {
     /**
      * Creates a NotAsked RemoteData.
      */
-    RemoteData.notAsked = () => ({ kind: "NotAsked" });
+    RemoteData.notAsked = () => _notAsked;
     /**
      * Creates a Loading RemoteData.
      */
-    RemoteData.loading = () => ({ kind: "Loading" });
+    RemoteData.loading = () => _loading;
     /**
      * Creates a Failure RemoteData with the given error.
      */
@@ -208,7 +210,5 @@ var RemoteData;
      * ); // Ok(42)
      * ```
      */
-    RemoteData.toResult = (onNotReady) => (data) => RemoteData.isSuccess(data)
-        ? Result_js_1.Result.ok(data.value)
-        : Result_js_1.Result.err(RemoteData.isFailure(data) ? data.error : onNotReady());
+    RemoteData.toResult = (onNotReady) => (data) => RemoteData.isSuccess(data) ? Result_js_1.Result.ok(data.value) : Result_js_1.Result.err(RemoteData.isFailure(data) ? data.error : onNotReady());
 })(RemoteData || (exports.RemoteData = RemoteData = {}));

package/script/src/Core/TaskValidation.js

@@ -94,9 +94,7 @@ var TaskValidation;
      * The fallback receives the accumulated error list so callers can inspect which errors occurred.
      * The fallback can produce a different success type, widening the result to `TaskValidation<E, A | B>`.
      */
-    TaskValidation.recover = (fallback) => (data) => Task_js_1.Task.chain((validation) => Validation_js_1.Validation.isValid(validation)
-        ? Task_js_1.Task.resolve(validation)
-        : fallback(validation.errors))(data);
+    TaskValidation.recover = (fallback) => (data) => Task_js_1.Task.chain((validation) => Validation_js_1.Validation.isValid(validation) ? Task_js_1.Task.resolve(validation) : fallback(validation.errors))(data);
     /**
      * Runs two TaskValidations concurrently and combines their results into a tuple.
      * If both are Valid, returns Valid with both values. If either fails, accumulates

package/script/src/Core/Tuple.js

@@ -0,0 +1,115 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Tuple = void 0;
+var Tuple;
+(function (Tuple) {
+    /**
+     * Creates a pair from two values.
+     *
+     * @example
+     * ```ts
+     * Tuple.make("Paris", 2_161_000); // ["Paris", 2161000]
+     * ```
+     */
+    Tuple.make = (first, second) => [first, second];
+    /**
+     * Returns the first value from the pair.
+     *
+     * @example
+     * ```ts
+     * Tuple.first(Tuple.make("Paris", 2_161_000)); // "Paris"
+     * ```
+     */
+    Tuple.first = (tuple) => tuple[0];
+    /**
+     * Returns the second value from the pair.
+     *
+     * @example
+     * ```ts
+     * Tuple.second(Tuple.make("Paris", 2_161_000)); // 2161000
+     * ```
+     */
+    Tuple.second = (tuple) => tuple[1];
+    /**
+     * Transforms the first value, leaving the second unchanged.
+     *
+     * @example
+     * ```ts
+     * pipe(Tuple.make("alice", 42), Tuple.mapFirst((s) => s.toUpperCase())); // ["ALICE", 42]
+     * ```
+     */
+    Tuple.mapFirst = (f) => (tuple) => [f(tuple[0]), tuple[1]];
+    /**
+     * Transforms the second value, leaving the first unchanged.
+     *
+     * @example
+     * ```ts
+     * pipe(Tuple.make("alice", 42), Tuple.mapSecond((n) => n * 2)); // ["alice", 84]
+     * ```
+     */
+    Tuple.mapSecond = (f) => (tuple) => [tuple[0], f(tuple[1])];
+    /**
+     * Transforms both values independently in a single step.
+     *
+     * @example
+     * ```ts
+     * pipe(
+     *   Tuple.make("alice", 42),
+     *   Tuple.mapBoth(
+     *     (name) => name.toUpperCase(),
+     *     (score) => score * 2,
+     *   ),
+     * ); // ["ALICE", 84]
+     * ```
+     */
+    Tuple.mapBoth = (onFirst, onSecond) => (tuple) => [
+        onFirst(tuple[0]),
+        onSecond(tuple[1]),
+    ];
+    /**
+     * Applies a binary function to both values, collapsing the pair into a single value.
+     * Useful as the final step when consuming a pair in a pipeline.
+     *
+     * @example
+     * ```ts
+     * pipe(Tuple.make("Alice", 100), Tuple.fold((name, score) => `${name}: ${score}`));
+     * // "Alice: 100"
+     * ```
+     */
+    Tuple.fold = (f) => (tuple) => f(tuple[0], tuple[1]);
+    /**
+     * Swaps the two values: `[A, B]` becomes `[B, A]`.
+     *
+     * @example
+     * ```ts
+     * Tuple.swap(Tuple.make("key", 1)); // [1, "key"]
+     * ```
+     */
+    Tuple.swap = (tuple) => [tuple[1], tuple[0]];
+    /**
+     * Converts the pair to a heterogeneous readonly array `readonly (A | B)[]`.
+     *
+     * @example
+     * ```ts
+     * Tuple.toArray(Tuple.make("hello", 42)); // ["hello", 42]
+     * ```
+     */
+    Tuple.toArray = (tuple) => [...tuple];
+    /**
+     * Runs a side effect with both values without changing the pair.
+     * Useful for logging or debugging in the middle of a pipeline.
+     *
+     * @example
+     * ```ts
+     * pipe(
+     *   Tuple.make("Paris", 2_161_000),
+     *   Tuple.tap((city, pop) => console.log(`${city}: ${pop}`)),
+     *   Tuple.mapSecond((n) => n / 1_000_000),
+     * ); // logs "Paris: 2161000", returns ["Paris", 2.161]
+     * ```
+     */
+    Tuple.tap = (f) => (tuple) => {
+        f(tuple[0], tuple[1]);
+        return tuple;
+    };
+})(Tuple || (exports.Tuple = Tuple = {}));

package/script/src/Core/index.js

@@ -14,22 +14,21 @@ 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("./Logged.js"), exports);
 __exportStar(require("./Deferred.js"), exports);
 __exportStar(require("./Lens.js"), exports);
+__exportStar(require("./Logged.js"), exports);
 __exportStar(require("./Option.js"), exports);
-__exportStar(require("./Reader.js"), exports);
 __exportStar(require("./Optional.js"), exports);
-__exportStar(require("./Rec.js"), exports);
 __exportStar(require("./Predicate.js"), exports);
+__exportStar(require("./Reader.js"), exports);
 __exportStar(require("./Refinement.js"), exports);
 __exportStar(require("./RemoteData.js"), exports);
-__exportStar(require("./State.js"), exports);
 __exportStar(require("./Result.js"), exports);
+__exportStar(require("./State.js"), exports);
 __exportStar(require("./Task.js"), exports);
 __exportStar(require("./TaskOption.js"), exports);
 __exportStar(require("./TaskResult.js"), exports);
 __exportStar(require("./TaskValidation.js"), exports);
 __exportStar(require("./These.js"), exports);
+__exportStar(require("./Tuple.js"), exports);
 __exportStar(require("./Validation.js"), exports);