@upyo/mock 0.1.0-dev.17

package/README.md

@@ -0,0 +1,186 @@
+<!-- deno-fmt-ignore-file -->
+
+@upyo/mock
+==========
+
+[![JSR][JSR badge]][JSR]
+[![npm][npm badge]][npm]
+
+Mock transport for the [Upyo] email library - perfect for testing email functionality without actually sending emails.
+
+[JSR]: https://jsr.io/@upyo/mock
+[JSR badge]: https://jsr.io/badges/@upyo/mock
+[npm]: https://www.npmjs.com/package/@upyo/mock
+[npm badge]: https://img.shields.io/npm/v/@upyo/mock?logo=npm
+[Upyo]: https://upyo.org/
+
+
+Features
+--------
+
+ -  *Memory-based storage*: Stores "sent" messages in memory for verification
+ -  *Configurable behavior*: Simulate delays, failures, and custom responses
+ -  *Rich testing API*: Query, filter, and wait for messages in tests
+ -  *Type-safe*: Full TypeScript support with readonly interfaces
+ -  *Cross-runtime*: Works on Deno, Node.js, Bun, and edge functions
+
+
+Installation
+------------
+
+~~~~ sh
+npm  add       @upyo/core @upyo/mock
+pnpm add       @upyo/core @upyo/mock
+yarn add       @upyo/core @upyo/mock
+deno add --jsr @upyo/core @upyo/mock
+bun  add       @upyo/core @upyo/mock
+~~~~
+
+
+Usage
+-----
+
+### Basic testing
+
+~~~~ typescript
+import { createMessage } from "@upyo/core";
+import { MockTransport } from "@upyo/mock";
+
+// Create a mock transport
+const transport = new MockTransport();
+
+const message = createMessage({
+  from: "sender@example.com",
+  to: "recipient@example.com",
+  subject: "Test Email",
+  content: { text: "This is a test email." },
+});
+
+// "Send" the email (it will be stored in memory)
+const receipt = await transport.send(message);
+
+// Verify the result
+console.log(receipt.successful); // true
+console.log(receipt.messageId); // "mock-message-1"
+
+// Check what was sent
+const sentMessages = transport.getSentMessages();
+console.log(sentMessages.length); // 1
+console.log(sentMessages[0].subject); // "Test Email"
+~~~~
+
+### Advanced configuration
+
+~~~~ typescript
+import { MockTransport } from "@upyo/mock";
+
+const transport = new MockTransport({
+  // Simulate network delay
+  delay: 100,
+
+  // Or use random delays
+  randomDelayRange: { min: 50, max: 200 },
+
+  // Simulate random failures (10% failure rate)
+  failureRate: 0.1,
+
+  // Custom default response
+  defaultResponse: {
+    successful: true,
+    messageId: "custom-id-prefix"
+  }
+});
+~~~~
+
+### Testing with failures
+
+~~~~ typescript
+const transport = new MockTransport();
+
+// Set up a specific failure for the next send
+transport.setNextResponse({
+  successful: false,
+  errorMessages: ["Invalid recipient address"]
+});
+
+const receipt = await transport.send(message);
+console.log(receipt.successful); // false
+console.log(receipt.errorMessages); // ["Invalid recipient address"]
+~~~~
+
+### Message querying and filtering
+
+~~~~ typescript
+const transport = new MockTransport();
+
+// Send some test messages
+await transport.send(createMessage({
+  from: "sender@example.com",
+  to: "user1@example.com",
+  subject: "Welcome User 1",
+  content: { text: "Welcome!" }
+}));
+
+await transport.send(createMessage({
+  from: "sender@example.com",
+  to: "user2@example.com",
+  subject: "Welcome User 2",
+  content: { text: "Welcome!" }
+}));
+
+// Query sent messages
+const allMessages = transport.getSentMessages();
+console.log(allMessages.length); // 2
+
+const user1Messages = transport.getMessagesTo("user1@example.com");
+console.log(user1Messages.length); // 1
+
+const welcomeMessages = transport.getMessagesBySubject("Welcome User 1");
+console.log(welcomeMessages.length); // 1
+
+// Custom filtering
+const textMessages = transport.findMessagesBy(msg =>
+  "text" in msg.content && msg.content.text.includes("Welcome")
+);
+console.log(textMessages.length); // 2
+~~~~
+
+### Async testing utilities
+
+~~~~ typescript
+const transport = new MockTransport();
+
+// Wait for a specific number of messages
+const waitPromise = transport.waitForMessageCount(3, 5000); // 5 second timeout
+
+// Send messages from elsewhere in your code...
+setTimeout(() => transport.send(message1), 100);
+setTimeout(() => transport.send(message2), 200);
+setTimeout(() => transport.send(message3), 300);
+
+await waitPromise; // Resolves when 3 messages are sent
+
+// Wait for a specific message
+const specificMessage = await transport.waitForMessage(
+  msg => msg.subject === "Important Alert",
+  3000 // 3 second timeout
+);
+~~~~
+
+### Cleanup and reset
+
+~~~~ typescript
+const transport = new MockTransport();
+
+// Send some messages and configure behavior
+await transport.send(message);
+transport.setDelay(100);
+transport.setFailureRate(0.2);
+
+// Clear just the sent messages
+transport.clearSentMessages();
+console.log(transport.getSentMessagesCount()); // 0
+
+// Or reset everything to initial state
+transport.reset(); // Clears messages and resets all configuration
+~~~~

package/dist/index.cjs

@@ -0,0 +1,336 @@
+
+//#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
+exports.MockTransport = MockTransport;