@nlozgachev/pipelined 0.11.0 → 0.12.0

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

@@ -18,3 +18,5 @@ __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);

package/types/src/Core/Tuple.d.ts

@@ -0,0 +1,129 @@
+/**
+ * Tuple<A, B> represents a pair of two values that are always both present.
+ * It is a typed alias for `readonly [A, B]`.
+ *
+ * Use Tuple when two values always travel together through a pipeline and you
+ * want to transform either or both sides without destructuring.
+ *
+ * @example
+ * ```ts
+ * import { Tuple } from "@nlozgachev/pipelined/core";
+ * import { pipe } from "@nlozgachev/pipelined/composition";
+ *
+ * const entry = Tuple.make("alice", 42);
+ *
+ * pipe(
+ *   entry,
+ *   Tuple.mapFirst((name) => name.toUpperCase()),
+ *   Tuple.mapSecond((score) => score * 2),
+ *   Tuple.fold((name, score) => `${name}: ${score}`),
+ * ); // "ALICE: 84"
+ * ```
+ */
+export type Tuple<A, B> = readonly [A, B];
+export declare namespace Tuple {
+    /**
+     * Creates a pair from two values.
+     *
+     * @example
+     * ```ts
+     * Tuple.make("Paris", 2_161_000); // ["Paris", 2161000]
+     * ```
+     */
+    const make: <A, B>(first: A, second: B) => Tuple<A, B>;
+    /**
+     * Returns the first value from the pair.
+     *
+     * @example
+     * ```ts
+     * Tuple.first(Tuple.make("Paris", 2_161_000)); // "Paris"
+     * ```
+     */
+    const first: <A, B>(tuple: Tuple<A, B>) => A;
+    /**
+     * Returns the second value from the pair.
+     *
+     * @example
+     * ```ts
+     * Tuple.second(Tuple.make("Paris", 2_161_000)); // 2161000
+     * ```
+     */
+    const second: <A, B>(tuple: Tuple<A, B>) => B;
+    /**
+     * Transforms the first value, leaving the second unchanged.
+     *
+     * @example
+     * ```ts
+     * pipe(Tuple.make("alice", 42), Tuple.mapFirst((s) => s.toUpperCase())); // ["ALICE", 42]
+     * ```
+     */
+    const mapFirst: <A, C>(f: (a: A) => C) => <B>(tuple: Tuple<A, B>) => Tuple<C, B>;
+    /**
+     * Transforms the second value, leaving the first unchanged.
+     *
+     * @example
+     * ```ts
+     * pipe(Tuple.make("alice", 42), Tuple.mapSecond((n) => n * 2)); // ["alice", 84]
+     * ```
+     */
+    const mapSecond: <B, D>(f: (b: B) => D) => <A>(tuple: Tuple<A, B>) => Tuple<A, D>;
+    /**
+     * 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]
+     * ```
+     */
+    const mapBoth: <A, C, B, D>(onFirst: (a: A) => C, onSecond: (b: B) => D) => (tuple: Tuple<A, B>) => Tuple<C, D>;
+    /**
+     * 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"
+     * ```
+     */
+    const fold: <A, B, C>(f: (a: A, b: B) => C) => (tuple: Tuple<A, B>) => C;
+    /**
+     * Swaps the two values: `[A, B]` becomes `[B, A]`.
+     *
+     * @example
+     * ```ts
+     * Tuple.swap(Tuple.make("key", 1)); // [1, "key"]
+     * ```
+     */
+    const swap: <A, B>(tuple: Tuple<A, B>) => Tuple<B, A>;
+    /**
+     * Converts the pair to a heterogeneous readonly array `readonly (A | B)[]`.
+     *
+     * @example
+     * ```ts
+     * Tuple.toArray(Tuple.make("hello", 42)); // ["hello", 42]
+     * ```
+     */
+    const toArray: <A, B>(tuple: Tuple<A, B>) => readonly (A | B)[];
+    /**
+     * 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]
+     * ```
+     */
+    const tap: <A, B>(f: (a: A, b: B) => void) => (tuple: Tuple<A, B>) => Tuple<A, B>;
+}
+//# sourceMappingURL=Tuple.d.ts.map

package/types/src/Core/Tuple.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Tuple.d.ts","sourceRoot":"","sources":["../../../src/src/Core/Tuple.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,MAAM,KAAK,CAAC,CAAC,EAAE,CAAC,IAAI,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AAE1C,yBAAiB,KAAK,CAAC;IACtB;;;;;;;OAOG;IACI,MAAM,IAAI,GAAI,CAAC,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE,QAAQ,CAAC,KAAG,KAAK,CAAC,CAAC,EAAE,CAAC,CAAoB,CAAC;IAEhF;;;;;;;OAOG;IACI,MAAM,KAAK,GAAI,CAAC,EAAE,CAAC,EAAE,OAAO,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,KAAG,CAAa,CAAC;IAE/D;;;;;;;OAOG;IACI,MAAM,MAAM,GAAI,CAAC,EAAE,CAAC,EAAE,OAAO,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,KAAG,CAAa,CAAC;IAEhE;;;;;;;OAOG;IACI,MAAM,QAAQ,GAAI,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,OAAO,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,KAAG,KAAK,CAAC,CAAC,EAAE,CAAC,CAA4B,CAAC;IAElH;;;;;;;OAOG;IACI,MAAM,SAAS,GAAI,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,OAAO,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,KAAG,KAAK,CAAC,CAAC,EAAE,CAAC,CAA4B,CAAC;IAEnH;;;;;;;;;;;;;OAaG;IACI,MAAM,OAAO,GAClB,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,SAAS,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,EAAE,UAAU,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,MAAM,OAAO,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,KAAG,KAAK,CAAC,CAAC,EAAE,CAAC,CAG5F,CAAC;IAEH;;;;;;;;;OASG;IACI,MAAM,IAAI,GAAI,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,KAAK,CAAC,MAAM,OAAO,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,KAAG,CAA0B,CAAC;IAExG;;;;;;;OAOG;IACI,MAAM,IAAI,GAAI,CAAC,EAAE,CAAC,EAAE,OAAO,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,KAAG,KAAK,CAAC,CAAC,EAAE,CAAC,CAAyB,CAAC;IAEpF;;;;;;;OAOG;IACI,MAAM,OAAO,GAAI,CAAC,EAAE,CAAC,EAAE,OAAO,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,KAAG,SAAS,CAAC,CAAC,GAAG,CAAC,CAAC,EAAgB,CAAC;IAEpF;;;;;;;;;;;;OAYG;IACI,MAAM,GAAG,GAAI,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,KAAK,IAAI,MAAM,OAAO,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,KAAG,KAAK,CAAC,CAAC,EAAE,CAAC,CAGrF,CAAC;CACF"}

package/types/src/Core/index.d.ts

@@ -1,18 +1,19 @@
-export * from "./Logged.js";
 export * from "./Deferred.js";
 export * from "./Lens.js";
+export * from "./Logged.js";
 export * from "./Option.js";
-export * from "./Reader.js";
 export * from "./Optional.js";
 export * from "./Predicate.js";
+export * from "./Reader.js";
 export * from "./Refinement.js";
 export * from "./RemoteData.js";
-export * from "./State.js";
 export * from "./Result.js";
+export * from "./State.js";
 export * from "./Task.js";
 export * from "./TaskOption.js";
 export * from "./TaskResult.js";
 export * from "./TaskValidation.js";
 export * from "./These.js";
+export * from "./Tuple.js";
 export * from "./Validation.js";
 //# sourceMappingURL=index.d.ts.map

package/types/src/Core/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/src/Core/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,WAAW,CAAC;AAC1B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,iBAAiB,CAAC;AAChC,cAAc,iBAAiB,CAAC;AAChC,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,iBAAiB,CAAC;AAChC,cAAc,iBAAiB,CAAC;AAChC,cAAc,qBAAqB,CAAC;AACpC,cAAc,YAAY,CAAC;AAC3B,cAAc,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/src/Core/index.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAC;AAC9B,cAAc,WAAW,CAAC;AAC1B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC;AAChC,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC;AAC1B,cAAc,iBAAiB,CAAC;AAChC,cAAc,iBAAiB,CAAC;AAChC,cAAc,qBAAqB,CAAC;AACpC,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,iBAAiB,CAAC"}