@vielzeug/toolkit 1.1.2 → 2.0.0

package/README.md

@@ -0,0 +1,419 @@
+# @vielzeug/toolkit
+
+> Typed utility functions for everyday TypeScript — arrays, objects, strings, async, dates, math, and more
+
+[![npm version](https://img.shields.io/npm/v/@vielzeug/toolkit)](https://www.npmjs.com/package/@vielzeug/toolkit) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**Toolkit** is a tree-shakeable collection of TypeScript utility functions covering arrays, objects, strings, async control-flow, dates, math, money, and type guards — all individually importable with full type inference and zero dependencies.
+
+## Installation
+
+```sh
+pnpm add @vielzeug/toolkit
+# npm install @vielzeug/toolkit
+# yarn add @vielzeug/toolkit
+```
+
+## Quick Start
+
+```typescript
+import { group, chunk, debounce, retry, merge, uuid, is } from '@vielzeug/toolkit';
+
+// Group an array by a key
+const byStatus = group(users, (u) => u.status);
+// { active: [...], inactive: [...] }
+
+// Split array into chunks
+const pages = chunk([1, 2, 3, 4, 5], 2); // [[1,2],[3,4],[5]]
+
+// Debounce an event handler
+const handleSearch = debounce((query: string) => fetchResults(query), 300);
+
+// Retry a failing async function
+const result = await retry(() => fetchData(), { times: 3, delay: 200 });
+
+// Deep merge objects
+const config = merge('deep', defaults, overrides);
+
+// Generate a UUID
+const id = uuid(); // e.g. "550e8400-e29b-41d4-a716-446655440000"
+
+// Runtime type checks
+if (is.string(value)) { /* value narrowed to string */ }
+```
+
+## Features
+
+- ✅ **Tree-shakeable** — import only what you use
+- ✅ **Type-safe** — full TypeScript inference on every utility
+- ✅ **Array** — `chunk`, `group`, `keyBy`, `fold`, `select`, `toggle`, `rotate`, `replace`, `search`, `uniq`, `sort`, `contains`, `pick`, `list`, `remoteList`
+- ✅ **Object** — `merge`, `diff`, `get`, `seek`, `prune`, `proxy`, `cache`, `parseJSON`
+- ✅ **String** — `camelCase`, `kebabCase`, `pascalCase`, `snakeCase`, `truncate`, `similarity`
+- ✅ **Async** — `retry`, `sleep`, `parallel`, `pool`, `queue`, `race`, `attempt`, `defer`, `waitFor`
+- ✅ **Function** — `debounce`, `throttle`, `memo`, `once`, `pipe`, `compose`, `curry`, `compare`, `fp`
+- ✅ **Math** — `sum`, `average`, `median`, `min`, `max`, `clamp`, `round`, `range`, `percent`, `linspace`, `allocate`, `distribute`
+- ✅ **Date** — `timeDiff`, `interval`, `expires`
+- ✅ **Money** — `currency`, `exchange`
+- ✅ **Random** — `uuid`, `random`, `draw`, `shuffle`
+- ✅ **Type guards** — `is.string`, `is.number`, `is.array`, `is.nil`, `is.equal`, `is.match`, and more
+- ✅ **Zero dependencies**
+
+## Usage
+
+### Array Utilities
+
+```typescript
+import { group, chunk, keyBy, fold, select, toggle, uniq, sort } from '@vielzeug/toolkit';
+
+// Group by key
+const byRole = group(users, (u) => u.role);     // { admin: [...], user: [...] }
+
+// Split into chunks
+const pages = chunk(items, 10);                  // Item[][]
+
+// Index by key
+const byId = keyBy(users, 'id');                 // { '1': user1, '2': user2 }
+
+// Fold (reduce without initial value)
+fold([1, 2, 3], (a, b) => a + b);               // 6
+
+// Filter nil elements from source, then map remaining
+select([null, 1, null, 2], (n) => n * 10); // [10, 20]
+
+// Filter by predicate, then map
+select([1, 2, 3, 4], (n) => n * 10, (n) => n > 2); // [30, 40]
+
+// Toggle item in/out of array
+toggle([1, 2, 3], 2);                            // [1, 3]
+toggle([1, 2, 3], 4);                            // [1, 2, 3, 4]
+
+// Sort by selector (single-field)
+sort([{ value: 3 }, { value: 1 }], (item) => item.value); // [{ value: 1 }, { value: 3 }]
+
+// Sort by object selectors (multi-field)
+sort(
+  [
+	{ age: 30, name: 'Bob' },
+	{ age: 30, name: 'Alice' },
+	{ age: 25, name: 'Chris' },
+  ],
+  { age: 'desc', name: 'asc' },
+);
+
+// Remove duplicates
+uniq([1, 2, 2, 3]);                              // [1, 2, 3]
+```
+
+### Object Utilities
+
+```typescript
+import { merge, diff, get, seek, prune, parseJSON } from '@vielzeug/toolkit';
+
+// Deep merge
+const cfg = merge('deep', { api: { host: 'localhost' } }, { api: { port: 3000 } });
+// { api: { host: 'localhost', port: 3000 } }
+
+// Nested path access
+get(cfg, 'api.host');   // 'localhost'
+
+// Recursively search object values by similarity
+seek(cfg, 'localhost', 1);   // true (exact match)
+
+// Remove nulls/empty values
+prune({ a: 1, b: null, c: '' });  // { a: 1 }
+
+// Safe JSON parse
+parseJSON('{"a":1}', {});  // { a: 1 }
+parseJSON('bad json', {}); // {}
+```
+
+### Async Utilities
+
+```typescript
+import { retry, sleep, parallel, pool, race, attempt, waitFor } from '@vielzeug/toolkit';
+
+// Retry with backoff
+const result = await retry(() => fetchData(), { times: 3, delay: 200, backoff: 2 });
+
+// Delay
+await sleep(500);
+
+// Process items with concurrency limit
+const results = await parallel(5, urls, async (url) => fetch(url).then((r) => r.json()));
+
+// Race promise against minimum delay (prevents loading flicker)
+const data = await race(fetchUser(id), 300);
+
+// Attempt with explicit success/failure handling
+const userAttempt = await attempt(fetchUser, { times: 2, timeout: 5000 });
+if (userAttempt.ok) {
+  console.log(userAttempt.value);
+} else {
+  console.error(userAttempt.error);
+}
+
+// Poll until condition is true
+await waitFor(() => document.querySelector('#app') !== null, { timeout: 5000 });
+```
+
+### String Utilities
+
+```typescript
+import { camelCase, kebabCase, snakeCase, pascalCase, truncate, similarity } from '@vielzeug/toolkit';
+
+camelCase('hello-world');          // 'helloWorld'
+kebabCase('helloWorld');           // 'hello-world'
+snakeCase('helloWorld');           // 'hello_world'
+pascalCase('hello-world');         // 'HelloWorld'
+truncate('A very long string', 10); // 'A very lon...'
+similarity('hello', 'hallo');      // ~0.8
+```
+
+### Function Utilities
+
+```typescript
+import { memo, once, pipe, debounce, throttle, compare } from '@vielzeug/toolkit';
+
+const fib    = memo((n: number): number => n <= 1 ? n : fib(n - 1) + fib(n - 2));
+const init   = once(() => bootstrap());
+const process = pipe(trim, normalize, validate);
+const search = debounce(fetchResults, 300);
+const scroll = throttle(updatePosition, 16);
+
+// Compare → always -1 | 0 | 1 (safe for sort)
+compare(1, 2);   // -1
+compare('b', 'a'); // 1
+```
+
+### Math Utilities
+
+```typescript
+import { sum, average, clamp, round, range, percent, linspace } from '@vielzeug/toolkit';
+
+sum([1, 2, 3, 4]);          // 10
+average([10, 20, 30]);      // 20
+clamp(105, 0, 100);         // 100
+round(Math.PI, 4);          // 3.1416
+range(1, 6, 1);              // [1, 2, 3, 4, 5]
+percent(25, 100);           // 25
+linspace(0, 10, 5);         // [0, 2.5, 5, 7.5, 10]
+```
+
+### Date Utilities
+
+```typescript
+import { timeDiff, interval, expires } from '@vielzeug/toolkit';
+
+// Human-readable time difference
+timeDiff(new Date('2025-01-01'), new Date());
+// e.g. { value: 2, unit: 'MONTH' }
+
+// Generate date range
+interval('2024-01-01', '2024-01-07', { interval: 'day' });
+// [Date, Date, Date, Date, Date, Date, Date]
+
+// Check expiration
+expires('2023-01-01'); // e.g. 'EXPIRED'
+```
+
+### Type Guards
+
+```typescript
+import { is } from '@vielzeug/toolkit';
+
+is.string(v);
+is.number(v);
+is.boolean(v);
+is.array(v);
+is.object(v);
+is.fn(v);
+is.date(v);
+is.promise(v);
+is.regex(v);
+is.nil(v);
+is.defined(v);
+is.primitive(v);
+is.empty(v);
+is.equal(a, b);
+is.match(obj, src);
+is.even(n);
+is.odd(n);
+is.positive(n);
+is.negative(n);
+is.zero(n);
+is.within(n, min, max);
+is.ge(a, b);
+is.gt(a, b);
+is.le(a, b);
+is.lt(a, b);
+is.typeOf(v); // e.g. 'string' | 'number' | 'array'
+```
+
+## API
+
+### Array
+
+| Function | Description |
+|---|---|
+| `chunk(arr, size)` | Split array into chunks of given size |
+| `contains(arr, value)` | Check if array contains a value (deep equality) |
+| `fold(arr, fn)` | Reduce without initial value |
+| `group(arr, selector)` | Group by key — returns `Record<string, T[]>` |
+| `keyBy(arr, selector)` | Index by key — returns `Record<string, T>` |
+| `list(data, opts?)` | Reactive client-side pagination |
+| `pick(arr, valueFn, predicate?)` | Pick single transformed element |
+| `remoteList(opts)` | Reactive server-side pagination |
+| `replace(arr, predicate, value)` | Replace first matching element |
+| `rotate(arr, n, opts?)` | Rotate elements by N positions |
+| `search(arr, query, opts?)` | Fuzzy search |
+| `select(arr, mapper, predicate?)` | Map elements matching predicate (default: not nil) |
+| `sort(arr, selector, direction?)` | Sort by selector with `'asc'`/`'desc'` direction |
+| `sort(arr, selectors)` | Sort by multiple fields using object selectors |
+| `toggle(arr, item, selector?, opts?)` | Add or remove item |
+| `uniq(arr)` | Remove duplicates |
+
+### Object
+
+| Function | Description |
+|---|---|
+| `cache()` | Key-value cache with auto GC |
+| `diff(a, b)` | Find differences between objects |
+| `merge(strategy, ...objs)` | Merge objects (deep/shallow/concat) |
+| `parseJSON(str, fallback?)` | Safe JSON parse |
+| `get(obj, path, default?)` | Access nested property by dot-path |
+| `proxy(obj, opts)` | Object proxy with get/set hooks |
+| `prune(value)` | Remove nulls/empty values recursively |
+| `seek(obj, query, tone?)` | Search object values by similarity score |
+
+### String
+
+| Function | Description |
+|---|---|
+| `camelCase(str)` | Convert to camelCase |
+| `kebabCase(str)` | Convert to kebab-case |
+| `pascalCase(str)` | Convert to PascalCase |
+| `similarity(a, b)` | Similarity score (0–1) between two strings |
+| `snakeCase(str)` | Convert to snake_case |
+| `truncate(str, limit)` | Truncate with ellipsis |
+
+### Function
+
+| Function | Description |
+|---|---|
+| `assert(cond, msg, opts?)` | Assert condition, throw on failure |
+| `assertParams(params, keys)` | Validate required object keys |
+| `compare(a, b)` | Safe comparator returning -1 \| 0 \| 1 |
+| `compareBy(criteria)` | Multi-key object comparator |
+| `compose(...fns)` | Right-to-left function composition |
+| `curry(fn)` | Curry with partial application |
+| `debounce(fn, ms)` | Delay execution until idle |
+| `fp(fn, ...args)` | Functional pipeline helper |
+| `memo(fn)` | Cache results by arguments |
+| `once(fn)` | Execute only on first call |
+| `pipe(...fns)` | Left-to-right function composition |
+| `throttle(fn, ms)` | Limit execution rate |
+
+### Async
+
+| Function | Description |
+|---|---|
+| `attempt(fn, opts?)` | Execute with retry and error handling |
+| `defer()` | Deferred promise with external resolve/reject |
+| `parallel(n, items, fn, signal?)` | Process array with concurrency limit |
+| `pool(n)` | Concurrency-limited promise pool |
+| `queue(opts?)` | Sequential/concurrent task queue |
+| `race(promise, minDelay)` | Race promise against minimum delay |
+| `retry(fn, opts?)` | Retry with backoff |
+| `sleep(ms)` | Async delay |
+| `waitFor(cond, opts?)` | Poll until condition is true |
+
+### Math
+
+| Function | Description |
+|---|---|
+| `abs(n)` | Absolute value |
+| `allocate(amount, ratios)` | Distribute proportionally (bigint) |
+| `average(arr, fn?)` | Average of numbers |
+| `clamp(n, min, max)` | Clamp to range |
+| `distribute(amount, n)` | Distribute evenly (bigint) |
+| `linspace(start, end, steps?)` | Evenly spaced number array |
+| `max(arr, fn?)` | Maximum value |
+| `median(arr, fn?)` | Median value |
+| `min(arr, fn?)` | Minimum value |
+| `percent(value, total)` | Percentage (0–100) |
+| `range(start, end, step?)` | Generate number array |
+| `round(n, precision?)` | Round to decimal places |
+| `sum(arr, fn?)` | Sum of numbers |
+
+### Date
+
+| Function | Description |
+|---|---|
+| `expires(date)` | Check expiration status |
+| `interval(start, end, opts?)` | Generate date array for a range |
+| `timeDiff(a, b?, units?)` | Time difference as `{ value, unit }` |
+
+### Money
+
+| Function | Description |
+|---|---|
+| `currency(money)` | Format for display |
+| `exchange(money, opts)` | Convert between currencies |
+
+### Random
+
+| Function | Description |
+|---|---|
+| `draw(arr)` | Random element from array |
+| `random(min, max)` | Random number in range |
+| `shuffle(arr)` | Shuffle array |
+| `uuid()` | Generate UUID v4 |
+
+### Type Guards (`is` namespace)
+
+All type checks live on the `is` object:
+
+```typescript
+import { is } from '@vielzeug/toolkit';
+
+is.string(v);
+is.number(v);
+is.boolean(v);
+is.array(v);
+is.object(v);
+is.fn(v);
+is.date(v);
+is.promise(v);
+is.regex(v);
+is.nil(v);
+is.defined(v);
+is.primitive(v);
+is.empty(v);
+is.equal(a, b);
+is.match(obj, src);
+is.even(n);
+is.odd(n);
+is.positive(n);
+is.negative(n);
+is.zero(n);
+is.within(n, min, max);
+is.ge(a, b);
+is.gt(a, b);
+is.le(a, b);
+is.lt(a, b);
+is.typeOf(v); // e.g. 'string' | 'number' | 'array'
+```
+
+## Documentation
+
+Full docs at **[vielzeug.dev/toolkit](https://vielzeug.dev/toolkit)**
+
+| | |
+|---|---|
+| [Usage Guide](https://vielzeug.dev/toolkit/usage) | Arrays, objects, async, strings |
+| [API Reference](https://vielzeug.dev/toolkit/api) | Complete function signatures |
+| [Examples](https://vielzeug.dev/toolkit/examples) | Real-world utility patterns |
+
+## License
+
+MIT © [Helmuth Saatkamp](https://github.com/helmuthdu) — Part of the [Vielzeug](https://github.com/helmuthdu/vielzeug) monorepo.

package/dist/array/chunk.cjs

@@ -1,2 +1,2 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const o=require("../function/assert.cjs"),u=require("../typed/isArray.cjs"),c=require("../typed/isString.cjs");function y(e,r=2,g={}){o.assert(u.isArray(e)||c.isString(e),"Argument must be an array or string.",{args:{input:e},type:TypeError}),o.assert(r>=1,"Chunk size must be at least 1.",{args:{size:r},type:RangeError});const{overlap:l=!1,pad:a=" "}=g;if(c.isString(e)&&l){const s=a+e+a,t=s.length-r+1;return Array.from({length:t},(h,n)=>s.slice(n,n+r))}return Array.from({length:Math.ceil(e.length/r)},(s,t)=>e.slice(t*r,t*r+r))}exports.chunk=y;
-//# sourceMappingURL=chunk.cjs.map
+const e=require(`../function/assert.cjs`),t=require(`../typed/isArray.cjs`),n=require(`../typed/isString.cjs`);function r(r,i=2,a={}){e.assert(t.isArray(r)||n.isString(r),`Argument must be an array or string.`,{args:{input:r},type:TypeError}),e.assert(i>=1,`Chunk size must be at least 1.`,{args:{size:i},type:RangeError});let{overlap:o=!1,pad:s=` `}=a;if(n.isString(r)&&o){let e=s+r+s,t=e.length-i+1;return Array.from({length:t},(t,n)=>e.slice(n,n+i))}return Array.from({length:Math.ceil(r.length/i)},(e,t)=>r.slice(t*i,t*i+i))}exports.chunk=r;
+//# sourceMappingURL=chunk.cjs.map

package/dist/array/chunk.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"chunk.cjs","sources":["../../src/array/chunk.ts"],"sourcesContent":["import { assert } from '../function/assert';\nimport { isArray } from '../typed/isArray';\nimport { isString } from '../typed/isString';\n\n// #region ChunkTypes\ntype ChunkOptions = {\n  overlap?: boolean;\n  pad?: string;\n};\n\ntype ChunkResult<T> = (T extends string ? string : T[])[];\n// #endregion ChunkTypes\n\n/**\n * Splits an array or string into chunks of a specified size.\n *\n * @example\n * ```ts\n * chunk([1, 2, 3, 4, 5], 2) // [[1, 2], [3, 4], [5]]\n * chunk(\"hello\", 2) // [\"he\", \"ll\", \"o\"]\n * chunk(\"hello\", 2, { overlap: true }) // [\" h\", \"he\", \"el\", \"ll\", \"lo\", \"o \"]\n * ```\n *\n * @param input - The input array or string to be chunked.\n * @param size - The size of each chunk.\n * @param [options] - Additional options for chunking.\n * @param [options.overlap] -\n * @param [options.pad] -\n *\n * @returns An array of chunks.\n *\n * @throws {RangeError} If the chunk size is invalid.\n * @throws {TypeError} If the input type is invalid.\n */\nexport function chunk<T>(input: T[] | string, size = 2, options: ChunkOptions = {}): ChunkResult<T> {\n  assert(isArray(input as T[]) || isString(input), 'Argument must be an array or string.', {\n    args: { input },\n    type: TypeError,\n  });\n\n  assert(size >= 1, 'Chunk size must be at least 1.', {\n    args: { size },\n    type: RangeError,\n  });\n\n  const { overlap = false, pad = ' ' } = options;\n\n  if (isString(input) && overlap) {\n    const padded = pad + input + pad;\n    const numChunks = padded.length - size + 1;\n    return Array.from({ length: numChunks }, (_, i) => padded.slice(i, i + size)) as ChunkResult<T>;\n  }\n\n  return Array.from({ length: Math.ceil(input.length / size) }, (_, i) =>\n    input.slice(i * size, i * size + size),\n  ) as ChunkResult<T>;\n}\n"],"names":["chunk","input","size","options","assert","isArray","isString","overlap","pad","padded","numChunks","_","i"],"mappings":"+LAkCO,SAASA,EAASC,EAAqBC,EAAO,EAAGC,EAAwB,CAAA,EAAoB,CAClGC,EAAAA,OAAOC,EAAAA,QAAQJ,CAAY,GAAKK,EAAAA,SAASL,CAAK,EAAG,uCAAwC,CACvF,KAAM,CAAE,MAAAA,CAAA,EACR,KAAM,SAAA,CACP,EAEDG,SAAOF,GAAQ,EAAG,iCAAkC,CAClD,KAAM,CAAE,KAAAA,CAAA,EACR,KAAM,UAAA,CACP,EAED,KAAM,CAAE,QAAAK,EAAU,GAAO,IAAAC,EAAM,KAAQL,EAEvC,GAAIG,EAAAA,SAASL,CAAK,GAAKM,EAAS,CAC9B,MAAME,EAASD,EAAMP,EAAQO,EACvBE,EAAYD,EAAO,OAASP,EAAO,EACzC,OAAO,MAAM,KAAK,CAAE,OAAQQ,GAAa,CAACC,EAAGC,IAAMH,EAAO,MAAMG,EAAGA,EAAIV,CAAI,CAAC,CAC9E,CAEA,OAAO,MAAM,KAAK,CAAE,OAAQ,KAAK,KAAKD,EAAM,OAASC,CAAI,CAAA,EAAK,CAACS,EAAGC,IAChEX,EAAM,MAAMW,EAAIV,EAAMU,EAAIV,EAAOA,CAAI,CAAA,CAEzC"}
+{"version":3,"file":"chunk.cjs","names":[],"sources":["../../src/array/chunk.ts"],"sourcesContent":["import { assert } from '../function/assert';\nimport { isArray } from '../typed/isArray';\nimport { isString } from '../typed/isString';\n\n// #region ChunkTypes\ntype ChunkOptions = {\n  overlap?: boolean;\n  pad?: string;\n};\n\ntype ChunkResult<T> = (T extends string ? string : T[])[];\n// #endregion ChunkTypes\n\n/**\n * Splits an array or string into chunks of a specified size.\n *\n * @example\n * ```ts\n * chunk([1, 2, 3, 4, 5], 2) // [[1, 2], [3, 4], [5]]\n * chunk(\"hello\", 2) // [\"he\", \"ll\", \"o\"]\n * chunk(\"hello\", 2, { overlap: true }) // [\" h\", \"he\", \"el\", \"ll\", \"lo\", \"o \"]\n * ```\n *\n * @param input - The input array or string to be chunked.\n * @param size - The size of each chunk.\n * @param [options] - Additional options for chunking.\n * @param [options.overlap] -\n * @param [options.pad] -\n *\n * @returns An array of chunks.\n *\n * @throws {RangeError} If the chunk size is invalid.\n * @throws {TypeError} If the input type is invalid.\n */\nexport function chunk<T>(input: T[] | string, size = 2, options: ChunkOptions = {}): ChunkResult<T> {\n  assert(isArray(input as T[]) || isString(input), 'Argument must be an array or string.', {\n    args: { input },\n    type: TypeError,\n  });\n\n  assert(size >= 1, 'Chunk size must be at least 1.', {\n    args: { size },\n    type: RangeError,\n  });\n\n  const { overlap = false, pad = ' ' } = options;\n\n  if (isString(input) && overlap) {\n    const padded = pad + input + pad;\n    const numChunks = padded.length - size + 1;\n\n    return Array.from({ length: numChunks }, (_, i) => padded.slice(i, i + size)) as ChunkResult<T>;\n  }\n\n  return Array.from({ length: Math.ceil(input.length / size) }, (_, i) =>\n    input.slice(i * size, i * size + size),\n  ) as ChunkResult<T>;\n}\n"],"mappings":"+GAkCA,SAAgB,EAAS,EAAqB,EAAO,EAAG,EAAwB,EAAE,CAAkB,CAClG,EAAA,OAAO,EAAA,QAAQ,EAAa,EAAI,EAAA,SAAS,EAAM,CAAE,uCAAwC,CACvF,KAAM,CAAE,QAAO,CACf,KAAM,UACP,CAAC,CAEF,EAAA,OAAO,GAAQ,EAAG,iCAAkC,CAClD,KAAM,CAAE,OAAM,CACd,KAAM,WACP,CAAC,CAEF,GAAM,CAAE,UAAU,GAAO,MAAM,KAAQ,EAEvC,GAAI,EAAA,SAAS,EAAM,EAAI,EAAS,CAC9B,IAAM,EAAS,EAAM,EAAQ,EACvB,EAAY,EAAO,OAAS,EAAO,EAEzC,OAAO,MAAM,KAAK,CAAE,OAAQ,EAAW,EAAG,EAAG,IAAM,EAAO,MAAM,EAAG,EAAI,EAAK,CAAC,CAG/E,OAAO,MAAM,KAAK,CAAE,OAAQ,KAAK,KAAK,EAAM,OAAS,EAAK,CAAE,EAAG,EAAG,IAChE,EAAM,MAAM,EAAI,EAAM,EAAI,EAAO,EAAK,CACvC"}

package/dist/array/chunk.d.ts

@@ -0,0 +1,29 @@
+type ChunkOptions = {
+    overlap?: boolean;
+    pad?: string;
+};
+type ChunkResult<T> = (T extends string ? string : T[])[];
+/**
+ * Splits an array or string into chunks of a specified size.
+ *
+ * @example
+ * ```ts
+ * chunk([1, 2, 3, 4, 5], 2) // [[1, 2], [3, 4], [5]]
+ * chunk("hello", 2) // ["he", "ll", "o"]
+ * chunk("hello", 2, { overlap: true }) // [" h", "he", "el", "ll", "lo", "o "]
+ * ```
+ *
+ * @param input - The input array or string to be chunked.
+ * @param size - The size of each chunk.
+ * @param [options] - Additional options for chunking.
+ * @param [options.overlap] -
+ * @param [options.pad] -
+ *
+ * @returns An array of chunks.
+ *
+ * @throws {RangeError} If the chunk size is invalid.
+ * @throws {TypeError} If the input type is invalid.
+ */
+export declare function chunk<T>(input: T[] | string, size?: number, options?: ChunkOptions): ChunkResult<T>;
+export {};
+//# sourceMappingURL=chunk.d.ts.map

package/dist/array/chunk.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk.d.ts","sourceRoot":"","sources":["../../src/array/chunk.ts"],"names":[],"mappings":"AAKA,KAAK,YAAY,GAAG;IAClB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,GAAG,CAAC,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,KAAK,WAAW,CAAC,CAAC,IAAI,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC;AAG1D;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,KAAK,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,MAAM,EAAE,IAAI,SAAI,EAAE,OAAO,GAAE,YAAiB,GAAG,WAAW,CAAC,CAAC,CAAC,CAuBlG"}

package/dist/array/chunk.js

@@ -1,25 +1,23 @@
-import { assert as m } from "../function/assert.js";
-import { isArray as c } from "../typed/isArray.js";
-import { isString as s } from "../typed/isString.js";
-function p(t, r = 2, g = {}) {
-  m(c(t) || s(t), "Argument must be an array or string.", {
-    args: { input: t },
-    type: TypeError
-  }), m(r >= 1, "Chunk size must be at least 1.", {
-    args: { size: r },
-    type: RangeError
-  });
-  const { overlap: l = !1, pad: e = " " } = g;
-  if (s(t) && l) {
-    const o = e + t + e, a = o.length - r + 1;
-    return Array.from({ length: a }, (f, n) => o.slice(n, n + r));
-  }
-  return Array.from(
-    { length: Math.ceil(t.length / r) },
-    (o, a) => t.slice(a * r, a * r + r)
-  );
+import { assert as e } from "../function/assert.js";
+import { isArray as t } from "../typed/isArray.js";
+import { isString as n } from "../typed/isString.js";
+//#region src/array/chunk.ts
+function r(r, i = 2, a = {}) {
+	e(t(r) || n(r), "Argument must be an array or string.", {
+		args: { input: r },
+		type: TypeError
+	}), e(i >= 1, "Chunk size must be at least 1.", {
+		args: { size: i },
+		type: RangeError
+	});
+	let { overlap: o = !1, pad: s = " " } = a;
+	if (n(r) && o) {
+		let e = s + r + s, t = e.length - i + 1;
+		return Array.from({ length: t }, (t, n) => e.slice(n, n + i));
+	}
+	return Array.from({ length: Math.ceil(r.length / i) }, (e, t) => r.slice(t * i, t * i + i));
 }
-export {
-  p as chunk
-};
-//# sourceMappingURL=chunk.js.map
+//#endregion
+export { r as chunk };
+
+//# sourceMappingURL=chunk.js.map

package/dist/array/chunk.js.map

@@ -1 +1 @@
-{"version":3,"file":"chunk.js","sources":["../../src/array/chunk.ts"],"sourcesContent":["import { assert } from '../function/assert';\nimport { isArray } from '../typed/isArray';\nimport { isString } from '../typed/isString';\n\n// #region ChunkTypes\ntype ChunkOptions = {\n  overlap?: boolean;\n  pad?: string;\n};\n\ntype ChunkResult<T> = (T extends string ? string : T[])[];\n// #endregion ChunkTypes\n\n/**\n * Splits an array or string into chunks of a specified size.\n *\n * @example\n * ```ts\n * chunk([1, 2, 3, 4, 5], 2) // [[1, 2], [3, 4], [5]]\n * chunk(\"hello\", 2) // [\"he\", \"ll\", \"o\"]\n * chunk(\"hello\", 2, { overlap: true }) // [\" h\", \"he\", \"el\", \"ll\", \"lo\", \"o \"]\n * ```\n *\n * @param input - The input array or string to be chunked.\n * @param size - The size of each chunk.\n * @param [options] - Additional options for chunking.\n * @param [options.overlap] -\n * @param [options.pad] -\n *\n * @returns An array of chunks.\n *\n * @throws {RangeError} If the chunk size is invalid.\n * @throws {TypeError} If the input type is invalid.\n */\nexport function chunk<T>(input: T[] | string, size = 2, options: ChunkOptions = {}): ChunkResult<T> {\n  assert(isArray(input as T[]) || isString(input), 'Argument must be an array or string.', {\n    args: { input },\n    type: TypeError,\n  });\n\n  assert(size >= 1, 'Chunk size must be at least 1.', {\n    args: { size },\n    type: RangeError,\n  });\n\n  const { overlap = false, pad = ' ' } = options;\n\n  if (isString(input) && overlap) {\n    const padded = pad + input + pad;\n    const numChunks = padded.length - size + 1;\n    return Array.from({ length: numChunks }, (_, i) => padded.slice(i, i + size)) as ChunkResult<T>;\n  }\n\n  return Array.from({ length: Math.ceil(input.length / size) }, (_, i) =>\n    input.slice(i * size, i * size + size),\n  ) as ChunkResult<T>;\n}\n"],"names":["chunk","input","size","options","assert","isArray","isString","overlap","pad","padded","numChunks","_","i"],"mappings":";;;AAkCO,SAASA,EAASC,GAAqBC,IAAO,GAAGC,IAAwB,CAAA,GAAoB;AAClG,EAAAC,EAAOC,EAAQJ,CAAY,KAAKK,EAASL,CAAK,GAAG,wCAAwC;AAAA,IACvF,MAAM,EAAE,OAAAA,EAAA;AAAA,IACR,MAAM;AAAA,EAAA,CACP,GAEDG,EAAOF,KAAQ,GAAG,kCAAkC;AAAA,IAClD,MAAM,EAAE,MAAAA,EAAA;AAAA,IACR,MAAM;AAAA,EAAA,CACP;AAED,QAAM,EAAE,SAAAK,IAAU,IAAO,KAAAC,IAAM,QAAQL;AAEvC,MAAIG,EAASL,CAAK,KAAKM,GAAS;AAC9B,UAAME,IAASD,IAAMP,IAAQO,GACvBE,IAAYD,EAAO,SAASP,IAAO;AACzC,WAAO,MAAM,KAAK,EAAE,QAAQQ,KAAa,CAACC,GAAGC,MAAMH,EAAO,MAAMG,GAAGA,IAAIV,CAAI,CAAC;AAAA,EAC9E;AAEA,SAAO,MAAM;AAAA,IAAK,EAAE,QAAQ,KAAK,KAAKD,EAAM,SAASC,CAAI,EAAA;AAAA,IAAK,CAACS,GAAGC,MAChEX,EAAM,MAAMW,IAAIV,GAAMU,IAAIV,IAAOA,CAAI;AAAA,EAAA;AAEzC;"}
+{"version":3,"file":"chunk.js","names":[],"sources":["../../src/array/chunk.ts"],"sourcesContent":["import { assert } from '../function/assert';\nimport { isArray } from '../typed/isArray';\nimport { isString } from '../typed/isString';\n\n// #region ChunkTypes\ntype ChunkOptions = {\n  overlap?: boolean;\n  pad?: string;\n};\n\ntype ChunkResult<T> = (T extends string ? string : T[])[];\n// #endregion ChunkTypes\n\n/**\n * Splits an array or string into chunks of a specified size.\n *\n * @example\n * ```ts\n * chunk([1, 2, 3, 4, 5], 2) // [[1, 2], [3, 4], [5]]\n * chunk(\"hello\", 2) // [\"he\", \"ll\", \"o\"]\n * chunk(\"hello\", 2, { overlap: true }) // [\" h\", \"he\", \"el\", \"ll\", \"lo\", \"o \"]\n * ```\n *\n * @param input - The input array or string to be chunked.\n * @param size - The size of each chunk.\n * @param [options] - Additional options for chunking.\n * @param [options.overlap] -\n * @param [options.pad] -\n *\n * @returns An array of chunks.\n *\n * @throws {RangeError} If the chunk size is invalid.\n * @throws {TypeError} If the input type is invalid.\n */\nexport function chunk<T>(input: T[] | string, size = 2, options: ChunkOptions = {}): ChunkResult<T> {\n  assert(isArray(input as T[]) || isString(input), 'Argument must be an array or string.', {\n    args: { input },\n    type: TypeError,\n  });\n\n  assert(size >= 1, 'Chunk size must be at least 1.', {\n    args: { size },\n    type: RangeError,\n  });\n\n  const { overlap = false, pad = ' ' } = options;\n\n  if (isString(input) && overlap) {\n    const padded = pad + input + pad;\n    const numChunks = padded.length - size + 1;\n\n    return Array.from({ length: numChunks }, (_, i) => padded.slice(i, i + size)) as ChunkResult<T>;\n  }\n\n  return Array.from({ length: Math.ceil(input.length / size) }, (_, i) =>\n    input.slice(i * size, i * size + size),\n  ) as ChunkResult<T>;\n}\n"],"mappings":";;;;AAkCA,SAAgB,EAAS,GAAqB,IAAO,GAAG,IAAwB,EAAE,EAAkB;AAMlG,CALA,EAAO,EAAQ,EAAa,IAAI,EAAS,EAAM,EAAE,wCAAwC;EACvF,MAAM,EAAE,UAAO;EACf,MAAM;EACP,CAAC,EAEF,EAAO,KAAQ,GAAG,kCAAkC;EAClD,MAAM,EAAE,SAAM;EACd,MAAM;EACP,CAAC;CAEF,IAAM,EAAE,aAAU,IAAO,SAAM,QAAQ;AAEvC,KAAI,EAAS,EAAM,IAAI,GAAS;EAC9B,IAAM,IAAS,IAAM,IAAQ,GACvB,IAAY,EAAO,SAAS,IAAO;AAEzC,SAAO,MAAM,KAAK,EAAE,QAAQ,GAAW,GAAG,GAAG,MAAM,EAAO,MAAM,GAAG,IAAI,EAAK,CAAC;;AAG/E,QAAO,MAAM,KAAK,EAAE,QAAQ,KAAK,KAAK,EAAM,SAAS,EAAK,EAAE,GAAG,GAAG,MAChE,EAAM,MAAM,IAAI,GAAM,IAAI,IAAO,EAAK,CACvC"}

package/dist/array/contains.cjs

@@ -1,2 +1,2 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const n=require("../function/assert.cjs"),r=require("../typed/isArray.cjs"),o=require("../typed/isEqual.cjs");function s(e,t){return n.assert(r.isArray(e),r.IS_ARRAY_ERROR_MSG,{args:{array:e},type:TypeError}),e.some(i=>o.isEqual(i,t))}s.fp=!0;exports.contains=s;
-//# sourceMappingURL=contains.cjs.map
+const e=require(`../function/assert.cjs`),t=require(`../typed/isArray.cjs`),n=require(`../typed/isEqual.cjs`);function r(r,i){return e.assert(t.isArray(r),t.IS_ARRAY_ERROR_MSG,{args:{array:r},type:TypeError}),r.some(e=>n.isEqual(e,i))}exports.contains=r;
+//# sourceMappingURL=contains.cjs.map

package/dist/array/contains.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"contains.cjs","sources":["../../src/array/contains.ts"],"sourcesContent":["import { assert } from '../function/assert';\nimport { IS_ARRAY_ERROR_MSG, isArray } from '../typed/isArray';\nimport { isEqual } from '../typed/isEqual';\n\n/**\n * Checks if a value is present in an array.\n *\n * @example\n * ```ts\n * const arr = [1, 2, 3, { a: 1 }, 'hello'];\n * const value = { a: 1 };\n * contains(arr, value) // true;\n * ```\n *\n * @param array - The array to check.\n * @param value - The value to search for.\n *\n * @returns true if the value is present in the array, else false.\n *\n * @throws {TypeError} If the first argument is not an array.\n */\n\n// biome-ignore lint/suspicious/noExplicitAny: -\nexport function contains<T>(array: T[], value: any): boolean {\n  assert(isArray(array), IS_ARRAY_ERROR_MSG, { args: { array }, type: TypeError });\n\n  return array.some((val) => isEqual(val, value));\n}\n\ncontains.fp = true;\n"],"names":["contains","array","value","assert","isArray","IS_ARRAY_ERROR_MSG","val","isEqual"],"mappings":"8LAuBO,SAASA,EAAYC,EAAYC,EAAqB,CAC3DC,OAAAA,EAAAA,OAAOC,EAAAA,QAAQH,CAAK,EAAGI,qBAAoB,CAAE,KAAM,CAAE,MAAAJ,CAAA,EAAS,KAAM,UAAW,EAExEA,EAAM,KAAMK,GAAQC,EAAAA,QAAQD,EAAKJ,CAAK,CAAC,CAChD,CAEAF,EAAS,GAAK"}
+{"version":3,"file":"contains.cjs","names":[],"sources":["../../src/array/contains.ts"],"sourcesContent":["import { assert } from '../function/assert';\nimport { IS_ARRAY_ERROR_MSG, isArray } from '../typed/isArray';\nimport { isEqual } from '../typed/isEqual';\n\n/**\n * Checks if a value is present in an array.\n *\n * @example\n * ```ts\n * const arr = [1, 2, 3, { a: 1 }, 'hello'];\n * const value = { a: 1 };\n * contains(arr, value) // true;\n * ```\n *\n * @param array - The array to check.\n * @param value - The value to search for.\n *\n * @returns true if the value is present in the array, else false.\n *\n * @throws {TypeError} If the first argument is not an array.\n */\n\nexport function contains<T>(array: T[], value: unknown): boolean {\n  assert(isArray(array), IS_ARRAY_ERROR_MSG, { args: { array }, type: TypeError });\n\n  return array.some((val) => isEqual(val, value));\n}\n"],"mappings":"8GAsBA,SAAgB,EAAY,EAAY,EAAyB,CAG/D,OAFA,EAAA,OAAO,EAAA,QAAQ,EAAM,CAAE,EAAA,mBAAoB,CAAE,KAAM,CAAE,QAAO,CAAE,KAAM,UAAW,CAAC,CAEzE,EAAM,KAAM,GAAQ,EAAA,QAAQ,EAAK,EAAM,CAAC"}

package/dist/array/contains.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Checks if a value is present in an array.
+ *
+ * @example
+ * ```ts
+ * const arr = [1, 2, 3, { a: 1 }, 'hello'];
+ * const value = { a: 1 };
+ * contains(arr, value) // true;
+ * ```
+ *
+ * @param array - The array to check.
+ * @param value - The value to search for.
+ *
+ * @returns true if the value is present in the array, else false.
+ *
+ * @throws {TypeError} If the first argument is not an array.
+ */
+export declare function contains<T>(array: T[], value: unknown): boolean;
+//# sourceMappingURL=contains.d.ts.map

package/dist/array/contains.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contains.d.ts","sourceRoot":"","sources":["../../src/array/contains.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;GAgBG;AAEH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAI/D"}

package/dist/array/contains.js

@@ -1,11 +1,14 @@
 import { assert as e } from "../function/assert.js";
-import { IS_ARRAY_ERROR_MSG as i, isArray as m } from "../typed/isArray.js";
-import { isEqual as p } from "../typed/isEqual.js";
-function s(r, o) {
-  return e(m(r), i, { args: { array: r }, type: TypeError }), r.some((t) => p(t, o));
+import { IS_ARRAY_ERROR_MSG as t, isArray as n } from "../typed/isArray.js";
+import { isEqual as r } from "../typed/isEqual.js";
+//#region src/array/contains.ts
+function i(i, a) {
+	return e(n(i), t, {
+		args: { array: i },
+		type: TypeError
+	}), i.some((e) => r(e, a));
 }
-s.fp = !0;
-export {
-  s as contains
-};
-//# sourceMappingURL=contains.js.map
+//#endregion
+export { i as contains };
+
+//# sourceMappingURL=contains.js.map

package/dist/array/contains.js.map

@@ -1 +1 @@
-{"version":3,"file":"contains.js","sources":["../../src/array/contains.ts"],"sourcesContent":["import { assert } from '../function/assert';\nimport { IS_ARRAY_ERROR_MSG, isArray } from '../typed/isArray';\nimport { isEqual } from '../typed/isEqual';\n\n/**\n * Checks if a value is present in an array.\n *\n * @example\n * ```ts\n * const arr = [1, 2, 3, { a: 1 }, 'hello'];\n * const value = { a: 1 };\n * contains(arr, value) // true;\n * ```\n *\n * @param array - The array to check.\n * @param value - The value to search for.\n *\n * @returns true if the value is present in the array, else false.\n *\n * @throws {TypeError} If the first argument is not an array.\n */\n\n// biome-ignore lint/suspicious/noExplicitAny: -\nexport function contains<T>(array: T[], value: any): boolean {\n  assert(isArray(array), IS_ARRAY_ERROR_MSG, { args: { array }, type: TypeError });\n\n  return array.some((val) => isEqual(val, value));\n}\n\ncontains.fp = true;\n"],"names":["contains","array","value","assert","isArray","IS_ARRAY_ERROR_MSG","val","isEqual"],"mappings":";;;AAuBO,SAASA,EAAYC,GAAYC,GAAqB;AAC3D,SAAAC,EAAOC,EAAQH,CAAK,GAAGI,GAAoB,EAAE,MAAM,EAAE,OAAAJ,EAAA,GAAS,MAAM,WAAW,GAExEA,EAAM,KAAK,CAACK,MAAQC,EAAQD,GAAKJ,CAAK,CAAC;AAChD;AAEAF,EAAS,KAAK;"}
+{"version":3,"file":"contains.js","names":[],"sources":["../../src/array/contains.ts"],"sourcesContent":["import { assert } from '../function/assert';\nimport { IS_ARRAY_ERROR_MSG, isArray } from '../typed/isArray';\nimport { isEqual } from '../typed/isEqual';\n\n/**\n * Checks if a value is present in an array.\n *\n * @example\n * ```ts\n * const arr = [1, 2, 3, { a: 1 }, 'hello'];\n * const value = { a: 1 };\n * contains(arr, value) // true;\n * ```\n *\n * @param array - The array to check.\n * @param value - The value to search for.\n *\n * @returns true if the value is present in the array, else false.\n *\n * @throws {TypeError} If the first argument is not an array.\n */\n\nexport function contains<T>(array: T[], value: unknown): boolean {\n  assert(isArray(array), IS_ARRAY_ERROR_MSG, { args: { array }, type: TypeError });\n\n  return array.some((val) => isEqual(val, value));\n}\n"],"mappings":";;;;AAsBA,SAAgB,EAAY,GAAY,GAAyB;AAG/D,QAFA,EAAO,EAAQ,EAAM,EAAE,GAAoB;EAAE,MAAM,EAAE,UAAO;EAAE,MAAM;EAAW,CAAC,EAEzE,EAAM,MAAM,MAAQ,EAAQ,GAAK,EAAM,CAAC"}

package/dist/array/fold.cjs

@@ -0,0 +1,2 @@
+const e=require(`../function/assert.cjs`),t=require(`../typed/isArray.cjs`);function n(n,r){e.assert(t.isArray(n),t.IS_ARRAY_ERROR_MSG,{args:{array:n,callback:r},type:TypeError});let i=n[0];for(let e=1;e<n.length;e++)i=r(i,n[e]);return i}exports.fold=n;
+//# sourceMappingURL=fold.cjs.map

package/dist/array/fold.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"fold.cjs","names":[],"sources":["../../src/array/fold.ts"],"sourcesContent":["import { assert } from '../function/assert';\nimport { IS_ARRAY_ERROR_MSG, isArray } from '../typed/isArray';\n\n/**\n * Folds an array down to a single value by applying a callback to each pair of\n * elements (reduce without an initial value).\n *\n * @example\n * ```ts\n * fold([1, 2, 3], (a, b) => a + b) // 6\n * fold([1, 2, 3], (a, b) => a > b ? a : b) // 3\n * fold([{ a: 1 }, { a: 2 }], (a, b) => ({ a: a.a + b.a })) // { a: 3 }\n * fold([], (a, b) => a + b) // undefined\n * fold([1], (a, b) => a + b) // 1\n * ```\n *\n * @param array - The array to fold.\n * @param callback - The function to invoke for each pair of elements.\n * @returns The folded value, or `undefined` if the array is empty.\n *\n * @throws {TypeError} If the first argument is not an array.\n */\nexport function fold<T>(array: readonly T[], callback: (a: T, b: T) => T): T | undefined {\n  assert(isArray(array), IS_ARRAY_ERROR_MSG, {\n    args: { array, callback },\n    type: TypeError,\n  });\n\n  let result = array[0];\n\n  for (let i = 1; i < array.length; i++) {\n    result = callback(result, array[i]);\n  }\n\n  return result;\n}\n"],"mappings":"4EAsBA,SAAgB,EAAQ,EAAqB,EAA4C,CACvF,EAAA,OAAO,EAAA,QAAQ,EAAM,CAAE,EAAA,mBAAoB,CACzC,KAAM,CAAE,QAAO,WAAU,CACzB,KAAM,UACP,CAAC,CAEF,IAAI,EAAS,EAAM,GAEnB,IAAK,IAAI,EAAI,EAAG,EAAI,EAAM,OAAQ,IAChC,EAAS,EAAS,EAAQ,EAAM,GAAG,CAGrC,OAAO"}

package/dist/array/fold.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Folds an array down to a single value by applying a callback to each pair of
+ * elements (reduce without an initial value).
+ *
+ * @example
+ * ```ts
+ * fold([1, 2, 3], (a, b) => a + b) // 6
+ * fold([1, 2, 3], (a, b) => a > b ? a : b) // 3
+ * fold([{ a: 1 }, { a: 2 }], (a, b) => ({ a: a.a + b.a })) // { a: 3 }
+ * fold([], (a, b) => a + b) // undefined
+ * fold([1], (a, b) => a + b) // 1
+ * ```
+ *
+ * @param array - The array to fold.
+ * @param callback - The function to invoke for each pair of elements.
+ * @returns The folded value, or `undefined` if the array is empty.
+ *
+ * @throws {TypeError} If the first argument is not an array.
+ */
+export declare function fold<T>(array: readonly T[], callback: (a: T, b: T) => T): T | undefined;
+//# sourceMappingURL=fold.d.ts.map