utilium 1.2.3 → 1.2.4

package/dist/cache.d.ts

@@ -0,0 +1,58 @@
+export interface Options {
+    /**
+     * If true, use multiple buffers to cache a file.
+     * This is useful when working with small parts of large files,
+     * since we don't need to allocate a large buffer that is mostly unused
+     * @default true
+     */
+    sparse?: boolean;
+    /**
+     * The threshold for whether to combine regions or not
+     * @see Region
+     * @default 0xfff // 4 KiB
+     */
+    regionGapThreshold?: number;
+    /**
+     * Whether to only update the cache when changing or deleting resources
+     * @default false
+     */
+    cacheOnly?: boolean;
+}
+export type Range = {
+    start: number;
+    end: number;
+};
+export interface Region {
+    /** The region's offset from the start of the resource */
+    offset: number;
+    /** Ranges cached in this region. These are absolute! */
+    ranges: Range[];
+    /** Data for this region */
+    data: Uint8Array;
+}
+/**
+ * The cache for a specific resource
+ * @internal
+ */
+export declare class Resource {
+    /** The resource ID */
+    readonly id: string;
+    /** The full size of the resource */
+    readonly size: number;
+    protected readonly options: Options;
+    /** Regions used to reduce unneeded allocations. Think of sparse arrays. */
+    readonly regions: Region[];
+    constructor(
+    /** The resource ID */
+    id: string, 
+    /** The full size of the resource */
+    size: number, options: Options, resources?: Map<string, Resource | undefined>);
+    /** Combines adjacent regions and combines adjacent ranges within a region */
+    collect(): void;
+    /** Takes an initial range and finds the sub-ranges that are not in the cache */
+    missing(start: number, end: number): Range[];
+    /** Get the region who's ranges include an offset */
+    regionAt(offset: number): Region | undefined;
+    /** Add new data to the cache at given specified offset */
+    add(data: Uint8Array, offset: number): this;
+}

package/dist/cache.js

@@ -0,0 +1,121 @@
+/** A ranged cache */
+import { extendBuffer } from './buffer.js';
+/**
+ * The cache for a specific resource
+ * @internal
+ */
+export class Resource {
+    id;
+    size;
+    options;
+    /** Regions used to reduce unneeded allocations. Think of sparse arrays. */
+    regions = [];
+    constructor(
+    /** The resource ID */
+    id, 
+    /** The full size of the resource */
+    size, options, resources) {
+        this.id = id;
+        this.size = size;
+        this.options = options;
+        options.sparse ??= true;
+        if (!options.sparse)
+            this.regions.push({ offset: 0, data: new Uint8Array(size), ranges: [] });
+        resources?.set(id, this);
+    }
+    /** 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) {
+                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 = extendBuffer(current.data, next.offset + next.data.byteLength);
+            current.data.set(next.data, next.offset - current.offset);
+            // Remove the next region after merging
+            this.regions.splice(i + 1, 1);
+        }
+    }
+    /** 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 range of region.ranges) {
+                if (range.end <= start)
+                    continue;
+                if (range.start >= end)
+                    break;
+                if (range.start > start) {
+                    missingRanges.push({ start, end: Math.min(range.start, end) });
+                }
+                // Adjust the current start if the region overlaps
+                if (range.end > start)
+                    start = Math.max(start, range.end);
+                if (start >= end)
+                    break;
+            }
+            if (start >= end)
+                break;
+        }
+        // If there are still missing parts at the end
+        if (start < end)
+            missingRanges.push({ start, end });
+        return missingRanges;
+    }
+    /** 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;
+        }
+    }
+    /** 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) {
+            region.data = extendBuffer(region.data, end);
+            region.data.set(data, offset);
+            region.ranges.push({ start: offset, end });
+            region.ranges.sort((a, b) => a.start - b.start);
+            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
+        }
+        return this;
+    }
+}

package/dist/debugging.js

@@ -1,10 +1,33 @@
 function defaultStringify(value) {
-    if (value === null)
-        return 'null';
-    if (value === undefined)
-        return 'undefined';
-    // eslint-disable-next-line @typescript-eslint/no-base-to-string
-    return value.toString();
+    switch (typeof value) {
+        case 'undefined':
+            return 'undefined';
+        case 'string':
+        case 'number':
+        case 'boolean':
+            return JSON.stringify(value);
+        case 'bigint':
+        case 'symbol':
+            return value.toString();
+        case 'function':
+            return value.name + '()';
+        case 'object':
+            if (value === null)
+                return 'null';
+            if (ArrayBuffer.isView(value)) {
+                const length = 'length' in value ? value.length : value.byteLength / value.constructor.BYTES_PER_ELEMENT;
+                return `${value.constructor.name.replaceAll('Array', '').toLowerCase()}[${length}]`;
+            }
+            if (Array.isArray(value))
+                return `unknown[${value.length}]`;
+            try {
+                const json = JSON.stringify(value);
+                return json.length < 100 ? json : value.toString();
+            }
+            catch {
+                return value.toString();
+            }
+    }
 }
 /**
  * Create a function that can be used to decorate classes and non-field members.

package/dist/requests.d.ts

@@ -1,69 +1,18 @@
-export interface CacheOptions {
-    /**
-     * If true, use multiple buffers to cache a file.
-     * This is useful when working with small parts of large files,
-     * since we don't need to allocate a large buffer that is mostly unused
-     * @default true
-     */
-    sparse?: boolean;
-    /**
-     * The threshold for whether to combine regions or not
-     * @see CacheRegion
-     * @default 0xfff // 4 KiB
-     */
-    regionGapThreshold?: number;
-    /**
-     * Whether to only update the cache when changing or deleting resources
-     * @default false
-     */
-    cacheOnly?: boolean;
-}
-/**
- * @deprecated Use `CacheOptions`
- */
-export type ResourceCacheOptions = CacheOptions;
-export type CacheRange = {
-    start: number;
-    end: number;
-};
-export interface CacheRegion {
-    /** The region's offset from the start of the resource */
-    offset: number;
-    /** Ranges cached in this region. These are absolute! */
-    ranges: CacheRange[];
-    /** Data for this region */
-    data: Uint8Array;
-}
-/**
- * The cache for a specific resource
- * @internal
- */
-export declare class ResourceCache {
-    /** The resource URL */
-    readonly url: string;
-    /** The full size of the resource */
-    readonly size: number;
-    protected readonly options: CacheOptions;
-    /** Regions used to reduce unneeded allocations. Think of sparse arrays. */
-    readonly regions: CacheRegion[];
-    constructor(
-    /** The resource URL */
-    url: string, 
-    /** The full size of the resource */
-    size: number, options: CacheOptions);
-    /** Combines adjacent regions and combines adjacent ranges within a region */
-    collect(): void;
-    /** Takes an initial range and finds the sub-ranges that are not in the cache */
-    missing(start: number, end: number): CacheRange[];
-    /** Get the region who's ranges include an offset */
-    regionAt(offset: number): CacheRegion | undefined;
-    /** Add new data to the cache at given specified offset */
-    add(data: Uint8Array, offset: number): this;
-}
+import * as cache from './cache.js';
+/** @deprecated Use `cache.Options` */
+export type ResourceCacheOptions = cache.Options;
+/** @deprecated Use `cache.Resource` */
+export declare const ResourceCache: typeof cache.Resource;
+/** @deprecated Use `cache.Resource` */
+export type ResourceCache = cache.Resource;
+/** @deprecated Use `cache.Range` */
+export type CacheRange = cache.Range;
+/** @deprecated Use `cache.Options` */
+export type CacheOptions = cache.Options;
 /**
  * @internal
  */
-export declare const resourcesCache: Map<string, ResourceCache | null>;
+export declare const resourcesCache: Map<string, cache.Resource | undefined>;
 export type Issue = {
     tag: 'status';
     response: Response;
@@ -79,7 +28,7 @@ export type Issue = {
  * @deprecated Use `Issue`
  */
 export type RequestError = Issue;
-export interface Options extends CacheOptions {
+export interface Options extends cache.Options {
     /** Optionally provide a function for logging warnings */
     warn?(message: string): unknown;
 }
@@ -114,7 +63,7 @@ export declare const GET: typeof get;
  */
 export declare function getCached(url: string, options: GetOptions): {
     data?: Uint8Array;
-    missing: CacheRange[];
+    missing: cache.Range[];
 };
 interface SetOptions extends Options {
     /** The offset we are updating at */

package/dist/requests.js

@@ -1,124 +1,8 @@
 /* Utilities for `fetch` when using range requests. It also allows you to handle errors easier */
-import { extendBuffer } from './buffer.js';
-/**
- * The cache for a specific resource
- * @internal
- */
-export class ResourceCache {
-    url;
-    size;
-    options;
-    /** Regions used to reduce unneeded allocations. Think of sparse arrays. */
-    regions = [];
-    constructor(
-    /** The resource URL */
-    url, 
-    /** The full size of the resource */
-    size, options) {
-        this.url = url;
-        this.size = size;
-        this.options = options;
-        options.sparse ??= true;
-        if (!options.sparse)
-            this.regions.push({ offset: 0, data: new Uint8Array(size), ranges: [] });
-        resourcesCache.set(url, this);
-    }
-    /** 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) {
-                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 = extendBuffer(current.data, next.offset + next.data.byteLength);
-            current.data.set(next.data, next.offset - current.offset);
-            // Remove the next region after merging
-            this.regions.splice(i + 1, 1);
-        }
-    }
-    /** 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 range of region.ranges) {
-                if (range.end <= start)
-                    continue;
-                if (range.start >= end)
-                    break;
-                if (range.start > start) {
-                    missingRanges.push({ start, end: Math.min(range.start, end) });
-                }
-                // Adjust the current start if the region overlaps
-                if (range.end > start)
-                    start = Math.max(start, range.end);
-                if (start >= end)
-                    break;
-            }
-            if (start >= end)
-                break;
-        }
-        // If there are still missing parts at the end
-        if (start < end)
-            missingRanges.push({ start, end });
-        return missingRanges;
-    }
-    /** 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;
-        }
-    }
-    /** 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) {
-            region.data = extendBuffer(region.data, end);
-            region.data.set(data, offset);
-            region.ranges.push({ start: offset, end });
-            region.ranges.sort((a, b) => a.start - b.start);
-            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
-        }
-        return this;
-    }
-}
+import * as cache from './cache.js';
+/** @deprecated Use `cache.Resource` */
+export const ResourceCache = cache.Resource;
+/* eslint-disable @typescript-eslint/only-throw-error */
 /**
  * @internal
  */
@@ -149,7 +33,7 @@ export async function get(url, options, init = {}) {
     // Request no using ranges
     if (typeof options.start != 'number' || typeof options.end != 'number') {
         const { data } = await _fetch(url, init);
-        new ResourceCache(url, data.byteLength, options).add(data, 0);
+        new cache.Resource(url, data.byteLength, options, resourcesCache).add(data, 0);
         return data;
     }
     // Range requests
@@ -162,22 +46,22 @@ export async function get(url, options, init = {}) {
         options.size = size;
     }
     const { size, start, end } = options;
-    const cache = resourcesCache.get(url) ?? new ResourceCache(url, size, options);
+    const resource = resourcesCache.get(url) ?? new cache.Resource(url, size, options, resourcesCache);
     req.headers.set('If-Range', new Date().toUTCString());
-    for (const { start: from, end: to } of cache.missing(start, end)) {
+    for (const { start: from, end: to } of resource.missing(start, end)) {
         const { data, response } = await _fetch(req, { headers: { Range: `bytes=${from}-${to}` } });
         if (response.status == 206) {
-            cache.add(data, from);
+            resource.add(data, from);
             continue;
         }
         // The first response doesn't have a "partial content" (206) status
         options.warn?.(url + ': Remote does not support range requests with bytes. Falling back to full data.');
-        new ResourceCache(url, size, options).add(data, 0);
+        new cache.Resource(url, size, options, resourcesCache).add(data, 0);
         return data.subarray(start, end);
     }
     // This ensures we get a single buffer with the entire requested range
-    cache.collect();
-    const region = cache.regionAt(start);
+    resource.collect();
+    const region = resource.regionAt(start);
     return region.data.subarray(start - region.offset, end - region.offset);
 }
 /**
@@ -226,13 +110,13 @@ export function getCached(url, options) {
  */
 export async function set(url, data, options, init = {}) {
     if (!resourcesCache.has(url)) {
-        new ResourceCache(url, options.size ?? data.byteLength, options);
+        new cache.Resource(url, options.size ?? data.byteLength, options, resourcesCache);
     }
-    const cache = resourcesCache.get(url);
+    const resource = resourcesCache.get(url);
     const { offset = 0 } = options;
     if (!options.cacheOnly)
         await _fetch(new Request(url, init), { method: 'POST' }, true);
-    cache.add(data, offset).collect();
+    resource.add(data, offset).collect();
 }
 /**
  * Make a DELETE request to remove the resource from the server and clear it from the cache.

package/package.json

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

package/readme.md

@@ -9,6 +9,7 @@ A bunch of utilities for Typescript. This includes:
 - Extending buffers easier with `extendBuffer`
 - Convenience types and functions for strings and objects
 - RNG functions
+- Ranged cache
 - `List`, a class that combines the best aspects of `Set` and arrays
 - `JSONFileMap` and `FolderMap`
 - Version utilities

package/src/cache.ts

@@ -0,0 +1,169 @@
+/** A ranged cache */
+import { extendBuffer } from './buffer.js';
+
+export interface Options {
+	/**
+	 * If true, use multiple buffers to cache a file.
+	 * This is useful when working with small parts of large files,
+	 * since we don't need to allocate a large buffer that is mostly unused
+	 * @default true
+	 */
+	sparse?: boolean;
+
+	/**
+	 * The threshold for whether to combine regions or not
+	 * @see Region
+	 * @default 0xfff // 4 KiB
+	 */
+	regionGapThreshold?: number;
+
+	/**
+	 * Whether to only update the cache when changing or deleting resources
+	 * @default false
+	 */
+	cacheOnly?: boolean;
+}
+
+export type Range = { start: number; end: number };
+
+export interface Region {
+	/** The region's offset from the start of the resource */
+	offset: number;
+
+	/** Ranges cached in this region. These are absolute! */
+	ranges: Range[];
+
+	/** Data for this region */
+	data: Uint8Array;
+}
+
+/**
+ * The cache for a specific resource
+ * @internal
+ */
+export class Resource {
+	/** Regions used to reduce unneeded allocations. Think of sparse arrays. */
+	public readonly regions: Region[] = [];
+
+	public constructor(
+		/** The resource ID */
+		public readonly id: string,
+		/** The full size of the resource */
+		public readonly size: number,
+		protected readonly options: Options,
+		resources?: Map<string, Resource | undefined>
+	) {
+		options.sparse ??= true;
+		if (!options.sparse) this.regions.push({ offset: 0, data: new Uint8Array(size), ranges: [] });
+
+		resources?.set(id, this);
+	}
+
+	/** Combines adjacent regions and combines adjacent ranges within a region */
+	public collect(): void {
+		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) {
+				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[], 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 = extendBuffer(current.data, next.offset + next.data.byteLength);
+			current.data.set(next.data, next.offset - current.offset);
+
+			// Remove the next region after merging
+			this.regions.splice(i + 1, 1);
+		}
+	}
+
+	/** Takes an initial range and finds the sub-ranges that are not in the cache */
+	public missing(start: number, end: number): Range[] {
+		const missingRanges: Range[] = [];
+
+		for (const region of this.regions) {
+			if (region.offset >= end) break;
+
+			for (const range of region.ranges) {
+				if (range.end <= start) continue;
+
+				if (range.start >= end) break;
+
+				if (range.start > start) {
+					missingRanges.push({ start, end: Math.min(range.start, end) });
+				}
+
+				// Adjust the current start if the region overlaps
+				if (range.end > start) start = Math.max(start, range.end);
+
+				if (start >= end) break;
+			}
+
+			if (start >= end) break;
+		}
+
+		// If there are still missing parts at the end
+		if (start < end) missingRanges.push({ start, end });
+
+		return missingRanges;
+	}
+
+	/** Get the region who's ranges include an offset */
+	public regionAt(offset: number): Region | undefined {
+		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;
+		}
+	}
+
+	/** Add new data to the cache at given specified offset */
+	public add(data: Uint8Array, offset: number): this {
+		const end = offset + data.byteLength;
+		const region = this.regionAt(offset);
+
+		if (region) {
+			region.data = extendBuffer(region.data, end);
+			region.data.set(data, offset);
+			region.ranges.push({ start: offset, end });
+			region.ranges.sort((a, b) => a.start - b.start);
+
+			return this;
+		}
+
+		// Find the correct index to insert the new region
+		const newRegion: Region = { 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
+		}
+
+		return this;
+	}
+}

package/src/debugging.ts

@@ -1,4 +1,4 @@
-/* eslint-disable @typescript-eslint/no-explicit-any */
+/* eslint-disable @typescript-eslint/no-explicit-any, @typescript-eslint/no-base-to-string */
 export interface CreateLoggerOptions {
 	/**
 	 * The function used to output
@@ -25,10 +25,33 @@ export interface CreateLoggerOptions {
 }
 
 function defaultStringify(value: unknown): string {
-	if (value === null) return 'null';
-	if (value === undefined) return 'undefined';
-	// eslint-disable-next-line @typescript-eslint/no-base-to-string
-	return value.toString();
+	switch (typeof value) {
+		case 'undefined':
+			return 'undefined';
+		case 'string':
+		case 'number':
+		case 'boolean':
+			return JSON.stringify(value);
+		case 'bigint':
+		case 'symbol':
+			return value.toString();
+		case 'function':
+			return value.name + '()';
+		case 'object':
+			if (value === null) return 'null';
+			if (ArrayBuffer.isView(value)) {
+				const length = 'length' in value ? (value.length as number) : value.byteLength / (value.constructor as any).BYTES_PER_ELEMENT;
+				return `${value.constructor.name.replaceAll('Array', '').toLowerCase()}[${length}]`;
+			}
+			if (Array.isArray(value)) return `unknown[${value.length}]`;
+			try {
+				const json = JSON.stringify(value);
+
+				return json.length < 100 ? json : value.toString();
+			} catch {
+				return value.toString();
+			}
+	}
 }
 
 type LoggableDecoratorContext = Exclude<DecoratorContext, ClassFieldDecoratorContext>;

package/src/requests.ts

@@ -1,184 +1,26 @@
 /* Utilities for `fetch` when using range requests. It also allows you to handle errors easier */
 
-import { extendBuffer } from './buffer.js';
+import * as cache from './cache.js';
 
-/* eslint-disable @typescript-eslint/only-throw-error */
-
-export interface CacheOptions {
-	/**
-	 * If true, use multiple buffers to cache a file.
-	 * This is useful when working with small parts of large files,
-	 * since we don't need to allocate a large buffer that is mostly unused
-	 * @default true
-	 */
-	sparse?: boolean;
-
-	/**
-	 * The threshold for whether to combine regions or not
-	 * @see CacheRegion
-	 * @default 0xfff // 4 KiB
-	 */
-	regionGapThreshold?: number;
-
-	/**
-	 * Whether to only update the cache when changing or deleting resources
-	 * @default false
-	 */
-	cacheOnly?: boolean;
-}
-
-/**
- * @deprecated Use `CacheOptions`
- */
-export type ResourceCacheOptions = CacheOptions;
-
-export type CacheRange = { start: number; end: number };
-
-export interface CacheRegion {
-	/** The region's offset from the start of the resource */
-	offset: number;
-
-	/** Ranges cached in this region. These are absolute! */
-	ranges: CacheRange[];
-
-	/** Data for this region */
-	data: Uint8Array;
-}
-
-/**
- * The cache for a specific resource
- * @internal
- */
-export class ResourceCache {
-	/** Regions used to reduce unneeded allocations. Think of sparse arrays. */
-	public readonly regions: CacheRegion[] = [];
-
-	public constructor(
-		/** The resource URL */
-		public readonly url: string,
-		/** The full size of the resource */
-		public readonly size: number,
-		protected readonly options: CacheOptions
-	) {
-		options.sparse ??= true;
-		if (!options.sparse) this.regions.push({ offset: 0, data: new Uint8Array(size), ranges: [] });
-
-		resourcesCache.set(url, this);
-	}
-
-	/** Combines adjacent regions and combines adjacent ranges within a region */
-	public collect(): void {
-		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) {
-				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: CacheRange[], 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 = extendBuffer(current.data, next.offset + next.data.byteLength);
-			current.data.set(next.data, next.offset - current.offset);
-
-			// Remove the next region after merging
-			this.regions.splice(i + 1, 1);
-		}
-	}
+// Compatibility
 
-	/** Takes an initial range and finds the sub-ranges that are not in the cache */
-	public missing(start: number, end: number): CacheRange[] {
-		const missingRanges: CacheRange[] = [];
+/** @deprecated Use `cache.Options` */
+export type ResourceCacheOptions = cache.Options;
+/** @deprecated Use `cache.Resource` */
+export const ResourceCache = cache.Resource;
+/** @deprecated Use `cache.Resource` */
+export type ResourceCache = cache.Resource;
+/** @deprecated Use `cache.Range` */
+export type CacheRange = cache.Range;
+/** @deprecated Use `cache.Options` */
+export type CacheOptions = cache.Options;
 
-		for (const region of this.regions) {
-			if (region.offset >= end) break;
-
-			for (const range of region.ranges) {
-				if (range.end <= start) continue;
-
-				if (range.start >= end) break;
-
-				if (range.start > start) {
-					missingRanges.push({ start, end: Math.min(range.start, end) });
-				}
-
-				// Adjust the current start if the region overlaps
-				if (range.end > start) start = Math.max(start, range.end);
-
-				if (start >= end) break;
-			}
-
-			if (start >= end) break;
-		}
-
-		// If there are still missing parts at the end
-		if (start < end) missingRanges.push({ start, end });
-
-		return missingRanges;
-	}
-
-	/** Get the region who's ranges include an offset */
-	public regionAt(offset: number): CacheRegion | undefined {
-		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;
-		}
-	}
-
-	/** Add new data to the cache at given specified offset */
-	public add(data: Uint8Array, offset: number): this {
-		const end = offset + data.byteLength;
-		const region = this.regionAt(offset);
-
-		if (region) {
-			region.data = extendBuffer(region.data, end);
-			region.data.set(data, offset);
-			region.ranges.push({ start: offset, end });
-			region.ranges.sort((a, b) => a.start - b.start);
-
-			return this;
-		}
-
-		// Find the correct index to insert the new region
-		const newRegion: CacheRegion = { 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
-		}
-
-		return this;
-	}
-}
+/* eslint-disable @typescript-eslint/only-throw-error */
 
 /**
  * @internal
  */
-export const resourcesCache = new Map<string, ResourceCache | null>();
+export const resourcesCache = new Map<string, cache.Resource | undefined>();
 
 export type Issue = { tag: 'status'; response: Response } | { tag: 'buffer'; response: Response; message: string } | { tag: 'fetch' | 'size'; message: string } | Error;
 
@@ -215,7 +57,7 @@ async function _fetch<const TBodyOptional extends boolean>(
 	return { response, data: raw ? new Uint8Array(raw) : undefined } as Fetched<TBodyOptional>;
 }
 
-export interface Options extends CacheOptions {
+export interface Options extends cache.Options {
 	/** Optionally provide a function for logging warnings */
 	warn?(message: string): unknown;
 }
@@ -250,7 +92,7 @@ export async function get(url: string, options: GetOptions, init: RequestInit =
 	// Request no using ranges
 	if (typeof options.start != 'number' || typeof options.end != 'number') {
 		const { data } = await _fetch(url, init);
-		new ResourceCache(url, data.byteLength, options).add(data, 0);
+		new cache.Resource(url, data.byteLength, options, resourcesCache).add(data, 0);
 		return data;
 	}
 
@@ -266,28 +108,28 @@ export async function get(url: string, options: GetOptions, init: RequestInit =
 	}
 
 	const { size, start, end } = options;
-	const cache = resourcesCache.get(url) ?? new ResourceCache(url, size, options);
+	const resource = resourcesCache.get(url) ?? new cache.Resource(url, size, options, resourcesCache);
 
 	req.headers.set('If-Range', new Date().toUTCString());
 
-	for (const { start: from, end: to } of cache.missing(start, end)) {
+	for (const { start: from, end: to } of resource.missing(start, end)) {
 		const { data, response } = await _fetch(req, { headers: { Range: `bytes=${from}-${to}` } });
 
 		if (response.status == 206) {
-			cache.add(data, from);
+			resource.add(data, from);
 			continue;
 		}
 
 		// The first response doesn't have a "partial content" (206) status
 		options.warn?.(url + ': Remote does not support range requests with bytes. Falling back to full data.');
-		new ResourceCache(url, size, options).add(data, 0);
+		new cache.Resource(url, size, options, resourcesCache).add(data, 0);
 		return data.subarray(start, end);
 	}
 
 	// This ensures we get a single buffer with the entire requested range
-	cache.collect();
+	resource.collect();
 
-	const region = cache.regionAt(start)!;
+	const region = resource.regionAt(start)!;
 	return region.data.subarray(start - region.offset, end - region.offset);
 }
 
@@ -300,7 +142,7 @@ export const GET = get;
  * Synchronously gets a cached resource
  * Assumes you pass valid start and end when using ranges
  */
-export function getCached(url: string, options: GetOptions): { data?: Uint8Array; missing: CacheRange[] } {
+export function getCached(url: string, options: GetOptions): { data?: Uint8Array; missing: cache.Range[] } {
 	const cache = resourcesCache.get(url);
 
 	/**
@@ -350,16 +192,16 @@ interface SetOptions extends Options {
  */
 export async function set(url: string, data: Uint8Array, options: SetOptions, init: RequestInit = {}): Promise<void> {
 	if (!resourcesCache.has(url)) {
-		new ResourceCache(url, options.size ?? data.byteLength, options);
+		new cache.Resource(url, options.size ?? data.byteLength, options, resourcesCache);
 	}
 
-	const cache = resourcesCache.get(url)!;
+	const resource = resourcesCache.get(url)!;
 
 	const { offset = 0 } = options;
 
 	if (!options.cacheOnly) await _fetch(new Request(url, init), { method: 'POST' }, true);
 
-	cache.add(data, offset).collect();
+	resource.add(data, offset).collect();
 }
 
 /**