@classytic/arc 2.8.0 → 2.8.3

package/dist/{utils-B-l6410F.mjs → utils-yYT3HDXt.mjs}

@@ -1,3 +1,4 @@
+import { t as ArcError } from "./errors-BF2bIOIS.mjs";
 //#region src/utils/compensation.ts
 /**
 * Run steps in order with automatic compensation on failure.
@@ -69,6 +70,69 @@ function defineCompensation(name, steps) {
 	};
 }
 //#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/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/responseSchemas.ts
 /**
 * Base success response schema
@@ -216,10 +280,6 @@ function listResponse(itemSchema) {
 	};
 }
 /**
-* Alias for listResponse - matches local responseSchemas.js naming
-*/
-const paginateWrapper = listResponse;
-/**
 * Create a single item response schema
 *
 * Runtime format: { success, data: {...} }
@@ -228,10 +288,6 @@ function itemResponse(itemSchema) {
 	return wrapResponse(itemSchema);
 }
 /**
-* Alias for itemResponse - matches local responseSchemas.js naming
-*/
-const itemWrapper = itemResponse;
-/**
 * Create a create/update response schema
 */
 function mutationResponse(itemSchema) {
@@ -288,10 +344,6 @@ function deleteResponse() {
 		additionalProperties: true
 	};
 }
-/**
-* Alias for deleteResponse - matches local responseSchemas.js naming
-*/
-const messageWrapper = deleteResponse;
 const responses = {
 	200: (schema) => ({
 		description: "Successful response",
@@ -591,4 +643,4 @@ function createStateMachine(name, transitions = {}, options = {}) {
 	};
 }
 //#endregion
-export { defineCompensation as _, getListQueryParams as a, listResponse as c, paginateWrapper as d, paginationSchema as f, wrapResponse as g, successResponseSchema as h, getDefaultCrudSchemas as i, messageWrapper as l, responses as m, deleteResponse as n, itemResponse as o, queryParams as p, errorResponseSchema as r, itemWrapper as s, createStateMachine as t, mutationResponse as u, withCompensation as v };
+export { withCompensation as _, getListQueryParams as a, mutationResponse as c, responses as d, successResponseSchema as f, defineCompensation as g, defineGuard as h, getDefaultCrudSchemas as i, paginationSchema as l, handleRaw as m, deleteResponse as n, itemResponse as o, wrapResponse as p, errorResponseSchema as r, listResponse as s, createStateMachine as t, queryParams as u };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/arc",
-  "version": "2.8.0",
+  "version": "2.8.3",
   "description": "Resource-oriented backend framework for Fastify — clean, minimal, powerful, tree-shakable",
   "type": "module",
   "exports": {
@@ -227,7 +227,7 @@
     "node": ">=22"
   },
   "peerDependencies": {
-    "@classytic/mongokit": ">=3.5.6",
+    "@classytic/mongokit": ">=3.6.0",
     "@classytic/streamline": ">=2.1.0",
     "@fastify/cors": ">=11.0.0",
     "@fastify/helmet": ">=13.0.0",
@@ -340,18 +340,18 @@
   },
   "dependencies": {
     "fastify-plugin": "^5.0.1",
-    "qs": "^6.14.1",
+    "qs": "^6.15.1",
     "secure-json-parse": "^4.1.0"
   },
   "devDependencies": {
-    "@better-auth/mongo-adapter": "^1.6.0",
-    "@biomejs/biome": "^2.4.10",
-    "@classytic/mongokit": "3.5.6",
+    "@better-auth/mongo-adapter": "^1.6.2",
+    "@biomejs/biome": "^2.4.11",
+    "@classytic/mongokit": "file:../../packages/mongokit/classytic-mongokit-3.6.0.tgz",
     "@classytic/streamline": "^2.1.0",
     "@fastify/cors": "^11.2.0",
     "@fastify/helmet": "^13.0.2",
     "@fastify/jwt": "^10.0.0",
-    "@fastify/multipart": "^9.0.0",
+    "@fastify/multipart": "^10.0.0",
     "@fastify/rate-limit": "^10.3.0",
     "@fastify/sensible": "^6.0.4",
     "@fastify/type-provider-typebox": "^6.0.0",
@@ -362,10 +362,11 @@
     "@types/node": "^22.10.0",
     "@types/qs": "^6.14.0",
     "@vitest/coverage-v8": "^3.2.4",
-    "better-auth": "^1.6.0",
+    "ajv": "^8.18.0",
+    "better-auth": "^1.6.2",
     "fastify-raw-body": "^5.0.0",
     "jsonwebtoken": "^9.0.0",
-    "knip": "^6.3.0",
+    "knip": "^6.4.1",
     "mongodb": "^7.1.0",
     "mongodb-memory-server": "^11.0.1",
     "mongoose": "^9.4.1",

package/skills/arc/SKILL.md

@@ -8,7 +8,7 @@ description: |
   Triggers: arc, fastify resource, defineResource, createApp, BaseController, arc preset,
   arc auth, arc events, arc jobs, arc websocket, arc mcp, arc plugin, arc testing, arc cli,
   arc permissions, arc hooks, arc pipeline, arc factory, arc cache, arc QueryCache.
-version: 2.8.0
+version: 2.8.1
 license: MIT
 metadata:
   author: Classytic
@@ -88,17 +88,28 @@ const productResource = defineResource({
     delete: requireRoles(['admin']),
   },
   cache: { staleTime: 30, gcTime: 300, tags: ['catalog'] },
-  additionalRoutes: [
-    { method: 'GET', path: '/featured', handler: 'getFeatured', permissions: allowPublic(), wrapHandler: true },
-  ],
 
-  // v2.8: routes (replaces additionalRoutes — additionalRoutes still works but is deprecated)
+  // v2.8.1: routeGuards — auto-apply to ALL routes (CRUD + custom + preset)
+  routeGuards: [modeGuard, orgGuard.preHandler],
+
+  // v2.8.1: fieldRules constraints → auto-map to OpenAPI + AJV validation
+  schemaOptions: {
+    fieldRules: {
+      name: { minLength: 2, maxLength: 200, description: 'Product name' },
+      price: { min: 0, max: 100000 },
+      sku: { pattern: '^[A-Z]{3}-\\d{3}$' },
+      status: { enum: ['draft', 'active', 'archived'] },
+      deletedAt: { systemManaged: true },
+    },
+  },
+
+  // Custom routes (compose with presets — softDelete adds /deleted, /:id/restore)
   routes: [
     { method: 'GET', path: '/stats', handler: 'getStats', permissions: auth() },
     { method: 'POST', path: '/webhook', handler: webhookFn, raw: true, permissions: auth() },
   ],
 
-  // v2.8: actions (replaces onRegister + createActionRouter)
+  // Actions (replaces onRegister + createActionRouter)
   actions: {
     approve: async (id, data, req) => service.approve(id, req.user._id),
     cancel: {
@@ -112,8 +123,70 @@ const productResource = defineResource({
 
 await fastify.register(productResource.toPlugin());
 // Auto-generates: GET /, GET /:id, POST /, PATCH /:id, DELETE /:id
+// + softDelete preset adds: GET /deleted, POST /:id/restore
+```
+
+## routeGuards + defineGuard (v2.8.1)
+
+Resource-level guards that apply to **every** route (CRUD + custom + preset):
+
+```typescript
+import { defineGuard } from '@classytic/arc/utils';
+import type { RouteHandlerMethod } from '@classytic/arc';
+
+// Simple guard — reject if condition fails
+const modeGuard: RouteHandlerMethod = async (req, reply) => {
+  if (!req.headers['x-mode']) {
+    reply.code(403).send({ error: 'Mode header required' });
+  }
+};
+
+// Typed guard — resolve context once, extract anywhere
+const orgGuard = defineGuard({
+  name: 'org',
+  resolve: (req) => {
+    const orgId = req.headers['x-org-id'] as string;
+    if (!orgId) throw new Error('Missing x-org-id');
+    return { orgId, actorId: req.user?.id ?? 'system' };
+  },
+});
+
+defineResource({
+  name: 'procurement',
+  routeGuards: [modeGuard, orgGuard.preHandler],  // all routes protected
+  routes: [{
+    method: 'GET', path: '/summary', raw: true, permissions: auth(),
+    handler: async (req, reply) => {
+      const { orgId } = orgGuard.from(req);  // typed, no re-computation
+      reply.send({ orgId, count: await Model.countDocuments() });
+    },
+  }],
+  // ...
+});
 ```
 
+**Execution order:** auth → permissions → cache/idempotency → `routeGuards` → per-route `preHandler`
+
+## fieldRules → OpenAPI + AJV (v2.8.1)
+
+One definition, two outputs — constraints auto-map to OpenAPI schema + Fastify AJV validation:
+
+```typescript
+schemaOptions: {
+  fieldRules: {
+    name: { minLength: 2, maxLength: 200, description: 'Product name' },
+    price: { min: 0, max: 100000 },
+    sku: { pattern: '^[A-Z]{3}-\\d{3}$' },
+    status: { enum: ['draft', 'active', 'archived'] },
+    password: { hidden: true },           // blocked from select + OpenAPI
+    deletedAt: { systemManaged: true },   // blocked from input schemas
+    slug: { immutable: true },            // excluded from update body
+  },
+},
+```
+
+Mongoose model-level constraints (`minlength`, `maxlength`, `min`, `max`, `enum`) take precedence. `fieldRules` supplements what the model doesn't declare.
+
 ## Authentication
 
 Auth uses a **discriminated union** with `type` field: