langaro-api 1.2.3 → 1.2.5

package/lib/cli/documentation-templates/15-cli-and-scaffolding.md

@@ -0,0 +1,344 @@
+# CLI & Scaffolding
+
+## Overview
+
+The `langaro-api` CLI provides commands for project scaffolding, resource creation, type generation, and project migration.
+
+---
+
+## Installation
+
+`langaro-api` is installed as a project dependency. The CLI is available via `npx`:
+
+```bash
+npx langaro-api          # Interactive menu (or auto-generate types in CI)
+npx langaro-api init     # Scaffold new project
+npx langaro-api new      # Create new resource
+npx langaro-api generate # Generate TypeScript types
+npx langaro-api --watch  # Watch mode for type generation
+npx langaro-api migrate  # Migrate existing project to use loaders
+```
+
+---
+
+## Interactive Menu
+
+Running `npx langaro-api` without arguments in a TTY terminal shows an interactive menu:
+
+```
+> Generate types
+  New resource
+  Migrate project
+  Init new project
+```
+
+Navigate with arrow keys, select with Enter.
+
+In a non-TTY environment (CI/CD), it auto-runs type generation.
+
+---
+
+## `langaro-api init`
+
+Scaffolds a complete project from scratch.
+
+### Usage
+
+```bash
+mkdir my-project && cd my-project
+npx langaro-api init
+```
+
+### Prompts
+
+| Prompt | Default | Description |
+|--------|---------|-------------|
+| Project name | folder name | Used in `package.json` |
+| Port | `8282` | Server listen port |
+| Database name | project name (underscored) | MySQL database |
+| Redis port | `6379` | Redis connection port |
+
+### Files Created
+
+**Root config:**
+- `package.json` — All dependencies pre-configured
+- `.babelrc` — Babel with `@` path alias
+- `jsconfig.json` — IDE path resolution
+- `.eslintrc.js` — Airbnb-base ESLint config
+- `.eslintignore`
+- `jest.config.js` — Jest test configuration
+- `.gitignore` — Standard ignores
+- `.env` — Environment variables (with auto-generated JWT_SECRET and MASTER_PASS)
+- `.env.example` — Template without secrets
+
+**Application:**
+- `src/config/server.js` — Server entry point
+- `src/config/app.js` — App class (middleware, routes, errors)
+- `src/config/queues.js` — BullMQ queue system
+- `src/config/instrument.js` — Sentry setup
+- `src/config/tests/global-setup-tests.js`
+- `src/config/tests/setup-tests.js`
+
+**Database:**
+- `src/database/connection.js` — Knex MySQL connection
+- `src/database/redis-config.js` — Redis connection params
+- `src/database/redis-cache.js` — RedisCache class
+
+**Loaders (index.js files):**
+- `src/database/models/index.js`
+- `src/database/services/index.js`
+- `src/controllers/index.js`
+- `src/routes/index.js`
+- `src/jobs/index.js`
+- `src/tasks/index.js`
+
+**Auth:**
+- `src/middlewares/auth.middleware.js` — JWT authentication
+
+**Utils:**
+- `src/utils/index.js` — Re-exports common packages
+- `src/utils/sleep.js` — Sleep utility
+
+**Empty directories:**
+- `src/integrations/`
+- `src/static/`
+- `src/temp/`
+- `src/database/tests/`
+
+**Documentation:**
+- `documentation/` — Architecture documentation (this folder)
+
+### Behavior
+
+- **Skips existing files** — Running `init` on an existing project only creates files that don't exist yet. Safe to run on existing projects to add missing scaffolding.
+- Auto-generates `JWT_SECRET` (UUID) and `MASTER_PASS` (random string) in `.env`
+
+### Next Steps After Init
+
+```bash
+npm install
+# Fill in .env (DB_PASSWORD, etc.)
+# Create the database in MySQL
+npm run dev
+npx langaro-api new  # Create your first resource
+```
+
+---
+
+## `langaro-api new`
+
+Scaffolds a new resource (controller, service, model, route).
+
+### Usage
+
+```bash
+npx langaro-api new
+```
+
+### Steps
+
+1. **Choose naming source:**
+   - **Enter manually** — Type a snake_case name
+   - **Fetch from database** — Select from existing MySQL tables
+
+2. **Select what to generate:**
+   - [x] Controller
+   - [x] Service
+   - [x] Model
+   - [x] Route
+
+   Toggle with Space, confirm with Enter.
+
+3. **Files created** (for resource `products`):
+   - `src/controllers/products/products.controller.js`
+   - `src/database/services/products.services.js`
+   - `src/database/models/products.model.js`
+   - `src/routes/products.router.js`
+
+4. **Types auto-regenerated** after creation.
+
+### Templates Created
+
+**Controller:**
+```javascript
+/** @param {typeof ProductsControllerBase} ServicesClass @generated-types */
+module.exports = (ServicesClass) => class extends ServicesClass {
+  async getAll(req, res) {
+    const data = await this.service.get();
+    res.status(200).json(data);
+  }
+};
+```
+
+**Service:**
+```javascript
+/** @param {typeof ProductsServicesBase} model @param {ModelsConstructorMap} models @generated-types */
+module.exports = (model, models) => class extends model {
+  async defaultMethod(something) {
+    const ProductsModel = new model();
+    return something;
+  }
+};
+```
+
+**Model:**
+```javascript
+/** @type {ModelConfig} @generated-types */
+module.exports = {
+  fields: {},
+  sortBy: 'created_at',
+};
+```
+
+**Route:**
+```javascript
+const createAuthMiddleware = require('@/middlewares/auth.middleware');
+
+/** @param {ControllersMap} controllers @param {ServicesMap} services @generated-types */
+module.exports = (controllers, services) => {
+  const auth = createAuthMiddleware(services);
+  const router = require('express').Router();
+  const controller = controllers.ProductsController;
+  const subject = 'products';
+
+  router.get('/', auth([{ subject }]), controller.getAll.bind(controller));
+
+  return router;
+};
+```
+
+### Resource Naming
+
+- Must be `snake_case`: `products`, `user_invoices`, `crm_leads`
+- Must start with a lowercase letter
+- Validated with: `/^[a-z][a-z0-9_]*$/`
+
+---
+
+## `langaro-api generate` / `langaro-api types`
+
+Generates TypeScript definition files and injects JSDoc annotations for IDE IntelliSense.
+
+### Output
+
+```
+@types/generated/
+├── crud.d.ts          # CRUD class + option interfaces
+├── services.d.ts      # Service interfaces + ServicesMap
+├── controllers.d.ts   # Controller base classes + ControllersMap
+├── index.d.ts         # Reference includes
+├── crud.d.ts.map      # Source maps for Go-to-Definition
+├── services.d.ts.map
+└── controllers.d.ts.map
+```
+
+### JSDoc Injection
+
+The generator also injects/updates `@generated-types` JSDoc comments in source files:
+
+```javascript
+// Before:
+module.exports = (ServicesClass) => class extends ServicesClass { ... }
+
+// After:
+/** @param {typeof UsersControllerBase} ServicesClass @generated-types */
+module.exports = (ServicesClass) => class extends ServicesClass { ... }
+```
+
+This enables IDE autocomplete for `this.service`, `this.services`, `controllers.*`, etc.
+
+### When to Run
+
+- After creating new component files
+- After renaming or deleting components
+- After `npm install` (if knex-extended-crud updated)
+- Automatically via `npm run dev` (watch mode)
+
+---
+
+## `langaro-api --watch`
+
+Continuous type generation that watches source directories:
+
+```bash
+npx langaro-api --watch
+```
+
+Watches: `src/database/models/`, `src/database/services/`, `src/controllers/`, `src/routes/`, `src/jobs/`, `src/tasks/`, `src/middlewares/`
+
+Debounce: 300ms
+
+Usually run via `npm run dev` which uses `npm-run-all -p dev:server dev:types`.
+
+---
+
+## `langaro-api migrate`
+
+Converts an existing project to use langaro-api loaders by replacing hand-written `index.js` files.
+
+### What It Does
+
+Replaces these files with loader calls:
+- `src/database/models/index.js` → `loadModels`
+- `src/database/services/index.js` → `loadServices`
+- `src/controllers/index.js` → `loadControllers`
+- `src/routes/index.js` → `attachRouters`
+- `src/jobs/index.js` → `loadJobs`
+- `src/tasks/index.js` → `loadTasks`
+
+Creates `.bak` backups of original files.
+
+---
+
+## Configuration File
+
+Optional `langaro-api.config.js` in project root to override default paths:
+
+```javascript
+module.exports = {
+  root: process.cwd(),
+  output: '@types/generated',
+  services: 'src/database/services',
+  models: 'src/database/models',
+  controllers: 'src/controllers',
+  routes: 'src/routes',
+  jobs: 'src/jobs',
+  tasks: 'src/tasks',
+  middlewares: 'src/middlewares',
+};
+```
+
+Only needed if your project uses non-standard directory names.
+
+---
+
+## Development Workflow
+
+```bash
+# Start development (server + type generation)
+npm run dev
+
+# Create a new resource
+npx langaro-api new
+
+# Manually regenerate types
+npm run generate-types
+
+# Run tests
+npm test
+```
+
+### npm Scripts (from init)
+
+```json
+{
+  "start": "babel-node ./src/config/server.js",
+  "dev": "npm-run-all -p dev:*",
+  "dev:server": "nodemon --exec babel-node ./src/config/server.js",
+  "dev:types": "langaro-api --watch",
+  "generate-types": "langaro-api",
+  "test": "jest",
+  "test:watch": "jest --watchAll",
+  "test:coverage": "jest --coverage"
+}
+```

package/lib/cli/documentation-templates/SUMMARY.md

@@ -0,0 +1,116 @@
+# Langaro API — Architecture Guide
+
+This project uses the **Langaro API** framework: a convention-over-configuration Node.js framework built on Express 5, Knex (MySQL), BullMQ, Redis, and Socket.io. Database operations are powered by **knex-extended-crud**, which provides a full-featured CRUD class with validation, caching, relationships, and batch operations.
+
+---
+
+## Quick Decision Tree
+
+| I need to... | Read |
+|-------------|------|
+| Understand the full architecture | `01-architecture-overview.md` |
+| Look up a CRUD method (get, create, update, etc.) | `02-crud-layer.md` |
+| Define field visibility, validation, or relationships for a table | `03-models.md` |
+| Add business logic for a table | `04-services.md` |
+| Add an API endpoint | `05-controllers.md` + `06-routes.md` |
+| Add a background job | `07-jobs.md` + `12-queues.md` |
+| Add a scheduled task | `08-tasks.md` |
+| Add or modify authentication/authorization | `09-middlewares.md` |
+| Connect to an external API | `10-integrations.md` |
+| Modify server startup, database, or Redis config | `11-config-and-bootstrap.md` |
+| Understand the queue system | `12-queues.md` |
+| Add a utility function | `13-utils.md` |
+| Write tests | `14-testing.md` |
+| Scaffold a new resource or project | `15-cli-and-scaffolding.md` |
+
+---
+
+## Adding a New Database-Backed Resource (end-to-end)
+
+1. Create the MySQL table (migration)
+2. Create the model: `src/database/models/{table}.model.js` → `03-models.md`
+3. Create the service: `src/database/services/{table}.services.js` → `04-services.md`
+4. Create the controller: `src/controllers/{table}/{table}.controller.js` → `05-controllers.md`
+5. Create the route: `src/routes/{table}.router.js` → `06-routes.md`
+6. Regenerate types: `npx langaro-api generate` → `15-cli-and-scaffolding.md`
+
+Or use the CLI shortcut: `npx langaro-api new`
+
+---
+
+## Document Index
+
+| # | Document | Description |
+|---|----------|-------------|
+| 01 | `01-architecture-overview.md` | Three-layer stack, boot sequence, inheritance chain, directory structure |
+| 02 | `02-crud-layer.md` | knex-extended-crud API: get, create, update, delete, search, validation, caching |
+| 03 | `03-models.md` | Model configuration: fields, hide, append, schema, filterOptions |
+| 04 | `04-services.md` | Business logic layer: factory pattern, transactions, Socket.io |
+| 05 | `05-controllers.md` | Request handlers: ServicesClass, validation, Queue, response patterns |
+| 06 | `06-routes.md` | Express routers: URL mapping, auth middleware, binding |
+| 07 | `07-jobs.md` | BullMQ async jobs: handle, retry, grouped queues, error handling |
+| 08 | `08-tasks.md` | Cron scheduled tasks: cronTime, environments, patterns |
+| 09 | `09-middlewares.md` | Authentication, authorization, permission system |
+| 10 | `10-integrations.md` | External service wrappers: Stripe, AWS, email, etc. |
+| 11 | `11-config-and-bootstrap.md` | Server, app, database, Redis, environment variables |
+| 12 | `12-queues.md` | Queue infrastructure: lifecycle, monitoring, shutdown |
+| 13 | `13-utils.md` | Utility functions: validation, formatting, common helpers |
+| 14 | `14-testing.md` | Jest config, test database, queue mocking, patterns |
+| 15 | `15-cli-and-scaffolding.md` | CLI commands: init, new, generate, watch, migrate |
+
+---
+
+## Architecture Stack
+
+```
+┌──────────────────────────────────┐
+│        PROJECT CODE              │
+│   (this repository)              │
+├──────────────────────────────────┤
+│        LANGARO-API               │
+│   (loaders, CLI, types)          │
+├──────────────────────────────────┤
+│     KNEX-EXTENDED-CRUD           │
+│   (CRUD, validation, cache)      │
+├──────────────────────────────────┤
+│   Express + Knex/MySQL + Redis   │
+│   BullMQ + Socket.io + Sentry   │
+└──────────────────────────────────┘
+```
+
+---
+
+## Naming Conventions
+
+| Component | File Pattern | Instance Key |
+|-----------|-------------|-------------|
+| Model | `{table}.model.js` | — |
+| Service | `{table}.services.js` | `PascalCaseServices` |
+| Controller | `{table}/{table}.controller.js` | `PascalCaseController` |
+| Route | `{table}.router.js` | URL: `/kebab-case` |
+| Job | `{name}.js` | Queue name: `kebab-case` |
+| Task | `{name}.js` | — |
+| Middleware | `{name}.middleware.js` | — |
+| Integration | `{name}.js` | — |
+
+**Tables** use `snake_case` matching the MySQL table name.
+
+---
+
+## Key Terminology
+
+| Term | Definition |
+|------|-----------|
+| **CRUD** | The base class from knex-extended-crud. All models and services inherit from it. |
+| **Model** | A configuration object (not a class) that shapes CRUD behavior for a table. |
+| **Service** | A class extending CRUD with custom business logic methods. |
+| **ServicesClass** | The base class injected into controllers with `this.service`, `this.services`, `this.Queue`, `this.io`. |
+| **Controller** | A class extending ServicesClass that handles HTTP requests. |
+| **Loader** | A framework function that auto-discovers and instantiates components from directories. |
+| **Factory Function** | The export pattern used by services, controllers, routes, jobs, and tasks — a function that receives dependencies and returns a class or object. |
+| **Queue** | The BullMQ job queue interface: `{ add(name, data, options) }`. |
+| **Task** | A cron-scheduled function that runs automatically at defined intervals. |
+| **append** | The relationship system that loads related data from other tables. |
+| **andWhere** | A declarative array-based query condition builder used in CRUD methods. |
+| **Safe Error** | An error created via `ApiError()` that returns a specific HTTP status and message to the client. |
+| **Unsafe Error** | Any uncaught error — returns generic 500 and is captured by Sentry. |

package/lib/cli/init.js

@@ -1106,15 +1106,43 @@ async function run() {
     createEmptyDir(root, dir);
   });
 
+  // documentation/ architecture documentation
+  const cloudTemplatesDir = path.join(__dirname, 'documentation-templates');
+  if (fs.existsSync(cloudTemplatesDir)) {
+    fs.readdirSync(cloudTemplatesDir)
+      .filter((f) => f.endsWith('.md'))
+      .sort()
+      .forEach((file) => {
+        const content = fs.readFileSync(path.join(cloudTemplatesDir, file), 'utf8');
+        writeFile(root, `documentation/${file}`, content);
+      });
+  }
+
   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 \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`);
+  console.log(`  5. \x1b[36mnpx langaro-api new\x1b[0m to create your first resource`);
+  console.log(`  6. Review \x1b[36mdocumentation/\x1b[0m for architecture documentation\n`);
 
   process.exit(0);
 }
 
-module.exports = run;
+function updateDocumentation(root) {
+  const templatesDir = path.join(__dirname, 'documentation-templates');
+  if (fs.existsSync(templatesDir)) {
+    fs.readdirSync(templatesDir)
+      .filter((f) => f.endsWith('.md'))
+      .sort()
+      .forEach((file) => {
+        const full = path.join(root, `documentation/${file}`);
+        fs.mkdirSync(path.dirname(full), { recursive: true });
+        fs.writeFileSync(full, fs.readFileSync(path.join(templatesDir, file), 'utf8'));
+        console.log(`  \x1b[32mcreated\x1b[0m documentation/${file}`);
+      });
+  }
+}
+
+module.exports = { run, updateDocumentation };

package/lib/generators/crud.js

@@ -95,6 +95,11 @@ module.exports = function generateCrudDts(projectRoot, outputDir) {
   lines.push('  count(options?: CRUDGetOptions, transaction?: any): Promise<number>;');
   lines.push('');
 
+  addMethodMapping(lines, 'atomicIncrementWhere');
+  lines.push('  atomicIncrementWhere(');
+  lines.push('    prop: string, value: any, increments: Record<string, number>,');
+  lines.push('    options?: CRUDUpdateOptions, transaction?: any');
+  lines.push('  ): Promise<{ success: boolean; data: any }>;');
   addMethodMapping(lines, 'updateWhere');
   lines.push('  updateWhere(');
   lines.push('    prop: string, value: any, data?: Record<string, any>,');
@@ -171,6 +176,8 @@ module.exports = function generateCrudDts(projectRoot, outputDir) {
     '  sortBy?: string;',
     "  sort?: 'asc' | 'desc';",
     '  where?: (query: any) => any;',
+    '  /** Lock the selected rows for update within a transaction (default: false) */',
+    '  lockRow?: boolean;',
     '  /** Attempt to read from Redis cache (default: false) */',
     '  cache?: boolean;',
     '  /** Write result to Redis cache with this TTL in hours */',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "langaro-api",
-  "version": "1.2.3",
+  "version": "1.2.5",
   "description": "Auto-generate TypeScript types, JSDoc annotations, and boilerplate loaders for knex-extended-crud projects",
   "main": "lib/index.js",
   "bin": {
@@ -22,7 +22,7 @@
   ],
   "peerDependencies": {
     "cron": ">=3.0.0",
-    "knex-extended-crud": ">=2.1.2"
+    "knex-extended-crud": ">=2.1.3"
   },
   "peerDependenciesMeta": {
     "cron": {