typeorm-query-scopes 0.1.0-beta.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,487 @@
+# TypeORM Scopes
+
+[![npm version](https://img.shields.io/npm/v/typeorm-query-scopes.svg)](https://www.npmjs.com/package/typeorm-query-scopes)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)
+[![TypeORM](https://img.shields.io/badge/TypeORM-0.3+-orange.svg)](https://typeorm.io/)
+
+> ⚠️ **Beta Release**: This is version 0.1.0-beta.1. The API is stable but may change based on community feedback. Please report any issues on GitHub.
+
+Sequelize-like scopes for TypeORM entities. Define reusable query filters using decorators and apply them easily to your queries.
+
+## Features
+
+- 🎯 **Reusable Queries** - Define once, use everywhere
+- 🔒 **Type Safe** - Full TypeScript support with autocomplete
+- 🎨 **Clean Code** - Decorator-based, declarative syntax
+- ⚡ **Zero Overhead** - No performance penalty
+- 🔄 **Composable** - Combine multiple scopes intelligently
+- 📦 **Easy Migration** - Familiar API for Sequelize users
+- ✨ **Type-Safe Scope Names** - IDE autocomplete and compile-time validation
+
+## Installation
+
+```bash
+npm install typeorm-query-scopes@beta
+# or
+yarn add typeorm-query-scopes@beta
+# or
+pnpm add typeorm-query-scopes@beta
+```
+
+Make sure you have TypeORM installed as a peer dependency:
+
+```bash
+npm install typeorm reflect-metadata
+```
+
+Enable decorators in your `tsconfig.json`:
+
+```json
+{
+  "compilerOptions": {
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true
+  }
+}
+```
+
+## Features
+
+- 🎯 **Decorator-based scope definitions** - Define scopes directly on your entities
+- 🔄 **Default scopes** - Automatically applied to all queries
+- 🔗 **Scope merging** - Combine multiple scopes intelligently
+- 📦 **Function scopes** - Dynamic scopes with parameters
+- 🎨 **TypeScript support** - Full type safety
+- ⚡ **Easy to use** - Similar API to Sequelize scopes
+
+## Quick Start
+
+👉 **[Quick Start Guide](./QUICK_START.md)** - Get started in 5 minutes!
+
+### 1. Define Scopes on Your Entity
+
+```typescript
+import { Entity, PrimaryGeneratedColumn, Column } from 'typeorm';
+import { Scopes, DefaultScope } from 'typeorm-query-scopes';
+
+@DefaultScope<User>({
+  where: { isActive: true }
+})
+@Scopes<User>({
+  // Simple scope with where condition
+  verified: {
+    where: { isVerified: true }
+  },
+  
+  // Scope with relations
+  withPosts: {
+    relations: { posts: true }
+  },
+  
+  // Scope with ordering
+  newest: {
+    order: { createdAt: 'DESC' }
+  },
+  
+  // Function scope with parameters
+  byRole: (role: string) => ({
+    where: { role }
+  }),
+  
+  // Complex scope
+  premium: {
+    where: { 
+      subscriptionType: 'premium',
+      subscriptionExpiry: MoreThan(new Date())
+    },
+    relations: { subscription: true }
+  }
+})
+@Entity()
+export class User {
+  @PrimaryGeneratedColumn()
+  id: number;
+
+  @Column()
+  email: string;
+
+  @Column()
+  role: string;
+
+  @Column({ default: true })
+  isActive: boolean;
+
+  @Column({ default: false })
+  isVerified: boolean;
+
+  @Column()
+  createdAt: Date;
+}
+```
+
+> 💡 **Type-Safe Scopes**: By adding the second generic parameter with scope names, you get IDE autocomplete and compile-time validation when calling `.scope("scopeName")`!
+
+### 2. Use Scopes in Your Queries
+
+```typescript
+import { getScopedRepository } from 'typeorm-query-scopes';
+import { dataSource } from './data-source';
+import { User } from './entities/User';
+
+// Create a scoped repository
+const userRepo = getScopedRepository(User, dataSource);
+
+// Apply single scope
+const verifiedUsers = await userRepo.scope('verified').find();
+
+// Apply multiple scopes
+const verifiedWithPosts = await userRepo
+  .scope('verified', 'withPosts')
+  .find();
+
+// Apply function scope with parameters
+const admins = await userRepo
+  .scope({ method: ['byRole', 'admin'] })
+  .find();
+
+// Combine scopes and additional options
+const recentAdmins = await userRepo
+  .scope('newest', { method: ['byRole', 'admin'] })
+  .find({ take: 10 });
+
+// Remove default scope
+const allUsers = await userRepo.unscoped().find();
+
+// Apply default scope explicitly with other scopes
+const activeVerified = await userRepo
+  .scope('defaultScope', 'verified')
+  .find();
+```
+
+## API Reference
+
+### Type-Safe Scope Names
+
+For better IDE support and compile-time safety, you can define scope names as types:
+
+```typescript
+@Scopes<User, {
+  active: any;
+  verified: any;
+  byRole: any;
+}>({
+  active: { where: { isActive: true } },
+  verified: { where: { isVerified: true } },
+  byRole: (role: string) => ({ where: { role } })
+})
+@Entity()
+class User { ... }
+
+// Now TypeScript knows the available scope names!
+const repo = getScopedRepository(User, dataSource);
+
+// ✅ TypeScript autocompletes: 'active' | 'verified' | 'byRole'
+repo.scope('active')  // IDE shows autocomplete!
+
+// ❌ TypeScript error: 'invalid' is not a valid scope name
+repo.scope('invalid')  // Compile error!
+```
+
+**Benefits:**
+- IDE autocomplete for scope names
+- Compile-time error checking
+- Better refactoring support
+- Self-documenting code
+
+### Decorators
+
+#### `@Scopes<Entity>(scopes)`
+
+Define named scopes on an entity.
+
+```typescript
+@Scopes<User>({
+  scopeName: { where: { field: value } },
+  dynamicScope: (param) => ({ where: { field: param } })
+})
+```
+
+#### `@DefaultScope<Entity>(scope)`
+
+Define a default scope that's automatically applied to all queries.
+
+```typescript
+@DefaultScope<User>({
+  where: { isActive: true }
+})
+```
+
+### ScopedRepository Methods
+
+#### `scope(...scopeNames)`
+
+Apply one or more scopes to the repository.
+
+```typescript
+// Single scope
+repo.scope('active')
+
+// Multiple scopes
+repo.scope('active', 'verified')
+
+// Function scope with parameters
+repo.scope({ method: ['byRole', 'admin'] })
+
+// Include default scope explicitly
+repo.scope('defaultScope', 'verified')
+```
+
+#### `unscoped()`
+
+Remove all scopes including the default scope.
+
+```typescript
+repo.unscoped().find()
+```
+
+#### `find(options?)`
+
+Find entities with applied scopes.
+
+```typescript
+await repo.scope('active').find({ take: 10 })
+```
+
+#### `findOne(options)`
+
+Find one entity with applied scopes.
+
+```typescript
+await repo.scope('active').findOne({ where: { id: 1 } })
+```
+
+#### `findOneBy(where)`
+
+Find one entity by conditions with applied scopes.
+
+```typescript
+await repo.scope('active').findOneBy({ email: 'user@example.com' })
+```
+
+#### `count(options?)`
+
+Count entities with applied scopes.
+
+```typescript
+await repo.scope('active').count()
+```
+
+#### `findAndCount(options?)`
+
+Find and count entities with applied scopes.
+
+```typescript
+const [users, total] = await repo.scope('active').findAndCount({ take: 10 })
+```
+
+## Scope Options
+
+Scopes support the following TypeORM find options:
+
+- `where` - Filter conditions (merged with AND logic)
+- `relations` - Relations to load
+- `order` - Sorting options
+- `select` - Fields to select
+- `skip` - Number of records to skip
+- `take` - Number of records to take
+- `cache` - Query caching options
+
+## Scope Merging
+
+When multiple scopes are applied, they are merged intelligently:
+
+- **where**: Merged using AND logic
+- **relations**: Combined (all relations loaded)
+- **order**: Later scopes override earlier ones
+- **select**: Combined (union of all fields)
+- **skip/take/cache**: Last scope wins
+
+```typescript
+@Scopes<User>({
+  scope1: {
+    where: { isActive: true },
+    order: { createdAt: 'DESC' },
+    take: 10
+  },
+  scope2: {
+    where: { isVerified: true },
+    take: 20
+  }
+})
+
+// Applying both scopes results in:
+// where: { isActive: true, isVerified: true }
+// order: { createdAt: 'DESC' }
+// take: 20 (scope2 overrides scope1)
+```
+
+## Advanced Examples
+
+### Scope with Complex Conditions
+
+```typescript
+import { MoreThan, LessThan, In } from 'typeorm';
+
+@Scopes<Product>({
+  inStock: {
+    where: { quantity: MoreThan(0) }
+  },
+  
+  inPriceRange: (min: number, max: number) => ({
+    where: {
+      price: MoreThan(min),
+      price: LessThan(max)
+    }
+  }),
+  
+  byCategories: (categories: string[]) => ({
+    where: { category: In(categories) }
+  })
+})
+```
+
+### Scope with Nested Relations
+
+```typescript
+@Scopes<Post>({
+  withAuthorAndComments: {
+    relations: {
+      author: true,
+      comments: {
+        user: true
+      }
+    }
+  },
+  
+  published: {
+    where: { 
+      status: 'published',
+      publishedAt: LessThan(new Date())
+    }
+  }
+})
+```
+
+### Reusable Scope Repository
+
+```typescript
+// Create a service with scoped repository
+export class UserService {
+  private userRepo: ScopedRepository<User>;
+
+  constructor(private dataSource: DataSource) {
+    this.userRepo = getScopedRepository(User, dataSource);
+  }
+
+  async getActiveUsers() {
+    return this.userRepo.scope('active').find();
+  }
+
+  async getAdmins() {
+    return this.userRepo
+      .scope({ method: ['byRole', 'admin'] })
+      .find();
+  }
+
+  async getAllUsersIncludingInactive() {
+    return this.userRepo.unscoped().find();
+  }
+}
+```
+
+## Comparison with Sequelize
+
+This package brings Sequelize-style scopes to TypeORM:
+
+| Feature | Sequelize | TypeORM Scopes |
+|---------|-----------|----------------|
+| Default scope | ✅ | ✅ |
+| Named scopes | ✅ | ✅ |
+| Function scopes | ✅ | ✅ |
+| Scope merging | ✅ | ✅ |
+| Unscoped queries | ✅ | ✅ |
+| Decorator-based | ❌ | ✅ |
+
+## Documentation
+
+- [Type-Safe Scopes Guide](./TYPE_SAFE_SCOPES.md) - Complete guide to type-safe scope names
+- [Migration from Sequelize](./MIGRATION_FROM_SEQUELIZE.md) - Guide for migrating from Sequelize scopes
+- [Basic Usage Example](./examples/basic-usage.ts) - Simple examples to get started
+- [Advanced Usage Example](./examples/advanced-usage.ts) - Complex scope patterns
+- [Type-Safe Scopes Example](./examples/type-safe-scopes.ts) - Type-safe scope demonstration
+- [Real-world Example](./examples/real-world-example.ts) - Complete blog application example
+- [Contributing Guide](./CONTRIBUTING.md) - How to contribute to the project
+- [Changelog](./CHANGELOG.md) - Version history and changes
+
+## Roadmap
+
+Future enhancements being considered:
+
+- [ ] Support for `update()` and `delete()` operations with scopes
+- [ ] Scope inheritance for entity inheritance
+- [ ] Query builder integration
+- [ ] Performance optimizations
+- [ ] Additional scope merging strategies
+- [ ] Scope validation and debugging tools
+
+## FAQ
+
+### Q: Can I use this with NestJS?
+
+Yes! TypeORM Scopes works perfectly with NestJS. Just inject the DataSource and create scoped repositories:
+
+```typescript
+@Injectable()
+export class UserService {
+  private userRepo: ScopedRepository<User>;
+
+  constructor(private dataSource: DataSource) {
+    this.userRepo = getScopedRepository(User, dataSource);
+  }
+
+  async getActiveUsers() {
+    return this.userRepo.scope('active').find();
+  }
+}
+```
+
+### Q: Does this work with MongoDB?
+
+Yes, TypeORM Scopes works with any database supported by TypeORM, including MongoDB.
+
+### Q: Can I combine scopes with QueryBuilder?
+
+Currently, scopes work with the repository pattern. QueryBuilder integration is planned for a future release.
+
+### Q: How does performance compare to regular TypeORM queries?
+
+Scopes add minimal overhead - they simply merge options before executing the query. The actual database query performance is identical to regular TypeORM queries.
+
+## License
+
+MIT - see [LICENSE](./LICENSE) file for details
+
+## Contributing
+
+Contributions are welcome! Please read our [Contributing Guide](./CONTRIBUTING.md) for details on our code of conduct and the process for submitting pull requests.
+
+## Support
+
+- 📖 [Documentation](./README.md)
+- 🐛 [Issue Tracker](https://github.com/yourusername/typeorm-query-scopes/issues)
+- 💬 [Discussions](https://github.com/yourusername/typeorm-query-scopes/discussions)
+
+## Acknowledgments
+
+Inspired by [Sequelize scopes](https://sequelize.org/docs/v7/other-topics/scopes/) - bringing the same powerful pattern to TypeORM.

package/dist/decorators.d.ts

@@ -0,0 +1,28 @@
+import { ScopeDefinition, ScopeOptions } from './types';
+/**
+ * Decorator to define scopes on an entity with type-safe scope names
+ * @example
+ * // Without type-safe names:
+ * @Scopes<User>({
+ *   active: { where: { isActive: true } }
+ * })
+ *
+ * // With type-safe names:
+ * @Scopes<User, { active: any; verified: any }>({
+ *   active: { where: { isActive: true } },
+ *   verified: { where: { isVerified: true } }
+ * })
+ * @Entity()
+ * class User { ... }
+ */
+export declare function Scopes<T, S extends Record<string, ScopeDefinition<T>> = Record<string, ScopeDefinition<T>>>(scopes: S): <C extends new (...args: any[]) => T>(target: C) => C & {
+    __scopeNames?: keyof S;
+};
+/**
+ * Decorator to define a default scope on an entity
+ * @example
+ * @DefaultScope<User>({ where: { isActive: true } })
+ * @Entity()
+ * class User { ... }
+ */
+export declare function DefaultScope<T>(scope: ScopeOptions<T>): (target: Function) => void;

package/dist/decorators.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Scopes = Scopes;
+exports.DefaultScope = DefaultScope;
+const metadata_1 = require("./metadata");
+/**
+ * Decorator to define scopes on an entity with type-safe scope names
+ * @example
+ * // Without type-safe names:
+ * @Scopes<User>({
+ *   active: { where: { isActive: true } }
+ * })
+ *
+ * // With type-safe names:
+ * @Scopes<User, { active: any; verified: any }>({
+ *   active: { where: { isActive: true } },
+ *   verified: { where: { isVerified: true } }
+ * })
+ * @Entity()
+ * class User { ... }
+ */
+function Scopes(scopes) {
+    return function (target) {
+        Object.entries(scopes).forEach(([name, scope]) => {
+            metadata_1.ScopeMetadataStorage.addScope(target, name, scope);
+        });
+        return target;
+    };
+}
+/**
+ * Decorator to define a default scope on an entity
+ * @example
+ * @DefaultScope<User>({ where: { isActive: true } })
+ * @Entity()
+ * class User { ... }
+ */
+function DefaultScope(scope) {
+    return function (target) {
+        metadata_1.ScopeMetadataStorage.setDefaultScope(target, scope);
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+export { Scopes, DefaultScope } from './decorators';
+export { ScopedRepository } from './scoped-repository';
+export { ScopeMetadataStorage } from './metadata';
+export { ScopeMerger } from './scope-merger';
+export type { ScopeOptions, ScopeFunction, ScopeDefinition, ScopeMetadata, ScopeName, ExtractScopeNames } from './types';
+import { DataSource, ObjectLiteral } from 'typeorm';
+import { ScopedRepository } from './scoped-repository';
+/**
+ * Create a scoped repository for an entity
+ * @example
+ * const userRepo = getScopedRepository(User, dataSource);
+ * const activeUsers = await userRepo.scope('active').find();
+ */
+export declare function getScopedRepository<Entity extends ObjectLiteral, EntityClass extends new (...args: any[]) => Entity = any>(entity: EntityClass, dataSource: DataSource): ScopedRepository<Entity, EntityClass>;

package/dist/index.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ScopeMerger = exports.ScopeMetadataStorage = exports.ScopedRepository = exports.DefaultScope = exports.Scopes = void 0;
+exports.getScopedRepository = getScopedRepository;
+var decorators_1 = require("./decorators");
+Object.defineProperty(exports, "Scopes", { enumerable: true, get: function () { return decorators_1.Scopes; } });
+Object.defineProperty(exports, "DefaultScope", { enumerable: true, get: function () { return decorators_1.DefaultScope; } });
+var scoped_repository_1 = require("./scoped-repository");
+Object.defineProperty(exports, "ScopedRepository", { enumerable: true, get: function () { return scoped_repository_1.ScopedRepository; } });
+var metadata_1 = require("./metadata");
+Object.defineProperty(exports, "ScopeMetadataStorage", { enumerable: true, get: function () { return metadata_1.ScopeMetadataStorage; } });
+var scope_merger_1 = require("./scope-merger");
+Object.defineProperty(exports, "ScopeMerger", { enumerable: true, get: function () { return scope_merger_1.ScopeMerger; } });
+const scoped_repository_2 = require("./scoped-repository");
+/**
+ * Create a scoped repository for an entity
+ * @example
+ * const userRepo = getScopedRepository(User, dataSource);
+ * const activeUsers = await userRepo.scope('active').find();
+ */
+function getScopedRepository(entity, dataSource) {
+    return new scoped_repository_2.ScopedRepository(entity, dataSource);
+}

package/dist/metadata.d.ts

@@ -0,0 +1,7 @@
+import { ScopeMetadata } from './types';
+export declare class ScopeMetadataStorage {
+    private static storage;
+    static getMetadata<T>(target: Function): ScopeMetadata<T>;
+    static setDefaultScope<T>(target: Function, scope: any): void;
+    static addScope<T>(target: Function, name: string, scope: any): void;
+}

package/dist/metadata.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ScopeMetadataStorage = void 0;
+const SCOPE_METADATA_KEY = Symbol('typeorm:scopes');
+class ScopeMetadataStorage {
+    static getMetadata(target) {
+        if (!this.storage.has(target)) {
+            this.storage.set(target, {
+                scopes: new Map(),
+            });
+        }
+        return this.storage.get(target);
+    }
+    static setDefaultScope(target, scope) {
+        const metadata = this.getMetadata(target);
+        metadata.defaultScope = scope;
+    }
+    static addScope(target, name, scope) {
+        const metadata = this.getMetadata(target);
+        metadata.scopes.set(name, scope);
+    }
+}
+exports.ScopeMetadataStorage = ScopeMetadataStorage;
+ScopeMetadataStorage.storage = new Map();

package/dist/scope-merger.d.ts

@@ -0,0 +1,8 @@
+import { ScopeOptions } from './types';
+export declare class ScopeMerger {
+    /**
+     * Merges multiple scope options into a single options object
+     * Similar to Sequelize's scope merging behavior
+     */
+    static merge<T>(...scopes: ScopeOptions<T>[]): ScopeOptions<T>;
+}

package/dist/scope-merger.js

@@ -0,0 +1,68 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ScopeMerger = void 0;
+class ScopeMerger {
+    /**
+     * Merges multiple scope options into a single options object
+     * Similar to Sequelize's scope merging behavior
+     */
+    static merge(...scopes) {
+        const result = {};
+        for (const scope of scopes) {
+            // Merge where conditions using AND logic
+            if (scope.where) {
+                if (!result.where) {
+                    result.where = Array.isArray(scope.where) ? [...scope.where] : { ...scope.where };
+                }
+                else {
+                    // Merge where conditions
+                    if (Array.isArray(result.where) && Array.isArray(scope.where)) {
+                        result.where = [...result.where, ...scope.where];
+                    }
+                    else if (Array.isArray(result.where)) {
+                        result.where = [...result.where, scope.where];
+                    }
+                    else if (Array.isArray(scope.where)) {
+                        result.where = [result.where, ...scope.where];
+                    }
+                    else {
+                        result.where = { ...result.where, ...scope.where };
+                    }
+                }
+            }
+            // Merge relations
+            if (scope.relations) {
+                result.relations = {
+                    ...(result.relations || {}),
+                    ...scope.relations,
+                };
+            }
+            // Merge order (later scopes override)
+            if (scope.order) {
+                result.order = {
+                    ...(result.order || {}),
+                    ...scope.order,
+                };
+            }
+            // Merge select (combine unique fields)
+            if (scope.select) {
+                if (!result.select) {
+                    result.select = [...scope.select];
+                }
+                else {
+                    const combined = new Set([...result.select, ...scope.select]);
+                    result.select = Array.from(combined);
+                }
+            }
+            // Override scalar values (last scope wins)
+            if (scope.skip !== undefined)
+                result.skip = scope.skip;
+            if (scope.take !== undefined)
+                result.take = scope.take;
+            if (scope.cache !== undefined)
+                result.cache = scope.cache;
+        }
+        return result;
+    }
+}
+exports.ScopeMerger = ScopeMerger;

package/dist/scoped-repository.d.ts

@@ -0,0 +1,54 @@
+import { FindManyOptions, FindOneOptions, ObjectLiteral, EntityTarget, DataSource } from 'typeorm';
+type ExtractScopeNames<T> = T extends {
+    __scopeNames?: infer S;
+} ? S : string;
+export declare class ScopedRepository<Entity extends ObjectLiteral, EntityClass = any> {
+    private target;
+    private dataSource;
+    private appliedScopes;
+    private includeDefaultScope;
+    constructor(target: EntityTarget<Entity>, dataSource: DataSource);
+    private get repository();
+    /**
+     * Apply one or more scopes to the repository
+     * @example
+     * userRepo.scope('active', 'withPosts').find()
+     * userRepo.scope({ method: ['byRole', 'admin'] }).find()
+     */
+    scope(...scopeNames: (ExtractScopeNames<EntityClass> | {
+        method: [ExtractScopeNames<EntityClass>, ...any[]];
+    } | null)[]): ScopedRepository<Entity, EntityClass>;
+    /**
+     * Remove the default scope
+     * @example
+     * userRepo.unscoped().find()
+     */
+    unscoped(): ScopedRepository<Entity, EntityClass>;
+    /**
+     * Get merged find options with all applied scopes
+     */
+    private getMergedOptions;
+    /**
+     * Find entities with applied scopes
+     */
+    find(options?: FindManyOptions<Entity>): Promise<Entity[]>;
+    /**
+     * Find one entity with applied scopes
+     */
+    findOne(options: FindOneOptions<Entity>): Promise<Entity | null>;
+    /**
+     * Find one entity by ID with applied scopes
+     */
+    findOneBy(where: any): Promise<Entity | null>;
+    /**
+     * Count entities with applied scopes
+     */
+    count(options?: FindManyOptions<Entity>): Promise<number>;
+    /**
+     * Find and count entities with applied scopes
+     */
+    findAndCount(options?: FindManyOptions<Entity>): Promise<[Entity[], number]>;
+    private clone;
+    private getEntityConstructor;
+}
+export {};

package/dist/scoped-repository.js

@@ -0,0 +1,129 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ScopedRepository = void 0;
+const metadata_1 = require("./metadata");
+const scope_merger_1 = require("./scope-merger");
+class ScopedRepository {
+    constructor(target, dataSource) {
+        this.target = target;
+        this.dataSource = dataSource;
+        this.appliedScopes = [];
+        this.includeDefaultScope = true;
+    }
+    get repository() {
+        return this.dataSource.getRepository(this.target);
+    }
+    /**
+     * Apply one or more scopes to the repository
+     * @example
+     * userRepo.scope('active', 'withPosts').find()
+     * userRepo.scope({ method: ['byRole', 'admin'] }).find()
+     */
+    scope(...scopeNames) {
+        const cloned = this.clone();
+        const metadata = metadata_1.ScopeMetadataStorage.getMetadata(this.getEntityConstructor());
+        for (const scopeName of scopeNames) {
+            if (scopeName === null || scopeName === 'defaultScope') {
+                cloned.includeDefaultScope = true;
+                continue;
+            }
+            if (typeof scopeName === 'string') {
+                const scopeDef = metadata.scopes.get(scopeName);
+                if (!scopeDef) {
+                    throw new Error(`Scope "${scopeName}" not found on entity`);
+                }
+                const scopeOptions = typeof scopeDef === 'function' ? scopeDef() : scopeDef;
+                cloned.appliedScopes.push(scopeOptions);
+            }
+            else if (typeof scopeName === 'object' && 'method' in scopeName && scopeName.method) {
+                const [name, ...args] = scopeName.method;
+                const scopeDef = metadata.scopes.get(name);
+                if (!scopeDef) {
+                    throw new Error(`Scope "${String(name)}" not found on entity`);
+                }
+                if (typeof scopeDef !== 'function') {
+                    throw new Error(`Scope "${String(name)}" is not a function`);
+                }
+                const scopeOptions = scopeDef(...args);
+                cloned.appliedScopes.push(scopeOptions);
+            }
+        }
+        return cloned;
+    }
+    /**
+     * Remove the default scope
+     * @example
+     * userRepo.unscoped().find()
+     */
+    unscoped() {
+        const cloned = this.clone();
+        cloned.includeDefaultScope = false;
+        cloned.appliedScopes = [];
+        return cloned;
+    }
+    /**
+     * Get merged find options with all applied scopes
+     */
+    getMergedOptions(options = {}) {
+        const scopesToApply = [];
+        // Add default scope if enabled
+        if (this.includeDefaultScope) {
+            const metadata = metadata_1.ScopeMetadataStorage.getMetadata(this.getEntityConstructor());
+            if (metadata.defaultScope) {
+                scopesToApply.push(metadata.defaultScope);
+            }
+        }
+        // Add applied scopes
+        scopesToApply.push(...this.appliedScopes);
+        // Add user-provided options
+        scopesToApply.push(options);
+        return scope_merger_1.ScopeMerger.merge(...scopesToApply);
+    }
+    /**
+     * Find entities with applied scopes
+     */
+    async find(options) {
+        const mergedOptions = this.getMergedOptions(options);
+        return this.repository.find(mergedOptions);
+    }
+    /**
+     * Find one entity with applied scopes
+     */
+    async findOne(options) {
+        const mergedOptions = this.getMergedOptions(options);
+        return this.repository.findOne(mergedOptions);
+    }
+    /**
+     * Find one entity by ID with applied scopes
+     */
+    async findOneBy(where) {
+        return this.findOne({ where });
+    }
+    /**
+     * Count entities with applied scopes
+     */
+    async count(options) {
+        const mergedOptions = this.getMergedOptions(options);
+        return this.repository.count(mergedOptions);
+    }
+    /**
+     * Find and count entities with applied scopes
+     */
+    async findAndCount(options) {
+        const mergedOptions = this.getMergedOptions(options);
+        return this.repository.findAndCount(mergedOptions);
+    }
+    clone() {
+        const cloned = new ScopedRepository(this.target, this.dataSource);
+        cloned.appliedScopes = [...this.appliedScopes];
+        cloned.includeDefaultScope = this.includeDefaultScope;
+        return cloned;
+    }
+    getEntityConstructor() {
+        if (typeof this.target === 'function') {
+            return this.target;
+        }
+        throw new Error('Entity target must be a constructor function');
+    }
+}
+exports.ScopedRepository = ScopedRepository;

package/dist/types.d.ts

@@ -0,0 +1,20 @@
+import { FindOptionsWhere, FindOptionsOrder, FindOptionsRelations } from 'typeorm';
+export type ScopeOptions<T> = {
+    where?: FindOptionsWhere<T> | FindOptionsWhere<T>[];
+    relations?: FindOptionsRelations<T>;
+    order?: FindOptionsOrder<T>;
+    skip?: number;
+    take?: number;
+    select?: (keyof T)[];
+    cache?: boolean | number;
+};
+export type ScopeFunction<T> = (...args: any[]) => ScopeOptions<T>;
+export type ScopeDefinition<T> = ScopeOptions<T> | ScopeFunction<T>;
+export interface ScopeMetadata<T = any> {
+    defaultScope?: ScopeOptions<T>;
+    scopes: Map<string, ScopeDefinition<T>>;
+}
+export type ScopeName<T> = T extends {
+    __scopeNames?: infer S;
+} ? S : string;
+export type ExtractScopeNames<T> = T extends Record<infer K, any> ? K : never;

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "typeorm-query-scopes",
+  "version": "0.1.0-beta.1",
+  "description": "Sequelize-like scopes for TypeORM entities - Define reusable query filters with decorators",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "test": "npx ts-node test/integration.test.ts",
+    "demo": "npx ts-node examples/demo.ts",
+    "docs:dev": "vitepress dev docs",
+    "docs:build": "vitepress build docs",
+    "docs:preview": "vitepress preview docs",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "typeorm",
+    "scopes",
+    "orm",
+    "database",
+    "query",
+    "decorator",
+    "typescript",
+    "sequelize",
+    "repository",
+    "filter",
+    "reusable-queries",
+    "type-safe"
+  ],
+  "author": "aramyounis",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aramyounis/typeorm-query-scopes.git"
+  },
+  "bugs": {
+    "url": "https://github.com/aramyounis/typeorm-query-scopes/issues"
+  },
+  "homepage": "https://github.com/aramyounis/typeorm-query-scopes#readme",
+  "peerDependencies": {
+    "typeorm": "^0.3.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "better-sqlite3": "^12.6.2",
+    "sqlite3": "^5.1.7",
+    "typeorm": "^0.3.0",
+    "typescript": "^5.0.0",
+    "vitepress": "^1.6.4",
+    "vue": "^3.5.29"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md",
+    "TYPE_SAFE_SCOPES.md",
+    "MIGRATION_FROM_SEQUELIZE.md"
+  ],
+  "engines": {
+    "node": ">=16.0.0"
+  }
+}