Users module

User management for node-backend-core 1.x, adapted from the existing node-backend-boilerplate Users module. CommonJS, Express 5, Sequelize 6 and MySQL.

Users has no functional dependencies or required environment variables. It does not authenticate requests or manage credentials, roles, tokens or external identities.

Installation

Copy the module root to your application's src/modules/users/. Include index.js, module.json and all runtime directories, particularly swagger/ and migrations/. Do not copy .git, .verification or node_modules. The application supplies the peer packages in package.json; reuse its installed Express, express-validator and Sequelize versions. Core classes and shared resources arrive through the lifecycle context, never through relative imports into the host.

npm pack creates a distributable archive. Extract its package/ contents into src/modules/users/. Installing only in node_modules does not enable discovery in Core V1. No installer CLI is included.

The Core discovers index.js, which imports module.json. Models are registered in registerModels; routes and the public service are composed in register. Swagger is discovered automatically. Apply the migration explicitly before using CRUD; see database migration. Core V1 catalogs migrations and seeders but does not execute them.

HTTP API

All endpoints are mounted under /api/v1/users:

| Method | Path | Action | | --- | --- | --- | | GET | / | List, filter and paginate | | GET | /:id | Get user; 404 when missing | | POST | / | Create | | PUT | /:id | Update supplied fields | | DELETE | /:id | Delete; returns 200 with null data | | PATCH | /:id/activate | Set active | | PATCH | /:id/deactivate | Set inactive |

Create accepts name (3–100 characters), email (valid, up to 150 characters), and optional active (default true). Update accepts the same fields and requires at least one. Unknown body fields are rejected with 422. Email is normalized by express-validator, preserving the original module's normalization convention. The database keeps the original 120-character name capacity for existing records.

List accepts page (default 1), limit (1–100, default 10), sort (id, name, email, created_at), order (ASC or DESC), and filters name, email (substring matches) and active. Unknown filters are rejected. The original list payload { rows, count } is preserved inside Core's ApiResponse. Responses contain only id, name, email, active, createdAt, updatedAt. Duplicate email is 409, validation failure 422, missing user 404.

Swagger: /api/docs; specification: /api/docs.json.

Security contract change: the original routes required JWT and ADMIN for mutations. This module has no authentication/authorization middleware. The host application is responsible for endpoint protection. Role assignment and password changes are excluded from this API; see migration notes.

Public API and events

See public API for per-application service access and event semantics. Other modules consume that API instead of importing model/repository files.

Tests

With this repository beside node-backend-core and Core dependencies installed:

npm test

For another layout, set CORE_PATH to the Core application root. The test launcher uses the host's dependencies when available; a standalone development checkout can install the declared development dependencies. No runtime package imports the test helper or requires CORE_PATH.

Real MySQL tests require TEST_DB_HOST, TEST_DB_PORT, TEST_DB_NAME, TEST_DB_USER, TEST_DB_PASSWORD. Use a dedicated database with no users table. Tests refuse to adopt an existing table and only remove tables they created. Without this configuration, five real-MySQL tests are explicitly skipped.

The module has its own Jest command because Core's Jest roots do not discover installed module tests. Run npm test in both repositories.

Reproducible Docker verification

The fixture expects this checkout beside node-backend-core. It builds the Core's existing Dockerfile and mounts a staged installation of Users. It uses loopback ports 13017/13317, isolated databases and a temporary MySQL filesystem. Test-only credentials are declared in the fixture; do not use them in deployments.

node scripts/stage.cjs
docker compose -p users-module-verification -f tests/runtime/docker-compose.yml up --build -d --wait
docker compose -p users-module-verification -f tests/runtime/docker-compose.yml exec -T api node src/modules/users/scripts/migrate.cjs

Check http://127.0.0.1:13017/health, /api/docs.json and /api/v1/users. Run the MySQL tests with host 127.0.0.1, port 13317, database users_module_test, user backend, password users_local_test_only.

Stop the fixture with the same compose command followed by down. This fixture does not use or remove existing Core database volumes. Its temporary data is lost when its MySQL container is removed.

See verification results for the completed checks.