webspresso 0.0.88 → 0.0.90

package/README.md

@@ -528,24 +528,39 @@ const { app } = createApp({
   pagesDir: './pages',
   viewsDir: './views',
   errorPages: {
-    // Option 1: Custom handler function
-    notFound: (req, res) => {
-      res.render('errors/404.njk', { url: req.url });
-    },
+    // 404 Not Found: Template path (relative to viewsDir) or custom handler fn
+    notFound: '404.njk', // or 'errors/404.njk', or (req, res, ctx) => res.render('404.njk', ctx)
     
-    // Option 2: Template path (rendered with Nunjucks)
-    serverError: 'errors/500.njk',
+    // 500 Internal Server Error: Template path or custom handler fn
+    serverError: 'errors/500.njk', // or (err, req, res, ctx) => ...
     
-    // Timeout error page (503)
-    timeout: 'errors/503.njk'
+    // 503 Request Timeout: Template path or custom handler fn
+    timeout: 'errors/503.njk' // or (req, res, ctx) => ...
   }
 });
 ```
 
-Error templates receive these variables:
-- `404.njk`: `{ url, method }`
-- `500.njk`: `{ error, status, isDev }`
-- `503.njk`: `{ url, method, isDev }`
+#### Error Template Context & Behavior
+
+All error templates rendered with Nunjucks automatically receive a rich request context:
+- **`404.njk` (`notFound`)**: `{ fsy, locale, isDev, url, method }` — sets HTTP status `404`. If omitted, Webspresso provides a responsive built-in HTML 404 page for browsers, or `{ error: 'Not Found', status: 404 }` JSON for API requests.
+- **`500.njk` (`serverError`)**: `{ fsy, locale, isDev, url, method, error, status }` — sets HTTP status `500` (or `err.status`).
+- **`503.njk` (`timeout`)**: `{ fsy, locale, isDev, url, method }` — sets HTTP status `503`.
+
+```njk
+{# Example views/404.njk #}
+{% extends "layout.njk" %}
+
+{% block content %}
+<div class="max-w-xl mx-auto text-center py-20">
+  <h1 class="text-6xl font-bold text-slate-800">404</h1>
+  <p class="text-xl text-slate-600 mt-4">Page Not Found: <code>{{ url }}</code></p>
+  <a href="{{ fsy.url('/') }}" class="mt-6 inline-block bg-blue-600 text-white px-6 py-2 rounded-lg">
+    Back to Home
+  </a>
+</div>
+{% endblock %}
+```
 
 **How errors reach this handler**
 
@@ -568,9 +583,11 @@ const { app } = createApp({
 });
 ```
 
-**Asset Management:**
+**Asset Management & Cache-Busting:**
+
+Webspresso includes a built-in `AssetManager` that automates static asset URL resolution, query-string cache-busting, Vite/Webpack build manifest lookups, and CDN prefixing in Nunjucks SSR templates.
 
-Configure asset handling with versioning and manifest support:
+Configure asset handling in `createApp`:
 
 ```javascript
 const { createApp } = require('webspresso');
@@ -579,54 +596,84 @@ const path = require('path');
 const { app } = createApp({
   pagesDir: './pages',
   viewsDir: './views',
-  publicDir: './public',
+  publicDir: './public', // default: 'public'
   assets: {
-    // Option 1: Simple versioning (cache busting)
-    version: '1.2.3',  // or process.env.APP_VERSION
-    
-    // Option 2: Manifest file (Vite, Webpack, etc.)
+    // 1. Static query-string versioning (Cache Busting)
+    // Appends ?v=1.2.3 (or &v=... if existing query params) to asset URLs
+    version: process.env.APP_VERSION || '1.0.0', // or Git commit hash, build timestamp
+
+    // 2. Build Tool Manifest (Vite, Webpack, etc.)
+    // Resolves hashed bundle filenames automatically (e.g. style.css -> assets/style-abc123.css)
     manifestPath: path.join(__dirname, 'public/.vite/manifest.json'),
-    
-    // URL prefix for assets
-    prefix: '/static'
+
+    // 3. Asset URL Prefix / CDN
+    // Prepended to all resolved asset paths
+    prefix: process.env.CDN_URL || '' // e.g. 'https://cdn.example.com' or '/static'
   }
 });
 ```
 
-Use asset helpers in templates:
+#### How Asset Resolution Works
+
+1. **Manifest Match First**: If `manifestPath` is configured and an entry matches the asset key, `AssetManager` resolves to the hashed filename (from Vite or Webpack manifest) and prepends `prefix`.
+2. **Fallback to Path & Versioning**: If no manifest is provided or the asset is not listed in the manifest, `AssetManager` uses the original path, prepends `prefix`, and appends `?v=<version>` (or `&v=<version>`) if `version` is set.
+3. **Leading Slash Normalization**: Paths with or without leading slashes (e.g., `'css/style.css'` or `'/css/style.css'`) are handled seamlessly.
+
+```json
+// Example Vite manifest format (.vite/manifest.json)
+{
+  "css/style.css": { "file": "assets/style-abc123.css", "src": "css/style.css" },
+  "js/app.js": { "file": "assets/app-xyz789.js", "src": "js/app.js" }
+}
+
+// Example Webpack manifest format (manifest.json)
+{
+  "/css/style.css": "/dist/style.abc123.css",
+  "/js/app.js": "/dist/app.xyz789.js"
+}
+```
+
+#### Template Helpers (`fsy`)
+
+Use `fsy` helpers inside your Nunjucks layouts and pages:
 
 ```njk
-{# Using fsy helpers (auto-resolved) #}
+{# 1. URL string resolution #}
 <link rel="stylesheet" href="{{ fsy.asset('/css/style.css') }}">
+{# Outputs: <link rel="stylesheet" href="/css/style.css?v=1.0.0"> (or /assets/style-abc123.css) #}
 
-{# Or generate full HTML tags #}
+{# 2. CSS link tag helper #}
 {{ fsy.css('/css/style.css') | safe }}
-{{ fsy.js('/js/app.js', { defer: true, type: 'module' }) | safe }}
-{{ fsy.img('/images/logo.png', 'Site Logo', { class: 'logo', loading: 'lazy' }) | safe }}
+{# With custom attributes (media, id, integrity, etc.): #}
+{{ fsy.css('/css/print.css', { media: 'print', id: 'print-styles' }) | safe }}
+
+{# 3. JS script tag helper #}
+{{ fsy.js('/js/app.js') | safe }}
+{# Supports boolean flags (async, defer) and module type: #}
+{{ fsy.js('/js/main.js', { defer: true, type: 'module' }) | safe }}
+{# Outputs: <script src="/js/main.js?v=1.0.0" defer type="module"></script> #}
+
+{# 4. Image tag helper #}
+{{ fsy.img('/images/logo.png', 'Company Logo') | safe }}
+{# With attributes (loading, class, width, height): #}
+{{ fsy.img('/images/hero.jpg', 'Hero Banner', { loading: 'lazy', class: 'w-full rounded', width: 1200, height: 600 }) | safe }}
 ```
 
-Asset helpers available in `fsy`:
-- `asset(path)` - Returns versioned/manifest-resolved URL
-- `css(href, attrs)` - Generates `<link>` tag
-- `js(src, attrs)` - Generates `<script>` tag
-- `img(src, alt, attrs)` - Generates `<img>` tag
+#### Programmatic Asset Manager API
 
-**Manifest Support:**
+You can also import and use `AssetManager` directly:
 
-Works with Vite and Webpack manifest formats:
+```javascript
+const { AssetManager, configureAssets, getAssetManager } = require('webspresso');
 
-```json
-// Vite manifest format (.vite/manifest.json)
-{
-  "css/style.css": { "file": "assets/style-abc123.css" },
-  "js/app.js": { "file": "assets/app-xyz789.js" }
-}
+// Configure global manager
+configureAssets({
+  version: '2.0.0',
+  prefix: 'https://cdn.example.com'
+});
 
-// Webpack manifest format
-{
-  "/css/style.css": "/dist/style.abc123.css",
-  "/js/app.js": "/dist/app.xyz789.js"
-}
+const manager = getAssetManager();
+console.log(manager.asset('/css/style.css')); // -> 'https://cdn.example.com/css/style.css?v=2.0.0'
 ```
 
 **Returns:** `{ app, nunjucksEnv, pluginManager, authMiddleware }` — `authMiddleware` is `null` when `auth` was not passed.

package/core/auth/manager.js

@@ -38,7 +38,7 @@ const DEFAULT_CONFIG = {
     saveUninitialized: false,
     cookie: {
       httpOnly: true,
-      secure: process.env.NODE_ENV === 'production',
+      secure: process.env.NODE_ENV === 'production' ? true : 'auto',
       sameSite: 'lax',
       maxAge: 24 * 60 * 60 * 1000, // 1 day
     },
@@ -272,9 +272,11 @@ class AuthManager {
           throw new AuthenticationError('Invalid user object', 'INVALID_USER');
         }
         
-        // Set session
-        req.session.userId = user.id;
-        req.session.loggedInAt = Date.now();
+        // Set session if active
+        if (req.session) {
+          req.session.userId = user.id;
+          req.session.loggedInAt = Date.now();
+        }
         
         // Set req.user
         req.user = user;
@@ -284,19 +286,21 @@ class AuthManager {
           await self.createRememberToken(user.id, res);
         }
         
-        // Regenerate session ID for security
-        return new Promise((resolve, reject) => {
-          req.session.regenerate((err) => {
-            if (err) {
-              reject(new AuthenticationError('Session regeneration failed', 'SESSION_ERROR'));
-            } else {
-              // Restore userId after regenerate
-              req.session.userId = user.id;
-              req.session.loggedInAt = Date.now();
-              resolve();
-            }
+        // Regenerate session ID for security if supported
+        if (req.session && typeof req.session.regenerate === 'function') {
+          return new Promise((resolve, reject) => {
+            req.session.regenerate((err) => {
+              if (err) {
+                reject(new AuthenticationError('Session regeneration failed', 'SESSION_ERROR'));
+              } else {
+                // Restore userId after regenerate
+                req.session.userId = user.id;
+                req.session.loggedInAt = Date.now();
+                resolve();
+              }
+            });
           });
-        });
+        }
       },
 
       /**
@@ -320,21 +324,25 @@ class AuthManager {
           }
           
           // Clear cookie
-          res.clearCookie(self.config.rememberMe.cookieName);
+          if (typeof res?.clearCookie === 'function') {
+            res.clearCookie(self.config.rememberMe.cookieName);
+          }
         }
         
         // Clear user
         req.user = null;
         
-        // Destroy session
-        return new Promise((resolve) => {
-          req.session.destroy((err) => {
-            if (err) {
-              console.error('Session destroy error:', err);
-            }
-            resolve();
+        // Destroy session if supported
+        if (req.session && typeof req.session.destroy === 'function') {
+          return new Promise((resolve) => {
+            req.session.destroy((err) => {
+              if (err) {
+                console.error('Session destroy error:', err);
+              }
+              resolve();
+            });
           });
-        });
+        }
       },
 
       /**
@@ -715,7 +723,9 @@ class AuthManager {
     const payload = {
       id: user.id,
       type: 'access',
-      [this.identifierField]: user[this.identifierField],
+      ...(this.identifierField && user[this.identifierField] ? { [this.identifierField]: user[this.identifierField] } : {}),
+      ...(user.email && { email: user.email }),
+      ...(user.role && { role: user.role }),
       ...options.payload,
     };
     return this.createJwt(payload, options);

package/core/auth/middleware.js

@@ -15,11 +15,21 @@ const cookieParser = require('cookie-parser');
 function createAuthMiddleware(authManager) {
   const config = authManager.config;
 
+  const sessionConfig = authManager.getSessionConfig();
+
   /**
    * Session middleware
-   * Sets up express-session
+   * Sets up express-session with secure cookie enforcement
    */
-  const sessionMiddleware = session(authManager.getSessionConfig());
+  const sessionMiddleware = session({
+    ...sessionConfig,
+    cookie: {
+      httpOnly: true,
+      sameSite: 'lax',
+      secure: 'auto',
+      ...(sessionConfig.cookie || {}),
+    },
+  });
 
   /**
    * Cookie parser middleware (needed for signed cookies / remember me)

package/core/orm/eager-loader.js

@@ -63,39 +63,37 @@ async function loadRelations(records, relationNames, model, knex, scopeContext)
  * @param {import('./types').ScopeContext} scopeContext - Scope context
  */
 async function loadBelongsTo(records, relationName, localKey, foreignKey, relatedModel, knex, scopeContext) {
-  // Collect unique foreign key values
-  const foreignKeyValues = [...new Set(
-    records
-      .map(r => r[foreignKey])
-      .filter(v => v !== null && v !== undefined)
-  )];
-
-  if (foreignKeyValues.length === 0) {
-    // No foreign keys, set all relations to null
-    for (const record of records) {
-      record[relationName] = null;
+  const fkSet = new Set();
+  const len = records.length;
+  for (let i = 0; i < len; i++) {
+    const v = records[i][foreignKey];
+    if (v !== null && v !== undefined) fkSet.add(v);
+  }
+
+  if (fkSet.size === 0) {
+    for (let i = 0; i < len; i++) {
+      records[i][relationName] = null;
     }
     return;
   }
 
-  // Build query for related records
+  const foreignKeyValues = Array.from(fkSet);
   let qb = knex(relatedModel.table).whereIn(relatedModel.primaryKey, foreignKeyValues);
-  
-  // Apply scopes to related model
   qb = applyScopes(qb, scopeContext, relatedModel);
-
   const relatedRecords = await qb;
 
-  // Index related records by primary key
   const relatedMap = new Map();
-  for (const related of relatedRecords) {
-    relatedMap.set(related[relatedModel.primaryKey], related);
+  const rLen = relatedRecords.length;
+  const pk = relatedModel.primaryKey;
+  for (let i = 0; i < rLen; i++) {
+    const item = relatedRecords[i];
+    relatedMap.set(item[pk], item);
   }
 
-  // Attach related records to parent records
-  for (const record of records) {
-    const fkValue = record[foreignKey];
-    record[relationName] = fkValue !== null && fkValue !== undefined
+  for (let i = 0; i < len; i++) {
+    const rec = records[i];
+    const fkValue = rec[foreignKey];
+    rec[relationName] = fkValue !== null && fkValue !== undefined
       ? relatedMap.get(fkValue) || null
       : null;
   }
@@ -115,43 +113,42 @@ async function loadBelongsTo(records, relationName, localKey, foreignKey, relate
  * @param {import('./types').ScopeContext} scopeContext - Scope context
  */
 async function loadHasMany(records, relationName, localKey, foreignKey, relatedModel, knex, scopeContext) {
-  // Collect unique primary key values from parent records
-  const primaryKeyValues = [...new Set(
-    records
-      .map(r => r[localKey])
-      .filter(v => v !== null && v !== undefined)
-  )];
-
-  if (primaryKeyValues.length === 0) {
-    // No primary keys, set all relations to empty arrays
-    for (const record of records) {
-      record[relationName] = [];
+  const pkSet = new Set();
+  const len = records.length;
+  for (let i = 0; i < len; i++) {
+    const v = records[i][localKey];
+    if (v !== null && v !== undefined) pkSet.add(v);
+  }
+
+  if (pkSet.size === 0) {
+    for (let i = 0; i < len; i++) {
+      records[i][relationName] = [];
     }
     return;
   }
 
-  // Build query for related records
+  const primaryKeyValues = Array.from(pkSet);
   let qb = knex(relatedModel.table).whereIn(foreignKey, primaryKeyValues);
-  
-  // Apply scopes to related model
   qb = applyScopes(qb, scopeContext, relatedModel);
-
   const relatedRecords = await qb;
 
-  // Group related records by foreign key
   const relatedGroups = new Map();
-  for (const related of relatedRecords) {
-    const fkValue = related[foreignKey];
-    if (!relatedGroups.has(fkValue)) {
-      relatedGroups.set(fkValue, []);
+  const rLen = relatedRecords.length;
+  for (let i = 0; i < rLen; i++) {
+    const item = relatedRecords[i];
+    const fkValue = item[foreignKey];
+    let group = relatedGroups.get(fkValue);
+    if (group === undefined) {
+      group = [];
+      relatedGroups.set(fkValue, group);
     }
-    relatedGroups.get(fkValue).push(related);
+    group.push(item);
   }
 
-  // Attach related records to parent records
-  for (const record of records) {
-    const pkValue = record[localKey];
-    record[relationName] = relatedGroups.get(pkValue) || [];
+  for (let i = 0; i < len; i++) {
+    const rec = records[i];
+    const pkValue = rec[localKey];
+    rec[relationName] = (pkValue !== null && pkValue !== undefined ? relatedGroups.get(pkValue) : undefined) || [];
   }
 }
 
@@ -169,42 +166,39 @@ async function loadHasMany(records, relationName, localKey, foreignKey, relatedM
  * @param {import('./types').ScopeContext} scopeContext - Scope context
  */
 async function loadHasOne(records, relationName, localKey, foreignKey, relatedModel, knex, scopeContext) {
-  // Collect unique primary key values from parent records
-  const primaryKeyValues = [...new Set(
-    records
-      .map(r => r[localKey])
-      .filter(v => v !== null && v !== undefined)
-  )];
-
-  if (primaryKeyValues.length === 0) {
-    // No primary keys, set all relations to null
-    for (const record of records) {
-      record[relationName] = null;
+  const pkSet = new Set();
+  const len = records.length;
+  for (let i = 0; i < len; i++) {
+    const v = records[i][localKey];
+    if (v !== null && v !== undefined) pkSet.add(v);
+  }
+
+  if (pkSet.size === 0) {
+    for (let i = 0; i < len; i++) {
+      records[i][relationName] = null;
     }
     return;
   }
 
-  // Build query for related records
+  const primaryKeyValues = Array.from(pkSet);
   let qb = knex(relatedModel.table).whereIn(foreignKey, primaryKeyValues);
-  
-  // Apply scopes to related model
   qb = applyScopes(qb, scopeContext, relatedModel);
-
   const relatedRecords = await qb;
 
-  // Index related records by foreign key (first occurrence wins for hasOne)
   const relatedMap = new Map();
-  for (const related of relatedRecords) {
-    const fkValue = related[foreignKey];
+  const rLen = relatedRecords.length;
+  for (let i = 0; i < rLen; i++) {
+    const item = relatedRecords[i];
+    const fkValue = item[foreignKey];
     if (!relatedMap.has(fkValue)) {
-      relatedMap.set(fkValue, related);
+      relatedMap.set(fkValue, item);
     }
   }
 
-  // Attach related records to parent records
-  for (const record of records) {
-    const pkValue = record[localKey];
-    record[relationName] = relatedMap.get(pkValue) || null;
+  for (let i = 0; i < len; i++) {
+    const rec = records[i];
+    const pkValue = rec[localKey];
+    rec[relationName] = (pkValue !== null && pkValue !== undefined ? relatedMap.get(pkValue) : undefined) || null;
   }
 }
 

package/core/orm/events.js

@@ -154,6 +154,23 @@ class ModelEventsClass {
     return listeners.length > 0 ? listeners : EMPTY_ARRAY;
   }
 
+  /**
+   * Fast boolean check whether any listener matches
+   * @param {string} model - Model name
+   * @param {string} hook - Hook name
+   * @returns {boolean}
+   */
+  hasListeners(model, hook) {
+    if (this.listeners.size === 0) return false;
+    const l = this.listeners;
+    return (
+      l.has(`${model}.${hook}`) ||
+      l.has(`*.${hook}`) ||
+      l.has(`${model}.*`) ||
+      l.has('*.*')
+    );
+  }
+
   /**
    * Emit an event synchronously (for after hooks)
    * @param {string} model - Model name
@@ -163,6 +180,7 @@ class ModelEventsClass {
    */
   emit(model, hook, data, context) {
     const listeners = this.getMatchingListeners(model, hook);
+    if (listeners.length === 0) return;
     const ctx = context || createEventContext(model, hook);
 
     for (const listener of listeners) {
@@ -187,6 +205,7 @@ class ModelEventsClass {
   async emitAsync(model, hook, data, context) {
     const listeners = this.getMatchingListeners(model, hook);
     const ctx = context || createEventContext(model, hook);
+    if (listeners.length === 0) return ctx;
 
     for (const listener of listeners) {
       if (ctx.isCancelled) break;

package/core/orm/model.js

@@ -54,6 +54,7 @@ function defineModel(options) {
   const columns = extractColumnsFromSchema(schema);
 
   // Validate relations
+  const normalizedRelations = {};
   for (const [relationName, relation] of Object.entries(relations)) {
     if (!['belongsTo', 'hasMany', 'hasOne'].includes(relation.type)) {
       throw new Error(
@@ -70,6 +71,8 @@ function defineModel(options) {
         `Relation "${relationName}" in model "${name}" must have a foreignKey string`
       );
     }
+
+    normalizedRelations[relationName] = relation;
   }
 
   // Create model definition
@@ -78,7 +81,7 @@ function defineModel(options) {
     table,
     schema,
     primaryKey,
-    relations,
+    relations: normalizedRelations,
     scopes: {
       softDelete: scopes.softDelete || false,
       timestamps: scopes.timestamps || false,
@@ -186,7 +189,10 @@ function unregisterModel(name) {
  * @returns {import('./types').ModelDefinition}
  */
 function resolveRelationModel(relation) {
-  const model = relation.model();
+  let model = typeof relation.model === 'function' ? relation.model() : relation.model;
+  if (typeof model === 'string') {
+    model = getModel(model);
+  }
   if (!model || !model.name) {
     throw new Error('Invalid relation model reference');
   }