@ts-fns/stdlib 0.1.0 → 0.2.1

package/dist/array/index.cjs

@@ -1,17 +1,35 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_orThrow = require("../orThrow-ejzcQYAI.cjs");
-const require_purry = require("../purry-B2_0DGLV.cjs");
+const require_function = require("../function-DYPifnmg.cjs");
+const require_purry = require("../purry-Dqp_F64t.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}
+* Creates an array from an iterable or array-like object.
+* @function
+*/
+const from = Array.from;
+/**
+* Creates an array from an async iterable.
+* @function
+*/
+const fromAsync = Array.fromAsync;
+/**
+* Checks whether a value is an array.
+* @function
+*/
+const isArray = Array.isArray;
+/**
+* Creates an array containing the given values.
+* @function
+*/
+const of = Array.of;
+/**
+* Alias of the built-in array constructor. `new Array() === new Arr.Ctor()
+* @function
 */
+const Ctor = Array;
+//#endregion
+//#region src/array/at.ts
 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);
@@ -20,8 +38,18 @@ function at(...args) {
 	return require_purry.purry(atImplementation, args);
 }
 function atAssert(...args) {
-	return require_purry.purry(require_orThrow.orThrow(atImplementation), args);
+	return require_purry.purry(require_function.orThrow(atImplementation), args);
 }
+/**
+* Like `at`, but throws when the index is out of bounds.
+*
+* @example
+* ```ts
+* at.assert([1, 2, 3], 1); // 2
+* at.assert(-1)([1, 2, 3]); // 3
+* at.assert([1, 2, 3], 3); // throws RangeError
+* ```
+*/
 at.assert = atAssert;
 //#endregion
 //#region src/array/chunk.ts
@@ -40,8 +68,17 @@ function chunk(...args) {
 	return require_purry.purry(chunkImplementation, args);
 }
 function chunkAssert(...args) {
-	return require_purry.purry(require_orThrow.orThrow(chunkImplementation), args);
+	return require_purry.purry(require_function.orThrow(chunkImplementation), args);
 }
+/**
+* Like `chunk`, but throws when the size is not a positive integer.
+*
+* @example
+* ```ts
+* chunk.assert([1, 2, 3, 4, 5], 2); // [[1, 2], [3, 4], [5]]
+* chunk.assert(0)([1, 2, 3]); // throws RangeError
+* ```
+*/
 chunk.assert = chunkAssert;
 //#endregion
 //#region src/array/concat.ts
@@ -78,8 +115,17 @@ function find(...args) {
 	return require_purry.purry(findImplementation, args);
 }
 function findAssert(...args) {
-	return require_purry.purry(require_orThrow.orThrow(findImplementation), args);
+	return require_purry.purry(require_function.orThrow(findImplementation), args);
 }
+/**
+* Like `find`, but throws when no element matches the predicate.
+*
+* @example
+* ```ts
+* find.assert([1, 2, 3], n => n > 1); // 2
+* find.assert(n => n > 10)([1, 2, 3]); // throws NotFoundError
+* ```
+*/
 find.assert = findAssert;
 //#endregion
 //#region src/array/findIndex.ts
@@ -92,8 +138,17 @@ function findIndex(...args) {
 	return require_purry.purry(findIndexImplementation, args);
 }
 function findIndexAssert(...args) {
-	return require_purry.purry(require_orThrow.orThrow(findIndexImplementation), args);
+	return require_purry.purry(require_function.orThrow(findIndexImplementation), args);
 }
+/**
+* Like `findIndex`, but throws when no element matches the predicate.
+*
+* @example
+* ```ts
+* findIndex.assert([1, 2, 3], n => n > 1); // 1
+* findIndex.assert(n => n > 10)([1, 2, 3]); // throws NotFoundError
+* ```
+*/
 findIndex.assert = findIndexAssert;
 //#endregion
 //#region src/array/findLast.ts
@@ -106,8 +161,17 @@ function findLast(...args) {
 	return require_purry.purry(findLastImplementation, args);
 }
 function findLastAssert(...args) {
-	return require_purry.purry(require_orThrow.orThrow(findLastImplementation), args);
+	return require_purry.purry(require_function.orThrow(findLastImplementation), args);
 }
+/**
+* Like `findLast`, but throws when no element matches the predicate.
+*
+* @example
+* ```ts
+* findLast.assert([1, 2, 3, 2], n => n === 2); // 2
+* findLast.assert(n => n > 10)([1, 2, 3]); // throws NotFoundError
+* ```
+*/
 findLast.assert = findLastAssert;
 //#endregion
 //#region src/array/findLastIndex.ts
@@ -120,8 +184,17 @@ function findLastIndex(...args) {
 	return require_purry.purry(findLastIndexImplementation, args);
 }
 function findLastIndexAssert(...args) {
-	return require_purry.purry(require_orThrow.orThrow(findLastIndexImplementation), args);
+	return require_purry.purry(require_function.orThrow(findLastIndexImplementation), args);
 }
+/**
+* Like `findLastIndex`, but throws when no element matches the predicate.
+*
+* @example
+* ```ts
+* findLastIndex.assert([1, 2, 3, 2], n => n === 2); // 3
+* findLastIndex.assert(n => n > 10)([1, 2, 3]); // throws NotFoundError
+* ```
+*/
 findLastIndex.assert = findLastIndexAssert;
 //#endregion
 //#region src/array/first.ts
@@ -130,8 +203,17 @@ function first(arr) {
 	return arr[0];
 }
 function firstAssert(arr) {
-	return require_orThrow.orThrow(first)(arr);
+	return require_function.orThrow(first)(arr);
 }
+/**
+* Like `first`, but throws when the array is empty.
+*
+* @example
+* ```ts
+* first.assert([1, 2, 3]); // 1
+* first.assert([]); // throws EmptyArrayError
+* ```
+*/
 first.assert = firstAssert;
 //#endregion
 //#region src/array/flatMap.ts
@@ -153,14 +235,29 @@ function forEach(...args) {
 //#endregion
 //#region src/array/init.ts
 /**
+* Returns all elements except the last.
 *
+* @example
+* ```ts
+* init([1, 2, 3]); // [1, 2]
+* init([1]); // []
+* ```
 */
 function init(arr) {
 	return arr.slice(0, arr.length - 1);
 }
 function initAssert(arr) {
-	return require_orThrow.orThrow(init)(arr);
+	return require_function.orThrow(init)(arr);
 }
+/**
+* Like `init`, but throws when the array is empty.
+*
+* @example
+* ```ts
+* init.assert([1, 2, 3]); // [1, 2]
+* init.assert([]); // throws EmptyArrayError
+* ```
+*/
 init.assert = initAssert;
 //#endregion
 //#region src/array/insert.ts
@@ -175,8 +272,17 @@ function insert(...args) {
 	return require_purry.purry(insertImplementation, args);
 }
 function insertAssert(...args) {
-	return require_purry.purry(require_orThrow.orThrow(insertImplementation), args);
+	return require_purry.purry(require_function.orThrow(insertImplementation), args);
 }
+/**
+* Like `insert`, but throws when the index is invalid.
+*
+* @example
+* ```ts
+* insert.assert([1, 2, 3], 1, 9); // [1, 9, 3]
+* insert.assert(10, 9)([1, 2, 3]); // throws RangeError
+* ```
+*/
 insert.assert = insertAssert;
 //#endregion
 //#region src/array/isEmpty.ts
@@ -201,15 +307,28 @@ function last(arr) {
 	return arr[arr.length - 1];
 }
 function lastAssert(arr) {
-	return require_orThrow.orThrow(last)(arr);
+	return require_function.orThrow(last)(arr);
 }
+/**
+* Like `last`, but throws when the array is empty.
+*
+* @example
+* ```ts
+* last.assert([1, 2, 3]); // 3
+* last.assert([]); // throws EmptyArrayError
+* ```
+*/
 last.assert = lastAssert;
 //#endregion
 //#region src/array/length.ts
 /**
-* Returns length of array
-* @param arr
-* @returns
+* Returns the number of elements in an array.
+*
+* @example
+* ```ts
+* length([1, 2, 3]); // 3
+* length([]); // 0
+* ```
 */
 function length(arr) {
 	return arr.length;
@@ -225,9 +344,13 @@ function map(...args) {
 //#endregion
 //#region src/array/ofLength.ts
 /**
-* Arr.ofLength
+* Creates a sparse array with the given length.
 *
-* @throws {RangeError}
+* @example
+* ```ts
+* ofLength(3); // [empty × 3]
+* ofLength<string>(2); // [empty × 2]
+* ```
 */
 function ofLength(arrayLength) {
 	return Array(arrayLength);
@@ -256,8 +379,17 @@ function pop(arr) {
 	return [arr[lastIndex], arr.slice(0, lastIndex)];
 }
 function popAssert(arr) {
-	return require_orThrow.orThrow(pop)(arr);
+	return require_function.orThrow(pop)(arr);
 }
+/**
+* Like `pop`, but throws when the array is empty.
+*
+* @example
+* ```ts
+* pop.assert([1, 2, 3]); // [3, [1, 2]]
+* pop.assert([]); // throws EmptyArrayError
+* ```
+*/
 pop.assert = popAssert;
 //#endregion
 //#region src/array/prepend.ts
@@ -310,9 +442,13 @@ function reduceRight1(...args) {
 //#endregion
 //#region src/array/rest.ts
 /**
-* Returns an array excluding the first entry
-* @param arr
-* @returns
+* Returns all elements except the first.
+*
+* @example
+* ```ts
+* rest([1, 2, 3]); // [2, 3]
+* rest([1]); // []
+* ```
 */
 function rest(arr) {
 	const [, ...tail] = arr;
@@ -320,12 +456,17 @@ function rest(arr) {
 }
 //#endregion
 //#region src/array/reverse.ts
-function reverseImplementation(arr) {
+/**
+* Returns a reversed copy of an array without mutating the original.
+*
+* @example
+* ```ts
+* reverse([1, 2, 3]); // [3, 2, 1]
+* ```
+*/
+function reverse(arr) {
 	return arr.toReversed();
 }
-function reverse(...args) {
-	return require_purry.purry(reverseImplementation, args);
-}
 //#endregion
 //#region src/array/scan.ts
 function scanImplementation(arr, callbackFn, initialValue) {
@@ -350,11 +491,28 @@ function shift(arr) {
 	return [head, tail];
 }
 function shiftAssert(arr) {
-	return require_orThrow.orThrow(shift)(arr);
+	return require_function.orThrow(shift)(arr);
 }
+/**
+* Like `shift`, but throws when the array is empty.
+*
+* @example
+* ```ts
+* shift.assert([1, 2, 3]); // [1, [2, 3]]
+* shift.assert([]); // throws EmptyArrayError
+* ```
+*/
 shift.assert = shiftAssert;
 //#endregion
 //#region src/array/shuffle.ts
+/**
+* Returns a shuffled copy of an array using the Fisher-Yates algorithm.
+*
+* @example
+* ```ts
+* shuffle([1, 2, 3, 4]); // e.g. [3, 1, 4, 2]
+* ```
+*/
 function shuffle(arr) {
 	const result = [...arr];
 	const len = result.length;
@@ -407,12 +565,29 @@ function take(...args) {
 }
 //#endregion
 //#region src/array/transpose.ts
+/**
+* Transposes a matrix so rows become columns and columns become rows.
+*
+* @example
+* ```ts
+* transpose([[1, 2], [3, 4], [5, 6]]); // [[1, 3, 5], [2, 4, 6]]
+* ```
+*/
 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
+/**
+* Returns a copy of an array with duplicate values removed.
+*
+* @example
+* ```ts
+* unique([1, 2, 2, 3]); // [1, 2, 3]
+* unique([]); // []
+* ```
+*/
 function unique(arr) {
 	if (arr.length === 0) return [];
 	return Array.from(new Set(arr));
@@ -434,6 +609,16 @@ function uniqueBy(...args) {
 }
 //#endregion
 //#region src/array/uniqueWith.ts
+/**
+* Returns a copy of an array with duplicates removed using a custom equality function.
+* Keeps the first occurrence of each equivalent value.
+*
+* @example
+* ```ts
+* uniqueWith([1, 1.0, 2], (a, b) => a === b); // [1, 2]
+* uniqueWith([], (a, b) => a === b); // []
+* ```
+*/
 function uniqueWith(arr, isEqual) {
 	if (arr.length === 0) return [];
 	return arr.filter((value, index) => {
@@ -459,8 +644,17 @@ function update(...args) {
 	return require_purry.purry(updateImplementation, args);
 }
 function updateAssert(...args) {
-	return require_purry.purry(require_orThrow.orThrow(updateImplementation), args);
+	return require_purry.purry(require_function.orThrow(updateImplementation), args);
 }
+/**
+* Like `update`, but throws when the index is out of bounds.
+*
+* @example
+* ```ts
+* update.assert([1, 2, 3], 1, n => n * 10); // [1, 20, 3]
+* update.assert(10, n => n)([1, 2, 3]); // throws RangeError
+* ```
+*/
 update.assert = updateAssert;
 //#endregion
 //#region src/array/window.ts
@@ -474,8 +668,17 @@ function window(...args) {
 	return require_purry.purry(windowImplementation, args);
 }
 function windowAssert(...args) {
-	return require_purry.purry(require_orThrow.orThrow(windowImplementation), args);
+	return require_purry.purry(require_function.orThrow(windowImplementation), args);
 }
+/**
+* Like `window`, but throws when the size is not a positive integer.
+*
+* @example
+* ```ts
+* window.assert([1, 2, 3, 4], 2); // [[1, 2], [2, 3], [3, 4]]
+* window.assert(0)([1, 2, 3]); // throws RangeError
+* ```
+*/
 window.assert = windowAssert;
 //#endregion
 //#region src/array/zip.ts
@@ -494,9 +697,8 @@ function zipWith(...args) {
 	return require_purry.purry(zipWithImplementation, args);
 }
 //#endregion
-exports.Array = arrayConstructor;
+exports.Ctor = Ctor;
 exports.at = at;
-exports.atAssert = atAssert;
 exports.chunk = chunk;
 exports.concat = concat;
 exports.drop = drop;