stabilize-orm 1.1.8 → 1.3.0

package/CHANGELOG.md

@@ -2,6 +2,38 @@
 
 All notable changes to this project will be documented in this file.
 
+## [Unreleased]
+
+- Further features and improvements coming soon.
+
+## [1.3.0] - 2025-10-18
+
+### Added
+- Introduced programmatic `defineModel` API for model definitions, eliminating the need for decorators (`model.ts`).
+- Added `MetadataStorage` class to manage model configurations without `reflect-metadata`.
+- Added support for defining lifecycle hooks in `ModelConfig` or as class methods (`hooks.ts`).
+- Added `example.ts` to demonstrate the new programmatic API usage.
+- Extended `ModelConfig` interface to support columns, relations, hooks, versioning, and soft deletes (`types.ts`).
+
+### Changed
+- Replaced decorator-based model definitions with `defineModel` API, removing dependency on `reflect-metadata` and TypeScript experimental features (`experimentalDecorators`, `emitDecoratorMetadata`).
+- Updated `stabilize.ts` to export `defineModel` and remove `reflect-metadata` import.
+- Modified `repository.ts` to use `MetadataStorage` for table names, columns, relations, validators, and soft delete fields.
+- Rewrote `hooks.ts` to support hooks via `ModelConfig` and class methods, integrated with `MetadataStorage`.
+- Updated `migrations.ts` to generate schemas using `MetadataStorage` instead of decorator metadata.
+- Revised `types.ts` to remove decorator-related types and add `ModelConfig`, `ColumnConfig`, and `RelationConfig` interfaces.
+- Updated `README.md` to reflect the new programmatic API, remove decorator references, and update examples.
+- Ensured compatibility with `verbatimModuleSyntax` by using `export type` for type exports in `stabilize.ts`.
+
+### Removed
+- Deleted `decorators.ts` as decorators are no longer used.
+- Removed dependency on `reflect-metadata` from the project.
+
+### Fixed
+- Fixed TypeScript type errors in `repository.ts` for `columns` and `relations` by mapping `MetadataStorage` outputs to match expected types.
+- Corrected `runHooks` in `repository.ts` to call `hook.callback(entity)` instead of `hook()`.
+- Fixed TypeScript `verbatimModuleSyntax` error in `stabilize.ts` by separating type and value exports.
+
 ## [1.1.2] - 2025-10-14
 
 ### Added
@@ -16,8 +48,4 @@ All notable changes to this project will be documented in this file.
 - Enhanced documentation for open source best practices.
 
 ### Fixed
-- Various bug fixes for connection handling and retry logic.
-
-## [Unreleased]
-
-- Further features and improvements coming soon.
+- Various bug fixes for connection handling and retry logic.

package/README.md

@@ -1,72 +1,70 @@
 # Stabilize ORM
 
-_A Modern, Type-Safe, and Expressive ORM for Bun, Node.js, and Deno_
+_A Modern, Type-Safe, and Expressive ORM for Bun_
 
 ---
 
-**Stabilize** is a lightweight, feature-rich ORM designed for performance and developer experience. It provides a unified, database-agnostic API for **PostgreSQL**, **MySQL**, and **SQLite**, powered by a robust query builder, an elegant decorator-based model system, and a full-featured command-line interface.
+**Stabilize** is a lightweight, feature-rich ORM designed for performance and developer experience. It provides a unified, database-agnostic API for **PostgreSQL**, **MySQL**, and **SQLite**. Powered by a robust query builder, programmatic model definitions, automatic versioning, and a full-featured command-line interface, Stabilize is built to scale with your app.
 
 ---
 
 ## 🚀 Features
 
--   **Unified API**: Write once, run against PostgreSQL, MySQL, or SQLite.
--   **Type-Safe Decorators**: Define models and columns with the powerful `DataTypes` enum for true database-agnostic schemas.
--   **Full-Featured CLI**: Generate models, manage migrations, seed data, and reset your database from the command line.
--   **Automatic Migrations**: Generate database-specific SQL schemas directly from your model definitions.
--   **Retry Logic**: Automatic exponential backoff for database queries to handle transient connection issues.
--   **Connection Pooling**: Efficient connection management for PostgreSQL and MySQL out of the box.
--   **Transactional Integrity**: Built-in support for atomic transactions with automatic rollback on failure.
--   **Advanced Query Builder**: A fluent, chainable API for building complex queries with joins, where clauses, ordering, and pagination.
--   **Model Relationships**: Define `OneToOne`, `ManyToOne`, `OneToMany`, and `ManyToMany` relationships with simple decorators.
--   **Pluggable Logging**: Includes a robust `ConsoleLogger` with support for file-based, rotating logs.
--   **Custom Errors**: `StabilizeError` provides clear, consistent error handling.
--   **Caching Layer**: Optional Redis-backed caching with `cache-aside` and `write-through` strategies.
+- **Unified API**: Write once, run on PostgreSQL, MySQL, or SQLite.
+- **Programmatic Model Definitions**: Define models and columns using the `defineModel` API with the `DataTypes` enum for database-agnostic schemas.
+- **Full-Featured CLI**: Generate models, manage migrations, seed data, and reset your database from the command line with [stabilize-cli](https://github.com/ElectronSz/stabilize-cli).
+- **Automatic Migrations**: Generate database-specific SQL schemas directly from your model definitions.
+- **Versioned Models & Time-Travel**: Enable versioning in your model configuration for automatic history tables and snapshot queries.
+- **Retry Logic**: Automatic exponential backoff for database queries to handle transient connection issues.
+- **Connection Pooling**: Efficient connection management for PostgreSQL and MySQL.
+- **Transactional Integrity**: Built-in support for atomic transactions with automatic rollback on failure.
+- **Advanced Query Builder**: Fluent, chainable API for building complex queries, including joins, filters, ordering, and pagination.
+- **Model Relationships**: Define `OneToOne`, `ManyToOne`, `OneToMany`, and `ManyToMany` relationships in the model configuration.
+- **Soft Deletes**: Enable soft deletes in the model configuration for transparent "deleted" flags and safe row removal.
+- **Lifecycle Hooks**: Define hooks in the model configuration or as class methods for lifecycle events like `beforeCreate`, `afterUpdate`, etc.
+- **Pluggable Logging**: Includes a robust `ConsoleLogger` with support for file-based, rotating logs.
+- **Custom Errors**: `StabilizeError` provides clear, consistent error handling.
+- **Caching Layer**: Optional Redis-backed caching with `cache-aside` and `write-through` strategies.
 
 ---
 
 ## 📦 Installation
 
-Stabilize ORM requires a modern JavaScript runtime (Bun v1.0+, Node.js v18+, Deno v1.28+).
+Stabilize ORM requires a modern JavaScript runtime (Bun v1.3+).
 
 ```bash
 # Using Bun
-bun add stabilize-orm reflect-metadata
+bun add stabilize-orm
 
 # Using npm
-npm install stabilize-orm reflect-metadata
+npm install stabilize-orm
 ```
 
 ---
 
 ## 📃 Documentation & Community
 
--   [Changelog](./CHANGELOG.md)
--   [License](./LICENSE.md)
--   [Code of Conduct](./CODE_OF_CONDUCT.md)
--   [Contributing Guide](./CONTRIBUTING.md)
--   [Security Policy](./SECURITY.md)
--   [Support](./SUPPORT.md)
--   [Funding](./FUNDING.md)
+- [Changelog](./CHANGELOG.md)
+- [License](./LICENSE.md)
+- [Code of Conduct](./CODE_OF_CONDUCT.md)
+- [Contributing Guide](./CONTRIBUTING.md)
+- [Security Policy](./SECURITY.md)
+- [Support](./SUPPORT.md)
+- [Funding](./FUNDING.md)
 
 ---
 
 ## ⚙️ Configuration
 
-First, create a database configuration file.
+Create a database configuration file.
 
 ```typescript
 // config/database.ts
 import { DBType, type DBConfig } from "stabilize-orm";
 
 const dbConfig: DBConfig = {
-  // Choose your database type
-  type: DBType.Postgres, 
-  
-  // Connection string for your database
+  type: DBType.Postgres,
   connectionString: process.env.DATABASE_URL || "postgres://user:password@localhost:5432/mydb",
-
-  // Optional: Connection retry settings
   retryAttempts: 3,
   retryDelay: 1000,
 };
@@ -74,29 +72,26 @@ const dbConfig: DBConfig = {
 export default dbConfig;
 ```
 
-Next, create a central ORM instance that your application can use. Remember to import `reflect-metadata` once at your application's entry point.
+Next, create a central ORM instance for your application.
 
 ```typescript
 // db.ts
-import 'reflect-metadata'; // declared first
 import { Stabilize, type CacheConfig, type LoggerConfig, LogLevel } from "stabilize-orm";
 import dbConfig from "./database";
 
 const cacheConfig: CacheConfig = {
   enabled: process.env.CACHE_ENABLED === "true",
   redisUrl: process.env.REDIS_URL,
-  ttl: 60, // Default TTL in seconds
+  ttl: 60,
 };
 
 const loggerConfig: LoggerConfig = {
-    level: LogLevel.Info,
-    // Optional: Configure file logging
-    filePath: 'logs/stabilize.log',
-    maxFileSize: 5 * 1024 * 1024, // 5MB
-    maxFiles: 3,
-}
+  level: LogLevel.Info,
+  filePath: "logs/stabilize.log",
+  maxFileSize: 5 * 1024 * 1024, // 5MB
+  maxFiles: 3,
+};
 
-// Create and export the ORM instance
 export const orm = new Stabilize(dbConfig, cacheConfig, loggerConfig);
 ```
 
@@ -104,127 +99,219 @@ export const orm = new Stabilize(dbConfig, cacheConfig, loggerConfig);
 
 ## 🏗️ Models & Relationships
 
-Define your database tables as classes using decorators. The new `@Column` decorator uses the `DataTypes` enum for a truly database-agnostic schema definition.
+Define your tables as classes using the `defineModel` function. The `DataTypes` enum ensures database-agnostic schemas.
 
-### Example: Users and Roles (Many-to-Many)
-
-Here's how to model a many-to-many relationship between `User` and `Role` through a `UserRole` join table.
+### Example: Users and Roles (Many-to-Many) with Versioning
 
 ```typescript
 // models/User.ts
-import 'reflect-metadata';
-import { Model, Column, DataTypes, Required, Unique, OneToMany } from 'stabilize-orm';
-import { UserRole } from './UserRole';
-
-@Model('users')
-export class User {
-  @Column({ type: DataTypes.INTEGER, name: 'id' })
-  id!: number;
-
-  @Column({ type: DataTypes.STRING, length: 100 })
-  @Required() @Unique()
-  email!: string;
-  
-  // This side of the relationship is for querying convenience
-  @OneToMany(() => UserRole, 'user')
-  roles?: UserRole[];
-}
+import { defineModel, DataTypes, RelationType } from "stabilize-orm";
+import { UserRole } from "./UserRole";
+
+const User = defineModel({
+  tableName: "users",
+  versioned: true,
+  columns: {
+    id: { type: DataTypes.Integer, required: true },
+    email: { type: DataTypes.String, length: 100, required: true, unique: true },
+  },
+  relations: [
+    {
+      type: RelationType.OneToMany,
+      target: () => UserRole,
+      property: "roles",
+      foreignKey: "userId",
+    },
+  ],
+  hooks: {
+    beforeCreate: (entity) => console.log(`Creating user: ${entity.email}`),
+  },
+});
+
+// Add a hook as a class method
+User.prototype.afterCreate = async function () {
+  console.log(`Created user with ID: ${this.id}`);
+};
+
+export { User };
 ```
 
 ```typescript
 // models/Role.ts
-import 'reflect-metadata';
-import { Model, Column, DataTypes, Required, Unique } from 'stabilize-orm';
-
-@Model('roles')
-export class Role {
-  @Column({ type: DataTypes.INTEGER, name: 'id' })
-  id!: number;
+import { defineModel, DataTypes } from "stabilize-orm";
+
+const Role = defineModel({
+  tableName: "roles",
+  columns: {
+    id: { type: DataTypes.Integer, required: true },
+    name: { type: DataTypes.String, length: 50, required: true, unique: true },
+  },
+});
 
-  @Column({ type: DataTypes.STRING, length: 50 })
-  @Required() @Unique()
-  name!: string;
-}
+export { Role };
 ```
 
 ```typescript
 // models/UserRole.ts
-import 'reflect-metadata';
-import { Model, Column, DataTypes, Required, ManyToOne, Index } from 'stabilize-orm';
-import { User } from './User';
-import { Role } from './Role';
-
-@Model('user_roles') // The join table
-export class UserRole {
-  @Column({ type: DataTypes.INTEGER, name: 'id' })
-  id!: number;
-
-  @Column({ type: DataTypes.INTEGER, name: 'user_id' })
-  @Required() @Index()
-  userId!: number;
-
-  @Column({ type: DataTypes.INTEGER, name: 'role_id' })
-  @Required() @Index()
-  roleId!: number;
-
-  // Define the "many" sides of the relationship
-  @ManyToOne(() => User, 'userId')
-  user?: User;
-
-  @ManyToOne(() => Role, 'roleId')
-  role?: Role;
-}
+import { defineModel, DataTypes, RelationType } from "stabilize-orm";
+import { User } from "./User";
+import { Role } from "./Role";
+
+const UserRole = defineModel({
+  tableName: "user_roles",
+  columns: {
+    id: { type: DataTypes.Integer, required: true },
+    userId: { type: DataTypes.Integer, required: true, index: "idx_user_id" },
+    roleId: { type: DataTypes.Integer, required: true, index: "idx_role_id" },
+  },
+  relations: [
+    {
+      type: RelationType.ManyToOne,
+      target: () => User,
+      property: "user",
+      foreignKey: "userId",
+    },
+    {
+      type: RelationType.ManyToOne,
+      target: () => Role,
+      property: "role",
+      foreignKey: "roleId",
+    },
+  ],
+});
+
+export { UserRole };
+```
+
+---
+
+## ⏳ Versioning & Auditing
+
+Enable automatic history tracking and time-travel queries by setting `versioned: true` in your model configuration.
+
+- Each change is recorded in a `<table>_history` table with version, operation, and audit columns.
+- Supports snapshot queries, rollbacks, audits, and time-travel.
+
+### **Versioning Example**
+
+```typescript
+import { defineModel, DataTypes } from "stabilize-orm";
+
+const User = defineModel({
+  tableName: "users",
+  versioned: true,
+  columns: {
+    id: { type: DataTypes.Integer, required: true },
+    name: { type: DataTypes.String, length: 100 },
+  },
+});
+
+// --- Using versioning features:
+
+const userRepository = orm.getRepository(User);
+
+// Rollback to a previous version
+await userRepository.rollback(1, 3); // roll back user with id=1 to version 3
+
+// Get a snapshot as of a specific date
+const userAsOf = await userRepository.asOf(1, new Date("2025-01-01T00:00:00Z"));
+console.log(userAsOf);
+
+// View full version history
+const history = await userRepository.history(1);
+console.log(history);
 ```
 
 ---
 
+## 🔄 Model Lifecycle Hooks
+
+Stabilize ORM supports lifecycle hooks defined in the model configuration or as class methods. You can run logic before/after create, update, delete, or save.
+
+### **Hooks Example**
+
+```typescript
+import { defineModel, DataTypes } from "stabilize-orm";
+
+const User = defineModel({
+  tableName: "users",
+  columns: {
+    id: { type: DataTypes.Integer, required: true },
+    name: { type: DataTypes.String, length: 100 },
+    createdAt: { type: DataTypes.DateTime },
+    updatedAt: { type: DataTypes.DateTime },
+  },
+  hooks: {
+    beforeCreate: (entity) => {
+      entity.createdAt = new Date();
+    },
+    beforeUpdate: (entity) => {
+      entity.updatedAt = new Date();
+    },
+    afterCreate: (entity) => {
+      console.log(`User created: ${entity.name}`);
+    },
+  },
+});
+
+// Add a hook as a class method
+User.prototype.afterUpdate = async function () {
+  console.log(`Updated user: ${this.name}`);
+};
+
+export { User };
+```
+
+Supported hooks: `beforeCreate`, `afterCreate`, `beforeUpdate`, `afterUpdate`, `beforeDelete`, `afterDelete`, `beforeSave`, `afterSave`.
+
+---
+
 ## 💻 Command-Line Interface (CLI)
 
-Stabilize includes a powerful CLI for managing your development workflow.
+Stabilize includes a powerful CLI for managing your workflow. See: [stabilize-cli on GitHub](https://github.com/ElectronSz/stabilize-cli)
 
 ### Generating Files
 
--   **Generate a model**:
+- **Generate a model**:
     ```bash
-    bun run stabilize-cli generate model Product
+    stabilize-cli generate model Product
     ```
 
--   **Generate a migration from a model**:
+- **Generate a migration from a model**:
     ```bash
-    # Reads models/User.ts and creates a new migration file
-    bun run stabilize-cli generate migration User
+    stabilize-cli generate migration User
     ```
 
--   **Generate a seed file**:
+- **Generate a seed file**:
     ```bash
-    bun run stabilize-cli generate seed InitialRoles
+    stabilize-cli generate seed InitialRoles
     ```
 
 ### Database & Migration Management
 
--   **Run all pending migrations**:
+- **Run all pending migrations**:
     ```bash
-    bun run stabilize-cli migrate
+    stabilize-cli migrate
     ```
 
--   **Roll back the last migration**:
+- **Roll back the last migration**:
     ```bash
-    bun run stabilize-cli migrate:rollback
+    stabilize-cli migrate:rollback
     ```
 
--   **Run all pending seeds** (in dependency order):
+- **Run all pending seeds (in dependency order)**:
     ```bash
-    bun run stabilize-cli seed
+    stabilize-cli seed
     ```
 
--   **Check the status of all migrations and seeds**:
+- **Check the status of migrations and seeds**:
     ```bash
-    bun run stabilize-cli status
+    stabilize-cli status
     ```
 
--   **Reset the database (drop, migrate, seed)**:
+- **Reset the database (drop, migrate, seed)**:
     ```bash
-    bun run stabilize-cli db:reset
+    stabilize-cli db:reset
     ```
 
 ---
@@ -233,34 +320,24 @@ Stabilize includes a powerful CLI for managing your development workflow.
 
 ### Basic CRUD with Repositories
 
-Interact with your data using the `Repository` pattern.
-
 ```typescript
-import { orm } from './db';
-import { User } from 'models/User';
+import { orm } from "./db";
+import { User } from "./models/User";
 
 const userRepository = orm.getRepository(User);
 
-// Create a new user
-const newUser = await userRepository.create({ email: 'lwazicd@icloud.com' });
-
-// Find a user by ID
+const newUser = await userRepository.create({ email: "lwazicd@icloud.com" });
 const foundUser = await userRepository.findOne(newUser.id);
-
-// Update a user
-const updatedUser = await userRepository.update(newUser.id, { email: 'admin@offbytesecure.com' });
-
-// Delete a user
+const updatedUser = await userRepository.update(newUser.id, { email: "admin@offbytesecure.com" });
 await userRepository.delete(newUser.id);
 ```
 
 ### Advanced Queries with the Query Builder
 
-For complex queries, use the fluent `find()` method, which returns a chainable `QueryBuilder`.
-
 ```typescript
-const activeAdmins = await orm.getRepository(UserRole)
-  .find() // Start a query on the user_roles table
+const activeAdmins = await orm
+  .getRepository(UserRole)
+  .find()
   .join("users", "user_roles.user_id = users.id")
   .join("roles", "user_roles.role_id = roles.id")
   .select("users.id", "users.email", "roles.name as role_name")
@@ -269,13 +346,9 @@ const activeAdmins = await orm.getRepository(UserRole)
   .execute();
 
 console.log(activeAdmins);
-// [ { id: 1, email: 'lwazicd@icloud.com', role_name: 'Admin' } ]
 ```
 
-The `execute()` method on a repository query does not require a client to be passed; it uses the repository's default client automatically.
-
----
-**API:**
+#### Query Builder API
 
 ```typescript
 {
@@ -286,16 +359,48 @@ The `execute()` method on a repository query does not require a client to be pas
   limit(limit: number): QueryBuilder<User>;
   offset(offset: number): QueryBuilder<User>;
   build(): { query: string; params: any[] };
-  execute(client: DBClient, cache?: Cache, cacheKey?: string): Promise<User[]>;
+  execute(client?: DBClient, cache?: Cache, cacheKey?: string): Promise<User[]>;
 }
 ```
 
+---
+
+## 🗑️ Soft Deletes
+
+Enable soft deletes by setting `softDelete: true` and marking a column (e.g., `deletedAt`) with `softDelete: true` in the model configuration.
+
+- Use `repository.delete(id)` to mark an entity as deleted.
+- Use `repository.recover(id)` to restore a soft-deleted entity.
+- Queries automatically exclude soft-deleted rows unless specified otherwise.
+
+### **Soft Delete Example**
+
+```typescript
+import { defineModel, DataTypes } from "stabilize-orm";
+
+const User = defineModel({
+  tableName: "users",
+  softDelete: true,
+  columns: {
+    id: { type: DataTypes.Integer, required: true },
+    email: { type: DataTypes.String, length: 100, required: true },
+    deletedAt: { type: DataTypes.DateTime, softDelete: true },
+  },
+});
+
+const userRepository = orm.getRepository(User);
+await userRepository.create({ email: "lwazicd@icloud.com" });
+await userRepository.delete(1); // Soft delete
+await userRepository.recover(1); // Recover
+```
+
+---
+
 ## 🌐 Express.js Integration
 
 Stabilize ORM works seamlessly with web frameworks like Express.
 
 ```typescript
-// src/server.ts
 import express from "express";
 import { orm } from "./db";
 import { User } from "./models/User";
@@ -305,7 +410,6 @@ app.use(express.json());
 
 const userRepository = orm.getRepository(User);
 
-// Get all users
 app.get("/users", async (req, res) => {
   try {
     const users = await userRepository.find().execute();
@@ -315,7 +419,6 @@ app.get("/users", async (req, res) => {
   }
 });
 
-// Create a new user
 app.post("/users", async (req, res) => {
   try {
     const user = await userRepository.create(req.body);
@@ -332,6 +435,13 @@ app.listen(3000, () => {
 
 ---
 
+## 🧑‍🔬 Testing & Time-Travel
+
+- Use time-travel queries to inspect historical entity states.
+- Assert audit trails and rollback operations in your tests.
+
+---
+
 ## 📑 License
 
 Licensed under the MIT License. See [LICENSE.md](./LICENSE.md) for details.
@@ -342,6 +452,6 @@ Licensed under the MIT License. See [LICENSE.md](./LICENSE.md) for details.
 
 Created with ❤️ by **ElectronSz**
 <br/>
-*File last updated: 2025-10-15 19:32:00 UTC*
+<em>File last updated: 2025-10-18 22:10:00 SAST</em>
 
 </div>

package/bun.lock

@@ -7,7 +7,6 @@
         "@types/pg": "^8.15.5",
         "@types/uuid": "^11.0.0",
         "commander": "^12.1.0",
-        "dotenv": "^17.2.3",
         "figlet": "^1.9.3",
         "glob": "^11.0.0",
         "ioredis": "^5.4.1",
@@ -307,8 +306,6 @@
 
     "denque": ["denque@2.1.0", "", {}, "sha512-HVQE3AAb/pxF8fQAoiqpvg9i3evqug3hoiwakOyZAwJm+6vZehbkYXZ0l4JxS+I3QxM97v5aaRNhj8v5oBhekw=="],
 
-    "dotenv": ["dotenv@17.2.3", "", {}, "sha512-JVUnt+DUIzu87TABbhPmNfVdBDt18BLOWjMUFJMSi/Qqg7NTYtabbvSNJGOJ7afbRuv9D/lngizHtP7QyLQ+9w=="],
-
     "eastasianwidth": ["eastasianwidth@0.2.0", "", {}, "sha512-I88TYZWc9XiYHRQ4/3c5rjjfgkjhLyW2luGIheGERbNQ6OY7yTybanSpDXZa8y7VUP9YmDcYa+eyq4ca7iLqWA=="],
 
     "emoji-regex": ["emoji-regex@9.2.2", "", {}, "sha512-L18DaJsXSUk2+42pv8mLs5jJT2hqFkFE4j21wOmgbUqsZ2hL72NsUU785g9RXgo3s0ZNgVl42TiHp3ZtOv/Vyg=="],