ts-data-forge 1.5.1 → 2.0.0

package/dist/array/tuple-utils.mjs

@@ -1,391 +0,0 @@
-/* eslint-disable @typescript-eslint/no-unsafe-type-assertion */
-/**
- * A collection of tuple utility functions.
- *
- * Provides type-safe operations for working with tuples (fixed-length arrays).
- * Unlike regular arrays, tuples preserve their exact length and element types
- * at compile time, enabling precise type inference and validation.
- *
- * Key features:
- * - All operations preserve tuple length and element types
- * - Type-safe indexing with compile-time bounds checking
- * - Immutable operations that return new tuples
- * - Precise type inference for transformed elements
- *
- * @example
- * ```typescript
- * // Tuples preserve exact types and length
- * const tuple = [1, 'hello', true] as const;
- * type TupleType = typeof tuple; // readonly [1, 'hello', true]
- *
- * // Operations preserve tuple structure
- * const mapped = Tpl.map(tuple, (x) => String(x)); // readonly ['1', 'hello', 'true']
- * const reversed = Tpl.toReversed(tuple); // readonly [true, 'hello', 1]
- * ```
- */
-var Tpl;
-(function (Tpl) {
-    //   length: size,
-    /**
-     * Returns the length of a tuple as a literal type.
-     *
-     * Unlike `array.length` which returns `number`, this preserves
-     * the exact length as a literal type (e.g., `3` not `number`).
-     *
-     * @template T - The tuple type whose length will be extracted
-     * @param list - The input tuple
-     * @returns The length of the tuple as a literal number type
-     *
-     * @example
-     * ```typescript
-     * const tpl = [1, 2, 3] as const;
-     * const len = Tpl.size(tpl); // 3 (literal type, not just number)
-     *
-     * // Type-level length extraction
-     * type Len = Length<typeof tpl>; // 3
-     *
-     * // Useful for compile-time validation
-     * function requiresTriple<T extends readonly [unknown, unknown, unknown]>(t: T) {}
-     * const pair = [1, 2] as const;
-     * // requiresTriple(pair); // Error: length mismatch
-     * ```
-     */
-    Tpl.size = (list) => list.length;
-    Tpl.length = Tpl.size;
-    /**
-     * Finds the index of the first element in a tuple that satisfies the predicate.
-     *
-     * Returns a type-safe index that can be one of the valid tuple indices or -1.
-     * The return type is precisely inferred based on the tuple's length.
-     *
-     * @template T - The tuple type to search within
-     * @param tpl - The input tuple
-     * @param predicate - A function to test each element for a condition
-     * @returns The index of the first matching element, or -1 if not found
-     *
-     * @example
-     * ```typescript
-     * const tpl = [1, 2, 3, 4] as const;
-     * const idx1 = Tpl.findIndex(tpl, (x) => x > 2); // 2 | 3 | -1
-     * const idx2 = Tpl.findIndex(tpl, (x) => x > 10); // -1
-     *
-     * // Type-safe indexing
-     * if (idx1 !== -1) {
-     *   const value = tpl[idx1]; // Safe access, TypeScript knows idx1 is valid
-     * }
-     *
-     * // With mixed types
-     * const mixed = [1, 'hello', true, null] as const;
-     * const strIndex = Tpl.findIndex(mixed, (x) => typeof x === 'string'); // 1 | -1
-     * ```
-     */
-    Tpl.findIndex = (tpl, predicate) => tpl.findIndex((value, index) => predicate(value, index));
-    /**
-     * Returns the first index at which a given element can be found in the tuple.
-     *
-     * Performs strict equality checking (===) and returns a type-safe index.
-     * The return type precisely reflects the possible indices of the tuple.
-     *
-     * @template T - The tuple type to search within
-     * @param tpl - The input tuple
-     * @param searchElement - Element to locate in the tuple (must be assignable to tuple's element types)
-     * @param fromIndex - Optional index to start the search at (defaults to 0)
-     * @returns The first index of the element, or -1 if not found
-     *
-     * @example
-     * ```typescript
-     * const tpl = ['a', 'b', 'c', 'b'] as const;
-     * const idx1 = Tpl.indexOf(tpl, 'b'); // 1 | 3 | -1 (type shows possible indices)
-     * const idx2 = Tpl.indexOf(tpl, 'b', 2); // 3 | -1 (search from index 2)
-     * const idx3 = Tpl.indexOf(tpl, 'd'); // -1
-     *
-     * // Type safety with literal types
-     * const nums = [1, 2, 3, 2] as const;
-     * const twoIndex = Tpl.indexOf(nums, 2); // 1 | 3 | -1
-     * // Tpl.indexOf(nums, '2'); // Error: string not assignable to 1 | 2 | 3
-     *
-     * // Works with mixed types
-     * const mixed = [1, 'hello', true, 1] as const;
-     * const oneIndex = Tpl.indexOf(mixed, 1); // 0 | 3 | -1
-     * ```
-     */
-    Tpl.indexOf = (tpl, searchElement, fromIndex) => tpl.indexOf(searchElement, fromIndex);
-    /**
-     * Returns the last index at which a given element can be found in the tuple.
-     *
-     * Searches backwards from the end (or from `fromIndex` if provided) and
-     * returns a type-safe index reflecting the tuple's structure.
-     *
-     * @template T - The tuple type to search within
-     * @param tpl - The input tuple
-     * @param searchElement - Element to locate in the tuple
-     * @param fromIndex - Optional index to start searching backwards from (defaults to last index)
-     * @returns The last index of the element, or -1 if not found
-     *
-     * @example
-     * ```typescript
-     * const tpl = ['a', 'b', 'c', 'b'] as const;
-     * const idx1 = Tpl.lastIndexOf(tpl, 'b'); // 3 | 1 | -1
-     * const idx2 = Tpl.lastIndexOf(tpl, 'b', 2); // 1 | -1 (search up to index 2)
-     * const idx3 = Tpl.lastIndexOf(tpl, 'd'); // -1
-     *
-     * // With duplicate values
-     * const nums = [1, 2, 3, 2, 1] as const;
-     * const lastOne = Tpl.lastIndexOf(nums, 1); // 4 | 0 | -1
-     * const lastTwo = Tpl.lastIndexOf(nums, 2); // 3 | 1 | -1
-     *
-     * // Type safety preserved
-     * const mixed = [true, 42, 'str', 42] as const;
-     * const last42 = Tpl.lastIndexOf(mixed, 42); // 3 | 1 | -1
-     * // Tpl.lastIndexOf(mixed, false); // Error: false not in tuple type
-     * ```
-     */
-    Tpl.lastIndexOf = (tpl, searchElement, fromIndex) => tpl.lastIndexOf(searchElement, fromIndex);
-    /**
-     * Creates a new tuple by transforming each element with a mapping function.
-     *
-     * Preserves the tuple's length while allowing element type transformation.
-     * The resulting tuple has the same structure but with transformed element types.
-     *
-     * @template T - The type of the input tuple
-     * @template B - The type that elements will be transformed to
-     * @param tpl - The input tuple
-     * @param mapFn - Function that transforms each element (receives element and index)
-     * @returns A new tuple with transformed elements, preserving the original length
-     *
-     * @example
-     * ```typescript
-     * // Basic transformation
-     * const nums = [1, 2, 3] as const;
-     * const doubled = Tpl.map(nums, (x) => x * 2); // readonly [2, 4, 6]
-     * const strings = Tpl.map(nums, (x) => String(x)); // readonly ['1', '2', '3']
-     *
-     * // With index
-     * const indexed = Tpl.map(nums, (x, i) => `${i}:${x}`);
-     * // readonly ['0:1', '1:2', '2:3']
-     *
-     * // Mixed type tuples
-     * const mixed = [1, 'hello', true] as const;
-     * const descriptions = Tpl.map(mixed, (x) => `Value: ${x}`);
-     * // readonly ['Value: 1', 'Value: hello', 'Value: true']
-     *
-     * // Type transformation preserves tuple structure
-     * type Original = readonly [number, string, boolean];
-     * type Mapped = { readonly [K in keyof Original]: string };
-     * // Mapped = readonly [string, string, string]
-     * ```
-     */
-    Tpl.map = (tpl, mapFn) => tpl.map((a, index) => mapFn(a, index));
-    // modification (returns new array)
-    /**
-     * Returns a new tuple with the element at the specified index replaced.
-     *
-     * This operation is type-safe with compile-time index validation.
-     * The resulting tuple type reflects that the element at the given index
-     * may be either the new type or the original type.
-     *
-     * @template T - The type of the input tuple
-     * @template N - The type of the new value to set
-     * @param tpl - The input tuple
-     * @param index - The index to update (must be valid for the tuple length)
-     * @param newValue - The new value to place at the index
-     * @returns A new tuple with the updated element
-     *
-     * @example
-     * ```typescript
-     * // Basic usage
-     * const tpl = ['a', 'b', 'c'] as const;
-     * const updated = Tpl.set(tpl, 1, 'B'); // readonly ['a', 'B', 'c']
-     *
-     * // Type changes are reflected
-     * const mixed = [1, 'hello', true] as const;
-     * const withNumber = Tpl.set(mixed, 1, 42);
-     * // readonly [1, 42 | 'hello', true]
-     *
-     * // Compile-time index validation
-     * const short = [1, 2] as const;
-     * // Tpl.set(short, 2, 3); // Error: index 2 is out of bounds
-     *
-     * // Different value types
-     * const nums = [1, 2, 3] as const;
-     * const withString = Tpl.set(nums, 0, 'first');
-     * // readonly ['first' | 1, 2, 3]
-     * ```
-     */
-    Tpl.set = (tpl, index, newValue) => Tpl.map(tpl, (a, i) => (i === index ? newValue : a));
-    /**
-     * Returns a new tuple with an element updated by applying a function.
-     *
-     * Similar to `set`, but instead of providing a new value directly,
-     * you provide a function that transforms the existing value.
-     * Useful for computed updates based on the current value.
-     *
-     * @template T - The type of the input tuple
-     * @template N - The type returned by the updater function
-     * @param tpl - The input tuple
-     * @param index - The index of the element to update
-     * @param updater - Function that transforms the current value to a new value
-     * @returns A new tuple with the updated element
-     *
-     * @example
-     * ```typescript
-     * // Numeric updates
-     * const nums = [1, 2, 3] as const;
-     * const doubled = Tpl.toUpdated(nums, 1, (x) => x * 10);
-     * // readonly [1, 20, 3]
-     *
-     * // String transformations
-     * const strs = ['hello', 'world', '!'] as const;
-     * const uppercased = Tpl.toUpdated(strs, 0, (s) => s.toUpperCase());
-     * // readonly ['HELLO', 'world', '!']
-     *
-     * // Complex transformations
-     * const data = [{count: 1}, {count: 2}, {count: 3}] as const;
-     * const incremented = Tpl.toUpdated(data, 1, (obj) => ({count: obj.count + 1}));
-     * // Updates the second object's count to 3
-     *
-     * // Type changes through updater
-     * const mixed = [1, 'hello', true] as const;
-     * const stringified = Tpl.toUpdated(mixed, 0, (n) => `Number: ${n}`);
-     * // readonly ['Number: 1' | 1, 'hello', true]
-     * ```
-     */
-    Tpl.toUpdated = (tpl, index, updater) => Tpl.map(tpl, (a, i) => (i === index ? updater(a) : a));
-    // transformation
-    /**
-     * Reverses a tuple, preserving element types in their new positions.
-     *
-     * The type system precisely tracks the reversal, so the returned tuple
-     * has its element types in the exact reverse order. This is more precise
-     * than array reversal which loses positional type information.
-     *
-     * @template T - The tuple type to reverse
-     * @param tpl - The input tuple
-     * @returns A new tuple with elements in reverse order and precise typing
-     *
-     * @example
-     * ```typescript
-     * // Basic reversal
-     * const nums = [1, 2, 3] as const;
-     * const reversed = Tpl.toReversed(nums); // readonly [3, 2, 1]
-     *
-     * // Mixed types preserved in reverse positions
-     * const mixed = [1, 'hello', true, null] as const;
-     * const revMixed = Tpl.toReversed(mixed);
-     * // readonly [null, true, 'hello', 1]
-     *
-     * // Type-level reversal
-     * type Original = readonly [number, string, boolean];
-     * type Reversed = Tuple.Reverse<Original>;
-     * // Reversed = readonly [boolean, string, number]
-     *
-     * // Empty and single-element tuples
-     * const empty = [] as const;
-     * const revEmpty = Tpl.toReversed(empty); // readonly []
-     * const single = [42] as const;
-     * const revSingle = Tpl.toReversed(single); // readonly [42]
-     * ```
-     */
-    Tpl.toReversed = (tpl) => 
-    // eslint-disable-next-line @typescript-eslint/no-unsafe-return
-    tpl.toReversed();
-    /**
-     * Sorts a tuple's elements, returning a new tuple with the same length.
-     *
-     * Unlike array sorting, this preserves the tuple's length but loses
-     * positional type information (all positions can contain any element
-     * from the original tuple). Default comparison is numeric ascending.
-     *
-     * @template T - The tuple type to sort
-     * @param tpl - The input tuple
-     * @param comparator - Optional comparison function (defaults to numeric comparison)
-     * @returns A new tuple with sorted elements
-     *
-     * @example
-     * ```typescript
-     * // Default numeric sorting
-     * const nums = [3, 1, 4, 1, 5] as const;
-     * const sorted = Tpl.toSorted(nums); // readonly [1, 1, 3, 4, 5]
-     *
-     * // Custom comparator
-     * const descending = Tpl.toSorted(nums, (a, b) => b - a);
-     * // readonly [5, 4, 3, 1, 1]
-     *
-     * // String sorting with comparator
-     * const strs = ['banana', 'apple', 'cherry'] as const;
-     * const alphaSorted = Tpl.toSorted(strs, (a, b) => a.localeCompare(b));
-     * // readonly ['apple', 'banana', 'cherry']
-     *
-     * // Mixed types require explicit comparator
-     * const mixed = [3, '2', 1, '4'] as const;
-     * const mixedSorted = Tpl.toSorted(mixed, (a, b) => Number(a) - Number(b));
-     * // readonly ['1', '2', '3', '4'] but typed as (3 | '2' | 1 | '4')[]
-     *
-     * // Note: Element types become union of all elements
-     * type Original = readonly [1, 2, 3];
-     * type Sorted = { readonly [K in keyof Original]: Original[number] };
-     * // Sorted = readonly [1 | 2 | 3, 1 | 2 | 3, 1 | 2 | 3]
-     * ```
-     */
-    Tpl.toSorted = ((tpl, comparator) => {
-        const cmp = comparator ?? ((x, y) => Number(x) - Number(y));
-        return tpl.toSorted(cmp);
-    });
-    /**
-     * Sorts a tuple by derived values from its elements.
-     *
-     * Allows sorting complex objects by extracting a sortable value from each.
-     * Like `toSorted`, this preserves tuple length but element types become
-     * a union of all possible elements.
-     *
-     * @template T - The tuple type to sort
-     * @template B - The type of values used for comparison
-     * @param tpl - The input tuple
-     * @param comparatorValueMapper - Function to extract comparison value from each element
-     * @param comparator - Optional comparator for the extracted values
-     * @returns A new sorted tuple
-     *
-     * @example
-     * ```typescript
-     * // Sort objects by numeric property
-     * const users = [
-     *   {name: 'Alice', age: 30},
-     *   {name: 'Bob', age: 20},
-     *   {name: 'Charlie', age: 25}
-     * ] as const;
-     * const byAge = Tpl.toSortedBy(users, (user) => user.age);
-     * // [{name: 'Bob', age: 20}, {name: 'Charlie', age: 25}, {name: 'Alice', age: 30}]
-     *
-     * // Sort by string property with custom comparator
-     * const byNameDesc = Tpl.toSortedBy(
-     *   users,
-     *   (user) => user.name,
-     *   (a, b) => b.localeCompare(a)
-     * );
-     * // Sorted by name in descending order
-     *
-     * // Sort by computed values
-     * const points = [{x: 3, y: 4}, {x: 1, y: 1}, {x: 2, y: 2}] as const;
-     * const byDistance = Tpl.toSortedBy(
-     *   points,
-     *   (p) => Math.sqrt(p.x ** 2 + p.y ** 2)
-     * );
-     * // Sorted by distance from origin
-     *
-     * // Custom comparator for complex sorting
-     * const items = [{priority: 1, name: 'A'}, {priority: 1, name: 'B'}] as const;
-     * const sorted = Tpl.toSortedBy(
-     *   items,
-     *   (item) => item.priority,
-     *   (a, b) => b - a // High priority first
-     * );
-     * ```
-     */
-    Tpl.toSortedBy = ((tpl, comparatorValueMapper, comparator) => Tpl.toSorted(tpl, (x, y) => comparator === undefined
-        ? comparatorValueMapper(x) -
-            comparatorValueMapper(y)
-        : comparator(comparatorValueMapper(x), comparatorValueMapper(y))));
-})(Tpl || (Tpl = {}));
-
-export { Tpl };
-//# sourceMappingURL=tuple-utils.mjs.map

package/dist/array/tuple-utils.mjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"tuple-utils.mjs","sources":["../../src/array/tuple-utils.mts"],"sourcesContent":[null],"names":[],"mappings":"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"}