utilium 2.4.0 → 2.5.1

package/LICENSE.md

@@ -0,0 +1,157 @@
+# GNU LESSER GENERAL PUBLIC LICENSE
+
+Version 3, 29 June 2007
+
+Copyright (C) 2007 Free Software Foundation, Inc.
+<https://fsf.org/>
+
+Everyone is permitted to copy and distribute verbatim copies of this
+license document, but changing it is not allowed.
+
+This version of the GNU Lesser General Public License incorporates the
+terms and conditions of version 3 of the GNU General Public License,
+supplemented by the additional permissions listed below.
+
+## 0. Additional Definitions.
+
+As used herein, "this License" refers to version 3 of the GNU Lesser
+General Public License, and the "GNU GPL" refers to version 3 of the
+GNU General Public License.
+
+"The Library" refers to a covered work governed by this License, other
+than an Application or a Combined Work as defined below.
+
+An "Application" is any work that makes use of an interface provided
+by the Library, but which is not otherwise based on the Library.
+Defining a subclass of a class defined by the Library is deemed a mode
+of using an interface provided by the Library.
+
+A "Combined Work" is a work produced by combining or linking an
+Application with the Library. The particular version of the Library
+with which the Combined Work was made is also called the "Linked
+Version".
+
+The "Minimal Corresponding Source" for a Combined Work means the
+Corresponding Source for the Combined Work, excluding any source code
+for portions of the Combined Work that, considered in isolation, are
+based on the Application, and not on the Linked Version.
+
+The "Corresponding Application Code" for a Combined Work means the
+object code and/or source code for the Application, including any data
+and utility programs needed for reproducing the Combined Work from the
+Application, but excluding the System Libraries of the Combined Work.
+
+## 1. Exception to Section 3 of the GNU GPL.
+
+You may convey a covered work under sections 3 and 4 of this License
+without being bound by section 3 of the GNU GPL.
+
+## 2. Conveying Modified Versions.
+
+If you modify a copy of the Library, and, in your modifications, a
+facility refers to a function or data to be supplied by an Application
+that uses the facility (other than as an argument passed when the
+facility is invoked), then you may convey a copy of the modified
+version:
+
+-   a) under this License, provided that you make a good faith effort
+    to ensure that, in the event an Application does not supply the
+    function or data, the facility still operates, and performs
+    whatever part of its purpose remains meaningful, or
+-   b) under the GNU GPL, with none of the additional permissions of
+    this License applicable to that copy.
+
+## 3. Object Code Incorporating Material from Library Header Files.
+
+The object code form of an Application may incorporate material from a
+header file that is part of the Library. You may convey such object
+code under terms of your choice, provided that, if the incorporated
+material is not limited to numerical parameters, data structure
+layouts and accessors, or small macros, inline functions and templates
+(ten or fewer lines in length), you do both of the following:
+
+-   a) Give prominent notice with each copy of the object code that
+    the Library is used in it and that the Library and its use are
+    covered by this License.
+-   b) Accompany the object code with a copy of the GNU GPL and this
+    license document.
+
+## 4. Combined Works.
+
+You may convey a Combined Work under terms of your choice that, taken
+together, effectively do not restrict modification of the portions of
+the Library contained in the Combined Work and reverse engineering for
+debugging such modifications, if you also do each of the following:
+
+-   a) Give prominent notice with each copy of the Combined Work that
+    the Library is used in it and that the Library and its use are
+    covered by this License.
+-   b) Accompany the Combined Work with a copy of the GNU GPL and this
+    license document.
+-   c) For a Combined Work that displays copyright notices during
+    execution, include the copyright notice for the Library among
+    these notices, as well as a reference directing the user to the
+    copies of the GNU GPL and this license document.
+-   d) Do one of the following:
+    -   0) Convey the Minimal Corresponding Source under the terms of
+        this License, and the Corresponding Application Code in a form
+        suitable for, and under terms that permit, the user to
+        recombine or relink the Application with a modified version of
+        the Linked Version to produce a modified Combined Work, in the
+        manner specified by section 6 of the GNU GPL for conveying
+        Corresponding Source.
+    -   1) Use a suitable shared library mechanism for linking with
+        the Library. A suitable mechanism is one that (a) uses at run
+        time a copy of the Library already present on the user's
+        computer system, and (b) will operate properly with a modified
+        version of the Library that is interface-compatible with the
+        Linked Version.
+-   e) Provide Installation Information, but only if you would
+    otherwise be required to provide such information under section 6
+    of the GNU GPL, and only to the extent that such information is
+    necessary to install and execute a modified version of the
+    Combined Work produced by recombining or relinking the Application
+    with a modified version of the Linked Version. (If you use option
+    4d0, the Installation Information must accompany the Minimal
+    Corresponding Source and Corresponding Application Code. If you
+    use option 4d1, you must provide the Installation Information in
+    the manner specified by section 6 of the GNU GPL for conveying
+    Corresponding Source.)
+
+## 5. Combined Libraries.
+
+You may place library facilities that are a work based on the Library
+side by side in a single library together with other library
+facilities that are not Applications and are not covered by this
+License, and convey such a combined library under terms of your
+choice, if you do both of the following:
+
+-   a) Accompany the combined library with a copy of the same work
+    based on the Library, uncombined with any other library
+    facilities, conveyed under the terms of this License.
+-   b) Give prominent notice with the combined library that part of it
+    is a work based on the Library, and explaining where to find the
+    accompanying uncombined form of the same work.
+
+## 6. Revised Versions of the GNU Lesser General Public License.
+
+The Free Software Foundation may publish revised and/or new versions
+of the GNU Lesser General Public License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns.
+
+Each version is given a distinguishing version number. If the Library
+as you received it specifies that a certain numbered version of the
+GNU Lesser General Public License "or any later version" applies to
+it, you have the option of following the terms and conditions either
+of that published version or of any later version published by the
+Free Software Foundation. If the Library as you received it does not
+specify a version number of the GNU Lesser General Public License, you
+may choose any version of the GNU Lesser General Public License ever
+published by the Free Software Foundation.
+
+If the Library as you received it specifies that a proxy can decide
+whether future versions of the GNU Lesser General Public License shall
+apply, that proxy's public statement of acceptance of any version is
+permanent authorization for you to choose that version for the
+Library.

package/dist/buffer.js

@@ -1,3 +1,5 @@
+// SPDX-License-Identifier: LGPL-3.0-or-later
+// Copyright (c) 2025 James Prevett
 /* eslint-disable @typescript-eslint/no-unused-expressions */
 /**
  * Grows a buffer if it isn't large enough

package/dist/cache.js

@@ -1,4 +1,8 @@
-/** A ranged cache */
+// SPDX-License-Identifier: LGPL-3.0-or-later
+/**
+ * A ranged cache
+ * Copyright (c) 2025 James Prevett
+ */
 import { extendBuffer } from './buffer.js';
 /**
  * The cache for a specific resource

package/dist/checksum.d.ts

@@ -1,4 +1,7 @@
-/** Utilities for computing checksums */
+/**
+ * Utilities for computing checksums
+ * Copyright (c) 2025 James Prevett
+ */
 /**
  * Computes the CRC32C checksum of a Uint8Array.
  */

package/dist/checksum.js

@@ -1,4 +1,8 @@
-/** Utilities for computing checksums */
+// SPDX-License-Identifier: LGPL-3.0-or-later
+/**
+ * Utilities for computing checksums
+ * Copyright (c) 2025 James Prevett
+ */
 // Precompute CRC32C table
 const crc32cTable = new Uint32Array(256);
 for (let i = 0; i < 256; i++) {

package/dist/debugging.js

@@ -1,3 +1,5 @@
+// SPDX-License-Identifier: LGPL-3.0-or-later
+// Copyright (c) 2025 James Prevett
 function defaultStringify(value) {
     switch (typeof value) {
         case 'undefined':

package/dist/dom.js

@@ -1,3 +1,5 @@
+// SPDX-License-Identifier: LGPL-3.0-or-later
+// Copyright (c) 2025 James Prevett
 /* eslint-disable @typescript-eslint/no-unused-expressions */
 /**
  * Upload a file

package/dist/fs.js

@@ -1,3 +1,5 @@
+// SPDX-License-Identifier: LGPL-3.0-or-later
+// Copyright (c) 2025 James Prevett
 import { isJSON } from './objects.js';
 import * as fs from 'fs';
 export class FileMap {

package/dist/index.d.ts

@@ -4,5 +4,6 @@ export * from './numbers.js';
 export * from './objects.js';
 export * from './random.js';
 export * from './string.js';
+export * from './type-math.js';
 export * from './types.js';
 export * as version from './version.js';

package/dist/index.js

@@ -1,3 +1,5 @@
+// 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 './list.js';
 export * from './misc.js';
@@ -5,5 +7,6 @@ export * from './numbers.js';
 export * from './objects.js';
 export * from './random.js';
 export * from './string.js';
+export * from './type-math.js';
 export * from './types.js';
 export * as version from './version.js';

package/dist/list.js

@@ -1,3 +1,5 @@
+// SPDX-License-Identifier: LGPL-3.0-or-later
+// Copyright (c) 2025 James Prevett
 import { EventEmitter } from 'eventemitter3';
 export class List extends EventEmitter {
     [Symbol.toStringTag] = 'List';

package/dist/misc.js

@@ -1,3 +1,5 @@
+// SPDX-License-Identifier: LGPL-3.0-or-later
+// Copyright (c) 2025 James Prevett
 import { resolveConstructors } from './objects.js';
 export function wait(time) {
     return new Promise(resolve => setTimeout(resolve, time));

package/dist/numbers.js

@@ -1,3 +1,5 @@
+// SPDX-License-Identifier: LGPL-3.0-or-later
+// Copyright (c) 2025 James Prevett
 export function range(min, max) {
     const a = [];
     for (let i = min; i < max; i++) {

package/dist/objects.d.ts

@@ -65,3 +65,70 @@ export declare function bindFunctions<T extends object, This = any>(fns: T, this
 export type Mutable<T> = {
     -readonly [P in keyof T]: T[P];
 };
+/**
+ * Makes properties with keys assignable to K in T required
+ * @see https://stackoverflow.com/a/69328045/17637456
+ */
+export type WithRequired<T, K extends keyof T> = T & {
+    [P in K]-?: T[P];
+};
+/**
+ * Makes properties with keys assignable to K in T optional
+ */
+export type WithOptional<T, K extends keyof T> = Pick<Partial<T>, K> & Omit<T, K>;
+export type ClassLike<Instance = any> = abstract new (...args: any[]) => Instance;
+export type InstancesFor<T extends readonly ClassLike[]> = T extends [] ? [] : T extends readonly [infer C extends ClassLike, ...infer Rest extends readonly ClassLike[]] ? [InstanceType<C>, ...InstancesFor<Rest>] : never;
+export type ConstructorsFor<T extends readonly unknown[]> = T extends [] ? [] : T extends readonly [infer I, ...infer Rest extends readonly unknown[]] ? [new (...args: any[]) => I, ...ConstructorsFor<Rest>] : never;
+export type Concrete<T extends ClassLike> = Pick<T, keyof T> & (new (...args: any[]) => InstanceType<T>);
+/**
+ * Extracts an object with properties assignable to P from an object T
+ * @see https://stackoverflow.com/a/71532723/17637456
+ */
+export type ExtractProperties<T, P> = {
+    [K in keyof T as T[K] extends infer Prop ? (Prop extends P ? K : never) : never]: T[K];
+};
+/**
+ * Extract the keys of T which are required
+ * @see https://stackoverflow.com/a/55247867/17637456
+ */
+export type RequiredKeys<T> = {
+    [K in keyof T]-?: {} extends {
+        [P in K]: T[K];
+    } ? never : K;
+}[keyof T];
+/**
+ * @see https://dev.to/tmhao2005/ts-useful-advanced-types-3k5e
+ */
+export type RequiredProperties<T extends object, K extends keyof T = keyof T> = Omit<T, K> & Required<Pick<T, K>>;
+/**
+ * @see https://dev.to/tmhao2005/ts-useful-advanced-types-3k5e
+ */
+export type DeepRequired<T> = {
+    [K in keyof T]-?: DeepRequired<T[K]>;
+};
+/**
+ * @see https://dev.to/tmhao2005/ts-useful-advanced-types-3k5e
+ */
+export type Optional<T, K extends keyof T> = Omit<T, K> & Partial<T>;
+/**
+ * @see https://dev.to/tmhao2005/ts-useful-advanced-types-3k5e
+ */
+export type NestedKeys<T extends object> = {
+    [P in keyof T & (string | number)]: T[P] extends Date ? `${P}` : T[P] extends Record<string, unknown> ? `${P}` | `${P}.${NestedKeys<T[P]>}` : `${P}`;
+}[keyof T & (string | number)];
+/**
+ * @see https://dev.to/tmhao2005/ts-useful-advanced-types-3k5e
+ */
+export type PartialRecursive<T> = {
+    [P in keyof T]?: T[P] extends (infer U)[] ? PartialRecursive<U>[] : T[P] extends object | undefined ? PartialRecursive<T[P]> : T[P];
+};
+/**
+ * Nothing in T
+ */
+export type Never<T> = {
+    [K in keyof T]?: never;
+};
+/**
+ * All of the properties in T or none of them
+ */
+export type AllOrNone<T> = T | Never<T>;

package/dist/objects.js

@@ -1,3 +1,6 @@
+// SPDX-License-Identifier: LGPL-3.0-or-later
+// Copyright (c) 2025 James Prevett
+/* eslint-disable @typescript-eslint/no-explicit-any */
 export function filterObject(object, predicate) {
     const entries = Object.entries(object);
     return Object.fromEntries(entries.filter(([key, value]) => predicate(key, value)));

package/dist/random.js

@@ -1,3 +1,5 @@
+// SPDX-License-Identifier: LGPL-3.0-or-later
+// Copyright (c) 2025 James Prevett
 export function randomFloat(min = 0, max = 1) {
     return Math.random() * (max - min) + min;
 }

package/dist/requests.d.ts

@@ -1,3 +1,8 @@
+/**
+ * Utilities for `fetch` when using range requests.
+ * It also allows you to handle errors easier
+ * Copyright (c) 2025 James Prevett
+ */
 import * as cache from './cache.js';
 /** @deprecated Use `cache.Options` */
 export type ResourceCacheOptions = cache.Options;

package/dist/requests.js

@@ -1,4 +1,9 @@
-/* Utilities for `fetch` when using range requests. It also allows you to handle errors easier */
+// SPDX-License-Identifier: LGPL-3.0-or-later
+/**
+ * Utilities for `fetch` when using range requests.
+ * It also allows you to handle errors easier
+ * Copyright (c) 2025 James Prevett
+ */
 import * as cache from './cache.js';
 /** @deprecated Use `cache.Resource` */
 export const ResourceCache = cache.Resource;

package/dist/shell.d.ts

@@ -1,3 +1,7 @@
+/**
+ * A simple wrapper for xterm.js that makes implementing shells easier
+ * Copyright (c) 2025 James Prevett
+ */
 import type { Terminal } from '@xterm/xterm';
 export interface ShellOptions {
     /**

package/dist/shell.js

@@ -1,3 +1,8 @@
+// SPDX-License-Identifier: LGPL-3.0-or-later
+/**
+ * A simple wrapper for xterm.js that makes implementing shells easier
+ * Copyright (c) 2025 James Prevett
+ */
 async function handleData($, data) {
     if ($.index == -1) {
         $.currentInput = $.input;

package/dist/string.d.ts

@@ -1,3 +1,4 @@
+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>;
 export type ConcatString<T extends string[]> = T extends [infer F extends string, ...infer R extends string[]] ? `${F}${ConcatString<R>}` : '';
@@ -22,3 +23,11 @@ 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;
+/**
+ * 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 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}`;

package/dist/string.js

@@ -1,3 +1,5 @@
+// SPDX-License-Identifier: LGPL-3.0-or-later
+// Copyright (c) 2025 James Prevett
 export function capitalize(value) {
     return (value.at(0).toUpperCase() + value.slice(1));
 }

package/dist/type-math.d.ts

@@ -0,0 +1,132 @@
+/**
+ * Type-system arithmetic.
+ * Copyright (c) 2025 James Prevett
+ *
+ * Notes on implementation:
+ *
+ * Snake case is used for internal types to reduce visual conflict/confusion with type variables.
+ * Type naming convention:
+ * `w_*` => internals that operate on whole numbers (i.e. n >= 0)
+ * `i_*` => internals that operate on integers
+ * `_*`  => general purpose internals
+ *
+ */
+import type { Repeat, StringLength } from './string.js';
+import type { $drain, Length } from './types.js';
+/**
+ * Maps a numeric literal type to a tuple type with that length
+ */
+type __tuple<L extends number, T extends any[] = []> = T extends {
+    length: L;
+} ? T : __tuple<L, [...T, any]>;
+/**
+ * Sum A and B (both must be whole numbers)
+ */
+type w_add<A extends number, B extends number> = Length<[...__tuple<A>, ...__tuple<B>]>;
+/**
+ * Subtracts B from A (both must be whole numbers)
+ */
+export type w_subtract<A extends number, B extends number> = __tuple<A> extends [...infer U, ...__tuple<B>] ? Length<U> : never;
+/**
+ * Is A strictly equal to B?
+ */
+export type Equal<A, B> = A extends B ? (B extends A ? true : false) : false;
+/**
+ * Is A or B zero?
+ */
+type _either_zero<A extends number, B extends number> = A extends 0 ? true : B extends 0 ? true : false;
+/**
+ * Is A less than B? (whole numbers)
+ */
+type w_less<A extends number, B extends number> = _either_zero<A, B> extends true ? Equal<A, B> extends true ? false : A extends 0 ? true : false : w_less<w_subtract<A, 1>, w_subtract<B, 1>>;
+/**
+ * Negate *any* number.
+ */
+export type Negate<N extends number> = N extends 0 ? 0 : `-${N}` extends `${infer V extends number}` ? V : `${N}` extends `-${infer V extends number}` ? V : never;
+export type Absolute<N extends number> = N extends 0 ? 0 : `${N}` extends `-${infer V extends number}` ? V : N;
+export type Is_Negative<N extends number> = `${N}` extends `-${number}` ? true : false;
+export type Is_Positive<N extends number> = `-${N}` extends `${number}` ? true : false;
+type _is_int<N extends number> = `${N}` extends `${number}.${number}` ? false : true;
+type _are_ints<A extends number, B extends number> = _is_int<A> extends true ? (_is_int<B> extends true ? true : false) : false;
+/**
+ * While `i_sum` is just as convenient and also more robust, this has a depth of 1 instead of 3.
+ */
+type i_increment<N extends number, I extends number = 1> = `${N}` extends `-${infer Abs extends number}` ? Negate<w_add<Abs, I>> : w_add<N, I>;
+/**
+ * While `i_sum` is just as convenient and also more robust, this has a depth of 1 instead of 3.
+ */
+type i_decrement<N extends number, I extends number = 1> = `${N}` extends `-${infer Abs extends number}` ? Negate<w_subtract<Abs, I>> : w_subtract<N, I>;
+/**
+ * Sum integers A and B.
+ *
+ * Does not perform integer validation!
+ * @internal
+ */
+type i_sum<A extends number, B extends number> = `${A}` extends `-${infer A_abs extends number}` ? `${B}` extends `-${infer B_abs extends number}` ? Negate<w_add<A_abs, B_abs>> : w_less<A_abs, B> extends true ? w_subtract<B, A_abs> : Negate<w_subtract<A_abs, B>> : `${B}` extends `-${infer B_abs extends number}` ? w_less<A, B_abs> extends true ? Negate<w_subtract<B_abs, A>> : w_subtract<A, B_abs> : w_add<A, B>;
+/**
+ * Add integers A and B.
+ * @internal
+ */
+export type $Add<A extends number, B extends number> = _are_ints<A, B> extends true ? i_sum<A, B> : never;
+/**
+ * Subtract integer B from A.
+ * @internal
+ */
+export type $Subtract<A extends number, B extends number> = _are_ints<A, B> extends true ? i_sum<A, Negate<B>> : never;
+/**
+ * Is A less than B?
+ * @internal
+ */
+type i_less<A extends number, B extends number> = $drain<_either_zero<A, B> extends true ? Equal<A, B> extends true ? false : A extends 0 ? true : false : i_less<i_decrement<A>, i_decrement<B>>>;
+export type $LessThan<A extends number, B extends number> = _are_ints<A, B> extends true ? i_less<A, B> : never;
+type i_max<A extends number, B extends number> = i_less<A, B> extends true ? B : A;
+export type $Max<A extends number, B extends number> = _are_ints<A, B> extends true ? i_max<A, B> : never;
+/**
+ * Accumulative subtraction:
+ * N: initial value
+ * D: divisor
+ * Q: quotient
+ */
+type w_divide<N extends number, D extends number, Q extends number> = $drain<D extends 0 ? never : i_less<N, D> extends true ? Q : w_divide<i_sum<N, Negate<D>>, D, i_increment<Q>>>;
+/**
+ * Integer division
+ */
+type i_divide<A extends number, B extends number> = `${A}` extends `-${infer A_abs extends number}` ? `${B}` extends `-${infer B_abs extends number}` ? w_divide<A_abs, B_abs, 0> : Negate<w_divide<A_abs, B, 0>> : `${B}` extends `-${infer B_abs extends number}` ? Negate<w_divide<A, B_abs, 0>> : w_divide<A, B, 0>;
+/**
+ * Integer division
+ */
+export type Divide<A extends number, B extends number> = _are_ints<A, B> extends true ? i_divide<A, B> : never;
+/**
+ * Modulo
+ */
+export type Modulo<A extends number, B extends number> = _are_ints<A, B> extends true ? (i_less<A, B> extends true ? A : Modulo<i_sum<A, Negate<B>>, B>) : never;
+/**
+ * Get the integer part of a number
+ */
+export type Integer<N extends number> = `${N}` extends `${infer I extends number}.${string}` ? I : N;
+/**
+ * Get the fractional part of a number
+ */
+export type Fraction<N extends number> = `${N}` extends `${number}.${infer S extends string}` ? `0.${S}` extends `${infer F extends number}` ? F : never : 0;
+type _f_sum_str<A_s extends string, B_s extends string, _A_neg extends boolean, _B_neg extends boolean, _A_len extends number = StringLength<A_s>, _B_len extends number = StringLength<B_s>> = $drain<Repeat<'0', i_max<0, w_subtract<_B_len, _A_len>>, A_s>> extends `${infer A_f extends number}` ? $drain<Repeat<'0', i_max<0, w_subtract<_A_len, _B_len>>, B_s>> extends `${infer B_f extends number}` ? i_sum<_A_neg extends true ? Negate<A_f> : A_f, _B_neg extends true ? Negate<B_f> : B_f> : never : never;
+/**
+ * Sum the fractional parts A and B of two numbers
+ */
+type f_sum<A extends number, B extends number, _A_neg extends boolean, _B_neg extends boolean> = `${A}` extends `0.${infer A_s extends string}` ? `${B}` extends `0.${infer B_s extends string}` ? `0.${_f_sum_str<A_s, B_s, _A_neg, _B_neg>}` extends `${infer F extends number}` ? F : never : never : never;
+type _sum_with_f<A extends number, B extends number, F extends number> = `${F}` extends `${infer C extends number}.${infer S}` ? `${i_sum<i_sum<Integer<A>, Integer<B>>, C>}.${S}` extends `${infer V extends number}` ? V : never : never;
+export type Add<A extends number, B extends number, __fA extends number = Fraction<A>, __fB extends number = Fraction<B>> = __fA extends 0 ? __fB extends 0 ? i_sum<A, B> : _sum_with_f<A, B, __fB> : __fB extends 0 ? _sum_with_f<A, B, __fA> : _sum_with_f<A, B, f_sum<__fA, __fB, Is_Negative<A>, Is_Negative<B>>>;
+export type Subtract<A extends number, B extends number> = Add<A, Negate<B>>;
+/**
+ * Accumulative addition:
+ * N: increment
+ * I: iterations (must be a whole number)
+ * A: sum
+ */
+type _mul_accumulate<N extends number, I extends number, A extends number> = $drain<I extends 0 ? A : _mul_accumulate<N, i_decrement<I>, Add<N, A>>>;
+/**
+ * Multiplication.
+ *
+ * Current limitation: B must be an integer.
+ */
+export type Multiply<A extends number, B extends number> = `${B}` extends `${number}.${number}` ? never : `${B}` extends `-${infer B_abs extends number}` ? Negate<_mul_accumulate<A, B_abs, 0>> : _mul_accumulate<A, B, 0>;
+export {};

package/dist/type-math.js

@@ -0,0 +1,15 @@
+// SPDX-License-Identifier: LGPL-3.0-or-later
+/**
+ * Type-system arithmetic.
+ * Copyright (c) 2025 James Prevett
+ *
+ * Notes on implementation:
+ *
+ * Snake case is used for internal types to reduce visual conflict/confusion with type variables.
+ * Type naming convention:
+ * `w_*` => internals that operate on whole numbers (i.e. n >= 0)
+ * `i_*` => internals that operate on integers
+ * `_*`  => general purpose internals
+ *
+ */
+export {};

package/dist/type-math.test.d.ts

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

package/dist/type-math.test.js

@@ -0,0 +1,38 @@
+// SPDX-License-Identifier: LGPL-3.0-or-later
+// Copyright (c) 2025 James Prevett
+// addition
+const add_positive = 3;
+const add_zero = 0;
+const add_diff_signs = -1;
+const add_negative = -3;
+const add_float = 1.7;
+// @ts-expect-error 2 + 2 != 5
+let fail = 5;
+fail = 4;
+// subtraction for sanity
+const subtract_normal = -18;
+const subtract_from_neg = -9;
+const subtract_both_neg = 5;
+const subtract_zero = -1;
+const subtract_floats = 3.3;
+// were doing multiplication in the type system now?!
+// yup.
+const multiply_normal = 6;
+const multiply_by_zero = 0;
+const multiply_negative = -12;
+const multiply_both_negative = 21;
+const multiply_large = 896;
+// division
+const divide_normal = 5;
+const divide_by_zero = NaN;
+const divide_negative = -4;
+const divide_both_negative = 6;
+// floor/fraction
+const int_normal = 3;
+const int_negative = -3;
+const fraction_normal = 0.1415;
+const fraction_negative = 0.1415;
+// With type variable
+const pi = 3.141;
+const octo_pi = 24.1128;
+export {};

package/dist/types.d.ts

@@ -1,3 +1,4 @@
+import type { Subtract } from './type-math.js';
 /**
  * Expands the type T (for intellisense and debugging)
  * @see https://stackoverflow.com/a/69288824/17637456
@@ -12,48 +13,6 @@ export type Expand<T> = T extends (...args: infer A) => infer R ? (...args: Expa
 export type ExpandRecursively<T> = T extends (...args: infer A) => infer R ? (...args: ExpandRecursively<A>) => ExpandRecursively<R> : T extends object ? T extends infer O ? {
     [K in keyof O]: ExpandRecursively<O[K]>;
 } : never : T;
-/**
- * Extracts an object with properties assignable to P from an object T
- * @see https://stackoverflow.com/a/71532723/17637456
- */
-export type ExtractProperties<T, P> = {
-    [K in keyof T as T[K] extends infer Prop ? (Prop extends P ? K : never) : never]: T[K];
-};
-/**
- * Extract the keys of T which are required
- * @see https://stackoverflow.com/a/55247867/17637456
- */
-export type RequiredKeys<T> = {
-    [K in keyof T]-?: {} extends {
-        [P in K]: T[K];
-    } ? never : K;
-}[keyof T];
-/**
- * @see https://dev.to/tmhao2005/ts-useful-advanced-types-3k5e
- */
-export type RequiredProperties<T extends object, K extends keyof T = keyof T> = Omit<T, K> & Required<Pick<T, K>>;
-/**
- * @see https://dev.to/tmhao2005/ts-useful-advanced-types-3k5e
- */
-export type DeepRequired<T> = {
-    [K in keyof T]-?: DeepRequired<T[K]>;
-};
-/**
- * @see https://dev.to/tmhao2005/ts-useful-advanced-types-3k5e
- */
-export type Optional<T, K extends keyof T> = Omit<T, K> & Partial<T>;
-/**
- * @see https://dev.to/tmhao2005/ts-useful-advanced-types-3k5e
- */
-export type NestedKeys<T extends object> = {
-    [P in keyof T & (string | number)]: T[P] extends Date ? `${P}` : T[P] extends Record<string, unknown> ? `${P}` | `${P}.${NestedKeys<T[P]>}` : `${P}`;
-}[keyof T & (string | number)];
-/**
- * @see https://dev.to/tmhao2005/ts-useful-advanced-types-3k5e
- */
-export type PartialRecursive<T> = {
-    [P in keyof T]?: T[P] extends (infer U)[] ? PartialRecursive<U>[] : T[P] extends object | undefined ? PartialRecursive<T[P]> : T[P];
-};
 /**
  * Get the keys of a union of objects
  * @see https://stackoverflow.com/a/65805753/17637456
@@ -106,9 +65,9 @@ export type Remove<A extends unknown[], B extends unknown[]> = Empty extends B ?
 /**
  * The length of T
  */
-export type Length<T extends {
-    length: number;
-}> = T['length'];
+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
@@ -116,24 +75,18 @@ type _FromLength<N extends number, R extends unknown[] = Empty> = Length<R> exte
 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>>;
 /**
  * Decrements N
+ * @deprecated Use Subtract<N, 1> instead
  */
-export type Decrement<N extends number> = Length<Shift<_FromLength<N>>>;
-/**
- * Gets the sum of A and B
- */
-export type Add<A extends number, B extends number> = Length<Concat<_FromLength<A>, _FromLength<B>>>;
-/**
- * Subtracts B from A
- */
-export type Subtract<A extends number, B extends number> = Length<Remove<_FromLength<A>, _FromLength<B>>>;
+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 ? Decrement<D> : null> : T;
+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
  */
@@ -165,10 +118,6 @@ export type OptionalTuple<T extends unknown[]> = T extends [infer Head, ...infer
  * Keys of a Map
  */
 export type MapKeys<T> = T extends Map<infer K, any> ? K : never;
-export type ClassLike<Instance = any> = abstract new (...args: any[]) => Instance;
-export type InstancesFor<T extends readonly ClassLike[]> = T extends [] ? [] : T extends readonly [infer C extends ClassLike, ...infer Rest extends readonly ClassLike[]] ? [InstanceType<C>, ...InstancesFor<Rest>] : never;
-export type ConstructorsFor<T extends readonly unknown[]> = T extends [] ? [] : T extends readonly [infer I, ...infer Rest extends readonly unknown[]] ? [new (...args: any[]) => I, ...ConstructorsFor<Rest>] : never;
-export type Concrete<T extends ClassLike> = Pick<T, keyof T> & (new (...args: any[]) => InstanceType<T>);
 /**
  * Converts a union to an intersection
  * @see https://stackoverflow.com/a/55128956/17637456
@@ -185,24 +134,9 @@ export type LastOfUnion<T> = UnionToIntersection<T extends any ? () => T : never
  */
 export type UnionToTuple<T, L = LastOfUnion<T>, N = [T] extends [never] ? true : false> = true extends N ? [] : Push<UnionToTuple<Exclude<T, L>>, L>;
 /**
- * Makes properties with keys assignable to K in T required
- * @see https://stackoverflow.com/a/69328045/17637456
- */
-export type WithRequired<T, K extends keyof T> = T & {
-    [P in K]-?: T[P];
-};
-/**
- * Makes properties with keys assignable to K in T optional
- */
-export type WithOptional<T, K extends keyof T> = Pick<Partial<T>, K> & Omit<T, K>;
-/**
- * Nothing in T
- */
-export type Never<T> = {
-    [K in keyof T]?: never;
-};
-/**
- * All of the properties in T or none of them
+ * Utility to reduce depth of TypeScript's internal type instantiation stack.
+ * Some wizard on the Kysely team came up with this.
+ * It improves performance for the math types by an order of magnitude.
  */
-export type AllOrNone<T> = T | Never<T>;
+export type $drain<T> = [T] extends [unknown] ? T : never;
 export {};

package/dist/types.js

@@ -1 +1,3 @@
+// SPDX-License-Identifier: LGPL-3.0-or-later
+// Copyright (c) 2025 James Prevett
 export {};

package/dist/version.js

@@ -1,3 +1,5 @@
+// SPDX-License-Identifier: LGPL-3.0-or-later
+// Copyright (c) 2025 James Prevett
 import { capitalize } from './string.js';
 export const regex = /^(?<core>\d+\.\d+\.\d+)(?:[-_](?<type>[^-_.]+)[-_.](?<pre>\d*(?:\.\d+)*))?/;
 export function parse(full, stripCore) {

package/eslint.shared.js

@@ -1,4 +1,8 @@
-/* Shared eslint rules */
+// SPDX-License-Identifier: LGPL-3.0-or-later
+/**
+ * Shared eslint rules
+ * Copyright (c) 2025 James Prevett
+ */
 import eslint from '@eslint/js';
 import globals from 'globals';
 import tseslint from 'typescript-eslint';

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "utilium",
-	"version": "2.4.0",
+	"version": "2.5.1",
 	"description": "Typescript utilities",
 	"funding": {
 		"type": "individual",
@@ -15,6 +15,9 @@
 		"./eslint": "./eslint.shared.js",
 		"./typedoc-no-ref": "./scripts/typedoc-no-ref.js"
 	},
+	"bin": {
+		"lice": "./scripts/lice.js"
+	},
 	"files": [
 		"dist",
 		"scripts",
@@ -31,7 +34,7 @@
 		"url": "git+https://github.com/james-pre/utilium.git"
 	},
 	"author": "James Prevett <jp@jamespre.dev> (https://jamespre.dev)",
-	"license": "MIT",
+	"license": "LGPL-3.0-or-later",
 	"bugs": {
 		"url": "https://github.com/james-pre/utilium/issues"
 	},

package/scripts/lice.js

@@ -0,0 +1,160 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: LGPL-3.0-or-later
+// Copyright (c) 2025 James Prevett
+
+import { readdirSync } from 'node:fs';
+import { readFile, writeFile } from 'node:fs/promises';
+import { join, matchesGlob, relative } from 'node:path';
+import { parseArgs, styleText } from 'node:util';
+
+const {
+	positionals: dirs,
+	values: { license: expectedLicense, write, verbose, force, exclude },
+} = parseArgs({
+	allowPositionals: true,
+	options: {
+		license: { type: 'string', short: 'L' },
+		write: { type: 'boolean', short: 'w', default: false },
+		verbose: { type: 'boolean', short: 'v', default: false },
+		force: { type: 'boolean', short: 'f', default: false },
+		exclude: { type: 'string', short: 'x', default: '' },
+	},
+});
+
+if (write && !expectedLicense) {
+	console.error(styleText('red', 'You must specify a license to write with --license/-L'));
+	process.exit(1);
+}
+
+const licenseSpec = /^\s*\/(?:\/|\*) SPDX-License-Identifier: (.+)/;
+
+async function check_file(path, display) {
+	if (matchesGlob(path, exclude)) {
+		console.log(styleText('whiteBright', ' (skipped)'));
+		return 'skipped';
+	}
+
+	const content = await readFile(path, 'utf-8');
+
+	const match = licenseSpec.exec(content);
+
+	if (!match) {
+		console.error(styleText('red', 'Missing:'), display);
+		return 'missing';
+	}
+
+	if (!expectedLicense) {
+		if (verbose) console.log(styleText(['dim'], 'Found: ') + display);
+		return 'with license';
+	}
+
+	const [, license] = match;
+
+	if (license == expectedLicense) {
+		if (verbose) console.log(styleText(['green', 'dim'], 'Correct: ') + display);
+		return 'correct';
+	}
+
+	console.warn(styleText('yellow', 'Mismatch:'), display);
+	return 'mismatched';
+}
+
+async function write_file(path, display) {
+	if (matchesGlob(path, exclude)) {
+		console.log(styleText('whiteBright', ' (skipped)'));
+		return 'skipped';
+	}
+
+	const content = await readFile(path, 'utf-8');
+
+	const match = licenseSpec.exec(content);
+
+	if (!match) {
+		await writeFile(path, `// SPDX-License-Identifier: ${expectedLicense}\n${content}`, 'utf-8');
+
+		console.log('Added: ' + display);
+		return 'added';
+	}
+
+	const [, license] = match;
+
+	if (license == expectedLicense) {
+		if (verbose) console.log(styleText(['green', 'dim'], 'Correct: ') + display);
+		return 'correct';
+	}
+
+	process.stdout.write(styleText('yellow', 'Mismatch: ') + display);
+
+	if (!force) {
+		console.log(styleText('whiteBright', ' (skipped)'));
+		return 'skipped';
+	}
+
+	await writeFile(path, content.replace(licenseSpec, `// SPDX-License-Identifier: ${expectedLicense}`), 'utf-8');
+	console.log(styleText('whiteBright', ' (overwritten)'));
+	return 'overwritten';
+}
+
+function check_dir(dir, display) {
+	const entries = readdirSync(dir, { withFileTypes: true });
+
+	const results = [];
+
+	for (const entry of entries) {
+		if (entry.isDirectory()) {
+			results.push(...check_dir(join(dir, entry.name), join(display, entry.name)));
+			continue;
+		}
+
+		if (!entry.isFile()) continue;
+
+		const op = write ? write_file : check_file;
+		results.push(op(join(dir, entry.name), join(display, entry.name)));
+	}
+
+	return results;
+}
+
+if (!dirs.length) {
+	console.error(styleText('red', 'No directories specified'));
+	process.exit(1);
+}
+
+if (verbose) console.log('Checking:', dirs.join(', '));
+
+const promises = [];
+
+for (const dir of dirs) {
+	const rel = relative(process.cwd(), dir);
+	promises.push(...check_dir(dir, rel.startsWith('..') ? dir : rel));
+}
+
+const styles = Object.assign(Object.create(null), {
+	missing: 'red',
+	'with license': 'white',
+	correct: 'green',
+	mismatched: 'yellow',
+	skipped: 'white',
+	added: 'cyan',
+	overwritten: 'magenta',
+});
+
+try {
+	const raw_results = await Promise.all(promises);
+	const results = Object.create(null);
+	for (const result of raw_results) {
+		if (!(result in results)) results[result] = 0;
+		results[result]++;
+	}
+	console.log(
+		write ? 'Wrote' : 'Checked',
+		styleText('blueBright', raw_results.length.toString()),
+		'files:',
+		Object.entries(results)
+			.map(([key, value]) => `${key in styles ? styleText(styles[key], value.toString()) : value} ${key}`)
+			.join(', ')
+	);
+} catch (error) {
+	console.error(styleText('red', error.toString()));
+	process.exit(1);
+}

package/scripts/typedoc-no-ref.js

@@ -1,3 +1,5 @@
+// SPDX-License-Identifier: LGPL-3.0-or-later
+// Copyright (c) 2025 James Prevett
 import { Converter, ReflectionKind } from 'typedoc';
 
 export function load({ application }) {