@oirnoir/util 0.0.0-stage → 0.0.60

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 oirnoir
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,11 @@
-# Temporary Holding Version
+# @oirnoir/util
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Basic utility functions for primarily private use but published as open source.
+
+This project is developed and maintained exclusively at [a private Forgejo instance](https://git.oirnoir.dev/OIRNOIR/util).
+
+## Supported runtimes
+
+Node.js 26+ (via npm) and Deno (via JSR or npm).
+
+The package is compiled to JavaScript for Node.js consumers; raw TypeScript is served directly to Deno consumers.

package/package.json

@@ -1,6 +1,45 @@
 {
-  "name": "@oirnoir/util",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@oirnoir/util",
+	"version": "0.0.60",
+	"license": "MIT",
+	"description": "Utility methods for Node.js and Deno",
+	"type": "module",
+	"engines": {
+		"node": ">=26"
+	},
+	"exports": {
+		".": {
+			"deno": "./src/index.ts",
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js"
+		}
+	},
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"files": [
+		"dist",
+		"src"
+	],
+	"scripts": {
+		"build": "esbuild src/index.ts --bundle --outfile=dist/index.js --format=esm --platform=node --external:timestring && tsc -p tsconfig.json",
+		"typecheck": "tsc --noEmit -p tsconfig.json",
+		"lint": "biome check . --write && biome lint",
+		"test": "node --test test/*.ts",
+		"publish:npm": "pnpm publish",
+		"publish:jsr": "deno publish --token $JSR_TOKEN"
+	},
+	"dependencies": {
+		"timestring": "^7.0.0"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "2.6.2",
+		"@types/node": "26.6.6",
+		"@types/timestring": "^7.0.0",
+		"esbuild": "0.25.12",
+		"typescript": "5.9.3"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"packageManager": "pnpm@12.16.1"
+}

package/src/Proxy.ts

@@ -0,0 +1,67 @@
+/**
+ * The response object for the request. Includes the
+ * response headers from the proxy service.
+ */
+export interface ProxyResponse extends Response {
+	proxyHeaders: Headers;
+}
+
+/**
+ * Proxy requests through a specific proprietary proxy.
+ */
+export class FetchProxy {
+	proxyEndpoint: string;
+
+	constructor(proxyEndpoint: string) {
+		this.proxyEndpoint = proxyEndpoint;
+		if (this.proxyEndpoint.length == 0)
+			throw new Error("Proxy endpoint must not be a blank string");
+	}
+
+	async fetch(
+		endpoint: string | URL,
+		options: RequestInit = {}
+	): Promise<ProxyResponse> {
+		const configuredOptions: RequestInit = {
+			method: options.method ?? "GET",
+			body: options.body ?? undefined,
+			mode: options.mode ?? undefined,
+			keepalive: options.keepalive ?? undefined,
+			signal: options.signal ?? undefined,
+			credentials: options.credentials ?? undefined,
+			redirect: "manual",
+			headers: {
+				endpoint: typeof endpoint == "string" ? endpoint : endpoint.toString(),
+				/* cspell: disable-next-line */
+				"oproxy-options": JSON.stringify({
+					method: options.method ?? "GET",
+					mode: options.mode ?? undefined,
+					credentials: options.credentials ?? undefined,
+					redirect: options.redirect ?? undefined,
+					referrer: options.referrer ?? undefined,
+					referrerPolicy: options.referrerPolicy ?? undefined,
+					integrity: options.integrity ?? undefined,
+					keepalive: options.keepalive ?? undefined
+				}),
+				headers: options.headers == null ? "{}" : JSON.stringify(options.headers)
+			}
+		};
+		const res = await fetch(this.proxyEndpoint, configuredOptions);
+		const receivedHeaders = res.headers.has("incomingHeaders")
+			? JSON.parse(res.headers?.get("incomingHeaders") ?? "")
+			: null;
+		const receivedStatus = res.headers.has("receivedStatus")
+			? Number(res.headers.get("receivedStatus"))
+			: res.status;
+		Object.defineProperty(res, "status", { get: () => receivedStatus });
+		const proxyHeaders = res.headers;
+		Object.defineProperty(res, "proxyHeaders", { get: () => proxyHeaders });
+		const resWithHeaders: ProxyResponse = res as ProxyResponse;
+		if (receivedHeaders != null) {
+			Object.defineProperty(resWithHeaders, "headers", {
+				get: () => new Headers(receivedHeaders)
+			});
+		}
+		return resWithHeaders;
+	}
+}

package/src/Type.ts

@@ -0,0 +1,137 @@
+/// Copyright (c) 2019 dirigeants, MIT License
+
+/**
+ * The class for deep checking Types
+ */
+export class Type {
+	/**
+	 * The value to generate a deep Type of
+	 */ // biome-ignore lint/suspicious/noExplicitAny: This can truly be any
+	public value: any;
+
+	/**
+	 * The shallow type of this
+	 */
+	public is: string;
+
+	/**
+	 * The parent of this type
+	 */
+	private parent?: Type;
+
+	/**
+	 * The child keys of this Type
+	 */
+	private childKeys: Map<string, Type>;
+
+	/**
+	 * The child values of this Type
+	 */
+	private childValues: Map<string, Type>;
+
+	/**
+	 * @param value - The value to generate a deep Type of
+	 * @param parent - The parent value used in recursion
+	 */ // biome-ignore lint/suspicious/noExplicitAny: This can truly be any
+	constructor(value: any, parent?: Type) {
+		this.value = value;
+		this.is = Type.resolve(value);
+		this.parent = parent;
+		this.childKeys = new Map();
+		this.childValues = new Map();
+	}
+
+	/**
+	 * The type string for the children of this Type
+	 */
+	get childTypes(): string {
+		if (!this.childValues.size) return "";
+		return `<${
+			(this.childKeys.size ? `${Type.list(this.childKeys)}, ` : "") +
+			Type.list(this.childValues)
+		}>`;
+	}
+
+	/**
+	 * The full type string generated.
+	 */
+	toString(): string {
+		this.check();
+		return this.is + this.childTypes;
+	}
+
+	/**
+	 * The subtype to create based on this.value's sub value.
+	 */ // biome-ignore lint/suspicious/noExplicitAny: This can truly be any
+	public addValue(value: any) {
+		const child = new Type(value, this);
+		this.childValues.set(child.is, child);
+	}
+
+	/**
+	 * The subtype to create based on this.value's entries.
+	 */ // biome-ignore lint/suspicious/noExplicitAny: This can truly be any
+	private addEntry([key, value]: [string, any]) {
+		const child = new Type(key, this);
+		this.childKeys.set(child.is, child);
+		this.addValue(value);
+	}
+
+	/**
+	 * Walks the linked list backwards, for checking circulars.
+	 */
+	private *parents() {
+		let current: Type | undefined = this;
+		// biome-ignore lint/suspicious/noAssignInExpressions: <Not sure why, this is how the original was written>
+		while ((current = current.parent)) yield current;
+	}
+
+	/**
+	 * Get the deep type name that defines the input.
+	 */
+	check() {
+		if (Object.isFrozen(this)) return;
+		if (typeof this.value === "object" && this.isCircular())
+			this.is = `[Circular:${this.is}]`;
+		else if (this.value instanceof Map)
+			for (const entry of this.value) this.addEntry(entry);
+		else if (Array.isArray(this.value) || this.value instanceof Set)
+			for (const value of this.value) this.addValue(value);
+		else if (this.is === "Object") this.is = "any";
+		Object.freeze(this);
+	}
+
+	/**
+	 * Checks if the value of this Type is a circular reference to any parent.
+	 */
+	isCircular(): boolean {
+		for (const parent of this.parents())
+			if (parent.value === this.value) return true;
+		return false;
+	}
+
+	/**
+	 * Resolves the type name that defines the input.
+	 */
+	// biome-ignore lint/suspicious/noExplicitAny: This can truly be any
+	static resolve(value: any): string {
+		const type = typeof value;
+		switch (type) {
+			case "object":
+				return value === null ? "null" : value.constructor?.name || "any";
+			case "function":
+				return `${value.constructor.name}(${value.length}-arity)`;
+			case "undefined":
+				return "void";
+			default:
+				return type;
+		}
+	}
+
+	/**
+	 * Joins the list of child types.
+	 */
+	static list(values: Map<string, Type>): string {
+		return values.has("any") ? "any" : [...values.values()].sort().join(" | ");
+	}
+}

package/src/index.ts

@@ -0,0 +1,369 @@
+import {
+	type ExecException,
+	type ExecOptions,
+	exec,
+	spawn
+} from "node:child_process";
+import { setTimeout } from "node:timers";
+/* cspell: disable-next-line */
+import timeString from "timestring";
+
+export * from "./Proxy.ts";
+export * from "./Type.ts";
+
+/**
+ * Adds commas to a number, for pretty human reading
+ */
+export function commaNumber(num: number): string {
+	// The previous implementation behaved correctly but this one is way cleaner
+	// https://stackoverflow.com/questions/2901102/how-can-i-format-a-number-with-commas-as-thousands-separators
+	return num.toString().replace(/\B(?=(\d{3})+(?!\d))/g, ",");
+}
+
+/**
+ * Represents a parsed user-inputted time.
+ * Returned by parseUserInputtedTime.
+ */
+export class ParsedTime {
+	public readonly intervalMs: number;
+	public readonly timestamp?: number;
+
+	constructor(data: { intervalMs: number; timestamp?: number }) {
+		this.intervalMs = data.intervalMs;
+		this.timestamp = data.timestamp;
+	}
+
+	get intervalSeconds(): number {
+		return Math.trunc(this.intervalMs / 1000);
+	}
+
+	get string(): string {
+		return msToHuman(this.intervalMs);
+	}
+}
+
+/**
+ * Parse user-inputted time. Timestamps can be allowed, optionally.
+ * relativeTime is used to calculate intervals when timestamps are
+ * inputted.
+ */
+export function parseUserInputtedTime(
+	rawTimeInterval: string,
+	allowTimestamps = false,
+	relativeTime: number = Date.now()
+): ParsedTime {
+	const digits = rawTimeInterval.match(/\d/g);
+	if (
+		(rawTimeInterval.endsWith("t") ||
+			(digits != null &&
+				digits.length > 0 &&
+				digits.join("") == rawTimeInterval)) &&
+		allowTimestamps
+	) {
+		let timestampString = rawTimeInterval.match(/\d/g)?.join("");
+		if (
+			timestampString == null ||
+			!isNumeric(timestampString, { allowDecimal: true, allowNegative: true })
+		)
+			timestampString = String(relativeTime);
+		const timestamp =
+			timestampString.length == String(relativeTime).length ||
+			timestampString.length == String(relativeTime).length + 1 ||
+			timestampString.length == String(relativeTime).length - 1
+				? Number(timestampString)
+				: timestampString.length == String(relativeTime).length - 3 ||
+						timestampString.length == String(relativeTime).length - 2 ||
+						timestampString.length == String(relativeTime).length - 4
+					? Number(timestampString) * 1000
+					: Number(timestampString);
+		const timeInterval = timestamp - relativeTime;
+		return new ParsedTime({ intervalMs: timeInterval, timestamp });
+	}
+	let timeInterval: number;
+	try {
+		timeInterval = timeString(rawTimeInterval, "ms");
+	} catch {
+		return { intervalSeconds: 0, intervalMs: 0, string: "" };
+	}
+	return new ParsedTime({ intervalMs: timeInterval });
+}
+
+/**
+ * Convert a total quantity of milliseconds into modulated ms, seconds, minutes, hours, days, weeks, years
+ */
+function explodeMs(ms: number) {
+	return {
+		milliseconds: Math.trunc(ms % 1000),
+		seconds: Math.trunc((ms / 1000) % 60),
+		minutes: Math.trunc((ms / 60000) % 60),
+		hours: Math.trunc((ms / 3600000) % 24),
+		days: Math.trunc((ms / 86400000) % 7),
+		weeks: Math.trunc((ms / 604800000) % 52),
+		years: Math.trunc(ms / 31449600000)
+	};
+}
+
+/**
+ * Converts a quantity of ms to human-readable format
+ */
+export function msToHuman(ms: number, includeMilliseconds = false): string {
+	const { milliseconds, seconds, minutes, hours, days, weeks, years } =
+		explodeMs(ms);
+	const durationComponents: string[] = [];
+	if (years > 0) {
+		durationComponents.push(`${years} year${years == 1 ? "" : "s"}`);
+	}
+	if (weeks > 0) {
+		durationComponents.push(`${weeks} week${weeks == 1 ? "" : "s"}`);
+	}
+	if (days > 0) {
+		durationComponents.push(`${days} day${days == 1 ? "" : "s"}`);
+	}
+	if (hours > 0) {
+		durationComponents.push(`${hours} hour${hours == 1 ? "" : "s"}`);
+	}
+	if (minutes > 0) {
+		durationComponents.push(`${minutes} minute${minutes == 1 ? "" : "s"}`);
+	}
+	if (seconds > 0) {
+		durationComponents.push(`${seconds} second${seconds == 1 ? "" : "s"}`);
+	}
+	if (milliseconds > 0 && includeMilliseconds) {
+		durationComponents.push(
+			`${milliseconds} millisecond${milliseconds == 1 ? "" : "s"}`
+		);
+	}
+	if (durationComponents.length == 0)
+		durationComponents.push(
+			includeMilliseconds ? "no time" : "less than a second"
+		);
+	const durationWords =
+		durationComponents.length >= 3
+			? `${durationComponents.slice(0, -1).join(", ")}, and ${durationComponents.at(-1)}`
+			: durationComponents.join(" and ");
+	return durationWords;
+}
+
+/**
+ * Converts a quantity of ms to a shorter human-readable format
+ */
+export function msToShort(ms: number, includeMilliseconds = false): string {
+	const { milliseconds, seconds, minutes, hours, days, weeks, years } =
+		explodeMs(ms);
+	let twoDigitMin = String(minutes);
+	while (twoDigitMin.length < 2) {
+		twoDigitMin = `0${twoDigitMin}`;
+	}
+	let twoDigitSec = String(seconds);
+	while (twoDigitSec.length < 2) {
+		twoDigitSec = `0${twoDigitSec}`;
+	}
+	let threeDigitMs = String(milliseconds);
+	while (threeDigitMs.length < 3) {
+		threeDigitMs = `0${threeDigitMs}`;
+	}
+	const durationComponents: string[] = [];
+	let topFound = false;
+	if (years > 0 || topFound) {
+		topFound = true;
+		durationComponents.push(`${years}y`);
+	}
+	if (weeks > 0 || topFound) {
+		topFound = true;
+		durationComponents.push(`${weeks}w`);
+	}
+	if (days > 0 || topFound) {
+		topFound = true;
+		durationComponents.push(`${days}d `);
+	}
+	if (hours > 0 || topFound) {
+		topFound = true;
+		durationComponents.push(`${hours}:`);
+	}
+	if (minutes > 0 || topFound) {
+		durationComponents.push(`${topFound ? twoDigitMin : minutes}:${twoDigitSec}`);
+		if (includeMilliseconds) durationComponents.push(`.${threeDigitMs}`);
+	} else {
+		durationComponents.push(`${seconds}`);
+		if (includeMilliseconds) durationComponents.push(`.${threeDigitMs}`);
+		durationComponents.push("s");
+	}
+	return durationComponents.join("");
+}
+
+/**
+ * Generate a random string of a specific length. Uses Math.random().
+ */
+export function randomString(
+	length: number,
+	alphabet = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789"
+): string {
+	let result = "";
+	let counter = 0;
+	while (counter < length) {
+		result += alphabet.charAt(Math.floor(Math.random() * alphabet.length));
+		counter += 1;
+	}
+	return result;
+}
+
+/**
+ * Check if a string is entirely numeric.
+ */
+export function isNumeric(
+	str: string | undefined | null,
+	options: { allowNegative: boolean; allowDecimal: boolean }
+): boolean {
+	if (str == null) return false;
+	let regex: RegExp;
+	if (options.allowNegative) {
+		if (options.allowDecimal) {
+			regex = /^-?\d+(\.\d+)?$/;
+		} else {
+			regex = /^-?\d+$/;
+		}
+	} else {
+		if (options.allowDecimal) {
+			regex = /^\d+(\.\d+)?$/;
+		} else {
+			regex = /^\d+$/;
+		}
+	}
+	return regex.test(str);
+}
+
+/**
+ * Returns a promise that resolves after a given number of milliseconds.
+ */
+export function sleep(ms: number): Promise<void> {
+	return new Promise((resolve) => {
+		setTimeout(resolve, ms);
+	});
+}
+
+/**
+ * Asynchronously execute a command-line command.
+ */
+export function execAsync(
+	command: string,
+	settings?: ExecOptions
+): Promise<{
+	error: ExecException | null;
+	stdout: string;
+	stderr: string;
+}> {
+	return new Promise((resolve) => {
+		exec(command, settings, (error, stdout, stderr) => {
+			resolve({ error, stdout: stdout as string, stderr: stderr as string });
+		});
+	});
+}
+
+/**
+ * A lightweight curl wrapper. Input arguments
+ * for curl, and a web API Response object is returned.
+ */
+export async function curl(...curlArgs: string[]): Promise<Response> {
+	const child = spawn("curl", ["-isSL", ...curlArgs]);
+
+	const stdoutChunks: Buffer[] = [];
+	const stderrChunks: Buffer[] = [];
+
+	child.stdout.on("data", (chunk: Buffer) => stdoutChunks.push(chunk));
+	child.stderr.on("data", (chunk: Buffer) => stderrChunks.push(chunk));
+
+	const code = await new Promise<number>((resolve, reject) => {
+		child.on("close", (c) => resolve(c ?? -1));
+		child.on("error", reject);
+	});
+
+	const stdoutText = new TextDecoder().decode(Buffer.concat(stdoutChunks));
+	const stderrText = new TextDecoder().decode(Buffer.concat(stderrChunks));
+
+	if (code !== 0) {
+		console.error("Curl stderr:");
+		console.error(stderrText);
+		throw new Error(`Curl exited with code ${code}`);
+	}
+
+	return parseRawHttpResponse(stdoutText);
+}
+
+/**
+ * Parses a raw HTTP response into a fetch Response
+ */
+export function parseRawHttpResponse(raw: string): Response {
+	const [headerPart, ...bodyParts] = raw.split(/\r?\n\r?\n/);
+	const body = bodyParts.join("\n\n");
+
+	const lines = headerPart.split(/\r?\n/);
+	const statusLine = lines.shift();
+	if (statusLine === undefined)
+		throw new Error("Curl HTTP Response Syntax Error: No status line!");
+
+	const [, statusCode, ...statusTextParts] = statusLine.split(" ");
+	const status = Number(statusCode);
+	const statusText = statusTextParts.join(" ");
+
+	const headers = new Headers();
+	for (const line of lines) {
+		const idx = line.indexOf(":");
+		if (idx !== -1) {
+			headers.append(line.slice(0, idx).trim(), line.slice(idx + 1).trim());
+		}
+	}
+
+	const isNullBodyStatus =
+		status === 101 || status === 204 || status === 205 || status === 304;
+
+	return new Response(isNullBodyStatus ? null : body, {
+		status,
+		statusText,
+		headers
+	});
+}
+
+class PrivateTimeoutIndicator {}
+
+/**
+ * Await a promise, but reject if the promise takes too long.
+ */
+export async function withTimeout<T>(
+	promise: Promise<T>,
+	timeout: number
+): Promise<T> {
+	const promises = [
+		promise,
+		sleep(timeout).then(() => new PrivateTimeoutIndicator())
+	];
+	const result = await Promise.race(promises);
+	if (result instanceof PrivateTimeoutIndicator) {
+		throw new Error("Timeout reached when awaiting promise resolution!");
+	}
+	return result;
+}
+
+/**
+ * Similar to `Array#splice()` but for two Uint8Arrays.
+ * Replaces `deleteCount` bytes of `array` starting from `start`
+ * with the contents of `toInsert`. If `toInsert` is not given, just deletes `deleteCount`.
+ */
+export function spliceUint8Array(
+	array: Uint8Array,
+	start: number,
+	deleteCount: number,
+	toInsert?: Uint8Array
+): Uint8Array<ArrayBuffer> {
+	const s = Math.max(0, Math.min(Math.trunc(start) || 0, array.length));
+	const dc = Math.max(
+		0,
+		Math.min(Math.trunc(deleteCount) || 0, array.length - s)
+	);
+	const output = new Uint8Array(array.length - dc + (toInsert?.length ?? 0));
+	const before = array.slice(0, s);
+	const after = array.slice(s + dc, array.length);
+	output.set(before);
+	if (toInsert != undefined) output.set(toInsert, s);
+	output.set(after, s + (toInsert?.length ?? 0));
+	return output;
+}