webspresso 0.0.94 → 0.0.96

package/plugins/xlsx/index.js

@@ -0,0 +1,91 @@
+'use strict';
+
+/**
+ * Webspresso XLSX Plugin
+ * Excel spreadsheet generation, parsing, ORM export, streaming, and res.xlsx() integration
+ * @module plugins/xlsx
+ */
+
+const engine = require('./engine');
+const { createXlsxMiddleware, XLSX_MIME_TYPE } = require('./middleware');
+const { createXlsxServices } = require('./services');
+
+/**
+ * Standalone XLSX Toolkit Singleton
+ */
+const xlsx = {
+  ...engine,
+  MIME_TYPE: XLSX_MIME_TYPE,
+  createMiddleware: createXlsxMiddleware,
+  createServices: createXlsxServices,
+};
+
+/**
+ * XLSX Plugin for Webspresso
+ * @param {Object} [options]
+ * @param {boolean} [options.enabled=true]
+ * @param {boolean} [options.sanitizeFormulas=true] - Prevent Formula Injection attacks
+ * @param {Object} [options.headerStyle] - Default header styling (fill, font, border)
+ * @param {Object} [options.db] - Optional database instance for model export services
+ * @returns {import('../../index').Plugin}
+ */
+function xlsxPlugin(options = {}) {
+  const {
+    enabled = true,
+    sanitizeFormulas = true,
+    headerStyle = { fill: '4F46E5', color: 'FFFFFF', bold: true },
+    db: dbOption,
+  } = options;
+
+  return {
+    name: 'xlsx',
+    version: '1.0.0',
+    description: 'Excel XLSX spreadsheet engine, res.xlsx() response decorator, and ORM export tools',
+    enabled,
+
+    register(ctx) {
+      if (!enabled) return;
+
+      // 1. Expose on PluginContext & global app
+      ctx.xlsx = xlsx;
+      if (ctx.app) {
+        ctx.app.xlsx = xlsx;
+      }
+
+      // 2. Register built-in services (xlsx.generate, xlsx.parse, xlsx.exportModel)
+      if (ctx.app && ctx.app.serviceRegistry) {
+        const db = dbOption ?? ctx.db ?? ctx.app?.get?.('db') ?? null;
+        const services = createXlsxServices({ db, ...options });
+        for (const [name, def] of Object.entries(services)) {
+          if (!ctx.app.serviceRegistry.has(name)) {
+            ctx.app.serviceRegistry.register(name, def);
+          }
+        }
+      }
+
+      // 3. Register named middleware & global decorator
+      const middleware = createXlsxMiddleware({
+        sanitizeFormulas,
+        headerStyle,
+        ...options,
+      });
+
+      if (ctx.middlewares) {
+        ctx.middlewares.xlsx = middleware;
+      }
+
+      if (ctx.app && typeof ctx.app.use === 'function') {
+        ctx.app.use(middleware);
+      }
+    },
+  };
+}
+
+module.exports = {
+  xlsxPlugin,
+  xlsx,
+  createXlsxMiddleware,
+  createXlsxServices,
+  XLSX_MIME_TYPE,
+  ...engine,
+};

package/plugins/xlsx/middleware.js

@@ -0,0 +1,87 @@
+'use strict';
+
+/**
+ * XLSX Express Middleware
+ * Decorates res.xlsx() and req.parseXlsx() helpers
+ * @module plugins/xlsx/middleware
+ */
+
+const { generate, parse, fromModel } = require('./engine');
+
+const XLSX_MIME_TYPE = 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet';
+
+/**
+ * Creates the XLSX middleware
+ * @param {Object} [globalOptions]
+ * @returns {Function}
+ */
+function createXlsxMiddleware(globalOptions = {}) {
+  return (req, res, next) => {
+    // 1. Response Helper: res.xlsx(data, filename, options)
+    res.xlsx = async function (data, filename = 'export.xlsx', options = {}) {
+      try {
+        let buffer;
+
+        if (Buffer.isBuffer(data)) {
+          buffer = data;
+        } else if (data && typeof data.find === 'function' && data.model) {
+          // Repository instance
+          buffer = await fromModel(data, options.filter || options.query || {}, {
+            ...globalOptions,
+            ...options,
+          });
+        } else if (Array.isArray(data)) {
+          buffer = await generate({
+            ...globalOptions,
+            ...options,
+            sheets: [
+              {
+                name: options.sheetName || 'Data',
+                columns: options.columns,
+                rows: data,
+                headerStyle: options.headerStyle,
+              },
+            ],
+          });
+        } else if (data && typeof data === 'object') {
+          buffer = await generate({
+            ...globalOptions,
+            ...options,
+            ...data,
+          });
+        } else {
+          throw new Error('res.xlsx() expects an Array of rows, a sheets object, a Model Repository, or a Buffer');
+        }
+
+        const safeFilename = filename.endsWith('.xlsx') ? filename : `${filename}.xlsx`;
+
+        res.setHeader('Content-Type', XLSX_MIME_TYPE);
+        res.setHeader(
+          'Content-Disposition',
+          `attachment; filename="${encodeURIComponent(safeFilename)}"; filename*=UTF-8''${encodeURIComponent(safeFilename)}`
+        );
+        res.setHeader('Content-Length', buffer.length);
+
+        return res.end(buffer);
+      } catch (err) {
+        return next(err);
+      }
+    };
+
+    // 2. Request Helper: req.parseXlsx(fileOrBuffer, options)
+    req.parseXlsx = async function (fileOrBuffer, options = {}) {
+      const target = fileOrBuffer || req.file?.buffer || req.rawBody || req.body;
+      if (!target) {
+        throw new Error('req.parseXlsx requires a file Buffer or multipart req.file.buffer');
+      }
+      return parse(target, options);
+    };
+
+    next();
+  };
+}
+
+module.exports = {
+  createXlsxMiddleware,
+  XLSX_MIME_TYPE,
+};

package/plugins/xlsx/services.js

@@ -0,0 +1,118 @@
+'use strict';
+
+/**
+ * Built-in XLSX Services
+ * Exposed via ctx.service('xlsx.*') and req.service('xlsx.*')
+ * @module plugins/xlsx/services
+ */
+
+const { z } = require('zod');
+const { generate, parse, fromModel } = require('./engine');
+
+/**
+ * Creates built-in services for the XLSX plugin
+ * @param {Object} [options]
+ * @param {Object} [options.db]
+ * @returns {Object.<string, Object>}
+ */
+function createXlsxServices(options = {}) {
+  return {
+    'xlsx.generate': {
+      schema: z.object({
+        sheets: z.array(
+          z.object({
+            name: z.string().optional(),
+            columns: z.array(z.object({ header: z.string(), key: z.string(), width: z.number().optional() })).optional(),
+            rows: z.array(z.record(z.any())),
+          })
+        ).or(z.object({
+          name: z.string().optional(),
+          columns: z.array(z.object({ header: z.string(), key: z.string(), width: z.number().optional() })).optional(),
+          rows: z.array(z.record(z.any())),
+        })),
+        creator: z.string().optional(),
+        title: z.string().optional(),
+      }),
+      handler: async (input) => {
+        const buffer = await generate(input);
+        return {
+          base64: buffer.toString('base64'),
+          size: buffer.length,
+          mimeType: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+        };
+      },
+    },
+
+    'xlsx.parse': {
+      schema: z.object({
+        base64: z.string().optional(),
+        sheet: z.union([z.string(), z.number()]).optional(),
+        headerRow: z.number().optional(),
+      }),
+      handler: async (input) => {
+        if (!input.base64 && !input.buffer) {
+          throw new Error('xlsx.parse requires base64 string or buffer');
+        }
+        const buffer = input.buffer || Buffer.from(input.base64, 'base64');
+        const data = await parse(buffer, {
+          sheet: input.sheet,
+          headerRow: input.headerRow,
+        });
+
+        const rowCount = Array.isArray(data)
+          ? data.length
+          : Object.values(data).reduce((acc, sheetRows) => acc + sheetRows.length, 0);
+
+        return {
+          data,
+          rowCount,
+        };
+      },
+    },
+
+    'xlsx.exportModel': {
+      schema: z.object({
+        model: z.string().min(1),
+        filter: z.record(z.any()).optional().default({}),
+        columns: z.array(z.string()).optional(),
+        filename: z.string().optional(),
+      }),
+      handler: async (input, ctx) => {
+        const db = ctx.db || options.db;
+        if (!db || typeof db.getRepository !== 'function') {
+          throw new Error('xlsx.exportModel requires an active database connection');
+        }
+
+        const repo = db.getRepository(input.model);
+        if (!repo) {
+          throw new Error(`Model repository "${input.model}" not found`);
+        }
+
+        let customColumns;
+        if (input.columns) {
+          customColumns = input.columns.map((c) => ({
+            header: c.charAt(0).toUpperCase() + c.slice(1).replace(/_/g, ' '),
+            key: c,
+          }));
+        }
+
+        const buffer = await fromModel(repo, input.filter, {
+          columns: customColumns,
+          title: `${input.model} Export`,
+        });
+
+        const filename = input.filename || `${input.model.toLowerCase()}_export.xlsx`;
+
+        return {
+          filename: filename.endsWith('.xlsx') ? filename : `${filename}.xlsx`,
+          base64: buffer.toString('base64'),
+          size: buffer.length,
+        };
+      },
+    },
+  };
+}
+
+module.exports = {
+  createXlsxServices,
+};

package/src/api/api-loader.js

@@ -0,0 +1,233 @@
+'use strict';
+
+/**
+ * Webspresso API Loader
+ * Handles validation and execution of defineApi() endpoints
+ * @module src/api/api-loader
+ */
+
+const { ZodError } = require('zod');
+const { z: zForApi } = require('../../core/validation');
+const { resolveMiddlewares } = require('../file-router');
+
+/**
+ * Compiles a schema definition from an API module
+ * @param {Object|Function} schemaDef
+ * @returns {Object|null}
+ */
+function compileApiSchema(schemaDef) {
+  if (!schemaDef) return null;
+  if (typeof schemaDef === 'function') {
+    try {
+      return schemaDef({ z: zForApi });
+    } catch (err) {
+      throw new Error(`Failed to compile API schema: ${err.message}`);
+    }
+  }
+  if (typeof schemaDef === 'object') {
+    return schemaDef;
+  }
+  return null;
+}
+
+/**
+ * Validates request input against compiled schema
+ * @param {import('express').Request} req
+ * @param {Object} compiledSchema
+ */
+function validateRequestInput(req, compiledSchema) {
+  req.input = {
+    body: undefined,
+    params: undefined,
+    query: undefined,
+    headers: undefined,
+  };
+
+  if (!compiledSchema) return;
+
+  if (compiledSchema.body && typeof compiledSchema.body.parse === 'function') {
+    req.input.body = compiledSchema.body.parse(req.body);
+  } else {
+    req.input.body = req.body;
+  }
+
+  if (compiledSchema.params && typeof compiledSchema.params.parse === 'function') {
+    req.input.params = compiledSchema.params.parse(req.params);
+  } else {
+    req.input.params = req.params;
+  }
+
+  if (compiledSchema.query && typeof compiledSchema.query.parse === 'function') {
+    req.input.query = compiledSchema.query.parse(req.query);
+  } else {
+    req.input.query = req.query;
+  }
+
+  if (compiledSchema.headers && typeof compiledSchema.headers.parse === 'function') {
+    req.input.headers = compiledSchema.headers.parse(req.headers);
+  }
+}
+
+/**
+ * Creates an Express route handler for a discovered API descriptor
+ * @param {Object} descriptor - Route descriptor
+ * @param {Object} context - Server context
+ * @returns {Function}
+ */
+function createApiHandler(descriptor, context) {
+  const {
+    middlewares = {},
+    serviceRegistry = null,
+    db = null,
+    options: appOptions = {},
+  } = context;
+
+  const isDev = process.env.NODE_ENV === 'development';
+  let cachedMiddlewares = null;
+  let cachedApiDef = null;
+  let cachedHandlerFn = null;
+  let cachedCompiledSchema = null;
+
+  return async (req, res, next) => {
+    try {
+      // 1. Reload module in development
+      if (isDev) {
+        try {
+          const resolvedPath = require.resolve(descriptor.file);
+          if (require.cache[resolvedPath]) {
+            delete require.cache[resolvedPath];
+            cachedMiddlewares = null;
+            cachedApiDef = null;
+            cachedHandlerFn = null;
+            cachedCompiledSchema = null;
+          }
+        } catch {}
+      }
+
+      let apiDef = cachedApiDef;
+      let handlerFn = cachedHandlerFn;
+      let compiledSchema = cachedCompiledSchema;
+
+      if (!apiDef) {
+        let apiModule = {};
+        try {
+          apiModule = require(descriptor.file);
+        } catch (loadErr) {
+          return next(loadErr);
+        }
+
+        apiDef = typeof apiModule === 'function' ? { handler: apiModule } : apiModule.default || apiModule;
+        handlerFn = apiDef.handler || (typeof apiModule === 'function' ? apiModule : null);
+
+        if (typeof handlerFn !== 'function') {
+          throw new Error(`API file "${descriptor.source}" does not export a valid handler function`);
+        }
+
+        compiledSchema = compileApiSchema(apiDef.schema);
+
+        if (!isDev) {
+          cachedApiDef = apiDef;
+          cachedHandlerFn = handlerFn;
+          cachedCompiledSchema = compiledSchema;
+        }
+      }
+
+      // 2. Injections
+      if (db) req.db = db;
+      if (serviceRegistry) {
+        req.service = (name, input, opts) =>
+          serviceRegistry.call(name, input, { req, res, db }, opts);
+      }
+
+      // 3. Schema validation
+      if (compiledSchema) {
+        try {
+          validateRequestInput(req, compiledSchema);
+        } catch (err) {
+          if (err instanceof ZodError || err.name === 'ZodError' || Array.isArray(err?.issues)) {
+            return res.status(400).json({
+              error: 'Validation Error',
+              issues: err.issues,
+            });
+          }
+          throw err;
+        }
+      } else {
+        req.input = {
+          body: req.body,
+          params: req.params,
+          query: req.query,
+        };
+      }
+
+      // 4. Resolve and execute middlewares (module-local first, cached across requests)
+      if (!cachedMiddlewares) {
+        const moduleMiddlewares = descriptor.moduleConfig?.middlewares || {};
+        const combinedRegistry = Object.assign({}, middlewares, moduleMiddlewares);
+        cachedMiddlewares = resolveMiddlewares(apiDef.middleware, combinedRegistry);
+      }
+
+      for (const mw of cachedMiddlewares) {
+        if (typeof mw !== 'function') continue;
+        await new Promise((resolve, reject) => {
+          try {
+            mw(req, res, (err) => {
+              if (err) reject(err);
+              else resolve();
+            });
+          } catch (syncErr) {
+            reject(syncErr);
+          }
+        });
+        if (res.headersSent) return;
+      }
+
+      // 5. Execute handler
+      const apiCtx = {
+        req,
+        res,
+        params: req.params || {},
+        query: req.query || {},
+        body: req.body || {},
+        input: req.input,
+        service: (name, input, opts) =>
+          serviceRegistry ? serviceRegistry.call(name, input, { req, res, db }, opts) : null,
+        module: descriptor.module || null,
+        config: appOptions,
+        logger: console,
+        db,
+      };
+
+      req.ctx = apiCtx;
+      res.service = apiCtx.service;
+      res.input = apiCtx.input;
+      res.module = apiCtx.module;
+
+      const result = await handlerFn(req, res, apiCtx);
+
+      // 6. Auto-respond if handler returned a value and response not yet sent
+      if (!res.headersSent) {
+        if (result !== undefined) {
+          return res.json(result);
+        }
+      }
+    } catch (err) {
+      if (err && typeof err === 'object') {
+        if (!err.route) err.route = descriptor.path;
+        if (!err.method) err.method = descriptor.method ? descriptor.method.toUpperCase() : (req.method || 'GET');
+        if (!err.source) err.source = descriptor.source || descriptor.file;
+        if (!err.file) err.file = descriptor.file;
+        if (!err.module) err.module = descriptor.module || null;
+        if (!err.phase) err.phase = 'handler';
+        if (!err.requestId) err.requestId = req.id || (req.headers && req.headers['x-request-id']) || null;
+      }
+      return next(err);
+    }
+  };
+}
+
+module.exports = {
+  createApiHandler,
+  compileApiSchema,
+  validateRequestInput,
+};

package/src/api/define-api.js

@@ -0,0 +1,35 @@
+'use strict';
+
+/**
+ * Webspresso API Definition Helper
+ * @module src/api/define-api
+ */
+
+/**
+ * Defines an API route with schema validation, response metadata, and handler
+ * @param {Object} config
+ * @param {string} [config.description] - Endpoint description for OpenAPI
+ * @param {Array<string>} [config.tags] - Endpoint tags for OpenAPI
+ * @param {Array<string|Function>} [config.middleware] - Named or functional middlewares
+ * @param {Object|Function} [config.schema] - Request schemas (params, query, body, headers)
+ * @param {Object} [config.response] - Expected response schemas by status code
+ * @param {Function} config.handler - Request handler: async (req, ctx) => data
+ * @returns {Object}
+ */
+function defineApi(config = {}) {
+  if (typeof config === 'function') {
+    return {
+      handler: config,
+      __isWebspressoApi: true,
+    };
+  }
+
+  return {
+    ...config,
+    __isWebspressoApi: true,
+  };
+}
+
+module.exports = {
+  defineApi,
+};