es-toolkit 1.52.0-dev.2095 → 1.52.0-dev.2096

package/dist/util/hash/node.mjs

@@ -0,0 +1,493 @@
+import { hash as hash$1 } from "node:crypto";
+//#region src/util/serialize/serializeBigInt.ts
+/**
+* Serializes a bigint into a string with an `n` suffix, like a bigint literal.
+*
+* @param value - The bigint to serialize.
+* @returns The serialized string.
+*
+* @example
+* serializeBigInt(123n); // "123n"
+*/
+function serializeBigInt(value) {
+	return `${value}n`;
+}
+//#endregion
+//#region src/util/serialize/serializeFunction.ts
+/**
+* Serializes a function into a string of the form `name:source`.
+*
+* Native functions have no meaningful source, so they are serialized as
+* `name:[native]`. For other functions, newlines and their surrounding
+* whitespace are collapsed so that formatting differences do not change
+* the output.
+*
+* @param value - The function to serialize.
+* @returns The serialized string.
+*
+* @example
+* function sum(a, b) {
+*   return a + b;
+* }
+* serializeFunction(sum); // "sum:function sum(a, b) {return a + b;}"
+* serializeFunction(Math.max); // "max:[native]"
+*/
+function serializeFunction(value) {
+	const source = Function.prototype.toString.call(value);
+	if (source.endsWith("[native code] }")) return `${value.name}:[native]`;
+	return `${value.name}:${source.replace(/\s*\n\s*/g, "")}`;
+}
+//#endregion
+//#region src/util/serialize/serializeNumber.ts
+/**
+* Serializes a number into a string.
+*
+* `-0` is serialized as `0`, and `NaN` and `Infinity` are serialized
+* as their string representations.
+*
+* @param value - The number to serialize.
+* @returns The serialized string.
+*
+* @example
+* serializeNumber(1); // "1"
+* serializeNumber(-0); // "0"
+* serializeNumber(NaN); // "NaN"
+* serializeNumber(Infinity); // "Infinity"
+*/
+function serializeNumber(value) {
+	return String(value);
+}
+//#endregion
+//#region src/util/serialize/compareValues.ts
+/**
+* Compares two values for sorting `Set` values and `Map` keys.
+*
+* Numbers are compared numerically and strings by code unit. Any other
+* combination is compared by the code unit order of the serialized values.
+*
+* @param a - The first value to compare.
+* @param b - The second value to compare.
+* @param refs - The circular reference context shared with the surrounding serialization.
+* @returns A negative number if `a` sorts before `b`, a positive number if
+*   `a` sorts after `b`, and `0` if they are equal.
+*/
+function compareValues(a, b, refs) {
+	if (typeof a === "number" && typeof b === "number") return a - b;
+	const serializedA = typeof a === "string" && typeof b === "string" ? a : serializeValue(a, refs);
+	const serializedB = typeof a === "string" && typeof b === "string" ? b : serializeValue(b, refs);
+	if (serializedA === serializedB) return 0;
+	return serializedA < serializedB ? -1 : 1;
+}
+//#endregion
+//#region src/util/serialize/serializeString.ts
+/**
+* Serializes a string into a single-quoted string literal.
+*
+* The string is not escaped; the output is intended for hashing and
+* change detection, not for parsing or re-evaluation.
+*
+* @param value - The string to serialize.
+* @returns The serialized string.
+*
+* @example
+* serializeString('abc'); // "'abc'"
+*/
+function serializeString(value) {
+	return `'${value}'`;
+}
+//#endregion
+//#region src/util/serialize/serializePlainObject.ts
+/**
+* Serializes the own enumerable string-keyed properties of an object
+* into a `{'key':value}` string.
+*
+* Keys are sorted by code unit so that the output does not depend on
+* property insertion order, and always quoted so that a key containing
+* `:` or `,` cannot be confused with the surrounding structure. Symbol
+* keys and non-enumerable properties are ignored.
+*
+* @param object - The object to serialize.
+* @param refs - The circular reference context shared with the surrounding serialization.
+* @returns The serialized string.
+*
+* @example
+* serializePlainObject({ b: 2, a: 1 }, new Map()); // "{'a':1,'b':2}"
+*/
+function serializePlainObject(object, refs) {
+	const keys = Object.keys(object).sort();
+	let result = "{";
+	for (let i = 0; i < keys.length; i++) {
+		const key = keys[i];
+		if (i > 0) result += ",";
+		result += `${serializeString(key)}:${serializeValue(object[key], refs)}`;
+	}
+	return result + "}";
+}
+//#endregion
+//#region src/predicate/isArrayBuffer.ts
+/**
+* Checks if a given value is `ArrayBuffer`.
+*
+* This function can also serve as a type predicate in TypeScript, narrowing the type of the argument to `ArrayBuffer`.
+*
+* @param value The value to check if it is a `ArrayBuffer`.
+* @returns Returns `true` if `value` is a `ArrayBuffer`, else `false`.
+*
+* @example
+* const value1 = new ArrayBuffer();
+* const value2 = new Array();
+* const value3 = new Map();
+*
+* console.log(isArrayBuffer(value1)); // true
+* console.log(isArrayBuffer(value2)); // false
+* console.log(isArrayBuffer(value3)); // false
+*/
+function isArrayBuffer(value) {
+	return value instanceof ArrayBuffer;
+}
+//#endregion
+//#region src/predicate/isDate.ts
+/**
+* Checks if `value` is a Date object.
+*
+* @param value The value to check.
+* @returns Returns `true` if `value` is a Date object, `false` otherwise.
+*
+* @example
+* const value1 = new Date();
+* const value2 = '2024-01-01';
+*
+* console.log(isDate(value1)); // true
+* console.log(isDate(value2)); // false
+*/
+function isDate(value) {
+	return value instanceof Date;
+}
+//#endregion
+//#region src/predicate/isError.ts
+/**
+* Checks if `value` is an Error object.
+*
+* @param value The value to check.
+* @returns Returns `true` if `value` is an Error object, `false` otherwise.
+*
+* @example
+* ```typescript
+* console.log(isError(new Error())); // true
+* console.log(isError('Error')); // false
+* console.log(isError({ name: 'Error', message: '' })); // false
+* ```
+*/
+function isError(value) {
+	return value instanceof Error;
+}
+//#endregion
+//#region src/predicate/isMap.ts
+/**
+* Checks if a given value is `Map`.
+*
+* This function can also serve as a type predicate in TypeScript, narrowing the type of the argument to `Map`.
+*
+* @param value The value to check if it is a `Map`.
+* @returns Returns `true` if `value` is a `Map`, else `false`.
+*
+* @example
+* const value1 = new Map();
+* const value2 = new Set();
+* const value3 = new WeakMap();
+*
+* console.log(isMap(value1)); // true
+* console.log(isMap(value2)); // false
+* console.log(isMap(value3)); // false
+*/
+function isMap(value) {
+	return value instanceof Map;
+}
+//#endregion
+//#region src/predicate/isPlainObject.ts
+/**
+* Checks if a given value is a plain object.
+*
+* @param value - The value to check.
+* @returns True if the value is a plain object, otherwise false.
+*
+* @example
+* ```typescript
+* // ✅👇 True
+*
+* isPlainObject({ });                       // ✅
+* isPlainObject({ key: 'value' });          // ✅
+* isPlainObject({ key: new Date() });       // ✅
+* isPlainObject(new Object());              // ✅
+* isPlainObject(Object.create(null));       // ✅
+* isPlainObject({ nested: { key: true} });  // ✅
+* isPlainObject(new Proxy({}, {}));         // ✅
+* isPlainObject({ [Symbol('tag')]: 'A' });  // ✅
+*
+* // ✅👇 (cross-realms, node context, workers, ...)
+* const runInNewContext = await import('node:vm').then(
+*     (mod) => mod.runInNewContext
+* );
+* isPlainObject(runInNewContext('({})'));   // ✅
+*
+* // ❌👇 False
+*
+* class Test { };
+* isPlainObject(new Test())           // ❌
+* isPlainObject(10);                  // ❌
+* isPlainObject(null);                // ❌
+* isPlainObject('hello');             // ❌
+* isPlainObject([]);                  // ❌
+* isPlainObject(new Date());          // ❌
+* isPlainObject(new Uint8Array([1])); // ❌
+* isPlainObject(Buffer.from('ABC'));  // ❌
+* isPlainObject(Promise.resolve({})); // ❌
+* isPlainObject(Object.create({}));   // ❌
+* isPlainObject(new (class Cls {}));  // ❌
+* isPlainObject(globalThis);          // ❌,
+* ```
+*/
+function isPlainObject(value) {
+	if (!value || typeof value !== "object") return false;
+	const proto = Object.getPrototypeOf(value);
+	if (!(proto === null || proto === Object.prototype || Object.getPrototypeOf(proto) === null)) return false;
+	return Object.prototype.toString.call(value) === "[object Object]";
+}
+//#endregion
+//#region src/predicate/isRegExp.ts
+/**
+* Checks if `value` is a RegExp.
+*
+* @param value The value to check.
+* @returns Returns `true` if `value` is a RegExp, `false` otherwise.
+*
+* @example
+* const value1 = /abc/;
+* const value2 = '/abc/';
+*
+* console.log(isRegExp(value1)); // true
+* console.log(isRegExp(value2)); // false
+*/
+function isRegExp(value) {
+	return value instanceof RegExp;
+}
+//#endregion
+//#region src/predicate/isSet.ts
+/**
+* Checks if a given value is `Set`.
+*
+* This function can also serve as a type predicate in TypeScript, narrowing the type of the argument to `Set`.
+*
+* @param value The value to check if it is a `Set`.
+* @returns Returns `true` if `value` is a `Set`, else `false`.
+*
+* @example
+* const value1 = new Set();
+* const value2 = new Map();
+* const value3 = new WeakSet();
+*
+* console.log(isSet(value1)); // true
+* console.log(isSet(value2)); // false
+* console.log(isSet(value3)); // false
+*/
+function isSet(value) {
+	return value instanceof Set;
+}
+//#endregion
+//#region src/predicate/isTypedArray.ts
+/**
+* Checks if a value is a TypedArray.
+* @param x The value to check.
+* @returns Returns true if `x` is a TypedArray, false otherwise.
+*
+* @example
+* const arr = new Uint8Array([1, 2, 3]);
+* isTypedArray(arr); // true
+*
+* const regularArray = [1, 2, 3];
+* isTypedArray(regularArray); // false
+*
+* const buffer = new ArrayBuffer(16);
+* isTypedArray(buffer); // false
+*/
+function isTypedArray(x) {
+	return ArrayBuffer.isView(x) && !(x instanceof DataView);
+}
+//#endregion
+//#region src/util/serialize/serializeObject.ts
+/**
+* Serializes an object, handling circular references and repeated references.
+*
+* The first time an object is visited, it is registered as `#ref{n}` where `n`
+* is the visit order; if the object is reached again while it is still being
+* serialized, the back-reference is emitted instead. Once completed, the
+* serialized string is memoized so that repeated references serialize
+* in constant time.
+*
+* @param value - The object to serialize, or `null`.
+* @param refs - The circular reference context shared across one serialization.
+* @returns The serialized string.
+* @throws {TypeError} If the object cannot be serialized.
+*/
+function serializeObject(value, refs) {
+	if (value === null) return "null";
+	const cached = refs.get(value);
+	if (cached !== void 0) return cached;
+	refs.set(value, `#ref${refs.size}`);
+	const result = serializeObjectImpl(value, refs);
+	refs.set(value, result);
+	return result;
+}
+function serializeObjectImpl(value, refs) {
+	if (Array.isArray(value)) return serializeArray(value, refs);
+	if (isPlainObject(value)) return serializePlainObject(value, refs);
+	if (isDate(value)) return Number.isNaN(value.getTime()) ? "Date(null)" : `Date(${serializeString(value.toISOString())})`;
+	if (isRegExp(value)) return `RegExp(${value.toString()})`;
+	if (isSet(value)) return `Set${serializeArray(Array.from(value).sort((a, b) => compareValues(a, b, refs)), refs)}`;
+	if (isMap(value)) return serializeEntries("Map", value.entries(), refs);
+	if (isTypedArray(value)) {
+		const name = value[Symbol.toStringTag];
+		if (name === "BigInt64Array" || name === "BigUint64Array") return `${name}[${value.join("n,")}${value.length > 0 ? "n" : ""}]`;
+		return `${name}[${value.join(",")}]`;
+	}
+	if (isArrayBuffer(value)) return `ArrayBuffer[${new Uint8Array(value).join(",")}]`;
+	if (isError(value)) return `Error(${value.name}: ${serializeString(value.message)})`;
+	const tag = Object.prototype.toString.call(value).slice(8, -1);
+	if (tag === "Object") return serializeClassInstance(value, refs);
+	if (typeof value.entries === "function") return serializeEntries(tag, value.entries(), refs);
+	throw new TypeError(`Cannot serialize ${tag}`);
+}
+function serializeArray(array, refs) {
+	let result = "[";
+	for (let i = 0; i < array.length; i++) {
+		if (i > 0) result += ",";
+		result += serializeValue(array[i], refs);
+	}
+	return result + "]";
+}
+function serializeEntries(tag, entries, refs) {
+	const sortedEntries = Array.from(entries).sort((a, b) => compareValues(a[0], b[0], refs));
+	let result = `${tag}{`;
+	for (let i = 0; i < sortedEntries.length; i++) {
+		const [key, value] = sortedEntries[i];
+		if (i > 0) result += ",";
+		result += `${serializeValue(key, refs)}:${serializeValue(value, refs)}`;
+	}
+	return result + "}";
+}
+function serializeClassInstance(value, refs) {
+	const constructor = value.constructor;
+	const name = constructor === Object || constructor === void 0 ? "" : constructor.name;
+	if ("toJSON" in value && typeof value.toJSON === "function") {
+		const json = value.toJSON();
+		if (json !== null && typeof json === "object") return name + serializeObject(json, refs);
+		return `${name}(${serializeValue(json, refs)})`;
+	}
+	return name + serializePlainObject(value, refs);
+}
+//#endregion
+//#region src/util/serialize/serializeSymbol.ts
+/**
+* Serializes a symbol into a string using its description.
+*
+* The description is quoted like any other string, so a symbol without a
+* description (`Symbol()`) is distinguishable from one with an empty
+* description (`Symbol('')`). Note that two different symbols with the same
+* description still serialize to the same string, since a symbol's identity
+* cannot be captured in a string.
+*
+* @param value - The symbol to serialize.
+* @returns The serialized string.
+*
+* @example
+* serializeSymbol(Symbol('test')); // "Symbol('test')"
+* serializeSymbol(Symbol()); // "Symbol()"
+*/
+function serializeSymbol(value) {
+	return value.description === void 0 ? "Symbol()" : `Symbol(${serializeString(value.description)})`;
+}
+//#endregion
+//#region src/util/serialize/serialize.ts
+/**
+* Serializes any value into a stable string.
+*
+* Two values with the same structure always serialize to the same string,
+* regardless of key insertion order, so the output is suitable for hashing,
+* cache keys, and change detection. It is not designed for security purposes;
+* intentional collisions can be crafted from user input.
+*
+* Plain object keys, `Map` keys, and `Set` values are sorted, so the output
+* does not depend on insertion order. String keys are always quoted, so a
+* string key never collides with a key of another type. Circular references
+* are serialized as `#ref{n}` back-references, where `n` is the order in
+* which the object was first visited.
+*
+* Objects that cannot be serialized meaningfully, such as `Promise`, `WeakMap`,
+* or `Blob`, throw a `TypeError`.
+*
+* @param value - The value to serialize.
+* @returns The serialized string.
+* @throws {TypeError} If the value contains an object that cannot be serialized.
+*
+* @example
+* serialize({ b: 2, a: 1 }); // "{'a':1,'b':2}"
+* serialize([1, 2n, 'a', { k: 1 }]); // "[1,2n,'a',{'k':1}]"
+* serialize(new Set([3, 1, 2])); // "Set[1,2,3]"
+* serialize(new Date(0)); // "Date('1970-01-01T00:00:00.000Z')"
+*
+* const obj = {};
+* obj.self = obj;
+* serialize(obj); // "{'self':#ref0}"
+*/
+function serialize(value) {
+	return serializeValue(value, /* @__PURE__ */ new Map());
+}
+/**
+* Serializes a value with a shared circular reference context.
+*
+* @param value - The value to serialize.
+* @param refs - Objects that are being serialized or have been serialized,
+*   mapped to their back-reference placeholder or completed serialization.
+* @returns The serialized string.
+*/
+function serializeValue(value, refs) {
+	switch (typeof value) {
+		case "string": return serializeString(value);
+		case "number": return serializeNumber(value);
+		case "bigint": return serializeBigInt(value);
+		case "symbol": return serializeSymbol(value);
+		case "function": return serializeFunction(value);
+		case "object": return serializeObject(value, refs);
+		case "boolean": return String(value);
+		case "undefined": return "undefined";
+	}
+}
+//#endregion
+//#region src/util/hash/node.ts
+/**
+* Hashes any value into a stable 43-character string.
+*
+* The value is serialized with `serialize`, so two values with the same
+* structure always hash to the same string regardless of key insertion
+* order, and then digested with SHA-256 and encoded in Base64URL format.
+*
+* The hash is stable across platforms, but it is not designed for security
+* purposes; intentional collisions can be crafted from user input.
+*
+* This entry uses the native `node:crypto` implementation and requires
+* Node.js 20.12 or later; in browsers, a pure JavaScript implementation
+* with identical output is used instead.
+*
+* @param value - The value to hash.
+* @returns The Base64URL-encoded SHA-256 hash of the serialized value.
+* @throws {TypeError} If the value contains an object that cannot be serialized.
+*
+* @example
+* hash({ b: 2, a: 1 }) === hash({ a: 1, b: 2 }); // true
+* hash([1, 2, 3]); // "phXuruId5Red4IDejDBSyNqQEThAa6ccOMAyhF99VPQ" (43 characters)
+*/
+function hash(value) {
+	return hash$1("sha256", serialize(value), "base64url");
+}
+//#endregion
+export { hash };

package/dist/util/hash/sha256.js

@@ -0,0 +1,158 @@
+//#region src/util/hash/sha256.ts
+const K = new Int32Array([
+	1116352408,
+	1899447441,
+	3049323471,
+	3921009573,
+	961987163,
+	1508970993,
+	2453635748,
+	2870763221,
+	3624381080,
+	310598401,
+	607225278,
+	1426881987,
+	1925078388,
+	2162078206,
+	2614888103,
+	3248222580,
+	3835390401,
+	4022224774,
+	264347078,
+	604807628,
+	770255983,
+	1249150122,
+	1555081692,
+	1996064986,
+	2554220882,
+	2821834349,
+	2952996808,
+	3210313671,
+	3336571891,
+	3584528711,
+	113926993,
+	338241895,
+	666307205,
+	773529912,
+	1294757372,
+	1396182291,
+	1695183700,
+	1986661051,
+	2177026350,
+	2456956037,
+	2730485921,
+	2820302411,
+	3259730800,
+	3345764771,
+	3516065817,
+	3600352804,
+	4094571909,
+	275423344,
+	430227734,
+	506948616,
+	659060556,
+	883997877,
+	958139571,
+	1322822218,
+	1537002063,
+	1747873779,
+	1955562222,
+	2024104815,
+	2227730452,
+	2361852424,
+	2428436474,
+	2756734187,
+	3204031479,
+	3329325298
+]);
+const BASE64_URL_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
+/**
+* Computes the SHA-256 digest of a string and encodes it in Base64URL
+* format without padding.
+*
+* The output is byte-identical to
+* `crypto.hash('sha256', data, 'base64url')` in Node.js.
+*
+* @param data - The string to hash. Encoded as UTF-8 before hashing.
+* @returns The 43-character Base64URL-encoded digest.
+*/
+function sha256(data) {
+	const bytes = new TextEncoder().encode(data);
+	const byteLength = bytes.length;
+	const paddedLength = ((byteLength + 8 >> 6) + 1) * 64;
+	const padded = new Uint8Array(paddedLength);
+	padded.set(bytes);
+	padded[byteLength] = 128;
+	const view = new DataView(padded.buffer);
+	view.setUint32(paddedLength - 8, Math.floor(byteLength / 536870912));
+	view.setUint32(paddedLength - 4, byteLength << 3 >>> 0);
+	let h0 = 1779033703;
+	let h1 = -1150833019;
+	let h2 = 1013904242;
+	let h3 = -1521486534;
+	let h4 = 1359893119;
+	let h5 = -1694144372;
+	let h6 = 528734635;
+	let h7 = 1541459225;
+	const w = new Int32Array(64);
+	for (let offset = 0; offset < paddedLength; offset += 64) {
+		for (let i = 0; i < 16; i++) w[i] = view.getUint32(offset + i * 4) | 0;
+		for (let i = 16; i < 64; i++) {
+			const x = w[i - 15];
+			const y = w[i - 2];
+			const sigma0 = (x >>> 7 | x << 25) ^ (x >>> 18 | x << 14) ^ x >>> 3 | 0;
+			const sigma1 = (y >>> 17 | y << 15) ^ (y >>> 19 | y << 13) ^ y >>> 10 | 0;
+			w[i] = w[i - 16] + sigma0 + w[i - 7] + sigma1 | 0;
+		}
+		let a = h0;
+		let b = h1;
+		let c = h2;
+		let d = h3;
+		let e = h4;
+		let f = h5;
+		let g = h6;
+		let h = h7;
+		for (let i = 0; i < 64; i++) {
+			const bigSigma1 = (e >>> 6 | e << 26) ^ (e >>> 11 | e << 21) ^ (e >>> 25 | e << 7);
+			const ch = e & f ^ ~e & g;
+			const t1 = h + bigSigma1 + ch + K[i] + w[i] | 0;
+			const t2 = ((a >>> 2 | a << 30) ^ (a >>> 13 | a << 19) ^ (a >>> 22 | a << 10)) + (a & b ^ a & c ^ b & c) | 0;
+			h = g;
+			g = f;
+			f = e;
+			e = d + t1 | 0;
+			d = c;
+			c = b;
+			b = a;
+			a = t1 + t2 | 0;
+		}
+		h0 = h0 + a | 0;
+		h1 = h1 + b | 0;
+		h2 = h2 + c | 0;
+		h3 = h3 + d | 0;
+		h4 = h4 + e | 0;
+		h5 = h5 + f | 0;
+		h6 = h6 + g | 0;
+		h7 = h7 + h | 0;
+	}
+	const digest = new Uint8Array(32);
+	const digestView = new DataView(digest.buffer);
+	digestView.setInt32(0, h0);
+	digestView.setInt32(4, h1);
+	digestView.setInt32(8, h2);
+	digestView.setInt32(12, h3);
+	digestView.setInt32(16, h4);
+	digestView.setInt32(20, h5);
+	digestView.setInt32(24, h6);
+	digestView.setInt32(28, h7);
+	let result = "";
+	for (let i = 0; i < 30; i += 3) {
+		const n = digest[i] << 16 | digest[i + 1] << 8 | digest[i + 2];
+		result += BASE64_URL_ALPHABET[n >>> 18 & 63] + BASE64_URL_ALPHABET[n >>> 12 & 63] + BASE64_URL_ALPHABET[n >>> 6 & 63] + BASE64_URL_ALPHABET[n & 63];
+	}
+	const n = digest[30] << 8 | digest[31];
+	result += BASE64_URL_ALPHABET[n >>> 10 & 63] + BASE64_URL_ALPHABET[n >>> 4 & 63] + BASE64_URL_ALPHABET[n << 2 & 63];
+	return result;
+}
+//#endregion
+exports.sha256 = sha256;