bunqueue-client 0.1.9 → 0.2.1

package/dist/types/src/infrastructure/persistence/statements.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Prepared SQLite statements
+ * Pre-compiled SQL for better performance
+ */
+import type { Database } from "../../../sdk/typescript/src/canonical-transport/bun-sqlite-types.js";
+/** Statement names */
+export type StatementName = 'insertJob' | 'updateJobState' | 'completeJob' | 'updateJobProgress' | 'deleteJob' | 'deleteJobResult' | 'getJob' | 'insertResult' | 'getResult' | 'insertDlq' | 'loadDlq' | 'deleteDlqEntry' | 'deleteDlqEntryForQueue' | 'clearDlqQueue' | 'deleteDependencyCompletionForAdmission' | 'deleteFlowFailuresForAdmission' | 'pinDependencyCompletionForAdmission' | 'insertCron' | 'updateCron' | 'upsertQueueState' | 'loadQueueState' | 'deleteQueueState';
+/** SQL statements */
+export declare const SQL_STATEMENTS: Record<StatementName, string>;
+/** Prepare all statements */
+export declare function prepareStatements(db: Database): Map<StatementName, ReturnType<Database['prepare']>>;
+/** Database row type for jobs (BLOB fields are Uint8Array from bun:sqlite) */
+export interface DbJob {
+    id: string;
+    queue: string;
+    name: string | null;
+    data: Uint8Array;
+    priority: number;
+    created_at: number;
+    run_at: number;
+    started_at: number | null;
+    completed_at: number | null;
+    attempts: number;
+    max_attempts: number;
+    backoff: number;
+    ttl: number | null;
+    timeout: number | null;
+    unique_key: string | null;
+    custom_id: string | null;
+    depends_on: Uint8Array | null;
+    parent_id: string | null;
+    children_ids: Uint8Array | null;
+    tags: Uint8Array | null;
+    state: string;
+    lifo: number;
+    group_id: string | null;
+    progress: number | null;
+    progress_msg: string | null;
+    remove_on_complete: number;
+    remove_on_fail: number;
+    fail_parent_on_failure: number;
+    remove_dependency_on_failure: number;
+    continue_parent_on_failure: number;
+    ignore_dependency_on_failure: number;
+    stall_timeout: number | null;
+    last_heartbeat: number | null;
+    stall_count: number;
+    timeline: Uint8Array | null;
+    stacktrace: Uint8Array | null;
+    dlq_retry_state: Uint8Array | null;
+    extended_options: Uint8Array | null;
+}
+/** Database row type for cron jobs */
+export interface DbCron {
+    name: string;
+    queue: string;
+    job_name: string | null;
+    data: Uint8Array;
+    schedule: string | null;
+    repeat_every: number | null;
+    priority: number;
+    next_run: number;
+    executions: number;
+    max_limit: number | null;
+    timezone: string | null;
+    unique_key: string | null;
+    dedup: Uint8Array | null;
+    skip_missed_on_restart: number;
+    skip_if_no_worker: number;
+    prevent_overlap: number;
+    job_options: Uint8Array | null;
+}
+/** Database row type for queue control-state (#100) */
+export interface DbQueueState {
+    name: string;
+    paused: number;
+    rate_limit: number | null;
+    concurrency_limit: number | null;
+    rate_limit_duration: number | null;
+    rate_limit_expires_at: number | null;
+    stall_enabled: number | null;
+    stall_interval: number | null;
+    max_stalls: number | null;
+    stall_grace_period: number | null;
+    dlq_config: Uint8Array | null;
+}

package/dist/types/src/infrastructure/persistence/types/admission.d.ts

@@ -0,0 +1,8 @@
+import type { JobId } from "../../../domain/types/job.js";
+/** Extra persisted state carried by a two-phase job admission. */
+export interface DurableAdmissionMetadata {
+    /** Terminal generation replaced by the incoming deterministic job ID. */
+    readonly retireGenerationId?: JobId;
+    /** Payload-free completion records referenced by the incoming job. */
+    readonly completionPins?: readonly JobId[];
+}

package/dist/types/src/infrastructure/persistence/types/batch.d.ts

@@ -0,0 +1,12 @@
+import type { Job } from "../../../domain/types/job.js";
+export interface BatchInsertResult {
+    transient: Job[];
+    conflicts: Job[];
+    error?: Error;
+}
+export type WriteBufferErrorCallback = (error: Error, jobCount: number, retryInfo?: {
+    retryCount: number;
+    nextBackoffMs: number;
+    maxRetries: number;
+}) => void;
+export type CriticalErrorCallback = (jobs: Job[], lastError: Error, totalAttempts: number) => void;

package/dist/types/src/infrastructure/persistence/types/sqlite.d.ts

@@ -0,0 +1,27 @@
+import type { Job, JobId, JobTimelineEntry } from "../../../domain/types/job.js";
+export interface ActiveJobWrite {
+    jobId: JobId;
+    startedAt: number;
+    timeline?: JobTimelineEntry[];
+}
+export interface CompletedJobWrite {
+    jobId: JobId;
+    completedAt: number;
+    timeline?: JobTimelineEntry[];
+}
+export type SqliteCriticalLossCallback = (jobs: Job[], lastError: Error, attempts: number) => void;
+export interface SqliteCriticalLoss {
+    jobs: Job[];
+    error: string;
+    attempts: number;
+    at: number;
+}
+export interface SqliteConfig {
+    path: string;
+    walMode?: boolean;
+    synchronous?: 'OFF' | 'NORMAL' | 'FULL';
+    cacheSize?: number;
+    writeBufferSize?: number;
+    writeBufferFlushMs?: number;
+    onCriticalLoss?: SqliteCriticalLossCallback;
+}

package/dist/types/src/infrastructure/persistence/writeBuffer.d.ts

@@ -0,0 +1,48 @@
+import type { Job, JobId } from "../../domain/types/job.js";
+import type { BatchInsertManager } from "./batchInsert.js";
+import type { CriticalErrorCallback, WriteBufferErrorCallback } from "./types/batch.js";
+import type { PersistedJobState } from "./sqliteSerializer.js";
+export declare class WriteBuffer {
+    private activeBuffer;
+    private flushBuffer;
+    private flushing;
+    private stopped;
+    private timer;
+    private readonly batchManager;
+    private readonly bufferSize;
+    private readonly onError;
+    private readonly onCriticalError?;
+    private retryCount;
+    private currentBackoffMs;
+    private readonly initialBackoffMs;
+    private readonly maxBackoffMs;
+    private readonly maxRetries;
+    private lastError;
+    private backoffTimer;
+    private autoFlushDeferrals;
+    constructor(batchManager: BatchInsertManager, bufferSize: number, flushIntervalMs: number, onError: WriteBufferErrorCallback, onCriticalError?: CriticalErrorCallback);
+    add(job: Job): void;
+    addBatch(jobs: Job[]): void;
+    withDeferredAutoFlush<T>(operation: () => T): T;
+    flush(): number;
+    flushIfReady(): number;
+    private scheduleBackoffRetry;
+    get pendingCount(): number;
+    removePending(jobId: string): void;
+    removePendingForQueue(queue: string): JobId[];
+    hasPending(jobId: string): boolean;
+    getPendingJob(jobId: JobId): Job | null;
+    setPendingState(jobId: JobId, state: PersistedJobState): boolean;
+    getPendingJobs(queue?: string): Job[];
+    stop(): void;
+    stopGracefully(timeoutMs?: number): Promise<number>;
+    private clearBackoffRetry;
+    private resetRetryState;
+    private flushBestEffort;
+    private reportLostJobs;
+    getRetryState(): {
+        retryCount: number;
+        currentBackoffMs: number;
+        lastError: Error | null;
+    };
+}

package/dist/types/src/infrastructure/persistence/writeBufferPending.d.ts

@@ -0,0 +1,11 @@
+import type { Job, JobId } from "../../domain/types/job.js";
+import { type PersistedJobState } from "./sqliteSerializer.js";
+export type PendingBuffers = readonly [active: Job[], flushing: Job[]];
+export declare function findPendingJob(buffers: PendingBuffers, jobId: JobId): Job | null;
+export declare function setPendingJobState(buffers: PendingBuffers, jobId: JobId, state: PersistedJobState): boolean;
+export declare function listPendingJobs(buffers: PendingBuffers, queue?: string): Job[];
+export declare function removePendingJob(buffers: PendingBuffers, jobId: JobId): [Job[], Job[]];
+export declare function removePendingQueue(buffers: PendingBuffers, queue: string): {
+    buffers: [Job[], Job[]];
+    removed: JobId[];
+};

package/dist/types/src/infrastructure/scheduler/cron/execution.d.ts

@@ -0,0 +1,12 @@
+import { CronRuntime } from "./runtime.js";
+/** Due-job execution and scheduler statistics. */
+export declare class CronExecution extends CronRuntime {
+    protected tick(): Promise<void>;
+    private getSkipReason;
+    private fireCronJob;
+    getStats(): {
+        total: number;
+        pending: number;
+        nextRun: number | null;
+    };
+}

package/dist/types/src/infrastructure/scheduler/cron/persisted.d.ts

@@ -0,0 +1,5 @@
+import { type CronJob } from "../../../domain/types/cron.js";
+/** Reject persisted Croner-only syntax before any scheduler state is mutated. */
+export declare function assertPersistedCronSupported(cron: CronJob): void;
+/** Validate a persisted collection atomically before loading any definition. */
+export declare function assertPersistedCronsSupported(crons: readonly CronJob[]): void;

package/dist/types/src/infrastructure/scheduler/cron/runtime.d.ts

@@ -0,0 +1,31 @@
+import { type CronJob, type CronJobInput } from "../../../domain/types/cron.js";
+import { MinHeap } from "../../../shared/minHeap.js";
+import type { CronHeapEntry, CronRegistryEntry, CronSchedulerConfig, PersistCronCallback, PushJobCallback } from "../types/cronScheduler.js";
+/** Registry, timers, and schedule mutation shared with cron execution. */
+export declare abstract class CronRuntime {
+    protected readonly cronJobs: Map<string, CronRegistryEntry>;
+    protected readonly cronHeap: MinHeap<CronHeapEntry>;
+    protected generation: number;
+    protected nextTimer: ReturnType<typeof setTimeout> | null;
+    protected safetyInterval: ReturnType<typeof setInterval> | null;
+    protected started: boolean;
+    protected pushJob: PushJobCallback | null;
+    protected persistCron: PersistCronCallback | null;
+    protected hasWorkers: ((queue: string) => boolean) | null;
+    protected dashboardEmit: ((event: string, data: Record<string, unknown>) => void) | null;
+    protected readonly lastFiredAt: Map<string, number>;
+    protected abstract tick(): Promise<void>;
+    constructor(config?: CronSchedulerConfig);
+    setPushCallback(callback: PushJobCallback): void;
+    setPersistCallback(callback: PersistCronCallback): void;
+    setWorkerCheckCallback(callback: (queue: string) => boolean): void;
+    setDashboardEmit(callback: (event: string, data: Record<string, unknown>) => void): void;
+    start(): void;
+    stop(): void;
+    add(input: CronJobInput): CronJob;
+    remove(name: string): boolean;
+    get(name: string): CronJob | undefined;
+    list(): CronJob[];
+    load(crons: CronJob[]): void;
+    protected scheduleNext(): void;
+}

package/dist/types/src/infrastructure/scheduler/cron/validation.d.ts

@@ -0,0 +1,3 @@
+import { type CronJobInput } from "../../../domain/types/cron.js";
+/** Reject invalid timing, calendar syntax, and timezones before state mutation. */
+export declare function assertValidCronInput(input: CronJobInput): void;

package/dist/types/src/infrastructure/scheduler/cronParser.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Cron Expression Parser
+ * Parses 5-6 field cron expressions and calculates next run time with Bun.cron
+ */
+/**
+ * Validate a cron expression
+ * @param expression - Cron expression (5 or 6 fields)
+ * @param timezone - Optional IANA timezone (e.g., "Europe/Rome")
+ * @returns null if valid, error message if invalid
+ */
+export declare function validateCronExpression(expression: string, timezone?: string): string | null;
+/**
+ * Calculate next run time from a cron expression
+ * @param expression - Cron expression
+ * @param fromTime - Start time (default: now)
+ * @param timezone - Optional IANA timezone (e.g., "Europe/Rome", "America/New_York")
+ * @returns Next run timestamp in milliseconds
+ */
+export declare function getNextCronRun(expression: string, fromTime?: number, timezone?: string): number;
+/**
+ * Calculate next run time from repeatEvery interval
+ * @param intervalMs - Interval in milliseconds
+ * @param lastRun - Last run timestamp
+ * @returns Next run timestamp
+ */
+export declare function getNextIntervalRun(intervalMs: number, lastRun?: number): number;
+/**
+ * Check if a cron job is due to run
+ * @param nextRun - Scheduled next run time
+ * @param now - Current time (default: Date.now())
+ * @returns true if job should run
+ */
+export declare function isDue(nextRun: number, now?: number): boolean;
+/**
+ * Parse common cron shortcuts
+ */
+export declare const CRON_SHORTCUTS: Record<string, string>;
+/**
+ * Expand cron shortcut to full expression
+ */
+export declare function expandCronShortcut(expression: string): string;
+/**
+ * Get human-readable description of cron schedule
+ */
+export declare function describeCron(expression: string): string;

package/dist/types/src/infrastructure/scheduler/cronScheduler.d.ts

@@ -0,0 +1,5 @@
+import { CronExecution } from "./cron/execution.js";
+export type { CronSchedulerConfig, PersistCronCallback, PushJobCallback, } from "./types/cronScheduler.js";
+/** Event-driven cron scheduler façade. */
+export declare class CronScheduler extends CronExecution {
+}

package/dist/types/src/infrastructure/scheduler/types/cronScheduler.d.ts

@@ -0,0 +1,16 @@
+import type { CronJob } from "../../../domain/types/cron.js";
+import type { JobInput } from "../../../domain/types/job.js";
+export interface CronSchedulerConfig {
+    /** @deprecated The scheduler now uses a precise event-driven timer. */
+    checkIntervalMs?: number;
+}
+export type PushJobCallback = (queue: string, input: JobInput) => Promise<void>;
+export type PersistCronCallback = (name: string, executions: number, nextRun: number) => void;
+export interface CronHeapEntry {
+    cron: CronJob;
+    generation: number;
+}
+export interface CronRegistryEntry {
+    cron: CronJob;
+    generation: number;
+}

package/dist/types/src/infrastructure/server/protocol/commands.d.ts

@@ -0,0 +1,8 @@
+import type { Command } from "../../../domain/types/command.js";
+import { type Response } from "../../../domain/types/response.js";
+import type { ConnectionState } from "../types/protocol.js";
+export declare function parseCommand(data: string): Command | null;
+export declare function serializeResponse(response: Response): string;
+export declare function parseCommands(data: string): Command[];
+export declare function createConnectionState(clientId: string): ConnectionState;
+export declare function errorResponse(message: string, requestId?: string): string;

package/dist/types/src/infrastructure/server/protocol/frameParser.d.ts

@@ -0,0 +1,16 @@
+export declare const MAX_FRAME_SIZE: number;
+export declare class FrameSizeError extends Error {
+    readonly requestedSize: number;
+    readonly maxSize: number;
+    constructor(requestedSize: number, maxSize: number);
+}
+export declare class FrameParser {
+    private buffer;
+    private readonly maxFrameSize;
+    constructor(maxFrameSize?: number);
+    addData(data: Uint8Array): Uint8Array[];
+    get bufferedBytes(): number;
+    get hasPartialFrame(): boolean;
+    clear(): void;
+    static frame(data: Uint8Array): Uint8Array;
+}

package/dist/types/src/infrastructure/server/protocol/lineBuffer.d.ts

@@ -0,0 +1,6 @@
+export declare class LineBuffer {
+    private buffer;
+    addData(data: string): string[];
+    getRemaining(): string;
+    clear(): void;
+}

package/dist/types/src/infrastructure/server/protocol/validation.d.ts

@@ -0,0 +1,10 @@
+export declare function validateQueueName(name: string): string | null;
+export { validateGroupId } from "../../../domain/types/group.js";
+export declare function validateJobData(data: unknown): string | null;
+export declare function validateNumericField(value: unknown, name: string, options?: {
+    min?: number;
+    max?: number;
+    required?: boolean;
+}): string | null;
+export declare function validateBackoffField(value: unknown): string | null;
+export declare function validateJobOptions(options: Record<string, unknown>): string | null;

package/dist/types/src/infrastructure/server/protocol.d.ts

@@ -0,0 +1,6 @@
+export { createConnectionState, errorResponse, parseCommand, parseCommands, serializeResponse, } from "./protocol/commands.js";
+export { FrameParser, FrameSizeError, MAX_FRAME_SIZE } from "./protocol/frameParser.js";
+export { LineBuffer } from "./protocol/lineBuffer.js";
+export { validateBackoffField, validateGroupId, validateJobData, validateJobOptions, validateNumericField, validateQueueName, } from "./protocol/validation.js";
+export type { ConnectionState } from "./types/protocol.js";
+export { validateWebhookUrl } from "../../shared/webhookValidation.js";

package/dist/types/src/infrastructure/server/socketWriteQueue.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Per-socket write queue
+ * =================================================================
+ * Bun's `socket.write()` may write FEWER bytes than provided when the kernel
+ * send buffer is full (backpressure). The unwritten tail is NOT retained by
+ * Bun — the caller is responsible for buffering it and resending once the
+ * socket fires `drain`. Ignoring the short count silently drops response
+ * bytes, corrupting the length-prefixed frame protocol.
+ *
+ * This helper buffers any unwritten tail per-socket and preserves ordering:
+ * while a pending tail exists, all subsequent writes are appended to the queue
+ * (never written ahead of older bytes), and the queue is flushed in order from
+ * the `drain` handler.
+ */
+import type { Socket } from 'bun';
+/** Minimal write surface a socket must expose for the queue. */
+interface WritableSocket {
+    write(data: Uint8Array): number;
+}
+/** Per-socket pending write state. Stored on `socket.data`. */
+export declare class SocketWriteQueue {
+    /** Buffered chunks waiting to be (re)written, in order. */
+    private pending;
+    /** Byte offset into pending[0] already written by a short write. */
+    private offset;
+    /** Total queued bytes (for bounds / observability). */
+    private queuedBytes;
+    /** Max queued bytes before the queue reports over-budget (0 = unbounded). */
+    private readonly maxBytes;
+    /**
+     * @param maxBytes Soft cap on buffered bytes. When `bytesQueued` exceeds this,
+     *   `isOverBudget` becomes true and the owner should drop the connection
+     *   (bounds write-side memory for a client that stopped reading). 0 disables.
+     */
+    constructor(maxBytes?: number);
+    /**
+     * True once the buffered byte count exceeds the configured cap. The owner is
+     * expected to terminate the connection and `clear()` the queue.
+     */
+    get isOverBudget(): boolean;
+    /**
+     * Enqueue `data` for delivery on `socket`, preserving order.
+     * Returns false if the socket appears closed (write threw / returned < 0).
+     */
+    write(socket: WritableSocket, data: Uint8Array): boolean;
+    /**
+     * Flush as much of the pending queue as the socket accepts.
+     * Call from the socket's `drain` handler. Stops at the first short write,
+     * leaving the remainder queued for the next drain.
+     */
+    flush(socket: WritableSocket): boolean;
+    /** Number of bytes still buffered awaiting drain. */
+    get bytesQueued(): number;
+    /** Whether there is unwritten data awaiting drain. */
+    get hasPending(): boolean;
+    /** Drop all buffered data (e.g. on close). */
+    clear(): void;
+}
+/**
+ * Convenience: write through a socket whose `data` carries a `writeQueue`.
+ * Keeps call sites in tcp.ts terse and consistent.
+ */
+export declare function queuedWrite<T extends {
+    writeQueue: SocketWriteQueue;
+}>(socket: Socket<T>, data: Uint8Array): void;
+export {};

package/dist/types/src/infrastructure/server/types/protocol.d.ts

@@ -0,0 +1,4 @@
+export interface ConnectionState {
+    authenticated: boolean;
+    clientId: string;
+}

package/dist/types/src/require-bun.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Bun-only runtime guard (defense-in-depth for the bundled path).
+ *
+ * The `"node"` export condition (-> bun-only.ts) already fails fast for a plain
+ * `node` import and for node-target bundlers. This guard covers the remaining
+ * case: a browser/neutral-target bundler that inlines the real client, whose
+ * output is then run on Node. Without it, the failure surfaces deep inside as a
+ * cryptic `Bun is not defined` / `Bun.connect is not a function`.
+ *
+ * Imported FIRST by the client entrypoints so it evaluates before any module
+ * that touches `Bun.*` at top level. No-op under Bun. Keep relative-import-free.
+ */
+export {};

package/dist/types/src/shared/asyncLock.d.ts

@@ -0,0 +1,13 @@
+/** FIFO asynchronous mutex with direct ownership handoff. */
+import type { LockGuard } from "./types/lock.js";
+export declare class AsyncLock {
+    private locked;
+    private readonly queue;
+    acquire(timeoutMs?: number): Promise<LockGuard>;
+    isLocked(): boolean;
+    /** Queue size includes lazily pruned timed-out entries. */
+    getQueueLength(): number;
+    private timeout;
+    private drain;
+    private createGuard;
+}

package/dist/types/src/shared/boundedMap.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Bounded Map - fast FIFO eviction without LRU tracking
+ */
+import type { MapLike } from "./lruMap.js";
+/**
+ * Bounded Map - fast FIFO eviction without LRU tracking
+ * Optimized for high-throughput scenarios where recency doesn't matter
+ * Uses batch eviction to avoid per-item iterator overhead
+ */
+export declare class BoundedMap<K, V> implements MapLike<K, V> {
+    private readonly cache;
+    private readonly maxSize;
+    private readonly onEvict?;
+    /** Evict 10% of items at once to amortize iterator cost */
+    private readonly evictBatchSize;
+    constructor(maxSize: number, onEvict?: (key: K, value: V) => void);
+    get(key: K): V | undefined;
+    set(key: K, value: V): void;
+    /** Evict multiple items at once - more efficient than one at a time */
+    private evictBatch;
+    has(key: K): boolean;
+    delete(key: K): boolean;
+    clear(): void;
+    get size(): number;
+    keys(): IterableIterator<K>;
+    values(): IterableIterator<V>;
+    entries(): IterableIterator<[K, V]>;
+    forEach(callback: (value: V, key: K) => void): void;
+    [Symbol.iterator](): IterableIterator<[K, V]>;
+}

package/dist/types/src/shared/boundedSet.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Bounded Set - fast FIFO eviction without LRU tracking
+ */
+import type { SetLike } from "./lruSet.js";
+/**
+ * Bounded Set - fast FIFO eviction without LRU tracking
+ * Optimized for high-throughput scenarios where recency doesn't matter
+ * Uses batch eviction to avoid per-item iterator overhead
+ */
+export declare class BoundedSet<T> implements SetLike<T> {
+    private readonly cache;
+    private readonly maxSize;
+    private readonly onEvict?;
+    /** Evict 10% of items at once to amortize iterator cost */
+    private readonly evictBatchSize;
+    constructor(maxSize: number, onEvict?: (value: T) => void);
+    add(value: T): void;
+    /** Evict multiple items at once - more efficient than one at a time */
+    private evictBatch;
+    has(value: T): boolean;
+    delete(value: T): boolean;
+    clear(): void;
+    get size(): number;
+    values(): IterableIterator<T>;
+    [Symbol.iterator](): IterableIterator<T>;
+}

package/dist/types/src/shared/hash.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Fast hash functions
+ * FNV-1a implementation for consistent hashing
+ */
+/**
+ * FNV-1a hash function (32-bit)
+ * Fast, good distribution for strings
+ */
+export declare function fnv1a(str: string): number;
+/**
+ * Shard configuration - auto-detected from hardware
+ * Uses power of 2 for fast bitwise mask
+ */
+export declare const SHARD_COUNT: number;
+export declare const SHARD_MASK: number;
+export declare function shardIndex(key: string): number;
+/**
+ * Calculate processing shard index from job ID (UUIDv7 string)
+ */
+export declare function processingShardIndex(jobId: string): number;
+/**
+ * Generate a UUID v7 using Bun's native implementation
+ * ~10x faster than manual Math.random() based UUID v4
+ */
+export declare function uuid(): string;
+/**
+ * Constant-time string comparison
+ * Prevents timing attacks on token validation
+ */
+export declare function constantTimeEqual(a: string, b: string): boolean;

package/dist/types/src/shared/histogram.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Lightweight Histogram for latency tracking
+ * Fixed bucket boundaries, O(1) observation via binary search
+ */
+export declare class Histogram {
+    private readonly buckets;
+    private readonly counts;
+    private sum;
+    private count;
+    constructor(buckets?: number[]);
+    /** Record an observation (in milliseconds) */
+    observe(value: number): void;
+    /** Get sum of all observations */
+    getSum(): number;
+    /** Get total count of observations */
+    getCount(): number;
+    /** Calculate a percentile (0-100) */
+    percentile(p: number): number;
+    /** Generate Prometheus histogram lines, optionally scaling observed values. */
+    toPrometheus(name: string, help: string, outputScale?: number): string;
+    /** Reset all counters */
+    reset(): void;
+}

package/dist/types/src/shared/lock.d.ts

@@ -0,0 +1,13 @@
+/** Async lock facade and scoped execution helpers. */
+import { AsyncLock } from "./asyncLock.js";
+import { RWLock } from "./rwLock.js";
+export { AsyncLock } from "./asyncLock.js";
+export { LockTimeoutError } from "./lockError.js";
+export { RWLock } from "./rwLock.js";
+export type { LockGuard } from "./types/lock.js";
+/** Execute with an exclusive lock and always release it. */
+export declare function withLock<T>(lock: AsyncLock, fn: () => T | Promise<T>, timeoutMs?: number): Promise<T>;
+/** Execute with a read lock and always release it. */
+export declare function withReadLock<T>(lock: RWLock, fn: () => T | Promise<T>, timeoutMs?: number): Promise<T>;
+/** Execute with a write lock and always release it. */
+export declare function withWriteLock<T>(lock: RWLock, fn: () => T | Promise<T>, timeoutMs?: number): Promise<T>;

package/dist/types/src/shared/lockError.d.ts

@@ -0,0 +1,3 @@
+export declare class LockTimeoutError extends Error {
+    constructor(message?: string);
+}

package/dist/types/src/shared/lockTimeout.d.ts

@@ -0,0 +1,2 @@
+/** Default lock acquisition timeout shared by lock implementations. */
+export declare const DEFAULT_LOCK_TIMEOUT_MS: number;