@gnosticdev/hono-actions 2.0.6 → 2.0.8

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;
 /**
@@ -76,14 +80,14 @@ type HonoActionParams<TSchema extends HonoActionSchema, TReturn, TEnv extends Ho
 declare function defineHonoAction<TEnv extends HonoEnv, TSchema extends HonoActionSchema, TReturn, TContext extends Context<TEnv, any, any>>({ schema, handler }: HonoActionParams<TSchema, TReturn, TEnv, TContext>): hono_hono_base.HonoBase<TEnv, {
     "/": {
         $post: {
-            input: unknown extends ((undefined extends z.input<TSchema | z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>> ? true : false) extends true ? {
-                json?: z.input<TSchema | z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>> | undefined;
+            input: unknown extends ((undefined extends z.input<TSchema> ? true : false) extends true ? {
+                json?: z.input<TSchema> | undefined;
             } : {
-                json: z.input<TSchema | z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>>;
-            }) ? {} : (undefined extends z.input<TSchema | z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>> ? true : false) extends true ? {
-                json?: z.input<TSchema | z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>> | undefined;
+                json: z.input<TSchema>;
+            }) ? {} : (undefined extends z.input<TSchema> ? true : false) extends true ? {
+                json?: z.input<TSchema> | undefined;
             } : {
-                json: z.input<TSchema | z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>>;
+                json: z.input<TSchema>;
             };
             output: {
                 data: null;
@@ -95,14 +99,14 @@ declare function defineHonoAction<TEnv extends HonoEnv, TSchema extends HonoActi
             outputFormat: "json";
             status: 500;
         } | {
-            input: unknown extends ((undefined extends z.input<TSchema | z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>> ? true : false) extends true ? {
-                json?: z.input<TSchema | z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>> | undefined;
+            input: unknown extends ((undefined extends z.input<TSchema> ? true : false) extends true ? {
+                json?: z.input<TSchema> | undefined;
             } : {
-                json: z.input<TSchema | z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>>;
-            }) ? {} : (undefined extends z.input<TSchema | z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>> ? true : false) extends true ? {
-                json?: z.input<TSchema | z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>> | undefined;
+                json: z.input<TSchema>;
+            }) ? {} : (undefined extends z.input<TSchema> ? true : false) extends true ? {
+                json?: z.input<TSchema> | undefined;
             } : {
-                json: z.input<TSchema | z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>>;
+                json: z.input<TSchema>;
             };
             output: unknown extends (Awaited<TReturn> | null extends bigint | readonly bigint[] ? never : { [K in keyof {
                 data: Awaited<TReturn>;
@@ -151,6 +155,6 @@ declare function defineHonoAction<TEnv extends HonoEnv, TSchema extends HonoActi
             status: 200;
         };
     };
-}, "/">;
+}, "/", "/">;
 
-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 {
@@ -24,23 +25,27 @@ function defineHonoAction({ schema, handler }) {
   const app = new Hono();
   const route = app.post(
     "/",
-    zValidator("json", schema ?? z.object({}), async (result, c) => {
-      if (!result.success) {
-        console.error(result.error.issues);
-        const firstIssue = result.error.issues[0];
-        return c.json(
-          {
-            data: null,
-            error: new HonoActionError({
-              message: firstIssue?.message || "Validation error",
-              code: "INPUT_VALIDATION_ERROR",
-              issue: firstIssue
-            })
-          },
-          400
-        );
+    zValidator(
+      "json",
+      schema ?? z.any(),
+      async (result, c) => {
+        if (!result.success) {
+          console.error(result.error.issues);
+          const firstIssue = result.error.issues[0];
+          return c.json(
+            {
+              data: null,
+              error: new HonoActionError({
+                message: firstIssue?.message || "Validation error",
+                code: "INPUT_VALIDATION_ERROR",
+                issue: firstIssue
+              })
+            },
+            400
+          );
+        }
       }
-    }),
+    ),
     async (c) => {
       try {
         const json = c.req.valid("json");
@@ -78,7 +83,5 @@ function defineHonoAction({ schema, handler }) {
   );
   return route;
 }
-export {
-  HonoActionError,
-  defineHonoAction
-};
+
+export { HonoActionError, defineHonoAction };

package/dist/index.d.ts

@@ -33,8 +33,11 @@ type IntegrationOptions = z.output<typeof optionsSchema>;
  * generates type-safe client code, and sets up API routes.
  *
  * Supprted Adapters:
- * - Cloudflare
- * - (more to come)
+ * - @astrojs/cloudflare
+ * - @astrojs/node
+ * - @astrojs/vercel
+ * - @astrojs/netlify
+ *
  *
  * @param options - Configuration options for the integration
  * @param options.basePath - Base path for API routes (default: '/api')

package/dist/index.js

@@ -1,20 +1,17 @@
+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) {
   const { basePath, relativeActionsPath, adapter } = opts;
-  let exportedApp = `export default app`;
+  let exportedApp = "export default app";
   if (adapter === "@astrojs/netlify") {
-    exportedApp = `export default handle(app)`;
+    exportedApp = "export default handle(app)";
   }
   return `import type { HonoEnv, MergeActionKeyIntoPath } from '@gnosticdev/hono-actions/actions'
 import { Hono } from 'hono'
@@ -106,27 +103,94 @@ export { handler as ALL }
 var generateHonoClient = (port) => `
 // Generated by Hono Actions Integration
 import type { HonoRouter } from './router.js'
-import { hc, parseResponse } from 'hono/client'
-import type { DetailedError } from 'hono/client'
+import { parseResponse, hc } from 'hono/client'
+import type { DetailedError, ClientRequestOptions } from 'hono/client'
 
 function getBaseUrl() {
-    // client side can just use the base path
+    // client side can just use the origin
     if (typeof window !== 'undefined') {
-        return '/'
+        return window.location.origin
     }
 
     // dev server (dev server) needs to know the port
     if (import.meta.env.DEV) {
-        return \`http://localhost:\${${port}}\`
+        return 'http://localhost:${port}'
     }
 
     // server side (production) needs full url
-    return import.meta.env.SITE ?? ''
+    if (import.meta.env.SITE) {
+        return import.meta.env.SITE
+    }
+
+    return '/'
+}
+
+export { parseResponse }
+export type { DetailedError, ClientRequestOptions, HonoRouter }
+export const honoClient = createHonoClient<HonoRouter>(getBaseUrl())
+export function createHonoClient<T extends HonoRouter = HonoRouter>(basePath: string, fetchOptions?: ClientRequestOptions) {
+    return hc<T>(basePath, fetchOptions)
+}
+`;
+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' {
+    /**
+     * Default hono client using the base url from the environment
+     * **Note** if running in production, the \`siteUrl\` option from the astro config will be used.
+     * If customization is needed, use the \`createHonoClient\` function instead.
+     */
+    export const honoClient: typeof import('./client').honoClient
+    /**
+     * Helper function to parse the response from the Hono client
+     */
+    export const parseResponse: typeof import('./client').parseResponse
+    /**
+     * Create a new hono client with custom base url + fetch options
+     */
+    export const createHonoClient: typeof import('./client').createHonoClient
+    export type DetailedError = import('./client').DetailedError
+    export type ClientRequestOptions = import('./client').ClientRequestOptions
+    /**
+     * The hono actions routes. for use in the hono client
+     */
+    export type HonoRouter = import('./client').HonoRouter
 }
-export { parseResponse, hc }
-export type { DetailedError }
-export const honoClient = hc<HonoRouter>(getBaseUrl())
 `;
+  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"];
@@ -237,6 +301,9 @@ ${ACTION_PATTERNS.map((p) => ` - ${p}`).join("\n")}`
             codeGenDir.pathname,
             "client.ts"
           );
+          if (!config.site) {
+            logger.warn("No site url found in astro config, add one if you want to use the hono client with SSR");
+          }
           const clientContent = generateHonoClient(config.server.port);
           await fs.writeFile(clientPathAbs, clientContent, "utf-8");
           addVirtualImports(params, {
@@ -261,26 +328,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 +339,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 +356,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

@@ -7,19 +7,18 @@
     "@hono/standard-validator": "^0.2.0",
     "@hono/zod-validator": "^0.2.2",
     "astro-integration-kit": "^0.19.0",
-    "hono": "^4.10.6",
     "tinyglobby": "^0.2.15"
   },
   "description": "Define server actions with built-in validation, error handling, and a pre-built hono client for calling the routes.",
   "devDependencies": {
-    "tsup": "^8.5.0",
-    "typescript": "catalog:",
-    "vitest": "catalog:",
     "@astrojs/cloudflare": "catalog:",
     "@astrojs/netlify": "catalog:",
     "@astrojs/node": "catalog:",
     "@astrojs/vercel": "catalog:",
-    "astro": "catalog:"
+    "@biomejs/biome": "catalog:",
+    "astro": "catalog:",
+    "tsup": "^8.5.0",
+    "typescript": "catalog:"
   },
   "exports": {
     ".": {
@@ -49,7 +48,8 @@
   "main": "./dist/index.js",
   "name": "@gnosticdev/hono-actions",
   "peerDependencies": {
-    "astro": "^5.13.0"
+    "astro": "^5.13.0",
+    "hono": "^4.10.6"
   },
   "publishConfig": {
     "access": "public"
@@ -61,5 +61,5 @@
   },
   "type": "module",
   "types": "./dist/index.d.ts",
-  "version": "2.0.6"
+  "version": "2.0.8"
 }