@flusys/nestjs-core 9.1.1 → 9.2.0

package/README.md

@@ -24,14 +24,30 @@ Access typed environment variables via the `envConfig` singleton — no class in
 ```typescript
 import { envConfig } from '@flusys/nestjs-core';
 
-const port    = envConfig.getPort();           // number
-const db      = envConfig.getTypeOrmConfig();  // { host, port, username, password, database }
+const port    = envConfig.getPort();           // number, PORT or 3000
+const db      = envConfig.getTypeOrmConfig();  // { type, host, port, username, password, database }
 const jwt     = envConfig.getJwtConfig();      // { secret, expiration, refreshSecret, ... }
 const origins = envConfig.getOrigins();        // string[]
 const isProd  = envConfig.isProduction();      // boolean
- public tryGetValue(key: string, throwOnMissing = false): string // get env value
+
+const value   = envConfig.tryGetValue('APP_URL');                  // string, '' when unset
+const size    = envConfig.getNumber('MAX_FILE_SIZE', false) ?? 10; // number | undefined
+const enabled = envConfig.getBoolean('ENABLE_DOMAIN_EVENTS', false); // boolean
 ```
 
+Parsing rules:
+
+| Input | Behaviour |
+| ----- | --------- |
+| Unset, empty or whitespace-only value | Treated as missing: throws `Config error - missing env.KEY` when required, otherwise `''` |
+| `getNumber(key)` (required) | Throws when missing or not a finite number |
+| `getNumber(key, false)` | `undefined` when missing or not a finite number, so `??` defaults apply |
+| `getBoolean` / `useTenantMode` / `DISABLE_HTTP_LOGGING` | Only `true` (any case, surrounding spaces ignored) is `true` |
+| `MODE` | Anything other than `dev` (any case) counts as production |
+| `ALLOW_ORIGINS` | Required; comma-separated, trimmed, empty entries dropped |
+| `DB_TYPE` | One of `mysql`, `postgres`, `mariadb`, `sqlite`, `mssql` (any case, default `mysql`); anything else throws. Default port: postgres 5432, mssql 1433, otherwise 3306 |
+| `ALLOW_ORIGINS`, `PORT`, `MODE`, `DB_*` via `tryGetValue` | Throws `Access denied` - use the dedicated method |
+
 ---
 
 ## 2. Migrations
@@ -39,6 +55,8 @@ const isProd  = envConfig.isProduction();      // boolean
 ### Create `src/persistence/migration.config.ts`
 
 ```typescript
+import { dirname } from 'path';
+import { fileURLToPath } from 'url';
 import { createMigrationDataSource, IMigrationConfig } from '@flusys/nestjs-core';
 import { envConfig } from '@flusys/nestjs-core/config';
 import { getAuthEntitiesByConfig } from '@flusys/nestjs-auth';
@@ -53,7 +71,7 @@ const bootstrapConfig = {
 export const migrationConfig: IMigrationConfig = {
   defaultDatabaseConfig: envConfig.getTypeOrmConfig(),
   bootstrapAppConfig: bootstrapConfig,
-  migrationsPath: `${__dirname}/migrations`,
+  migrationsPath: `${dirname(fileURLToPath(import.meta.url))}/migrations`,
   migrationsTableName: 'migrations',
   entities: [
     ...getAuthEntitiesByConfig(bootstrapConfig),
@@ -78,6 +96,7 @@ export default createMigrationDataSource({
     "migration:run":      "npm run migration -- run",
     "migration:revert":   "npm run migration -- revert",
     "migration:status":   "npm run migration -- status",
+    "migration:reset":    "npm run migration -- reset",
     "migration:run:all":    "npm run migration -- run:all",
     "migration:revert:all": "npm run migration -- revert:all",
     "migration:status:all": "npm run migration -- status:all"
@@ -104,8 +123,21 @@ TENANT_ID=tenant-1 npm run migration:status
 npm run migration:run:all
 npm run migration:revert:all
 npm run migration:status:all
+
+# Dev only: drop + recreate the database, wipe migration files, generate and run "Init"
+npm run migration:reset
 ```
 
+CLI rules:
+
+- Migration names must start with a letter and contain only letters, digits, `_` or `-` (checked before anything runs, including before `reset` drops the database).
+- Flag values keep everything after the first `=` (`--config=a=b.ts`); an empty `--name=` counts as missing.
+- `TENANT_ID` must match a configured tenant; an unknown id fails instead of falling back to the default database.
+- `run`, `revert`, `status` and every `:all` command exit with code 1 when any database fails. `:all` supports only `run`, `revert` and `status`; each tenant runs independently, so one failing tenant does not stop the others, and every connection is closed even on failure.
+- `reset` refuses to run unless `MODE=dev` or `--force` is passed, and never resets the PostgreSQL `postgres` maintenance database.
+- Without `--config`, the CLI tries `MIGRATION_CONFIG`, then `src/persistence/migration.config.{ts,js}` and `persistence/migration.config.{ts,js}`. A config file that exists but fails to import reports its real error. The module must export `migrationConfig` (or default-export the config object).
+- `ignoreTable` in `IMigrationConfig` removes generated statements that mention runtime-managed tables (for example the entity builder's `eb_<code>` tables).
+
 ---
 
 ## 3. Swagger
@@ -133,7 +165,8 @@ async function bootstrap() {
       // Exclude controllers by @ApiTags name
       excludeTags: ['Internal', 'Health'],
 
-      // Exclude specific paths (supports * and ** wildcards)
+      // Exclude specific paths: * matches one path segment, ** matches any depth,
+      // every other character (., +, {id}, ...) is literal
       excludePaths: ['/api/auth/internal/*', '/api/health'],
 
       // Exclude properties from a DTO schema
@@ -141,7 +174,7 @@ async function bootstrap() {
         { schemaName: 'CreateUserDto', properties: ['passwordHash', 'salt'] },
       ],
 
-      // Exclude query parameters from specific endpoints
+      // Exclude query parameters from specific endpoints (method is case-insensitive)
       excludeQueryParameters: [
         { pathPattern: '/api/auth/*', method: 'post', parameters: ['debug'] },
       ],

package/config/env-config.service.d.ts

@@ -1,3 +1,4 @@
+import { type DatabaseType } from '../interfaces/database.interface.js';
 declare class EnvConfigService {
     private env;
     private restrictedKeys;
@@ -6,13 +7,14 @@ declare class EnvConfigService {
     });
     private getValue;
     tryGetValue(key: string, throwOnMissing?: boolean): string;
-    getNumber(key: string, throwOnMissing?: boolean): number;
+    getNumber(key: string, throwOnMissing?: true): number;
+    getNumber(key: string, throwOnMissing: boolean): number | undefined;
     getBoolean(key: string, throwOnMissing?: boolean): boolean;
     getPort(): number;
     isProduction(): boolean;
     getOrigins(): string[];
     getTypeOrmConfig(): {
-        type: "mysql" | "postgres" | "mariadb" | "sqlite" | "mssql";
+        type: DatabaseType;
         host: string;
         port: number;
         username: string;