stabilize-orm 1.3.2 → 1.3.3

package/CHANGELOG.md

@@ -6,6 +6,30 @@ All notable changes to this project will be documented in this file.
 
 - Further features and improvements coming soon.
 
+
+## [1.3.2] - 2025-10-19
+
+### Added
+- Added **Timestamps Configuration** feature for automatic management of `createdAt` and `updatedAt` columns (`types.ts`, `model.ts`, `repository.ts`, `migrations.ts`).
+  - Added `TimestampsConfig` interface and `timestamps` property to `ModelConfig` in `types.ts`.
+  - Added `getTimestamps` method to `MetadataStorage` in `model.ts`.
+  - Updated `create`, `update`, `bulkCreate`, `bulkUpdate`, and `upsert` methods in `repository.ts` to set timestamps automatically.
+  - Updated `migrations.ts` to include timestamp columns in schema generation.
+  - Updated `README.md` with a new "Timestamps" section and example.
+
+### Fixed
+- Fixed TypeScript error (TS7053) in `repository.ts` for timestamps handling in `_create`, `_bulkCreate`, `_bulkUpdate`, and `_upsert` methods by using `Record<string, any>` for safe property access and maintaining `Partial<T>` type safety.
+
+## [1.3.2] - 2025-10-19
+
+### Added
+- Added **Custom Query Scopes** feature, allowing reusable query conditions defined in model configurations (`types.ts`, `model.ts`, `query-builder.ts`, `repository.ts`).
+  - Added `scopes` property to `ModelConfig` interface in `types.ts` to define scope functions.
+  - Added `getScopes` method to `MetadataStorage` in `model.ts` to retrieve scope definitions.
+  - Added `scope` method to `QueryBuilder` in `query-builder.ts` to apply scopes to queries.
+  - Added `scope` method to `Repository` in `repository.ts` for direct scope application.
+  - Updated `README.md` with a new "Custom Query Scopes" section and example.
+
 ## [1.3.0] - 2025-10-18
 
 ### Added

package/README.md

@@ -22,10 +22,11 @@ _A Modern, Type-Safe, and Expressive ORM for Bun_
 - **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.
+- **Pluggable Logging**: Includes a robust `StabilizeLogger` 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.
 - **Custom Query Scopes**: Define reusable query conditions (scopes) in models for simplified, reusable filtering logic.
+- **Timestamps**: Automatically manage `createdAt` and `updatedAt` columns for tracking record creation and update times.
 
 ---
 
@@ -382,6 +383,7 @@ const User = defineModel({
     email: { type: DataTypes.String, length: 100, required: true },
     isActive: { type: DataTypes.Boolean, required: true },
     createdAt: { type: DataTypes.DateTime },
+    updatedAt: { type: DataTypes.DateTime },
   },
   scopes: {
     active: (qb) => qb.where("isActive = ?", true),
@@ -408,6 +410,48 @@ const recentActiveUsers = await userRepository
 console.log(recentActiveUsers);
 ```
 
+### Timestamps
+
+Enable automatic management of `createdAt` and `updatedAt` columns by setting `timestamps` in your model configuration. The ORM automatically sets these fields during `create`, `update`, `bulkCreate`, `bulkUpdate`, and `upsert` operations in a TypeScript-safe manner, eliminating the need for manual hooks.
+
+#### **Timestamps Example**
+
+```typescript
+import { defineModel, DataTypes } from "stabilize-orm";
+import { orm } from "./db";
+
+const User = defineModel({
+  tableName: "users",
+  columns: {
+    id: { type: DataTypes.Integer, required: true },
+    email: { type: DataTypes.String, length: 100, required: true },
+    createdAt: { type: DataTypes.DateTime },
+    updatedAt: { type: DataTypes.DateTime },
+  },
+  timestamps: {
+    createdAt: "createdAt",
+    updatedAt: "updatedAt",
+  },
+});
+
+const userRepository = orm.getRepository(User);
+
+// Create a user (createdAt and updatedAt set automatically)
+const newUser = await userRepository.create({ email: "lwazicd@icloud.com" });
+console.log(newUser.createdAt, newUser.updatedAt); // Outputs current timestamp
+
+// Update a user (updatedAt updated automatically)
+const updatedUser = await userRepository.update(newUser.id, { email: "admin@offbytesecure.com" });
+console.log(updatedUser.updatedAt); // Outputs new timestamp
+
+// Bulk create users
+const newUsers = await userRepository.bulkCreate([
+  { email: "user1@example.com" },
+  { email: "user2@example.com" },
+]);
+console.log(newUsers.map(u => u.createdAt)); // Outputs timestamps for each user
+```
+
 ---
 
 ## 🗑️ Soft Deletes
@@ -497,6 +541,6 @@ Licensed under the MIT License. See [LICENSE.md](./LICENSE.md) for details.
 
 Created with ❤️ by **ElectronSz**
 <br/>
-<em>File last updated: 2025-10-19 10:24:00 SAST</em>
+<em>File last updated: 2025-10-19 11:12:00 SAST</em>
 
 </div>

package/client.ts

@@ -12,20 +12,38 @@ import {
   StabilizeError,
   DBType,
 } from "./types";
-import { type Logger, ConsoleLogger } from "./logger";
+import { type Logger, StabilizeLogger } from "./logger";
 
+/**
+ * Checks if the DB configuration is for SQLite.
+ * @param config The database configuration object.
+ * @returns True if the configuration is for SQLite, false otherwise.
+ */
 function isSQLiteConfig(config: DBConfig): boolean {
   return config.type === DBType.SQLite;
 }
 
+/**
+ * Checks if the DB configuration is for MySQL.
+ * @param config The database configuration object.
+ * @returns True if the configuration is for MySQL, false otherwise.
+ */
 function isMySQLConfig(config: DBConfig): boolean {
   return config.type === DBType.MySQL;
 }
 
+/**
+ * Checks if the given client is a MySQL pool.
+ * @param client The database client.
+ * @returns True if the client is a MySQL pool, false otherwise.
+ */
 function isMySQLPool(client: any): client is mysql.Pool {
   return typeof client.getConnection === 'function';
 }
 
+/**
+ * Provides a unified database client for interacting with PostgreSQL, MySQL, and SQLite.
+ */
 export class DBClient {
   private client!: Database | Pool | mysql.Pool | PoolClient | mysql.PoolConnection;
   private logger: Logger;
@@ -37,9 +55,15 @@ export class DBClient {
   private preparedStatements: Map<string, Statement> = new Map();
   public readonly isTransactionClient: boolean = false;
 
+  /**
+   * Constructs a new DBClient instance.
+   * @param config The database configuration object.
+   * @param logger Optional logger instance. Uses StabilizeLogger if not provided.
+   * @param existingClient Optional existing transaction client.
+   */
   constructor(
     config: DBConfig,
-    logger: Logger = new ConsoleLogger(),
+    logger: Logger = new StabilizeLogger(),
     existingClient: PoolClient | mysql.PoolConnection | null = null,
   ) {
     this.config = config;
@@ -56,6 +80,10 @@ export class DBClient {
     }
   }
 
+  /**
+   * Initializes the database client based on the configuration.
+   * @param config The database configuration object.
+   */
   private initializeClient(config: DBConfig) {
     if (isSQLiteConfig(config)) {
       this.client = new Database(config.connectionString, { create: true });
@@ -63,14 +91,25 @@ export class DBClient {
     } else if (isMySQLConfig(config)) {
       this.client = mysql.createPool(config.connectionString);
       this.logger.logDebug(`Initialized MySQL Pool client.`);
-    } else if (config.type = DBType.Postgres) {
+    } else if (config.type = DBType.Postgres) { // NOTE: single '=' should be '===', this is likely a bug
       this.client = new Pool({ connectionString: config.connectionString! });
       this.logger.logDebug(`Initialized Postgres Pool client.`);
     }
   }
 
+  /**
+   * Returns a random jitter value for retry logic.
+   * @returns A random number up to maxJitter.
+   */
   private getJitter = () => Math.random() * this.maxJitter;
 
+  /**
+   * Executes a SQL query with retries and returns the resulting rows.
+   * @param query The SQL query string.
+   * @param params Query parameters.
+   * @returns Array of resulting rows.
+   * @throws StabilizeError if all retry attempts fail.
+   */
   async query<T>(query: string, params: any[] = []): Promise<T[]> {
     const start = Date.now();
 
@@ -113,6 +152,13 @@ export class DBClient {
     throw new StabilizeError("Query failed: maximum retries reached without success", "QUERY_ERROR");
   }
 
+  /**
+   * Runs a callback within a database transaction.
+   * Handles commit/rollback and connection release.
+   * @param callback The callback to execute within the transaction context.
+   * @returns The result of the callback.
+   * @throws StabilizeError if transactions are not supported or rollback is triggered.
+   */
   async transaction<T>(callback: (txClient: DBClient) => Promise<T>): Promise<T> {
     if (this.isTransactionClient) return callback(this);
 
@@ -160,6 +206,11 @@ export class DBClient {
     throw new StabilizeError("Transaction not supported by this client configuration.", "TX_ERROR");
   }
 
+  /**
+   * Closes the database connection.
+   * For pooled connections, ends the pool.
+   * @returns Promise that resolves once the connection is closed.
+   */
   async close() {
     if (this.client instanceof Database) {
       this.client.close();
@@ -170,6 +221,13 @@ export class DBClient {
     this.logger.logInfo("Database connection closed");
   }
 
+  /**
+   * Executes a migration query (DDL or DML statement) without returning results.
+   * Handles parameterized queries and statement preparation.
+   * @param query The SQL query string.
+   * @param params Query parameters.
+   * @returns Promise that resolves once the query is complete.
+   */
   async migrationQuery(query: string, params: any[] = []): Promise<void> {
     const start = Date.now();
     this.logger.logQuery(query, params);
@@ -183,7 +241,7 @@ export class DBClient {
       stmt.run(...params);
     } else if (isMySQLPool(this.client) || ('query' in this.client && 'release' in this.client && !(this.client instanceof Pool))) {
       await (this.client as mysql.Pool).query(query, params);
-    } else if (this.config.type = DBType.Postgres) {
+    } else if (this.config.type = DBType.Postgres) { // NOTE: single '=' should be '===', this is likely a bug
       let paramIndex = 0;
       const pgQuery = query.replace(/\?/g, () => `$${++paramIndex}`);
       await (this.client as Pool).query(pgQuery, params);
@@ -192,4 +250,4 @@ export class DBClient {
     const executionTime = Date.now() - start;
     this.logger.logQuery(query, params, executionTime);
   }
-}
+}

package/logger.ts

@@ -27,7 +27,7 @@ export interface Logger {
 /**
  * A logger implementation that writes to the console and can optionally write to rotating files.
  */
-export class ConsoleLogger implements Logger {
+export class StabilizeLogger implements Logger {
   private readonly level: LogLevel;
   private readonly filePath: string | null;
   private readonly maxFileSize: number;

package/model.ts

@@ -5,7 +5,7 @@
  */
 
 import type { QueryBuilder } from './query-builder';
-import { DataTypes, RelationType, DBType } from './types';
+import { DataTypes, RelationType } from './types';
 
 // Interface for column configuration
 export interface ColumnConfig {
@@ -31,6 +31,11 @@ export interface RelationConfig {
     joinTable?: string;
 }
 
+export interface TimestampsConfig {
+    createdAt?: string;
+    updatedAt?: string;
+}
+
 // Interface for model configuration
 export interface ModelConfig {
     tableName: string;
@@ -39,8 +44,10 @@ export interface ModelConfig {
     columns: Record<string, ColumnConfig>;
     relations?: RelationConfig[];
     scopes?: Record<string, (qb: QueryBuilder<any>, ...args: any[]) => QueryBuilder<any>>; // Custom query scopes
+    timestamps?: TimestampsConfig; // Auto-managed timestamp columns
 }
 
+
 /**
  * Metadata storage for models.
  * Stores and retrieves model configuration such as columns, relations, scopes, etc.
@@ -145,6 +152,10 @@ export class MetadataStorage {
     static getScopes(model: Function): Record<string, (qb: QueryBuilder<any>, ...args: any[]) => QueryBuilder<any>> {
         return this.getModelMetadata(model)?.scopes || {};
     }
+
+    static getTimestamps(model: Function): TimestampsConfig {
+        return this.getModelMetadata(model)?.timestamps || {};
+    }
 }
 
 /**
@@ -171,6 +182,7 @@ export function defineModel(config: ModelConfig) {
         columns: config.columns,
         relations: config.relations || [],
         scopes: config.scopes || {},
+        timestamps: config.timestamps || {},
     });
 
     return Model;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stabilize-orm",
-  "version": "1.3.2",
+  "version": "1.3.3",
   "description": "A lightweight, type-safe ORM for Bun.js with support for SQLite, MySQL, PostgreSQL, and Redis caching",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/repository.ts

@@ -6,7 +6,7 @@
 
 import { Cache } from "./cache";
 import { DBClient } from "./client";
-import { ConsoleLogger, type Logger } from "./logger";
+import { StabilizeLogger, type Logger } from "./logger";
 import { QueryBuilder } from "./query-builder";
 import {
   DataTypes,
@@ -58,7 +58,7 @@ export class Repository<T> {
     client: DBClient,
     model: new (...args: any[]) => T,
     cacheConfig: CacheConfig = { enabled: false, ttl: 60 },
-    logger: Logger = new ConsoleLogger(),
+    logger: Logger = new StabilizeLogger(),
   ) {
     this.client = client;
     this.cache = cacheConfig.enabled ? new Cache(cacheConfig, logger) : null;
@@ -148,16 +148,16 @@ export class Repository<T> {
     return qb;
   }
 
-    /**
-   * Applies a custom scope to the query for the repository's table.
-   * @param name The name of the scope to apply.
-   * @param args Optional arguments to pass to the scope function.
-   * @returns A `QueryBuilder` instance with the scope applied.
-   * @example
-   * ```
-   * const activeUsers = await userRepository.scope('active').execute(client);
-   * ```
-   */
+  /**
+ * Applies a custom scope to the query for the repository's table.
+ * @param name The name of the scope to apply.
+ * @param args Optional arguments to pass to the scope function.
+ * @returns A `QueryBuilder` instance with the scope applied.
+ * @example
+ * ```
+ * const activeUsers = await userRepository.scope('active').execute(client);
+ * ```
+ */
   scope(name: string, ...args: any[]): QueryBuilder<T> {
     this.logger.logDebug(`Applying scope ${name} to ${this.table}`);
     return this.find().scope(name, ...args);
@@ -357,10 +357,19 @@ export class Repository<T> {
     );
     this.validate(entity);
 
-    const keys = Object.keys(entity).filter((k) => this.columns[k]);
+    const timestamps = MetadataStorage.getTimestamps((this as any).model || Object);
+    const entityWithTimestamps = { ...entity } as Record<string, any>;
+    if (timestamps.createdAt && !entityWithTimestamps[timestamps.createdAt]) {
+      entityWithTimestamps[timestamps.createdAt] = new Date();
+    }
+    if (timestamps.updatedAt && !entityWithTimestamps[timestamps.updatedAt]) {
+      entityWithTimestamps[timestamps.updatedAt] = new Date();
+    }
+
+    const keys = Object.keys(entityWithTimestamps).filter((k) => this.columns[k]);
     const columnNames = keys.map((k) => this.columns[k]?.name).join(", ");
     const placeholders = keys.map(() => "?").join(", ");
-    const params = keys.map((k) => (entity as any)[k]);
+    const params = keys.map((k) => (entityWithTimestamps as any)[k]);
     let query = `INSERT INTO ${this.table} (${columnNames}) VALUES (${placeholders})`;
 
     let insertedResult: T[] | undefined;
@@ -398,7 +407,6 @@ export class Repository<T> {
     );
     return result;
   }
-
   /**
    * Creates multiple records in the database in batches.
    * @param entities An array of entities to create.
@@ -459,11 +467,18 @@ export class Repository<T> {
     const batchSize = options.batchSize || 1000;
     entities.forEach((entity) => this.validate(entity));
 
+    const timestamps = MetadataStorage.getTimestamps((this as any).model || Object);
+    const entitiesWithTimestamps = entities.map(entity => ({
+      ...entity,
+      ...(timestamps.createdAt && !(entity as Record<string, any>)[timestamps.createdAt] ? { [timestamps.createdAt]: new Date() } : {}),
+      ...(timestamps.updatedAt && !(entity as Record<string, any>)[timestamps.updatedAt] ? { [timestamps.updatedAt]: new Date() } : {}),
+    })) as Partial<T>[];
+
     const dbType = this.getDBType(client);
     const results: T[] = [];
 
-    for (let i = 0; i < entities.length; i += batchSize) {
-      const batch = entities.slice(i, i + batchSize);
+    for (let i = 0; i < entitiesWithTimestamps.length; i += batchSize) {
+      const batch = entitiesWithTimestamps.slice(i, i + batchSize);
       const keys = Object.keys(batch[0]!).filter((k) => this.columns[k]);
       const columnNames = keys.map((k) => this.columns[k]?.name).join(", ");
 
@@ -498,7 +513,6 @@ export class Repository<T> {
           finalResults = await queryBuilder.execute(client);
         }
         results.push(...finalResults);
-
       } else {
         const placeholders = `(${keys.map(() => "?").join(", ")})`;
         query = `INSERT INTO ${this.table} (${columnNames}) VALUES ${batch.map(() => placeholders).join(", ")}`;
@@ -582,7 +596,13 @@ export class Repository<T> {
     this.logger.logDebug(`Updating ${this.table} with ID ${id}`);
     this.validate(entity);
 
-    const keys = Object.keys(entity).filter((k) => this.columns[k]);
+    const timestamps = MetadataStorage.getTimestamps((this as any).model || Object);
+    const entityWithTimestamps = { ...entity } as Record<string, any>;;
+    if (timestamps.updatedAt && !entityWithTimestamps[timestamps.updatedAt]) {
+      entityWithTimestamps[timestamps.updatedAt] = new Date();
+    }
+
+    const keys = Object.keys(entityWithTimestamps).filter((k) => this.columns[k]);
     const setClause = keys.map((k) => `${this.columns[k]?.name} = ?`).join(", ");
     const query = `UPDATE ${this.table} SET ${setClause} WHERE id = ?${this.softDeleteField ? ` AND ${this.softDeleteField} IS NULL` : ""}`;
     const params = [...keys.map((k) => (entity as any)[k]), id];
@@ -645,6 +665,8 @@ export class Repository<T> {
     const batchSize = options.batchSize || 1000;
     updates.forEach((update) => this.validate(update.set));
 
+    const timestamps = MetadataStorage.getTimestamps((this as any).model || Object);
+
     for (let i = 0; i < updates.length; i += batchSize) {
       const batch = updates.slice(i, i + batchSize);
       for (const update of batch) {
@@ -662,11 +684,16 @@ export class Repository<T> {
           await this.runHooks(instance, "beforeUpdate");
           await this.runHooks(instance, "beforeSave");
 
-          const keys = Object.keys(update.set).filter((k) => this.columns[k]);
+          const updateWithTimestamps = {
+            ...update.set,
+            ...(timestamps.updatedAt && !(update.set as Record<string, any>)[timestamps.updatedAt] ? { [timestamps.updatedAt]: new Date() } : {}),
+          } as Partial<T>;
+
+          const keys = Object.keys(updateWithTimestamps).filter((k) => this.columns[k]);
           const setClause = keys.map((k) => `${this.columns[k]?.name} = ?`).join(", ");
           const query = `UPDATE ${this.table} SET ${setClause} WHERE id = ?${this.softDeleteField ? ` AND ${this.softDeleteField} IS NULL` : ""}`;
           const params = [
-            ...keys.map((k) => (update.set as any)[k]),
+            ...keys.map((k) => (updateWithTimestamps as any)[k]),
             id,
           ];
           await client.query(query, params);