@elyukai/utils 0.2.1 → 0.2.4

package/CHANGELOG.md

@@ -2,6 +2,25 @@
 
 All notable changes to this project will be documented in this file. See [commit-and-tag-version](https://github.com/absolute-version/commit-and-tag-version) for commit guidelines.
 
+## [0.2.4](https://github.com/elyukai/ts-utils/compare/v0.2.3...v0.2.4) (2026-02-20)
+
+## [0.2.3](https://github.com/elyukai/ts-utils/compare/v0.2.2...v0.2.3) (2026-02-20)
+
+
+### Features
+
+* add basic reader monad ([1b25fb2](https://github.com/elyukai/ts-utils/commit/1b25fb2d948cb02d0d122eeefdc512fd4b781b4a))
+* add identity function ([1f5836c](https://github.com/elyukai/ts-utils/commit/1f5836cf015a554ba0cf1140467fe3bc1e44df05))
+* add more reader methods ([00408ed](https://github.com/elyukai/ts-utils/commit/00408edcbfa6b18fb20eede78c5f19efbe07fcd1))
+
+## [0.2.2](https://github.com/elyukai/ts-utils/compare/v0.2.1...v0.2.2) (2026-02-11)
+
+
+### Features
+
+* add FixedArray helper ([4a1b61a](https://github.com/elyukai/ts-utils/commit/4a1b61a51ad53c35767adf716d4a64ef10f4dc10))
+* add static groupBy method to dictionary ([2ee4802](https://github.com/elyukai/ts-utils/commit/2ee4802db8f1b821819f4ced5f79079153a6c11e))
+
 ## [0.2.1](https://github.com/elyukai/ts-utils/compare/v0.2.0...v0.2.1) (2026-02-07)
 
 

package/dist/array/fixed.d.ts

@@ -0,0 +1,13 @@
+/**
+ * A helper type that builds a tuple type of a desired length.
+ * @module
+ */
+/**
+ * A recursive type that constructs an array of type `T` with a length of `N`.
+ */
+type FixedArrayAux<T, N extends number, A extends T[]> = A["length"] extends N ? A : FixedArrayAux<T, N, [...A, T]>;
+/**
+ * A type representing an array of a fixed size `N` containing elements of type `T`.
+ */
+export type FixedArray<T, N extends number> = FixedArrayAux<T, N, []>;
+export {};

package/dist/array/fixed.js

@@ -0,0 +1,5 @@
+/**
+ * A helper type that builds a tuple type of a desired length.
+ * @module
+ */
+export {};

package/dist/dictionary.d.ts

@@ -21,6 +21,10 @@ export declare class Dictionary<T extends AnyNonNullish | null, K extends string
      * Constructs a dictionary from an array of key-value pairs.
      */
     static fromEntries<T extends AnyNonNullish | null, K extends string = string>(entries: [K, T][]): Dictionary<T, K>;
+    /**
+     * Groups the given items by the key returned by the given function and returns a dictionary mapping each key to an array of items with that key.
+     */
+    static groupBy<T, K extends string>(items: T[], keyFn: (item: T) => K): Dictionary<T[], K>;
     /**
      * Returns the value associated with the given key, or `undefined` if the key does not exist.
      */

package/dist/dictionary.js

@@ -25,6 +25,22 @@ export class Dictionary {
     static fromEntries(entries) {
         return new Dictionary(Object.fromEntries(entries));
     }
+    /**
+     * Groups the given items by the key returned by the given function and returns a dictionary mapping each key to an array of items with that key.
+     */
+    static groupBy(items, keyFn) {
+        const record = {};
+        for (const item of items) {
+            const key = keyFn(item);
+            if (record[key] === undefined) {
+                record[key] = [item];
+            }
+            else {
+                record[key].push(item);
+            }
+        }
+        return new Dictionary(record);
+    }
     /**
      * Returns the value associated with the given key, or `undefined` if the key does not exist.
      */

package/dist/function.d.ts

@@ -2,6 +2,10 @@
  * Utility functions for combining functions.
  * @module
  */
+/**
+ * Returns the input value unchanged.
+ */
+export declare const identity: <T>(value: T) => T;
 /**
  * Returns a function that always returns the given value.
  * @param value The value to return from the new function.

package/dist/function.js

@@ -2,6 +2,10 @@
  * Utility functions for combining functions.
  * @module
  */
+/**
+ * Returns the input value unchanged.
+ */
+export const identity = (value) => value;
 /**
  * Returns a function that always returns the given value.
  * @param value The value to return from the new function.

package/dist/reader.d.ts

@@ -0,0 +1,69 @@
+/**
+ * A simple implementation of the Reader monad, which allows you to write functions that depend on some shared environment.
+ * @module
+ */
+/**
+ * The Reader monad represents a computation that depends on some shared environment. It allows you to write functions that can access this environment without having to pass it explicitly as an argument.
+ * @template T The type of the value produced by the Reader.
+ * @template R The type of the environment that the Reader depends on.
+ */
+export declare class Reader<in R, out T> {
+    #private;
+    private constructor();
+    /**
+     * Always produce the given value, regardless of the environment.
+     */
+    static of<R = unknown, T = never>(value: T): Reader<R, T>;
+    /**
+     * Retrieve the entire environment.
+     */
+    static ask<R>(): Reader<R, R>;
+    /**
+     * Retrieve a transformed value of the environment.
+     */
+    static asks<R, T>(f: (env: R) => T): Reader<R, T>;
+    /**
+     * Applies the given function to the value produced by this Reader and returns a new Reader that produces the result.
+     */
+    map<U>(f: (value: T) => U): Reader<R, U>;
+    /**
+     * Combines this Reader with another Reader by applying a function to both of their results and returning a new Reader that produces the result.
+     */
+    map2<U, V>(other: Reader<R, U>, f: (first: T, second: U) => V): Reader<R, V>;
+    /**
+     * Applies the given function to the value produced by this Reader and returns a new Reader that produces the result. The function must return a Reader, which allows you to chain computations that depend on the same environment.
+     */
+    then<U>(f: (value: T) => Reader<R, U>): Reader<R, U>;
+    /**
+     * Applies the given function to the value produced by this Reader and returns a new Reader that produces the result. The function must return a Reader, which allows you to chain computations that depend on a shared environment. The environments do not have to be the same, but will need to be combined.
+     *
+     * The suffix ‘W’ stands for ‘widening’, as this method allows you to widen the environment that the Reader depends on.
+     */
+    thenW<U, S>(f: (value: T) => Reader<S, U>): Reader<R & S, U>;
+    /**
+     * Modifies the environment for this Reader by applying the given function to it before running the computation.
+     *
+     * This allows you to adapt the environment for a specific computation without changing the original Reader.
+     */
+    with<S>(modifyEnv: (env: S) => R): Reader<S, T>;
+    /**
+     * Computes the result by providing the required environment.
+     */
+    run(env: R): T;
+    /**
+     * Evaluate each reader in the array, and collect the results in a single reader instance.
+     */
+    static sequence<R, T>(readers: Reader<R, T>[]): Reader<R, T[]>;
+    /**
+     * Transforms a function that returns a Reader into a Reader that produces a function.
+     *
+     * This makes functions producing Readers that depend on more arguments sometimes easier to work with.
+     */
+    static defer<Args extends unknown[], R, T>(fn: (...args: Args) => Reader<R, T>): Reader<R, (...args: Args) => T>;
+    /**
+     * Transforms a Reader that produces a function into a function that returns a Reader.
+     *
+     * This is the inverse of {@link defer}.
+     */
+    static undefer<Args extends unknown[], R, T>(reader: Reader<R, (...args: Args) => T>): (...args: Args) => Reader<R, T>;
+}

package/dist/reader.js

@@ -0,0 +1,100 @@
+/**
+ * A simple implementation of the Reader monad, which allows you to write functions that depend on some shared environment.
+ * @module
+ */
+// A simpler wrapper for working with text that is generated based on different contexts, which encapsulates the context and reduces main code clutter. The context is only applied in the end.
+/**
+ * The Reader monad represents a computation that depends on some shared environment. It allows you to write functions that can access this environment without having to pass it explicitly as an argument.
+ * @template T The type of the value produced by the Reader.
+ * @template R The type of the environment that the Reader depends on.
+ */
+export class Reader {
+    #fn;
+    constructor(fn) {
+        this.#fn = fn;
+    }
+    /**
+     * Always produce the given value, regardless of the environment.
+     */
+    static of(value) {
+        return new Reader(() => value);
+    }
+    /**
+     * Retrieve the entire environment.
+     */
+    static ask() {
+        return new Reader((env) => env);
+    }
+    /**
+     * Retrieve a transformed value of the environment.
+     */
+    static asks(f) {
+        return new Reader((env) => f(env));
+    }
+    /**
+     * Applies the given function to the value produced by this Reader and returns a new Reader that produces the result.
+     */
+    map(f) {
+        return new Reader((env) => f(this.#fn(env)));
+    }
+    /**
+     * Combines this Reader with another Reader by applying a function to both of their results and returning a new Reader that produces the result.
+     */
+    map2(other, f) {
+        return new Reader((env) => f(this.#fn(env), other.#fn(env)));
+    }
+    /**
+     * Applies the given function to the value produced by this Reader and returns a new Reader that produces the result. The function must return a Reader, which allows you to chain computations that depend on the same environment.
+     */
+    then(f) {
+        return new Reader((env) => f(this.#fn(env)).#fn(env));
+    }
+    /**
+     * Applies the given function to the value produced by this Reader and returns a new Reader that produces the result. The function must return a Reader, which allows you to chain computations that depend on a shared environment. The environments do not have to be the same, but will need to be combined.
+     *
+     * The suffix ‘W’ stands for ‘widening’, as this method allows you to widen the environment that the Reader depends on.
+     */
+    thenW(f) {
+        return new Reader((env) => f(this.#fn(env)).#fn(env));
+    }
+    /**
+     * Modifies the environment for this Reader by applying the given function to it before running the computation.
+     *
+     * This allows you to adapt the environment for a specific computation without changing the original Reader.
+     */
+    with(modifyEnv) {
+        return new Reader((env) => this.#fn(modifyEnv(env)));
+    }
+    /**
+     * Computes the result by providing the required environment.
+     */
+    run(env) {
+        return this.#fn(env);
+    }
+    /**
+     * Evaluate each reader in the array, and collect the results in a single reader instance.
+     */
+    static sequence(readers) {
+        return new Reader((env) => readers.map((reader) => reader.run(env)));
+    }
+    /**
+     * Transforms a function that returns a Reader into a Reader that produces a function.
+     *
+     * This makes functions producing Readers that depend on more arguments sometimes easier to work with.
+     */
+    static defer(fn) {
+        return new Reader((env) => (...args) => fn(...args).run(env));
+    }
+    /**
+     * Transforms a Reader that produces a function into a function that returns a Reader.
+     *
+     * This is the inverse of {@link defer}.
+     */
+    static undefer(reader) {
+        return (...args) => new Reader((env) => reader.run(env)(...args));
+    }
+}
+// type Readable<T> =
+//   T extends Record<string, unknown>
+//     ? { [K in keyof T]: Readable<T[K]> }
+//     : T

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elyukai/utils",
-  "version": "0.2.1",
+  "version": "0.2.4",
   "description": "A set of JavaScript helper functions.",
   "files": [
     "dist",
@@ -32,16 +32,15 @@
   },
   "homepage": "https://github.com/elyukai/ts-utils#readme",
   "devDependencies": {
-    "@eslint/js": "^9.39.2",
-    "@types/node": "^25.0.10",
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^25.3.0",
     "commit-and-tag-version": "^12.6.1",
-    "eslint": "^9.39.2",
-    "eslint-plugin-jsdoc": "^62.4.1",
-    "glob": "^13.0.0",
+    "eslint": "^10.0.1",
+    "eslint-plugin-jsdoc": "^62.7.0",
     "prettier": "^3.8.1",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",
-    "typescript-eslint": "^8.53.1"
+    "typescript-eslint": "^8.56.0"
   },
   "type": "module"
 }