honertia 0.1.2 → 0.1.4

package/README.md

@@ -11,11 +11,11 @@
 
 ## Overview
 
-An Inertia.js-style adapter for Hono with Effect.js integration. Inertia keeps a server-driven app but behaves like an SPA: link clicks and form posts are intercepted, a fetch/XHR request returns a JSON page object (component + props), and the client swaps the page without a full reload. Honertia layers Laravel-style route patterns and Effect actions on top of that so handlers stay clean, readable, and composable.
+An Inertia.js-style adapter for Hono with Effect.ts integration. Inertia keeps a server-driven app but behaves like an SPA: link clicks and form posts are intercepted, a fetch/XHR request returns a JSON page object (component + props), and the client swaps the page without a full reload. Honertia layers Laravel-style route patterns and Effect actions on top of that so handlers stay clean, readable, and composable.
 
 ## Raison d'être
 
-I've found myself wanting to use Cloudflare Workers for everything, but having come from a Laravel background nothing quite matched the DX and simplicity of Laravel x Inertia.js. When building Laravel projects I would always use Loris Leiva's laravel-actions package among other opinionated architecture decisions such as Vite, Tailwind, Bun, React etc., all of which have or will be incorporated into this project. With Cloudflare Workers the obvious choice is Hono and so we've adapted the Inertia.js protocol to run on workers+hono to mimic a Laravel-style app. Ever since learning of Effect.ts I've known that I wanted to use it for something bigger, and so we've utilised it here. Ultimately this is a workers+hono+vite+bun+laravel+inertia+effect+betterauth+planetscale mashup.
+I wanted to build on Cloudflare Workers whilst retaining the ergonomics of the Laravel+Inertia combination. There are certain patterns that I always use with Laravel (such as the laravel-actions package) and so we have incorporated those ideas into honertia. Now, we can't have Laravel in javascript - but we can create it in the aggregate. For auth we have used better-auth, for validation we have leant on Effect's Schema, and for the database we are using Drizzle. To make it testable and hardy we wrapped everything in Effect.ts
 
 ## Installation
 
@@ -25,6 +25,37 @@ bun add honertia
 
 ## Quick Start
 
+[![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/PatrickOgilvie/honertia-worker-demo)
+
+### Recommended File Structure
+
+```
+.
+├── src/
+│   ├── index.ts                 # Hono app setup (setupHonertia)
+│   ├── routes.ts                # effectRoutes / effectAuthRoutes
+│   ├── main.tsx                 # Inertia + React client entry
+│   ├── styles.css               # Tailwind CSS entry
+│   ├── actions/
+│   │   └── projects/
+│   │       └── list.ts           # listProjects action
+│   ├── pages/
+│   │   └── Projects/
+│   │       └── Index.tsx         # render('Projects/Index')
+│   ├── db/
+│   │   └── db.ts
+│   │   └── schema.ts
+│   ├── lib/
+│   │   └── auth.ts
+│   └── types.ts
+├── dist/
+│   └── manifest.json            # generated by Vite build
+├── vite.config.ts
+├── wrangler.toml                # or wrangler.jsonc
+├── package.json
+└── tsconfig.json
+```
+
 ```typescript
 // src/index.ts
 import { Hono } from 'hono'
@@ -33,8 +64,8 @@ import { setupHonertia, createTemplate, createVersion, registerErrorHandlers, vi
 import { Context, Layer } from 'effect'
 import manifest from '../dist/manifest.json'
 
-import { createDb } from './db'
 import type { Env } from './types'
+import { createDb } from './db/db'
 import { createAuth } from './lib/auth'
 import { registerRoutes } from './routes'
 
@@ -100,13 +131,17 @@ import type { Env } from './types'
 import { effectRoutes } from 'honertia/effect'
 import { effectAuthRoutes, RequireAuthLayer } from 'honertia/auth'
 import { showDashboard, listProjects, createProject, showProject, deleteProject } from './actions'
+import { loginUser, registerUser, logoutUser } from './actions/auth'
 
 export function registerRoutes(app: Hono<Env>) {
-  // Auth routes (login, register, logout, API handler) wired to better-auth.
-  // CORS for /api/auth/* can be enabled via the `cors` option (see below).
+  // Auth routes: pages, form actions, logout, and API handler in one place.
   effectAuthRoutes(app, {
     loginComponent: 'Auth/Login',
     registerComponent: 'Auth/Register',
+    // Form actions (automatically wrapped with RequireGuestLayer)
+    loginAction: loginUser,
+    registerAction: registerUser,
+    logoutAction: logoutUser,
   })
 
   // Effect routes give you typed, DI-friendly handlers (no direct Hono ctx).
@@ -126,6 +161,126 @@ export function registerRoutes(app: Hono<Env>) {
 }
 ```
 
+### Example Action
+
+Here's the `listProjects` action referenced above:
+
+```typescript
+// src/actions/projects/list.ts
+import { Effect } from 'effect'
+import { eq } from 'drizzle-orm'
+import { DatabaseService, AuthUserService, render, type AuthUser } from 'honertia/effect'
+import { schema, type Database, type Project } from '../../db'
+
+interface ProjectsIndexProps {
+  projects: Project[]
+}
+
+const fetchProjects = (
+  db: Database,
+  user: AuthUser
+): Effect.Effect<ProjectsIndexProps, Error, never> =>
+  Effect.tryPromise({
+    try: async () => {
+      const projects = await db.query.projects.findMany({
+        where: eq(schema.projects.userId, user.user.id),
+        orderBy: (projects, { desc }) => [desc(projects.createdAt)],
+      })
+      return { projects }
+    },
+    catch: (error) => error instanceof Error ? error : new Error(String(error)),
+  })
+
+export const listProjects = Effect.gen(function* () {
+  const db = yield* DatabaseService
+  const user = yield* AuthUserService
+  const props = yield* fetchProjects(db as Database, user)
+  return yield* render('Projects/Index', props)
+})
+```
+
+The component name `Projects/Index` maps to a file on disk. A common
+Vite + React layout is:
+
+```
+src/pages/Projects/Index.tsx
+```
+
+That means the folders mirror the component path, and `Index.tsx` is the file
+that exports the page component. In the example below, `Link` comes from
+`@inertiajs/react` because it performs Inertia client-side visits (preserving
+page state and avoiding full reloads), whereas a plain `<a>` would do a full
+navigation.
+
+```tsx
+// src/pages/Projects/Index.tsx
+/**
+ * Projects Index Page
+ */
+
+import { Link } from '@inertiajs/react'
+import Layout from '~/components/Layout'
+import type { PageProps, Project } from '~/types'
+
+interface Props {
+  projects: Project[]
+}
+
+export default function ProjectsIndex({ projects }: PageProps<Props>) {
+  return (
+    <Layout>
+      <div className="flex justify-between items-center mb-6">
+        <h1 className="text-2xl font-bold text-gray-900">Projects</h1>
+        <Link
+          href="/projects/create"
+          className="bg-indigo-600 text-white px-4 py-2 rounded-md hover:bg-indigo-700"
+        >
+          New Project
+        </Link>
+      </div>
+      
+      <div className="bg-white rounded-lg shadow">
+        {projects.length === 0 ? (
+          <div className="p-6 text-center text-gray-500">
+            No projects yet.{' '}
+            <Link href="/projects/create" className="text-indigo-600 hover:underline">
+              Create your first project
+            </Link>
+          </div>
+        ) : (
+          <ul className="divide-y divide-gray-200">
+            {projects.map((project) => (
+              <li key={project.id}>
+                <Link
+                  href={`/projects/${project.id}`}
+                  className="block px-6 py-4 hover:bg-gray-50"
+                >
+                  <div className="flex justify-between items-start">
+                    <div>
+                      <h3 className="text-sm font-medium text-gray-900">
+                        {project.name}
+                      </h3>
+                      {project.description && (
+                        <p className="text-sm text-gray-500 mt-1">
+                          {project.description}
+                        </p>
+                      )}
+                    </div>
+                    <span className="text-sm text-gray-400">
+                      {new Date(project.createdAt).toLocaleDateString()}
+                    </span>
+                  </div>
+                </Link>
+              </li>
+            ))}
+          </ul>
+        )}
+      </div>
+    </Layout>
+  )
+}
+```
+
 ### Environment Variables
 
 Honertia reads these from `c.env` (Cloudflare Workers bindings):
@@ -254,155 +409,6 @@ Optional dev convenience: if you want to run the worker without building the
 client, you can keep a stub `dist/manifest.json` (ignored by git) and replace it
 once you run `vite build`.
 
-### Recommended File Structure
-
-Here's a minimal project layout that matches the Quick Start:
-
-```
-.
-├── src/
-│   ├── index.ts                 # Hono app setup (setupHonertia)
-│   ├── routes.ts                # effectRoutes / effectAuthRoutes
-│   ├── main.tsx                 # Inertia + React client entry
-│   ├── styles.css               # Tailwind CSS entry
-│   ├── actions/
-│   │   └── projects/
-│   │       └── list.ts           # listProjects action
-│   ├── pages/
-│   │   └── Projects/
-│   │       └── Index.tsx         # render('Projects/Index')
-│   ├── db.ts
-│   ├── lib/
-│   │   └── auth.ts
-│   └── types.ts
-├── dist/
-│   └── manifest.json            # generated by Vite build
-├── vite.config.ts
-├── wrangler.toml                # or wrangler.jsonc
-├── package.json
-└── tsconfig.json
-```
-
-### Example Action
-
-Here's the `listProjects` action referenced above:
-
-```typescript
-// src/actions/projects/list.ts
-import { Effect } from 'effect'
-import { eq } from 'drizzle-orm'
-import { DatabaseService, AuthUserService, render, type AuthUser } from 'honertia/effect'
-import { schema, type Database, type Project } from '../../db'
-
-interface ProjectsIndexProps {
-  projects: Project[]
-}
-
-const fetchProjects = (
-  db: Database,
-  user: AuthUser
-): Effect.Effect<ProjectsIndexProps, Error, never> =>
-  Effect.tryPromise({
-    try: async () => {
-      const projects = await db.query.projects.findMany({
-        where: eq(schema.projects.userId, user.user.id),
-        orderBy: (projects, { desc }) => [desc(projects.createdAt)],
-      })
-      return { projects }
-    },
-    catch: (error) => error instanceof Error ? error : new Error(String(error)),
-  })
-
-export const listProjects = Effect.gen(function* () {
-  const db = yield* DatabaseService
-  const user = yield* AuthUserService
-  const props = yield* fetchProjects(db as Database, user)
-  return yield* render('Projects/Index', props)
-})
-```
-
-The component name `Projects/Index` maps to a file on disk. A common
-Vite + React layout is:
-
-```
-src/pages/Projects/Index.tsx
-```
-
-That means the folders mirror the component path, and `Index.tsx` is the file
-that exports the page component. In the example below, `Link` comes from
-`@inertiajs/react` because it performs Inertia client-side visits (preserving
-page state and avoiding full reloads), whereas a plain `<a>` would do a full
-navigation.
-
-```tsx
-// src/pages/Projects/Index.tsx
-/**
- * Projects Index Page
- */
-
-import { Link } from '@inertiajs/react'
-import Layout from '~/components/Layout'
-import type { PageProps, Project } from '~/types'
-
-interface Props {
-  projects: Project[]
-}
-
-export default function ProjectsIndex({ projects }: PageProps<Props>) {
-  return (
-    <Layout>
-      <div className="flex justify-between items-center mb-6">
-        <h1 className="text-2xl font-bold text-gray-900">Projects</h1>
-        <Link
-          href="/projects/create"
-          className="bg-indigo-600 text-white px-4 py-2 rounded-md hover:bg-indigo-700"
-        >
-          New Project
-        </Link>
-      </div>
-      
-      <div className="bg-white rounded-lg shadow">
-        {projects.length === 0 ? (
-          <div className="p-6 text-center text-gray-500">
-            No projects yet.{' '}
-            <Link href="/projects/create" className="text-indigo-600 hover:underline">
-              Create your first project
-            </Link>
-          </div>
-        ) : (
-          <ul className="divide-y divide-gray-200">
-            {projects.map((project) => (
-              <li key={project.id}>
-                <Link
-                  href={`/projects/${project.id}`}
-                  className="block px-6 py-4 hover:bg-gray-50"
-                >
-                  <div className="flex justify-between items-start">
-                    <div>
-                      <h3 className="text-sm font-medium text-gray-900">
-                        {project.name}
-                      </h3>
-                      {project.description && (
-                        <p className="text-sm text-gray-500 mt-1">
-                          {project.description}
-                        </p>
-                      )}
-                    </div>
-                    <span className="text-sm text-gray-400">
-                      {new Date(project.createdAt).toLocaleDateString()}
-                    </span>
-                  </div>
-                </Link>
-              </li>
-            ))}
-          </ul>
-        )}
-      </div>
-    </Layout>
-  )
-}
-```
-
 ### Vite Helpers
 
 The `vite` helper provides dev/prod asset management:
@@ -427,47 +433,55 @@ vite.hmrHead()  // HMR preamble script tags for React Fast Refresh
 
 ### Effect-Based Handlers
 
-Route handlers are Effect computations that return `Response | Redirect`:
+Route handlers are Effect computations that return `Response | Redirect`. Actions are fully composable - you opt-in to features by yielding services:
 
 ```typescript
 import { Effect } from 'effect'
 import {
+  action,
+  authorize,
+  validateRequest,
   DatabaseService,
-  AuthUserService,
   render,
   redirect,
-} from 'honertia'
-
-// Simple page render
-export const showDashboard = Effect.gen(function* () {
-  const db = yield* DatabaseService
-  const user = yield* AuthUserService
+} from 'honertia/effect'
 
-  const projects = yield* Effect.tryPromise(() =>
-    db.query.projects.findMany({
-      where: eq(schema.projects.userId, user.user.id),
-      limit: 5,
-    })
-  )
+// Simple page render with auth
+export const showDashboard = action(
+  Effect.gen(function* () {
+    const auth = yield* authorize()
+    const db = yield* DatabaseService
 
-  return yield* render('Dashboard/Index', { projects })
-})
+    const projects = yield* Effect.tryPromise(() =>
+      db.query.projects.findMany({
+        where: eq(schema.projects.userId, auth.user.id),
+        limit: 5,
+      })
+    )
 
-// Form submission with redirect
-export const createProject = Effect.gen(function* () {
-  const db = yield* DatabaseService
-  const user = yield* AuthUserService
-  const input = yield* validateRequest(CreateProjectSchema)
+    return yield* render('Dashboard/Index', { projects })
+  })
+)
 
-  yield* Effect.tryPromise(() =>
-    db.insert(schema.projects).values({
-      ...input,
-      userId: user.user.id,
+// Form submission with permissions, validation, and redirect
+export const createProject = action(
+  Effect.gen(function* () {
+    const auth = yield* authorize((a) => a.user.role === 'admin')
+    const input = yield* validateRequest(CreateProjectSchema, {
+      errorComponent: 'Projects/Create',
     })
-  )
+    const db = yield* DatabaseService
 
-  return yield* redirect('/projects')
-})
+    yield* Effect.tryPromise(() =>
+      db.insert(schema.projects).values({
+        ...input,
+        userId: auth.user.id,
+      })
+    )
+
+    return yield* redirect('/projects')
+  })
+)
 ```
 
 ### Services
@@ -805,19 +819,37 @@ const user = yield* currentUser       // AuthUser | null
 ### Built-in Auth Routes
 
 ```typescript
-import { effectAuthRoutes } from 'honertia'
+import { effectAuthRoutes } from 'honertia/auth'
+import { loginUser, registerUser, logoutUser, verify2FA, forgotPassword } from './actions/auth'
 
 effectAuthRoutes(app, {
+  // Page routes
   loginPath: '/login',           // GET: show login page
   registerPath: '/register',     // GET: show register page
   logoutPath: '/logout',         // POST: logout and redirect
   apiPath: '/api/auth',          // Better-auth API handler
   logoutRedirect: '/login',
+  loginRedirect: '/',
   loginComponent: 'Auth/Login',
   registerComponent: 'Auth/Register',
+
+  // Form actions (automatically wrapped with RequireGuestLayer)
+  loginAction: loginUser,        // POST /login
+  registerAction: registerUser,  // POST /register
+  logoutAction: logoutUser,      // POST /logout (overrides default)
+
+  // Extended auth flows (all guest-only POST routes)
+  guestActions: {
+    '/login/2fa': verify2FA,
+    '/forgot-password': forgotPassword,
+  },
 })
 ```
 
+All `loginAction`, `registerAction`, and `guestActions` are automatically wrapped with
+`RequireGuestLayer`, so authenticated users will be redirected. The `logoutAction` is
+not wrapped (logout should work regardless of auth state).
+
 To enable CORS for the auth API handler (`/api/auth/*`), pass a `cors` config.
 By default, no CORS headers are added (recommended when your UI and API share the same origin).
 Use this when your frontend is on a different origin (local dev, separate domain, mobile app, etc.).
@@ -835,44 +867,326 @@ effectAuthRoutes(app, {
 This sets the appropriate `Access-Control-*` headers and handles `OPTIONS` preflight for the auth API routes.
 Always keep the `origin` list tight; avoid `'*'` for auth endpoints, especially with `credentials: true`.
 
-## Action Factories
+### Better-auth Form Actions
 
-For common patterns, use action factories:
+Honertia provides `betterAuthFormAction` to handle the common pattern of form-based
+authentication: validate input, call better-auth, map errors to field-level messages,
+and redirect on success. This bridges better-auth's JSON responses with Inertia's
+form handling conventions.
 
 ```typescript
-import { effectAction, dbAction, authAction } from 'honertia'
+// src/actions/auth/login.ts
+import { betterAuthFormAction } from 'honertia/auth'
+import { Schema as S } from 'effect'
+import { requiredString, email } from 'honertia'
+import type { Auth } from './lib/auth' // your better-auth instance type
 
-// effectAction: validation + custom handler
-export const updateSettings = effectAction(
-  SettingsSchema,
-  (input) => Effect.gen(function* () {
-    yield* saveSettings(input)
-    return yield* redirect('/settings')
-  }),
-  { errorComponent: 'Settings/Edit' }
+const LoginSchema = S.Struct({
+  email,
+  password: requiredString,
+})
+
+// Map better-auth error codes to user-friendly field errors
+const mapLoginError = (error: { code?: string; message?: string }) => {
+  switch (error.code) {
+    case 'INVALID_EMAIL_OR_PASSWORD':
+      return { email: 'Invalid email or password' }
+    case 'USER_NOT_FOUND':
+      return { email: 'No account found with this email' }
+    case 'INVALID_PASSWORD':
+      return { password: 'Incorrect password' }
+    default:
+      return { email: error.message ?? 'Login failed' }
+  }
+}
+
+export const loginUser = betterAuthFormAction({
+  schema: LoginSchema,
+  errorComponent: 'Auth/Login',
+  redirectTo: '/',
+  errorMapper: mapLoginError,
+  // `auth` is the better-auth instance from AuthService
+  // `input` is the validated form data
+  // `request` is the original Request (needed for session cookies)
+  call: (auth: Auth, input, request) =>
+    auth.api.signInEmail({
+      body: { email: input.email, password: input.password },
+      request,
+      returnHeaders: true,
+    }),
+})
+```
+
+```typescript
+// src/actions/auth/register.ts
+import { betterAuthFormAction } from 'honertia/auth'
+import { Schema as S } from 'effect'
+import { requiredString, email, password } from 'honertia'
+import type { Auth } from './lib/auth'
+
+const RegisterSchema = S.Struct({
+  name: requiredString,
+  email,
+  password: password({ min: 8, letters: true, numbers: true }),
+})
+
+const mapRegisterError = (error: { code?: string; message?: string }) => {
+  switch (error.code) {
+    case 'USER_ALREADY_EXISTS':
+      return { email: 'An account with this email already exists' }
+    case 'PASSWORD_TOO_SHORT':
+      return { password: 'Password must be at least 8 characters' }
+    default:
+      return { email: error.message ?? 'Registration failed' }
+  }
+}
+
+export const registerUser = betterAuthFormAction({
+  schema: RegisterSchema,
+  errorComponent: 'Auth/Register',
+  redirectTo: '/',
+  errorMapper: mapRegisterError,
+  call: (auth: Auth, input, request) =>
+    auth.api.signUpEmail({
+      body: { name: input.name, email: input.email, password: input.password },
+      request,
+      returnHeaders: true,
+    }),
+})
+```
+
+For logout, use the simpler `betterAuthLogoutAction`:
+
+```typescript
+// src/actions/auth/logout.ts
+import { betterAuthLogoutAction } from 'honertia/auth'
+
+export const logoutUser = betterAuthLogoutAction({
+  redirectTo: '/login',
+})
+```
+
+**How errors are handled:**
+
+1. **Schema validation fails** → Re-renders `errorComponent` with field errors from Effect Schema
+2. **better-auth returns an error** → Calls your `errorMapper`, then re-renders `errorComponent` with those errors
+3. **Success** → Sets session cookies from better-auth's response headers, then 303 redirects to `redirectTo`
+
+## Anatomy of an Action
+
+Actions in Honertia are fully composable Effect computations. Instead of using different action factories for different combinations of features, you opt-in to exactly what you need by yielding services and helpers inside your action.
+
+This design is inspired by Laravel's [laravel-actions](https://laravelactions.com/) package, where you opt-in to capabilities by adding methods to your action class. In Honertia, you opt-in by yielding services - the order of your `yield*` statements determines the execution order.
+
+### The `action` Wrapper
+
+The `action` function is a semantic wrapper that marks an Effect as an action:
+
+```typescript
+import { Effect } from 'effect'
+import { action } from 'honertia/effect'
+
+export const myAction = action(
+  Effect.gen(function* () {
+    // Your action logic here
+    return new Response('OK')
+  })
 )
+```
+
+It's intentionally minimal - all the power comes from what you yield inside.
+
+### Composable Helpers
+
+#### `authorize` - Authentication & Authorization
+
+Opt-in to authentication and authorization checks. Returns the authenticated user, fails with `UnauthorizedError` if no user is present, and fails with `ForbiddenError` if the check returns `false`.
+
+```typescript
+import { authorize } from 'honertia/effect'
+
+// Just require authentication (any logged-in user)
+const auth = yield* authorize()
+
+// Require a specific role
+const auth = yield* authorize((a) => a.user.role === 'admin')
+
+// Require resource ownership
+const auth = yield* authorize((a) => a.user.id === project.userId)
+```
+
+If the check function returns `false`, the action fails immediately with a `ForbiddenError`.
+
+#### `validateRequest` - Schema Validation
+
+Opt-in to request validation using Effect Schema:
+
+```typescript
+import { Schema as S } from 'effect'
+import { validateRequest, requiredString } from 'honertia/effect'
+
+const input = yield* validateRequest(
+  S.Struct({ name: requiredString, description: S.optional(S.String) }),
+  { errorComponent: 'Projects/Create' }
+)
+// input is fully typed: { name: string, description?: string }
+```
+
+On validation failure, re-renders `errorComponent` with field-level errors.
+
+#### `DatabaseService` - Database Access
+
+Opt-in to database access:
+
+```typescript
+import { DatabaseService } from 'honertia/effect'
+
+const db = yield* DatabaseService
+const projects = yield* Effect.tryPromise(() =>
+  db.query.projects.findMany()
+)
+```
+
+#### `render` / `redirect` - Responses
+
+Return responses from your action:
+
+```typescript
+import { render, redirect } from 'honertia/effect'
+
+// Render a page
+return yield* render('Projects/Index', { projects })
+
+// Redirect after mutation
+return yield* redirect('/projects')
+```
+
+### Building an Action
 
-// dbAction: validation + db + auth
-export const createProject = dbAction(
-  CreateProjectSchema,
-  (input, { db, user }) => Effect.gen(function* () {
+Here's how these composables work together:
+
+```typescript
+import { Effect, Schema as S } from 'effect'
+import {
+  action,
+  authorize,
+  validateRequest,
+  DatabaseService,
+  redirect,
+  requiredString,
+} from 'honertia/effect'
+
+const CreateProjectSchema = S.Struct({
+  name: requiredString,
+  description: S.optional(S.String),
+})
+
+export const createProject = action(
+  Effect.gen(function* () {
+    // 1. Authorization - fail fast if not allowed
+    const auth = yield* authorize((a) => a.user.role === 'author')
+
+    // 2. Validation - parse and validate request body
+    const input = yield* validateRequest(CreateProjectSchema, {
+      errorComponent: 'Projects/Create',
+    })
+
+    // 3. Database - perform the mutation
+    const db = yield* DatabaseService
     yield* Effect.tryPromise(() =>
-      db.insert(projects).values({ ...input, userId: user.user.id })
+      db.insert(projects).values({
+        ...input,
+        userId: auth.user.id,
+      })
     )
+
+    // 4. Response - redirect on success
     return yield* redirect('/projects')
-  }),
-  { errorComponent: 'Projects/Create' }
+  })
 )
+```
+
+### Execution Order Matters
+
+The order you yield services determines when they execute:
+
+```typescript
+// Authorization BEFORE validation (recommended for mutations)
+// Don't waste cycles validating if user can't perform the action
+const auth = yield* authorize((a) => a.user.role === 'admin')
+const input = yield* validateRequest(schema)
+
+// Validation BEFORE authorization (when you need input for auth check)
+const input = yield* validateRequest(schema)
+const auth = yield* authorize((a) => a.user.id === input.ownerId)
+```
 
-// authAction: just requires auth
-export const showDashboard = authAction((user) =>
+### Type Safety
+
+Effect tracks all service requirements at the type level. Your action's type signature shows exactly what it needs:
+
+```typescript
+// This action requires: RequestService, DatabaseService
+export const createProject: Effect.Effect<
+  Response | Redirect,
+  ValidationError | UnauthorizedError | ForbiddenError | Error,
+  RequestService | DatabaseService
+>
+```
+
+The compiler ensures all required services are provided when the action runs.
+Note: `authorize` uses an optional `AuthUserService`, so it won't appear in the required service list unless you `yield* AuthUserService` directly or provide `RequireAuthLayer` explicitly.
+
+### Minimal Actions
+
+Not every action needs all features. Use only what you need:
+
+```typescript
+// Public page - no auth, no validation
+export const showAbout = action(
+  Effect.gen(function* () {
+    return yield* render('About', {})
+  })
+)
+
+// Read-only authenticated page
+export const showDashboard = action(
+  Effect.gen(function* () {
+    const auth = yield* authorize()
+    const db = yield* DatabaseService
+    const stats = yield* fetchStats(db, auth)
+    return yield* render('Dashboard', { stats })
+  })
+)
+
+// API endpoint with just validation
+export const searchProjects = action(
   Effect.gen(function* () {
-    const data = yield* fetchDashboardData(user)
-    return yield* render('Dashboard', data)
+    const { query } = yield* validateRequest(S.Struct({ query: S.String }))
+    const db = yield* DatabaseService
+    const results = yield* search(db, query)
+    return yield* json({ results })
   })
 )
 ```
 
+### Helper Utilities
+
+#### `dbTransaction` - Database Transactions
+
+Run multiple database operations in a transaction with automatic rollback on failure:
+
+```typescript
+import { dbTransaction } from 'honertia/effect'
+
+yield* dbTransaction(async (tx) => {
+  await tx.insert(users).values({ name: 'Alice', email: 'alice@example.com' })
+  await tx.update(accounts).set({ balance: 100 }).where(eq(accounts.userId, id))
+  // If any operation fails, the entire transaction rolls back
+  return { success: true }
+})
+```
+
 ## React Integration
 
 ### Page Component Type
@@ -943,6 +1257,13 @@ On Cloudflare Workers, database connections and other I/O objects are isolated p
 
 If you're using PlanetScale with Hyperdrive, the "connection" you create per request is lightweight - it's just a client pointing at Hyperdrive's persistent connection pool.
 
+## Acknowledgements
+
+- Inertia.js by Jonathan Reinink and its contributors
+- Laravel by Taylor Otwell and the Laravel community
+
+🐐
+
 ## Contributing
 
 Contributions are welcome! Please feel free to submit a Pull Request.