guren-api
Human-browsable Guren API reference — code patterns and examples for every subsystem (Controllers, Models, Routes, Middleware, Authentication, Authorization, Events, Jobs, Queue, Mail, Cache, Validati
SKILL.mdpackages/cli/templates/agent/core/skills/guren-api/SKILL.md
GitHubGuren API Documentation Skill
You are a documentation assistant for the Guren framework.
The authoritative signature-level API reference lives in
__RULES_DIR__/*.md(each file'spathsfrontmatter states the paths it covers); this skill is a subsystem tour for interactive Q&A.
Your Role
Help users understand and use Guren framework APIs by providing examples, patterns, and source file locations.
Core Subsystems
Controllers
Source: packages/server/src/mvc/Controller.ts
import { Controller } from '@guren/core'
import { pages } from '@/.guren/pages.gen'
import { PostPayloadSchema, PostIdParamSchema } from '../Validators/PostValidator.js'
export default class PostController extends Controller {
async index() {
const posts = await Post.all()
return this.inertia(pages.posts.Index, { posts })
}
async show() {
const { id } = this.validateParams(PostIdParamSchema) // throws 422
const post = await Post.findOrFail(id) // throws 404
return this.inertia(pages.posts.Show, { post })
}
async store() {
// routes/web.ts: router.post('/posts', { name: 'posts.store', body: PostPayloadSchema }, [PostController, 'store'])
const { body: data } = this.validated('posts.store') // route contract already answered 422
const user = await this.auth.userOrFail<UserRecord>() // throws 401 — <T> defaults to Authenticatable, no .id
const post = await Post.create(data, { set: { authorId: user.id } }) // authorId is not fillable
return this.redirect('/posts/' + post?.id)
}
}
Note: Server-side controllers use URL string literals for redirects. The
route()helper is a frontend-only utility generated by codegen for React components.
For public content pages that need no client framework (blog posts, docs),
this.view(Component, props, options?) renders a hono/jsx component from
app/View/ to plain SSR HTML — see rules/controllers-http.md
("Server-rendered content pages") for the conventions.
Route contract input: a route's params/query/body schemas are validated before the action (422 on failure):
this.validated('route.name')→{ params, query, body }as the schemas parsed them; typed afterbunx guren codegen, an undeclared segment isundefined, and a name other than the served route throws
Validation helpers (Zod duck-type — any schema with safeParse() works), for routes without a contract:
this.validateBody<T>(schema): Promise<T>— parse request bodythis.validateQuery<T>(schema): T— parse query parametersthis.validateParams<T>(schema): T— parse route parameters
All throw ValidationException (HTTP 422) on failure.
Auth helpers:
this.auth.user<T>()— returns user or nullthis.auth.userOrFail<T>()— returns user or throwsAuthenticationException(401)
Models
Source: packages/orm/src/Model.ts
import { defineModel } from '@guren/core'
import { posts } from '@/db/schema'
export class Post extends defineModel(posts) {}
// Usage
await Post.find(1) // returns null if not found
await Post.findOrFail(1) // throws ModelNotFoundException (404)
await Post.where('published', true).get()
await Post.create({ title: 'Hello' })
ModelNotFoundException (source: packages/orm/src/ModelNotFoundException.ts) carries statusCode: 404 and is automatically rendered as HTTP 404 by the ExceptionHandler.
Mass assignment protection — prevent injection of unintended fields via create() / update():
export class Post extends defineModel(posts, {
// Whitelist: only these fields are accepted (recommended).
// Typed against the table's columns — a typo is a compile error.
// authorId is chosen by the server, so it is not listed: it goes in `set`.
fillable: ['title', 'excerpt', 'body'],
}) {}
export class User extends defineModel(users, {
base: AuthenticatableModel,
// The model hashes a plain `password` into `passwordHash`
optionalOnCreate: ['passwordHash'],
requireOnCreate: ['password'],
// Whitelist for mass assignment (credential columns are denied by the base class)
fillable: ['name', 'email', 'password'],
}) {}
fillable(whitelist) — only listed fields pass through tocreate()/update(); unlisted input keys throwMassAssignmentException. The primary key (id) is always silently stripped.static fillable = [...]on the class also works (untyped) and shadows the option;hidden,visible,accessors, andappendshave the same typed option forms.- Credential columns (
passwordHash,rememberToken) always throw on authenticatable models — the framework denies them; listing them infillabledoes not open them - Enforced by
Model.filterFillable(), called automatically before persistence - Always define
fillableon models that accept user input — this is the second defense layer after Zod validation - A column the server chooses (owner
authorId, parentpostId) stays out offillableand goes inset:Post.create(data, { set: { authorId: user.id } }),Post.update(where, data, { set: { … } }).datais still filtered;setthrows onid, a credential column, a fillable key, a keydataalso carries, or a model with nofillable. Never spread request input intoset forceCreate()/forceUpdate()bypass filtering. They are for writes that carry no request data: seeders, system records, OAuth hash sentinels (passwordHash: 'oauth:...'). Never call them with request input
Relationships — declare once, eager-load anywhere:
// app/Models/User.ts
export class User extends defineModel(users, { base: AuthenticatableModel, optionalOnCreate: ['passwordHash'] }) {
static override relationTypes: { posts: HasManyRecord<PostRecord> } = { posts: [] }
}
User.hasMany('posts', () => import('./Post.js').then((m) => m.Post), 'authorId', 'id')
// app/Models/Post.ts
export class Post extends defineModel(posts) {
static override relationTypes: { author: BelongsToRecord<UserRecord> } = { author: null }
}
Post.belongsTo('author', () => import('./User.js').then((m) => m.User), 'authorId', 'id')
// Eager loading (typed via relationTypes)
await User.with('posts') // users[0].posts: PostRecord[]
await User.with('posts.comments') // nested, dot notation
await User.where('active', true).with('posts').get() // QueryBuilder
await User.findWith(1, 'posts') // single record + relations
await User.withCount('posts') // users[0].postsCount: number (no rows loaded)
await Post.withPaginate('author', { page: 1 }) // paginated + relations
Also available: hasOne, belongsToMany(name, related, pivotTable, foreignPivotKey, relatedPivotKey, parentKey?, relatedKey?), hasManyThrough, morphMany/morphTo. There are no attach/detach/sync pivot helpers and no firstOrCreate/updateOrCreate — manage pivot rows via a model on the pivot table (PivotModel.create(...) / PivotModel.delete(...)), and hand-roll find-or-create with Model.first(where) + Model.create(...). Full guide: docs/en/guides/database.md (Relationships section).
Routes
Source: packages/server/src/mvc/Router.ts
import { Router, requireAuthenticated } from '@guren/core'
import { PostPayloadSchema } from '../app/Http/Validators/PostValidator.js'
export function registerWebRoutes(baseRouter: Router): void {
// aliasMiddleware() returns a Router carrying the alias name in its type —
// capture it, or a later .middleware('auth') will not compile.
const router = baseRouter.aliasMiddleware('auth', requireAuthenticated({ redirectTo: '/login' }))
router.get('/posts', [PostController, 'index']).name('posts.index')
// Attach body schema to mutation routes for codegen type extraction
router.post('/posts', { name: 'posts.store', body: PostPayloadSchema }, [PostController, 'store'])
router.put('/posts/:id', { name: 'posts.update', body: PostPayloadSchema }, [PostController, 'update'])
router.middleware('auth').group((auth) => {
auth.get('/dashboard', [DashboardController, 'index'])
})
}
Verbs: get / post / put / patch / delete / query share the same overloads;
router.on(method, path, ...) covers anything else. query() registers HTTP QUERY
(RFC 10008) — safe like GET but body-carrying; read-only handlers only (CSRF skips it),
not expressible in OpenAPI 3.1, not sendable from Inertia forms (use the API client).
Route contract options — attach body, params, query schemas to routes:
- Schemas are metadata for codegen (not double-validated for Controller actions)
bunx guren codegenextracts schemas → generates typedApiRoutesinterface- Frontend derives form types via
RouteBody<ApiRoutes, 'route.name'>
End-to-End Type Safety
Source: packages/cli/src/api-client-types.ts, packages/inertia-client/src/typed-forms.ts
Guren provides bidirectional type safety between frontend forms and backend validation:
Zod schema (Validator) → Route body option → codegen → ApiRoutes → Frontend form type
→ Route contract middleware → Runtime validation (422 on failure) → this.validated()
ApiRoutes[...]['body'] is the request shape — what the browser sends, before
validation. A coercing schema is rendered as it travels: z.coerce.date() is a
string in the form and a Date in the controller. ['response'] is the other
side, the parsed shape a client gets back.
1. Define schema once (Validator file):
export const PostPayloadSchema = z.object({ title: z.string().min(1), body: z.string().min(1) })
2. Attach to route (routes/web.ts):
router.post('/posts', { name: 'posts.store', body: PostPayloadSchema }, [PostController, 'store'])
3. Frontend derives types (after bunx guren codegen):
import type { ApiRoutes } from '@/.guren/api-client.gen'
import type { RouteBody, RouteErrors } from '@guren/inertia-client/typed-forms'
import { route } from '@/.guren/routes.gen'
type PostFormData = RouteBody<ApiRoutes, 'posts.store'> // { title: string; body: string }
type PostErrors = RouteErrors<PostFormData> // Partial<Record<'title' | 'body', string | string[]>>
// Typed form submission
form.post(route('posts.store'))
// Typed navigation
<Link href={route('posts.show', { id: post.id })}>
4. Controller reads the validated body (the route validated it before the action ran):
const { body: data } = this.validated('posts.store') // typed from the contract after codegen
Middleware
Source: packages/server/src/http/middleware/
import { defineMiddleware } from '@guren/core'
export const logRequest = defineMiddleware(async (ctx, next) => {
console.log(ctx.req.method, ctx.req.url)
await next()
})
Authentication
Source: packages/server/src/auth/
import { Router, requireAuthenticated } from '@guren/core'
const router = new Router()
.aliasMiddleware('auth', requireAuthenticated({ redirectTo: '/login' }))
router.middleware('auth').group((auth) => {
// Protected routes
})
// In controller
const user = await this.auth.user() // returns user | null
const user = await this.auth.userOrFail() // throws AuthenticationException (401)
const isLoggedIn = await this.auth.check() // returns boolean
Additional auth features:
- API Tokens:
packages/server/src/auth/api-token.ts - Email Verification:
packages/server/src/auth/email-verification.ts - Password Reset:
packages/server/src/auth/password-reset.ts
Testing (@guren/testing)
Source: packages/testing/src/
Included by default in create-app-scaffolded apps' devDependencies; if missing, bun add -d @guren/testing.
import { TestApp } from '@guren/testing'
const app = await TestApp.create({
auth: {}, // mounts session + CSRF middleware (needed for withCsrf())
routes: registerWebRoutes,
})
await app.get('/posts').assertOk()
const csrf = await app.actingAs(user).withCsrf() // header auth + primed XSRF cookie
await csrf.post('/posts', { title: 'Hi' }).assertRedirect('/posts')
actingAs(user)/withCsrf()each return a newTestApp— chain or reassign, don't discard the result- Without
auth, no session/CSRF middleware is mounted —app.json().post(...)skips CSRF entirely, fine for quick checks but not production-representative - The main entry has no vitest dependency; DB lifecycle helpers (
useDatabaseTransactionsetc.) use bun:test globals automatically — vitest projectsimport '@guren/testing/vitest'once in setup to register hooks
Extended Subsystems
Authorization (Gate & Policy)
Source: packages/server/src/authorization/
Gate.ts— Define abilities and policiesPolicy.ts— Resource-based authorizationmiddleware.ts— Route-level authorization middleware
Events & Listeners
Source: packages/server/src/events/
Event.ts— Base event classEventManager.ts— Event dispatcherListener.ts— Base listener classbuiltin.ts— Built-in framework events
Register listeners with events.listen(Listener) in the app's event provider
(app/Providers/EventProvider.ts), and list that provider in createApp({ providers }).
Jobs & Queue
Source: packages/server/src/queue/
Job.ts— Base job class withhandle()methodQueueManager.ts— Queue manager (memory, Redis drivers)Worker.ts— Queue worker process
Drivers: packages/server/src/queue/drivers/
Source: packages/server/src/mail/
Mail.ts— Base mailable classMailManager.ts— Mail manager
Transports:
MemoryTransport.ts— For testingResendTransport.ts— Resend APISmtpTransport.ts— SMTP
Cache
Source: packages/server/src/cache/
CacheManager.ts— Cache managerTaggedCache.ts— Tag-based cache invalidation
Stores:
MemoryStore.ts— In-memoryFileStore.ts— File-basedRedisStore.ts— Redis
Validation
Source: packages/server/src/http/validation/
Validator.ts— Validation enginerules.ts— Built-in validation rulesFormRequest.ts— Form request validation (packages/server/src/http/FormRequest.ts)
Broadcasting
Source: packages/server/src/broadcasting/
BroadcastManager.ts— Broadcast manager
Channels: Channel.ts, PrivateChannel.ts, PresenceChannel.ts
Drivers: MemoryDriver.ts, RedisDriver.ts
Notifications
Source: packages/server/src/notifications/
Notification.ts— Base notification classNotificationManager.ts— Notification dispatcher
Channels: MailChannel.ts, SlackChannel.ts, DatabaseChannel.ts, MemoryChannel.ts
Storage
Source: packages/server/src/storage/
StorageManager.ts— Storage manager
Drivers: LocalDriver.ts, MemoryDriver.ts, S3Driver.ts. On Cloudflare Workers, R2Driver from @guren/plugin-cloudflare (bucket binding; register with storage.registerDisk()).
Scheduling
Source: packages/server/src/scheduling/
Schedule.ts— Schedule definitionScheduler.ts— Scheduler runnerScheduledTask.ts— Individual scheduled taskCronParser.ts— Cron expression parser
I18n (Internationalization)
Source: packages/server/src/i18n/
I18nManager.ts— I18n managerTranslator.ts— Translation enginepluralization.ts— Pluralization rules
Loaders: JsonLoader.ts, MemoryLoader.ts
App wiring: createApp({ i18n: { supported: ['en', 'ja'] } }) loads
lang/<locale>/*.json, mounts locale detection (query → cookie →
Accept-Language), and shares the _i18n prop with Inertia pages.
Translate with this.t() / this.tc() / this.locale in controllers and
useTranslation() from @guren/inertia-client in pages. guren codegen
emits typed keys (.guren/translations.gen.ts); guren check --i18n
validates catalog parity and placeholders.
Encryption
Source: packages/server/src/encryption/
Encrypter.ts— Encrypt/decrypt valuesHash.ts— Hashing utilitiesRandom.ts— Secure random generation
Health Checks
Source: packages/server/src/health/
HealthManager.ts— Health check managerHealthCheck.ts— Base health check
Checks: DatabaseCheck.ts, RedisCheck.ts, CacheCheck.ts, MemoryCheck.ts, StorageCheck.ts, CustomCheck.ts
Error Handling
Source: packages/server/src/errors/
ExceptionHandler.ts— Global exception handler (supports duck-typedstatusCodeproperty)HttpException.ts— Base HTTP exceptiondebug-page.ts— Debug error page
Exceptions: NotFoundHttpException.ts, ValidationException.ts, AuthenticationException.ts, AuthorizationException.ts, MethodNotAllowedException.ts
The ExceptionHandler automatically handles:
HttpExceptionsubclasses → uses their status code- Any error with a
statusCodeproperty (duck-typed) → uses that status code (e.g.,ModelNotFoundException→ 404) - Other errors → 500 (message hidden unless debug mode)
Factory methods — throw directly from a controller method, no try/catch needed:
HttpException.badRequest(msg?) // 400
HttpException.unauthorized(msg?) // 401
HttpException.forbidden(msg?) // 403
HttpException.notFound(msg?) // 404
HttpException.conflict(msg?) // 409
HttpException.unprocessable(msg?, errors?) // 422 — same errors shape as validateBody()
HttpException.internal(msg?) // 500
// also: methodNotAllowed / gone / tooManyRequests / notImplemented / badGateway / serviceUnavailable / gatewayTimeout
new ValidationException({ email: ['Already registered'] }) // 422
ValidationException.withMessages({ email: 'Already registered' }) // string | string[] values
new AuthenticationException(message?, guard?, redirectTo?) // 401
AuthenticationException.withRedirect(redirectTo, message?)
new AuthorizationException(message?, action?, resource?) // 403
AuthorizationException.deny(resource?) // e.g. AuthorizationException.deny('Comment')
AuthorizationException.forAction(action, resource?)
new NotFoundHttpException(message?) // 404
NotFoundHttpException.forModel('User', 123)
Model.findOrFail() throws ModelNotFoundException (exported from @guren/core) — it does not extend HttpException; the handler picks it up via its duck-typed statusCode: 404.
Container & Service Providers
Source: packages/server/src/container/
Container.ts— IoC containerServiceProvider.ts— Base service provider
Built-in providers: packages/server/src/providers/
Console Commands
Source: packages/server/src/console/
Command.ts— Base command classConsoleKernel.ts— Console kernelInput.ts/Output.ts— IO handling
API Resources
Source: packages/server/src/http/resources/
Resource.ts— API resource transformerResourceCollection.ts— Collection of resourcesPaginator.ts— Offset-based paginationCursorPaginator.ts— Cursor-based pagination
Database (Factory & Seeder)
Source: packages/server/src/database/
Factory.ts— Model factory for testingSeeder.ts—BaseSeeder/Seeder, deprecated in 2.9.0 (removed in 3.0.0)SeederRunner.ts— deprecated in 2.9.0 (removed in 3.0.0), wired to no command
Seeding itself does not live here. db:seed runs every seeder in db/seeders/,
and seeders are written with defineSeeder from @guren/core.
Logging
Source: packages/server/src/logging/
LogManager.ts— Log managerLogger.ts— Logger instance
Channels: ConsoleChannel.ts, FileChannel.ts, DailyFileChannel.ts
Redis
Source: packages/server/src/redis/
client.ts— Redis client- Session, rate-limit, API token, email verification, password reset stores
Reference Locations
| Subsystem | Source Path |
|---|---|
| Controllers | packages/server/src/mvc/Controller.ts |
| Models | packages/orm/src/Model.ts |
| Routes | packages/server/src/mvc/Route.ts |
| Auth | packages/server/src/auth/ |
| Testing | packages/testing/src/ |
| Authorization | packages/server/src/authorization/ |
| Events | packages/server/src/events/ |
| Queue/Jobs | packages/server/src/queue/ |
packages/server/src/mail/ |
|
| Cache | packages/server/src/cache/ |
| Validation | packages/server/src/http/validation/ |
| Broadcasting | packages/server/src/broadcasting/ |
| Notifications | packages/server/src/notifications/ |
| Storage | packages/server/src/storage/ |
| Scheduling | packages/server/src/scheduling/ |
| I18n | packages/server/src/i18n/ |
| Encryption | packages/server/src/encryption/ |
| Health Checks | packages/server/src/health/ |
| Error Handling | packages/server/src/errors/ |
| Container | packages/server/src/container/ |
| Console | packages/server/src/console/ |
| API Resources | packages/server/src/http/resources/ |
| Database/Seeder | packages/server/src/database/ |
| Logging | packages/server/src/logging/ |
| Redis | packages/server/src/redis/ |
| Example App | examples/blog/ |
| API Example | examples/api/ |
| Docs | web/ |