utilium 3.1.1 → 3.2.0

package/dist/diff.d.ts

@@ -0,0 +1,208 @@
+import type { CoercibleToString } from './string.js';
+import type { Subtract, SubtractBigInt } from './type-math.js';
+import type { ExpandRecursively, Falsy, UnionToTuple } from './types.js';
+/** @internal @hidden */
+export interface _EQ {
+    result: 'equal';
+}
+/** @internal @hidden */
+export interface _NEQ {
+    result: 'not-equal';
+}
+interface GenericResult {
+    type?: string;
+    result: string;
+}
+/** @internal @hidden */
+export interface _StringUnknownSubstring {
+    result: 'substring';
+    before: string;
+    after: string;
+    add: boolean;
+}
+/** @internal @hidden */
+export type _StringUnknown = _StringUnknownSubstring | _EQ | _NEQ;
+export type String<From extends string, To extends string> = string extends To ? _StringUnknown : string extends From ? _StringUnknown : To extends From ? _EQ : To extends `${infer Before}${From}${infer After}` ? {
+    result: 'substring';
+    before: Before;
+    after: After;
+    add: true;
+} : From extends `${infer Before}${To}${infer After}` ? {
+    result: 'substring';
+    before: Before;
+    after: After;
+    add: false;
+} : {
+    result: 'not-equal';
+};
+export declare function string<From extends string, To extends string>(from: From, to: To): String<From, To>;
+/** @internal @hidden */
+export interface _NumberUnknownDiff {
+    type: 'number';
+    result: 'diff';
+    value: number;
+}
+/** @internal @hidden */
+export type _NumberUnknown = _NumberUnknownDiff | (_NEQ & {
+    type: 'number';
+});
+/**
+ * Diff two numbers.
+ * `not-equal` is only returned when encountering `NaN` or infinite values
+ */
+export type Number<From extends number, To extends number> = number extends To ? _NumberUnknown : number extends From ? _NumberUnknown : To extends From ? _EQ & {
+    type: 'number';
+} : {
+    result: 'diff';
+    type: 'number';
+    value: Subtract<To, From>;
+};
+export declare function number<From extends number, To extends number>(from: From, to: To): Number<From, To>;
+/** @internal @hidden */
+export interface _BigIntUnknown {
+    type: 'bigint';
+    result: 'diff';
+    value: bigint;
+}
+export type BigInt<From extends bigint, To extends bigint> = bigint extends From ? _BigIntUnknown : bigint extends To ? _BigIntUnknown : From extends To ? _EQ & {
+    type: 'bigint';
+} : {
+    type: 'bigint';
+    result: 'diff';
+    value: SubtractBigInt<To, From>;
+};
+export declare function bigint<From extends bigint, To extends bigint>(from: From, to: To): BigInt<To, From>;
+/** @internal @hidden */
+export interface _BooleanUnknown {
+    type: 'boolean';
+    result: 'equal' | 'not-equal';
+}
+export type Boolean<From extends boolean, To extends boolean> = boolean extends From ? _BooleanUnknown : boolean extends To ? _BooleanUnknown : {
+    type: 'boolean';
+} & (From extends To ? _EQ : _NEQ);
+export declare function boolean<From extends boolean, To extends boolean>(from: From, to: To): Boolean<From, To>;
+type fn = (...args: unknown[]) => unknown;
+/** @internal @hidden */
+export interface _FunctionUnknownDiff {
+    type: 'function';
+    result: 'diff';
+    return: GenericResult;
+    args: _ArrayUnknown;
+}
+/** @internal @hidden */
+type _FunctionUnknown = _FunctionUnknownDiff | (_NEQ & {
+    type: 'function';
+}) | (_EQ & {
+    type: 'function';
+});
+/** @internal @hidden */
+export interface _FunctionType<From extends fn, To extends fn> {
+    type: 'function';
+    result: 'diff';
+    return: Deep<ReturnType<From>, ReturnType<To>>;
+    args: Array<Parameters<From>, Parameters<To>>;
+}
+export type FunctionType<From extends fn, To extends fn> = fn extends From ? _FunctionUnknown : fn extends To ? _FunctionUnknown : From extends To ? To extends From ? _EQ & {
+    type: 'function';
+} : _FunctionType<From, To> : _FunctionType<From, To>;
+/** @internal @hidden */
+export interface _FunctionRTArgDiff {
+    type: 'function';
+    result: 'diff-arg';
+    argCount: number;
+}
+type _FunctionRTUnknown = _FunctionRTArgDiff | (_EQ & {
+    type: 'function';
+});
+export type FunctionRT<From extends fn, To extends fn> = fn extends From ? _FunctionRTUnknown : fn extends To ? _FunctionRTUnknown : Parameters<From>['length'] extends Parameters<To>['length'] ? _EQ & {
+    type: 'function';
+} : {
+    type: 'function';
+    result: 'diff-arg';
+    argCount: Subtract<Parameters<From>['length'], Parameters<To>['length']>;
+};
+export declare function functionRT<From extends fn, To extends fn>(from: From, to: To): FunctionRT<From, To>;
+interface _ArrayUnknownDiff {
+    type: 'array';
+    result: 'diff';
+    elements: number;
+    changed: GenericResult[];
+}
+type _ArrayUnknown = _ArrayUnknownDiff | {
+    type: 'array';
+    result: 'equal';
+};
+interface _ArrayDiff<From extends ArrayLike<unknown>, To extends ArrayLike<unknown>> {
+    type: 'array';
+    result: 'diff';
+    elements: Subtract<From['length'], To['length']>;
+    changed: {
+        [K in keyof From & keyof To & number]: Deep<From[K], To[K]>;
+    }[keyof From & keyof To & number];
+}
+export type Array<From extends ArrayLike<unknown>, To extends ArrayLike<unknown>> = ArrayLike<unknown> extends From ? _ArrayUnknown : ArrayLike<unknown> extends To ? _ArrayUnknown : number extends From['length'] ? _ArrayUnknown : number extends To['length'] ? _ArrayUnknown : From['length'] extends To['length'] ? {
+    [K in keyof From & keyof To & number]: Deep<From[K], To[K]>['result'];
+}[keyof From & keyof To & number] extends 'equal' ? {
+    type: 'array';
+    result: 'equal';
+} : _ArrayDiff<From, To> : _ArrayDiff<From, To>;
+export declare function array<From extends ArrayLike<unknown>, To extends ArrayLike<unknown>>(from: From, to: To): Array<From, To>;
+interface _ObjectUnknownDiff {
+    type: 'object';
+    result: 'diff';
+    removed: string[];
+    added: string[];
+    changed: Record<string, GenericResult>;
+}
+type _ObjectUnknown = _ObjectUnknownDiff | ({
+    type: 'object';
+} & _EQ);
+interface _ObjectDiff<From extends object, To extends object> {
+    type: 'object';
+    result: 'diff';
+    removed: Exclude<keyof From, keyof To> extends never ? [] : UnionToTuple<Exclude<keyof From, keyof To>>;
+    added: Exclude<keyof To, keyof From> extends never ? [] : UnionToTuple<Exclude<keyof To, keyof From>>;
+    changed: {
+        [K in keyof From & keyof To]: Deep<From[K], To[K]>;
+    };
+}
+export type Object<From extends object, To extends object> = object extends From ? _ObjectUnknown : object extends To ? _ObjectUnknown : From extends To ? To extends From ? {
+    type: 'object';
+    result: 'equal';
+} : _ObjectDiff<From, To> : _ObjectDiff<From, To>;
+export declare function object<From extends object, To extends object>(from: From, to: To): Object<From, To>;
+interface NotComparable {
+    result: 'not-comparable';
+}
+type DeepCommon<From, To> = unknown extends From ? GenericResult : unknown extends To ? GenericResult : From extends string ? To extends CoercibleToString ? String<From, `${To}`> & {
+    type: 'string';
+    coerced: To extends string ? false : true;
+} : NotComparable : From extends number ? To extends number ? Number<From, To> & {
+    coerced: false;
+} : To extends bigint ? `${To}` extends `${infer V extends number}` ? Number<From, V> & {
+    coerced: true;
+} : never & 'error: bigint -> number' : NotComparable : From extends bigint ? To extends bigint ? BigInt<To, From> & {
+    coerced: false;
+} : To extends number ? `${To}` extends `${infer V extends bigint}` ? BigInt<From, V> & {
+    coerced: true;
+} : never & 'error: number -> bigint' : NotComparable : From extends boolean ? To extends boolean | Falsy ? Boolean<From, To extends boolean ? To : false> & {
+    coerced: To extends boolean ? false : true;
+} : NotComparable : From extends symbol ? To extends symbol ? {
+    type: 'symbol';
+    result: symbol extends To ? 'equal' | 'not-equal' : symbol extends From ? 'equal' | 'not-equal' : To extends From ? 'equal' : 'not-equal';
+} : NotComparable : From extends undefined ? To extends undefined | Falsy ? {
+    result: 'equal';
+    type: 'undefined';
+    coerced: To extends undefined ? false : true;
+} : NotComparable : From extends null ? To extends null | Falsy ? {
+    result: 'equal';
+    type: 'null';
+    coerced: To extends null ? false : true;
+} : NotComparable : From extends ArrayLike<unknown> ? To extends ArrayLike<unknown> ? Array<From, To> : NotComparable : From extends object ? To extends undefined | null ? NotComparable : To extends object ? Object<From, To> : NotComparable : NotComparable;
+export type DeepRT<From, To> = From extends fn ? To extends fn ? FunctionRT<From, To> : NotComparable : DeepCommon<From, To>;
+export type Deep<From, To> = From extends fn ? To extends fn ? FunctionType<From, To> : NotComparable : DeepCommon<From, To>;
+interface GenericDeepResult extends GenericResult {
+    coerced?: boolean;
+}
+export declare function deep<From, To>(from: From, to: To): ExpandRecursively<DeepRT<From, To>> & GenericDeepResult;
+export {};

package/dist/diff.js

@@ -0,0 +1,138 @@
+export function string(from, to) {
+    const _to = to;
+    if (from === _to)
+        return { result: 'equal' };
+    const to_at = _to.indexOf(from);
+    if (to_at !== -1)
+        return {
+            result: 'substring',
+            before: _to.slice(0, to_at),
+            after: _to.slice(to_at + from.length),
+            add: true,
+        };
+    const from_at = from.indexOf(_to);
+    if (from_at !== -1)
+        return {
+            result: 'substring',
+            before: from.slice(0, from_at),
+            after: from.slice(from_at + _to.length),
+            add: false,
+        };
+    return { result: 'not-equal' };
+}
+export function number(from, to) {
+    const _to = to;
+    if (Number.isNaN(to) || Number.isNaN(from)) {
+        return { type: 'number', result: 'not-equal' };
+    }
+    if (!Number.isFinite(to) || !Number.isFinite(from)) {
+        return { type: 'number', result: _to === from ? 'equal' : 'not-equal' };
+    }
+    if (_to === from)
+        return { type: 'number', result: 'equal' };
+    return { type: 'number', result: 'diff', value: from - to };
+}
+export function bigint(from, to) {
+    const _to = to;
+    if (_to === from)
+        return { type: 'bigint', result: 'equal' };
+    return { type: 'bigint', result: 'diff', value: from - to };
+}
+export function boolean(from, to) {
+    return { type: 'boolean', result: !!to === !!from ? 'equal' : 'not-equal' };
+}
+export function functionRT(from, to) {
+    if (from.length === to.length) {
+        return { type: 'function', result: 'equal' };
+    }
+    return { type: 'function', result: 'diff-arg', argCount: from.length - to.length };
+}
+export function array(from, to) {
+    const lengthDiff = from.length - to.length, changed = [];
+    let neq = false;
+    for (let i = 0; i < Math.min(from.length, to.length); i++) {
+        const diff = deep(from[i], to[i]);
+        changed.push(diff);
+        if (diff.result !== 'equal')
+            neq = true;
+    }
+    return (!neq && !lengthDiff
+        ? { type: 'array', result: 'equal' }
+        : { type: 'array', result: 'diff', elements: lengthDiff, changed });
+}
+export function object(from, to) {
+    const fromKeys = new Set(Object.keys(from)), toKeys = new Set(Object.keys(to));
+    const removed = fromKeys.difference(toKeys), added = toKeys.difference(fromKeys);
+    const changed = Object.create(null);
+    let neq = false;
+    for (const key of fromKeys.intersection(toKeys)) {
+        changed[key] = deep(from[key], to[key]);
+        if (changed[key].result !== 'equal')
+            neq = true;
+    }
+    return (neq || removed.size || added.size
+        ? { type: 'object', result: 'diff', removed: Array.from(removed), added: Array.from(added), changed }
+        : { type: 'object', result: 'equal' });
+}
+export function deep(from, to) {
+    const rt = (value) => value;
+    switch (typeof from) {
+        case 'string':
+            if (['symbol', 'function', 'object'].includes(typeof to))
+                break;
+            return rt({
+                type: 'string',
+                coerced: typeof to !== 'string',
+                ...string(from, `${to}`),
+            });
+        case 'number':
+            if (typeof to == 'number')
+                return rt({ ...number(from, to), coerced: false });
+            if (typeof to == 'bigint')
+                return rt({ ...number(from, Number(to)), coerced: true });
+            break;
+        case 'bigint':
+            if (typeof to == 'bigint')
+                return rt({ ...bigint(from, to), coerced: false });
+            if (typeof to == 'number')
+                return rt({ ...bigint(from, BigInt(to)), coerced: true });
+            break;
+        case 'boolean':
+            if (typeof to == 'boolean')
+                return rt({ ...boolean(from, to), coerced: false });
+            if (!to)
+                return rt({ ...boolean(from, false), coerced: true });
+            break;
+        case 'symbol':
+            if (typeof to !== 'symbol')
+                break;
+            return rt({ type: 'symbol', result: from == to ? 'equal' : 'not-equal' });
+        case 'undefined':
+            if (to === undefined)
+                return rt({ type: 'undefined', result: 'equal', coerced: false });
+            if (!to)
+                return rt({ type: 'undefined', result: 'equal', coerced: true });
+            break;
+        case 'function':
+            if (typeof to !== 'function')
+                break;
+            return rt({ ...functionRT(from, to) });
+        case 'object':
+            if (from === null) {
+                if (to === null)
+                    return rt({ type: 'null', result: 'equal', coerced: false });
+                if (!to)
+                    return rt({ type: 'null', result: 'equal', coerced: true });
+                break;
+            }
+            if (typeof to != 'object' || !to)
+                break;
+            if (Array.isArray(from)) {
+                if (!Array.isArray(to))
+                    break;
+                return rt(array(from, to));
+            }
+            return rt(object(from, to));
+    }
+    return rt({ result: 'not-comparable' });
+}

package/dist/index.d.ts

@@ -3,6 +3,7 @@ export * from './buffer.js';
 export * as cache from './cache.js';
 export * from './checksum.js';
 export * from './color.js';
+export * as diff from './diff.js';
 export * from './list.js';
 export * from './misc.js';
 export * from './numbers.js';

package/dist/index.js

@@ -6,6 +6,7 @@ export * from './buffer.js';
 export * as cache from './cache.js';
 export * from './checksum.js';
 export * from './color.js';
+export * as diff from './diff.js';
 export * from './list.js';
 export * from './misc.js';
 export * from './numbers.js';

package/dist/numbers.d.ts

@@ -1,3 +1,4 @@
+import type { CoercibleToString } from './string.js';
 export declare function range(min: number, max: number): number[];
 export declare function toDegrees(radians: number): number;
 export declare function toRadians(degrees: number): number;
@@ -6,3 +7,5 @@ export declare const formatCompact: {
     (value: number | bigint): string;
     (value: number | bigint | Intl.StringNumericLiteral): string;
 };
+export type ToNumber<T extends CoercibleToString> = `${T}` extends `${infer U extends number}` ? U : never;
+export type ToBigInt<T extends CoercibleToString> = `${T}` extends `${infer U extends bigint}` ? U : never;

package/dist/objects.d.ts

@@ -1,4 +1,5 @@
 import type { FilterOut } from './array.js';
+import * as diff from './diff.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;
@@ -22,6 +23,8 @@ export type DeepAssign<To extends object, From extends object> = {
     [K in keyof To | keyof From]: K extends keyof To ? K extends keyof From ? To[K] extends object ? From[K] extends object ? Expand<DeepAssign<To[K], From[K]>> : never : From[K] extends object ? never : From[K] : To[K] : From[K & keyof From];
 };
 export declare function deepAssign<To extends object, From extends object>(to: To, from: From, treatArraysAsPrimitives?: boolean): DeepAssign<To, From>;
+export type StructurallyEqual<To, From> = diff.DeepRT<To, From>['result'] extends 'equal' ? true : false;
+export declare function structurallyEqual<To, From>(to: To, from: From): StructurallyEqual<To, From>;
 /**
  * Entries of T
  */

package/dist/objects.js

@@ -1,6 +1,7 @@
 // SPDX-License-Identifier: LGPL-3.0-or-later
 // Copyright (c) 2025 James Prevett
 /* eslint-disable @typescript-eslint/no-explicit-any */
+import * as diff from './diff.js';
 import { _throw } from './misc.js';
 export function filterObject(object, predicate) {
     const entries = Object.entries(object);
@@ -64,6 +65,9 @@ export function deepAssign(to, from, treatArraysAsPrimitives = false) {
     }
     return to;
 }
+export function structurallyEqual(to, from) {
+    return (diff.deep(from, to).result === 'equal');
+}
 export function isJSON(str) {
     try {
         JSON.parse(str);

package/dist/string.d.ts

@@ -39,4 +39,5 @@ export type Repeat<T extends string, N extends number, Init extends string = ''>
 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 type CoercibleToString = string | number | bigint | boolean | null | undefined;
 export {};

package/dist/type-math.d.ts

@@ -12,6 +12,7 @@
  *
  */
 import type { Length } from './array.js';
+import type { ToNumber } from './numbers.js';
 import type { Repeat, StringLength } from './string.js';
 import type { $drain } from './types.js';
 /**
@@ -79,6 +80,10 @@ export type $Subtract<A extends number, B extends number> = _are_ints<A, B> exte
  * @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>>>;
+/**
+ * Is A less than B?
+ * @internal
+ */
 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;
@@ -116,7 +121,9 @@ type _f_sum_str<A_s extends string, B_s extends string, _A_neg extends boolean,
 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 AddBigInt<A extends bigint, B extends bigint> = i_sum<ToNumber<A>, ToNumber<B>>;
 export type Subtract<A extends number, B extends number> = Add<A, Negate<B>>;
+export type SubtractBigInt<A extends bigint, B extends bigint> = i_sum<ToNumber<A>, Negate<ToNumber<B>>>;
 /**
  * Accumulative addition:
  * N: increment

package/dist/types.d.ts

@@ -48,4 +48,5 @@ export type UnionToTuple<T, L = LastOfUnion<T>, N = [T] extends [never] ? true :
  * It improves performance for the math types by an order of magnitude.
  */
 export type $drain<T> = [T] extends [unknown] ? T : never;
+export type Falsy = null | undefined | false | 0 | 0n | '';
 export {};

package/package.json

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