webspresso 0.0.5 → 0.0.6

package/README.md

@@ -7,6 +7,7 @@ A minimal, file-based SSR framework for Node.js with Nunjucks templating.
 - **File-Based Routing**: Create pages by adding `.njk` files to a `pages/` directory
 - **Dynamic Routes**: Use `[param]` for dynamic params and `[...rest]` for catch-all routes
 - **API Endpoints**: Add `.js` files to `pages/api/` with method suffixes (e.g., `health.get.js`)
+- **Schema Validation**: Zod-based request validation for body, params, and query
 - **Built-in i18n**: JSON-based translations with automatic locale detection
 - **Lifecycle Hooks**: Global and route-level hooks for request processing
 - **Template Helpers**: Laravel-inspired helper functions available in templates
@@ -494,6 +495,75 @@ Create `.js` files in `pages/api/` with optional method suffixes:
 | `pages/api/echo.post.js` | `POST /api/echo` |
 | `pages/api/users/[id].get.js` | `GET /api/users/:id` |
 
+**Basic API Handler:**
+
+```javascript
+// pages/api/health.get.js
+module.exports = async function handler(req, res) {
+  res.json({ status: 'ok' });
+};
+```
+
+**With Schema Validation:**
+
+```javascript
+// pages/api/posts.post.js
+module.exports = {
+  schema: ({ z }) => ({
+    body: z.object({
+      title: z.string().min(3).max(100),
+      content: z.string(),
+      tags: z.array(z.string()).optional()
+    }),
+    query: z.object({
+      draft: z.coerce.boolean().default(false)
+    })
+  }),
+
+  async handler(req, res) {
+    // Validated & parsed data available in req.input
+    const { title, content, tags } = req.input.body;
+    const { draft } = req.input.query;
+    
+    // Original req.body, req.query remain untouched
+    res.json({ success: true, title, draft });
+  }
+};
+```
+
+**Schema Options:**
+
+| Key | Description |
+|-----|-------------|
+| `body` | Validates `req.body` (POST/PUT/PATCH) |
+| `params` | Validates route parameters (e.g., `:id`) |
+| `query` | Validates query string parameters |
+| `response` | Response schema (for documentation, not enforced) |
+
+All schemas use [Zod](https://zod.dev) for validation. Invalid requests throw a `ZodError` which can be caught by error handlers.
+
+**Dynamic Route with Params Validation:**
+
+```javascript
+// pages/api/users/[id].get.js
+module.exports = {
+  schema: ({ z }) => ({
+    params: z.object({
+      id: z.string().uuid()
+    }),
+    query: z.object({
+      fields: z.string().optional()
+    })
+  }),
+
+  async handler(req, res) {
+    const { id } = req.input.params;  // Validated UUID
+    const user = await getUser(id);
+    res.json(user);
+  }
+};
+```
+
 ### Route Config
 
 Add a `.js` file alongside your `.njk` file to configure the route:

package/core/applySchema.js

@@ -0,0 +1,48 @@
+/**
+ * Schema Applicator
+ * Parses and validates request input against compiled schemas
+ */
+
+/**
+ * Apply compiled schema to request
+ * Parses body, params, and query against their respective schemas
+ * Stores validated results in req.input
+ * 
+ * @param {Object} req - Express request object
+ * @param {Object|null} compiledSchema - Compiled schema from compileSchema
+ * @returns {void}
+ * @throws {ZodError} If validation fails
+ */
+function applySchema(req, compiledSchema) {
+  // Initialize req.input
+  req.input = {
+    body: undefined,
+    params: undefined,
+    query: undefined
+  };
+
+  // No schema means no validation
+  if (!compiledSchema) {
+    return;
+  }
+
+  // Parse body if schema exists
+  if (compiledSchema.body) {
+    req.input.body = compiledSchema.body.parse(req.body);
+  }
+
+  // Parse params if schema exists
+  if (compiledSchema.params) {
+    req.input.params = compiledSchema.params.parse(req.params);
+  }
+
+  // Parse query if schema exists
+  if (compiledSchema.query) {
+    req.input.query = compiledSchema.query.parse(req.query);
+  }
+}
+
+module.exports = {
+  applySchema
+};
+

package/core/compileSchema.js

@@ -0,0 +1,68 @@
+/**
+ * Schema Compiler
+ * Compiles schema definitions from API files
+ */
+
+const z = require('zod');
+const schemaCache = require('../utils/schemaCache');
+
+/**
+ * Compile schema from an API module
+ * @param {string} filePath - Absolute file path to API module
+ * @param {Object} apiModule - The loaded API module
+ * @returns {Object|null} Compiled schema object or null if no schema
+ */
+function compileSchema(filePath, apiModule) {
+  // Return cached schema if exists
+  if (schemaCache.has(filePath)) {
+    return schemaCache.get(filePath);
+  }
+
+  // Check if module exports schema
+  const schemaFn = apiModule.schema;
+  
+  // Schema is optional
+  if (schemaFn === undefined) {
+    schemaCache.set(filePath, null);
+    return null;
+  }
+
+  // Schema must be a function
+  if (typeof schemaFn !== 'function') {
+    throw new Error(`Schema in ${filePath} must be a function`);
+  }
+
+  // Call schema function with { z }
+  const compiled = schemaFn({ z });
+
+  // Validate compiled schema structure
+  if (compiled !== null && typeof compiled !== 'object') {
+    throw new Error(`Schema function in ${filePath} must return an object or null`);
+  }
+
+  // Cache and return
+  schemaCache.set(filePath, compiled);
+  return compiled;
+}
+
+/**
+ * Clear schema cache for a file (for hot-reload)
+ * @param {string} filePath - Absolute file path
+ */
+function invalidateSchema(filePath) {
+  schemaCache.del(filePath);
+}
+
+/**
+ * Clear all cached schemas
+ */
+function clearAllSchemas() {
+  schemaCache.clear();
+}
+
+module.exports = {
+  compileSchema,
+  invalidateSchema,
+  clearAllSchemas
+};
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "webspresso",
-  "version": "0.0.5",
+  "version": "0.0.6",
   "description": "Minimal, production-ready SSR framework for Node.js with file-based routing, Nunjucks templating, built-in i18n, and CLI tooling",
   "main": "index.js",
   "bin": {
@@ -29,14 +29,17 @@
   "files": [
     "index.js",
     "bin/",
-    "src/"
+    "src/",
+    "utils/",
+    "core/"
   ],
   "dependencies": {
     "commander": "^11.1.0",
     "express": "^4.18.2",
     "helmet": "^7.2.0",
     "inquirer": "^8.2.6",
-    "nunjucks": "^3.2.4"
+    "nunjucks": "^3.2.4",
+    "zod": "^3.23.0"
   },
   "peerDependencies": {
     "dotenv": "^16.0.0"

package/src/plugin-manager.js

@@ -449,3 +449,4 @@ module.exports = {
   matchPattern
 };
 
+

package/utils/schemaCache.js

@@ -0,0 +1,59 @@
+/**
+ * Schema Cache
+ * Caches compiled Zod schemas per file path
+ */
+
+const cache = new Map();
+
+/**
+ * Get cached schema for a file path
+ * @param {string} filePath - Absolute file path
+ * @returns {Object|undefined} Compiled schema or undefined
+ */
+function get(filePath) {
+  return cache.get(filePath);
+}
+
+/**
+ * Set compiled schema for a file path
+ * @param {string} filePath - Absolute file path
+ * @param {Object} schema - Compiled schema object
+ */
+function set(filePath, schema) {
+  cache.set(filePath, schema);
+}
+
+/**
+ * Check if schema exists in cache
+ * @param {string} filePath - Absolute file path
+ * @returns {boolean}
+ */
+function has(filePath) {
+  return cache.has(filePath);
+}
+
+/**
+ * Clear all cached schemas
+ * Useful for development hot-reload
+ */
+function clear() {
+  cache.clear();
+}
+
+/**
+ * Delete a specific schema from cache
+ * @param {string} filePath - Absolute file path
+ * @returns {boolean} True if deleted
+ */
+function del(filePath) {
+  return cache.delete(filePath);
+}
+
+module.exports = {
+  get,
+  set,
+  has,
+  clear,
+  del
+};
+