utilium 1.1.3 → 1.2.0

package/dist/buffer.d.ts

@@ -0,0 +1,15 @@
+/**
+ * A generic ArrayBufferView (typed array) constructor
+ */
+export interface ArrayBufferViewConstructor {
+    readonly prototype: ArrayBufferView<ArrayBufferLike>;
+    new (length: number): ArrayBufferView<ArrayBuffer>;
+    new (array: ArrayLike<number>): ArrayBufferView<ArrayBuffer>;
+    new <TArrayBuffer extends ArrayBufferLike = ArrayBuffer>(buffer: TArrayBuffer, byteOffset?: number, length?: number): ArrayBufferView<TArrayBuffer>;
+    new (array: ArrayLike<number> | ArrayBuffer): ArrayBufferView<ArrayBuffer>;
+}
+/**
+ * Grows a buffer if it isn't large enough
+ * @returns The original buffer if resized successfully, or a newly created buffer
+ */
+export declare function extendBuffer<T extends ArrayBufferLike | ArrayBufferView>(buffer: T, newByteLength: number): T;

package/dist/buffer.js

@@ -0,0 +1,32 @@
+/* eslint-disable @typescript-eslint/no-unsafe-call,@typescript-eslint/no-unused-expressions */
+/**
+ * Grows a buffer if it isn't large enough
+ * @returns The original buffer if resized successfully, or a newly created buffer
+ */
+export function extendBuffer(buffer, newByteLength) {
+    if (buffer.byteLength >= newByteLength)
+        return buffer;
+    if (ArrayBuffer.isView(buffer)) {
+        const newBuffer = extendBuffer(buffer.buffer, newByteLength);
+        return new buffer.constructor(newBuffer, buffer.byteOffset, newByteLength);
+    }
+    const isShared = typeof SharedArrayBuffer !== 'undefined' && buffer instanceof SharedArrayBuffer;
+    // Note: If true, the buffer must be resizable/growable because of the first check.
+    if (buffer.maxByteLength > newByteLength) {
+        isShared ? buffer.grow(newByteLength) : buffer.resize(newByteLength);
+        return buffer;
+    }
+    if (isShared) {
+        const newBuffer = new SharedArrayBuffer(newByteLength);
+        new Uint8Array(newBuffer).set(new Uint8Array(buffer));
+        return newBuffer;
+    }
+    try {
+        return buffer.transfer(newByteLength);
+    }
+    catch {
+        const newBuffer = new ArrayBuffer(newByteLength);
+        new Uint8Array(newBuffer).set(new Uint8Array(buffer));
+        return newBuffer;
+    }
+}

package/dist/debugging.d.ts

@@ -0,0 +1,13 @@
+export interface CreateLoggerOptions {
+    output?: (...args: any[]) => void;
+    stringify?: (value: unknown) => string;
+    className?: boolean;
+    separator?: string;
+    returnValue?: boolean;
+}
+type LoggableDecoratorContext = Exclude<DecoratorContext, ClassFieldDecoratorContext>;
+/**
+ * Create a function that can be used to decorate classes and non-field members.
+ */
+export declare function createLogDecorator(options: CreateLoggerOptions): <T extends (...args: any[]) => any>(value: T, context: LoggableDecoratorContext) => T;
+export {};

package/dist/debugging.js

@@ -0,0 +1,30 @@
+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();
+}
+/**
+ * Create a function that can be used to decorate classes and non-field members.
+ */
+export function createLogDecorator(options) {
+    const { output = console.log, separator = '#', returnValue = false, stringify = defaultStringify, className = true } = options;
+    return function log(value, context) {
+        if (context.kind == 'class') {
+            return function (...args) {
+                output(`new ${value.name} (${args.map(stringify).join(', ')})`);
+                return Reflect.construct(value, args);
+            };
+        }
+        return function (...args) {
+            const prefix = (className ? this.constructor.name + separator : '') + context.name.toString();
+            output(`${prefix}(${args.map(stringify).join(', ')})`);
+            const result = value.call(this, ...args);
+            if (returnValue)
+                output(' => ' + stringify(result));
+            return result;
+        };
+    };
+}

package/dist/fs.d.ts

@@ -9,7 +9,7 @@ export declare abstract class FileMap<V> implements Map<string, V> {
     abstract has(key: string): boolean;
     abstract set(key: string, value: V): this;
     get size(): number;
-    get [Symbol.iterator](): () => IterableIterator<[string, V]>;
+    get [Symbol.iterator](): () => MapIterator<[string, V]>;
     get keys(): typeof this._map.keys;
     get values(): typeof this._map.values;
     get entries(): typeof this._map.entries;

package/dist/index.js

@@ -1,3 +1,5 @@
+// This file should not be added to
+// For better tree shaking, import from whichever file is actually needed
 export * from './list.js';
 export * from './misc.js';
 export * from './numbers.js';

package/dist/internal/struct.d.ts

@@ -19,6 +19,7 @@ export declare const init: typeof Symbol.struct_init;
 export interface Options {
     align: number;
     bigEndian: boolean;
+    isUnion: boolean;
 }
 export interface Member {
     type: primitive.Type | Static;

package/dist/misc.d.ts

@@ -1,3 +1,11 @@
 export declare function wait(time: number): Promise<unknown>;
 export declare const greekLetterNames: string[];
 export declare function isHex(str: string): boolean;
+/** Prevent infinite loops */
+export declare function canary(error?: Error): () => void;
+/**
+ * A wrapper for throwing things in an expression context.
+ * You will likely want to remove this if you can just use `throw` in expressions.
+ * @see https://github.com/tc39/proposal-throw-expressions
+ */
+export declare function _throw(e: unknown): never;

package/dist/misc.js

@@ -31,3 +31,18 @@ const hexRegex = /^[0-9a-f-.]+$/;
 export function isHex(str) {
     return hexRegex.test(str);
 }
+/** Prevent infinite loops */
+export function canary(error = new Error()) {
+    const timeout = setTimeout(() => {
+        throw error;
+    }, 5000);
+    return () => clearTimeout(timeout);
+}
+/**
+ * A wrapper for throwing things in an expression context.
+ * You will likely want to remove this if you can just use `throw` in expressions.
+ * @see https://github.com/tc39/proposal-throw-expressions
+ */
+export function _throw(e) {
+    throw e;
+}

package/dist/requests.d.ts

@@ -0,0 +1,45 @@
+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 RequestError = {
+    tag: 'status';
+    response: Response;
+} | {
+    tag: 'buffer';
+    response: Response;
+    message: string;
+} | {
+    tag: 'fetch' | 'size';
+    message: string;
+} | Error;
+export interface RequestOptions extends ResourceCacheOptions {
+    /**
+     * When using range requests,
+     * a HEAD request must normally be used to determine the full size of the resource.
+     * This allows that request to be skipped
+     */
+    size?: number;
+    /** The start of the range */
+    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>;

package/dist/requests.js

@@ -0,0 +1,172 @@
+/* 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();
+/**
+ * Wraps `fetch`
+ * @throws RequestError
+ */
+async function _fetchBuffer(input, init = {}) {
+    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) => {
+        throw { tag: 'buffer', response, message: error.message };
+    });
+    return { response, data: new Uint8Array(arrayBuffer) };
+}
+/**
+ * Make a GET request without worrying about ranges
+ * @throws RequestError
+ */
+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);
+        return data;
+    }
+    // Range requests
+    if (typeof options.size != 'number') {
+        options.warn?.(url + ': Size not provided, an additional HEAD request is being made');
+        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' };
+        options.size = size;
+    }
+    const { size, start, end } = options;
+    const cache = requestsCache.get(url) ?? new ResourceCache(url, size, options);
+    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}` } });
+        if (response.status == 206) {
+            cache.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);
+        return data.subarray(start, end);
+    }
+    // This ensures we get a single buffer with the entire requested range
+    cache.collect();
+    const region = cache.regionAt(start);
+    return region.data.subarray(start - region.offset, end - region.offset);
+}

package/dist/struct.js

@@ -36,11 +36,12 @@ export function struct(options = {}) {
                 throw new TypeError('Not a valid type: ' + type);
             }
             members.set(name, {
-                offset: size,
+                offset: options.isUnion ? 0 : size,
                 type: primitive.isValid(type) ? primitive.normalize(type) : type,
                 length,
             });
-            size += sizeof(type) * (length || 1);
+            const memberSize = sizeof(type) * (length || 1);
+            size = options.isUnion ? Math.max(size, memberSize) : size + memberSize;
             size = align(size, options.align || 1);
         }
         context.metadata[Symbol.struct_metadata] = { options, members, size };
@@ -74,6 +75,7 @@ export function serialize(instance) {
     const { options, members } = instance.constructor[symbol_metadata(instance.constructor)][Symbol.struct_metadata];
     const buffer = new Uint8Array(sizeof(instance));
     const view = new DataView(buffer.buffer);
+    // for unions we should write members in ascending last modified order, but we don't have that info.
     for (const [name, { type, length, offset }] of members) {
         for (let i = 0; i < (length || 1); i++) {
             const iOff = offset + sizeof(type) * i;

package/dist/types.d.ts

@@ -192,4 +192,14 @@ export type WithRequired<T, K extends keyof T> = T & {
  * Makes properties with keys assignable to K in T optional
  */
 export type WithOptional<T, K extends keyof T> = Pick<Partial<T>, K> & Omit<T, K>;
+/**
+ * Nothing in T
+ */
+export type Never<T> = {
+    [K in keyof T]?: never;
+};
+/**
+ * All of the properties in T or none of them
+ */
+export type AllOrNone<T> = T | Never<T>;
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "utilium",
-	"version": "1.1.3",
+	"version": "1.2.0",
 	"description": "Typescript utilities",
 	"funding": {
 		"type": "individual",
@@ -42,15 +42,13 @@
 	"homepage": "https://github.com/james-pre/utilium#readme",
 	"devDependencies": {
 		"@eslint/js": "^9.12.0",
-		"@stylistic/eslint-plugin": "^2.9.0",
-		"@types/eslint__js": "^8.42.3",
 		"@types/node": "^20.12.7",
 		"eslint": "^9.12.0",
 		"globals": "^15.10.0",
 		"prettier": "^3.2.5",
 		"tsx": "^4.19.1",
-		"typedoc": "^0.26.6",
-		"typescript": "^5.5.4",
+		"typedoc": "^0.27.6",
+		"typescript": "^5.7.2",
 		"typescript-eslint": "^8.8.0"
 	},
 	"dependencies": {

package/readme.md

@@ -2,12 +2,14 @@
 
 A bunch of utilities for Typescript. This includes:
 
--   Structs (using decorators)
--   Compile-time math types
--   Debugging types
--   Convenience types and functions for strings and objects
--   RNG functions
--   `List`, a class that combines the best aspects of `Set` and arrays
--   `JSONFileMap` and `FolderMap`
--   Version utilities
--   Xterm.js shell handling (arrows, home/end, prompting, etc.)
+- Structs (using decorators)
+- Compile-time math types
+- Debugging types and functions
+- Utilities for using `fetch` with [HTTP range requests](https://developer.mozilla.org/en-US/docs/Web/HTTP/Range_requests)
+- Extending buffers easier with `extendBuffer`
+- Convenience types and functions for strings and objects
+- RNG functions
+- `List`, a class that combines the best aspects of `Set` and arrays
+- `JSONFileMap` and `FolderMap`
+- Version utilities
+- Xterm.js shell handling (arrows, home/end, prompting, etc.)

package/src/buffer.ts

@@ -0,0 +1,47 @@
+/* eslint-disable @typescript-eslint/no-unsafe-call,@typescript-eslint/no-unused-expressions */
+
+/**
+ * A generic ArrayBufferView (typed array) constructor
+ */
+export interface ArrayBufferViewConstructor {
+	readonly prototype: ArrayBufferView<ArrayBufferLike>;
+	new (length: number): ArrayBufferView<ArrayBuffer>;
+	new (array: ArrayLike<number>): ArrayBufferView<ArrayBuffer>;
+	new <TArrayBuffer extends ArrayBufferLike = ArrayBuffer>(buffer: TArrayBuffer, byteOffset?: number, length?: number): ArrayBufferView<TArrayBuffer>;
+	new (array: ArrayLike<number> | ArrayBuffer): ArrayBufferView<ArrayBuffer>;
+}
+
+/**
+ * Grows a buffer if it isn't large enough
+ * @returns The original buffer if resized successfully, or a newly created buffer
+ */
+export function extendBuffer<T extends ArrayBufferLike | ArrayBufferView>(buffer: T, newByteLength: number): T {
+	if (buffer.byteLength >= newByteLength) return buffer;
+
+	if (ArrayBuffer.isView(buffer)) {
+		const newBuffer = extendBuffer(buffer.buffer, newByteLength);
+		return new (buffer.constructor as ArrayBufferViewConstructor)(newBuffer, buffer.byteOffset, newByteLength) as T;
+	}
+
+	const isShared = typeof SharedArrayBuffer !== 'undefined' && buffer instanceof SharedArrayBuffer;
+
+	// Note: If true, the buffer must be resizable/growable because of the first check.
+	if (buffer.maxByteLength > newByteLength) {
+		isShared ? buffer.grow(newByteLength) : (buffer as ArrayBuffer).resize(newByteLength);
+		return buffer;
+	}
+
+	if (isShared) {
+		const newBuffer = new SharedArrayBuffer(newByteLength) as T & SharedArrayBuffer;
+		new Uint8Array(newBuffer).set(new Uint8Array(buffer));
+		return newBuffer;
+	}
+
+	try {
+		return (buffer as ArrayBuffer).transfer(newByteLength) as T;
+	} catch {
+		const newBuffer = new ArrayBuffer(newByteLength) as T & ArrayBuffer;
+		new Uint8Array(newBuffer).set(new Uint8Array(buffer));
+		return newBuffer;
+	}
+}

package/src/debugging.ts

@@ -0,0 +1,45 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+export interface CreateLoggerOptions {
+	output?: (...args: any[]) => void;
+	stringify?: (value: unknown) => string;
+	className?: boolean;
+	separator?: string;
+	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();
+}
+
+type LoggableDecoratorContext = Exclude<DecoratorContext, ClassFieldDecoratorContext>;
+
+/**
+ * Create a function that can be used to decorate classes and non-field members.
+ */
+export function createLogDecorator(options: CreateLoggerOptions) {
+	const { output = console.log, separator = '#', returnValue = false, stringify = defaultStringify, className = true } = options;
+
+	return function log<T extends (...args: any[]) => any>(value: T, context: LoggableDecoratorContext): T {
+		if (context.kind == 'class') {
+			return function (...args: any[]) {
+				output(`new ${value.name} (${args.map(stringify).join(', ')})`);
+				return Reflect.construct(value, args);
+			} as T;
+		}
+
+		return function (this: any, ...args: any[]) {
+			const prefix = (className ? this.constructor.name + separator : '') + context.name.toString();
+
+			output(`${prefix}(${args.map(stringify).join(', ')})`);
+
+			const result = value.call(this, ...args);
+
+			if (returnValue) output(' => ' + stringify(result));
+
+			return result;
+		} as T;
+	};
+}

package/src/index.ts

@@ -1,3 +1,6 @@
+// This file should not be added to
+// For better tree shaking, import from whichever file is actually needed
+
 export * from './list.js';
 export * from './misc.js';
 export * from './numbers.js';

package/src/internal/struct.ts

@@ -29,6 +29,7 @@ export const init: typeof Symbol.struct_init = Symbol.struct_init;
 export interface Options {
 	align: number;
 	bigEndian: boolean;
+	isUnion: boolean;
 }
 
 export interface Member {

package/src/misc.ts

@@ -34,3 +34,21 @@ const hexRegex = /^[0-9a-f-.]+$/;
 export function isHex(str: string) {
 	return hexRegex.test(str);
 }
+
+/** Prevent infinite loops */
+export function canary(error: Error = new Error()) {
+	const timeout = setTimeout(() => {
+		throw error;
+	}, 5000);
+
+	return () => clearTimeout(timeout);
+}
+
+/**
+ * A wrapper for throwing things in an expression context.
+ * You will likely want to remove this if you can just use `throw` in expressions.
+ * @see https://github.com/tc39/proposal-throw-expressions
+ */
+export function _throw(e: unknown): never {
+	throw e;
+}

package/src/requests.ts

@@ -0,0 +1,251 @@
+/* Utilities for `fetch` when using range requests. It also allows you to handle errors easier */
+
+import { extendBuffer } from './buffer.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;
+}
+
+type CacheRange = { start: number; end: number };
+
+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. */
+	protected 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;
+
+			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, 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);
+
+			return this;
+		}
+
+		// 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);
+
+		// 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<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 }> {
+	const response = await fetch(input, init).catch((error: Error) => {
+		throw { tag: 'fetch', message: error.message } satisfies RequestError;
+	});
+
+	if (!response.ok) throw { tag: 'status', response } satisfies RequestError;
+
+	const arrayBuffer = await response.arrayBuffer().catch((error: Error) => {
+		throw { tag: 'buffer', response, message: error.message } satisfies RequestError;
+	});
+
+	return { response, data: new Uint8Array(arrayBuffer) };
+}
+
+export interface RequestOptions extends ResourceCacheOptions {
+	/**
+	 * When using range requests,
+	 * a HEAD request must normally be used to determine the full size of the resource.
+	 * This allows that request to be skipped
+	 */
+	size?: number;
+
+	/** The start of the range */
+	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 async function GET(url: string, options: RequestOptions, 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);
+		return data;
+	}
+
+	// Range requests
+
+	if (typeof options.size != 'number') {
+		options.warn?.(url + ': Size not provided, an additional HEAD request is being made');
+
+		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;
+		options.size = size;
+	}
+
+	const { size, start, end } = options;
+	const cache = requestsCache.get(url) ?? new ResourceCache(url, size, options);
+
+	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}` } });
+
+		if (response.status == 206) {
+			cache.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);
+		return data.subarray(start, end);
+	}
+
+	// This ensures we get a single buffer with the entire requested range
+	cache.collect();
+
+	const region = cache.regionAt(start)!;
+	return region.data.subarray(start - region.offset, end - region.offset);
+}

package/src/struct.ts

@@ -45,11 +45,12 @@ export function struct(options: Partial<Options> = {}) {
 				throw new TypeError('Not a valid type: ' + type);
 			}
 			members.set(name, {
-				offset: size,
+				offset: options.isUnion ? 0 : size,
 				type: primitive.isValid(type) ? primitive.normalize(type) : type,
 				length,
 			});
-			size += sizeof(type) * (length || 1);
+			const memberSize = sizeof(type) * (length || 1);
+			size = options.isUnion ? Math.max(size, memberSize) : size + memberSize;
 			size = align(size, options.align || 1);
 		}
 
@@ -90,6 +91,7 @@ export function serialize(instance: unknown): Uint8Array {
 	const buffer = new Uint8Array(sizeof(instance));
 	const view = new DataView(buffer.buffer);
 
+	// for unions we should write members in ascending last modified order, but we don't have that info.
 	for (const [name, { type, length, offset }] of members) {
 		for (let i = 0; i < (length || 1); i++) {
 			const iOff = offset + sizeof(type) * i;

package/src/types.ts

@@ -232,3 +232,13 @@ export type WithRequired<T, K extends keyof T> = T & { [P in K]-?: T[P] };
  * Makes properties with keys assignable to K in T optional
  */
 export type WithOptional<T, K extends keyof T> = Pick<Partial<T>, K> & Omit<T, K>;
+
+/**
+ * Nothing in T
+ */
+export type Never<T> = { [K in keyof T]?: never };
+
+/**
+ * All of the properties in T or none of them
+ */
+export type AllOrNone<T> = T | Never<T>;