webspresso 0.0.60 → 0.0.62

package/README.md

@@ -336,7 +336,7 @@ Creates and configures the Express app.
 - `pagesDir` (required): Path to pages directory
 - `viewsDir` (optional): Path to views/layouts directory
 - `publicDir` (optional): Path to public/static directory
-- `db` (optional): Database instance — exposed as `ctx.db` in plugin hooks (`register`, `onRoutesReady`) and in page `load`/`meta` functions
+- `db` (optional): Database instance — exposed as `ctx.db` in plugin hooks (`register`, `onRoutesReady`) and in page `load`/`meta` functions; also registered for [`getDb()` / `getAppContext()`](#app-context-getdb-hasdb-getappcontext) below
 - `logging` (optional): Enable request logging (default: true in development)
 - `helmet` (optional): Helmet security configuration
   - `true` or `undefined`: Use default secure configuration
@@ -386,6 +386,54 @@ module.exports = {
 };
 ```
 
+### App context (`req.db`, `getDb`, `attachDbMiddleware`)
+
+With **`createApp({ db })`**, file-based **API** routes (`pages/api/*.js`) get the same ORM instance on **`req.db`** before your **`middleware`** array and the handler run — no extra `require` in the handler:
+
+```javascript
+module.exports = async function handler(req, res) {
+  if (!req.db) {
+    return res.status(503).json({ error: 'Database not configured' });
+  }
+  const posts = await req.db.getRepository('Post').query().limit(10).list();
+  res.json(posts);
+};
+
+module.exports.middleware = ['auth']; // can use req.db too
+```
+
+The framework also registers that instance for **non-request** code (scripts, jobs) and for tests:
+
+```javascript
+const { getDb, hasDb } = require('webspresso');
+// hasDb() / getDb() — getDb() throws if createApp had no db
+```
+
+For routes you add manually in **`setupRoutes`**, run **`attachDbMiddleware`** early so those handlers get `req.db`:
+
+```javascript
+const { createApp, attachDbMiddleware } = require('webspresso');
+
+createApp({
+  pagesDir: './pages',
+  db,
+  setupRoutes(app) {
+    app.use(attachDbMiddleware);
+    app.get('/custom/api', (req, res) => res.json({ ok: !!req.db }));
+  },
+});
+```
+
+| Export | Role |
+|--------|------|
+| `req.db` | Set on each API request when `createApp({ db })` was used (file-based API routes + after `attachDbMiddleware`) |
+| `getDb()` | Same instance as `req.db`; **throws** if no `db` was passed to `createApp` |
+| `hasDb()` | `true` if `createApp` was given `db` |
+| `getAppContext()` | `{ db }` — `db` may be `null` |
+| `attachDbMiddleware` | Express middleware to populate `req.db` for non–file-router routes |
+| `resetAppContext()` | Clears context (mainly for tests) |
+| `setAppContext(partial)` | Low-level merge; normally only `createApp` uses this |
+
 **Custom Error Pages:**
 
 ```javascript
@@ -1240,6 +1288,7 @@ The `zdb` helpers wrap Zod schemas with database column metadata:
 |--------|-------------|---------|
 | `zdb.id()` | Primary key (bigint, auto-increment) | |
 | `zdb.uuid()` | UUID primary key | |
+| `zdb.nanoid(opts)` | Nanoid primary key (URL-safe string, stored as VARCHAR) | `maxLength` (default `21`) |
 | `zdb.string(opts)` | VARCHAR column | `maxLength`, `unique`, `index`, `nullable` |
 | `zdb.text(opts)` | TEXT column | `nullable` |
 | `zdb.integer(opts)` | INTEGER column | `nullable`, `default` |
@@ -1255,6 +1304,9 @@ The `zdb` helpers wrap Zod schemas with database column metadata:
 | `zdb.enum(values, opts)` | ENUM column | `default`, `nullable` |
 | `zdb.foreignKey(table, opts)` | Foreign key (bigint) | `referenceColumn`, `nullable` |
 | `zdb.foreignUuid(table, opts)` | Foreign key (uuid) | `referenceColumn`, `nullable` |
+| `zdb.foreignNanoid(table, opts)` | Foreign key (nanoid string) | `referenceColumn`, `nullable`, `maxLength` (must match referenced PK) |
+
+**Nanoid columns:** Migration scaffolding emits `table.string(column, maxLength)`. For a **nanoid primary key**, if you omit the primary key on `repository.create()`, Webspresso fills it with a cryptographically random ID using the same default alphabet as the [`nanoid`](https://github.com/ai/nanoid) package (implemented in-framework; no extra dependency). You can also call **`generateNanoid`** (exported from `webspresso`) anywhere you need the same generator.
 
 ### Model Definition
 

package/core/openapi/orm-components.js

@@ -101,6 +101,13 @@ function columnToOpenApiType(meta) {
       result.format = 'uuid';
       break;
 
+    case 'nanoid':
+      result.type = 'string';
+      if (meta.maxLength) {
+        result.maxLength = meta.maxLength;
+      }
+      break;
+
     case 'json':
       result.type = 'object';
       break;

package/core/orm/index.js

@@ -14,6 +14,7 @@ const { createSeeder } = require('./seeder');
 const { createScopeContext } = require('./scopes');
 const { ModelEvents, Hooks, HookCancellationError, createEventContext } = require('./events');
 const { omitHiddenColumns, sanitizeForOutput } = require('./utils');
+const { generateNanoid } = require('./utils/nanoid');
 
 /**
  * Create a database instance
@@ -273,6 +274,7 @@ module.exports = {
   // Column utilities
   extractColumnsFromSchema,
   getColumnMeta,
+  generateNanoid,
   // Output sanitization (exclude hidden columns from API/templates)
   omitHiddenColumns,
   sanitizeForOutput,

package/core/orm/migrations/scaffold.js

@@ -164,6 +164,19 @@ function generateColumnLine(columnName, meta) {
       }
       break;
 
+    case 'nanoid': {
+      const nanoLen = meta.maxLength || 21;
+      if (meta.primary) {
+        parts.push(`table.string('${columnName}', ${nanoLen})`);
+      } else if (meta.references) {
+        parts.push(`table.string('${columnName}', ${nanoLen})`);
+        fkLine = `table.foreign('${columnName}').references('${meta.referenceColumn || 'id'}').inTable('${meta.references}');`;
+      } else {
+        parts.push(`table.string('${columnName}', ${nanoLen})`);
+      }
+      break;
+    }
+
     default:
       parts.push(`table.string('${columnName}')`);
   }

package/core/orm/schema-helpers.js

@@ -359,6 +359,30 @@ function createSchemaHelpers(z) {
       }, z);
     },
 
+    /**
+     * Nanoid primary key column (URL-safe string, default length 21)
+     * @param {Partial<import('./types').ColumnMeta>} [options={}]
+     * @returns {SchemaBuilder}
+     */
+    nanoid(options = {}) {
+      const { maxLength = 21, ...rest } = options;
+      const schema = z
+        .string()
+        .length(maxLength)
+        .regex(/^[A-Za-z0-9_-]+$/)
+        .optional();
+      return createSchemaBuilder(
+        schema,
+        {
+          type: 'nanoid',
+          primary: true,
+          maxLength,
+          ...rest,
+        },
+        z
+      );
+    },
+
     /**
      * String column (varchar)
      * @param {Partial<import('./types').ColumnMeta>} [options={}]
@@ -667,6 +691,36 @@ function createSchemaHelpers(z) {
         ...rest,
       }, z);
     },
+
+    /**
+     * Nanoid foreign key column
+     * @param {string} references - Referenced table name
+     * @param {Partial<import('./types').ColumnMeta>} [options={}]
+     * @returns {SchemaBuilder}
+     */
+    foreignNanoid(references, options = {}) {
+      const {
+        referenceColumn = 'id',
+        nullable = false,
+        maxLength = 21,
+        ...rest
+      } = options;
+      let schema = z
+        .string()
+        .length(maxLength)
+        .regex(/^[A-Za-z0-9_-]+$/);
+      if (nullable) {
+        schema = schema.nullable().optional();
+      }
+      return createSchemaBuilder(schema, {
+        type: 'nanoid',
+        references,
+        referenceColumn,
+        nullable,
+        maxLength,
+        ...rest,
+      }, z);
+    },
   };
 
   return helpers;

package/core/orm/scopes.js

@@ -4,6 +4,8 @@
  * @module core/orm/scopes
  */
 
+const { generateNanoid } = require('./utils/nanoid');
+
 /**
  * Apply soft delete scope to a query builder
  * @param {import('knex').Knex.QueryBuilder} qb - Knex query builder
@@ -115,6 +117,29 @@ function applyInsertTenant(data, context, model) {
   };
 }
 
+/**
+ * Generate nanoid primary key when missing on insert
+ * @param {Object} data - Data to insert
+ * @param {import('./types').ModelDefinition} model - Model definition
+ * @returns {Object}
+ */
+function applyInsertNanoidPrimary(data, model) {
+  const pk = model.primaryKey;
+  const meta = model.columns && model.columns.get(pk);
+  if (!meta || meta.type !== 'nanoid') {
+    return data;
+  }
+  const val = data[pk];
+  if (val !== undefined && val !== null && val !== '') {
+    return data;
+  }
+  const len = meta.maxLength || 21;
+  return {
+    ...data,
+    [pk]: generateNanoid(len),
+  };
+}
+
 /**
  * Get soft delete data (for UPDATE instead of DELETE)
  * @returns {Object} Soft delete update data
@@ -142,6 +167,7 @@ function applyInsertModifiers(data, context, model) {
   let modified = { ...data };
   modified = applyInsertTimestamps(modified, model);
   modified = applyInsertTenant(modified, context, model);
+  modified = applyInsertNanoidPrimary(modified, model);
   return modified;
 }
 
@@ -174,6 +200,7 @@ module.exports = {
   applyInsertTimestamps,
   applyUpdateTimestamps,
   applyInsertTenant,
+  applyInsertNanoidPrimary,
   applyInsertModifiers,
   applyUpdateModifiers,
   getSoftDeleteData,

package/core/orm/seeder.js

@@ -5,6 +5,7 @@
  */
 
 const { getModel, getAllModels } = require('./model');
+const { generateNanoid } = require('./utils/nanoid');
 
 /**
  * @typedef {Object} SeederOptions
@@ -189,6 +190,9 @@ function createSeeder(faker, knex) {
       case 'uuid':
         return faker.string.uuid();
 
+      case 'nanoid':
+        return generateNanoid(meta.maxLength || 21);
+
       case 'json':
         return { key: faker.lorem.word(), value: faker.lorem.sentence() };
 

package/core/orm/types.js

@@ -9,7 +9,7 @@
 // ============================================================================
 
 /**
- * @typedef {'id'|'string'|'text'|'integer'|'bigint'|'float'|'decimal'|'boolean'|'date'|'datetime'|'timestamp'|'json'|'array'|'enum'|'uuid'} ColumnType
+ * @typedef {'id'|'string'|'text'|'integer'|'bigint'|'float'|'decimal'|'boolean'|'date'|'datetime'|'timestamp'|'json'|'array'|'enum'|'uuid'|'nanoid'} ColumnType
  */
 
 /**

package/core/orm/utils/nanoid.js

@@ -0,0 +1,30 @@
+/**
+ * URL-safe ID generation compatible with the default nanoid alphabet/algorithm.
+ * @module core/orm/utils/nanoid
+ */
+
+const crypto = require('crypto');
+
+/** Same 64-char alphabet as npm `nanoid` default (URL-safe). */
+const URL_ALPHABET =
+  'useandom-26T198340PX75pxJACKVERYMINDBUSHWOLF_GQZbfghjklqvwyzrict';
+
+/**
+ * @param {number} [size=21] - Id length (default matches nanoid)
+ * @returns {string}
+ */
+function generateNanoid(size = 21) {
+  const n = Math.max(1, Math.floor(size));
+  const bytes = new Uint8Array(n);
+  crypto.randomFillSync(bytes);
+  let id = '';
+  for (let i = 0; i < n; i++) {
+    id += URL_ALPHABET[bytes[i] & 63];
+  }
+  return id;
+}
+
+module.exports = {
+  generateNanoid,
+  URL_ALPHABET,
+};

package/index.js

@@ -3,6 +3,14 @@
  */
 
 const { createApp } = require('./src/server');
+const {
+  attachDbMiddleware,
+  getAppContext,
+  getDb,
+  hasDb,
+  resetAppContext,
+  setAppContext,
+} = require('./src/app-context');
 const { 
   mountPages, 
   filePathToRoute, 
@@ -35,6 +43,13 @@ const { schemaExplorerPlugin, adminPanelPlugin, siteAnalyticsPlugin, auditLogPlu
 module.exports = {
   // Main API
   createApp,
+
+  attachDbMiddleware,
+  getAppContext,
+  getDb,
+  hasDb,
+  resetAppContext,
+  setAppContext,
   
   // Router utilities (for advanced use)
   mountPages,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "webspresso",
-  "version": "0.0.60",
+  "version": "0.0.62",
   "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": {

package/plugins/admin-panel/components.js

@@ -1083,6 +1083,7 @@ function getFieldRenderer(col, modelMeta) {
     json: 'json',
     array: 'array',
     uuid: 'string',
+    nanoid: 'string',
   };
   return FieldRenderers[typeMap[col.type] || 'string'];
 }

package/plugins/admin-panel/field-renderers/index.js

@@ -68,6 +68,7 @@ function initializeDefaultRenderers() {
   registerFieldRenderer('timestamp', basicRenderers.DateTimeField);
   registerFieldRenderer('enum', basicRenderers.SelectField);
   registerFieldRenderer('uuid', basicRenderers.TextField);
+  registerFieldRenderer('nanoid', basicRenderers.TextField);
   registerFieldRenderer('id', basicRenderers.NumberField);
   
   // Complex types

package/src/app-context.js

@@ -0,0 +1,75 @@
+/**
+ * Process-wide app context set by createApp() — use from API handlers, jobs, etc.
+ * @module src/app-context
+ */
+
+/** @type {{ db: object|null }} */
+let context = {
+  db: null,
+};
+
+/**
+ * Merge into the current context (typically called once from createApp).
+ * @param {{ db?: object|null }} partial
+ */
+function setAppContext(partial) {
+  context = { ...context, ...partial };
+}
+
+/**
+ * @returns {{ db: object|null }}
+ */
+function getAppContext() {
+  return context;
+}
+
+/**
+ * Database instance passed to createApp({ db }) (Knex + ORM helpers).
+ * @returns {object}
+ * @throws {Error} If createApp was not given a db instance
+ */
+function getDb() {
+  if (!context.db) {
+    throw new Error(
+      'No database registered. Create a DB with createDatabase(), then pass it to createApp({ db }). ' +
+        'Or use hasDb() before calling getDb().'
+    );
+  }
+  return context.db;
+}
+
+/**
+ * @returns {boolean}
+ */
+function hasDb() {
+  return context.db != null;
+}
+
+/**
+ * Clear context (e.g. between tests).
+ */
+function resetAppContext() {
+  context = { db: null };
+}
+
+/**
+ * Express middleware: sets `req.db` from registered app context.
+ * File-based `pages/api/*` routes attach this automatically; use in `setupRoutes`
+ * for manually registered handlers that need `req.db`.
+ * @type {import('express').RequestHandler}
+ */
+function attachDbMiddleware(req, res, next) {
+  if (context.db != null) {
+    req.db = context.db;
+  }
+  next();
+}
+
+module.exports = {
+  setAppContext,
+  getAppContext,
+  getDb,
+  hasDb,
+  resetAppContext,
+  attachDbMiddleware,
+};

package/src/file-router.js

@@ -397,6 +397,11 @@ function mountPages(app, options) {
     
     app[route.method](route.routePath, async (req, res, next) => {
       try {
+        // Same instance as createApp({ db }) / getAppContext().db — available to handler & route middleware
+        if (db != null) {
+          req.db = db;
+        }
+
         // Reload handler in dev mode
         if (isDev && require.cache[require.resolve(route.fullPath)]) {
           delete require.cache[require.resolve(route.fullPath)];

package/src/server.js

@@ -8,6 +8,7 @@ const helmet = require('helmet');
 const nunjucks = require('nunjucks');
 const timeout = require('connect-timeout');
 
+const { setAppContext } = require('./app-context');
 const { mountPages } = require('./file-router');
 const { configureAssets, createHelpers, getScriptInjector } = require('./helpers');
 const { createPluginManager } = require('./plugin-manager');
@@ -200,6 +201,8 @@ function createApp(options = {}) {
   if (!pagesDir) {
     throw new Error('pagesDir is required');
   }
+
+  setAppContext({ db: options.db ?? null });
   
   const app = express();
   

package/templates/skills/webspresso-usage/SKILL.md

@@ -143,13 +143,14 @@ Analytics plugin adds `fsy.analyticsHead`, `fsy.verificationTags`, etc., when co
 
 ## 9. ORM overview
 
-**Define schema** with **`zdb`** (`zdb.id()`, `zdb.string({...})`, `zdb.foreignKey`, `zdb.timestamp`, `zdb.json`, …).
+**Define schema** with **`zdb`** (`zdb.id()`, `zdb.uuid()`, `zdb.nanoid()`, `zdb.string({...})`, `zdb.foreignKey`, `zdb.foreignUuid`, `zdb.foreignNanoid`, `zdb.timestamp`, `zdb.json`, …).
 
 **Define model** with **`defineModel({ name, table, schema, relations, scopes, hidden, admin })`**.
 
 - **Relations:** `belongsTo`, `hasMany`, `hasOne` with `model: () => OtherModel`.
 - **Scopes:** `softDelete`, `timestamps`, optional `tenant` column.
 - **`hidden`:** columns never exposed in admin/API (e.g. `password_hash`).
+- **Nanoid PK:** `zdb.nanoid()` / `zdb.nanoid({ maxLength: 12 })` — string primary key; migrations use `string(length)`. On **`create()`**, omitting the PK auto-fills a URL-safe id (built-in generator, same alphabet as `nanoid`). Use **`zdb.foreignNanoid('table', { maxLength })`** when the parent uses nanoid PKs; **`generateNanoid`** is exported from `webspresso` for manual ids.
 
 **Database:** `createDatabase({ client, connection, models: './models' })` — auto-loads `models/*.js` (ignore `_prefix`).
 
@@ -161,7 +162,7 @@ Analytics plugin adds `fsy.analyticsHead`, `fsy.verificationTags`, etc., when co
 
 **Transactions:** `db.transaction(async (trx) => { trx.getRepository('User') })`.
 
-Pass **`db`** into **`createApp({ db })`** so **`ctx.db`** works in pages and plugins.
+Pass **`db`** into **`createApp({ db })`** so **`ctx.db`** works in pages and plugins. **`pages/api/`** handlers receive **`req.db`** (and route **`middleware`** runs after it). Outside requests, use **`getDb()`** / **`hasDb()`**; for **`setupRoutes`**-only routes, use **`attachDbMiddleware`**.
 
 ---