webspresso 0.0.89 → 0.0.91

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.
@@ -1197,6 +1244,82 @@ The SEO Checker panel appears as a floating widget and can be opened via:
 - Dev toolbar "SEO Check" button
 - Floating toggle button (🔍) in bottom-right corner
 
+**Basic Auth Plugin:**
+- Zero-dependency HTTP Basic Authentication (RFC 7617) with timing-safe password verification (`crypto.timingSafeEqual`).
+- Can protect the entire application globally or expose named route middleware (`middleware: ['basicAuth']`).
+
+```javascript
+const { basicAuthPlugin } = require('webspresso/plugins');
+
+const { app } = createApp({
+  pagesDir: './pages',
+  plugins: [
+    basicAuthPlugin({
+      global: false, // Set to true to protect the whole app
+      users: {
+        admin: 'supersecret',
+      },
+      realm: 'Protected Area',
+    }),
+  ],
+});
+```
+
+**Realtime Layer & Plugin:**
+- Framework-agnostic, plugin-based, and adapter-supported realtime layer (`core/realtime` and `plugins/realtime`).
+- Adapters for **Generic WebSocket**, **SSE (Server-Sent Events)**, and **Socket.IO**.
+- Universal API for browsers and SSR safety (never initializes network connections during server-side rendering).
+- Built-in exponential backoff reconnection with jitter, multi-strategy authentication (token, cookie, custom), auto-recovery of subscriptions on reconnect, and token sanitization.
+
+```javascript
+const { createApp } = require('webspresso');
+const { realtimePlugin, websocket } = require('webspresso/plugins');
+
+// 1. App Plugin Setup
+const { app } = createApp({
+  plugins: [
+    realtimePlugin({
+      adapter: websocket({ url: '/realtime' }),
+      auth: { strategy: 'cookie' },
+      autoConnect: true,
+    }),
+  ],
+});
+
+// 2. Subscription & RPC
+const sub = app.realtime.subscribe('project:123', { role: 'editor' }, {
+  connected() {
+    console.log('Connected to project:123');
+  },
+  received(data) {
+    console.log('Live message:', data);
+  },
+});
+
+sub.perform('user_typing', { userId: 42, isTyping: true });
+sub.send({ text: 'Hello team!' });
+
+// 3. Standalone Client Usage (with Token Auth & Refresh)
+const { realtime, websocket } = require('webspresso');
+
+const client = realtime({
+  adapter: websocket({ url: 'wss://api.example.com/realtime' }),
+  auth: {
+    strategy: 'token',
+    getToken: async () => localStorage.getItem('token'),
+    refreshToken: async () => {
+      const res = await fetch('/api/auth/refresh', { method: 'POST' });
+      const { token } = await res.json();
+      localStorage.setItem('token', token);
+      return token;
+    },
+    onUnauthorized: (err) => {
+      window.location.href = '/login';
+    },
+  },
+});
+```
+
 ### Creating Custom Plugins
 
 ```javascript
@@ -1537,31 +1660,87 @@ module.exports = {
 };
 ```
 
-## i18n
+## i18n & Localization
+
+Webspresso features a zero-dependency, ultra-fast internationalization engine built directly on native Node.js `Intl` APIs (`Intl.PluralRules`, `Intl.NumberFormat`, `Intl.DateTimeFormat`, `Intl.RelativeTimeFormat`).
 
-### Global Translations
+### 1. Global & Route-Specific Translations
 
-Add JSON files to `pages/locales/`:
+Add JSON files to `pages/locales/` for global dictionary entries, or inside any route directory `pages/catalog/locales/` for route-specific overrides:
 
 ```json
+// pages/locales/en.json
 {
   "nav": {
     "home": "Home",
     "about": "About"
+  },
+  "cart": {
+    "zero": "Your cart is empty",
+    "one": "You have 1 item in your cart",
+    "other": "You have {{count}} items in your cart"
   }
 }
 ```
 
-### Route-Specific Translations
+### 2. Basic Translation & Interpolation
 
-Add a `locales/` folder inside any route directory to override global translations.
+```nunjucks
+{# Direct function call #}
+<h1>{{ t('nav.home') }}</h1>
+
+{# With parameter interpolation #}
+<p>{{ t('welcome', { name: currentUser.username }) }}</p>
 
-### Using Translations
+{# With Nunjucks filter #}
+<h1>{{ 'nav.home' | t }}</h1>
+<p>{{ 'welcome' | t({ name: currentUser.username }) }}</p>
+```
+
+### 3. Native Pluralization (`Intl.PluralRules`)
 
-In templates:
+Pass `count` (or `n`, `cardinal`) to automatically select the correct CLDR plural category (`zero`, `one`, `two`, `few`, `many`, `other`) or exact number (`0`, `1`):
 
 ```nunjucks
-<h1>{{ t('nav.home') }}</h1>
+<p>{{ t('cart', { count: cart.items.length }) }}</p>
+```
+
+You can also use the inline `t.plural()` helper:
+```nunjucks
+<p>{{ t.plural(items.length, { one: '1 item', other: '{{count}} items' }) }}</p>
+```
+
+### 4. Fallback Locales Chain
+
+If a translation key is missing in the requested locale (e.g. `tr`), Webspresso automatically falls back to `DEFAULT_LOCALE` (default: `en`) before returning the key name or default fallback value. Check key existence with `t.has('key')` or `t.exists('key')`.
+
+### 5. Built-in `Intl` Formatters on `t`
+
+Format numbers, currencies, dates, and relative times according to the active locale without external date/number libraries:
+
+```nunjucks
+{# Numbers #}
+<span>{{ t.number(1234567.89) }}</span> {# TR: 1.234.567,89 | EN: 1,234,567.89 #}
+
+{# Currencies #}
+<span>{{ t.currency(199.99, 'TRY') }}</span> {# ₺199,99 #}
+<span>{{ t.currency(49.99, 'USD') }}</span>  {# $49.99 #}
+
+{# Dates #}
+<span>{{ t.date(post.created_at, { dateStyle: 'long' }) }}</span>
+
+{# Relative Time #}
+<span>{{ t.relativeTime(-2, 'day') }}</span> {# "2 days ago" or "2 gün önce" #}
+```
+
+### 6. Language Switcher Helpers
+
+Use `fsy.localeUrl(targetLocale)` to generate a URL with the current page path and query parameters preserved:
+
+```nunjucks
+<a href="{{ fsy.localeUrl('en') }}">English</a>
+<a href="{{ fsy.localeUrl('tr') }}">Türkçe</a>
+<a href="{{ fsy.localeUrl('de') }}">Deutsch</a>
 ```
 
 ## Template Helpers
@@ -1635,6 +1814,224 @@ module.exports = {
 10. Nunjucks render
 11. Route `afterRender`
 
+## Services Layer
+
+Webspresso includes a lightweight, framework-agnostic **Services Layer** to organize reusable business logic, query flows, and multi-step mutations under `services/`.
+
+Services are automatically discovered from the filesystem and can be invoked from SSR data loaders (`ctx.service()`), API routes (`req.service()`), background jobs, cron, CLI tasks, or other services.
+
+### 1. File Structure & Service Names
+
+Files inside `services/` map directly to dot-separated service names:
+
+```text
+services/
+  user/
+    get.js           → user.get
+    create.js        → user.create
+    profile/
+      get.js         → user.profile.get
+  post/
+    publish.js       → post.publish
+    listByUser.js    → post.listByUser
+  payment/
+    refund.js        → payment.refund
+```
+
+### 2. Service Definition
+
+Services export a handler and an optional input validation schema:
+
+```javascript
+// services/user/get.js
+module.exports = {
+  schema: {
+    id: 'number',
+  },
+
+  async handler({ id }, ctx) {
+    return ctx.db.users.findById(id);
+  },
+};
+```
+
+You can also use the `defineService` helper:
+
+```javascript
+// services/payment/refund.js
+const { defineService } = require('webspresso');
+
+module.exports = defineService({
+  // Zod functional schema syntax ({ z }) with built-in nanoid support
+  schema: ({ z }) => z.object({
+    transactionId: z.string().min(3),
+    amount: z.number().positive(),
+    reason: z.string().optional(),
+  }),
+
+  async handler({ transactionId, amount, reason }, ctx) {
+    // Process refund logic...
+    return { refundId: 'ref_123', transactionId, amount, status: 'succeeded' };
+  },
+});
+```
+
+### 3. Service-to-Service Composition
+
+Services can seamlessly call other services via `ctx.service()` while sharing the exact same request context (`ctx.db`, `ctx.auth`, `ctx.session`, `ctx.user`):
+
+```javascript
+// services/post/publish.js
+module.exports = {
+  schema: ({ z }) => z.object({
+    title: z.string(),
+    authorId: z.number(),
+  }),
+
+  async handler({ title, authorId }, ctx) {
+    const author = await ctx.service('user.get', { id: authorId });
+
+    return ctx.db.posts.create({
+      title,
+      author_id: author.id,
+      published_at: new Date(),
+    });
+  },
+};
+```
+
+> **Circular Call Protection**: Webspresso automatically tracks service call stacks and detects recursive/circular dependencies (e.g. `user.get -> profile.get -> user.get`), throwing an informative `Circular service call detected` error.
+
+### 4. Invoking from SSR & API Routes
+
+In SSR page data loaders (`pages/users/[id].njk`):
+
+```javascript
+// pages/users/[id].js
+module.exports = {
+  async load(req, ctx) {
+    const user = await ctx.service('user.get', { id: Number(req.params.id) });
+    return { user };
+  },
+};
+```
+
+In API routes or Express middleware:
+
+```javascript
+// pages/api/users.post.js
+module.exports = async function(req, res) {
+  const user = await req.service('user.create', req.body);
+  res.status(201).json(user);
+};
+```
+
+### 5. Service Caching & Memoization (`cache: '5m'`)
+
+Services can be cached in-memory with automatic TTL expiration and deterministic key serialization:
+
+```javascript
+// services/product/stats.js
+module.exports = {
+  // Cache result for 5 minutes based on input arguments
+  cache: '5m', // supports '30s', '5m', '1h', '1d', ms numbers, or { ttl: '5m', key: (input) => input.id }
+
+  async handler({ productId }, ctx) {
+    return ctx.db.stats.getProductStats(productId);
+  },
+};
+```
+
+You can invalidate cache keys explicitly on mutations:
+
+```javascript
+// From any service or route:
+ctx.service.invalidate('product.stats', { productId: 42 });
+
+// Or clear all cached entries for a service:
+ctx.service.clearCache('product.stats');
+```
+
+You can also use `memoize` as a standalone utility for any async function:
+
+```javascript
+const { memoize } = require('webspresso');
+
+const fetchRemoteRates = memoize(async () => {
+  return fetchExchangeRates();
+}, { ttl: '10m', maxSize: 100 });
+```
+
+### 6. Timeouts & Database Transactions (`timeout`, `transaction`)
+
+You can protect services against hanging handlers and ensure automatic ACID transaction rollbacks:
+
+```javascript
+// services/order/checkout.js
+module.exports = {
+  // Abort with 504 Gateway Timeout if execution exceeds 5 seconds
+  timeout: '5s',
+
+  // Wrap execution in an automatic Knex transaction (rolls back on any error)
+  transaction: true,
+
+  async handler({ orderId, items }, ctx) {
+    // ctx.trx and ctx.db are automatically bound to the active transaction
+    await ctx.db('orders').where({ id: orderId }).update({ status: 'paid' });
+    await ctx.service('inventory.deduct', { items }); // Nested services reuse the exact same transaction!
+
+    return { orderId, success: true };
+  },
+};
+```
+
+### 7. Authorization & Role Guards (`auth`)
+
+Services can enforce authentication and role-based access control (RBAC) automatically:
+
+```javascript
+// services/admin/billing.js
+module.exports = {
+  // Requires authenticated user with 'admin' or 'finance' role
+  auth: ['admin', 'finance'], // or auth: true (any logged in user) or auth: (user, ctx) => boolean
+
+  async handler(input, ctx) {
+    // Guaranteed to have authorized ctx.user
+    return ctx.db('billing_records').select();
+  },
+};
+```
+
+Throws `UnauthorizedError` (401) when unauthenticated or `ForbiddenError` (403) when role permissions are insufficient.
+
+### 8. Interactive CLI Runner (`webspresso service`)
+
+You can test and run any service directly from the command line without starting the HTTP server:
+
+```bash
+# Interactive selection & prompt mode
+npx webspresso service
+
+# Run a specific service with JSON payload
+npx webspresso service user.get -i '{"id": 42}'
+
+# Run with key=value query string
+npx webspresso service payment.refund -i 'transactionId=tx_123 amount=49.99'
+```
+
+### 7. Programmatic Usage & Testing
+
+You can execute services directly in unit tests or background scripts:
+
+```javascript
+const { createServiceRegistry } = require('webspresso');
+
+const services = createServiceRegistry({ servicesDir: './services' });
+const user = await services.call('user.get', { id: 42 }, { db: mockDb });
+```
+
+---
+
 ## Environment Variables
 
 | Variable | Default | Description |