stratal 0.0.22 → 0.0.24

package/dist/queue.module-nddvxzCB.mjs

@@ -0,0 +1,613 @@
+import { t as __exportAll } from "./chunk-BBjsoOtd.mjs";
+import { c as Transient, d as inject, o as Request, r as DI_TOKENS, s as Singleton } from "./di-DseMn-z9.mjs";
+import { a as ApplicationError, n as getContainer, t as containerStorage } from "./container-storage-BmOJ4_Na.mjs";
+import { n as __decorateParam, t as __decorate } from "./decorate-CuAoSZvs.mjs";
+import { LOGGER_TOKENS } from "./logger/index.mjs";
+import "./errors-mXYxG0XB.mjs";
+import { n as Module } from "./module.decorator-CYHY6pG5.mjs";
+import "./module/index.mjs";
+import { CACHE_TOKENS, CacheModule } from "./cache/index.mjs";
+import { t as QUEUE_TOKENS } from "./queue.tokens-DjHnFmre.mjs";
+import { t as I18N_TOKENS } from "./i18n.tokens-CZ_v8oyS.mjs";
+//#region src/queue/queue.error.ts
+var QueueError = class extends ApplicationError {};
+//#endregion
+//#region src/queue/queue-manager.ts
+const DEFAULT_MAX_RETRIES = 3;
+let QueueManager = class QueueManager {
+	registry;
+	logger;
+	store;
+	maxRetries;
+	constructor(registry, logger, store, options) {
+		this.registry = registry;
+		this.logger = logger;
+		this.store = store;
+		this.maxRetries = options.maxRetries ?? DEFAULT_MAX_RETRIES;
+	}
+	async processBatch(queueName, batch) {
+		for (const message of batch.messages) {
+			const queueMessage = message.body;
+			const idempotencyKey = queueMessage.metadata?.idempotencyKey ?? queueMessage.id;
+			if (await this.store.isProcessed(idempotencyKey)) {
+				message.ack();
+				continue;
+			}
+			const container = getContainer();
+			const consumers = this.registry.getConsumerClasses(queueMessage.type).map((ConsumerClass) => container.resolve(ConsumerClass));
+			const results = await Promise.allSettled(consumers.map((consumer) => consumer.handle(queueMessage)));
+			let lastError;
+			let failedConsumer;
+			for (let i = 0; i < results.length; i++) {
+				const result = results[i];
+				if (result.status === "rejected") {
+					const consumer = consumers[i];
+					const errorInstance = result.reason instanceof Error ? result.reason : new Error(String(result.reason));
+					this.logger.error("Queue message processing failed", errorInstance, {
+						type: queueMessage.type,
+						queue: queueName,
+						messageId: queueMessage.id,
+						idempotencyKey
+					});
+					if (consumer.onError) await consumer.onError(errorInstance, queueMessage);
+					lastError = errorInstance;
+					failedConsumer = consumer.constructor.name;
+				}
+			}
+			if (lastError !== void 0) if (message.attempts > this.maxRetries) {
+				try {
+					const binding = queueMessage.metadata?.binding;
+					if (!binding) throw new QueueError(`Queue message ${queueMessage.id} has no binding metadata and cannot be recorded for retry. Messages must be dispatched through a Stratal queue sender (@InjectQueue).`);
+					const failedJob = {
+						id: queueMessage.id,
+						queue: queueName,
+						binding,
+						type: queueMessage.type,
+						message: queueMessage,
+						error: {
+							name: lastError.name,
+							message: lastError.message,
+							stack: lastError.stack
+						},
+						consumer: failedConsumer,
+						attempts: message.attempts,
+						failedAt: (/* @__PURE__ */ new Date()).toISOString()
+					};
+					await this.store.storeFailedJob(failedJob);
+				} catch (error) {
+					this.logger.error("Failed to persist failed queue job", error instanceof Error ? error : new Error(String(error)), {
+						queue: queueName,
+						messageId: queueMessage.id,
+						type: queueMessage.type
+					});
+				}
+				message.ack();
+			} else message.retry();
+			else {
+				await this.store.markProcessed(idempotencyKey);
+				message.ack();
+			}
+		}
+	}
+};
+QueueManager = __decorate([
+	Transient(DI_TOKENS.Queue),
+	__decorateParam(0, inject(DI_TOKENS.ConsumerRegistry)),
+	__decorateParam(1, inject(LOGGER_TOKENS.LoggerService)),
+	__decorateParam(2, inject(QUEUE_TOKENS.QueueStore)),
+	__decorateParam(3, inject(QUEUE_TOKENS.QueueModuleOptions))
+], QueueManager);
+//#endregion
+//#region src/queue/consumer-registry.ts
+let ConsumerRegistry = class ConsumerRegistry {
+	/** Map from message type to consumer classes handling that type */
+	classesByType = /* @__PURE__ */ new Map();
+	/** All registrations (for iteration / listing) */
+	registrations = [];
+	/** Registered consumer classes (dedupe) */
+	registeredClasses = /* @__PURE__ */ new Set();
+	/**
+	* Register a queue consumer class.
+	*
+	* Indexes the class by each of its declared message types. A fresh instance
+	* is resolved per message from the request-scoped container at dispatch time —
+	* consumers are never held as long-lived singletons, so they may safely inject
+	* request-scoped providers (`@InjectQueue`, i18n, auth context, …).
+	*
+	* @param consumerClass - Queue consumer class to register
+	* @param messageTypes - Message types the consumer handles
+	*/
+	register(consumerClass, messageTypes) {
+		if (this.registeredClasses.has(consumerClass)) return;
+		this.registeredClasses.add(consumerClass);
+		this.registrations.push({
+			consumerClass,
+			messageTypes
+		});
+		for (const messageType of messageTypes) {
+			const existing = this.classesByType.get(messageType) ?? [];
+			existing.push(consumerClass);
+			this.classesByType.set(messageType, existing);
+		}
+	}
+	/**
+	* Get all consumer classes that can handle a specific message type.
+	*
+	* Returns classes that either declare the message type explicitly or use the
+	* `'*'` wildcard. Callers resolve a fresh instance per message from the
+	* request-scoped container.
+	*
+	* @param messageType - The message type to find consumers for
+	* @returns Array of consumer classes that can handle this message type
+	*/
+	getConsumerClasses(messageType) {
+		const exactMatch = this.classesByType.get(messageType) ?? [];
+		const wildcardMatch = this.classesByType.get("*") ?? [];
+		return Array.from(new Set([...exactMatch, ...wildcardMatch]));
+	}
+	/**
+	* Check if any consumers can handle a message type
+	*
+	* @param messageType - The message type to check
+	* @returns true if at least one consumer can handle this type
+	*/
+	hasConsumers(messageType) {
+		return this.getConsumerClasses(messageType).length > 0;
+	}
+	/**
+	* Get all registered message types
+	*
+	* @returns Array of message types with registered consumers
+	*/
+	getMessageTypes() {
+		return Array.from(this.classesByType.keys());
+	}
+	/**
+	* Get all consumer registrations (class + message types) for listing.
+	*/
+	getRegistrations() {
+		return this.registrations;
+	}
+};
+ConsumerRegistry = __decorate([Singleton(DI_TOKENS.ConsumerRegistry)], ConsumerRegistry);
+//#endregion
+//#region src/queue/queue-sender.ts
+/**
+* Queue Sender
+*
+* Implementation of IQueueSender bound to a specific queue binding.
+* Created by QueueRegistry for each registered binding.
+*
+* Automatically enriches messages with:
+* - `id`: UUID generated via crypto.randomUUID()
+* - `metadata.locale`: Current locale from I18n context
+* - `metadata.idempotencyKey`: Deterministic SHA-256 hash of type + payload (if not provided)
+*
+* @example
+* ```typescript
+* // Created by QueueRegistry, not directly instantiated
+* const sender = registry.getQueue('NOTIFICATIONS_QUEUE')
+*
+* await sender.dispatch({
+*   type: 'email.send',
+*   payload: { to: 'user@example.com', subject: 'Hello' }
+* })
+* ```
+*/
+var QueueSender = class {
+	binding;
+	provider;
+	i18n;
+	constructor(binding, provider, i18n) {
+		this.binding = binding;
+		this.provider = provider;
+		this.i18n = i18n;
+	}
+	/**
+	* Dispatch a message to this queue.
+	*
+	* @param message - Message to dispatch (without id)
+	*/
+	async dispatch(message) {
+		const metadata = { ...message.metadata };
+		if (!metadata.locale) {
+			const locale = this.i18n.getLocale();
+			if (locale) metadata.locale = locale;
+		}
+		metadata.idempotencyKey ??= await this.generateIdempotencyKey(message.type, message.payload);
+		metadata.binding = this.binding;
+		const fullMessage = {
+			id: crypto.randomUUID(),
+			...message,
+			metadata
+		};
+		await this.provider.send(this.binding, fullMessage);
+	}
+	async generateIdempotencyKey(type, payload) {
+		const data = new TextEncoder().encode(stableStringify({
+			type,
+			payload
+		}));
+		const hash = await crypto.subtle.digest("SHA-256", data);
+		return `queue:${Array.from(new Uint8Array(hash)).map((b) => b.toString(16).padStart(2, "0")).join("")}`;
+	}
+};
+/**
+* Deterministic JSON serialization: object keys are emitted in sorted order at
+* every level so the output depends only on the data, not on key insertion
+* order. Arrays keep their order (order is significant). Used to derive a stable
+* idempotency hash from a message's `type` + `payload`.
+*/
+function stableStringify(value) {
+	if (value === null || typeof value !== "object") return JSON.stringify(value) ?? "null";
+	if (Array.isArray(value)) return `[${value.map(stableStringify).join(",")}]`;
+	return `{${Object.keys(value).sort().map((key) => {
+		const v = value[key];
+		if (v === void 0) return void 0;
+		return `${JSON.stringify(key)}:${stableStringify(v)}`;
+	}).filter((entry) => entry !== void 0).join(",")}}`;
+}
+//#endregion
+//#region src/queue/queue-registry.ts
+let QueueRegistry = class QueueRegistry {
+	i18n;
+	provider;
+	senders = /* @__PURE__ */ new Map();
+	constructor(providerFactory, i18n) {
+		this.i18n = i18n;
+		this.provider = providerFactory.create();
+	}
+	/**
+	* Get or create a QueueSender for the specified binding.
+	*
+	* Senders are cached per binding within the request scope.
+	*
+	* @param binding - The queue binding to get a sender for
+	* @returns QueueSender bound to the specified binding
+	*/
+	getQueue(binding) {
+		let sender = this.senders.get(binding);
+		if (!sender) {
+			sender = new QueueSender(binding, this.provider, this.i18n);
+			this.senders.set(binding, sender);
+		}
+		return sender;
+	}
+};
+QueueRegistry = __decorate([
+	Request(QUEUE_TOKENS.QueueRegistry),
+	__decorateParam(0, inject(QUEUE_TOKENS.QueueProviderFactory)),
+	__decorateParam(1, inject(I18N_TOKENS.I18nService))
+], QueueRegistry);
+//#endregion
+//#region src/queue/queue-store.ts
+const IDEM_PREFIX = "queue:idem:";
+const FAILED_PREFIX = "queue:failed:";
+const DEFAULT_IDEMPOTENCY_TTL = 86400;
+/** Default KV binding name used for queue state when none is configured. */
+const DEFAULT_STORE_BINDING = "CACHE";
+let QueueStore = class QueueStore {
+	cache;
+	idempotencyTtl;
+	constructor(cache, options) {
+		this.cache = cache.binding(options.store?.binding ?? "CACHE");
+		this.idempotencyTtl = options.idempotency?.ttl ?? DEFAULT_IDEMPOTENCY_TTL;
+	}
+	async isProcessed(key) {
+		return await this.cache.get(`${IDEM_PREFIX}${key}`) !== null;
+	}
+	async markProcessed(key) {
+		await this.cache.put(`${IDEM_PREFIX}${key}`, "1", { expirationTtl: this.idempotencyTtl });
+	}
+	async storeFailedJob(job) {
+		const metadata = {
+			queue: job.queue,
+			binding: job.binding,
+			type: job.type,
+			consumer: job.consumer,
+			attempts: job.attempts,
+			failedAt: job.failedAt
+		};
+		await this.cache.put(`${FAILED_PREFIX}${job.id}`, JSON.stringify(job), { metadata });
+	}
+	async getFailedJob(messageId) {
+		return this.cache.get(`${FAILED_PREFIX}${messageId}`, "json");
+	}
+	async removeFailedJob(messageId) {
+		await this.cache.delete(`${FAILED_PREFIX}${messageId}`);
+	}
+	async listFailedJobs(options) {
+		const result = await this.cache.list({
+			prefix: FAILED_PREFIX,
+			limit: options?.limit ?? 50,
+			cursor: options?.cursor
+		});
+		return {
+			keys: result.keys.filter((key) => key.metadata != null).map((key) => ({
+				id: key.name.slice(13),
+				metadata: key.metadata
+			})),
+			cursor: result.list_complete ? void 0 : result.cursor
+		};
+	}
+	async purgeFailedJobs() {
+		let cursor;
+		do {
+			const result = await this.cache.list({
+				prefix: FAILED_PREFIX,
+				cursor
+			});
+			await Promise.all(result.keys.map((key) => this.cache.delete(key.name)));
+			cursor = result.list_complete ? void 0 : result.cursor;
+		} while (cursor);
+	}
+	/**
+	* Delete failed jobs older than `retentionSeconds` (by their `failedAt`
+	* timestamp). Returns the number removed. Backs the opt-in
+	* {@link FailedJobCleanupJob} cron — failed jobs otherwise persist
+	* indefinitely until retried or purged.
+	*/
+	async purgeFailedJobsOlderThan(retentionSeconds) {
+		const cutoff = Date.now() - retentionSeconds * 1e3;
+		let cursor;
+		let removed = 0;
+		do {
+			const result = await this.cache.list({
+				prefix: FAILED_PREFIX,
+				cursor
+			});
+			const expired = result.keys.filter((key) => {
+				const failedAt = key.metadata?.failedAt;
+				return failedAt !== void 0 && Date.parse(failedAt) < cutoff;
+			});
+			await Promise.all(expired.map((key) => this.cache.delete(key.name)));
+			removed += expired.length;
+			cursor = result.list_complete ? void 0 : result.cursor;
+		} while (cursor);
+		return removed;
+	}
+};
+QueueStore = __decorate([
+	Transient(QUEUE_TOKENS.QueueStore),
+	__decorateParam(0, inject(CACHE_TOKENS.TieredCacheService)),
+	__decorateParam(1, inject(QUEUE_TOKENS.QueueModuleOptions))
+], QueueStore);
+//#endregion
+//#region src/queue/providers/cloudflare-queue.provider.ts
+let CloudflareQueueProvider = class CloudflareQueueProvider {
+	env;
+	constructor(env) {
+		this.env = env;
+	}
+	/**
+	* Send a message to a Cloudflare Queue
+	*
+	* @param binding - Queue binding identifier (e.g., 'NOTIFICATIONS_QUEUE')
+	* @param message - Complete message with id and payload
+	* @throws {QueueError} If the binding is not configured on env
+	*/
+	async send(binding, message) {
+		const queue = this.env[binding];
+		if (!queue) throw new QueueError(`Queue binding "${binding}" was not found in the environment`);
+		await queue.send(message);
+	}
+};
+CloudflareQueueProvider = __decorate([Transient(), __decorateParam(0, inject(DI_TOKENS.CloudflareEnv))], CloudflareQueueProvider);
+//#endregion
+//#region src/queue/providers/sync-queue.provider.ts
+let SyncQueueProvider = class SyncQueueProvider {
+	registry;
+	root;
+	constructor(registry, root) {
+		this.registry = registry;
+		this.root = root;
+	}
+	/**
+	* Process a message synchronously.
+	*
+	* Runs inside the active request scope when dispatch happens within one (an
+	* HTTP request, or `runInScope` for queues/cron/commands). When dispatched
+	* with no ambient scope — e.g. a service invoked directly in a test — it
+	* establishes its own request scope (mirroring the production queue handler)
+	* so consumers and their request-scoped dependencies resolve correctly.
+	*
+	* @param _binding - Queue binding (not used for routing, consumers match by message type)
+	* @param message - Complete message with id and payload
+	* @throws Re-throws any error from consumer.handle() after calling onError()
+	*/
+	async send(_binding, message) {
+		const ambient = containerStorage.getStore();
+		if (ambient) {
+			await this.process(ambient, message);
+			return;
+		}
+		const locale = message.metadata?.locale ?? "en";
+		await this.root.runInRequestScope({
+			getLocale: () => locale,
+			setLocale: () => {},
+			getContainer: () => containerStorage.getStore() ?? this.root
+		}, (container) => this.process(container, message));
+	}
+	/**
+	* Resolve a fresh consumer per message from `container` (matched by type) and
+	* invoke each sequentially, fail-fast on the first error after `onError`.
+	*/
+	async process(container, message) {
+		const consumers = this.registry.getConsumerClasses(message.type).map((ConsumerClass) => container.resolve(ConsumerClass));
+		for (const consumer of consumers) try {
+			await consumer.handle(message);
+		} catch (error) {
+			const errorInstance = error instanceof Error ? error : new Error(String(error));
+			if (consumer.onError) await consumer.onError(errorInstance, message);
+			throw errorInstance;
+		}
+	}
+};
+SyncQueueProvider = __decorate([
+	Transient(),
+	__decorateParam(0, inject(DI_TOKENS.ConsumerRegistry)),
+	__decorateParam(1, inject(DI_TOKENS.Container))
+], SyncQueueProvider);
+//#endregion
+//#region src/queue/services/queue-provider-factory.ts
+let QueueProviderFactory = class QueueProviderFactory {
+	env;
+	registry;
+	container;
+	options;
+	constructor(env, registry, container, options) {
+		this.env = env;
+		this.registry = registry;
+		this.container = container;
+		this.options = options;
+	}
+	/**
+	* Create a queue provider based on module configuration
+	*
+	* @returns Queue provider instance
+	* @throws {QueueError} If provider type is not supported
+	*/
+	create() {
+		const providerType = this.options?.provider ?? "cloudflare";
+		switch (providerType) {
+			case "cloudflare": return new CloudflareQueueProvider(this.env);
+			case "sync": return new SyncQueueProvider(this.registry, this.container);
+			default: throw new QueueError(`Queue provider "${String(providerType)}" is not supported`);
+		}
+	}
+};
+QueueProviderFactory = __decorate([
+	Transient(QUEUE_TOKENS.QueueProviderFactory),
+	__decorateParam(0, inject(DI_TOKENS.CloudflareEnv)),
+	__decorateParam(1, inject(DI_TOKENS.ConsumerRegistry)),
+	__decorateParam(2, inject(DI_TOKENS.Container)),
+	__decorateParam(3, inject(QUEUE_TOKENS.QueueModuleOptions, { isOptional: true }))
+], QueueProviderFactory);
+//#endregion
+//#region src/queue/queue.module.ts
+/**
+* Queue Module
+*
+* Provides declarative queue infrastructure with provider abstraction.
+*
+* **Usage:**
+* ```typescript
+* // 1. Configure provider (once, in app root)
+* QueueModule.forRootAsync({
+*   inject: [CONFIG_TOKENS.ConfigService],
+*   useFactory: (config) => ({ provider: config.get('queue').provider })
+* })
+*
+* // 2. Register queue bindings (the binding IS the injection token)
+* QueueModule.registerQueue('NOTIFICATIONS_QUEUE')
+* QueueModule.registerQueue('BACKGROUND_QUEUE')
+*
+* // 3. Inject and use
+* constructor(@InjectQueue('NOTIFICATIONS_QUEUE') private queue: IQueueSender) {}
+* await this.queue.dispatch({ type: 'email.send', payload: {...} })
+* ```
+*
+* **Providers:**
+* - `cloudflare`: Production provider using Cloudflare Queue bindings
+* - `sync`: Testing provider that processes messages immediately
+*/
+var queue_module_exports = /* @__PURE__ */ __exportAll({ QueueModule: () => QueueModule });
+var _QueueModule;
+let QueueModule = _QueueModule = class QueueModule {
+	/**
+	* Fail fast at boot if the configured KV store binding is missing, rather
+	* than letting every queue invocation hard-fail lazily. The binding backs
+	* idempotency claims and failed-job storage, so without it the queue
+	* subsystem cannot function.
+	*/
+	onInitialize({ container }) {
+		const options = container.resolve(QUEUE_TOKENS.QueueModuleOptions);
+		if (options.provider !== "cloudflare") return;
+		const binding = options.store?.binding ?? "CACHE";
+		if (!container.resolve(DI_TOKENS.CloudflareEnv)[binding]) throw new QueueError(`Queue KV store binding "${binding}" was not found in the environment. The queue subsystem persists idempotency claims and failed jobs to KV. Add a kv_namespaces entry for "${binding}" in wrangler.jsonc, or set QueueModule.forRootAsync({ ..., store: { binding: 'YOUR_KV' } }) to point at an existing namespace.`);
+	}
+	/**
+	* Configure queue infrastructure with async factory.
+	*
+	* Use when provider configuration depends on other services like ConfigService.
+	*
+	* @param options - Async configuration with factory and inject tokens
+	* @returns Dynamic module with queue infrastructure
+	*
+	* @example
+	* ```typescript
+	* QueueModule.forRootAsync({
+	*   inject: [CONFIG_TOKENS.ConfigService],
+	*   useFactory: (config: IConfigService) => ({
+	*     provider: config.get('queue').provider
+	*   })
+	* })
+	* ```
+	*/
+	static forRootAsync(options) {
+		return {
+			module: _QueueModule,
+			providers: [{
+				provide: QUEUE_TOKENS.QueueModuleOptions,
+				useFactory: options.useFactory,
+				inject: options.inject
+			}]
+		};
+	}
+	/**
+	* Register a queue binding for injection.
+	*
+	* The binding name doubles as the DI injection token and the
+	* `env`-lookup key. Binding names are typed against `StratalEnv`
+	* (autocomplete works once an app augments `StratalEnv` with its
+	* Cloudflare bindings).
+	*
+	* @param binding - Queue binding identifier (e.g. `NOTIFICATIONS_QUEUE`).
+	* @returns Dynamic module that provides the queue sender
+	*
+	* @example
+	* ```typescript
+	* // In AppModule imports
+	* QueueModule.registerQueue('NOTIFICATIONS_QUEUE')
+	*
+	* // Then inject using the binding name
+	* constructor(@InjectQueue('NOTIFICATIONS_QUEUE') private queue: IQueueSender) {}
+	* ```
+	*/
+	static registerQueue(binding) {
+		return {
+			module: _QueueModule,
+			providers: [{
+				provide: binding,
+				useFactory: (registry) => registry.getQueue(binding),
+				inject: [QUEUE_TOKENS.QueueRegistry]
+			}]
+		};
+	}
+};
+QueueModule = _QueueModule = __decorate([Module({
+	imports: [CacheModule],
+	providers: [
+		{
+			provide: DI_TOKENS.ConsumerRegistry,
+			useClass: ConsumerRegistry
+		},
+		QueueManager,
+		{
+			provide: QUEUE_TOKENS.QueueProviderFactory,
+			useClass: QueueProviderFactory
+		},
+		{
+			provide: QUEUE_TOKENS.QueueRegistry,
+			useClass: QueueRegistry
+		},
+		{
+			provide: QUEUE_TOKENS.QueueStore,
+			useClass: QueueStore
+		}
+	]
+})], QueueModule);
+//#endregion
+export { CloudflareQueueProvider as a, QueueRegistry as c, QueueManager as d, QueueError as f, SyncQueueProvider as i, QueueSender as l, queue_module_exports as n, DEFAULT_STORE_BINDING as o, QueueProviderFactory as r, QueueStore as s, QueueModule as t, ConsumerRegistry as u };
+
+//# sourceMappingURL=queue.module-nddvxzCB.mjs.map