@hgargg-0710/one/dist/src/array/array.d.ts

A tiny npm library purposed for providing beautiful solutions to frequent miniature (one-line/one-expression) tasks for various JS datatypes.

export type Pair<A = any, B = A> = [A, B];
export type Pairs<A = any, B = A> = Pair<A, B>[];
/**
 * A generic type for representation of N-tuples with the same type.
 *
 * Creates a type of `[Type, ...]` (`LowLim` items) `| [Type, ...]` (`LowLim + 1` items) `| ... | [Type, ...]` (`UpLim` items).
 *
 * Example:
 *
 * `type Z = Tuple<number, 0, 3>`
 *
 * `type O = Tuple<string, 4>`
 *
 * Are the same as:
 *
 * `type Z = [] | [number] | [number, number] | [number, number, number]`
 *
 * `type O = [string, string, string, string]`
 */
export type Tuple<Type, LowLim extends number, UpLim extends number = LowLim> = LowLim extends LowLim ? number extends LowLim ? Type[] : LowLim extends UpLim ? _TupleOfBase<Type, LowLim, []> : _TupleOf<Type, Tuple<Type, LowLim>, Tuple<Type, UpLim>, []> : never;
type _TupleOfBase<Type, Limit extends number, Rem extends unknown[]> = Rem["length"] extends Limit ? Rem : _TupleOfBase<Type, Limit, [...Rem, Type]>;
type _TupleOf<Type, LowLim extends unknown[], UpLim extends unknown[], Rem extends unknown[]> = LowLim["length"] extends 0 ? [] | (UpLim["length"] extends 0 ? never : _TupleOf<Type, [Type], UpLim, []>) : Rem["length"] extends LowLim["length"] ? Rem : _TupleOf<Type, LowLim, UpLim, [...Rem, Type]> | (LowLim["length"] extends UpLim["length"] ? never : _TupleOf<Type, [...LowLim, Type], UpLim, Rem>);
/**
 * Returns a predicate, purpose of which is to indicate that the argument `x` is a `Tuple`,
 * with `.length` being precisely `n`.
 */
export declare const isTuple: <Items extends number>(n: number) => <Type>(x: any) => x is Tuple<Type, Items>;
/**
 * A predicate, purpose of which is to determine that the given item is an array of length 2.
 */
export declare const isPair: <A = any, B = any>(x: any) => x is Pair<A, B>;
/**
 * A type-only no-op function, purpose of which is to treat the given arguments as an array of respective specific type.
 */
export declare const tuple: <T extends any[]>(...args: T) => T;
/**
 * A function for creating a copy of the given array without the last `count` elements (by default - 1)
 */
export declare const lastOut: <Type = any>(x: Type[], count?: number) => Type[];
/**
 * A function for obtaining the last element of the given array.
 */
export declare const last: <Type = any>(x: Type[]) => Type;
/**
 * Sets the value of the last element of the array `x` to be `v`.
 * @returns `v`
 */
export declare const setLast: <T = any>(x: T[], v: T) => T;
/**
 * A function for mutating the given array via setting its` `.length` to `0`.
 */
export declare const clear: <Type = any>(x: Type[]) => number;
/**
 * A function for creating a copy of the array with `values` inserted into it at `index`, and `replaceNum(x)` items skipped.
 */
export declare const insertion: (replaceNum: (x: any[]) => number) => <Type = any>(x: Type[], index: number, ...values: Type[]) => Type[];
/**
 * Same as `insertion(constant(0))`. Creates a copy, which is a result of inserting items at a given index without any removal
 */
export declare const insert: <Type = any>(x: Type[], index: number, ...values: Type[]) => Type[];
/**
 * Same as `insertion(constant(1))`. Creates a copy, which is a result of inserting items at a given index, removing only a single item
 */
export declare const replace: <Type = any>(x: Type[], index: number, ...values: Type[]) => Type[];
/**
 * Creates a copy of a given array, which is a result of removal of `count` items from the given index (default - a single item);
 */
export declare const out: <Type = any>(array: Type[], index: number, count?: number) => Type[];
/**
 * Creates a copy of a given array, with the first `count` items removed (by default - 1)
 */
export declare const firstOut: <Type = any>(x: Type[], count?: number) => Type[];
/**
 * Gets the first item of the array
 */
export declare const first: <Type = any>(x: Type[]) => Type;
/**
 * Calls `f` on `x`, assigning all the own keys on `x`, that are not in `excluded` to `x`.
 *
 * Useful for creating "hybrid" arrays from existing objects.
 */
export declare const propPreserve: (f: Function, excluded?: (string | symbol)[]) => (x: object) => any;
/**
 * Creates a copy of the given array
 */
export declare const copy: <Type = any>(x: Type[]) => Type[];
/**
 * Creates and returns a new array. Same functionality as `array.map(f)`.
 *
 * Better performance for much larger inputs (no engine input size optimizations)
 */
export declare function map<TypeFrom = any, TypeTo = any>(array: TypeFrom[], f: (item?: TypeFrom, index?: number, array?: TypeFrom[]) => TypeTo): TypeTo[];
/**
 * Creates and returns a new array. Same functionality as `array.prop(f)`.
 *
 * Better performance for much larger inputs (no engine input size optimizations)
 */
export declare function filter<Type = any>(array: Type[], prop: (item?: Type, index?: number, array?: Type[]) => boolean): Type[];
/**
 * Creates and returns a new array. Same functionality as `array.reduce(f, init)`.
 *
 * Better performance for much larger inputs (no engine input size optimizations)
 */
export declare function reduce<Type = any>(array: Type[], f: (item?: any, curr?: Type, i?: number) => any, init?: any): any;
/**
 * Creates and returns a new array. Same functionality as `array.reduceRight(f, init)`
 *
 * Better performance for much larger inputs (no engine input size optimizations)
 */
export declare function reduceRight<Type = any>(array: Type[], f: (item?: any, curr?: Type, i?: number) => any, init?: any): any;
/**
 * Allocates and returns a new empty array.
 */
export declare const empty: () => [];
/**
 * Conducts the comparison of two iterables `a` and `b`
 * by converting them to arrays and using element-by-element `pred(a[i], b[i], i)`.
 *
 * For comparison to yield `true`, it is required for both arrays to have the same length.
 *
 * `pred` defaults to `(x, y) => x === y`
 */
export declare const same: (a: Iterable<any>, b: Iterable<any>, pred?: (x?: any, y?: any, i?: any) => boolean) => boolean;
/**
 * Creates the array consisting of all the unique items of the given
 * Iterable, in the order in which they appear
 */
export declare const uniqueArr: <T = any>(x: Iterable<T>) => T[];
/**
 * Returns either the first truthy element of `x`, or `last(x)`
 */
export declare const or: <T = any>(x: T[]) => T;
/**
 * Returns either the first falsy element of `x` or `last(x)`
 */
export declare const and: <T = any>(x: T[]) => T;
/**
 * Creates a function returning new shallow copies of `array` [useful for factoring-out/remembering information about the array`s contents]
 */
export declare const allocator: <T = any>(array: T[]) => () => T[];
/**
 * Returns the last index of a given array
 */
export declare const lastIndex: (array: any[]) => number;
/**
 * @returns whether the given array is empty
 */
export declare const isEmpty: (array: any[]) => boolean;
/**
 * Recursively applies `array.same(a[i], b[i], i)` for `a[i]` and `b[i]` - arrays,
 * to the given arrays `a` and `b` (otherwise, applying `pred(a[i], b[i], i)`),
 * and returns the result.
 */
export declare const recursiveSame: (a: any[], b: any[], pred?: (x?: any, y?: any, i?: number) => boolean) => any;
/**
 * Calls `array.sort(order)` with `order` defaulting to `number.difference`
 */
export declare const sort: <T = any>(array: T[], order?: (a: any, b: any) => number) => T[];
/**
 * Creates a new function, which creates a new array of length `n`, indexes of which
 * defined by the `indexes` array (note: which is pre-ordered), are filled with `values`,
 * the remaining ones being filled by the values of the `x` array
 */
export declare const substitute: (n: number, indexes: number[]) => (values: any[]) => (x: any[]) => any[];
/**
 * Returns the array of keys for the given array `x`
 */
export declare const keys: <T = any>(x: T[]) => number[];
/**
 * Returns an Array of numbers from `0` to `n - 1`
 */
export declare const numbers: (n: number) => number[];
export {};