utilium 1.2.2 → 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.d.ts

@@ -1,8 +1,25 @@
 export interface CreateLoggerOptions {
+    /**
+     * The function used to output
+     * @default console.log
+     */
     output?: (...args: any[]) => void;
     stringify?: (value: unknown) => string;
+    /**
+     * Whether to output the class name when logging methods
+     * @default true
+     */
     className?: boolean;
+    /**
+     * The separator used to separate the class name and method.
+     * Ignored if `className` is `false`
+     * @default '#'
+     */
     separator?: string;
+    /**
+     * Whether to log the return value
+     * @default false
+     */
     returnValue?: boolean;
 }
 type LoggableDecoratorContext = Exclude<DecoratorContext, ClassFieldDecoratorContext>;

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,31 +1,19 @@
-export interface ResourceCacheOptions {
-    /**
-     * 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;
-}
-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;
-}
-export type RequestError = {
+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, cache.Resource | undefined>;
+export type Issue = {
     tag: 'status';
     response: Response;
 } | {
@@ -36,7 +24,19 @@ export type RequestError = {
     tag: 'fetch' | 'size';
     message: string;
 } | Error;
-export interface RequestOptions extends ResourceCacheOptions {
+/**
+ * @deprecated Use `Issue`
+ */
+export type RequestError = Issue;
+export interface Options extends cache.Options {
+    /** Optionally provide a function for logging warnings */
+    warn?(message: string): unknown;
+}
+/**
+ * @deprecated Use `Options`
+ */
+export type RequestOptions = Options;
+export interface GetOptions extends Options {
     /**
      * When using range requests,
      * a HEAD request must normally be used to determine the full size of the resource.
@@ -47,19 +47,38 @@ export interface RequestOptions extends ResourceCacheOptions {
     start?: number;
     /** The end of the range */
     end?: number;
-    /** Optionally provide a function for logging warnings */
-    warn?(message: string): unknown;
 }
 /**
  * Make a GET request without worrying about ranges
  * @throws RequestError
  */
-export declare function GET(url: string, options: RequestOptions, init?: RequestInit): Promise<Uint8Array>;
+export declare function get(url: string, options: GetOptions, init?: RequestInit): Promise<Uint8Array>;
+/**
+ * @deprecated Use `get`
+ */
+export declare const GET: typeof get;
 /**
  * Synchronously gets a cached resource
  * Assumes you pass valid start and end when using ranges
  */
-export declare function getCached(url: string, options: RequestOptions): {
-    data: Uint8Array;
-    missing: CacheRange[];
+export declare function getCached(url: string, options: GetOptions): {
+    data?: Uint8Array;
+    missing: cache.Range[];
 };
+interface SetOptions extends Options {
+    /** The offset we are updating at */
+    offset?: number;
+    /** If a cache for the resource doesn't exist, this will be used as the full size */
+    size?: number;
+}
+/**
+ * Make a POST request to set (or create) data on the server and update the cache.
+ * @throws RequestError
+ */
+export declare function set(url: string, data: Uint8Array, options: SetOptions, init?: RequestInit): Promise<void>;
+/**
+ * Make a DELETE request to remove the resource from the server and clear it from the cache.
+ * @throws RequestError
+ */
+export declare function remove(url: string, options?: Options, init?: RequestInit): Promise<void>;
+export {};

package/dist/requests.js

@@ -1,145 +1,39 @@
 /* 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 */
-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: [] });
-        requestsCache.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, start, end = start + data.byteLength) {
-        const region = this.regionAt(start);
-        if (region) {
-            region.data = extendBuffer(region.data, end);
-            region.ranges.push({ start, 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: start, ranges: [{ start, end }] };
-        const insertIndex = this.regions.findIndex(region => region.offset > start);
-        // 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;
-    }
-}
-const requestsCache = new Map();
+import * as cache from './cache.js';
+/** @deprecated Use `cache.Resource` */
+export const ResourceCache = cache.Resource;
+/* eslint-disable @typescript-eslint/only-throw-error */
+/**
+ * @internal
+ */
+export const resourcesCache = new Map();
 /**
  * Wraps `fetch`
  * @throws RequestError
  */
-async function _fetchBuffer(input, init = {}) {
+async function _fetch(input, init = {}, bodyOptional = false) {
     const response = await fetch(input, init).catch((error) => {
         throw { tag: 'fetch', message: error.message };
     });
     if (!response.ok)
         throw { tag: 'status', response };
-    const arrayBuffer = await response.arrayBuffer().catch((error) => {
+    const raw = await response.arrayBuffer().catch((error) => {
+        if (bodyOptional)
+            return;
         throw { tag: 'buffer', response, message: error.message };
     });
-    return { response, data: new Uint8Array(arrayBuffer) };
+    return { response, data: raw ? new Uint8Array(raw) : undefined };
 }
 /**
  * Make a GET request without worrying about ranges
  * @throws RequestError
  */
-export async function GET(url, options, init = {}) {
+export async function get(url, options, init = {}) {
     const req = new Request(url, init);
     // Request no using ranges
     if (typeof options.start != 'number' || typeof options.end != 'number') {
-        const { data } = await _fetchBuffer(url, init);
-        new ResourceCache(url, data.byteLength, options).add(data, 0);
+        const { data } = await _fetch(url, init);
+        new cache.Resource(url, data.byteLength, options, resourcesCache).add(data, 0);
         return data;
     }
     // Range requests
@@ -152,35 +46,43 @@ export async function GET(url, options, init = {}) {
         options.size = size;
     }
     const { size, start, end } = options;
-    const cache = requestsCache.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)) {
-        const { data, response } = await _fetchBuffer(req, { headers: { Range: `bytes=${from}-${to}` } });
+    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);
 }
+/**
+ * @deprecated Use `get`
+ */
+export const GET = get;
 /**
  * Synchronously gets a cached resource
  * Assumes you pass valid start and end when using ranges
  */
 export function getCached(url, options) {
-    const cache = requestsCache.get(url);
+    const cache = resourcesCache.get(url);
     /**
      * @todo Make sure we have a size?
      */
-    if (!cache)
-        return { data: new Uint8Array(0), missing: [{ start: 0, end: options.size ?? 0 }] };
+    if (!cache) {
+        if (options.size)
+            return { data: new Uint8Array(0), missing: [{ start: 0, end: options.size ?? 0 }] };
+        options.warn?.(url + ': Size not provided and cache is empty, can not determine missing range');
+        return { data: undefined, missing: [] };
+    }
     const { start = 0, end = cache.size } = options;
     const data = new Uint8Array(end - start);
     for (const region of cache.regions) {
@@ -202,3 +104,26 @@ export function getCached(url, options) {
     }
     return { data, missing: cache.missing(start, end) };
 }
+/**
+ * Make a POST request to set (or create) data on the server and update the cache.
+ * @throws RequestError
+ */
+export async function set(url, data, options, init = {}) {
+    if (!resourcesCache.has(url)) {
+        new cache.Resource(url, options.size ?? data.byteLength, options, resourcesCache);
+    }
+    const resource = resourcesCache.get(url);
+    const { offset = 0 } = options;
+    if (!options.cacheOnly)
+        await _fetch(new Request(url, init), { method: 'POST' }, true);
+    resource.add(data, offset).collect();
+}
+/**
+ * Make a DELETE request to remove the resource from the server and clear it from the cache.
+ * @throws RequestError
+ */
+export async function remove(url, options = {}, init = {}) {
+    if (!options.cacheOnly)
+        await _fetch(new Request(url, init), { method: 'DELETE' }, true);
+    resourcesCache.delete(url);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "utilium",
-	"version": "1.2.2",
+	"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,17 +1,57 @@
-/* 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
+	 * @default console.log
+	 */
 	output?: (...args: any[]) => void;
 	stringify?: (value: unknown) => string;
+	/**
+	 * Whether to output the class name when logging methods
+	 * @default true
+	 */
 	className?: boolean;
+	/**
+	 * The separator used to separate the class name and method.
+	 * Ignored if `className` is `false`
+	 * @default '#'
+	 */
 	separator?: string;
+	/**
+	 * Whether to log the return value
+	 * @default false
+	 */
 	returnValue?: boolean;
 }
 
 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,187 +1,73 @@
 /* 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 ResourceCacheOptions {
-	/**
-	 * 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;
-}
-
-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 */
-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: ResourceCacheOptions
-	) {
-		options.sparse ??= true;
-		if (!options.sparse) this.regions.push({ offset: 0, data: new Uint8Array(size), ranges: [] });
-
-		requestsCache.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);
-		}
-	}
-
-	/** 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[] = [];
-
-		for (const region of this.regions) {
-			if (region.offset >= end) break;
+// Compatibility
 
-			for (const range of region.ranges) {
-				if (range.end <= start) continue;
+/** @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;
 
-				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, start: number, end: number = start + data.byteLength): this {
-		const region = this.regionAt(start);
-
-		if (region) {
-			region.data = extendBuffer(region.data, end);
-			region.ranges.push({ start, end });
-			region.ranges.sort((a, b) => a.start - b.start);
+/* eslint-disable @typescript-eslint/only-throw-error */
 
-			return this;
-		}
+/**
+ * @internal
+ */
+export const resourcesCache = new Map<string, cache.Resource | undefined>();
 
-		// Find the correct index to insert the new region
-		const newRegion: CacheRegion = { data, offset: start, ranges: [{ start, end }] };
-		const insertIndex = this.regions.findIndex(region => region.offset > start);
+export type Issue = { tag: 'status'; response: Response } | { tag: 'buffer'; response: Response; message: string } | { tag: 'fetch' | 'size'; message: string } | Error;
 
-		// 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
-		}
+/**
+ * @deprecated Use `Issue`
+ */
+export type RequestError = Issue;
 
-		return this;
-	}
+interface Fetched<TBodyOptional extends boolean> {
+	response: Response;
+	data: false extends TBodyOptional ? Uint8Array : Uint8Array | undefined;
 }
 
-const requestsCache = new Map<string, ResourceCache | null>();
-
-export type RequestError = { tag: 'status'; response: Response } | { tag: 'buffer'; response: Response; message: string } | { tag: 'fetch' | 'size'; message: string } | Error;
-
 /**
  * Wraps `fetch`
  * @throws RequestError
  */
-async function _fetchBuffer(input: RequestInfo, init: RequestInit = {}): Promise<{ response: Response; data: Uint8Array }> {
+async function _fetch<const TBodyOptional extends boolean>(
+	input: RequestInfo,
+	init: RequestInit = {},
+	bodyOptional: TBodyOptional = false as TBodyOptional
+): Promise<Fetched<TBodyOptional>> {
 	const response = await fetch(input, init).catch((error: Error) => {
-		throw { tag: 'fetch', message: error.message } satisfies RequestError;
+		throw { tag: 'fetch', message: error.message } satisfies Issue;
 	});
 
-	if (!response.ok) throw { tag: 'status', response } satisfies RequestError;
+	if (!response.ok) throw { tag: 'status', response } satisfies Issue;
 
-	const arrayBuffer = await response.arrayBuffer().catch((error: Error) => {
-		throw { tag: 'buffer', response, message: error.message } satisfies RequestError;
+	const raw = await response.arrayBuffer().catch((error: Error) => {
+		if (bodyOptional) return;
+		throw { tag: 'buffer', response, message: error.message } satisfies Issue;
 	});
 
-	return { response, data: new Uint8Array(arrayBuffer) };
+	return { response, data: raw ? new Uint8Array(raw) : undefined } as Fetched<TBodyOptional>;
+}
+
+export interface Options extends cache.Options {
+	/** Optionally provide a function for logging warnings */
+	warn?(message: string): unknown;
 }
 
-export interface RequestOptions extends ResourceCacheOptions {
+/**
+ * @deprecated Use `Options`
+ */
+export type RequestOptions = Options;
+
+export interface GetOptions extends Options {
 	/**
 	 * When using range requests,
 	 * a HEAD request must normally be used to determine the full size of the resource.
@@ -194,22 +80,19 @@ export interface RequestOptions extends ResourceCacheOptions {
 
 	/** The end of the range */
 	end?: number;
-
-	/** Optionally provide a function for logging warnings */
-	warn?(message: string): unknown;
 }
 
 /**
  * Make a GET request without worrying about ranges
  * @throws RequestError
  */
-export async function GET(url: string, options: RequestOptions, init: RequestInit = {}): Promise<Uint8Array> {
+export async function get(url: string, options: GetOptions, init: RequestInit = {}): Promise<Uint8Array> {
 	const req = new Request(url, init);
 
 	// Request no using ranges
 	if (typeof options.start != 'number' || typeof options.end != 'number') {
-		const { data } = await _fetchBuffer(url, init);
-		new ResourceCache(url, data.byteLength, options).add(data, 0);
+		const { data } = await _fetch(url, init);
+		new cache.Resource(url, data.byteLength, options, resourcesCache).add(data, 0);
 		return data;
 	}
 
@@ -220,47 +103,56 @@ export async function GET(url: string, options: RequestOptions, init: RequestIni
 
 		const { headers } = await fetch(req, { method: 'HEAD' });
 		const size = parseInt(headers.get('Content-Length') ?? '');
-		if (typeof size != 'number') throw { tag: 'size', message: 'Response is missing content-length header and no size was provided' } satisfies RequestError;
+		if (typeof size != 'number') throw { tag: 'size', message: 'Response is missing content-length header and no size was provided' } satisfies Issue;
 		options.size = size;
 	}
 
 	const { size, start, end } = options;
-	const cache = requestsCache.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)) {
-		const { data, response } = await _fetchBuffer(req, { headers: { Range: `bytes=${from}-${to}` } });
+	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);
 }
 
+/**
+ * @deprecated Use `get`
+ */
+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: RequestOptions): { data: Uint8Array; missing: CacheRange[] } {
-	const cache = requestsCache.get(url);
+export function getCached(url: string, options: GetOptions): { data?: Uint8Array; missing: cache.Range[] } {
+	const cache = resourcesCache.get(url);
 
 	/**
 	 * @todo Make sure we have a size?
 	 */
-	if (!cache) return { data: new Uint8Array(0), missing: [{ start: 0, end: options.size ?? 0 }] };
+	if (!cache) {
+		if (options.size) return { data: new Uint8Array(0), missing: [{ start: 0, end: options.size ?? 0 }] };
+		options.warn?.(url + ': Size not provided and cache is empty, can not determine missing range');
+		return { data: undefined, missing: [] };
+	}
 
 	const { start = 0, end = cache.size } = options;
 
@@ -285,3 +177,38 @@ export function getCached(url: string, options: RequestOptions): { data: Uint8Ar
 
 	return { data, missing: cache.missing(start, end) };
 }
+
+interface SetOptions extends Options {
+	/** The offset we are updating at */
+	offset?: number;
+
+	/** If a cache for the resource doesn't exist, this will be used as the full size */
+	size?: number;
+}
+
+/**
+ * Make a POST request to set (or create) data on the server and update the cache.
+ * @throws RequestError
+ */
+export async function set(url: string, data: Uint8Array, options: SetOptions, init: RequestInit = {}): Promise<void> {
+	if (!resourcesCache.has(url)) {
+		new cache.Resource(url, options.size ?? data.byteLength, options, resourcesCache);
+	}
+
+	const resource = resourcesCache.get(url)!;
+
+	const { offset = 0 } = options;
+
+	if (!options.cacheOnly) await _fetch(new Request(url, init), { method: 'POST' }, true);
+
+	resource.add(data, offset).collect();
+}
+
+/**
+ * Make a DELETE request to remove the resource from the server and clear it from the cache.
+ * @throws RequestError
+ */
+export async function remove(url: string, options: Options = {}, init: RequestInit = {}): Promise<void> {
+	if (!options.cacheOnly) await _fetch(new Request(url, init), { method: 'DELETE' }, true);
+	resourcesCache.delete(url);
+}