utilium 2.7.2 → 2.8.1

package/dist/array.d.ts

@@ -0,0 +1,120 @@
+import type { Subtract } from './type-math.js';
+import type { Expand } from './types.js';
+/**
+ * Filter an array by the types *not* assignable to `Predicate`
+ *
+ * @example ```ts
+ * type nonempty = FilterOut<['example', 'with', 'empty', ''], ''>; // ['example', 'with', 'empty']
+ * ```
+ */
+export type FilterOut<Arr extends readonly any[], Predicate> = Arr extends readonly [infer Head, ...infer Rest] ? Head extends Predicate ? FilterOut<Rest, Predicate> : [Head, ...FilterOut<Rest, Predicate>] : [];
+/**
+ * Filter an array by the types assignable to `Predicate`
+ *
+ * @example ```ts
+ * type negatives = Filter<['-1', '2', '-3'], `-${number}`>; // ['-1', '-3']
+ * ```
+ */
+export type Filter<Arr extends readonly any[], Predicate> = Arr extends readonly [infer Head, ...infer Rest] ? Head extends Predicate ? [Head, ...Filter<Rest, Predicate>] : Filter<Rest, Predicate> : [];
+export type Some<Arr extends readonly any[], Predicate> = Arr extends readonly [infer Head, ...infer Rest] ? Head extends Predicate ? true : Some<Rest, Predicate> : false;
+export type Every<Arr extends readonly any[], Predicate> = Arr extends readonly [infer Head, ...infer Rest] ? Head extends Predicate ? Every<Rest, Predicate> : false : true;
+/**
+ * Empty
+ */
+export type Empty = [];
+/**
+ * Removes the first element of T and shifts
+ */
+export type Shift<T extends unknown[]> = T extends [unknown, ...infer Rest] ? Rest : never;
+/**
+ * Gets the first element of T
+ */
+export type First<T extends unknown[]> = T extends [infer F, ...unknown[]] ? F : never;
+/**
+ * Inserts V into T at the start of T
+ */
+export type Unshift<T extends unknown[], V> = [V, ...T];
+/**
+ * Removes the last element of T
+ */
+export type Pop<T extends unknown[]> = T extends [...infer _, unknown] ? _ : never;
+/**
+ * Gets the last element of T
+ */
+export type Last<T extends unknown[]> = T extends [...unknown[], infer Last] ? Last : never;
+/**
+ * Appends V to T
+ */
+export type Push<T extends unknown[], V> = [...T, V];
+/**
+ * Concatenates A and B
+ */
+export type Concat<A extends unknown[], B extends unknown[]> = Empty extends B ? A : Concat<Unshift<A, 0>, Shift<B>>;
+/**
+ * Extracts from A what is not B
+ *
+ * @remarks
+ * It does not remove duplicates (so Remove\<[0, 0, 0], [0, 0]\> yields [0]). This is intended and necessary behavior.
+ */
+export type Remove<A extends unknown[], B extends unknown[]> = Empty extends B ? A : Remove<Shift<A>, Shift<B>>;
+/**
+ * The length of T
+ */
+export type Length<T extends unknown[]> = T extends {
+    length: infer L extends number;
+} ? L : never;
+type _FromLength<N extends number, R extends unknown[] = Empty> = Length<R> extends N ? R : _FromLength<N, Unshift<R, 0>>;
+/**
+ * Creates a tuple of length N
+ */
+export type FromLength<N extends number> = _FromLength<N>;
+/**
+ * Gets the type of an array's members
+ */
+export type Member<T, D = null> = D extends 0 ? T : T extends (infer U)[] ? Member<U, D extends number ? Subtract<D, 1> : null> : T;
+/**
+ * Flattens an array
+ */
+export type FlattenArray<A extends unknown[], D = null> = A extends (infer U)[] ? Member<Exclude<U, A>, D>[] : A extends unknown[] ? {
+    [K in keyof A]: Member<A[K], D>;
+} : A;
+/**
+ * Whether T is a tuple
+ */
+export type IsTuple<T> = T extends [] ? false : T extends [infer _Head, ...infer _Rest] ? true : false;
+/**
+ * Flattens a tuple
+ */
+export type FlattenTuple<A extends unknown[]> = A extends [infer U, ...infer Rest] ? U extends unknown[] ? [...U, ...FlattenTuple<Rest>] : [U, ...FlattenTuple<Rest>] : [];
+/**
+ * Flattens an array or tuple
+ */
+export type Flatten<A extends unknown[]> = IsTuple<A> extends true ? FlattenTuple<A> : FlattenArray<A>;
+type _Tuple<T, N extends number, R extends unknown[] = Empty> = R['length'] extends N ? R : _Tuple<T, N, [T, ...R]>;
+/**
+ * Creates a tuple of T with length N
+ */
+export type Tuple<T, N extends number> = _Tuple<T, N>;
+/**
+ * Makes all members of the tuple T optional
+ */
+export type OptionalTuple<T extends unknown[]> = T extends [infer Head, ...infer Tail] ? [Head?, ...OptionalTuple<Tail>] : T;
+/**
+ * Converts an array of objects with a common key into a keyed object
+ *
+ * @example
+ * ```ts
+ * type ducksArray = [
+ * 	{ name: 'Gerald', quacks: 6 },
+ * 	{ name: 'Dorthy', quacks: 7 },
+ * ];
+ *
+ * type ducks = FromKeyedArray<ducksArray, 'name'>; // { Gerald: { name: 'Gerald', quacks: 6 }, Dorthy: { name: 'Dorthy', quacks: 7 } }
+ * ```
+ */
+export type FromKeyed<A extends any[], KeyName extends A extends (infer E)[] ? keyof E : never> = A extends (infer Element)[] ? {
+    [K in Element[KeyName] & PropertyKey]: Expand<Element & {
+        [_ in KeyName & PropertyKey]: K;
+    }>;
+} : never;
+export {};

package/dist/array.js

@@ -0,0 +1 @@
+export {};

package/dist/index.d.ts

@@ -1,3 +1,8 @@
+export * from './array.js';
+export * from './buffer.js';
+export * as cache from './cache.js';
+export * from './checksum.js';
+export * from './color.js';
 export * from './list.js';
 export * from './misc.js';
 export * from './numbers.js';

package/dist/index.js

@@ -1,6 +1,11 @@
 // SPDX-License-Identifier: LGPL-3.0-or-later
 // Copyright (c) 2025 James Prevett
 // For better tree shaking, import from whichever file is actually needed
+export * from './array.js';
+export * from './buffer.js';
+export * as cache from './cache.js';
+export * from './checksum.js';
+export * from './color.js';
 export * from './list.js';
 export * from './misc.js';
 export * from './numbers.js';

package/dist/objects.d.ts

@@ -1,4 +1,6 @@
-import type { Expand, UnionToTuple } from './types.js';
+import type { FilterOut } from './array.js';
+import type { Split } from './string.js';
+import type { $drain, Expand, UnionToTuple } from './types.js';
 export declare function filterObject<O extends object, R extends object>(object: O, predicate: (key: keyof O, value: O[keyof O]) => boolean): R;
 export declare function pick<T extends object, K extends keyof T>(object: T, ...keys: readonly K[]): Pick<T, K>;
 export declare function pick<T extends object, K extends keyof T>(object: T, ...keys: readonly (readonly K[])[]): Pick<T, K>;
@@ -46,9 +48,77 @@ export interface ConstMap<T extends Partial<Record<keyof any, any>>, K extends k
     has(key: keyof T | K): boolean;
 }
 export declare function map<const T extends Partial<Record<any, any>>>(items: T): Map<keyof T, T[keyof T]>;
-export declare function getByString<T, P extends string>(object: T, path: P, separator?: RegExp): GetByString<T, P>;
-export type GetByString<Data, Path extends string> = Path extends `__proto__${`${'.' | '[' | ']' | "'" | '"'}${string}` | ''}` ? never : Path extends `${infer Key extends keyof Data & (string | number)}${'.' | '[' | ']' | "'" | '"'}${infer Rest}` ? Key extends '' ? GetByString<Data, Rest> : GetByString<Data[Key], Rest> : Path extends keyof Data & (string | number) ? Data[Path] : undefined;
-export declare function setByString<T>(object: Record<string, any>, path: string, value: unknown, separator?: RegExp): T;
+/**
+ * Flatten an object structure into a set of "keys".
+ *
+ * @example
+ * ```ts
+ * type example = FlattenKeys<{ h: { s: { l: 1; v: 2 } } }>;
+ * type result = "h" | "h.s" | "h.s.l" | "h.s.v";
+ * ```
+ */
+export type FlattenKeys<O> = {
+    [K in keyof O & (string | number)]: O[K] extends Record<any, any> ? K | `${K}.${$drain<FlattenKeys<O[K]>>}` : K;
+}[O extends readonly unknown[] ? keyof O & `${number}` : keyof O & (string | number)];
+export type KeySeparator = '.' | '[' | ']';
+type GetByPath<Data, Path extends (string | number)[]> = Path extends [
+    infer Key extends keyof Data | '__proto__',
+    ...infer Rest extends (string | number)[]
+] ? Key extends '__proto__' ? never : Rest extends [] ? Data[Key & keyof Data] : GetByPath<Data[Key & keyof Data], Rest> : undefined;
+/**
+ * Get a value using a path of property keys.
+ *
+ * @see {@link getByString}
+ *
+ * @example
+ * ```ts
+ * interface Duck {
+ * 	taxonomy: {
+ * 		genus: 'anas';
+ * 		species: 'platyrhynchos';
+ * 	};
+ * }
+ *
+ * type DuckSpecies = GetByString<Duck, 'taxonomy.species'>; // 'platyrhynchos'
+ * ```
+ */
+export type GetByString<Data, Path extends string | number = FlattenKeys<Data>> = GetByPath<Data, FilterOut<Split<`${Path}`, KeySeparator>, ''>>;
+/**
+ * Get a value using a path of property keys.
+ *
+ * @example
+ * Translation keys mapping to locale objects
+ * ```ts
+ * const locale = {
+ * 	preference: {
+ * 		theme: {
+ * 			label: 'Theme'
+ * 		}
+ * 	}
+ * } as const;
+ *
+ * const text = getByString(locale, 'preference.theme.label'); // 'Theme'
+ * ```
+ *
+ * @example
+ * Arrays
+ * ```ts
+ * const pascal = {
+ * 	triangle: [
+ * 		[1],
+ * 		[1, 1],
+ * 		[1, 2, 1],
+ * 		[1, 3, 3, 1],
+ * 		[1, 4, 6, 4, 1]
+ * 	]
+ * } as const;
+ *
+ * const row3 = getByString(pascal, 'triangle[3]'); // readonly [1, 3, 3, 1]
+ * const r4c3 = getByString(pascal, 'triangle[4][2]'); // 6
+ * ```
+ */
+export declare function getByString<const T, const P extends string | number = FlattenKeys<T>>(object: T, path: P): GetByString<T, P>;
+export declare function setByString<const V, const T, const P extends string | number = FlattenKeys<T>>(object: T, path: P, value: V): V;
 export type JSONPrimitive = null | string | number | boolean;
 export interface JSONObject {
     [K: string]: JSONValue | undefined;
@@ -149,4 +219,4 @@ export type Never<T> = {
  * All of the properties in T or none of them
  */
 export type AllOrNone<T> = T | Never<T>;
-export type Filter<Key, Arr extends readonly any[]> = Arr extends readonly [infer L, ...infer R] ? L extends Key ? Filter<Key, R> : [L, ...Filter<Key, R>] : [];
+export {};

package/dist/objects.js

@@ -88,17 +88,58 @@ export function* getAllPrototypes(object) {
 export function map(items) {
     return new Map(Object.entries(items));
 }
-export function getByString(object, path, separator = /[.[\]'"]/) {
+const keySeparator = /[.[\]]/;
+/**
+ * Get a value using a path of property keys.
+ *
+ * @example
+ * Translation keys mapping to locale objects
+ * ```ts
+ * const locale = {
+ * 	preference: {
+ * 		theme: {
+ * 			label: 'Theme'
+ * 		}
+ * 	}
+ * } as const;
+ *
+ * const text = getByString(locale, 'preference.theme.label'); // 'Theme'
+ * ```
+ *
+ * @example
+ * Arrays
+ * ```ts
+ * const pascal = {
+ * 	triangle: [
+ * 		[1],
+ * 		[1, 1],
+ * 		[1, 2, 1],
+ * 		[1, 3, 3, 1],
+ * 		[1, 4, 6, 4, 1]
+ * 	]
+ * } as const;
+ *
+ * const row3 = getByString(pascal, 'triangle[3]'); // readonly [1, 3, 3, 1]
+ * const r4c3 = getByString(pascal, 'triangle[4][2]'); // 6
+ * ```
+ */
+export function getByString(object, path) {
     return path
-        .split(separator)
+        .toString()
+        .split(keySeparator)
         .filter(p => p)
         .reduce((o, p) => (p == '__proto__' ? _throw(new Error('getByString called with __proto__ in path')) : o?.[p]), object);
 }
-export function setByString(object, path, value, separator = /[.[\]'"]/) {
-    return path
-        .split(separator)
-        .filter(p => p && p != '__proto__')
-        .reduce((o, p, i) => (o[p] = path.split(separator).filter(p => p).length === ++i ? value : o[p] || {}), object);
+export function setByString(object, path, value) {
+    const parts = path
+        .toString()
+        .split(keySeparator)
+        .filter(p => p);
+    return parts.reduce((o, p, i) => {
+        if (p == '__proto__')
+            throw new Error('setByString called with __proto__ in path');
+        return (o[p] = parts.length === i + 1 ? value : o[p] || {});
+    }, object);
 }
 /**
  * Binds a this value for all of the functions in an object (not recursive)

package/dist/string.d.ts

@@ -1,3 +1,4 @@
+import type { Some } from './array.js';
 import type { $Max, w_subtract } from './type-math.js';
 export declare function capitalize<T extends string>(value: T): Capitalize<T>;
 export declare function uncapitalize<T extends string>(value: T): Uncapitalize<T>;
@@ -23,11 +24,19 @@ export declare function decodeUUID(uuid: Uint8Array): UUID;
 export declare function encodeUUID(uuid: UUID): Uint8Array<ArrayBuffer>;
 export declare function stringifyUUID(uuid: bigint): UUID;
 export declare function parseUUID(uuid: UUID): bigint;
+/**
+ * Used to support union delimiters, e.g. `'.' | ':'`
+ */
+type _SplitVariant<T extends string, CurrentDelim extends Delimiter, Delimiter extends string = ''> = T extends `${infer Left}${CurrentDelim}${infer Right}` ? [Left, ...Split<Right, Delimiter>] : [T];
 /**
  * Split a string.
  */
-export type Split<T extends string, Delimiter extends string = ''> = string extends T ? string[] : T extends '' ? [] : T extends `${infer Left}${Delimiter}${infer Right}` ? [Left, ...Split<Right, Delimiter>] : [T];
+export type Split<T extends string, Delimiter extends string = ''> = string extends T ? string[] : T extends '' ? [''] : {
+    [D in Delimiter]: Some<_SplitVariant<T, D, Delimiter>, `${string}${Delimiter}${string}`> extends true ? never : _SplitVariant<T, D, Delimiter>;
+}[Delimiter];
 export type StringLength<T extends string> = Split<T>['length'];
 export type Repeat<T extends string, N extends number, Init extends string = ''> = N extends 0 ? Init : Repeat<T, w_subtract<N, StringLength<T>>, `${Init}${T}`>;
 export type PadRight<Init extends string, R extends string, N extends number> = Repeat<R, $Max<0, w_subtract<N, StringLength<Init>>>, Init>;
 export type PadLeft<Init extends string, R extends string, N extends number> = `${Repeat<R, $Max<0, w_subtract<N, StringLength<Init>>>>}${Init}`;
+export type NonEmptyString = `${any}${string}`;
+export {};

package/dist/type-math.d.ts

@@ -11,8 +11,9 @@
  * `_*`  => general purpose internals
  *
  */
+import type { Length } from './array.js';
 import type { Repeat, StringLength } from './string.js';
-import type { $drain, Length } from './types.js';
+import type { $drain } from './types.js';
 /**
  * Maps a numeric literal type to a tuple type with that length
  */

package/dist/type-math.test.js

@@ -5,7 +5,7 @@ const add_positive = 3;
 const add_zero = 0;
 const add_diff_signs = -1;
 const add_negative = -3;
-const add_float = 1.7;
+const add_float = 1.6;
 // @ts-expect-error 2 + 2 != 5
 let fail = 5;
 fail = 4;
@@ -14,7 +14,7 @@ const subtract_normal = -18;
 const subtract_from_neg = -9;
 const subtract_both_neg = 5;
 const subtract_zero = -1;
-const subtract_floats = 3.3;
+const subtract_floats = 3.1;
 // were doing multiplication in the type system now?!
 // yup.
 const multiply_normal = 6;
@@ -34,5 +34,6 @@ const fraction_normal = 0.1415;
 const fraction_negative = 0.1415;
 // With type variable
 const pi = 3.141;
+// @ts-expect-error 2589 — Recently this started to become too deep even though it worked in the past
 const octo_pi = 24.1128;
 export {};

package/dist/types.d.ts

@@ -1,3 +1,4 @@
+import type { Length, Unshift, Push, FromLength } from './array.js';
 import type { Subtract } from './type-math.js';
 /**
  * Expands the type T (for intellisense and debugging)
@@ -23,97 +24,16 @@ type StrictUnionHelper<T, TAll> = T extends unknown ? T & Partial<Record<Exclude
  * @see https://stackoverflow.com/a/65805753/17637456
  */
 export type StrictUnion<T> = Expand<StrictUnionHelper<T, T>>;
-/**
- * Empty
- */
-export type Empty = [];
-/**
- * Removes the first element of T and shifts
- */
-export type Shift<T extends unknown[]> = T extends [unknown, ...infer Rest] ? Rest : never;
-/**
- * Gets the first element of T
- */
-export type First<T extends unknown[]> = T extends [infer F, ...unknown[]] ? F : never;
-/**
- * Inserts V into T at the start of T
- */
-export type Unshift<T extends unknown[], V> = [V, ...T];
-/**
- * Removes the last element of T
- */
-export type Pop<T extends unknown[]> = T extends [...infer _, unknown] ? _ : never;
-/**
- * Gets the last element of T
- */
-export type Last<T extends unknown[]> = T extends [...unknown[], infer Last] ? Last : never;
-/**
- * Appends V to T
- */
-export type Push<T extends unknown[], V> = [...T, V];
-/**
- * Concats A and B
- */
-export type Concat<A extends unknown[], B extends unknown[]> = Empty extends B ? A : Concat<Unshift<A, 0>, Shift<B>>;
-/**
- * Extracts from A what is not B
- *
- * @remarks
- * It does not remove duplicates (so Remove\<[0, 0, 0], [0, 0]\> yields [0]). This is intended and necessary behavior.
- */
-export type Remove<A extends unknown[], B extends unknown[]> = Empty extends B ? A : Remove<Shift<A>, Shift<B>>;
-/**
- * The length of T
- */
-export type Length<T extends unknown[]> = T extends {
-    length: infer L extends number;
-} ? L : never;
-type _FromLength<N extends number, R extends unknown[] = Empty> = Length<R> extends N ? R : _FromLength<N, Unshift<R, 0>>;
-/**
- * Creates a tuple of length N
- */
-export type FromLength<N extends number> = _FromLength<N>;
 /**
  * Increments N
  * @deprecated Use Add<N, 1> instead
  */
-export type Increment<N extends number> = Length<Unshift<_FromLength<N>, 0>>;
+export type Increment<N extends number> = Length<Unshift<FromLength<N>, 0>>;
 /**
  * Decrements N
  * @deprecated Use Subtract<N, 1> instead
  */
 export type Decrement<N extends number> = Subtract<N, 1>;
-/**
- * Gets the type of an array's members
- */
-export type Member<T, D = null> = D extends 0 ? T : T extends (infer U)[] ? Member<U, D extends number ? Subtract<D, 1> : null> : T;
-/**
- * Flattens an array
- */
-export type FlattenArray<A extends unknown[], D = null> = A extends (infer U)[] ? Member<Exclude<U, A>, D>[] : A extends unknown[] ? {
-    [K in keyof A]: Member<A[K], D>;
-} : A;
-/**
- * Whether T is a tuple
- */
-export type IsTuple<T> = T extends [] ? false : T extends [infer _Head, ...infer _Rest] ? true : false;
-/**
- * Flattens a tuple
- */
-export type FlattenTuple<A extends unknown[]> = A extends [infer U, ...infer Rest] ? U extends unknown[] ? [...U, ...FlattenTuple<Rest>] : [U, ...FlattenTuple<Rest>] : [];
-/**
- * Flattens an array or tuple
- */
-export type Flatten<A extends unknown[]> = IsTuple<A> extends true ? FlattenTuple<A> : FlattenArray<A>;
-type _Tuple<T, N extends number, R extends unknown[] = Empty> = R['length'] extends N ? R : _Tuple<T, N, [T, ...R]>;
-/**
- * Creates a tuple of T with length N
- */
-export type Tuple<T, N extends number> = _Tuple<T, N>;
-/**
- * Makes all members of the tuple T optional
- */
-export type OptionalTuple<T extends unknown[]> = T extends [infer Head, ...infer Tail] ? [Head?, ...OptionalTuple<Tail>] : T;
 /**
  * Keys of a Map
  */

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "utilium",
-	"version": "2.7.2",
+	"version": "2.8.1",
 	"description": "Typescript utilities",
 	"funding": {
 		"type": "individual",