semola 0.5.3 → 0.6.0

package/dist/lib/pubsub/index.mjs

@@ -1,4 +1,30 @@
-import { err, mightThrow, mightThrowSync, ok } from "../errors/index.mjs";
+import { mightThrow, mightThrowSync } from "../errors/index.mjs";
+//#region src/lib/pubsub/errors.ts
+var UnsubscribeError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "UnsubscribeError";
+	}
+};
+var SerializationError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "SerializationError";
+	}
+};
+var PublishError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "PublishError";
+	}
+};
+var SubscribeError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "SubscribeError";
+	}
+};
+//#endregion
 //#region src/lib/pubsub/index.ts
 var PubSub = class {
 	options;
@@ -21,33 +47,32 @@ var PubSub = class {
 		const inFlightUnsubscribe = this.unsubscribeInFlight;
 		if (inFlightUnsubscribe) await inFlightUnsubscribe;
 		const handler = this.handlers.get(handlerId);
-		if (!handler) return err("UnsubscribeError", "Not subscribed");
+		if (!handler) throw new UnsubscribeError("Not subscribed");
 		this.handlers.delete(handlerId);
-		if (this.handlers.size > 0) return ok(true);
+		if (this.handlers.size > 0) return;
 		this.isSubscribed = false;
 		this.unsubscribeInFlight = mightThrow(this.options.subscriber.unsubscribe(this.options.channel));
 		const unsubscribeInFlight = this.unsubscribeInFlight;
 		if (!unsubscribeInFlight) {
 			this.handlers.set(handlerId, handler);
 			this.isSubscribed = true;
-			return err("UnsubscribeError", `Unable to unsubscribe from ${this.options.channel}`);
+			throw new UnsubscribeError(`Unable to unsubscribe from ${this.options.channel}`);
 		}
 		const [unsubscribeError] = await unsubscribeInFlight;
 		if (unsubscribeError) {
 			this.handlers.set(handlerId, handler);
 			this.isSubscribed = true;
 			this.unsubscribeInFlight = null;
-			return err("UnsubscribeError", `Unable to unsubscribe from ${this.options.channel}`);
+			throw new UnsubscribeError(`Unable to unsubscribe from ${this.options.channel}`);
 		}
 		this.unsubscribeInFlight = null;
-		return ok(true);
 	}
 	async publish(message) {
 		const [stringifyError, stringified] = mightThrowSync(() => JSON.stringify(message));
-		if (stringifyError || !stringified) return err("SerializationError", "Unable to serialize message");
+		if (stringifyError || !stringified) throw new SerializationError("Unable to serialize message");
 		const [publishError, count] = await mightThrow(this.options.publisher.publish(this.options.channel, stringified));
-		if (publishError) return err("PublishError", `Unable to publish to ${this.options.channel}`);
-		return ok(count);
+		if (publishError) throw new PublishError(`Unable to publish to ${this.options.channel}`);
+		return count;
 	}
 	async subscribe(handler) {
 		const inFlightUnsubscribe = this.unsubscribeInFlight;
@@ -55,39 +80,39 @@ var PubSub = class {
 		const handlerId = this.nextHandlerId;
 		this.nextHandlerId += 1;
 		this.handlers.set(handlerId, handler);
-		if (this.isActive()) return ok(() => this.unsubscribeHandler(handlerId));
+		if (this.isActive()) return () => this.unsubscribeHandler(handlerId);
 		const inFlightSubscribe = this.subscribeInFlight;
 		if (inFlightSubscribe) {
 			const [inFlightError] = await inFlightSubscribe;
 			if (inFlightError || !this.isSubscribed) {
 				this.handlers.delete(handlerId);
-				return err("SubscribeError", `Unable to subscribe to ${this.options.channel}`);
+				throw new SubscribeError(`Unable to subscribe to ${this.options.channel}`);
 			}
-			return ok(() => this.unsubscribeHandler(handlerId));
+			return () => this.unsubscribeHandler(handlerId);
 		}
 		this.subscribeInFlight = mightThrow(this.options.subscriber.subscribe(this.options.channel, async (message, channel) => this.onMessage(message, channel)));
 		const subscribeInFlight = this.subscribeInFlight;
 		if (!subscribeInFlight) {
 			this.handlers.delete(handlerId);
-			return err("SubscribeError", `Unable to subscribe to ${this.options.channel}`);
+			throw new SubscribeError(`Unable to subscribe to ${this.options.channel}`);
 		}
 		const [subscribeError, count] = await subscribeInFlight;
 		this.subscribeInFlight = null;
 		if (subscribeError) {
 			this.handlers.delete(handlerId);
-			return err("SubscribeError", `Unable to subscribe to ${this.options.channel}`);
+			throw new SubscribeError(`Unable to subscribe to ${this.options.channel}`);
 		}
 		if (!count) {
 			this.handlers.delete(handlerId);
-			return err("SubscribeError", `Unable to subscribe to ${this.options.channel}`);
+			throw new SubscribeError(`Unable to subscribe to ${this.options.channel}`);
 		}
 		this.isSubscribed = true;
-		return ok(() => this.unsubscribeHandler(handlerId));
+		return () => this.unsubscribeHandler(handlerId);
 	}
 	async unsubscribe() {
 		const inFlightUnsubscribe = this.unsubscribeInFlight;
 		if (inFlightUnsubscribe) await inFlightUnsubscribe;
-		if (!this.isActive()) return err("UnsubscribeError", "Not subscribed");
+		if (!this.isActive()) throw new UnsubscribeError("Not subscribed");
 		const handlers = new Map(this.handlers);
 		this.handlers.clear();
 		this.isSubscribed = false;
@@ -96,17 +121,16 @@ var PubSub = class {
 		if (!unsubscribeInFlight) {
 			this.handlers = handlers;
 			this.isSubscribed = true;
-			return err("UnsubscribeError", `Unable to unsubscribe from ${this.options.channel}`);
+			throw new UnsubscribeError(`Unable to unsubscribe from ${this.options.channel}`);
 		}
 		const [unsubscribeError] = await unsubscribeInFlight;
 		if (unsubscribeError) {
 			this.handlers = handlers;
 			this.isSubscribed = true;
 			this.unsubscribeInFlight = null;
-			return err("UnsubscribeError", `Unable to unsubscribe from ${this.options.channel}`);
+			throw new UnsubscribeError(`Unable to unsubscribe from ${this.options.channel}`);
 		}
 		this.unsubscribeInFlight = null;
-		return ok(true);
 	}
 	isActive() {
 		return this.handlers.size > 0 && this.isSubscribed;
@@ -114,5 +138,3 @@ var PubSub = class {
 };
 //#endregion
 export { PubSub };
-
-//# sourceMappingURL=index.mjs.map

package/dist/lib/queue/index.cjs

@@ -1,5 +1,22 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_chunk = require("../../chunk-CKQMccvm.cjs");
 const require_lib_errors_index = require("../errors/index.cjs");
+let node_assert = require("node:assert");
+node_assert = require_chunk.__toESM(node_assert);
+//#region src/lib/queue/errors.ts
+var SerializationError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "SerializationError";
+	}
+};
+var EnqueueError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "EnqueueError";
+	}
+};
+//#endregion
 //#region src/lib/queue/index.ts
 const toMinimalJob = (jobState) => ({
 	id: jobState.id,
@@ -12,9 +29,9 @@ const DEFAULT_RETRIES = 3;
 const DEFAULT_TIMEOUT = 3e4;
 const DEFAULT_CONCURRENCY = 1;
 const DEFAULT_POLL_INTERVAL = 100;
-const MAX_BACKOFF_DELAY = 6e4;
-const BASE_BACKOFF_DELAY = 1e3;
-const BACKOFF_MULTIPLIER = 2;
+const DEFAULT_RETRY_MAX_DELAY = 6e4;
+const DEFAULT_RETRY_BASE_DELAY = 1e3;
+const DEFAULT_RETRY_MULTIPLIER = 2;
 const SHUTDOWN_POLL_INTERVAL = 10;
 var Queue = class {
 	options;
@@ -24,14 +41,26 @@ var Queue = class {
 	timeout;
 	concurrency;
 	pollInterval;
+	retryBaseDelay;
+	retryMultiplier;
+	retryMaxDelay;
 	constructor(options) {
 		this.options = options;
 		this.retries = options.retries ?? DEFAULT_RETRIES;
 		this.timeout = options.timeout ?? DEFAULT_TIMEOUT;
 		this.concurrency = options.concurrency ?? DEFAULT_CONCURRENCY;
 		this.pollInterval = options.pollInterval ?? DEFAULT_POLL_INTERVAL;
+		this.retryBaseDelay = options.retryBackoff?.baseDelay ?? DEFAULT_RETRY_BASE_DELAY;
+		this.retryMultiplier = options.retryBackoff?.multiplier ?? DEFAULT_RETRY_MULTIPLIER;
+		this.retryMaxDelay = options.retryBackoff?.maxDelay ?? DEFAULT_RETRY_MAX_DELAY;
+		node_assert.default.ok(Number.isFinite(this.retryBaseDelay) && this.retryBaseDelay > 0, "Invalid retryBackoff.baseDelay: must be a positive finite number");
+		node_assert.default.ok(Number.isFinite(this.retryMultiplier) && this.retryMultiplier > 0, "Invalid retryBackoff.multiplier: must be a positive finite number");
+		node_assert.default.ok(Number.isFinite(this.retryMaxDelay) && this.retryMaxDelay > 0, "Invalid retryBackoff.maxDelay: must be a positive finite number");
 		this.startWorkers();
 	}
+	computeBackoffDelay(attempt) {
+		return Math.min(this.retryBaseDelay * this.retryMultiplier ** (attempt - 1), this.retryMaxDelay);
+	}
 	async enqueue(data) {
 		const job = {
 			id: crypto.randomUUID(),
@@ -41,10 +70,10 @@ var Queue = class {
 			createdAt: Date.now()
 		};
 		const [serializeError, serialized] = this.serializeJob(job);
-		if (serializeError || !serialized) return require_lib_errors_index.err("QueueError", "Unable to serialize job data");
+		if (serializeError || !serialized) throw new SerializationError("Unable to serialize job data");
 		const [enqueueError] = await this.enqueueJobData(serialized);
-		if (enqueueError) return require_lib_errors_index.err("QueueError", "Unable to enqueue job");
-		return require_lib_errors_index.ok(job.id);
+		if (enqueueError) throw new EnqueueError("Unable to enqueue job");
+		return job.id;
 	}
 	async stop() {
 		this.running = false;
@@ -70,7 +99,8 @@ var Queue = class {
 		return require_lib_errors_index.mightThrow(this.options.redis.lpush(deadLetterKey, deadLetterEntry));
 	}
 	formatErrorMessage(error) {
-		return error instanceof Error ? error.message : String(error);
+		if (!error) return "Unknown error";
+		return error.message;
 	}
 	startWorkers() {
 		for (let i = 0; i < this.concurrency; i++) this.processJobs();
@@ -131,13 +161,13 @@ var Queue = class {
 		});
 		if (job.attempts <= job.maxRetries) {
 			if (this.options.onRetry) {
-				const delay = Math.min(BASE_BACKOFF_DELAY * BACKOFF_MULTIPLIER ** (job.attempts - 1), MAX_BACKOFF_DELAY);
+				const delay = this.computeBackoffDelay(job.attempts);
 				await require_lib_errors_index.mightThrow(Promise.resolve(this.options.onRetry({
 					job: toMinimalJob(job),
 					error: errorMsg,
 					nextRetryDelayMs: delay,
 					retriesRemaining: job.maxRetries - job.attempts,
-					backoffMultiplier: BACKOFF_MULTIPLIER
+					backoffMultiplier: this.retryMultiplier
 				})));
 			}
 			await this.retryJob(job);
@@ -162,7 +192,7 @@ var Queue = class {
 		})));
 	}
 	async retryJob(job) {
-		const delay = Math.min(BASE_BACKOFF_DELAY * BACKOFF_MULTIPLIER ** (job.attempts - 1), MAX_BACKOFF_DELAY);
+		const delay = this.computeBackoffDelay(job.attempts);
 		await new Promise((resolve) => setTimeout(resolve, delay));
 		const [stringifyError, serialized] = this.serializeJob(job);
 		if (stringifyError || !serialized) {

package/dist/lib/queue/index.d.cts

@@ -1,5 +1,54 @@
-import { QueueOptions } from "../../queue/types.cjs";
-
+//#region src/lib/queue/types.d.ts
+type Job<T> = {
+  id: string;
+  data: T;
+  attempts: number;
+  maxRetries: number;
+  createdAt: number;
+};
+type RetryContext<T> = {
+  job: Job<T>;
+  error: string;
+  nextRetryDelayMs: number;
+  retriesRemaining: number;
+  backoffMultiplier: number;
+};
+type ErrorContext<T> = {
+  job: Job<T>;
+  lastError: string;
+  totalDurationMs: number;
+  totalAttempts: number;
+  errorHistory: Array<{
+    attempt: number;
+    error: string;
+    timestamp: number;
+  }>;
+};
+type ParseErrorContext = {
+  rawJobData: string;
+  parseError: string;
+  timestamp: number;
+};
+type QueueRetryBackoff = {
+  baseDelay?: number;
+  multiplier?: number;
+  maxDelay?: number;
+};
+type QueueOptions<T> = {
+  name: string;
+  redis: Bun.RedisClient;
+  handler: (data: T, signal?: AbortSignal) => void | Promise<void>;
+  onSuccess?: (job: Job<T>) => void | Promise<void>;
+  onRetry?: (context: RetryContext<T>) => void | Promise<void>;
+  onError?: (context: ErrorContext<T>) => void | Promise<void>;
+  onParseError?: (context: ParseErrorContext) => void | Promise<void>;
+  retries?: number;
+  retryBackoff?: QueueRetryBackoff;
+  timeout?: number;
+  concurrency?: number;
+  pollInterval?: number;
+};
+//#endregion
 //#region src/lib/queue/index.d.ts
 declare class Queue<T> {
   private options;
@@ -9,11 +58,12 @@ declare class Queue<T> {
   private timeout;
   private concurrency;
   private pollInterval;
+  private retryBaseDelay;
+  private retryMultiplier;
+  private retryMaxDelay;
   constructor(options: QueueOptions<T>);
-  enqueue(data: T): Promise<readonly [{
-    readonly type: "QueueError";
-    readonly message: string;
-  }, null] | readonly [null, string]>;
+  private computeBackoffDelay;
+  enqueue(data: T): Promise<string>;
   stop(): Promise<void>;
   private waitForPollInterval;
   private serializeJob;
@@ -28,5 +78,4 @@ declare class Queue<T> {
   private retryJob;
 }
 //#endregion
-export { Queue };
-//# sourceMappingURL=index.d.cts.map
+export { Queue };

package/dist/lib/queue/index.d.mts

@@ -1,5 +1,54 @@
-import { QueueOptions } from "../../queue/types.mjs";
-
+//#region src/lib/queue/types.d.ts
+type Job<T> = {
+  id: string;
+  data: T;
+  attempts: number;
+  maxRetries: number;
+  createdAt: number;
+};
+type RetryContext<T> = {
+  job: Job<T>;
+  error: string;
+  nextRetryDelayMs: number;
+  retriesRemaining: number;
+  backoffMultiplier: number;
+};
+type ErrorContext<T> = {
+  job: Job<T>;
+  lastError: string;
+  totalDurationMs: number;
+  totalAttempts: number;
+  errorHistory: Array<{
+    attempt: number;
+    error: string;
+    timestamp: number;
+  }>;
+};
+type ParseErrorContext = {
+  rawJobData: string;
+  parseError: string;
+  timestamp: number;
+};
+type QueueRetryBackoff = {
+  baseDelay?: number;
+  multiplier?: number;
+  maxDelay?: number;
+};
+type QueueOptions<T> = {
+  name: string;
+  redis: Bun.RedisClient;
+  handler: (data: T, signal?: AbortSignal) => void | Promise<void>;
+  onSuccess?: (job: Job<T>) => void | Promise<void>;
+  onRetry?: (context: RetryContext<T>) => void | Promise<void>;
+  onError?: (context: ErrorContext<T>) => void | Promise<void>;
+  onParseError?: (context: ParseErrorContext) => void | Promise<void>;
+  retries?: number;
+  retryBackoff?: QueueRetryBackoff;
+  timeout?: number;
+  concurrency?: number;
+  pollInterval?: number;
+};
+//#endregion
 //#region src/lib/queue/index.d.ts
 declare class Queue<T> {
   private options;
@@ -9,11 +58,12 @@ declare class Queue<T> {
   private timeout;
   private concurrency;
   private pollInterval;
+  private retryBaseDelay;
+  private retryMultiplier;
+  private retryMaxDelay;
   constructor(options: QueueOptions<T>);
-  enqueue(data: T): Promise<readonly [{
-    readonly type: "QueueError";
-    readonly message: string;
-  }, null] | readonly [null, string]>;
+  private computeBackoffDelay;
+  enqueue(data: T): Promise<string>;
   stop(): Promise<void>;
   private waitForPollInterval;
   private serializeJob;
@@ -28,5 +78,4 @@ declare class Queue<T> {
   private retryJob;
 }
 //#endregion
-export { Queue };
-//# sourceMappingURL=index.d.mts.map
+export { Queue };

package/dist/lib/queue/index.mjs

@@ -1,4 +1,19 @@
-import { err, mightThrow, mightThrowSync, ok } from "../errors/index.mjs";
+import { mightThrow, mightThrowSync } from "../errors/index.mjs";
+import assert from "node:assert";
+//#region src/lib/queue/errors.ts
+var SerializationError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "SerializationError";
+	}
+};
+var EnqueueError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "EnqueueError";
+	}
+};
+//#endregion
 //#region src/lib/queue/index.ts
 const toMinimalJob = (jobState) => ({
 	id: jobState.id,
@@ -11,9 +26,9 @@ const DEFAULT_RETRIES = 3;
 const DEFAULT_TIMEOUT = 3e4;
 const DEFAULT_CONCURRENCY = 1;
 const DEFAULT_POLL_INTERVAL = 100;
-const MAX_BACKOFF_DELAY = 6e4;
-const BASE_BACKOFF_DELAY = 1e3;
-const BACKOFF_MULTIPLIER = 2;
+const DEFAULT_RETRY_MAX_DELAY = 6e4;
+const DEFAULT_RETRY_BASE_DELAY = 1e3;
+const DEFAULT_RETRY_MULTIPLIER = 2;
 const SHUTDOWN_POLL_INTERVAL = 10;
 var Queue = class {
 	options;
@@ -23,14 +38,26 @@ var Queue = class {
 	timeout;
 	concurrency;
 	pollInterval;
+	retryBaseDelay;
+	retryMultiplier;
+	retryMaxDelay;
 	constructor(options) {
 		this.options = options;
 		this.retries = options.retries ?? DEFAULT_RETRIES;
 		this.timeout = options.timeout ?? DEFAULT_TIMEOUT;
 		this.concurrency = options.concurrency ?? DEFAULT_CONCURRENCY;
 		this.pollInterval = options.pollInterval ?? DEFAULT_POLL_INTERVAL;
+		this.retryBaseDelay = options.retryBackoff?.baseDelay ?? DEFAULT_RETRY_BASE_DELAY;
+		this.retryMultiplier = options.retryBackoff?.multiplier ?? DEFAULT_RETRY_MULTIPLIER;
+		this.retryMaxDelay = options.retryBackoff?.maxDelay ?? DEFAULT_RETRY_MAX_DELAY;
+		assert.ok(Number.isFinite(this.retryBaseDelay) && this.retryBaseDelay > 0, "Invalid retryBackoff.baseDelay: must be a positive finite number");
+		assert.ok(Number.isFinite(this.retryMultiplier) && this.retryMultiplier > 0, "Invalid retryBackoff.multiplier: must be a positive finite number");
+		assert.ok(Number.isFinite(this.retryMaxDelay) && this.retryMaxDelay > 0, "Invalid retryBackoff.maxDelay: must be a positive finite number");
 		this.startWorkers();
 	}
+	computeBackoffDelay(attempt) {
+		return Math.min(this.retryBaseDelay * this.retryMultiplier ** (attempt - 1), this.retryMaxDelay);
+	}
 	async enqueue(data) {
 		const job = {
 			id: crypto.randomUUID(),
@@ -40,10 +67,10 @@ var Queue = class {
 			createdAt: Date.now()
 		};
 		const [serializeError, serialized] = this.serializeJob(job);
-		if (serializeError || !serialized) return err("QueueError", "Unable to serialize job data");
+		if (serializeError || !serialized) throw new SerializationError("Unable to serialize job data");
 		const [enqueueError] = await this.enqueueJobData(serialized);
-		if (enqueueError) return err("QueueError", "Unable to enqueue job");
-		return ok(job.id);
+		if (enqueueError) throw new EnqueueError("Unable to enqueue job");
+		return job.id;
 	}
 	async stop() {
 		this.running = false;
@@ -69,7 +96,8 @@ var Queue = class {
 		return mightThrow(this.options.redis.lpush(deadLetterKey, deadLetterEntry));
 	}
 	formatErrorMessage(error) {
-		return error instanceof Error ? error.message : String(error);
+		if (!error) return "Unknown error";
+		return error.message;
 	}
 	startWorkers() {
 		for (let i = 0; i < this.concurrency; i++) this.processJobs();
@@ -130,13 +158,13 @@ var Queue = class {
 		});
 		if (job.attempts <= job.maxRetries) {
 			if (this.options.onRetry) {
-				const delay = Math.min(BASE_BACKOFF_DELAY * BACKOFF_MULTIPLIER ** (job.attempts - 1), MAX_BACKOFF_DELAY);
+				const delay = this.computeBackoffDelay(job.attempts);
 				await mightThrow(Promise.resolve(this.options.onRetry({
 					job: toMinimalJob(job),
 					error: errorMsg,
 					nextRetryDelayMs: delay,
 					retriesRemaining: job.maxRetries - job.attempts,
-					backoffMultiplier: BACKOFF_MULTIPLIER
+					backoffMultiplier: this.retryMultiplier
 				})));
 			}
 			await this.retryJob(job);
@@ -161,7 +189,7 @@ var Queue = class {
 		})));
 	}
 	async retryJob(job) {
-		const delay = Math.min(BASE_BACKOFF_DELAY * BACKOFF_MULTIPLIER ** (job.attempts - 1), MAX_BACKOFF_DELAY);
+		const delay = this.computeBackoffDelay(job.attempts);
 		await new Promise((resolve) => setTimeout(resolve, delay));
 		const [stringifyError, serialized] = this.serializeJob(job);
 		if (stringifyError || !serialized) {
@@ -179,5 +207,3 @@ var Queue = class {
 };
 //#endregion
 export { Queue };
-
-//# sourceMappingURL=index.mjs.map