utilium 1.2.1 → 1.2.3

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/requests.d.ts

@@ -1,4 +1,4 @@
-export interface ResourceCacheOptions {
+export interface CacheOptions {
     /**
      * If true, use multiple buffers to cache a file.
      * This is useful when working with small parts of large files,
@@ -12,12 +12,59 @@ export interface ResourceCacheOptions {
      * @default 0xfff // 4 KiB
      */
     regionGapThreshold?: number;
+    /**
+     * Whether to only update the cache when changing or deleting resources
+     * @default false
+     */
+    cacheOnly?: boolean;
 }
-type CacheRange = {
+/**
+ * @deprecated Use `CacheOptions`
+ */
+export type ResourceCacheOptions = CacheOptions;
+export type CacheRange = {
     start: number;
     end: number;
 };
-export type RequestError = {
+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;
+}
+/**
+ * @internal
+ */
+export declare const resourcesCache: Map<string, ResourceCache | null>;
+export type Issue = {
     tag: 'status';
     response: Response;
 } | {
@@ -28,7 +75,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 CacheOptions {
+    /** 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.
@@ -39,20 +98,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;
+export declare function getCached(url: string, options: GetOptions): {
+    data?: Uint8Array;
     missing: CacheRange[];
 };
+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,7 +1,10 @@
 /* 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 {
+/**
+ * The cache for a specific resource
+ * @internal
+ */
+export class ResourceCache {
     url;
     size;
     options;
@@ -18,7 +21,7 @@ class ResourceCache {
         options.sparse ??= true;
         if (!options.sparse)
             this.regions.push({ offset: 0, data: new Uint8Array(size), ranges: [] });
-        requestsCache.set(url, this);
+        resourcesCache.set(url, this);
     }
     /** Combines adjacent regions and combines adjacent ranges within a region */
     collect() {
@@ -93,17 +96,19 @@ class ResourceCache {
         }
     }
     /** Add new data to the cache at given specified offset */
-    add(data, start, end = start + data.byteLength) {
-        const region = this.regionAt(start);
+    add(data, offset) {
+        const end = offset + data.byteLength;
+        const region = this.regionAt(offset);
         if (region) {
             region.data = extendBuffer(region.data, end);
-            region.ranges.push({ start, 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: start, ranges: [{ start, end }] };
-        const insertIndex = this.regions.findIndex(region => region.offset > start);
+        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
@@ -114,31 +119,36 @@ class ResourceCache {
         return this;
     }
 }
-const requestsCache = new Map();
+/**
+ * @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);
+        const { data } = await _fetch(url, init);
         new ResourceCache(url, data.byteLength, options).add(data, 0);
         return data;
     }
@@ -152,10 +162,10 @@ 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 cache = resourcesCache.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}` } });
+        const { data, response } = await _fetch(req, { headers: { Range: `bytes=${from}-${to}` } });
         if (response.status == 206) {
             cache.add(data, from);
             continue;
@@ -170,17 +180,25 @@ export async function GET(url, options, init = {}) {
     const region = cache.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 +220,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 ResourceCache(url, options.size ?? data.byteLength, options);
+    }
+    const cache = resourcesCache.get(url);
+    const { offset = 0 } = options;
+    if (!options.cacheOnly)
+        await _fetch(new Request(url, init), { method: 'POST' }, true);
+    cache.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.1",
+	"version": "1.2.3",
 	"description": "Typescript utilities",
 	"funding": {
 		"type": "individual",

package/src/debugging.ts

@@ -1,9 +1,26 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
 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;
 }
 

package/src/requests.ts

@@ -4,7 +4,7 @@ import { extendBuffer } from './buffer.js';
 
 /* eslint-disable @typescript-eslint/only-throw-error */
 
-export interface ResourceCacheOptions {
+export interface CacheOptions {
 	/**
 	 * If true, use multiple buffers to cache a file.
 	 * This is useful when working with small parts of large files,
@@ -19,11 +19,22 @@ export interface ResourceCacheOptions {
 	 * @default 0xfff // 4 KiB
 	 */
 	regionGapThreshold?: number;
+
+	/**
+	 * Whether to only update the cache when changing or deleting resources
+	 * @default false
+	 */
+	cacheOnly?: boolean;
 }
 
-type CacheRange = { start: number; end: number };
+/**
+ * @deprecated Use `CacheOptions`
+ */
+export type ResourceCacheOptions = CacheOptions;
+
+export type CacheRange = { start: number; end: number };
 
-interface CacheRegion {
+export interface CacheRegion {
 	/** The region's offset from the start of the resource */
 	offset: number;
 
@@ -34,8 +45,11 @@ interface CacheRegion {
 	data: Uint8Array;
 }
 
-/** The cache for a specific resource */
-class ResourceCache {
+/**
+ * The cache for a specific resource
+ * @internal
+ */
+export class ResourceCache {
 	/** Regions used to reduce unneeded allocations. Think of sparse arrays. */
 	public readonly regions: CacheRegion[] = [];
 
@@ -44,12 +58,12 @@ class ResourceCache {
 		public readonly url: string,
 		/** The full size of the resource */
 		public readonly size: number,
-		protected readonly options: ResourceCacheOptions
+		protected readonly options: CacheOptions
 	) {
 		options.sparse ??= true;
 		if (!options.sparse) this.regions.push({ offset: 0, data: new Uint8Array(size), ranges: [] });
 
-		requestsCache.set(url, this);
+		resourcesCache.set(url, this);
 	}
 
 	/** Combines adjacent regions and combines adjacent ranges within a region */
@@ -133,20 +147,22 @@ class ResourceCache {
 	}
 
 	/** 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);
+	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.ranges.push({ start, 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: start, ranges: [{ start, end }] };
-		const insertIndex = this.regions.findIndex(region => region.offset > start);
+		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) {
@@ -159,29 +175,57 @@ class ResourceCache {
 	}
 }
 
-const requestsCache = new Map<string, ResourceCache | null>();
+/**
+ * @internal
+ */
+export const resourcesCache = new Map<string, ResourceCache | null>();
+
+export type Issue = { tag: 'status'; response: Response } | { tag: 'buffer'; response: Response; message: string } | { tag: 'fetch' | 'size'; message: string } | Error;
+
+/**
+ * @deprecated Use `Issue`
+ */
+export type RequestError = Issue;
 
-export type RequestError = { tag: 'status'; response: Response } | { tag: 'buffer'; response: Response; message: string } | { tag: 'fetch' | 'size'; message: string } | Error;
+interface Fetched<TBodyOptional extends boolean> {
+	response: Response;
+	data: false extends TBodyOptional ? Uint8Array : Uint8Array | undefined;
+}
 
 /**
  * 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 CacheOptions {
+	/** 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,21 +238,18 @@ 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);
+		const { data } = await _fetch(url, init);
 		new ResourceCache(url, data.byteLength, options).add(data, 0);
 		return data;
 	}
@@ -220,17 +261,17 @@ 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 cache = resourcesCache.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}` } });
+		const { data, response } = await _fetch(req, { headers: { Range: `bytes=${from}-${to}` } });
 
 		if (response.status == 206) {
 			cache.add(data, from);
@@ -250,17 +291,26 @@ export async function GET(url: string, options: RequestOptions, init: RequestIni
 	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: CacheRange[] } {
+	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 +335,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 ResourceCache(url, options.size ?? data.byteLength, options);
+	}
+
+	const cache = resourcesCache.get(url)!;
+
+	const { offset = 0 } = options;
+
+	if (!options.cacheOnly) await _fetch(new Request(url, init), { method: 'POST' }, true);
+
+	cache.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);
+}