@ttoss/postgresdb 0.2.27 → 0.4.0

package/README.md

@@ -50,7 +50,7 @@ Create `models/User.ts`:
 import { Table, Column, Model } from '@ttoss/postgresdb';
 
 @Table
-export class User extends Model<User> {
+export class User extends Model {
   @Column
   declare name: string;
 
@@ -130,6 +130,66 @@ const user = await db.User.create({
 });
 ```
 
+## Vector Support (pgvector)
+
+This package includes built-in support for [pgvector](https://github.com/pgvector/pgvector), enabling vector similarity search for AI/ML applications like semantic search, recommendations, and RAG systems.
+
+### Setup
+
+Enable pgvector by setting `createVectorExtension: true` when initializing:
+
+```typescript
+import { initialize } from '@ttoss/postgresdb';
+import * as models from './models';
+
+export const db = await initialize({
+  models,
+  createVectorExtension: true, // Automatically creates the pgvector extension
+});
+```
+
+This automatically executes `CREATE EXTENSION IF NOT EXISTS vector` on your database.
+
+### Using VECTOR Type
+
+Define vector columns using `DataType.VECTOR(dimensions)`:
+
+```typescript
+import { Table, Column, Model, DataType } from '@ttoss/postgresdb';
+
+@Table
+class Document extends Model {
+  @Column
+  declare content: string;
+
+  @Column({
+    type: DataType.VECTOR(1536), // 1536-dimensional vector (e.g., OpenAI embeddings)
+    allowNull: true,
+  })
+  declare embedding: number[];
+}
+```
+
+### Vector Operations
+
+```typescript
+import { db } from './db';
+
+// Create document with embedding
+const doc = await db.Document.create({
+  content: 'Machine learning tutorial',
+  embedding: [0.1, 0.2, 0.3, ...], // 1536-dimensional array
+});
+
+// Find similar documents using cosine distance
+const similar = await db.Document.findAll({
+  order: sequelize.literal(`embedding <=> '[0.1, 0.2, 0.3, ...]'`),
+  limit: 5,
+});
+```
+
+For advanced vector operations and indexing, see the [pgvector documentation](https://github.com/pgvector/pgvector#readme).
+
 ## Monorepo Usage
 
 Share models across packages with this setup:
@@ -193,6 +253,12 @@ Testing models with decorators requires special configuration because Jest's Bab
 
 **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.
 
+:::warning Import from compiled output
+
+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.
+
+:::
+
 ### Setup
 
 **1. Install dependencies:**
@@ -282,7 +348,6 @@ describe('User model', () => {
 
 ### Key Points
 
-- **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.
@@ -304,6 +369,97 @@ Initializes database connection and loads models.
 
 All [sequelize-typescript](https://www.npmjs.com/package/sequelize-typescript) decorators are exported: `@Table`, `@Column`, `@ForeignKey`, etc.
 
+#### Hooks
+
+Lifecycle hooks allow you to execute code at specific points in the model lifecycle. All hook decorators from sequelize-typescript are available:
+
+**Instance Hooks:**
+
+- `@BeforeValidate`, `@AfterValidate`, `@ValidationFailed`
+- `@BeforeCreate`, `@AfterCreate`
+- `@BeforeUpdate`, `@AfterUpdate`
+- `@BeforeDestroy`, `@AfterDestroy`
+- `@BeforeSave`, `@AfterSave` (v4 only)
+- `@BeforeUpsert`, `@AfterUpsert` (v4 only)
+- `@BeforeRestore`, `@AfterRestore`
+
+**Bulk Hooks:**
+
+- `@BeforeBulkCreate`, `@AfterBulkCreate`
+- `@BeforeBulkUpdate`, `@AfterBulkUpdate`
+- `@BeforeBulkDestroy`, `@AfterBulkDestroy`
+- `@BeforeBulkRestore`, `@AfterBulkRestore`
+- `@BeforeBulkSync`, `@AfterBulkSync`
+
+**Query Hooks:**
+
+- `@BeforeFind`, `@AfterFind`
+- `@BeforeFindAfterExpandIncludeAll`, `@BeforeFindAfterOptions`
+- `@BeforeCount`
+
+**Connection Hooks:**
+
+- `@BeforeConnect`, `@AfterConnect`
+- `@BeforeDefine`, `@AfterDefine`
+- `@BeforeInit`, `@AfterInit`
+
+**Example:**
+
+```typescript
+import {
+  Table,
+  Column,
+  Model,
+  BeforeCreate,
+  BeforeUpdate,
+} from '@ttoss/postgresdb';
+
+@Table
+class Product extends Model {
+  @Column
+  declare name: string;
+
+  @Column
+  declare slug: string;
+
+  @BeforeCreate
+  static generateSlug(instance: Product) {
+    if (instance.name && !instance.slug) {
+      instance.slug = instance.name.toLowerCase().replace(/\s+/g, '-');
+    }
+  }
+
+  @BeforeUpdate
+  static updateSlug(instance: Product) {
+    if (instance.changed('name') && instance.name) {
+      instance.slug = instance.name.toLowerCase().replace(/\s+/g, '-');
+    }
+  }
+}
+```
+
+See the [sequelize-typescript hooks documentation](https://github.com/sequelize/sequelize-typescript#hooks) for more details.
+
+### DataType
+
+All standard Sequelize data types are available through `DataType`, including:
+
+- **`DataType.VECTOR(dimensions)`**: PostgreSQL vector type for storing embeddings (requires [pgvector](https://github.com/pgvector/pgvector) extension). Use for AI/ML applications like semantic search and recommendations.
+
+Example:
+
+```typescript
+import { Column, DataType } from '@ttoss/postgresdb';
+
+@Column({
+  type: DataType.VECTOR(768), // 768-dimensional vector
+  allowNull: true,
+})
+declare embedding: number[];
+```
+
+See [Sequelize DataTypes documentation](https://sequelize.org/docs/v6/core-concepts/model-basics/#data-types) for all available types.
+
 ### Types
 
 #### `ModelColumns<T>`
@@ -314,7 +470,7 @@ Extracts column types from a model:
 import { Column, Model, type ModelColumns, Table } from '@ttoss/postgresdb';
 
 @Table
-class User extends Model<User> {
+class User extends Model {
   @Column
   declare name?: string;
 

package/dist/esm/index.js

@@ -6,12 +6,17 @@ var __name = (target, value) => __defProp(target, "name", {
 });
 
 // src/sequelize-typescript.ts
-import { BelongsTo, BelongsToMany, Column, CreatedAt, DataType, DeletedAt, ForeignKey, HasMany, HasOne, Index, Model, PrimaryKey, Sequelize, Table, Unique, UpdatedAt } from "sequelize-typescript";
+import pgvector from "pgvector/sequelize";
+import { DataType as SequelizeDataType, Sequelize } from "sequelize-typescript";
+import { AfterBulkCreate, AfterBulkDestroy, AfterBulkRestore, AfterBulkSync, AfterBulkUpdate, AfterConnect, AfterCreate, AfterDefine, AfterDestroy, AfterFind, AfterInit, AfterRestore, AfterSave, AfterUpdate, AfterUpsert, AfterValidate, BeforeBulkCreate, BeforeBulkDestroy, BeforeBulkRestore, BeforeBulkSync, BeforeBulkUpdate, BeforeConnect, BeforeCount, BeforeCreate, BeforeDefine, BeforeDestroy, BeforeFind, BeforeFindAfterExpandIncludeAll, BeforeFindAfterOptions, BeforeInit, BeforeRestore, BeforeSave, BeforeUpdate, BeforeUpsert, BeforeValidate, BelongsTo, BelongsToMany, Column, CreatedAt, DeletedAt, ForeignKey, HasMany, HasOne, Index, Model, PrimaryKey, Sequelize as Sequelize2, Table, Unique, UpdatedAt, ValidationFailed } from "sequelize-typescript";
+pgvector.registerType(Sequelize);
+var DataType = SequelizeDataType;
 
 // src/initialize.ts
 var sequelize;
 var initialize = /* @__PURE__ */__name(async ({
   models,
+  createVectorExtension = false,
   ...restOptions
 }) => {
   const username = process.env.DATABASE_USER,
@@ -20,7 +25,7 @@ var initialize = /* @__PURE__ */__name(async ({
     host = process.env.DATABASE_HOST,
     port = Number(process.env.DATABASE_PORT) || 5432;
   if (!sequelize) {
-    sequelize = new Sequelize({
+    sequelize = new Sequelize2({
       logging: false,
       username,
       password,
@@ -43,6 +48,9 @@ var initialize = /* @__PURE__ */__name(async ({
   if (username && password && database && host && port) {
     await sequelize.authenticate();
   }
+  if (createVectorExtension) {
+    await sequelize.query("CREATE EXTENSION IF NOT EXISTS vector;");
+  }
   const close = sequelize.close;
   return {
     sequelize,
@@ -53,4 +61,4 @@ var initialize = /* @__PURE__ */__name(async ({
 
 // src/index.ts
 import { Op } from "sequelize";
-export { BelongsTo, BelongsToMany, Column, CreatedAt, DataType, DeletedAt, ForeignKey, HasMany, HasOne, Index, Model, Op, PrimaryKey, Sequelize, Table, Unique, UpdatedAt, initialize };
+export { AfterBulkCreate, AfterBulkDestroy, AfterBulkRestore, AfterBulkSync, AfterBulkUpdate, AfterConnect, AfterCreate, AfterDefine, AfterDestroy, AfterFind, AfterInit, AfterRestore, AfterSave, AfterUpdate, AfterUpsert, AfterValidate, BeforeBulkCreate, BeforeBulkDestroy, BeforeBulkRestore, BeforeBulkSync, BeforeBulkUpdate, BeforeConnect, BeforeCount, BeforeCreate, BeforeDefine, BeforeDestroy, BeforeFind, BeforeFindAfterExpandIncludeAll, BeforeFindAfterOptions, BeforeInit, BeforeRestore, BeforeSave, BeforeUpdate, BeforeUpsert, BeforeValidate, BelongsTo, BelongsToMany, Column, CreatedAt, DataType, DeletedAt, ForeignKey, HasMany, HasOne, Index, Model, Op, PrimaryKey, Sequelize2 as Sequelize, Table, Unique, UpdatedAt, ValidationFailed, initialize };

package/dist/index.d.ts

@@ -1,16 +1,30 @@
-import { ModelCtor, SequelizeOptions, Sequelize, Model } from 'sequelize-typescript';
-export { BelongsTo, BelongsToMany, Column, CreatedAt, DataType, DeletedAt, ForeignKey, HasMany, HasOne, Index, Model, ModelCtor, PrimaryKey, Sequelize, SequelizeOptions, Table, Unique, UpdatedAt } from 'sequelize-typescript';
+import { DataType as DataType$1, ModelCtor, SequelizeOptions, Sequelize, Model } from 'sequelize-typescript';
+export { AfterBulkCreate, AfterBulkDestroy, AfterBulkRestore, AfterBulkSync, AfterBulkUpdate, AfterConnect, AfterCreate, AfterDefine, AfterDestroy, AfterFind, AfterInit, AfterRestore, AfterSave, AfterUpdate, AfterUpsert, AfterValidate, BeforeBulkCreate, BeforeBulkDestroy, BeforeBulkRestore, BeforeBulkSync, BeforeBulkUpdate, BeforeConnect, BeforeCount, BeforeCreate, BeforeDefine, BeforeDestroy, BeforeFind, BeforeFindAfterExpandIncludeAll, BeforeFindAfterOptions, BeforeInit, BeforeRestore, BeforeSave, BeforeUpdate, BeforeUpsert, BeforeValidate, BelongsTo, BelongsToMany, Column, CreatedAt, DeletedAt, ForeignKey, HasMany, HasOne, Index, Model, ModelCtor, PrimaryKey, Sequelize, SequelizeOptions, Table, Unique, UpdatedAt, ValidationFailed } from 'sequelize-typescript';
+import { DataType as DataType$2 } from 'sequelize';
 export { Op } from 'sequelize';
 
+/**
+ * Extend DataType to include VECTOR type from pgvector
+ */
+declare const DataType: typeof DataType$1 & {
+    VECTOR: (dimensions: number) => DataType$2;
+};
+
 type Options<Models> = Omit<SequelizeOptions, 'models' | 'dialect'> & {
     models: Models;
+    /**
+     * If true, creates the pgvector extension in the database.
+     * This is required to use VECTOR data types.
+     * @default false
+     */
+    createVectorExtension?: boolean;
 };
 declare const initialize: <Models extends {
     [key: string]: ModelCtor;
-}>({ models, ...restOptions }: Options<Models>) => Promise<{
+}>({ models, createVectorExtension, ...restOptions }: Options<Models>) => Promise<{
     sequelize: Sequelize;
 } & Models>;
 
 type ModelColumns<T> = Omit<T, keyof Model> & Pick<Model, 'id' | 'createdAt' | 'updatedAt'>;
 
-export { type ModelColumns, initialize };
+export { DataType, type ModelColumns, initialize };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ttoss/postgresdb",
-  "version": "0.2.27",
+  "version": "0.4.0",
   "description": "A library to handle PostgreSQL database connections and queries",
   "license": "MIT",
   "author": "ttoss",
@@ -25,10 +25,12 @@
   "sideEffects": false,
   "dependencies": {
     "pg": "^8.16.3",
+    "pgvector": "^0.2.1",
     "sequelize": "^6.37.7",
     "sequelize-typescript": "^2.1.6"
   },
   "devDependencies": {
+    "@testcontainers/postgresql": "^11.8.1",
     "jest": "^30.2.0",
     "tsup": "^8.5.1",
     "@ttoss/config": "^1.35.12"
@@ -44,6 +46,7 @@
   },
   "scripts": {
     "build": "tsup",
-    "test": "echo jest"
+    "pretest": "tsup --config ./tests/tsup.pretest.config.ts",
+    "test": "jest --projects tests/unit"
   }
 }