@classytic/arc 2.28.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/index.d.mts

@@ -1,8 +1,8 @@
-import { V as ResourceDefinition } from "../index-DPRH0Cme.mjs";
-import { c as AnyRecord } from "../types-Dmw-6Qeo.mjs";
-import { n as ArcModuleInput } from "../types-Cu6vVJmh.mjs";
-import "../index-CZY4EGga.mjs";
-import { n as preloadResourcesAsync, r as CreateAppOptions, t as preloadResources } from "../preloadResources-CM4uUaFv.mjs";
+import { V as ResourceDefinition } from "../index-Q5gzEIWY.mjs";
+import { l as AnyRecord, r as PermissionCheck } from "../types-ChvvVNP8.mjs";
+import { n as ArcModuleInput } from "../types-D_n8L6VY.mjs";
+import "../index-CCzVR-N3.mjs";
+import { n as preloadResourcesAsync, r as CreateAppOptions, t as preloadResources } from "../preloadResources-DCfa2egz.mjs";
 import { StorageContractSetup, StorageContractSetupResult, runStorageContract } from "./storageContract.mjs";
 import { FastifyInstance, FastifyServerOptions } from "fastify";
 import { Mock } from "vitest";
@@ -72,6 +72,34 @@ interface ArcAssertion {
 }
 declare function expectArc(response: ArcResponseLike): ArcAssertion;
 //#endregion
+//#region src/testing/authorizationConformance.d.ts
+/** One surface's observed enforcement: the HTTP status + the filter arc passed the repo. */
+interface SurfaceObservation {
+  /** HTTP status the surface returned (200 = allowed, 401/403 = denied). */
+  status: number;
+  /** The filter arc handed the repository for this surface (undefined if never reached). */
+  filter: AnyRecord | undefined;
+}
+/** Result of {@link runAuthorizationConformance} — one observation per surface. */
+interface AuthorizationConformance {
+  /** `GET /confs` — the CRUD list surface. */
+  list: SurfaceObservation;
+  /** `GET /confs/aggregations/tally` — the aggregation surface. */
+  aggregation: SurfaceObservation;
+  /** Close the throwaway app. Always call (e.g. in `finally`). */
+  close(): Promise<void>;
+}
+/**
+ * Boot a one-resource app gated by `permission` on both list + an aggregation,
+ * hit both surfaces anonymously, and report what arc enforced on each.
+ */
+declare function runAuthorizationConformance(opts: {
+  /** The permission under test — applied to `list` and the aggregation alike. */
+  permission: PermissionCheck;
+  /** Rows the mock repo returns for list (aggregation returns a count). */
+  rows?: AnyRecord[];
+}): Promise<AuthorizationConformance>;
+//#endregion
 //#region src/testing/authSession.d.ts
 /**
  * A concrete auth session — headers ready to drop into `app.inject`.
@@ -622,4 +650,4 @@ declare function createTestApp(options?: CreateTestAppOptions): Promise<TestAppC
  */
 declare function createMinimalTestApp(options?: FastifyServerOptions): FastifyInstance;
 //#endregion
-export { type ArcAssertion, type ArcResponseLike, type AuthMode, type AuthResponse, type BetterAuthTestHelpers, type BetterAuthTestHelpersOptions, type BetterAuthTestUser, type BootModuleAppOptions, type BootModulesInput, type CreateOrgInput, type CreateTestAppOptions, type DbMode, type FixtureDestroyer, type FixtureFactory, type FixtureRegistration, HttpTestHarness, type HttpTestHarnessOptions, type MockRepository, type ModuleTestApp, type OrgResponse, type RoleConfig, type SetupBetterAuthTestAppInput, type SetupBetterAuthTestAppResult, type SignInInput, type SignUpInput, type StorageContractSetup, type StorageContractSetupResult, type TestAppContext, type TestAuthProvider, type TestAuthSession, type TestDatabase, type TestDatabaseFactory, type TestFixtures, type TestkitContext, bootModuleApp, createBetterAuthProvider, createBetterAuthTestHelpers, createCustomAuthProvider, createDataFactory, createHttpTestHarness, createJwtAuthProvider, createMinimalTestApp, createMockController, createMockReply, createMockRepository, createMockRequest, createMockUser, createSpy, createTestApp, createTestFixtures, createTestTimer, expectArc, mongoMemoryDatabase, preloadResources, preloadResourcesAsync, runStorageContract, safeParseBody, setupBetterAuthTestApp, waitFor };
+export { type ArcAssertion, type ArcResponseLike, type AuthMode, type AuthResponse, type AuthorizationConformance, type BetterAuthTestHelpers, type BetterAuthTestHelpersOptions, type BetterAuthTestUser, type BootModuleAppOptions, type BootModulesInput, type CreateOrgInput, type CreateTestAppOptions, type DbMode, type FixtureDestroyer, type FixtureFactory, type FixtureRegistration, HttpTestHarness, type HttpTestHarnessOptions, type MockRepository, type ModuleTestApp, type OrgResponse, type RoleConfig, type SetupBetterAuthTestAppInput, type SetupBetterAuthTestAppResult, type SignInInput, type SignUpInput, type StorageContractSetup, type StorageContractSetupResult, type SurfaceObservation, type TestAppContext, type TestAuthProvider, type TestAuthSession, type TestDatabase, type TestDatabaseFactory, type TestFixtures, type TestkitContext, bootModuleApp, createBetterAuthProvider, createBetterAuthTestHelpers, createCustomAuthProvider, createDataFactory, createHttpTestHarness, createJwtAuthProvider, createMinimalTestApp, createMockController, createMockReply, createMockRepository, createMockRequest, createMockUser, createSpy, createTestApp, createTestFixtures, createTestTimer, expectArc, mongoMemoryDatabase, preloadResources, preloadResourcesAsync, runAuthorizationConformance, runStorageContract, safeParseBody, setupBetterAuthTestApp, waitFor };