s3db.js 13.6.0 → 14.0.2

package/src/plugins/api/utils/custom-routes.js

@@ -6,6 +6,7 @@
  */
 
 import { asyncHandler } from './error-handler.js';
+import { withContext, autoWrapHandler } from '../concerns/route-context.js';
 
 /**
  * Parse route definition from key
@@ -31,30 +32,41 @@ export function parseRouteKey(key) {
  * @param {Object} routes - Routes object { 'METHOD /path': handler }
  * @param {Object} context - Context to pass to handlers (resource, database, etc.)
  * @param {boolean} verbose - Enable verbose logging
+ * @param {Object} options - Additional options
+ * @param {boolean} options.autoWrap - Auto-wrap handlers with enhanced context (default: true)
  */
-export function mountCustomRoutes(app, routes, context = {}, verbose = false) {
+export function mountCustomRoutes(app, routes, context = {}, verbose = false, options = {}) {
   if (!routes || typeof routes !== 'object') {
     return;
   }
 
+  const { autoWrap = true } = options;
+
   for (const [key, handler] of Object.entries(routes)) {
     try {
       const { method, path } = parseRouteKey(key);
 
       // Wrap handler with async error handler and context
       const wrappedHandler = asyncHandler(async (c) => {
-        // Inject context into Hono context
+        // Inject legacy context into Hono context (for backward compatibility)
         c.set('customRouteContext', context);
 
-        // Call user handler with Hono context
-        return await handler(c);
+        // Auto-wrap handler if enabled and handler expects 2 arguments (c, ctx)
+        if (autoWrap && handler.length === 2) {
+          // Handler expects (c, ctx) - wrap it with enhanced context
+          return await withContext(handler, { resource: context.resource })(c);
+        } else {
+          // Handler expects only (c) - use legacy behavior
+          return await handler(c);
+        }
       });
 
       // Mount route
       app.on(method, path, wrappedHandler);
 
       if (verbose) {
-        console.log(`[Custom Routes] Mounted ${method} ${path}`);
+        const contextType = (autoWrap && handler.length === 2) ? '(enhanced)' : '(legacy)';
+        console.log(`[Custom Routes] Mounted ${method} ${path} ${contextType}`);
       }
     } catch (err) {
       console.error(`[Custom Routes] Error mounting route "${key}":`, err.message);

package/src/plugins/api/utils/guards.js

@@ -3,21 +3,53 @@
  *
  * Guards determine if a user can perform an operation on a resource.
  * Supports: functions, scopes, roles, and combined logic.
+ *
+ * NEW: Guards can now receive full RouteContext for access to:
+ * - ctx.user, ctx.resources, ctx.param(), ctx.query()
+ * - ctx.setPartition() for tenant isolation
  */
 
 /**
- * Check if user passes guard
- * @param {Object} user - Authenticated user object
+ * Check if guard passes (NEW: supports RouteContext)
+ *
+ * @param {Object|RouteContext} ctxOrUser - RouteContext (new) or user object (legacy)
  * @param {Function|string|Array|Object|null} guard - Guard configuration
- * @param {Object} context - Additional context (data, resourceName, operation)
+ * @param {Object|null} recordOrContext - Record being accessed (update/delete) or legacy context
  * @returns {boolean} True if authorized
+ *
+ * @example
+ * // NEW: Guard with RouteContext
+ * users.guard = {
+ *   list: (ctx) => {
+ *     if (ctx.user.scopes?.includes('preset:admin')) return true;
+ *     ctx.setPartition('byUserId', { userId: ctx.user.id });
+ *     return true;
+ *   }
+ * };
+ *
+ * @example
+ * // LEGACY: Guard with user object (still works!)
+ * users.guard = {
+ *   list: (user, context) => {
+ *     return user.scopes?.includes('preset:admin');
+ *   }
+ * };
  */
-export function checkGuard(user, guard, context = {}) {
+export function checkGuard(ctxOrUser, guard, recordOrContext = null) {
   // No guard = public access
   if (!guard) {
     return true;
   }
 
+  // Detect if first param is RouteContext (has .user property and ._currentResource)
+  const isRouteContext = ctxOrUser && typeof ctxOrUser === 'object' &&
+                          ('user' in ctxOrUser || '_currentResource' in ctxOrUser);
+
+  const ctx = isRouteContext ? ctxOrUser : null;
+  const user = isRouteContext ? ctxOrUser.user : ctxOrUser;
+  const record = isRouteContext ? recordOrContext : null;
+  const legacyContext = isRouteContext ? {} : (recordOrContext || {});
+
   // No user = unauthorized (unless guard explicitly allows)
   if (!user && guard !== true) {
     return false;
@@ -28,10 +60,23 @@ export function checkGuard(user, guard, context = {}) {
     return guard;
   }
 
-  // Guard is function: (user, context) => boolean
+  // Guard is function
   if (typeof guard === 'function') {
     try {
-      return guard(user, context);
+      // NEW: Pass RouteContext if available, else legacy (user, context) signature
+      if (ctx) {
+        // Detect guard signature: (ctx, record) or (ctx)
+        const guardLength = guard.length;
+
+        if (guardLength >= 2 && record !== null) {
+          return guard(ctx, record);  // (ctx, record) for update/delete
+        } else {
+          return guard(ctx);  // (ctx) for list/create
+        }
+      } else {
+        // LEGACY: (user, context) signature
+        return guard(user, legacyContext);
+      }
     } catch (err) {
       console.error('[Guards] Error executing guard function:', err);
       return false;
@@ -72,7 +117,11 @@ export function checkGuard(user, guard, context = {}) {
     // Check custom function
     if (guard.check && typeof guard.check === 'function') {
       try {
-        return guard.check(user, context);
+        if (ctx) {
+          return guard.check(ctx, record);
+        } else {
+          return guard.check(user, legacyContext);
+        }
       } catch (err) {
         console.error('[Guards] Error executing guard.check function:', err);
         return false;
@@ -169,22 +218,27 @@ export function getOperationGuard(guards, operation) {
 }
 
 /**
- * Create guard middleware for Hono
+ * Create guard middleware for Hono (NEW: with RouteContext)
  * @param {Object} guards - Guards configuration
  * @param {string} operation - Operation name
+ * @param {Object} options - Options { resource, database, plugins }
  * @returns {Function} Hono middleware
  */
-export function guardMiddleware(guards, operation) {
+export function guardMiddleware(guards, operation, options = {}) {
   return async (c, next) => {
-    const user = c.get('user');
+    // Import RouteContext dynamically to avoid circular dependency
+    const { RouteContext } = await import('../concerns/route-context.js');
+
+    const legacyContext = c.get('customRouteContext') || {};
+    const { database, resource, plugins = {} } = { ...legacyContext, ...options };
+
+    // Create RouteContext for guard
+    const ctx = new RouteContext(c, database, resource, plugins);
+
     const guard = getOperationGuard(guards, operation);
 
-    // Check guard
-    const authorized = checkGuard(user, guard, {
-      operation,
-      resourceName: c.req.param('resource'),
-      data: c.req.method !== 'GET' ? await c.req.json().catch(() => ({})) : {}
-    });
+    // Check guard (pass RouteContext)
+    const authorized = checkGuard(ctx, guard, null);
 
     if (!authorized) {
       return c.json({
@@ -194,13 +248,18 @@ export function guardMiddleware(guards, operation) {
           code: 'FORBIDDEN',
           details: {
             operation,
-            user: user ? { id: user.id, role: user.role } : null
+            user: ctx.user ? { id: ctx.user.id, role: ctx.user.role } : null
           }
         },
         _status: 403
       }, 403);
     }
 
+    // Store partition filters in context for use by route handlers
+    if (ctx.hasPartitionFilters()) {
+      c.set('partitionFilters', ctx.getPartitionFilters());
+    }
+
     await next();
   };
 }

package/src/plugins/api/utils/openapi-generator-cached.class.js

@@ -0,0 +1,133 @@
+/**
+ * OpenAPIGeneratorCached - Smart caching wrapper for OpenAPI generation
+ *
+ * Caches OpenAPI spec and invalidates only when schema changes:
+ * - Resource changes (add/remove/modify)
+ * - Auth configuration changes
+ * - Version changes
+ *
+ * Performance: 0ms cache hits vs ~50-200ms generation
+ */
+
+import { generateOpenAPISpec } from './openapi-generator.js';
+import { createHash } from 'crypto';
+
+export class OpenAPIGeneratorCached {
+  constructor({ database, options }) {
+    this.database = database;
+    this.options = options;
+
+    this.cache = null;
+    this.cacheKey = null;
+
+    if (options.verbose) {
+      console.log('[OpenAPIGenerator] Caching enabled');
+    }
+  }
+
+  /**
+   * Generate OpenAPI spec (with caching)
+   * @returns {Object} OpenAPI specification
+   */
+  generate() {
+    // Check if cache is valid
+    const currentKey = this.generateCacheKey();
+
+    if (this.cacheKey === currentKey && this.cache) {
+      if (this.options.verbose) {
+        console.log('[OpenAPIGenerator] Cache HIT (0ms)');
+      }
+      return this.cache;
+    }
+
+    // Cache miss - regenerate
+    if (this.options.verbose) {
+      const reason = !this.cache ? 'initial' : 'invalidated';
+      console.log(`[OpenAPIGenerator] Cache MISS (${reason})`);
+    }
+
+    const startTime = Date.now();
+    this.cache = generateOpenAPISpec(this.database, this.options);
+    this.cacheKey = currentKey;
+
+    if (this.options.verbose) {
+      const duration = Date.now() - startTime;
+      console.log(`[OpenAPIGenerator] Generated spec in ${duration}ms`);
+    }
+
+    return this.cache;
+  }
+
+  /**
+   * Generate cache key based on schema state
+   * @private
+   * @returns {string} Cache key (hash)
+   */
+  generateCacheKey() {
+    // Components that affect OpenAPI spec
+    const components = {
+      // Resource names and versions
+      resources: Object.keys(this.database.resources).map(name => {
+        const resource = this.database.resources[name];
+        return {
+          name,
+          version: resource.config?.currentVersion || resource.version || 'v1',
+          // Shallow hash of attributes (type changes invalidate cache)
+          attributes: Object.keys(resource.attributes || {}).sort().join(',')
+        };
+      }),
+
+      // Auth configuration affects security schemes
+      auth: {
+        drivers: this.options.auth?.drivers?.map(d => d.driver).sort() || [],
+        pathRules: this.options.auth?.pathRules?.length || 0,
+        pathAuth: !!this.options.auth?.pathAuth
+      },
+
+      // Resource config affects paths
+      resourceConfig: Object.keys(this.options.resources || {}).sort(),
+
+      // Version prefix affects URLs
+      versionPrefix: this.options.versionPrefix,
+
+      // API info
+      apiInfo: {
+        title: this.options.title,
+        version: this.options.version,
+        description: this.options.description
+      }
+    };
+
+    // Hash the components
+    const hash = createHash('sha256')
+      .update(JSON.stringify(components))
+      .digest('hex')
+      .substring(0, 16);  // First 16 chars sufficient for cache key
+
+    return hash;
+  }
+
+  /**
+   * Invalidate cache (force regeneration on next request)
+   */
+  invalidate() {
+    this.cache = null;
+    this.cacheKey = null;
+
+    if (this.options.verbose) {
+      console.log('[OpenAPIGenerator] Cache manually invalidated');
+    }
+  }
+
+  /**
+   * Get cache statistics
+   * @returns {Object} Cache stats
+   */
+  getStats() {
+    return {
+      cached: !!this.cache,
+      cacheKey: this.cacheKey,
+      size: this.cache ? JSON.stringify(this.cache).length : 0
+    };
+  }
+}

package/src/plugins/api/utils/openapi-generator.js

@@ -98,12 +98,13 @@ function generateResourceSchema(resource) {
   const properties = {};
   const required = [];
 
-  const allAttributes = resource.config?.attributes || resource.attributes || {};
+  // Use $schema for reliable access to resource definition
+  const allAttributes = resource.$schema.attributes || {};
 
   // Filter out plugin attributes - they are internal implementation details
   // and should not be exposed in public API documentation
-  const pluginAttrNames = resource.schema?._pluginAttributes
-    ? Object.values(resource.schema._pluginAttributes).flat()
+  const pluginAttrNames = resource.$schema._pluginAttributes
+    ? Object.values(resource.$schema._pluginAttributes).flat()
     : [];
 
   const attributes = Object.fromEntries(
@@ -111,7 +112,7 @@ function generateResourceSchema(resource) {
   );
 
   // Extract resource description (supports both string and object format)
-  const resourceDescription = resource.config?.description;
+  const resourceDescription = resource.$schema.description;
   const attributeDescriptions = typeof resourceDescription === 'object'
     ? (resourceDescription.attributes || {})
     : {};
@@ -215,8 +216,8 @@ function generateResourcePaths(resource, version, config = {}) {
   }
 
   // Extract partition information for documentation
-  // Partitions are stored in resource.config.options.partitions
-  const partitions = resource.config?.options?.partitions || resource.config?.partitions || resource.partitions || {};
+  // Use $schema for reliable access to partition definitions
+  const partitions = resource.$schema.partitions || {};
   const partitionNames = Object.keys(partitions);
   const hasPartitions = partitionNames.length > 0;
 

package/src/plugins/api/utils/template-engine.js

@@ -3,6 +3,7 @@
  *
  * Provides c.render() helper that works with multiple template engines:
  * - EJS (for mrt-shortner compatibility)
+ * - Pug (formerly Jade)
  * - JSX (Hono native)
  * - Custom engines via setRenderer()
  *
@@ -19,6 +20,17 @@
  * });
  *
  * @example
+ * // Pug usage
+ * app.use('*', setupTemplateEngine({
+ *   engine: 'pug',
+ *   templatesDir: './views'
+ * }));
+ *
+ * app.get('/page', async (c) => {
+ *   return c.render('landing', { urlCount: 1000 });
+ * });
+ *
+ * @example
  * // JSX usage (no setup needed)
  * app.get('/page', (c) => {
  *   return c.render(<h1>Hello</h1>);
@@ -45,11 +57,27 @@ async function loadEJS() {
   }
 }
 
+/**
+ * Lazy-load Pug (peer dependency)
+ * @returns {Promise<Object>} Pug module
+ */
+async function loadPug() {
+  try {
+    const pug = await import('pug');
+    return pug.default || pug;
+  } catch (err) {
+    throw new Error(
+      'Pug template engine not installed. Install with: npm install pug\n' +
+      'Pug is a peer dependency to keep the core package lightweight.'
+    );
+  }
+}
+
 /**
  * Setup template engine middleware
  * @param {Object} options - Template engine options
- * @param {string} options.engine - Engine name: 'ejs', 'jsx', 'custom'
- * @param {string} options.templatesDir - Directory containing templates (required for EJS)
+ * @param {string} options.engine - Engine name: 'ejs', 'pug', 'jsx', 'custom'
+ * @param {string} options.templatesDir - Directory containing templates (required for EJS/Pug)
  * @param {string} options.layout - Default layout template (optional for EJS)
  * @param {Object} options.engineOptions - Additional engine-specific options
  * @param {Function} options.customRenderer - Custom render function (for 'custom' engine)
@@ -70,7 +98,7 @@ export function setupTemplateEngine(options = {}) {
   return async (c, next) => {
     /**
      * Render template with data
-     * @param {string|JSX.Element} template - Template name (for EJS) or JSX element
+     * @param {string|JSX.Element} template - Template name (for EJS/Pug) or JSX element
      * @param {Object} data - Data to pass to template
      * @param {Object} renderOptions - Render-specific options
      * @returns {Response} HTML response
@@ -82,6 +110,37 @@ export function setupTemplateEngine(options = {}) {
         return c.html(template);
       }
 
+      // Pug: File-based rendering
+      if (engine === 'pug') {
+        // Lazy-load Pug
+        const pug = await loadPug();
+
+        const templateFile = template.endsWith('.pug') ? template : `${template}.pug`;
+        const templatePath = join(templatesPath, templateFile);
+
+        if (!existsSync(templatePath)) {
+          throw new Error(`Template not found: ${templatePath}`);
+        }
+
+        // Merge global data + render data
+        const renderData = {
+          ...data,
+          // Add helpers that Pug templates might expect
+          _url: c.req.url,
+          _path: c.req.path,
+          _method: c.req.method
+        };
+
+        // Render template
+        const html = pug.renderFile(templatePath, {
+          ...renderData,
+          ...engineOptions,
+          ...renderOptions
+        });
+
+        return c.html(html);
+      }
+
       // EJS: File-based rendering
       if (engine === 'ejs') {
         // Lazy-load EJS
@@ -164,6 +223,20 @@ export function ejsEngine(templatesDir, options = {}) {
   });
 }
 
+/**
+ * Create Pug template engine middleware (convenience wrapper)
+ * @param {string} templatesDir - Directory containing templates
+ * @param {Object} options - Additional options
+ * @returns {Function} Hono middleware
+ */
+export function pugEngine(templatesDir, options = {}) {
+  return setupTemplateEngine({
+    engine: 'pug',
+    templatesDir,
+    ...options
+  });
+}
+
 /**
  * Create JSX template engine middleware (convenience wrapper)
  * Note: JSX rendering is built into Hono, this just provides c.render()
@@ -184,5 +257,6 @@ export function jsxEngine() {
 export default {
   setupTemplateEngine,
   ejsEngine,
+  pugEngine,
   jsxEngine
 };

package/src/plugins/audit.plugin.js

@@ -426,12 +426,24 @@
  */
 
 import { Plugin } from "./plugin.class.js";
+import { getValidatedNamespace } from "./namespace.js";
 import tryFn from "../concerns/try-fn.js";
+import { resolveResourceName } from "./concerns/resource-names.js";
 
 export class AuditPlugin extends Plugin {
   constructor(options = {}) {
     super(options);
+
+    // Validate and set namespace (standardized)
+    this.namespace = getValidatedNamespace(options, '');
+
+    const resourceNames = options.resourceNames || {};
     this.auditResource = null;
+    this._auditResourceDescriptor = {
+      defaultName: 'plg_audits',
+      override: resourceNames.audit || options.resourceName
+    };
+    this.auditResourceName = this._resolveAuditResourceName();
     this.config = {
       includeData: options.includeData !== false,
       includePartitions: options.includePartitions !== false,
@@ -440,10 +452,20 @@ export class AuditPlugin extends Plugin {
     };
   }
 
+  _resolveAuditResourceName() {
+    return resolveResourceName('audit', this._auditResourceDescriptor, {
+      namespace: this.namespace
+    });
+  }
+
+  onNamespaceChanged() {
+    this.auditResourceName = this._resolveAuditResourceName();
+  }
+
   async onInstall() {
     // Create audit resource
     const [ok, err, auditResource] = await tryFn(() => this.database.createResource({
-      name: 'plg_audits',
+      name: this.auditResourceName,
       attributes: {
         id: 'string|required',
         resourceName: 'string|required',
@@ -464,19 +486,19 @@ export class AuditPlugin extends Plugin {
       },
       behavior: 'body-overflow'
     }));
-    this.auditResource = ok ? auditResource : (this.database.resources.plg_audits || null);
+    this.auditResource = ok ? auditResource : (this.database.resources[this.auditResourceName] || null);
     if (!ok && !this.auditResource) return;
 
     // Hook into database for new resources
     this.database.addHook('afterCreateResource', (context) => {
-      if (context.resource.name !== 'plg_audits') {
+      if (context.resource.name !== this.auditResourceName) {
         this.setupResourceAuditing(context.resource);
       }
     });
 
     // Setup existing resources
     for (const resource of Object.values(this.database.resources)) {
-      if (resource.name !== 'plg_audits') {
+      if (resource.name !== this.auditResourceName) {
         this.setupResourceAuditing(resource);
       }
     }
@@ -630,9 +652,9 @@ export class AuditPlugin extends Plugin {
 
   getPartitionValues(data, resource) {
     if (!this.config.includePartitions) return null;
-    
-    // Access partitions from resource.config.partitions, not resource.partitions
-    const partitions = resource.config?.partitions || resource.partitions;
+
+    // Use $schema for reliable access to partition definitions
+    const partitions = resource.$schema.partitions;
     if (!partitions) {
       return null;
     }
@@ -847,4 +869,4 @@ export class AuditPlugin extends Plugin {
 
     return deletedCount;
   }
-} 
+}