langaro-api 1.0.5 → 1.0.7

package/lib/cli/init.js

@@ -1,9 +1,24 @@
 const fs = require('fs');
 const path = require('path');
 const readline = require('readline');
+const crypto = require('crypto');
 
 const OWN_VERSION = require('../../package.json').version;
 
+function generateUUID() {
+  return crypto.randomUUID();
+}
+
+function generateRandomString(length = 24) {
+  const chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
+  let result = '';
+  const bytes = crypto.randomBytes(length);
+  for (let i = 0; i < length; i++) {
+    result += chars[bytes[i] % chars.length];
+  }
+  return result;
+}
+
 function ask(rl, question, defaultVal) {
   const suffix = defaultVal ? ` (${defaultVal})` : '';
   return new Promise((resolve) => {
@@ -199,11 +214,11 @@ newrelic_agent.log
 @types/generated/
 `;
 
-function envContent(port, dbName, redisPort) {
+function envContent(port, dbName, redisPort, { jwtSecret = '', masterPass = '' } = {}) {
   return `NODE_ENV="development"
 TZ="UTC"
 PORT="${port}"
-APP_URL="http://localhost:${port}"
+APP_URL="http://localhost:3000"
 API_URL="http://localhost:${port}"
 
 # Database
@@ -216,13 +231,13 @@ DB_PORT="3306"
 # Redis
 REDIS_HOST="127.0.0.1"
 REDIS_PORT="${redisPort}"
-REDIS_PASSWORD=""
+# REDIS_PASSWORD=""
 # REDIS_USERNAME=""
 # REDIS_TLS=""
 
 # Security
-JWT_SECRET=""
-MASTER_PASS=""
+JWT_SECRET="${jwtSecret}"
+MASTER_PASS="${masterPass}"
 
 # Queue Management
 BULLBOARD_PATH="/admin/queues"
@@ -380,7 +395,23 @@ class App {
 
     if (process.env.NODE_ENV !== 'test') {
       this.express.use(morgan('dev', {
-        skip: (req) => req.method === 'OPTIONS',
+        skip: (req) => {
+          // Ignore OPTIONS requests
+          if (req.method === 'OPTIONS') {
+            return true;
+          }
+
+          const skipUrls = [
+            process.env.BULLBOARD_PATH,
+            \`\${process.env.BULLBOARD_PATH}/static\`,
+          ];
+
+          if (skipUrls.indexOf(req.baseUrl) !== -1) {
+            return true;
+          }
+
+          return false;
+        },
       }));
     }
 
@@ -620,19 +651,16 @@ module.exports = function (services) {
 };
 `;
 
-const UTILS_INDEX = `const { ApiError } = require('trigger-api-error');
-const { StatusCodes } = require('http-status-codes');
-const { validateRequiredFields } = require('validate-required-fields');
-const { validateFieldsFormat } = require('validate-fields-format');
-const { fieldShouldNotBeSent } = require('forbid-fields-sent');
+const UTILS_INDEX = `export * from 'validate-required-fields';
+export * from 'trigger-api-error';
+export * from 'http-status-codes';
+export * from 'forbid-fields-sent';
+export * from 'validate-fields-format';
+export * from './sleep';
+`;
 
-module.exports = {
-  ApiError,
-  StatusCodes,
-  validateRequiredFields,
-  validateFieldsFormat,
-  fieldShouldNotBeSent,
-};
+const UTILS_SLEEP = `// eslint-disable-next-line no-promise-executor-return
+exports.sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 `;
 
 const GLOBAL_SETUP_TESTS = `require('dotenv').config({ path: '.env.test' });
@@ -648,6 +676,319 @@ const matchers = require('jest-extended');
 expect.extend(matchers);
 `;
 
+const QUEUES_JS = `require('dotenv').config({
+  path: process.env.NODE_ENV === 'test' ? '.env.test' : '.env',
+});
+
+const Sentry = require('@/config/instrument');
+const redisConfig = require('@/database/redis-config');
+const IORedis = require('ioredis');
+const { Queue, Worker } = require('bullmq');
+const { BullMQAdapter } = require('@bull-board/api/bullMQAdapter');
+const { sleep } = require('@/utils');
+
+const isTestEnv = process.env.NODE_ENV === 'test';
+const inactivityCheckIntervalMs = 1 * 60 * 1000;
+const inactivityTimeLimitMs = 10 * 60 * 1000;
+
+let isShuttingDown = false;
+let connection;
+const jobConfigs = new Map();
+const activeQueues = new Map();
+let ioRef;
+let bullBoardUpdateQueuesRef;
+let cleanupIntervalId = null;
+
+function createRedisConnection() {
+  const connectionInstance = new IORedis(redisConfig.connection);
+  connectionInstance.on('error', (error) => {
+    console.error('Redis Connection Error:', error);
+    Sentry.captureException(error, { tags: { service: 'redis' } });
+  });
+  return connectionInstance;
+}
+
+function getDefaultJobOptions() {
+  return {
+    attempts: 100,
+    backoff: { type: 'fixed', delay: 1000 * 60 },
+    removeOnComplete: { age: 60 * 60 * 24 * 30, count: 1000 },
+    removeOnFail: { age: 60 * 60 * 24 * 90, count: 5000 },
+  };
+}
+
+function getDefaultWorkerOptions() {
+  return {
+    autorun: false,
+    limiter: { max: 2, duration: 1000 },
+    maxStalledCount: 5,
+  };
+}
+
+function updateBullBoard() {
+  if (bullBoardUpdateQueuesRef && typeof bullBoardUpdateQueuesRef === 'function') {
+    bullBoardUpdateQueuesRef(Array.from(activeQueues.values()).map((qd) => new BullMQAdapter(qd.queue)));
+  }
+}
+
+async function getOrCreateQueueAndWorker(queueName, groupId, baseConfig) {
+  const queueNameWithGroupId = \`\${queueName}\${groupId ? \`-\${groupId}\` : ''}\`;
+
+  if (activeQueues.has(queueNameWithGroupId)) {
+    const existing = activeQueues.get(queueNameWithGroupId);
+    existing.lastActivity = Date.now();
+    return existing;
+  }
+
+  console.log(\`Creating queue and worker for: \${queueNameWithGroupId}\`);
+
+  const finalJobOptions = { ...getDefaultJobOptions(), ...(baseConfig.jobOptions || {}) };
+  const queue = new Queue(queueNameWithGroupId, { connection, defaultJobOptions: finalJobOptions });
+
+  const finalWorkerOptions = { connection, ...getDefaultWorkerOptions(), ...(baseConfig.workerOptions || {}) };
+  const worker = new Worker(
+    queueNameWithGroupId,
+    async (jobObj) => {
+      const queueData = activeQueues.get(queueNameWithGroupId);
+      if (queueData) { queueData.lastActivity = Date.now(); }
+      // eslint-disable-next-line no-use-before-define
+      await baseConfig.handle(jobObj.data, jobObj, { add }, ioRef);
+    },
+    finalWorkerOptions,
+  );
+
+  worker.on('failed', (job, error) => {
+    Sentry.captureException(error, {
+      tags: { queue: queueNameWithGroupId },
+      contexts: { data: { 'Job data': job?.data, queue: queueNameWithGroupId } },
+    });
+  });
+
+  worker.on('error', (error) => {
+    Sentry.captureException(error, { tags: { queue: queueNameWithGroupId, event: 'worker-error' } });
+  });
+
+  const queueData = {
+    queue, worker, lastActivity: Date.now(), name: queueNameWithGroupId, queueName, groupId,
+  };
+
+  if (!isShuttingDown) {
+    activeQueues.set(queueNameWithGroupId, queueData);
+    worker.run();
+    console.log(\`Worker running for: \${queueNameWithGroupId}\`);
+  }
+
+  updateBullBoard();
+  return queueData;
+}
+
+// eslint-disable-next-line no-unused-vars
+async function add(queueName, data, options = {}) {
+  const baseConfig = jobConfigs.get(queueName);
+  if (!baseConfig) {
+    throw new Error(\`Queue configuration not found for: \${queueName}\`);
+  }
+
+  try {
+    if (baseConfig.group && !options.groupId) {
+      throw new Error(\`Missing groupId for grouped queue: \${queueName}\`);
+    }
+
+    const queueData = await getOrCreateQueueAndWorker(queueName, options.groupId, baseConfig);
+    await queueData.queue.add(queueData.name, data, options);
+  } catch (error) {
+    console.error(\`Failed to add job to queue \${queueName}:\`, error);
+    Sentry.captureException(error, { tags: { queue: queueName, operation: 'addJob' } });
+    throw error;
+  }
+}
+
+async function closeInactiveQueues() {
+  const now = Date.now();
+  const queuesToRemove = [];
+
+  const checks = Array.from(activeQueues.entries()).map(async ([queueName, queueData]) => {
+    if (now - queueData.lastActivity <= inactivityTimeLimitMs) return;
+    try {
+      const [activeCount, waitingCount, delayedCount] = await Promise.all([
+        queueData.queue.getActiveCount(),
+        queueData.queue.getWaitingCount(),
+        queueData.queue.getDelayedCount(),
+      ]);
+      if (activeCount === 0 && waitingCount === 0 && delayedCount === 0) {
+        queuesToRemove.push(queueName);
+      }
+    } catch (error) {
+      Sentry.captureException(error, { tags: { queue: queueName, operation: 'checkBeforeClose' } });
+    }
+  });
+
+  await Promise.allSettled(checks);
+  if (queuesToRemove.length === 0) return;
+
+  await Promise.allSettled(
+    queuesToRemove.map(async (queueName) => {
+      const queueData = activeQueues.get(queueName);
+      if (!queueData) return;
+      try {
+        await queueData.worker.close();
+        await queueData.queue.close();
+        activeQueues.delete(queueName);
+      } catch (error) {
+        Sentry.captureException(error, { tags: { queue: queueName, operation: 'closeInactive' } });
+      }
+    }),
+  );
+
+  updateBullBoard();
+}
+
+function startCleanupInterval() {
+  if (cleanupIntervalId) clearInterval(cleanupIntervalId);
+  if (!isTestEnv) {
+    cleanupIntervalId = setInterval(closeInactiveQueues, inactivityCheckIntervalMs);
+  }
+}
+
+async function startWorkersForExistingQueues() {
+  if (!connection) return;
+
+  const stream = connection.scanStream({ match: 'bull:*:meta', count: 1000 });
+  const potentialQueueNames = new Set();
+
+  stream.on('data', (keys) => {
+    (keys || []).forEach((key) => {
+      const match = key.match(/^bull:(.+):meta$/);
+      if (match && match[1]) potentialQueueNames.add(match[1]);
+    });
+  });
+
+  try {
+    await new Promise((resolve, reject) => { stream.on('end', resolve); stream.on('error', reject); });
+  } catch (error) {
+    Sentry.captureException(error, { tags: { operation: 'startWorkersForExistingQueues' } });
+    return;
+  }
+
+  if (potentialQueueNames.size === 0) return;
+
+  const sortedConfigKeys = Array.from(jobConfigs.keys()).sort((a, b) => b.length - a.length);
+
+  await Promise.all(
+    Array.from(potentialQueueNames).map(async (fullQueueName) => {
+      let baseName = null;
+      let groupId = null;
+      let config = null;
+
+      sortedConfigKeys.some((potentialBase) => {
+        const baseConfig = jobConfigs.get(potentialBase);
+        if (fullQueueName === potentialBase && !baseConfig.group) {
+          baseName = potentialBase;
+          config = baseConfig;
+          return true;
+        }
+        if (baseConfig.group && fullQueueName.startsWith(\`\${potentialBase}-\`)) {
+          baseName = potentialBase;
+          groupId = fullQueueName.slice(potentialBase.length + 1);
+          config = baseConfig;
+          return true;
+        }
+        return false;
+      });
+
+      if (!config || activeQueues.has(fullQueueName)) return;
+
+      try {
+        const activeCount = await connection.llen(\`bull:\${fullQueueName}:active\`);
+        const waitCount = await connection.llen(\`bull:\${fullQueueName}:wait\`);
+        const delayedCount = await connection.zcard(\`bull:\${fullQueueName}:delayed\`);
+
+        if (waitCount > 0 || delayedCount > 0 || activeCount > 0) {
+          await getOrCreateQueueAndWorker(baseName, groupId, config);
+        }
+      } catch (error) {
+        Sentry.captureException(error, { tags: { queue: fullQueueName, operation: 'startupScanInit' } });
+      }
+    }),
+  );
+}
+
+async function initializeQueues(services, socketIo, bullBoardReplaceQueues) {
+  if (isTestEnv) { return { add: jest.fn() }; }
+
+  console.log('Queue system initializing...');
+
+  connection = createRedisConnection();
+  ioRef = socketIo;
+  bullBoardUpdateQueuesRef = bullBoardReplaceQueues;
+
+  const { loadJobs } = require('langaro-api');
+  const jobs = loadJobs(services);
+  Object.entries(jobs).forEach(([name, job]) => {
+    jobConfigs.set(name, {
+      handle: job.handle,
+      jobOptions: job.jobOptions || {},
+      workerOptions: job.workerOptions || {},
+      group: job.group,
+    });
+  });
+
+  await startWorkersForExistingQueues();
+  startCleanupInterval();
+
+  console.log('Queue system initialized.');
+  return { add };
+}
+
+async function shutdownQueues() {
+  if (isShuttingDown) return;
+  isShuttingDown = true;
+
+  console.log('Gracefully shutting down queues...');
+
+  if (cleanupIntervalId) {
+    clearInterval(cleanupIntervalId);
+    cleanupIntervalId = null;
+  }
+
+  const activeQueuesValues = Array.from(activeQueues.values());
+
+  await Promise.allSettled(activeQueuesValues.map(async (qd) => {
+    try { await qd.worker.pause(); } catch (e) { console.error(\`Error pausing \${qd.name}:\`, e); }
+  }));
+
+  let retries = 0;
+  const maxRetries = 400;
+  while (retries++ < maxRetries) {
+    const stillActive = await Promise.all(activeQueuesValues.map((qd) => qd.queue.getActiveCount()));
+    if (stillActive.reduce((a, b) => a + b, 0) === 0) break;
+    await sleep(3000);
+  }
+
+  await Promise.allSettled(activeQueuesValues.map(async (qd) => {
+    try {
+      await qd.worker.close();
+      await qd.queue.close();
+    } catch (e) {
+      Sentry.captureException(e, { tags: { queue: qd.name, operation: 'shutdown' } });
+    }
+  }));
+
+  activeQueues.clear();
+  jobConfigs.clear();
+
+  if (connection) {
+    try { await connection.quit(); } catch (e) {
+      Sentry.captureException(e, { tags: { service: 'redis', operation: 'quit' } });
+    }
+  }
+
+  console.log('Queue shutdown complete.');
+}
+
+module.exports = { initializeQueues, shutdownQueues };
+`;
+
 const MODELS_INDEX = `const { loadModels } = require('langaro-api');
 
 module.exports = (knexInstance) => loadModels(knexInstance, __dirname);
@@ -726,12 +1067,16 @@ async function run() {
   writeFile(root, 'jest.config.js', JEST_CONFIG);
   writeFile(root, '.gitignore', GITIGNORE);
   writeFile(root, '.env.example', envContent(port, dbName, redisPort));
-  writeFile(root, '.env', envContent(port, dbName, redisPort));
+  writeFile(root, '.env', envContent(port, dbName, redisPort, {
+    jwtSecret: generateUUID(),
+    masterPass: generateRandomString(24),
+  }));
 
   // src/config/
   writeFile(root, 'src/config/server.js', serverJs(port));
   writeFile(root, 'src/config/app.js', APP_JS);
   writeFile(root, 'src/config/instrument.js', INSTRUMENT_JS);
+  writeFile(root, 'src/config/queues.js', QUEUES_JS);
   writeFile(root, 'src/config/tests/global-setup-tests.js', GLOBAL_SETUP_TESTS);
   writeFile(root, 'src/config/tests/setup-tests.js', SETUP_TESTS);
 
@@ -753,6 +1098,7 @@ async function run() {
 
   // src/utils
   writeFile(root, 'src/utils/index.js', UTILS_INDEX);
+  writeFile(root, 'src/utils/sleep.js', UTILS_SLEEP);
 
   // Empty directories
   ['src/integrations', 'src/static', 'src/temp', 'src/database/tests'].forEach((dir) => {
@@ -762,7 +1108,7 @@ async function run() {
   console.log(`\n\x1b[32mProject scaffolded!\x1b[0m\n`);
   console.log('Next steps:');
   console.log(`  1. \x1b[36mnpm install\x1b[0m`);
-  console.log(`  2. Fill in your secrets in \x1b[36m.env\x1b[0m (JWT_SECRET, DB_PASSWORD, etc.)`);
+  console.log(`  2. Fill in your \x1b[36m.env\x1b[0m (DB_PASSWORD, etc.)`);
   console.log(`  3. Create the \x1b[36m${dbName}\x1b[0m database in MySQL`);
   console.log(`  4. \x1b[36mnpm run dev\x1b[0m`);
   console.log(`  5. \x1b[36mnpx langaro-api new\x1b[0m to create your first resource\n`);

package/lib/generators/controllers.js

@@ -1,6 +1,7 @@
 const fs = require('fs');
 const path = require('path');
-const { pascalCase, extractMethods } = require('../utils');
+const { pascalCase, extractMethodsWithLocations } = require('../utils');
+const { generateSourceMap } = require('../sourcemap');
 
 function scanControllerEntries(controllersDir) {
   const entries = [];
@@ -22,42 +23,102 @@ function scanControllerEntries(controllersDir) {
   return entries.sort((a, b) => a.tableName.localeCompare(b.tableName));
 }
 
-function generateControllersDts(controllersDir) {
+function resolveServiceFile(tableName, servicesDir, modelsDir) {
+  if (servicesDir) {
+    const serviceFile = path.join(servicesDir, `${tableName}.services.js`);
+    if (fs.existsSync(serviceFile)) return serviceFile;
+  }
+  if (modelsDir) {
+    const modelFile = path.join(modelsDir, `${tableName}.model.js`);
+    if (fs.existsSync(modelFile)) return modelFile;
+  }
+  return null;
+}
+
+function generateControllersDts(controllersDir, outputDir, servicesDir, modelsDir) {
   const lines = ['// Auto-generated by langaro-api — DO NOT EDIT', ''];
   const controllerEntries = scanControllerEntries(controllersDir);
+  const mappings = [];
+  const sources = [];
+  const sourceIndexMap = {};
+
+  function getSourceIndex(filePath) {
+    const rel = path.relative(outputDir, filePath).replace(/\\/g, '/');
+    if (!(rel in sourceIndexMap)) {
+      sourceIndexMap[rel] = sources.length;
+      sources.push(rel);
+    }
+    return sourceIndexMap[rel];
+  }
+
+  function addMapping(col, sourceIdx, srcLine, srcCol) {
+    mappings.push({
+      genLine: lines.length,
+      genCol: col,
+      sourceIndex: sourceIdx,
+      sourceLine: srcLine,
+      sourceCol: srcCol,
+    });
+  }
 
   // Base classes for JSDoc @param on "ServicesClass"
-  controllerEntries.forEach(({ tableName }) => {
+  controllerEntries.forEach(({ tableName, filePath }) => {
     const pc = pascalCase(tableName);
-    lines.push(
-      `declare class ${pc}ControllerBase {`,
-      `  service: ServicesMap['${pc}Services'];`,
-      '  services: ServicesMap;',
-      '  Queue: QueueMap;',
-      '  io: any;',
-      '}',
-      '',
-    );
+    const controllerIdx = getSourceIndex(filePath);
+    const serviceFile = resolveServiceFile(tableName, servicesDir, modelsDir);
+    const serviceIdx = serviceFile ? getSourceIndex(serviceFile) : controllerIdx;
+
+    addMapping(0, controllerIdx, 0, 0);
+    lines.push(`declare class ${pc}ControllerBase {`);
+
+    // service: property → maps to the service/model file
+    addMapping(0, serviceIdx, 0, 0);
+    lines.push(`  service: ServicesMap['${pc}Services'];`);
+
+    // remaining properties → map to controller file
+    addMapping(0, controllerIdx, 0, 0);
+    lines.push('  services: ServicesMap;');
+    addMapping(0, controllerIdx, 0, 0);
+    lines.push('  Queue: QueueMap;');
+    addMapping(0, controllerIdx, 0, 0);
+    lines.push('  io: any;');
+    addMapping(0, controllerIdx, 0, 0);
+    lines.push('}');
+    lines.push('');
   });
 
   // Controller interfaces with their methods (for router autocomplete)
   controllerEntries.forEach(({ tableName, filePath }) => {
     const pc = pascalCase(tableName);
-    const methods = extractMethods(filePath);
+    const methods = extractMethodsWithLocations(filePath);
+    const sourceIdx = getSourceIndex(filePath);
+
+    addMapping(0, sourceIdx, 0, 0);
     lines.push(`declare interface I${pc}Controller extends ${pc}ControllerBase {`);
-    methods.forEach((m) => lines.push(`  ${m}(...args: any[]): any;`));
-    lines.push('}', '');
+    methods.forEach((m) => {
+      addMapping(2, sourceIdx, m.line, m.col);
+      lines.push(`  ${m.name}(...args: any[]): any;`);
+    });
+    addMapping(0, sourceIdx, 0, 0);
+    lines.push('}');
+    lines.push('');
   });
 
-  // ControllersMap — used to type the "controllers" param in routers
+  // ControllersMap
   lines.push('declare interface ControllersMap {');
-  controllerEntries.forEach(({ tableName }) => {
+  controllerEntries.forEach(({ tableName, filePath }) => {
     const pc = pascalCase(tableName);
+    addMapping(2, getSourceIndex(filePath), 0, 0);
     lines.push(`  ${pc}Controller: I${pc}Controller;`);
   });
   lines.push('}', '');
 
-  return lines.join('\n');
+  lines.push('//# sourceMappingURL=controllers.d.ts.map');
+
+  const content = lines.join('\n');
+  const sourceMap = generateSourceMap('controllers.d.ts', sources, mappings);
+
+  return { content, sourceMap };
 }
 
 module.exports = { scanControllerEntries, generateControllersDts };

package/lib/generators/crud.js

@@ -1,69 +1,159 @@
-module.exports = function generateCrudDts() {
-  return [
+const path = require('path');
+const { extractMethodsWithLocations } = require('../utils');
+const { generateSourceMap } = require('../sourcemap');
+
+// Extract method name from a .d.ts declaration line like "  getWhere(...): ..."
+function extractMethodName(line) {
+  const match = line.match(/^\s+([a-zA-Z_$][a-zA-Z0-9_$]*)\s*\(/);
+  return match ? match[1] : null;
+}
+
+module.exports = function generateCrudDts(projectRoot, outputDir) {
+  // Try to resolve knex-extended-crud source
+  let crudSourcePath = null;
+  let methodLineMap = {};
+
+  if (projectRoot && outputDir) {
+    try {
+      crudSourcePath = require.resolve('knex-extended-crud', {
+        paths: [projectRoot],
+      });
+      const methods = extractMethodsWithLocations(crudSourcePath);
+      methods.forEach((m) => {
+        methodLineMap[m.name] = { line: m.line, col: m.col };
+      });
+    } catch {
+      crudSourcePath = null;
+    }
+  }
+
+  const hasMappings = !!crudSourcePath;
+  const mappings = [];
+  const sources = [];
+  let sourceIdx = -1;
+
+  if (hasMappings) {
+    const rel = path.relative(outputDir, crudSourcePath).replace(/\\/g, '/');
+    sources.push(rel);
+    sourceIdx = 0;
+  }
+
+  function addMethodMapping(linesArr, methodName) {
+    if (!hasMappings) return;
+    const loc = methodLineMap[methodName];
+    if (loc) {
+      mappings.push({
+        genLine: linesArr.length,
+        genCol: 2,
+        sourceIndex: sourceIdx,
+        sourceLine: loc.line,
+        sourceCol: loc.col,
+      });
+    }
+  }
+
+  const lines = [
     '// Auto-generated by langaro-api — DO NOT EDIT',
     '',
-    'declare class CRUD {',
-    '  table: string;',
-    '  knex: any;',
-    '  hide: string[];',
-    '  append: string[];',
-    '  fields: Record<string, any>;',
-    '  schema: any;',
-    '  options: {',
-    '    perPage: number;',
-    '    currentPage: number;',
-    '    isLengthAware: boolean;',
-    '    exactMatch: boolean;',
-    '    sortBy: string;',
-    '    sort: string;',
-    '  };',
-    '',
-    '  createTransaction(): Promise<any>;',
-    '',
-    '  create(data?: Record<string, any>, transaction?: any): Promise<{ success: boolean; data: any }>;',
-    '  batchCreate(data?: any[], transaction?: any): Promise<{ success: boolean; data: any[] }>;',
-    '',
-    '  get(options?: CRUDGetOptions, transaction?: any): Promise<{ success: boolean; data: any[]; pagination?: any }>;',
-    '  getWhere(prop: string, value: any, options?: CRUDGetOptions, transaction?: any): Promise<{ success: boolean; data: any }>;',
-    '  search(field: string, term: string, options?: CRUDGetOptions, transaction?: any): Promise<{ success: boolean; data: any[] }>;',
-    '  count(options?: CRUDGetOptions, transaction?: any): Promise<number>;',
-    '',
-    '  updateWhere(',
-    '    prop: string, value: any, data?: Record<string, any>,',
-    '    options?: CRUDUpdateOptions, transaction?: any',
-    '  ): Promise<{ success: boolean; data: any }>;',
-    '  batchUpdate(data: any[], options?: CRUDBatchUpdateOptions, transaction?: any): Promise<any[]>;',
-    '',
-    '  deleteWhere(',
-    '    prop: string, values: any, options?: CRUDDeleteOptions, transaction?: any',
-    '  ): Promise<{ success: boolean; data: any }>;',
-    '',
-    '  defaultInsertValidations(',
-    '    requestData: Record<string, any>, options?: Record<string, any>, transaction?: any',
-    '  ): Promise<Record<string, any>>;',
-    '  defaultUpdateValidations(',
-    '    itemId: any, requestData: Record<string, any>,',
-    '    options?: Record<string, any>, transaction?: any',
-    '  ): Promise<Record<string, any>>;',
-    '  validateAndFormatFields(',
-    '    data: Record<string, any>, skipFields?: string[], transaction?: any',
-    '  ): Promise<{ success: boolean; data?: Record<string, any>; err?: string }>;',
-    '  validateForeignIds(data: Record<string, any>, transaction?: any): Promise<void>;',
-    '',
-    '  tableInfo(options?: Record<string, any>, transaction?: any): Promise<Record<string, any>>;',
-    '  requiredFields(options?: Record<string, any>, transaction?: any): Promise<{ data: string[] }>;',
-    '',
-    '  appendItems(',
-    '    items: any[], appendArr: string[], appendOptions?: Record<string, any>, transaction?: any',
-    '  ): Promise<any[]>;',
-    '  refreshCache(transaction?: any): Promise<void>;',
-    '  clearSchemaCache(): void;',
-    '  clearTableCache(tableName: string): void;',
-    '  disableCache(): void;',
-    '  enableCache(): void;',
-    '  setCacheTimeout(timeout: number): void;',
-    '}',
-    '',
+  ];
+
+  // CRUD class
+  lines.push('declare class CRUD {');
+  lines.push('  table: string;');
+  lines.push('  knex: any;');
+  lines.push('  hide: string[];');
+  lines.push('  append: string[];');
+  lines.push('  fields: Record<string, any>;');
+  lines.push('  schema: any;');
+  lines.push('  options: {');
+  lines.push('    perPage: number;');
+  lines.push('    currentPage: number;');
+  lines.push('    isLengthAware: boolean;');
+  lines.push('    exactMatch: boolean;');
+  lines.push('    sortBy: string;');
+  lines.push('    sort: string;');
+  lines.push('  };');
+  lines.push('');
+
+  addMethodMapping(lines, 'createTransaction');
+  lines.push('  createTransaction(): Promise<any>;');
+  lines.push('');
+
+  addMethodMapping(lines, 'create');
+  lines.push('  create(data?: Record<string, any>, transaction?: any): Promise<{ success: boolean; data: any }>;');
+  addMethodMapping(lines, 'batchCreate');
+  lines.push('  batchCreate(data?: any[], transaction?: any): Promise<{ success: boolean; data: any[] }>;');
+  lines.push('');
+
+  addMethodMapping(lines, 'get');
+  lines.push('  get(options?: CRUDGetOptions, transaction?: any): Promise<{ success: boolean; data: any[]; pagination?: any }>;');
+  addMethodMapping(lines, 'getWhere');
+  lines.push('  getWhere(prop: string, value: any, options?: CRUDGetOptions, transaction?: any): Promise<{ success: boolean; data: any }>;');
+  addMethodMapping(lines, 'search');
+  lines.push('  search(field: string, term: string, options?: CRUDGetOptions, transaction?: any): Promise<{ success: boolean; data: any[] }>;');
+  addMethodMapping(lines, 'count');
+  lines.push('  count(options?: CRUDGetOptions, transaction?: any): Promise<number>;');
+  lines.push('');
+
+  addMethodMapping(lines, 'updateWhere');
+  lines.push('  updateWhere(');
+  lines.push('    prop: string, value: any, data?: Record<string, any>,');
+  lines.push('    options?: CRUDUpdateOptions, transaction?: any');
+  lines.push('  ): Promise<{ success: boolean; data: any }>;');
+  addMethodMapping(lines, 'batchUpdate');
+  lines.push('  batchUpdate(data: any[], options?: CRUDBatchUpdateOptions, transaction?: any): Promise<any[]>;');
+  lines.push('');
+
+  addMethodMapping(lines, 'deleteWhere');
+  lines.push('  deleteWhere(');
+  lines.push('    prop: string, values: any, options?: CRUDDeleteOptions, transaction?: any');
+  lines.push('  ): Promise<{ success: boolean; data: any }>;');
+  lines.push('');
+
+  addMethodMapping(lines, 'defaultInsertValidations');
+  lines.push('  defaultInsertValidations(');
+  lines.push('    requestData: Record<string, any>, options?: Record<string, any>, transaction?: any');
+  lines.push('  ): Promise<Record<string, any>>;');
+  addMethodMapping(lines, 'defaultUpdateValidations');
+  lines.push('  defaultUpdateValidations(');
+  lines.push('    itemId: any, requestData: Record<string, any>,');
+  lines.push('    options?: Record<string, any>, transaction?: any');
+  lines.push('  ): Promise<Record<string, any>>;');
+  addMethodMapping(lines, 'validateAndFormatFields');
+  lines.push('  validateAndFormatFields(');
+  lines.push('    data: Record<string, any>, skipFields?: string[], transaction?: any');
+  lines.push('  ): Promise<{ success: boolean; data?: Record<string, any>; err?: string }>;');
+  addMethodMapping(lines, 'validateForeignIds');
+  lines.push('  validateForeignIds(data: Record<string, any>, transaction?: any): Promise<void>;');
+  lines.push('');
+
+  addMethodMapping(lines, 'tableInfo');
+  lines.push('  tableInfo(options?: Record<string, any>, transaction?: any): Promise<Record<string, any>>;');
+  addMethodMapping(lines, 'requiredFields');
+  lines.push('  requiredFields(options?: Record<string, any>, transaction?: any): Promise<{ data: string[] }>;');
+  lines.push('');
+
+  addMethodMapping(lines, 'appendItems');
+  lines.push('  appendItems(');
+  lines.push('    items: any[], appendArr: string[], appendOptions?: Record<string, any>, transaction?: any');
+  lines.push('  ): Promise<any[]>;');
+  addMethodMapping(lines, 'refreshCache');
+  lines.push('  refreshCache(transaction?: any): Promise<void>;');
+  addMethodMapping(lines, 'clearSchemaCache');
+  lines.push('  clearSchemaCache(): void;');
+  addMethodMapping(lines, 'clearTableCache');
+  lines.push('  clearTableCache(tableName: string): void;');
+  addMethodMapping(lines, 'disableCache');
+  lines.push('  disableCache(): void;');
+  addMethodMapping(lines, 'enableCache');
+  lines.push('  enableCache(): void;');
+  addMethodMapping(lines, 'setCacheTimeout');
+  lines.push('  setCacheTimeout(timeout: number): void;');
+  lines.push('}');
+  lines.push('');
+
+  // Options interfaces (no source mappings needed)
+  lines.push(
     'declare interface CRUDGetOptions {',
     '  perPage?: number;',
     '  currentPage?: number;',
@@ -153,5 +243,16 @@ module.exports = function generateCrudDts() {
     '  };',
     '}',
     '',
-  ].join('\n');
+  );
+
+  if (hasMappings) {
+    lines.push('//# sourceMappingURL=crud.d.ts.map');
+  }
+
+  const content = lines.join('\n');
+  const sourceMap = hasMappings
+    ? generateSourceMap('crud.d.ts', sources, mappings)
+    : null;
+
+  return { content, sourceMap };
 };

package/lib/generators/services.js

@@ -1,10 +1,23 @@
 const fs = require('fs');
 const path = require('path');
-const { pascalCase, extractMethods, isCustomService } = require('../utils');
+const { pascalCase, extractMethodsWithLocations, isCustomService } = require('../utils');
+const { generateSourceMap } = require('../sourcemap');
 
-module.exports = function generateServicesDts(servicesDir, modelsDir) {
+module.exports = function generateServicesDts(servicesDir, modelsDir, outputDir) {
   const lines = ['// Auto-generated by langaro-api — DO NOT EDIT', ''];
   const serviceEntries = [];
+  const mappings = [];
+  const sources = [];
+  const sourceIndexMap = {};
+
+  function getSourceIndex(filePath) {
+    const rel = path.relative(outputDir, filePath).replace(/\\/g, '/');
+    if (!(rel in sourceIndexMap)) {
+      sourceIndexMap[rel] = sources.length;
+      sources.push(rel);
+    }
+    return sourceIndexMap[rel];
+  }
 
   // Services with custom .services.js files
   if (fs.existsSync(servicesDir)) {
@@ -17,22 +30,42 @@ module.exports = function generateServicesDts(servicesDir, modelsDir) {
         const interfaceName = `I${serviceName}`;
         const filePath = path.join(servicesDir, file);
         const custom = isCustomService(filePath);
-        const methods = extractMethods(filePath);
+        const methods = extractMethodsWithLocations(filePath);
+        const sourceIdx = getSourceIndex(filePath);
+
+        const addMapping = (col, srcLine, srcCol) => {
+          mappings.push({
+            genLine: lines.length,
+            genCol: col,
+            sourceIndex: sourceIdx,
+            sourceLine: srcLine,
+            sourceCol: srcCol,
+          });
+        };
 
         if (custom) {
+          addMapping(0, 0, 0);
           lines.push(`declare interface ${interfaceName} {`);
+          addMapping(0, 0, 0);
           lines.push('  table: string;');
         } else {
+          addMapping(0, 0, 0);
           lines.push(`declare interface ${interfaceName} extends CRUD {`);
         }
-        methods.forEach((m) => lines.push(`  ${m}(...args: any[]): any;`));
-        lines.push('}', '');
+        methods.forEach((m) => {
+          addMapping(2, m.line, m.col);
+          lines.push(`  ${m.name}(...args: any[]): any;`);
+        });
+        addMapping(0, 0, 0);
+        lines.push('}');
+        lines.push('');
 
         serviceEntries.push({
           interfaceName,
           serviceName,
           tableName,
           custom,
+          sourceIdx,
         });
       });
   }
@@ -60,12 +93,22 @@ module.exports = function generateServicesDts(servicesDir, modelsDir) {
   lines.push('declare interface ServicesMap {');
   serviceEntries
     .sort((a, b) => a.serviceName.localeCompare(b.serviceName))
-    .forEach(({ interfaceName, serviceName }) => {
+    .forEach(({ interfaceName, serviceName, sourceIdx }) => {
+      const genLine = lines.length;
       lines.push(`  ${serviceName}: ${interfaceName};`);
+      if (sourceIdx !== undefined) {
+        mappings.push({
+          genLine,
+          genCol: 2,
+          sourceIndex: sourceIdx,
+          sourceLine: 0,
+          sourceCol: 0,
+        });
+      }
     });
   lines.push('}', '');
 
-  // ModelsConstructorMap — typed table names for "new models.xxx()"
+  // ModelsConstructorMap
   lines.push('declare interface ModelsConstructorMap {');
   serviceEntries
     .filter(({ custom }) => !custom)
@@ -77,10 +120,26 @@ module.exports = function generateServicesDts(servicesDir, modelsDir) {
   lines.push('}', '');
 
   // Base classes for JSDoc @param on the "model" parameter
-  serviceEntries.forEach(({ serviceName, custom }) => {
-    if (!custom) lines.push(`declare class ${serviceName}Base extends CRUD {}`);
+  serviceEntries.forEach(({ serviceName, custom, sourceIdx }) => {
+    if (!custom) {
+      if (sourceIdx !== undefined) {
+        mappings.push({
+          genLine: lines.length,
+          genCol: 0,
+          sourceIndex: sourceIdx,
+          sourceLine: 0,
+          sourceCol: 0,
+        });
+      }
+      lines.push(`declare class ${serviceName}Base extends CRUD {}`);
+    }
   });
   lines.push('');
 
-  return lines.join('\n');
+  lines.push('//# sourceMappingURL=services.d.ts.map');
+
+  const content = lines.join('\n');
+  const sourceMap = generateSourceMap('services.d.ts', sources, mappings);
+
+  return { content, sourceMap };
 };

package/lib/index.js

@@ -44,9 +44,21 @@ function generateTypes(userConfig = {}) {
 
   // Generate .d.ts files
   fs.mkdirSync(outputDir, { recursive: true });
-  fs.writeFileSync(path.join(outputDir, 'crud.d.ts'), generateCrudDts());
-  fs.writeFileSync(path.join(outputDir, 'services.d.ts'), generateServicesDts(servicesDir, modelsDir));
-  fs.writeFileSync(path.join(outputDir, 'controllers.d.ts'), generateControllersDts(controllersDir));
+
+  const crud = generateCrudDts(root, outputDir);
+  fs.writeFileSync(path.join(outputDir, 'crud.d.ts'), crud.content);
+  if (crud.sourceMap) {
+    fs.writeFileSync(path.join(outputDir, 'crud.d.ts.map'), crud.sourceMap);
+  }
+
+  const services = generateServicesDts(servicesDir, modelsDir, outputDir);
+  fs.writeFileSync(path.join(outputDir, 'services.d.ts'), services.content);
+  fs.writeFileSync(path.join(outputDir, 'services.d.ts.map'), services.sourceMap);
+
+  const controllers = generateControllersDts(controllersDir, outputDir, servicesDir, modelsDir);
+  fs.writeFileSync(path.join(outputDir, 'controllers.d.ts'), controllers.content);
+  fs.writeFileSync(path.join(outputDir, 'controllers.d.ts.map'), controllers.sourceMap);
+
   fs.writeFileSync(path.join(outputDir, 'index.d.ts'), generateIndexDts());
 
   // Inject JSDoc annotations into source files

package/lib/sourcemap.js

@@ -0,0 +1,67 @@
+const BASE64 = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+
+function encodeVLQ(value) {
+  let vlq = value < 0 ? (-value << 1) + 1 : value << 1;
+  let encoded = '';
+  do {
+    let digit = vlq & 0x1f;
+    vlq >>>= 5;
+    if (vlq > 0) digit |= 0x20;
+    encoded += BASE64[digit];
+  } while (vlq > 0);
+  return encoded;
+}
+
+/**
+ * Generate a source map JSON string.
+ *
+ * @param {string} generatedFile - The name of the generated .d.ts file
+ * @param {string[]} sources - Array of relative source file paths
+ * @param {Array<{genLine: number, genCol: number, sourceIndex: number, sourceLine: number, sourceCol: number}>} mappings
+ * @returns {string} JSON source map
+ */
+function generateSourceMap(generatedFile, sources, mappings) {
+  const sorted = [...mappings].sort((a, b) => a.genLine - b.genLine || a.genCol - b.genCol);
+
+  let prevGenLine = 0;
+  let prevSourceIndex = 0;
+  let prevSourceLine = 0;
+  let prevSourceCol = 0;
+
+  const lineSegments = [];
+
+  sorted.forEach((m) => {
+    // Fill empty lines with ;
+    while (prevGenLine < m.genLine) {
+      lineSegments.push('');
+      prevGenLine++;
+    }
+
+    const segment =
+      encodeVLQ(m.genCol) +
+      encodeVLQ(m.sourceIndex - prevSourceIndex) +
+      encodeVLQ(m.sourceLine - prevSourceLine) +
+      encodeVLQ(m.sourceCol - prevSourceCol);
+
+    // Append to current line
+    if (lineSegments.length === 0 || prevGenLine > lineSegments.length - 1) {
+      lineSegments.push(segment);
+    } else {
+      const existing = lineSegments[lineSegments.length - 1];
+      lineSegments[lineSegments.length - 1] = existing ? existing + ',' + segment : segment;
+    }
+
+    prevSourceIndex = m.sourceIndex;
+    prevSourceLine = m.sourceLine;
+    prevSourceCol = m.sourceCol;
+  });
+
+  return JSON.stringify({
+    version: 3,
+    file: generatedFile,
+    sources,
+    mappings: lineSegments.join(';'),
+  });
+}
+
+module.exports = { generateSourceMap };

package/lib/utils.js

@@ -26,6 +26,10 @@ function matchAll(regex, text) {
 }
 
 function extractMethods(filePath) {
+  return extractMethodsWithLocations(filePath).map((m) => m.name);
+}
+
+function extractMethodsWithLocations(filePath) {
   const content = fs.readFileSync(filePath, 'utf8');
 
   const patterns = [
@@ -34,10 +38,23 @@ function extractMethods(filePath) {
     /^async\s+function\s+([a-zA-Z_$][a-zA-Z0-9_$]*)\s*\(/gm,
   ];
 
-  const names = patterns.flatMap((r) => matchAll(r, content).map((m) => m[1]));
-  return [...new Set(names)].filter(
-    (n) => n !== 'constructor' && !n.startsWith('_') && !JS_RESERVED.has(n),
-  );
+  const seen = new Set();
+  const results = [];
+
+  patterns.forEach((r) => {
+    matchAll(r, content).forEach((m) => {
+      const name = m[1];
+      if (name === 'constructor' || name.startsWith('_') || JS_RESERVED.has(name)) return;
+      if (seen.has(name)) return;
+      seen.add(name);
+      const line = content.substring(0, m.index).split('\n').length - 1;
+      const lineText = content.split('\n')[line];
+      const col = lineText.indexOf(name);
+      results.push({ name, line, col: col >= 0 ? col : 0 });
+    });
+  });
+
+  return results;
 }
 
 function isCustomService(filePath) {
@@ -64,6 +81,7 @@ module.exports = {
   pascalCase,
   matchAll,
   extractMethods,
+  extractMethodsWithLocations,
   isCustomService,
   scanJsFilesRecursively,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "langaro-api",
-  "version": "1.0.5",
+  "version": "1.0.7",
   "description": "Auto-generate TypeScript types, JSDoc annotations, and boilerplate loaders for knex-extended-crud projects",
   "main": "lib/index.js",
   "bin": {
@@ -21,8 +21,8 @@
     "boilerplate"
   ],
   "peerDependencies": {
-    "knex-extended-crud": ">=2.0.31",
-    "cron": ">=3.0.0"
+    "cron": "^4.4.0",
+    "knex-extended-crud": ">=2.0.31"
   },
   "peerDependenciesMeta": {
     "cron": {