@plyaz/db 0.4.0 → 0.5.0

package/dist/repository/BaseRepository.d.ts

@@ -7,6 +7,7 @@
  *
  */
 import type { DatabaseResult, PaginatedResult, QueryOptions, Filter, DatabaseServiceInterface, CreateInput, OperationConfig } from "@plyaz/types/db";
+import { QueryBuilder } from "../builder/query/QueryBuilder";
 /**
  * BASE REPOSITORY - Repository Layer Foundation
  *
@@ -86,6 +87,45 @@ export declare abstract class BaseRepository<T extends Record<string, unknown>>
     protected readonly tableName: string;
     protected readonly defaultConfig?: OperationConfig;
     constructor(db: DatabaseServiceInterface, tableName: string, defaultConfig?: OperationConfig);
+    /**
+     * Create a fluent QueryBuilder for this repository
+     *
+     * Returns a type-safe, chainable query builder that can execute queries
+     * directly against this repository.
+     *
+     * @returns QueryBuilder bound to this repository
+     *
+     * @example
+     * ```typescript
+     * // Fluent query with execute
+     * const result = await userRepository.query()
+     *   .where('status', 'eq', 'active')
+     *   .orderByDesc('createdAt')
+     *   .limit(20)
+     *   .execute();
+     *
+     * // Get data directly
+     * const users = await userRepository.query()
+     *   .where('role', 'eq', 'admin')
+     *   .getMany();
+     *
+     * // Get single record
+     * const user = await userRepository.query()
+     *   .where('email', 'eq', 'john@example.com')
+     *   .getOne();
+     *
+     * // Complex queries
+     * const orders = await orderRepository.query()
+     *   .where('status', 'eq', 'pending')
+     *   .andWhere('totalAmount', 'gte', 100)
+     *   .orWhere('priority', 'eq', 'high')
+     *   .whereIn('region', ['US', 'EU'])
+     *   .orderBy('createdAt', 'desc')
+     *   .paginate(1, 25)
+     *   .execute();
+     * ```
+     */
+    query(): QueryBuilder<T>;
     /**
      * Get the table name for this repository
      *
@@ -124,25 +164,35 @@ export declare abstract class BaseRepository<T extends Record<string, unknown>>
     /**
      * Find multiple entities with optional filtering, sorting, and pagination
      *
-     * @param {QueryOptions<T>} [options] - Optional query configuration with type-safe fields
+     * Accepts either QueryOptions object or a QueryBuilder instance.
+     *
+     * @param {QueryOptions<T> | QueryBuilder<T>} [options] - Query configuration or QueryBuilder
      * @param {OperationConfig} [config] - Optional per-operation configuration (adapter selection, schema override, etc.)
      * @returns {Promise<DatabaseResult<PaginatedResult<T>>>} Promise resolving to paginated results
      *
      * @example
      * ```typescript
+     * // Using QueryOptions (traditional)
      * const result = await userRepository.findMany({
      *   filter: { field: 'status', operator: 'eq', value: 'active' },
      *   sort: [{ field: 'createdAt', direction: 'desc' }],
      *   pagination: { limit: 20, offset: 0 }
      * });
      *
+     * // Using QueryBuilder
+     * const query = QueryBuilder.create<User>()
+     *   .where('status', 'eq', 'active')
+     *   .orderByDesc('createdAt')
+     *   .limit(20);
+     * const result = await userRepository.findMany(query);
+     *
      * // Query from analytics database
      * const analyticsResult = await userRepository.findMany({}, {
      *   adapter: 'analytics'
      * });
      * ```
      */
-    findMany(options?: QueryOptions<T>, config?: OperationConfig): Promise<DatabaseResult<PaginatedResult<T>>>;
+    findMany(options?: QueryOptions<T> | QueryBuilder<T>, config?: OperationConfig): Promise<DatabaseResult<PaginatedResult<T>>>;
     /**
      * Create a new entity in the database
      *
@@ -216,7 +266,9 @@ export declare abstract class BaseRepository<T extends Record<string, unknown>>
     /**
      * Count entities matching optional filter criteria
      *
-     * @param {Filter<T>} [filter] - Optional filter conditions with type-safe fields
+     * Accepts either a Filter object or a QueryBuilder instance.
+     *
+     * @param {Filter<T> | QueryBuilder<T>} [filter] - Filter conditions or QueryBuilder
      * @param {OperationConfig} [config] - Optional per-operation configuration (adapter selection, schema override, etc.)
      * @returns {Promise<DatabaseResult<number>>} Promise resolving to the count
      *
@@ -227,13 +279,19 @@ export declare abstract class BaseRepository<T extends Record<string, unknown>>
      *   field: 'status', operator: 'eq', value: 'active'
      * });
      *
+     * // Using QueryBuilder
+     * const query = QueryBuilder.create<User>()
+     *   .where('status', 'eq', 'active')
+     *   .andWhere('verified', 'eq', true);
+     * const result = await userRepository.count(query);
+     *
      * // Count in specific adapter
      * const archiveCount = await userRepository.count(undefined, {
      *   adapter: 'archive'
      * });
      * ```
      */
-    count(filter?: Filter<T>, config?: OperationConfig): Promise<DatabaseResult<number>>;
+    count(filter?: Filter<T> | QueryBuilder<T>, config?: OperationConfig): Promise<DatabaseResult<number>>;
     /**
      * Check if an entity exists by ID
      *
@@ -258,7 +316,9 @@ export declare abstract class BaseRepository<T extends Record<string, unknown>>
     /**
      * Find the first entity matching filter criteria
      *
-     * @param {Filter<T>} filter - Filter conditions with type-safe fields
+     * Accepts either a Filter object or a QueryBuilder instance.
+     *
+     * @param {Filter<T> | QueryBuilder<T>} filter - Filter conditions or QueryBuilder
      * @param {OperationConfig} [config] - Optional per-operation configuration (adapter selection, schema override, etc.)
      * @returns {Promise<DatabaseResult<T | null>>} Promise resolving to first match or null
      *
@@ -268,6 +328,12 @@ export declare abstract class BaseRepository<T extends Record<string, unknown>>
      *   field: 'email', operator: 'eq', value: 'john@example.com'
      * });
      *
+     * // Using QueryBuilder
+     * const query = QueryBuilder.create<User>()
+     *   .where('email', 'eq', 'john@example.com')
+     *   .andWhere('status', 'eq', 'active');
+     * const result = await userRepository.findOne(query);
+     *
      * // Find in specific adapter
      * const archivedUser = await userRepository.findOne({
      *   field: 'email', operator: 'eq', value: 'john@example.com'
@@ -277,7 +343,7 @@ export declare abstract class BaseRepository<T extends Record<string, unknown>>
      * });
      * ```
      */
-    findOne(filter: Filter<T>, config?: OperationConfig): Promise<DatabaseResult<T | null>>;
+    findOne(filter: Filter<T> | QueryBuilder<T>, config?: OperationConfig): Promise<DatabaseResult<T | null>>;
     /**
      * Soft delete an entity by ID (recoverable deletion)
      *

package/dist/repository/BaseRepository.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"BaseRepository.d.ts","sourceRoot":"","sources":["../../src/repository/BaseRepository.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EACV,cAAc,EACd,eAAe,EACf,YAAY,EACZ,MAAM,EACN,wBAAwB,EACxB,WAAW,EACX,eAAe,EAChB,MAAM,iBAAiB,CAAC;AAEzB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyEG;AACH,8BAAsB,cAAc,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAIlE,SAAS,CAAC,QAAQ,CAAC,EAAE,EAAE,wBAAwB;IAC/C,SAAS,CAAC,QAAQ,CAAC,SAAS,EAAE,MAAM;IAJtC,SAAS,CAAC,QAAQ,CAAC,aAAa,CAAC,EAAE,eAAe,CAAC;gBAG9B,EAAE,EAAE,wBAAwB,EAC5B,SAAS,EAAE,MAAM,EACpC,aAAa,CAAC,EAAE,eAAe;IAKjC;;;;;;;OAOG;IACH,YAAY,IAAI,MAAM;IAItB;;;OAGG;IACH,OAAO,CAAC,WAAW;IAYnB;;;;;;;;;;;;;;;;;;;OAmBG;IACG,QAAQ,CACZ,EAAE,EAAE,MAAM,EACV,MAAM,CAAC,EAAE,eAAe,GACvB,OAAO,CAAC,cAAc,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IAIpC;;;;;;;;;;;;;;;;;;;;OAoBG;IACG,QAAQ,CACZ,OAAO,CAAC,EAAE,YAAY,CAAC,CAAC,CAAC,EACzB,MAAM,CAAC,EAAE,eAAe,GACvB,OAAO,CAAC,cAAc,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC;IAI9C;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACG,MAAM,CACV,IAAI,EAAE,WAAW,CAAC,CAAC,CAAC,EACpB,MAAM,CAAC,EAAE,eAAe,GACvB,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC;IAI7B;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACG,MAAM,CACV,EAAE,EAAE,MAAM,EACV,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,EAChB,MAAM,CAAC,EAAE,eAAe,GACvB,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC;IAS7B;;;;;;;;;;;;;;;;;;;OAmBG;IACG,MAAM,CACV,EAAE,EAAE,MAAM,EACV,MAAM,CAAC,EAAE,eAAe,GACvB,OAAO,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC;IAIhC;;;;;;;;;;;;;;;;;;;OAmBG;IACG,KAAK,CACT,MAAM,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,EAClB,MAAM,CAAC,EAAE,eAAe,GACvB,OAAO,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC;IAIlC;;;;;;;;;;;;;;;;;;;OAmBG;IACG,MAAM,CACV,EAAE,EAAE,MAAM,EACV,MAAM,CAAC,EAAE,eAAe,GACvB,OAAO,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC;IAanC;;;;;;;;;;;;;;;;;;;;;OAqBG;IACG,OAAO,CACX,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,EACjB,MAAM,CAAC,EAAE,eAAe,GACvB,OAAO,CAAC,cAAc,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IAIpC;;;;;;;;;;;;;;;;;;;;OAoBG;IACG,UAAU,CACd,EAAE,EAAE,MAAM,EACV,MAAM,CAAC,EAAE,eAAe,GACvB,OAAO,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC;CAGjC"}
+{"version":3,"file":"BaseRepository.d.ts","sourceRoot":"","sources":["../../src/repository/BaseRepository.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@plyaz/db",
-  "version": "0.4.0",
-  "description": "Package description",
+  "version": "0.5.0",
+  "description": "Unified database abstraction layer with CLI for migrations and seeds",
   "type": "module",
   "keywords": [],
   "packageManager": "pnpm@10.11.0",
@@ -42,7 +42,7 @@
     "@plyaz/errors": "^1.5.0",
     "@plyaz/logger": "^1.4.1",
     "@plyaz/testing": "^1.5.1",
-    "@plyaz/types": "^1.22.9",
+    "@plyaz/types": "^1.25.0",
     "@supabase/supabase-js": "^2.75.0",
     "commander": "^12.1.0",
     "drizzle-orm": "^0.44.6",

package/template/config/db.config.mjs.template

@@ -0,0 +1,33 @@
+/**
+ * Database Configuration
+ *
+ * Used by the @plyaz/db CLI for migrations and seeds
+ *
+ * @type {import('@plyaz/db').DatabaseServiceConfig}
+ */
+export default {
+  // ============================================================================
+  // ADAPTER CONFIGURATION
+  // ============================================================================
+
+  adapter: globalThis.process.env.DB_ADAPTER ?? '{{ADAPTER}}',
+
+  config: {
+    connectionString: globalThis.process.env.DATABASE_URL ?? '{{CONNECTION_STRING}}',
+    poolSize: 20,
+
+    // Custom ID columns (optional)
+    // tableIdColumns: {
+    //   'feature_flags': 'key',
+    // },
+  },
+
+  // ============================================================================
+  // MIGRATIONS & SEEDS PATHS
+  // ============================================================================
+
+  migrationsPath: '{{MIGRATIONS_PATH}}',
+  seedsPath: '{{SEEDS_PATH}}',
+  migrationsTable: '{{MIGRATIONS_TABLE}}',
+  seedsTable: '{{SEEDS_TABLE}}',
+};