@orkestrel/database 0.0.2 → 0.0.3

package/dist/src/core/index.cjs

@@ -24,6 +24,10 @@ var DEFAULT_PRIMARY = "id";
 * `VALIDATION` {@link DatabaseError}; the cap is generous for any legitimate search.
 */
 var MAX_PATTERN_LENGTH = 1024;
+/** The number of bytes encoded by an RFC 4122 UUID. */
+var UUID_BYTE_COUNT = 16;
+/** The number of distinct values one UUID byte may hold. */
+var UUID_BYTE_RANGE = 256;
 //#endregion
 //#region src/core/errors.ts
 /**
@@ -1312,6 +1316,40 @@ async function auditDriver(factory) {
 	for await (const finding of driverFindings(factory)) findings.push(finding);
 	return findings;
 }
+/**
+* Generate an RFC 4122 version 4 UUID from a number source — no host crypto global.
+*
+* @remarks
+* Draws exactly {@link UUID_BYTE_COUNT} values from `random`, one per byte, then
+* forces the version (`4`) and variant (`10xx`) bits. The default source is
+* `Math.random` — a pure-ECMAScript intrinsic, so generation works on every host;
+* pass a seeded source (`seededRandom` from `@orkestrel/contract`) and reuse it
+* across calls for reproducible sequences in tests and fixtures — production
+* identifiers should keep the default source, whose engine entropy is far larger
+* than a 32-bit seed. Each byte is floored and masked, so a source straying
+* outside `[0, 1)` (negative, `>= 1`, `NaN`, `Infinity`) can never yield a
+* malformed UUID. Suitable as a collision-resistant record identifier — not a
+* cryptographic token; never use one as a secret.
+*
+* @param random - A number source returning values in the half-open range `[0, 1)` (defaults to `Math.random`)
+* @returns A lowercase RFC 4122 version 4 UUID
+*
+* @example
+* ```ts
+* import { generateUUID } from '@orkestrel/database'
+* import { seededRandom } from '@orkestrel/contract'
+*
+* generateUUID() // e.g. '9b2f7c1e-3d4a-4f6b-8e2d-5a1c0b9f8e7d'
+* generateUUID(seededRandom(42)) // the same UUID on every run
+* ```
+*/
+function generateUUID(random = Math.random) {
+	const bytes = Array.from({ length: 16 }, () => Math.floor(random() * 256) & 255);
+	bytes[6] = bytes[6] & 15 | 64;
+	bytes[8] = bytes[8] & 63 | 128;
+	const hex = bytes.map((byte) => byte.toString(16).padStart(2, "0"));
+	return `${hex.slice(0, 4).join("")}-${hex.slice(4, 6).join("")}-${hex.slice(6, 8).join("")}-${hex.slice(8, 10).join("")}-${hex.slice(10).join("")}`;
+}
 //#endregion
 //#region src/core/Cursor.ts
 /**
@@ -2426,6 +2464,8 @@ exports.MAX_PATTERN_LENGTH = MAX_PATTERN_LENGTH;
 exports.MemoryDriver = MemoryDriver;
 exports.Query = Query;
 exports.Table = Table;
+exports.UUID_BYTE_COUNT = UUID_BYTE_COUNT;
+exports.UUID_BYTE_RANGE = UUID_BYTE_RANGE;
 exports.applyCriteria = applyCriteria;
 exports.auditDriver = auditDriver;
 exports.checkAbort = checkAbort;
@@ -2438,6 +2478,7 @@ exports.deepEqual = deepEqual;
 exports.driverFindings = driverFindings;
 exports.extractKey = extractKey;
 exports.filterRows = filterRows;
+exports.generateUUID = generateUUID;
 exports.globMatch = globMatch;
 exports.isDatabaseError = isDatabaseError;
 exports.isDriverMeta = isDriverMeta;