@demicodes/utils 0.1.0 → 0.2.1

package/dist/index.d.mts

@@ -34,6 +34,8 @@ declare function throwIfAborted(signal: AbortSignal): void;
  * promise is not canceled; this only stops the caller from awaiting it past the abort.
  */
 declare function abortable<T>(promise: Promise<T>, signal: AbortSignal): Promise<T>;
+/** Returns the string `code` of an errno-style error (`ENOENT`, `EEXIST`, …), or null. */
+declare function errorCode(error: unknown): string | null;
 /** Reports whether an unknown thrown value is a file-not-found error (ENOENT). */
 declare function isFileNotFoundError(error: unknown): boolean;
 //#endregion
@@ -68,10 +70,20 @@ declare function encodeUtf8(text: string): Uint8Array;
 declare function decodeUtf8(data: Uint8Array): string;
 /** Returns the UTF-8 byte length of a string. */
 declare function utf8Bytes(text: string): number;
+/** Packs a latin1 byte-string (each char = one byte, 0–255) into bytes. */
+declare function encodeLatin1(text: string): Uint8Array;
+/** Unpacks bytes into a latin1 byte-string (each char = one byte). */
+declare function decodeLatin1(bytes: Uint8Array): string;
+/** Strictly decodes UTF-8; returns null when the bytes are not valid UTF-8. */
+declare function decodeUtf8Strict(bytes: Uint8Array): string | null;
 /** Slices a string by UTF-8 byte offsets, returning the decoded substring. */
 declare function utf8Slice(text: string, start: number, end: number): string;
 /** Concatenates byte chunks into a single `Uint8Array`. */
 declare function concatBytes(chunks: readonly Uint8Array[]): Uint8Array;
+/** Encodes bytes as standard base64 (platform-neutral, no Node or DOM globals). */
+declare function bytesToBase64(bytes: Uint8Array): string;
+/** Decodes standard base64 to bytes, throwing on malformed payloads. */
+declare function base64ToBytes(base64: string): Uint8Array;
 //#endregion
 //#region src/strings.d.ts
 /** Clamps a number into the inclusive `[min, max]` range. */
@@ -96,6 +108,14 @@ declare function parseJsonObject(value: string): Record<string, unknown> | null;
  * "[Circular]". Returns undefined when the top-level value has no JSON form.
  */
 declare function safeJsonStringify(value: unknown): string | undefined;
+/**
+ * JSON.stringify that round-trips values plain JSON cannot: `Uint8Array` is
+ * encoded as a `__demiUint8Array`-marked base64 object and `bigint` as a
+ * `__demiBigInt`-marked string. Decode with `parsePortableJson`.
+ */
+declare function stringifyPortableJson(value: unknown, space?: number): string;
+/** Parses JSON produced by `stringifyPortableJson`, reviving marked `Uint8Array` and `bigint` values. */
+declare function parsePortableJson<T>(text: string): T;
 //#endregion
 //#region src/paths.d.ts
 /**
@@ -113,4 +133,4 @@ declare function isAbsolutePath(path: string): boolean;
 /** Generates a random UUID. */
 declare function createId(): string;
 //#endregion
-export { AbortError, Deferred, abortable, asError, asRecord, asString, clamp, concatBytes, createId, decodeUtf8, deferred, delay, dirnamePath, encodeUtf8, errorMessage, isAbortError, isAbsolutePath, isFileNotFoundError, isRecord, nonEmptyString, noop, normalizeBaseUrl, normalizePath, numberOrNull, numberOrZero, parseJsonObject, parseJsonOrString, safeJsonStringify, shortHash, stringOrNull, tail, throwIfAborted, truncate, utf8Bytes, utf8Slice, waitFor, withTimeout };
+export { AbortError, Deferred, abortable, asError, asRecord, asString, base64ToBytes, bytesToBase64, clamp, concatBytes, createId, decodeLatin1, decodeUtf8, decodeUtf8Strict, deferred, delay, dirnamePath, encodeLatin1, encodeUtf8, errorCode, errorMessage, isAbortError, isAbsolutePath, isFileNotFoundError, isRecord, nonEmptyString, noop, normalizeBaseUrl, normalizePath, numberOrNull, numberOrZero, parseJsonObject, parseJsonOrString, parsePortableJson, safeJsonStringify, shortHash, stringOrNull, stringifyPortableJson, tail, throwIfAborted, truncate, utf8Bytes, utf8Slice, waitFor, withTimeout };

package/dist/index.mjs

@@ -84,9 +84,15 @@ function abortable(promise, signal) {
 		});
 	});
 }
+/** Returns the string `code` of an errno-style error (`ENOENT`, `EEXIST`, …), or null. */
+function errorCode(error) {
+	if (typeof error !== "object" || error === null) return null;
+	const code = error.code;
+	return typeof code === "string" ? code : null;
+}
 /** Reports whether an unknown thrown value is a file-not-found error (ENOENT). */
 function isFileNotFoundError(error) {
-	return typeof error === "object" && error !== null && error.code === "ENOENT";
+	return errorCode(error) === "ENOENT";
 }
 //#endregion
 //#region src/async.ts
@@ -154,6 +160,27 @@ function decodeUtf8(data) {
 function utf8Bytes(text) {
 	return encoder.encode(text).byteLength;
 }
+/** Packs a latin1 byte-string (each char = one byte, 0–255) into bytes. */
+function encodeLatin1(text) {
+	const out = new Uint8Array(text.length);
+	for (let i = 0; i < text.length; i += 1) out[i] = text.charCodeAt(i) & 255;
+	return out;
+}
+/** Unpacks bytes into a latin1 byte-string (each char = one byte). */
+function decodeLatin1(bytes) {
+	let out = "";
+	const chunk = 32768;
+	for (let i = 0; i < bytes.length; i += chunk) out += String.fromCharCode(...bytes.subarray(i, i + chunk));
+	return out;
+}
+/** Strictly decodes UTF-8; returns null when the bytes are not valid UTF-8. */
+function decodeUtf8Strict(bytes) {
+	try {
+		return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+	} catch {
+		return null;
+	}
+}
 /** Slices a string by UTF-8 byte offsets, returning the decoded substring. */
 function utf8Slice(text, start, end) {
 	if (start <= 0 && end >= utf8Bytes(text)) return text;
@@ -170,6 +197,47 @@ function concatBytes(chunks) {
 	}
 	return combined;
 }
+const BASE64_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+/** Encodes bytes as standard base64 (platform-neutral, no Node or DOM globals). */
+function bytesToBase64(bytes) {
+	let output = "";
+	for (let index = 0; index < bytes.byteLength; index += 3) {
+		const first = bytes[index];
+		const second = bytes[index + 1];
+		const third = bytes[index + 2];
+		output += BASE64_ALPHABET[first >> 2];
+		output += BASE64_ALPHABET[(first & 3) << 4 | (second ?? 0) >> 4];
+		output += second === void 0 ? "=" : BASE64_ALPHABET[(second & 15) << 2 | (third ?? 0) >> 6];
+		output += third === void 0 ? "=" : BASE64_ALPHABET[third & 63];
+	}
+	return output;
+}
+/** Decodes standard base64 to bytes, throwing on malformed payloads. */
+function base64ToBytes(base64) {
+	const clean = base64.replace(/\s+/g, "");
+	if (clean.length === 0) return /* @__PURE__ */ new Uint8Array();
+	if (clean.length % 4 !== 0) throw new Error("Invalid base64 payload length");
+	const padding = clean.endsWith("==") ? 2 : clean.endsWith("=") ? 1 : 0;
+	const bytes = new Uint8Array(clean.length / 4 * 3 - padding);
+	let offset = 0;
+	for (let index = 0; index < clean.length; index += 4) {
+		const first = base64Value(clean[index]);
+		const second = base64Value(clean[index + 1]);
+		const third = clean[index + 2] === "=" ? 0 : base64Value(clean[index + 2]);
+		const fourth = clean[index + 3] === "=" ? 0 : base64Value(clean[index + 3]);
+		const triple = first << 18 | second << 12 | third << 6 | fourth;
+		if (offset < bytes.byteLength) bytes[offset++] = triple >> 16 & 255;
+		if (offset < bytes.byteLength) bytes[offset++] = triple >> 8 & 255;
+		if (offset < bytes.byteLength) bytes[offset++] = triple & 255;
+	}
+	return bytes;
+}
+function base64Value(char) {
+	if (!char || char === "=") throw new Error("Invalid base64 payload");
+	const value = BASE64_ALPHABET.indexOf(char);
+	if (value === -1) throw new Error("Invalid base64 payload");
+	return value;
+}
 //#endregion
 //#region src/strings.ts
 /** Clamps a number into the inclusive `[min, max]` range. */
@@ -240,6 +308,40 @@ function safeJsonStringify(value) {
 		return;
 	}
 }
+const BINARY_MARKER = "__demiUint8Array";
+const BIGINT_MARKER = "__demiBigInt";
+/**
+* JSON.stringify that round-trips values plain JSON cannot: `Uint8Array` is
+* encoded as a `__demiUint8Array`-marked base64 object and `bigint` as a
+* `__demiBigInt`-marked string. Decode with `parsePortableJson`.
+*/
+function stringifyPortableJson(value, space) {
+	return JSON.stringify(value, (_key, nested) => {
+		if (nested instanceof Uint8Array) return {
+			[BINARY_MARKER]: true,
+			base64: bytesToBase64(nested)
+		};
+		if (typeof nested === "bigint") return {
+			[BIGINT_MARKER]: true,
+			value: nested.toString()
+		};
+		return nested;
+	}, space);
+}
+/** Parses JSON produced by `stringifyPortableJson`, reviving marked `Uint8Array` and `bigint` values. */
+function parsePortableJson(text) {
+	return JSON.parse(text, (_key, nested) => {
+		if (isEncodedUint8Array(nested)) return base64ToBytes(nested.base64);
+		if (isEncodedBigInt(nested)) return BigInt(nested.value);
+		return nested;
+	});
+}
+function isEncodedUint8Array(value) {
+	return isRecord(value) && value[BINARY_MARKER] === true && typeof value.base64 === "string";
+}
+function isEncodedBigInt(value) {
+	return isRecord(value) && value[BIGINT_MARKER] === true && typeof value.value === "string";
+}
 //#endregion
 //#region src/paths.ts
 /**
@@ -287,4 +389,4 @@ function createId() {
 	return globalThis.crypto.randomUUID();
 }
 //#endregion
-export { AbortError, abortable, asError, asRecord, asString, clamp, concatBytes, createId, decodeUtf8, deferred, delay, dirnamePath, encodeUtf8, errorMessage, isAbortError, isAbsolutePath, isFileNotFoundError, isRecord, nonEmptyString, noop, normalizeBaseUrl, normalizePath, numberOrNull, numberOrZero, parseJsonObject, parseJsonOrString, safeJsonStringify, shortHash, stringOrNull, tail, throwIfAborted, truncate, utf8Bytes, utf8Slice, waitFor, withTimeout };
+export { AbortError, abortable, asError, asRecord, asString, base64ToBytes, bytesToBase64, clamp, concatBytes, createId, decodeLatin1, decodeUtf8, decodeUtf8Strict, deferred, delay, dirnamePath, encodeLatin1, encodeUtf8, errorCode, errorMessage, isAbortError, isAbsolutePath, isFileNotFoundError, isRecord, nonEmptyString, noop, normalizeBaseUrl, normalizePath, numberOrNull, numberOrZero, parseJsonObject, parseJsonOrString, parsePortableJson, safeJsonStringify, shortHash, stringOrNull, stringifyPortableJson, tail, throwIfAborted, truncate, utf8Bytes, utf8Slice, waitFor, withTimeout };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@demicodes/utils",
   "description": "Shared zero-dependency utilities for Demi (type guards, errors, async, bytes, strings, paths, JSON).",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "private": false,
   "type": "module",
   "main": "./dist/index.mjs",