utilium 3.6.2 → 3.7.0

package/dist/array.d.ts

@@ -117,4 +117,5 @@ export type FromKeyed<A extends any[], KeyName extends (A extends (infer E)[] ?
         [_ in KeyName & PropertyKey]: K;
     }>;
 } : never;
+export declare function chunkArray<const T>(array: readonly T[], chunkSize: number): T[][];
 export {};

package/dist/array.js

@@ -1 +1,8 @@
-export {};
+export function chunkArray(array, chunkSize) {
+    if (!Number.isSafeInteger(chunkSize) || chunkSize <= 0)
+        throw new Error('chunkArray: chunk size must be a positive integer');
+    const chunks = [];
+    for (let i = 0; i < array.length; i += chunkSize)
+        chunks.push(array.slice(i, i + chunkSize));
+    return chunks;
+}

package/dist/cache.d.ts

@@ -1,3 +1,7 @@
+/**
+ * A ranged cache
+ * Copyright (c) 2025 James Prevett
+ */
 export interface Options {
     /**
      * If true, use multiple buffers to cache a file.
@@ -17,11 +21,20 @@ export interface Options {
      * @default false
      */
     cacheOnly?: boolean;
+    /**
+     * Multiplier applied to a region's capacity when it has to grow.
+     * Values outside `[1, 100]` fall back to the default.
+     * Higher trades memory for fewer reallocations, while `1` allocates exactly what is needed and makes repeated appends quadratic.
+     * @default 2
+     */
+    growFactor?: number;
 }
 export type Range = {
     start: number;
     end: number;
 };
+/** Insert `[start, end)` into a sorted, non-overlapping list of ranges, merging it with any ranges it touches. */
+export declare function addRange(ranges: Range[], start: number, end: number): void;
 export interface Region {
     /** The region's offset from the start of the resource */
     offset: number;
@@ -47,8 +60,20 @@ export declare class Resource<ID> {
     constructor(
     /** The resource ID */
     id: ID, _size: number, options: Options, resources?: Map<ID, Resource<ID> | undefined>);
+    /**
+     * Resize `region.data` to `length` bytes.
+     * Capacity can be over-allocated geometrically so appending to a region repeatedly stays amortized O(1).
+     */
+    protected resizeRegion(region: Region, length: number): void;
+    /** Merge the region after `index` into the one at `index`, if the gap between them is small enough */
+    protected mergeAt(index: number): boolean;
     /** Combines adjacent regions and combines adjacent ranges within a region */
     collect(): void;
+    /**
+     * Combine the region at `index` with the neighbors it now reaches.
+     * Only that region can have changed, so this does not re-walk the whole list the way `collect` does.
+     */
+    protected collectAt(index: number): void;
     /** Takes an initial range and finds the sub-ranges that are not in the cache */
     missing(start: number, end: number): Range[];
     /**
@@ -56,8 +81,12 @@ export declare class Resource<ID> {
      * This is conceptually the inverse of `missing`.
      */
     cached(start: number, end: number): Range[];
+    /** Index of the first region positioned after `offset`. Regions are kept sorted, so this is a binary search. */
+    protected indexAfter(offset: number): number;
     /** Get the region who's ranges include an offset */
     regionAt(offset: number): Region | undefined;
+    /** The regions overlapping `[start, end)`, in order. Seeks to the first one rather than scanning from the start. */
+    regionsIn(start: number, end: number): Generator<Region>;
     /** Add new data to the cache at given specified offset */
     add(data: Uint8Array, offset: number): this;
 }

package/dist/cache.js

@@ -1,9 +1,27 @@
-// SPDX-License-Identifier: LGPL-3.0-or-later
-/**
- * A ranged cache
- * Copyright (c) 2025 James Prevett
- */
-import { extendBuffer } from './buffer.js';
+/** Insert `[start, end)` into a sorted, non-overlapping list of ranges, merging it with any ranges it touches. */
+export function addRange(ranges, start, end) {
+    let i = ranges.length;
+    while (i > 0 && ranges[i - 1].start > start)
+        i--;
+    const prev = ranges[i - 1];
+    if (prev && prev.end >= start) {
+        if (prev.end >= end)
+            return;
+        prev.end = end;
+    }
+    else {
+        ranges.splice(i, 0, { start, end });
+        i++;
+    }
+    const merged = ranges[i - 1];
+    let j = i;
+    while (j < ranges.length && ranges[j].start <= merged.end) {
+        merged.end = Math.max(merged.end, ranges[j].end);
+        j++;
+    }
+    if (j > i)
+        ranges.splice(i, j - i);
+}
 /**
  * The cache for a specific resource
  * @internal
@@ -51,50 +69,71 @@ export class Resource {
         this._size = _size;
         this.options = options;
         options.sparse ??= true;
+        if (!options.growFactor
+            || !Number.isFinite(options.growFactor)
+            || options.growFactor < 1
+            || options.growFactor > 100)
+            options.growFactor = 2;
         if (!options.sparse)
             this.regions.push({ offset: 0, data: new Uint8Array(_size), ranges: [] });
         resources?.set(id, this);
     }
+    /**
+     * Resize `region.data` to `length` bytes.
+     * Capacity can be over-allocated geometrically so appending to a region repeatedly stays amortized O(1).
+     */
+    resizeRegion(region, length) {
+        const { buffer, byteOffset } = region.data;
+        if (buffer.byteLength - byteOffset >= length) {
+            region.data = new Uint8Array(buffer, byteOffset, length);
+            return;
+        }
+        const grown = new Uint8Array(Math.max(length, (buffer.byteLength - byteOffset) * this.options.growFactor));
+        grown.set(region.data);
+        region.data = grown.subarray(0, length);
+    }
+    /** Merge the region after `index` into the one at `index`, if the gap between them is small enough */
+    mergeAt(index) {
+        const current = this.regions[index];
+        const next = this.regions[index + 1];
+        if (!current || !next)
+            return false;
+        const { regionGapThreshold = 0xfff } = this.options;
+        if (next.offset - (current.offset + current.data.byteLength) > regionGapThreshold)
+            return false;
+        for (const range of next.ranges)
+            addRange(current.ranges, range.start, range.end);
+        const length = next.offset + next.data.byteLength - current.offset;
+        if (length > current.data.byteLength)
+            this.resizeRegion(current, length);
+        current.data.set(next.data, next.offset - current.offset);
+        this.regions.splice(index + 1, 1);
+        return true;
+    }
     /** Combines adjacent regions and combines adjacent ranges within a region */
     collect() {
         if (!this.options.sparse)
             return;
-        const { regionGapThreshold = 0xfff } = this.options;
-        for (let i = 0; i < this.regions.length - 1;) {
-            const current = this.regions[i];
-            const next = this.regions[i + 1];
-            if (next.offset - (current.offset + current.data.byteLength) > regionGapThreshold) {
+        for (let i = 0; i < this.regions.length - 1;)
+            if (!this.mergeAt(i))
                 i++;
-                continue;
-            }
-            // Combine ranges
-            current.ranges.push(...next.ranges);
-            current.ranges.sort((a, b) => a.start - b.start);
-            // Combine overlapping/adjacent ranges
-            current.ranges = current.ranges.reduce((acc, range) => {
-                if (!acc.length || acc.at(-1).end < range.start) {
-                    acc.push(range);
-                }
-                else {
-                    acc.at(-1).end = Math.max(acc.at(-1).end, range.end);
-                }
-                return acc;
-            }, []);
-            // Extend buffer to include the new region. `current.data` starts at
-            // `current.offset`, so its length is measured from there (the `.set()`
-            // destination is already relative to `current.offset`).
-            current.data = extendBuffer(current.data, next.offset + next.data.byteLength - current.offset);
-            current.data.set(next.data, next.offset - current.offset);
-            // Remove the next region after merging
-            this.regions.splice(i + 1, 1);
-        }
+    }
+    /**
+     * Combine the region at `index` with the neighbors it now reaches.
+     * Only that region can have changed, so this does not re-walk the whole list the way `collect` does.
+     */
+    collectAt(index) {
+        if (!this.options.sparse)
+            return;
+        if (index > 0 && this.mergeAt(index - 1))
+            index--;
+        while (this.mergeAt(index))
+            ;
     }
     /** Takes an initial range and finds the sub-ranges that are not in the cache */
     missing(start, end) {
         const missingRanges = [];
-        for (const region of this.regions) {
-            if (region.offset >= end)
-                break;
+        for (const region of this.regionsIn(start, end)) {
             for (const range of region.ranges) {
                 if (range.end <= start)
                     continue;
@@ -123,9 +162,7 @@ export class Resource {
      */
     cached(start, end) {
         const cachedRanges = [];
-        for (const region of this.regions) {
-            if (region.offset >= end)
-                break;
+        for (const region of this.regionsIn(start, end)) {
             for (const range of region.ranges) {
                 if (range.end <= start)
                     continue;
@@ -150,43 +187,52 @@ export class Resource {
         }
         return merged;
     }
+    /** Index of the first region positioned after `offset`. Regions are kept sorted, so this is a binary search. */
+    indexAfter(offset) {
+        let low = 0, high = this.regions.length;
+        while (low < high) {
+            const mid = (low + high) >> 1;
+            if (this.regions[mid].offset > offset)
+                high = mid;
+            else
+                low = mid + 1;
+        }
+        return low;
+    }
     /** Get the region who's ranges include an offset */
     regionAt(offset) {
-        if (!this.regions.length)
-            return;
-        for (const region of this.regions) {
-            if (region.offset > offset)
-                break;
-            // Check if the offset is within this region
-            if (offset >= region.offset && offset < region.offset + region.data.byteLength)
-                return region;
+        const region = this.regions[this.indexAfter(offset) - 1];
+        if (region && offset < region.offset + region.data.byteLength)
+            return region;
+    }
+    /** The regions overlapping `[start, end)`, in order. Seeks to the first one rather than scanning from the start. */
+    *regionsIn(start, end) {
+        for (let i = Math.max(0, this.indexAfter(start) - 1); i < this.regions.length; i++) {
+            const region = this.regions[i];
+            if (region.offset >= end)
+                return;
+            if (region.offset + region.data.byteLength > start)
+                yield region;
         }
     }
     /** Add new data to the cache at given specified offset */
     add(data, offset) {
         const end = offset + data.byteLength;
-        const region = this.regionAt(offset);
-        if (region) {
+        const index = this.indexAfter(offset) - 1;
+        const region = this.regions[index];
+        if (region && offset < region.offset + region.data.byteLength) {
             // `region.data` holds bytes starting at `region.offset`, so positions
             // within it are relative to `region.offset` (not absolute resource offsets).
-            region.data = extendBuffer(region.data, end - region.offset);
+            if (end - region.offset > region.data.byteLength)
+                this.resizeRegion(region, end - region.offset);
             region.data.set(data, offset - region.offset);
-            region.ranges.push({ start: offset, end });
-            region.ranges.sort((a, b) => a.start - b.start);
-            this.collect();
+            addRange(region.ranges, offset, end);
+            this.collectAt(index);
             return this;
         }
-        // Find the correct index to insert the new region
-        const newRegion = { data, offset: offset, ranges: [{ start: offset, end }] };
-        const insertIndex = this.regions.findIndex(region => region.offset > offset);
         // Insert at the right index to keep regions sorted
-        if (insertIndex == -1) {
-            this.regions.push(newRegion); // Append if no later region exists
-        }
-        else {
-            this.regions.splice(insertIndex, 0, newRegion); // Insert before the first region with a greater offset
-        }
-        this.collect();
+        this.regions.splice(index + 1, 0, { data, offset, ranges: [{ start: offset, end }] });
+        this.collectAt(index + 1);
         return this;
     }
 }

package/package.json

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