@classytic/arc 2.3.0 → 2.4.1

package/dist/cli/index.mjs

@@ -1,156 +1,7 @@
+import describe from "./commands/describe.mjs";
+import { exportDocs } from "./commands/docs.mjs";
+import { doctor } from "./commands/doctor.mjs";
 import generate from "./commands/generate.mjs";
 import init from "./commands/init.mjs";
 import introspect from "./commands/introspect.mjs";
-import describe from "./commands/describe.mjs";
-import { exportDocs } from "./commands/docs.mjs";
-import { existsSync, readFileSync } from "node:fs";
-import { join, resolve } from "node:path";
-
-//#region src/cli/commands/doctor.ts
-/**
-* Arc CLI - Doctor Command
-*
-* Health check utility that validates the development environment.
-* Checks Node.js version, dependencies, configuration, and env variables.
-*/
-async function doctor(_args = []) {
-	console.log("\nArc Doctor\n");
-	const results = [];
-	const cwd = process.cwd();
-	const nodeVersion = process.versions.node;
-	if (parseInt(nodeVersion.split(".")[0] ?? "0", 10) >= 22) results.push({
-		status: "pass",
-		label: `Node.js ${nodeVersion}`,
-		detail: "required: >=22"
-	});
-	else results.push({
-		status: "fail",
-		label: `Node.js ${nodeVersion}`,
-		detail: "required: >=22"
-	});
-	const pkg = findPackageJson(cwd);
-	const allDeps = {
-		...pkg?.dependencies ?? {},
-		...pkg?.devDependencies ?? {}
-	};
-	const arcVersion = allDeps["@classytic/arc"];
-	if (arcVersion) results.push({
-		status: "pass",
-		label: `@classytic/arc ${arcVersion}`
-	});
-	else results.push({
-		status: "warn",
-		label: "@classytic/arc not found in dependencies"
-	});
-	const fastifyVersion = allDeps["fastify"];
-	if (fastifyVersion) {
-		const clean = fastifyVersion.replace(/^[\^~>=<]+/, "");
-		if (parseInt(clean.split(".")[0] ?? "0", 10) >= 5) results.push({
-			status: "pass",
-			label: `fastify ${fastifyVersion}`,
-			detail: "required: ^5.0.0"
-		});
-		else results.push({
-			status: "fail",
-			label: `fastify ${fastifyVersion}`,
-			detail: "required: ^5.0.0 — Arc requires Fastify 5"
-		});
-	} else results.push({
-		status: "fail",
-		label: "fastify not found in dependencies",
-		detail: "required: ^5.0.0"
-	});
-	const tsconfigPath = resolve(cwd, "tsconfig.json");
-	if (existsSync(tsconfigPath)) try {
-		const stripped = readFileSync(tsconfigPath, "utf-8").replace(/\/\/.*$/gm, "");
-		const moduleRes = JSON.parse(stripped)?.compilerOptions?.moduleResolution;
-		if (moduleRes && ![
-			"nodenext",
-			"node16",
-			"bundler"
-		].includes(moduleRes.toLowerCase())) results.push({
-			status: "warn",
-			label: "tsconfig.json found",
-			detail: `moduleResolution "${moduleRes}" — recommend "NodeNext" or "Bundler"`
-		});
-		else results.push({
-			status: "pass",
-			label: "tsconfig.json found"
-		});
-	} catch {
-		results.push({
-			status: "pass",
-			label: "tsconfig.json found"
-		});
-	}
-	else results.push({
-		status: "warn",
-		label: "tsconfig.json not found"
-	});
-	for (const dep of [
-		{
-			name: "@fastify/rate-limit",
-			purpose: "rate limiting"
-		},
-		{
-			name: "@fastify/helmet",
-			purpose: "security headers"
-		},
-		{
-			name: "@fastify/cors",
-			purpose: "CORS support"
-		}
-	]) if (allDeps[dep.name]) results.push({
-		status: "pass",
-		label: `${dep.name} installed`
-	});
-	else results.push({
-		status: "warn",
-		label: `${dep.name} not installed`,
-		detail: `${dep.purpose} disabled`
-	});
-	if (allDeps["better-auth"]) results.push({
-		status: "pass",
-		label: `better-auth ${allDeps["better-auth"]}`
-	});
-	for (const env of [{
-		name: "MONGO_URI",
-		severity: "warn",
-		detail: "required at runtime for MongoDB"
-	}, {
-		name: "BETTER_AUTH_SECRET",
-		severity: "warn",
-		detail: "required for Better Auth session encryption"
-	}]) if (process.env[env.name]) results.push({
-		status: "pass",
-		label: `${env.name} set`
-	});
-	else results.push({
-		status: env.severity,
-		label: `${env.name} not set`,
-		detail: env.detail
-	});
-	let passCount = 0;
-	let warnCount = 0;
-	let failCount = 0;
-	for (const r of results) {
-		const icon = r.status === "pass" ? "[pass]" : r.status === "warn" ? "[warn]" : "[FAIL]";
-		const detail = r.detail ? ` (${r.detail})` : "";
-		console.log(`  ${icon} ${r.label}${detail}`);
-		if (r.status === "pass") passCount++;
-		else if (r.status === "warn") warnCount++;
-		else failCount++;
-	}
-	console.log(`\n${passCount} passed, ${warnCount} warnings, ${failCount} failures\n`);
-	if (failCount > 0) process.exitCode = 1;
-}
-function findPackageJson(dir) {
-	const paths = [join(dir, "package.json"), join(dir, "..", "package.json")];
-	for (const p of paths) try {
-		if (existsSync(p)) return JSON.parse(readFileSync(p, "utf-8"));
-	} catch {}
-	return null;
-}
-
-//#endregion
-export { describe, doctor, exportDocs, generate, init, introspect };
+export { describe, doctor, exportDocs, generate, init, introspect };

package/dist/{constants-DdXFXQtN.mjs → constants-Cxde4rpC.mjs}

@@ -79,6 +79,5 @@ const RESERVED_QUERY_PARAMS = Object.freeze(new Set([
 	"lean",
 	"_policyFilters"
 ]));
-
 //#endregion
-export { DEFAULT_SORT as a, HOOK_OPERATIONS as c, MAX_REGEX_LENGTH as d, MAX_SEARCH_LENGTH as f, SYSTEM_FIELDS as h, DEFAULT_MAX_LIMIT as i, HOOK_PHASES as l, RESERVED_QUERY_PARAMS as m, DEFAULT_ID_FIELD as n, DEFAULT_TENANT_FIELD as o, MUTATION_OPERATIONS as p, DEFAULT_LIMIT as r, DEFAULT_UPDATE_METHOD as s, CRUD_OPERATIONS as t, MAX_FILTER_DEPTH as u };
+export { DEFAULT_SORT as a, HOOK_OPERATIONS as c, MAX_REGEX_LENGTH as d, MAX_SEARCH_LENGTH as f, SYSTEM_FIELDS as h, DEFAULT_MAX_LIMIT as i, HOOK_PHASES as l, RESERVED_QUERY_PARAMS as m, DEFAULT_ID_FIELD as n, DEFAULT_TENANT_FIELD as o, MUTATION_OPERATIONS as p, DEFAULT_LIMIT as r, DEFAULT_UPDATE_METHOD as s, CRUD_OPERATIONS as t, MAX_FILTER_DEPTH as u };

package/dist/core/index.d.mts

@@ -1,5 +1,3 @@
-import "../elevation-DGo5shaX.mjs";
-import { E as defineResource, T as ResourceDefinition, c as BaseController, d as QueryResolverConfig, f as BodySanitizer, h as AccessControlConfig, l as BaseControllerOptions, m as AccessControl, p as BodySanitizerConfig, u as QueryResolver } from "../interface-BtdYtQUA.mjs";
-import "../types-RLkFVgaw.mjs";
-import { A as createCrudRouter, C as MutationOperation, D as ActionRouterConfig, E as ActionHandler, O as IdempotencyService, S as MUTATION_OPERATIONS, T as SYSTEM_FIELDS, _ as HookOperation, a as getControllerScope, b as MAX_REGEX_LENGTH, c as CrudOperation, d as DEFAULT_MAX_LIMIT, f as DEFAULT_SORT, g as HOOK_PHASES, h as HOOK_OPERATIONS, i as getControllerContext, j as createPermissionMiddleware, k as createActionRouter, l as DEFAULT_ID_FIELD, m as DEFAULT_UPDATE_METHOD, n as createFastifyHandler, o as sendControllerResponse, p as DEFAULT_TENANT_FIELD, r as createRequestContext, s as CRUD_OPERATIONS, t as createCrudHandlers, u as DEFAULT_LIMIT, v as HookPhase, w as RESERVED_QUERY_PARAMS, x as MAX_SEARCH_LENGTH, y as MAX_FILTER_DEPTH } from "../fastifyAdapter-6b_eRDBw.mjs";
-export { AccessControl, type AccessControlConfig, type ActionHandler, type ActionRouterConfig, BaseController, type BaseControllerOptions, BodySanitizer, type BodySanitizerConfig, CRUD_OPERATIONS, CrudOperation, DEFAULT_ID_FIELD, DEFAULT_LIMIT, DEFAULT_MAX_LIMIT, DEFAULT_SORT, DEFAULT_TENANT_FIELD, DEFAULT_UPDATE_METHOD, HOOK_OPERATIONS, HOOK_PHASES, HookOperation, HookPhase, type IdempotencyService, MAX_FILTER_DEPTH, MAX_REGEX_LENGTH, MAX_SEARCH_LENGTH, MUTATION_OPERATIONS, MutationOperation, QueryResolver, type QueryResolverConfig, RESERVED_QUERY_PARAMS, ResourceDefinition, SYSTEM_FIELDS, createActionRouter, createCrudHandlers, createCrudRouter, createFastifyHandler, createPermissionMiddleware, createRequestContext, defineResource, getControllerContext, getControllerScope, sendControllerResponse };
+import { Ct as QueryResolverConfig, Dt as AccessControlConfig, Et as AccessControl, Lt as ResourceDefinition, Rt as defineResource, St as QueryResolver, Tt as BodySanitizerConfig, bt as BaseController, wt as BodySanitizer, xt as BaseControllerOptions } from "../interface-DGmPxakH.mjs";
+import { A as RESERVED_QUERY_PARAMS, C as HookOperation, D as MAX_SEARCH_LENGTH, E as MAX_REGEX_LENGTH, O as MUTATION_OPERATIONS, S as HOOK_PHASES, T as MAX_FILTER_DEPTH, _ as DEFAULT_MAX_LIMIT, a as getControllerScope, b as DEFAULT_UPDATE_METHOD, c as createPermissionMiddleware, d as IdempotencyService, f as createActionRouter, g as DEFAULT_LIMIT, h as DEFAULT_ID_FIELD, i as getControllerContext, j as SYSTEM_FIELDS, k as MutationOperation, l as ActionHandler, m as CrudOperation, n as createFastifyHandler, o as sendControllerResponse, p as CRUD_OPERATIONS, r as createRequestContext, s as createCrudRouter, t as createCrudHandlers, u as ActionRouterConfig, v as DEFAULT_SORT, w as HookPhase, x as HOOK_OPERATIONS, y as DEFAULT_TENANT_FIELD } from "../index-BL8CaQih.mjs";
+export { AccessControl, AccessControlConfig, ActionHandler, ActionRouterConfig, BaseController, BaseControllerOptions, BodySanitizer, BodySanitizerConfig, CRUD_OPERATIONS, CrudOperation, DEFAULT_ID_FIELD, DEFAULT_LIMIT, DEFAULT_MAX_LIMIT, DEFAULT_SORT, DEFAULT_TENANT_FIELD, DEFAULT_UPDATE_METHOD, HOOK_OPERATIONS, HOOK_PHASES, HookOperation, HookPhase, IdempotencyService, MAX_FILTER_DEPTH, MAX_REGEX_LENGTH, MAX_SEARCH_LENGTH, MUTATION_OPERATIONS, MutationOperation, QueryResolver, QueryResolverConfig, RESERVED_QUERY_PARAMS, ResourceDefinition, SYSTEM_FIELDS, createActionRouter, createCrudHandlers, createCrudRouter, createFastifyHandler, createPermissionMiddleware, createRequestContext, defineResource, getControllerContext, getControllerScope, sendControllerResponse };

package/dist/core/index.mjs

@@ -1,4 +1,5 @@
-import { a as DEFAULT_SORT, c as HOOK_OPERATIONS, d as MAX_REGEX_LENGTH, f as MAX_SEARCH_LENGTH, h as SYSTEM_FIELDS, i as DEFAULT_MAX_LIMIT, l as HOOK_PHASES, m as RESERVED_QUERY_PARAMS, n as DEFAULT_ID_FIELD, o as DEFAULT_TENANT_FIELD, p as MUTATION_OPERATIONS, r as DEFAULT_LIMIT, s as DEFAULT_UPDATE_METHOD, t as CRUD_OPERATIONS, u as MAX_FILTER_DEPTH } from "../constants-DdXFXQtN.mjs";
-import { _ as QueryResolver, c as createPermissionMiddleware, d as createFastifyHandler, f as createRequestContext, g as BaseController, h as sendControllerResponse, m as getControllerScope, n as defineResource, o as createActionRouter, p as getControllerContext, s as createCrudRouter, t as ResourceDefinition, u as createCrudHandlers, v as BodySanitizer, y as AccessControl } from "../defineResource-DWbpJYtm.mjs";
-
-export { AccessControl, BaseController, BodySanitizer, CRUD_OPERATIONS, DEFAULT_ID_FIELD, DEFAULT_LIMIT, DEFAULT_MAX_LIMIT, DEFAULT_SORT, DEFAULT_TENANT_FIELD, DEFAULT_UPDATE_METHOD, HOOK_OPERATIONS, HOOK_PHASES, MAX_FILTER_DEPTH, MAX_REGEX_LENGTH, MAX_SEARCH_LENGTH, MUTATION_OPERATIONS, QueryResolver, RESERVED_QUERY_PARAMS, ResourceDefinition, SYSTEM_FIELDS, createActionRouter, createCrudHandlers, createCrudRouter, createFastifyHandler, createPermissionMiddleware, createRequestContext, defineResource, getControllerContext, getControllerScope, sendControllerResponse };
+import { a as DEFAULT_SORT, c as HOOK_OPERATIONS, d as MAX_REGEX_LENGTH, f as MAX_SEARCH_LENGTH, h as SYSTEM_FIELDS, i as DEFAULT_MAX_LIMIT, l as HOOK_PHASES, m as RESERVED_QUERY_PARAMS, n as DEFAULT_ID_FIELD, o as DEFAULT_TENANT_FIELD, p as MUTATION_OPERATIONS, r as DEFAULT_LIMIT, s as DEFAULT_UPDATE_METHOD, t as CRUD_OPERATIONS, u as MAX_FILTER_DEPTH } from "../constants-Cxde4rpC.mjs";
+import { i as AccessControl, n as QueryResolver, r as BodySanitizer, t as BaseController } from "../BaseController-CkM5dUh_.mjs";
+import { t as createActionRouter } from "../core-C1XCMtqM.mjs";
+import { c as createCrudHandlers, d as getControllerContext, f as getControllerScope, l as createFastifyHandler, n as defineResource, o as createCrudRouter, p as sendControllerResponse, s as createPermissionMiddleware, t as ResourceDefinition, u as createRequestContext } from "../defineResource-D9aY5Cy6.mjs";
+export { AccessControl, BaseController, BodySanitizer, CRUD_OPERATIONS, DEFAULT_ID_FIELD, DEFAULT_LIMIT, DEFAULT_MAX_LIMIT, DEFAULT_SORT, DEFAULT_TENANT_FIELD, DEFAULT_UPDATE_METHOD, HOOK_OPERATIONS, HOOK_PHASES, MAX_FILTER_DEPTH, MAX_REGEX_LENGTH, MAX_SEARCH_LENGTH, MUTATION_OPERATIONS, QueryResolver, RESERVED_QUERY_PARAMS, ResourceDefinition, SYSTEM_FIELDS, createActionRouter, createCrudHandlers, createCrudRouter, createFastifyHandler, createPermissionMiddleware, createRequestContext, defineResource, getControllerContext, getControllerScope, sendControllerResponse };

package/dist/core-C1XCMtqM.mjs

@@ -0,0 +1,185 @@
+//#region src/core/createActionRouter.ts
+/**
+* Create action-based state transition endpoint
+*
+* Registers: POST /:id/action
+* Body: { action: string, ...actionData }
+*
+* @param fastify - Fastify instance
+* @param config - Action router configuration
+*/
+function createActionRouter(fastify, config) {
+	const { tag, actions, actionPermissions = {}, actionSchemas = {}, globalAuth, idempotencyService, onError } = config;
+	const actionEnum = Object.keys(actions);
+	if (actionEnum.length === 0) {
+		fastify.log.warn("[createActionRouter] No actions defined, skipping route creation");
+		return;
+	}
+	const bodyProperties = { action: {
+		type: "string",
+		enum: actionEnum,
+		description: `Action to perform: ${actionEnum.join(" | ")}`
+	} };
+	Object.entries(actionSchemas).forEach(([actionName, schema]) => {
+		if (schema && typeof schema === "object") Object.entries(schema).forEach(([propName, propSchema]) => {
+			bodyProperties[propName] = {
+				...propSchema,
+				description: `${propSchema.description || ""} (for ${actionName} action)`.trim()
+			};
+		});
+	});
+	const routeSchema = {
+		tags: tag ? [tag] : void 0,
+		summary: `Perform action (${actionEnum.join("/")})`,
+		description: buildActionDescription(actions, actionPermissions),
+		params: {
+			type: "object",
+			properties: { id: {
+				type: "string",
+				description: "Resource ID"
+			} },
+			required: ["id"]
+		},
+		body: {
+			type: "object",
+			properties: bodyProperties,
+			required: ["action"]
+		}
+	};
+	const preHandler = [];
+	const hasPublicActions = Object.entries(actionPermissions).some(([, p]) => p?._isPublic) || globalAuth && globalAuth?._isPublic;
+	const hasProtectedActions = Object.entries(actionPermissions).some(([, p]) => !p?._isPublic) || globalAuth && !globalAuth?._isPublic;
+	if (hasProtectedActions && !hasPublicActions && fastify.authenticate) preHandler.push(fastify.authenticate);
+	fastify.post("/:id/action", {
+		schema: routeSchema,
+		preHandler: preHandler.length ? preHandler : void 0
+	}, async (req, reply) => {
+		const { action, ...data } = req.body;
+		const { id } = req.params;
+		const rawIdempotencyKey = req.headers["idempotency-key"];
+		const idempotencyKey = Array.isArray(rawIdempotencyKey) ? rawIdempotencyKey[0] : rawIdempotencyKey;
+		const handler = actions[action];
+		if (!handler) return reply.code(400).send({
+			success: false,
+			error: `Invalid action '${action}'. Valid actions: ${actionEnum.join(", ")}`,
+			validActions: actionEnum
+		});
+		const permissionCheck = actionPermissions[action] ?? globalAuth;
+		if (hasPublicActions && hasProtectedActions && permissionCheck) {
+			if (!permissionCheck?._isPublic && fastify.authenticate) {
+				try {
+					await fastify.authenticate(req, reply);
+				} catch {
+					if (!reply.sent) return reply.code(401).send({
+						success: false,
+						error: "Authentication required"
+					});
+					return;
+				}
+				if (reply.sent) return;
+			}
+		}
+		if (permissionCheck) {
+			const context = {
+				user: req.user ?? null,
+				request: req,
+				resource: tag ?? "action",
+				action,
+				resourceId: id,
+				params: req.params,
+				data
+			};
+			let result;
+			try {
+				result = await permissionCheck(context);
+			} catch (err) {
+				req.log?.warn?.({
+					err,
+					resource: tag ?? "action",
+					action
+				}, "Permission check threw");
+				return reply.code(403).send({
+					success: false,
+					error: "Permission denied"
+				});
+			}
+			if (typeof result === "boolean") {
+				if (!result) return reply.code(context.user ? 403 : 401).send({
+					success: false,
+					error: context.user ? `Permission denied for '${action}'` : "Authentication required"
+				});
+			} else {
+				const permResult = result;
+				if (!permResult.granted) return reply.code(context.user ? 403 : 401).send({
+					success: false,
+					error: permResult.reason ?? (context.user ? `Permission denied for '${action}'` : "Authentication required")
+				});
+			}
+		}
+		try {
+			if (idempotencyKey && idempotencyService) {
+				const user = req.user;
+				const payloadForHash = {
+					action,
+					id,
+					data,
+					userId: (user?._id)?.toString?.() || user?.id || null
+				};
+				const idempotencyResult = await idempotencyService.check(idempotencyKey, payloadForHash);
+				if (!idempotencyResult.isNew && "existingResult" in idempotencyResult) return reply.send({
+					success: true,
+					data: idempotencyResult.existingResult,
+					cached: true
+				});
+			}
+			const result = await handler(id, data, req);
+			if (idempotencyService) await idempotencyService.complete(idempotencyKey, result);
+			return reply.send({
+				success: true,
+				data: result
+			});
+		} catch (error) {
+			if (idempotencyService) await idempotencyService.fail(idempotencyKey, error);
+			if (onError) {
+				const { statusCode, error: errorMsg, code } = onError(error, action, id);
+				return reply.code(statusCode).send({
+					success: false,
+					error: errorMsg,
+					code
+				});
+			}
+			const err = error;
+			const statusCode = err.statusCode || err.status || 500;
+			const errorCode = err.code || "ACTION_FAILED";
+			if (statusCode >= 500) req.log.error({
+				err: error,
+				action,
+				id
+			}, "Action handler error");
+			return reply.code(statusCode).send({
+				success: false,
+				error: err.message || `Failed to execute '${action}' action`,
+				code: errorCode
+			});
+		}
+	});
+	fastify.log.debug({
+		actions: actionEnum,
+		tag
+	}, "[createActionRouter] Registered action endpoint: POST /:id/action");
+}
+/**
+* Build description with action details
+* Uses _roles metadata from PermissionCheck functions for OpenAPI docs
+*/
+function buildActionDescription(actions, actionPermissions) {
+	const lines = ["Unified action endpoint for state transitions.\n\n**Available actions:**"];
+	Object.keys(actions).forEach((action) => {
+		const roles = actionPermissions[action]?._roles;
+		const roleStr = roles?.length ? ` (requires: ${roles.join(" or ")})` : "";
+		lines.push(`- \`${action}\`${roleStr}`);
+	});
+	return lines.join("\n");
+}
+//#endregion
+export { createActionRouter as t };

package/dist/{createApp-CgKOPhA4.mjs → createApp-ByWNRsZj.mjs}

@@ -1,8 +1,7 @@
-import { t as __exportAll } from "./chunk-C7Uep-_p.mjs";
-import { n as PUBLIC_SCOPE } from "./types-Beqn1Un7.mjs";
+import { t as __exportAll } from "./chunk-BpYLSNr0.mjs";
+import { n as PUBLIC_SCOPE } from "./types-C6TQjtdi.mjs";
 import Fastify from "fastify";
 import qs from "qs";
-
 //#region src/factory/presets.ts
 /**
 * Production preset - strict security, performance optimized
@@ -61,7 +60,7 @@ const productionPreset = {
 	},
 	underPressure: {
 		exposeStatusRoute: true,
-		maxEventLoopDelay: 1e3,
+		maxEventLoopDelay: 3e3,
 		maxHeapUsedBytes: 1024 * 1024 * 1024,
 		maxRssBytes: 1024 * 1024 * 1024
 	}
@@ -128,18 +127,29 @@ const testingPreset = {
 	} }
 };
 /**
-* Edge/Serverless preset - minimal cold-start overhead
+* Edge/Serverless preset — minimal cold-start overhead
 *
-* Optimized for AWS Lambda, Vercel, Cloudflare Workers, and similar environments.
-* Disables all heavy plugins that add cold-start latency:
-* - Security headers (handled by API Gateway / CDN)
-* - Rate limiting (handled by API Gateway / CDN)
-* - Health monitoring (Lambda has its own health checks)
-* - File uploads (use pre-signed URLs instead)
-* - Raw body parsing (register per-route if needed)
+* Strips non-essential plugins to reduce startup time. Designed for:
+* - Cloudflare Workers (requires `nodejs_compat` flag + `toFetchHandler()`)
+* - AWS Lambda via `@fastify/aws-lambda` or `toFetchHandler()`
+* - Vercel Serverless Functions (Node.js runtime)
+* - Google Cloud Functions (Node.js runtime)
+* - Any environment where the platform handles security, rate limiting, and health checks
 *
-* Arc core plugins (requestId, health, gracefulShutdown) are also disabled
-* since the serverless runtime manages request lifecycle.
+* Use with `toFetchHandler()` from `@classytic/arc/factory` for edge runtimes:
+* ```typescript
+* import { createApp, toFetchHandler } from '@classytic/arc/factory';
+* const app = await createApp({ preset: 'edge' });
+* export default { fetch: toFetchHandler(app) };
+* ```
+*
+* **Edge runtime requirements:**
+* - Cloudflare Workers: enable `nodejs_compat` in wrangler.toml
+* - Vercel: use Node.js runtime (not Edge Runtime) or enable nodejs compat
+*
+* Arc uses `node:crypto` and `AsyncLocalStorage` — both supported by
+* modern edge runtimes with Node.js compat flags. No TCP server is needed
+* when using `toFetchHandler()` (routes through Fastify's `.inject()`).
 */
 const edgePreset = {
 	logger: { level: "warn" },
@@ -170,7 +180,6 @@ function getPreset(name) {
 		default: throw new Error(`Unknown preset: ${name}`);
 	}
 }
-
 //#endregion
 //#region src/factory/createApp.ts
 /**
@@ -280,7 +289,7 @@ async function loadPlugin(name, logger) {
 */
 async function createApp(options) {
 	if (options.debug !== void 0 && options.debug !== false) {
-		const { configureArcLogger } = await import("./logger-ByrvQWZO.mjs").then((n) => n.r);
+		const { configureArcLogger } = await import("./logger-Dz3j1ItV.mjs").then((n) => n.r);
 		configureArcLogger({ debug: options.debug });
 	}
 	const authConfig = options.auth;
@@ -288,15 +297,19 @@ async function createApp(options) {
 	if (!isAuthDisabled && authConfig && authConfig.type === "jwt") {
 		if (!authConfig.jwt?.secret && !authConfig.authenticate) throw new Error("createApp: JWT secret required when Arc auth is enabled.\nProvide auth.jwt.secret, auth.authenticate, or set auth: false to disable.\nExample: auth: { type: 'jwt', jwt: { secret: process.env.JWT_SECRET } }");
 	}
+	const deferredWarnings = [];
 	if (options.runtime === "distributed") {
 		const MEMORY_NAMES = new Set(["memory", "memory-cache"]);
 		const missing = [];
 		const eventsTransport = options.stores?.events;
 		if (!eventsTransport || MEMORY_NAMES.has(eventsTransport.name)) missing.push("events transport");
-		const cacheStore = options.stores?.cache;
-		if (!cacheStore || MEMORY_NAMES.has(cacheStore.name)) missing.push("cache store");
+		if (options.arcPlugins?.caching) {
+			const cacheStore = options.stores?.cache;
+			if (!cacheStore || MEMORY_NAMES.has(cacheStore.name)) missing.push("cache store");
+		}
 		const idempotencyStore = options.stores?.idempotency;
-		if (!idempotencyStore || MEMORY_NAMES.has(idempotencyStore.name)) missing.push("idempotency store");
+		if (idempotencyStore && MEMORY_NAMES.has(idempotencyStore.name)) missing.push("idempotency store (memory-backed in distributed mode)");
+		else if (!idempotencyStore) deferredWarnings.push("runtime: 'distributed' — no idempotency store configured. Write-path deduplication will be instance-local. If resources use the idempotency plugin, provide stores.idempotency with a Redis/MongoDB store.");
 		if (options.arcPlugins?.queryCache) {
 			const qcStore = options.stores?.queryCache;
 			if (!qcStore || MEMORY_NAMES.has(qcStore.name)) missing.push("queryCache store");
@@ -307,7 +320,7 @@ async function createApp(options) {
 		...options.preset ? getPreset(options.preset) : {},
 		...options
 	};
-	let fastify = Fastify({
+	const fastify = Fastify({
 		logger: config.logger ?? true,
 		trustProxy: config.trustProxy ?? false,
 		routerOptions: { querystringParser: (str) => qs.parse(str) },
@@ -318,6 +331,7 @@ async function createApp(options) {
 			keywords: ["example", ...config.ajv?.keywords ?? []]
 		} }
 	});
+	for (const warning of deferredWarnings) fastify.log.warn(warning);
 	if (config.typeProvider === "typebox") try {
 		const { TypeBoxValidatorCompiler } = await import("@fastify/type-provider-typebox");
 		fastify.setValidatorCompiler(TypeBoxValidatorCompiler);
@@ -342,7 +356,7 @@ async function createApp(options) {
 	if (config.cors !== false) {
 		const cors = await loadPlugin("cors");
 		const corsOptions = { ...config.cors ?? {} };
-		if (config.preset === "production" && (!corsOptions || !("origin" in corsOptions))) throw new Error("CORS origin must be explicitly configured in production.\nSet cors.origin to allowed domains or set cors: false to disable.\nExample: cors: { origin: ['https://yourdomain.com'] }\nDocs: https://github.com/classytic/arc#security");
+		if (config.preset === "production" && corsOptions && !("origin" in corsOptions)) fastify.log.warn("CORS origin is not explicitly configured in production. Set cors.origin to allowed domains, cors: { origin: '*' }, or cors: false to disable.");
 		if (corsOptions.credentials && corsOptions.origin === "*") corsOptions.origin = true;
 		await fastify.register(cors, corsOptions);
 		fastify.log.debug("CORS enabled");
@@ -354,8 +368,11 @@ async function createApp(options) {
 			timeWindow: "1 minute"
 		};
 		await fastify.register(rateLimit, rateLimitOpts);
-		if (config.preset === "production") {
-			if (!(typeof rateLimitOpts === "object" && "store" in rateLimitOpts)) fastify.log.warn("Rate limiting is using in-memory store. In multi-instance deployments, each instance tracks limits independently. Configure a Redis store for distributed rate limiting: rateLimit: { store: new RedisStore({ ... }) }");
+		if (!(typeof rateLimitOpts === "object" && "store" in rateLimitOpts)) {
+			if (config.runtime === "distributed") {
+				fastify.log.error("Rate limiting is using in-memory store in distributed mode. Each instance tracks limits independently — this breaks rate limiting. Configure a Redis store: rateLimit: { store: new RedisStore({ ... }) }");
+				throw new Error("[Arc] runtime: 'distributed' with rate limiting requires a shared store.\nProvide rateLimit: { store: new RedisStore({ ... }) } or disable rate limiting: rateLimit: false");
+			} else if (config.preset === "production") fastify.log.warn("Rate limiting is using in-memory store. In multi-instance deployments, each instance tracks limits independently. Configure a Redis store for distributed rate limiting: rateLimit: { store: new RedisStore({ ... }) }");
 		}
 		fastify.log.debug("Rate limiting enabled");
 	} else fastify.log.warn("Rate limiting disabled");
@@ -409,7 +426,7 @@ async function createApp(options) {
 	};
 	trackPlugin("arc-core");
 	if (config.arcPlugins?.events !== false) {
-		const { default: eventPlugin } = await import("./eventPlugin-BEOvaDqo.mjs").then((n) => n.n);
+		const { default: eventPlugin } = await import("./eventPlugin-Ba00swHF.mjs").then((n) => n.n);
 		const eventOpts = typeof config.arcPlugins?.events === "object" ? config.arcPlugins.events : {};
 		await fastify.register(eventPlugin, {
 			...eventOpts,
@@ -434,16 +451,16 @@ async function createApp(options) {
 		fastify.log.debug("Arc gracefulShutdown plugin enabled");
 	}
 	if (config.arcPlugins?.caching) {
-		const { default: cachingPlugin } = await import("./caching-GSDJcA6-.mjs").then((n) => n.r);
+		const { default: cachingPlugin } = await import("./caching-BSXB-Xr7.mjs").then((n) => n.r);
 		const cachingOpts = config.arcPlugins.caching === true ? {} : config.arcPlugins.caching;
 		await fastify.register(cachingPlugin, cachingOpts);
 		trackPlugin("arc-caching", cachingOpts);
 		fastify.log.debug("Arc caching plugin enabled");
 	}
 	if (config.arcPlugins?.queryCache) {
-		const { queryCachePlugin } = await import("./queryCachePlugin-B6R0d4av.mjs").then((n) => n.n);
+		const { queryCachePlugin } = await import("./queryCachePlugin-ClosZdNS.mjs").then((n) => n.n);
 		const qcOpts = config.arcPlugins.queryCache === true ? {} : config.arcPlugins.queryCache;
-		const store = options.stores?.queryCache ?? new (await (import("./memory-B2v7KrCB.mjs").then((n) => n.n))).MemoryCacheStore();
+		const store = options.stores?.queryCache ?? new (await (import("./memory-Cb_7iy9e.mjs").then((n) => n.n))).MemoryCacheStore();
 		await fastify.register(queryCachePlugin, {
 			store,
 			...qcOpts
@@ -453,12 +470,25 @@ async function createApp(options) {
 	}
 	if (config.arcPlugins?.sse) if (config.arcPlugins?.events === false) fastify.log.warn("SSE plugin requires events plugin (arcPlugins.events). SSE disabled.");
 	else {
-		const { default: ssePlugin } = await import("./sse-DkqQ1uxb.mjs").then((n) => n.r);
+		const { default: ssePlugin } = await import("./sse-BkViJPlT.mjs").then((n) => n.r);
 		const sseOpts = config.arcPlugins.sse === true ? {} : config.arcPlugins.sse;
 		await fastify.register(ssePlugin, sseOpts);
 		trackPlugin("arc-sse", sseOpts);
 		fastify.log.debug("Arc SSE plugin enabled");
 	}
+	if (config.arcPlugins?.metrics) {
+		const { default: metricsPlugin } = await import("./metrics-Csh4nsvv.mjs").then((n) => n.r);
+		const metricsOpts = config.arcPlugins.metrics === true ? {} : config.arcPlugins.metrics;
+		await fastify.register(metricsPlugin, metricsOpts);
+		trackPlugin("arc-metrics", metricsOpts);
+		fastify.log.debug("Arc metrics plugin enabled");
+	}
+	if (config.arcPlugins?.versioning) {
+		const { default: versioningPlugin } = await import("./versioning-BzfeHmhj.mjs").then((n) => n.r);
+		await fastify.register(versioningPlugin, config.arcPlugins.versioning);
+		trackPlugin("arc-versioning", config.arcPlugins.versioning);
+		fastify.log.debug("Arc versioning plugin enabled");
+	}
 	fastify.decorateRequest("scope", null);
 	fastify.addHook("onRequest", async (request) => {
 		if (!request.scope) request.scope = PUBLIC_SCOPE;
@@ -480,13 +510,13 @@ async function createApp(options) {
 			break;
 		case "authenticator": {
 			const { authenticate, optionalAuthenticate } = authConfig;
-			fastify.decorate("authenticate", async function(request, reply) {
+			fastify.decorate("authenticate", async (request, reply) => {
 				await authenticate(request, reply);
 			});
-			if (!fastify.hasDecorator("optionalAuthenticate")) if (optionalAuthenticate) fastify.decorate("optionalAuthenticate", async function(request, reply) {
+			if (!fastify.hasDecorator("optionalAuthenticate")) if (optionalAuthenticate) fastify.decorate("optionalAuthenticate", async (request, reply) => {
 				await optionalAuthenticate(request, reply);
 			});
-			else fastify.decorate("optionalAuthenticate", async function(request, reply) {
+			else fastify.decorate("optionalAuthenticate", async (request, reply) => {
 				let intercepted = false;
 				const proxyReply = new Proxy(reply, { get(target, prop) {
 					if (prop === "code") return (statusCode) => {
@@ -521,13 +551,13 @@ async function createApp(options) {
 		}
 	}
 	if (config.elevation) {
-		const { elevationPlugin } = await import("./elevation-DSTbVvYj.mjs").then((n) => n.r);
+		const { elevationPlugin } = await import("./elevation-BEdACOLB.mjs").then((n) => n.r);
 		await fastify.register(elevationPlugin, config.elevation);
 		trackPlugin("arc-elevation", config.elevation);
 		fastify.log.debug("Elevation plugin enabled");
 	}
 	if (config.errorHandler !== false) {
-		const { errorHandlerPlugin } = await import("./errorHandler-C3GY3_ow.mjs").then((n) => n.n);
+		const { errorHandlerPlugin } = await import("./errorHandler--zp54tGc.mjs").then((n) => n.n);
 		const errorOpts = typeof config.errorHandler === "object" ? config.errorHandler : { includeStack: config.preset !== "production" };
 		await fastify.register(errorHandlerPlugin, errorOpts);
 		trackPlugin("arc-error-handler", errorOpts);
@@ -583,6 +613,5 @@ const ArcFactory = {
 		});
 	}
 };
-
 //#endregion
-export { getPreset as a, developmentPreset as i, createApp as n, productionPreset as o, createApp_exports as r, testingPreset as s, ArcFactory as t };
+export { getPreset as a, developmentPreset as i, createApp as n, productionPreset as o, createApp_exports as r, testingPreset as s, ArcFactory as t };