webspresso 0.0.4 → 0.0.6

package/README.md

@@ -7,11 +7,12 @@ 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
 - **Plugin System**: Extensible architecture with version control and inter-plugin communication
-- **Built-in Plugins**: Sitemap generator, analytics integration (Google, Yandex, Bing)
+- **Built-in Plugins**: Development dashboard, sitemap generator, analytics integration (Google, Yandex, Bing)
 
 ## Installation
 
@@ -325,12 +326,13 @@ Webspresso has a built-in plugin system with version control and dependency mana
 
 ```javascript
 const { createApp } = require('webspresso');
-const { sitemapPlugin, analyticsPlugin } = require('webspresso/plugins');
+const { sitemapPlugin, analyticsPlugin, dashboardPlugin } = require('webspresso/plugins');
 
 const { app } = createApp({
   pagesDir: './pages',
   viewsDir: './views',
   plugins: [
+    dashboardPlugin(),  // Dev dashboard at /_webspresso
     sitemapPlugin({
       hostname: 'https://example.com',
       exclude: ['/admin/*', '/api/*'],
@@ -357,6 +359,28 @@ const { app } = createApp({
 
 ### Built-in Plugins
 
+**Dashboard Plugin:**
+- Development dashboard at `/_webspresso`
+- Monitor all routes (SSR pages and API endpoints)
+- View loaded plugins and configuration
+- Filter and search routes
+- Only active in development mode (disabled in production)
+
+```javascript
+const { dashboardPlugin } = require('webspresso/plugins');
+
+const { app } = createApp({
+  pagesDir: './pages',
+  plugins: [
+    dashboardPlugin()  // Available at /_webspresso in dev mode
+  ]
+});
+```
+
+Options:
+- `path` - Custom dashboard path (default: `/_webspresso`)
+- `enabled` - Force enable/disable (default: auto based on NODE_ENV)
+
 **Sitemap Plugin:**
 - Generates `/sitemap.xml` from routes automatically
 - Excludes dynamic routes and API endpoints
@@ -471,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.4",
+  "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
+};
+