@gnosticdev/hono-actions 2.0.6 → 2.0.7

package/README.md

@@ -239,6 +239,95 @@ const handleSubmit = async (formData: FormData) => {
 }
 ```
 
+## Advanced Usage
+
+### Using AsyncLocalStorage with Custom Hono Instances
+
+For advanced use cases involving request-scoped data and custom Hono instances, see [docs/async_hooks.md](./docs/async_hooks.md).
+
+## Augmenting Type Interfaces
+
+When using this library, you may need to augment the type interfaces to add custom types for your environment bindings, Hono context variables, or Astro locals. This is especially important when using the Cloudflare adapter.
+
+### Cloudflare Runtime Types
+
+When using the `@astrojs/cloudflare` adapter, the library automatically exports Cloudflare runtime types. However, it assumes that Cloudflare types have been generated by Wrangler via the `wrangler types` command, which creates an `Env` interface that is automatically added to `HonoEnv['Bindings']`.
+
+To generate Cloudflare types:
+
+```bash
+bunx --bun wrangler types
+```
+
+This creates a `worker-configuration.d.ts` file (or similar) containing the `Env` interface based on your `wrangler.jsonc` configuration.
+
+### Extending HonoEnv Types
+
+To add additional types to your Hono environment, create a type declaration file (e.g., `src/env.d.ts`) and augment the module:
+
+```typescript
+// src/env.d.ts
+import '@gnosticdev/hono-actions/actions'
+
+// Augmenting the actions types for use with cloudflare adapter
+declare module '@gnosticdev/hono-actions/actions' {
+    // 1) Extend existing Bindings, with Env from worker-configuration.d.ts
+    interface Bindings extends Env {
+        anotherVar: string
+    }
+
+    // 2) Add Variables available on `ctx.var.db` or `ctx.var.db.get('randomKey')` in hono actions
+    interface HonoEnv {
+        Variables: {
+            db: Map<string, any>
+        }
+        Bindings: Bindings
+    }
+}
+
+// Extend Astro Locals if you want to use in middleware
+// need to add this to global scope bc we have an import in the file
+declare global {
+    type Runtime = import('@astrojs/cloudflare').Runtime<Env>
+    declare namespace App {
+        interface Locals extends Runtime {
+            db: Map<string, any> // this will now be available on both `ctx.var.db` and `Astro.locals.db`
+        }
+    }
+}
+
+
+```
+
+Now in your actions, you'll have full type safety:
+
+```typescript
+// src/hono.ts
+import { defineHonoAction, type HonoEnv } from '@gnosticdev/hono-actions/actions'
+
+export const myAction = defineHonoAction({
+  handler: async (input, ctx) => {
+    // ctx.env has type: Bindings (includes Env + your custom bindings)
+    const kv = ctx.env.CUSTOM_KV
+
+    // ctx.var has type: HonoEnv['Variables']
+    const user = kv.get('user')
+
+    return { success: true }
+  }
+})
+```
+
+And in your Astro pages:
+
+```typescript
+// src/pages/index.astro
+---
+// Astro.locals has type: App.Locals
+const user = Astro.locals.user
+---
+```
+
 ## Package Structure
 
 This package provides these entry points:

package/dist/actions.d.ts

@@ -20,6 +20,10 @@ declare class HonoActionError<TMessage extends string, TCode extends ActionError
 
 interface Bindings {
 }
+interface Variables {
+    /** Variables */
+    [key: string]: unknown;
+}
 /**
  * HonoEnv is passed to the Hono context to provide types on `ctx.env`.
  *
@@ -36,7 +40,7 @@ interface Bindings {
  */
 interface HonoEnv {
     Bindings: Bindings;
-    Variables: Record<string, unknown>;
+    Variables: Variables;
 }
 type HonoActionSchema = z.ZodTypeAny;
 /**
@@ -153,4 +157,4 @@ declare function defineHonoAction<TEnv extends HonoEnv, TSchema extends HonoActi
     };
 }, "/">;
 
-export { type Bindings, HonoActionError, type HonoEnv, type MergeActionKeyIntoPath, defineHonoAction };
+export { type Bindings, HonoActionError, type HonoEnv, type MergeActionKeyIntoPath, type Variables, defineHonoAction };

package/dist/actions.js

@@ -1,7 +1,8 @@
+import { zValidator } from '@hono/zod-validator';
+import { z } from 'astro/zod';
+import { Hono } from 'hono';
+
 // src/actions.ts
-import { zValidator } from "@hono/zod-validator";
-import { z } from "astro/zod";
-import { Hono } from "hono";
 
 // src/error.ts
 var HonoActionError = class extends Error {
@@ -78,7 +79,5 @@ function defineHonoAction({ schema, handler }) {
   );
   return route;
 }
-export {
-  HonoActionError,
-  defineHonoAction
-};
+
+export { HonoActionError, defineHonoAction };

package/dist/index.js

@@ -1,13 +1,10 @@
+import { defineIntegration, createResolver, addVirtualImports } from 'astro-integration-kit';
+import { z } from 'astro/zod';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { glob } from 'tinyglobby';
+
 // src/integration.ts
-import {
-  addVirtualImports,
-  createResolver,
-  defineIntegration
-} from "astro-integration-kit";
-import { z } from "astro/zod";
-import fs from "node:fs/promises";
-import path from "node:path";
-import { glob } from "tinyglobby";
 
 // src/integration-files.ts
 function generateRouter(opts) {
@@ -127,6 +124,48 @@ export { parseResponse, hc }
 export type { DetailedError }
 export const honoClient = hc<HonoRouter>(getBaseUrl())
 `;
+var generateIntegrationTypes = (adapter) => {
+  let actionTypes = `
+    // Generated by Hono Actions Integration
+    declare module '@gnosticdev/hono-actions/actions' {
+        interface Bindings { [key: string]: unknown }
+        interface Variables { [key: string]: unknown }
+        interface HonoEnv { Bindings: Bindings, Variables: Variables }
+    }
+    export {}
+    `;
+  let clientTypes = `
+// Generated by Hono Actions Integration
+declare module '@gnosticdev/hono-actions/client' {
+    export const honoClient: typeof import('./client').honoClient
+    export const parseResponse: typeof import('./client').parseResponse
+    export type DetailedError = import('./client').DetailedError
+}
+`;
+  switch (adapter) {
+    // cloudflare uses Bindings and Variables passed in from the route handler
+    case "@astrojs/cloudflare":
+      actionTypes = `
+// Generated by Hono Actions Integration
+// keeping separate from the main types.d.ts to avoid clobbering package exports
+declare module '@gnosticdev/hono-actions/actions' {
+    interface Bindings extends Env { ASTRO_LOCALS: App.Locals }
+    interface Variables { [key: string]: unknown }
+    interface HonoEnv { Bindings: Bindings, Variables: Variables }
+}
+export {}
+`;
+      clientTypes += `
+type Runtime = import('@astrojs/cloudflare').Runtime<Env>
+
+declare namespace App {
+    interface Locals extends Runtime {}
+}
+`;
+      break;
+  }
+  return { actionTypes, clientTypes };
+};
 
 // src/lib/utils.ts
 var reservedRoutes = ["_astro", "_actions", "_server_islands"];
@@ -261,26 +300,6 @@ ${ACTION_PATTERNS.map((p) => ` - ${p}`).join("\n")}`
           config,
           logger
         }) => {
-          injectTypes({
-            filename: "actions.d.ts",
-            content: `
-// Generated by Hono Actions Integration
-// keeping separate from the main types.d.ts to avoid clobbering package exports
-declare module '@gnosticdev/hono-actions/actions' {
-    interface Bindings extends Env { ASTRO_LOCALS: App.Locals }
-    interface HonoEnv { Bindings: Bindings }
-}
-export {}
-`
-          });
-          let clientTypes = `
-// Generated by Hono Actions Integration
-declare module '@gnosticdev/hono-actions/client' {
-    export const honoClient: typeof import('./client').honoClient
-    export const parseResponse: typeof import('./client').parseResponse
-    export type DetailedError = import('./client').DetailedError
-}
-`;
           const adapter = config.adapter?.name;
           if (!adapter) {
             logger.warn("No adapter found...");
@@ -292,14 +311,11 @@ declare module '@gnosticdev/hono-actions/client' {
             );
             return;
           }
-          if (adapter === "@astrojs/cloudflare") {
-            clientTypes += `
-    type Runtime = import('@astrojs/cloudflare').Runtime<Env>
-        declare namespace App {
-            interface Locals extends Runtime {}
-        }
-    `;
-          }
+          const { actionTypes, clientTypes } = generateIntegrationTypes(adapter);
+          injectTypes({
+            filename: "actions.d.ts",
+            content: actionTypes
+          });
           injectTypes({
             filename: "types.d.ts",
             content: clientTypes
@@ -312,6 +328,5 @@ declare module '@gnosticdev/hono-actions/client' {
 
 // src/index.ts
 var src_default = integration_default;
-export {
-  src_default as default
-};
+
+export { src_default as default };

package/package.json

@@ -19,7 +19,8 @@
     "@astrojs/netlify": "catalog:",
     "@astrojs/node": "catalog:",
     "@astrojs/vercel": "catalog:",
-    "astro": "catalog:"
+    "astro": "catalog:",
+    "@biomejs/biome": "catalog:"
   },
   "exports": {
     ".": {
@@ -61,5 +62,5 @@
   },
   "type": "module",
   "types": "./dist/index.d.ts",
-  "version": "2.0.6"
+  "version": "2.0.7"
 }