@naturalcycles/js-lib 15.95.0 → 15.97.0

package/dist/abort.d.ts

@@ -40,7 +40,7 @@ export declare function polyfilledAbortSignalTimeout(ms: NumberOfMilliseconds):
  * Returns AbortSignal.any(signals) is the array (after filtering undefined inputs) is not empty,
  * otherwise undefined.
  */
-export declare function abortSignalAnyOrUndefined(signals: (AbortSignal | undefined)[]): AbortSignal | undefined;
+export declare function abortSignalAnyOrUndefined(signals: readonly (AbortSignal | undefined)[]): AbortSignal | undefined;
 /**
  * Returns an AbortSignal that aborts when any of the given signals abort.
  * Uses native `AbortSignal.any()` when available, falls back to a polyfill.
@@ -50,5 +50,5 @@ export declare function abortSignalAnyOrUndefined(signals: (AbortSignal | undefi
  *
  * If only 1 signal is passed in the input array - that Signal is returned as-is.
  */
-export declare function abortSignalAny(signals: AbortSignal[]): AbortSignal;
-export declare function polyfilledAbortSignalAny(signals: AbortSignal[]): AbortSignal;
+export declare function abortSignalAny(signals: readonly AbortSignal[]): AbortSignal;
+export declare function polyfilledAbortSignalAny(signals: readonly AbortSignal[]): AbortSignal;

package/dist/abort.js

@@ -58,7 +58,7 @@ export function abortSignalAny(signals) {
         return signals[0];
     }
     return typeof AbortSignal.any === 'function'
-        ? AbortSignal.any(signals)
+        ? AbortSignal.any(signals) // lib.dom types require a mutable array, but it is only read
         : polyfilledAbortSignalAny(signals);
 }
 export function polyfilledAbortSignalAny(signals) {

package/dist/analytics/analytics.model.d.ts

@@ -60,7 +60,7 @@ export interface AnalyticsClientEvent {
     userId?: AnalyticsDistinctId;
 }
 /** Canonical utm parameters. */
-export declare const CANONICAL_UTM_PARAMS: string[];
+export declare const CANONICAL_UTM_PARAMS: readonly string[];
 /** Keyed by `initial_<canonical utm param>`, to avoid permanently saving non-standard ones. */
 export type FirstTouchUtms = StringMap<string | null>;
 /**

package/dist/array/array.util.d.ts

@@ -1,4 +1,4 @@
-import type { AbortablePredicate, FalsyValue, Mapper, MutateOptions, Predicate, StringMap } from '../types.js';
+import type { AbortablePredicate, FalsyValue, Mapper, MutateOptions, NonEmptyArray, Predicate, StringMap } from '../types.js';
 /**
  * Creates an array of elements split into groups the length of size. If collection can’t be split evenly, the
  * final chunk will be the remaining elements.
@@ -11,7 +11,7 @@ import type { AbortablePredicate, FalsyValue, Mapper, MutateOptions, Predicate,
  *
  * Based on: https://github.com/you-dont-need/You-Dont-Need-Lodash-Underscore#_chunk
  */
-export declare function _chunk<T>(array: readonly T[], size?: number): T[][];
+export declare function _chunk<T>(array: readonly T[], size?: number): NonEmptyArray<T>[];
 /**
  * Removes duplicates from given array.
  */
@@ -89,7 +89,7 @@ export declare function _mapBy<ITEM, KEY>(items: readonly ITEM[], mapper: Mapper
  *
  * Returning `undefined` from the Mapper will EXCLUDE the item.
  */
-export declare function _groupBy<T>(items: readonly T[], mapper: Mapper<T, any>): StringMap<T[]>;
+export declare function _groupBy<T>(items: readonly T[], mapper: Mapper<T, any>): StringMap<NonEmptyArray<T>>;
 /**
  * Similar to `Array.find`, but the `predicate` may return `END` to stop the iteration early.
  *
@@ -138,7 +138,7 @@ export declare function _countBy<T>(items: Iterable<T>, mapper: Mapper<T, any>):
  * _intersection([2, 1], [2, 3])
  * // [2]
  */
-export declare function _intersection<T>(a1: T[], a2: T[] | Set<T>): T[];
+export declare function _intersection<T>(a1: readonly T[], a2: readonly T[] | Set<T>): T[];
 /**
  * Returns true if there is at least 1 item common between 2 arrays.
  * Otherwise returns false.
@@ -147,7 +147,7 @@ export declare function _intersection<T>(a1: T[], a2: T[] | Set<T>): T[];
  *
  * Passing second array as Set is more performant (it'll skip turning the array into Set in-place).
  */
-export declare function _intersectsWith<T>(a1: T[], a2: T[] | Set<T>): boolean;
+export declare function _intersectsWith<T>(a1: readonly T[], a2: readonly T[] | Set<T>): boolean;
 /**
  * Returns array1 minus array2.
  *
@@ -157,11 +157,11 @@ export declare function _intersectsWith<T>(a1: T[], a2: T[] | Set<T>): boolean;
  *
  * Passing second array as Set is more performant (it'll skip turning the array into Set in-place).
  */
-export declare function _difference<T>(a1: T[], a2: T[] | Set<T>): T[];
+export declare function _difference<T>(a1: readonly T[], a2: readonly T[] | Set<T>): T[];
 /**
  * Does NOT mutate the array, returns a filtered array instead.
  */
-export declare function _arrayRemove<T>(a: T[], itemToRemove: T): T[];
+export declare function _arrayRemove<T>(a: readonly T[], itemToRemove: T): T[];
 /**
  * "Toggles" an item to be present or absent in the array,
  * based on the predicate. Respects uniqueness.
@@ -217,6 +217,12 @@ export declare function _first<T>(array: readonly T[]): T;
  * Returns first item of the array (or undefined if array is empty).
  */
 export declare function _firstOrUndefined<T>(array: readonly T[]): T | undefined;
+/**
+ * Type guard that narrows an array to NonEmptyArray (array with at least one element).
+ * Readonly arrays are narrowed to `Readonly<NonEmptyArray<T>>`.
+ */
+export declare function _isNonEmptyArray<T>(array: T[]): array is NonEmptyArray<T>;
+export declare function _isNonEmptyArray<T>(array: readonly T[]): array is Readonly<NonEmptyArray<T>>;
 /**
  * Returns the first item of a non-empty iterable (Set, Map.values(), generator, etc.).
  * Throws if the iterable is empty.

package/dist/array/array.util.js

@@ -144,9 +144,14 @@ export function _groupBy(items, mapper) {
     const map = {};
     for (const item of items) {
         const key = mapper(item);
-        if (key !== undefined) {
-            ;
-            (map[key] ||= []).push(item);
+        if (key === undefined)
+            continue;
+        const group = map[key];
+        if (group) {
+            group.push(item);
+        }
+        else {
+            map[key] = [item];
         }
     }
     return map;
@@ -403,6 +408,9 @@ export function _first(array) {
 export function _firstOrUndefined(array) {
     return array[0];
 }
+export function _isNonEmptyArray(array) {
+    return array.length > 0;
+}
 /**
  * Returns the first item of a non-empty iterable (Set, Map.values(), generator, etc.).
  * Throws if the iterable is empty.

package/dist/browser/i18n/translation.service.d.ts

@@ -37,7 +37,7 @@ export declare class TranslationService {
      * Loads locale(s) (if not already cached) via configured TranslationLoader.
      * Resolves promise when done (ready to be used).
      */
-    loadLocale(locale: string | string[]): Promise<void>;
+    loadLocale(locale: string | readonly string[]): Promise<void>;
     /**
      * Will invoke `missingTranslationHandler` on missing tranlation.
      *

package/dist/datetime/localDate.d.ts

@@ -250,21 +250,21 @@ declare class LocalDateFactory {
     /**
      * Returns the earliest (min) LocalDate from the array, or undefined if the array is empty.
      */
-    minOrUndefined(items: LocalDateInputNullable[]): LocalDate | undefined;
+    minOrUndefined(items: readonly LocalDateInputNullable[]): LocalDate | undefined;
     /**
      * Returns the earliest LocalDate from the array.
      * Throws if the array is empty.
      */
-    min(items: LocalDateInputNullable[]): LocalDate;
+    min(items: readonly LocalDateInputNullable[]): LocalDate;
     /**
      * Returns the latest (max) LocalDate from the array, or undefined if the array is empty.
      */
-    maxOrUndefined(items: LocalDateInputNullable[]): LocalDate | undefined;
+    maxOrUndefined(items: readonly LocalDateInputNullable[]): LocalDate | undefined;
     /**
      * Returns the latest LocalDate from the array.
      * Throws if the array is empty.
      */
-    max(items: LocalDateInputNullable[]): LocalDate;
+    max(items: readonly LocalDateInputNullable[]): LocalDate;
     /**
      * Returns the range (array) of LocalDates between min and max.
      * By default, min is included, max is excluded.

package/dist/datetime/localTime.d.ts

@@ -322,10 +322,10 @@ declare class LocalTimeFactory {
      */
     isTimezoneValid(tz: string): boolean;
     sort(items: LocalTime[], dir?: SortDirection, opt?: MutateOptions): LocalTime[];
-    minOrUndefined(items: LocalTimeInputNullable[]): LocalTime | undefined;
-    min(items: LocalTimeInputNullable[]): LocalTime;
-    maxOrUndefined(items: LocalTimeInputNullable[]): LocalTime | undefined;
-    max(items: LocalTimeInputNullable[]): LocalTime;
+    minOrUndefined(items: readonly LocalTimeInputNullable[]): LocalTime | undefined;
+    min(items: readonly LocalTimeInputNullable[]): LocalTime;
+    maxOrUndefined(items: readonly LocalTimeInputNullable[]): LocalTime | undefined;
+    max(items: readonly LocalTimeInputNullable[]): LocalTime;
 }
 interface LocalTimeFn extends LocalTimeFactory {
     (d: LocalTimeInput): LocalTime;

package/dist/decorators/decorator.util.d.ts

@@ -21,4 +21,4 @@ export declare function _getTargetMethodSignature(target: AnyObject, keyStr: str
  * returns:
  * a, b, c
  */
-export declare function _getArgsSignature(args?: any[], logArgs?: boolean): string;
+export declare function _getArgsSignature(args?: readonly any[], logArgs?: boolean): string;

package/dist/decorators/timeout.decorator.js

@@ -10,8 +10,11 @@ export function _Timeout(opt) {
         const keyStr = String(key);
         descriptor.value = async function (...args) {
             const ctx = this;
-            opt.name ||= _getMethodSignature(ctx, keyStr);
-            return await pTimeout(() => originalFn.apply(this, args), opt);
+            // Not mutating the shared decorator options, as the name depends on the instance (ctx)
+            return await pTimeout(() => originalFn.apply(this, args), {
+                ...opt,
+                name: opt.name || _getMethodSignature(ctx, keyStr),
+            });
         };
         return descriptor;
     };

package/dist/error/error.model.d.ts

@@ -81,7 +81,7 @@ export interface ErrorData {
     /**
      * Used in e.g http 403 error.
      */
-    adminPermissionsRequired?: string[];
+    adminPermissionsRequired?: readonly string[];
     /**
      * Open-ended.
      */

package/dist/http/fetcher.js

@@ -706,10 +706,6 @@ export class Fetcher {
     }
     normalizeCfg(cfg) {
         const { debug = false, logger = consoleLogger } = cfg;
-        if (cfg.baseUrl?.endsWith('/')) {
-            logger.warn(`Fetcher: baseUrl should not end with slash: ${cfg.baseUrl}`);
-            cfg.baseUrl = cfg.baseUrl.slice(0, cfg.baseUrl.length - 1);
-        }
         const norm = _merge({
             baseUrl: '',
             name: this.getFetcherName(cfg),
@@ -746,6 +742,11 @@ export class Fetcher {
             errorData: {},
         }, _omit(cfg, ['method', 'credentials', 'headers', 'redirect', 'logger', 'name', 'keepalive']));
         norm.init.headers = _mapKeys(norm.init.headers, k => k.toLowerCase());
+        // Normalizing `norm`, not the input `cfg`, to not mutate the input
+        if (norm.baseUrl.endsWith('/')) {
+            logger.warn(`Fetcher: baseUrl should not end with slash: ${norm.baseUrl}`);
+            norm.baseUrl = norm.baseUrl.slice(0, -1);
+        }
         return norm;
     }
     getFetcherName(cfg) {

package/dist/http/http.model.d.ts

@@ -4,4 +4,4 @@ export type HttpStatusFamily = 5 | 4 | 3 | 2 | 1;
  * Number, representing a valid Http status code (e.g 401, 500, etc)
  */
 export type HttpStatusCode = number;
-export declare const HTTP_METHODS: HttpMethod[];
+export declare const HTTP_METHODS: readonly HttpMethod[];

package/dist/log/commonLogger.d.ts

@@ -74,4 +74,4 @@ export declare function createCommonLoggerAtLevel(logger?: CommonLogger, minLeve
 /**
  * Creates a "proxy" CommonLogger that pipes log entries to all provided sub-loggers.
  */
-export declare function commonLoggerPipe(loggers: CommonLogger[]): CommonLogger;
+export declare function commonLoggerPipe(loggers: readonly CommonLogger[]): CommonLogger;

package/dist/math/math.util.d.ts

@@ -6,11 +6,11 @@
  * _average([1, 2, 3, 4])
  * // 2.5
  */
-export declare function _average(values: number[]): number;
+export declare function _average(values: readonly number[]): number;
 /**
  * Same as _average, but safely returns null if input array is empty or nullish.
  */
-export declare function _averageOrNull(values: number[] | undefined | null): number | null;
+export declare function _averageOrNull(values: readonly number[] | undefined | null): number | null;
 /**
  * @returns Population standard deviation of the array of numbers
  *
@@ -19,15 +19,15 @@ export declare function _averageOrNull(values: number[] | undefined | null): num
  * _stdDev([2, 4, 4, 4, 5, 5, 7, 9])
  * // 2
  */
-export declare function _stdDev(values: number[]): number;
+export declare function _stdDev(values: readonly number[]): number;
 /**
  * Same as _stdDev, but safely returns null if input array is empty or nullish.
  */
-export declare function _stdDevOrNull(values: number[] | undefined | null): number | null;
+export declare function _stdDevOrNull(values: readonly number[] | undefined | null): number | null;
 /**
  * valuesArray and weightsArray length is expected to be the same.
  */
-export declare function _averageWeighted(values: number[], weights: number[]): number;
+export declare function _averageWeighted(values: readonly number[], weights: readonly number[]): number;
 /**
  * @example
  *
@@ -40,11 +40,11 @@ export declare function _averageWeighted(values: number[], weights: number[]): n
  * _percentile([1, 2, 3], 100)
  * // 3
  */
-export declare function _percentile(values: number[], pc: number): number;
+export declare function _percentile(values: readonly number[], pc: number): number;
 /**
  * A tiny bit more efficient function than calling _percentile individually.
  */
-export declare function _percentiles(values: number[], pcs: number[]): Record<number, number>;
+export declare function _percentiles(values: readonly number[], pcs: readonly number[]): Record<number, number>;
 /**
  * @example
  *
@@ -54,4 +54,4 @@ export declare function _percentiles(values: number[], pcs: number[]): Record<nu
  * _median([1, 2, 3, 4])
  * // 2.5
  */
-export declare function _median(values: number[]): number;
+export declare function _median(values: readonly number[]): number;

package/dist/math/math.util.js

@@ -70,7 +70,7 @@ export function _averageWeighted(values, weights) {
  * // 3
  */
 export function _percentile(values, pc) {
-    const sorted = values.sort(comparators.numericAsc);
+    const sorted = values.toSorted(comparators.numericAsc);
     // Floating pos in the range of [0; length - 1]
     const pos = ((values.length - 1) * pc) / 100;
     const dec = pos % 1;
@@ -83,7 +83,7 @@ export function _percentile(values, pc) {
  */
 export function _percentiles(values, pcs) {
     const r = {};
-    const sorted = values.sort(comparators.numericAsc);
+    const sorted = values.toSorted(comparators.numericAsc);
     for (const pc of pcs) {
         // Floating pos in the range of [0; length - 1]
         const pos = ((values.length - 1) * pc) / 100;

package/dist/math/stack.util.d.ts

@@ -13,7 +13,12 @@ export declare class Stack<T> {
      * Currently this slot contains OLDEST item (if any).
      */
     private nextIndex;
-    readonly items: T[];
+    private readonly buffer;
+    /**
+     * Raw "items buffer" as-is (not ordered properly).
+     * Readonly, because mutating it (e.g sorting in-place) would corrupt the Stack.
+     */
+    get items(): readonly T[];
     push(item: T): this;
     /**
      * Fill (overwrite) the whole Stack (all its items) with the passed `item`.
@@ -23,7 +28,7 @@ export declare class Stack<T> {
      * Returns last items in the right order.
      * Unlike raw `items` property that returns "items buffer" as-is (not ordered properly).
      */
-    get itemsOrdered(): T[];
+    get itemsOrdered(): readonly T[];
 }
 /**
  * Fixed-size FILO stack of Numbers.
@@ -46,5 +51,5 @@ export declare class NumberStack extends Stack<number> {
      * Returns null if Stack is empty.
      */
     percentileOrNull(pc: number): number | null;
-    percentiles(pcs: number[]): Record<number, number>;
+    percentiles(pcs: readonly number[]): Record<number, number>;
 }

package/dist/math/stack.util.js

@@ -16,9 +16,16 @@ export class Stack {
      * Currently this slot contains OLDEST item (if any).
      */
     nextIndex = 0;
-    items = [];
+    buffer = [];
+    /**
+     * Raw "items buffer" as-is (not ordered properly).
+     * Readonly, because mutating it (e.g sorting in-place) would corrupt the Stack.
+     */
+    get items() {
+        return this.buffer;
+    }
     push(item) {
-        this.items[this.nextIndex] = item;
+        this.buffer[this.nextIndex] = item;
         this.nextIndex = this.nextIndex === this.size - 1 ? 0 : this.nextIndex + 1;
         return this;
     }
@@ -27,7 +34,7 @@ export class Stack {
      */
     fill(item) {
         for (let i = 0; i < this.size; i++) {
-            this.items[i] = item;
+            this.buffer[i] = item;
         }
         return this;
     }
@@ -36,12 +43,12 @@ export class Stack {
      * Unlike raw `items` property that returns "items buffer" as-is (not ordered properly).
      */
     get itemsOrdered() {
-        if (this.items.length < this.size) {
+        if (this.buffer.length < this.size) {
             // Buffer is not filled yet, just return it as-is
-            return this.items;
+            return this.buffer;
         }
         // Buffer was filled and started to "overwrite itself", will need to return 2 slices
-        return [...this.items.slice(this.nextIndex), ...this.items.slice(0, this.nextIndex)];
+        return [...this.buffer.slice(this.nextIndex), ...this.buffer.slice(0, this.nextIndex)];
     }
 }
 /**

package/dist/number/number.util.d.ts

@@ -5,7 +5,7 @@ export declare function _randomInt(minIncl: number, maxIncl: number): number;
  * Should be used on non-empty arrays! (otherwise will return undefined,
  * which is not reflected in the output type)
  */
-export declare function _randomArrayItem<T>(array: T[]): T;
+export declare function _randomArrayItem<T>(array: readonly T[]): T;
 /**
  * Convenience function to "throttle" some code - run it less often.
  *

package/dist/object/keySortedMap.d.ts

@@ -24,7 +24,7 @@ export interface KeySortedMap<K, V> extends Map<K, V> {
 export declare class KeySortedMap<K, V> {
     #private;
     private readonly map;
-    constructor(entries?: [K, V][], opt?: KeySortedMapOptions<K>);
+    constructor(entries?: readonly [K, V][], opt?: KeySortedMapOptions<K>);
     /**
      * Convenience way to create KeySortedMap from object.
      */

package/dist/object/lazyKeySortedMap.d.ts

@@ -21,7 +21,7 @@ export declare class LazyKeySortedMap<K, V> {
     private readonly map;
     private readonly maybeSortedKeys;
     private keysAreSorted;
-    constructor(entries?: [K, V][], opt?: LazyKeySortedMapOptions<K>);
+    constructor(entries?: readonly [K, V][], opt?: LazyKeySortedMapOptions<K>);
     /**
      * Convenience way to create KeySortedMap from object.
      */

package/dist/object/object.util.d.ts

@@ -28,7 +28,7 @@ export declare function _omitWithUndefined<T extends AnyObject, K extends keyof
  *  'account.updated',
  * ])
  */
-export declare function _mask<T extends AnyObject>(obj: T, props: string[], opt?: MutateOptions): T;
+export declare function _mask<T extends AnyObject>(obj: T, props: readonly string[], opt?: MutateOptions): T;
 /**
  * Removes "falsy" values from the object.
  */

package/dist/object/sortObject.d.ts

@@ -4,4 +4,4 @@ import type { AnyObject } from '../types.js';
  * All keys that are not listed in `keyOrder` go last.
  * Does not mutate original object.
  */
-export declare function _sortObject<T extends AnyObject>(obj: T, keyOrder: (keyof T)[]): T;
+export declare function _sortObject<T extends AnyObject>(obj: T, keyOrder: readonly (keyof T)[]): T;

package/dist/promise/pTimeout.js

@@ -8,7 +8,7 @@ import { _typeCast } from '../types.js';
  * If the Function rejects - passes this rejection further.
  */
 export function pTimeoutFn(fn, opt) {
-    opt.name ||= fn.name;
+    opt = { ...opt, name: opt.name || fn.name }; // copy, to not mutate the input options
     if (!opt.timeout) {
         return fn;
     }

package/dist/semver.d.ts

@@ -46,21 +46,21 @@ declare class SemverFactory {
     /**
      * Returns the highest (max) Semver from the array, or undefined if the array is empty.
      */
-    maxOrUndefined(items: SemverInputNullable[]): Semver | undefined;
+    maxOrUndefined(items: readonly SemverInputNullable[]): Semver | undefined;
     /**
      * Returns the highest Semver from the array.
      * Throws if the array is empty.
      */
-    max(items: SemverInputNullable[]): Semver;
+    max(items: readonly SemverInputNullable[]): Semver;
     /**
      * Returns the lowest (min) Semver from the array, or undefined if the array is empty.
      */
-    minOrUndefined(items: SemverInputNullable[]): Semver | undefined;
+    minOrUndefined(items: readonly SemverInputNullable[]): Semver | undefined;
     /**
      * Returns the lowest Semver from the array.
      * Throws if the array is empty.
      */
-    min(items: SemverInputNullable[]): Semver;
+    min(items: readonly SemverInputNullable[]): Semver;
     /**
      * Sorts an array of Semvers in `dir` order (ascending by default).
      */

package/dist/string/pupa.d.ts

@@ -19,4 +19,4 @@ export interface PupaOptions {
 /**
  * API: https://github.com/sindresorhus/pupa
  */
-export declare function pupa(template: string, data: any[] | AnyObject, opt?: PupaOptions): string;
+export declare function pupa(template: string, data: readonly any[] | AnyObject, opt?: PupaOptions): string;

package/dist/types.d.ts

@@ -181,6 +181,17 @@ export interface BatchResult<RES = any, ERR = Error> {
  * type Foo = ValuesOf<typeof arr> // 'a' | 'b'
  */
 export type ValuesOf<T extends readonly any[]> = T[number];
+/**
+ * Array with at least one element.
+ * Index 0 is typed as `T` (not `T | undefined`) under `noUncheckedIndexedAccess`.
+ *
+ * Use `_isNonEmptyArray` to narrow a regular array to it.
+ *
+ * Caveats:
+ * - Mutating methods (pop, shift, splice, `length = 0`) can empty it without the type noticing.
+ * - Non-emptiness is lost after map, filter, slice, concat (they return `T[]`). Spread preserves it.
+ */
+export type NonEmptyArray<T> = [T, ...T[]];
 /**
  * Based on: https://stackoverflow.com/a/49286056/4919972
  *

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@naturalcycles/js-lib",
   "type": "module",
-  "version": "15.95.0",
+  "version": "15.97.0",
   "dependencies": {
     "tslib": "^2"
   },
@@ -14,7 +14,7 @@
     }
   },
   "devDependencies": {
-    "@naturalcycles/dev-lib": "0.0.0",
+    "@naturalcycles/dev-lib": "20.68.0",
     "@types/node": "^26",
     "@types/semver": "^7",
     "typescript": "^7",

package/src/abort.ts

@@ -67,7 +67,7 @@ export function polyfilledAbortSignalTimeout(ms: NumberOfMilliseconds): AbortSig
  * otherwise undefined.
  */
 export function abortSignalAnyOrUndefined(
-  signals: (AbortSignal | undefined)[],
+  signals: readonly (AbortSignal | undefined)[],
 ): AbortSignal | undefined {
   const filtered = signals.filter(_isTruthy)
   return filtered.length ? abortSignalAny(filtered) : undefined
@@ -82,17 +82,17 @@ export function abortSignalAnyOrUndefined(
  *
  * If only 1 signal is passed in the input array - that Signal is returned as-is.
  */
-export function abortSignalAny(signals: AbortSignal[]): AbortSignal {
+export function abortSignalAny(signals: readonly AbortSignal[]): AbortSignal {
   if (signals.length === 1) {
     return signals[0]!
   }
 
   return typeof AbortSignal.any === 'function'
-    ? AbortSignal.any(signals)
+    ? AbortSignal.any(signals as AbortSignal[]) // lib.dom types require a mutable array, but it is only read
     : polyfilledAbortSignalAny(signals)
 }
 
-export function polyfilledAbortSignalAny(signals: AbortSignal[]): AbortSignal {
+export function polyfilledAbortSignalAny(signals: readonly AbortSignal[]): AbortSignal {
   const ac = new AbortController()
 
   for (const signal of signals) {

package/src/analytics/analytics.model.ts

@@ -70,7 +70,7 @@ export interface AnalyticsClientEvent {
 }
 
 /** Canonical utm parameters. */
-export const CANONICAL_UTM_PARAMS = [
+export const CANONICAL_UTM_PARAMS: readonly string[] = [
   'utm_source',
   'utm_medium',
   'utm_campaign',

package/src/array/array.util.ts

@@ -4,6 +4,7 @@ import type {
   FalsyValue,
   Mapper,
   MutateOptions,
+  NonEmptyArray,
   Predicate,
   StringMap,
 } from '../types.js'
@@ -21,12 +22,12 @@ import { END } from '../types.js'
  *
  * Based on: https://github.com/you-dont-need/You-Dont-Need-Lodash-Underscore#_chunk
  */
-export function _chunk<T>(array: readonly T[], size = 1): T[][] {
+export function _chunk<T>(array: readonly T[], size = 1): NonEmptyArray<T>[] {
   const a: T[][] = []
   for (let i = 0; i < array.length; i += size) {
     a.push(array.slice(i, i + size))
   }
-  return a
+  return a as NonEmptyArray<T>[]
 }
 
 /**
@@ -158,13 +159,20 @@ export function _mapBy<ITEM, KEY>(
  *
  * Returning `undefined` from the Mapper will EXCLUDE the item.
  */
-export function _groupBy<T>(items: readonly T[], mapper: Mapper<T, any>): StringMap<T[]> {
-  const map: StringMap<T[]> = {}
+export function _groupBy<T>(
+  items: readonly T[],
+  mapper: Mapper<T, any>,
+): StringMap<NonEmptyArray<T>> {
+  const map: StringMap<NonEmptyArray<T>> = {}
 
   for (const item of items) {
     const key = mapper(item)
-    if (key !== undefined) {
-      ;(map[key] ||= []).push(item)
+    if (key === undefined) continue
+    const group = map[key]
+    if (group) {
+      group.push(item)
+    } else {
+      map[key] = [item]
     }
   }
   return map
@@ -294,7 +302,7 @@ export function _countBy<T>(items: Iterable<T>, mapper: Mapper<T, any>): StringM
  * _intersection([2, 1], [2, 3])
  * // [2]
  */
-export function _intersection<T>(a1: T[], a2: T[] | Set<T>): T[] {
+export function _intersection<T>(a1: readonly T[], a2: readonly T[] | Set<T>): T[] {
   const a2set = a2 instanceof Set ? a2 : new Set(a2)
   return a1.filter(v => a2set.has(v))
 }
@@ -307,7 +315,7 @@ export function _intersection<T>(a1: T[], a2: T[] | Set<T>): T[] {
  *
  * Passing second array as Set is more performant (it'll skip turning the array into Set in-place).
  */
-export function _intersectsWith<T>(a1: T[], a2: T[] | Set<T>): boolean {
+export function _intersectsWith<T>(a1: readonly T[], a2: readonly T[] | Set<T>): boolean {
   const a2set = a2 instanceof Set ? a2 : new Set(a2)
   return a1.some(v => a2set.has(v))
 }
@@ -321,7 +329,7 @@ export function _intersectsWith<T>(a1: T[], a2: T[] | Set<T>): boolean {
  *
  * Passing second array as Set is more performant (it'll skip turning the array into Set in-place).
  */
-export function _difference<T>(a1: T[], a2: T[] | Set<T>): T[] {
+export function _difference<T>(a1: readonly T[], a2: readonly T[] | Set<T>): T[] {
   const a2set = a2 instanceof Set ? a2 : new Set(a2)
   return a1.filter(v => !a2set.has(v))
 }
@@ -329,7 +337,7 @@ export function _difference<T>(a1: T[], a2: T[] | Set<T>): T[] {
 /**
  * Does NOT mutate the array, returns a filtered array instead.
  */
-export function _arrayRemove<T>(a: T[], itemToRemove: T): T[] {
+export function _arrayRemove<T>(a: readonly T[], itemToRemove: T): T[] {
   return a.filter(r => r !== itemToRemove)
 }
 
@@ -468,6 +476,16 @@ export function _firstOrUndefined<T>(array: readonly T[]): T | undefined {
   return array[0]
 }
 
+/**
+ * Type guard that narrows an array to NonEmptyArray (array with at least one element).
+ * Readonly arrays are narrowed to `Readonly<NonEmptyArray<T>>`.
+ */
+export function _isNonEmptyArray<T>(array: T[]): array is NonEmptyArray<T>
+export function _isNonEmptyArray<T>(array: readonly T[]): array is Readonly<NonEmptyArray<T>>
+export function _isNonEmptyArray(array: readonly unknown[]): boolean {
+  return array.length > 0
+}
+
 /**
  * Returns the first item of a non-empty iterable (Set, Map.values(), generator, etc.).
  * Throws if the iterable is empty.

package/src/browser/i18n/translation.service.ts

@@ -71,7 +71,7 @@ export class TranslationService {
    * Loads locale(s) (if not already cached) via configured TranslationLoader.
    * Resolves promise when done (ready to be used).
    */
-  async loadLocale(locale: string | string[]): Promise<void> {
+  async loadLocale(locale: string | readonly string[]): Promise<void> {
     const locales = Array.isArray(locale) ? locale : [locale]
 
     await pMap(locales, async locale => {

package/src/browser/imageFitter.ts

@@ -74,7 +74,7 @@ export class ImageFitter {
     this.resizeObserver.disconnect()
   }
 
-  private update(entries: ResizeObserverEntry[]): void {
+  private update(entries: readonly ResizeObserverEntry[]): void {
     const width = Math.floor(entries[0]!.contentRect.width)
     if (width === this.containerWidth) return // we're only interested in width changes
     this.containerWidth = width

package/src/datetime/localDate.ts

@@ -730,7 +730,7 @@ class LocalDateFactory {
   /**
    * Returns the earliest (min) LocalDate from the array, or undefined if the array is empty.
    */
-  minOrUndefined(items: LocalDateInputNullable[]): LocalDate | undefined {
+  minOrUndefined(items: readonly LocalDateInputNullable[]): LocalDate | undefined {
     let min: LocalDate | undefined
     for (const item of items) {
       if (!item) continue
@@ -746,7 +746,7 @@ class LocalDateFactory {
    * Returns the earliest LocalDate from the array.
    * Throws if the array is empty.
    */
-  min(items: LocalDateInputNullable[]): LocalDate {
+  min(items: readonly LocalDateInputNullable[]): LocalDate {
     const min = this.minOrUndefined(items)
     _assert(min, 'localDate.min called on empty array')
     return min
@@ -755,7 +755,7 @@ class LocalDateFactory {
   /**
    * Returns the latest (max) LocalDate from the array, or undefined if the array is empty.
    */
-  maxOrUndefined(items: LocalDateInputNullable[]): LocalDate | undefined {
+  maxOrUndefined(items: readonly LocalDateInputNullable[]): LocalDate | undefined {
     let max: LocalDate | undefined
     for (const item of items) {
       if (!item) continue
@@ -771,7 +771,7 @@ class LocalDateFactory {
    * Returns the latest LocalDate from the array.
    * Throws if the array is empty.
    */
-  max(items: LocalDateInputNullable[]): LocalDate {
+  max(items: readonly LocalDateInputNullable[]): LocalDate {
     const max = this.maxOrUndefined(items)
     _assert(max, 'localDate.max called on empty array')
     return max

package/src/datetime/localTime.ts

@@ -1024,7 +1024,7 @@ class LocalTimeFactory {
     return opt.mutate ? items.sort(cmp) : items.toSorted(cmp)
   }
 
-  minOrUndefined(items: LocalTimeInputNullable[]): LocalTime | undefined {
+  minOrUndefined(items: readonly LocalTimeInputNullable[]): LocalTime | undefined {
     let min: LocalTime | undefined
     for (const item of items) {
       if (!item) continue
@@ -1036,13 +1036,13 @@ class LocalTimeFactory {
     return min
   }
 
-  min(items: LocalTimeInputNullable[]): LocalTime {
+  min(items: readonly LocalTimeInputNullable[]): LocalTime {
     const min = this.minOrUndefined(items)
     _assert(min, 'localTime.min called on empty array')
     return min
   }
 
-  maxOrUndefined(items: LocalTimeInputNullable[]): LocalTime | undefined {
+  maxOrUndefined(items: readonly LocalTimeInputNullable[]): LocalTime | undefined {
     let max: LocalTime | undefined
     for (const item of items) {
       if (!item) continue
@@ -1054,7 +1054,7 @@ class LocalTimeFactory {
     return max
   }
 
-  max(items: LocalTimeInputNullable[]): LocalTime {
+  max(items: readonly LocalTimeInputNullable[]): LocalTime {
     const max = this.maxOrUndefined(items)
     _assert(max, 'localTime.max called on empty array')
     return max

package/src/decorators/decorator.util.ts

@@ -34,7 +34,7 @@ export function _getTargetMethodSignature(target: AnyObject, keyStr: string): st
  * returns:
  * a, b, c
  */
-export function _getArgsSignature(args: any[] = [], logArgs = true): string {
+export function _getArgsSignature(args: readonly any[] = [], logArgs = true): string {
   if (!logArgs) return ''
 
   return args

package/src/decorators/timeout.decorator.ts

@@ -14,8 +14,11 @@ export function _Timeout(opt: PTimeoutOptions): MethodDecorator {
 
     descriptor.value = async function (this: typeof _target, ...args: any[]) {
       const ctx = this
-      opt.name ||= _getMethodSignature(ctx, keyStr)
-      return await pTimeout(() => originalFn.apply(this, args), opt)
+      // Not mutating the shared decorator options, as the name depends on the instance (ctx)
+      return await pTimeout(() => originalFn.apply(this, args), {
+        ...opt,
+        name: opt.name || _getMethodSignature(ctx, keyStr),
+      })
     } as any
 
     return descriptor

package/src/error/error.model.ts

@@ -94,7 +94,7 @@ export interface ErrorData {
   /**
    * Used in e.g http 403 error.
    */
-  adminPermissionsRequired?: string[]
+  adminPermissionsRequired?: readonly string[]
 
   /**
    * Open-ended.

package/src/http/fetcher.ts

@@ -848,11 +848,6 @@ export class Fetcher {
   private normalizeCfg(cfg: FetcherCfg & FetcherOptions): FetcherNormalizedCfg {
     const { debug = false, logger = consoleLogger } = cfg
 
-    if (cfg.baseUrl?.endsWith('/')) {
-      logger.warn(`Fetcher: baseUrl should not end with slash: ${cfg.baseUrl}`)
-      cfg.baseUrl = cfg.baseUrl.slice(0, cfg.baseUrl.length - 1)
-    }
-
     const norm: FetcherNormalizedCfg = _merge(
       {
         baseUrl: '',
@@ -894,6 +889,12 @@ export class Fetcher {
 
     norm.init.headers = _mapKeys(norm.init.headers, k => k.toLowerCase())
 
+    // Normalizing `norm`, not the input `cfg`, to not mutate the input
+    if (norm.baseUrl.endsWith('/')) {
+      logger.warn(`Fetcher: baseUrl should not end with slash: ${norm.baseUrl}`)
+      norm.baseUrl = norm.baseUrl.slice(0, -1)
+    }
+
     return norm
   }
 

package/src/http/http.model.ts

@@ -8,4 +8,4 @@ export type HttpStatusFamily = 5 | 4 | 3 | 2 | 1
  */
 export type HttpStatusCode = number
 
-export const HTTP_METHODS: HttpMethod[] = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD']
+export const HTTP_METHODS: readonly HttpMethod[] = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD']

package/src/log/commonLogger.ts

@@ -142,7 +142,7 @@ export function createCommonLoggerAtLevel(
 /**
  * Creates a "proxy" CommonLogger that pipes log entries to all provided sub-loggers.
  */
-export function commonLoggerPipe(loggers: CommonLogger[]): CommonLogger {
+export function commonLoggerPipe(loggers: readonly CommonLogger[]): CommonLogger {
   return {
     debug: (...args) => loggers.forEach(logger => logger.debug(...args)),
     log: (...args) => loggers.forEach(logger => logger.log(...args)),

package/src/math/math.util.ts

@@ -9,7 +9,7 @@ import { _assert } from '../error/assert.js'
  * _average([1, 2, 3, 4])
  * // 2.5
  */
-export function _average(values: number[]): number {
+export function _average(values: readonly number[]): number {
   _assert(values.length, '_average is called on empty array')
   let total = 0
   for (const n of values) total += n
@@ -19,7 +19,7 @@ export function _average(values: number[]): number {
 /**
  * Same as _average, but safely returns null if input array is empty or nullish.
  */
-export function _averageOrNull(values: number[] | undefined | null): number | null {
+export function _averageOrNull(values: readonly number[] | undefined | null): number | null {
   return values?.length ? _average(values) : null
 }
 
@@ -31,7 +31,7 @@ export function _averageOrNull(values: number[] | undefined | null): number | nu
  * _stdDev([2, 4, 4, 4, 5, 5, 7, 9])
  * // 2
  */
-export function _stdDev(values: number[]): number {
+export function _stdDev(values: readonly number[]): number {
   _assert(values.length, '_stdDev is called on empty array')
   const avg = _average(values)
   let sumSquaredDiff = 0
@@ -45,14 +45,14 @@ export function _stdDev(values: number[]): number {
 /**
  * Same as _stdDev, but safely returns null if input array is empty or nullish.
  */
-export function _stdDevOrNull(values: number[] | undefined | null): number | null {
+export function _stdDevOrNull(values: readonly number[] | undefined | null): number | null {
   return values?.length ? _stdDev(values) : null
 }
 
 /**
  * valuesArray and weightsArray length is expected to be the same.
  */
-export function _averageWeighted(values: number[], weights: number[]): number {
+export function _averageWeighted(values: readonly number[], weights: readonly number[]): number {
   let numerator = 0
   let denominator = 0
   for (let i = 0; i < values.length; i++) {
@@ -74,8 +74,8 @@ export function _averageWeighted(values: number[], weights: number[]): number {
  * _percentile([1, 2, 3], 100)
  * // 3
  */
-export function _percentile(values: number[], pc: number): number {
-  const sorted = values.sort(comparators.numericAsc)
+export function _percentile(values: readonly number[], pc: number): number {
+  const sorted = values.toSorted(comparators.numericAsc)
 
   // Floating pos in the range of [0; length - 1]
   const pos = ((values.length - 1) * pc) / 100
@@ -89,10 +89,13 @@ export function _percentile(values: number[], pc: number): number {
 /**
  * A tiny bit more efficient function than calling _percentile individually.
  */
-export function _percentiles(values: number[], pcs: number[]): Record<number, number> {
+export function _percentiles(
+  values: readonly number[],
+  pcs: readonly number[],
+): Record<number, number> {
   const r = {} as Record<number, number>
 
-  const sorted = values.sort(comparators.numericAsc)
+  const sorted = values.toSorted(comparators.numericAsc)
 
   for (const pc of pcs) {
     // Floating pos in the range of [0; length - 1]
@@ -116,7 +119,7 @@ export function _percentiles(values: number[], pcs: number[]): Record<number, nu
  * _median([1, 2, 3, 4])
  * // 2.5
  */
-export function _median(values: number[]): number {
+export function _median(values: readonly number[]): number {
   const sorted = values.toSorted(comparators.numericAsc)
   const len = sorted.length
   const mid = Math.floor(len / 2)

package/src/math/stack.util.ts

@@ -16,10 +16,18 @@ export class Stack<T> {
    */
   private nextIndex = 0
 
-  readonly items: T[] = []
+  private readonly buffer: T[] = []
+
+  /**
+   * Raw "items buffer" as-is (not ordered properly).
+   * Readonly, because mutating it (e.g sorting in-place) would corrupt the Stack.
+   */
+  get items(): readonly T[] {
+    return this.buffer
+  }
 
   push(item: T): this {
-    this.items[this.nextIndex] = item
+    this.buffer[this.nextIndex] = item
     this.nextIndex = this.nextIndex === this.size - 1 ? 0 : this.nextIndex + 1
     return this
   }
@@ -29,7 +37,7 @@ export class Stack<T> {
    */
   fill(item: T): this {
     for (let i = 0; i < this.size; i++) {
-      this.items[i] = item
+      this.buffer[i] = item
     }
     return this
   }
@@ -38,14 +46,14 @@ export class Stack<T> {
    * Returns last items in the right order.
    * Unlike raw `items` property that returns "items buffer" as-is (not ordered properly).
    */
-  get itemsOrdered(): T[] {
-    if (this.items.length < this.size) {
+  get itemsOrdered(): readonly T[] {
+    if (this.buffer.length < this.size) {
       // Buffer is not filled yet, just return it as-is
-      return this.items
+      return this.buffer
     }
 
     // Buffer was filled and started to "overwrite itself", will need to return 2 slices
-    return [...this.items.slice(this.nextIndex), ...this.items.slice(0, this.nextIndex)]
+    return [...this.buffer.slice(this.nextIndex), ...this.buffer.slice(0, this.nextIndex)]
   }
 }
 
@@ -90,7 +98,7 @@ export class NumberStack extends Stack<number> {
     return this.items.length === 0 ? null : _percentile(this.items, pc)
   }
 
-  percentiles(pcs: number[]): Record<number, number> {
+  percentiles(pcs: readonly number[]): Record<number, number> {
     return _percentiles(this.items, pcs)
   }
 }

package/src/number/number.util.ts

@@ -9,7 +9,7 @@ export function _randomInt(minIncl: number, maxIncl: number): number {
  * Should be used on non-empty arrays! (otherwise will return undefined,
  * which is not reflected in the output type)
  */
-export function _randomArrayItem<T>(array: T[]): T {
+export function _randomArrayItem<T>(array: readonly T[]): T {
   return array[_randomInt(0, array.length - 1)]!
 }
 

package/src/object/keySortedMap.ts

@@ -29,7 +29,7 @@ export class KeySortedMap<K, V> {
   private readonly map: Map<K, V>
   readonly #sortedKeys: K[]
 
-  constructor(entries: [K, V][] = [], opt: KeySortedMapOptions<K> = {}) {
+  constructor(entries: readonly [K, V][] = [], opt: KeySortedMapOptions<K> = {}) {
     this.#comparator = opt.comparator
     this.map = new Map(entries)
     this.#sortedKeys = Array.from(this.map.keys())

package/src/object/lazyKeySortedMap.ts

@@ -25,7 +25,7 @@ export class LazyKeySortedMap<K, V> {
   private readonly maybeSortedKeys: K[]
   private keysAreSorted = false
 
-  constructor(entries: [K, V][] = [], opt: LazyKeySortedMapOptions<K> = {}) {
+  constructor(entries: readonly [K, V][] = [], opt: LazyKeySortedMapOptions<K> = {}) {
     this.#comparator = opt.comparator
     this.map = new Map(entries)
     this.maybeSortedKeys = Array.from(this.map.keys())

package/src/object/object.util.ts

@@ -101,7 +101,11 @@ export function _omitWithUndefined<T extends AnyObject, K extends keyof T>(
  *  'account.updated',
  * ])
  */
-export function _mask<T extends AnyObject>(obj: T, props: string[], opt: MutateOptions = {}): T {
+export function _mask<T extends AnyObject>(
+  obj: T,
+  props: readonly string[],
+  opt: MutateOptions = {},
+): T {
   const r = opt.mutate ? obj : _deepCopy(obj)
   for (const k of props) {
     _unset(r, k)

package/src/object/sortObject.ts

@@ -5,7 +5,7 @@ import type { AnyObject } from '../types.js'
  * All keys that are not listed in `keyOrder` go last.
  * Does not mutate original object.
  */
-export function _sortObject<T extends AnyObject>(obj: T, keyOrder: (keyof T)[]): T {
+export function _sortObject<T extends AnyObject>(obj: T, keyOrder: readonly (keyof T)[]): T {
   const r = {} as T
 
   // First, go over ordered keys

package/src/promise/pMap.ts

@@ -166,7 +166,7 @@ export async function pMap<IN, OUT>(
  pMap with serial (non-concurrent) execution.
  */
 async function pMap1<IN, OUT>(
-  items: IN[],
+  items: readonly IN[],
   mapper: AbortableAsyncMapper<IN, OUT>,
   errorMode: ErrorMode,
   logger: CommonLogger | null,
@@ -202,7 +202,7 @@ async function pMap1<IN, OUT>(
  pMap with fully concurrent execution, like Promise.all
  */
 async function pMapAll<IN, OUT>(
-  items: IN[],
+  items: readonly IN[],
   mapper: AbortableAsyncMapper<IN, OUT>,
   errorMode: ErrorMode,
   logger: CommonLogger | null,

package/src/promise/pTimeout.ts

@@ -47,7 +47,7 @@ export interface PTimeoutOptions {
  * If the Function rejects - passes this rejection further.
  */
 export function pTimeoutFn<T extends AnyAsyncFunction>(fn: T, opt: PTimeoutOptions): T {
-  opt.name ||= fn.name
+  opt = { ...opt, name: opt.name || fn.name } // copy, to not mutate the input options
 
   if (!opt.timeout) {
     return fn

package/src/semver.ts

@@ -88,7 +88,7 @@ class SemverFactory {
   /**
    * Returns the highest (max) Semver from the array, or undefined if the array is empty.
    */
-  maxOrUndefined(items: SemverInputNullable[]): Semver | undefined {
+  maxOrUndefined(items: readonly SemverInputNullable[]): Semver | undefined {
     let max: Semver | undefined
     for (const item of items) {
       const input = this.fromInputOrUndefined(item)
@@ -103,7 +103,7 @@ class SemverFactory {
    * Returns the highest Semver from the array.
    * Throws if the array is empty.
    */
-  max(items: SemverInputNullable[]): Semver {
+  max(items: readonly SemverInputNullable[]): Semver {
     const max = this.maxOrUndefined(items)
     _assert(max, 'semver.max called on empty array')
     return max
@@ -112,7 +112,7 @@ class SemverFactory {
   /**
    * Returns the lowest (min) Semver from the array, or undefined if the array is empty.
    */
-  minOrUndefined(items: SemverInputNullable[]): Semver | undefined {
+  minOrUndefined(items: readonly SemverInputNullable[]): Semver | undefined {
     let min: Semver | undefined
     for (const item of items) {
       const input = this.fromInputOrUndefined(item)
@@ -127,7 +127,7 @@ class SemverFactory {
    * Returns the lowest Semver from the array.
    * Throws if the array is empty.
    */
-  min(items: SemverInputNullable[]): Semver {
+  min(items: readonly SemverInputNullable[]): Semver {
     const min = this.minOrUndefined(items)
     _assert(min, 'semver.min called on empty array')
     return min

package/src/string/pupa.ts

@@ -36,7 +36,11 @@ export interface PupaOptions {
 /**
  * API: https://github.com/sindresorhus/pupa
  */
-export function pupa(template: string, data: any[] | AnyObject, opt: PupaOptions = {}): string {
+export function pupa(
+  template: string,
+  data: readonly any[] | AnyObject,
+  opt: PupaOptions = {},
+): string {
   if (typeof template !== 'string') {
     throw new TypeError(`Expected a \`string\` in the first argument, got \`${typeof template}\``)
   }

package/src/string/readingTime.ts

@@ -41,7 +41,7 @@ export interface ReadingTimeResult extends ReadingTimeStats {
 
 type WordBoundFunction = (char: string) => boolean
 
-function codeIsInRanges(num: number, arrayOfRanges: number[][]): boolean {
+function codeIsInRanges(num: number, arrayOfRanges: readonly number[][]): boolean {
   return arrayOfRanges.some(([lowerBound, upperBound]) => lowerBound! <= num && num <= upperBound!)
 }
 

package/src/types.ts

@@ -225,6 +225,18 @@ export interface BatchResult<RES = any, ERR = Error> {
  */
 export type ValuesOf<T extends readonly any[]> = T[number]
 
+/**
+ * Array with at least one element.
+ * Index 0 is typed as `T` (not `T | undefined`) under `noUncheckedIndexedAccess`.
+ *
+ * Use `_isNonEmptyArray` to narrow a regular array to it.
+ *
+ * Caveats:
+ * - Mutating methods (pop, shift, splice, `length = 0`) can empty it without the type noticing.
+ * - Non-emptiness is lost after map, filter, slice, concat (they return `T[]`). Spread preserves it.
+ */
+export type NonEmptyArray<T> = [T, ...T[]]
+
 /**
  * Based on: https://stackoverflow.com/a/49286056/4919972
  *

package/src/ua/ua.ts

@@ -379,7 +379,7 @@ function mergeMapEntries(
 function rgxMapper(
   target: UABrowser | UACpu | UADevice | UAEngine | UAOS,
   ua: string,
-  arrays: UARegexMapEntry[],
+  arrays: readonly UARegexMapEntry[],
 ): void {
   const t = target as unknown as Record<string, string | undefined>
   let matches: RegExpExecArray | null = null