@orkestrel/database 0.0.2 → 0.0.3

package/dist/src/core/index.d.cts

@@ -6,6 +6,7 @@ import { EmitterInterface } from '@orkestrel/emitter';
 import { FieldPath } from '@orkestrel/contract';
 import { Infer } from '@orkestrel/contract';
 import { JSONSchema } from '@orkestrel/contract';
+import { RandomFunction } from '@orkestrel/contract';
 
 /** An aggregate computed over a numeric column. */
 export declare type AggregateFunction = 'count' | 'sum' | 'average' | 'minimum' | 'maximum';
@@ -837,6 +838,35 @@ export declare function extractKey(row: Row, column: string): Key | undefined;
  */
 export declare function filterRows(rows: readonly Row[], conditions: readonly Condition[]): readonly Row[];
 
+/**
+ * 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
+ * ```
+ */
+export declare function generateUUID(random?: RandomFunction): string;
+
 export declare function globMatch(value: string, pattern: string): boolean;
 
 /**
@@ -1694,6 +1724,12 @@ export declare interface TransactionInterface {
     rollback(): Promise<void>;
 }
 
+/** The number of bytes encoded by an RFC 4122 UUID. */
+export declare const UUID_BYTE_COUNT = 16;
+
+/** The number of distinct values one UUID byte may hold. */
+export declare const UUID_BYTE_RANGE = 256;
+
 /**
  * Match a value against a wildcard pattern in LINEAR time — the shared, ReDoS-SAFE
  * engine behind {@link likeMatch} and {@link globMatch}.

package/dist/src/core/index.d.ts

@@ -6,6 +6,7 @@ import { EmitterInterface } from '@orkestrel/emitter';
 import { FieldPath } from '@orkestrel/contract';
 import { Infer } from '@orkestrel/contract';
 import { JSONSchema } from '@orkestrel/contract';
+import { RandomFunction } from '@orkestrel/contract';
 
 /** An aggregate computed over a numeric column. */
 export declare type AggregateFunction = 'count' | 'sum' | 'average' | 'minimum' | 'maximum';
@@ -837,6 +838,35 @@ export declare function extractKey(row: Row, column: string): Key | undefined;
  */
 export declare function filterRows(rows: readonly Row[], conditions: readonly Condition[]): readonly Row[];
 
+/**
+ * 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
+ * ```
+ */
+export declare function generateUUID(random?: RandomFunction): string;
+
 export declare function globMatch(value: string, pattern: string): boolean;
 
 /**
@@ -1694,6 +1724,12 @@ export declare interface TransactionInterface {
     rollback(): Promise<void>;
 }
 
+/** The number of bytes encoded by an RFC 4122 UUID. */
+export declare const UUID_BYTE_COUNT = 16;
+
+/** The number of distinct values one UUID byte may hold. */
+export declare const UUID_BYTE_RANGE = 256;
+
 /**
  * Match a value against a wildcard pattern in LINEAR time — the shared, ReDoS-SAFE
  * engine behind {@link likeMatch} and {@link globMatch}.

package/dist/src/core/index.js

@@ -23,6 +23,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
 /**
@@ -1311,6 +1315,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
 /**
@@ -2416,6 +2454,6 @@ function createMemoryDriver() {
 	return new MemoryDriver();
 }
 //#endregion
-export { Clause, Cursor, DEFAULT_PRIMARY, Database, DatabaseError, MAX_PATTERN_LENGTH, MemoryDriver, Query, Table, applyCriteria, auditDriver, checkAbort, compareValues, computeAggregate, conformDriver, createDatabase, createMemoryDriver, deepEqual, driverFindings, extractKey, filterRows, globMatch, isDatabaseError, isDriverMeta, likeMatch, matchesCondition, matchesCriteria, migrateRows, planMigration, shapeToColumnType, sortRows, wildcardMatch };
+export { Clause, Cursor, DEFAULT_PRIMARY, Database, DatabaseError, MAX_PATTERN_LENGTH, MemoryDriver, Query, Table, UUID_BYTE_COUNT, UUID_BYTE_RANGE, applyCriteria, auditDriver, checkAbort, compareValues, computeAggregate, conformDriver, createDatabase, createMemoryDriver, deepEqual, driverFindings, extractKey, filterRows, generateUUID, globMatch, isDatabaseError, isDriverMeta, likeMatch, matchesCondition, matchesCriteria, migrateRows, planMigration, shapeToColumnType, sortRows, wildcardMatch };
 
 //# sourceMappingURL=index.js.map