@upyo/mock 0.1.0-dev.17

package/dist/index.js

@@ -0,0 +1,335 @@
+//#region src/config.ts
+/**
+* Creates a resolved mock configuration by applying default values to optional fields.
+*
+* This function takes a partial mock configuration and returns a complete
+* configuration with all optional fields filled with sensible defaults.
+*
+* @param config - The mock configuration with optional fields
+* @returns A resolved configuration with all defaults applied
+*
+* @example
+* ```typescript
+* const resolved = createMockConfig({
+*   delay: 100
+* });
+*
+* // resolved.defaultResponse will be { successful: true, messageId: "mock-message-id" }
+* // resolved.failureRate will be 0 (default)
+* // resolved.generateUniqueMessageIds will be true (default)
+* ```
+*/
+function createMockConfig(config = {}) {
+	return {
+		defaultResponse: config.defaultResponse ?? {
+			successful: true,
+			messageId: "mock-message-id"
+		},
+		delay: config.delay ?? 0,
+		randomDelayRange: config.randomDelayRange ?? {
+			min: 0,
+			max: 0
+		},
+		failureRate: config.failureRate ?? 0,
+		generateUniqueMessageIds: config.generateUniqueMessageIds ?? true
+	};
+}
+
+//#endregion
+//#region src/mock-transport.ts
+/**
+* A mock transport implementation for testing purposes.
+*
+* This transport doesn't actually send emails but stores them in memory,
+* making it useful for unit testing email functionality. It provides
+* comprehensive testing capabilities including message verification,
+* behavior simulation, and async utilities.
+*/
+var MockTransport = class {
+	/**
+	* The resolved configuration used by this mock transport.
+	*/
+	config;
+	sentMessages = [];
+	nextResponse = null;
+	messageIdCounter = 1;
+	/**
+	* Creates a new MockTransport instance.
+	*
+	* @param config Configuration options for the mock transport behavior.
+	*/
+	constructor(config = {}) {
+		this.config = createMockConfig(config);
+	}
+	/**
+	* Sends an email message through the mock transport.
+	*
+	* The message is stored in memory and can be retrieved for testing verification.
+	* Respects configured delays, failure rates, and response overrides.
+	*
+	* @param message The email message to send.
+	* @param options Transport options including abort signal.
+	* @returns A promise that resolves to a receipt indicating success or failure.
+	* @throws {DOMException} When the operation is aborted via `AbortSignal`.
+	*/
+	async send(message, options) {
+		if (options?.signal?.aborted) throw new DOMException("The operation was aborted.", "AbortError");
+		await this.applyDelay();
+		if (options?.signal?.aborted) throw new DOMException("The operation was aborted.", "AbortError");
+		this.sentMessages.push(message);
+		const response = this.getResponse();
+		return response;
+	}
+	/**
+	* Sends multiple email messages through the mock transport.
+	*
+	* Each message is processed sequentially using the send() method, respecting
+	* all configured behavior including delays and failure rates.
+	*
+	* @param messages An iterable or async iterable of messages to send.
+	* @param options Transport options including abort signal.
+	* @returns An async iterable of receipts, one for each message.
+	* @throws {DOMException} When the operation is aborted via `AbortSignal`.
+	*/
+	async *sendMany(messages, options) {
+		for await (const message of messages) {
+			if (options?.signal?.aborted) throw new DOMException("The operation was aborted.", "AbortError");
+			yield await this.send(message, options);
+		}
+	}
+	/**
+	* Get all messages that have been "sent" through this transport.
+	*
+	* @returns A readonly array containing copies of all sent messages.
+	*/
+	getSentMessages() {
+		return [...this.sentMessages];
+	}
+	/**
+	* Get the last message that was sent, or undefined if no messages have been sent.
+	*
+	* @returns The most recently sent message, or undefined if none.
+	*/
+	getLastSentMessage() {
+		return this.sentMessages[this.sentMessages.length - 1];
+	}
+	/**
+	* Get the total number of messages that have been sent.
+	*
+	* @returns The count of messages sent through this transport.
+	*/
+	getSentMessagesCount() {
+		return this.sentMessages.length;
+	}
+	/**
+	* Clear all stored messages.
+	*
+	* This removes all messages from the internal storage but does not
+	* reset other configuration like delays or failure rates.
+	*/
+	clearSentMessages() {
+		this.sentMessages = [];
+	}
+	/**
+	* Set the response that will be returned for the next send operation.
+	*
+	* After being used once, it will revert to the default response.
+	* This is useful for testing specific success or failure scenarios.
+	*
+	* @param receipt The receipt to return for the next send operation.
+	*/
+	setNextResponse(receipt) {
+		this.nextResponse = receipt;
+	}
+	/**
+	* Set the default response that will be returned for send operations.
+	*
+	* This response is used when no next response is set and random failures
+	* are not triggered.
+	*
+	* @param receipt The default receipt to return for send operations.
+	*/
+	setDefaultResponse(receipt) {
+		this.config = {
+			...this.config,
+			defaultResponse: receipt
+		};
+	}
+	/**
+	* Set the failure rate (0.0 to 1.0). When set, sends will randomly fail
+	* at the specified rate instead of using the configured responses.
+	*
+	* @param rate The failure rate as a decimal between 0.0 and 1.0.
+	* @throws {RangeError} When rate is not between 0.0 and 1.0.
+	*/
+	setFailureRate(rate) {
+		if (rate < 0 || rate > 1) throw new RangeError("Failure rate must be between 0.0 and 1.0");
+		this.config = {
+			...this.config,
+			failureRate: rate
+		};
+	}
+	/**
+	* Set a fixed delay in milliseconds for all send operations.
+	*
+	* This overrides any random delay range that was previously configured.
+	*
+	* @param milliseconds The delay in milliseconds (must be non-negative).
+	* @throws {RangeError} When milliseconds is negative.
+	*/
+	setDelay(milliseconds) {
+		if (milliseconds < 0) throw new RangeError("Delay must be non-negative");
+		this.config = {
+			...this.config,
+			delay: milliseconds,
+			randomDelayRange: {
+				min: 0,
+				max: 0
+			}
+		};
+	}
+	/**
+	* Set a random delay range in milliseconds for send operations.
+	*
+	* This overrides any fixed delay that was previously configured.
+	*
+	* @param min The minimum delay in milliseconds.
+	* @param max The maximum delay in milliseconds.
+	* @throws {RangeError} When min or max is negative, or min > max.
+	*/
+	setRandomDelay(min, max) {
+		if (min < 0 || max < 0 || min > max) throw new RangeError("Invalid delay range");
+		this.config = {
+			...this.config,
+			delay: 0,
+			randomDelayRange: {
+				min,
+				max
+			}
+		};
+	}
+	/**
+	* Find the first message matching the given predicate.
+	*
+	* @param predicate A function that tests each message.
+	* @returns The first matching message, or undefined if none found.
+	*/
+	findMessageBy(predicate) {
+		return this.sentMessages.find(predicate);
+	}
+	/**
+	* Find all messages matching the given predicate.
+	*
+	* @param predicate A function that tests each message.
+	* @returns An array of all matching messages.
+	*/
+	findMessagesBy(predicate) {
+		return this.sentMessages.filter(predicate);
+	}
+	/**
+	* Get all messages sent to a specific email address.
+	*
+	* Searches through To, CC, and BCC recipients to find messages
+	* that were sent to the specified email address.
+	*
+	* @param email The email address to search for.
+	* @returns An array of messages sent to the specified address.
+	*/
+	getMessagesTo(email) {
+		return this.sentMessages.filter((message) => [
+			...message.recipients,
+			...message.ccRecipients,
+			...message.bccRecipients
+		].some((addr) => addr.address === email));
+	}
+	/**
+	* Get all messages with a specific subject.
+	*
+	* @param subject The exact subject line to match.
+	* @returns An array of messages with the specified subject.
+	*/
+	getMessagesBySubject(subject) {
+		return this.sentMessages.filter((message) => message.subject === subject);
+	}
+	/**
+	* Wait for a specific number of messages to be sent.
+	*
+	* This method polls the message count until the target is reached or
+	* the timeout expires.  Useful for testing async email workflows where you
+	* need to wait for messages to be sent.
+	*
+	* @param count The number of messages to wait for.
+	* @param timeout The timeout in milliseconds (default: 5000).
+	* @returns A promise that resolves when the count is reached.
+	* @throws {Error} When the timeout is exceeded before reaching the target
+	*                 count.
+	*/
+	async waitForMessageCount(count, timeout = 5e3) {
+		const startTime = Date.now();
+		while (this.sentMessages.length < count) {
+			if (Date.now() - startTime > timeout) throw new Error(`Timeout waiting for ${count} messages (got ${this.sentMessages.length})`);
+			await new Promise((resolve) => setTimeout(resolve, 10));
+		}
+	}
+	/**
+	* Wait for a message matching the given predicate.
+	*
+	* This method polls for a matching message until one is found or the timeout
+	* expires.  Useful for testing async email workflows where you need to wait
+	* for specific messages.
+	*
+	* @param predicate A function that tests each message for a match.
+	* @param timeout The timeout in milliseconds (default: 5000).
+	* @returns A promise that resolves with the matching message.
+	* @throws {Error} When the timeout is exceeded before finding a matching
+	*                 message.
+	*/
+	async waitForMessage(predicate, timeout = 5e3) {
+		const startTime = Date.now();
+		while (true) {
+			const message = this.findMessageBy(predicate);
+			if (message) return message;
+			if (Date.now() - startTime > timeout) throw new Error("Timeout waiting for message");
+			await new Promise((resolve) => setTimeout(resolve, 10));
+		}
+	}
+	/**
+	* Reset the transport to its initial state.
+	*
+	* Clears all messages, resets all configuration to defaults, and
+	* resets the message ID counter. This is useful for test cleanup.
+	*/
+	reset() {
+		this.sentMessages = [];
+		this.nextResponse = null;
+		this.config = createMockConfig();
+		this.messageIdCounter = 1;
+	}
+	async applyDelay() {
+		let delayMs = this.config.delay;
+		if (this.config.randomDelayRange && (this.config.randomDelayRange.min > 0 || this.config.randomDelayRange.max > 0)) {
+			const { min, max } = this.config.randomDelayRange;
+			delayMs = Math.random() * (max - min) + min;
+		}
+		if (delayMs > 0) await new Promise((resolve) => setTimeout(resolve, delayMs));
+	}
+	getResponse() {
+		if (this.config.failureRate > 0 && Math.random() < this.config.failureRate) return {
+			successful: false,
+			errorMessages: ["Simulated random failure"]
+		};
+		if (this.nextResponse) {
+			const response = this.nextResponse;
+			this.nextResponse = null;
+			return response;
+		}
+		if (this.config.defaultResponse.successful && this.config.generateUniqueMessageIds) return {
+			successful: true,
+			messageId: `mock-message-${this.messageIdCounter++}`
+		};
+		return this.config.defaultResponse;
+	}
+};
+
+//#endregion
+export { MockTransport };

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@upyo/mock",
+  "version": "0.1.0-dev.17+3ffd074a",
+  "description": "Mock transport for Upyo email library—useful for testing",
+  "keywords": [
+    "email",
+    "mail",
+    "mock",
+    "testing",
+    "test"
+  ],
+  "license": "MIT",
+  "author": {
+    "name": "Hong Minhee",
+    "email": "hong@minhee.org",
+    "url": "https://hongminhee.org/"
+  },
+  "homepage": "https://upyo.org/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dahlia/upyo.git",
+    "directory": "packages/mock/"
+  },
+  "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.1.0-dev.17+3ffd074a"
+  },
+  "devDependencies": {
+    "@dotenvx/dotenvx": "^1.47.3",
+    "tsdown": "^0.12.7",
+    "typescript": "5.8.3"
+  },
+  "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",
+    "test:deno": "deno test --allow-env"
+  }
+}