miqro.js 0.1.2 → 0.1.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 qnton
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,7 +1,17 @@
 # Miqro
 
 A minimal, high-performance microservice engine built on [Bun](https://bun.sh/) and [Hono](https://hono.dev/).
-Designed to process webhooks and run scheduled cron jobs utilizing file-based workflow configurations.
+Designed to process webhooks and run scheduled cron jobs utilizing file-based workflow configurations with first-class TypeScript support and Zod validation.
+
+## Key Features
+
+- **High Performance:** Powered by Bun and Hono.
+- **Developer Friendly:** Built-in CLI for scaffolding and development.
+- **Zod Validation:** Automatic request validation for your webhooks.
+- **Security First:** Simple API Key and Bearer Token authentication.
+- **Scheduled Jobs:** Native support for cron-based workflows.
+- **Middleware Support:** Easily extend the engine with Hono middleware.
+- **Single File Builds:** Bundle your entire project into a single executable artifact.
 
 ## Quick Start
 
@@ -11,7 +21,7 @@ bunx miqro.js init
 bun add miqro.js
 ```
 
-This creates a `miqro.config.ts`, a `workflows/` directory, a basic `package.json`, and a `tsconfig.json`.
+This creates a `miqro.config.ts`, a `workflows/` directory, and configures your environment.
 
 Start the development server with hot-reloading:
 ```bash
@@ -20,46 +30,57 @@ bun run dev
 
 ## Commands
 
-- `miqro.js init` (or `miqro init`): Scaffolds `miqro.config.ts` and a `workflows/` directory.
-- `miqro.js dev`: Starts the engine in development mode with hot-reloading (`bun --watch`).
-- `miqro.js start`: Starts the engine dynamically for production.
-- `miqro.js build`: Compiles your project and workflows into a single standalone file at `./dist/index.js`.
+- `miqro init`: Scaffolds a new project.
+- `miqro dev`: Starts the engine in development mode with hot-reloading.
+- `miqro start`: Starts the engine for production.
+- `miqro build`: Compiles your project into a single standalone file at `./dist/index.js`.
 
 ## Configuration
 
-The engine is configured via `miqro.config.ts` in your project root:
+The engine is configured via `miqro.config.ts`:
 
 ```typescript
-// miqro.config.ts
 import type { MiqroConfig } from 'miqro.js';
 
 export default {
   port: 3000,
-  workflowsDir: './workflows', // Directory containing workflows
+  workflowsDir: './workflows',
+  middleware: [
+    async (c, next) => {
+      console.log(`[${c.req.method}] ${c.req.url}`);
+      await next();
+    }
+  ]
 } satisfies MiqroConfig;
 ```
 
 ## Workflows
 
-Workflows belong in the directory specified by `workflowsDir`. 
-Miqro automatically discovers `.ts` or `.js` module exports and registers them.
+### Webhook Workflow with Validation
 
-### Webhook Workflow
-
-Webhooks respond to `POST /{id}`. Authentication supports `none`, `apiKey`, or `bearer`.
+Webhooks respond to `POST /{id}`. Use **Zod** to validate your payloads and get full type safety in your execution logic.
 
 ```typescript
-// workflows/example-webhook.ts
-import type { Workflow } from 'miqro.js';
+import { z } from "zod";
+import type { Workflow } from "miqro.js";
 
 export default {
   config: {
     id: 'process-payment',
     name: 'Payment Webhook',
-    auth: { type: 'apiKey', key: process.env.API_KEY || 'secret' }
+    auth: { type: 'apiKey', key: process.env.API_KEY || 'secret' },
+    schema: z.object({
+      amount: z.number().positive(),
+      currency: z.string().length(3),
+      customerEmail: z.string().email(),
+    })
   },
-  execute: async (payload: any) => {
-    console.log(`Received payload!`, payload);
+  execute: async (payload, context) => {
+    // payload is automatically typed based on the schema!
+    console.log(`Processing ${payload.amount} ${payload.currency} for ${payload.customerEmail}`);
+    
+    // access request metadata via context
+    console.log(`User Agent: ${context.headers['user-agent']}`);
   }
 } satisfies Workflow;
 ```
@@ -69,18 +90,27 @@ export default {
 If a workflow config provides a `schedule` property (a valid Cron string), it will be executed automatically.
 
 ```typescript
-// workflows/example-cron.ts
 import type { Workflow } from 'miqro.js';
 
 export default {
   config: {
-    id: 'hourly-sync',
-    name: 'Sync Database',
-    auth: { type: 'none' }, // Auth is required but ignored for cron tasks
-    schedule: '0 * * * *'   // Runs every hour
+    id: 'daily-cleanup',
+    name: 'Database Cleanup',
+    auth: { type: 'none' }, 
+    schedule: '0 0 * * *' // Runs every night at midnight
   },
-  execute: async () => {
-    console.log(`Running background sync...`);
+  execute: async (payload, context) => {
+    console.log(`Running scheduled cleanup for ${context.name}...`);
   }
 } satisfies Workflow;
-```
+```
+
+## Execution Context
+
+The `execute` function receives a `MiqroContext` object providing access to:
+
+- `workflowId`: The ID of the current workflow.
+- `name`: The display name of the workflow.
+- `params`: Route parameters.
+- `query`: URL query parameters.
+- `headers`: HTTP Request headers.

package/dist/cli.js

@@ -2939,7 +2939,14 @@ async function loadWorkflows(workflowsDir) {
             import_node_cron.default.schedule(workflow.config.schedule, () => {
               console.log(`[Cron] Executing scheduled workflow: ${workflow.config.id}`);
               const payload = { source: "cron", timestamp: Date.now() };
-              workflow.execute(payload);
+              const context = {
+                workflowId: workflow.config.id,
+                name: workflow.config.name,
+                params: {},
+                query: {},
+                headers: {}
+              };
+              workflow.execute(payload, context);
             });
             console.log(`[Miqro] Scheduled workflow '${workflow.config.id}' with cron: '${workflow.config.schedule}'`);
           }
@@ -2961,7 +2968,14 @@ async function startMiqroCore(config, staticWorkflows) {
         import_node_cron.default.schedule(workflow.config.schedule, () => {
           console.log(`[Cron] Executing scheduled workflow: ${workflow.config.id}`);
           const payload = { source: "cron", timestamp: Date.now() };
-          workflow.execute(payload);
+          const context = {
+            workflowId: workflow.config.id,
+            name: workflow.config.name,
+            params: {},
+            query: {},
+            headers: {}
+          };
+          workflow.execute(payload, context);
         });
         console.log(`[Miqro] Scheduled workflow '${workflow.config.id}' with cron: '${workflow.config.schedule}'`);
       }
@@ -2969,6 +2983,11 @@ async function startMiqroCore(config, staticWorkflows) {
   }
   const app = new Hono2;
   app.use("*", logger());
+  if (config.middleware) {
+    for (const mw of config.middleware) {
+      app.use("*", mw);
+    }
+  }
   app.get("/health", (c) => c.json({
     status: "ok",
     uptime: process.uptime(),
@@ -2976,34 +2995,45 @@ async function startMiqroCore(config, staticWorkflows) {
   }));
   app.post("/:workflowId", async (c) => {
     try {
-      const payload = await c.req.json();
       const workflowId = c.req.param("workflowId");
-      if (workflowId) {
-        const workflow = workflows[workflowId];
-        if (!workflow) {
-          return c.json({ error: `Workflow '${workflowId}' not found` }, 404);
+      const workflow = workflows[workflowId];
+      if (!workflow) {
+        return c.json({ error: `Workflow '${workflowId}' not found` }, 404);
+      }
+      const authHeader = c.req.header("Authorization");
+      const { auth } = workflow.config;
+      if (auth.type === "apiKey") {
+        const apiKey = c.req.header("x-api-key") || c.req.query("apiKey");
+        if (apiKey !== auth.key) {
+          return c.json({ error: "Unauthorized: Invalid API Key" }, 401);
         }
-        const authHeader = c.req.header("Authorization");
-        const { auth } = workflow.config;
-        if (auth.type === "apiKey") {
-          const apiKey = c.req.header("x-api-key") || c.req.query("apiKey");
-          if (apiKey !== auth.key) {
-            return c.json({ error: "Unauthorized: Invalid API Key" }, 401);
-          }
-        } else if (auth.type === "bearer") {
-          if (!authHeader || !authHeader.startsWith(`Bearer ${auth.token}`)) {
-            return c.json({ error: "Unauthorized: Invalid Bearer token" }, 401);
-          }
+      } else if (auth.type === "bearer") {
+        if (!authHeader || !authHeader.startsWith(`Bearer ${auth.token}`)) {
+          return c.json({ error: "Unauthorized: Invalid Bearer token" }, 401);
         }
-        await workflow.execute(payload);
-        return c.json({
-          status: "success",
-          message: `Workflow '${workflowId}' executed`
-        });
       }
+      let payload = await c.req.json();
+      if (workflow.config.schema) {
+        const result = workflow.config.schema.safeParse(payload);
+        if (!result.success) {
+          return c.json({
+            error: "Validation Failed",
+            details: result.error.format()
+          }, 400);
+        }
+        payload = result.data;
+      }
+      const context = {
+        workflowId: workflow.config.id,
+        name: workflow.config.name,
+        params: c.req.param(),
+        query: c.req.query(),
+        headers: c.req.header()
+      };
+      await workflow.execute(payload, context);
       return c.json({
         status: "success",
-        message: "Payload received but no workflow triggered"
+        message: `Workflow '${workflowId}' executed`
       });
     } catch (error) {
       console.error("[Miqro Webhook Error]", error);
@@ -3061,18 +3091,25 @@ export default {
     }
     const sampleWorkflowPath = resolve(workflowsPath, "sample.ts");
     if (!existsSync(sampleWorkflowPath)) {
-      const sampleWorkflow = `import type { Workflow } from "miqro.js";
+      const sampleWorkflow = `import { z } from "zod";
+import type { Workflow } from "miqro.js";
+
+const schema = z.object({
+  message: z.string().min(1),
+});
 
 export default {
   config: {
     id: "hello-world",
     name: "Hello World Workflow",
     auth: { type: "none" },
+    schema,
   },
-  execute: async (payload: any) => {
-    console.log("Hello from Miqro!", payload);
+  execute: async (payload, context) => {
+    console.log("Hello from Miqro!", payload.message);
+    console.log("Context workflow ID:", context.workflowId);
   },
-} satisfies Workflow;
+} satisfies Workflow<z.infer<typeof schema>>;
 `;
       await writeFile(sampleWorkflowPath, sampleWorkflow);
     }
@@ -3081,6 +3118,13 @@ export default {
       const pkgContent = {
         name: "miqro-project",
         type: "module",
+        dependencies: {
+          "miqro.js": "^0.1.3",
+          zod: "^3.24.1"
+        },
+        devDependencies: {
+          "@types/bun": "latest"
+        },
         scripts: {
           dev: "miqro dev",
           start: "miqro start",
@@ -3102,7 +3146,8 @@ export default {
           noEmit: true,
           strict: true,
           skipLibCheck: true,
-          allowSyntheticDefaultImports: true
+          allowSyntheticDefaultImports: true,
+          types: ["bun-types"]
         }
       };
       await writeFile(tsconfigPath, JSON.stringify(tsconfigContent, null, 2));
@@ -3110,7 +3155,7 @@ export default {
     console.log("\u2705 Created miqro.config.ts and workflows directory with a sample.");
     console.log(`
 \uD83D\uDC49 Next steps:`);
-    console.log("  1. Run: bun add miqro.js");
+    console.log("  1. Run: bun install");
     console.log("  2. Run: bun run dev");
     process.exit(0);
   }
@@ -3134,7 +3179,8 @@ export default {
     console.log("\uD83D\uDD04 Starting Miqro in DEV mode (hot-reloading enabled)...");
     Bun.spawn(["bun", "--watch", Bun.argv[1], "start"], {
       stdout: "inherit",
-      stderr: "inherit"
+      stderr: "inherit",
+      cwd: process.cwd()
     });
   } else if (command === "start") {
     console.log("\uD83D\uDE80 Starting Miqro...");

package/dist/index.d.ts

@@ -14,4 +14,4 @@ export declare function startMiqro(config: MiqroConfig): Promise<{
     port: string | number;
     fetch: (request: Request, Env?: unknown, executionCtx?: import("hono").ExecutionContext) => Response | Promise<Response>;
 }>;
-export type { AuthConfig, Workflow, WorkflowConfig } from "./types";
+export type { AuthConfig, MiqroConfig, Workflow, WorkflowConfig, } from "./types";

package/dist/index.js

@@ -2938,7 +2938,14 @@ async function loadWorkflows(workflowsDir) {
             import_node_cron.default.schedule(workflow.config.schedule, () => {
               console.log(`[Cron] Executing scheduled workflow: ${workflow.config.id}`);
               const payload = { source: "cron", timestamp: Date.now() };
-              workflow.execute(payload);
+              const context = {
+                workflowId: workflow.config.id,
+                name: workflow.config.name,
+                params: {},
+                query: {},
+                headers: {}
+              };
+              workflow.execute(payload, context);
             });
             console.log(`[Miqro] Scheduled workflow '${workflow.config.id}' with cron: '${workflow.config.schedule}'`);
           }
@@ -2960,7 +2967,14 @@ async function startMiqroCore(config, staticWorkflows) {
         import_node_cron.default.schedule(workflow.config.schedule, () => {
           console.log(`[Cron] Executing scheduled workflow: ${workflow.config.id}`);
           const payload = { source: "cron", timestamp: Date.now() };
-          workflow.execute(payload);
+          const context = {
+            workflowId: workflow.config.id,
+            name: workflow.config.name,
+            params: {},
+            query: {},
+            headers: {}
+          };
+          workflow.execute(payload, context);
         });
         console.log(`[Miqro] Scheduled workflow '${workflow.config.id}' with cron: '${workflow.config.schedule}'`);
       }
@@ -2968,6 +2982,11 @@ async function startMiqroCore(config, staticWorkflows) {
   }
   const app = new Hono2;
   app.use("*", logger());
+  if (config.middleware) {
+    for (const mw of config.middleware) {
+      app.use("*", mw);
+    }
+  }
   app.get("/health", (c) => c.json({
     status: "ok",
     uptime: process.uptime(),
@@ -2975,34 +2994,45 @@ async function startMiqroCore(config, staticWorkflows) {
   }));
   app.post("/:workflowId", async (c) => {
     try {
-      const payload = await c.req.json();
       const workflowId = c.req.param("workflowId");
-      if (workflowId) {
-        const workflow = workflows[workflowId];
-        if (!workflow) {
-          return c.json({ error: `Workflow '${workflowId}' not found` }, 404);
+      const workflow = workflows[workflowId];
+      if (!workflow) {
+        return c.json({ error: `Workflow '${workflowId}' not found` }, 404);
+      }
+      const authHeader = c.req.header("Authorization");
+      const { auth } = workflow.config;
+      if (auth.type === "apiKey") {
+        const apiKey = c.req.header("x-api-key") || c.req.query("apiKey");
+        if (apiKey !== auth.key) {
+          return c.json({ error: "Unauthorized: Invalid API Key" }, 401);
         }
-        const authHeader = c.req.header("Authorization");
-        const { auth } = workflow.config;
-        if (auth.type === "apiKey") {
-          const apiKey = c.req.header("x-api-key") || c.req.query("apiKey");
-          if (apiKey !== auth.key) {
-            return c.json({ error: "Unauthorized: Invalid API Key" }, 401);
-          }
-        } else if (auth.type === "bearer") {
-          if (!authHeader || !authHeader.startsWith(`Bearer ${auth.token}`)) {
-            return c.json({ error: "Unauthorized: Invalid Bearer token" }, 401);
-          }
+      } else if (auth.type === "bearer") {
+        if (!authHeader || !authHeader.startsWith(`Bearer ${auth.token}`)) {
+          return c.json({ error: "Unauthorized: Invalid Bearer token" }, 401);
         }
-        await workflow.execute(payload);
-        return c.json({
-          status: "success",
-          message: `Workflow '${workflowId}' executed`
-        });
       }
+      let payload = await c.req.json();
+      if (workflow.config.schema) {
+        const result = workflow.config.schema.safeParse(payload);
+        if (!result.success) {
+          return c.json({
+            error: "Validation Failed",
+            details: result.error.format()
+          }, 400);
+        }
+        payload = result.data;
+      }
+      const context = {
+        workflowId: workflow.config.id,
+        name: workflow.config.name,
+        params: c.req.param(),
+        query: c.req.query(),
+        headers: c.req.header()
+      };
+      await workflow.execute(payload, context);
       return c.json({
         status: "success",
-        message: "Payload received but no workflow triggered"
+        message: `Workflow '${workflowId}' executed`
       });
     } catch (error) {
       console.error("[Miqro Webhook Error]", error);

package/dist/types.d.ts

@@ -1,3 +1,5 @@
+import type { MiddlewareHandler } from "hono";
+import type { z } from "zod";
 export type AuthConfig = {
     type: "none";
 } | {
@@ -7,18 +9,27 @@ export type AuthConfig = {
     type: "bearer";
     token: string;
 };
-export interface WorkflowConfig {
+export interface MiqroContext {
+    workflowId: string;
+    name: string;
+    params: Record<string, string>;
+    query: Record<string, string | string[]>;
+    headers: Record<string, string>;
+}
+export interface WorkflowConfig<T = unknown> {
     id: string;
     name: string;
     description?: string;
     auth: AuthConfig;
     schedule?: string;
+    schema?: z.ZodType<T>;
 }
-export interface Workflow {
-    config: WorkflowConfig;
-    execute: (payload: unknown) => Promise<void> | void;
+export interface Workflow<T = unknown> {
+    config: WorkflowConfig<T>;
+    execute: (payload: T, context: MiqroContext) => Promise<void> | void;
 }
 export interface MiqroConfig {
     workflowsDir: string;
     port?: number;
+    middleware?: MiddlewareHandler[];
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "miqro.js",
-	"version": "0.1.2",
+	"version": "0.1.4",
 	"description": "Minimal, high-performance microservice engine.",
 	"main": "dist/index.js",
 	"types": "dist/index.d.ts",
@@ -30,6 +30,7 @@
 	},
 	"dependencies": {
 		"hono": "^4.12.2",
-		"node-cron": "^4.2.1"
+		"node-cron": "^4.2.1",
+		"zod": "^4.3.6"
 	}
 }