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.md

GitHub

Guren 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's paths frontmatter 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 after bunx guren codegen, an undeclared segment is undefined, 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 body
  • this.validateQuery<T>(schema): T — parse query parameters
  • this.validateParams<T>(schema): T — parse route parameters

All throw ValidationException (HTTP 422) on failure.

Auth helpers:

  • this.auth.user<T>() — returns user or null
  • this.auth.userOrFail<T>() — returns user or throws AuthenticationException (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 to create() / update(); unlisted input keys throw MassAssignmentException. The primary key (id) is always silently stripped. static fillable = [...] on the class also works (untyped) and shadows the option; hidden, visible, accessors, and appends have the same typed option forms.
  • Credential columns (passwordHash, rememberToken) always throw on authenticatable models — the framework denies them; listing them in fillable does not open them
  • Enforced by Model.filterFillable(), called automatically before persistence
  • Always define fillable on models that accept user input — this is the second defense layer after Zod validation
  • A column the server chooses (owner authorId, parent postId) stays out of fillable and goes in set: Post.create(data, { set: { authorId: user.id } }), Post.update(where, data, { set: { … } }). data is still filtered; set throws on id, a credential column, a fillable key, a key data also carries, or a model with no fillable. Never spread request input into set
  • 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 codegen extracts schemas → generates typed ApiRoutes interface
  • 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 new TestApp — 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 (useDatabaseTransactions etc.) use bun:test globals automatically — vitest projects import '@guren/testing/vitest' once in setup to register hooks

Extended Subsystems

Authorization (Gate & Policy)

Source: packages/server/src/authorization/

  • Gate.ts — Define abilities and policies
  • Policy.ts — Resource-based authorization
  • middleware.ts — Route-level authorization middleware

Events & Listeners

Source: packages/server/src/events/

  • Event.ts — Base event class
  • EventManager.ts — Event dispatcher
  • Listener.ts — Base listener class
  • builtin.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 with handle() method
  • QueueManager.ts — Queue manager (memory, Redis drivers)
  • Worker.ts — Queue worker process

Drivers: packages/server/src/queue/drivers/

Mail

Source: packages/server/src/mail/

  • Mail.ts — Base mailable class
  • MailManager.ts — Mail manager

Transports:

  • MemoryTransport.ts — For testing
  • ResendTransport.ts — Resend API
  • SmtpTransport.ts — SMTP

Cache

Source: packages/server/src/cache/

  • CacheManager.ts — Cache manager
  • TaggedCache.ts — Tag-based cache invalidation

Stores:

  • MemoryStore.ts — In-memory
  • FileStore.ts — File-based
  • RedisStore.ts — Redis

Validation

Source: packages/server/src/http/validation/

  • Validator.ts — Validation engine
  • rules.ts — Built-in validation rules
  • FormRequest.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 class
  • NotificationManager.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 definition
  • Scheduler.ts — Scheduler runner
  • ScheduledTask.ts — Individual scheduled task
  • CronParser.ts — Cron expression parser

I18n (Internationalization)

Source: packages/server/src/i18n/

  • I18nManager.ts — I18n manager
  • Translator.ts — Translation engine
  • pluralization.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 values
  • Hash.ts — Hashing utilities
  • Random.ts — Secure random generation

Health Checks

Source: packages/server/src/health/

  • HealthManager.ts — Health check manager
  • HealthCheck.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-typed statusCode property)
  • HttpException.ts — Base HTTP exception
  • debug-page.ts — Debug error page

Exceptions: NotFoundHttpException.ts, ValidationException.ts, AuthenticationException.ts, AuthorizationException.ts, MethodNotAllowedException.ts

The ExceptionHandler automatically handles:

  • HttpException subclasses → uses their status code
  • Any error with a statusCode property (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 container
  • ServiceProvider.ts — Base service provider

Built-in providers: packages/server/src/providers/

Console Commands

Source: packages/server/src/console/

  • Command.ts — Base command class
  • ConsoleKernel.ts — Console kernel
  • Input.ts / Output.ts — IO handling

API Resources

Source: packages/server/src/http/resources/

  • Resource.ts — API resource transformer
  • ResourceCollection.ts — Collection of resources
  • Paginator.ts — Offset-based pagination
  • CursorPaginator.ts — Cursor-based pagination

Database (Factory & Seeder)

Source: packages/server/src/database/

  • Factory.ts — Model factory for testing
  • Seeder.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 manager
  • Logger.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/
Mail 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/