@classytic/arc 2.25.0 → 2.30.0

package/dist/subscribe-helpers-DfzsivM6.mjs

@@ -0,0 +1,339 @@
+import { n as createEvent } from "./EventTransport-C6YA8xY9.mjs";
+//#region src/events/defineEvent.ts
+/**
+* defineEvent — Typed Event Definitions with Optional Schema Validation
+*
+* Provides:
+* 1. defineEvent() — declare an event with name, schema, version, description
+* 2. EventRegistry — catalog of all known events + payload validation
+* 3. .create() helper — build DomainEvent with auto-generated metadata
+*
+* The built-in validator checks: object type, required fields, and top-level
+* property types. It does NOT recurse into nested objects, validate arrays,
+* enums, patterns, formats, or $ref. This is intentional — it's a lightweight
+* guard, not a full JSON Schema engine.
+*
+* For full validation, pass a custom `validate` function to `createEventRegistry()`:
+*
+* @example
+* ```typescript
+* import Ajv from 'ajv';
+* const ajv = new Ajv();
+*
+* const registry = createEventRegistry({
+*   validate: (schema, payload) => {
+*     const valid = ajv.validate(schema, payload);
+*     return valid
+*       ? { valid: true }
+*       : { valid: false, errors: ajv.errorsText().split(', ') };
+*   },
+* });
+* ```
+*
+* @example
+* ```typescript
+* import { defineEvent, createEventRegistry } from '@classytic/arc/events';
+*
+* const OrderCreated = defineEvent({
+*   name: 'order.created',
+*   version: 1,
+*   schema: {
+*     type: 'object',
+*     properties: {
+*       orderId: { type: 'string' },
+*       total: { type: 'number' },
+*     },
+*     required: ['orderId', 'total'],
+*   },
+* });
+*
+* // Type-safe event creation
+* const event = OrderCreated.create({ orderId: 'o-1', total: 100 });
+* await fastify.events.publish(event.type, event.payload, event.meta);
+*
+* // Registry for introspection + validation
+* const registry = createEventRegistry();
+* registry.register(OrderCreated);
+* const result = registry.validate('order.created', payload);
+* ```
+*/
+/**
+* Define a typed event with optional schema validation.
+*
+* @example
+* const OrderCreated = defineEvent({
+*   name: 'order.created',
+*   schema: { type: 'object', properties: { orderId: { type: 'string' } }, required: ['orderId'] },
+* });
+*
+* const event = OrderCreated.create({ orderId: '123' });
+*/
+function defineEvent(input) {
+	const { name, schema, version = 1, description } = input;
+	return {
+		name,
+		schema,
+		version,
+		description,
+		create(payload, meta) {
+			return createEvent(name, payload, {
+				schemaVersion: version,
+				...meta
+			});
+		}
+	};
+}
+/**
+* Create an event registry for cataloging and validating events.
+*
+* The registry is opt-in — unregistered events pass validation.
+* This allows gradual adoption without breaking existing code.
+*
+* @param options.validate - Custom validator replacing the built-in minimal validator.
+*   The built-in validator only checks top-level object structure (type, required, property types).
+*   For nested objects, arrays, enums, patterns, or $ref, provide AJV or similar.
+*/
+function createEventRegistry(options) {
+	const customValidator = options?.validate;
+	const definitions = /* @__PURE__ */ new Map();
+	function registryKey(name, version) {
+		return `${name}:v${version}`;
+	}
+	return {
+		register(definition) {
+			const key = registryKey(definition.name, definition.version);
+			if (definitions.has(key)) throw new Error(`Event '${definition.name}' v${definition.version} is already registered. Use a different version number for schema evolution.`);
+			definitions.set(key, definition);
+		},
+		get(name, version) {
+			if (version !== void 0) return definitions.get(registryKey(name, version));
+			let latest;
+			let latestVersion = -1;
+			for (const def of definitions.values()) if (def.name === name && def.version > latestVersion) {
+				latest = def;
+				latestVersion = def.version;
+			}
+			return latest;
+		},
+		catalog() {
+			return Array.from(definitions.values()).map((def) => ({
+				name: def.name,
+				version: def.version,
+				description: def.description,
+				schema: def.schema
+			}));
+		},
+		validate(name, payload, version) {
+			let target = version !== void 0 ? definitions.get(registryKey(name, version)) : void 0;
+			if (!target && version === void 0) {
+				let latestVersion = -1;
+				for (const candidate of definitions.values()) if (candidate.name === name && candidate.version > latestVersion) {
+					target = candidate;
+					latestVersion = candidate.version;
+				}
+			}
+			if (!target) return { valid: true };
+			if (!target.schema) return { valid: true };
+			return customValidator ? customValidator(target.schema, payload) : validatePayload(payload, target.schema);
+		}
+	};
+}
+/**
+* Built-in minimal validator — lightweight guard, NOT a full JSON Schema engine.
+*
+* Checks:
+* - payload is an object (not null, not array)
+* - required fields are present
+* - top-level property types match (string, number, boolean, array, object)
+*
+* Does NOT check:
+* - nested object properties
+* - array item types
+* - enum, pattern, format, minLength, minimum, $ref
+*
+* For full validation, pass a custom `validate` function to `createEventRegistry()`.
+*/
+function validatePayload(payload, schema) {
+	const errors = [];
+	if (schema.type === "object") {
+		if (payload === null || payload === void 0 || typeof payload !== "object" || Array.isArray(payload)) return {
+			valid: false,
+			errors: ["Payload must be an object"]
+		};
+		const record = payload;
+		if (schema.required) {
+			for (const field of schema.required) if (!(field in record) || record[field] === void 0) errors.push(`Missing required field: '${field}'`);
+		}
+		if (schema.properties) {
+			for (const [key, propSchema] of Object.entries(schema.properties)) if (key in record && record[key] !== void 0 && record[key] !== null) {
+				const expectedType = propSchema.type;
+				if (expectedType) {
+					const value = record[key];
+					const actualType = Array.isArray(value) ? "array" : typeof value;
+					if (expectedType === "integer") {
+						if (actualType !== "number" || !Number.isInteger(value)) errors.push(`Field '${key}': expected integer, got ${actualType}`);
+					} else if (expectedType !== actualType) errors.push(`Field '${key}': expected ${expectedType}, got ${actualType}`);
+				}
+			}
+		}
+	}
+	return errors.length === 0 ? { valid: true } : {
+		valid: false,
+		errors
+	};
+}
+//#endregion
+//#region src/events/subscribe-helpers.ts
+/**
+* Subscribe-side helpers — close the symmetry that arc's publish-side
+* already has via [`eventPlugin({ registry, validateMode: 'reject' })`](./eventPlugin.ts).
+*
+* Two wrapper pairs, both transport-agnostic:
+*
+* - `wrapWithSchema` / `subscribeWithSchema` — read the schema from a
+*   typed `EventDefinitionOutput<T>` and validate `event.payload` before
+*   the handler runs. Single source of truth for event shape: declare
+*   once at `defineEvent`, enforced on BOTH sides without parallel Zod
+*   schemas in subscriber files.
+*
+* - `wrapWithBoundary` / `subscribeWithBoundary` — catch + log + swallow
+*   handler errors, for projection / cache-invalidation / fire-and-forget
+*   handlers where retry would just delay the next-event resync. Lighter
+*   than `withRetry` (no DLQ, no exponential backoff) and avoids the
+*   "single bad event poisons the bus" hazard.
+*
+* Both pairs compose with `withRetry` and with each other:
+*
+* ```ts
+* await subscribeWithSchema(
+*   fastify,
+*   OrderPaid,
+*   withRetry(handler, { maxRetries: 3 }),
+* );
+* ```
+*
+* @see [retry.ts](./retry.ts) for the retry + DLQ wrapper.
+* @see [defineEvent.ts](./defineEvent.ts) for `defineEvent` / `EventDefinitionOutput`.
+*/
+/**
+* Pure handler wrapper — returns a new `EventHandler` that validates
+* `event.payload` against the definition's schema before invoking the handler.
+*
+* The returned handler's input is `DomainEvent<unknown>` (since the transport
+* delivers untyped events) but the inner `handler` receives `DomainEvent<T>`.
+* No cast at the call site.
+*
+* @example
+* ```ts
+* await fastify.events.subscribe(
+*   OrderPaid.name,
+*   wrapWithSchema(OrderPaid, async (event) => {
+*     // event.payload is typed via the registered schema — no cast.
+*     await postSalesEntry(event.payload.orderId, event.payload.total);
+*   }),
+* );
+* ```
+*/
+function wrapWithSchema(definition, handler, options = {}) {
+	const { validate, registry, onInvalid, logger = console, name } = options;
+	const label = name ?? definition.name;
+	return async (event) => {
+		const eventVersion = typeof event.meta?.schemaVersion === "number" ? event.meta.schemaVersion : definition.version;
+		let result;
+		if (validate && definition.schema) result = validate(definition.schema, event.payload);
+		else if (registry) result = registry.validate(definition.name, event.payload, eventVersion);
+		else if (definition.schema) {
+			const adhoc = createEventRegistry();
+			adhoc.register(definition);
+			result = adhoc.validate(definition.name, event.payload);
+		} else result = { valid: true };
+		if (!result.valid) {
+			const errors = result.errors ?? ["payload failed validation"];
+			if (onInvalid) try {
+				await onInvalid(event, errors);
+			} catch (cbErr) {
+				logger.error(`[Arc Events] '${label}' onInvalid callback threw:`, cbErr);
+			}
+			else logger.warn(`[Arc Events] '${label}' skipped event ${event.meta?.id ?? "<no-id>"} — payload failed validation: ${errors.join("; ")}`);
+			return;
+		}
+		await handler(event);
+	};
+}
+/**
+* Convenience: validate + subscribe in one call. Equivalent to
+* `fastify.events.subscribe(definition.name, wrapWithSchema(definition, handler, options))`.
+*
+* Returns the unsubscribe function from the underlying transport.
+*
+* @example
+* ```ts
+* await subscribeWithSchema(fastify, OrderPaid, async (event) => {
+*   await postSalesEntry(event.payload.orderId, event.payload.total);
+* });
+*
+* // Compose with withRetry — schema validation runs FIRST, then retry on
+* // handler failure. Invalid payloads skip without burning retry attempts.
+* await subscribeWithSchema(
+*   fastify,
+*   OrderPaid,
+*   withRetry(handler, { maxRetries: 3 }),
+* );
+* ```
+*/
+async function subscribeWithSchema(fastify, definition, handler, options) {
+	return fastify.events.subscribe(definition.name, wrapWithSchema(definition, handler, options));
+}
+/**
+* Pure handler wrapper — returns a new `EventHandler` that catches handler
+* exceptions and routes them to `onError` (or logs and swallows). For
+* projection / cache-invalidation / fire-and-forget handlers where retry
+* would just delay the next-event resync, and where one bad event must NOT
+* stop processing of subsequent events.
+*
+* Lighter than `withRetry`: no exponential backoff, no DLQ. Composes with
+* `withRetry` if you want both ("retry, then log if exhausted, never throw").
+*
+* @example
+* ```ts
+* await fastify.events.subscribe(
+*   'product:variants.changed',
+*   wrapWithBoundary(async (event) => {
+*     cache.invalidate(event.payload.productId);
+*   }),
+* );
+* ```
+*/
+function wrapWithBoundary(handler, options = {}) {
+	const { onError, logger = console, name } = options;
+	const label = name ?? handler.name ?? "anonymous";
+	return async (event) => {
+		try {
+			await handler(event);
+		} catch (err) {
+			const error = err instanceof Error ? err : new Error(String(err));
+			if (onError) try {
+				await onError(error, event);
+			} catch (cbErr) {
+				logger.error(`[Arc Events] '${label}' onError callback threw:`, cbErr);
+			}
+			else logger.error(`[Arc Events] '${label}' threw on ${event.type} — swallowed (boundary): ${error.message}`, {
+				err: error,
+				event: event.type,
+				eventId: event.meta?.id,
+				handler: label
+			});
+		}
+	};
+}
+/**
+* Convenience: subscribe + error-boundary in one call. Equivalent to
+* `fastify.events.subscribe(pattern, wrapWithBoundary(handler, options))`.
+*
+* Returns the unsubscribe function from the underlying transport.
+*/
+async function subscribeWithBoundary(fastify, pattern, handler, options) {
+	return fastify.events.subscribe(pattern, wrapWithBoundary(handler, options));
+}
+//#endregion
+export { createEventRegistry as a, wrapWithSchema as i, subscribeWithSchema as n, defineEvent as o, wrapWithBoundary as r, subscribeWithBoundary as t };

package/dist/testing/cleanupStoreContract.d.mts

@@ -0,0 +1,10 @@
+import { D as CleanupRunStore } from "../types-C_ZZRcD6.mjs";
+//#region src/testing/cleanupStoreContract.d.ts
+interface CleanupRunStoreContractSetupResult {
+  store: CleanupRunStore;
+  teardown?: () => Promise<void>;
+}
+type CleanupRunStoreContractSetup = () => Promise<CleanupRunStoreContractSetupResult>;
+declare function runCleanupRunStoreContract(name: string, setup: CleanupRunStoreContractSetup): void;
+//#endregion
+export { CleanupRunStoreContractSetup, CleanupRunStoreContractSetupResult, runCleanupRunStoreContract };