quidproquo-core 0.1.0 → 0.1.2

package/lib/esm/actions/ai/AiMessage.d.ts

@@ -2,12 +2,20 @@ export interface AiTextPart {
     type: 'text';
     text: string;
 }
-export interface AiFilePart {
+export interface AiFileUrlPart {
     type: 'file';
     url: string;
     mediaType: string;
     filename?: string;
 }
+export interface AiFileDrivePart {
+    type: 'file';
+    drive: string;
+    filepath: string;
+    mediaType: string;
+    filename?: string;
+}
+export type AiFilePart = AiFileUrlPart | AiFileDrivePart;
 export interface AiToolCallPart {
     type: 'tool-call';
     toolCallId: string;

package/lib/esm/actions/ai/AiPromptActionRequester.d.ts

@@ -1,9 +1,11 @@
 import { AiMessage } from './AiMessage';
 import { AiModel } from './AiModel';
 import { AiPromptActionRequester } from './AiPromptActionTypes';
+import { AiReasoningConfig } from './AiReasoningConfig';
 export interface AskAiPromptOptions {
     system?: string;
     aiName?: string;
     messages?: AiMessage[];
+    reasoning?: AiReasoningConfig;
 }
 export declare function askAiPrompt(model: AiModel, prompt: string, options?: AskAiPromptOptions): AiPromptActionRequester;

package/lib/esm/actions/ai/AiPromptActionRequester.js

@@ -8,6 +8,7 @@ export function* askAiPrompt(model, prompt, options) {
             messages: options?.messages,
             system: options?.system,
             aiName: options?.aiName,
+            reasoning: options?.reasoning,
         },
     };
 }

package/lib/esm/actions/ai/AiPromptActionTypes.d.ts

@@ -2,12 +2,14 @@ import { Action, ActionProcessor, ActionRequester } from '../../types/Action';
 import { AiActionType } from './AiActionType';
 import { AiMessage } from './AiMessage';
 import { AiModel } from './AiModel';
+import { AiReasoningConfig } from './AiReasoningConfig';
 export interface AiPromptActionPayload {
     model: AiModel;
     prompt: string;
     messages?: AiMessage[];
     system?: string;
     aiName?: string;
+    reasoning?: AiReasoningConfig;
 }
 export interface AiPromptActionResult {
     text: string;

package/lib/esm/actions/ai/AiPromptStreamActionRequester.d.ts

@@ -1,9 +1,11 @@
 import { AiMessage } from './AiMessage';
 import { AiModel } from './AiModel';
 import { AiPromptStreamActionRequester } from './AiPromptStreamActionTypes';
+import { AiReasoningConfig } from './AiReasoningConfig';
 export interface AskAiPromptStreamOptions {
     system?: string;
     aiName?: string;
     messages?: AiMessage[];
+    reasoning?: AiReasoningConfig;
 }
 export declare function askAiPromptStream(model: AiModel, prompt: string, options?: AskAiPromptStreamOptions): AiPromptStreamActionRequester;

package/lib/esm/actions/ai/AiPromptStreamActionRequester.js

@@ -8,6 +8,7 @@ export function* askAiPromptStream(model, prompt, options) {
             messages: options?.messages,
             system: options?.system,
             aiName: options?.aiName,
+            reasoning: options?.reasoning,
         },
     };
 }

package/lib/esm/actions/ai/AiPromptStreamActionTypes.d.ts

@@ -3,6 +3,7 @@ import { StreamHandle } from '../../types/StreamRegistry';
 import { AiActionType } from './AiActionType';
 import { AiMessage } from './AiMessage';
 import { AiModel } from './AiModel';
+import { AiReasoningConfig } from './AiReasoningConfig';
 import { AiStreamPart } from './types';
 export interface AiPromptStreamActionPayload {
     model: AiModel;
@@ -10,6 +11,7 @@ export interface AiPromptStreamActionPayload {
     messages?: AiMessage[];
     system?: string;
     aiName?: string;
+    reasoning?: AiReasoningConfig;
 }
 export interface AiPromptStreamAction extends Action<AiPromptStreamActionPayload> {
     type: AiActionType.PromptStream;

package/lib/esm/actions/ai/AiReasoningConfig.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Enables extended thinking for a prompt. Presence turns reasoning on; the
+ * budget caps how many tokens the model may spend thinking before it answers.
+ * Reasoning progress is surfaced as Reasoning* stream parts.
+ */
+export interface AiReasoningConfig {
+    budgetTokens?: number;
+}

package/lib/esm/actions/ai/AiReasoningConfig.js

@@ -0,0 +1 @@
+export {};

package/lib/esm/actions/ai/index.d.ts

@@ -5,4 +5,5 @@ export * from './AiPromptActionRequester';
 export * from './AiPromptActionTypes';
 export * from './AiPromptStreamActionRequester';
 export * from './AiPromptStreamActionTypes';
+export * from './AiReasoningConfig';
 export * from './types';

package/lib/esm/actions/ai/index.js

@@ -5,4 +5,5 @@ export * from './AiPromptActionRequester';
 export * from './AiPromptActionTypes';
 export * from './AiPromptStreamActionRequester';
 export * from './AiPromptStreamActionTypes';
+export * from './AiReasoningConfig';
 export * from './types';

package/lib/esm/actions/date/DateNowActionTypes.d.ts

@@ -1,8 +1,9 @@
 import { Action, ActionProcessor, ActionRequester } from '../../types/Action';
+import { QpqIsoDateTime } from '../../types/QpqIsoDateTime';
 import { DateActionType } from './DateActionType';
 export type DateNowActionPayload = undefined;
 export interface DateNowAction extends Action<DateNowActionPayload> {
     type: DateActionType.Now;
 }
-export type DateNowActionProcessor = ActionProcessor<DateNowAction, string>;
-export type DateNowActionRequester = ActionRequester<DateNowAction, string>;
+export type DateNowActionProcessor = ActionProcessor<DateNowAction, QpqIsoDateTime>;
+export type DateNowActionRequester = ActionRequester<DateNowAction, QpqIsoDateTime>;

package/lib/esm/actions/file/index.d.ts

@@ -5,8 +5,8 @@ export * from './FileExistsActionRequester';
 export * from './FileExistsActionTypes';
 export * from './FileGenerateTemporarySecureUrlActionRequester';
 export * from './FileGenerateTemporarySecureUrlActionTypes';
-export * from "./FileGenerateTemporaryUploadSecureUrlActionRequester";
-export * from "./FileGenerateTemporaryUploadSecureUrlActionTypes";
+export * from './FileGenerateTemporaryUploadSecureUrlActionRequester';
+export * from './FileGenerateTemporaryUploadSecureUrlActionTypes';
 export * from './FileIsColdStorageActionRequester';
 export * from './FileIsColdStorageActionTypes';
 export * from './FileListDirectoryActionRequester';

package/lib/esm/actions/file/index.js

@@ -5,8 +5,8 @@ export * from './FileExistsActionRequester';
 export * from './FileExistsActionTypes';
 export * from './FileGenerateTemporarySecureUrlActionRequester';
 export * from './FileGenerateTemporarySecureUrlActionTypes';
-export * from "./FileGenerateTemporaryUploadSecureUrlActionRequester";
-export * from "./FileGenerateTemporaryUploadSecureUrlActionTypes";
+export * from './FileGenerateTemporaryUploadSecureUrlActionRequester';
+export * from './FileGenerateTemporaryUploadSecureUrlActionTypes';
 export * from './FileIsColdStorageActionRequester';
 export * from './FileIsColdStorageActionTypes';
 export * from './FileListDirectoryActionRequester';

package/lib/esm/actions/keyValueStore/KeyValueStoreUpsertActionRequester.d.ts

@@ -1,6 +1,7 @@
 import { KeyValueStoreUpsertActionRequester, KeyValueStoreUpsertOptions } from './KeyValueStoreUpsertActionTypes';
 export declare const KeyValueStoreUpsertErrorTypeEnum: {
     ResourceNotFound: string;
+    Conflict: string;
     ServiceUnavailable: string;
 };
 export declare function askKeyValueStoreUpsert<KvsItem>(keyValueStoreName: string, item: KvsItem, options?: KeyValueStoreUpsertOptions): KeyValueStoreUpsertActionRequester<KvsItem>;

package/lib/esm/actions/keyValueStore/KeyValueStoreUpsertActionRequester.js

@@ -1,6 +1,13 @@
 import { createErrorEnumForAction } from '../../types';
 import { KeyValueStoreActionType } from './KeyValueStoreActionType';
-export const KeyValueStoreUpsertErrorTypeEnum = createErrorEnumForAction(KeyValueStoreActionType.Upsert, ['ServiceUnavailable', 'ResourceNotFound']);
+export const KeyValueStoreUpsertErrorTypeEnum = createErrorEnumForAction(KeyValueStoreActionType.Upsert, [
+    'ServiceUnavailable',
+    'ResourceNotFound',
+    // A conditional (ifNotExists) write lost to an existing item. Namespaced —
+    // not ErrorTypeEnum.Conflict — so retry logic can target the write race
+    // specifically without also catching domain-level conflicts.
+    'Conflict',
+]);
 export function* askKeyValueStoreUpsert(keyValueStoreName, item, options) {
     return yield {
         type: KeyValueStoreActionType.Upsert,

package/lib/esm/actions/keyValueStore/KeyValueStoreUpsertActionTypes.d.ts

@@ -2,6 +2,7 @@ import { Action, ActionProcessor, ActionRequester } from '../../types/Action';
 import { KeyValueStoreActionType } from './KeyValueStoreActionType';
 export interface KeyValueStoreUpsertOptions {
     ttlInSeconds?: number;
+    ifNotExists?: boolean;
 }
 export interface KeyValueStoreUpsertActionPayload<KvsItem> {
     keyValueStoreName: string;

package/lib/esm/actions/userDirectory/UserDirectoryActionType.d.ts

@@ -1,3 +1,4 @@
+import { QpqIsoDateTime } from '../../types/QpqIsoDateTime';
 import { AuthenticateUserChallenge } from './types';
 export declare enum UserDirectoryActionType {
     CreateUser = "@quidproquo-core/UserDirectory/CreateUser",
@@ -23,7 +24,7 @@ export declare enum UserDirectoryActionType {
 export interface AuthenticationInfo {
     accessToken?: string;
     expirationDurationInSeconds?: number;
-    expiresAt?: string;
+    expiresAt?: QpqIsoDateTime;
     idToken?: string;
     refreshToken?: string;
     tokenType?: string;

package/lib/esm/config/index.d.ts

@@ -1,3 +1,3 @@
 export * from './QPQConfig';
 export * from './settings';
-export * from "./utils";
+export * from './utils';

package/lib/esm/config/index.js

@@ -1,3 +1,3 @@
 export * from './QPQConfig';
 export * from './settings';
-export * from "./utils";
+export * from './utils';

package/lib/esm/config/utils/index.d.ts

@@ -1,2 +1,2 @@
-export * from "./crossModuleUtils";
-export * from "./qpqFunctionRuntimeUtils";
+export * from './crossModuleUtils';
+export * from './qpqFunctionRuntimeUtils';

package/lib/esm/config/utils/index.js

@@ -1,2 +1,2 @@
-export * from "./crossModuleUtils";
-export * from "./qpqFunctionRuntimeUtils";
+export * from './crossModuleUtils';
+export * from './qpqFunctionRuntimeUtils';

package/lib/esm/index.d.ts

@@ -5,7 +5,7 @@ export * from './createImplementationRuntime';
 export * from './logic';
 export * from './logic/actionLogic';
 export * from './proiseify';
-export * from "./qpqCoreUtilsLib";
+export * from './qpqCoreUtilsLib';
 export * from './qpqExecuteLog';
 export * from './runtime';
 export * from './stories';

package/lib/esm/index.js

@@ -5,7 +5,7 @@ export * from './createImplementationRuntime';
 export * from './logic';
 export * from './logic/actionLogic';
 export * from './proiseify';
-export * from "./qpqCoreUtilsLib";
+export * from './qpqCoreUtilsLib';
 export * from './qpqExecuteLog';
 export * from './runtime';
 export * from './stories';

package/lib/esm/proiseify/getSystemExecuteStoryActionProcessor.js

@@ -47,7 +47,15 @@ const getProcessExecuteStory = (qpqConfig) => {
             return actionResultError(ErrorTypeEnum.NotFound, `Unable to dynamically load: [${payload.runtime}]`);
         }
         try {
-            const qpqPromisifyRuntime = [payload, session, actionProcessors, logger, updateSession, dynamicModuleLoader, streamRegistry];
+            const qpqPromisifyRuntime = [
+                payload,
+                session,
+                actionProcessors,
+                logger,
+                updateSession,
+                dynamicModuleLoader,
+                streamRegistry,
+            ];
             const result = await story(...payload.params, getRun(qpqPromisifyRuntime));
             return actionResult(result);
         }

package/lib/esm/qpqCoreUtilsLib.js

@@ -3,5 +3,5 @@ import * as qpqCoreUtilsLib from './qpqCoreUtils';
 // TODO: Cleanup util exports
 export const qpqCoreUtils = {
     ...qpqCoreUtilsLib,
-    ...moreUtils
+    ...moreUtils,
 };

package/lib/esm/runtime/resolveStoryWithLogs.js

@@ -1,19 +1,36 @@
 import { resolveStory } from './resolveStory';
-export async function resolveStoryWithLogs(story, args, qpqConfig, callerSession, getActionProcessors, getTimeNow, logger, runtimeCorrelation, runtimeType, dynamicModuleLoader, qpqFunctionRuntimeInfo, initialTags, streamRegistry) {
-    const logs = [];
-    const oldConsoleLog = console.log;
-    try {
+let activeLogCollectors = [];
+let unpatchedConsoleLog = null;
+const pushLogCollector = (collector) => {
+    if (unpatchedConsoleLog === null) {
+        const original = console.log;
+        unpatchedConsoleLog = original;
         console.log = (...args) => {
-            const logEntry = { t: getTimeNow(), a: args };
-            logs.push(logEntry);
-            return oldConsoleLog(...args);
+            for (const active of activeLogCollectors) {
+                active.logs.push({ t: active.getTimeNow(), a: args });
+            }
+            return original(...args);
         };
+    }
+    activeLogCollectors.push(collector);
+};
+const popLogCollector = (collector) => {
+    activeLogCollectors = activeLogCollectors.filter((active) => active !== collector);
+    if (activeLogCollectors.length === 0 && unpatchedConsoleLog !== null) {
+        console.log = unpatchedConsoleLog;
+        unpatchedConsoleLog = null;
+    }
+};
+export async function resolveStoryWithLogs(story, args, qpqConfig, callerSession, getActionProcessors, getTimeNow, logger, runtimeCorrelation, runtimeType, dynamicModuleLoader, qpqFunctionRuntimeInfo, initialTags, streamRegistry) {
+    const collector = { logs: [], getTimeNow };
+    try {
+        pushLogCollector(collector);
         const storyResult = await resolveStory(story, args, qpqConfig, callerSession, getActionProcessors, getTimeNow, logger, runtimeCorrelation, runtimeType, dynamicModuleLoader, qpqFunctionRuntimeInfo, initialTags, streamRegistry);
-        storyResult.logs = logs;
+        storyResult.logs = collector.logs;
         logger.log(storyResult);
         return storyResult;
     }
     finally {
-        console.log = oldConsoleLog;
+        popLogCollector(collector);
     }
 }

package/lib/esm/stories/askRetry.d.ts

@@ -1,3 +1,7 @@
 import { AskResponse } from '../types';
 import { askCatch } from './system';
-export declare function askRetry<R>(askRunLogic: () => AskResponse<R>, maxRetries: number, timeToWaitMs: number, errorTypeRetryList?: string[]): ReturnType<typeof askCatch<AskResponse<R>>>;
+export type AskRetryOptions = {
+    linearBackoff?: boolean;
+    maxJitterMs?: number;
+};
+export declare function askRetry<R>(askRunLogic: () => AskResponse<R>, maxRetries: number, timeToWaitMs: number, errorTypeRetryList?: string[], options?: AskRetryOptions): ReturnType<typeof askCatch<AskResponse<R>>>;

package/lib/esm/stories/askRetry.js

@@ -1,6 +1,6 @@
-import { askDelay } from '../actions';
+import { askDelay, askNewGuid } from '../actions';
 import { askCatch } from './system';
-export function* askRetry(askRunLogic, maxRetries, timeToWaitMs, errorTypeRetryList) {
+export function* askRetry(askRunLogic, maxRetries, timeToWaitMs, errorTypeRetryList, options) {
     let attempt = 0;
     while (true) {
         const result = yield* askCatch(askRunLogic());
@@ -13,6 +13,11 @@ export function* askRetry(askRunLogic, maxRetries, timeToWaitMs, errorTypeRetryL
                 return result;
             }
         }
-        yield* askDelay(timeToWaitMs);
+        let waitMs = options?.linearBackoff ? timeToWaitMs * attempt : timeToWaitMs;
+        if (options?.maxJitterMs) {
+            const guid = yield* askNewGuid();
+            waitMs += Math.floor((parseInt(guid.slice(0, 2), 16) / 255) * options.maxJitterMs);
+        }
+        yield* askDelay(waitMs);
     }
 }

package/lib/esm/types/QpqIsoDateTime.d.ts

@@ -0,0 +1,23 @@
+export type TYear = `${number}${number}${number}${number}`;
+export type TMonth = `${number}${number}`;
+export type TDay = `${number}${number}`;
+export type THours = `${number}${number}`;
+export type TMinutes = `${number}${number}`;
+export type TSeconds = `${number}${number}`;
+export type TMilliseconds = `${number}${number}${number}`;
+/**
+ * Represent a string like `2021-01-08`
+ */
+export type TDateISODate = `${TYear}-${TMonth}-${TDay}`;
+/**
+ * Represent a string like `14:42:34.678`
+ */
+export type TDateISOTime = `${THours}:${TMinutes}:${TSeconds}.${TMilliseconds}`;
+/**
+ * Represent a string like `2021-01-08T14:42:34.678Z` (format: ISO 8601).
+ *
+ * It is not possible to type more precisely (list every possible values for months, hours etc) as
+ * it would result in a warning from TypeScript:
+ *   "Expression produces a union type that is too complex to represent. ts(2590)
+ */
+export type QpqIsoDateTime = `${TDateISODate}T${TDateISOTime}Z`;

package/lib/esm/types/QpqIsoDateTime.js

@@ -0,0 +1,3 @@
+// Template-literal typing for ISO-8601 timestamps
+// (from https://gist.github.com/MrChocolatine/367fb2a35d02f6175cc8ccb3d3a20054)
+export {};

package/lib/esm/types/index.d.ts

@@ -20,6 +20,7 @@ export * from './Nullable';
 export * from './QPQBinaryData';
 export * from './QpqContextIdentifier';
 export * from './QpqFunctionRuntime';
+export * from './QpqIsoDateTime';
 export * from './QpqLogger';
 export * from './QpqPagedData';
 export * from './QueueEvent';

package/lib/esm/types/index.js

@@ -20,6 +20,7 @@ export * from './Nullable';
 export * from './QPQBinaryData';
 export * from './QpqContextIdentifier';
 export * from './QpqFunctionRuntime';
+export * from './QpqIsoDateTime';
 export * from './QpqLogger';
 export * from './QpqPagedData';
 export * from './QueueEvent';

package/lib/esm/utils/dateTime/getQpqIsoDateTimeFromDate.d.ts

@@ -0,0 +1,2 @@
+import { QpqIsoDateTime } from '../../types/QpqIsoDateTime';
+export declare const getQpqIsoDateTimeFromDate: (date: Date) => QpqIsoDateTime;

package/lib/esm/utils/dateTime/getQpqIsoDateTimeFromDate.js

@@ -0,0 +1 @@
+export const getQpqIsoDateTimeFromDate = (date) => date.toISOString();

package/lib/esm/utils/dateTime/getValidQpqIsoDateTime.d.ts

@@ -0,0 +1,2 @@
+import { QpqIsoDateTime } from '../../types/QpqIsoDateTime';
+export declare const getValidQpqIsoDateTime: (value: string | undefined) => QpqIsoDateTime | undefined;

package/lib/esm/utils/dateTime/getValidQpqIsoDateTime.js

@@ -0,0 +1,2 @@
+const qpqIsoDateTimeRegex = /^\d{4}-[01]\d-[0-3]\dT[0-2]\d:[0-5]\d:[0-5]\d\.\d{3}Z$/;
+export const getValidQpqIsoDateTime = (value) => value && qpqIsoDateTimeRegex.test(value) ? value : undefined;

package/lib/esm/utils/dateTime/index.d.ts

@@ -0,0 +1,2 @@
+export * from './getQpqIsoDateTimeFromDate';
+export * from './getValidQpqIsoDateTime';

package/lib/esm/utils/dateTime/index.js

@@ -0,0 +1,2 @@
+export * from './getQpqIsoDateTimeFromDate';
+export * from './getValidQpqIsoDateTime';

package/lib/esm/utils/hash/index.d.ts

@@ -1 +1,2 @@
 export * from './generateSimpleHash';
+export * from './sha1';

package/lib/esm/utils/hash/index.js

@@ -1 +1,2 @@
 export * from './generateSimpleHash';
+export * from './sha1';

package/lib/esm/utils/hash/sha1.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Computes the SHA-1 digest of the given bytes.
+ *
+ * This is a pure TypeScript implementation (RFC 3174) so it stays synchronous and
+ * works in both Node and browsers without the async Web Crypto API or a Node-only
+ * `crypto` import. SHA-1 is not collision-resistant, so this must never be used for
+ * security purposes - it exists for deterministic identifiers like v5 UUIDs.
+ *
+ * @param {Uint8Array} message - The bytes to hash.
+ * @returns {Uint8Array} The 20-byte SHA-1 digest.
+ */
+export declare function sha1(message: Uint8Array): Uint8Array;

package/lib/esm/utils/hash/sha1.js

@@ -0,0 +1,82 @@
+/**
+ * Computes the SHA-1 digest of the given bytes.
+ *
+ * This is a pure TypeScript implementation (RFC 3174) so it stays synchronous and
+ * works in both Node and browsers without the async Web Crypto API or a Node-only
+ * `crypto` import. SHA-1 is not collision-resistant, so this must never be used for
+ * security purposes - it exists for deterministic identifiers like v5 UUIDs.
+ *
+ * @param {Uint8Array} message - The bytes to hash.
+ * @returns {Uint8Array} The 20-byte SHA-1 digest.
+ */
+export function sha1(message) {
+    // Pad to a multiple of 64 bytes: a 0x80 byte, zeros, then the 64-bit big-endian bit length.
+    const messageLength = message.length;
+    const paddedLength = Math.ceil((messageLength + 1 + 8) / 64) * 64;
+    const padded = new Uint8Array(paddedLength);
+    padded.set(message);
+    padded[messageLength] = 0x80;
+    const view = new DataView(padded.buffer);
+    const bitLength = messageLength * 8;
+    view.setUint32(paddedLength - 8, Math.floor(bitLength / 0x100000000));
+    view.setUint32(paddedLength - 4, bitLength >>> 0);
+    let h0 = 0x67452301;
+    let h1 = 0xefcdab89;
+    let h2 = 0x98badcfe;
+    let h3 = 0x10325476;
+    let h4 = 0xc3d2e1f0;
+    const w = new Uint32Array(80);
+    for (let block = 0; block < paddedLength; block += 64) {
+        for (let t = 0; t < 16; t++) {
+            w[t] = view.getUint32(block + t * 4);
+        }
+        for (let t = 16; t < 80; t++) {
+            const x = w[t - 3] ^ w[t - 8] ^ w[t - 14] ^ w[t - 16];
+            w[t] = (x << 1) | (x >>> 31);
+        }
+        let a = h0;
+        let b = h1;
+        let c = h2;
+        let d = h3;
+        let e = h4;
+        for (let t = 0; t < 80; t++) {
+            let f;
+            let k;
+            if (t < 20) {
+                f = (b & c) | (~b & d);
+                k = 0x5a827999;
+            }
+            else if (t < 40) {
+                f = b ^ c ^ d;
+                k = 0x6ed9eba1;
+            }
+            else if (t < 60) {
+                f = (b & c) | (b & d) | (c & d);
+                k = 0x8f1bbcdc;
+            }
+            else {
+                f = b ^ c ^ d;
+                k = 0xca62c1d6;
+            }
+            const temp = (((a << 5) | (a >>> 27)) + f + e + k + w[t]) >>> 0;
+            e = d;
+            d = c;
+            c = (b << 30) | (b >>> 2);
+            b = a;
+            a = temp;
+        }
+        h0 = (h0 + a) >>> 0;
+        h1 = (h1 + b) >>> 0;
+        h2 = (h2 + c) >>> 0;
+        h3 = (h3 + d) >>> 0;
+        h4 = (h4 + e) >>> 0;
+    }
+    const digest = new Uint8Array(20);
+    const digestView = new DataView(digest.buffer);
+    digestView.setUint32(0, h0);
+    digestView.setUint32(4, h1);
+    digestView.setUint32(8, h2);
+    digestView.setUint32(12, h3);
+    digestView.setUint32(16, h4);
+    return digest;
+}

package/lib/esm/utils/index.d.ts

@@ -1,4 +1,5 @@
 export * from './array';
+export * from './dateTime';
 export * from './functions';
 export * from './hash';
 export * from './logs';

package/lib/esm/utils/index.js

@@ -1,4 +1,5 @@
 export * from './array';
+export * from './dateTime';
 export * from './functions';
 export * from './hash';
 export * from './logs';

package/lib/esm/utils/uuid/generateUuidV5.d.ts

@@ -0,0 +1,20 @@
+export declare enum UuidNamespace {
+    dns = "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
+    url = "6ba7b811-9dad-11d1-80b4-00c04fd430c8",
+    oid = "6ba7b812-9dad-11d1-80b4-00c04fd430c8",
+    x500 = "6ba7b814-9dad-11d1-80b4-00c04fd430c8"
+}
+/**
+ * Generates a deterministic name-based (version 5) UUID - the sister of `generateUuid`.
+ *
+ * Where `generateUuid` mints a random v4 UUID, this derives a UUID from a name and a
+ * namespace UUID per RFC 4122: the same inputs always produce the same UUID, so it is
+ * useful for stable identifiers (e.g. mapping an external key to a UUID). It hashes with
+ * the bundled pure-TypeScript SHA-1 so it stays synchronous and dependency-free in both
+ * Node and browsers.
+ *
+ * @param {string} name - The name to derive the UUID from.
+ * @param {string} namespace - The namespace UUID, e.g. `UuidNamespace.dns` or any UUID of your own.
+ * @returns {string} The derived v5 UUID, e.g. `2ed6657d-e927-568b-95e1-2665a8aea6a2`.
+ */
+export declare function generateUuidV5(name: string, namespace: string): string;

package/lib/esm/utils/uuid/generateUuidV5.js

@@ -0,0 +1,50 @@
+import { sha1 } from '../hash/sha1';
+// The well-known namespace UUIDs from RFC 4122 Appendix C.
+export var UuidNamespace;
+(function (UuidNamespace) {
+    UuidNamespace["dns"] = "6ba7b810-9dad-11d1-80b4-00c04fd430c8";
+    UuidNamespace["url"] = "6ba7b811-9dad-11d1-80b4-00c04fd430c8";
+    UuidNamespace["oid"] = "6ba7b812-9dad-11d1-80b4-00c04fd430c8";
+    UuidNamespace["x500"] = "6ba7b814-9dad-11d1-80b4-00c04fd430c8";
+})(UuidNamespace || (UuidNamespace = {}));
+const uuidFormatRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const uuidToBytes = (uuid) => {
+    const hex = uuid.replace(/-/g, '');
+    const bytes = new Uint8Array(16);
+    for (let i = 0; i < 16; i++) {
+        bytes[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+    }
+    return bytes;
+};
+const bytesToUuid = (bytes) => {
+    const hex = Array.from(bytes, (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, 32)}`;
+};
+/**
+ * Generates a deterministic name-based (version 5) UUID - the sister of `generateUuid`.
+ *
+ * Where `generateUuid` mints a random v4 UUID, this derives a UUID from a name and a
+ * namespace UUID per RFC 4122: the same inputs always produce the same UUID, so it is
+ * useful for stable identifiers (e.g. mapping an external key to a UUID). It hashes with
+ * the bundled pure-TypeScript SHA-1 so it stays synchronous and dependency-free in both
+ * Node and browsers.
+ *
+ * @param {string} name - The name to derive the UUID from.
+ * @param {string} namespace - The namespace UUID, e.g. `UuidNamespace.dns` or any UUID of your own.
+ * @returns {string} The derived v5 UUID, e.g. `2ed6657d-e927-568b-95e1-2665a8aea6a2`.
+ */
+export function generateUuidV5(name, namespace) {
+    if (!uuidFormatRegex.test(namespace)) {
+        throw new Error(`Invalid namespace UUID [${namespace}]`);
+    }
+    const namespaceBytes = uuidToBytes(namespace);
+    const nameBytes = new TextEncoder().encode(name);
+    const input = new Uint8Array(namespaceBytes.length + nameBytes.length);
+    input.set(namespaceBytes);
+    input.set(nameBytes, namespaceBytes.length);
+    const bytes = sha1(input).slice(0, 16);
+    // RFC 4122: the high nibble of byte 6 carries the version, the top bits of byte 8 the variant.
+    bytes[6] = (bytes[6] & 0x0f) | 0x50;
+    bytes[8] = (bytes[8] & 0x3f) | 0x80;
+    return bytesToUuid(bytes);
+}

package/lib/esm/utils/uuid/index.d.ts

@@ -1 +1,2 @@
 export * from './generateUuid';
+export * from './generateUuidV5';