@classytic/arc 2.20.0 → 2.22.0

package/dist/utils/index.mjs

@@ -1,6 +1,6 @@
 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-DkO8Nk6-.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-ChjYQpjn.mjs";
-import { a as toJsonSchema, i as isZodSchema, n as convertRouteSchema, r as isJsonSchema, t as convertOpenApiSchemas } from "../schemaConverter-U0MnO9vd.mjs";
+import { A as createCircuitBreaker, C as defineErrorMapper, D as CircuitBreakerError, E as CircuitBreaker, F as simpleEqualityMatcher, M as assertValidConfig, N as formatValidationErrors, O as CircuitBreakerRegistry, P as validateResourceConfig, S as defineGuard, T as withCompensation, _ as ArcQueryParser, a as bareListResponse, b as MONGO_DIALECT, c as errorDetailSchema, d as keysetListResponse, f as listResponse, g as responses, h as queryParams, i as aggregateListResponse, j as createCircuitBreakerRegistry, k as CircuitState, 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 defineCompensation, x as NEUTRAL_DIALECT, y as handleRaw } from "../utils-FhJ88TJE.mjs";
+import { a as isZodSchema, i as isJsonSchema, n as convertRouteSchema, o as toJsonSchema, t as convertOpenApiSchemas } from "../schemaConverter-Ds5reSGs.mjs";
 import { a as promoteStreamTokenToHeader, i as pipeUIMessageStreamToReply, n as forwardedStreamHeaders, r as isReadableStream, t as UI_MESSAGE_STREAM_HEADERS } from "../streaming-BQcW6_Kq.mjs";
 import { t as hasEvents } from "../typeGuards-C9KXUly6.mjs";
-export { ArcError, ArcQueryParser, CircuitBreaker, CircuitBreakerError, CircuitBreakerRegistry, CircuitState, ConflictError, ForbiddenError, NotFoundError, OrgAccessDeniedError, OrgRequiredError, RateLimitError, ServiceUnavailableError, UI_MESSAGE_STREAM_HEADERS, UnauthorizedError, ValidationError, aggregateListResponse, assertValidConfig, bareListResponse, convertOpenApiSchemas, convertRouteSchema, createCircuitBreaker, createCircuitBreakerRegistry, createDomainError, createError, createQueryParser, createStateMachine, defineCompensation, defineErrorMapper, defineGuard, deleteResponse, errorContractSchema, errorDetailSchema, formatValidationErrors, forwardedStreamHeaders, getDefaultCrudSchemas, getListQueryParams, getUserId, handleRaw, hasEvents, isArcError, isJsonSchema, isReadableStream, isZodSchema, keysetListResponse, listResponse, offsetListResponse, paginationSchema, pipeUIMessageStreamToReply, promoteStreamTokenToHeader, queryParams, responses, scheduleBackground, simpleEqualityMatcher, toJsonSchema, validateResourceConfig, withCompensation };
+export { ArcError, ArcQueryParser, CircuitBreaker, CircuitBreakerError, CircuitBreakerRegistry, CircuitState, ConflictError, ForbiddenError, MONGO_DIALECT, NEUTRAL_DIALECT, NotFoundError, OrgAccessDeniedError, OrgRequiredError, RateLimitError, ServiceUnavailableError, UI_MESSAGE_STREAM_HEADERS, UnauthorizedError, ValidationError, aggregateListResponse, assertValidConfig, bareListResponse, convertOpenApiSchemas, convertRouteSchema, createCircuitBreaker, createCircuitBreakerRegistry, createDomainError, createError, createQueryParser, createStateMachine, defineCompensation, defineErrorMapper, defineGuard, deleteResponse, errorContractSchema, errorDetailSchema, formatValidationErrors, forwardedStreamHeaders, getDefaultCrudSchemas, getListQueryParams, getUserId, handleRaw, hasEvents, isArcError, isJsonSchema, isReadableStream, isZodSchema, keysetListResponse, listResponse, offsetListResponse, paginationSchema, pipeUIMessageStreamToReply, promoteStreamTokenToHeader, queryParams, responses, scheduleBackground, simpleEqualityMatcher, toJsonSchema, validateResourceConfig, withCompensation };

package/dist/{utils-ChjYQpjn.mjs → utils-FhJ88TJE.mjs}

@@ -1,7 +1,7 @@
 import { m as RESERVED_QUERY_PARAMS, t as CRUD_OPERATIONS } from "./constants-DNre0wRg.mjs";
 import { arcLog } from "./logger/index.mjs";
 import { t as ArcError } from "./errors-DkO8Nk6-.mjs";
-import { r as getAvailablePresets } from "./presets-DWsYQdbV.mjs";
+import { r as getAvailablePresets } from "./presets-gw0ciIUD.mjs";
 import { errorContractSchema as errorContractSchema$1, errorDetailSchema as errorDetailSchema$1 } from "@classytic/repo-core/errors";
 //#region src/utils/simpleEqualityMatcher.ts
 /**
@@ -752,6 +752,55 @@ function defineGuard(config) {
 	};
 }
 //#endregion
+//#region src/utils/filter-dialect.ts
+/**
+* Default dialect — MongoDB / MongoKit operator shape. Emits `$`-prefixed
+* tokens and the `$options: 'i'` case-insensitive sibling. This is what
+* `ArcQueryParser` uses when no dialect is supplied, so behaviour is identical
+* to every prior arc version.
+*/
+const MONGO_DIALECT = {
+	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"
+	},
+	caseInsensitiveModifier: () => ({ $options: "i" })
+};
+/**
+* Store-neutral reference dialect — emits UN-prefixed operator tokens as a
+* translation AST (`?price[gte]=40` → `{ price: { gte: 40 } }`, with
+* `{ caseInsensitive: true }` for `like`/`contains`). A non-Mongo adapter can
+* consume this directly instead of writing a full `QueryParserInterface`. Use
+* as a starting point; adjust the token names to your store's vocabulary.
+*/
+const NEUTRAL_DIALECT = {
+	operators: {
+		eq: "eq",
+		ne: "ne",
+		gt: "gt",
+		gte: "gte",
+		lt: "lt",
+		lte: "lte",
+		in: "in",
+		nin: "nin",
+		like: "like",
+		contains: "contains",
+		regex: "regex",
+		exists: "exists"
+	},
+	caseInsensitiveModifier: () => ({ caseInsensitive: true })
+};
+//#endregion
 //#region src/utils/handleRaw.ts
 /**
 * Wrap a raw Fastify handler with Arc's response shape and error handling.
@@ -868,22 +917,17 @@ var ArcQueryParser = class {
 	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"
-	};
+	/**
+	* Datastore dialect — owns the store-specific operator tokens + the
+	* case-insensitive modifier. Defaults to Mongo (backward-compatible).
+	*/
+	dialect;
+	/** Supported filter operators (neutral name → emitted token), from the dialect. */
+	get operators() {
+		return this.dialect.operators;
+	}
 	constructor(options = {}) {
+		this.dialect = options.dialect ?? MONGO_DIALECT;
 		this.maxLimit = options.maxLimit ?? 1e3;
 		this.defaultLimit = options.defaultLimit ?? 20;
 		this.maxRegexLength = options.maxRegexLength ?? 200;
@@ -1063,17 +1107,17 @@ var ArcQueryParser = class {
 			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 = {};
+				const fieldOps = {};
 				let needsCaseInsensitive = false;
 				for (const [op, opValue] of Object.entries(operatorObj)) {
-					const mongoOp = this.operators[op];
-					if (mongoOp) {
-						mongoFilters[mongoOp] = this.parseFilterValue(opValue, op);
+					const token = this.operators[op];
+					if (token) {
+						fieldOps[token] = this.parseFilterValue(opValue, op);
 						if (op === "contains" || op === "like") needsCaseInsensitive = true;
 					}
 				}
-				if (needsCaseInsensitive) mongoFilters.$options = "i";
-				filters[key] = mongoFilters;
+				if (needsCaseInsensitive) Object.assign(fieldOps, this.dialect.caseInsensitiveModifier());
+				filters[key] = fieldOps;
 				return;
 			}
 			if (allKnownOperators && this._allowedOperators) return;
@@ -1083,12 +1127,12 @@ var ArcQueryParser = class {
 		const [, fieldName, operator] = match;
 		if (!fieldName) return;
 		if (operator && this.operators[operator] && (!this._allowedOperators || this._allowedOperators.has(operator))) {
-			const mongoOp = this.operators[operator];
+			const token = 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";
+			fieldFilter[token] = parsedValue;
+			if (operator === "contains" || operator === "like") Object.assign(fieldFilter, this.dialect.caseInsensitiveModifier());
 		} else if (!operator) filters[fieldName] = this.parseFilterValue(value);
 	}
 	parseFilterValue(value, operator) {
@@ -1251,26 +1295,72 @@ const paginationSchema = {
 	]
 };
 /**
-* List response schema — full union of every wire shape `toCanonicalList`
-* can emit. Hosts who know their endpoint only ever produces one variant
-* can pin to a narrower helper:
+* List response schema — accepts every wire shape `toCanonicalList` can
+* emit. Hosts who know their endpoint only ever produces one variant can
+* pin to a narrower helper (sharper OpenAPI docs, same serializer speed):
 *   - `offsetListResponse(item)` — `{ method: 'offset', data, page, limit, total, pages, hasNext, hasPrev }`
 *   - `keysetListResponse(item)` — `{ method: 'keyset', data, limit, hasMore, next: string|null }`
 *   - `aggregateListResponse(item)` — `{ method: 'aggregate', ...offset fields }`
 *   - `bareListResponse(item)` — `{ data }`
 *
-* The default `listResponse(item)` is the union (`oneOf`) of all four so
-* Fastify validation accepts any canonical kit shape — pre-2.13 this only
-* modelled offset and rejected keyset/aggregate/bare lists at the
-* response-schema gate.
+* SHAPE: one merged permissive object, NOT a `oneOf` union (2.22). The
+* pre-2.22 union was semantically identical on the wire — every variant is
+* `additionalProperties: true` and the property definitions never conflict
+* (`next` only exists on keyset, the offset counters only on offset/
+* aggregate; fast-json-stringify skips undefined optionals) — but
+* fast-json-stringify implements top-level `oneOf` by running full AJV
+* validation PER RESPONSE to pick the branch, on the hottest route of
+* every arc app. The merge keeps the exact bytes (pinned by
+* `tests/utils/list-response-serialization.test.ts`) and drops the
+* per-response branch validation. Only `data` is required — the one field
+* all four variants share.
 */
 function listResponse(itemSchema) {
-	return { oneOf: [
-		offsetListResponse(itemSchema),
-		keysetListResponse(itemSchema),
-		aggregateListResponse(itemSchema),
-		bareListResponse(itemSchema)
-	] };
+	return {
+		type: "object",
+		properties: {
+			method: {
+				type: "string",
+				description: "Pagination method discriminant — 'offset' | 'keyset' | 'aggregate'; absent on bare lists.",
+				example: "offset"
+			},
+			data: {
+				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
+			},
+			hasMore: { type: "boolean" },
+			next: {
+				type: ["string", "null"],
+				description: "Cursor token for the next page, or null."
+			}
+		},
+		required: ["data"],
+		additionalProperties: true
+	};
 }
 /** Offset variant — `{ method: 'offset', data, page, limit, total, pages, hasNext, hasPrev }`. */
 function offsetListResponse(itemSchema) {
@@ -1688,4 +1778,4 @@ function getUserId(user) {
 	return id ? String(id) : void 0;
 }
 //#endregion
-export { assertValidConfig as A, withCompensation as C, CircuitState as D, CircuitBreakerRegistry as E, validateResourceConfig as M, simpleEqualityMatcher as N, createCircuitBreaker as O, defineCompensation as S, CircuitBreakerError as T, ArcQueryParser as _, bareListResponse as a, defineGuard as b, errorDetailSchema$1 as c, keysetListResponse as d, listResponse as f, responses as g, queryParams as h, aggregateListResponse as i, formatValidationErrors as j, createCircuitBreakerRegistry as k, getDefaultCrudSchemas as l, paginationSchema as m, createStateMachine as n, deleteResponse as o, offsetListResponse as p, scheduleBackground as r, errorContractSchema$1 as s, getUserId as t, getListQueryParams as u, createQueryParser as v, CircuitBreaker as w, defineErrorMapper as x, handleRaw as y };
+export { createCircuitBreaker as A, defineErrorMapper as C, CircuitBreakerError as D, CircuitBreaker as E, simpleEqualityMatcher as F, assertValidConfig as M, formatValidationErrors as N, CircuitBreakerRegistry as O, validateResourceConfig as P, defineGuard as S, withCompensation as T, ArcQueryParser as _, bareListResponse as a, MONGO_DIALECT as b, errorDetailSchema$1 as c, keysetListResponse as d, listResponse as f, responses as g, queryParams as h, aggregateListResponse as i, createCircuitBreakerRegistry as j, CircuitState as k, getDefaultCrudSchemas as l, paginationSchema as m, createStateMachine as n, deleteResponse as o, offsetListResponse as p, scheduleBackground as r, errorContractSchema$1 as s, getUserId as t, getListQueryParams as u, createQueryParser as v, defineCompensation as w, NEUTRAL_DIALECT as x, handleRaw as y };

package/dist/{versioning-D_eBCfNr.d.mts → versioning-DLwklPlG.d.mts}

@@ -1,12 +1,6 @@
-import { n as DomainEvent } from "./EventTransport-IEn7Tn-Q.mjs";
+import { n as DomainEvent } from "./EventTransport-QmY7A258.mjs";
 import { FastifyPluginAsync, FastifyRequest } from "fastify";
-
 //#region src/plugins/health.d.ts
-declare module "fastify" {
-  interface FastifyRequest {
-    _startTime?: number;
-  }
-}
 interface HealthCheck {
   /** Name of the dependency */
   name: string;

package/dist/{websocket-MlYlrYq0.d.mts → websocket-uuWqM6UY.d.mts}

@@ -1,6 +1,5 @@
-import { a as PushRefRegistry, l as EnvelopeWriter, s as PushRefStore } from "./pushref-registry-DnCqL3aa.mjs";
+import { a as PushRefRegistry, l as EnvelopeWriter, s as PushRefStore } from "./pushref-registry-BbcnpNTm.mjs";
 import { FastifyBaseLogger, FastifyPluginAsync } from "fastify";
-
 //#region src/integrations/websocket/adapter.d.ts
 /**
  * WebSocket cross-instance adapter contract.
@@ -135,8 +134,10 @@ interface WebSocketClient {
     send(data: string): void;
     close(code?: number, reason?: string): void;
     readyState: number;
-    bufferedAmount?: number; /** RFC 6455 §5.5.2 ping control frame. Browsers auto-respond at the protocol layer. */
-    ping?(data?: unknown): void; /** Immediate socket destroy — no Close frame, no flush. Use for zombies. */
+    bufferedAmount?: number;
+    /** RFC 6455 §5.5.2 ping control frame. Browsers auto-respond at the protocol layer. */
+    ping?(data?: unknown): void;
+    /** Immediate socket destroy — no Close frame, no flush. Use for zombies. */
     terminate?(): void;
   };
   subscriptions: Set<string>;

package/llms.txt

@@ -0,0 +1,39 @@
+# @classytic/arc
+
+> Resource-oriented backend framework for Fastify. One `defineResource()` call =
+> REST + validation + auth + permissions + events + caching + OpenAPI + MCP tools.
+> DB-agnostic via @classytic/repo-core adapter kits (mongokit, sqlitekit, prismakit).
+
+IMPORTANT for coding agents: hand-rolling is a bug in arc apps. Before writing any
+route, validation, pagination, auth check, cron, queue worker, counter, or audit
+code, check whether arc provides it — it almost certainly does:
+
+- CRUD routes            → defineResource({ name, adapter, permissions })
+- Role/ownership checks  → @classytic/arc/permissions (requireRoles, requireOwnership, permissionMatrix, requireQuota)
+- Identity/tenant access → @classytic/arc/scope (getUserId, requireOrgId — never read scope fields directly)
+- Body/response schemas  → schemaOptions.fieldRules (customSchemas when wire ≠ model)
+- Query filter/sort/page → the resource queryParser (allow-listed) + keyset cursors
+- Soft delete/slug/tree/bulk/files/search → presets: [...]
+- Recurring jobs         → schedulesPlugin (@classytic/arc/plugins; LockAdapter leader safety)
+- Durable queues         → @classytic/arc/integrations/jobs (BullMQ/Redis) or @classytic/streamline (Mongo)
+- Headless worker process→ createWorker(sameOptions) (@classytic/arc/factory)
+- Usage counters/quotas  → @classytic/arc/usage (usagePlugin, requireQuota) + rateLimit.plan
+- Audit + record history → audit: true, history: true on the resource
+- Idempotency            → @classytic/arc/idempotency
+- Events/outbox/webhooks → @classytic/arc/events, integrations/webhooks
+- AI/MCP tools           → generated from every resource (incl. _count/_exists/_distinct list verbs)
+- App boot               → createApp({ beforeBoot: connectDatabase, ... }) — DB connect goes IN beforeBoot
+
+## Docs (inside this package)
+
+- skills/arc/SKILL.md — full framework guide (boot, defineResource, presets, auth, testing)
+- skills/arc/references/api-reference.md — every subpath import
+- skills/arc-code-review/references/arc-cheatsheet.md — hand-rolled-code → arc-feature map
+- skills/arc-code-review/SKILL.md — audit workflow for existing codebases
+
+## Conventions that bite
+
+- request.user is undefined on public routes — guard it.
+- Custom endpoints go in the resource's routes:/actions: (inherit auth/OpenAPI/MCP);
+  bare fastify.get() bypasses everything.
+- mongokit >=3.21 defaults schemaGenerator; schemaGenerator: false kills OpenAPI+MCP bodies.