fiberx-backend-toolkit 0.1.20 → 1.0.1

package/README.md

@@ -1,23 +1,13 @@
 # FiberX Backend Toolkit
 
-A comprehensive TypeScript backend toolkit providing shared domain logic, infrastructure helpers, and utilities for FiberX server-side applications and services.
+Shared TypeScript backend utilities for FiberX services. The package includes Sequelize connection helpers, schema-driven migration generation, migration and seeder runners, Express middleware, storage helpers, mailer processors, RBAC loading, validators, and common utilities.
 
-## Overview
-
-The FiberX Backend Toolkit is a centralized library designed to streamline backend development across FiberX services. It provides database abstraction layers, migration management, utilities for common operations, and TypeScript type definitions for consistency across the ecosystem.
-
-## Features
+## Requirements
 
-- **Database Management**: Multi-connector support with Sequelize integration for ORM operations
-- **Schema Migration System**: Automated schema management, migration generation, and execution
-- **Seeding Support**: Database seeder generation and execution tools
-- **Utility Functions**: 
-  - Input validation and transformation
-  - Environment variable management
-  - SQL formatting and query building
-  - Structured logging with file persistence
-- **TypeScript Support**: Fully typed exports for schema, migration, and utility types
-- **Flexible Exports**: Modular exports for `utils`, `types`, and `database` modules
+- Node.js 20.x
+- TypeScript projects using CommonJS or transpiled output
+- Sequelize v6
+- A project-level environment file in `environment_variables/`
 
 ## Installation
 
@@ -25,191 +15,269 @@ The FiberX Backend Toolkit is a centralized library designed to streamline backe
 npm install fiberx-backend-toolkit
 ```
 
-## Requirements
+## Quality Commands
 
-- Node.js 20.x or higher
-- npm or yarn package manager
+```bash
+npm run typecheck
+npm run lint
+npm run format:check
+npm run spell:check
+npm run build
+npm run check
+```
 
-## Quick Start
+Use `npm run format` to apply Prettier formatting locally. The CI workflow runs type checking, linting, formatting checks, spell checking, and the build on every push and pull request.
 
-### Import Types
+## Import Paths
 
-```typescript
-import type { SchemaInterface, MigrationInterface } from "fiberx-backend-toolkit/types";
+```ts
+import { LoggerUtil, EnvManagerUtil } from "fiberx-backend-toolkit/utils";
+import { SequelizeConnector, MigrationRunnerScript } from "fiberx-backend-toolkit/database";
+import { AuthenticationMiddleWare } from "fiberx-backend-toolkit/middle-ware";
+import type { SchemaDefinitionInterface } from "fiberx-backend-toolkit/types";
 ```
 
-### Import Utilities
+The root package also re-exports the public modules:
 
-```typescript
-import { LoggerUtil, InputValidatorUtil, EnvManagerUtil } from "fiberx-backend-toolkit/utils";
+```ts
+import { SequelizeConnector, LoggerUtil } from "fiberx-backend-toolkit";
+```
 
-// Initialize logger
-const logger = new LoggerUtil("my-module");
-logger.info("Application started");
+## Environment Configuration
 
-// Use environment manager
-const apiKey = EnvManagerUtil.get("API_KEY");
+By default, the toolkit reads YAML files from:
+
+```text
+environment_variables/
 ```
 
-### Database Operations
+The file is selected from `process.env.MODE`:
 
-```typescript
-import { SequelizeConnector, MigrationRunnerScript } from "fiberx-backend-toolkit/database";
-
-// Initialize database connector
-const connector = new SequelizeConnector(config);
+```text
+development -> development_env.yaml
+staging     -> staging_env.yaml
+production  -> production_env.yaml
+```
 
-// Run migrations
-const migrationRunner = new MigrationRunnerScript(connector);
-await migrationRunner.run();
+Example:
+
+```yaml
+MODE: development
+DB_DIALECT: postgres
+DB_HOST: localhost
+DB_PORT: 5432
+DB_NAME: fiberx_app
+DB_USER: postgres
+DB_PASSWORD: postgres
+DB_LOGGING: false
 ```
 
-## Core Modules
+For compatibility, the previous misspelled `environment_variables/` directory is still read if the corrected directory is not present.
+
+## Database Connection
+
+Use `SequelizeConnector.getInstance()` rather than constructing the connector directly.
+
+```ts
+import { SequelizeConnector } from "fiberx-backend-toolkit/database";
 
-### Utilities (`/src/utils`)
+const connector = SequelizeConnector.getInstance();
 
-- **LoggerUtil**: Structured logging with file-based persistence
-- **InputValidatorUtil**: Input validation and sanitization
-- **InputTransformerUtil**: Data transformation utilities
-- **EnvManagerUtil**: Environment variable management and parsing
-- **SqlFormatterUtil**: SQL query formatting and beautification
+const sequelize = await connector.connect({
+    name: "default",
+    dialect: "postgres",
+    database: "fiberx_app",
+    username: "postgres",
+    password: "postgres",
+    host: "localhost",
+    port: 5432,
+    logging: false,
+});
+```
 
-### Database (`/src/database`)
+`connect()` authenticates and attempts database creation for supported SQL dialects. `connectSync()` only creates a Sequelize instance and is useful when model files need to be initialized before application bootstrap.
 
-#### Connectors
-- **BaseConnector**: Abstract base class for database connections
-- **SequelizeConnector**: Sequelize ORM connector implementation
+## Directory Convention
 
-#### Schema Utilities
-- **SchemaDiffUtil**: Compare database schemas and detect changes
-- **SchemaNormalizerUtil**: Normalize schema definitions for consistency
+The generator and runner scripts expect these project-root paths:
 
-#### Scripts
-- **CreateSchemaScript**: Generate initial database schema
-- **MakeMigrationsScript**: Auto-generate migration files from schema changes
-- **MigrationRunnerScript**: Execute pending database migrations
-- **CreateSeederScript**: Generate seeder files for initial data
-- **SeederRunnerScript**: Execute database seeders
+```text
+src/database/
+  schemas/
+  schema_snapshots/
+  models/
+  migrations/
+  seeders/
+```
 
-### Types (`/src/types`)
+Missing directories are created where the scripts need them.
+
+## Schema Definitions
+
+Schemas are plain TypeScript files with a default export:
+
+```ts
+import { DataTypes } from "sequelize";
+import type { SchemaDefinitionInterface } from "fiberx-backend-toolkit/types";
+
+const UserSchema: SchemaDefinitionInterface = {
+    connection_name: "default",
+    database_name: "public",
+    migration_priority: 1,
+    table_name: "users",
+    model_name: "User",
+    timestamps: true,
+    columns: {
+        id: {
+            type: DataTypes.BIGINT,
+            primaryKey: true,
+            autoIncrement: true,
+            allowNull: false,
+        },
+        email: {
+            type: DataTypes.STRING(255),
+            allowNull: false,
+            unique: true,
+        },
+    },
+    indexes: [{ name: "users_email_unique", fields: ["email"], unique: true }],
+};
+
+export default UserSchema;
+```
 
-- **SchemaInterface**: Database schema type definitions
-- **MigrationInterface**: Migration type definitions
-- **UtilInterface**: Utility function types
+You can scaffold a schema:
 
-## Module Exports
+```ts
+import { CreateSchemaScript } from "fiberx-backend-toolkit/database";
 
-The toolkit provides structured exports for easy integration:
+new CreateSchemaScript("User").run();
+```
 
-```typescript
-// Main exports (all modules)
-import * as toolkit from "fiberx-backend-toolkit";
+## Migration Workflow
 
-// Utils only
-import { LoggerUtil, InputValidatorUtil } from "fiberx-backend-toolkit/utils";
+Generate migrations from schema changes:
 
-// Database only
-import { SequelizeConnector, MigrationRunnerScript } from "fiberx-backend-toolkit/database";
+```ts
+import { MakeMigrationsScript } from "fiberx-backend-toolkit/database";
 
-// Types only
-import type { SchemaInterface } from "fiberx-backend-toolkit/types";
+new MakeMigrationsScript().run();
 ```
 
-## Configuration
+Run migrations:
 
-The toolkit uses standardized directory conventions:
+```ts
+import { MigrationRunnerScript } from "fiberx-backend-toolkit/database";
 
+await new MigrationRunnerScript().run("up");
 ```
-project_root/
-├── logs/                              # Log files directory
-├── environment_variables/             # Environment variable files
-├── src/database/
-│   ├── schemas/                      # Schema definitions
-│   ├── schema_snapshots/             # Schema snapshots for comparison
-│   ├── models/                       # Sequelize models
-│   ├── migrations/                   # Database migrations
-│   └── seeders/                      # Database seeders
+
+Rollback migrations:
+
+```ts
+await new MigrationRunnerScript().run("down");
 ```
 
-## Dependencies
+Run a specific migration file:
 
-### Core Dependencies
-- **sequelize**: ^6.37.7 - SQL ORM
-- **sequelize-typescript**: ^2.1.6 - TypeScript decorators for Sequelize
-- **axios**: ^1.11.0 - HTTP client
-- **bcrypt**: ^6.0.0 - Password hashing
-- **jsonwebtoken**: ^9.0.2 - JWT handling
-- **dayjs**: ^1.11.18 - Date/time utilities
-- **js-yaml**: ^4.1.0 - YAML parsing
-- **uuid**: ^12.0.0 - UUID generation
+```ts
+await new MigrationRunnerScript().run("up", undefined, "1_20260515120000_create_table_users.ts");
+```
 
-## Build
+Migration runner behavior:
+
+- Tracks applied migrations in `sequelize_database_tables_meta`.
+- Supports both `.ts` and `.js` migration files and ignores `.d.ts`.
+- Uses dialect-safe quoting for metadata reads.
+- Sorts by numeric migration priority, then filename.
+- Runs toolkit-generated migrations and metadata updates in a Sequelize transaction.
+- Skips already-applied migrations on `up` and skips unapplied migrations on `down`.
+
+When running TypeScript migration files directly, execute your script with `ts-node` and `tsconfig-paths/register` so path aliases resolve.
 
 ```bash
-npm run build
+node -r ts-node/register -r tsconfig-paths/register ./scripts/migrate.ts
 ```
 
-The build process uses `tsup` for optimized TypeScript bundling.
-
-## API Documentation
+## Model Generation
 
-### LoggerUtil
+Generate Sequelize model files from schemas:
 
-```typescript
-const logger = new LoggerUtil("module-name");
+```ts
+import { SequelizeModelGeneratorScript } from "fiberx-backend-toolkit/database";
 
-logger.info("Information message");
-logger.warn("Warning message");
-logger.error("Error message");
-logger.debug("Debug message");
+new SequelizeModelGeneratorScript().generateModelsFromSchemas();
 ```
 
-Logs are stored locally in the configured `LOG_DIR`.
+The old misspelled `SeqeulizeModelGeneratorScript` export is still available for compatibility.
 
-### InputValidatorUtil
+## Seeders
 
-Validates and sanitizes user inputs with built-in rules and custom validators.
+Create and run seeders:
 
-### EnvManagerUtil
+```ts
+import { CreateSeederScript, SeederRunnerScript } from "fiberx-backend-toolkit/database";
 
-```typescript
-const dbHost = EnvManagerUtil.get("DB_HOST", "localhost");
-const dbPort = EnvManagerUtil.getAsNumber("DB_PORT", 5432);
+new CreateSeederScript("User", "initial_users").run();
+
+await new SeederRunnerScript().run("up");
+await new SeederRunnerScript().run("down", "user");
 ```
 
-### SequelizeConnector
+Seeder state is tracked in `sequelize_database_table_seeder_meta`.
 
-Provides abstraction over Sequelize for database operations with connection pooling and query management.
+## Express Middleware
 
-## Project Structure
+```ts
+import { AuthenticationMiddleWare } from "fiberx-backend-toolkit/middle-ware";
 
-```
-fiberx-backend-toolkit/
-├── src/
-│   ├── code_templates/         # Code generation templates
-│   ├── config/                 # Configuration constants
-│   ├── database/               # Database module
-│   ├── types/                  # TypeScript type definitions
-│   ├── utils/                  # Utility functions
-│   └── index.ts                # Main entry point
-├── package.json
-├── tsconfig.json
-├── tsup.config.ts              # Build configuration
-└── README.md
+const auth = new AuthenticationMiddleWare({
+    extractRequestInfoMethod: async (req) => ({
+        access_token: req.headers.authorization ?? null,
+        refresh_token: null,
+        origin_url: req.headers.origin ?? "",
+        request_id: String(req.headers["x-request-id"] ?? ""),
+    }),
+    validateActorHasPermissionMethod: async (requestInfo) => {
+        return requestInfo.permission_name === "user.read";
+    },
+});
+
+app.get("/users", auth.setPermissionName("user.read"), handler);
 ```
 
-## License
+`AuthenticationMiddleWare` is the corrected export. The previous `AuthenicationMiddleWare` export remains available for existing services.
+
+## Utility Modules
+
+```ts
+import {
+    LoggerUtil,
+    EnvManagerUtil,
+    InputValidatorUtil,
+    InputTransformerUtil,
+    SafeExecuteUtil,
+    UUIDGeneratorUtil,
+    EncryptorDecryptorUtil,
+    TOTPServiceUtil,
+} from "fiberx-backend-toolkit/utils";
+```
 
-ISC
+## Build
 
-## Author
+```bash
+npm run build
+```
 
-David Matt-Ojo
+The build emits CommonJS JavaScript and declarations to `dist/`.
 
-## Repository
+## Notes
 
-[GitHub - fiberx-backend-toolkit](https://github.com/fiberx-innovations/fiberx-backend-toolkit)
+- Generated migrations accept an optional third argument for transaction options.
+- Existing older migrations still run, but only generated or manually transaction-aware migrations can fully participate in the runner transaction.
+- Avoid `sequelize.sync({ alter: true })` in production services that use these migration scripts. Treat schema files as the source for migration generation, and treat migration files as the auditable database history.
+- updated the code
 
-## Support
+## License
 
-For issues, bugs, or feature requests, please visit the [issues page](https://github.com/fiberx-innovations/fiberx-backend-toolkit/issues).
+ISC

package/dist/code_templates/sequelize_code_template.d.ts

@@ -5,4 +5,4 @@ declare const SEQUELIZE_UPDATE_EXISTING_SCHEMA_MIGRATION_FILE_CODE_TEMPLATE: (ta
 declare const SEQUELIZE_SEEDER_TEMPLATE: (class_name: string, table_name: string) => string;
 declare const SEQUELIZE_MODEL_CODE_TEMPLATE: (schema_model_name: string, schema_file_name: string, schema_columns: Record<string, SchemaColumnInterface>) => string;
 declare const SEQUELIZE_MODELS_INDEX_CODE_TEMPLATE: (model_names: string[], imports: string) => string;
-export { SEQUELIZE_SCHEMA_CODE_TEMPLATE, SEQUELIZE_SEEDER_TEMPLATE, SEQUELIZE_CREATE_NEW_SCHEMA_MIGRATION_FILE_CODE_TEMPLATE, SEQUELIZE_UPDATE_EXISTING_SCHEMA_MIGRATION_FILE_CODE_TEMPLATE, SEQUELIZE_MODEL_CODE_TEMPLATE, SEQUELIZE_MODELS_INDEX_CODE_TEMPLATE };
+export { SEQUELIZE_SCHEMA_CODE_TEMPLATE, SEQUELIZE_SEEDER_TEMPLATE, SEQUELIZE_CREATE_NEW_SCHEMA_MIGRATION_FILE_CODE_TEMPLATE, SEQUELIZE_UPDATE_EXISTING_SCHEMA_MIGRATION_FILE_CODE_TEMPLATE, SEQUELIZE_MODEL_CODE_TEMPLATE, SEQUELIZE_MODELS_INDEX_CODE_TEMPLATE, };