@nlozgachev/pipekit 0.1.6 → 0.1.7

package/esm/src/Core/These.js

@@ -0,0 +1,242 @@
+import { Result } from "./Result.js";
+export var These;
+(function (These) {
+    /**
+     * Creates a These holding only an error/warning (no success value).
+     *
+     * @example
+     * ```ts
+     * These.toErr("Something went wrong");
+     * ```
+     */
+    These.toErr = (error) => Result.toErr(error);
+    /**
+     * Creates a These holding only a success value (no error).
+     *
+     * @example
+     * ```ts
+     * These.toOk(42);
+     * ```
+     */
+    These.toOk = (value) => Result.toOk(value);
+    /**
+     * Creates a These holding both an error/warning and a success value.
+     *
+     * @example
+     * ```ts
+     * These.toBoth("Deprecated API used", result);
+     * ```
+     */
+    These.toBoth = (error, value) => ({
+        kind: "Both",
+        error,
+        value,
+    });
+    /**
+     * Type guard — checks if a These holds only an error/warning.
+     */
+    These.isErr = (data) => data.kind === "Error";
+    /**
+     * Type guard — checks if a These holds only a success value.
+     */
+    These.isOk = (data) => data.kind === "Ok";
+    /**
+     * Type guard — checks if a These holds both an error/warning and a success value.
+     */
+    These.isBoth = (data) => data.kind === "Both";
+    /**
+     * Returns true if the These contains a success value (Ok or Both).
+     */
+    These.hasValue = (data) => data.kind === "Ok" || data.kind === "Both";
+    /**
+     * Returns true if the These contains an error/warning (Err or Both).
+     */
+    These.hasError = (data) => data.kind === "Error" || data.kind === "Both";
+    /**
+     * Transforms the success value, leaving the error unchanged.
+     *
+     * @example
+     * ```ts
+     * pipe(These.toOk(5), These.map(n => n * 2));          // Ok(10)
+     * pipe(These.toBoth("warn", 5), These.map(n => n * 2)); // Both("warn", 10)
+     * pipe(These.toErr("err"), These.map(n => n * 2));      // Err("err")
+     * ```
+     */
+    These.map = (f) => (data) => {
+        if (These.isErr(data))
+            return data;
+        if (These.isOk(data))
+            return These.toOk(f(data.value));
+        return These.toBoth(data.error, f(data.value));
+    };
+    /**
+     * Transforms the error/warning value, leaving the success value unchanged.
+     *
+     * @example
+     * ```ts
+     * pipe(These.toErr("err"), These.mapErr(e => e.toUpperCase()));         // Err("ERR")
+     * pipe(These.toBoth("warn", 5), These.mapErr(e => e.toUpperCase()));    // Both("WARN", 5)
+     * ```
+     */
+    These.mapErr = (f) => (data) => {
+        if (These.isOk(data))
+            return data;
+        if (These.isErr(data))
+            return These.toErr(f(data.error));
+        return These.toBoth(f(data.error), data.value);
+    };
+    /**
+     * Transforms both the error and success values independently.
+     *
+     * @example
+     * ```ts
+     * pipe(
+     *   These.toBoth("warn", 5),
+     *   These.bimap(e => e.toUpperCase(), n => n * 2)
+     * ); // Both("WARN", 10)
+     * ```
+     */
+    These.bimap = (onErr, onOk) => (data) => {
+        if (These.isErr(data))
+            return These.toErr(onErr(data.error));
+        if (These.isOk(data))
+            return These.toOk(onOk(data.value));
+        return These.toBoth(onErr(data.error), onOk(data.value));
+    };
+    /**
+     * Chains These computations by passing the success value to f.
+     * - Err propagates unchanged.
+     * - Ok(a) applies f(a) directly.
+     * - Both(e, a): applies f(a); if the result is Ok(b), returns Both(e, b)
+     *   to preserve the warning. Otherwise returns f(a) as-is.
+     *
+     * @example
+     * ```ts
+     * const double = (n: number): These<string, number> => These.toOk(n * 2);
+     *
+     * pipe(These.toOk(5), These.chain(double));           // Ok(10)
+     * pipe(These.toBoth("warn", 5), These.chain(double)); // Both("warn", 10)
+     * pipe(These.toErr("err"), These.chain(double));      // Err("err")
+     * ```
+     */
+    These.chain = (f) => (data) => {
+        if (These.isErr(data))
+            return data;
+        if (These.isOk(data))
+            return f(data.value);
+        const result = f(data.value);
+        return These.isOk(result) ? These.toBoth(data.error, result.value) : result;
+    };
+    /**
+     * Extracts a value from a These by providing handlers for all three cases.
+     *
+     * @example
+     * ```ts
+     * pipe(
+     *   these,
+     *   These.fold(
+     *     e => `Error: ${e}`,
+     *     a => `Value: ${a}`,
+     *     (e, a) => `Both: ${e} / ${a}`
+     *   )
+     * );
+     * ```
+     */
+    These.fold = (onErr, onOk, onBoth) => (data) => {
+        if (These.isErr(data))
+            return onErr(data.error);
+        if (These.isOk(data))
+            return onOk(data.value);
+        return onBoth(data.error, data.value);
+    };
+    /**
+     * Pattern matches on a These, returning the result of the matching case.
+     *
+     * @example
+     * ```ts
+     * pipe(
+     *   these,
+     *   These.match({
+     *     err: e => `Error: ${e}`,
+     *     ok: a => `Value: ${a}`,
+     *     both: (e, a) => `Both: ${e} / ${a}`
+     *   })
+     * );
+     * ```
+     */
+    These.match = (cases) => (data) => {
+        if (These.isErr(data))
+            return cases.err(data.error);
+        if (These.isOk(data))
+            return cases.ok(data.value);
+        return cases.both(data.error, data.value);
+    };
+    /**
+     * Returns the success value, or a default if the These has no success value.
+     *
+     * @example
+     * ```ts
+     * pipe(These.toOk(5), These.getOrElse(0));           // 5
+     * pipe(These.toBoth("warn", 5), These.getOrElse(0)); // 5
+     * pipe(These.toErr("err"), These.getOrElse(0));      // 0
+     * ```
+     */
+    These.getOrElse = (defaultValue) => (data) => These.hasValue(data) ? data.value : defaultValue;
+    /**
+     * Executes a side effect on the success value without changing the These.
+     * Useful for logging or debugging.
+     */
+    These.tap = (f) => (data) => {
+        if (These.hasValue(data))
+            f(data.value);
+        return data;
+    };
+    /**
+     * Swaps the roles of error and success values.
+     * - Err(e)      → Ok(e)
+     * - Ok(a)       → Err(a)
+     * - Both(e, a)  → Both(a, e)
+     *
+     * @example
+     * ```ts
+     * These.swap(These.toErr("err"));        // Ok("err")
+     * These.swap(These.toOk(5));             // Err(5)
+     * These.swap(These.toBoth("warn", 5));   // Both(5, "warn")
+     * ```
+     */
+    These.swap = (data) => {
+        if (These.isErr(data))
+            return These.toOk(data.error);
+        if (These.isOk(data))
+            return These.toErr(data.value);
+        return These.toBoth(data.value, data.error);
+    };
+    /**
+     * Converts a These to an Option.
+     * Ok and Both produce Some; Err produces None.
+     *
+     * @example
+     * ```ts
+     * These.toOption(These.toOk(42));          // Some(42)
+     * These.toOption(These.toBoth("warn", 42)); // Some(42)
+     * These.toOption(These.toErr("err"));       // None
+     * ```
+     */
+    These.toOption = (data) => These.hasValue(data) ? { kind: "Some", value: data.value } : { kind: "None" };
+    /**
+     * Converts a These to a Result, discarding any warning from Both.
+     * Ok and Both produce Ok; Err produces Err.
+     *
+     * @example
+     * ```ts
+     * These.toResult(These.toOk(42));           // Ok(42)
+     * These.toResult(These.toBoth("warn", 42)); // Ok(42)
+     * These.toResult(These.toErr("err"));       // Err("err")
+     * ```
+     */
+    These.toResult = (data) => {
+        if (These.hasValue(data))
+            return Result.toOk(data.value);
+        return data;
+    };
+})(These || (These = {}));

package/esm/src/Core/index.js

@@ -4,5 +4,8 @@ export * from "./Rec.js";
 export * from "./RemoteData.js";
 export * from "./Result.js";
 export * from "./Task.js";
+export * from "./TaskOption.js";
 export * from "./TaskResult.js";
+export * from "./TaskValidation.js";
+export * from "./These.js";
 export * from "./Validation.js";

package/esm/src/Types/Brand.js

@@ -0,0 +1,28 @@
+export var Brand;
+(function (Brand) {
+    /**
+     * Creates a branding constructor for brand K over type T.
+     * The resulting function performs an unchecked cast — only use when the raw
+     * value is known to satisfy the brand's invariants.
+     *
+     * @example
+     * ```ts
+     * type PositiveNumber = Brand<"PositiveNumber", number>;
+     * const toPositiveNumber = Brand.make<"PositiveNumber", number>();
+     *
+     * const n: PositiveNumber = toPositiveNumber(42);
+     * ```
+     */
+    Brand.make = () => (value) => value;
+    /**
+     * Strips the brand and returns the underlying value.
+     * Since Brand<K, T> extends T this is rarely needed, but can improve readability.
+     *
+     * @example
+     * ```ts
+     * const userId: UserId = toUserId("user-123");
+     * const raw: string = Brand.unwrap(userId); // "user-123"
+     * ```
+     */
+    Brand.unwrap = (branded) => branded;
+})(Brand || (Brand = {}));

package/esm/src/Types/index.js

@@ -1 +1,2 @@
+export * from "./Brand.js";
 export * from "./NonEmptyList.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nlozgachev/pipekit",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "description": "Simple functional programming toolkit for TypeScript",
   "keywords": [
     "functional",

package/script/src/Core/TaskOption.js

@@ -0,0 +1,102 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TaskOption = void 0;
+const Option_js_1 = require("./Option.js");
+const Task_js_1 = require("./Task.js");
+var TaskOption;
+(function (TaskOption) {
+    /**
+     * Wraps a value in a Some inside a Task.
+     */
+    TaskOption.of = (value) => Task_js_1.Task.of(Option_js_1.Option.of(value));
+    /**
+     * Creates a TaskOption that resolves to None.
+     */
+    TaskOption.none = () => Task_js_1.Task.of(Option_js_1.Option.toNone());
+    /**
+     * Lifts an Option into a TaskOption.
+     */
+    TaskOption.fromOption = (option) => Task_js_1.Task.of(option);
+    /**
+     * Lifts a Task into a TaskOption by wrapping its result in Some.
+     */
+    TaskOption.fromTask = (task) => Task_js_1.Task.map(Option_js_1.Option.of)(task);
+    /**
+     * Creates a TaskOption from a Promise-returning function.
+     * Returns Some if the promise resolves, None if it rejects.
+     *
+     * @example
+     * ```ts
+     * const fetchUser = TaskOption.tryCatch(() =>
+     *   fetch("/user/1").then(r => r.json())
+     * );
+     * ```
+     */
+    TaskOption.tryCatch = (f) => () => f().then(Option_js_1.Option.of).catch(() => Option_js_1.Option.toNone());
+    /**
+     * Transforms the value inside a TaskOption.
+     */
+    TaskOption.map = (f) => (data) => Task_js_1.Task.map(Option_js_1.Option.map(f))(data);
+    /**
+     * Chains TaskOption computations. If the first resolves to Some, passes the
+     * value to f. If the first resolves to None, propagates None.
+     *
+     * @example
+     * ```ts
+     * pipe(
+     *   findUser("123"),
+     *   TaskOption.chain(user => findOrg(user.orgId))
+     * )();
+     * ```
+     */
+    TaskOption.chain = (f) => (data) => Task_js_1.Task.chain((option) => Option_js_1.Option.isSome(option) ? f(option.value) : Task_js_1.Task.of(Option_js_1.Option.toNone()))(data);
+    /**
+     * Applies a function wrapped in a TaskOption to a value wrapped in a TaskOption.
+     * Both Tasks run in parallel.
+     */
+    TaskOption.ap = (arg) => (data) => () => Promise.all([data(), arg()]).then(([of_, oa]) => Option_js_1.Option.ap(oa)(of_));
+    /**
+     * Extracts a value from a TaskOption by providing handlers for both cases.
+     */
+    TaskOption.fold = (onNone, onSome) => (data) => Task_js_1.Task.map(Option_js_1.Option.fold(onNone, onSome))(data);
+    /**
+     * Pattern matches on a TaskOption, returning a Task of the result.
+     *
+     * @example
+     * ```ts
+     * pipe(
+     *   findUser("123"),
+     *   TaskOption.match({
+     *     some: user => `Hello, ${user.name}`,
+     *     none: () => "User not found"
+     *   })
+     * )();
+     * ```
+     */
+    TaskOption.match = (cases) => (data) => Task_js_1.Task.map(Option_js_1.Option.match(cases))(data);
+    /**
+     * Returns the value or a default if the TaskOption resolves to None.
+     */
+    TaskOption.getOrElse = (defaultValue) => (data) => Task_js_1.Task.map(Option_js_1.Option.getOrElse(defaultValue))(data);
+    /**
+     * Executes a side effect on the value without changing the TaskOption.
+     * Useful for logging or debugging.
+     */
+    TaskOption.tap = (f) => (data) => Task_js_1.Task.map(Option_js_1.Option.tap(f))(data);
+    /**
+     * Filters the value inside a TaskOption. Returns None if the predicate fails.
+     */
+    TaskOption.filter = (predicate) => (data) => Task_js_1.Task.map(Option_js_1.Option.filter(predicate))(data);
+    /**
+     * Converts a TaskOption to a TaskResult, using onNone to produce the error value.
+     *
+     * @example
+     * ```ts
+     * pipe(
+     *   findUser("123"),
+     *   TaskOption.toTaskResult(() => "User not found")
+     * );
+     * ```
+     */
+    TaskOption.toTaskResult = (onNone) => (data) => Task_js_1.Task.map(Option_js_1.Option.toResult(onNone))(data);
+})(TaskOption || (exports.TaskOption = TaskOption = {}));

package/script/src/Core/TaskValidation.js

@@ -0,0 +1,96 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TaskValidation = void 0;
+const Task_js_1 = require("./Task.js");
+const Validation_js_1 = require("./Validation.js");
+var TaskValidation;
+(function (TaskValidation) {
+    /**
+     * Wraps a value in a valid TaskValidation.
+     */
+    TaskValidation.of = (value) => Task_js_1.Task.of(Validation_js_1.Validation.of(value));
+    /**
+     * Creates a failed TaskValidation with a single error.
+     */
+    TaskValidation.fail = (error) => Task_js_1.Task.of(Validation_js_1.Validation.fail(error));
+    /**
+     * Lifts a Validation into a TaskValidation.
+     */
+    TaskValidation.fromValidation = (validation) => Task_js_1.Task.of(validation);
+    /**
+     * Creates a TaskValidation from a Promise-returning function.
+     * Catches any errors and transforms them using the onError function.
+     *
+     * @example
+     * ```ts
+     * const fetchUser = (id: string): TaskValidation<string, User> =>
+     *   TaskValidation.tryCatch(
+     *     () => fetch(`/users/${id}`).then(r => r.json()),
+     *     e => `Failed to fetch user: ${e}`
+     *   );
+     * ```
+     */
+    TaskValidation.tryCatch = (f, onError) => () => f()
+        .then((Validation_js_1.Validation.of))
+        .catch((e) => Validation_js_1.Validation.fail(onError(e)));
+    /**
+     * Transforms the success value inside a TaskValidation.
+     */
+    TaskValidation.map = (f) => (data) => Task_js_1.Task.map(Validation_js_1.Validation.map(f))(data);
+    /**
+     * Chains TaskValidation computations. If the first is Valid, passes the value
+     * to f. If the first is Invalid, propagates the errors.
+     *
+     * Note: chain short-circuits on first error. Use ap to accumulate errors.
+     */
+    TaskValidation.chain = (f) => (data) => Task_js_1.Task.chain((validation) => Validation_js_1.Validation.isValid(validation)
+        ? f(validation.value)
+        : Task_js_1.Task.of(Validation_js_1.Validation.toInvalid(validation.errors)))(data);
+    /**
+     * Applies a function wrapped in a TaskValidation to a value wrapped in a
+     * TaskValidation. Both Tasks run in parallel and errors from both sides
+     * are accumulated.
+     *
+     * @example
+     * ```ts
+     * pipe(
+     *   TaskValidation.of((name: string) => (age: number) => ({ name, age })),
+     *   TaskValidation.ap(validateName(name)),
+     *   TaskValidation.ap(validateAge(age))
+     * )();
+     * ```
+     */
+    TaskValidation.ap = (arg) => (data) => () => Promise.all([data(), arg()]).then(([vf, va]) => Validation_js_1.Validation.ap(va)(vf));
+    /**
+     * Extracts a value from a TaskValidation by providing handlers for both cases.
+     */
+    TaskValidation.fold = (onInvalid, onValid) => (data) => Task_js_1.Task.map(Validation_js_1.Validation.fold(onInvalid, onValid))(data);
+    /**
+     * Pattern matches on a TaskValidation, returning a Task of the result.
+     *
+     * @example
+     * ```ts
+     * pipe(
+     *   validateForm(input),
+     *   TaskValidation.match({
+     *     valid: data => save(data),
+     *     invalid: errors => showErrors(errors)
+     *   })
+     * )();
+     * ```
+     */
+    TaskValidation.match = (cases) => (data) => Task_js_1.Task.map(Validation_js_1.Validation.match(cases))(data);
+    /**
+     * Returns the success value or a default value if the TaskValidation is invalid.
+     */
+    TaskValidation.getOrElse = (defaultValue) => (data) => Task_js_1.Task.map(Validation_js_1.Validation.getOrElse(defaultValue))(data);
+    /**
+     * Executes a side effect on the success value without changing the TaskValidation.
+     * Useful for logging or debugging.
+     */
+    TaskValidation.tap = (f) => (data) => Task_js_1.Task.map(Validation_js_1.Validation.tap(f))(data);
+    /**
+     * Recovers from an Invalid state by providing a fallback TaskValidation.
+     */
+    TaskValidation.recover = (fallback) => (data) => Task_js_1.Task.chain((validation) => Validation_js_1.Validation.isValid(validation) ? Task_js_1.Task.of(validation) : fallback())(data);
+})(TaskValidation || (exports.TaskValidation = TaskValidation = {}));