stabilize-orm 1.3.0 → 1.3.2

package/README.md

@@ -25,6 +25,7 @@ _A Modern, Type-Safe, and Expressive ORM for Bun_
 - **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.
+- **Custom Query Scopes**: Define reusable query conditions (scopes) in models for simplified, reusable filtering logic.
 
 ---
 
@@ -358,11 +359,55 @@ console.log(activeAdmins);
   orderBy(clause: string): QueryBuilder<User>;
   limit(limit: number): QueryBuilder<User>;
   offset(offset: number): QueryBuilder<User>;
+  scope(name: string, ...args: any[]): QueryBuilder<User>;
   build(): { query: string; params: any[] };
   execute(client?: DBClient, cache?: Cache, cacheKey?: string): Promise<User[]>;
 }
 ```
 
+### Custom Query Scopes
+
+Define reusable query conditions (scopes) in your model configuration to simplify and reuse common filtering logic. Scopes are applied via the `scope` method on `Repository` or `QueryBuilder`, allowing you to chain them with other query operations.
+
+#### **Scopes 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 },
+    isActive: { type: DataTypes.Boolean, required: true },
+    createdAt: { type: DataTypes.DateTime },
+  },
+  scopes: {
+    active: (qb) => qb.where("isActive = ?", true),
+    recent: (qb, days: number) => qb.where("createdAt >= ?", new Date(Date.now() - days * 24 * 60 * 60 * 1000)),
+  },
+});
+
+const userRepository = orm.getRepository(User);
+
+// Fetch active users
+const activeUsers = await userRepository.scope("active").execute();
+
+// Fetch users created in the last 7 days
+const recentUsers = await userRepository.scope("recent", 7).execute();
+
+// Combine scopes with other query operations
+const recentActiveUsers = await userRepository
+  .scope("active")
+  .scope("recent", 7)
+  .orderBy("createdAt DESC")
+  .limit(10)
+  .execute();
+
+console.log(recentActiveUsers);
+```
+
 ---
 
 ## 🗑️ Soft Deletes
@@ -452,6 +497,6 @@ Licensed under the MIT License. See [LICENSE.md](./LICENSE.md) for details.
 
 Created with ❤️ by **ElectronSz**
 <br/>
-<em>File last updated: 2025-10-18 22:10:00 SAST</em>
+<em>File last updated: 2025-10-19 10:24:00 SAST</em>
 
 </div>

package/model.ts

@@ -1,10 +1,10 @@
-
 /**
  * @file model.ts
  * @description Provides a programmatic API for defining models and a metadata storage system.
  * @author ElectronSz
  */
 
+import type { QueryBuilder } from './query-builder';
 import { DataTypes, RelationType, DBType } from './types';
 
 // Interface for column configuration
@@ -38,28 +38,57 @@ export interface ModelConfig {
     softDelete?: boolean;
     columns: Record<string, ColumnConfig>;
     relations?: RelationConfig[];
+    scopes?: Record<string, (qb: QueryBuilder<any>, ...args: any[]) => QueryBuilder<any>>; // Custom query scopes
 }
 
-// Metadata storage for models
+/**
+ * Metadata storage for models.
+ * Stores and retrieves model configuration such as columns, relations, scopes, etc.
+ */
 export class MetadataStorage {
     private static models: Map<Function, ModelConfig> = new Map();
 
+    /**
+     * Associates model metadata with a class constructor.
+     * @param model - The class constructor for the model.
+     * @param config - The model configuration object.
+     */
     static setModelMetadata(model: Function, config: ModelConfig) {
         this.models.set(model, config);
     }
 
+    /**
+     * Retrieves the model configuration for a given model class.
+     * @param model - The class constructor for the model.
+     * @returns The model configuration or undefined if not found.
+     */
     static getModelMetadata(model: Function): ModelConfig | undefined {
         return this.models.get(model);
     }
 
+    /**
+     * Gets the table name for a given model class.
+     * @param model - The class constructor for the model.
+     * @returns The table name or an empty string if not found.
+     */
     static getTableName(model: Function): string {
         return this.getModelMetadata(model)?.tableName || '';
     }
 
+    /**
+     * Gets the column configuration for a given model class.
+     * @param model - The class constructor for the model.
+     * @returns Record of column names to their configuration.
+     */
     static getColumns(model: Function): Record<string, ColumnConfig> {
         return this.getModelMetadata(model)?.columns || {};
     }
 
+    /**
+     * Collects validation rules for each column of a given model.
+     * @param model - The class constructor for the model.
+     * @returns An object mapping column names to an array of validation rule names.
+     */
     static getValidators(model: Function): Record<string, string[]> {
         const columns = this.getModelMetadata(model)?.columns || {};
         const validators: Record<string, string[]> = {};
@@ -72,6 +101,11 @@ export class MetadataStorage {
         return validators;
     }
 
+    /**
+     * Gets the relationship configuration for a given model class.
+     * @param model - The class constructor for the model.
+     * @returns Record of property names to their relation configuration.
+     */
     static getRelations(model: Function): Record<string, RelationConfig> {
         const relations = this.getModelMetadata(model)?.relations || [];
         const result: Record<string, RelationConfig> = {};
@@ -81,6 +115,11 @@ export class MetadataStorage {
         return result;
     }
 
+    /**
+     * Finds the soft delete field, if any, for a given model class.
+     * @param model - The class constructor for the model.
+     * @returns The key of the soft delete field, or null if not found.
+     */
     static getSoftDeleteField(model: Function): string | null {
         const columns = this.getModelMetadata(model)?.columns || {};
         for (const [key, col] of Object.entries(columns)) {
@@ -89,14 +128,36 @@ export class MetadataStorage {
         return null;
     }
 
+    /**
+     * Checks if the model is versioned.
+     * @param model - The class constructor for the model.
+     * @returns True if versioned, false otherwise.
+     */
     static isVersioned(model: Function): boolean {
         return !!this.getModelMetadata(model)?.versioned;
     }
+
+    /**
+     * Gets custom query scopes for a given model class.
+     * @param model - The class constructor for the model.
+     * @returns Record of scope names to scope functions.
+     */
+    static getScopes(model: Function): Record<string, (qb: QueryBuilder<any>, ...args: any[]) => QueryBuilder<any>> {
+        return this.getModelMetadata(model)?.scopes || {};
+    }
 }
 
-// Programmatic model definition
+/**
+ * Programmatically defines a model and stores its metadata.
+ * @param config - The model configuration object.
+ * @returns The dynamically created model class.
+ */
 export function defineModel(config: ModelConfig) {
     class Model {
+        /**
+         * Constructs a model instance from plain data.
+         * @param data - The plain object to assign properties from.
+         */
         constructor(data: any) {
             Object.assign(this, data);
         }
@@ -109,7 +170,8 @@ export function defineModel(config: ModelConfig) {
         softDelete: config.softDelete || false,
         columns: config.columns,
         relations: config.relations || [],
+        scopes: config.scopes || {},
     });
 
     return Model;
-}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stabilize-orm",
-  "version": "1.3.0",
+  "version": "1.3.2",
   "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/query-builder.ts

@@ -6,6 +6,8 @@
 
 import { DBClient } from "./client";
 import { Cache } from "./cache";
+import { MetadataStorage } from "./model";
+import { StabilizeError } from "./types";
 
 /**
  * A fluent interface for building SQL SELECT queries.
@@ -125,7 +127,7 @@ export class QueryBuilder<T> {
    */
   build(): { query: string; params: any[] } {
     let query = `SELECT ${this.selectFields.join(", ")} FROM ${this.table}`;
-    
+
     if (this.joins.length > 0) {
       query += " " + this.joins.join(" ");
     }
@@ -166,7 +168,7 @@ export class QueryBuilder<T> {
     cacheKey?: string,
   ): Promise<T[]> {
     const { query, params } = this.build();
-    
+
     // Attempt to retrieve from cache first (cache-aside read)
     if (cache && cacheKey) {
       const cached = await cache.get<T[]>(cacheKey);
@@ -178,9 +180,30 @@ export class QueryBuilder<T> {
 
     // Store the database results in the cache for future requests
     if (cache && cacheKey && results.length > 0) {
-      await cache.set(cacheKey, results, 60); 
+      await cache.set(cacheKey, results, 60);
     }
-    
+
     return results;
   }
+
+  /**
+   * Applies a named scope to the current query builder.
+   *
+   * This method looks up a scope function by name for the current model (based on the table name),
+   * then invokes the scope function with the query builder and any additional arguments.
+   *
+   * @param {string} name - The name of the scope to apply.
+   * @param {...any} args - Additional arguments to pass to the scope function.
+   * @throws {StabilizeError} If no model is found for the current table, or if the specified scope does not exist.
+   * @returns {QueryBuilder<T>} The query builder instance after applying the scope.
+   */
+  scope(name: string, ...args: any[]): QueryBuilder<T> {
+    const model = Object.values(MetadataStorage['models']).find(m => m.tableName === this.table)?.constructor;
+    if (!model) throw new StabilizeError(`Model for table ${this.table} not found`, "SCOPE_ERROR");
+    const scopes = MetadataStorage.getScopes(model);
+    const scopeFn = scopes[name];
+    if (!scopeFn) throw new StabilizeError(`Scope ${name} not found`, "SCOPE_ERROR");
+    return scopeFn(this, ...args);
+  }
+  
 }

package/repository.ts

@@ -148,6 +148,21 @@ 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);
+   * ```
+   */
+  scope(name: string, ...args: any[]): QueryBuilder<T> {
+    this.logger.logDebug(`Applying scope ${name} to ${this.table}`);
+    return this.find().scope(name, ...args);
+  }
+
   /**
    * Finds a single record by its primary key (id).
    * @param id The ID of the record to find.

package/types.ts

@@ -42,6 +42,7 @@ export enum DataTypes {
   JSON,      // Maps to JSON, JSONB, or TEXT
   UUID,      // Maps to UUID or VARCHAR(36)
   BLOB,      // Maps to BYTEA or BLOB
+  
 }
 
 export interface DBConfig {