webspresso 0.0.63 → 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)
@@ -1882,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/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/index.d.ts

@@ -0,0 +1,482 @@
+/**
+ * Type definitions for webspresso (CommonJS package).
+ */
+
+import type { Application, NextFunction, Request, RequestHandler, Response } from 'express';
+import type { Knex } from 'knex';
+import type { ZodObject, ZodTypeAny } from 'zod';
+
+// --- Express / app ---
+
+export interface ErrorPageContext {
+  fsy: Record<string, unknown>;
+  locale: string;
+  isDev: boolean;
+  url: string;
+  method: string;
+  [key: string]: unknown;
+}
+
+export interface CreateAppOptions {
+  pagesDir: string;
+  viewsDir?: string;
+  publicDir?: string;
+  logging?: boolean;
+  helmet?: boolean | Record<string, unknown>;
+  middlewares?: Record<string, RequestHandler>;
+  plugins?: WebspressoPlugin[];
+  assets?: {
+    version?: string;
+    manifestPath?: string;
+    prefix?: string;
+  };
+  errorPages?: {
+    notFound?: string | ((req: Request, res: Response, ctx: ErrorPageContext) => unknown);
+    serverError?:
+      | string
+      | ((err: unknown, req: Request, res: Response, ctx: ErrorPageContext) => unknown);
+    timeout?: string | ((req: Request, res: Response, ctx: ErrorPageContext) => unknown);
+  };
+  timeout?: string | false;
+  auth?: unknown;
+  db?: DatabaseInstance | null;
+  setupRoutes?: (app: Application, ctx: SetupRoutesContext) => void;
+  [key: string]: unknown;
+}
+
+export interface SetupRoutesContext {
+  nunjucksEnv: unknown;
+  authMiddleware?: RequestHandler;
+  pluginManager: PluginManager;
+  options: CreateAppOptions;
+}
+
+export interface CreateAppResult {
+  app: Application;
+  nunjucksEnv: unknown;
+  pluginManager: PluginManager;
+  authMiddleware?: RequestHandler;
+}
+
+export function createApp(options?: CreateAppOptions): CreateAppResult;
+
+// --- App context ---
+
+export function attachDbMiddleware(req: Request, res: Response, next: NextFunction): void;
+
+export function getAppContext(): { db: DatabaseInstance | null };
+
+export function getDb(): DatabaseInstance;
+
+export function hasDb(): boolean;
+
+export function resetAppContext(): void;
+
+export function setAppContext(partial: { db?: DatabaseInstance | null }): void;
+
+// --- File router ---
+
+export function mountPages(
+  app: Application,
+  options: Record<string, unknown>
+): unknown;
+
+export function filePathToRoute(filePath: string, pagesDir: string): string;
+
+export function extractMethodFromFilename(filename: string): string | null;
+
+export function scanDirectory(
+  dir: string,
+  options?: Record<string, unknown>
+): unknown[];
+
+export function loadI18n(pagesDir: string, routePath?: string): Record<string, unknown>;
+
+export function createTranslator(
+  dictionaries: Record<string, unknown>,
+  locale: string
+): (key: string, params?: Record<string, unknown>) => string;
+
+export function detectLocale(
+  req: Request,
+  supportedLocales: string[],
+  defaultLocale: string
+): string;
+
+// --- Helpers / assets ---
+
+export function createHelpers(context: Record<string, unknown>): Record<string, unknown>;
+
+export const utils: Record<string, unknown>;
+
+export class AssetManager {
+  constructor(options?: Record<string, unknown>);
+  [key: string]: unknown;
+}
+
+export function configureAssets(
+  nunjucksEnv: unknown,
+  options?: Record<string, unknown>
+): void;
+
+export function getAssetManager(): AssetManager | null;
+
+// --- Plugins ---
+
+export interface RoutesReadyContext {
+  app: Application;
+  nunjucksEnv: unknown;
+  options: CreateAppOptions;
+  db: DatabaseInstance | null;
+  routes: unknown;
+  usePlugin(name: string): unknown;
+  addHelper(name: string, fn: (...args: unknown[]) => unknown): void;
+  addFilter(name: string, fn: (...args: unknown[]) => unknown): void;
+  addRoute(method: string, path: string, ...handlers: RequestHandler[]): void;
+  [key: string]: unknown;
+}
+
+export interface PluginRegisterContext {
+  app: Application;
+  nunjucksEnv: unknown;
+  options: Record<string, unknown>;
+  db: DatabaseInstance | null;
+  usePlugin(name: string): unknown;
+  addHelper(name: string, fn: (...args: unknown[]) => unknown): void;
+  addFilter(name: string, fn: (...args: unknown[]) => unknown): void;
+  addRoute(method: string, path: string, ...handlers: RequestHandler[]): void;
+  routes: unknown;
+  [key: string]: unknown;
+}
+
+export interface WebspressoPlugin {
+  name: string;
+  version: string;
+  dependencies?: Record<string, string>;
+  register?(ctx: PluginRegisterContext): void | Promise<void>;
+  onRoutesReady?(ctx: RoutesReadyContext): void;
+  onReady?(): void | Promise<void>;
+  api?: Record<string, unknown>;
+  csp?: Record<string, unknown>;
+  [key: string]: unknown;
+}
+
+export class PluginManager {
+  [key: string]: unknown;
+}
+
+export function createPluginManager(): PluginManager;
+
+export function getPluginManager(): PluginManager | null;
+
+export function resetPluginManager(): void;
+
+// --- ORM: scopes & model ---
+
+export interface ScopeContext {
+  tenantId?: unknown;
+  withTrashed?: boolean;
+  onlyTrashed?: boolean;
+  [key: string]: unknown;
+}
+
+export type RelationType = 'belongsTo' | 'hasMany' | 'hasOne';
+
+export interface RelationDefinition {
+  type: RelationType;
+  model: () => ModelDefinition;
+  foreignKey: string;
+  localKey?: string;
+}
+
+export interface AdminMetadata {
+  enabled?: boolean;
+  label?: string;
+  icon?: string | null;
+  customFields?: Record<string, unknown>;
+  queries?: Record<string, (repo: Repository) => Promise<unknown>>;
+}
+
+export interface RestMetadata {
+  enabled?: boolean;
+  path?: string;
+  allowInclude?: string[];
+}
+
+export interface ScopeOptions {
+  softDelete?: boolean;
+  timestamps?: boolean;
+  tenant?: string | null;
+}
+
+export interface ModelOptions {
+  name: string;
+  table: string;
+  schema: ZodObject<Record<string, ZodTypeAny>>;
+  primaryKey?: string;
+  relations?: Record<string, RelationDefinition>;
+  scopes?: ScopeOptions;
+  admin?: AdminMetadata;
+  rest?: RestMetadata;
+  hooks?: Record<string, (...args: unknown[]) => unknown>;
+  hidden?: string[];
+}
+
+export interface ModelDefinition {
+  name: string;
+  table: string;
+  schema: ZodObject<Record<string, ZodTypeAny>>;
+  primaryKey: string;
+  relations: Record<string, RelationDefinition>;
+  scopes: {
+    softDelete: boolean;
+    timestamps: boolean;
+    tenant: string | null;
+  };
+  columns: Map<string, unknown>;
+  admin: {
+    enabled: boolean;
+    label: string;
+    icon: string | null;
+    customFields: Record<string, unknown>;
+    queries: Record<string, (repo: Repository) => Promise<unknown>>;
+  };
+  rest: {
+    enabled: boolean;
+    path: string | null;
+    allowInclude: string[] | null;
+  };
+  hidden: string[];
+  hooks: Record<string, unknown>;
+}
+
+export function defineModel(options: ModelOptions): ModelDefinition;
+
+export function getModel(name: string): ModelDefinition | undefined;
+
+export function getAllModels(): Map<string, ModelDefinition>;
+
+export function hasModel(name: string): boolean;
+
+export function clearRegistry(): void;
+
+// --- ORM: schema & columns ---
+
+/** zdb column helpers (id, string, timestamp, …) + `schema()` */
+export type Zdb = Record<string, any> & {
+  schema(shape: Record<string, ZodTypeAny>): ZodObject<Record<string, ZodTypeAny>>;
+};
+
+export const zdb: Zdb;
+
+export function createSchemaHelpers(z: typeof import('zod').z): Zdb;
+
+export function extractColumnsFromSchema(schema: ZodObject<Record<string, ZodTypeAny>>): Map<string, unknown>;
+
+export function getColumnMeta(schema: ZodTypeAny): unknown;
+
+// --- ORM: query / repository ---
+
+export interface FindOptions {
+  with?: string[];
+  select?: string[];
+}
+
+export interface PaginatedResult {
+  data: Record<string, unknown>[];
+  total: number;
+  page: number;
+  perPage: number;
+  totalPages: number;
+}
+
+export interface QueryBuilder {
+  where(column: string, value: unknown): this;
+  where(column: string, operator: string, value: unknown): this;
+  where(conditions: Record<string, unknown>): this;
+  orWhere(...args: unknown[]): this;
+  whereIn(column: string, values: unknown[]): this;
+  whereBetween(column: string, range: [unknown, unknown]): this;
+  select(...columns: string[]): this;
+  orderBy(column: string, direction?: 'asc' | 'desc'): this;
+  limit(n: number): this;
+  offset(n: number): this;
+  with(...relations: string[]): this;
+  withTrashed(): this;
+  onlyTrashed(): this;
+  first(): Promise<Record<string, unknown> | null>;
+  list(): Promise<Record<string, unknown>[]>;
+  get(): Promise<Record<string, unknown>[]>;
+  count(): Promise<number>;
+  paginate(page?: number, perPage?: number): Promise<PaginatedResult>;
+  exists(): Promise<boolean>;
+  clone(): QueryBuilder;
+  getWiths(): string[];
+  delete(): Promise<number>;
+  update(data: Record<string, unknown>): Promise<number>;
+  [key: string]: unknown;
+}
+
+export interface Repository {
+  findById(id: string | number, options?: FindOptions): Promise<Record<string, unknown> | null>;
+  findOne(conditions: Record<string, unknown>, options?: FindOptions): Promise<Record<string, unknown> | null>;
+  findAll(options?: FindOptions): Promise<Record<string, unknown>[]>;
+  create(data: Record<string, unknown>): Promise<Record<string, unknown>>;
+  createMany(data: Record<string, unknown>[]): Promise<Record<string, unknown>[]>;
+  update(id: string | number, data: Record<string, unknown>): Promise<Record<string, unknown> | null>;
+  updateWhere(conditions: Record<string, unknown>, data: Record<string, unknown>): Promise<number>;
+  delete(id: string | number): Promise<boolean>;
+  forceDelete(id: string | number): Promise<boolean>;
+  restore(id: string | number): Promise<Record<string, unknown> | null>;
+  query(): QueryBuilder;
+  raw(sql: string, bindings?: unknown[]): Promise<unknown>;
+  count(conditions?: Record<string, unknown>): Promise<number>;
+  exists(conditions: Record<string, unknown>): Promise<boolean>;
+  with(...relations: string[]): QueryBuilder;
+  model: ModelDefinition;
+}
+
+// --- ORM: database ---
+
+export interface MigrationConfig {
+  directory?: string;
+  tableName?: string;
+}
+
+export interface DatabaseConfig {
+  client?: string;
+  connection?: string | Record<string, unknown>;
+  models?: string;
+  migrations?: MigrationConfig;
+  pool?: Record<string, unknown>;
+  useNullAsDefault?: boolean;
+  [key: string]: unknown;
+}
+
+export interface MigrationStatus {
+  name: string;
+  completed: boolean;
+  ran_at: Date | null;
+  batch: number | null;
+}
+
+export interface MigrationResult {
+  batch: number;
+  migrations: string[];
+}
+
+export interface MakeMigrationResult {
+  filename: string;
+  filepath: string;
+  content: string | null;
+}
+
+export interface MigrationManager {
+  latest(): Promise<MigrationResult>;
+  rollback(options?: { all?: boolean }): Promise<MigrationResult>;
+  currentVersion(): Promise<string>;
+  status(): Promise<MigrationStatus[]>;
+  make(name: string, options?: { content?: string }): Promise<string | MakeMigrationResult>;
+  up(name: string): Promise<void>;
+  down(name: string): Promise<void>;
+  getConfig(): MigrationConfig & { directory: string; tableName: string };
+  hasTable(): Promise<boolean>;
+  unlock(): Promise<void>;
+}
+
+export interface TransactionContext {
+  trx: Knex.Transaction;
+  getRepository(modelName: string, scopeContext?: ScopeContext): Repository;
+  createRepository(model: ModelDefinition, scopeContext?: ScopeContext): Repository;
+}
+
+export interface DatabaseInstance {
+  knex: Knex;
+  migrate: MigrationManager;
+  getModel(name: string): ModelDefinition;
+  hasModel(name: string): boolean;
+  getAllModels(): ModelDefinition[];
+  registerModel(model: ModelDefinition): void;
+  getRepository(modelName: string, scopeContext?: ScopeContext): Repository;
+  createRepository(model: ModelDefinition, scopeContext?: ScopeContext): Repository;
+  query(modelName: string, scopeContext?: ScopeContext): QueryBuilder;
+  transaction<T>(callback: (ctx: TransactionContext) => Promise<T>): Promise<T>;
+  createSeeder(): unknown;
+  destroy(): Promise<void>;
+}
+
+export function createDatabase(config: DatabaseConfig): DatabaseInstance;
+
+// --- ORM: nanoid / zod ---
+
+export function generateNanoid(options?: { maxLength?: number } | number): string;
+
+export const zodNanoid: ZodTypeAny;
+
+export function extendZ(z: typeof import('zod').z): typeof import('zod').z;
+
+// --- ORM: sanitize ---
+
+export function omitHiddenColumns(record: unknown, model: ModelDefinition): unknown;
+
+export function sanitizeForOutput(
+  records: unknown,
+  model: ModelDefinition
+): unknown;
+
+// --- ORM: events ---
+
+export const ModelEvents: {
+  on(event: string, handler: (...args: unknown[]) => void): void;
+  emit(event: string, ...args: unknown[]): void;
+  emitAsync?(event: string, ...args: unknown[]): Promise<void>;
+  [key: string]: unknown;
+};
+
+export const Hooks: Record<string, string>;
+
+export class HookCancellationError extends Error {
+  reason: string;
+  model: string;
+  hook: string;
+  constructor(reason: string, model: string, hook: string);
+}
+
+export function createEventContext(
+  model: string,
+  operation: string,
+  trx?: unknown | null
+): {
+  model: string;
+  operation: string;
+  trx: unknown | null;
+  isCancelled: boolean;
+  cancelReason: string | null;
+  cancel(reason?: string): void;
+};
+
+// --- Built-in plugins (subset re-exported from main index.js) ---
+
+export function schemaExplorerPlugin(options?: Record<string, unknown>): WebspressoPlugin;
+
+export function adminPanelPlugin(options?: Record<string, unknown>): WebspressoPlugin;
+
+export function siteAnalyticsPlugin(options?: Record<string, unknown>): WebspressoPlugin;
+
+export function auditLogPlugin(options?: Record<string, unknown>): WebspressoPlugin;
+
+export function recaptchaPlugin(options?: Record<string, unknown>): WebspressoPlugin;
+
+export function swaggerPlugin(options?: Record<string, unknown>): WebspressoPlugin;
+
+export function healthCheckPlugin(options?: Record<string, unknown>): WebspressoPlugin;
+
+export interface RestResourcePluginOptions {
+  path?: string;
+  middleware?: RequestHandler[];
+  models?: string[] | null;
+  excludeModels?: string[];
+  filter?: (model: ModelDefinition) => boolean;
+}
+
+export function restResourcePlugin(options?: RestResourcePluginOptions): WebspressoPlugin;

package/index.js

@@ -38,7 +38,7 @@ const {
 const orm = require('./core/orm');
 
 // Built-in plugins
-const { schemaExplorerPlugin, adminPanelPlugin, siteAnalyticsPlugin, auditLogPlugin, recaptchaPlugin, swaggerPlugin, healthCheckPlugin } = require('./plugins');
+const { schemaExplorerPlugin, adminPanelPlugin, siteAnalyticsPlugin, auditLogPlugin, recaptchaPlugin, swaggerPlugin, healthCheckPlugin, restResourcePlugin } = require('./plugins');
 
 module.exports = {
   // Main API
@@ -89,4 +89,5 @@ module.exports = {
   recaptchaPlugin,
   swaggerPlugin,
   healthCheckPlugin,
+  restResourcePlugin,
 };

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "webspresso",
-  "version": "0.0.63",
+  "version": "0.0.64",
   "description": "Minimal, production-ready SSR framework for Node.js with file-based routing, Nunjucks templating, built-in i18n, and CLI tooling",
   "main": "index.js",
+  "types": "index.d.ts",
   "bin": {
     "webspresso": "./bin/webspresso.js"
   },
@@ -14,6 +15,7 @@
     "test:e2e:ui": "playwright test --ui",
     "test:e2e:debug": "playwright test --debug",
     "test:e2e:headed": "playwright test --headed",
+    "check:types": "tsc --project tests/ts-smoke/tsconfig.json",
     "release": "release-it"
   },
   "keywords": [
@@ -34,6 +36,7 @@
   },
   "files": [
     "index.js",
+    "index.d.ts",
     "bin/",
     "src/",
     "utils/",
@@ -82,6 +85,8 @@
     }
   },
   "devDependencies": {
+    "@types/express": "^4.17.21",
+    "@types/node": "^20.14.0",
     "@faker-js/faker": "^9.9.0",
     "@playwright/test": "^1.48.0",
     "@vitest/coverage-v8": "^3.0.0",
@@ -90,6 +95,7 @@
     "dotenv": "^16.3.1",
     "release-it": "^19.0.0",
     "supertest": "^6.3.4",
+    "typescript": "~5.6.3",
     "vitest": "^3.0.0"
   },
   "engines": {