@zola_do/typeorm 0.2.5 → 0.2.7

package/README.md

@@ -1,7 +1,20 @@
 # @zola_do/typeorm
 
+[![npm version](https://img.shields.io/npm/v/@zola_do/typeorm.svg)](https://www.npmjs.com/package/@zola_do/typeorm)
+[![npm downloads](https://img.shields.io/npm/dm/@zola_do/typeorm.svg)](https://www.npmjs.com/package/@zola_do/typeorm)
+[![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](https://opensource.org/licenses/ISC)
+
 TypeORM configuration helpers and service for NestJS applications.
 
+## Overview
+
+`@zola_do/typeorm` provides:
+
+- **Environment-based Configuration** — Database settings from environment variables
+- **Auto-entity Discovery** — Automatically loads entities and migrations
+- **DataSource Options** — TypeORM 0.3+ compatible configuration
+- **Config Service** — Injectable service for database access
+
 ## Installation
 
 ```bash
@@ -12,65 +25,405 @@ npm install @zola_do/typeorm
 npm install @zola_do/nestjs-shared
 ```
 
-## Usage
+### Dependencies
+
+```bash
+npm install @nestjs/typeorm typeorm typeorm-extension dotenv
+```
+
+## Read replicas (TypeORM `replication`)
+
+`@zola_do/typeorm` exposes `dataSourceOptions` as a starting point. For read scaling, use TypeORM's [`replication`](https://typeorm.io/data-source-options#postgres--cockroachdb--sap-hana--sql.js) option in the object you pass to `TypeOrmModule.forRoot`: supply `master` (writer) and `slaves` (readers). Environment variables are then modeled in your app (for example `DATABASE_REPLICA_HOSTS` parsed to an array) rather than hard-coded in the library.
+
+## Quick Start
+
+### 1. Configure Environment
+
+```bash
+# .env
+DATABASE_HOST=localhost
+DATABASE_PORT=5432
+DATABASE_NAME=myapp
+DATABASE_USER=postgres
+DATABASE_PASSWORD=secret
+APP_NAME=myapp
+```
+
+### 2. Register in AppModule
+
+```typescript
+import { Module } from "@nestjs/common";
+import { TypeOrmModule } from "@nestjs/typeorm";
+import { dataSourceOptions } from "@zola_do/typeorm";
+
+@Module({
+  imports: [TypeOrmModule.forRoot(dataSourceOptions)],
+})
+export class AppModule {}
+```
+
+### 3. Use Entities
+
+```typescript
+import { CommonEntity } from "@zola_do/nestjs-shared";
+import { Entity, Column } from "typeorm";
+
+@Entity("products")
+export class Product extends CommonEntity {
+  @Column()
+  name: string;
+
+  @Column("decimal", { precision: 10, scale: 2 })
+  price: number;
+}
+```
+
+## Entity Configuration
 
-### Configuring the Database
+### CommonEntity
 
-Use `TypeOrmConfigHelper` or `dataSourceOptions` to configure TypeORM in your `AppModule`:
+All entities should extend `CommonEntity` for consistent audit fields:
+
+```typescript
+import { CommonEntity } from "@zola_do/nestjs-shared";
+import { Entity, Column, PrimaryGeneratedColumn } from "typeorm";
+
+@Entity("products")
+export class Product extends CommonEntity {
+  @PrimaryGeneratedColumn("uuid")
+  id: string;
+
+  @Column()
+  name: string;
+}
+```
+
+### CommonEntity Fields
+
+| Field       | Type     | Description                      |
+| ----------- | -------- | -------------------------------- |
+| `id`        | `UUID`   | Primary key (auto-generated)     |
+| `createdAt` | `Date`   | Auto-set on creation             |
+| `updatedAt` | `Date`   | Auto-updated on changes          |
+| `createdBy` | `string` | Nullable - user who created      |
+| `updatedBy` | `string` | Nullable - user who last updated |
+| `deletedAt` | `Date`   | Nullable - soft delete timestamp |
+
+### Entity Patterns
+
+#### Basic Entity
+
+```typescript
+@Entity("categories")
+export class Category extends CommonEntity {
+  @PrimaryGeneratedColumn("uuid")
+  id: string;
+
+  @Column()
+  name: string;
+
+  @Column({ nullable: true })
+  description: string;
+
+  @OneToMany(() => Product, (product) => product.category)
+  products: Product[];
+}
+```
+
+#### Entity with Relations
+
+```typescript
+@Entity("orders")
+export class Order extends CommonEntity {
+  @PrimaryGeneratedColumn("uuid")
+  id: string;
+
+  @Column()
+  customerId: string;
+
+  @Column("decimal", { precision: 10, scale: 2 })
+  total: number;
+
+  @Column({ default: "pending" })
+  status: string;
+
+  @ManyToOne(() => Customer, (customer) => customer.orders)
+  @JoinColumn({ name: "customerId" })
+  customer: Customer;
+
+  @OneToMany(() => OrderItem, (item) => item.order)
+  items: OrderItem[];
+}
+```
+
+#### Entity with Indexes
+
+```typescript
+@Entity("products", {
+  indexes: [
+    { name: "idx_product_name", columns: ["name"] },
+    { name: "idx_product_status_price", columns: ["status", "price"] },
+  ],
+})
+export class Product extends CommonEntity {
+  @Column()
+  name: string;
+
+  @Column({ default: "active" })
+  status: string;
+
+  @Column("decimal", { precision: 10, scale: 2 })
+  price: number;
+}
+```
+
+## TypeOrmConfigHelper
+
+Access individual configuration values:
+
+```typescript
+import { TypeOrmConfigHelper } from "@zola_do/typeorm";
+
+console.log(TypeOrmConfigHelper.DATABASE_HOST); // 'localhost'
+console.log(TypeOrmConfigHelper.DATABASE_PORT); // 5432
+console.log(TypeOrmConfigHelper.DATABASE_NAME); // 'myapp'
+console.log(TypeOrmConfigHelper.DATABASE_USER); // 'postgres'
+console.log(TypeOrmConfigHelper.DATABASE_PASSWORD); // 'secret'
+```
+
+### Config Keys
+
+| Key                 | Type     | Description                           |
+| ------------------- | -------- | ------------------------------------- |
+| `DATABASE_HOST`     | `string` | Database host                         |
+| `DATABASE_PORT`     | `number` | Database port                         |
+| `DATABASE_NAME`     | `string` | Database name                         |
+| `DATABASE_USER`     | `string` | Database user                         |
+| `DATABASE_PASSWORD` | `string` | Database password                     |
+| `APP_NAME`          | `string` | App name (fallback for DATABASE_NAME) |
+
+## TypeOrmService
+
+Injectable service for direct database access:
+
+```typescript
+import { Injectable } from "@nestjs/common";
+import { TypeOrmService } from "@zola_do/typeorm";
+
+@Injectable()
+export class AnalyticsService {
+  constructor(private readonly typeorm: TypeOrmService) {}
+
+  async getTableStats() {
+    return await this.typeorm.query(`
+      SELECT
+        schemaname,
+        relname,
+        n_tup_ins as inserts,
+        n_tup_upd as updates,
+        n_tup_del as deletes
+      FROM pg_stat_user_tables
+      WHERE schemaname = 'public'
+    `);
+  }
+}
+```
+
+## DataSource Options
+
+The `dataSourceOptions` object provides full TypeORM configuration:
 
 ```typescript
-import { Module } from '@nestjs/common';
-import { TypeOrmModule } from '@nestjs/typeorm';
 import { dataSourceOptions } from '@zola_do/typeorm';
 
+// Full options structure
+{
+  type: 'postgres',
+  host: 'localhost',
+  port: 5432,
+  database: 'myapp',
+  username: 'postgres',
+  password: 'secret',
+  entities: ['dist/**/*.entity.js', '**/*.entity.js'],
+  migrations: ['dist/**/*.migration.js', '**/*.migration.js'],
+  synchronize: false, // Use migrations in production
+  logging: process.env.NODE_ENV === 'development',
+  // ... more TypeORM options
+}
+```
+
+### Production Configuration
+
+```typescript
+// app.module.ts
+import { dataSourceOptions } from "@zola_do/typeorm";
+
 @Module({
   imports: [
-    TypeOrmModule.forRoot(dataSourceOptions),
-    // ... other modules
+    TypeOrmModule.forRoot({
+      ...dataSourceOptions,
+      synchronize: false,
+      migrationsRun: true,
+      logging: ["error", "warn"],
+    }),
   ],
 })
 export class AppModule {}
 ```
 
-### TypeOrmConfigHelper
+## Environment Variables
+
+| Variable            | Description                  | Default                  |
+| ------------------- | ---------------------------- | ------------------------ |
+| `DATABASE_HOST`     | Database host                | `localhost`              |
+| `DATABASE_PORT`     | Database port                | `5432`                   |
+| `DATABASE_NAME`     | Database name                | Falls back to `APP_NAME` |
+| `DATABASE_USER`     | Database user                | `postgres`               |
+| `DATABASE_PASSWORD` | Database password            | Required in production   |
+| `APP_NAME`          | Fallback for `DATABASE_NAME` | —                        |
+
+### Validation Rules
+
+- In production (`NODE_ENV === 'production'`), `DATABASE_PASSWORD` is required
+- Either `DATABASE_NAME` or `APP_NAME` must be set
+
+## Auto-Discovery
+
+Entities and migrations are auto-discovered:
+
+```typescript
+// dataSourceOptions.entities supports glob patterns
+entities: [
+  __dirname + "/../../**/*.entity.js", // Compiled output
+  "**/*.entity.js", // Source files
+];
+
+// dataSourceOptions.migrations supports glob patterns
+migrations: [__dirname + "/../../**/*.migration.js"];
+```
+
+### Entity File Location
+
+```
+src/
+├── entities/
+│   ├── base.entity.ts
+│   ├── product.entity.ts
+│   └── category.entity.ts
+└── app.module.ts
+```
+
+## Migrations
+
+### Generate Migration
+
+```bash
+npx typeorm migration:generate -d dist/typeorm/data-source.js src/migrations/ProductColumns
+```
+
+### Run Migrations
+
+```bash
+npx typeorm migration:run -d dist/typeorm/data-source.js
+```
 
-Access individual config values:
+### Create Migration Manually
 
 ```typescript
-import { TypeOrmConfigHelper } from '@zola_do/typeorm';
+import { MigrationInterface, QueryRunner, Table } from "typeorm";
 
-const host = TypeOrmConfigHelper.DATABASE_HOST;
-const port = TypeOrmConfigHelper.DATABASE_PORT;
-const database = TypeOrmConfigHelper.DATABASE_NAME;
-const username = TypeOrmConfigHelper.DATABASE_USER;
-const password = TypeOrmConfigHelper.DATABASE_PASSWORD;
+export class CreateProducts1704064000000 implements MigrationInterface {
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.createTable(
+      new Table({
+        name: "products",
+        columns: [
+          {
+            name: "id",
+            type: "uuid",
+            isPrimary: true,
+            generationStrategy: "uuid",
+          },
+          { name: "name", type: "varchar" },
+          { name: "price", type: "decimal", precision: 10, scale: 2 },
+          { name: "created_at", type: "timestamp", default: "now()" },
+          { name: "updated_at", type: "timestamp", default: "now()" },
+        ],
+      }),
+      true,
+    );
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.dropTable("products");
+  }
+}
 ```
 
-### TypeOrmService
+## API Reference
 
-Inject the TypeORM service for direct database access when needed:
+### Constants
 
 ```typescript
-import { TypeOrmService } from '@zola_do/typeorm';
+TypeOrmConfigHelper.DATABASE_HOST;
+TypeOrmConfigHelper.DATABASE_PORT;
+TypeOrmConfigHelper.DATABASE_NAME;
+TypeOrmConfigHelper.DATABASE_USER;
+TypeOrmConfigHelper.DATABASE_PASSWORD;
+```
+
+### DataSource
+
+```typescript
+import { dataSourceOptions } from "@zola_do/typeorm";
+// Type: DataSourceOptions
+```
+
+### Service
+
+```typescript
+import { TypeOrmService } from "@zola_do/typeorm";
 
 @Injectable()
-export class SomeService {
+class MyService {
   constructor(private readonly typeorm: TypeOrmService) {}
+
+  async query(sql: string, parameters?: any[]) {
+    return this.typeorm.query(sql, parameters);
+  }
 }
 ```
 
-## Environment Variables
+## Troubleshooting
+
+### Q: Entities not being loaded?
+
+Check glob pattern in `dataSourceOptions.entities`. The pattern should match your compiled `.js` files:
+
+```typescript
+entities: [__dirname + "/../../**/*.entity.js"];
+```
+
+### Q: Migrations not running?
+
+Ensure `migrationsRun: true` in production or run manually:
+
+```bash
+npm run migration:run
+```
+
+### Q: Connection refused?
+
+Verify `DATABASE_HOST` and `DATABASE_PORT` are correct and the database is accessible.
+
+## Related Packages
+
+- [@zola_do/crud](../crud) — Uses TypeORM entities
+- [@zola_do/collection-query](../collection-query) — Query builder for TypeORM
 
-| Variable | Description | Default |
-|----------|-------------|---------|
-| `DATABASE_HOST` | Database host | `localhost` |
-| `DATABASE_PORT` | Database port | `5432` |
-| `DATABASE_NAME` | Database name | Falls back to `APP_NAME` |
-| `DATABASE_USER` | Database user | `postgres` |
-| `DATABASE_PASSWORD` | Database password | Required in production |
-| `APP_NAME` | Fallback for `DATABASE_NAME` when `DATABASE_NAME` is not set | — |
+## License
 
-**Note:** In production, `DATABASE_PASSWORD` is required. Either `DATABASE_NAME` or `APP_NAME` must be set.
+ISC
 
 ## Community
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zola_do/typeorm",
-  "version": "0.2.5",
+  "version": "0.2.7",
   "description": "TypeORM configuration for NestJS",
   "author": "zolaDO",
   "license": "ISC",