flashq 0.3.3 → 0.3.4

package/dist/client/reconnect.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Reconnection logic for FlashQ client.
+ *
+ * Implements exponential backoff with jitter for automatic reconnection
+ * after connection loss.
+ */
+import { EventEmitter } from 'events';
+import type { Logger } from '../utils/logger';
+/** Connection state machine states */
+export type ConnectionState = 'disconnected' | 'connecting' | 'connected' | 'reconnecting' | 'closed';
+/** Configuration for reconnection behavior */
+export interface ReconnectConfig {
+    /** Whether auto-reconnect is enabled */
+    enabled: boolean;
+    /** Maximum number of reconnection attempts (0 = unlimited) */
+    maxAttempts: number;
+    /** Initial delay between reconnection attempts (ms) */
+    initialDelay: number;
+    /** Maximum delay between reconnection attempts (ms) */
+    maxDelay: number;
+}
+/** Event data emitted during reconnection */
+export interface ReconnectEventData {
+    /** Current attempt number */
+    attempt: number;
+    /** Delay before this attempt (ms) */
+    delay: number;
+}
+/**
+ * Manages reconnection state and scheduling.
+ *
+ * Implements exponential backoff with jitter:
+ * delay = min(initialDelay * 2^attempt, maxDelay) + random jitter
+ *
+ * @example
+ * ```typescript
+ * const manager = new ReconnectManager(config, logger, emitter);
+ *
+ * manager.schedule(async () => {
+ *   await connect();
+ *   manager.reset();
+ * });
+ * ```
+ */
+export declare class ReconnectManager {
+    private readonly config;
+    private readonly logger;
+    private readonly emitter;
+    /** Current reconnection attempt number */
+    private attempts;
+    /** Timer handle for scheduled reconnection */
+    private timer;
+    /** Whether reconnection was cancelled */
+    private cancelled;
+    constructor(config: ReconnectConfig, logger: Logger, emitter: EventEmitter);
+    /**
+     * Calculates the delay for the next reconnection attempt.
+     *
+     * Uses exponential backoff with 30% jitter to prevent
+     * thundering herd problems.
+     *
+     * @param attempt - Current attempt number (1-based)
+     * @returns Delay in milliseconds
+     */
+    calculateDelay(attempt: number): number;
+    /**
+     * Checks if more reconnection attempts are allowed.
+     *
+     * @returns true if another attempt can be made
+     */
+    canRetry(): boolean;
+    /**
+     * Schedules a reconnection attempt.
+     *
+     * @param connectFn - Async function that performs the connection
+     */
+    schedule(connectFn: () => Promise<void>): void;
+    /**
+     * Resets the reconnection state after successful connection.
+     */
+    reset(): void;
+    /**
+     * Cancels any pending reconnection attempt.
+     */
+    cancel(): void;
+    /**
+     * Gets the current attempt count.
+     */
+    getAttempts(): number;
+}
+/**
+ * Waits for a reconnection to complete.
+ *
+ * @param emitter - Event emitter that fires reconnection events
+ * @param timeout - Maximum time to wait (ms)
+ * @returns Promise that resolves when reconnected
+ * @throws ConnectionError if reconnection fails or times out
+ */
+export declare function waitForReconnection(emitter: EventEmitter, timeout: number): Promise<void>;
+//# sourceMappingURL=reconnect.d.ts.map

package/dist/client/reconnect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reconnect.d.ts","sourceRoot":"","sources":["../../src/client/reconnect.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AAEtC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAE9C,sCAAsC;AACtC,MAAM,MAAM,eAAe,GACvB,cAAc,GACd,YAAY,GACZ,WAAW,GACX,cAAc,GACd,QAAQ,CAAC;AAEb,8CAA8C;AAC9C,MAAM,WAAW,eAAe;IAC9B,wCAAwC;IACxC,OAAO,EAAE,OAAO,CAAC;IACjB,8DAA8D;IAC9D,WAAW,EAAE,MAAM,CAAC;IACpB,uDAAuD;IACvD,YAAY,EAAE,MAAM,CAAC;IACrB,uDAAuD;IACvD,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,6CAA6C;AAC7C,MAAM,WAAW,kBAAkB;IACjC,6BAA6B;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,qCAAqC;IACrC,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,gBAAgB;IASzB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAV1B,0CAA0C;IAC1C,OAAO,CAAC,QAAQ,CAAK;IACrB,8CAA8C;IAC9C,OAAO,CAAC,KAAK,CAA8C;IAC3D,yCAAyC;IACzC,OAAO,CAAC,SAAS,CAAS;gBAGP,MAAM,EAAE,eAAe,EACvB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,YAAY;IAGxC;;;;;;;;OAQG;IACH,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;IASvC;;;;OAIG;IACH,QAAQ,IAAI,OAAO;IAMnB;;;;OAIG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI;IAgC9C;;OAEG;IACH,KAAK,IAAI,IAAI;IAKb;;OAEG;IACH,MAAM,IAAI,IAAI;IAQd;;OAEG;IACH,WAAW,IAAI,MAAM;CAGtB;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAuBzF"}

package/dist/client/reconnect.js

@@ -0,0 +1,154 @@
+"use strict";
+/**
+ * Reconnection logic for FlashQ client.
+ *
+ * Implements exponential backoff with jitter for automatic reconnection
+ * after connection loss.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ReconnectManager = void 0;
+exports.waitForReconnection = waitForReconnection;
+const errors_1 = require("../errors");
+/**
+ * Manages reconnection state and scheduling.
+ *
+ * Implements exponential backoff with jitter:
+ * delay = min(initialDelay * 2^attempt, maxDelay) + random jitter
+ *
+ * @example
+ * ```typescript
+ * const manager = new ReconnectManager(config, logger, emitter);
+ *
+ * manager.schedule(async () => {
+ *   await connect();
+ *   manager.reset();
+ * });
+ * ```
+ */
+class ReconnectManager {
+    config;
+    logger;
+    emitter;
+    /** Current reconnection attempt number */
+    attempts = 0;
+    /** Timer handle for scheduled reconnection */
+    timer = null;
+    /** Whether reconnection was cancelled */
+    cancelled = false;
+    constructor(config, logger, emitter) {
+        this.config = config;
+        this.logger = logger;
+        this.emitter = emitter;
+    }
+    /**
+     * Calculates the delay for the next reconnection attempt.
+     *
+     * Uses exponential backoff with 30% jitter to prevent
+     * thundering herd problems.
+     *
+     * @param attempt - Current attempt number (1-based)
+     * @returns Delay in milliseconds
+     */
+    calculateDelay(attempt) {
+        const baseDelay = Math.min(this.config.initialDelay * Math.pow(2, attempt - 1), this.config.maxDelay);
+        // Add 0-30% jitter
+        return baseDelay + Math.random() * 0.3 * baseDelay;
+    }
+    /**
+     * Checks if more reconnection attempts are allowed.
+     *
+     * @returns true if another attempt can be made
+     */
+    canRetry() {
+        if (!this.config.enabled || this.cancelled)
+            return false;
+        if (this.config.maxAttempts === 0)
+            return true; // Unlimited
+        return this.attempts < this.config.maxAttempts;
+    }
+    /**
+     * Schedules a reconnection attempt.
+     *
+     * @param connectFn - Async function that performs the connection
+     */
+    schedule(connectFn) {
+        if (!this.canRetry()) {
+            this.logger.error('Max reconnection attempts reached', { attempts: this.attempts });
+            this.emitter.emit('reconnect_failed', new errors_1.ConnectionError('Max reconnection attempts reached', 'RECONNECTION_FAILED'));
+            return;
+        }
+        this.attempts++;
+        const delay = this.calculateDelay(this.attempts);
+        this.logger.info('Scheduling reconnection', { attempt: this.attempts, delay: Math.round(delay) });
+        this.emitter.emit('reconnecting', { attempt: this.attempts, delay });
+        this.timer = setTimeout(async () => {
+            try {
+                await connectFn();
+                this.logger.info('Reconnected successfully', { attempt: this.attempts });
+                this.emitter.emit('reconnected');
+            }
+            catch (error) {
+                this.logger.warn('Reconnection attempt failed', {
+                    attempt: this.attempts,
+                    error: error instanceof Error ? error.message : error,
+                });
+                // Schedule next attempt
+                this.schedule(connectFn);
+            }
+        }, delay);
+    }
+    /**
+     * Resets the reconnection state after successful connection.
+     */
+    reset() {
+        this.attempts = 0;
+        this.cancelled = false;
+    }
+    /**
+     * Cancels any pending reconnection attempt.
+     */
+    cancel() {
+        this.cancelled = true;
+        if (this.timer) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+    }
+    /**
+     * Gets the current attempt count.
+     */
+    getAttempts() {
+        return this.attempts;
+    }
+}
+exports.ReconnectManager = ReconnectManager;
+/**
+ * Waits for a reconnection to complete.
+ *
+ * @param emitter - Event emitter that fires reconnection events
+ * @param timeout - Maximum time to wait (ms)
+ * @returns Promise that resolves when reconnected
+ * @throws ConnectionError if reconnection fails or times out
+ */
+function waitForReconnection(emitter, timeout) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            emitter.removeListener('reconnected', onReconnect);
+            emitter.removeListener('reconnect_failed', onFailed);
+            reject(new errors_1.ConnectionError('Reconnection timeout', 'RECONNECTION_FAILED'));
+        }, timeout);
+        const onReconnect = () => {
+            clearTimeout(timer);
+            emitter.removeListener('reconnect_failed', onFailed);
+            resolve();
+        };
+        const onFailed = (err) => {
+            clearTimeout(timer);
+            emitter.removeListener('reconnected', onReconnect);
+            reject(err);
+        };
+        emitter.once('reconnected', onReconnect);
+        emitter.once('reconnect_failed', onFailed);
+    });
+}
+//# sourceMappingURL=reconnect.js.map

package/dist/client/reconnect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reconnect.js","sourceRoot":"","sources":["../../src/client/reconnect.ts"],"names":[],"mappings":"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"}

package/dist/client/tcp/handler.d.ts

@@ -0,0 +1,106 @@
+/**
+ * TCP protocol handler for FlashQ client.
+ *
+ * Handles buffer management, message framing, and protocol serialization
+ * for both JSON (newline-delimited) and binary (MessagePack) protocols.
+ */
+/**
+ * Pending request tracking for async responses.
+ */
+export interface PendingRequest {
+    /** Resolves with the response data */
+    resolve: (value: unknown) => void;
+    /** Rejects with an error */
+    reject: (error: Error) => void;
+    /** Timeout timer handle */
+    timer: ReturnType<typeof setTimeout>;
+}
+/**
+ * Handles JSON protocol buffer parsing.
+ *
+ * Accumulates incoming data chunks and extracts complete
+ * newline-delimited JSON messages.
+ */
+export declare class JsonBufferHandler {
+    /** Accumulated string chunks waiting to be joined */
+    private chunks;
+    /** Partial line from previous parse */
+    private remainder;
+    /**
+     * Appends new data to the buffer.
+     *
+     * @param data - Raw data from socket
+     */
+    append(data: Buffer | string): void;
+    /**
+     * Extracts all complete lines from the buffer.
+     *
+     * Complete lines are separated by newlines. Any partial line
+     * at the end is kept for the next call.
+     *
+     * @returns Array of complete JSON strings
+     */
+    extractLines(): string[];
+    /**
+     * Resets the buffer state.
+     */
+    reset(): void;
+}
+/**
+ * Handles binary (MessagePack) protocol buffer parsing.
+ *
+ * Each message is framed with a 4-byte big-endian length prefix
+ * followed by the MessagePack-encoded payload.
+ */
+export declare class BinaryBufferHandler {
+    /** Accumulated binary data */
+    private buffer;
+    /**
+     * Appends new data to the buffer.
+     *
+     * @param data - Raw data from socket
+     */
+    append(data: Buffer): void;
+    /**
+     * Extracts all complete frames from the buffer.
+     *
+     * Frame format: [4-byte length BE][payload]
+     *
+     * @returns Array of decoded message objects
+     */
+    extractFrames(): Record<string, unknown>[];
+    /**
+     * Resets the buffer state.
+     */
+    reset(): void;
+}
+/**
+ * Encodes a command for TCP transmission.
+ *
+ * @param command - Command object to encode
+ * @param reqId - Request ID to include
+ * @param useBinary - Whether to use MessagePack encoding
+ * @returns Buffer ready for socket.write()
+ */
+export declare function encodeCommand(command: Record<string, unknown>, reqId: string, useBinary: boolean): Buffer;
+/**
+ * Parses a JSON response from a string.
+ *
+ * @param line - JSON string to parse
+ * @returns Parsed response object or null if invalid
+ */
+export declare function parseJsonResponse(line: string): Record<string, unknown> | null;
+/**
+ * Generates a unique request ID.
+ *
+ * Format: "r{incrementing number}"
+ *
+ * @returns Unique request ID string
+ */
+export declare function generateRequestId(): string;
+/**
+ * Resets the request ID counter.
+ * Primarily used for testing.
+ */
+export declare function resetRequestIdCounter(): void;
+//# sourceMappingURL=handler.d.ts.map

package/dist/client/tcp/handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handler.d.ts","sourceRoot":"","sources":["../../../src/client/tcp/handler.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,sCAAsC;IACtC,OAAO,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;IAClC,4BAA4B;IAC5B,MAAM,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IAC/B,2BAA2B;IAC3B,KAAK,EAAE,UAAU,CAAC,OAAO,UAAU,CAAC,CAAC;CACtC;AAED;;;;;GAKG;AACH,qBAAa,iBAAiB;IAC5B,qDAAqD;IACrD,OAAO,CAAC,MAAM,CAAgB;IAC9B,uCAAuC;IACvC,OAAO,CAAC,SAAS,CAAM;IAEvB;;;;OAIG;IACH,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAInC;;;;;;;OAOG;IACH,YAAY,IAAI,MAAM,EAAE;IAWxB;;OAEG;IACH,KAAK,IAAI,IAAI;CAId;AAED;;;;;GAKG;AACH,qBAAa,mBAAmB;IAC9B,8BAA8B;IAC9B,OAAO,CAAC,MAAM,CAA2B;IAEzC;;;;OAIG;IACH,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAI1B;;;;;;OAMG;IACH,aAAa,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE;IAgB1C;;OAEG;IACH,KAAK,IAAI,IAAI;CAGd;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,OAAO,GACjB,MAAM,CAYR;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAM9E;AAKD;;;;;;GAMG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAE1C;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,IAAI,IAAI,CAE5C"}

package/dist/client/tcp/handler.js

@@ -0,0 +1,155 @@
+"use strict";
+/**
+ * TCP protocol handler for FlashQ client.
+ *
+ * Handles buffer management, message framing, and protocol serialization
+ * for both JSON (newline-delimited) and binary (MessagePack) protocols.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BinaryBufferHandler = exports.JsonBufferHandler = void 0;
+exports.encodeCommand = encodeCommand;
+exports.parseJsonResponse = parseJsonResponse;
+exports.generateRequestId = generateRequestId;
+exports.resetRequestIdCounter = resetRequestIdCounter;
+const msgpack_1 = require("@msgpack/msgpack");
+/**
+ * Handles JSON protocol buffer parsing.
+ *
+ * Accumulates incoming data chunks and extracts complete
+ * newline-delimited JSON messages.
+ */
+class JsonBufferHandler {
+    /** Accumulated string chunks waiting to be joined */
+    chunks = [];
+    /** Partial line from previous parse */
+    remainder = '';
+    /**
+     * Appends new data to the buffer.
+     *
+     * @param data - Raw data from socket
+     */
+    append(data) {
+        this.chunks.push(typeof data === 'string' ? data : data.toString());
+    }
+    /**
+     * Extracts all complete lines from the buffer.
+     *
+     * Complete lines are separated by newlines. Any partial line
+     * at the end is kept for the next call.
+     *
+     * @returns Array of complete JSON strings
+     */
+    extractLines() {
+        // Join chunks only when processing (more efficient than += on each chunk)
+        const fullBuffer = this.remainder + this.chunks.join('');
+        this.chunks.length = 0; // Clear array without reallocating
+        const lines = fullBuffer.split('\n');
+        this.remainder = lines.pop() ?? '';
+        return lines.filter((line) => line.trim());
+    }
+    /**
+     * Resets the buffer state.
+     */
+    reset() {
+        this.chunks.length = 0;
+        this.remainder = '';
+    }
+}
+exports.JsonBufferHandler = JsonBufferHandler;
+/**
+ * Handles binary (MessagePack) protocol buffer parsing.
+ *
+ * Each message is framed with a 4-byte big-endian length prefix
+ * followed by the MessagePack-encoded payload.
+ */
+class BinaryBufferHandler {
+    /** Accumulated binary data */
+    buffer = Buffer.alloc(0);
+    /**
+     * Appends new data to the buffer.
+     *
+     * @param data - Raw data from socket
+     */
+    append(data) {
+        this.buffer = Buffer.concat([this.buffer, data]);
+    }
+    /**
+     * Extracts all complete frames from the buffer.
+     *
+     * Frame format: [4-byte length BE][payload]
+     *
+     * @returns Array of decoded message objects
+     */
+    extractFrames() {
+        const frames = [];
+        while (this.buffer.length >= 4) {
+            const len = this.buffer.readUInt32BE(0);
+            if (this.buffer.length < 4 + len)
+                break;
+            const frameData = this.buffer.subarray(4, 4 + len);
+            this.buffer = this.buffer.subarray(4 + len);
+            frames.push((0, msgpack_1.decode)(frameData));
+        }
+        return frames;
+    }
+    /**
+     * Resets the buffer state.
+     */
+    reset() {
+        this.buffer = Buffer.alloc(0);
+    }
+}
+exports.BinaryBufferHandler = BinaryBufferHandler;
+/**
+ * Encodes a command for TCP transmission.
+ *
+ * @param command - Command object to encode
+ * @param reqId - Request ID to include
+ * @param useBinary - Whether to use MessagePack encoding
+ * @returns Buffer ready for socket.write()
+ */
+function encodeCommand(command, reqId, useBinary) {
+    const payload = { ...command, reqId };
+    if (useBinary) {
+        const encoded = (0, msgpack_1.encode)(payload);
+        const frame = Buffer.alloc(4 + encoded.length);
+        frame.writeUInt32BE(encoded.length, 0);
+        frame.set(encoded, 4);
+        return frame;
+    }
+    return Buffer.from(JSON.stringify(payload) + '\n');
+}
+/**
+ * Parses a JSON response from a string.
+ *
+ * @param line - JSON string to parse
+ * @returns Parsed response object or null if invalid
+ */
+function parseJsonResponse(line) {
+    try {
+        return JSON.parse(line);
+    }
+    catch {
+        return null;
+    }
+}
+/** Counter for generating unique request IDs */
+let requestIdCounter = 0;
+/**
+ * Generates a unique request ID.
+ *
+ * Format: "r{incrementing number}"
+ *
+ * @returns Unique request ID string
+ */
+function generateRequestId() {
+    return `r${++requestIdCounter}`;
+}
+/**
+ * Resets the request ID counter.
+ * Primarily used for testing.
+ */
+function resetRequestIdCounter() {
+    requestIdCounter = 0;
+}
+//# sourceMappingURL=handler.js.map

package/dist/client/tcp/handler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"handler.js","sourceRoot":"","sources":["../../../src/client/tcp/handler.ts"],"names":[],"mappings":"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"}

package/dist/client/tcp/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * TCP protocol module exports.
+ */
+export { type PendingRequest, JsonBufferHandler, BinaryBufferHandler, encodeCommand, parseJsonResponse, generateRequestId, resetRequestIdCounter, } from './handler';
+//# sourceMappingURL=index.d.ts.map

package/dist/client/tcp/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/client/tcp/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EACL,KAAK,cAAc,EACnB,iBAAiB,EACjB,mBAAmB,EACnB,aAAa,EACb,iBAAiB,EACjB,iBAAiB,EACjB,qBAAqB,GACtB,MAAM,WAAW,CAAC"}

package/dist/client/tcp/index.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resetRequestIdCounter = exports.generateRequestId = exports.parseJsonResponse = exports.encodeCommand = exports.BinaryBufferHandler = exports.JsonBufferHandler = void 0;
+/**
+ * TCP protocol module exports.
+ */
+var handler_1 = require("./handler");
+Object.defineProperty(exports, "JsonBufferHandler", { enumerable: true, get: function () { return handler_1.JsonBufferHandler; } });
+Object.defineProperty(exports, "BinaryBufferHandler", { enumerable: true, get: function () { return handler_1.BinaryBufferHandler; } });
+Object.defineProperty(exports, "encodeCommand", { enumerable: true, get: function () { return handler_1.encodeCommand; } });
+Object.defineProperty(exports, "parseJsonResponse", { enumerable: true, get: function () { return handler_1.parseJsonResponse; } });
+Object.defineProperty(exports, "generateRequestId", { enumerable: true, get: function () { return handler_1.generateRequestId; } });
+Object.defineProperty(exports, "resetRequestIdCounter", { enumerable: true, get: function () { return handler_1.resetRequestIdCounter; } });
+//# sourceMappingURL=index.js.map

package/dist/client/tcp/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/client/tcp/index.ts"],"names":[],"mappings":";;;AAAA;;GAEG;AACH,qCAQmB;AANjB,4GAAA,iBAAiB,OAAA;AACjB,8GAAA,mBAAmB,OAAA;AACnB,wGAAA,aAAa,OAAA;AACb,4GAAA,iBAAiB,OAAA;AACjB,4GAAA,iBAAiB,OAAA;AACjB,gHAAA,qBAAqB,OAAA"}

package/dist/client/validation.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Input validation utilities for FlashQ client.
+ *
+ * Provides validation functions for queue names, job data sizes,
+ * and batch operation limits.
+ */
+/** Maximum allowed job data size in bytes (1MB) */
+export declare const MAX_JOB_DATA_SIZE: number;
+/** Maximum number of jobs per batch operation */
+export declare const MAX_BATCH_SIZE = 1000;
+/**
+ * Validates a queue name against naming rules.
+ *
+ * Queue names must:
+ * - Be non-empty strings
+ * - Contain only alphanumeric characters, underscores, hyphens, or dots
+ * - Be between 1 and 256 characters long
+ *
+ * @param queue - The queue name to validate
+ * @throws ValidationError if the queue name is invalid
+ *
+ * @example
+ * ```typescript
+ * validateQueueName('my-queue');      // OK
+ * validateQueueName('queue.name');    // OK
+ * validateQueueName('queue name');    // Throws: contains space
+ * validateQueueName('');              // Throws: empty
+ * ```
+ */
+export declare function validateQueueName(queue: string): void;
+/**
+ * Validates that job data does not exceed the maximum allowed size.
+ *
+ * The size is calculated by JSON-stringifying the data and measuring
+ * the resulting string length in bytes.
+ *
+ * @param data - The job data to validate
+ * @throws ValidationError if the data exceeds MAX_JOB_DATA_SIZE
+ *
+ * @example
+ * ```typescript
+ * validateJobDataSize({ small: 'data' });  // OK
+ * validateJobDataSize(largeBuffer);        // Throws if > 1MB
+ * ```
+ */
+export declare function validateJobDataSize(data: unknown): void;
+/**
+ * Validates batch operation size.
+ *
+ * @param count - Number of items in the batch
+ * @param operation - Name of the operation for error messages
+ * @throws ValidationError if count exceeds MAX_BATCH_SIZE
+ *
+ * @example
+ * ```typescript
+ * validateBatchSize(100, 'push');   // OK
+ * validateBatchSize(1500, 'push');  // Throws: exceeds 1000
+ * ```
+ */
+export declare function validateBatchSize(count: number, operation: string): void;
+/**
+ * Validates a job ID is a positive integer.
+ *
+ * @param jobId - The job ID to validate
+ * @throws ValidationError if jobId is not a positive integer
+ */
+export declare function validateJobId(jobId: number): void;
+/**
+ * Validates a timeout value is within acceptable bounds.
+ *
+ * @param timeout - Timeout in milliseconds
+ * @param min - Minimum allowed value (default: 0)
+ * @param max - Maximum allowed value (default: 10 minutes)
+ * @throws ValidationError if timeout is out of bounds
+ */
+export declare function validateTimeout(timeout: number, min?: number, max?: number): void;
+//# sourceMappingURL=validation.d.ts.map

package/dist/client/validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../src/client/validation.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,mDAAmD;AACnD,eAAO,MAAM,iBAAiB,QAAc,CAAC;AAE7C,iDAAiD;AACjD,eAAO,MAAM,cAAc,OAAO,CAAC;AAKnC;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAUrD;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,CAQvD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CAOxE;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAIjD;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,SAAI,EAAE,GAAG,SAAS,GAAG,IAAI,CAO5E"}