@classytic/arc 2.10.8 → 2.11.0

package/dist/utils-D3Yxnrwr.mjs

@@ -0,0 +1,1639 @@
+import { m as RESERVED_QUERY_PARAMS, t as CRUD_OPERATIONS } from "./constants-BhY1OHoH.mjs";
+import { arcLog } from "./logger/index.mjs";
+import { t as ArcError } from "./errors-D5c-5BJL.mjs";
+import { r as getAvailablePresets } from "./presets-k604Lj99.mjs";
+//#region src/utils/simpleEqualityMatcher.ts
+/**
+* `simpleEqualityMatcher` — a minimal, dialect-agnostic flat-key equality
+* matcher for `DataAdapter.matchesFilter` / `BaseController({ matchesFilter })`.
+*
+* **What it does:** for each `[key, expected]` in the filter, compares
+* `item[key]` to `expected` via string coercion (so Mongo `ObjectId` values
+* match their string representation) and returns `true` only if every
+* filter entry matches. Array item values are matched implicitly (contains).
+*
+* **What it does NOT do:**
+* - No `$eq` / `$ne` / `$in` / `$nin` / `$gt` / `$lt` / `$regex` / `$exists`
+* - No `$and` / `$or`
+* - No dot-path traversal (`"owner.id"`)
+* - No schema-specific coercion
+*
+* **Why it exists:** 95%+ of arc's `_policyFilters` are produced by built-in
+* permission helpers and are shaped like `{ ownerId: "u1" }` or
+* `{ organizationId: "org_x" }` — flat equality. For that common shape,
+* this helper is a safe, tested, 15-line defense-in-depth matcher that
+* hosts using minimal repos (no `getOne(compoundFilter)` DB path) can opt
+* into without arc shipping a full Mongo-syntax engine.
+*
+* **When to use:**
+* - Your adapter/repo doesn't natively filter on `getOne(compoundFilter)`
+* - Your `_policyFilters` are flat equality (from arc's built-in permission helpers)
+* - You want defense-in-depth on `validateItemAccess` / `fetchDetailed`'s `getById` fallback
+*
+* **When NOT to use:**
+* - Your `_policyFilters` use operators (`$in`, `$ne`, etc.) — supply a
+*   native matcher (mongokit's repo does the filter at the DB layer; for
+*   custom repos, wrap the kit's own predicate engine).
+* - You're a mongokit / sqlitekit / Prisma user — the DB-level filter
+*   applied by `getOne(compoundFilter)` already covers this.
+*
+* @example
+* ```ts
+* import { simpleEqualityMatcher } from '@classytic/arc/utils';
+*
+* // On a custom adapter
+* const adapter: DataAdapter = {
+*   repository,
+*   type: 'custom',
+*   name: 'in-memory',
+*   matchesFilter: simpleEqualityMatcher,
+* };
+*
+* // Or directly on BaseController for ad-hoc controllers
+* new BaseController(repo, { matchesFilter: simpleEqualityMatcher });
+* ```
+*/
+function simpleEqualityMatcher(item, filters) {
+	if (!item || typeof item !== "object") return false;
+	const obj = item;
+	for (const [key, expected] of Object.entries(filters)) {
+		if (expected && typeof expected === "object" && !Array.isArray(expected) && Object.getPrototypeOf(expected) === Object.prototype && Object.keys(expected).some((k) => k.startsWith("$"))) return false;
+		const actual = obj[key];
+		if (Array.isArray(actual)) {
+			const expectedStr = String(expected);
+			if (!actual.some((v) => String(v) === expectedStr)) return false;
+			continue;
+		}
+		if (String(actual) !== String(expected)) return false;
+	}
+	return true;
+}
+//#endregion
+//#region src/utils/userHelpers.ts
+/**
+* Extract a user ID from a user object. Accepts `id` or `_id` — returns
+* `undefined` when neither is present. Used by arc's controllers to
+* populate `createdBy` / `updatedBy` fields and for cache scoping.
+*
+* @example
+* ```ts
+* import { getUserId } from '@classytic/arc/utils';
+* const uid = getUserId(request.user);
+* ```
+*/
+function getUserId(user) {
+	if (!user) return void 0;
+	const id = user.id ?? user._id;
+	return id ? String(id) : void 0;
+}
+//#endregion
+//#region src/utils/queryParser.ts
+/**
+* Arc Query Parser - Default URL-to-Query Parser
+*
+* Framework-agnostic query parser that converts URL parameters to query options.
+* This is Arc's built-in parser; users can swap in MongoKit's QueryParser,
+* pgkit's parser, or any custom parser implementing QueryParserInterface.
+*
+* @example
+* // Use Arc default parser (auto-applied if no queryParser option)
+* defineResource({ name: 'product', adapter: ... });
+*
+* // Use MongoKit's QueryParser (recommended for MongoDB - has $lookup, aggregations, etc.)
+* import { QueryParser } from '@classytic/mongokit';
+* defineResource({
+*   name: 'product',
+*   adapter: ...,
+*   queryParser: new QueryParser(),
+* });
+*
+* // Use custom parser for SQL databases
+* defineResource({
+*   name: 'user',
+*   adapter: ...,
+*   queryParser: new PgQueryParser(),
+* });
+*/
+const log = arcLog("queryParser");
+/**
+* Regex patterns that can cause catastrophic backtracking (ReDoS attacks)
+* Detects:
+* - Quantifiers: {n,m}
+* - Possessive quantifiers: *+, ++, ?+
+* - Nested quantifiers: (a+)+, (a*)*
+* - Backreferences: \1, \2, etc.
+*/
+const DANGEROUS_REGEX_PATTERNS = /(\{[0-9,]+\}|\*\+|\+\+|\?\+|(\(.+\))\+|\(\?:|\\[0-9]|(\[.+\]).+(\[.+\]))/;
+/**
+* Arc's default query parser
+*
+* Converts URL query parameters to a structured query format:
+* - Pagination: ?page=1&limit=20
+* - Sorting: ?sort=-createdAt,name (- prefix = descending)
+* - Filtering: ?status=active&price[gte]=100&price[lte]=500
+* - Search: ?search=keyword
+* - Populate: ?populate=author,category
+* - Field selection: ?select=name,price,status
+* - Keyset pagination: ?after=cursor_value
+*
+* For advanced MongoDB features ($lookup, aggregations), use MongoKit's QueryParser.
+*/
+var ArcQueryParser = class {
+	maxLimit;
+	defaultLimit;
+	maxRegexLength;
+	maxSearchLength;
+	maxFilterDepth;
+	_allowedFilterFields;
+	_allowedSortFields;
+	_allowedOperators;
+	/** Allowed filter fields (used by MCP for auto-derive) */
+	allowedFilterFields;
+	/** Allowed sort fields (used by MCP for sort descriptions) */
+	allowedSortFields;
+	/** Allowed operators (used by MCP for operator descriptions) */
+	allowedOperators;
+	/** Supported filter operators */
+	operators = {
+		eq: "$eq",
+		ne: "$ne",
+		gt: "$gt",
+		gte: "$gte",
+		lt: "$lt",
+		lte: "$lte",
+		in: "$in",
+		nin: "$nin",
+		like: "$regex",
+		contains: "$regex",
+		regex: "$regex",
+		exists: "$exists"
+	};
+	constructor(options = {}) {
+		this.maxLimit = options.maxLimit ?? 1e3;
+		this.defaultLimit = options.defaultLimit ?? 20;
+		this.maxRegexLength = options.maxRegexLength ?? 200;
+		this.maxSearchLength = options.maxSearchLength ?? 200;
+		this.maxFilterDepth = options.maxFilterDepth ?? 10;
+		if (options.allowedFilterFields) {
+			this._allowedFilterFields = new Set(options.allowedFilterFields);
+			this.allowedFilterFields = options.allowedFilterFields;
+		}
+		if (options.allowedSortFields) {
+			this._allowedSortFields = new Set(options.allowedSortFields);
+			this.allowedSortFields = options.allowedSortFields;
+		}
+		if (options.allowedOperators) {
+			this._allowedOperators = new Set(options.allowedOperators);
+			this.allowedOperators = options.allowedOperators;
+		}
+	}
+	/**
+	* Parse URL query parameters into structured query options
+	*/
+	parse(query) {
+		const q = query ?? {};
+		const page = this.parseNumber(q.page, 1);
+		const limit = Math.min(this.parseNumber(q.limit, this.defaultLimit), this.maxLimit);
+		const after = this.parseString(q.after ?? q.cursor);
+		const sort = this.parseSort(q.sort);
+		const { populate, populateOptions } = this.parsePopulate(q.populate);
+		const search = this.parseSearch(q.search);
+		const select = this.parseSelect(q.select);
+		return {
+			filters: this.parseFilters(q),
+			limit,
+			sort,
+			populate,
+			populateOptions,
+			search,
+			page: after ? void 0 : page,
+			after,
+			select
+		};
+	}
+	parseNumber(value, defaultValue) {
+		if (value === void 0 || value === null) return defaultValue;
+		const num = parseInt(String(value), 10);
+		return Number.isNaN(num) ? defaultValue : Math.max(1, num);
+	}
+	parseString(value) {
+		if (value === void 0 || value === null) return void 0;
+		const str = String(value).trim();
+		return str.length > 0 ? str : void 0;
+	}
+	/**
+	* Parse populate parameter — handles both simple string and bracket notation.
+	*
+	* Simple: ?populate=author,category → { populate: 'author,category' }
+	* Bracket: ?populate[author][select]=name,email → { populateOptions: [{ path: 'author', select: 'name email' }] }
+	*/
+	parsePopulate(value) {
+		if (value === void 0 || value === null) return {};
+		if (typeof value === "string") {
+			const trimmed = value.trim();
+			return trimmed.length > 0 ? { populate: trimmed } : {};
+		}
+		if (typeof value === "object" && !Array.isArray(value)) {
+			const obj = value;
+			const keys = Object.keys(obj);
+			if (keys.length === 0) return {};
+			const options = [];
+			for (const path of keys) {
+				if (!/^[a-zA-Z_][a-zA-Z0-9_.]*$/.test(path)) continue;
+				const config = obj[path];
+				if (typeof config === "object" && config !== null && !Array.isArray(config)) {
+					const cfg = config;
+					const option = { path };
+					if (typeof cfg.select === "string") option.select = cfg.select.split(",").map((s) => s.trim()).filter(Boolean).join(" ");
+					if (typeof cfg.match === "object" && cfg.match !== null) option.match = cfg.match;
+					options.push(option);
+				} else options.push({ path });
+			}
+			return options.length > 0 ? { populateOptions: options } : {};
+		}
+		return {};
+	}
+	parseSort(value) {
+		if (!value) return void 0;
+		const sortStr = String(value);
+		const result = {};
+		for (const field of sortStr.split(",")) {
+			const trimmed = field.trim();
+			if (!trimmed) continue;
+			if (!/^-?[a-zA-Z_][a-zA-Z0-9_.]*$/.test(trimmed)) continue;
+			const fieldName = trimmed.startsWith("-") ? trimmed.slice(1) : trimmed;
+			if (this._allowedSortFields && !this._allowedSortFields.has(fieldName)) continue;
+			if (trimmed.startsWith("-")) result[fieldName] = -1;
+			else result[fieldName] = 1;
+		}
+		return Object.keys(result).length > 0 ? result : void 0;
+	}
+	parseSearch(value) {
+		if (!value) return void 0;
+		const search = String(value).trim();
+		if (search.length === 0) return void 0;
+		if (search.length > this.maxSearchLength) return search.slice(0, this.maxSearchLength);
+		return search;
+	}
+	parseSelect(value) {
+		if (!value) return void 0;
+		const selectStr = String(value);
+		const result = {};
+		for (const field of selectStr.split(",")) {
+			const trimmed = field.trim();
+			if (!trimmed) continue;
+			if (!/^-?[a-zA-Z_][a-zA-Z0-9_.]*$/.test(trimmed)) continue;
+			if (trimmed.startsWith("-")) result[trimmed.slice(1)] = 0;
+			else result[trimmed] = 1;
+		}
+		return Object.keys(result).length > 0 ? result : void 0;
+	}
+	/**
+	* Check if a value exceeds the maximum nesting depth.
+	* Prevents filter bombs where deeply nested objects consume excessive memory/CPU.
+	*/
+	exceedsDepth(obj, currentDepth = 0) {
+		if (currentDepth > this.maxFilterDepth) return true;
+		if (obj === null || obj === void 0) return false;
+		if (Array.isArray(obj)) return obj.some((v) => this.exceedsDepth(v, currentDepth));
+		if (typeof obj !== "object") return false;
+		return Object.values(obj).some((v) => this.exceedsDepth(v, currentDepth + 1));
+	}
+	parseFilters(query) {
+		const filters = {};
+		for (const [key, value] of Object.entries(query)) {
+			if (RESERVED_QUERY_PARAMS.has(key)) continue;
+			if (value === void 0 || value === null) continue;
+			if (!/^[a-zA-Z_][a-zA-Z0-9_.]*$/.test(key)) continue;
+			if (this._allowedFilterFields && !this._allowedFilterFields.has(key)) continue;
+			if (this.exceedsDepth(value)) continue;
+			if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+				const operatorObj = value;
+				const operatorKeys = Object.keys(operatorObj);
+				const allOperators = operatorKeys.every((op) => this.operators[op] && (!this._allowedOperators || this._allowedOperators.has(op)));
+				const allKnownOperators = operatorKeys.every((op) => this.operators[op]);
+				if (allOperators && operatorKeys.length > 0) {
+					const mongoFilters = {};
+					let needsCaseInsensitive = false;
+					for (const [op, opValue] of Object.entries(operatorObj)) {
+						const mongoOp = this.operators[op];
+						if (mongoOp) {
+							mongoFilters[mongoOp] = this.parseFilterValue(opValue, op);
+							if (op === "contains" || op === "like") needsCaseInsensitive = true;
+						}
+					}
+					if (needsCaseInsensitive) mongoFilters.$options = "i";
+					filters[key] = mongoFilters;
+					continue;
+				}
+				if (allKnownOperators && this._allowedOperators) continue;
+			}
+			const match = key.match(/^([a-zA-Z_][a-zA-Z0-9_.]*)(?:\[([a-z]+)\])?$/);
+			if (!match) continue;
+			const [, fieldName, operator] = match;
+			if (!fieldName) continue;
+			if (operator && this.operators[operator] && (!this._allowedOperators || this._allowedOperators.has(operator))) {
+				const mongoOp = this.operators[operator];
+				const parsedValue = this.parseFilterValue(value, operator);
+				if (!filters[fieldName]) filters[fieldName] = {};
+				const fieldFilter = filters[fieldName];
+				fieldFilter[mongoOp] = parsedValue;
+				if (operator === "contains" || operator === "like") fieldFilter.$options = "i";
+			} else if (!operator) filters[fieldName] = this.parseFilterValue(value);
+		}
+		return filters;
+	}
+	parseFilterValue(value, operator) {
+		if (operator === "in" || operator === "nin") {
+			if (Array.isArray(value)) return value.map((v) => this.coerceValue(v));
+			if (typeof value === "string" && value.includes(",")) return value.split(",").map((v) => this.coerceValue(v.trim()));
+			return [this.coerceValue(value)];
+		}
+		if (operator === "like" || operator === "contains" || operator === "regex") return this.sanitizeRegex(String(value));
+		if (operator === "exists") {
+			const str = String(value).toLowerCase();
+			return str === "true" || str === "1";
+		}
+		return this.coerceValue(value);
+	}
+	coerceValue(value) {
+		if (value === "true") return true;
+		if (value === "false") return false;
+		if (value === "null") return null;
+		if (typeof value === "string") {
+			const num = Number(value);
+			if (!Number.isNaN(num) && value.trim() !== "") return num;
+		}
+		return value;
+	}
+	/**
+	* Generate OpenAPI-compatible JSON Schema for query parameters.
+	* Arc's defineResource() auto-detects this method and uses it
+	* to document list endpoint query parameters in OpenAPI/Swagger.
+	*/
+	getQuerySchema() {
+		const operatorLines = Object.entries(this.operators).map(([op, mongoOp]) => {
+			return `  ${op} → ${mongoOp}: ${{
+				eq: "Equal (default when no operator specified)",
+				ne: "Not equal",
+				gt: "Greater than",
+				gte: "Greater than or equal",
+				lt: "Less than",
+				lte: "Less than or equal",
+				in: "In list (comma-separated values)",
+				nin: "Not in list",
+				like: "Pattern match (case-insensitive)",
+				contains: "Contains substring (case-insensitive)",
+				regex: "Regex pattern",
+				exists: "Field exists (true/false)"
+			}[op] || op}`;
+		});
+		return {
+			type: "object",
+			properties: {
+				page: {
+					type: "integer",
+					description: "Page number for offset pagination",
+					default: 1,
+					minimum: 1
+				},
+				limit: {
+					type: "integer",
+					description: "Number of items per page",
+					default: this.defaultLimit,
+					minimum: 1,
+					maximum: this.maxLimit
+				},
+				sort: {
+					type: "string",
+					description: "Sort fields (comma-separated). Prefix with - for descending. Example: -createdAt,name"
+				},
+				search: {
+					type: "string",
+					description: "Full-text search query",
+					maxLength: this.maxSearchLength
+				},
+				select: {
+					type: "string",
+					description: "Fields to include/exclude (comma-separated). Prefix with - to exclude. Example: name,email,-password"
+				},
+				populate: {
+					type: "string",
+					description: "Fields to populate/join (comma-separated). Example: author,category"
+				},
+				after: {
+					type: "string",
+					description: "Cursor value for keyset pagination"
+				},
+				_filterOperators: {
+					type: "string",
+					description: ["Available filter operators (use as field[operator]=value):", ...operatorLines].join("\n")
+				}
+			}
+		};
+	}
+	sanitizeRegex(pattern) {
+		const truncated = pattern.length > this.maxRegexLength;
+		let sanitized = pattern.slice(0, this.maxRegexLength);
+		if (DANGEROUS_REGEX_PATTERNS.test(sanitized)) {
+			sanitized = sanitized.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+			log.warn(`regex pattern matched a ReDoS-dangerous shape and was escaped to a literal string. original="${pattern}" sanitized="${sanitized}"`);
+		} else if (truncated) log.warn(`regex pattern exceeded maxRegexLength (${this.maxRegexLength}) and was truncated. original-length=${pattern.length}`);
+		return sanitized;
+	}
+};
+/**
+* Create a new ArcQueryParser instance
+*/
+function createQueryParser(options) {
+	return new ArcQueryParser(options);
+}
+//#endregion
+//#region src/utils/responseSchemas.ts
+/**
+* Base success response schema
+*/
+const successResponseSchema = {
+	type: "object",
+	properties: { success: {
+		type: "boolean",
+		example: true
+	} },
+	required: ["success"]
+};
+/**
+* Error response schema
+*/
+const errorResponseSchema = {
+	type: "object",
+	properties: {
+		success: {
+			type: "boolean",
+			example: false
+		},
+		error: {
+			type: "string",
+			description: "Error message"
+		},
+		code: {
+			type: "string",
+			description: "Error code"
+		},
+		message: {
+			type: "string",
+			description: "Detailed message"
+		}
+	},
+	required: ["success", "error"]
+};
+/**
+* Pagination schema - matches MongoKit/Arc runtime format
+*
+* Runtime format (flat fields):
+* { page, limit, total, pages, hasNext, hasPrev }
+*/
+const paginationSchema = {
+	type: "object",
+	properties: {
+		page: {
+			type: "integer",
+			example: 1
+		},
+		limit: {
+			type: "integer",
+			example: 20
+		},
+		total: {
+			type: "integer",
+			example: 100
+		},
+		pages: {
+			type: "integer",
+			example: 5
+		},
+		hasNext: {
+			type: "boolean",
+			example: true
+		},
+		hasPrev: {
+			type: "boolean",
+			example: false
+		}
+	},
+	required: [
+		"page",
+		"limit",
+		"total",
+		"pages",
+		"hasNext",
+		"hasPrev"
+	]
+};
+/**
+* Wrap a data schema in a success response
+*/
+function wrapResponse(dataSchema) {
+	return {
+		type: "object",
+		properties: {
+			success: {
+				type: "boolean",
+				example: true
+			},
+			data: dataSchema
+		},
+		required: ["success", "data"],
+		additionalProperties: true
+	};
+}
+/**
+* Create a list response schema with pagination - matches MongoKit/Arc runtime format
+*
+* Runtime format:
+* { success, docs: [...], page, limit, total, pages, hasNext, hasPrev }
+*
+* Note: Uses 'docs' array (not 'data') with flat pagination fields
+*/
+function listResponse(itemSchema) {
+	return {
+		type: "object",
+		properties: {
+			success: {
+				type: "boolean",
+				example: true
+			},
+			docs: {
+				type: "array",
+				items: itemSchema
+			},
+			page: {
+				type: "integer",
+				example: 1
+			},
+			limit: {
+				type: "integer",
+				example: 20
+			},
+			total: {
+				type: "integer",
+				example: 100
+			},
+			pages: {
+				type: "integer",
+				example: 5
+			},
+			hasNext: {
+				type: "boolean",
+				example: false
+			},
+			hasPrev: {
+				type: "boolean",
+				example: false
+			}
+		},
+		required: ["success", "docs"],
+		additionalProperties: true
+	};
+}
+/**
+* Create a single item response schema
+*
+* Runtime format: { success, data: {...} }
+*/
+function itemResponse(itemSchema) {
+	return wrapResponse(itemSchema);
+}
+/**
+* Create a create/update response schema
+*/
+function mutationResponse(itemSchema) {
+	return {
+		type: "object",
+		properties: {
+			success: {
+				type: "boolean",
+				example: true
+			},
+			data: itemSchema,
+			message: {
+				type: "string",
+				example: "Created successfully"
+			}
+		},
+		required: ["success", "data"],
+		additionalProperties: true
+	};
+}
+/**
+* Create a delete response schema
+*
+* Runtime format: { success, data: { message, id?, soft? } }
+*/
+function deleteResponse() {
+	return {
+		type: "object",
+		properties: {
+			success: {
+				type: "boolean",
+				example: true
+			},
+			data: {
+				type: "object",
+				properties: {
+					message: {
+						type: "string",
+						example: "Deleted successfully"
+					},
+					id: {
+						type: "string",
+						example: "507f1f77bcf86cd799439011"
+					},
+					soft: {
+						type: "boolean",
+						example: false
+					}
+				},
+				required: ["message"]
+			}
+		},
+		required: ["success"],
+		additionalProperties: true
+	};
+}
+const responses = {
+	200: (schema) => ({
+		description: "Successful response",
+		content: { "application/json": { schema } }
+	}),
+	201: (schema) => ({
+		description: "Created successfully",
+		content: { "application/json": { schema: mutationResponse(schema) } }
+	}),
+	400: {
+		description: "Bad Request",
+		content: { "application/json": { schema: {
+			...errorResponseSchema,
+			properties: {
+				...errorResponseSchema.properties,
+				code: {
+					type: "string",
+					example: "VALIDATION_ERROR"
+				},
+				details: {
+					type: "object",
+					properties: { errors: {
+						type: "array",
+						items: {
+							type: "object",
+							properties: {
+								field: { type: "string" },
+								message: { type: "string" }
+							}
+						}
+					} }
+				}
+			}
+		} } }
+	},
+	401: {
+		description: "Unauthorized",
+		content: { "application/json": { schema: {
+			...errorResponseSchema,
+			properties: {
+				...errorResponseSchema.properties,
+				code: {
+					type: "string",
+					example: "UNAUTHORIZED"
+				}
+			}
+		} } }
+	},
+	403: {
+		description: "Forbidden",
+		content: { "application/json": { schema: {
+			...errorResponseSchema,
+			properties: {
+				...errorResponseSchema.properties,
+				code: {
+					type: "string",
+					example: "FORBIDDEN"
+				}
+			}
+		} } }
+	},
+	404: {
+		description: "Not Found",
+		content: { "application/json": { schema: {
+			...errorResponseSchema,
+			properties: {
+				...errorResponseSchema.properties,
+				code: {
+					type: "string",
+					example: "NOT_FOUND"
+				}
+			}
+		} } }
+	},
+	409: {
+		description: "Conflict",
+		content: { "application/json": { schema: {
+			...errorResponseSchema,
+			properties: {
+				...errorResponseSchema.properties,
+				code: {
+					type: "string",
+					example: "CONFLICT"
+				}
+			}
+		} } }
+	},
+	500: {
+		description: "Internal Server Error",
+		content: { "application/json": { schema: {
+			...errorResponseSchema,
+			properties: {
+				...errorResponseSchema.properties,
+				code: {
+					type: "string",
+					example: "INTERNAL_ERROR"
+				}
+			}
+		} } }
+	}
+};
+const queryParams = {
+	pagination: {
+		page: {
+			type: "integer",
+			minimum: 1,
+			default: 1,
+			description: "Page number"
+		},
+		limit: {
+			type: "integer",
+			minimum: 1,
+			maximum: 100,
+			default: 20,
+			description: "Items per page"
+		}
+	},
+	sorting: { sort: {
+		type: "string",
+		description: "Sort field (prefix with - for descending)",
+		example: "-createdAt"
+	} },
+	filtering: {
+		select: {
+			description: "Fields to include (space-separated or object)",
+			example: "name email createdAt"
+		},
+		populate: {
+			description: "Relations to populate (comma-separated string or bracket-notation object)",
+			example: "author,category"
+		}
+	}
+};
+/**
+* Get standard list query parameters schema
+*/
+function getListQueryParams() {
+	return {
+		type: "object",
+		properties: {
+			...queryParams.pagination,
+			...queryParams.sorting,
+			...queryParams.filtering
+		},
+		additionalProperties: true
+	};
+}
+/**
+* Generic item schema that allows any properties.
+* Used as default when no user schema is provided.
+* Enables fast-json-stringify while still passing through all fields.
+*/
+const genericItemSchema = {
+	type: "object",
+	additionalProperties: true
+};
+/**
+* Recursively strip `example` keys from a schema object.
+* The `example` keyword is OpenAPI metadata — not standard JSON Schema —
+* and triggers Ajv strict mode errors when used on routes without the
+* `keywords: ['example']` AJV config (e.g., raw Fastify without createApp).
+*/
+function stripExamples(schema) {
+	if (schema === null || typeof schema !== "object") return schema;
+	if (Array.isArray(schema)) return schema.map(stripExamples);
+	const result = {};
+	for (const [key, value] of Object.entries(schema)) {
+		if (key === "example") continue;
+		result[key] = stripExamples(value);
+	}
+	return result;
+}
+/**
+* Get default response schemas for all CRUD operations.
+*
+* When routes have response schemas, Fastify compiles them with
+* fast-json-stringify for 2-3x faster serialization and prevents
+* accidental field disclosure.
+*
+* These defaults use `additionalProperties: true` so all fields pass through.
+* Override with specific schemas for full serialization performance + safety.
+*
+* Note: `example` properties are stripped from defaults so they work with
+* any Fastify instance (not just createApp which adds `keywords: ['example']`).
+*/
+function getDefaultCrudSchemas() {
+	return stripExamples({
+		list: {
+			querystring: getListQueryParams(),
+			response: { 200: listResponse(genericItemSchema) }
+		},
+		get: { response: { 200: itemResponse(genericItemSchema) } },
+		create: { response: { 201: mutationResponse(genericItemSchema) } },
+		update: { response: { 200: itemResponse(genericItemSchema) } },
+		delete: { response: { 200: deleteResponse() } }
+	});
+}
+//#endregion
+//#region src/core/validateResourceConfig.ts
+/**
+* Resource Configuration Validator
+*
+* Fail-fast validation at definition time.
+* Invalid configs throw immediately with clear, actionable errors.
+*
+* @example
+* const result = validateResourceConfig(config);
+* if (!result.valid) {
+*   console.error(formatValidationErrors(result.errors));
+* }
+*/
+/**
+* Validate a resource configuration
+*/
+function validateResourceConfig(config, options = {}) {
+	const errors = [];
+	const warnings = [];
+	if (!config.name) errors.push({
+		field: "name",
+		message: "Resource name is required",
+		suggestion: "Add a unique resource name (e.g., \"product\", \"user\")"
+	});
+	else if (!/^[a-z][a-z0-9-]*$/i.test(config.name)) errors.push({
+		field: "name",
+		message: `Invalid resource name "${config.name}"`,
+		suggestion: "Use alphanumeric characters and hyphens, starting with a letter"
+	});
+	const crudRoutes = CRUD_OPERATIONS;
+	const disabledRoutes = new Set(config.disabledRoutes ?? []);
+	const enabledCrudRoutes = crudRoutes.filter((route) => !disabledRoutes.has(route));
+	if (!config.disableDefaultRoutes && enabledCrudRoutes.length > 0) {
+		if (!config.adapter) errors.push({
+			field: "adapter",
+			message: "Data adapter is required when CRUD routes are enabled",
+			suggestion: "Provide an adapter: createMongooseAdapter({ model, repository })"
+		});
+		else if (!config.adapter.repository) errors.push({
+			field: "adapter.repository",
+			message: "Adapter must provide a repository",
+			suggestion: "Ensure your adapter returns a valid StandardRepo (see @classytic/repo-core)"
+		});
+	} else if (!config.adapter && !config.routes?.length) warnings.push({
+		field: "config",
+		message: "Resource has no adapter and no routes",
+		suggestion: "Provide either adapter for CRUD or routes for custom logic"
+	});
+	if (config.controller && !options.skipControllerCheck && !config.disableDefaultRoutes) {
+		const ctrl = config.controller;
+		const requiredMethods = CRUD_OPERATIONS;
+		for (const method of requiredMethods) if (typeof ctrl[method] !== "function") errors.push({
+			field: `controller.${method}`,
+			message: `Missing required CRUD method "${method}"`,
+			suggestion: "Extend BaseController which implements IController interface"
+		});
+	}
+	if (config.controller && config.routes) validateRouteHandlers(config.controller, config.routes, errors);
+	if (config.permissions) validatePermissionKeys(config, options, errors, warnings);
+	if (config.presets && !options.allowUnknownPresets) validatePresets(config.presets, errors, warnings);
+	if (config.prefix) {
+		if (!config.prefix.startsWith("/")) errors.push({
+			field: "prefix",
+			message: `Prefix must start with "/" (got "${config.prefix}")`,
+			suggestion: `Change to "/${config.prefix}"`
+		});
+		if (config.prefix.endsWith("/") && config.prefix !== "/") warnings.push({
+			field: "prefix",
+			message: `Prefix should not end with "/" (got "${config.prefix}")`,
+			suggestion: `Change to "${config.prefix.slice(0, -1)}"`
+		});
+	}
+	if (config.routes) validateRoutes(config.routes, errors);
+	return {
+		valid: errors.length === 0,
+		errors,
+		warnings
+	};
+}
+function validateRouteHandlers(controller, routes, errors) {
+	const ctrl = controller;
+	for (const route of routes) if (typeof route.handler === "string") {
+		if (typeof ctrl[route.handler] !== "function") errors.push({
+			field: `routes[${route.method} ${route.path}]`,
+			message: `Handler "${route.handler}" not found on controller`,
+			suggestion: `Add method "${route.handler}" to controller or use a function handler`
+		});
+	}
+}
+function validatePermissionKeys(config, options, _errors, warnings) {
+	const validKeys = new Set([...CRUD_OPERATIONS, ...options.additionalPermissionKeys ?? []]);
+	for (const route of config.routes ?? []) if (typeof route.handler === "string") validKeys.add(route.handler);
+	for (const preset of config.presets ?? []) {
+		const presetName = typeof preset === "string" ? preset : preset.name;
+		if (presetName === "softDelete") {
+			validKeys.add("deleted");
+			validKeys.add("restore");
+		}
+		if (presetName === "slugLookup") validKeys.add("getBySlug");
+		if (presetName === "tree") {
+			validKeys.add("tree");
+			validKeys.add("children");
+			validKeys.add("getTree");
+			validKeys.add("getChildren");
+		}
+	}
+	for (const key of Object.keys(config.permissions ?? {})) if (!validKeys.has(key)) warnings.push({
+		field: `permissions.${key}`,
+		message: `Unknown permission key "${key}"`,
+		suggestion: `Valid keys: ${Array.from(validKeys).join(", ")}`
+	});
+}
+function validatePresets(presets, errors, warnings) {
+	const availablePresets = getAvailablePresets();
+	for (const preset of presets) {
+		if (typeof preset === "object" && ("middlewares" in preset || "routes" in preset)) continue;
+		const presetName = typeof preset === "string" ? preset : preset.name;
+		if (!availablePresets.includes(presetName)) errors.push({
+			field: "presets",
+			message: `Unknown preset "${presetName}"`,
+			suggestion: `Available presets: ${availablePresets.join(", ")}`
+		});
+		if (typeof preset === "object") validatePresetOptions(preset, warnings);
+	}
+}
+function validatePresetOptions(preset, warnings) {
+	const validOptions = {
+		slugLookup: ["slugField"],
+		tree: ["parentField"],
+		softDelete: ["deletedField"],
+		ownedByUser: ["ownerField"],
+		multiTenant: ["tenantField", "allowPublic"]
+	}[preset.name] ?? [];
+	const providedOptions = Object.keys(preset).filter((k) => k !== "name");
+	for (const opt of providedOptions) if (!validOptions.includes(opt)) warnings.push({
+		field: `presets[${preset.name}].${opt}`,
+		message: `Unknown option "${opt}" for preset "${preset.name}"`,
+		suggestion: validOptions.length > 0 ? `Valid options: ${validOptions.join(", ")}` : `Preset "${preset.name}" has no configurable options`
+	});
+}
+function validateRoutes(routes, errors) {
+	const validMethods = [
+		"GET",
+		"POST",
+		"PUT",
+		"PATCH",
+		"DELETE",
+		"OPTIONS",
+		"HEAD"
+	];
+	const seenRoutes = /* @__PURE__ */ new Set();
+	for (const [i, route] of routes.entries()) {
+		if (!validMethods.includes(route.method)) errors.push({
+			field: `routes[${i}].method`,
+			message: `Invalid HTTP method "${route.method}"`,
+			suggestion: `Valid methods: ${validMethods.join(", ")}`
+		});
+		if (!route.path) errors.push({
+			field: `routes[${i}].path`,
+			message: "Route path is required"
+		});
+		else if (!route.path.startsWith("/")) errors.push({
+			field: `routes[${i}].path`,
+			message: `Route path must start with "/" (got "${route.path}")`,
+			suggestion: `Change to "/${route.path}"`
+		});
+		if (!route.handler) errors.push({
+			field: `routes[${i}].handler`,
+			message: "Route handler is required"
+		});
+		const routeKey = `${route.method} ${route.path}`;
+		if (seenRoutes.has(routeKey)) errors.push({
+			field: `routes[${i}]`,
+			message: `Duplicate route "${routeKey}"`
+		});
+		seenRoutes.add(routeKey);
+	}
+}
+/**
+* Format validation errors for display
+*/
+function formatValidationErrors(resourceName, result) {
+	const lines = [];
+	if (result.errors.length > 0) {
+		lines.push(`Resource "${resourceName}" validation failed:`);
+		lines.push("");
+		lines.push("ERRORS:");
+		for (const err of result.errors) {
+			lines.push(`  ✗ ${err.field}: ${err.message}`);
+			if (err.suggestion) lines.push(`    → ${err.suggestion}`);
+		}
+	}
+	if (result.warnings.length > 0) {
+		if (lines.length > 0) lines.push("");
+		lines.push("WARNINGS:");
+		for (const warn of result.warnings) {
+			lines.push(`  ⚠ ${warn.field}: ${warn.message}`);
+			if (warn.suggestion) lines.push(`    → ${warn.suggestion}`);
+		}
+	}
+	return lines.join("\n");
+}
+/**
+* Validate and throw if invalid
+*/
+function assertValidConfig(config, options) {
+	const result = validateResourceConfig(config, options);
+	if (!result.valid) {
+		const errorMsg = formatValidationErrors(config.name ?? "unknown", result);
+		throw new Error(errorMsg);
+	}
+}
+//#endregion
+//#region src/utils/circuitBreaker.ts
+/**
+* Circuit Breaker Pattern
+*
+* Wraps external service calls with failure protection.
+* Prevents cascading failures by "opening" the circuit when
+* a service is failing, allowing it time to recover.
+*
+* States:
+* - CLOSED: Normal operation, requests pass through
+* - OPEN: Too many failures, all requests fail fast
+* - HALF_OPEN: Testing if service recovered, limited requests
+*
+* @example
+* import { CircuitBreaker } from '@classytic/arc/utils';
+*
+* const paymentBreaker = new CircuitBreaker(async (amount) => {
+*   return await stripe.charges.create({ amount });
+* }, {
+*   failureThreshold: 5,
+*   resetTimeout: 30000,
+*   timeout: 5000,
+* });
+*
+* try {
+*   const result = await paymentBreaker.call(100);
+* } catch (error) {
+*   // Handle failure or circuit open
+* }
+*/
+const CircuitState = {
+	CLOSED: "CLOSED",
+	OPEN: "OPEN",
+	HALF_OPEN: "HALF_OPEN"
+};
+var CircuitBreakerError = class extends Error {
+	state;
+	constructor(message, state) {
+		super(message);
+		this.name = "CircuitBreakerError";
+		this.state = state;
+	}
+};
+var CircuitBreaker = class {
+	state = CircuitState.CLOSED;
+	failures = 0;
+	successes = 0;
+	totalCalls = 0;
+	nextAttempt = 0;
+	lastCallAt = null;
+	openedAt = null;
+	failureThreshold;
+	resetTimeout;
+	timeout;
+	successThreshold;
+	fallback;
+	onStateChange;
+	onError;
+	name;
+	fn;
+	constructor(fn, options = {}) {
+		this.fn = fn;
+		this.failureThreshold = options.failureThreshold ?? 5;
+		this.resetTimeout = options.resetTimeout ?? 6e4;
+		this.timeout = options.timeout ?? 1e4;
+		this.successThreshold = options.successThreshold ?? 1;
+		this.fallback = options.fallback;
+		this.onStateChange = options.onStateChange;
+		this.onError = options.onError;
+		this.name = options.name ?? "CircuitBreaker";
+	}
+	/**
+	* Call the wrapped function with circuit breaker protection
+	*/
+	async call(...args) {
+		this.totalCalls++;
+		this.lastCallAt = Date.now();
+		if (this.state === CircuitState.OPEN) {
+			if (Date.now() < this.nextAttempt) {
+				const error = new CircuitBreakerError(`Circuit breaker is OPEN for ${this.name}`, CircuitState.OPEN);
+				if (this.fallback) return this.fallback(...args);
+				throw error;
+			}
+			this.setState(CircuitState.HALF_OPEN);
+		}
+		try {
+			const result = await this.executeWithTimeout(args);
+			this.onSuccess();
+			return result;
+		} catch (err) {
+			this.onFailure(err instanceof Error ? err : new Error(String(err)));
+			throw err;
+		}
+	}
+	/**
+	* Execute function with timeout
+	*/
+	async executeWithTimeout(args) {
+		return new Promise((resolve, reject) => {
+			const timeoutId = setTimeout(() => {
+				reject(/* @__PURE__ */ new Error(`Request timeout after ${this.timeout}ms`));
+			}, this.timeout);
+			this.fn(...args).then((result) => {
+				clearTimeout(timeoutId);
+				resolve(result);
+			}).catch((error) => {
+				clearTimeout(timeoutId);
+				reject(error);
+			});
+		});
+	}
+	/**
+	* Handle successful call
+	*/
+	onSuccess() {
+		this.failures = 0;
+		this.successes++;
+		if (this.state === CircuitState.HALF_OPEN) {
+			if (this.successes >= this.successThreshold) {
+				this.setState(CircuitState.CLOSED);
+				this.successes = 0;
+			}
+		}
+	}
+	/**
+	* Handle failed call
+	*/
+	onFailure(error) {
+		this.failures++;
+		this.successes = 0;
+		if (this.onError) this.onError(error);
+		if (this.state === CircuitState.HALF_OPEN || this.failures >= this.failureThreshold) {
+			this.setState(CircuitState.OPEN);
+			this.nextAttempt = Date.now() + this.resetTimeout;
+			this.openedAt = Date.now();
+		}
+	}
+	/**
+	* Change circuit state
+	*/
+	setState(newState) {
+		const oldState = this.state;
+		if (oldState !== newState) {
+			this.state = newState;
+			if (this.onStateChange) this.onStateChange(oldState, newState);
+		}
+	}
+	/**
+	* Manually open the circuit
+	*/
+	open() {
+		this.setState(CircuitState.OPEN);
+		this.nextAttempt = Date.now() + this.resetTimeout;
+		this.openedAt = Date.now();
+	}
+	/**
+	* Manually close the circuit
+	*/
+	close() {
+		this.failures = 0;
+		this.successes = 0;
+		this.setState(CircuitState.CLOSED);
+		this.openedAt = null;
+	}
+	/**
+	* Get current statistics
+	*/
+	getStats() {
+		return {
+			name: this.name,
+			state: this.state,
+			failures: this.failures,
+			successes: this.successes,
+			totalCalls: this.totalCalls,
+			openedAt: this.openedAt,
+			lastCallAt: this.lastCallAt
+		};
+	}
+	/**
+	* Get current state
+	*/
+	getState() {
+		return this.state;
+	}
+	/**
+	* Check if circuit is open
+	*/
+	isOpen() {
+		return this.state === CircuitState.OPEN;
+	}
+	/**
+	* Check if circuit is closed
+	*/
+	isClosed() {
+		return this.state === CircuitState.CLOSED;
+	}
+	/**
+	* Reset statistics
+	*/
+	reset() {
+		this.failures = 0;
+		this.successes = 0;
+		this.totalCalls = 0;
+		this.lastCallAt = null;
+		this.openedAt = null;
+		this.setState(CircuitState.CLOSED);
+	}
+};
+/**
+* Create a circuit breaker with sensible defaults
+*
+* @example
+* const emailBreaker = createCircuitBreaker(
+*   async (to, subject, body) => sendEmail(to, subject, body),
+*   { name: 'email-service' }
+* );
+*/
+function createCircuitBreaker(fn, options) {
+	return new CircuitBreaker(fn, options);
+}
+/**
+* Circuit breaker registry for managing multiple breakers
+*/
+var CircuitBreakerRegistry = class {
+	breakers = /* @__PURE__ */ new Map();
+	/**
+	* Register a circuit breaker
+	*/
+	register(name, fn, options) {
+		const breaker = new CircuitBreaker(fn, {
+			...options,
+			name
+		});
+		this.breakers.set(name, breaker);
+		return breaker;
+	}
+	/**
+	* Get a circuit breaker by name
+	*/
+	get(name) {
+		return this.breakers.get(name);
+	}
+	/**
+	* Get all breakers
+	*/
+	getAll() {
+		return this.breakers;
+	}
+	/**
+	* Get statistics for all breakers
+	*/
+	getAllStats() {
+		const stats = {};
+		for (const [name, breaker] of this.breakers.entries()) stats[name] = breaker.getStats();
+		return stats;
+	}
+	/**
+	* Reset all breakers
+	*/
+	resetAll() {
+		for (const breaker of this.breakers.values()) breaker.reset();
+	}
+	/**
+	* Open all breakers
+	*/
+	openAll() {
+		for (const breaker of this.breakers.values()) breaker.open();
+	}
+	/**
+	* Close all breakers
+	*/
+	closeAll() {
+		for (const breaker of this.breakers.values()) breaker.close();
+	}
+};
+/**
+* Create a new CircuitBreakerRegistry instance.
+* Use this instead of a global singleton — attach to fastify.arc or pass explicitly.
+*/
+function createCircuitBreakerRegistry() {
+	return new CircuitBreakerRegistry();
+}
+//#endregion
+//#region src/utils/compensation.ts
+/**
+* Run steps in order with automatic compensation on failure.
+*
+* @typeParam TCtx - Context type shared across steps (defaults to Record<string, unknown>)
+*/
+async function withCompensation(_name, steps, initialContext, hooks) {
+	const ctx = { ...initialContext };
+	const completedSteps = [];
+	const results = {};
+	const completed = [];
+	for (const step of steps) {
+		if (step.fireAndForget) {
+			completedSteps.push(step.name);
+			step.execute(ctx).then((result) => hooks?.onStepComplete?.(step.name, result), () => {});
+			continue;
+		}
+		try {
+			const result = await step.execute(ctx);
+			completedSteps.push(step.name);
+			results[step.name] = result;
+			completed.push({
+				step,
+				result
+			});
+			hooks?.onStepComplete?.(step.name, result);
+		} catch (err) {
+			const error = err instanceof Error ? err : new Error(String(err));
+			hooks?.onStepFailed?.(step.name, error);
+			const compensationErrors = await rollback(ctx, completed, hooks);
+			return {
+				success: false,
+				completedSteps,
+				results,
+				failedStep: step.name,
+				error: error.message,
+				...compensationErrors.length > 0 ? { compensationErrors } : {}
+			};
+		}
+	}
+	return {
+		success: true,
+		completedSteps,
+		results
+	};
+}
+async function rollback(ctx, completed, hooks) {
+	const errors = [];
+	for (let i = completed.length - 1; i >= 0; i--) {
+		const entry = completed[i];
+		if (!entry?.step.compensate) continue;
+		const compensateFn = entry.step.compensate;
+		try {
+			await compensateFn(ctx, entry.result);
+			hooks?.onCompensate?.(entry.step.name);
+		} catch (err) {
+			errors.push({
+				step: entry.step.name,
+				error: err instanceof Error ? err.message : String(err)
+			});
+		}
+	}
+	return errors;
+}
+function defineCompensation(name, steps) {
+	return {
+		name,
+		execute: (initialContext, hooks) => withCompensation(name, steps, initialContext, hooks)
+	};
+}
+//#endregion
+//#region src/utils/defineErrorMapper.ts
+/**
+* Register an `ErrorMapper` with its domain-specific generic argument and
+* have it assign cleanly into `ErrorMapper[]` (no `as unknown as ErrorMapper`).
+*
+* The returned mapper is identical at runtime — `type` and `toResponse` are
+* passed through untouched. Only the declared type widens from
+* `ErrorMapper<T>` to `ErrorMapper` so the array inference works.
+*
+* Safety: the `errorHandlerPlugin` dispatches via `error instanceof mapper.type`
+* before invoking `toResponse`, so the widened callback signature is never
+* called with a non-`T` error at runtime. This helper codifies that invariant
+* in one place.
+*/
+function defineErrorMapper(mapper) {
+	return mapper;
+}
+//#endregion
+//#region src/utils/defineGuard.ts
+/** Hidden property key for guard context storage on the request object. */
+const GUARD_STORE_KEY = "__arcGuardContext";
+/**
+* Create a typed guard. See module JSDoc for usage.
+*/
+function defineGuard(config) {
+	const { name, resolve } = config;
+	const preHandler = async (req, reply) => {
+		const ctx = await resolve(req, reply);
+		if (!reply.sent) {
+			const store = req[GUARD_STORE_KEY] ?? {};
+			store[name] = ctx;
+			req[GUARD_STORE_KEY] = store;
+		}
+	};
+	return {
+		preHandler,
+		name,
+		from(req) {
+			const store = req[GUARD_STORE_KEY];
+			if (!store || !(name in store)) throw new Error(`Guard '${name}' not resolved on this request. Add it to routeGuards or the route's preHandler array.`);
+			return store[name];
+		}
+	};
+}
+//#endregion
+//#region src/utils/envelope.ts
+/**
+* Standard response envelope helper.
+*
+* Wraps a handler return value in arc's `{ success: true, data, ...meta }`
+* shape. Pure utility — no types module coupling, no runtime dependencies.
+*
+* @example
+* ```ts
+* import { envelope } from '@classytic/arc';
+*
+* handler: async (req, reply) => {
+*   const results = await search(req.query.q);
+*   return envelope(results, { took: performance.now() - t0 });
+* }
+* ```
+*/
+/**
+* Wrap data in arc's standard `{ success: true, data }` envelope, with
+* optional top-level meta keys merged in.
+*/
+function envelope(data, meta) {
+	return {
+		success: true,
+		data,
+		...meta
+	};
+}
+//#endregion
+//#region src/utils/handleRaw.ts
+/**
+* Wrap a raw Fastify handler with Arc's response envelope and error handling.
+*
+* @param handler - Async function that receives `(request, reply)` and returns data.
+*   The return value is sent as `{ success: true, data }`. If it returns
+*   `undefined` or `null`, `{ success: true }` is sent (no `data` field).
+* @param statusCode - HTTP status code for successful responses (default: 200)
+*/
+function handleRaw(handler, statusCode = 200) {
+	return async (request, reply) => {
+		try {
+			const result = await handler(request, reply);
+			if (reply.sent) return;
+			if (result === void 0 || result === null) reply.code(statusCode).send({ success: true });
+			else reply.code(statusCode).send({
+				success: true,
+				data: result
+			});
+		} catch (err) {
+			if (reply.sent) return;
+			if (err instanceof ArcError) {
+				reply.code(err.statusCode).send(err.toJSON());
+				return;
+			}
+			const error = err;
+			const code = error.statusCode ?? error.status ?? 500;
+			reply.code(code).send({
+				success: false,
+				error: error.message ?? "Internal server error",
+				...error.code && { code: error.code }
+			});
+		}
+	};
+}
+//#endregion
+//#region src/utils/stateMachine.ts
+/**
+* Create a state machine for validating transitions
+*
+* @param name - Name of the state machine (used in error messages)
+* @param transitions - Map of actions to allowed source statuses
+* @param options - Additional options (history, guards, actions)
+* @returns State machine with can() and assert() methods
+*
+* @example
+* // Basic usage
+* const transferState = createStateMachine('Transfer', {
+*   approve: ['draft'],
+*   dispatch: ['approved'],
+*   receive: ['dispatched', 'in_transit'],
+*   cancel: ['draft', 'approved'],
+* });
+*
+* @example
+* // With guards and actions
+* const orderState = createStateMachine('Order', {
+*   approve: {
+*     from: ['pending'],
+*     to: 'approved',
+*     guard: ({ data }) => data.paymentConfirmed,
+*     before: ({ from, to }) => console.log(`Approving order from ${from} to ${to}`),
+*     after: ({ data }) => sendApprovalEmail(data.customerId),
+*   },
+* }, { trackHistory: true });
+*/
+function createStateMachine(name, transitions = {}, options = {}) {
+	const normalized = /* @__PURE__ */ new Map();
+	const history = options.trackHistory ? [] : void 0;
+	Object.entries(transitions).forEach(([action, allowed]) => {
+		if (Array.isArray(allowed)) normalized.set(action, { from: new Set(allowed) });
+		else if (typeof allowed === "object" && "from" in allowed) normalized.set(action, {
+			from: new Set(Array.isArray(allowed.from) ? allowed.from : [allowed.from]),
+			to: allowed.to,
+			guard: allowed.guard,
+			before: allowed.before,
+			after: allowed.after
+		});
+	});
+	const can = (action, status) => {
+		const transition = normalized.get(action);
+		if (!transition || !status) return false;
+		return transition.from.has(status);
+	};
+	const canAsync = async (action, status, context) => {
+		const transition = normalized.get(action);
+		if (!transition || !status) return false;
+		if (!transition.from.has(status)) return false;
+		if (transition.guard) try {
+			return await transition.guard({
+				from: status,
+				to: transition.to || "",
+				action,
+				data: context
+			});
+		} catch {
+			return false;
+		}
+		return true;
+	};
+	const assert = (action, status, errorFactory, message) => {
+		if (can(action, status)) return;
+		const errorMessage = message || `${name} cannot '${action}' when status is '${status || "unknown"}'`;
+		if (typeof errorFactory === "function") throw errorFactory(errorMessage);
+		throw new Error(errorMessage);
+	};
+	const recordTransition = (from, to, action, metadata) => {
+		if (history) history.push({
+			from,
+			to,
+			action,
+			timestamp: /* @__PURE__ */ new Date(),
+			metadata
+		});
+	};
+	const getHistory = () => {
+		return history ? [...history] : [];
+	};
+	const clearHistory = () => {
+		if (history) history.length = 0;
+	};
+	const getAvailableActions = (status) => {
+		const actions = [];
+		for (const [action, transition] of normalized.entries()) if (transition.from.has(status)) actions.push(action);
+		return actions;
+	};
+	return {
+		can,
+		canAsync,
+		assert,
+		recordTransition,
+		getHistory,
+		clearHistory,
+		getAvailableActions
+	};
+}
+//#endregion
+export { createQueryParser as A, mutationResponse as C, successResponseSchema as D, responses as E, simpleEqualityMatcher as M, wrapResponse as O, listResponse as S, queryParams as T, deleteResponse as _, defineErrorMapper as a, getListQueryParams as b, CircuitBreaker as c, CircuitState as d, createCircuitBreaker as f, validateResourceConfig as g, formatValidationErrors as h, defineGuard as i, getUserId as j, ArcQueryParser as k, CircuitBreakerError as l, assertValidConfig as m, handleRaw as n, defineCompensation as o, createCircuitBreakerRegistry as p, envelope as r, withCompensation as s, createStateMachine as t, CircuitBreakerRegistry as u, errorResponseSchema as v, paginationSchema as w, itemResponse as x, getDefaultCrudSchemas as y };