@ttoss/postgresdb 0.2.22 → 0.2.23

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"
-}
-```
-
-## Usage
-
-### Setup the database
+### Database Setup
 
-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,19 @@ 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:
+_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 +78,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 command works by importing the `db` object from the `src/db.ts` file and calling the `sync` method on it.
+This imports `db` from `src/db.ts` and syncs the schema.
 
-### 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 +128,78 @@ const user = await db.User.create({
 });
 ```
 
-All models are available in the `db` object.
-
-### Using in a monorepo
-
-If you want to use in a monorepo by sharing the models between packages, you need to create some configurations to make it work.
-
-#### On the `postgresdb` package
+## Monorepo Usage
 
-1. Create your `postgresdb` package following the steps above.
+Share models across packages with this setup:
 
-1. Exports your main file in the `package.json` file:
+**In the database package (`@yourproject/postgresdb`):**
 
-   ```json
-   {
-     "type": "module",
-     "exports": "./src/index.ts"
-   }
-   ```
+`package.json`:
 
-1. Create a new file called `src/index.ts` with the following content to exports the `models` you've created:
-
-   ```typescript
-   export * as models from './models';
-   ```
-
-   _We recommend to not export the `db` object in this file because you may want to use different configurations in different packages._
-
-#### On the other packages
-
-1. Install `@ttoss/postgresdb` package:
+```json
+{
+  "type": "module",
+  "exports": "./src/index.ts"
+}
+```
 
-   ```bash
-   pnpm add @ttoss/postgresdb
-   ```
+`src/index.ts`:
 
-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):
+```typescript
+export * as models from './models';
+```
 
-   ```json
-   {
-     "dependencies": {
-       "@yourproject/postgresdb": "workspace:^"
-     }
-   }
-   ```
+_Don't export `db` here - each package may need different configurations._
 
-1. Include the `postgresdb` package in the `include` field of the `tsconfig.json` file:
+**In consuming packages:**
 
-   ```json
-   {
-     "include": ["src", "../postgresdb/src"]
-   }
-   ```
+Add dependencies to `package.json`:
 
-   _This way, you can import the models using the `@yourproject/postgresdb` package._
+```json
+{
+  "dependencies": {
+    "@ttoss/postgresdb": "^x.x.x",
+    "@yourproject/postgresdb": "workspace:^"
+  }
+}
+```
 
-1. Create a new file called `src/db.ts` with the following content:
+Update `tsconfig.json`:
 
-   ```typescript
-   import { initialize } from '@ttoss/postgresdb';
-   import { models } from '@yourproject/postgresdb';
+```json
+{
+  "include": ["src", "../postgresdb/src"]
+}
+```
 
-   export const db = initialize({
-     models,
-     // other configurations
-   });
-   ```
+Create `src/db.ts`:
 
-1. Use the `db` object to interact with the database.
+```typescript
+import { initialize } from '@ttoss/postgresdb';
+import { models } from '@yourproject/postgresdb';
 
-## API
+export const db = initialize({ models });
+```
 
-### `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 +213,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.23",
   "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": [