@wener/utils 1.1.56 → 1.1.58

package/lib/web/getRandomValues.js

@@ -7,32 +7,26 @@ function _instanceof(left, right) {
     }
 }
 var _globalThis_crypto_getRandomValues, _globalThis_crypto, _globalThis_msCrypto_getRandomValues, _globalThis_msCrypto;
-// eslint-disable-next-line @typescript-eslint/consistent-type-imports
 import { getNodeCrypto } from "../crypto/getNodeCrypto.js";
 import { getGlobalThis } from "./getGlobalThis.js";
-var globalThis = getGlobalThis();
+var _globalThis = getGlobalThis();
 // chrome 11+, safari 5+, nodejs 17.4+
 // https://developer.mozilla.org/en-US/docs/Web/API/Crypto/getRandomValues
-export var getRandomValues = ((_globalThis_crypto = globalThis.crypto) === null || _globalThis_crypto === void 0 ? void 0 : (_globalThis_crypto_getRandomValues = _globalThis_crypto.getRandomValues) === null || _globalThis_crypto_getRandomValues === void 0 ? void 0 : _globalThis_crypto_getRandomValues.bind(globalThis.crypto)) || ((_globalThis_msCrypto = globalThis.msCrypto) === null || _globalThis_msCrypto === void 0 ? void 0 : (_globalThis_msCrypto_getRandomValues = _globalThis_msCrypto.getRandomValues) === null || _globalThis_msCrypto_getRandomValues === void 0 ? void 0 : _globalThis_msCrypto_getRandomValues.bind(globalThis.msCrypto)) || function () {
-    throw new Error("[getRandomValues]: No secure random number generator available.");
-};
+export var getRandomValues = ((_globalThis_crypto = _globalThis.crypto) === null || _globalThis_crypto === void 0 ? void 0 : (_globalThis_crypto_getRandomValues = _globalThis_crypto.getRandomValues) === null || _globalThis_crypto_getRandomValues === void 0 ? void 0 : _globalThis_crypto_getRandomValues.bind(_globalThis.crypto)) || ((_globalThis_msCrypto = _globalThis.msCrypto) === null || _globalThis_msCrypto === void 0 ? void 0 : (_globalThis_msCrypto_getRandomValues = _globalThis_msCrypto.getRandomValues) === null || _globalThis_msCrypto_getRandomValues === void 0 ? void 0 : _globalThis_msCrypto_getRandomValues.bind(_globalThis.msCrypto)) || _getRandomValues;
 function _getRandomValues(buf) {
     var nodeCrypto = getNodeCrypto();
-    // avoid type error
     var wc = nodeCrypto === null || nodeCrypto === void 0 ? void 0 : nodeCrypto.webcrypto;
     if (wc === null || wc === void 0 ? void 0 : wc.getRandomValues) {
-        var _wc_getRandomValues;
-        getRandomValues = (_wc_getRandomValues = wc.getRandomValues) === null || _wc_getRandomValues === void 0 ? void 0 : _wc_getRandomValues.bind(nodeCrypto === null || nodeCrypto === void 0 ? void 0 : nodeCrypto.webcrypto);
-        return wc.getRandomValues(buf);
+        getRandomValues = wc.getRandomValues.bind(wc);
+        return getRandomValues(buf);
     }
     if (nodeCrypto === null || nodeCrypto === void 0 ? void 0 : nodeCrypto.randomBytes) {
         if (!_instanceof(buf, Uint8Array)) {
             throw new TypeError("expected Uint8Array");
         }
         if (buf.length > 65536) {
-            var e = new Error();
+            var e = new Error("Failed to execute 'getRandomValues' on 'Crypto': The ArrayBufferView's byte length (".concat(buf.length, ") exceeds the number of bytes of entropy available via this API (65536)."));
             e.code = 22;
-            e.message = "Failed to execute 'getRandomValues' on 'Crypto': The ArrayBufferView's byte length (".concat(buf.length, ") exceeds the number of bytes of entropy available via this API (65536).");
             e.name = "QuotaExceededError";
             throw e;
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wener/utils",
-  "version": "1.1.56",
+  "version": "1.1.58",
   "type": "module",
   "description": "Utils for daily use",
   "repository": {
@@ -69,12 +69,12 @@
     "lodash"
   ],
   "devDependencies": {
-    "@sinclair/typebox": "^0.34.41",
+    "@sinclair/typebox": "^0.34.47",
     "@types/ws": "^8.18.1",
     "https-proxy-agent": "^7.0.6",
     "node-fetch": "^3.3.2",
-    "undici": "^7.16.0",
-    "zod": "^4.1.13"
+    "undici": "^7.18.2",
+    "zod": "^4.3.5"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org",

package/src/crypto/randomUUIDv7.test.ts

@@ -0,0 +1,82 @@
+import { describe, expect, test } from 'vitest';
+import { createRandomUUIDv7, isUUIDv7, parseUUIDv7Timestamp, randomUUIDv7 } from './randomUUIDv7';
+
+describe('randomUUIDv7', () => {
+	test('generates valid UUIDv7', () => {
+		const uuid = randomUUIDv7();
+		expect(uuid).toMatch(/^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i);
+	});
+
+	test('generates unique UUIDs', () => {
+		const uuids = new Set<string>();
+		for (let i = 0; i < 1000; i++) {
+			uuids.add(randomUUIDv7());
+		}
+		expect(uuids.size).toBe(1000);
+	});
+
+	test('respects provided timestamp', () => {
+		const ts = 1704067200000; // 2024-01-01 00:00:00 UTC
+		const uuid = randomUUIDv7(ts);
+		const extractedTs = parseUUIDv7Timestamp(uuid);
+		expect(extractedTs).toBe(ts);
+	});
+
+	test('UUIDs are sortable by time', () => {
+		const ts1 = 1704067200000;
+		const ts2 = 1704067201000;
+		const uuid1 = randomUUIDv7(ts1);
+		const uuid2 = randomUUIDv7(ts2);
+		expect(uuid1 < uuid2).toBe(true);
+	});
+});
+
+describe('isUUIDv7', () => {
+	test('returns true for valid UUIDv7', () => {
+		const uuid = randomUUIDv7();
+		expect(isUUIDv7(uuid)).toBe(true);
+	});
+
+	test('returns false for UUIDv4', () => {
+		expect(isUUIDv7('550e8400-e29b-41d4-a716-446655440000')).toBe(false);
+	});
+
+	test('returns false for invalid strings', () => {
+		expect(isUUIDv7('')).toBe(false);
+		expect(isUUIDv7(null)).toBe(false);
+		expect(isUUIDv7(undefined)).toBe(false);
+		expect(isUUIDv7('not-a-uuid')).toBe(false);
+	});
+});
+
+describe('parseUUIDv7Timestamp', () => {
+	test('extracts correct timestamp', () => {
+		const ts = Date.now();
+		const uuid = randomUUIDv7(ts);
+		expect(parseUUIDv7Timestamp(uuid)).toBe(ts);
+	});
+
+	test('throws for invalid UUID format', () => {
+		expect(() => parseUUIDv7Timestamp('invalid')).toThrow('Invalid UUID format');
+	});
+});
+
+describe('createRandomUUIDv7', () => {
+	test('creates generator with custom now function', () => {
+		let currentTime = 1704067200000;
+		const generator = createRandomUUIDv7({ now: () => currentTime });
+
+		const uuid1 = generator();
+		expect(parseUUIDv7Timestamp(uuid1)).toBe(currentTime);
+
+		currentTime = 1704067201000;
+		const uuid2 = generator();
+		expect(parseUUIDv7Timestamp(uuid2)).toBe(currentTime);
+	});
+
+	test('generator accepts explicit timestamp override', () => {
+		const generator = createRandomUUIDv7({ now: () => 1000 });
+		const uuid = generator(2000);
+		expect(parseUUIDv7Timestamp(uuid)).toBe(2000);
+	});
+});

package/src/crypto/randomUUIDv7.ts

@@ -1 +1,80 @@
 // https://github.com/LiosK/uuidv7/blob/main/src/index.ts
+// https://www.rfc-editor.org/rfc/rfc9562.html#name-uuid-version-7
+
+import { getRandomValues } from '../web/getRandomValues';
+
+/**
+ * Generate a UUIDv7 string
+ *
+ * UUIDv7 format (RFC 9562):
+ * - 48 bits: Unix timestamp in milliseconds
+ * - 4 bits: version (7)
+ * - 12 bits: random (rand_a)
+ * - 2 bits: variant (10)
+ * - 62 bits: random (rand_b)
+ *
+ * Format: xxxxxxxx-xxxx-7xxx-yxxx-xxxxxxxxxxxx
+ * where y is 8, 9, a, or b (variant bits)
+ */
+export function randomUUIDv7(timestamp?: number): string {
+	const ts = timestamp ?? Date.now();
+	const bytes = new Uint8Array(16);
+	getRandomValues(bytes);
+
+	// timestamp (48 bits)
+	bytes[0] = (ts / 2 ** 40) & 0xff;
+	bytes[1] = (ts / 2 ** 32) & 0xff;
+	bytes[2] = (ts / 2 ** 24) & 0xff;
+	bytes[3] = (ts / 2 ** 16) & 0xff;
+	bytes[4] = (ts / 2 ** 8) & 0xff;
+	bytes[5] = ts & 0xff;
+
+	// version (4 bits) = 7
+	bytes[6] = (bytes[6] & 0x0f) | 0x70;
+
+	// variant (2 bits) = 10
+	bytes[8] = (bytes[8] & 0x3f) | 0x80;
+
+	return formatUUID(bytes);
+}
+
+function formatUUID(bytes: Uint8Array): string {
+	const hex = Array.from(bytes)
+		.map((b) => b.toString(16).padStart(2, '0'))
+		.join('');
+	return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+
+/**
+ * Extract timestamp from UUIDv7
+ */
+export function parseUUIDv7Timestamp(uuid: string): number {
+	const hex = uuid.replace(/-/g, '');
+	if (hex.length !== 32) {
+		throw new Error('Invalid UUID format');
+	}
+	const tsHex = hex.slice(0, 12);
+	return parseInt(tsHex, 16);
+}
+
+/**
+ * Check if a string is a valid UUIDv7
+ */
+export function isUUIDv7(uuid: string | null | undefined): boolean {
+	if (!uuid) return false;
+	const match = uuid.match(/^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i);
+	return match !== null;
+}
+
+export interface CreateRandomUUIDv7Options {
+	now?: () => number;
+}
+
+/**
+ * Create a UUIDv7 generator with custom options
+ */
+export function createRandomUUIDv7({ now = Date.now }: CreateRandomUUIDv7Options = {}) {
+	return function uuidv7(timestamp?: number): string {
+		return randomUUIDv7(timestamp ?? now());
+	};
+}

package/src/index.ts

@@ -52,7 +52,7 @@ export { parseDate } from './langs/parseDate';
 export { shallowClone } from './langs/shallowClone';
 export { shallowEqual } from './langs/shallowEqual';
 
-export type { MixinFunction, MixinInstance, MixinReturnValue } from './langs/mixin';
+export type { MixinFn } from './langs/mixin';
 
 export { AsyncCloser } from './langs/AsyncCloser';
 export { Closer } from './langs/Closer';
@@ -101,10 +101,17 @@ export { sha1, sha256, sha384, sha512, hmac, type DigestOptions } from './crypto
 export { md5 } from './crypto/md5';
 export { hex } from './crypto/base';
 export { isULID, createULID, ulid, parseULID } from './crypto/ulid';
+export {
+	randomUUIDv7,
+	isUUIDv7,
+	parseUUIDv7Timestamp,
+	createRandomUUIDv7,
+	type CreateRandomUUIDv7Options,
+} from './crypto/randomUUIDv7';
 export { PEM } from './crypto/pem/pem';
 
 // math
-export { createRandom } from './maths/random';
+export { createRandom, resolveRandom, type RNG } from './maths/random';
 export { clamp } from './maths/clamp';
 
 // network

package/src/langs/mixin.test.ts

@@ -3,9 +3,6 @@ import { mixin } from './mixin';
 
 // import type { Constructor } from '#/types';
 type Constructor<T = {}> = new (...args: any[]) => T;
-function Ent<T extends Function>(): (target: T) => void {
-	return () => {};
-}
 
 test('mixin', () => {
 	// @Ent()

package/src/langs/parseBoolean.ts

@@ -2,13 +2,22 @@ export interface ParseBooleanOptions {
 	strict?: boolean;
 }
 
-export function parseBoolean(s: string | boolean | number | null | undefined, options: { strict: true }): boolean | undefined;
-export function parseBoolean(s: string | boolean | number | null | undefined | any, options?: ParseBooleanOptions): boolean;
+export function parseBoolean(
+	s: string | boolean | number | null | undefined,
+	options: { strict: true },
+): boolean | undefined;
+export function parseBoolean(
+	s: string | boolean | number | null | undefined | any,
+	options?: ParseBooleanOptions,
+): boolean;
 /** @deprecated Use `parseBoolean(s, { strict: true })` instead */
 export function parseBoolean(s: string | boolean | number | null | undefined, strict: true): boolean | undefined;
 export function parseBoolean(s: string | boolean | number | null | undefined | any): boolean;
-export function parseBoolean(s?: string | boolean | number | null, options?: boolean | ParseBooleanOptions): boolean | undefined {
-	const strict = typeof options === 'boolean' ? options : options?.strict ?? false;
+export function parseBoolean(
+	s?: string | boolean | number | null,
+	options?: boolean | ParseBooleanOptions,
+): boolean | undefined {
+	const strict = typeof options === 'boolean' ? options : (options?.strict ?? false);
 	if (typeof s === 'boolean') {
 		return s;
 	}

package/src/maths/clamp.test.ts

@@ -3,21 +3,24 @@ import { clamp } from './clamp';
 
 test('clamp', () => {
 	for (const [a, b] of [
+		// 基本用法
 		[[null, 0, 0], 0],
 		[[null, 1, 10], 1],
 		[[undefined, 1, 10], 1],
 		[[undefined, 1, 10, 5], 5],
 		[[2, 1, 10, 5], 2],
 		[[11, 1, 10, 5], 10],
-		[[11, { min: 1, max: 10 }], 10],
-		[[null, { min: 1, max: 10 }], 1],
-		[[null, { min: 1, max: 10, default: 5 }], 5],
-		[[2n, 1, 10, 5], 2n],
-		[[1, 2], 2], //  min
-		[[1, undefined, 0], 0], // max
-		[[], undefined],
-		[[null], undefined],
-	]) {
+		[[0, 1, 10, 5], 1],
+		// 只限制 min
+		[[1, 2, undefined], 2],
+		[[5, 2, undefined], 5],
+		// 只限制 max
+		[[1, undefined, 0], 0],
+		[[5, undefined, 10], 5],
+		// BigInt
+		[[2n, 1n, 10n, 5n], 2n],
+		[[11n, 1n, 10n, 5n], 10n],
+	] as const) {
 		expect(clamp.apply(null, a as any), `${a} -> ${b}`).toBe(b);
 	}
 });

package/src/maths/clamp.ts

@@ -1,22 +1,16 @@
-import { isDefined } from '../langs/isDefined';
-import { isNil } from '../langs/isNil';
-
-// export function clamp<T>(value: T | null | undefined, opts: { min?: T; max?: T; default?: T }): T;
-export function clamp<T>(value: T | null | undefined, min: T, max: T, def?: T): T;
-export function clamp<T>(value: T | null | undefined, ...o: any[]): T {
-	let min: T, max: T, def: T;
-	if (o.length === 1 && o[0] && typeof o[0] === 'object') {
-		({ min, max, default: def = min! } = o[0]);
-	} else {
-		[min, max, def = min!] = o;
+export function clamp<T>(
+	value: T | null | undefined,
+	min: T | null | undefined,
+	max: T | null | undefined,
+	def?: T,
+): T {
+	if (value == null) {
+		return def ?? min!;
 	}
-	if (isNil(value)) {
-		return def;
-	}
-	if (isDefined(min) && value < min) {
+	if (min != null && value < min) {
 		return min;
 	}
-	if (isDefined(max) && value > max) {
+	if (max != null && value > max) {
 		return max;
 	}
 	return value;

package/src/maths/createRandom.test.ts

@@ -1,12 +1,200 @@
-import { expect, test } from 'vitest';
-import { createRandom } from './random';
-
-test('createRandom', () => {
-	let random = createRandom(0);
-	expect(random.random(100)).toBe(47);
-	for (const a of random) {
-		expect(a).toBe(0.557133817113936);
-		break;
-	}
-	expect(random.randomBytes(4)).toEqual(Uint8Array.from([163, 85, 196, 62]));
+import { describe, expect, test } from 'vitest';
+import { createRandom, resolveRandom } from './random';
+
+describe('createRandom', () => {
+	test('deterministic with same seed', () => {
+		const r1 = createRandom(12345);
+		const r2 = createRandom(12345);
+		expect(r1.random()).toBe(r2.random());
+		expect(r1.randomInt(100)).toBe(r2.randomInt(100));
+	});
+
+	test('random() returns [0, 1)', () => {
+		const r = createRandom(0);
+		for (let i = 0; i < 100; i++) {
+			const v = r.random();
+			expect(v).toBeGreaterThanOrEqual(0);
+			expect(v).toBeLessThan(1);
+		}
+	});
+
+	test('random(a) returns [0, a)', () => {
+		const r = createRandom(42);
+		for (let i = 0; i < 100; i++) {
+			const v = r.random(50);
+			expect(v).toBeGreaterThanOrEqual(0);
+			expect(v).toBeLessThan(50);
+		}
+	});
+
+	test('random(a, b) returns [a, b)', () => {
+		const r = createRandom(42);
+		for (let i = 0; i < 100; i++) {
+			const v = r.random(10, 20);
+			expect(v).toBeGreaterThanOrEqual(10);
+			expect(v).toBeLessThan(20);
+		}
+	});
+
+	test('randomInt(max) returns [0, max]', () => {
+		const r = createRandom(42);
+		const results = new Set<number>();
+		for (let i = 0; i < 1000; i++) {
+			const v = r.randomInt(5);
+			expect(v).toBeGreaterThanOrEqual(0);
+			expect(v).toBeLessThanOrEqual(5);
+			expect(Number.isInteger(v)).toBe(true);
+			results.add(v);
+		}
+		// should hit all values 0-5
+		expect(results.size).toBe(6);
+	});
+
+	test('randomInt(min, max) returns [min, max]', () => {
+		const r = createRandom(42);
+		const results = new Set<number>();
+		for (let i = 0; i < 1000; i++) {
+			const v = r.randomInt(10, 15);
+			expect(v).toBeGreaterThanOrEqual(10);
+			expect(v).toBeLessThanOrEqual(15);
+			expect(Number.isInteger(v)).toBe(true);
+			results.add(v);
+		}
+		// should hit all values 10-15
+		expect(results.size).toBe(6);
+	});
+
+	test('shuffle', () => {
+		const r = createRandom(42);
+		const arr = [1, 2, 3, 4, 5];
+		const shuffled = r.shuffle([...arr]);
+		expect(shuffled).toHaveLength(5);
+		expect(shuffled.sort()).toEqual(arr);
+	});
+
+	test('sample', () => {
+		const r = createRandom(42);
+		const arr = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
+		const sampled = r.sample(arr, 3);
+		expect(sampled).toHaveLength(3);
+		// all sampled items should be from original array
+		for (const v of sampled) {
+			expect(arr).toContain(v);
+		}
+		// no duplicates
+		expect(new Set(sampled).size).toBe(3);
+	});
+
+	test('sample with n >= arr.length returns shuffled copy', () => {
+		const r = createRandom(42);
+		const arr = [1, 2, 3];
+		const sampled = r.sample(arr, 5);
+		expect(sampled).toHaveLength(3);
+		expect(sampled.sort()).toEqual(arr);
+	});
+
+	test('pick', () => {
+		const r = createRandom(42);
+		const arr = [1, 2, 3, 4, 5];
+		const picked = r.pick(arr);
+		expect(arr).toContain(picked);
+	});
+
+	test('reset restores initial state', () => {
+		const r = createRandom(42);
+		const first = r.random();
+		r.random();
+		r.random();
+		r.reset();
+		expect(r.random()).toBe(first);
+	});
+
+	test('reset with new seed', () => {
+		const r = createRandom(42);
+		r.reset(100);
+		const r2 = createRandom(100);
+		expect(r.random()).toBe(r2.random());
+	});
+
+	test('reset with string seed', () => {
+		const r = createRandom(42);
+		r.reset('hello');
+		const r2 = createRandom('hello');
+		expect(r.random()).toBe(r2.random());
+	});
+
+	test('seed property', () => {
+		const r = createRandom(12345);
+		expect(r.seed).toBe(12345);
+	});
+
+	test('string seed', () => {
+		const r1 = createRandom('test-seed');
+		const r2 = createRandom('test-seed');
+		expect(r1.random()).toBe(r2.random());
+	});
+
+	test('randomBytes(n) returns Uint8Array of length n', () => {
+		const r = createRandom(42);
+		const bytes = r.randomBytes(16);
+		expect(bytes).toBeInstanceOf(Uint8Array);
+		expect(bytes.length).toBe(16);
+	});
+
+	test('randomBytes fills provided buffer', () => {
+		const r = createRandom(42);
+		const buf = new Uint8Array(8);
+		const result = r.randomBytes(buf);
+		expect(result).toBe(buf);
+		// should not be all zeros
+		expect(buf.some((v) => v !== 0)).toBe(true);
+	});
+
+	test('randomBytes is deterministic', () => {
+		const r1 = createRandom(42);
+		const r2 = createRandom(42);
+		expect(r1.randomBytes(16)).toEqual(r2.randomBytes(16));
+	});
+
+	test('randomBytes handles non-multiple of 4', () => {
+		const r = createRandom(42);
+		const bytes1 = r.randomBytes(1);
+		expect(bytes1.length).toBe(1);
+
+		const r2 = createRandom(42);
+		const bytes5 = r2.randomBytes(5);
+		expect(bytes5.length).toBe(5);
+
+		const r3 = createRandom(42);
+		const bytes7 = r3.randomBytes(7);
+		expect(bytes7.length).toBe(7);
+	});
+
+	test('randomBytes produces values in range 0-255', () => {
+		const r = createRandom(42);
+		const bytes = r.randomBytes(1000);
+		for (const b of bytes) {
+			expect(b).toBeGreaterThanOrEqual(0);
+			expect(b).toBeLessThanOrEqual(255);
+		}
+	});
+});
+
+describe('resolveRandom', () => {
+	test('returns existing RNG', () => {
+		const r = createRandom(42);
+		expect(resolveRandom(r)).toBe(r);
+	});
+
+	test('creates RNG from number seed', () => {
+		const r = resolveRandom(42);
+		const r2 = createRandom(42);
+		expect(r.random()).toBe(r2.random());
+	});
+
+	test('creates RNG from string seed', () => {
+		const r = resolveRandom('test');
+		const r2 = createRandom('test');
+		expect(r.random()).toBe(r2.random());
+	});
 });