webspresso 0.0.60 → 0.0.61

package/README.md

@@ -1240,6 +1240,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 +1256,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "webspresso",
-  "version": "0.0.60",
+  "version": "0.0.61",
   "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/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`).