@ts-fns/stdlib 0.1.0

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright 2025 Harris Miller
+
+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

@@ -0,0 +1,132 @@
+# @ts-fns/stdlib
+
+## Core concepts
+
+* Functional Programming style API
+* Stand-alone functions
+* Fully type-safe
+* Immutability, with appropriate exceptions
+* Normalized return types to `Error | T` unions
+* pipe/compose work like ADT `map`/`flatMap` under the hood
+* Interoperable with other FP focused libraries!
+
+Elixir style everything, for consistent, clean, and type-safe code
+
+## Usage
+
+Very much a Work in progress
+
+Still working on the standard alias
+
+```typescript
+import * as Arr from '@ts-fns/stdlib/array';
+import * as Func from '@ts-fns/stdlib/function';
+import * as Guard from '@ts-fns/stdlib/guard';
+import * as Iter from '@ts-fns/stdlib/iterator';
+import * as Lens from '@ts-fns/stdlib/lens';
+import * as Map from '@ts-fns/stdlib/map';
+import * as Num from '@ts-fns/stdlib/number';
+import * as Obj from '@ts-fns/stdlib/object';
+import * as Ord from '@ts-fns/stdlib/order';
+import * as Set from '@ts-fns/stdlib/set';
+import * as Str from '@ts-fns/stdlib/string';
+import * as Tuple from '@ts-fns/stdlib/tuple';
+```
+
+## Details
+
+### Normalized return types to `Error | T` unions
+
+Javascript has no normalized "Empty" value that gets returned from methods. `-1`? `undefined`? `null`?. In addition, while exceptions and try/catch blocks are the built-in mechanisms for Errors, sometimes those errors are represented as values. For example, `Number.parseInt()` returns `NaN` instead of throwing.
+
+Errors-as-values in the form of unions are the most idiomatic way to continue to use javascript without introducing new paradigms such as `Result`. Control-flow logic doesn't change in most cases, you just change your condition parameters
+
+```typescript
+/* vanilla js */
+const user = users.find(u => u.id === id);
+//    ^? User | undefined
+
+if (user === undefined) {
+  // handle "NotFound" case
+}
+
+/* @ts-fns/stdlib */
+import * as Arr from '@ts-fns/stdlib/array';
+
+const user = Arr.find(users, u => u.id === id);
+//    ^? User | NotFoundError
+
+if (user instanceof NotFoundError) {
+  // handle "NotFound" case
+}
+```
+
+While functions that throw get changed from try-catch blocks to other control-flow mechanics, this is probably for the better, as it aligns into a single paradigm flow
+
+```typescript
+/* vanilla js */
+let updatedUsers;
+try {
+  updatedUsers = users.with(5, updatedUser);
+} catch(e) {
+  // handle error
+}
+
+/* @ts-fns/stdlib */
+import * as Arr from '@ts-fns/stdlib/array';
+
+const updatedUsers = Arr.insert(users, 5, updatedUser)
+
+if (updatedUsers instanceof RangeError) {
+  // handle error
+}
+```
+
+Errors are no longer opaque, and compliment Typescript's type system. Yielding more type-safety and less error prone code.
+
+### Two Type of Errors
+
+This repo subscribes to Effect's philosophy that there are Expected and Unexpected Errors (read about it here: https://effect.website/docs/guide/effects/errors).
+
+Just like Effect does not track Unexpected Errors, neither does `@ts-fns/stdlib`. In particular, this library only captures expected errors, returning them as values. Unexpected errors are thrown as normal.
+
+#### Expected Errors
+
+Some examples
+
+* `Array.prototype.with()` throws a `RangeError` if the index is out of bounds. `Arr.update()` returns `RangeError` as a value for the same reason.
+* Different value are used to represent "not found". `Arr.indexOf()` returns `-1`. `Arr.find()` returns `undefined`. `Str.match()` returns `null`. `@ts-fns/stdlib` normalizes these by returning `NotFoundError` as a value
+* Array function that would normally return when called on an empty array will return `EmptyArrayError` instead.
+
+All functions that catch, or add, expected Errors will return that errors as a value, typed as part of that function's return type union.
+
+##### Type narrowing to remove errors from return type
+
+`Arr.first()` returns `EmptyArrayError | T`. The guard function `Arr.isNotEmpty()` validates at runtime that an array is not empty and narrow an array `T[]` to `NonEmptyArray<T>`. `Arr.first()` is typed to accept `ReadonlyNonEmptyArray<T>` and will return only `T` for that case. This allows you to remove errors from the return type by validating at runtime that the error condition cannot exist.
+
+```typescript
+import * as Arr from '@ts-fns/stdlib/array';
+
+const arr: number[] = [];
+
+const first = Arr.first(arr);
+//    ^? EmptyArrayError | number
+
+if (Arr.isNotEmpty(arr)) {
+  const first = Arr.first(arr);
+  //    ^? number
+}
+```
+
+#### Unexpected Errors
+
+`Str.startsWith()` is a good example. Javascript's `String.prototype.startsWith()` [throws an TypeError if the search value is a regex](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/endsWith#exceptions). Though defined, this error is considered *unexpected* because it would be illogical to use a regex. Javascript coerces other types to strings, Typescript defines `string` as the only valid argument type.
+
+Any function that does this will have `@throws` in their JSDoc comment to indicate this possibility.
+
+### TODO
+
+Go over:
+* `.assert()` to remove errors from the return types but with the risk of throwing
+* `gen()` function to utilize generator functions to write procedural code and aggregate error handle to the result
+* `pipe`/`compose` act like ADT `.map()`/`.flatMap()` under-the-hood, allowing you to string together functions that throw error, but defer those errors to the result

package/dist/array/index.cjs

@@ -0,0 +1,551 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_orThrow = require("../orThrow-ejzcQYAI.cjs");
+const require_purry = require("../purry-B2_0DGLV.cjs");
+const require_errors = require("../errors-O-d_Vemi.cjs");
+require("../function-CB82a2GS.cjs");
+//#region src/array/_globalAliases.ts
+const { from, fromAsync, isArray, of } = Array;
+const arrayConstructor = Array;
+//#endregion
+//#region src/array/at.ts
+/**
+* Internal method that wraps `arr.at()` but throws the same `RangeError` that `arr.with()` does
+* @throws {RangeError}
+*/
+function atImplementation(arr, index) {
+	if (arr.length === 0 || index >= arr.length || index < -arr.length) return /* @__PURE__ */ new RangeError(`Arr.at() :: Invalid index : ${index}`);
+	return arr.at(index);
+}
+function at(...args) {
+	return require_purry.purry(atImplementation, args);
+}
+function atAssert(...args) {
+	return require_purry.purry(require_orThrow.orThrow(atImplementation), args);
+}
+at.assert = atAssert;
+//#endregion
+//#region src/array/chunk.ts
+function chunkImplementation(arr, size) {
+	if (size < 1) throw new RangeError(`Arr.chunk() :: ${size} must be a positive integer`);
+	if (arr.length === 0) return [];
+	if (size >= arr.length) return [[...arr]];
+	const chunks = Math.ceil(arr.length / size);
+	if (size === 1) return arr.map((v) => [v]);
+	return Array(chunks).fill(void 0).map((_, index) => {
+		const start = index * size;
+		return arr.slice(start, start + size);
+	});
+}
+function chunk(...args) {
+	return require_purry.purry(chunkImplementation, args);
+}
+function chunkAssert(...args) {
+	return require_purry.purry(require_orThrow.orThrow(chunkImplementation), args);
+}
+chunk.assert = chunkAssert;
+//#endregion
+//#region src/array/concat.ts
+function concatImplementation(arr, other) {
+	return [...arr, ...other];
+}
+function concat(...args) {
+	return require_purry.purry(concatImplementation, args);
+}
+//#endregion
+//#region src/array/drop.ts
+function dropImplementation(arr, n) {
+	return arr.slice(n);
+}
+function drop(...args) {
+	return require_purry.purry(dropImplementation, args);
+}
+//#endregion
+//#region src/array/every.ts
+function everyImplementation(arr, predicate) {
+	return arr.every(predicate);
+}
+function every(...args) {
+	return require_purry.purry(everyImplementation, args);
+}
+//#endregion
+//#region src/array/find.ts
+function findImplementation(arr, predicate) {
+	const foundIndex = arr.findIndex(predicate);
+	if (foundIndex === -1) return new require_errors.NotFoundError("Arr.find :: predicate found no match.");
+	return arr[foundIndex];
+}
+function find(...args) {
+	return require_purry.purry(findImplementation, args);
+}
+function findAssert(...args) {
+	return require_purry.purry(require_orThrow.orThrow(findImplementation), args);
+}
+find.assert = findAssert;
+//#endregion
+//#region src/array/findIndex.ts
+function findIndexImplementation(arr, predicate) {
+	const result = arr.findIndex(predicate);
+	if (result === -1) return new require_errors.NotFoundError("Arr.findIndex.orError() :: predicate found no match.");
+	return result;
+}
+function findIndex(...args) {
+	return require_purry.purry(findIndexImplementation, args);
+}
+function findIndexAssert(...args) {
+	return require_purry.purry(require_orThrow.orThrow(findIndexImplementation), args);
+}
+findIndex.assert = findIndexAssert;
+//#endregion
+//#region src/array/findLast.ts
+function findLastImplementation(arr, predicate) {
+	const foundIndex = arr.findLastIndex(predicate);
+	if (foundIndex === -1) return new require_errors.NotFoundError("Arr.findLast() :: predicate found no match.");
+	return arr[foundIndex];
+}
+function findLast(...args) {
+	return require_purry.purry(findLastImplementation, args);
+}
+function findLastAssert(...args) {
+	return require_purry.purry(require_orThrow.orThrow(findLastImplementation), args);
+}
+findLast.assert = findLastAssert;
+//#endregion
+//#region src/array/findLastIndex.ts
+function findLastIndexImplementation(arr, predicate) {
+	const result = arr.findLastIndex(predicate);
+	if (result === -1) return new require_errors.NotFoundError("Arr.findLastIndex() :: predicate found no match.");
+	return result;
+}
+function findLastIndex(...args) {
+	return require_purry.purry(findLastIndexImplementation, args);
+}
+function findLastIndexAssert(...args) {
+	return require_purry.purry(require_orThrow.orThrow(findLastIndexImplementation), args);
+}
+findLastIndex.assert = findLastIndexAssert;
+//#endregion
+//#region src/array/first.ts
+function first(arr) {
+	if (arr.length === 0) return new require_errors.EmptyArrayError("Arr.first() :: array is empty");
+	return arr[0];
+}
+function firstAssert(arr) {
+	return require_orThrow.orThrow(first)(arr);
+}
+first.assert = firstAssert;
+//#endregion
+//#region src/array/flatMap.ts
+function flatMapImplementation(arr, callbackfn) {
+	return arr.flatMap(callbackfn);
+}
+function flatMap(...args) {
+	return require_purry.purry(flatMapImplementation, args);
+}
+//#endregion
+//#region src/array/forEach.ts
+function forEachImplementation(arr, callbackfn) {
+	arr.forEach(callbackfn);
+	return arr;
+}
+function forEach(...args) {
+	return require_purry.purry(forEachImplementation, args);
+}
+//#endregion
+//#region src/array/init.ts
+/**
+*
+*/
+function init(arr) {
+	return arr.slice(0, arr.length - 1);
+}
+function initAssert(arr) {
+	return require_orThrow.orThrow(init)(arr);
+}
+init.assert = initAssert;
+//#endregion
+//#region src/array/insert.ts
+function insertImplementation(arr, index, value) {
+	try {
+		return arr.with(index, value);
+	} catch (_e) {
+		return /* @__PURE__ */ new RangeError(`Arr.insert() - Invalid index : ${index}`);
+	}
+}
+function insert(...args) {
+	return require_purry.purry(insertImplementation, args);
+}
+function insertAssert(...args) {
+	return require_purry.purry(require_orThrow.orThrow(insertImplementation), args);
+}
+insert.assert = insertAssert;
+//#endregion
+//#region src/array/isEmpty.ts
+function isNotEmpty(arr) {
+	return arr.length > 0;
+}
+function isEmpty(arr) {
+	return arr.length === 0;
+}
+//#endregion
+//#region src/array/join.ts
+function joinImplementation(arr, separator) {
+	return arr.join(separator);
+}
+function join(...args) {
+	return require_purry.purry(joinImplementation, args);
+}
+//#endregion
+//#region src/array/last.ts
+function last(arr) {
+	if (arr.length === 0) return new require_errors.EmptyArrayError("Arr.last() :: array is empty");
+	return arr[arr.length - 1];
+}
+function lastAssert(arr) {
+	return require_orThrow.orThrow(last)(arr);
+}
+last.assert = lastAssert;
+//#endregion
+//#region src/array/length.ts
+/**
+* Returns length of array
+* @param arr
+* @returns
+*/
+function length(arr) {
+	return arr.length;
+}
+//#endregion
+//#region src/array/map.ts
+function mapImplementation(arr, callbackfn) {
+	return arr.map(callbackfn);
+}
+function map(...args) {
+	return require_purry.purry(mapImplementation, args);
+}
+//#endregion
+//#region src/array/ofLength.ts
+/**
+* Arr.ofLength
+*
+* @throws {RangeError}
+*/
+function ofLength(arrayLength) {
+	return Array(arrayLength);
+}
+//#endregion
+//#region src/array/partition.ts
+function partitionImplementation(arr, predicate) {
+	const len = arr.length;
+	const left = [];
+	const right = [];
+	for (let i = 0; i < len; i += 1) {
+		const value = arr[i];
+		if (predicate(value, i, arr)) left.push(value);
+		else right.push(value);
+	}
+	return [left, right];
+}
+function partition(...args) {
+	return require_purry.purry(partitionImplementation, args);
+}
+//#endregion
+//#region src/array/pop.ts
+function pop(arr) {
+	if (arr.length === 0) return new require_errors.EmptyArrayError("Arr.pop() :: array is empty");
+	const lastIndex = arr.length - 1;
+	return [arr[lastIndex], arr.slice(0, lastIndex)];
+}
+function popAssert(arr) {
+	return require_orThrow.orThrow(pop)(arr);
+}
+pop.assert = popAssert;
+//#endregion
+//#region src/array/prepend.ts
+function prependImplementation(arr, other) {
+	return [...other, ...arr];
+}
+function prepend(...args) {
+	return require_purry.purry(prependImplementation, args);
+}
+//#endregion
+//#region src/array/push.ts
+function pushImplementation(arr, value) {
+	return [...arr, value];
+}
+function push(...args) {
+	return require_purry.purry(pushImplementation, args);
+}
+//#endregion
+//#region src/array/reduce.ts
+function reduceImplementation(arr, callbackFn, initialValue) {
+	return arr.reduce(callbackFn, initialValue);
+}
+function reduce(...args) {
+	return require_purry.purry(reduceImplementation, args);
+}
+//#endregion
+//#region src/array/reduce1.ts
+function reduce1Implementation(arr, callbackFn) {
+	return arr.reduce(callbackFn);
+}
+function reduce1(...args) {
+	return require_purry.purry(reduce1Implementation, args);
+}
+//#endregion
+//#region src/array/reduceRight.ts
+function reduceRightImplementation(arr, callbackFn, initialValue) {
+	return arr.reduceRight(callbackFn, initialValue);
+}
+function reduceRight(...args) {
+	return require_purry.purry(reduceRightImplementation, args);
+}
+//#endregion
+//#region src/array/reduceRight1.ts
+function reduceRight1Implementation(arr, callbackFn) {
+	return arr.reduceRight(callbackFn);
+}
+function reduceRight1(...args) {
+	return require_purry.purry(reduceRight1Implementation, args);
+}
+//#endregion
+//#region src/array/rest.ts
+/**
+* Returns an array excluding the first entry
+* @param arr
+* @returns
+*/
+function rest(arr) {
+	const [, ...tail] = arr;
+	return tail;
+}
+//#endregion
+//#region src/array/reverse.ts
+function reverseImplementation(arr) {
+	return arr.toReversed();
+}
+function reverse(...args) {
+	return require_purry.purry(reverseImplementation, args);
+}
+//#endregion
+//#region src/array/scan.ts
+function scanImplementation(arr, callbackFn, initialValue) {
+	const len = arr.length;
+	const result = Array(len + 1);
+	let acc = initialValue;
+	result[0] = acc;
+	for (let index = 0; index < len; index += 1) {
+		acc = callbackFn(acc, arr[index], index, arr);
+		result[index + 1] = acc;
+	}
+	return result;
+}
+function scan(...args) {
+	return require_purry.purry(scanImplementation, args);
+}
+//#endregion
+//#region src/array/shift.ts
+function shift(arr) {
+	if (arr.length === 0) return new require_errors.EmptyArrayError("Arr.shift() :: array is empty");
+	const [head, ...tail] = arr;
+	return [head, tail];
+}
+function shiftAssert(arr) {
+	return require_orThrow.orThrow(shift)(arr);
+}
+shift.assert = shiftAssert;
+//#endregion
+//#region src/array/shuffle.ts
+function shuffle(arr) {
+	const result = [...arr];
+	const len = result.length;
+	for (let i = 0; i < len; i += 1) {
+		const rand = i + Math.floor(Math.random() * (len - i));
+		const value = result[rand];
+		result[rand] = result[i];
+		result[i] = value;
+	}
+	return result;
+}
+//#endregion
+//#region src/array/some.ts
+function someImplementation(arr, predicate) {
+	return arr.some(predicate);
+}
+function some(...args) {
+	return require_purry.purry(someImplementation, args);
+}
+//#endregion
+//#region src/array/sort.ts
+function sortImplementation(arr, compareFn) {
+	return arr.toSorted(compareFn);
+}
+function sort(...args) {
+	return require_purry.purry(sortImplementation, args);
+}
+//#endregion
+//#region src/array/sortBy.ts
+function sortByImplementation(arr, mapFn) {
+	return arr.toSorted((left, right) => {
+		const l = mapFn(left);
+		const r = mapFn(right);
+		if (l < r) return -1;
+		if (l > r) return 0;
+		return 0;
+	});
+}
+function sortBy(...args) {
+	return require_purry.purry(sortByImplementation, args);
+}
+//#endregion
+//#region src/array/take.ts
+function takeImplementation(arr, limit) {
+	if (limit < 1) throw new RangeError(`Arr.take() :: ${limit} must be a positive integer`);
+	return arr.slice(0, limit);
+}
+function take(...args) {
+	return require_purry.purry(takeImplementation, args);
+}
+//#endregion
+//#region src/array/transpose.ts
+function transpose(arr) {
+	const maxLen = arr.reduce((acc, inner) => Math.max(acc, inner.length), 0);
+	return Array(maxLen).fill(void 0).map((_, index) => arr.map((inner) => inner[index]));
+}
+//#endregion
+//#region src/array/unique.ts
+function unique(arr) {
+	if (arr.length === 0) return [];
+	return Array.from(new Set(arr));
+}
+//#endregion
+//#region src/array/uniqueBy.ts
+function uniqueByImplementation(arr, mapFn) {
+	if (arr.length === 0) return [];
+	const map = /* @__PURE__ */ new Map();
+	arr.forEach((_, index) => {
+		const value = arr[index];
+		const key = mapFn(value);
+		if (!map.has(key)) map.set(key, value);
+	});
+	return Array.from(map.values());
+}
+function uniqueBy(...args) {
+	return require_purry.purry(uniqueByImplementation, args);
+}
+//#endregion
+//#region src/array/uniqueWith.ts
+function uniqueWith(arr, isEqual) {
+	if (arr.length === 0) return [];
+	return arr.filter((value, index) => {
+		return index === (arr.find((otherValue, otherIndex) => index === otherIndex || isEqual(value, otherValue)) ?? -1);
+	});
+}
+//#endregion
+//#region src/array/unshift.ts
+function unshiftImplementation(arr, value) {
+	return [value, ...arr];
+}
+function unshift(...args) {
+	return require_purry.purry(unshiftImplementation, args);
+}
+//#endregion
+//#region src/array/update.ts
+function updateImplementation(arr, index, fn) {
+	if (index >= arr.length || index < -arr.length) return /* @__PURE__ */ new RangeError(`Arr.update() :: Invalid index : ${index}`);
+	const updatedValue = fn(arr.at(index));
+	return arr.with(index, updatedValue);
+}
+function update(...args) {
+	return require_purry.purry(updateImplementation, args);
+}
+function updateAssert(...args) {
+	return require_purry.purry(require_orThrow.orThrow(updateImplementation), args);
+}
+update.assert = updateAssert;
+//#endregion
+//#region src/array/window.ts
+function windowImplementation(arr, size) {
+	if (size < 1) throw new RangeError(`Arr.window() :: ${size} must be a positive integer`);
+	const limit = arr.length - (size - 1);
+	if (limit < 0) return [];
+	return Array(limit).fill(void 0).map((_, index) => arr.slice(index, index + size));
+}
+function window(...args) {
+	return require_purry.purry(windowImplementation, args);
+}
+function windowAssert(...args) {
+	return require_purry.purry(require_orThrow.orThrow(windowImplementation), args);
+}
+window.assert = windowAssert;
+//#endregion
+//#region src/array/zip.ts
+function zipImplementation(arr, other) {
+	return Array(Math.min(arr.length, other.length)).fill(void 0).map((_, index) => [arr[index], other[index]]);
+}
+function zip(...args) {
+	return require_purry.purry(zipImplementation, args);
+}
+//#endregion
+//#region src/array/zipWith.ts
+function zipWithImplementation(arr, other, fn) {
+	return Array(Math.min(arr.length, other.length)).fill(void 0).map((_, index) => fn(arr[index], other[index]));
+}
+function zipWith(...args) {
+	return require_purry.purry(zipWithImplementation, args);
+}
+//#endregion
+exports.Array = arrayConstructor;
+exports.at = at;
+exports.atAssert = atAssert;
+exports.chunk = chunk;
+exports.concat = concat;
+exports.drop = drop;
+exports.every = every;
+exports.find = find;
+exports.findIndex = findIndex;
+exports.findLast = findLast;
+exports.findLastIndex = findLastIndex;
+exports.first = first;
+exports.flatMap = flatMap;
+exports.forEach = forEach;
+exports.from = from;
+exports.fromAsync = fromAsync;
+exports.init = init;
+exports.insert = insert;
+exports.isArray = isArray;
+exports.isEmpty = isEmpty;
+exports.isNotEmpty = isNotEmpty;
+exports.join = join;
+exports.last = last;
+exports.length = length;
+exports.map = map;
+exports.of = of;
+exports.ofLength = ofLength;
+exports.partition = partition;
+exports.pop = pop;
+exports.prepend = prepend;
+exports.push = push;
+exports.reduce = reduce;
+exports.reduce1 = reduce1;
+exports.reduceRight = reduceRight;
+exports.reduceRight1 = reduceRight1;
+exports.rest = rest;
+exports.reverse = reverse;
+exports.scan = scan;
+exports.shift = shift;
+exports.shuffle = shuffle;
+exports.some = some;
+exports.sort = sort;
+exports.sortBy = sortBy;
+exports.take = take;
+exports.transpose = transpose;
+exports.unique = unique;
+exports.uniqueBy = uniqueBy;
+exports.uniqueWith = uniqueWith;
+exports.unshift = unshift;
+exports.update = update;
+exports.window = window;
+exports.zip = zip;
+exports.zipWith = zipWith;
+
+//# sourceMappingURL=index.cjs.map