v4.1.0

.changeset/lovely-socks-argue.md

@@ -0,0 +1,5 @@
+---
+'@cleverbrush/schema': minor
+---
+
+fix(schema): make ~standard.validate return Promise to support async validation per Standard Schema v1 spec

.changeset/quiet-pans-create.md

@@ -0,0 +1,29 @@
+---
+'@cleverbrush/client': minor
+'@cleverbrush/server': minor
+---
+
+feat(client): optimistic update + offline support + tag-based cache invalidation
+
+- Add `optimisticUpdate()` middleware — tags mutations with IDs and tracks network failures
+- Add `offlineQueue()` middleware — queues mutations when offline, replays on reconnect
+- Add `useOptimisticMutation()` React hook — automatic TanStack Query cache snapshot/rollback
+- Add `OfflineError` class extending `NetworkError`
+- Extend `PerCallOverrides` with `optimisticUpdate` and `offlineQueue` keys
+
+feat(server, client): tag-based cache invalidation via `.clearsCacheTag()` endpoint annotations
+
+- Add `.clearsCacheTag(name[, selector])` to `EndpointBuilder` — declare cache tags with optional property selectors
+- Add `CacheTagDefinition`, `CacheTagPropertyAccessor`, `createCacheTagTree`, `serializeTag`, `computeCacheKey` to `@cleverbrush/server`
+- Add `cacheTags()` middleware to `@cleverbrush/client/cache` — tag-keyed HTTP caching with automatic invalidation on mutations
+- Add `CacheTagMiddlewareOptions` with `ttlByTag`, `defaultTtl`, `condition`
+- Add `cacheTags` and `headers` fields to `EndpointMeta` for middleware introspection
+- Add implicit TanStack Query invalidation in `useMutation` when endpoint declares cache tags
+- Add `CacheTagSelector` type for IDE autocomplete in `.clearsCacheTag()` selector callbacks
+
+feat(server, client): request idempotency middleware
+
+- Add `idempotency()` server middleware — stores responses keyed by `X-Idempotency-Key` header, replays stored response on duplicate keys
+- Add `idempotency()` client middleware — auto-generates UUID v4 as `X-Idempotency-Key` header for mutating requests, preserves key across retries
+- Export `IdempotencyOptions` (client) and `ServerIdempotencyOptions` (server)
+- Add `cacheResponse()` server middleware — tag-based server-side response caching with handler-level invalidation

.changeset/separate-knex-schema-operations.md

@@ -0,0 +1,5 @@
+---
+"@cleverbrush/knex-schema": patch
+---
+
+Extract query operations into modular files (helpers, select, where, insert, update, delete, join, pagination, state) from monolithic SchemaQueryBuilder. No public API changes.

.changeset/tiny-dragons-shout.md

@@ -0,0 +1,11 @@
+---
+'@cleverbrush/schema': minor
+'@cleverbrush/schema-json': minor
+---
+
+Add `intersection()` schema builder for combining two schemas (both must pass)
+
+- New `IntersectionSchemaBuilder` class with `intersection(left, right)` factory
+- Validates both schemas against the input and merges outputs
+- Maps to `allOf` in JSON Schema (to/from bidirectional)
+- Supports all standard modifiers: `.optional()`, `.nullable()`, `.default()`, `.catch()`, `.brand()`, `.readonly()`, `.addValidator()`, `.addPreprocessor()`, etc.

.changeset/tiny-socks-march.md

@@ -0,0 +1,24 @@
+---
+"@cleverbrush/server": minor
+"@cleverbrush/server-openapi": minor
+---
+
+feat(server): add file upload support via `.upload()` and `FilePart` type
+
+Adds `multipart/form-data` parsing with `@fastify/busboy`, a new `.upload()`
+method on `EndpointBuilder`, and the `FilePart` type for handling uploaded
+files in endpoint handlers. The OpenAPI generator emits `multipart/form-data`
+request bodies for upload-enabled endpoints.
+
+```ts
+const ep = endpoint
+    .post("/api/avatar")
+    .upload({ maxFileSize: 2 * 1024 * 1024 })
+    .body(object({ description: string().optional() }));
+
+server.handle(ep, ({ files }) => {
+    const avatar = files["avatar"];
+    // { filename, mimeType, buffer, size }
+});
+```
+

demos/todo-backend/Dockerfile

@@ -5,7 +5,7 @@ FROM node:22-alpine AS builder
 WORKDIR /app
 
 # Copy root workspace manifest for npm workspaces resolution
-COPY package.json package-lock.json* turbo.json tsconfig.build.json ./
+COPY package.json package-lock.json* turbo.json tsconfig.json tsconfig.build.json ./
 
 # Copy all workspace package.json files for dependency resolution
 COPY libs/async/package.json ./libs/async/
@@ -26,6 +26,8 @@ COPY libs/server-openapi/package.json ./libs/server-openapi/
 COPY libs/otel/package.json ./libs/otel/
 COPY libs/client/package.json ./libs/client/
 COPY libs/benchmarks/package.json ./libs/benchmarks/
+COPY libs/orm/package.json ./libs/orm/
+COPY libs/orm-cli/package.json ./libs/orm-cli/
 COPY demos/todo-backend/package.json ./demos/todo-backend/
 
 # Install all workspace dependencies

demos/todo-backend/migrations/20260502000001_add_todo_attachment.ts

@@ -0,0 +1,17 @@
+import type { Knex } from 'knex';
+
+export async function up(knex: Knex): Promise<void> {
+    await knex.schema.table('todos', (table) => {
+        table.binary('attachment_data').nullable();
+        table.string('attachment_name', 1024).nullable();
+        table.string('attachment_mime_type', 255).nullable();
+    });
+}
+
+export async function down(knex: Knex): Promise<void> {
+    await knex.schema.table('todos', (table) => {
+        table.dropColumn('attachment_data');
+        table.dropColumn('attachment_name');
+        table.dropColumn('attachment_mime_type');
+    });
+}

demos/todo-backend/src/api/contract.ts

@@ -82,9 +82,13 @@ export const api = defineApi({
         list: todosResource
             .get()
             .query(TodoListQuerySchema)
+            .cacheTag('todo-list', p => ({
+                page: p.query.page,
+                limit: p.query.limit
+            }))
             .responses({ 200: array(TodoResponseSchema) }),
 
-        get: todosResource.get(ById).responses({
+        get: todosResource.get(ById).cacheTag('todo', p => ({ id: p.params.id })).responses({
             200: TodoResponseSchema,
             403: ErrorResponseSchema,
             404: ErrorResponseSchema
@@ -96,6 +100,7 @@ export const api = defineApi({
                     id: number().coerce()
                 })`/${t => t.id}/with-author`
             )
+            .cacheTag('todo-author', p => ({ id: p.params.id }))
             .responses({
                 200: TodoWithAuthorResponseSchema,
                 403: ErrorResponseSchema,
@@ -105,15 +110,20 @@ export const api = defineApi({
         create: todosResource
             .post()
             .body(CreateTodoBodySchema)
+            .clearsCacheTag('todo-list')
             .responses({ 201: TodoResponseSchema }),
 
-        update: todosResource.patch(ById).body(UpdateTodoBodySchema).responses({
+        update: todosResource.patch(ById).body(UpdateTodoBodySchema)
+            .clearsCacheTag('todo-list')
+            .clearsCacheTag('todo', p => ({ id: p.params.id })).responses({
             200: TodoResponseSchema,
             403: ErrorResponseSchema,
             404: ErrorResponseSchema
         }),
 
-        delete: todosResource.delete(ById).responses({
+        delete: todosResource.delete(ById)
+            .clearsCacheTag('todo-list')
+            .clearsCacheTag('todo', p => ({ id: p.params.id })).responses({
             204: null,
             403: ErrorResponseSchema,
             404: ErrorResponseSchema
@@ -153,6 +163,8 @@ export const api = defineApi({
         complete: todosResource
             .post(route({ id: number().coerce() })`/${t => t.id}/complete`)
             .headers(CompletionRequestHeadersSchema)
+            .clearsCacheTag('todo-list')
+            .clearsCacheTag('todo', p => ({ id: p.params.id }))
             .responses({
                 200: TodoResponseSchema,
                 409: ErrorResponseSchema,
@@ -164,10 +176,25 @@ export const api = defineApi({
             route({ id: number().coerce() })`/${t => t.id}/attachment`
         ),
 
+        uploadAttachment: todosResource
+            .post(
+                route({ id: number().coerce() })`/${t => t.id}/attachment`
+            )
+            .upload({
+                maxFileSize: 10 * 1024 * 1024,
+                allowedMimeTypes: [
+                    'image/*',
+                    'application/pdf',
+                    'text/plain'
+                ]
+            })
+            .body(object({ description: string().optional() })),
+
         listActivity: todosResource
             .get(
                 route({ id: number().coerce() })`/${t => t.id}/activity`
             )
+            .cacheTag('todo-activity', p => ({ id: p.params.id }))
             .responses({
                 200: array(TodoActivityResponseSchema),
                 403: ErrorResponseSchema,
@@ -179,15 +206,24 @@ export const api = defineApi({
         list: usersResource
             .get()
             .query(PaginationQuerySchema)
+            .cacheTag('user-list', p => ({
+                page: p.query.page,
+                limit: p.query.limit
+            }))
             .responses({ 200: array(UserResponseSchema) }),
 
-        delete: usersResource.delete(ById).responses({
+        delete: usersResource.delete(ById)
+            .clearsCacheTag('user-list')
+            .clearsCacheTag('user-profile')
+            .responses({
             204: null,
             400: ErrorResponseSchema,
             404: ErrorResponseSchema
         }),
 
-        me: usersResource.get(route({})`/me`).returns(UserResponseSchema)
+        me: usersResource.get(route({})`/me`)
+            .cacheTag('user-profile')
+            .returns(UserResponseSchema)
     },
 
     webhooks: {
@@ -204,9 +240,14 @@ export const api = defineApi({
         listAll: activityResource
             .get()
             .query(object({ limit: number().coerce().optional() }))
+            .cacheTag('activity-list', p => ({
+                limit: p.query.limit
+            }))
             .responses({ 200: array(TodoActivityResponseSchema) }),
 
-        delete: activityResource.delete(ById).responses({
+        delete: activityResource.delete(ById)
+            .clearsCacheTag('activity-list')
+            .responses({
             204: null,
             404: ErrorResponseSchema
         })

demos/todo-backend/src/api/endpoints.ts

@@ -1,11 +1,17 @@
-import { defineWebhook } from '@cleverbrush/server';
 // eslint-disable-next-line @typescript-eslint/no-unused-vars
 import { POLYMORPHIC_TYPE_BRAND } from '@cleverbrush/orm';
-import { DbToken, KnexToken, LoggerToken, TrackedDbToken } from '../di/tokens.js';
+import { TodoResponseSchema } from './schemas.js';
+import { defineWebhook } from '@cleverbrush/server';
+import {
+    DbToken,
+    KnexToken,
+    LoggerToken,
+    TrackedDbToken
+} from '../di/tokens.js';
 import { api } from './contract.js';
 import {
     type ImportTodosBody,
-    ImportTodosBodySchema,
+    type ImportTodosBodySchema,
     PrincipalSchema,
     TodoNotificationPayloadSchema,
     WebhookAckSchema
@@ -179,16 +185,32 @@ export const ExportTodosEndpoint = api.todos.exportCsv
 
 export const DownloadAttachmentEndpoint = api.todos.downloadAttachment
     .authorize(PrincipalSchema)
-    .inject({ db: DbToken })
-    .producesFile('text/plain', 'A plain-text summary of the todo.')
+    .inject({ knex: KnexToken })
     .summary('Download todo attachment')
     .description(
-        'Downloads a plain-text summary of the todo as a file attachment. ' +
-            'Demonstrates `.producesFile()` and `ActionResult.file()`.'
+        'Downloads the uploaded file attachment for a todo. ' +
+            'Returns the original file with its original content type.'
     )
     .tags('todos')
     .operationId('downloadTodoAttachment');
 
+// ── Upload attachment ─────────────────────────────────────────────────────────
+// Features: .upload(), multipart/form-data, FilePart, file persistence in DB
+
+export const UploadAttachmentEndpoint = api.todos.uploadAttachment
+    .authorize(PrincipalSchema)
+    .inject({ db: DbToken, knex: KnexToken })
+    .responses({ 201: TodoResponseSchema })
+    .summary('Upload todo attachment')
+    .description(
+        'Uploads a file attachment for a todo. ' +
+            'Supports images, PDFs, and plain text files up to 10 MB. ' +
+            'The file is stored in the database and can be downloaded via ' +
+            'the download attachment endpoint.'
+    )
+    .tags('todos')
+    .operationId('uploadTodoAttachment');
+
 // ── Import todos ──────────────────────────────────────────────────────────────
 // Features: .example(), .examples(), .headers(), ActionResult.json(), ActionResult.accepted()
 
@@ -391,6 +413,7 @@ export const endpoints = {
         sendEvent: SendTodoEventEndpoint,
         exportCsv: ExportTodosEndpoint,
         downloadAttachment: DownloadAttachmentEndpoint,
+        uploadAttachment: UploadAttachmentEndpoint,
         importBulk: ImportTodosEndpoint,
         legacyReplace: LegacyReplaceTodoEndpoint,
         complete: CompleteTodoEndpoint,

demos/todo-backend/src/api/handlers/index.ts

@@ -26,7 +26,8 @@ import {
     listTodoActivityHandler,
     listTodosHandler,
     sendTodoEventHandler,
-    updateTodoHandler
+    updateTodoHandler,
+    uploadAttachmentHandler
 } from './todos.js';
 import {
     deleteUserHandler,
@@ -51,6 +52,7 @@ export const handlers: HandlerMap<typeof endpoints> = {
         sendEvent: sendTodoEventHandler,
         exportCsv: exportTodosHandler,
         downloadAttachment: downloadAttachmentHandler,
+        uploadAttachment: uploadAttachmentHandler,
         importBulk: importTodosHandler,
         legacyReplace: legacyReplaceTodoHandler,
         complete: completeTodoHandler,