@xeplr/base-apis 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Xeplr
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/express.js

@@ -0,0 +1,155 @@
+var express = require('express');
+var cors = require('cors');
+var cookieParser = require('cookie-parser');
+var path = require('path');
+var { createServer } = require('./lib/server');
+var logs = require('@xeplr/logs');
+
+/**
+ * Create and initialize an Express application.
+ * Factory function — each call returns a fresh app instance.
+ *
+ * @param {number|string} port       - Port or named pipe to listen on
+ * @param {string}        appName    - Service name (used for debug namespace and console logs)
+ * @param {object}        [options]  - Configuration options
+ * @param {object}        [options.routes]        - Route map: { '/path': router }
+ * @param {Function[]}    [options.middleware]     - Middleware to apply before routes (e.g. authMiddleware)
+ * @param {object}        [options.views]         - { engine: 'pug', dir: '/abs/path' }
+ * @param {string}        [options.staticDir]     - Path to static files directory
+ * @param {string}        [options.corsOptions]   - Custom CORS options (default: allow all)
+ * @param {Function}      [options.errorHandler]  - Custom error handler (req, res, next)
+ * @param {object|false}  [options.log]           - Logger config (false to disable)
+ * @param {string}        [options.log.logDir='./logs']        - Log directory
+ * @param {number}        [options.log.fatalThreshold=4]       - Level >= this is fatal (4=error, 5=critical)
+ * @param {number}        [options.log.emailThreshold=5]       - Level >= this triggers email
+ * @param {string|string[]} [options.log.emailTo]              - Email recipient(s)
+ * @param {object}        [options.log.emailService]           - Email service instance
+ * @param {object}        [options.upload]        - File upload config
+ * @param {string}        [options.upload.route='/internal/upload'] - Upload endpoint path
+ * @param {string}        [options.upload.destination='./uploads']  - Storage directory
+ * @param {string[]}      [options.upload.allowedTypes=['*']]       - MIME types
+ * @param {number}        [options.upload.maxSize=5242880]          - Max file size in bytes
+ * @param {string}        [options.upload.fieldName='file']         - Form field name
+ * @param {number}        [options.upload.maxFiles=10]              - Max files per request
+ * @param {string}        [options.upload.serveRoute='/uploads']    - Static serve path for uploaded files
+ * @returns {{ app: Express, server: http.Server }}
+ */
+function createApp(port, appName, options) {
+  options = options || {};
+  var app = express();
+
+  // ── Logger ──
+  if (options.log !== false) {
+    var logCfg = options.log || {};
+    logs.configure({
+      appName: appName,
+      logDir: logCfg.logDir || './logs',
+      fatalThreshold: logCfg.fatalThreshold,
+      emailThreshold: logCfg.emailThreshold,
+      emailTo: logCfg.emailTo,
+      emailService: logCfg.emailService,
+      isDev: (process.env.NODE_ENV || 'development') !== 'production'
+    });
+    app.use(logs.requestLogger());
+  }
+
+  // ── View engine ──
+  if (options.views) {
+    app.set('views', options.views.dir);
+    app.set('view engine', options.views.engine || 'pug');
+  }
+
+  // ── Standard middleware ──
+  app.use(cors(options.corsOptions));
+  app.use(express.json());
+  app.use(express.urlencoded({ extended: false }));
+  app.use(cookieParser());
+
+  // ── Static files ──
+  if (options.staticDir) {
+    app.use(express.static(options.staticDir));
+  }
+
+  // ── File upload (static serve before auth, upload route after auth) ──
+  if (options.upload) {
+    var serveRoute = options.upload.serveRoute || '/uploads';
+    var destination = path.resolve(options.upload.destination || process.env.UPLOAD_DIR || './uploads');
+    app.use(serveRoute, express.static(destination));
+  }
+
+  // ── Injected middleware (auth, etc.) ──
+  if (options.middleware) {
+    options.middleware.forEach(function(mw) { app.use(mw); });
+  }
+
+  // ── File upload (upload endpoint — behind auth) ──
+  if (options.upload) {
+    var FileUploader = require('@xeplr/utils').FileUploader;
+    var uploadCfg = options.upload;
+    var destination = path.resolve(uploadCfg.destination || process.env.UPLOAD_DIR || './uploads');
+    var uploader = new FileUploader({
+      auth: uploadCfg.auth || null,
+      allowedTypes: uploadCfg.allowedTypes || ['*'],
+      maxSize: uploadCfg.maxSize || 5 * 1024 * 1024,
+      destination: destination
+    });
+
+    var uploadRoute = uploadCfg.route || '/internal/upload';
+    var fieldName = uploadCfg.fieldName || 'file';
+    var maxFiles = uploadCfg.maxFiles || 10;
+
+    app.post(uploadRoute, uploader.array(fieldName, maxFiles), function(req, res) {
+      if (!req.files || req.files.length === 0) {
+        return res.status(400).json({ error: 'No files uploaded' });
+      }
+      var files = req.files.map(function(f) {
+        return {
+          filename: f.filename,
+          originalName: f.originalname,
+          size: f.size,
+          mimetype: f.mimetype
+        };
+      });
+      res.json(files.length === 1 ? files[0] : files);
+    });
+  }
+
+  // ── Routes ──
+  if (options.routes) {
+    Object.keys(options.routes).forEach(function(routePath) {
+      app.use(routePath, options.routes[routePath]);
+    });
+  }
+
+  // ── 404 handler ──
+  if (options.views) {
+    var createError = require('http-errors');
+    app.use(function(req, res, next) { next(createError(404)); });
+  } else {
+    app.use(function(req, res) { res.status(404).json({ error: 'Not found' }); });
+  }
+
+  // ── Error handler ──
+  if (options.errorHandler) {
+    app.use(options.errorHandler);
+  } else if (options.views) {
+    app.use(function(err, req, res, next) {
+      res.locals.message = err.message;
+      res.locals.error = req.app.get('env') === 'development' ? err : {};
+      res.status(err.status || 500);
+      res.render('error');
+    });
+  } else {
+    app.use(function(err, req, res, next) {
+      res.status(err.status || 500).json({ error: err.message });
+    });
+  }
+
+  // ── Start HTTP server ──
+  app.set('port', port);
+  var server = createServer(app, port, appName);
+
+  return { app: app, server: server };
+}
+
+module.exports = createApp;

package/index.js

@@ -0,0 +1,10 @@
+module.exports = {
+  createApp: require('./express'),
+  createHttpServer: require('./http'),
+  genericRoute: require('./lib/genericRoute'),
+  genericController: require('./lib/genericController'),
+  runCluster: require('./lib/cluster').runCluster,
+  broadcast: require('./lib/cluster').broadcast,
+  isPrimary: require('./lib/cluster').isPrimary,
+  isWorker: require('./lib/cluster').isWorker
+};

package/lib/cluster.js

@@ -0,0 +1,114 @@
+var cluster = require('cluster');
+var os = require('os');
+
+/**
+ * Run an Express app across multiple worker processes using Node.js cluster.
+ *
+ * The primary process forks workers and manages lifecycle.
+ * Each worker runs the app independently with its own event loop.
+ *
+ * Workers can notify each other via `broadcast()` — primary relays
+ * the message to all other workers.
+ *
+ * Usage:
+ *
+ *   var { runCluster } = require('@xeplr/base-apis');
+ *
+ *   runCluster({
+ *     workers: 4,                        // default: CPU count
+ *     start: function() {                // called in each worker
+ *       var { createApp } = require('@xeplr/base-apis');
+ *       createApp(3000, 'myapp', { routes: { ... } });
+ *     },
+ *     onMessage: function(msg) {         // called in each worker when broadcast received
+ *       if (msg.type === 'cache-clear') clearLocalCache();
+ *     }
+ *   });
+ *
+ * Inside a worker, notify others:
+ *
+ *   var { broadcast } = require('@xeplr/base-apis/lib/cluster');
+ *   broadcast({ type: 'cache-clear', key: 'users' });
+ *
+ * @param {object}   options
+ * @param {Function} options.start      - Called in each worker to boot the app
+ * @param {number}   [options.workers]  - Number of workers (default: os.cpus().length)
+ * @param {Function} [options.onMessage] - Handler for broadcast messages in workers
+ * @param {boolean}  [options.respawn]  - Restart crashed workers (default: true)
+ */
+function runCluster(options) {
+  var workerCount = options.workers || os.cpus().length;
+  var respawn = options.respawn !== false;
+
+  if (cluster.isPrimary) {
+    console.log('[cluster] Primary ' + process.pid + ' starting ' + workerCount + ' workers');
+
+    // Fork workers
+    for (var i = 0; i < workerCount; i++) {
+      cluster.fork();
+    }
+
+    // Relay messages from one worker to all others
+    cluster.on('message', function(sender, msg) {
+      if (msg && msg._broadcast) {
+        for (var id in cluster.workers) {
+          var worker = cluster.workers[id];
+          if (worker && worker !== sender && !worker.isDead()) {
+            worker.send(msg);
+          }
+        }
+      }
+    });
+
+    // Respawn dead workers
+    cluster.on('exit', function(worker, code, signal) {
+      console.log('[cluster] Worker ' + worker.process.pid + ' died (' + (signal || code) + ')');
+      if (respawn) {
+        console.log('[cluster] Spawning replacement worker');
+        cluster.fork();
+      }
+    });
+  } else {
+    // Worker process — boot the app
+    options.start();
+
+    // Listen for broadcast messages from other workers
+    if (options.onMessage) {
+      process.on('message', function(msg) {
+        if (msg && msg._broadcast) {
+          options.onMessage(msg);
+        }
+      });
+    }
+
+    console.log('[cluster] Worker ' + process.pid + ' started');
+  }
+}
+
+/**
+ * Send a message to all other workers via the primary process.
+ * Call this from within a worker process.
+ *
+ * @param {object} msg - Any serializable object. Gets `_broadcast: true` added.
+ */
+function broadcast(msg) {
+  if (!process.send) return; // not in a cluster worker
+  msg._broadcast = true;
+  process.send(msg);
+}
+
+/**
+ * Check if current process is the primary.
+ */
+function isPrimary() {
+  return cluster.isPrimary;
+}
+
+/**
+ * Check if current process is a worker.
+ */
+function isWorker() {
+  return cluster.isWorker;
+}
+
+module.exports = { runCluster, broadcast, isPrimary, isWorker };

package/lib/genericController.js

@@ -0,0 +1,218 @@
+var { respond } = require('@xeplr/utils/lib/response');
+var { HTTP, STATUS } = require('@xeplr/utils/isomorphic');
+var { generateId } = require('@xeplr/utils/lib/helpers');
+
+/**
+ * Generic CRUD controller.
+ * Processes the changeset from xeplr-ui-table in a single transaction.
+ *
+ * Changeset rules:
+ *   - No id           → INSERT (new record)
+ *   - Has id, deleted  → SOFT DELETE (isActive = false)
+ *   - Has id           → PATCH (only changed fields)
+ *   - Children nested inside parent follow same rules, recursively
+ */
+
+/**
+ * Save handler — processes a changeset array in a single transaction.
+ *
+ * @param {object} req       - Express request. Body: changeset array.
+ * @param {object} res       - Express response.
+ * @param {object} hierarchy - { key, model, children: [...] }
+ */
+async function save(req, res, hierarchy) {
+  var changeSet = req.body;
+
+  if (!Array.isArray(changeSet) || changeSet.length === 0) {
+    return respond(res, HTTP.BAD_REQUEST, STATUS.BAD_REQUEST, 'bad_request', {
+      message: 'Expected a non-empty changeset array'
+    });
+  }
+
+  var rootDef = hierarchy;
+  var knex = rootDef.model.knex();
+  var updatedIds = [];
+
+  var trx = await knex.transaction();
+
+  try {
+    for (var i = 0; i < changeSet.length; i++) {
+      var ids = await processEntry(changeSet[i], rootDef, trx);
+      updatedIds = updatedIds.concat(ids);
+    }
+
+    await trx.commit();
+    respond(res, HTTP.OK, STATUS.UPDATED, 'updated', { updatedIds: updatedIds });
+  } catch (err) {
+    await trx.rollback();
+    respond(res, HTTP.SERVER_ERROR, STATUS.SERVER_ERROR, 'server_error', { error: err });
+  }
+}
+
+/**
+ * Process a single changeset entry (recursive for children).
+ * @param {object} entry      - The changeset row
+ * @param {object} def        - Hierarchy definition { key, model, children, foreignKey }
+ * @param {object} trx        - Knex transaction
+ * @param {string} [parentId] - Parent record ID (set automatically for children)
+ */
+async function processEntry(entry, def, trx, parentId) {
+  var Model = def.model;
+  var children = def.children || [];
+  var ids = [];
+
+  // ── SOFT DELETE ──
+  if (entry.deleted === true) {
+    await Model.query(trx).findById(entry.id).patch({ isActive: false });
+    ids.push(entry.id);
+    return ids;
+  }
+
+  // Separate own fields from child arrays
+  var ownFields = {};
+  var childData = {};
+  var keys = Object.keys(entry);
+
+  for (var k = 0; k < keys.length; k++) {
+    var key = keys[k];
+    if (key === 'deleted') continue;
+
+    var childDef = findChildDef(children, key);
+    if (childDef) {
+      childData[key] = entry[key];
+    } else {
+      ownFields[key] = entry[key];
+    }
+  }
+
+  // Auto-set foreign key if this is a child record
+  if (def.foreignKey && parentId) {
+    ownFields[def.foreignKey] = parentId;
+  }
+
+  var recordId = ownFields.id;
+
+  // ── INSERT ──
+  if (!recordId) {
+    recordId = generateId();
+    ownFields.id = recordId;
+    await Model.query(trx).insert(ownFields);
+    ids.push(recordId);
+  } else {
+    // ── PATCH ──
+    var patchFields = Object.assign({}, ownFields);
+    delete patchFields.id;
+
+    if (Object.keys(patchFields).length > 0) {
+      await Model.query(trx).findById(recordId).patch(patchFields);
+      ids.push(recordId);
+    }
+  }
+
+  // ── Process children recursively ──
+  for (var c = 0; c < children.length; c++) {
+    var cDef = children[c];
+    var childEntries = childData[cDef.key];
+    if (!childEntries || !Array.isArray(childEntries)) continue;
+
+    for (var j = 0; j < childEntries.length; j++) {
+      var childIds = await processEntry(childEntries[j], cDef, trx, recordId);
+      ids = ids.concat(childIds);
+    }
+  }
+
+  return ids;
+}
+
+function findChildDef(children, key) {
+  for (var i = 0; i < children.length; i++) {
+    if (children[i].key === key) return children[i];
+  }
+  return null;
+}
+
+/**
+ * Delete handler — soft delete by ids.
+ */
+async function deleteByIds(req, res, Model) {
+  var ids = req.body.ids;
+
+  if (!Array.isArray(ids) || ids.length === 0) {
+    return respond(res, HTTP.BAD_REQUEST, STATUS.BAD_REQUEST, 'bad_request', {
+      message: 'Expected a non-empty ids array'
+    });
+  }
+
+  try {
+    await Model.query().whereIn('id', ids).patch({ isActive: false });
+    respond(res, HTTP.OK, STATUS.DELETED, 'deleted', { updatedIds: ids });
+  } catch (err) {
+    respond(res, HTTP.SERVER_ERROR, STATUS.SERVER_ERROR, 'server_error', { error: err });
+  }
+}
+
+/**
+ * Get by ID — single record with eager children.
+ */
+async function getById(req, res, Model, graph) {
+  try {
+    var query = Model.query().findById(req.params.id);
+    if (graph) {
+      query = query.withGraphFetched(graph);
+    }
+    var record = await query;
+
+    if (!record) {
+      return respond(res, HTTP.NOT_FOUND, STATUS.NOT_FOUND, 'not_found');
+    }
+
+    respond(res, HTTP.OK, STATUS.SUCCESS, 'success', { dataArray: [record] });
+  } catch (err) {
+    respond(res, HTTP.SERVER_ERROR, STATUS.SERVER_ERROR, 'server_error', { error: err });
+  }
+}
+
+/**
+ * List — paginated, with optional eager graph.
+ *
+ * Query params:
+ *   ?page=1&limit=50    — pagination (default: page 1, limit 50)
+ *   ?limit=0            — no pagination, return all (use carefully)
+ *
+ * Response includes pagination metadata in dataArray wrapper:
+ *   { dataArray: [...], pagination: { page, limit, total, totalPages } }
+ */
+async function list(req, res, Model, graph) {
+  try {
+    var page = parseInt(req.query.page) || 1;
+    var limit = req.query.limit !== undefined ? parseInt(req.query.limit) : 50;
+
+    var query = Model.query();
+    if (graph) {
+      query = query.withGraphFetched(graph);
+    }
+
+    // limit=0 means no pagination (return all)
+    if (limit > 0) {
+      var countResult = await Model.query().count('* as total').first();
+      var total = countResult.total || 0;
+      var totalPages = Math.ceil(total / limit);
+      var offset = (page - 1) * limit;
+
+      query = query.limit(limit).offset(offset);
+      var records = await query;
+
+      respond(res, HTTP.OK, STATUS.SUCCESS, 'success', {
+        dataArray: records,
+        pagination: { page: page, limit: limit, total: total, totalPages: totalPages }
+      });
+    } else {
+      var records = await query;
+      respond(res, HTTP.OK, STATUS.SUCCESS, 'success', { dataArray: records });
+    }
+  } catch (err) {
+    respond(res, HTTP.SERVER_ERROR, STATUS.SERVER_ERROR, 'server_error', { error: err });
+  }
+}
+
+module.exports = { save, deleteByIds, getById, list };

package/lib/genericRoute.js

@@ -0,0 +1,139 @@
+var express = require('express');
+var controller = require('./genericController');
+
+/**
+ * Generate CRUD routes for a model hierarchy.
+ *
+ * Usage:
+ *
+ *   var { genericRoute } = require('@xeplr/base-apis');
+ *
+ *   // Basic — all routes require auth
+ *   var deptRoutes = genericRoute(hierarchy, { auth: authMiddleware });
+ *
+ *   // Per-operation auth
+ *   var deptRoutes = genericRoute(hierarchy, {
+ *     auth: {
+ *       list:   authMiddleware,            // any authenticated user can list
+ *       getById: authMiddleware,
+ *       save:   [authMiddleware, adminOnly], // save needs admin
+ *       delete: [authMiddleware, adminOnly]
+ *     }
+ *   });
+ *
+ *   // No auth (dev/internal only)
+ *   var deptRoutes = genericRoute(hierarchy);
+ *
+ * Hierarchy:
+ *   {
+ *     key: 'department',
+ *     model: Department,
+ *     children: [
+ *       { key: 'employees', model: Employee,
+ *         children: [{ key: 'salaries', model: Salary }]
+ *       }
+ *     ]
+ *   }
+ *
+ * Generated routes:
+ *   GET    /              → list (paginated: ?page=1&limit=50)
+ *   GET    /:id           → get by id (with eager children)
+ *   POST   /save          → save changeset (transactional)
+ *   POST   /delete        → soft delete by ids
+ *
+ * @param {object}           hierarchy     - { key, model, children? }
+ * @param {object}           [options]
+ * @param {Function|object}  [options.auth] - Single middleware or { list, getById, save, delete }
+ * @returns {Router}
+ */
+function genericRoute(hierarchy, options) {
+  options = options || {};
+  var router = express.Router();
+  var Model = hierarchy.model;
+  var graph = buildGraph(hierarchy);
+
+  var auth = resolveAuth(options.auth);
+
+  // GET / — list (paginated)
+  router.get('/', auth.list, function(req, res) {
+    controller.list(req, res, Model, graph);
+  });
+
+  // GET /:id — get single with eager children
+  router.get('/:id', auth.getById, function(req, res) {
+    controller.getById(req, res, Model, graph);
+  });
+
+  // POST /save — process changeset
+  router.post('/save', auth.save, function(req, res) {
+    controller.save(req, res, hierarchy);
+  });
+
+  // POST /delete — soft delete by ids
+  router.post('/delete', auth.delete, function(req, res) {
+    controller.deleteByIds(req, res, Model);
+  });
+
+  return router;
+}
+
+/**
+ * Resolve auth option into per-operation middleware arrays.
+ *
+ * Input forms:
+ *   undefined              → no auth (passthrough)
+ *   Function               → same middleware for all operations
+ *   [Function, Function]   → same middleware chain for all operations
+ *   { list, save, ... }    → per-operation middleware
+ */
+function resolveAuth(auth) {
+  var noop = function(req, res, next) { next(); };
+  var defaults = { list: [noop], getById: [noop], save: [noop], delete: [noop] };
+
+  if (!auth) return defaults;
+
+  // Single function or array → apply to all operations
+  if (typeof auth === 'function' || Array.isArray(auth)) {
+    var mw = Array.isArray(auth) ? auth : [auth];
+    return { list: mw, getById: mw, save: mw, delete: mw };
+  }
+
+  // Per-operation object
+  return {
+    list:    toArray(auth.list) || defaults.list,
+    getById: toArray(auth.getById) || defaults.getById,
+    save:    toArray(auth.save) || defaults.save,
+    delete:  toArray(auth.delete) || defaults.delete
+  };
+}
+
+function toArray(val) {
+  if (!val) return null;
+  return Array.isArray(val) ? val : [val];
+}
+
+/**
+ * Build an Objection.js eager graph string from the hierarchy.
+ * { children: [{ key: 'employees', children: [{ key: 'salaries' }] }] }
+ * → '[employees.[salaries]]'
+ */
+function buildGraph(hierarchy) {
+  var children = hierarchy.children;
+  if (!children || children.length === 0) return null;
+
+  var parts = [];
+  for (var i = 0; i < children.length; i++) {
+    var child = children[i];
+    var childGraph = buildGraph(child);
+    if (childGraph) {
+      parts.push(child.key + '.' + childGraph);
+    } else {
+      parts.push(child.key);
+    }
+  }
+
+  if (parts.length === 1) return parts[0];
+  return '[' + parts.join(', ') + ']';
+}
+
+module.exports = genericRoute;

package/lib/requestLogger.js

@@ -0,0 +1,53 @@
+var fs = require('fs');
+var path = require('path');
+
+/**
+ * Request logger middleware — logs entry and exit for every API hit to a text file.
+ *
+ * @param {string} appName - Service name (used in log prefix)
+ * @param {object} [options]
+ * @param {string} [options.logDir='./logs'] - Directory for log files
+ * @param {string} [options.filename] - Log filename (default: <appName>-requests.log)
+ */
+function createRequestLogger(appName, options) {
+  options = options || {};
+  var logDir = path.resolve(options.logDir || process.env.LOG_DIR || './logs');
+  var filename = options.filename || (appName + '-requests.log');
+
+  if (!fs.existsSync(logDir)) {
+    fs.mkdirSync(logDir, { recursive: true });
+  }
+
+  var logPath = path.join(logDir, filename);
+  var stream = fs.createWriteStream(logPath, { flags: 'a' });
+
+  function timestamp() {
+    return new Date().toISOString();
+  }
+
+  function write(line) {
+    stream.write(line + '\n');
+  }
+
+  return function requestLogger(req, res, next) {
+    var id = Math.random().toString(36).slice(2, 10);
+    var method = req.method;
+    var url = req.originalUrl || req.url;
+    var entryTime = Date.now();
+
+    write('[' + timestamp() + '] [' + appName + '] [' + id + '] → ' + method + ' ' + url);
+
+    var originalEnd = res.end;
+    res.end = function() {
+      res.end = originalEnd;
+      res.end.apply(res, arguments);
+
+      var duration = Date.now() - entryTime;
+      write('[' + timestamp() + '] [' + appName + '] [' + id + '] ← ' + method + ' ' + url + ' ' + res.statusCode + ' ' + duration + 'ms');
+    };
+
+    next();
+  };
+}
+
+module.exports = createRequestLogger;

package/lib/server.js

@@ -0,0 +1,46 @@
+const http = require('http');
+
+function normalizePort(val) {
+  const port = parseInt(val, 10);
+  if (isNaN(port)) return val;   // named pipe
+  if (port >= 0) return port;
+  return false;
+}
+
+function createServer(handler, port, name) {
+  const dbg = require('debug')('architects:' + name);
+  const normalizedPort = normalizePort(port);
+
+  const server = http.createServer(handler);
+  server.listen(normalizedPort);
+
+  server.on('error', function onError(error) {
+    if (error.syscall !== 'listen') throw error;
+    const bind = typeof normalizedPort === 'string'
+      ? 'Pipe ' + normalizedPort
+      : 'Port ' + normalizedPort;
+    switch (error.code) {
+      case 'EACCES':
+        console.error(bind + ' requires elevated privileges');
+        process.exit(1);
+        break;
+      case 'EADDRINUSE':
+        console.error(bind + ' is already in use');
+        process.exit(1);
+        break;
+      default:
+        throw error;
+    }
+  });
+
+  server.on('listening', function onListening() {
+    const addr = server.address();
+    const bind = typeof addr === 'string' ? 'pipe ' + addr : 'port ' + addr.port;
+    dbg('Listening on ' + bind);
+    console.log(name + ' service listening on ' + bind);
+  });
+
+  return server;
+}
+
+module.exports = { createServer, normalizePort };

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@xeplr/base-apis",
+  "version": "1.0.0",
+  "description": "Base API bootstrapper — Express and plain HTTP server factories with middleware injection",
+  "main": "index.js",
+  "files": ["index.js", "lib/", "express.js"],
+  "keywords": ["express", "http", "api", "server", "bootstrap", "crud"],
+  "author": "xeplr",
+  "license": "MIT",
+  "repository": { "type": "git", "url": "https://github.com/Xeplr/xeplr-base-apis" },
+  "publishConfig": { "access": "public" },
+  "dependencies": {
+    "cookie-parser": "^1.4.7",
+    "cors": "^2.8.6",
+    "debug": "^4.4.3",
+    "http-errors": "^2.0.1",
+    "@xeplr/logs": "^1.0.0"
+  },
+  "peerDependencies": {
+    "express": "^4.0.0 || ^5.0.0"
+  }
+}