@classytic/arc 2.15.4 → 2.16.1

package/dist/utils/index.mjs

@@ -1,5 +1,5 @@
 import { a as OrgAccessDeniedError, c as ServiceUnavailableError, d as createDomainError, f as createError, i as NotFoundError, l as UnauthorizedError, n as ConflictError, o as OrgRequiredError, p as isArcError, r as ForbiddenError, s as RateLimitError, t as ArcError, u as ValidationError } from "../errors-j4aJm1Wg.mjs";
-import { A as assertValidConfig, C as withCompensation, D as CircuitState, E as CircuitBreakerRegistry, M as validateResourceConfig, N as simpleEqualityMatcher, O as createCircuitBreaker, S as defineCompensation, T as CircuitBreakerError, _ as ArcQueryParser, a as bareListResponse, b as defineGuard, c as errorDetailSchema, d as keysetListResponse, f as listResponse, g as responses, h as queryParams, i as aggregateListResponse, j as formatValidationErrors, k as createCircuitBreakerRegistry, l as getDefaultCrudSchemas, m as paginationSchema, n as createStateMachine, o as deleteResponse, p as offsetListResponse, r as scheduleBackground, s as errorContractSchema, t as getUserId, u as getListQueryParams, v as createQueryParser, w as CircuitBreaker, x as defineErrorMapper, y as handleRaw } from "../utils-_h9B3c57.mjs";
+import { A as assertValidConfig, C as withCompensation, D as CircuitState, E as CircuitBreakerRegistry, M as validateResourceConfig, N as simpleEqualityMatcher, O as createCircuitBreaker, S as defineCompensation, T as CircuitBreakerError, _ as ArcQueryParser, a as bareListResponse, b as defineGuard, c as errorDetailSchema, d as keysetListResponse, f as listResponse, g as responses, h as queryParams, i as aggregateListResponse, j as formatValidationErrors, k as createCircuitBreakerRegistry, l as getDefaultCrudSchemas, m as paginationSchema, n as createStateMachine, o as deleteResponse, p as offsetListResponse, r as scheduleBackground, s as errorContractSchema, t as getUserId, u as getListQueryParams, v as createQueryParser, w as CircuitBreaker, x as defineErrorMapper, y as handleRaw } from "../utils-DPXZnZUx.mjs";
 import { a as toJsonSchema, i as isZodSchema, n as convertRouteSchema, r as isJsonSchema, t as convertOpenApiSchemas } from "../schemaConverter-De34B1ZG.mjs";
 import { t as hasEvents } from "../typeGuards-BzkXkvVv.mjs";
 export { ArcError, ArcQueryParser, CircuitBreaker, CircuitBreakerError, CircuitBreakerRegistry, CircuitState, ConflictError, ForbiddenError, NotFoundError, OrgAccessDeniedError, OrgRequiredError, RateLimitError, ServiceUnavailableError, UnauthorizedError, ValidationError, aggregateListResponse, assertValidConfig, bareListResponse, convertOpenApiSchemas, convertRouteSchema, createCircuitBreaker, createCircuitBreakerRegistry, createDomainError, createError, createQueryParser, createStateMachine, defineCompensation, defineErrorMapper, defineGuard, deleteResponse, errorContractSchema, errorDetailSchema, formatValidationErrors, getDefaultCrudSchemas, getListQueryParams, getUserId, handleRaw, hasEvents, isArcError, isJsonSchema, isZodSchema, keysetListResponse, listResponse, offsetListResponse, paginationSchema, queryParams, responses, scheduleBackground, simpleEqualityMatcher, toJsonSchema, validateResourceConfig, withCompensation };

package/dist/{utils-_h9B3c57.mjs → utils-DPXZnZUx.mjs}

@@ -1,7 +1,7 @@
-import { m as RESERVED_QUERY_PARAMS, t as CRUD_OPERATIONS } from "./constants-Cxde4rpC.mjs";
+import { m as RESERVED_QUERY_PARAMS, t as CRUD_OPERATIONS } from "./constants-TrJVIJl0.mjs";
 import { arcLog } from "./logger/index.mjs";
 import { t as ArcError } from "./errors-j4aJm1Wg.mjs";
-import { r as getAvailablePresets } from "./presets-BbkjdPeH.mjs";
+import { r as getAvailablePresets } from "./presets-C9BE6WaZ.mjs";
 import { errorContractSchema as errorContractSchema$1, errorDetailSchema as errorDetailSchema$1 } from "@classytic/repo-core/errors";
 //#region src/utils/simpleEqualityMatcher.ts
 /**
@@ -142,7 +142,10 @@ function validateResourceConfig(config, options = {}) {
 			suggestion: `Change to "${config.prefix.slice(0, -1)}"`
 		});
 	}
-	if (config.routes) validateRoutes(config.routes, errors);
+	if (config.routes) {
+		validateRoutes(config.routes, errors);
+		validateRouteCrudCollisions(config, errors);
+	}
 	return {
 		valid: errors.length === 0,
 		errors,
@@ -210,6 +213,71 @@ function validatePresetOptions(preset, warnings) {
 		suggestion: validOptions.length > 0 ? `Valid options: ${validOptions.join(", ")}` : `Preset "${preset.name}" has no configurable options`
 	});
 }
+/**
+* Detect collisions between user-declared `routes:` entries and the
+* auto-CRUD route table that `createCrudRouter` will register.
+*
+* Without this check, a custom `POST /` on the same prefix as auto-CRUD's
+* `create` boots fine through `defineResource()` and only blows up at
+* `app.register()` time with Fastify's opaque `FST_ERR_DUPLICATED_ROUTE`.
+* That error doesn't mention `disabledRoutes` and doesn't distinguish
+* "you collided with auto-CRUD" from "you collided with yourself" — so
+* the consumer has to grep arc's source to discover the fix.
+*
+* We surface the fix in the error message, naming the conflicting op
+* and the literal line to add.
+*
+* Honored config:
+*   - `disableDefaultRoutes: true` → no auto-CRUD, no collisions possible
+*   - `disabledRoutes: ['create']` → that op's path is free for custom use
+*   - `updateMethod: 'PUT' | 'both'` → update slot covers PUT/PATCH accordingly
+*/
+function validateRouteCrudCollisions(config, errors) {
+	if (config.disableDefaultRoutes) return;
+	if (!config.routes || config.routes.length === 0) return;
+	const updateMethod = config.updateMethod ?? "PATCH";
+	const updateMethods = updateMethod === "both" ? ["PUT", "PATCH"] : [updateMethod];
+	const disabled = new Set(config.disabledRoutes ?? []);
+	const crudTable = [
+		{
+			op: "list",
+			method: "GET",
+			path: "/"
+		},
+		{
+			op: "get",
+			method: "GET",
+			path: "/:id"
+		},
+		{
+			op: "create",
+			method: "POST",
+			path: "/"
+		},
+		...updateMethods.map((m) => ({
+			op: "update",
+			method: m,
+			path: "/:id"
+		})),
+		{
+			op: "delete",
+			method: "DELETE",
+			path: "/:id"
+		}
+	];
+	for (const [i, route] of config.routes.entries()) {
+		if (!route.method || !route.path) continue;
+		for (const crud of crudTable) {
+			if (disabled.has(crud.op)) continue;
+			if (route.method !== crud.method || route.path !== crud.path) continue;
+			errors.push({
+				field: `routes[${i}]`,
+				message: `Route ${route.method} ${route.path} collides with auto-CRUD "${crud.op}"`,
+				suggestion: `Add \`disabledRoutes: ['${crud.op}']\` to suppress the auto-CRUD route, or move your custom handler to a different path. Set \`disableDefaultRoutes: true\` to disable all auto-CRUD on this resource.`
+			});
+		}
+	}
+}
 function validateRoutes(routes, errors) {
 	const validMethods = [
 		"GET",
@@ -236,9 +304,11 @@ function validateRoutes(routes, errors) {
 			message: `Route path must start with "/" (got "${route.path}")`,
 			suggestion: `Change to "/${route.path}"`
 		});
-		if (!route.handler) errors.push({
+		const routeWithRefs = route;
+		if (!route.handler && typeof routeWithRefs.controllerMethod !== "function") errors.push({
 			field: `routes[${i}].handler`,
-			message: "Route handler is required"
+			message: "Route must declare either `handler` (string / function) or `controllerMethod`",
+			suggestion: "Prefer `controllerMethod: (c: MyController) => c.method` for typed handler refs."
 		});
 		const routeKey = `${route.method} ${route.path}`;
 		if (seenRoutes.has(routeKey)) errors.push({
@@ -761,12 +831,26 @@ const DANGEROUS_REGEX_PATTERNS = /(\{[0-9,]+\}|\*\+|\+\+|\?\+|(\(.+\))\+|\(\?:|\
 * 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
+* - Filtering — TWO supported forms (both produce identical output):
+*     - Bare (default, terse):     `?status=active&price[gte]=100&price[lte]=500`
+*     - Bracket envelope:          `?filter[status]=active&filter[price][gte]=100`
+*   The envelope form matches the convention used by JSON:API / Stripe /
+*   most modern REST style guides, and is the safe choice on busy URLs
+*   that might otherwise collide with reserved meta keys (`page`, `sort`,
+*   `select`, `populate`, etc.). Operator notation (`[gte]`, `[lte]`,
+*   `[ne]`, `[in]`, ...) works inside either form.
 * - Search: ?search=keyword
 * - Populate: ?populate=author,category
 * - Field selection: ?select=name,price,status
 * - Keyset pagination: ?after=cursor_value
 *
+* **NOTE on parser portability.** `ArcQueryParser` accepts both filter
+* forms. Other parser implementations (`@classytic/mongokit`'s
+* `QueryParser`, custom hosts-side parsers) may accept only one form —
+* MongoKit historically only accepts the bare form. If your host swaps
+* `queryParser` to a different implementation, double-check which forms
+* it understands before publishing URLs that mix the two.
+*
 * For advanced MongoDB features ($lookup, aggregations), use MongoKit's QueryParser.
 */
 var ArcQueryParser = class {
@@ -930,49 +1014,82 @@ var ArcQueryParser = class {
 		if (typeof obj !== "object") return false;
 		return Object.values(obj).some((v) => this.exceedsDepth(v, currentDepth + 1));
 	}
+	/**
+	* Parse all filter entries from the query, supporting BOTH the bare
+	* top-level form and the bracket-wrapped `filter[...]` envelope.
+	*
+	* Two equivalent ways to express the same query:
+	*   - Bare (legacy, arc default): `?status=active&price[gte]=40`
+	*   - Bracket envelope (REST convention): `?filter[status]=active&filter[price][gte]=40`
+	*
+	* Both forms parse to the same `filters: { status: 'active', price: { $gte: 40 } }`.
+	* The envelope form mirrors the convention used by most REST API style
+	* guides (JSON:API, Stripe API, etc.) and disambiguates filter fields
+	* from reserved meta params on busy URLs — a query string with a field
+	* literally named `page` or `sort` can't collide with the framework's
+	* meta keys when wrapped under `filter[...]`. The bare form stays as
+	* the default since it's the shortest path for simple queries; expect
+	* it to remain supported indefinitely.
+	*
+	* Precedence when the same key appears in both forms:
+	*   `?status=closed&filter[status]=active` → bare wins (`status: closed`).
+	* Mixing should be rare; the deterministic rule avoids silent surprises.
+	*/
 	parseFilters(query) {
 		const filters = {};
+		const envelope = query.filter;
+		if (typeof envelope === "object" && envelope !== null && !Array.isArray(envelope)) for (const [key, value] of Object.entries(envelope)) this.applyFilterEntry(filters, key, value);
 		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;
-						}
+			this.applyFilterEntry(filters, key, value);
+		}
+		return filters;
+	}
+	/**
+	* Apply one filter entry — used by both the bracket-envelope branch and
+	* the bare top-level branch of `parseFilters`. Centralising the field-
+	* validation + operator-conversion logic keeps the two forms in
+	* lockstep; a future regex/security tweak only changes one place.
+	*/
+	applyFilterEntry(filters, key, value) {
+		if (value === void 0 || value === null) return;
+		if (!/^[a-zA-Z_][a-zA-Z0-9_.]*(?:\[[a-z]+\])?$/.test(key)) return;
+		const bareKey = key.replace(/\[[a-z]+\]$/, "");
+		if (this._allowedFilterFields && !this._allowedFilterFields.has(bareKey)) return;
+		if (this.exceedsDepth(value)) return;
+		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;
+				if (needsCaseInsensitive) mongoFilters.$options = "i";
+				filters[key] = mongoFilters;
+				return;
 			}
-			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);
+			if (allKnownOperators && this._allowedOperators) return;
 		}
-		return filters;
+		const match = key.match(/^([a-zA-Z_][a-zA-Z0-9_.]*)(?:\[([a-z]+)\])?$/);
+		if (!match) return;
+		const [, fieldName, operator] = match;
+		if (!fieldName) return;
+		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);
 	}
 	parseFilterValue(value, operator) {
 		if (operator === "in" || operator === "nin") {