honertia 0.1.38 → 0.1.41

package/README.md

@@ -4,6 +4,14 @@ Inertia.js adapter for Hono with Effect.ts. Server-driven app with SPA behavior.
 
 ## CLI Commands
 
+`honertia` is shipped as a package binary. You can run commands with:
+
+```bash
+bunx honertia <command>
+# or
+npx honertia <command>
+```
+
 ### Generate Action
 
 ```bash
@@ -117,8 +125,8 @@ honertia db status              # Show migration status
 honertia db status --json       # JSON output
 honertia db migrate             # Run pending migrations
 honertia db migrate --preview   # Preview SQL without executing
-honertia db rollback            # Rollback last migration
-honertia db rollback --preview  # Preview rollback SQL
+honertia db rollback --preview  # Preview rollback SQL for latest applied migration
+# Non-preview rollback execution is manual (run preview SQL yourself)
 honertia db generate add_email  # Generate new migration
 ```
 
@@ -824,7 +832,7 @@ export const listProjects = action(
         })
       ),
       S.Array(ProjectSchema),
-      Duration.minutes(5)
+      { ttl: Duration.minutes(5) }
     )
 
     return yield* render('Projects/Index', { projects: userProjects })
@@ -979,6 +987,93 @@ export const destroyProject = action(
 )
 ```
 
+### Real-World Transaction (Order Checkout)
+
+Pass a validated/trusted transaction object as the second argument to
+`dbMutation`/`dbTransaction` when you want strict write scoping.
+Inside that callback, write methods only accept values that come from
+that scoped object.
+
+```typescript
+import { Effect, Schema as S } from 'effect'
+import {
+  action,
+  authorize,
+  validate,
+  validateRequest,
+  DatabaseService,
+  dbTransaction,
+  mergeMutationInput,
+  redirect,
+  requiredString,
+} from 'honertia/effect'
+import { eq } from 'drizzle-orm'
+import { orders, orderItems, inventory } from '~/db/schema'
+
+const CheckoutSchema = S.Struct({
+  productId: requiredString,
+  quantity: S.NumberFromString,
+})
+
+const CheckoutTransactionSchema = S.Struct({
+  createOrder: S.Struct({
+    userId: S.String,
+    status: S.Literal('pending'),
+  }),
+  createItem: S.Struct({
+    productId: S.String,
+    quantity: S.Number,
+    // Reserve transaction-derived fields you plan to fill later.
+    orderId: S.optional(S.String),
+  }),
+  updateInventory: S.Struct({
+    reserved: S.Number,
+  }),
+})
+
+export const checkout = action(
+  Effect.gen(function* () {
+    const auth = yield* authorize()
+    const input = yield* validateRequest(CheckoutSchema, {
+      errorComponent: 'Checkout/Show',
+    })
+    const db = yield* DatabaseService
+
+    const txInput = yield* validate(CheckoutTransactionSchema, {
+      createOrder: {
+        userId: auth.user.id,
+        status: 'pending',
+      },
+      createItem: {
+        productId: input.productId,
+        quantity: input.quantity,
+      },
+      updateInventory: {
+        reserved: input.quantity,
+      },
+    })
+    // For untyped/unknown payloads (e.g. external JSON), use validateUnknown(schema, raw)
+
+    const order = yield* dbTransaction(db, txInput, async (tx, scoped) => {
+      const [created] = await tx.insert(orders).values(scoped.createOrder).returning()
+
+      const itemInsert = mergeMutationInput(scoped.createItem, {
+        orderId: created.id,
+      })
+      await tx.insert(orderItems).values(itemInsert)
+
+      await tx.update(inventory)
+        .set(scoped.updateInventory)
+        .where(eq(inventory.productId, scoped.createItem.productId))
+
+      return created
+    })
+
+    return yield* redirect(`/orders/${order.id}`)
+  })
+)
+```
+
 ### API Endpoint (JSON Response)
 
 ```typescript
@@ -1676,7 +1771,7 @@ export const listProjects = action(
         catch: (error) => new Error(String(error)),
       }),
       S.Array(ProjectSchema),
-      Duration.minutes(5)
+      { ttl: Duration.minutes(5) }
     )
 
     return yield* render('Projects/Index', { projects: userProjects })
@@ -1688,12 +1783,19 @@ export const listProjects = action(
 
 | Function | Description |
 |----------|-------------|
-| `cache(key, compute, schema, ttl)` | Get from cache or compute and store |
+| `cache(key, compute, schema, options)` | Get from cache or compute and store |
 | `cacheGet(key, schema)` | Get value from cache (returns `Option`) |
-| `cacheSet(key, value, schema, ttl)` | Store value in cache |
+| `cacheSet(key, value, schema, options)` | Store value in cache |
 | `cacheInvalidate(key)` | Delete a single cache key |
 | `cacheInvalidatePrefix(prefix)` | Delete all keys with prefix |
 
+The `options` parameter is an object with the following properties:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `ttl` | `Duration.DurationInput` | Time-to-live for cached values (required) |
+| `swr` | `Duration.DurationInput` | Stale-while-revalidate window (optional) |
+
 ### Cache Invalidation
 
 Invalidate cache when data changes:
@@ -1783,7 +1885,7 @@ if (Option.isSome(cached)) {
 const user = yield* fetchUser(id)
 
 // Store in cache
-yield* cacheSet(`user:${id}`, user, UserSchema, Duration.hours(1))
+yield* cacheSet(`user:${id}`, user, UserSchema, { ttl: Duration.hours(1) })
 
 return user
 ```
@@ -1812,7 +1914,8 @@ const handler = action(
     yield* cache.delete('my-key')
 
     // List keys by prefix
-    const keys = yield* cache.list({ prefix: 'user:' })
+    const page = yield* cache.list({ prefix: 'user:' })
+    const keys = page.keys
   })
 )
 ```
@@ -1850,7 +1953,10 @@ const createRedisCacheClient = (redisUrl: string): CacheClient => {
       Effect.tryPromise({
         try: async () => {
           const keys = await client.keys(options?.prefix ? `${options.prefix}*` : '*')
-          return { keys: keys.map((name) => ({ name })) }
+          return {
+            keys: keys.map((name) => ({ name })),
+            list_complete: true,
+          }
         },
         catch: (e) => new CacheClientError('Redis keys failed', e),
       }),
@@ -1900,6 +2006,7 @@ const makeTestCache = (): Layer.Layer<CacheService> => {
         keys: [...store.keys()]
           .filter((k) => !options?.prefix || k.startsWith(options.prefix))
           .map((name) => ({ name })),
+        list_complete: true,
       })),
   }
 
@@ -1921,8 +2028,8 @@ describe('cache', () => {
         return { id: '1', name: 'Test' }
       })
 
-      const first = yield* cache('test:1', compute, TestSchema, Duration.hours(1))
-      const second = yield* cache('test:1', compute, TestSchema, Duration.hours(1))
+      const first = yield* cache('test:1', compute, TestSchema, { ttl: Duration.hours(1) })
+      const second = yield* cache('test:1', compute, TestSchema, { ttl: Duration.hours(1) })
 
       expect(first).toEqual(second)
       expect(callCount).toBe(1) // Only computed once
@@ -1937,9 +2044,9 @@ describe('cache', () => {
         return { id: '1', name: `Call ${callCount}` }
       })
 
-      yield* cache('test:1', compute, TestSchema, Duration.hours(1))
+      yield* cache('test:1', compute, TestSchema, { ttl: Duration.hours(1) })
       yield* cacheInvalidate('test:1')
-      yield* cache('test:1', compute, TestSchema, Duration.hours(1))
+      yield* cache('test:1', compute, TestSchema, { ttl: Duration.hours(1) })
 
       expect(callCount).toBe(2) // Computed twice
     }).pipe(Effect.provide(makeTestCache()), Effect.runPromise))
@@ -1979,6 +2086,421 @@ Recommended cache key patterns:
 `api:exchange:${currency}`
 ```
 
+### Stale-While-Revalidate (SWR)
+
+The cache supports the stale-while-revalidate pattern for improved latency and resilience. When enabled, stale values are returned immediately while a background refresh is triggered. In environments without `ExecutionContext`, stale entries are recomputed synchronously instead.
+
+```typescript
+import { Effect, Duration } from 'effect'
+import { cache, DatabaseService } from 'honertia/effect'
+
+const UserSchema = S.Struct({
+  id: S.String,
+  name: S.String,
+  email: S.String,
+})
+
+// Basic usage with TTL only
+const user = yield* cache(
+  `user:${id}`,
+  fetchUser(id),
+  UserSchema,
+  { ttl: Duration.hours(1) }
+)
+
+// With stale-while-revalidate
+const user = yield* cache(
+  `user:${id}`,
+  fetchUser(id),
+  UserSchema,
+  {
+    ttl: Duration.hours(1),      // Fresh for 1 hour
+    swr: Duration.minutes(5),    // Serve stale for 5 more minutes while refreshing
+  }
+)
+```
+
+**How SWR works:**
+
+| Cache State | Behavior |
+|-------------|----------|
+| Fresh (age < TTL) | Return cached value immediately |
+| Stale (TTL < age < TTL + SWR) | Return stale value immediately, trigger background refresh |
+| Expired (age > TTL + SWR) | Compute new value synchronously |
+| Cold (no cache) | Compute new value synchronously |
+
+**Benefits:**
+- **Faster responses**: Users always get an immediate response (stale or fresh)
+- **Reduced latency spikes**: No waiting for slow database queries during cache refresh
+- **Graceful degradation**: If the background refresh fails, stale data is still served
+
+**Real-world example:**
+
+```typescript
+import { Effect, Duration, Schema as S } from 'effect'
+import { action, authorize, cache, render, DatabaseService } from 'honertia/effect'
+import { eq } from 'drizzle-orm'
+import { projects } from '~/db/schema'
+
+const ProjectListSchema = S.Array(
+  S.Struct({
+    id: S.String,
+    name: S.String,
+    createdAt: S.Date,
+  })
+)
+
+export const indexProjects = action(
+  Effect.gen(function* () {
+    const auth = yield* authorize()
+    const db = yield* DatabaseService
+
+    // Cache project list with SWR
+    // - Fresh for 5 minutes
+    // - Serve stale for 1 additional minute while refreshing in background
+    const userProjects = yield* cache(
+      `projects:user:${auth.user.id}`,
+      Effect.tryPromise(() =>
+        db.query.projects.findMany({
+          where: eq(projects.userId, auth.user.id),
+          orderBy: (p, { desc }) => [desc(p.createdAt)],
+        })
+      ),
+      ProjectListSchema,
+      {
+        ttl: Duration.minutes(5),
+        swr: Duration.minutes(1),
+      }
+    )
+
+    return yield* render('Projects/Index', { projects: userProjects })
+  })
+)
+```
+
+### Background Tasks with ExecutionContextService
+
+The `ExecutionContextService` provides access to Cloudflare Workers' `waitUntil` API, allowing you to run tasks after the response is sent. This is automatically used by the cache's SWR feature for background refresh.
+
+```typescript
+import { Effect } from 'effect'
+import { action, ExecutionContextService, authorize, render } from 'honertia/effect'
+
+export const dashboard = action(
+  Effect.gen(function* () {
+    const auth = yield* authorize()
+    const ctx = yield* ExecutionContextService
+
+    // Send analytics in background - doesn't block response
+    yield* ctx.runInBackground(
+      Effect.tryPromise(() =>
+        fetch('https://analytics.example.com/events', {
+          method: 'POST',
+          body: JSON.stringify({
+            event: 'page_view',
+            userId: auth.user.id,
+            page: 'dashboard',
+            timestamp: Date.now(),
+          }),
+        })
+      )
+    )
+
+    return yield* render('Dashboard', { user: auth.user })
+  })
+)
+```
+
+**ExecutionContextService API:**
+
+| Method | Description |
+|--------|-------------|
+| `isAvailable` | `boolean` - Whether background execution is available |
+| `runInBackground(effect)` | Run an Effect after the response is sent |
+| `waitUntil(promise)` | Raw `waitUntil` for external promises |
+
+**Common use cases:**
+
+```typescript
+import { Effect } from 'effect'
+import {
+  ExecutionContextService,
+  authorize,
+  DatabaseService,
+  dbMutation,
+  asTrusted,
+  BindingsService,
+} from 'honertia/effect'
+
+// Audit logging
+const auditLog = (action: string, details: Record<string, unknown>) =>
+  Effect.gen(function* () {
+    const ctx = yield* ExecutionContextService
+    const user = yield* authorize()
+    const db = yield* DatabaseService
+
+    yield* ctx.runInBackground(
+      dbMutation(db, async (tx) => {
+        await tx.insert(auditLogs).values(asTrusted({
+          userId: user.user.id,
+          action,
+          details,
+          timestamp: new Date(),
+        }))
+      })
+    )
+  })
+
+// Webhook delivery with retries
+const deliverWebhook = (url: string, payload: unknown) =>
+  Effect.gen(function* () {
+    const ctx = yield* ExecutionContextService
+
+    yield* ctx.runInBackground(
+      Effect.tryPromise(() =>
+        fetch(url, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify(payload),
+        })
+      ).pipe(
+        Effect.retry({ times: 3 }),
+        Effect.catchAll((error) =>
+          Effect.logError('Webhook delivery failed', { url, error })
+        )
+      )
+    )
+  })
+
+// Conditional background work
+const maybeNotifySlack = (message: string) =>
+  Effect.gen(function* () {
+    const ctx = yield* ExecutionContextService
+    const bindings = yield* BindingsService
+
+    // Only run if Slack is configured and background is available
+    if (bindings.SLACK_WEBHOOK_URL && ctx.isAvailable) {
+      yield* ctx.runInBackground(
+        Effect.tryPromise(() =>
+          fetch(bindings.SLACK_WEBHOOK_URL, {
+            method: 'POST',
+            body: JSON.stringify({ text: message }),
+          })
+        )
+      )
+    }
+  })
+```
+
+**Important notes:**
+- Background tasks run after the response is sent to the user
+- Errors in background tasks are logged but don't crash the worker
+- In non-Worker environments (tests, local dev), `isAvailable` is `false` and stale entries are recomputed synchronously
+- Use `catchAll` to handle errors gracefully in background tasks
+
+### Cache Key Versioning
+
+Cache versioning ensures cache correctness when your data schema changes. Without versioning, schema changes can cause decode errors or serve stale data with the wrong shape.
+
+**The Problem:**
+
+```typescript
+// Version 1 of your schema
+const UserSchemaV1 = S.Struct({
+  id: S.String,
+  name: S.String,
+  email: S.String,
+})
+
+// You deploy with cached data...
+
+// Version 2 adds a required field
+const UserSchemaV2 = S.Struct({
+  id: S.String,
+  name: S.String,
+  email: S.String,
+  avatar: S.String,  // New required field!
+})
+
+// Cached V1 data fails to decode with V2 schema → Runtime error
+```
+
+**Solution 1: Auto Schema Versioning (Recommended)**
+
+Pass `version: true` to automatically version cache keys based on a hash of the schema structure. When you change the schema, the hash changes, and old cached data is automatically bypassed.
+
+```typescript
+import { Effect, Duration, Schema as S } from 'effect'
+import { cache, DatabaseService } from 'honertia/effect'
+
+const UserSchema = S.Struct({
+  id: S.String,
+  name: S.String,
+  email: S.String,
+})
+
+// Cache key becomes "a1b2c3:user:123" (hash:key)
+const user = yield* cache(
+  `user:${id}`,
+  fetchUser(id),
+  UserSchema,
+  { ttl: Duration.hours(1), version: true }
+)
+```
+
+**When to use `version: true`:**
+- You want automatic cache invalidation when schemas evolve
+- You're iterating quickly on data structures during development
+- You want zero-downtime deployments without manual cache clearing
+
+**When NOT to use `version: true`:**
+- You need cache hits to survive deployments (use explicit versions instead)
+- Schema changes are intentionally backward-compatible
+- You're caching data that doesn't depend on schema structure
+
+**Solution 2: Explicit Version Strings**
+
+For more control, pass an explicit version string. Bump it manually when your schema changes.
+
+```typescript
+// Cache key becomes "v2:user:123"
+const user = yield* cache(
+  `user:${id}`,
+  fetchUser(id),
+  UserSchema,
+  { ttl: Duration.hours(1), version: 'v2' }
+)
+```
+
+**When to use explicit versions:**
+- You want cache hits to survive deployments
+- You need predictable cache keys for debugging
+- You're coordinating schema changes across services
+
+**Full Example: User Profile with Versioned Cache**
+
+```typescript
+import { Effect, Duration, Schema as S } from 'effect'
+import {
+  action,
+  authorize,
+  cache,
+  cacheInvalidate,
+  asTrusted,
+  render,
+  redirect,
+  DatabaseService,
+  validateRequest,
+  dbMutation,
+} from 'honertia/effect'
+import { eq } from 'drizzle-orm'
+import { users } from '~/db/schema'
+
+// Schema definition - changing this auto-invalidates cache when version: true
+const UserProfileSchema = S.Struct({
+  id: S.String,
+  name: S.String,
+  email: S.String,
+  bio: S.NullOr(S.String),
+  avatarUrl: S.NullOr(S.String),
+})
+
+// GET /profile - cached with auto-versioning
+export const showProfile = action(
+  Effect.gen(function* () {
+    const auth = yield* authorize()
+    const db = yield* DatabaseService
+
+    const profile = yield* cache(
+      `user:profile:${auth.user.id}`,
+      Effect.tryPromise(() =>
+        db.query.users.findFirst({
+          where: eq(users.id, auth.user.id),
+          columns: { id: true, name: true, email: true, bio: true, avatarUrl: true },
+        })
+      ),
+      UserProfileSchema,
+      {
+        ttl: Duration.hours(1),
+        swr: Duration.minutes(5),
+        version: true,  // Auto-invalidates when UserProfileSchema changes
+      }
+    )
+
+    return yield* render('Profile/Show', { profile })
+  })
+)
+
+// PUT /profile - invalidate cache after update
+export const updateProfile = action(
+  Effect.gen(function* () {
+    const auth = yield* authorize()
+    const input = yield* validateRequest(UpdateProfileSchema, {
+      errorComponent: 'Profile/Edit',
+    })
+    const db = yield* DatabaseService
+
+    yield* dbMutation(db, async (db) => {
+      await db.update(users)
+        .set(asTrusted({ name: input.name, bio: input.bio }))
+        .where(eq(users.id, auth.user.id))
+    })
+
+    // Invalidate with same versioning strategy
+    yield* cacheInvalidate(`user:profile:${auth.user.id}`, {
+      schema: UserProfileSchema,
+      version: true,
+    })
+
+    return yield* redirect('/profile')
+  })
+)
+```
+
+**Versioning with `cacheGet` and `cacheInvalidate`:**
+
+When using manual cache operations, pass the same version option:
+
+```typescript
+import { cacheGet, cacheSet, cacheInvalidate } from 'honertia/effect'
+
+// Get with auto-versioning
+const cached = yield* cacheGet(`user:${id}`, UserSchema, { version: true })
+
+// Set with explicit version
+yield* cacheSet(`user:${id}`, user, UserSchema, {
+  ttl: Duration.hours(1),
+  version: 'v2',
+})
+
+// Invalidate with versioning - requires schema when using version
+yield* cacheInvalidate(`user:${id}`, { schema: UserSchema, version: true })
+
+// Simple invalidation (no versioning)
+yield* cacheInvalidate(`user:${id}`)
+```
+
+**How Schema Hashing Works:**
+
+The auto-versioning feature uses the djb2 hash algorithm on the serialized schema AST:
+
+1. Schema structure is serialized to a string representation
+2. A fast, deterministic hash is computed (djb2)
+3. The hash is prepended to the cache key
+
+This means:
+- Same schema definition → same hash → cache hits work
+- Changed schema structure → different hash → cache miss, fresh data computed
+- Adding/removing fields, changing types, or modifying constraints all change the hash
+
+**Cache Options Reference:**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `ttl` | `Duration.DurationInput` | Time-to-live for cached values (required) |
+| `swr` | `Duration.DurationInput` | Stale-while-revalidate window (optional) |
+| `version` | `string \| boolean` | `true` = auto schema hash, `string` = explicit prefix (optional) |
+
 ---
 
 ## Services Reference
@@ -1990,6 +2512,7 @@ Recommended cache key patterns:
 | `AuthUserService` | Current user session | `const user = yield* AuthUserService` |
 | `BindingsService` | Cloudflare bindings | `const { KV } = yield* BindingsService` |
 | `CacheService` | KV-backed cache client | `const cache = yield* CacheService` |
+| `ExecutionContextService` | Background task execution | `const ctx = yield* ExecutionContextService` |
 | `RequestService` | Request context | `const req = yield* RequestService` |
 
 ### Using BindingsService

package/dist/__tmp_db_safety_probe.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=__tmp_db_safety_probe.d.ts.map

package/dist/__tmp_db_safety_probe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"__tmp_db_safety_probe.d.ts","sourceRoot":"","sources":["../src/__tmp_db_safety_probe.ts"],"names":[],"mappings":""}

package/dist/__tmp_db_safety_probe.js

@@ -0,0 +1,13 @@
+import { asValidated } from './effect/validation.js';
+async function probe() {
+    const raw = { name: 'Pat', email: 'pat@example.com' };
+    // @ts-expect-error raw input should be rejected by SafeTx
+    await db.insert('users').values(raw);
+    const validated = asValidated(raw);
+    await db.insert('users').values(validated);
+    const merged = { ...validated, email: validated.email.toLowerCase() };
+    await db.insert('users').values(merged);
+    const role = (Math.random() > 0.5 ? 'admin' : 'member');
+    const mergedWithUnvalidated = { ...validated, role };
+    await dbWithRole.insert('users').values(mergedWithUnvalidated);
+}

package/dist/__tmp_scoped_astrusted_probe.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=__tmp_scoped_astrusted_probe.d.ts.map

package/dist/__tmp_scoped_astrusted_probe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"__tmp_scoped_astrusted_probe.d.ts","sourceRoot":"","sources":["../src/__tmp_scoped_astrusted_probe.ts"],"names":[],"mappings":""}

package/dist/__tmp_scoped_astrusted_probe.js

@@ -0,0 +1,10 @@
+import { Effect } from 'effect';
+import { dbMutation } from './effect/action.js';
+import { asTrusted } from './effect/validation.js';
+const txInput = asTrusted({ createUser: { name: 'pat' } });
+const program = dbMutation(db, txInput, async (tx, scoped) => {
+    await tx.insert('users').values(scoped.createUser);
+    // @ts-expect-error scoped mode rejects ad-hoc asTrusted payloads
+    await tx.insert('users').values(asTrusted({ name: 'other' }));
+});
+void Effect.runSync(program);

package/dist/__tmp_scoped_derived_probe.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=__tmp_scoped_derived_probe.d.ts.map

package/dist/__tmp_scoped_derived_probe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"__tmp_scoped_derived_probe.d.ts","sourceRoot":"","sources":["../src/__tmp_scoped_derived_probe.ts"],"names":[],"mappings":""}