hono-crud 0.13.3 → 0.13.4

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.13.4
+
+### Patch Changes
+
+- 6c22eaa: Restructure the project into a pnpm-workspaces monorepo. `hono-crud` is now the thin core; the database adapters, documentation UIs, and optional middleware ship as separate installable packages under the `@hono-crud/*` scope:
+
+  - `@hono-crud/memory`, `@hono-crud/drizzle`, `@hono-crud/prisma` — CRUD adapters (was `hono-crud/adapters/*`)
+  - `@hono-crud/swagger`, `@hono-crud/scalar` — documentation UIs (was exported from the `hono-crud` barrel / `hono-crud/ui`)
+  - `@hono-crud/cache`, `@hono-crud/rate-limit`, `@hono-crud/idempotency`, `@hono-crud/health` — optional middleware (was `hono-crud/{cache,rate-limit,idempotency,health}`)
+
+  Breaking: these symbols are no longer re-exported from `hono-crud`; install the corresponding `@hono-crud/*` package and import from it. The unified `createCrudMiddleware`, `HonoCrudEnv`, and `StorageEnv` no longer cover cache/rate-limit/idempotency — compose those packages' own middleware instead. A `hono-crud/internal` entrypoint is available for authoring adapters.
+
 All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
@@ -18,15 +30,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 %b
 %b
 %b
+
 ## [0.8.0] — 2026-05-03
 
 ### Added
+
 - `middlewares?: MiddlewareHandler[]` slot on every per-endpoint config in `EndpointsConfig<M>` (`create`, `list`, `read`, `update`, `delete`, `search`, `aggregate`, `restore`, `batchCreate`, `batchUpdate`, `batchDelete`, `batchRestore`, `batchUpsert`, `export`, `import`, `upsert`, `clone`). Middleware listed here runs before the endpoint handler. The existing `RegisterCrudOptions.endpointMiddlewares` continues to work and overrides config-API middlewares for the same verb. Coverage: `tests/per-endpoint-middlewares.test.ts`.
 
 ### Fixed
+
 - `HonoOpenAPIHandler.registerRoute` was passing the OpenAPI-style path (`/widgets/{id}`) to `app.use(...)` for per-route middleware. Hono's `use` expects the route-syntax form (`/widgets/:id`), so middleware on dynamic-segment routes (e.g., `delete`, `read`, `update`, `restore`, `clone`) silently never fired. The fix passes the raw path to `app.use(...)` and keeps the OpenAPI conversion only for `createRoute({ path })`. This unblocks both the new config-API `middlewares` slot and the existing `RegisterCrudOptions.endpointMiddlewares` option on `:id` routes.
 
 ### Compatibility
+
 - Additive. Existing consumers see no behaviour change other than the bugfix above (middleware that previously was silently dropped on `:id` routes will now run as documented).
 
 %b
@@ -47,6 +63,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 %b
 %b
 %b
+
 ## [0.1.0] - 2025-01-29
 
 ### Added
@@ -67,7 +84,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Edge runtime support (Cloudflare Workers, Deno, Bun, Node.js)
 
 [0.1.0]: https://github.com/ksh-us/hono-crud/releases/tag/v0.1.0
-
 [0.1.1]: https://github.com/ksh-us/hono-crud/compare/v0.0.0...v0.1.1
 [0.1.2]: https://github.com/ksh-us/hono-crud/compare/v0.1.1...v0.1.2
 [0.1.3]: https://github.com/ksh-us/hono-crud/compare/v0.1.2...v0.1.3

package/README.md

@@ -1,435 +1,34 @@
 # hono-crud
 
-[![npm version](https://img.shields.io/npm/v/hono-crud.svg)](https://www.npmjs.com/package/hono-crud)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)
+CRUD generator for [Hono](https://hono.dev) with Zod validation and OpenAPI generation.
 
-Type-safe CRUD generator for [Hono](https://hono.dev) with Zod validation and automatic OpenAPI documentation.
+Define a model once and register fully-typed Create / Read / Update / Delete / List endpoints. Core also ships auth, logging, events, encryption, serialization, audit, versioning, multi-tenant, and API-versioning helpers. Persistence adapters and docs UIs live in separate `@hono-crud/*` packages.
 
-## Features
-
-- **Full CRUD Operations** - Generate Create, Read, Update, Delete, List endpoints with one call
-- **OpenAPI/Swagger** - Auto-generated docs with Swagger UI, Scalar, and ReDoc
-- **Database Adapters** - Memory (prototyping), Drizzle ORM, and Prisma
-- **4 API Patterns** - Class-based, functional, builder, and config-based
-- **Zod Validation** - Type-safe request/response validation
-- **TypeScript First** - Full type inference and autocompletion
-- **Edge Ready** - Works with Cloudflare Workers, Deno, Bun, and Node.js
-- **Authentication** - JWT, API Key middleware with role/permission guards
-- **Caching** - Response caching with automatic invalidation
-- **Rate Limiting** - Fixed/sliding window with tier-based limits
-- **Advanced Features** - Soft delete, relations, batch operations, search, versioning, audit logging, and more
-
-## Installation
+## Install
 
 ```bash
 npm install hono-crud hono zod
 ```
 
-Peer dependencies: `hono >= 4.0.0` and `zod >= 4.0.0` are required.
+You will also want a storage adapter, e.g. `@hono-crud/memory`, `@hono-crud/drizzle`, or `@hono-crud/prisma`.
 
-## Quick Start
+## Usage
 
-```typescript
-import { Hono } from 'hono';
+```ts
 import { z } from 'zod';
-import { fromHono, registerCrud, setupSwaggerUI, defineModel, defineMeta } from 'hono-crud';
-import {
-  MemoryCreateEndpoint,
-  MemoryReadEndpoint,
-  MemoryUpdateEndpoint,
-  MemoryDeleteEndpoint,
-  MemoryListEndpoint,
-} from 'hono-crud/adapters/memory';
-
-// 1. Define your schema
-const UserSchema = z.object({
-  id: z.uuid(),
-  email: z.email(),
-  name: z.string().min(1),
-  role: z.enum(['admin', 'user']),
-});
-
-// 2. Create model + meta
-const UserModel = defineModel({
-  tableName: 'users',
-  schema: UserSchema,
-  primaryKeys: ['id'],
-});
-
-const userMeta = defineMeta({ model: UserModel });
-
-// 3. Define endpoints
-class UserCreate extends MemoryCreateEndpoint {
-  _meta = userMeta;
-  schema = { tags: ['Users'], summary: 'Create a user' };
-}
+import { fromHono, registerCrud, defineModel, defineMeta } from 'hono-crud';
+import { MemoryCreateEndpoint, MemoryReadEndpoint, MemoryListEndpoint } from '@hono-crud/memory';
 
-class UserList extends MemoryListEndpoint {
-  _meta = userMeta;
-  schema = { tags: ['Users'], summary: 'List users' };
-  filterFields = ['role'];
-  searchFields = ['name', 'email'];
-}
+const UserSchema = z.object({ id: z.string(), name: z.string() });
+const model = defineModel({ schema: UserSchema, primaryKey: 'id' });
+const meta = defineMeta({ tableName: 'users' });
 
-class UserRead extends MemoryReadEndpoint {
-  _meta = userMeta;
-  schema = { tags: ['Users'], summary: 'Get a user' };
-}
-
-class UserUpdate extends MemoryUpdateEndpoint {
-  _meta = userMeta;
-  schema = { tags: ['Users'], summary: 'Update a user' };
-  allowedUpdateFields = ['name', 'role'];
-}
-
-class UserDelete extends MemoryDeleteEndpoint {
-  _meta = userMeta;
-  schema = { tags: ['Users'], summary: 'Delete a user' };
-}
-
-// 4. Wire it up
 const app = fromHono(new Hono());
-
 registerCrud(app, '/users', {
-  create: UserCreate,
-  list: UserList,
-  read: UserRead,
-  update: UserUpdate,
-  delete: UserDelete,
+  model,
+  meta,
+  endpoints: { create: MemoryCreateEndpoint, read: MemoryReadEndpoint, list: MemoryListEndpoint },
 });
-
-// 5. OpenAPI docs
-app.doc('/openapi.json', {
-  openapi: '3.1.0',
-  info: { title: 'My API', version: '1.0.0' },
-});
-setupSwaggerUI(app, { docsPath: '/docs', specPath: '/openapi.json' });
-
-export default app;
 ```
 
-This generates:
-
-| Method | Route | Description |
-|--------|-------|-------------|
-| `POST` | `/users` | Create a user |
-| `GET` | `/users` | List users (with filtering, search, pagination) |
-| `GET` | `/users/:id` | Get a user by ID |
-| `PATCH` | `/users/:id` | Update a user |
-| `DELETE` | `/users/:id` | Delete a user |
-
-## API Patterns
-
-hono-crud supports four ways to define endpoints. All produce classes compatible with `registerCrud()` and can be mixed.
-
-| Pattern | Best For | Style |
-|---------|----------|-------|
-| **Class-based** | Complex logic, database adapters | `class UserList extends MemoryListEndpoint { ... }` |
-| **Functional** | Quick setup | `createList({ meta, filterFields: ['role'] }, MemoryListEndpoint)` |
-| **Builder** | Readable chains | `crud(meta).list().filter('role').build(MemoryListEndpoint)` |
-| **Config-based** | Declarative, all-in-one | `defineEndpoints({ meta, list: { ... } }, MemoryAdapters)` |
-
-```typescript
-import { createList, crud, defineEndpoints, MemoryAdapters } from 'hono-crud';
-
-// Functional
-const UserList = createList(
-  { meta: userMeta, filterFields: ['role'], searchFields: ['name'] },
-  MemoryListEndpoint
-);
-
-// Builder
-const UserList = crud(userMeta)
-  .list()
-  .filter('role')
-  .search('name')
-  .pagination(20, 100)
-  .build(MemoryListEndpoint);
-
-// Config-based (all endpoints at once)
-const endpoints = defineEndpoints({
-  meta: userMeta,
-  create: { openapi: { tags: ['Users'], summary: 'Create user' } },
-  list: { filtering: { fields: ['role'] }, search: { fields: ['name'] } },
-  read: {},
-  update: { fields: { allowed: ['name', 'role'] } },
-  delete: {},
-}, MemoryAdapters);
-
-registerCrud(app, '/users', endpoints);
-```
-
-See [docs/alternative-api-patterns.md](./docs/alternative-api-patterns.md) for the full reference.
-
-## Database Adapters
-
-### Memory
-
-Zero-config, perfect for prototyping and tests:
-
-```typescript
-import { MemoryCreateEndpoint, MemoryListEndpoint /* ... */ } from 'hono-crud/adapters/memory';
-```
-
-### Drizzle
-
-Use `createDrizzleCrud` for minimal boilerplate:
-
-```typescript
-import { createDrizzleCrud } from 'hono-crud/adapters/drizzle';
-import { db } from './db';
-
-const User = createDrizzleCrud(db, userMeta);
-
-class UserCreate extends User.Create {
-  schema = { tags: ['Users'], summary: 'Create user' };
-}
-
-class UserList extends User.List {
-  schema = { tags: ['Users'], summary: 'List users' };
-  filterFields = ['role'];
-}
-```
-
-Or set `db` directly on each endpoint class:
-
-```typescript
-import { DrizzleListEndpoint } from 'hono-crud/adapters/drizzle';
-
-class UserList extends DrizzleListEndpoint {
-  _meta = userMeta;
-  db = drizzleDb;
-  filterFields = ['role'];
-}
-```
-
-### Prisma
-
-```typescript
-import { PrismaListEndpoint } from 'hono-crud/adapters/prisma';
-
-class UserList extends PrismaListEndpoint {
-  _meta = userMeta;
-  prisma = prismaClient;
-  filterFields = ['role'];
-}
-```
-
-See [docs/database-adapters.md](./docs/database-adapters.md) for complete setup guides.
-
-## Authentication
-
-Built-in JWT and API Key middleware with composable guards:
-
-```typescript
-import { createJWTMiddleware, requireRoles, requireAuthenticated, anyOf } from 'hono-crud';
-
-// JWT middleware
-app.use('/api/*', createJWTMiddleware({
-  secret: process.env.JWT_SECRET!,
-  issuer: 'my-app',
-}));
-
-// Guards on specific endpoints
-registerCrud(app, '/users', endpoints, {
-  middlewares: [requireAuthenticated()],
-  endpointMiddlewares: {
-    delete: [requireRoles('admin')],
-  },
-});
-
-// Composable guards
-app.use('/admin/*', anyOf(
-  requireRoles('admin'),
-  requireOwnership((ctx) => ctx.req.param('id'))
-));
-```
-
-See [docs/authentication.md](./docs/authentication.md) for JWT, API Key, guards, and better-auth integration.
-
-## Middleware
-
-### Caching
-
-```typescript
-import { withCache, withCacheInvalidation, setCacheStorage, MemoryCacheStorage } from 'hono-crud';
-
-class UserRead extends withCache(MemoryReadEndpoint) {
-  _meta = userMeta;
-  cacheConfig = { ttl: 300, perUser: false };
-}
-```
-
-See [docs/caching.md](./docs/caching.md).
-
-### Rate Limiting
-
-```typescript
-import { createRateLimitMiddleware, setRateLimitStorage, MemoryRateLimitStorage } from 'hono-crud';
-
-setRateLimitStorage(new MemoryRateLimitStorage());
-
-app.use('/api/*', createRateLimitMiddleware({
-  limit: 100,
-  windowSeconds: 60,
-  keyStrategy: 'ip',
-}));
-```
-
-See [docs/rate-limiting.md](./docs/rate-limiting.md).
-
-### Logging
-
-```typescript
-import { createLoggingMiddleware, setLoggingStorage, MemoryLoggingStorage } from 'hono-crud';
-
-setLoggingStorage(new MemoryLoggingStorage());
-
-app.use('*', createLoggingMiddleware({
-  redactHeaders: ['authorization', 'cookie'],
-  redactBodyFields: ['password'],
-}));
-```
-
-See [docs/logging.md](./docs/logging.md).
-
-## Response shape
-
-Every CRUD endpoint defaults to a small, predictable response envelope so consumers always know where to find `result` and `error`:
-
-```jsonc
-// Success — single item (Create / Read / Update / Restore / Upsert / Clone / …)
-{ "success": true, "result": { "id": "…", … } }
-
-// Success — list / search (with pagination metadata)
-{ "success": true, "result": [ … ], "result_info": { "page": 1, "per_page": 20, … } }
-
-// Error — produced by `ApiException`s thrown from the endpoint or by
-// `createErrorHandler` for everything else
-{ "success": false, "error": { "code": "NOT_FOUND", "message": "…", "details": … } }
-```
-
-### Pluggable envelope (`responseEnvelope`)
-
-If your house API standard prefers a different shape — RFC 7807 Problem Details, JSON:API `{ data, meta }`, or any custom envelope — pass `responseEnvelope` to `registerCrud`. The two functions are the **final formatting step** before the response body is serialised:
-
-```typescript
-import { registerCrud, type ResponseEnvelope } from 'hono-crud';
-
-const envelope: ResponseEnvelope = {
-  success: (result, info) =>
-    info ? { data: result, meta: info } : { data: result },
-  error: (err) => ({
-    errors: [{ status: err.code, title: err.message, source: err.details }],
-  }),
-};
-
-registerCrud(app, '/users', endpoints, { responseEnvelope: envelope });
-```
-
-The `info` argument is the pagination metadata for list/search responses; it's `undefined` for single-item responses, so a single envelope works across the whole CRUD surface.
-
-### Composition with `createErrorHandler`
-
-For errors, the envelope composes with the existing `mappers` chain on `createErrorHandler`. The order is fixed:
-
-1. `mappers[]` (and the built-in `zodErrorMapper`) transform the raw `Error` into a structured `ApiException` (`{ code, message, details? }`).
-2. `responseEnvelope.error(...)` wraps that structured object into the final response body.
-
-```typescript
-import { createErrorHandler, type ErrorMapper } from 'hono-crud';
-
-const prismaMapper: ErrorMapper = (err) => {
-  if ((err as { code?: string }).code === 'P2002') {
-    return new ConflictException('Duplicate key', { /* … */ });
-  }
-};
-
-app.onError(createErrorHandler({
-  mappers: [prismaMapper],
-  // Handler-level default — applies to errors that propagate to onError
-  // (i.e. anything that's not already an ApiException). Per-route envelope
-  // set via `registerCrud({ responseEnvelope })` always wins.
-  responseEnvelope: envelope,
-}));
-```
-
-This split lets you keep your domain-error mappers (Prisma codes, Drizzle constraint violations, …) unchanged and layer a custom shape on top — no response-rewriting middleware required.
-
-When `responseEnvelope` is omitted (the default), the response body is byte-identical to pre-0.10.0 — existing consumers see no behaviour change.
-
-## Advanced Features
-
-- **Soft Delete & Restore** - `softDelete: true` in model, `?withDeleted=true`, restore endpoint
-- **Relations** - `hasOne`, `hasMany`, `belongsTo` with `?include=posts,profile`
-- **Nested Writes** - Create/update related records in a single request
-- **Batch Operations** - Batch create, update, delete, restore, upsert
-- **Upsert** - Create or update by unique keys
-- **Versioning** - Record version history with rollback
-- **Audit Logging** - Track who changed what and when
-- **Full-Text Search** - Weighted search with highlighting
-- **Aggregation** - Sum, count, avg, min, max with grouping
-- **Export/Import** - CSV and JSON export/import
-- **Computed Fields** - Virtual fields calculated on read
-- **Field Selection** - `?fields=id,name,email`
-- **Events & Webhooks** - Event emitter with webhook delivery
-- **Encryption** - Field-level encryption with Web Crypto API
-- **Idempotency** - Idempotency key middleware for safe retries
-- **Multi-Tenancy** - Tenant isolation via header, path, query, or JWT
-- **Health Checks** - Liveness and readiness endpoints
-- **Error Handling** - Typed exceptions with custom error handlers
-
-See [docs/advanced-features.md](./docs/advanced-features.md) for examples of every feature.
-
-### Subpath Imports
-
-Every advanced feature is also exposed as a tree-shakeable subpath, so apps that only need one feature can import it directly without pulling in the rest of the library:
-
-```typescript
-import { multiTenant } from 'hono-crud/multi-tenant';
-import { createAuditLogger, MemoryAuditLogStorage } from 'hono-crud/audit';
-import { VersionManager, MemoryVersioningStorage } from 'hono-crud/versioning';
-import { CrudEventEmitter, registerWebhooks } from 'hono-crud/events';
-import { idempotency, MemoryIdempotencyStorage } from 'hono-crud/idempotency';
-import { createHealthEndpoints } from 'hono-crud/health';
-import { encryptFields, decryptFields, StaticKeyProvider } from 'hono-crud/encryption';
-import { applyProfile, type SerializationProfile } from 'hono-crud/serialization';
-import { apiVersion, getApiVersion } from 'hono-crud/api-version';
-```
-
-The same symbols remain available from `'hono-crud'` for convenience.
-
-## API Documentation
-
-```typescript
-import { setupSwaggerUI, setupReDoc, setupScalar } from 'hono-crud';
-
-// OpenAPI spec
-app.doc('/openapi.json', {
-  openapi: '3.1.0',
-  info: { title: 'My API', version: '1.0.0' },
-});
-
-// Documentation UIs
-setupSwaggerUI(app, { docsPath: '/docs', specPath: '/openapi.json' });
-setupReDoc(app, { redocPath: '/redoc', specPath: '/openapi.json' });
-setupScalar(app, '/reference', { specUrl: '/openapi.json' });
-```
-
-## Examples
-
-See the [examples/](./examples) directory for complete working applications:
-
-- [Memory Adapter](./examples/memory) - Basic CRUD, alternative APIs, comprehensive features
-- [Drizzle + PostgreSQL](./examples/drizzle) - Schema, relations, filtering, batch operations
-- [Prisma + PostgreSQL](./examples/prisma) - Schema, relations, filtering, batch operations
-
-## Requirements
-
-- Node.js >= 20
-- TypeScript >= 5.0
-
-## License
-
-[MIT](./LICENSE) - Kauan Guesser
+See the [repository README](https://github.com/kshdotdev/hono-crud) for the full guide.

package/dist/audit/index.d.ts

@@ -1,8 +1,8 @@
 import { Context, Env } from 'hono';
-import { A as AuditConfig, c as AuditLogEntry, d as AuditAction } from '../types-Dfi9RdjS.js';
+import { A as AuditConfig, a as AuditLogEntry, b as AuditAction } from '../types-38Hj6wN4.js';
 import { S as StorageRegistry } from '../registry-PNJjvSvm.js';
 import 'zod';
-import '../types-B5wq2iKZ.js';
+import '../types-DcRAcexC.js';
 import '../types-BAcN7U0B.js';
 import '@hono/zod-openapi';
 

package/dist/audit/index.js

@@ -1 +1 @@
-export{e as AuditLogger,a as MemoryAuditLogStorage,b as auditStorageRegistry,f as createAuditLogger,d as getAuditStorage,c as setAuditStorage}from'../chunk-FJCWFB5L.js';import'../chunk-KUFOENSK.js';import'../chunk-GBQQ3YQX.js';import'../chunk-MDHMZPXK.js';import'../chunk-VJRDAVID.js';
+export{e as AuditLogger,a as MemoryAuditLogStorage,b as auditStorageRegistry,f as createAuditLogger,d as getAuditStorage,c as setAuditStorage}from'../chunk-CTU6AAXM.js';import'../chunk-RU3RY5SC.js';import'../chunk-MDHMZPXK.js';import'../chunk-VJRDAVID.js';