@vielzeug/toolkit 1.0.14 → 1.1.3

package/README.md

@@ -0,0 +1,546 @@
+# @vielzeug/toolkit
+
+<div align="center">
+  <img src="../../docs/public/logo-utils.svg" alt="Toolkit Logo" width="120" />
+  
+  <p><strong>A comprehensive, type-safe utility library for modern JavaScript and TypeScript.</strong></p>
+
+[![npm version](https://img.shields.io/npm/v/@vielzeug/toolkit.svg)](https://www.npmjs.com/package/@vielzeug/toolkit)
+[![npm downloads](https://img.shields.io/npm/dm/@vielzeug/toolkit.svg)](https://www.npmjs.com/package/@vielzeug/toolkit)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-100%25-blue)](https://www.typescriptlang.org/)
+[![Bundle Size](https://img.shields.io/bundlephobia/minzip/@vielzeug/toolkit)](https://bundlephobia.com/package/@vielzeug/toolkit)
+
+</div>
+
+## Features
+
+- 🎯 **119 Type-Safe Utilities** - Covering arrays, objects, strings, async operations, and more
+- 📦 **Tree-Shakeable** - Import only what you need, minimize bundle size
+- 🔒 **Zero Dependencies** - No supply chain risks, no version conflicts
+- 💪 **Full TypeScript Support** - Complete type inference and safety
+- ⚡ **Async-First** - Built-in support for promises and async operations
+- 🧪 **Battle-Tested** - >95% test coverage, production-ready
+- 🌐 **Isomorphic** - Works in both browser and Node.js environments
+
+## Installation
+
+::: code-group
+
+```bash [pnpm]
+pnpm add @vielzeug/toolkit
+```
+
+```bash [npm]
+npm install @vielzeug/toolkit
+```
+
+```bash [yarn]
+yarn add @vielzeug/toolkit
+```
+
+:::
+
+## Quick Start
+
+```typescript
+import { chunk, map, retry, pool } from '@vielzeug/toolkit';
+
+// Array operations
+const batches = chunk([1, 2, 3, 4, 5], 2);
+// [[1, 2], [3, 4], [5]]
+
+// Async map with automatic Promise handling
+const users = await map([1, 2, 3], async (id) => fetchUser(id));
+
+// Retry with exponential backoff
+const data = await retry(() => fetch('/api/data').then((r) => r.json()), { times: 3, delay: 1000, backoff: 2 });
+
+// Rate limiting with promise pool
+const apiPool = pool(5); // Max 5 concurrent requests
+const results = await Promise.all(urls.map((url) => apiPool(() => fetch(url))));
+```
+
+## Categories
+
+### 📊 Array (25 utilities)
+
+Transform, filter, group, and manipulate arrays with full type safety.
+
+```typescript
+import { group, uniq, flatten, sort } from '@vielzeug/toolkit';
+
+// Group by property
+const grouped = group(users, (user) => user.role);
+
+// Remove duplicates
+const unique = uniq([1, 2, 2, 3, 3, 3]);
+
+// Flatten nested arrays
+const flat = flatten([
+  [1, 2],
+  [3, [4, 5]],
+]);
+
+// Sort with custom comparator
+const sorted = sort(items, (a, b) => a.price - b.price);
+```
+
+**Available utilities:**
+`aggregate`, `alternate`, `arrange`, `chunk`, `compact`, `contains`, `every`, `filter`, `find`, `findIndex`, `findLast`, `flatten`, `group`, `list`, `map`, `pick`, `reduce`, `remoteList`, `search`, `select`, `shift`, `some`, `sort`, `substitute`, `uniq`
+
+---
+
+### ⚡ Async (11 utilities)
+
+Promise utilities, concurrency control, retries, and async patterns.
+
+```typescript
+import { parallel, queue, waitFor, race, defer } from '@vielzeug/toolkit';
+
+// Process with controlled concurrency
+await parallel(3, urls, async (url) => fetch(url));
+
+// Task queue with monitoring
+const taskQueue = queue({ concurrency: 5 });
+taskQueue.add(() => processTask());
+await taskQueue.onIdle();
+
+// Wait for condition
+await waitFor(() => document.querySelector('#app') !== null);
+
+// Race with minimum delay (better UX)
+const data = await race(fetchData(), 500);
+
+// Externally-controlled promise
+const deferred = defer<string>();
+setTimeout(() => deferred.resolve('Done!'), 1000);
+```
+
+**Available utilities:**
+`attempt`, `defer`, `delay`, `parallel`, `pool`, `predict`, `queue`, `race`, `retry`, `sleep`, `waitFor`
+
+---
+
+### 📅 Date (3 utilities)
+
+Date manipulation and time calculations.
+
+```typescript
+import { interval, timeDiff, expires } from '@vielzeug/toolkit';
+
+// Calculate time intervals
+const days = interval(new Date('2024-01-01'), new Date('2024-12-31'), 'days');
+
+// Time difference
+const diff = timeDiff(date1, date2);
+
+// Check expiration
+if (expires(expiryDate)) {
+  // Handle expired
+}
+```
+
+**Available utilities:**
+`expires`, `interval`, `timeDiff`
+
+---
+
+### ⚙️ Function (14 utilities)
+
+Function composition, memoization, and execution control.
+
+```typescript
+import { debounce, throttle, memo, pipe, curry } from '@vielzeug/toolkit';
+
+// Debounce user input
+const search = debounce((query) => fetchResults(query), 300);
+
+// Throttle scroll events
+const onScroll = throttle(() => updateUI(), 100);
+
+// Memoize expensive calculations
+const fibonacci = memo((n) => (n <= 1 ? n : fibonacci(n - 1) + fibonacci(n - 2)));
+
+// Function composition
+const transform = pipe(
+  (x) => x * 2,
+  (x) => x + 1,
+  (x) => x.toString(),
+);
+
+// Currying
+const add = curry((a, b, c) => a + b + c);
+const add5 = add(5);
+```
+
+**Available utilities:**
+`assert`, `assertParams`, `compare`, `compareBy`, `compose`, `curry`, `debounce`, `fp`, `memo`, `once`, `pipe`, `proxy`, `prune`, `throttle`, `worker`
+
+---
+
+### 🔢 Math (17 utilities)
+
+Mathematical operations, statistics, and calculations.
+
+```typescript
+import { average, median, clamp, range, distribute } from '@vielzeug/toolkit';
+
+// Calculate average
+const avg = average([1, 2, 3, 4, 5]); // 3
+
+// Find median
+const med = median([1, 2, 3, 4, 5]); // 3
+
+// Clamp value to range
+const clamped = clamp(150, 0, 100); // 100
+
+// Generate range
+const numbers = range(1, 10); // [1, 2, 3, ..., 10]
+
+// Distribute amount
+const shares = distribute(100, 3); // [33.33, 33.33, 33.34]
+```
+
+**Available utilities:**
+`abs`, `add`, `allocate`, `average`, `boil`, `clamp`, `distribute`, `divide`, `max`, `median`, `min`, `multiply`, `range`, `rate`, `round`, `subtract`, `sum`
+
+---
+
+### 💰 Money (3 utilities)
+
+Currency formatting and exchange calculations.
+
+```typescript
+import { currency, exchange } from '@vielzeug/toolkit';
+
+// Format currency
+const formatted = currency(1234.56, 'USD'); // "$1,234.56"
+
+// Currency exchange
+const converted = exchange(100, 'USD', 'EUR', 0.85); // 85
+```
+
+**Available utilities:**
+`currency`, `exchange`, `types`
+
+---
+
+### 📦 Object (10 utilities)
+
+Deep merging, cloning, diffing, and object manipulation.
+
+```typescript
+import { merge, clone, diff, path, seek } from '@vielzeug/toolkit';
+
+// Deep merge
+const merged = merge(obj1, obj2);
+
+// Deep clone
+const copy = clone(original);
+
+// Diff objects
+const changes = diff(oldObj, newObj);
+
+// Get nested value
+const value = path(obj, 'user.address.city');
+
+// Search object
+const results = seek(data, (val) => val > 100);
+```
+
+**Available utilities:**
+`cache`, `clone`, `diff`, `entries`, `keys`, `merge`, `parseJSON`, `path`, `seek`, `values`
+
+---
+
+### 🎲 Random (4 utilities)
+
+Random values, shuffling, and UUID generation.
+
+```typescript
+import { random, shuffle, draw, uuid } from '@vielzeug/toolkit';
+
+// Random number
+const num = random(1, 100);
+
+// Shuffle array
+const shuffled = shuffle([1, 2, 3, 4, 5]);
+
+// Draw random items
+const winners = draw(participants, 3);
+
+// Generate UUID
+const id = uuid(); // "550e8400-e29b-41d4-a716-446655440000"
+```
+
+**Available utilities:**
+`draw`, `random`, `shuffle`, `uuid`
+
+---
+
+### 📝 String (6 utilities)
+
+String formatting, case conversion, and similarity.
+
+```typescript
+import { camelCase, kebabCase, pascalCase, snakeCase, truncate, similarity } from '@vielzeug/toolkit';
+
+// Case conversions
+camelCase('hello world'); // "helloWorld"
+kebabCase('hello world'); // "hello-world"
+pascalCase('hello world'); // "HelloWorld"
+snakeCase('hello world'); // "hello_world"
+
+// Truncate text
+truncate('Long text here', 10); // "Long text..."
+
+// String similarity
+similarity('hello', 'hallo'); // 0.8
+```
+
+**Available utilities:**
+`camelCase`, `kebabCase`, `pascalCase`, `similarity`, `snakeCase`, `truncate`
+
+---
+
+### ✅ Typed (27 utilities)
+
+Type guards, type checking, and validation.
+
+```typescript
+import { isString, isArray, isPromise, isEmpty, isEqual } from '@vielzeug/toolkit';
+
+// Type guards with narrowing
+if (isString(value)) {
+  // TypeScript knows value is string
+  console.log(value.toUpperCase());
+}
+
+// Check arrays
+if (isArray(data)) {
+  data.forEach((item) => console.log(item));
+}
+
+// Promise detection
+if (isPromise(result)) {
+  await result;
+}
+
+// Empty check
+if (isEmpty(obj)) {
+  // Handle empty
+}
+
+// Deep equality
+if (isEqual(obj1, obj2)) {
+  // Objects are equal
+}
+```
+
+**Available utilities:**
+`ge`, `gt`, `is`, `isArray`, `isBoolean`, `isDate`, `isDefined`, `isEmpty`, `isEqual`, `isEven`, `isFunction`, `isNegative`, `isNil`, `isNumber`, `isObject`, `isOdd`, `isPositive`, `isPrimitive`, `isPromise`, `isRegex`, `isString`, `isWithin`, `isZero`, `le`, `lt`, `typeOf`
+
+## Real-World Examples
+
+### API Rate Limiting with Retry
+
+```typescript
+import { pool, retry, predict } from '@vielzeug/toolkit';
+
+// Create rate-limited pool
+const apiPool = pool(10); // Max 10 concurrent requests
+
+async function fetchWithRetry(url: string) {
+  return apiPool(() =>
+    retry(
+      () =>
+        predict(
+          async (signal) => {
+            const response = await fetch(url, { signal });
+            if (!response.ok) throw new Error(`HTTP ${response.status}`);
+            return response.json();
+          },
+          { timeout: 5000 },
+        ),
+      { times: 3, delay: 1000, backoff: 2 },
+    ),
+  );
+}
+
+// Process many URLs with rate limiting and retry
+const results = await Promise.all(urls.map((url) => fetchWithRetry(url)));
+```
+
+### Batch Processing with Progress
+
+```typescript
+import { chunk, parallel, sleep } from '@vielzeug/toolkit';
+
+async function processBatch(items: any[], batchSize = 10) {
+  const batches = chunk(items, batchSize);
+  const results = [];
+
+  for (let i = 0; i < batches.length; i++) {
+    console.log(`Processing batch ${i + 1}/${batches.length}`);
+
+    const batchResults = await parallel(3, batches[i], async (item) => {
+      return await processItem(item);
+    });
+
+    results.push(...batchResults);
+
+    // Delay between batches
+    if (i < batches.length - 1) {
+      await sleep(1000);
+    }
+  }
+
+  return results;
+}
+```
+
+### Form Validation Pipeline
+
+```typescript
+import { pipe, curry, isEmpty, isString } from '@vielzeug/toolkit';
+
+const required = (value: any) => {
+  if (isEmpty(value)) throw new Error('Required field');
+  return value;
+};
+
+const minLength = curry((min: number, value: string) => {
+  if (!isString(value) || value.length < min) {
+    throw new Error(`Minimum ${min} characters`);
+  }
+  return value;
+});
+
+const email = (value: string) => {
+  if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value)) {
+    throw new Error('Invalid email');
+  }
+  return value;
+};
+
+// Create validation pipeline
+const validateEmail = pipe(required, minLength(5), email);
+
+try {
+  const validEmail = validateEmail(userInput);
+} catch (error) {
+  console.error(error.message);
+}
+```
+
+## Performance & Bundle Size
+
+### Tree-Shaking
+
+Toolkit is designed for optimal tree-shaking. Import only what you use:
+
+```typescript
+// ✅ Good - Only includes chunk function (~0.5KB gzipped)
+import { chunk } from '@vielzeug/toolkit';
+
+// ⚠️ Avoid - Imports entire library (~35KB gzipped)
+import * as toolkit from '@vielzeug/toolkit';
+```
+
+### Bundle Size by Category
+
+| Category | Utilities | Approx. Size (gzipped) |
+| -------- | --------- | ---------------------- |
+| Array    | 25        | ~8KB                   |
+| Async    | 11        | ~3KB                   |
+| Date     | 3         | ~1KB                   |
+| Function | 14        | ~5KB                   |
+| Math     | 17        | ~4KB                   |
+| Money    | 3         | ~1KB                   |
+| Object   | 10        | ~3KB                   |
+| Random   | 4         | ~1KB                   |
+| String   | 6         | ~2KB                   |
+| Typed    | 27        | ~3KB                   |
+
+> **Note**: Individual utilities are typically **0.1-0.8 KB gzipped** each.
+
+## TypeScript Support
+
+Full TypeScript support with complete type inference:
+
+```typescript
+import { map, filter, group } from '@vielzeug/toolkit';
+
+const numbers = [1, 2, 3, 4, 5];
+
+// Type inferred as number[]
+const doubled = map(numbers, (n) => n * 2);
+
+// Type inferred as number[]
+const evens = filter(numbers, (n) => n % 2 === 0);
+
+// Type inferred as Record<string, User[]>
+const byRole = group(users, (u) => u.role);
+
+// Async operations automatically return Promise
+const results = await map(ids, async (id) => fetchUser(id));
+// Type: Promise<User[]>
+```
+
+## Comparison with Alternatives
+
+| Feature                | Toolkit          | Lodash            | Ramda             | Native JS  |
+| ---------------------- | ---------------- | ----------------- | ----------------- | ---------- |
+| TypeScript Support     | ✅ First-class   | ⚠️ Via @types     | ⚠️ Via @types     | ❌ Limited |
+| Tree-shakeable         | ✅ By default    | ⚠️ lodash-es only | ✅ Yes            | N/A        |
+| Bundle Size (min+gzip) | ~0.1-1KB/utility | ~24KB (full)      | ~12KB (full)      | 0KB        |
+| Dependencies           | 0                | 0                 | 0                 | N/A        |
+| Async Support          | ✅ Built-in      | ❌ Limited        | ❌ Limited        | ⚠️ Manual  |
+| Learning Curve         | Low              | Low               | High (FP focused) | Low        |
+
+## Documentation
+
+- **[Full Documentation](https://helmuthdu.github.io/vielzeug/toolkit/)**
+- **[API Reference](https://helmuthdu.github.io/vielzeug/toolkit/api)**
+- **[Usage Guide](https://helmuthdu.github.io/vielzeug/toolkit/usage)**
+- **[Examples](https://helmuthdu.github.io/vielzeug/toolkit/examples/array)**
+
+## Contributing
+
+We welcome contributions! Please see our [Contributing Guide](../../CONTRIBUTING.md) for details.
+
+### Development
+
+```bash
+# Install dependencies
+pnpm install
+
+# Build the package
+pnpm build
+
+# Run tests
+pnpm test
+
+# Run tests in watch mode
+pnpm test:watch
+
+# Type check
+pnpm typecheck
+```
+
+## License
+
+MIT © [Helmuth Saatkamp](https://github.com/helmuthdu/vielzeug)
+
+## Related Packages
+
+Part of the [@vielzeug](https://helmuthdu.github.io/vielzeug/) monorepo:
+
+- **[@vielzeug/deposit](../deposit)** - Type-safe local storage with schemas and expiration
+- **[@vielzeug/fetchit](../fetchit)** - Advanced HTTP client with caching and retries
+- **[@vielzeug/formit](../formit)** - Type-safe form state and validation
+- **[@vielzeug/i18nit](../i18nit)** - Internationalization with TypeScript
+- **[@vielzeug/logit](../logit)** - Beautiful console logging
+- **[@vielzeug/permit](../permit)** - Role-based access control
+- **[@vielzeug/validit](../validit)** - Type-safe validation schemas

package/dist/async/attempt.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"attempt.cjs","sources":["../../src/async/attempt.ts"],"sourcesContent":["import { Logit } from '@vielzeug/logit';\nimport type { Fn } from '../types';\nimport { predict } from './predict';\nimport { retry } from './retry';\n\ntype AttemptOptions = {\n  identifier?: string;\n  retries?: number;\n  silent?: boolean;\n  timeout?: number;\n};\n\n/**\n * Attempts to execute a function with advanced error handling and retry logic.\n *\n * @example\n * ```ts\n * const unreliableFunction = async () => {\n *   if (Math.random() < 0.7) throw new Error ('Random failure');\n *   return 'Success!';\n * };\n *\n * await attempt(\n *   unreliableFunction,\n *   { retries: 3, silent: false, timeout: 5000 }); // Success! (or undefined if all attempts failed)\n * ```\n *\n * @param fn - The function to be executed.\n * @param [options] - Configuration options for the attempt.\n * @param [options.identifier] - Custom identifier for logging purposes.\n * @param [options.retries=0] - Number of retry attempts if the function fails.\n * @param [options.silent=false] - If true, suppresses error logging.\n * @param [options.timeout=7000] - Timeout in milliseconds for function execution.\n *\n * @returns The result of the function or undefined if it failed.\n */\nexport async function attempt<T extends Fn, R = Awaited<ReturnType<T>>>(\n  fn: T,\n  { silent = false, retries = 0, timeout = 7000, identifier = fn.name || 'anonymous function' }: AttemptOptions = {},\n): Promise<R | undefined> {\n  try {\n    return await retry(() => predict<R>(() => fn(), { timeout }), { times: retries + 1 });\n  } catch (err) {\n    if (!silent) {\n      Logit.error(`attempt(${identifier}) -> all attempts failed`, { cause: err });\n    }\n    return undefined;\n  }\n}\n"],"names":["attempt","fn","silent","retries","timeout","identifier","retry","predict","err","Logit"],"mappings":"+KAoCA,eAAsBA,EACpBC,EACA,CAAE,OAAAC,EAAS,GAAO,QAAAC,EAAU,EAAG,QAAAC,EAAU,IAAM,WAAAC,EAAaJ,EAAG,MAAQ,oBAAA,EAAyC,CAAA,EACxF,CACxB,GAAI,CACF,OAAO,MAAMK,EAAAA,MAAM,IAAMC,EAAAA,QAAW,IAAMN,EAAA,EAAM,CAAE,QAAAG,CAAA,CAAS,EAAG,CAAE,MAAOD,EAAU,EAAG,CACtF,OAASK,EAAK,CACPN,GACHO,QAAM,MAAM,WAAWJ,CAAU,2BAA4B,CAAE,MAAOG,EAAK,EAE7E,MACF,CACF"}

package/dist/async/attempt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"attempt.js","sources":["../../src/async/attempt.ts"],"sourcesContent":["import { Logit } from '@vielzeug/logit';\nimport type { Fn } from '../types';\nimport { predict } from './predict';\nimport { retry } from './retry';\n\ntype AttemptOptions = {\n  identifier?: string;\n  retries?: number;\n  silent?: boolean;\n  timeout?: number;\n};\n\n/**\n * Attempts to execute a function with advanced error handling and retry logic.\n *\n * @example\n * ```ts\n * const unreliableFunction = async () => {\n *   if (Math.random() < 0.7) throw new Error ('Random failure');\n *   return 'Success!';\n * };\n *\n * await attempt(\n *   unreliableFunction,\n *   { retries: 3, silent: false, timeout: 5000 }); // Success! (or undefined if all attempts failed)\n * ```\n *\n * @param fn - The function to be executed.\n * @param [options] - Configuration options for the attempt.\n * @param [options.identifier] - Custom identifier for logging purposes.\n * @param [options.retries=0] - Number of retry attempts if the function fails.\n * @param [options.silent=false] - If true, suppresses error logging.\n * @param [options.timeout=7000] - Timeout in milliseconds for function execution.\n *\n * @returns The result of the function or undefined if it failed.\n */\nexport async function attempt<T extends Fn, R = Awaited<ReturnType<T>>>(\n  fn: T,\n  { silent = false, retries = 0, timeout = 7000, identifier = fn.name || 'anonymous function' }: AttemptOptions = {},\n): Promise<R | undefined> {\n  try {\n    return await retry(() => predict<R>(() => fn(), { timeout }), { times: retries + 1 });\n  } catch (err) {\n    if (!silent) {\n      Logit.error(`attempt(${identifier}) -> all attempts failed`, { cause: err });\n    }\n    return undefined;\n  }\n}\n"],"names":["attempt","fn","silent","retries","timeout","identifier","retry","predict","err","Logit"],"mappings":";;;AAoCA,eAAsBA,EACpBC,GACA,EAAE,QAAAC,IAAS,IAAO,SAAAC,IAAU,GAAG,SAAAC,IAAU,KAAM,YAAAC,IAAaJ,EAAG,QAAQ,qBAAA,IAAyC,CAAA,GACxF;AACxB,MAAI;AACF,WAAO,MAAMK,EAAM,MAAMC,EAAW,MAAMN,EAAA,GAAM,EAAE,SAAAG,EAAA,CAAS,GAAG,EAAE,OAAOD,IAAU,GAAG;AAAA,EACtF,SAASK,GAAK;AACZ,IAAKN,KACHO,EAAM,MAAM,WAAWJ,CAAU,4BAA4B,EAAE,OAAOG,GAAK;AAE7E;AAAA,EACF;AACF;"}

package/dist/async/defer.cjs

@@ -0,0 +1,2 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});function i(){let e,r;return{promise:new Promise((t,o)=>{e=t,r=o}),reject:r,resolve:e}}exports.defer=i;
+//# sourceMappingURL=defer.cjs.map

package/dist/async/defer.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"defer.cjs","sources":["../../src/async/defer.ts"],"sourcesContent":["/**\n * Creates a deferred promise with resolve and reject methods exposed.\n * Useful for creating promises that are resolved/rejected externally.\n *\n * @example\n * ```ts\n * const deferred = defer<string>();\n *\n * setTimeout(() => {\n *   deferred.resolve('Done!');\n * }, 1000);\n *\n * const result = await deferred.promise; // 'Done!'\n * ```\n *\n * @returns Object with promise and resolve/reject methods\n */\nexport function defer<T = void>(): {\n  promise: Promise<T>;\n  resolve: (value: T | PromiseLike<T>) => void;\n  reject: (reason?: unknown) => void;\n} {\n  let resolve!: (value: T | PromiseLike<T>) => void;\n  let reject!: (reason?: unknown) => void;\n\n  const promise = new Promise<T>((res, rej) => {\n    resolve = res;\n    reject = rej;\n  });\n\n  return { promise, reject, resolve };\n}\n"],"names":["defer","resolve","reject","res","rej"],"mappings":"gFAiBO,SAASA,GAId,CACA,IAAIC,EACAC,EAOJ,MAAO,CAAE,QALO,IAAI,QAAW,CAACC,EAAKC,IAAQ,CAC3CH,EAAUE,EACVD,EAASE,CACX,CAAC,EAEiB,OAAAF,EAAQ,QAAAD,CAAA,CAC5B"}

package/dist/async/defer.js

@@ -0,0 +1,10 @@
+function s() {
+  let e, r;
+  return { promise: new Promise((o, t) => {
+    e = o, r = t;
+  }), reject: r, resolve: e };
+}
+export {
+  s as defer
+};
+//# sourceMappingURL=defer.js.map

package/dist/async/defer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"defer.js","sources":["../../src/async/defer.ts"],"sourcesContent":["/**\n * Creates a deferred promise with resolve and reject methods exposed.\n * Useful for creating promises that are resolved/rejected externally.\n *\n * @example\n * ```ts\n * const deferred = defer<string>();\n *\n * setTimeout(() => {\n *   deferred.resolve('Done!');\n * }, 1000);\n *\n * const result = await deferred.promise; // 'Done!'\n * ```\n *\n * @returns Object with promise and resolve/reject methods\n */\nexport function defer<T = void>(): {\n  promise: Promise<T>;\n  resolve: (value: T | PromiseLike<T>) => void;\n  reject: (reason?: unknown) => void;\n} {\n  let resolve!: (value: T | PromiseLike<T>) => void;\n  let reject!: (reason?: unknown) => void;\n\n  const promise = new Promise<T>((res, rej) => {\n    resolve = res;\n    reject = rej;\n  });\n\n  return { promise, reject, resolve };\n}\n"],"names":["defer","resolve","reject","res","rej"],"mappings":"AAiBO,SAASA,IAId;AACA,MAAIC,GACAC;AAOJ,SAAO,EAAE,SALO,IAAI,QAAW,CAACC,GAAKC,MAAQ;AAC3C,IAAAH,IAAUE,GACVD,IAASE;AAAA,EACX,CAAC,GAEiB,QAAAF,GAAQ,SAAAD,EAAA;AAC5B;"}

package/dist/async/delay.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"delay.cjs","sources":["../../src/async/delay.ts"],"sourcesContent":["import type { Fn } from '../types';\nimport { sleep } from './sleep';\n\n/**\n * Delays the execution of a function by a specified amount of time.\n *\n * @example\n * ```ts\n * const log = () => console.log('Hello, world!');\n *\n * delay(log, 1000); // logs 'Hello, world!' after 1 second\n * ```\n *\n * @param fn - The function to be delayed.\n * @param delay - The amount of time to delay the function execution, in milliseconds. Default is 700.\n *\n * @returns A Promise that resolves with the result of the function execution.\n */\nexport async function delay<T extends Fn>(fn: T, delay = 700) {\n  await sleep(delay);\n\n  return fn();\n}\n"],"names":["delay","fn","sleep"],"mappings":"+GAkBA,eAAsBA,EAAoBC,EAAOD,EAAQ,IAAK,CAC5D,aAAME,EAAAA,MAAMF,CAAK,EAEVC,EAAA,CACT"}

package/dist/async/delay.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"delay.js","sources":["../../src/async/delay.ts"],"sourcesContent":["import type { Fn } from '../types';\nimport { sleep } from './sleep';\n\n/**\n * Delays the execution of a function by a specified amount of time.\n *\n * @example\n * ```ts\n * const log = () => console.log('Hello, world!');\n *\n * delay(log, 1000); // logs 'Hello, world!' after 1 second\n * ```\n *\n * @param fn - The function to be delayed.\n * @param delay - The amount of time to delay the function execution, in milliseconds. Default is 700.\n *\n * @returns A Promise that resolves with the result of the function execution.\n */\nexport async function delay<T extends Fn>(fn: T, delay = 700) {\n  await sleep(delay);\n\n  return fn();\n}\n"],"names":["delay","fn","sleep"],"mappings":";AAkBA,eAAsBA,EAAoBC,GAAOD,IAAQ,KAAK;AAC5D,eAAME,EAAMF,CAAK,GAEVC,EAAA;AACT;"}

package/dist/async/parallel.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"parallel.cjs","sources":["../../src/async/parallel.ts"],"sourcesContent":["/**\n * Processes an array with an async callback with controlled parallelism.\n * Similar to Promise.all, but limits how many items are processed concurrently.\n * Returns an ordered array of results.\n *\n * @example\n * ```ts\n * // Process 3 items at a time\n * const results = await parallel(3, [1, 2, 3, 4, 5], async (n) => {\n *   await delay(100);\n *   return n * 2;\n * });\n * // [2, 4, 6, 8, 10]\n *\n * // With abort signal\n * const controller = new AbortController();\n * const results = await parallel(2, items, async (item) => {\n *   return processItem(item);\n * }, controller.signal);\n * ```\n *\n * @param limit - Maximum number of concurrent operations (must be >= 1)\n * @param array - Array of items to process\n * @param callback - Async function to process each item\n * @param signal - Optional AbortSignal to cancel processing\n * @returns Promise resolving to an ordered array of results\n * @throws {Error} If limit is less than 1\n * @throws {DOMException} If aborted via signal\n */\nexport async function parallel<T, R>(\n  limit: number,\n  array: T[],\n  callback: (item: T, index: number, array: T[]) => Promise<R>,\n  signal?: AbortSignal,\n): Promise<R[]> {\n  if (limit < 1) {\n    throw new Error('Limit must be at least 1');\n  }\n\n  if (signal?.aborted) {\n    throw new DOMException('Aborted', 'AbortError');\n  }\n\n  const results: R[] = new Array(array.length);\n  let currentIndex = 0;\n  let hasError = false;\n  let error: unknown;\n\n  // Check for abort\n  const checkAbort = () => {\n    if (signal?.aborted) {\n      hasError = true;\n      error = new DOMException('Aborted', 'AbortError');\n      return true;\n    }\n    return false;\n  };\n\n  // Worker function that processes items from the queue\n  const worker = async (): Promise<void> => {\n    while (currentIndex < array.length && !hasError) {\n      if (checkAbort()) {\n        break;\n      }\n\n      const index = currentIndex++;\n\n      try {\n        results[index] = await callback(array[index], index, array);\n      } catch (err) {\n        hasError = true;\n        error = err;\n        break;\n      }\n    }\n  };\n\n  // Create workers up to the limit\n  const workers: Promise<void>[] = [];\n  const workerCount = Math.min(limit, array.length);\n\n  for (let i = 0; i < workerCount; i++) {\n    workers.push(worker());\n  }\n\n  // Wait for all workers to complete\n  await Promise.all(workers);\n\n  // If there was an error, throw it\n  if (hasError) {\n    throw error;\n  }\n\n  return results;\n}\n"],"names":["parallel","limit","array","callback","signal","results","currentIndex","hasError","error","checkAbort","worker","index","err","workers","workerCount","i"],"mappings":"gFA6BA,eAAsBA,EACpBC,EACAC,EACAC,EACAC,EACc,CACd,GAAIH,EAAQ,EACV,MAAM,IAAI,MAAM,0BAA0B,EAG5C,GAAIG,GAAQ,QACV,MAAM,IAAI,aAAa,UAAW,YAAY,EAGhD,MAAMC,EAAe,IAAI,MAAMH,EAAM,MAAM,EAC3C,IAAII,EAAe,EACfC,EAAW,GACXC,EAGJ,MAAMC,EAAa,IACbL,GAAQ,SACVG,EAAW,GACXC,EAAQ,IAAI,aAAa,UAAW,YAAY,EACzC,IAEF,GAIHE,EAAS,SAA2B,CACxC,KAAOJ,EAAeJ,EAAM,QAAU,CAACK,GACjC,CAAAE,KAD2C,CAK/C,MAAME,EAAQL,IAEd,GAAI,CACFD,EAAQM,CAAK,EAAI,MAAMR,EAASD,EAAMS,CAAK,EAAGA,EAAOT,CAAK,CAC5D,OAASU,EAAK,CACZL,EAAW,GACXC,EAAQI,EACR,KACF,CACF,CACF,EAGMC,EAA2B,CAAA,EAC3BC,EAAc,KAAK,IAAIb,EAAOC,EAAM,MAAM,EAEhD,QAASa,EAAI,EAAGA,EAAID,EAAaC,IAC/BF,EAAQ,KAAKH,GAAQ,EAOvB,GAHA,MAAM,QAAQ,IAAIG,CAAO,EAGrBN,EACF,MAAMC,EAGR,OAAOH,CACT"}

package/dist/async/parallel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parallel.js","sources":["../../src/async/parallel.ts"],"sourcesContent":["/**\n * Processes an array with an async callback with controlled parallelism.\n * Similar to Promise.all, but limits how many items are processed concurrently.\n * Returns an ordered array of results.\n *\n * @example\n * ```ts\n * // Process 3 items at a time\n * const results = await parallel(3, [1, 2, 3, 4, 5], async (n) => {\n *   await delay(100);\n *   return n * 2;\n * });\n * // [2, 4, 6, 8, 10]\n *\n * // With abort signal\n * const controller = new AbortController();\n * const results = await parallel(2, items, async (item) => {\n *   return processItem(item);\n * }, controller.signal);\n * ```\n *\n * @param limit - Maximum number of concurrent operations (must be >= 1)\n * @param array - Array of items to process\n * @param callback - Async function to process each item\n * @param signal - Optional AbortSignal to cancel processing\n * @returns Promise resolving to an ordered array of results\n * @throws {Error} If limit is less than 1\n * @throws {DOMException} If aborted via signal\n */\nexport async function parallel<T, R>(\n  limit: number,\n  array: T[],\n  callback: (item: T, index: number, array: T[]) => Promise<R>,\n  signal?: AbortSignal,\n): Promise<R[]> {\n  if (limit < 1) {\n    throw new Error('Limit must be at least 1');\n  }\n\n  if (signal?.aborted) {\n    throw new DOMException('Aborted', 'AbortError');\n  }\n\n  const results: R[] = new Array(array.length);\n  let currentIndex = 0;\n  let hasError = false;\n  let error: unknown;\n\n  // Check for abort\n  const checkAbort = () => {\n    if (signal?.aborted) {\n      hasError = true;\n      error = new DOMException('Aborted', 'AbortError');\n      return true;\n    }\n    return false;\n  };\n\n  // Worker function that processes items from the queue\n  const worker = async (): Promise<void> => {\n    while (currentIndex < array.length && !hasError) {\n      if (checkAbort()) {\n        break;\n      }\n\n      const index = currentIndex++;\n\n      try {\n        results[index] = await callback(array[index], index, array);\n      } catch (err) {\n        hasError = true;\n        error = err;\n        break;\n      }\n    }\n  };\n\n  // Create workers up to the limit\n  const workers: Promise<void>[] = [];\n  const workerCount = Math.min(limit, array.length);\n\n  for (let i = 0; i < workerCount; i++) {\n    workers.push(worker());\n  }\n\n  // Wait for all workers to complete\n  await Promise.all(workers);\n\n  // If there was an error, throw it\n  if (hasError) {\n    throw error;\n  }\n\n  return results;\n}\n"],"names":["parallel","limit","array","callback","signal","results","currentIndex","hasError","error","checkAbort","worker","index","err","workers","workerCount","i"],"mappings":"AA6BA,eAAsBA,EACpBC,GACAC,GACAC,GACAC,GACc;AACd,MAAIH,IAAQ;AACV,UAAM,IAAI,MAAM,0BAA0B;AAG5C,MAAIG,GAAQ;AACV,UAAM,IAAI,aAAa,WAAW,YAAY;AAGhD,QAAMC,IAAe,IAAI,MAAMH,EAAM,MAAM;AAC3C,MAAII,IAAe,GACfC,IAAW,IACXC;AAGJ,QAAMC,IAAa,MACbL,GAAQ,WACVG,IAAW,IACXC,IAAQ,IAAI,aAAa,WAAW,YAAY,GACzC,MAEF,IAIHE,IAAS,YAA2B;AACxC,WAAOJ,IAAeJ,EAAM,UAAU,CAACK,KACjC,CAAAE,OAD2C;AAK/C,YAAME,IAAQL;AAEd,UAAI;AACF,QAAAD,EAAQM,CAAK,IAAI,MAAMR,EAASD,EAAMS,CAAK,GAAGA,GAAOT,CAAK;AAAA,MAC5D,SAASU,GAAK;AACZ,QAAAL,IAAW,IACXC,IAAQI;AACR;AAAA,MACF;AAAA,IACF;AAAA,EACF,GAGMC,IAA2B,CAAA,GAC3BC,IAAc,KAAK,IAAIb,GAAOC,EAAM,MAAM;AAEhD,WAASa,IAAI,GAAGA,IAAID,GAAaC;AAC/B,IAAAF,EAAQ,KAAKH,GAAQ;AAOvB,MAHA,MAAM,QAAQ,IAAIG,CAAO,GAGrBN;AACF,UAAMC;AAGR,SAAOH;AACT;"}

package/dist/async/pool.cjs

@@ -0,0 +1,2 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const a=require("../function/assert.cjs");function u(e){a.assert(e>=1,"Pool limit must be at least 1",{args:{limit:e},type:RangeError});let t=0;const n=[],r=()=>{n.length>0&&t<e&&n.shift()?.()};return async o=>{for(;t>=e;)await new Promise(s=>n.push(s));t++;try{return await o()}finally{t--,r()}}}exports.pool=u;
+//# sourceMappingURL=pool.cjs.map

package/dist/async/pool.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"pool.cjs","sources":["../../src/async/pool.ts"],"sourcesContent":["import { assert } from '../function/assert';\n\n/**\n * Creates a promise pool that limits the number of concurrent promises.\n * Useful for rate limiting API calls or controlling resource usage.\n *\n * @example\n * ```ts\n * const requestPool = pool(3);\n *\n * const results = await Promise.all([\n *   requestPool(() => fetch('/api/1')),\n *   requestPool(() => fetch('/api/2')),\n *   requestPool(() => fetch('/api/3')),\n *   requestPool(() => fetch('/api/4')), // Will wait for one of the above to finish\n * ]);\n * ```\n *\n * @param limit - Maximum number of concurrent promises\n * @returns Function that accepts a promise-returning function and executes it when a slot is available\n */\nexport function pool(limit: number): <T>(fn: () => Promise<T>) => Promise<T> {\n  assert(limit >= 1, 'Pool limit must be at least 1', { args: { limit }, type: RangeError });\n\n  let activeCount = 0;\n  const queue: Array<() => void> = [];\n\n  const dequeue = (): void => {\n    if (queue.length > 0 && activeCount < limit) {\n      const next = queue.shift();\n      next?.();\n    }\n  };\n\n  return async <T>(fn: () => Promise<T>): Promise<T> => {\n    while (activeCount >= limit) {\n      await new Promise<void>((resolve) => queue.push(resolve));\n    }\n\n    activeCount++;\n\n    try {\n      return await fn();\n    } finally {\n      activeCount--;\n      dequeue();\n    }\n  };\n}\n"],"names":["pool","limit","assert","activeCount","queue","dequeue","fn","resolve"],"mappings":"0HAqBO,SAASA,EAAKC,EAAwD,CAC3EC,SAAOD,GAAS,EAAG,gCAAiC,CAAE,KAAM,CAAE,MAAAA,CAAA,EAAS,KAAM,WAAY,EAEzF,IAAIE,EAAc,EAClB,MAAMC,EAA2B,CAAA,EAE3BC,EAAU,IAAY,CACtBD,EAAM,OAAS,GAAKD,EAAcF,GACvBG,EAAM,MAAA,IACnB,CAEJ,EAEA,MAAO,OAAUE,GAAqC,CACpD,KAAOH,GAAeF,GACpB,MAAM,IAAI,QAAeM,GAAYH,EAAM,KAAKG,CAAO,CAAC,EAG1DJ,IAEA,GAAI,CACF,OAAO,MAAMG,EAAA,CACf,QAAA,CACEH,IACAE,EAAA,CACF,CACF,CACF"}

package/dist/async/pool.js

@@ -0,0 +1,22 @@
+import { assert as s } from "../function/assert.js";
+function c(e) {
+  s(e >= 1, "Pool limit must be at least 1", { args: { limit: e }, type: RangeError });
+  let t = 0;
+  const n = [], r = () => {
+    n.length > 0 && t < e && n.shift()?.();
+  };
+  return async (o) => {
+    for (; t >= e; )
+      await new Promise((a) => n.push(a));
+    t++;
+    try {
+      return await o();
+    } finally {
+      t--, r();
+    }
+  };
+}
+export {
+  c as pool
+};
+//# sourceMappingURL=pool.js.map

package/dist/async/pool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pool.js","sources":["../../src/async/pool.ts"],"sourcesContent":["import { assert } from '../function/assert';\n\n/**\n * Creates a promise pool that limits the number of concurrent promises.\n * Useful for rate limiting API calls or controlling resource usage.\n *\n * @example\n * ```ts\n * const requestPool = pool(3);\n *\n * const results = await Promise.all([\n *   requestPool(() => fetch('/api/1')),\n *   requestPool(() => fetch('/api/2')),\n *   requestPool(() => fetch('/api/3')),\n *   requestPool(() => fetch('/api/4')), // Will wait for one of the above to finish\n * ]);\n * ```\n *\n * @param limit - Maximum number of concurrent promises\n * @returns Function that accepts a promise-returning function and executes it when a slot is available\n */\nexport function pool(limit: number): <T>(fn: () => Promise<T>) => Promise<T> {\n  assert(limit >= 1, 'Pool limit must be at least 1', { args: { limit }, type: RangeError });\n\n  let activeCount = 0;\n  const queue: Array<() => void> = [];\n\n  const dequeue = (): void => {\n    if (queue.length > 0 && activeCount < limit) {\n      const next = queue.shift();\n      next?.();\n    }\n  };\n\n  return async <T>(fn: () => Promise<T>): Promise<T> => {\n    while (activeCount >= limit) {\n      await new Promise<void>((resolve) => queue.push(resolve));\n    }\n\n    activeCount++;\n\n    try {\n      return await fn();\n    } finally {\n      activeCount--;\n      dequeue();\n    }\n  };\n}\n"],"names":["pool","limit","assert","activeCount","queue","dequeue","fn","resolve"],"mappings":";AAqBO,SAASA,EAAKC,GAAwD;AAC3E,EAAAC,EAAOD,KAAS,GAAG,iCAAiC,EAAE,MAAM,EAAE,OAAAA,EAAA,GAAS,MAAM,YAAY;AAEzF,MAAIE,IAAc;AAClB,QAAMC,IAA2B,CAAA,GAE3BC,IAAU,MAAY;AAC1B,IAAID,EAAM,SAAS,KAAKD,IAAcF,KACvBG,EAAM,MAAA,IACnB;AAAA,EAEJ;AAEA,SAAO,OAAUE,MAAqC;AACpD,WAAOH,KAAeF;AACpB,YAAM,IAAI,QAAc,CAACM,MAAYH,EAAM,KAAKG,CAAO,CAAC;AAG1D,IAAAJ;AAEA,QAAI;AACF,aAAO,MAAMG,EAAA;AAAA,IACf,UAAA;AACE,MAAAH,KACAE,EAAA;AAAA,IACF;AAAA,EACF;AACF;"}

package/dist/async/predict.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"predict.cjs","sources":["../../src/async/predict.ts"],"sourcesContent":["/**\n * Creates a Promise that can be aborted using an AbortController.\n *\n * @example\n * ```ts\n * const slowFn = () => new Promise(resolve => setTimeout(() => resolve('slow'), 10000));\n * const fastFn = () => new Promise(resolve => setTimeout(() => resolve('fast'), 5000));\n *\n * predict(slowFn); // rejects after 7 seconds\n * predict(fastFn); // resolves with 'fast' after 5 seconds\n * ```\n *\n * @param fn - The function to execute, which receives an AbortSignal.\n * @param options - The options for the abortable function.\n * @param [options.signal] - The AbortSignal to use for aborting the Promise.\n * @param [options.timeout=7000] - The timeout in milliseconds after which the Promise will be aborted.\n *\n * @returns - A Promise that resolves with the result of the callback or rejects if aborted.\n */\nexport function predict<T>(\n  fn: (signal: AbortSignal) => Promise<T>,\n  options: { signal?: AbortSignal; timeout?: number } = {},\n): Promise<T> {\n  const { signal, timeout = 7000 } = options;\n  const abortSignal = signal ? AbortSignal.any([AbortSignal.timeout(timeout), signal]) : AbortSignal.timeout(timeout);\n\n  return Promise.race([\n    fn(abortSignal),\n    new Promise<never>((_, reject) => {\n      abortSignal.addEventListener('abort', () => reject(new Error('Operation aborted')), { once: true });\n    }),\n  ]);\n}\n"],"names":["predict","fn","options","signal","timeout","abortSignal","_","reject"],"mappings":"gFAmBO,SAASA,EACdC,EACAC,EAAsD,GAC1C,CACZ,KAAM,CAAE,OAAAC,EAAQ,QAAAC,EAAU,GAAA,EAASF,EAC7BG,EAAcF,EAAS,YAAY,IAAI,CAAC,YAAY,QAAQC,CAAO,EAAGD,CAAM,CAAC,EAAI,YAAY,QAAQC,CAAO,EAElH,OAAO,QAAQ,KAAK,CAClBH,EAAGI,CAAW,EACd,IAAI,QAAe,CAACC,EAAGC,IAAW,CAChCF,EAAY,iBAAiB,QAAS,IAAME,EAAO,IAAI,MAAM,mBAAmB,CAAC,EAAG,CAAE,KAAM,EAAA,CAAM,CACpG,CAAC,CAAA,CACF,CACH"}

package/dist/async/predict.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"predict.js","sources":["../../src/async/predict.ts"],"sourcesContent":["/**\n * Creates a Promise that can be aborted using an AbortController.\n *\n * @example\n * ```ts\n * const slowFn = () => new Promise(resolve => setTimeout(() => resolve('slow'), 10000));\n * const fastFn = () => new Promise(resolve => setTimeout(() => resolve('fast'), 5000));\n *\n * predict(slowFn); // rejects after 7 seconds\n * predict(fastFn); // resolves with 'fast' after 5 seconds\n * ```\n *\n * @param fn - The function to execute, which receives an AbortSignal.\n * @param options - The options for the abortable function.\n * @param [options.signal] - The AbortSignal to use for aborting the Promise.\n * @param [options.timeout=7000] - The timeout in milliseconds after which the Promise will be aborted.\n *\n * @returns - A Promise that resolves with the result of the callback or rejects if aborted.\n */\nexport function predict<T>(\n  fn: (signal: AbortSignal) => Promise<T>,\n  options: { signal?: AbortSignal; timeout?: number } = {},\n): Promise<T> {\n  const { signal, timeout = 7000 } = options;\n  const abortSignal = signal ? AbortSignal.any([AbortSignal.timeout(timeout), signal]) : AbortSignal.timeout(timeout);\n\n  return Promise.race([\n    fn(abortSignal),\n    new Promise<never>((_, reject) => {\n      abortSignal.addEventListener('abort', () => reject(new Error('Operation aborted')), { once: true });\n    }),\n  ]);\n}\n"],"names":["predict","fn","options","signal","timeout","abortSignal","_","reject"],"mappings":"AAmBO,SAASA,EACdC,GACAC,IAAsD,IAC1C;AACZ,QAAM,EAAE,QAAAC,GAAQ,SAAAC,IAAU,IAAA,IAASF,GAC7BG,IAAcF,IAAS,YAAY,IAAI,CAAC,YAAY,QAAQC,CAAO,GAAGD,CAAM,CAAC,IAAI,YAAY,QAAQC,CAAO;AAElH,SAAO,QAAQ,KAAK;AAAA,IAClBH,EAAGI,CAAW;AAAA,IACd,IAAI,QAAe,CAACC,GAAGC,MAAW;AAChC,MAAAF,EAAY,iBAAiB,SAAS,MAAME,EAAO,IAAI,MAAM,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAA,CAAM;AAAA,IACpG,CAAC;AAAA,EAAA,CACF;AACH;"}