@satoshibits/functional 1.0.2

package/README.md

@@ -0,0 +1,242 @@
+# Functional Library
+
+A comprehensive collection of functional programming utilities for TypeScript, designed to promote immutability, composability, and type safety.
+
+## Overview
+
+This library provides a set of pure, composable functions that follow functional programming principles. All utilities are designed to be tree-shakeable, type-safe, and optimized for performance.
+
+## Architecture Principles
+
+- **Pure Functions**: All utilities are pure functions with no side effects
+- **Immutability**: Functions never mutate input data, always returning new values
+- **Composability**: Designed to work together through function composition
+- **Type Safety**: Full TypeScript support with comprehensive type inference
+- **Tree-Shaking**: No barrel exports - import directly from specific modules
+- **Performance**: Optimized implementations with minimal overhead
+
+## Modules
+
+### `array-utils.mts`
+
+Functional utilities for array manipulation and transformation.
+
+**Functions:**
+
+- `mapWithIndex` - Map with access to element index
+- `filterMap` - Combined filter and map in a single pass
+- `chunk` - Split array into chunks of specified size
+- `groupBy` - Group elements by a key function
+- `findSafe` - Type-safe array element finder returning Result type
+- `partition` - Split array into two based on predicate
+
+### `object-utils.mts`
+
+Utilities for immutable object operations.
+
+**Functions:**
+
+- `mapValues` - Transform object values while preserving keys
+- `pick` - Create new object with selected keys
+- `omit` - Create new object without specified keys
+- `merge` - Deep merge objects with type safety
+
+### `composition.mts`
+
+Core function composition utilities.
+
+**Functions:**
+
+- `pipe` - Left-to-right function composition
+- `pipeAsync` - Async function pipeline
+- `compose` - Right-to-left function composition
+- `composeAsync` - Async function composition
+- `flow` - Type-safe variadic pipe
+- `flowAsync` - Type-safe variadic async pipe
+- `tap` - Side effect injection
+- `curry` - Function currying
+- `partial` - Partial application
+- `flip` - Flip function arguments
+- `memoize` - Function memoization
+- `constant` - Create constant function
+- `identity` - Identity function
+- `noop` - No-operation function
+
+### `predicates.mts`
+
+Predicate functions and logical combinators.
+
+**Functions:**
+
+- `and` - Logical AND combinator
+- `or` - Logical OR combinator
+- `not` - Logical NOT combinator
+- `xor` - Logical XOR combinator
+- `isNil` - Check for null or undefined
+- `isNotNil` - Check for non-null/undefined
+- `isEmpty` - Check for empty values
+- `isNotEmpty` - Check for non-empty values
+- `equals` - Deep equality check
+- `oneOf` - Check if value is in array
+- `inRange` - Check if number is in range
+- `matches` - Partial object matching
+- `hasProperty` - Property existence check
+- `includes` - Substring/array element check
+- `alwaysTrue` - Constant true predicate
+- `alwaysFalse` - Constant false predicate
+
+### `performance.mts`
+
+Performance optimization utilities.
+
+**Functions:**
+
+- `debounce` - Delay function execution
+- `throttle` - Rate limit function calls
+- `batchAsync` - Batch async operations
+- `performanceUtils.measure` - Measure function execution time
+
+### `pipeline.mts`
+
+Fluent pipeline API for chaining operations.
+
+**Class:**
+
+- `Pipeline` - Chainable transformation pipeline with methods:
+  - `map` - Transform value
+  - `flatMap` - Transform and flatten
+  - `filter` - Conditional transformation
+  - `tap` - Side effects
+  - `pipeAsync` - Async transformations
+  - `value` - Extract final value
+
+### `result.mts`
+
+Result type for explicit error handling without exceptions.
+
+**Types & Functions:**
+
+- `Result<T, E>` - Success or error union type
+- `Result.ok` - Create success result
+- `Result.err` - Create error result
+- `Result.map` - Transform success value
+- `Result.mapError` - Transform error value
+- `Result.chain` - Monadic bind
+- `Result.match` - Pattern matching
+- `Result.isOk` - Type guard for success
+- `Result.isErr` - Type guard for error
+
+### `reader-result.mts`
+
+Reader monad combined with Result type for dependency injection and error handling.
+
+**Types & Functions:**
+
+- `ReaderResult<D, E, A>` - Reader + Result monad
+- `ReaderResult.of` - Create from value
+- `ReaderResult.fromResult` - Lift Result
+- `ReaderResult.ask` - Access dependencies
+- `ReaderResult.chain` - Monadic composition
+- `ReaderResult.map` - Transform success value
+- `ReaderResult.run` - Execute with dependencies
+
+### `validation.mts`
+
+Validation utilities and error types.
+
+**Types & Functions:**
+
+- `ValidationError` - Structured validation error
+- `createValidationError` - Error factory
+- `combineValidationErrors` - Merge multiple errors
+- `formatValidationError` - Error formatting
+
+## Usage Patterns
+
+### Import Strategy
+
+Always import directly from specific modules for optimal tree-shaking:
+
+```typescript
+// ✅ Correct - Direct imports
+import { pipe, compose } from "@/lib/functional/composition.mjs";
+import { mapValues, pick } from "@/lib/functional/object-utils.mjs";
+
+// ❌ Wrong - No barrel imports (index.mts was removed)
+import { pipe } from "@/lib/functional";
+```
+
+### Composition Patterns
+
+Functions are designed to work together through composition:
+
+```typescript
+import { chunk, filterMap } from "@/lib/functional/array-utils.mjs";
+import { pipe } from "@/lib/functional/composition.mjs";
+import { isNotNil } from "@/lib/functional/predicates.mjs";
+
+// Combine utilities for complex transformations
+const processData = pipe(
+  filterMap((x: unknown) => (isNotNil(x) ? x : undefined)),
+  chunk(10),
+);
+```
+
+### Error Handling
+
+Use Result types for explicit error handling:
+
+```typescript
+import { findSafe } from "@/lib/functional/array-utils.mjs";
+import { Result } from "@/lib/functional/result.mjs";
+
+// Functions return Result types for safety
+const result = findSafe((x: User) => x.id === targetId)(users);
+
+if (result.success) {
+  console.log("Found user:", result.data);
+} else {
+  console.log("User not found");
+}
+```
+
+## Testing
+
+All utilities have comprehensive test suites. Run tests with:
+
+```bash
+# Run all functional library tests
+pnpm test src/lib/functional
+
+# Run specific module tests
+pnpm test src/lib/functional/array-utils.test.ts
+```
+
+## Performance Considerations
+
+- **Memory Efficiency**: Functions like `filterMap` avoid intermediate arrays
+- **Lazy Evaluation**: Pipeline class enables lazy transformation chains
+- **Memoization**: Use `memoize` for expensive pure computations
+- **Batching**: `batchAsync` optimizes concurrent async operations
+
+## Migration Guide
+
+If migrating from the old structure:
+
+1. Replace imports from `pipe.mts` with `composition.mts`
+2. Import array/object utilities from their dedicated modules
+3. Remove any imports from `index.mts` (barrel file removed)
+4. Update type imports for Result and ValidationError
+
+## Contributing
+
+When adding new utilities:
+
+1. Ensure functions are pure with no side effects
+2. Add comprehensive JSDoc with `@example` blocks
+3. Include proper `@since` tags with current date
+4. Write thorough unit tests
+5. Follow established naming conventions
+6. Update this README with new functions
+
+## License - MIT

package/dist/array-utils.d.mts

@@ -0,0 +1,317 @@
+/**
+ * @module array-utils
+ * @description Functional utilities for working with arrays in a type-safe, immutable manner.
+ * These functions are designed to be composed and follow functional programming principles.
+ * All operations return new arrays, preserving immutability.
+ *
+ * @example
+ * ```typescript
+ * import { filterMap, chunk, groupBy } from './array-utils.mts';
+ *
+ * // filter and transform in one pass
+ * const numbers = filterMap((s: string) => {
+ *   const n = parseInt(s);
+ *   return isNaN(n) ? undefined : n;
+ * })(['1', 'a', '2', 'b', '3']);
+ * // => [1, 2, 3]
+ *
+ * // chunk into batches
+ * const batches = chunk(3)([1, 2, 3, 4, 5, 6, 7]);
+ * // => [[1, 2, 3], [4, 5, 6], [7]]
+ *
+ * // group by property
+ * const users = [
+ *   { name: 'Alice', role: 'admin' },
+ *   { name: 'Bob', role: 'user' },
+ *   { name: 'Charlie', role: 'admin' }
+ * ];
+ * const byRole = groupBy((u: typeof users[0]) => u.role)(users);
+ * // => { admin: [Alice, Charlie], user: [Bob] }
+ * ```
+ *
+ * @category Utilities
+ * @since 2025-07-03
+ */
+/**
+ * Map over an array with index.
+ * @description Transforms each element of an array using a function that receives both the element and its index.
+ * Useful when you need both the element and its position during transformation.
+ * Preserves the original array and returns a new array with transformed values.
+ *
+ * @template T - The type of elements in the input array
+ * @template U - The type of elements in the output array
+ * @param {function(T, number): U} fn - Transformation function that receives item and index
+ * @returns {function(T[]): U[]} A function that takes an array and returns the transformed array
+ *
+ * @category Transformation
+ * @example
+ * const indexed = mapWithIndex((item, i) => `${i}: ${item}`)(['a', 'b', 'c']);
+ * // => ['0: a', '1: b', '2: c']
+ *
+ * @example
+ * // Creating a numbered list
+ * const items = ['First', 'Second', 'Third'];
+ * const numbered = mapWithIndex((item, i) => `${i + 1}. ${item}`)(items);
+ * // => ['1. First', '2. Second', '3. Third']
+ *
+ * @example
+ * // Add index metadata to objects
+ * const data = [{ name: 'Alice' }, { name: 'Bob' }];
+ * const withIndex = mapWithIndex((item, i) => ({ ...item, index: i }))(data);
+ * // => [{ name: 'Alice', index: 0 }, { name: 'Bob', index: 1 }]
+ *
+ * @see map - Standard array map without index
+ * @see filterMap - Transform and filter in one pass
+ * @since 2025-07-03
+ */
+export declare const mapWithIndex: <T, U>(fn: (item: T, index: number) => U) => (arr: T[]) => U[];
+/**
+ * Filter and map in a single pass, removing undefined values.
+ * More efficient than chaining filter and map when transformation might return undefined.
+ * Optimized to avoid creating intermediate arrays for better memory efficiency.
+ *
+ * @category Transformation
+ * @example
+ * const nums = filterMap((s: string) => {
+ *   const n = parseInt(s);
+ *   return isNaN(n) ? undefined : n;
+ * })(['1', 'a', '2', 'b', '3']);
+ * // => [1, 2, 3]
+ *
+ * @example
+ * // Parse and validate in one pass
+ * const parseEmails = filterMap((str: string) => {
+ *   const trimmed = str.trim();
+ *   return trimmed.includes('@') ? trimmed : undefined;
+ * });
+ * parseEmails(['  john@example.com', 'invalid', 'jane@test.com  ']);
+ * // => ['john@example.com', 'jane@test.com']
+ *
+ * @example
+ * // Extract and transform nested data
+ * const users = [
+ *   { name: 'Alice', profile: { age: 25 } },
+ *   { name: 'Bob', profile: null },
+ *   { name: 'Charlie', profile: { age: 30 } }
+ * ];
+ * const ages = filterMap((u: typeof users[0]) =>
+ *   u.profile ? { name: u.name, age: u.profile.age } : undefined
+ * )(users);
+ * // => [{ name: 'Alice', age: 25 }, { name: 'Charlie', age: 30 }]
+ *
+ * @see map - Transform without filtering
+ * @see filter - Filter without transformation
+ * @since 2025-07-03
+ */
+export declare const filterMap: <T, U>(fn: (item: T, index: number) => U | undefined) => (arr: T[]) => U[];
+/**
+ * Chunk an array into smaller arrays of specified size.
+ * @description Splits an array into multiple sub-arrays of a specified maximum size.
+ * The last chunk may contain fewer elements if the array length is not evenly divisible by the chunk size.
+ * Useful for pagination, batch processing, or creating grid layouts.
+ *
+ * @template T - The type of elements in the array
+ * @param {number} size - The maximum size of each chunk (must be positive)
+ * @returns {function(T[]): T[][]} A function that takes an array and returns an array of chunks
+ *
+ * @category Grouping
+ * @example
+ * const chunks = chunk(2)([1, 2, 3, 4, 5]);
+ * // => [[1, 2], [3, 4], [5]]
+ *
+ * @example
+ * // Batch API requests
+ * const userIds = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
+ * const batches = chunk(3)(userIds);
+ * // => [[1, 2, 3], [4, 5, 6], [7, 8, 9], [10]]
+ *
+ * @example
+ * // Create rows for a grid
+ * const items = ['A', 'B', 'C', 'D', 'E', 'F'];
+ * const rows = chunk(3)(items);
+ * // => [['A', 'B', 'C'], ['D', 'E', 'F']]
+ *
+ * @example
+ * // Process large dataset in batches
+ * const processInBatches = async <T>(items: T[], batchSize: number, processor: (batch: T[]) => Promise<void>) => {
+ *   const batches = chunk(batchSize)(items);
+ *   for (const batch of batches) {
+ *     await processor(batch);
+ *   }
+ * };
+ *
+ * @see groupBy - Group by a key function
+ * @see partition - Split into two arrays
+ * @since 2025-07-03
+ */
+export declare const chunk: <T>(size: number) => (arr: T[]) => T[][];
+/**
+ * Group array elements by a key function.
+ * @description Creates an object where keys are the grouping values and values are arrays of elements.
+ * Each element is placed into exactly one group based on the key function result.
+ * The order of elements within each group is preserved from the original array.
+ *
+ * @template T - The type of elements in the array
+ * @template K - The type of the grouping key (must be string or number)
+ * @param {function(T): K} keyFn - Function that extracts the grouping key from each element
+ * @returns {function(T[]): Record<K, T[]>} A function that takes an array and returns grouped elements
+ *
+ * @category Grouping
+ * @example
+ * const users = [
+ *   { name: 'Alice', age: 25 },
+ *   { name: 'Bob', age: 30 },
+ *   { name: 'Charlie', age: 25 }
+ * ];
+ * const byAge = groupBy((u: typeof users[0]) => u.age)(users);
+ * // => { 25: [{ name: 'Alice', age: 25 }, { name: 'Charlie', age: 25 }], 30: [{ name: 'Bob', age: 30 }] }
+ *
+ * @example
+ * // Group by first letter
+ * const words = ['apple', 'banana', 'apricot', 'cherry', 'avocado'];
+ * const byFirstLetter = groupBy((word: string) => word[0])(words);
+ * // => { a: ['apple', 'apricot', 'avocado'], b: ['banana'], c: ['cherry'] }
+ *
+ * @example
+ * // Group transactions by status
+ * const transactions = [
+ *   { id: 1, status: 'pending', amount: 100 },
+ *   { id: 2, status: 'completed', amount: 200 },
+ *   { id: 3, status: 'pending', amount: 150 }
+ * ];
+ * const byStatus = groupBy((t: typeof transactions[0]) => t.status)(transactions);
+ * // => { pending: [{id: 1, ...}, {id: 3, ...}], completed: [{id: 2, ...}] }
+ *
+ * @example
+ * // Group by computed property
+ * const scores = [65, 72, 88, 95, 42, 58, 90];
+ * const byGrade = groupBy((score: number) => {
+ *   if (score >= 90) return 'A';
+ *   if (score >= 80) return 'B';
+ *   if (score >= 70) return 'C';
+ *   if (score >= 60) return 'D';
+ *   return 'F';
+ * })(scores);
+ * // => { A: [95, 90], B: [88], C: [72], D: [65], F: [42, 58] }
+ *
+ * @see chunk - Group into fixed-size arrays
+ * @see partition - Split into two groups
+ * @since 2025-07-03
+ */
+export declare const groupBy: <T, K extends string | number>(keyFn: (item: T) => K) => (arr: T[]) => Record<K, T[]>;
+/**
+ * Find the first item that matches a predicate, returning a Result.
+ * @description Safe alternative to Array.find that explicitly handles the not-found case.
+ * Returns a discriminated union result that forces explicit handling of both success and failure cases.
+ * This prevents runtime errors from undefined values and makes the control flow explicit.
+ *
+ * @template T - The type of elements in the array
+ * @param {function(T): boolean} predicate - Function to test each element
+ * @returns {function(T[]): { success: true; data: T } | { success: false; error: string }} A function that searches the array and returns a Result
+ *
+ * @category Search
+ * @example
+ * const result = findSafe((n: number) => n > 3)([1, 2, 3, 4, 5]);
+ * // => { success: true, data: 4 }
+ *
+ * const notFound = findSafe((n: number) => n > 10)([1, 2, 3]);
+ * // => { success: false, error: 'Item not found' }
+ *
+ * @example
+ * // Find user by email
+ * const users = [
+ *   { id: 1, email: 'alice@example.com' },
+ *   { id: 2, email: 'bob@example.com' }
+ * ];
+ * const findByEmail = (email: string) =>
+ *   findSafe((u: typeof users[0]) => u.email === email)(users);
+ *
+ * const result = findByEmail('alice@example.com');
+ * if (result.success) {
+ *   console.log('Found user:', result.data.id);
+ * } else {
+ *   console.log('User not found');
+ * }
+ *
+ * @example
+ * // Chain with other operations safely
+ * const processUser = (email: string) => {
+ *   const result = findSafe((u: User) => u.email === email)(users);
+ *   if (!result.success) {
+ *     return { success: false, error: `No user with email ${email}` };
+ *   }
+ *   // process result.data safely
+ *   return { success: true, data: processUserData(result.data) };
+ * };
+ *
+ * @see find - Native array find (returns undefined)
+ * @see filter - Get all matching items
+ * @since 2025-07-03
+ */
+export declare const findSafe: <T>(predicate: (item: T) => boolean) => (arr: T[]) => {
+    success: true;
+    data: T;
+} | {
+    success: false;
+    error: string;
+};
+/**
+ * Partition an array into two arrays based on a predicate.
+ * @description Splits an array into two parts: elements that satisfy the predicate go into the first array,
+ * and elements that don't satisfy the predicate go into the second array.
+ * More efficient than running filter twice with opposite predicates.
+ * Preserves the relative order of elements in both resulting arrays.
+ *
+ * @template T - The type of elements in the array
+ * @param {function(T): boolean} predicate - Function to test each element
+ * @returns {function(T[]): [T[], T[]]} A function that takes an array and returns a tuple of [matching, non-matching] arrays
+ *
+ * @category Grouping
+ * @example
+ * const [evens, odds] = partition((n: number) => n % 2 === 0)([1, 2, 3, 4, 5]);
+ * // => evens: [2, 4], odds: [1, 3, 5]
+ *
+ * @example
+ * // Separate valid and invalid data
+ * const data = [
+ *   { id: 1, valid: true },
+ *   { id: 2, valid: false },
+ *   { id: 3, valid: true }
+ * ];
+ * const [valid, invalid] = partition((item: typeof data[0]) => item.valid)(data);
+ * // => valid: [{id: 1, valid: true}, {id: 3, valid: true}]
+ * // => invalid: [{id: 2, valid: false}]
+ *
+ * @example
+ * // Separate active and inactive users
+ * const users = [
+ *   { name: 'Alice', lastLogin: new Date('2024-01-10') },
+ *   { name: 'Bob', lastLogin: new Date('2023-12-01') },
+ *   { name: 'Charlie', lastLogin: new Date('2024-01-14') }
+ * ];
+ * const thirtyDaysAgo = new Date();
+ * thirtyDaysAgo.setDate(thirtyDaysAgo.getDate() - 30);
+ *
+ * const [active, inactive] = partition(
+ *   (u: typeof users[0]) => u.lastLogin > thirtyDaysAgo
+ * )(users);
+ *
+ * @example
+ * // Partition by multiple criteria
+ * const products = [
+ *   { name: 'Laptop', price: 1200, inStock: true },
+ *   { name: 'Mouse', price: 25, inStock: false },
+ *   { name: 'Keyboard', price: 80, inStock: true }
+ * ];
+ * const [available, unavailable] = partition(
+ *   (p: typeof products[0]) => p.inStock && p.price < 1000
+ * )(products);
+ * // => available: [{ name: 'Keyboard', ... }]
+ * // => unavailable: [{ name: 'Laptop', ... }, { name: 'Mouse', ... }]
+ *
+ * @see filter - Get only matching items
+ * @see groupBy - Group into multiple categories
+ * @since 2025-07-03
+ */
+export declare const partition: <T>(predicate: (item: T) => boolean) => (arr: T[]) => [T[], T[]];
+//# sourceMappingURL=array-utils.d.mts.map

package/dist/array-utils.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"array-utils.d.mts","sourceRoot":"","sources":["../src/array-utils.mts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,eAAO,MAAM,YAAY,GACtB,CAAC,EAAE,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,CAAC,WAClC,CAAC,EAAE,KAAG,CAAC,EACA,CAAC;AAEhB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,eAAO,MAAM,SAAS,GACnB,CAAC,EAAE,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,CAAC,GAAG,SAAS,WAC9C,CAAC,EAAE,KAAG,CAAC,EAOL,CAAC;AAEX;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,eAAO,MAAM,KAAK,GACf,CAAC,QAAS,MAAM,WACX,CAAC,EAAE,KAAG,CAAC,EAAE,EAMd,CAAC;AAEJ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AACH,eAAO,MAAM,OAAO,GACjB,CAAC,EAAE,CAAC,SAAS,MAAM,GAAG,MAAM,SAAS,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,WAC9C,CAAC,EAAE,KAAG,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAUxB,CAAC;AAEJ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,eAAO,MAAM,QAAQ,GAClB,CAAC,aAAc,CAAC,IAAI,EAAE,CAAC,KAAK,OAAO,WAE7B,CAAC,EAAE,KACP;IAAE,OAAO,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,CAAC,CAAA;CAAE,GAAG;IAAE,OAAO,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAM9D,CAAC;AAEJ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyDG;AACH,eAAO,MAAM,SAAS,GACnB,CAAC,aAAc,CAAC,IAAI,EAAE,CAAC,KAAK,OAAO,WAC9B,CAAC,EAAE,KAAG,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,CAWpB,CAAC"}