webspresso 0.0.97 → 0.0.99

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

@@ -1,5 +1,8 @@
+'use strict';
+
 /**
  * Build OpenAPI 3 document from file-router API route metadata + Zod schemas
+ * @module core/openapi/build-from-api-routes
  */
 
 const fs = require('fs');
@@ -16,11 +19,81 @@ const OPENAPI_METHODS = new Set(['get', 'post', 'put', 'patch', 'delete', 'head'
  * @returns {string}
  */
 function expressPathToOpenApi(expressPath) {
+  if (!expressPath) return '';
   return String(expressPath)
     .replace(/:([A-Za-z0-9_]+)/g, '{$1}')
+    .replace(/\[([A-Za-z0-9_]+)\]/g, '{$1}')
     .replace(/\*/g, '{wildcard}');
 }
 
+/**
+ * Resolves the physical file path of an API route descriptor
+ * @param {Object} route
+ * @param {string} [pagesDir]
+ * @returns {string|null}
+ */
+function resolveRouteFilePath(route, pagesDir) {
+  const rawFile = route.file || route.source;
+  if (!rawFile) return null;
+
+  if (path.isAbsolute(rawFile) && fs.existsSync(rawFile)) {
+    return rawFile;
+  }
+
+  const fromCwd = path.resolve(process.cwd(), rawFile);
+  if (fs.existsSync(fromCwd)) {
+    return fromCwd;
+  }
+
+  if (pagesDir) {
+    const fromPages = path.join(path.resolve(pagesDir), rawFile);
+    if (fs.existsSync(fromPages)) {
+      return fromPages;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Infers an expressive operation summary from HTTP method and path
+ * @param {string} method
+ * @param {string} routePath
+ * @returns {string}
+ */
+function inferOperationSummary(method, routePath) {
+  const clean = String(routePath || '').replace(/^\/api\/?/, '').replace(/\/$/, '');
+  const segments = clean.split('/').filter(Boolean);
+  const lastSeg = segments[segments.length - 1] || 'root';
+  const isParam = lastSeg.startsWith(':') || (lastSeg.startsWith('{') && lastSeg.endsWith('}')) || (lastSeg.startsWith('[') && lastSeg.endsWith(']'));
+  const resource = isParam && segments.length > 1 ? segments[segments.length - 2] : lastSeg;
+  const m = String(method || 'GET').toUpperCase();
+
+  if (m === 'GET') {
+    return isParam ? `Get ${resource} by ID` : `List ${resource}`;
+  }
+  if (m === 'POST') return `Create ${resource}`;
+  if (m === 'PUT' || m === 'PATCH') return `Update ${resource}`;
+  if (m === 'DELETE') return `Delete ${resource}`;
+  return `${m} /api/${clean}`;
+}
+
+/**
+ * Infers tag category from route path segments
+ * @param {string} routePath
+ * @param {string[]} [explicitTags]
+ * @returns {string[]}
+ */
+function inferOperationTags(routePath, explicitTags) {
+  if (Array.isArray(explicitTags) && explicitTags.length > 0) return explicitTags;
+  const clean = String(routePath || '').replace(/^\/api\/?/, '').replace(/\/$/, '');
+  const firstSeg = clean.split('/').filter(Boolean)[0];
+  if (firstSeg && !firstSeg.startsWith(':') && !firstSeg.startsWith('{') && !firstSeg.startsWith('[')) {
+    return [firstSeg];
+  }
+  return ['api'];
+}
+
 /**
  * @param {import('zod').ZodObject<any>} zodObj
  * @param {'path' | 'query'} where
@@ -38,19 +111,31 @@ function expandZodObjectToParameters(zodObj, where) {
 }
 
 /**
- * @param {object} route - { type, method, pattern, file }
+ * @param {object} route - { type, method, pattern, path, file }
  * @param {object|null} compiled - compileSchema result
+ * @param {object|null} [mod] - Raw route module
  * @returns {object} OpenAPI Operation Object
  */
-function buildOperation(route, compiled) {
-  const filePath = route.file;
-  const method = route.method.toLowerCase();
-  const summary = `${method.toUpperCase()} ${filePath}`;
+function buildOperation(route, compiled, mod = null) {
+  const filePath = route.file || route.source || '';
+  const method = (route.method || 'GET').toLowerCase();
+  const routePath = route.path || route.pattern || filePath;
+
+  let summary = (mod && (mod.summary || mod.openapi?.summary)) || route.summary;
+  if (!summary) {
+    if (filePath) {
+      summary = `${method.toUpperCase()} ${filePath}`;
+    } else {
+      summary = inferOperationSummary(method, routePath);
+    }
+  }
+
+  const tags = inferOperationTags(routePath, (mod && (mod.tags || mod.openapi?.tags)) || route.tags);
 
   const op = {
-    tags: ['api'],
+    tags,
     summary,
-    operationId: String(filePath)
+    operationId: String(filePath || routePath)
       .replace(/[^a-zA-Z0-9]+/g, '_')
       .replace(/^_|_$/g, ''),
     responses: {
@@ -60,6 +145,25 @@ function buildOperation(route, compiled) {
     },
   };
 
+  if (mod && mod.description) {
+    op.description = mod.description;
+  }
+
+  // Auth / Security detection
+  const middlewares = Array.isArray(route.middleware)
+    ? route.middleware
+    : (Array.isArray(mod?.middleware) ? mod.middleware : []);
+  const security = [];
+  if (middlewares.includes('jwt') || middlewares.includes('bearer')) {
+    security.push({ bearerAuth: [] });
+  }
+  if (middlewares.includes('auth') || middlewares.includes('session')) {
+    security.push({ sessionAuth: [] });
+  }
+  if (security.length > 0) {
+    op.security = security;
+  }
+
   if (compiled?.response) {
     op.responses['200'] = {
       description: 'OK',
@@ -94,16 +198,17 @@ function buildOperation(route, compiled) {
 }
 
 /**
+ * Builds an OpenAPI 3.0 document from application routes and ORM components
  * @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.routes - Route metadata array
+ * @param {string} opts.pagesDir - Pages directory path
+ * @param {boolean} [opts.includeOrmSchemas=false]
+ * @param {string[]} [opts.ormExclude=[]]
  * @param {object} [opts.info]
  * @param {object[]} [opts.servers]
  * @returns {object} OpenAPI 3.0.x document
  */
-function buildOpenApiDocument(opts) {
+function buildOpenApiDocument(opts = {}) {
   const {
     routes = [],
     pagesDir,
@@ -118,31 +223,39 @@ function buildOpenApiDocument(opts) {
   }
 
   const paths = Object.create(null);
-  const apiRoutes = routes.filter((r) => r.type === 'api');
-  const absPages = path.resolve(pagesDir);
+  const apiRoutes = routes.filter((r) => r.type === 'api' || (r.path && r.path.startsWith('/api')));
 
   for (const route of apiRoutes) {
-    const fullPath = path.join(absPages, route.file);
-    if (!fs.existsSync(fullPath)) {
-      continue;
-    }
+    const fullPath = resolveRouteFilePath(route, pagesDir);
 
-    let mod;
-    try {
-      mod = require(fullPath);
-    } catch {
+    if (route.file && !fullPath) {
       continue;
     }
 
+    let mod = null;
     let compiled = null;
-    try {
-      compiled = compileSchema(fullPath, mod);
-    } catch {
-      compiled = null;
+
+    if (fullPath) {
+      try {
+        mod = require(fullPath);
+      } catch {
+        mod = null;
+      }
+
+      if (mod) {
+        try {
+          compiled = compileSchema(fullPath, mod);
+        } catch {
+          compiled = null;
+        }
+      }
     }
 
-    const openApiPath = expressPathToOpenApi(route.pattern);
-    const method = route.method.toLowerCase();
+    const routePattern = route.path || route.pattern || '';
+    if (!routePattern) continue;
+
+    const openApiPath = expressPathToOpenApi(routePattern);
+    const method = (route.method || 'GET').toLowerCase();
 
     if (!OPENAPI_METHODS.has(method)) {
       continue;
@@ -152,7 +265,7 @@ function buildOpenApiDocument(opts) {
       paths[openApiPath] = Object.create(null);
     }
 
-    paths[openApiPath][method] = buildOperation(route, compiled);
+    paths[openApiPath][method] = buildOperation(route, compiled, mod);
   }
 
   const doc = {
@@ -165,6 +278,20 @@ function buildOpenApiDocument(opts) {
     servers,
     paths,
     components: {
+      securitySchemes: {
+        bearerAuth: {
+          type: 'http',
+          scheme: 'bearer',
+          bearerFormat: 'JWT',
+          description: 'Stateless JWT Bearer token authentication',
+        },
+        sessionAuth: {
+          type: 'apiKey',
+          in: 'cookie',
+          name: 'connect.sid',
+          description: 'Session cookie authentication',
+        },
+      },
       schemas: includeOrmSchemas ? generateOrmOpenApiSchemas({ exclude: ormExclude }) : {},
     },
   };
@@ -174,5 +301,9 @@ function buildOpenApiDocument(opts) {
 
 module.exports = {
   expressPathToOpenApi,
+  resolveRouteFilePath,
+  inferOperationSummary,
+  inferOperationTags,
+  buildOperation,
   buildOpenApiDocument,
 };

package/core/orm/cache/fingerprint.js

@@ -28,7 +28,21 @@ function stableValue(v) {
     const k = keys[0];
     return { [k]: stableValue(v[k]) };
   }
-  keys.sort();
+  if (keyLen === 2) {
+    const k0 = keys[0];
+    const k1 = keys[1];
+    return k0 < k1
+      ? { [k0]: stableValue(v[k0]), [k1]: stableValue(v[k1]) }
+      : { [k1]: stableValue(v[k1]), [k0]: stableValue(v[k0]) };
+  }
+  let isSorted = true;
+  for (let i = 1; i < keyLen; i++) {
+    if (keys[i - 1] > keys[i]) {
+      isSorted = false;
+      break;
+    }
+  }
+  if (!isSorted) keys.sort();
   const out = {};
   for (let i = 0; i < keyLen; i++) {
     const k = keys[i];

package/core/orm/cache/memory-provider.js

@@ -56,8 +56,20 @@ function createMemoryCacheProvider(options = {}) {
     if (store.has(key)) removeKey(key);
 
     if (maxEntries > 0 && store.size >= maxEntries) {
-      const first = store.keys().next().value;
-      if (first !== undefined) removeKey(first);
+      // Active sweep: evict expired entries before falling back to FIFO eviction
+      const now = Date.now();
+      let freed = 0;
+      for (const [k, entry] of store.entries()) {
+        if (entry.expiresAt > 0 && now > entry.expiresAt) {
+          removeKey(k);
+          freed++;
+          if (freed >= 10 || store.size < maxEntries) break;
+        }
+      }
+      if (store.size >= maxEntries) {
+        const first = store.keys().next().value;
+        if (first !== undefined) removeKey(first);
+      }
     }
 
     const expiresAt = ttlMs > 0 ? Date.now() + ttlMs : 0;
@@ -82,6 +94,18 @@ function createMemoryCacheProvider(options = {}) {
     for (const t of tags) tagToKeys.delete(t);
   }
 
+  function pruneExpired() {
+    const now = Date.now();
+    let count = 0;
+    for (const [k, entry] of store.entries()) {
+      if (entry.expiresAt > 0 && now > entry.expiresAt) {
+        removeKey(k);
+        count++;
+      }
+    }
+    return count;
+  }
+
   function clear() {
     store.clear();
     tagToKeys.clear();
@@ -99,6 +123,7 @@ function createMemoryCacheProvider(options = {}) {
     get,
     set,
     invalidateTags,
+    pruneExpired,
     clear,
     getSizeStats,
   };

package/core/orm/eager-loader.js

@@ -1,31 +1,109 @@
 /**
  * Webspresso ORM - Eager Loader
- * Batch loading algorithm for relations
+ * Batch loading algorithm for relations (supports direct & arbitrary nested relations)
  * @module core/orm/eager-loader
  */
 
 const { resolveRelationModel, getRelationKeys } = require('./model');
 const { applyScopes, createScopeContext } = require('./scopes');
+const { getJsonColumns, deserializeJsonFields } = require('./json-fields');
 
 /**
- * Load relations for a set of records using batch queries
+ * Parse relation specifications into a grouped structure: Map<topLevelRelation, string[]>
+ * Supports dot notation ('author.profile'), arrays (['author', 'comments.author']),
+ * and nested relation chains of arbitrary depth.
+ * 
+ * @param {Array<string|Object>} relationNames
+ * @returns {Map<string, string[]>}
+ */
+function parseRelationTree(relationNames) {
+  const tree = new Map();
+
+  function addPath(top, nested) {
+    if (!top || typeof top !== 'string') return;
+    const cleanTop = top.trim();
+    if (!cleanTop) return;
+
+    if (!tree.has(cleanTop)) {
+      tree.set(cleanTop, []);
+    }
+    if (nested) {
+      if (Array.isArray(nested)) {
+        for (const item of nested) {
+          if (item && typeof item === 'string') tree.get(cleanTop).push(item.trim());
+        }
+      } else if (typeof nested === 'string') {
+        const cleanNested = nested.trim();
+        if (cleanNested) tree.get(cleanTop).push(cleanNested);
+      }
+    }
+  }
+
+  function processItem(item) {
+    if (!item) return;
+
+    if (typeof item === 'string') {
+      const dotIndex = item.indexOf('.');
+      if (dotIndex === -1) {
+        addPath(item);
+      } else {
+        const top = item.slice(0, dotIndex);
+        const rest = item.slice(dotIndex + 1);
+        addPath(top, rest);
+      }
+    } else if (Array.isArray(item)) {
+      for (const sub of item) {
+        processItem(sub);
+      }
+    } else if (typeof item === 'object') {
+      for (const [key, value] of Object.entries(item)) {
+        if (value === true || value == null) {
+          processItem(key);
+        } else if (typeof value === 'string' || Array.isArray(value)) {
+          const dotIndex = key.indexOf('.');
+          if (dotIndex === -1) {
+            addPath(key, value);
+          } else {
+            const top = key.slice(0, dotIndex);
+            const rest = key.slice(dotIndex + 1);
+            const nestedValues = Array.isArray(value) ? value : [value];
+            for (const v of nestedValues) {
+              addPath(top, `${rest}.${v}`);
+            }
+          }
+        }
+      }
+    }
+  }
+
+  const list = Array.isArray(relationNames) ? relationNames : [relationNames];
+  for (const item of list) {
+    processItem(item);
+  }
+
+  return tree;
+}
+
+/**
+ * Load relations for a set of records using batch queries (supports nested relations)
  * @param {Object[]} records - Records to load relations for
- * @param {string[]} relationNames - Names of relations to load
+ * @param {Array<string|Object>} relationNames - Names of relations to load (e.g. ['author.profile', 'comments.author'])
  * @param {import('./types').ModelDefinition} model - Model definition
  * @param {import('knex').Knex|import('knex').Knex.Transaction} knex - Knex instance
  * @param {import('./types').ScopeContext} [scopeContext] - Scope context
  * @returns {Promise<Object[]>} Records with relations attached
  */
 async function loadRelations(records, relationNames, model, knex, scopeContext) {
-  if (!records.length || !relationNames.length) {
+  if (!records || !records.length || !relationNames || !relationNames.length) {
     return records;
   }
 
   const context = scopeContext || createScopeContext();
+  const tree = parseRelationTree(relationNames);
 
-  // Process each relation
-  for (const relationName of relationNames) {
-    const relation = model.relations[relationName];
+  // Process each relation grouped by top-level
+  for (const [relationName, nestedPaths] of tree.entries()) {
+    const relation = model.relations?.[relationName];
     if (!relation) {
       console.warn(`Relation "${relationName}" not found on model "${model.name}"`);
       continue;
@@ -43,6 +121,38 @@ async function loadRelations(records, relationNames, model, knex, scopeContext)
       case 'hasOne':
         await loadHasOne(records, relationName, localKey, foreignKey, relatedModel, knex, context);
         break;
+      default:
+        console.warn(`Unsupported relation type "${relation.type}" for relation "${relationName}" on model "${model.name}"`);
+        continue;
+    }
+
+    // Process nested relations if any
+    if (nestedPaths.length > 0) {
+      const childRecords = [];
+      const seenRefs = new Set();
+      const len = records.length;
+
+      for (let i = 0; i < len; i++) {
+        const child = records[i][relationName];
+        if (!child) continue;
+
+        if (Array.isArray(child)) {
+          for (let j = 0; j < child.length; j++) {
+            const item = child[j];
+            if (item && typeof item === 'object' && !seenRefs.has(item)) {
+              seenRefs.add(item);
+              childRecords.push(item);
+            }
+          }
+        } else if (typeof child === 'object' && !seenRefs.has(child)) {
+          seenRefs.add(child);
+          childRecords.push(child);
+        }
+      }
+
+      if (childRecords.length > 0) {
+        await loadRelations(childRecords, nestedPaths, relatedModel, knex, context);
+      }
     }
   }
 
@@ -116,6 +226,14 @@ async function loadBelongsTo(records, relationName, localKey, foreignKey, relate
     relatedModel
   );
 
+  const jsonCols = getJsonColumns(relatedModel);
+  if (jsonCols.size > 0) {
+    const rLen = relatedRecords.length;
+    for (let i = 0; i < rLen; i++) {
+      deserializeJsonFields(relatedRecords[i], jsonCols);
+    }
+  }
+
   const relatedMap = new Map();
   const rLen = relatedRecords.length;
   const pk = relatedModel.primaryKey;
@@ -171,6 +289,14 @@ async function loadHasMany(records, relationName, localKey, foreignKey, relatedM
     relatedModel
   );
 
+  const jsonCols = getJsonColumns(relatedModel);
+  if (jsonCols.size > 0) {
+    const rLen = relatedRecords.length;
+    for (let i = 0; i < rLen; i++) {
+      deserializeJsonFields(relatedRecords[i], jsonCols);
+    }
+  }
+
   const relatedGroups = new Map();
   const rLen = relatedRecords.length;
   for (let i = 0; i < rLen; i++) {
@@ -229,6 +355,14 @@ async function loadHasOne(records, relationName, localKey, foreignKey, relatedMo
     relatedModel
   );
 
+  const jsonCols = getJsonColumns(relatedModel);
+  if (jsonCols.size > 0) {
+    const rLen = relatedRecords.length;
+    for (let i = 0; i < rLen; i++) {
+      deserializeJsonFields(relatedRecords[i], jsonCols);
+    }
+  }
+
   const relatedMap = new Map();
   const rLen = relatedRecords.length;
   for (let i = 0; i < rLen; i++) {
@@ -247,9 +381,9 @@ async function loadHasOne(records, relationName, localKey, foreignKey, relatedMo
 }
 
 /**
- * Load a single relation for a single record
+ * Load a single relation (or nested relation path) for a single record
  * @param {Object} record - Record to load relation for
- * @param {string} relationName - Name of relation to load
+ * @param {string} relationName - Name or dot-separated path of relation to load (e.g. 'author.profile')
  * @param {import('./types').ModelDefinition} model - Model definition
  * @param {import('knex').Knex} knex - Knex instance
  * @param {import('./types').ScopeContext} [scopeContext] - Scope context
@@ -267,5 +401,5 @@ module.exports = {
   loadHasMany,
   loadHasOne,
   queryInChunks,
+  parseRelationTree,
 };
-

package/core/orm/index.js

@@ -7,7 +7,7 @@
 const path = require('path');
 const fs = require('fs');
 const { createSchemaHelpers, extractColumnsFromSchema, getColumnMeta } = require('./schema-helpers');
-const { defineModel, getModel, getAllModels, hasModel, clearRegistry } = require('./model');
+const { defineModel, getModel, getAllModels, hasModel, clearRegistry, resolveModelName } = require('./model');
 const { createRepository } = require('./repository');
 const { createMigrationManager } = require('./migrations');
 const { createSeeder } = require('./seeder');
@@ -172,13 +172,11 @@ function createDatabase(config) {
 
   /**
    * Get a model by name
-   * @param {string|import('./types').ModelDefinition} nameOrModel - Model name or model definition
+   * @param {string|Object|import('./types').ModelDefinition} nameOrModel - Model name or model definition
    * @returns {import('./types').ModelDefinition}
    */
   function getModelInstance(nameOrModel) {
-    const name = typeof nameOrModel === 'object' && nameOrModel !== null && nameOrModel.name
-      ? nameOrModel.name
-      : nameOrModel;
+    const name = resolveModelName(nameOrModel);
 
     // First check local registry
     let model = models.get(name);
@@ -199,11 +197,12 @@ function createDatabase(config) {
 
   /**
    * Check if a model exists
-   * @param {string} name - Model name
+   * @param {string|Object} name - Model name
    * @returns {boolean}
    */
   function hasModelInstance(name) {
-    return models.has(name);
+    const modelName = resolveModelName(name);
+    return models.has(modelName) || hasModel(modelName);
   }
 
   /**
@@ -211,6 +210,12 @@ function createDatabase(config) {
    * @returns {Array<import('./types').ModelDefinition>}
    */
   function getAllModelInstances() {
+    const globalModels = getAllModels();
+    for (const [name, model] of globalModels) {
+      if (!models.has(name)) {
+        models.set(name, model);
+      }
+    }
     return Array.from(models.values());
   }
 
@@ -367,9 +372,17 @@ module.exports = {
   Hooks,
   HookCancellationError,
   createEventContext,
+  // Eager loading & nested relations
+  loadRelations: require('./eager-loader').loadRelations,
+  loadRelation: require('./eager-loader').loadRelation,
+  parseRelationTree: require('./eager-loader').parseRelationTree,
   // Query Complexity & DoS Protection
   QueryComplexityError: require('./complexity').QueryComplexityError,
   validateQueryComplexity: require('./complexity').validateQueryComplexity,
   resolveQueryLimits: require('./complexity').resolveQueryLimits,
   DEFAULT_QUERY_LIMITS: require('./complexity').DEFAULT_QUERY_LIMITS,
+  // Universal Full-Text Search
+  buildSearchClause: require('./search').buildSearchClause,
+  tokenizeSearchTerm: require('./search').tokenizeSearchTerm,
+  detectDialect: require('./search').detectDialect,
 };