webspresso 0.0.62 → 0.0.64

package/README.md

@@ -15,7 +15,8 @@ A minimal, file-based SSR framework for Node.js with Nunjucks templating.
 - **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**: Development dashboard, sitemap generator, SEO checker, analytics integration (Google, Yandex, Bing), self-hosted site analytics, optional Swagger UI for HTTP APIs, configurable HTTP health probe endpoint
+- **Built-in Plugins**: Development dashboard, sitemap generator, SEO checker, analytics integration (Google, Yandex, Bing), self-hosted site analytics, optional Swagger UI for HTTP APIs, configurable HTTP health probe endpoint, optional REST CRUD routes from ORM models
+- **TypeScript**: Published **`index.d.ts`** (via `package.json` `"types"`) for `createApp`, ORM, plugins, and router helpers — use from TS/JS with IDE autocomplete; runtime stays CommonJS
 
 ## Installation
 
@@ -25,6 +26,18 @@ npm install -g webspresso
 npm install webspresso
 ```
 
+## TypeScript
+
+The npm package ships with **[`index.d.ts`](index.d.ts)** so consumers get typings for the public API (`createApp`, `defineModel`, `createDatabase`, `zdb`, plugins, etc.). No extra `@types/webspresso` package is required.
+
+```typescript
+import { createApp, defineModel, zdb } from 'webspresso';
+```
+
+Install **`@types/express`** in your app if you want full **`Express.Application`** / **`Request`** / **`Response`** inference when you touch `createApp().app` or write middleware. **`knex`** and **`zod`** bring their own types.
+
+Framework development (this repo): run **`npm run check:types`** to typecheck the declarations against a small smoke file (`tests/ts-smoke/`).
+
 ## Quick Start
 
 ### Using CLI (Recommended)
@@ -1030,7 +1043,40 @@ module.exports = async function handler(req, res) {
 };
 ```
 
-**With Schema Validation:**
+**Object export (`handler`, `middleware`, `schema`):**
+
+Use a single export object when you need **named middleware** from `createApp({ middlewares })` and/or a **Zod** `schema`. Order at runtime: **`req.db`** (if configured) → **schema** (`req.input`) → **middleware** chain → **handler**.
+
+```javascript
+// pages/api/search.post.js
+module.exports = {
+  middleware: ['requireAuth'],
+  schema: ({ z }) => ({
+    body: z.object({ q: z.string() }),
+  }),
+  handler: async (req, res) => {
+    const { q } = req.input.body;
+    const results = [];
+    return res.json({ results, q });
+  },
+};
+```
+
+Register `requireAuth` (and any other names) on the app:
+
+```javascript
+createApp({
+  pagesDir: './pages',
+  middlewares: {
+    requireAuth: (req, res, next) => {
+      if (!req.session?.user) return res.status(401).json({ error: 'Unauthorized' });
+      next();
+    },
+  },
+});
+```
+
+**With Schema Validation (same object shape):**
 
 ```javascript
 // pages/api/posts.post.js
@@ -1066,7 +1112,25 @@ module.exports = {
 | `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.
+All schemas use [Zod](https://zod.dev) for validation. Invalid requests receive **`400 JSON`**: `{ error: 'Validation Error', issues: [...] }` (no `handler` / `middleware` run).
+
+For **nanoid** route parameters (same alphabet and default length as **`generateNanoid`** / **`zdb.nanoid()`**), use **`z.nanoid()`** on the `z` passed into your API schema (Webspresso extends it; no extra import). Optional: **`z.nanoid(12)`** or **`z.nanoid({ maxLength: 12 })`** (matches **`zdb.nanoid({ maxLength })`**). For scripts or tests outside `schema: ({ z })`, **`zodNanoid(z, size?)`** and **`extendZ(z)`** are exported from `webspresso`.
+
+```javascript
+module.exports = {
+  schema: ({ z }) => ({
+    params: z.object({
+      id: z.nanoid(),                  // default 21 chars
+      shortId: z.nanoid(12),           // numeric length
+      other: z.nanoid({ maxLength: 8 }), // zdb-style options
+    }),
+  }),
+  async handler(req, res) {
+    const { id } = req.input.params;
+    // ...
+  },
+};
+```
 
 **Dynamic Route with Params Validation:**
 
@@ -1831,6 +1895,34 @@ const user = plugin.api.getModel('User');    // Single model
 const names = plugin.api.getModelNames();    // Model names
 ```
 
+### REST resources plugin
+
+Registers **REST-style CRUD** routes for ORM models (`GET` list, `GET /:id`, `POST`, `PATCH /:id`, `DELETE /:id`). Relations are eager-loaded only when the client passes **`?include=relation1,relation2`**; loading uses the ORM batch eager loader (no classic N+1 from relation queries). **Nested includes** (e.g. `posts.comments`) are **not** supported—only top-level relation names defined on the model.
+
+**Model opt-in** via `defineModel({ ..., rest: { enabled: true, path: 'optional-segment', allowInclude: ['company'] } })`. If you pass **`models: ['User', 'Post']`** to the plugin, those names are exposed even when `rest.enabled` is false.
+
+**Setup:**
+
+```javascript
+const { createApp, restResourcePlugin } = require('webspresso');
+
+const { app } = createApp({
+  pagesDir: './pages',
+  db,
+  plugins: [
+    restResourcePlugin({
+      path: '/api/rest',
+      middleware: [], // optional Express handlers (e.g. auth) — `attachDbMiddleware` is applied after these
+      models: null,   // optional whitelist of model names; when omitted, only `rest.enabled` models are exposed
+      excludeModels: [],
+      filter: null,   // optional (model) => boolean
+    }),
+  ],
+});
+```
+
+List query parameters: `page`, `perPage`, `sort`, `order`, `include`, `trashed` (`only` / `include` when the model uses soft delete), plus **equality filters** on real columns (unknown keys are ignored).
+
 ### Health check plugin
 
 Exposes a lightweight **GET** endpoint for load balancers and orchestrators (Kubernetes, Docker healthcheck, etc.). **Enabled by default** in all environments; set `enabled: false` to turn it off.

package/core/compileSchema.js

@@ -4,8 +4,12 @@
  */
 
 const z = require('zod');
+const { extendZ } = require('./orm/utils/nanoid');
 const schemaCache = require('../utils/schemaCache');
 
+/** Zod plus `z.nanoid()` for API schemas (does not mutate the global `z`). */
+const zForApi = extendZ(z);
+
 /**
  * Compile schema from an API module
  * @param {string} filePath - Absolute file path to API module
@@ -32,8 +36,8 @@ function compileSchema(filePath, apiModule) {
     throw new Error(`Schema in ${filePath} must be a function`);
   }
 
-  // Call schema function with { z }
-  const compiled = schemaFn({ z });
+  // Call schema function with { z } (extended with z.nanoid, same as generateNanoid / zdb.nanoid)
+  const compiled = schemaFn({ z: zForApi });
 
   // Validate compiled schema structure
   if (compiled !== null && typeof compiled !== 'object') {

package/core/orm/index.js

@@ -14,7 +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');
+const { generateNanoid, zodNanoid, extendZ } = require('./utils/nanoid');
 
 /**
  * Create a database instance
@@ -275,6 +275,8 @@ module.exports = {
   extractColumnsFromSchema,
   getColumnMeta,
   generateNanoid,
+  zodNanoid,
+  extendZ,
   // Output sanitization (exclude hidden columns from API/templates)
   omitHiddenColumns,
   sanitizeForOutput,

package/core/orm/model.js

@@ -27,6 +27,7 @@ function defineModel(options) {
     relations = {},
     scopes = {},
     admin = {},
+    rest = {},
     hooks = {},
     hidden = [],
   } = options;
@@ -89,6 +90,11 @@ function defineModel(options) {
       customFields: admin.customFields || {},
       queries: admin.queries || {},
     },
+    rest: {
+      enabled: rest.enabled === true,
+      path: typeof rest.path === 'string' && rest.path.length > 0 ? rest.path.replace(/^\/+|\/+$/g, '') : null,
+      allowInclude: Array.isArray(rest.allowInclude) ? rest.allowInclude.filter((x) => typeof x === 'string') : null,
+    },
     hidden: Array.isArray(hidden) ? hidden : [],
     hooks: {},
   };

package/core/orm/types.js

@@ -134,6 +134,13 @@
  * @property {Object.<string, QueryConfig>} [queries={}] - Custom query functions
  */
 
+/**
+ * @typedef {Object} RestMetadata
+ * @property {boolean} [enabled=false] - Expose this model via restResourcePlugin (when not using plugin `models` whitelist)
+ * @property {string} [path] - URL segment override (no slashes); default: pluralized model name
+ * @property {string[]} [allowInclude] - Allowed relation names for `?include=`; default: all `model.relations` keys
+ */
+
 // ============================================================================
 // Model Types
 // ============================================================================
@@ -147,6 +154,7 @@
  * @property {RelationsMap} [relations={}] - Relation definitions
  * @property {ScopeOptions} [scopes={}] - Scope options
  * @property {AdminMetadata} [admin] - Admin panel metadata
+ * @property {RestMetadata} [rest] - REST resource plugin metadata
  * @property {string[]} [hidden=[]] - Column names to never expose in API/templates (e.g. password_hash, api_token)
  */
 
@@ -160,6 +168,7 @@
  * @property {ScopeOptions} scopes - Scope options
  * @property {Map<string, ColumnMeta>} columns - Parsed column metadata
  * @property {AdminMetadata} [admin] - Admin panel metadata
+ * @property {RestMetadata} rest - REST resource plugin metadata
  * @property {string[]} hidden - Column names never exposed in API/templates
  */
 

package/core/orm/utils/nanoid.js

@@ -24,7 +24,60 @@ function generateNanoid(size = 21) {
   return id;
 }
 
+/**
+ * Zod schema for IDs produced by {@link generateNanoid} (same default alphabet & length).
+ * Prefer **`z.nanoid()`** in API `schema: ({ z }) => …`; use this when building Zod schemas outside compiled routes.
+ * @param {typeof import('zod').z} z - Zod instance (from `schema: ({ z }) => …`)
+ * @param {number} [size=21]
+ */
+function zodNanoid(z, size = 21) {
+  const n = Math.max(1, Math.floor(size));
+  const alphabet = new Set(URL_ALPHABET);
+  return z.string().length(n).refine((s) => [...s].every((ch) => alphabet.has(ch)), {
+    message: `Expected ${n}-character nanoid (default URL alphabet)`,
+  });
+}
+
+/**
+ * @param {unknown} arg - `undefined` → 21; number → length; `{ maxLength }` (zdb-compatible)
+ * @returns {number}
+ */
+function resolveNanoidSize(arg) {
+  if (arg === undefined) return 21;
+  if (arg === null) return 21;
+  if (typeof arg === 'number' && !Number.isNaN(arg)) {
+    return Math.max(1, Math.floor(arg));
+  }
+  if (typeof arg === 'object' && arg !== null && 'maxLength' in arg) {
+    const n = /** @type {{ maxLength?: unknown }} */ (arg).maxLength;
+    if (typeof n === 'number' && !Number.isNaN(n)) {
+      return Math.max(1, Math.floor(n));
+    }
+  }
+  return 21;
+}
+
+/**
+ * Wraps Zod's `z` with **`z.nanoid()`** / **`z.nanoid(12)`** / **`z.nanoid({ maxLength: 12 })`**
+ * without mutating the global `z` object. Used by API `schema: ({ z }) => …`.
+ * @param {typeof import('zod').z} zod
+ */
+function extendZ(zod) {
+  return new Proxy(zod, {
+    get(target, prop, receiver) {
+      if (prop === 'nanoid') {
+        return function nanoid(arg) {
+          return zodNanoid(zod, resolveNanoidSize(arg));
+        };
+      }
+      return Reflect.get(target, prop, receiver);
+    },
+  });
+}
+
 module.exports = {
   generateNanoid,
+  zodNanoid,
+  extendZ,
   URL_ALPHABET,
 };