@upyo/pool 0.3.0-dev.36

package/dist/index.js

@@ -0,0 +1,396 @@
+//#region src/config.ts
+/**
+* Creates a resolved pool configuration with defaults applied.
+*
+* @param config The pool configuration.
+* @returns The resolved configuration with defaults.
+* @throws {Error} If the configuration is invalid.
+* @since 0.3.0
+*/
+function createPoolConfig(config) {
+	if (!config.transports || config.transports.length === 0) throw new Error("Pool must have at least one transport");
+	const enabledTransports = config.transports.filter((entry) => entry.enabled !== false);
+	if (enabledTransports.length === 0) throw new Error("Pool must have at least one enabled transport");
+	const resolvedTransports = config.transports.map((entry) => ({
+		transport: entry.transport,
+		weight: entry.weight ?? 1,
+		priority: entry.priority ?? 0,
+		selector: entry.selector,
+		enabled: entry.enabled ?? true
+	}));
+	if (config.strategy === "weighted") {
+		const hasValidWeights = resolvedTransports.some((entry) => entry.enabled && entry.weight > 0);
+		if (!hasValidWeights) throw new Error("Weighted strategy requires at least one enabled transport with positive weight");
+	}
+	return {
+		strategy: config.strategy,
+		transports: resolvedTransports,
+		maxRetries: config.maxRetries ?? enabledTransports.length,
+		timeout: config.timeout,
+		continueOnSuccess: config.continueOnSuccess ?? false
+	};
+}
+
+//#endregion
+//#region src/strategies/round-robin-strategy.ts
+/**
+* Round-robin strategy that cycles through transports in order.
+*
+* This strategy maintains an internal counter and selects transports
+* in a circular fashion, ensuring even distribution of messages across
+* all enabled transports.
+* @since 0.3.0
+*/
+var RoundRobinStrategy = class {
+	currentIndex = 0;
+	/**
+	* Selects the next transport in round-robin order.
+	*
+	* @param _message The message to send (unused in this strategy).
+	* @param transports Available transports.
+	* @param attemptedIndices Indices of transports that have already been
+	*                         attempted.
+	* @returns The selected transport or `undefined` if all transports have been
+	*          attempted.
+	*/
+	select(_message, transports, attemptedIndices) {
+		const enabledCount = transports.filter((t) => t.enabled).length;
+		if (enabledCount < 1) return void 0;
+		for (let attempts = 0; attempts < enabledCount; attempts++) {
+			while (!transports[this.currentIndex].enabled) this.currentIndex = (this.currentIndex + 1) % transports.length;
+			const index = this.currentIndex;
+			const entry = transports[index];
+			this.currentIndex = (this.currentIndex + 1) % transports.length;
+			if (attemptedIndices.has(index)) continue;
+			return {
+				entry,
+				index
+			};
+		}
+		return void 0;
+	}
+	/**
+	* Resets the round-robin counter to start from the beginning.
+	*/
+	reset() {
+		this.currentIndex = 0;
+	}
+};
+
+//#endregion
+//#region src/strategies/weighted-strategy.ts
+/**
+* Weighted strategy that distributes traffic based on configured weights.
+*
+* This strategy uses weighted random selection to distribute messages
+* across transports proportionally to their configured weights.
+* A transport with weight 2 will receive approximately twice as many
+* messages as a transport with weight 1.
+* @since 0.3.0
+*/
+var WeightedStrategy = class {
+	/**
+	* Selects a transport based on weighted random distribution.
+	*
+	* @param _message The message to send (unused in this strategy).
+	* @param transports Available transports.
+	* @param attemptedIndices Indices of transports that have already been
+	*                         attempted.
+	* @returns The selected transport or `undefined` if all transports have been
+	*          attempted.
+	*/
+	select(_message, transports, attemptedIndices) {
+		const availableTransports = transports.map((entry, index) => ({
+			entry,
+			index
+		})).filter(({ entry, index }) => entry.enabled && entry.weight > 0 && !attemptedIndices.has(index));
+		if (availableTransports.length < 1) return void 0;
+		const totalWeight = availableTransports.reduce((sum, { entry }) => sum + entry.weight, 0);
+		if (totalWeight <= 0) return void 0;
+		const random = Math.random() * totalWeight;
+		let cumulativeWeight = 0;
+		for (const { entry, index } of availableTransports) {
+			cumulativeWeight += entry.weight;
+			if (random < cumulativeWeight) return {
+				entry,
+				index
+			};
+		}
+		const last = availableTransports[availableTransports.length - 1];
+		return {
+			entry: last.entry,
+			index: last.index
+		};
+	}
+	/**
+	* Resets the strategy (no-op for weighted strategy as it's stateless).
+	*/
+	reset() {}
+};
+
+//#endregion
+//#region src/strategies/priority-strategy.ts
+/**
+* Priority strategy that selects transports based on priority values.
+*
+* This strategy always attempts to use the highest priority transport
+* first, falling back to lower priority transports only when higher
+* priority ones fail. Transports with the same priority are considered
+* equivalent and one is selected randomly.
+* @since 0.3.0
+*/
+var PriorityStrategy = class {
+	/**
+	* Selects the highest priority transport that hasn't been attempted.
+	*
+	* @param _message The message to send (unused in this strategy).
+	* @param transports Available transports.
+	* @param attemptedIndices Indices of transports that have already been
+	*                         attempted.
+	* @returns The selected transport or `undefined` if all transports have been
+	*          attempted.
+	*/
+	select(_message, transports, attemptedIndices) {
+		const availableTransports = transports.map((entry, index) => ({
+			entry,
+			index
+		})).filter(({ entry, index }) => entry.enabled && !attemptedIndices.has(index));
+		if (availableTransports.length < 1) return void 0;
+		availableTransports.sort((a, b) => b.entry.priority - a.entry.priority);
+		const highestPriority = availableTransports[0].entry.priority;
+		const topPriorityTransports = availableTransports.filter(({ entry }) => entry.priority === highestPriority);
+		if (topPriorityTransports.length > 1) {
+			const randomIndex = Math.floor(Math.random() * topPriorityTransports.length);
+			return topPriorityTransports[randomIndex];
+		}
+		return topPriorityTransports[0];
+	}
+	/**
+	* Resets the strategy (no-op for priority strategy as it's stateless).
+	*/
+	reset() {}
+};
+
+//#endregion
+//#region src/strategies/selector-strategy.ts
+/**
+* Selector strategy that routes messages based on custom selector functions.
+*
+* This strategy evaluates each transport's selector function (if provided)
+* to determine if it should handle a specific message. Transports without
+* selectors are considered as catch-all fallbacks. Among matching transports,
+* one is selected randomly.
+* @since 0.3.0
+*/
+var SelectorStrategy = class {
+	/**
+	* Selects a transport based on selector function matching.
+	*
+	* @param message The message to send.
+	* @param transports Available transports.
+	* @param attemptedIndices Indices of transports that have already been
+	*                         attempted.
+	* @returns The selected transport or `undefined` if no transport matches.
+	*/
+	select(message, transports, attemptedIndices) {
+		const availableTransports = transports.map((entry, index) => ({
+			entry,
+			index
+		})).filter(({ entry, index }) => entry.enabled && !attemptedIndices.has(index));
+		if (availableTransports.length < 1) return void 0;
+		const withSelectors = [];
+		const withoutSelectors = [];
+		for (const transport of availableTransports) if (transport.entry.selector) try {
+			if (transport.entry.selector(message)) withSelectors.push(transport);
+		} catch {}
+		else withoutSelectors.push(transport);
+		const candidates = withSelectors.length > 0 ? withSelectors : withoutSelectors;
+		if (candidates.length < 1) return void 0;
+		const randomIndex = Math.floor(Math.random() * candidates.length);
+		return candidates[randomIndex];
+	}
+	/**
+	* Resets the strategy (no-op for selector strategy as it's stateless).
+	*/
+	reset() {}
+};
+
+//#endregion
+//#region src/pool-transport.ts
+/**
+* Pool transport that combines multiple transports with various load balancing
+* and failover strategies.
+*
+* This transport implements the same `Transport` interface, making it a drop-in
+* replacement for any single transport. It distributes messages across multiple
+* underlying transports based on the configured strategy.
+*
+* @example Round-robin load balancing
+* ```typescript
+* import { PoolTransport } from "@upyo/pool";
+*
+* const transport = new PoolTransport({
+*   strategy: "round-robin",
+*   transports: [
+*     { transport: mailgunTransport },
+*     { transport: sendgridTransport },
+*     { transport: sesTransport },
+*   ],
+* });
+* ```
+*
+* @example Priority-based failover
+* ```typescript
+* const transport = new PoolTransport({
+*   strategy: "priority",
+*   transports: [
+*     { transport: primaryTransport, priority: 100 },
+*     { transport: backupTransport, priority: 50 },
+*     { transport: lastResortTransport, priority: 10 },
+*   ],
+* });
+* ```
+*
+* @example Custom routing with selectors
+* ```typescript
+* const transport = new PoolTransport({
+*   strategy: "selector-based",
+*   transports: [
+*     {
+*       transport: bulkEmailTransport,
+*       selector: (msg) => msg.tags?.includes("newsletter"),
+*     },
+*     {
+*       transport: transactionalTransport,
+*       selector: (msg) => msg.priority === "high",
+*     },
+*     { transport: defaultTransport }, // Catches everything else
+*   ],
+* });
+* ```
+*
+* @since 0.3.0
+*/
+var PoolTransport = class {
+	/**
+	* The resolved configuration used by this pool transport.
+	*/
+	config;
+	strategy;
+	/**
+	* Creates a new PoolTransport instance.
+	*
+	* @param config Configuration options for the pool transport.
+	* @throws {Error} If the configuration is invalid.
+	*/
+	constructor(config) {
+		this.config = createPoolConfig(config);
+		this.strategy = this.createStrategy(this.config.strategy);
+	}
+	/**
+	* Sends a single email message using the pool strategy.
+	*
+	* The transport is selected based on the configured strategy. If the
+	* selected transport fails, the pool will retry with other transports
+	* up to the configured retry limit.
+	*
+	* @param message The email message to send.
+	* @param options Optional transport options including abort signal.
+	* @returns A promise that resolves to a receipt indicating success or failure.
+	*/
+	async send(message, options) {
+		const attemptedIndices = /* @__PURE__ */ new Set();
+		const errors = [];
+		for (let attempt = 0; attempt < this.config.maxRetries; attempt++) {
+			if (options?.signal?.aborted) throw new DOMException("The operation was aborted.", "AbortError");
+			const selection = this.strategy.select(message, this.config.transports, attemptedIndices);
+			if (!selection) break;
+			attemptedIndices.add(selection.index);
+			try {
+				const sendOptions = this.createSendOptions(options);
+				const receipt = await selection.entry.transport.send(message, sendOptions);
+				if (receipt.successful) return receipt;
+				errors.push(...receipt.errorMessages);
+			} catch (error) {
+				if (error instanceof DOMException && error.name === "AbortError") throw error;
+				const errorMessage = error instanceof Error ? error.message : String(error);
+				errors.push(errorMessage);
+			}
+		}
+		return {
+			successful: false,
+			errorMessages: errors.length > 0 ? errors : ["All transports failed to send the message"]
+		};
+	}
+	/**
+	* Sends multiple email messages using the pool strategy.
+	*
+	* Each message is sent individually using the `send` method, respecting
+	* the configured strategy and retry logic.
+	*
+	* @param messages An iterable or async iterable of messages to send.
+	* @param options Optional transport options including abort signal.
+	* @returns An async iterable of receipts, one for each message.
+	*/
+	async *sendMany(messages, options) {
+		this.strategy.reset();
+		for await (const message of messages) {
+			if (options?.signal?.aborted) throw new DOMException("The operation was aborted.", "AbortError");
+			yield await this.send(message, options);
+		}
+	}
+	/**
+	* Disposes of all underlying transports that support disposal.
+	*
+	* This method is called automatically when using the `await using` syntax.
+	* It ensures proper cleanup of resources held by the underlying transports.
+	*/
+	async [Symbol.asyncDispose]() {
+		const disposalPromises = [];
+		for (const entry of this.config.transports) {
+			const transport = entry.transport;
+			if (typeof transport[Symbol.asyncDispose] === "function") {
+				const asyncDispose = transport[Symbol.asyncDispose]();
+				disposalPromises.push(Promise.resolve(asyncDispose));
+			} else if (typeof transport[Symbol.dispose] === "function") try {
+				transport[Symbol.dispose]();
+			} catch {}
+		}
+		await Promise.allSettled(disposalPromises);
+	}
+	/**
+	* Creates a strategy instance based on the strategy type or returns the provided strategy.
+	*/
+	createStrategy(strategy) {
+		if (typeof strategy === "object" && strategy !== null) return strategy;
+		switch (strategy) {
+			case "round-robin": return new RoundRobinStrategy();
+			case "weighted": return new WeightedStrategy();
+			case "priority": return new PriorityStrategy();
+			case "selector-based": return new SelectorStrategy();
+			default: throw new Error(`Unknown strategy: ${strategy}`);
+		}
+	}
+	/**
+	* Creates send options with timeout if configured.
+	*/
+	createSendOptions(options) {
+		if (!this.config.timeout) return options;
+		const controller = new AbortController();
+		const timeoutId = setTimeout(() => controller.abort(), this.config.timeout);
+		if (options?.signal) options.signal.addEventListener("abort", () => {
+			clearTimeout(timeoutId);
+			controller.abort();
+		});
+		controller.signal.addEventListener("abort", () => {
+			clearTimeout(timeoutId);
+		});
+		return {
+			...options,
+			signal: controller.signal
+		};
+	}
+};
+
+//#endregion
+export { PoolTransport, PriorityStrategy, RoundRobinStrategy, SelectorStrategy, WeightedStrategy };

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "@upyo/pool",
+  "version": "0.3.0-dev.36+e7618f03",
+  "description": "Pool transport for Upyo email library—provides load balancing and failover for multiple email providers",
+  "keywords": [
+    "email",
+    "mail",
+    "pool",
+    "load-balancing",
+    "failover",
+    "round-robin",
+    "weighted"
+  ],
+  "license": "MIT",
+  "author": {
+    "name": "Hong Minhee",
+    "email": "hong@minhee.org",
+    "url": "https://hongminhee.org/"
+  },
+  "homepage": "https://upyo.org/transports/pool",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dahlia/upyo.git",
+    "directory": "packages/pool/"
+  },
+  "bugs": {
+    "url": "https://github.com/dahlia/upyo/issues"
+  },
+  "funding": [
+    "https://github.com/sponsors/dahlia"
+  ],
+  "engines": {
+    "node": ">=20.0.0",
+    "bun": ">=1.2.0",
+    "deno": ">=2.3.0"
+  },
+  "files": [
+    "dist/",
+    "package.json",
+    "README.md"
+  ],
+  "type": "module",
+  "module": "./dist/index.js",
+  "main": "./dist/index.cjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": {
+        "import": "./dist/index.d.ts",
+        "require": "./dist/index.d.cts"
+      },
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "sideEffects": false,
+  "peerDependencies": {
+    "@upyo/core": "0.3.0-dev.36+e7618f03"
+  },
+  "devDependencies": {
+    "@dotenvx/dotenvx": "^1.47.3",
+    "tsdown": "^0.12.7",
+    "typescript": "5.8.3",
+    "@upyo/mock": "0.3.0-dev.36+e7618f03"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "prepublish": "tsdown",
+    "test": "tsdown && dotenvx run --ignore=MISSING_ENV_FILE -- node --experimental-transform-types --test",
+    "test:bun": "tsdown && bun test --timeout=30000 --env-file=.env",
+    "test:deno": "deno test --allow-env --env-file=.env"
+  }
+}