@ttoss/postgresdb 0.2.22 → 0.2.24

package/README.md

@@ -1,6 +1,6 @@
 # @ttoss/postgresdb
 
-This package uses [Sequelize](https://sequelize.org/) to provide a simple framework for working with PostgreSQL databases.
+A lightweight [Sequelize](https://sequelize.org/) wrapper for PostgreSQL databases with TypeScript support.
 
 ## Installation
 
@@ -9,27 +9,19 @@ pnpm add @ttoss/postgresdb
 pnpm add -D @ttoss/postgresdb-cli
 ```
 
-### ESM only
+**ESM only**: Add `"type": "module"` to your `package.json`.
 
-This package is [ESM only](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c). Make sure to use it in an ESM environment.
+## Quick Start
 
-```json
-{
-  "type": "module"
-}
-```
+### Database Setup
 
-## Usage
-
-### Setup the database
-
-If you already have a database, you can skip this step. If you don't, you can use the following Docker command to create a new PostgreSQL database on port 5432 using Docker:
+Use Docker to create a PostgreSQL instance:
 
 ```bash
 docker run --name postgres-test -e POSTGRES_PASSWORD=mysecretpassword -d -p 5432:5432 postgres
 ```
 
-If you want to use [Docker Compose](https://docs.docker.com/compose/), you can create a `docker-compose.yml` file with the following content:
+Or with Docker Compose (`docker-compose.yml`):
 
 ```yaml
 services:
@@ -46,15 +38,13 @@ volumes:
   db-data:
 ```
 
-And run the following command:
-
 ```bash
 docker compose up -d
 ```
 
-### Create a model
+### Define Models
 
-Create a folder called `models` and add a new file called `User.ts` with the following content:
+Create `models/User.ts`:
 
 ```typescript
 import { Table, Column, Model } from '@ttoss/postgresdb';
@@ -67,19 +57,21 @@ export class User extends Model<User> {
   @Column
   declare email: string;
 }
-
-_This packages exports all decorators from [sequelize-typescript](https://github.com/sequelize/sequelize-typescript), so you can use them to define your models._
 ```
 
-Export the model in the `models/index.ts` file:
+**Important:** You must use the `declare` keyword on class properties to ensure TypeScript doesn't emit them as actual fields. Without `declare`, public class fields would shadow Sequelize's getters and setters, blocking access to the model's data. See [Sequelize documentation on public class fields](https://sequelize.org/docs/v6/core-concepts/model-basics/#caveat-with-public-class-fields) for details.
+
+_All [sequelize-typescript](https://github.com/sequelize/sequelize-typescript) decorators are available._
+
+Export in `models/index.ts`:
 
 ```typescript
 export { User } from './User';
 ```
 
-### Create a new instance of the database
+### Initialize Database
 
-Create a new file called `src/db.ts` with the following content:
+Create `src/db.ts`:
 
 ```typescript
 import { initialize } from '@ttoss/postgresdb';
@@ -88,60 +80,46 @@ import * as models from './models';
 export const db = await initialize({ models });
 ```
 
-_Note: the script [`sync`](#sync-the-database-schema) will use the `db` object to sync the database schema with the models._
-
-### Environment variables
-
-You can set the database connection parameters in two ways:
+### Configuration
 
-1. Defining them in the `src/db.ts` file using the `initialize` function.
+**Option 1 - Direct configuration:**
 
-   ```typescript
-   export const db = initialize({
-     database: '', // database name
-     username: '', // database username
-     password: '', // database password
-     host: '', // database host
-     port: 5432, // database port. Default: 5432
-     models,
-   });
-   ```
-
-2. Using environment variables:
-
-   - `DB_NAME`: database name
-   - `DB_USERNAME`: database username
-   - `DB_PASSWORD`: database password
-   - `DB_HOST`: database host
-   - `DB_PORT`: database port. Default: 5432
+```typescript
+export const db = initialize({
+  database: 'mydb',
+  username: 'user',
+  password: 'pass',
+  host: 'localhost',
+  port: 5432,
+  models,
+});
+```
 
-   `@ttoss/postgresdb` will use them automatically if they are defined.
+**Option 2 - Environment variables (`.env`):**
 
-   Here is an example of a `.env` file:
+```env
+DB_NAME=postgres
+DB_USERNAME=postgres
+DB_PASSWORD=mysecretpassword
+DB_HOST=localhost
+DB_PORT=5432
+```
 
-   ```env
-   DB_NAME=postgres
-   DB_USERNAME=postgres
-   DB_PASSWORD=mysecretpassword
-   DB_HOST=localhost
-   DB_PORT=5432
-   ```
+Environment variables are automatically used if defined.
 
-### Sync the database schema
+### Sync Schema
 
-To [sync](https://sequelize.org/docs/v6/core-concepts/model-basics/#model-synchronization) the database schema with the models, use the [`sync` command](https://ttoss.dev/docs/modules/packages/postgresdb-cli/):
+[Synchronize](https://sequelize.org/docs/v6/core-concepts/model-basics/#model-synchronization) database schema with models:
 
 ```bash
 pnpm dlx @ttoss/postgresdb-cli sync
 ```
 
-By now, you should have a working database with a `User` table.
+This imports `db` from `src/db.ts` and syncs the schema.
 
-This command works by importing the `db` object from the `src/db.ts` file and calling the `sync` method on it.
+### CRUD Operations
 
-### CRUD operations
-
-You can now use the `db` object to interact with the database. Check the [Sequelize documentation](https://sequelize.org/master/manual/model-querying-basics.html) for more information.
+All models are accessible via the `db` object. See [Sequelize documentation](https://sequelize.org/master/manual/model-querying-basics.html) for complete query API.
 
 ```typescript
 import { db } from './db';
@@ -152,96 +130,185 @@ const user = await db.User.create({
 });
 ```
 
-All models are available in the `db` object.
+## Monorepo Usage
+
+Share models across packages with this setup:
+
+**In the database package (`@yourproject/postgresdb`):**
+
+`package.json`:
+
+```json
+{
+  "type": "module",
+  "exports": "./src/index.ts"
+}
+```
+
+`src/index.ts`:
+
+```typescript
+export * as models from './models';
+```
+
+_Don't export `db` here - each package may need different configurations._
 
-### Using in a monorepo
+**In consuming packages:**
 
-If you want to use in a monorepo by sharing the models between packages, you need to create some configurations to make it work.
+Add dependencies to `package.json`:
 
-#### On the `postgresdb` package
+```json
+{
+  "dependencies": {
+    "@ttoss/postgresdb": "^x.x.x",
+    "@yourproject/postgresdb": "workspace:^"
+  }
+}
+```
+
+Update `tsconfig.json`:
+
+```json
+{
+  "compilerOptions": {
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true
+  },
+  "include": ["src", "../postgresdb/src"]
+}
+```
+
+Create `src/db.ts`:
+
+```typescript
+import { initialize } from '@ttoss/postgresdb';
+import { models } from '@yourproject/postgresdb';
+
+export const db = initialize({ models });
+```
 
-1. Create your `postgresdb` package following the steps above.
+## Testing
 
-1. Exports your main file in the `package.json` file:
+Testing models with decorators requires special configuration because Jest's Babel transformer doesn't properly transpile TypeScript decorators. The solution is to build your models before running tests.
 
-   ```json
-   {
-     "type": "module",
-     "exports": "./src/index.ts"
-   }
-   ```
+**Why test your models?** Beyond validating functionality, tests serve as a critical safety check for schema changes. They ensure that running `sync --alter` won't accidentally remove columns or relationships from your database. If a model property is missing or incorrectly defined, tests will fail before you can damage production data.
 
-1. Create a new file called `src/index.ts` with the following content to exports the `models` you've created:
+### Setup
 
-   ```typescript
-   export * as models from './models';
-   ```
+**1. Install dependencies:**
 
-   _We recommend to not export the `db` object in this file because you may want to use different configurations in different packages._
+```bash
+pnpm add -D @testcontainers/postgresql jest @types/jest
+```
 
-#### On the other packages
+**2. Configure `tsconfig.json`:**
+
+```json
+{
+  "compilerOptions": {
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true
+  }
+}
+```
 
-1. Install `@ttoss/postgresdb` package:
+These options are required for decorator support. Without them, TypeScript won't properly compile decorator metadata.
 
-   ```bash
-   pnpm add @ttoss/postgresdb
-   ```
+**3. Add build script to `package.json`:**
 
-1. Add your `postgresdb` package as a dependency. In the case you're using PNPM, you can use the [workspace protocol](https://pnpm.io/workspaces#workspace-protocol-workspace):
+```json
+{
+  "scripts": {
+    "build": "tsup",
+    "pretest": "pnpm run build",
+    "test": "jest"
+  }
+}
+```
 
-   ```json
-   {
-     "dependencies": {
-       "@yourproject/postgresdb": "workspace:^"
-     }
-   }
-   ```
+The `pretest` script ensures models are built before tests run.
 
-1. Include the `postgresdb` package in the `include` field of the `tsconfig.json` file:
+### Test Example
 
-   ```json
-   {
-     "include": ["src", "../postgresdb/src"]
-   }
-   ```
+```typescript
+import {
+  PostgreSqlContainer,
+  StartedPostgreSqlContainer,
+} from '@testcontainers/postgresql';
+import { initialize, Sequelize } from '@ttoss/postgresdb';
+import { models } from 'dist/index'; // Import from built output
+
+let sequelize: Sequelize;
+let postgresContainer: StartedPostgreSqlContainer;
+
+jest.setTimeout(60000);
+
+beforeAll(async () => {
+  // Start PostgreSQL container
+  postgresContainer = await new PostgreSqlContainer('postgres:17').start();
+
+  // Initialize database with container credentials
+  const db = await initialize({
+    models,
+    logging: false,
+    username: postgresContainer.getUsername(),
+    password: postgresContainer.getPassword(),
+    database: postgresContainer.getDatabase(),
+    host: postgresContainer.getHost(),
+    port: postgresContainer.getPort(),
+  });
+
+  sequelize = db.sequelize;
+
+  // Sync database schema
+  await sequelize.sync();
+});
 
-   _This way, you can import the models using the `@yourproject/postgresdb` package._
+afterAll(async () => {
+  await sequelize.close();
+  await postgresContainer.stop();
+});
 
-1. Create a new file called `src/db.ts` with the following content:
+describe('User model', () => {
+  test('should create and retrieve user', async () => {
+    const userData = { email: 'test@example.com' };
+    const user = await models.User.create(userData);
 
-   ```typescript
-   import { initialize } from '@ttoss/postgresdb';
-   import { models } from '@yourproject/postgresdb';
+    const foundUser = await models.User.findByPk(user.id);
+    expect(foundUser).toMatchObject(userData);
+  });
+});
+```
 
-   export const db = initialize({
-     models,
-     // other configurations
-   });
-   ```
+### Key Points
 
-1. Use the `db` object to interact with the database.
+- **Import from `dist/`**: Tests must import models from the compiled output (`dist/index`), not source files, because decorators aren't transpiled by Jest's Babel transformer. See [this Stack Overflow answer](https://stackoverflow.com/a/53920890/8786986) for details.
+- **Testcontainers**: Use [`@testcontainers/postgresql`](https://www.npmjs.com/package/@testcontainers/postgresql) to spin up isolated PostgreSQL instances for each test run.
+- **Timeout**: Set a longer timeout with `jest.setTimeout(60000)` as container startup can take time.
+- **Sync schema**: Call `sequelize.sync()` after initialization to create tables based on your models.
+- **Schema validation**: Tests verify that all model properties are correctly defined. This prevents `sync --alter` from accidentally removing database columns due to missing or misconfigured model properties.
 
-## API
+For a complete working example with full test configuration, see the [terezinha-farm/postgresdb](https://github.com/ttoss/ttoss/tree/main/terezinha-farm/postgresdb) example in this repository.
 
-### `initialize(options: InitializeOptions): db`
+## API Reference
 
-Initialize the database connection and load the models.
+### `initialize(options)`
 
-#### Options
+Initializes database connection and loads models.
 
-All [Sequelize options](https://sequelize.org/api/v6/class/src/sequelize.js~sequelize#instance-constructor-constructor) are available, expect `models`.
+**Options:** All [Sequelize options](https://sequelize.org/api/v6/class/src/sequelize.js~sequelize#instance-constructor-constructor) except `dialect` (always `postgres`), plus:
 
-- `models`: An object with all models to be loaded. The keys are the model names, and the values are the model classes. This way, you can access the models using the `db` object.
+- `models` (required): Object mapping model names to model classes
 
-### Sequelize decorators
+### Decorators
 
-This package exports all decorators from [sequelize-typescript](https://www.npmjs.com/package/sequelize-typescript), i.e., `@Table`, `@Column`, `@ForeignKey`, etc.
+All [sequelize-typescript](https://www.npmjs.com/package/sequelize-typescript) decorators are exported: `@Table`, `@Column`, `@ForeignKey`, etc.
 
-## Types
+### Types
 
-### `ModelColumns<T>`
+#### `ModelColumns<T>`
 
-A type that represents the columns of a model.
+Extracts column types from a model:
 
 ```typescript
 import { Column, Model, type ModelColumns, Table } from '@ttoss/postgresdb';
@@ -255,11 +322,6 @@ class User extends Model<User> {
   declare email: string;
 }
 
-/**
- * UserColumns = {
- *  name?: string;
- *  email: string;
- * }
- */
+// Inferred type: { name?: string; email: string; }
 type UserColumns = ModelColumns<User>;
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ttoss/postgresdb",
-  "version": "0.2.22",
+  "version": "0.2.24",
   "description": "A library to handle PostgreSQL database connections and queries",
   "license": "MIT",
   "author": "ttoss",
@@ -15,8 +15,8 @@
   "type": "module",
   "exports": {
     ".": {
-      "import": "./dist/esm/index.js",
-      "types": "./dist/index.d.ts"
+      "types": "./dist/index.d.ts",
+      "default": "./dist/esm/index.js"
     }
   },
   "files": [
@@ -31,7 +31,7 @@
   "devDependencies": {
     "jest": "^30.2.0",
     "tsup": "^8.5.1",
-    "@ttoss/config": "^1.35.10"
+    "@ttoss/config": "^1.35.11"
   },
   "keywords": [
     "database",