onlyfuncs 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kyrylo Tykhanskyi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,139 @@
-# Temporary Holding Version
+<p align="center">
+  <img src="public/logo-transparent.png" alt="OnlyFuncs banner" width="700">
+</p>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# OnlyFuncs
+
+Lightweight and hopefully ready to use library for functional programming in JavaScript. 
+It was written out of curiosity and because someone got really bored with OOP.
+
+
+## Description 
+
+Provides a wide set of functions and types that are quite regular for functional programming. For example map, 
+pipe, compose, result, option, traverse etc. So if you want to give FP a shot, save yourself some time and try 
+the lib. It doesn't bite. Mostly.
+
+Also, it does its best to be readable and supports asynchronous operations.
+
+
+## Installation 
+
+```bash
+npm install onlyfuncs
+```
+
+
+## Quick Start
+
+Import the functions you need from the library module:
+
+```js
+import { pipe } from "onlyfuncs/function";
+import * as Option from "onlyfuncs/option";
+import * as Result from "onlyfuncs/result";
+```
+
+Or directly from the root:
+
+```js
+import { Option, Result } from "onlyfuncs";
+```
+
+Use them in chains:
+
+```js
+const racer = (name) => pipe(
+    Option.fromNullable(name),
+    Option.map((name) => name.trim()),
+    Option.filter((name) => name.length > 0),
+    Option.getOrElse(() => "Luigi")
+);
+
+console.log(racer(" Mario   ")) // Mario
+console.log(racer("   ")) // Luigi
+console.log(racer()) // Luigi
+console.log(racer("Bowser")) // Bowser
+```
+
+Reach out to Result if you want to check why operation failed:
+
+```js
+const racer = (value) => pipe(
+    Result.fromThrowable(() => JSON.parse(value)),
+    Result.mapError((_) => "invalid JSON"),
+    Result.map((user) => user?.name),
+    Result.flatMap((name) => typeof name === "string" && name.trim().length > 0
+        ? Result.ok(name.trim())
+        : Result.err("name is missing")),
+    Result.match({
+        onOk: (name) => `Select: ${name}`,
+        onErr: (err) => `Could not choose a racer: ${err}`
+    })
+);
+
+
+console.log(racer('{"name": "Mario"}')); // Mario
+console.log(racer('{"na": "Luigi"}')); // Name is missing
+console.log(racer('{')); // Invalid JSON
+console.log(racer('{"name": "Bowser", "power": "fireball"}')); // Bowser
+```
+
+Reach out to TaskResult for running async operations that may fail:
+
+```js
+import { pipe } from "onlyfuncs/function";
+import * as TaskResult from "onlyfuncs/task-result";
+
+const lookupItem = async (name) => {
+    const response = await fetch(
+        `https://dummyjson.com/products/search?q=${encodeURIComponent(name)}`,
+    );
+
+    if (!response.ok) {
+        throw new Error(`Request failed: ${response.status}`);
+    }
+
+    return await response.json();
+};
+
+const item = (name) => pipe(
+    TaskResult.fromThrowable(() => lookupItem(name)),
+    TaskResult.mapError((err) => err.message),
+    TaskResult.map((data) => data.products[0]),
+    TaskResult.filterOrElse({
+        predicate: (item) => item !== undefined,
+        onFalse: () => `${name} was not found`,
+    }),
+    TaskResult.map((item) => item.title),
+    TaskResult.match({
+        onOk: (title) => `Gotcha ${title}`,
+        onErr: (err) => `Could not get item: ${err}`,
+    }),
+);
+
+console.log(await item("cup")()); 
+console.log(await item("apple")());
+console.log(await item("moonstone")());
+```
+
+
+## Modules
+
+| Module | Import | Purpose |
+| --- | --- | --- |
+| Function | `onlyfuncs/function` | Compose and transform functions with `pipe`, `flow`, and `compose`|
+| Option | `onlyfuncs/option` | Represent optional values and handle missing data|
+| Result | `onlyfuncs/result` | Represent success or failure and recover from errors|
+| Predicate | `onlyfuncs/predicate` | Combine and adapt boolean checks |
+| ReadonlyArray | `onlyfuncs/readonly-array` | Find, group, and transform array values |
+| Task | `onlyfuncs/task` | Define lazy asynchronous computations |
+| TaskResult | `onlyfuncs/task-result` | Combine asynchronous computations with success and failure handling |
+| Semigroup | `onlyfuncs/semigroup` | Combine values, such as strings, arrays, and records |
+| Monoid | `onlyfuncs/monoid` | Combine values with an identity |
+| Validation | `onlyfuncs/validation` | Accumulate errors from independent checks |
+
+
+## License
+
+MIT © 2026 Kyrylo Tykhanskyi. See [LICENSE](LICENSE).

package/package.json

@@ -1,6 +1,31 @@
 {
   "name": "onlyfuncs",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "description": "Lightweight library for functional programming",
+  "version": "0.1.0",
+  "license": "MIT",
+  "type": "module",
+  "repository": "https://github.com/devkyt/onlyfuncs",
+  "scripts": {
+    "test": "node --test"
+  },
+  "files": [
+    "src/index.js",
+    "src/*/index.js"
+  ],
+  "exports": {
+    ".": "./src/index.js",
+    "./function": "./src/function/index.js",
+    "./option": "./src/option/index.js",
+    "./result": "./src/result/index.js",
+    "./predicate": "./src/predicate/index.js",
+    "./readonly-array": "./src/readonly-array/index.js",
+    "./task": "./src/task/index.js",
+    "./task-result": "./src/task-result/index.js",
+    "./semigroup": "./src/semigroup/index.js",
+    "./monoid": "./src/monoid/index.js",
+    "./validation": "./src/validation/index.js"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/"
+  }
+}

package/src/function/index.js

@@ -0,0 +1,109 @@
+/**
+ * Returns the input unchanged, preserving object references.
+ *
+ * @template A
+ * @param {A} value - The value to return.
+ * @returns {A} The original value.
+ * @example
+ * identity("Link"); // "Link"
+ */
+export const identity = (value) => value;
+
+
+/**
+ * Creates a function that returns the same captured value on every call.
+ * Object references are preserved.
+ *
+ * @template A
+ * @param {A} value - The value to capture.
+ * @returns {() => A} The constant function.
+ * @example
+ * const hero = constant("Link");
+ * hero(); // "Link"
+ */
+export const constant = (value) => () => value;
+
+
+/**
+ * Immediately passes a value through steps from left to right.
+ * Each step receives only the previous result. With no steps, returns the input.
+ * Promises are passed along without awaiting. A throw stops the remaining steps.
+ *
+ * @param {any} value - The input passed to the first step.
+ * @param {...((value: any) => any)} functions - Steps to apply in order.
+ * @returns {any} The final value, or the input if no steps are given.
+ * @throws {TypeError} When a non-function step is reached.
+ * @example
+ * pipe(3, n => n + 1, n => n * 2); // 8
+ */
+export const pipe = (value, ...functions) => {
+    const apply = (value, fn) => {
+        if (typeof fn !=='function') {
+            throw new TypeError('pipe: expected all arguments to be functions');
+        }
+
+        return fn(value)
+    }
+
+    return functions.reduce((acc, fn) => apply(acc, fn), value);
+}
+
+/**
+ * Creates a function that passes its input through steps from left to right.
+ * Each step receives only the previous result. With no steps, returns the input.
+ * Promises are passed along without awaiting. A throw stops the remaining steps.
+ *
+ * @param {...((value: any) => any)} functions - Steps to apply in order.
+ * @returns {(value: any) => any} The composed function.
+ * @throws {TypeError} When the returned function reaches a non-function step.
+ * @example
+ * const calculate = flow(n => n + 1, n => n * 2);
+ * calculate(3); // 8
+ */
+export const flow = (...functions) => (value) => pipe(value, ...functions);
+
+
+/**
+ * Creates a function that passes its input through steps from right to left.
+ * Each step receives only the previous result. With no steps, returns the input.
+ * Promises are passed along without awaiting. A throw stops the remaining steps.
+ *
+ * @param {...((value: any) => any)} functions - Steps to apply in reverse order.
+ * @returns {(value: any) => any} The composed function.
+ * @throws {TypeError} When the returned function reaches a non-function step.
+ * @example
+ * const calculate = compose(n => n * 2, n => n + 1);
+ * calculate(3); // 8
+ */
+export const compose = (...functions) => flow(...functions.reverse());
+
+
+/**
+ * Converts a two-argument function into two successive one-argument calls.
+ * Calls fn after receiving the second argument, preserving argument order.
+ * Exceptions from fn propagate.
+ *
+ * @template A, B, R
+ * @param {(first: A, second: B) => R} fn - The two-argument function.
+ * @returns {(first: A) => (second: B) => R} The curried function.
+ * @example
+ * const subtract = curry2((a, b) => a - b);
+ * subtract(10)(3); // 7
+ */
+export const curry2 = (fn) => (x) => (y) => fn(x, y);
+
+
+/**
+ * Converts a three-argument function into three successive one-argument calls.
+ * Calls fn after receiving the third argument, preserving argument order.
+ * Exceptions from fn propagate.
+ *
+ * @template A, B, C, R
+ * @param {(first: A, second: B, third: C) => R} fn - The three-argument function.
+ * @returns {(first: A) => (second: B) => (third: C) => R} The curried function.
+ * @example
+ * const cast = curry3((caster, spell, target) => `${caster}: ${spell} on ${target}`);
+ * cast("Rauru")("Blizzard")("Goblin"); // "Rauru: Blizzard on Goblin"
+ */
+export const curry3 = (fn) => (x) => (y) => (z) => fn(x, y, z);
+

package/src/index.js

@@ -0,0 +1,10 @@
+export * as Function from "./function/index.js";
+export * as Option from "./option/index.js";
+export * as Result from "./result/index.js";
+export * as Predicate from "./predicate/index.js";
+export * as ReadonlyArray from "./readonly-array/index.js";
+export * as Task from "./task/index.js";
+export * as TaskResult from "./task-result/index.js";
+export * as Semigroup from "./semigroup/index.js";
+export * as Monoid from "./monoid/index.js";
+export * as Validation from "./validation/index.js";

package/src/monoid/index.js

@@ -0,0 +1,121 @@
+import * as Semigroup from "../semigroup/index.js"
+
+/**
+ * An associative combination operation with an identity value.
+ * Combining a value with the identity on either side should preserve that value.
+ * Custom combiners should preserve inputs, and empty() should create a fresh identity
+ * when it is mutable. JavaScript number rounding can limit numeric associativity.
+ *
+ * @template A
+ * @typedef {Object} Monoid
+ * @property {(left: A, right: A) => A} combine - Combines the left and right values in that order.
+ * @property {() => A} empty - Supplies the identity for the combination operation.
+ */
+
+/**
+ * Combines numbers by addition, with zero as the identity.
+ * Uses JavaScript number arithmetic.
+ *
+ * @type {Monoid<number>}
+ * @example
+ * sum.combine(sum.empty(), 3); // 3
+ */
+export const sum = {
+    combine: Semigroup.sum.combine,
+    empty: () => 0,
+};
+
+
+/**
+ * Combines numbers by multiplication, with one as the identity.
+ * Uses JavaScript number arithmetic.
+ *
+ * @type {Monoid<number>}
+ * @example
+ * product.combine(product.empty(), 3); // 3
+ */
+export const product = {
+    combine: Semigroup.product.combine,
+    empty: () => 1,
+};
+
+
+/**
+ * Concatenates strings in left-to-right order, with the empty string as the identity.
+ *
+ * @type {Monoid<string>}
+ * @example
+ * string.combine(string.empty(), "Link"); // "Link"
+ */
+export const string = {
+    combine: Semigroup.string.combine,
+    empty: () => "",
+};
+
+
+/**
+ * Concatenates arrays without changing them; empty() creates a new empty array.
+ * Each combination creates a new array, preserving the elements' references.
+ *
+ * @type {{
+ *   combine: <A, B>(left: ReadonlyArray<A>, right: ReadonlyArray<B>) => (A | B)[],
+ *   empty: <A>() => A[]
+ * }}
+ * @example
+ * array.combine(array.empty(), ["Link"]); // ["Link"]
+ * array.empty() === array.empty(); // false
+ */
+export const array = {
+    combine: Semigroup.array.combine,
+    empty: () => [],
+};
+
+
+/**
+ * Creates a monoid that combines matching fields into a new object.
+ * Captures the schema's own enumerable string keys and monoid references at creation.
+ * Ignores extra input fields. Each empty() call creates a new object and calls each
+ * field's empty() once; field monoids control freshness of their values.
+ * Field operations run in schema order; exceptions propagate.
+ *
+ * @template {Record<string, any>} A
+ * @param {{[K in keyof A]: Monoid<A[K]>}} fields - A monoid for each field to combine.
+ * @returns {Monoid<A>} The record monoid.
+ * @example
+ * const stats = struct({ health: sum, inventory: array });
+ * stats.empty(); // { health: 0, inventory: [] }
+ * stats.combine(stats.empty(), { health: 3, inventory: ["Bow"] });
+ * // { health: 3, inventory: ["Bow"] }
+ */
+export const struct = (fields) => {
+    const entries = Object.entries(fields);
+
+    return {
+        combine: Semigroup.struct(fields).combine,
+        empty: () => Object.fromEntries(
+            entries.map(([key, monoid]) => [
+                key,
+                monoid.empty()
+            ])
+        ),
+    };
+};
+
+
+/**
+ * Combines a finite iterable left to right, starting from the monoid's identity.
+ * Calls empty() once when values are supplied, including for empty input.
+ * Iteration, empty(), and combiner exceptions propagate.
+ *
+ * @template A
+ * @param {Monoid<A>} monoid - Supplies the identity and combines the accumulator with each element.
+ * @returns {(values: Iterable<A>) => A} A function combining a finite iterable.
+ * @example
+ * combineAll(sum)([2, 3, 4]); // 9
+ * combineAll(sum)([]); // 0
+ */
+export const combineAll = (monoid) => (values) =>
+    Semigroup.combineMany({ semigroup: monoid, initial: monoid.empty() })(values);
+
+
+