@gnosticdev/hono-actions 1.0.0

package/README.md

@@ -0,0 +1,89 @@
+# @gnosticdev/define-hono-action
+
+Type-safe Hono action definitions with Valibot validation.
+
+## Installation
+
+```bash
+npm install @gnosticdev/define-hono-action
+```
+
+## Peer Dependencies
+
+This package requires the following peer dependencies:
+
+- `@hono/valibot-validator`: ^0.2.0
+- `hono`: ^4.0.0
+- `valibot`: ^0.30.0
+
+## Usage
+
+```typescript
+import { defineHonoAction, ActionError } from '@gnosticdev/define-hono-action'
+import * as v from 'valibot'
+
+// Define a simple action
+export const simpleAction = defineHonoAction({
+  path: '/simple',
+  handler: async (input, ctx) => {
+    return { message: 'Hello World!' }
+  }
+})
+
+// Define an action with validation
+export const validatedAction = defineHonoAction({
+  path: '/validated',
+  schema: v.object({
+    name: v.string(),
+    email: v.pipe(v.string(), v.email())
+  }),
+  handler: async (input, ctx) => {
+    // input is automatically typed based on schema
+    return {
+      message: `Hello ${input.name}!`,
+      email: input.email
+    }
+  }
+})
+
+// Use custom error handling
+export const errorAction = defineHonoAction({
+  path: '/error',
+  handler: async (input, ctx) => {
+    if (someCondition) {
+      throw new ActionError('Custom error message', 'EXTERNAL_API_ERROR')
+    }
+    return { success: true }
+  }
+})
+
+// Export all actions
+export const honoActions = {
+  simpleAction,
+  validatedAction,
+  errorAction
+}
+```
+
+## Types
+
+The package exports the following types:
+
+- `ActionErrorCode`: Union type of possible error codes
+- `ActionError`: Custom error class for action errors
+- `HonoActions`: Type for collections of actions
+
+## Error Codes
+
+Available error codes:
+
+- `INPUT_VALIDATION_ERROR`: Validation failed for input data
+- `EXTERNAL_API_ERROR`: Error calling external API
+- `INTERNAL_SERVER_ERROR`: Internal server error
+- `UNKNOWN_ERROR`: Unknown error occurred
+- `LOCATION_NOT_FOUND`: Location not found
+- `SESSION_NOT_FOUND`: Session not found
+
+## License
+
+MIT

package/dist/define-action.d.ts

@@ -0,0 +1,119 @@
+import type { Context } from 'hono';
+import * as v from 'valibot';
+export interface Bindings {
+}
+/**
+ * HonoEnv is passed to the Hono context to provide types on `ctx.env`.
+ *
+ * We are using `HonoEnv` to avoid confusion with the Cloudflare types on `Env` -> which cooresponds to `Bindings`
+ */
+export interface HonoEnv {
+    Bindings: Bindings;
+    Variables: Record<string, any>;
+}
+type HonoActionSchema = v.ObjectSchema<v.ObjectEntries, v.ErrorMessage<v.ObjectIssue> | undefined> | v.NeverSchema<undefined>;
+interface HonoActionContext<TEnv extends HonoEnv, TPath extends string, TSchema extends HonoActionSchema> extends Context<TEnv, TPath, {
+    input: v.InferInput<TSchema>;
+    output: v.InferOutput<TSchema>;
+    outputFormat: 'json';
+}> {
+    env: TEnv['Bindings'];
+}
+type HonoActionParams<TPath extends string, TSchema extends HonoActionSchema, TReturn, TEnv extends HonoEnv = HonoEnv> = {
+    path: TPath;
+    schema?: TSchema;
+    handler: (params: v.InferOutput<TSchema>, context: HonoActionContext<TEnv, TPath, TSchema>) => Promise<TReturn>;
+};
+/**
+ * Defines a type-safe Hono action using Valibot for input validation.
+ *
+ * @param path - The path of the action.
+ * @param schema - The object schema for Valibot validation.
+ * @default never
+ * @param handler - The handler function for the action.
+ * @returns A Hono app instance with the defined route
+ */
+export declare function defineHonoAction<TPath extends string, TSchema extends HonoActionSchema, TReturn, TEnv extends HonoEnv = HonoEnv>({ path, schema, handler }: HonoActionParams<TPath, TSchema, TReturn, TEnv>): import("hono/hono-base").HonoBase<TEnv, { [K in import("hono/types").MergePath<"/", TPath>]: {
+    $post: {
+        input: import("hono/types").AddParam<unknown extends ((undefined extends v.InferInput<TSchema | v.UnionSchema<[v.NeverSchema<undefined>, v.ObjectSchema<{}, undefined>], undefined>> ? true : false) extends true ? {
+            json?: (v.InferInput<TSchema | v.UnionSchema<[v.NeverSchema<undefined>, v.ObjectSchema<{}, undefined>], undefined>> extends infer T_1 ? T_1 extends v.InferInput<TSchema | v.UnionSchema<[v.NeverSchema<undefined>, v.ObjectSchema<{}, undefined>], undefined>> ? T_1 extends any ? T_1 : { [K2 in keyof T_1]?: any; } : never : never) | undefined;
+        } : {
+            json: v.InferInput<TSchema | v.UnionSchema<[v.NeverSchema<undefined>, v.ObjectSchema<{}, undefined>], undefined>> extends infer T_2 ? T_2 extends v.InferInput<TSchema | v.UnionSchema<[v.NeverSchema<undefined>, v.ObjectSchema<{}, undefined>], undefined>> ? T_2 extends any ? T_2 : { [K2_1 in keyof T_2]: any; } : never : never;
+        }) ? {} : (undefined extends v.InferInput<TSchema | v.UnionSchema<[v.NeverSchema<undefined>, v.ObjectSchema<{}, undefined>], undefined>> ? true : false) extends true ? {
+            json?: (v.InferInput<TSchema | v.UnionSchema<[v.NeverSchema<undefined>, v.ObjectSchema<{}, undefined>], undefined>> extends infer T_3 ? T_3 extends v.InferInput<TSchema | v.UnionSchema<[v.NeverSchema<undefined>, v.ObjectSchema<{}, undefined>], undefined>> ? T_3 extends any ? T_3 : { [K2_2 in keyof T_3]?: any; } : never : never) | undefined;
+        } : {
+            json: v.InferInput<TSchema | v.UnionSchema<[v.NeverSchema<undefined>, v.ObjectSchema<{}, undefined>], undefined>> extends infer T_4 ? T_4 extends v.InferInput<TSchema | v.UnionSchema<[v.NeverSchema<undefined>, v.ObjectSchema<{}, undefined>], undefined>> ? T_4 extends any ? T_4 : { [K2_3 in keyof T_4]: any; } : never : never;
+        }, import("hono/types").MergePath<"/", TPath>>;
+        output: unknown extends ({
+            data: Awaited<TReturn>;
+            error: null;
+        } extends import("hono/utils/types").JSONValue ? { [K_2 in keyof {
+            data: Awaited<TReturn>;
+            error: null;
+        } as ({
+            data: Awaited<TReturn>;
+            error: null;
+        }[K_2] extends infer T_5 ? T_5 extends {
+            data: Awaited<TReturn>;
+            error: null;
+        }[K_2] ? T_5 extends import("hono/utils/types").InvalidJSONValue ? true : false : never : never) extends true ? never : K_2]: boolean extends ({
+            data: Awaited<TReturn>;
+            error: null;
+        }[K_2] extends infer T_6 ? T_6 extends {
+            data: Awaited<TReturn>;
+            error: null;
+        }[K_2] ? T_6 extends import("hono/utils/types").InvalidJSONValue ? true : false : never : never) ? import("hono/utils/types").JSONParsed<{
+            data: Awaited<TReturn>;
+            error: null;
+        }[K_2]> | undefined : import("hono/utils/types").JSONParsed<{
+            data: Awaited<TReturn>;
+            error: null;
+        }[K_2]>; } : never) ? {} : {
+            data: Awaited<TReturn>;
+            error: null;
+        } extends import("hono/utils/types").JSONValue ? { [K_2 in keyof {
+            data: Awaited<TReturn>;
+            error: null;
+        } as ({
+            data: Awaited<TReturn>;
+            error: null;
+        }[K_2] extends infer T_5 ? T_5 extends {
+            data: Awaited<TReturn>;
+            error: null;
+        }[K_2] ? T_5 extends import("hono/utils/types").InvalidJSONValue ? true : false : never : never) extends true ? never : K_2]: boolean extends ({
+            data: Awaited<TReturn>;
+            error: null;
+        }[K_2] extends infer T_6 ? T_6 extends {
+            data: Awaited<TReturn>;
+            error: null;
+        }[K_2] ? T_6 extends import("hono/utils/types").InvalidJSONValue ? true : false : never : never) ? import("hono/utils/types").JSONParsed<{
+            data: Awaited<TReturn>;
+            error: null;
+        }[K_2]> | undefined : import("hono/utils/types").JSONParsed<{
+            data: Awaited<TReturn>;
+            error: null;
+        }[K_2]>; } : never;
+        outputFormat: "json";
+        status: 200;
+    } | {
+        input: import("hono/types").AddParam<unknown extends ((undefined extends v.InferInput<TSchema | v.UnionSchema<[v.NeverSchema<undefined>, v.ObjectSchema<{}, undefined>], undefined>> ? true : false) extends true ? {
+            json?: (v.InferInput<TSchema | v.UnionSchema<[v.NeverSchema<undefined>, v.ObjectSchema<{}, undefined>], undefined>> extends infer T_5 ? T_5 extends v.InferInput<TSchema | v.UnionSchema<[v.NeverSchema<undefined>, v.ObjectSchema<{}, undefined>], undefined>> ? T_5 extends any ? T_5 : { [K2_4 in keyof T_5]?: any; } : never : never) | undefined;
+        } : {
+            json: v.InferInput<TSchema | v.UnionSchema<[v.NeverSchema<undefined>, v.ObjectSchema<{}, undefined>], undefined>> extends infer T_6 ? T_6 extends v.InferInput<TSchema | v.UnionSchema<[v.NeverSchema<undefined>, v.ObjectSchema<{}, undefined>], undefined>> ? T_6 extends any ? T_6 : { [K2_5 in keyof T_6]: any; } : never : never;
+        }) ? {} : (undefined extends v.InferInput<TSchema | v.UnionSchema<[v.NeverSchema<undefined>, v.ObjectSchema<{}, undefined>], undefined>> ? true : false) extends true ? {
+            json?: (v.InferInput<TSchema | v.UnionSchema<[v.NeverSchema<undefined>, v.ObjectSchema<{}, undefined>], undefined>> extends infer T_7 ? T_7 extends v.InferInput<TSchema | v.UnionSchema<[v.NeverSchema<undefined>, v.ObjectSchema<{}, undefined>], undefined>> ? T_7 extends any ? T_7 : { [K2_6 in keyof T_7]?: any; } : never : never) | undefined;
+        } : {
+            json: v.InferInput<TSchema | v.UnionSchema<[v.NeverSchema<undefined>, v.ObjectSchema<{}, undefined>], undefined>> extends infer T_8 ? T_8 extends v.InferInput<TSchema | v.UnionSchema<[v.NeverSchema<undefined>, v.ObjectSchema<{}, undefined>], undefined>> ? T_8 extends any ? T_8 : { [K2_7 in keyof T_8]: any; } : never : never;
+        }, import("hono/types").MergePath<"/", TPath>>;
+        output: {
+            data: null;
+            error: {
+                message: string;
+                code: string;
+            };
+        };
+        outputFormat: "json";
+        status: 500;
+    };
+}; } extends infer T ? { [KeyType in keyof T]: T[KeyType]; } : never, "/">;
+export {};

package/dist/define-action.js

@@ -0,0 +1,57 @@
+import { vValidator } from '@hono/valibot-validator';
+import { createFactory } from 'hono/factory';
+import * as v from 'valibot';
+import { HonoActionError } from './error.js';
+/**
+ * Defines a type-safe Hono action using Valibot for input validation.
+ *
+ * @param path - The path of the action.
+ * @param schema - The object schema for Valibot validation.
+ * @default never
+ * @param handler - The handler function for the action.
+ * @returns A Hono app instance with the defined route
+ */
+export function defineHonoAction({ path, schema, handler }) {
+    const factory = createFactory();
+    const app = factory.createApp();
+    const route = app.post(path, vValidator('json', schema ?? v.union([v.never(), v.object({})]), async (result, c) => {
+        if (!result.success) {
+            console.error(result.issues);
+            return c.json({
+                data: null,
+                error: new HonoActionError({
+                    message: result.issues[0].message,
+                    code: 'INPUT_VALIDATION_ERROR',
+                    issue: result.issues[0]
+                })
+            }, 400);
+        }
+    }), async (c) => {
+        try {
+            const json = c.req.valid('json');
+            // context is validated after the middleware, but we only need the original definition to be passed back in to the handler here.
+            const result = await handler(json, c);
+            return c.json({
+                data: result,
+                error: null
+            }, 200);
+        }
+        catch (error) {
+            console.error(error);
+            let errorMessage = 'Internal server error';
+            let errorCode = 'INTERNAL_SERVER_ERROR';
+            if (error instanceof HonoActionError) {
+                errorMessage = error.message;
+                errorCode = error.code;
+            }
+            return c.json({
+                data: null,
+                error: {
+                    message: errorMessage,
+                    code: errorCode
+                }
+            }, 500);
+        }
+    });
+    return route;
+}

package/dist/error.d.ts

@@ -0,0 +1,14 @@
+import type * as v from 'valibot';
+/**
+ * Standard error codes for actions
+ */
+export type ActionErrorCode = 'INPUT_VALIDATION_ERROR' | 'EXTERNAL_API_ERROR' | 'INTERNAL_SERVER_ERROR' | 'UNKNOWN_ERROR' | 'LOCATION_NOT_FOUND' | 'SESSION_NOT_FOUND';
+export declare class HonoActionError<TSchema extends v.ObjectSchema<v.ObjectEntries, v.ErrorMessage<v.ObjectIssue> | undefined>, TMessage extends string, TCode extends ActionErrorCode, TIssue extends v.InferIssue<TSchema>> extends Error {
+    code: TCode;
+    issue?: TIssue;
+    constructor({ message, code, issue }: {
+        message: TMessage;
+        code: TCode;
+        issue?: TIssue;
+    });
+}

package/dist/error.js

@@ -0,0 +1,10 @@
+export class HonoActionError extends Error {
+    code;
+    issue;
+    constructor({ message, code, issue }) {
+        super(message);
+        this.name = 'HonoActionError';
+        this.code = code;
+        this.issue = issue;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+import type { Bindings, HonoEnv } from './define-action.js';
+import { defineHonoAction } from './define-action.js';
+import { HonoActionError } from './error.js';
+export type { Bindings, HonoEnv };
+export { defineHonoAction, HonoActionError };

package/dist/index.js

@@ -0,0 +1,3 @@
+import { defineHonoAction } from './define-action.js';
+import { HonoActionError } from './error.js';
+export { defineHonoAction, HonoActionError };

package/package.json

@@ -0,0 +1,62 @@
+{
+  "author": {
+    "name": "gnosticdev",
+    "url": "https://github.com/gnosticdev"
+  },
+  "dependencies": {
+    "@hono/valibot-validator": "0.5.3",
+    "astro-integration-kit": "^0.19.0",
+    "hono": "^4.9.4"
+  },
+  "description": "Type-safe Hono server actions with build-in validation",
+  "devDependencies": {
+    "@types/bun": "^1.2.20",
+    "typescript": "5.9.2"
+  },
+  "engineStrict": true,
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "exports": {
+    ".": {
+      "default": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./define-action": {
+      "default": "./dist/define-action.js",
+      "types": "./dist/define-action.d.ts"
+    },
+    "./error": {
+      "default": "./dist/error.js",
+      "types": "./dist/error.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "hono",
+    "actions",
+    "astro",
+    "validation",
+    "server actions"
+  ],
+  "license": "MIT",
+  "main": "dist/index.js",
+  "name": "@gnosticdev/hono-actions",
+  "packageManager": "bun@1.2.21",
+  "peerDependencies": {
+    "astro": "^5.13.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc",
+    "dev": "rm -rf dist && tsc --watch",
+    "prepublishOnly": "bun run build"
+  },
+  "type": "module",
+  "types": "dist/index.d.ts",
+  "version": "1.0.0"
+}