webspresso 0.0.57 → 0.0.60

package/core/openapi/build-from-api-routes.js

@@ -0,0 +1,172 @@
+/**
+ * Build OpenAPI 3 document from file-router API route metadata + Zod schemas
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { zodToJsonSchema } = require('zod-to-json-schema');
+const { compileSchema } = require('../compileSchema');
+const { generateOrmOpenApiSchemas } = require('./orm-components');
+
+/**
+ * Express route pattern → OpenAPI path (e.g. /users/:id → /users/{id})
+ * @param {string} expressPath
+ * @returns {string}
+ */
+function expressPathToOpenApi(expressPath) {
+  return String(expressPath)
+    .replace(/:([A-Za-z0-9_]+)/g, '{$1}')
+    .replace(/\*/g, '{wildcard}');
+}
+
+/**
+ * @param {import('zod').ZodObject<any>} zodObj
+ * @param {'path' | 'query'} where
+ * @returns {object[]}
+ */
+function expandZodObjectToParameters(zodObj, where) {
+  if (!zodObj || zodObj._def?.typeName !== 'ZodObject') return [];
+  const shape = zodObj.shape;
+  return Object.entries(shape).map(([name, zType]) => ({
+    name,
+    in: where,
+    required: where === 'path' ? true : !zType.isOptional(),
+    schema: zodToJsonSchema(zType, { target: 'openApi3', $refStrategy: 'none' }),
+  }));
+}
+
+/**
+ * @param {object} route - { type, method, pattern, file }
+ * @param {object|null} compiled - compileSchema result
+ * @returns {object} OpenAPI Operation Object
+ */
+function buildOperation(route, compiled) {
+  const filePath = route.file;
+  const method = route.method.toLowerCase();
+  const summary = `${method.toUpperCase()} ${filePath}`;
+
+  const op = {
+    tags: ['api'],
+    summary,
+    operationId: String(filePath)
+      .replace(/[^a-zA-Z0-9]+/g, '_')
+      .replace(/^_|_$/g, ''),
+    responses: {
+      200: {
+        description: 'OK',
+      },
+    },
+  };
+
+  if (compiled?.response) {
+    op.responses['200'] = {
+      description: 'OK',
+      content: {
+        'application/json': {
+          schema: zodToJsonSchema(compiled.response, { target: 'openApi3', $refStrategy: 'none' }),
+        },
+      },
+    };
+  }
+
+  const parameters = [
+    ...expandZodObjectToParameters(compiled?.params, 'path'),
+    ...expandZodObjectToParameters(compiled?.query, 'query'),
+  ];
+
+  if (parameters.length) {
+    op.parameters = parameters;
+  }
+
+  if (compiled?.body) {
+    op.requestBody = {
+      content: {
+        'application/json': {
+          schema: zodToJsonSchema(compiled.body, { target: 'openApi3', $refStrategy: 'none' }),
+        },
+      },
+    };
+  }
+
+  return op;
+}
+
+/**
+ * @param {object} opts
+ * @param {object[]} opts.routes - route metadata from mountPages
+ * @param {string} opts.pagesDir
+ * @param {boolean} [opts.includeOrmSchemas]
+ * @param {string[]} [opts.ormExclude]
+ * @param {object} [opts.info]
+ * @param {object[]} [opts.servers]
+ * @returns {object} OpenAPI 3.0.x document
+ */
+function buildOpenApiDocument(opts) {
+  const {
+    routes = [],
+    pagesDir,
+    includeOrmSchemas = false,
+    ormExclude = [],
+    info = {},
+    servers = [{ url: '/' }],
+  } = opts;
+
+  if (!pagesDir) {
+    throw new Error('buildOpenApiDocument: pagesDir is required');
+  }
+
+  const paths = {};
+  const apiRoutes = routes.filter((r) => r.type === 'api');
+  const absPages = path.resolve(pagesDir);
+
+  for (const route of apiRoutes) {
+    const fullPath = path.join(absPages, route.file);
+    if (!fs.existsSync(fullPath)) {
+      continue;
+    }
+
+    let mod;
+    try {
+      mod = require(fullPath);
+    } catch {
+      continue;
+    }
+
+    let compiled = null;
+    try {
+      compiled = compileSchema(fullPath, mod);
+    } catch {
+      compiled = null;
+    }
+
+    const openApiPath = expressPathToOpenApi(route.pattern);
+    const method = route.method.toLowerCase();
+
+    if (!paths[openApiPath]) {
+      paths[openApiPath] = {};
+    }
+
+    paths[openApiPath][method] = buildOperation(route, compiled);
+  }
+
+  const doc = {
+    openapi: '3.0.3',
+    info: {
+      title: info.title || 'API',
+      version: info.version || '1.0.0',
+      ...(info.description ? { description: info.description } : {}),
+    },
+    servers,
+    paths,
+    components: {
+      schemas: includeOrmSchemas ? generateOrmOpenApiSchemas({ exclude: ormExclude }) : {},
+    },
+  };
+
+  return doc;
+}
+
+module.exports = {
+  expressPathToOpenApi,
+  buildOpenApiDocument,
+};

package/core/openapi/orm-components.js

@@ -0,0 +1,139 @@
+/**
+ * ORM column → OpenAPI schema fragments (shared by schema-explorer and swagger plugin)
+ */
+
+const { getAllModels } = require('../orm/model');
+
+/**
+ * Generate OpenAPI 3 components.schemas from registered ORM models
+ * @param {{ exclude?: string[] }} options
+ * @returns {Record<string, object>}
+ */
+function generateOrmOpenApiSchemas(options = {}) {
+  const { exclude = [] } = options;
+  const models = getAllModels();
+  const schemas = {};
+
+  for (const [name, model] of models) {
+    if (exclude.includes(name)) continue;
+
+    const properties = {};
+    const required = [];
+
+    if (model.columns) {
+      for (const [colName, meta] of model.columns) {
+        properties[colName] = columnToOpenApiType(meta);
+
+        if (!meta.nullable && !meta.autoIncrement && meta.default === undefined) {
+          required.push(colName);
+        }
+      }
+    }
+
+    schemas[name] = {
+      type: 'object',
+      properties,
+      required: required.length > 0 ? required : undefined,
+    };
+
+    const inputProperties = {};
+    const inputRequired = [];
+
+    if (model.columns) {
+      for (const [colName, meta] of model.columns) {
+        if (meta.autoIncrement || meta.auto) continue;
+
+        inputProperties[colName] = columnToOpenApiType(meta);
+
+        if (!meta.nullable && meta.default === undefined) {
+          inputRequired.push(colName);
+        }
+      }
+    }
+
+    schemas[`${name}Input`] = {
+      type: 'object',
+      properties: inputProperties,
+      required: inputRequired.length > 0 ? inputRequired : undefined,
+    };
+  }
+
+  return schemas;
+}
+
+/**
+ * @param {Object} meta - Column metadata
+ * @returns {Object}
+ */
+function columnToOpenApiType(meta) {
+  const result = {};
+
+  switch (meta.type) {
+    case 'bigint':
+    case 'integer':
+      result.type = 'integer';
+      if (meta.type === 'bigint') result.format = 'int64';
+      break;
+
+    case 'float':
+    case 'decimal':
+      result.type = 'number';
+      if (meta.type === 'decimal') result.format = 'double';
+      break;
+
+    case 'boolean':
+      result.type = 'boolean';
+      break;
+
+    case 'date':
+      result.type = 'string';
+      result.format = 'date';
+      break;
+
+    case 'datetime':
+    case 'timestamp':
+      result.type = 'string';
+      result.format = 'date-time';
+      break;
+
+    case 'uuid':
+      result.type = 'string';
+      result.format = 'uuid';
+      break;
+
+    case 'json':
+      result.type = 'object';
+      break;
+
+    case 'enum':
+      result.type = 'string';
+      if (meta.enumValues) {
+        result.enum = meta.enumValues;
+      }
+      break;
+
+    case 'text':
+    case 'string':
+    default:
+      result.type = 'string';
+      if (meta.maxLength) {
+        result.maxLength = meta.maxLength;
+      }
+      break;
+  }
+
+  if (meta.nullable) {
+    result.nullable = true;
+  }
+
+  if (meta.default !== undefined) {
+    result.default = meta.default;
+  }
+
+  return result;
+}
+
+module.exports = {
+  generateOrmOpenApiSchemas,
+  columnToOpenApiType,
+};

package/core/orm/index.js

@@ -186,7 +186,7 @@ function createDatabase(config) {
    * Get query builder for a model
    * @param {string} modelName - Model name
    * @param {import('./types').ScopeContext} [scopeContext] - Scope context
-   * @returns {import('knex').Knex.QueryBuilder}
+   * @returns {import('./query-builder').QueryBuilder}
    */
   function query(modelName, scopeContext) {
     const model = getModelInstance(modelName);

package/core/orm/json-fields.js

@@ -0,0 +1,70 @@
+/**
+ * Webspresso ORM - JSON column helpers (shared by repository and query builder)
+ * @module core/orm/json-fields
+ */
+
+/**
+ * Get JSON column names from model
+ * @param {import('./types').ModelDefinition} model - Model definition
+ * @returns {Set<string>} Set of JSON column names
+ */
+function getJsonColumns(model) {
+  const jsonCols = new Set();
+  if (model.columns) {
+    for (const [name, meta] of model.columns) {
+      if (meta.type === 'json') {
+        jsonCols.add(name);
+      }
+    }
+  }
+  return jsonCols;
+}
+
+/**
+ * Serialize JSON fields for database storage
+ * @param {Object} data - Data to serialize
+ * @param {Set<string>} jsonColumns - JSON column names
+ * @returns {Object} Serialized data
+ */
+function serializeJsonFields(data, jsonColumns) {
+  if (jsonColumns.size === 0) return data;
+
+  const serialized = { ...data };
+  for (const col of jsonColumns) {
+    if (col in serialized && serialized[col] !== null && serialized[col] !== undefined) {
+      if (typeof serialized[col] !== 'string') {
+        serialized[col] = JSON.stringify(serialized[col]);
+      }
+    }
+  }
+  return serialized;
+}
+
+/**
+ * Deserialize JSON fields from database
+ * @param {Object} record - Record from database
+ * @param {Set<string>} jsonColumns - JSON column names
+ * @returns {Object} Deserialized record
+ */
+function deserializeJsonFields(record, jsonColumns) {
+  if (!record || jsonColumns.size === 0) return record;
+
+  for (const col of jsonColumns) {
+    if (col in record && record[col] !== null && record[col] !== undefined) {
+      if (typeof record[col] === 'string') {
+        try {
+          record[col] = JSON.parse(record[col]);
+        } catch {
+          // If parsing fails, keep the original string value
+        }
+      }
+    }
+  }
+  return record;
+}
+
+module.exports = {
+  getJsonColumns,
+  serializeJsonFields,
+  deserializeJsonFields,
+};

package/core/orm/query-builder.js

@@ -5,66 +5,14 @@
  */
 
 const { applyScopes, createScopeContext } = require('./scopes');
-
-/**
- * Get JSON column names from model
- * @param {import('./types').ModelDefinition} model - Model definition
- * @returns {Set<string>} Set of JSON column names
- */
-function getJsonColumns(model) {
-  const jsonCols = new Set();
-  if (model.columns) {
-    for (const [name, meta] of model.columns) {
-      if (meta.type === 'json') {
-        jsonCols.add(name);
-      }
-    }
-  }
-  return jsonCols;
-}
-
-/**
- * Serialize JSON fields for database storage
- * @param {Object} data - Data to serialize
- * @param {Set<string>} jsonColumns - JSON column names
- * @returns {Object} Serialized data
- */
-function serializeJsonFields(data, jsonColumns) {
-  if (jsonColumns.size === 0) return data;
-  
-  const serialized = { ...data };
-  for (const col of jsonColumns) {
-    if (col in serialized && serialized[col] !== null && serialized[col] !== undefined) {
-      if (typeof serialized[col] !== 'string') {
-        serialized[col] = JSON.stringify(serialized[col]);
-      }
-    }
-  }
-  return serialized;
-}
-
-/**
- * Deserialize JSON fields from database
- * @param {Object} record - Record from database
- * @param {Set<string>} jsonColumns - JSON column names
- * @returns {Object} Deserialized record
- */
-function deserializeJsonFields(record, jsonColumns) {
-  if (!record || jsonColumns.size === 0) return record;
-  
-  for (const col of jsonColumns) {
-    if (col in record && record[col] !== null && record[col] !== undefined) {
-      if (typeof record[col] === 'string') {
-        try {
-          record[col] = JSON.parse(record[col]);
-        } catch {
-          // If parsing fails, keep the original string value
-        }
-      }
-    }
-  }
-  return record;
-}
+const { loadRelations } = require('./eager-loader');
+const { ensureArray } = require('./utils');
+const { ModelEvents, createEventContext, Hooks, HookCancellationError } = require('./events');
+const {
+  getJsonColumns,
+  serializeJsonFields,
+  deserializeJsonFields,
+} = require('./json-fields');
 
 /**
  * Create a new query builder
@@ -92,7 +40,7 @@ class QueryBuilder {
     this.knex = knex;
     this.scopeContext = initialContext || createScopeContext();
     this.jsonColumns = getJsonColumns(model);
-    
+
     /** @type {import('./types').QueryState} */
     this.state = {
       wheres: [],
@@ -167,7 +115,7 @@ class QueryBuilder {
   orWhere(columnOrConditions, operatorOrValue, value) {
     const startIndex = this.state.wheres.length;
     this.where(columnOrConditions, operatorOrValue, value);
-    
+
     // Mark the new clauses as OR
     for (let i = startIndex; i < this.state.wheres.length; i++) {
       this.state.wheres[i].boolean = 'or';
@@ -338,11 +286,22 @@ class QueryBuilder {
     return this;
   }
 
+  /**
+   * Transaction handle for lifecycle hooks (matches repository pattern)
+   * @returns {import('knex').Knex.Transaction|null}
+   */
+  _hookTrx() {
+    return this.knex.isTransaction ? this.knex : null;
+  }
+
   /**
    * Build the Knex query
+   * @param {Object} [options]
+   * @param {boolean} [options.includeLimitOffset=true] - When false, omit LIMIT/OFFSET (for aggregates / pagination)
    * @returns {import('knex').Knex.QueryBuilder}
    */
-  toKnex() {
+  toKnex(options = {}) {
+    const { includeLimitOffset = true } = options;
     let qb = this.knex(this.model.table);
 
     // Apply global scopes
@@ -364,10 +323,10 @@ class QueryBuilder {
       }
 
       const method = where.boolean === 'or' ? 'orWhere' : 'where';
-      
+
       switch (where.operator) {
         case 'in':
-          qb = where.boolean === 'or' 
+          qb = where.boolean === 'or'
             ? qb.orWhereIn(where.column, where.value)
             : qb.whereIn(where.column, where.value);
           break;
@@ -396,14 +355,16 @@ class QueryBuilder {
       qb = qb.orderBy(orderBy.column, orderBy.direction);
     }
 
-    // Apply limit
-    if (this.state.limitValue !== undefined) {
-      qb = qb.limit(this.state.limitValue);
-    }
+    if (includeLimitOffset) {
+      // Apply limit
+      if (this.state.limitValue !== undefined) {
+        qb = qb.limit(this.state.limitValue);
+      }
 
-    // Apply offset
-    if (this.state.offsetValue !== undefined) {
-      qb = qb.offset(this.state.offsetValue);
+      // Apply offset
+      if (this.state.offsetValue !== undefined) {
+        qb = qb.offset(this.state.offsetValue);
+      }
     }
 
     return qb;
@@ -414,12 +375,24 @@ class QueryBuilder {
    * @returns {Promise<Object|null>}
    */
   async first() {
+    const ctx = createEventContext(this.model.name, 'find', this._hookTrx());
+    await ModelEvents.emitAsync(this.model.name, Hooks.BEFORE_FIND, {}, ctx);
+    if (ctx.isCancelled) {
+      throw new HookCancellationError(ctx.cancelReason, this.model.name, Hooks.BEFORE_FIND);
+    }
+
     const qb = this.toKnex().first();
     const result = await qb;
     if (!result) return null;
-    
-    // Deserialize JSON fields
+
     deserializeJsonFields(result, this.jsonColumns);
+
+    const withs = this.getWiths();
+    if (withs.length > 0) {
+      await loadRelations([result], ensureArray(withs), this.model, this.knex, this.scopeContext);
+    }
+
+    ModelEvents.emit(this.model.name, Hooks.AFTER_FIND, result, ctx);
     return result;
   }
 
@@ -428,12 +401,26 @@ class QueryBuilder {
    * @returns {Promise<Object[]>}
    */
   async list() {
+    const ctx = createEventContext(this.model.name, 'find', this._hookTrx());
+    await ModelEvents.emitAsync(this.model.name, Hooks.BEFORE_FIND, {}, ctx);
+    if (ctx.isCancelled) {
+      throw new HookCancellationError(ctx.cancelReason, this.model.name, Hooks.BEFORE_FIND);
+    }
+
     const results = await this.toKnex();
-    
-    // Deserialize JSON fields
+
     for (const record of results) {
       deserializeJsonFields(record, this.jsonColumns);
     }
+
+    const withs = this.getWiths();
+    if (withs.length > 0 && results.length > 0) {
+      await loadRelations(results, ensureArray(withs), this.model, this.knex, this.scopeContext);
+    }
+
+    for (const record of results) {
+      ModelEvents.emit(this.model.name, Hooks.AFTER_FIND, record, ctx);
+    }
     return results;
   }
 
@@ -450,7 +437,7 @@ class QueryBuilder {
    * @returns {Promise<number>}
    */
   async count() {
-    const result = await this.toKnex().count('* as count').first();
+    const result = await this.toKnex({ includeLimitOffset: false }).count('* as count').first();
     return parseInt(result?.count || 0, 10);
   }
 
@@ -470,22 +457,33 @@ class QueryBuilder {
    * @returns {Promise<import('./types').PaginatedResult>}
    */
   async paginate(page = 1, perPage = 15) {
-    // Clone state for count query
-    const countQb = this.toKnex().clone();
-    
-    // Get total count
-    const countResult = await countQb.count('* as count').first();
+    const ctx = createEventContext(this.model.name, 'find', this._hookTrx());
+    await ModelEvents.emitAsync(this.model.name, Hooks.BEFORE_FIND, {}, ctx);
+    if (ctx.isCancelled) {
+      throw new HookCancellationError(ctx.cancelReason, this.model.name, Hooks.BEFORE_FIND);
+    }
+
+    const base = this.toKnex({ includeLimitOffset: false });
+
+    const countResult = await base.clone().count('* as count').first();
     const total = parseInt(countResult?.count || 0, 10);
 
-    // Get paginated data
     const offset = (page - 1) * perPage;
-    const data = await this.toKnex().limit(perPage).offset(offset);
+    const data = await base.clone().limit(perPage).offset(offset);
 
-    // Deserialize JSON fields
     for (const record of data) {
       deserializeJsonFields(record, this.jsonColumns);
     }
 
+    const withs = this.getWiths();
+    if (withs.length > 0 && data.length > 0) {
+      await loadRelations(data, ensureArray(withs), this.model, this.knex, this.scopeContext);
+    }
+
+    for (const record of data) {
+      ModelEvents.emit(this.model.name, Hooks.AFTER_FIND, record, ctx);
+    }
+
     return {
       data,
       total,
@@ -509,7 +507,6 @@ class QueryBuilder {
    * @returns {Promise<number>} Number of updated records
    */
   async update(data) {
-    // Serialize JSON fields
     const serialized = serializeJsonFields(data, this.jsonColumns);
     return this.toKnex().update(serialized);
   }
@@ -554,4 +551,3 @@ module.exports = {
   createQueryBuilder,
   QueryBuilder,
 };
-