@nlozgachev/pipelined 0.11.0 → 0.12.0

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

@@ -2,3 +2,5 @@ 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.11.0",
+  "version": "0.12.0",
   "description": "Simple functional programming toolkit for TypeScript",
   "keywords": [
     "functional",

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,20 +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("./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("./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);