@classytic/arc 2.14.2 → 2.15.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/arc",
-  "version": "2.14.2",
+  "version": "2.15.3",
   "description": "Resource-oriented backend framework for Fastify - clean, minimal, powerful, tree-shakable",
   "type": "module",
   "exports": {
@@ -246,7 +246,7 @@
   },
   "peerDependencies": {
     "@classytic/primitives": ">=0.4.0",
-    "@classytic/repo-core": ">=0.4.0",
+    "@classytic/repo-core": ">=0.4.1",
     "@classytic/streamline": ">=2.3.0",
     "@fastify/cors": ">=11.0.0",
     "@fastify/helmet": ">=13.0.0",
@@ -357,10 +357,10 @@
     "@better-auth/mongo-adapter": "^1.6.9",
     "@biomejs/biome": "^2.4.11",
     "@classytic/dev-tools": "^0.2.0",
-    "@classytic/mongokit": "^3.13.0",
+    "@classytic/mongokit": "^3.13.2",
     "@classytic/primitives": "^0.4.0",
-    "@classytic/repo-core": "^0.4.0",
-    "@classytic/sqlitekit": "^0.3.0",
+    "@classytic/repo-core": "^0.4.1",
+    "@classytic/sqlitekit": "^0.3.1",
     "@classytic/streamline": "^2.3.0",
     "@fastify/cors": "^11.2.0",
     "@fastify/helmet": "^13.0.2",

package/skills/arc/SKILL.md

@@ -639,6 +639,83 @@ defineResource({
 
 MCP auto-derives `filterableFields` from `queryParser`.
 
+## Aggregations — dashboards in declarative form
+
+Add `aggregations: { … }` to a resource and Arc registers `GET
+/{prefix}/aggregations/:name` per entry. Each runs a portable `$match
+→ $group → $project → $sort → $limit` pipeline against the kit's
+`repo.aggregate(req, options)` — same shape across mongokit /
+sqlitekit / prismakit, so dashboards work unchanged across backends.
+
+```typescript
+import { defineResource, defineAggregation } from '@classytic/arc';
+
+defineResource({
+  name: 'transaction',
+  adapter,
+  presets: [multiTenantPreset({ tenantField: 'organizationId' })],
+  permissions: { list: canViewRevenue() },
+
+  aggregations: {
+    byPaymentMethod: defineAggregation({
+      groupBy: 'method',
+      measures: { total: 'sum:amount', count: 'count' },
+      sort: { total: -1 },
+      cache: { staleTime: 60, swr: true, tags: ['revenue'] },
+      permissions: canViewRevenue(),
+    }),
+    byFlow: defineAggregation({
+      groupBy: 'flow',
+      measures: { total: 'sum:amount', count: 'count' },
+      cache: { staleTime: 60, swr: true, tags: ['revenue'] },
+      permissions: canViewRevenue(),
+    }),
+    byDay: defineAggregation({
+      dateBuckets: { day: { field: 'createdAt', interval: 'day' } },
+      groupBy: 'flow',
+      measures: { total: 'sum:amount', count: 'count' },
+      sort: { day: 1 },
+      requireDateRange: { field: 'createdAt', maxRangeDays: 365 },
+      cache: { staleTime: 60, swr: true, tags: ['revenue'] },
+      permissions: canViewRevenue(),
+    }),
+  },
+});
+```
+
+**Tenant scope flows through the second arg, NOT the filter.** Arc is
+DB-agnostic — type-coercion (string → ObjectId for mongokit
+`fieldType: 'objectId'`, UUID/text for sqlitekit, etc.) belongs to the
+kit. Arc threads `tenantOptions` to `repo.aggregate(req, options)`;
+the kit's multi-tenant plugin reads `context.organizationId`, casts
+correctly, and merges into the request. Authors never inject the
+tenant key into `aggReq.filter` themselves.
+
+**Caller filters via query string compose with `groupBy` / measures:**
+
+```
+GET /api/transactions/aggregations/byPaymentMethod?status=verified
+GET /api/transactions/aggregations/byDay?createdAt[gte]=2026-01-01&createdAt[lt]=2026-02-01
+```
+
+**Safety guards on the declaration:**
+- `requireDateRange: { field, maxRangeDays }` — bounded range mandatory; kills accidental all-time scans
+- `requireFilters: ['orgId']` — mandatory scope keys
+- `maxGroups: 1000` — post-execution row cap; 422 on overflow
+
+**Cache invalidation:** writes through resource CRUD bump the
+matching tag. Aggregations cached with the same `tags` invalidate
+together. SWR mode serves stale immediately while revalidating in
+background.
+
+**MCP auto-export:** every aggregation surfaces as an MCP tool
+named `{resource}_aggregations_{name}` with the same permission gate
+and filter validation as the HTTP route.
+
+For backends without `repo.aggregate` (custom adapters), declare a
+`materialized` hook on the aggregation — Arc routes through it
+instead of the kit and returns the same `{ rows }` envelope.
+
 ## QueryCache
 
 TanStack Query-style server cache, stale-while-revalidate, auto-invalidation on mutations.

package/skills/arc-code-review/references/anti-patterns.md

@@ -894,6 +894,49 @@ Then check whether the hook body sets headers (`reply.header(`, `reply.headers[`
 
 ---
 
+## §33. Hand-rolled aggregation routes when `aggregations: { … }` would do 🟠
+
+**Detection:**
+```
+pattern: "Model\\.aggregate\\(\\["
+output_mode: content
+```
+Also: `\\.aggregate\\(\\s*\\[`, `\\$group\\b`, `\\$match\\b` inside resource handler files. Plus inline mongoose pipeline imports inside route handlers (vs. inside the kit's repository).
+
+**Anti-pattern:**
+```typescript
+// In a custom GET /aggregate/byPaymentMethod route:
+const orgId = getOrgId(getScope(req));
+const rows = await Transaction.aggregate([
+  { $match: { organizationId: new mongoose.Types.ObjectId(orgId), status: 'verified' } },
+  { $group: { _id: '$method', total: { $sum: '$amount' }, count: { $sum: 1 } } },
+  { $sort: { total: -1 } },
+]);
+return reply.send({ rows });
+```
+
+**Why high:** loses every cross-cutting feature arc's aggregation router gives for free — per-aggregation permissions, OpenAPI schema, MCP tool export, SWR cache + tag invalidation, `requireFilters` / `requireDateRange` safety guards, `maxGroups` cap, multi-tenant scope without manual `ObjectId` casting. The hand-rolled version also drifts: every new bucket needs a new route, no central declaration, no unified shape across kits.
+
+**Fix:** declare `aggregations: { name: defineAggregation({ groupBy, measures, sort, cache, permissions }) }` on the resource. Arc registers `GET /:prefix/aggregations/:name` per entry, threads `tenantOptions` to `repo.aggregate(req, options)`, and the kit's multi-tenant plugin handles type-coercion. Type-coercion (string → ObjectId / UUID / text) is **the kit's responsibility, not the framework's** — never inject the tenant key into `aggReq.filter` from arc-host code.
+
+```typescript
+import { defineAggregation } from '@classytic/arc';
+
+aggregations: {
+  byPaymentMethod: defineAggregation({
+    groupBy: 'method',
+    measures: { total: 'sum:amount', count: 'count' },
+    sort: { total: -1 },
+    cache: { staleTime: 60, swr: true, tags: ['revenue'] },
+    permissions: canViewRevenue(),
+  }),
+}
+```
+
+For backends without `repo.aggregate`, declare a `materialized` hook on the aggregation — the router calls it instead of the kit and keeps the same `{ rows }` envelope, permission gate, and cache contract.
+
+---
+
 ## Detection checklist (run-order)
 
 Run sweeps in this order — early hits often invalidate later context:
@@ -909,3 +952,4 @@ Run sweeps in this order — early hits often invalidate later context:
 9. §14, §18, §19 — preset adoption + custom controller wiring
 10. §11, §12, §13, §29, §30, §31 — style and edges
 11. §32a–§32g — canonical-contract drift (pagination / events / tenant / errors / adapter imports), missing `requireOrgId` accessors, missing `schemaGenerator`, kit-specific adapter imports from arc (3.0 break)
+12. §33 — hand-rolled `Model.aggregate([...])` in resource routes vs declarative `aggregations: { … }`

package/skills/arc-code-review/references/arc-cheatsheet.md

@@ -246,6 +246,33 @@ Modes: `memory` (default) | `distributed` (`stores.queryCache: RedisCacheStore`)
 
 ---
 
+## Aggregations (declarative dashboards)
+
+```typescript
+import { defineAggregation } from '@classytic/arc';
+
+aggregations: {
+  byMethod: defineAggregation({
+    groupBy: 'method',
+    measures: { total: 'sum:amount', count: 'count' },
+    sort: { total: -1 },
+    cache: { staleTime: 60, swr: true, tags: ['revenue'] },
+    permissions: canViewRevenue(),
+  }),
+  byDay: defineAggregation({
+    dateBuckets: { day: { field: 'createdAt', interval: 'day' } },
+    groupBy: 'flow',
+    measures: { total: 'sum:amount' },
+    requireDateRange: { field: 'createdAt', maxRangeDays: 365 },
+    permissions: canViewRevenue(),
+  }),
+}
+```
+
+Registers `GET /:prefix/aggregations/:name` per entry. Same permissions, OpenAPI, MCP tool, cache + tag invalidation as CRUD. Tenant flows via the kit's multi-tenant plugin (string → ObjectId casting handled by the kit, **not** by hand). Caller filters via query string (`?status=verified&createdAt[gte]=...`) compose with the declaration. Safety: `requireFilters`, `requireDateRange`, `maxGroups`. **Anti-pattern:** custom routes calling `Model.aggregate([...])` directly — see anti-patterns §33.
+
+---
+
 ## CLI
 
 ```bash