sqlcache 2.9.0 → 2.9.1

package/index.d.ts

@@ -1,14 +1,16 @@
 /**
  * Type definitions for sqlcache
  * Project: https://github.com/hayatialikeles/sqlcache
- * Definitions by: Ali Hayati Keleş
+ * Definitions by: Hayati Ali Keleş
  */
 
 /// <reference types="node" />
 
 declare module 'sqlcache' {
     /**
-     * MySQL query result type
+     * Result of a write statement: mysql2's ResultSetHeader (`affectedRows`, `insertId`, `info`,
+     * `serverStatus`, `warningStatus`, `changedRows`, `fieldCount`). `warningCount`, `message` and
+     * `protocol41` are kept for compatibility; mysql2 does not set them.
      */
     export interface QueryResult {
         affectedRows?: number;
@@ -19,6 +21,10 @@ declare module 'sqlcache' {
         changedRows?: number;
         fieldCount?: number;
         serverStatus?: number;
+        /** Server message, e.g. "Rows matched: 1  Changed: 1  Warnings: 0" */
+        info?: string;
+        /** Number of warnings */
+        warningStatus?: number;
     }
 
     /**
@@ -40,14 +46,23 @@ declare module 'sqlcache' {
     // ==================== DATABASE FUNCTIONS ====================
 
     /**
-     * Executes a SQL query and returns the result from the cache or the database.
-     * If a resetCacheName is provided, it deletes the cache item before executing the query.
+     * Runs a SQL statement on MySQL. It never reads the cache. After the statement succeeds, every
+     * cached key starting with `resetCacheName` (a prefix, or an array of prefixes) is deleted; without
+     * it, automatic invalidation applies when CORE_AUTO_INVALIDATION=true or enableAutoInvalidation()
+     * is on. A `resetCacheName` replaces the automatic patterns for the call.
      *
-     * @param sql - The SQL query to execute
-     * @param parameters - The parameters to be passed to the SQL query
-     * @param resetCacheName - The name of the cache item to reset (optional)
+     * Prefixes are Redis glob patterns: escape `* ? [ ] \` in user-supplied parts. An empty prefix
+     * without REDIS_VHOST deletes every key in that Redis database.
+     *
+     * On connection errors the statement is attempted up to 3 times, so a write can run twice: make
+     * writes idempotent. mysql2 errors carry `err.sql` with the parameter values filled in.
+     *
+     * @param sql - The SQL statement to execute
+     * @param parameters - The parameters to be passed to the SQL statement (optional)
+     * @param resetCacheName - Prefix or prefixes of the cache keys to delete after the statement (optional)
      * @param database - The database name to switch to (optional)
-     * @returns A promise that resolves with the result of the query
+     * @returns The mysql2 result: rows for a SELECT, a {@link QueryResult} for a write. Pass the type
+     *   for reads, e.g. `QuaryCache<User[]>('SELECT ...', [id])`.
      *
      * @example
      * ```typescript
@@ -57,14 +72,17 @@ declare module 'sqlcache' {
      *   "users-cache"
      * );
      * console.log(result.insertId);
+     *
+     * // Several prefixes
+     * await QuaryCache("DELETE FROM users WHERE id = ?", [1], ["users:", "profiles:"]);
      * ```
      */
-    export function QuaryCache(
+    export function QuaryCache<T = QueryResult>(
         sql: string,
-        parameters: any[],
-        resetCacheName?: string | null,
+        parameters?: any[],
+        resetCacheName?: string | string[] | null,
         database?: string | null
-    ): Promise<QueryResult>;
+    ): Promise<T>;
 
     /**
      * Retrieves data from cache or database based on the provided SQL query and parameters.
@@ -79,8 +97,19 @@ declare module 'sqlcache' {
      * (`DB_COALESCE_QUERIES=false` turns this off). Auto-generated keys of calls that pass
      * `database` end with `@<database>`, so databases (tenants) never share cache entries.
      *
+     * **v2.9.1:** empty results are not written to the cache (they were never served from it), and a
+     * cached value that is not a non-empty array is treated as a miss. A read that started before an
+     * invalidation in the same process does not write its possibly stale result. A caller that has
+     * waited `DB_COALESCE_MAX_WAIT` ms (default 10000) for a shared query starts its own, but still
+     * takes the shared result if it arrives first; an `ER_QUERY_TIMEOUT` of the shared query goes to
+     * every caller waiting on it.
+     *
+     * Results are cached for 40000 s as JSON: on a cache hit a `Date` is an ISO string and a `Buffer`
+     * is `{ type, data }`, while a miss returns mysql2's types. Without `cacheName` and with automatic
+     * keys disabled, the call rejects with `cacheName is required...`.
+     *
      * @param sql - The SQL query to be executed
-     * @param parameters - The parameters to be passed to the SQL query
+     * @param parameters - The parameters to be passed to the SQL query (optional)
      * @param cacheName - The name of the cache to store the data (optional if auto key enabled)
      * @param database - The database name to switch to (optional)
      * @returns A promise that resolves to the retrieved data
@@ -110,7 +139,7 @@ declare module 'sqlcache' {
      */
     export function getCacheQuery<T = any>(
         sql: string,
-        parameters: any[],
+        parameters?: any[],
         cacheName?: string | null,
         database?: string | null
     ): Promise<T[]>;
@@ -126,13 +155,21 @@ declare module 'sqlcache' {
      * optimizer hint also bounds the count. With `DB_PAGINATION_REUSE_TOTAL=true` the total of one
      * page is reused for the other pages of the same query until `cacheName` is invalidated.
      *
+     * Each page is cached as `<cacheName>:page<n>:size<m>`, so invalidating `cacheName` clears every
+     * page.
+     *
+     * **v2.9.1:** `LIMIT` is appended on a new line, so SQL ending in a `-- comment` paginates
+     * correctly, and a cached value is only used if it is a page object. Without a `cacheName`, an
+     * automatic key is used when automatic keys are enabled; otherwise the result is not cached and a
+     * one-time warning is logged (before 2.9.1 all such calls shared one cache key).
+     *
      * @param sql - The SQL query to execute
-     * @param parameters - The parameters to be used in the SQL query
-     * @param cacheName - The name of the cache to store the data
+     * @param parameters - The parameters to be used in the SQL query (`[]` for none)
+     * @param cacheName - The name of the cache to store the data (`null`: see above)
      * @param page - The page number of the data to retrieve (0-based)
      * @param pageSize - The number of records per page (default: 30)
      * @param database - The database name to switch to (optional)
-     * @returns A promise that resolves to an object containing the paginated data
+     * @returns A promise that resolves to `{ totalCount, pageCount, detail }`
      *
      * @example
      * ```typescript
@@ -145,7 +182,7 @@ declare module 'sqlcache' {
      * const result = await getCacheQueryPagination<Product>(
      *   "SELECT * FROM products WHERE category = ?",
      *   [5],
-     *   "products-cat-5-page-0",
+     *   "products:cat:5",
      *   0,
      *   25
      * );
@@ -158,7 +195,7 @@ declare module 'sqlcache' {
     export function getCacheQueryPagination<T = any>(
         sql: string,
         parameters: any[],
-        cacheName: string,
+        cacheName: string | null | undefined,
         page: number,
         pageSize?: number,
         database?: string | null
@@ -236,6 +273,9 @@ declare module 'sqlcache' {
      * merged. Waits for Redis like delKeyItem, and invalidations that could not run because Redis
      * was unreachable are replayed once it is ready again.
      *
+     * Prefixes are Redis glob patterns (`*` is appended): escape `* ? [ ] \` in user-supplied parts.
+     * An empty prefix without REDIS_VHOST deletes every key in that Redis database.
+     *
      * @param keys - Single prefix or array of prefixes
      * @returns A promise that resolves when deletion is complete
      *
@@ -253,7 +293,8 @@ declare module 'sqlcache' {
     /**
      * Check if Redis connection is healthy.
      * Useful for health-check endpoints and monitoring.
-     * With REDIS_ENABLED=false the first call opens the connection.
+     * **v2.9.1:** with REDIS_ENABLED=false it returns false without opening a connection (2.9.0
+     * opened one on the first call).
      *
      * @returns true if Redis is connected and ready
      *
@@ -289,11 +330,15 @@ declare module 'sqlcache' {
         database?: string | null;
         /** Number of records per chunk (default: 1000) */
         chunkSize?: number;
-        /** Cache name prefix to reset after insert */
-        resetCacheName?: string | null;
+        /**
+         * Cache name prefix (or prefixes) to reset after insert. Without it, automatic invalidation
+         * applies when enabled (v2.9.1).
+         */
+        resetCacheName?: string | string[] | null;
         /**
          * v2.9.0: insert all chunks in one transaction (all or nothing, and faster for large
-         * inserts). Without it each chunk commits on its own, as before (default: false)
+         * inserts). Without it each chunk commits on its own, as before (default: false).
+         * v2.9.1: an error from COMMIT is not retried and carries `err.commitOutcomeUnknown = true`.
          */
         transaction?: boolean;
     }
@@ -341,6 +386,19 @@ declare module 'sqlcache' {
      * Executes a bulk insert operation with automatic chunking for large datasets.
      * Prevents memory issues by splitting large datasets into manageable chunks.
      *
+     * The columns are the keys of the first record, and the table and column names are used in the
+     * SQL as-is. Never pass untrusted keys: map request or CSV input onto a fixed list of columns.
+     * **v2.9.1:** an invalid name is rejected before anything is sent, with a `TypeError`
+     * (`bulkInsert: invalid table name "<name>"` / `bulkInsert: invalid column name "<name>"`).
+     *
+     * After a connection error the insert is retried from the first unacknowledged chunk, so a chunk
+     * can be inserted twice. With `transaction: true` a retry starts over, and (v2.9.1) an error from
+     * COMMIT is not retried and carries `err.commitOutcomeUnknown = true`.
+     *
+     * **v2.9.1:** without `resetCacheName`, automatic invalidation (CORE_AUTO_INVALIDATION /
+     * enableAutoInvalidation) applies, and invalidation also runs when the insert fails after rows
+     * may have been written.
+     *
      * @param table - The table name to insert into
      * @param records - Array of objects with column-value pairs
      * @param options - Optional settings for bulk insert
@@ -374,9 +432,17 @@ declare module 'sqlcache' {
      * pool connection) no longer runs the query afterwards. A query that is already running
      * keeps running and caches its result, unless `cancelOnTimeout: true` is set.
      *
+     * **v2.9.1:** a timeout during the database switch also stops the query from being sent. With
+     * `cancelOnTimeout`, the connection whose query was killed is discarded instead of being
+     * returned to the pool, and at most 4 cancellations run at once. Without a `cacheName`, an
+     * automatic key is used when automatic keys are enabled; otherwise the result is not cached and
+     * a one-time warning is logged (before 2.9.1 all such calls shared one cache key).
+     *
+     * The call rejects with `Query timeout exceeded` when the timeout fires.
+     *
      * @param sql - The SQL query to execute
-     * @param parameters - Query parameters
-     * @param cacheName - Cache key for storing results
+     * @param parameters - Query parameters (optional)
+     * @param cacheName - Cache key for storing results (see above when omitted)
      * @param options - Optional timeout and database settings
      * @returns Promise resolving to query results
      *
@@ -392,19 +458,23 @@ declare module 'sqlcache' {
      */
     export function getCacheQueryWithTimeout<T = any>(
         sql: string,
-        parameters: any[],
-        cacheName: string,
+        parameters?: any[],
+        cacheName?: string | null,
         options?: QueryTimeoutOptions
     ): Promise<T[]>;
 
     /**
-     * Gracefully closes all database connections.
+     * Gracefully closes the MySQL connection pool; new queries are rejected afterwards.
      * Should be called during application shutdown to prevent connection leaks.
      *
+     * The Redis client is not closed: when Redis is enabled, also call `getRedisClient().quit()`,
+     * or the open Redis connection keeps the process alive.
+     *
      * @example
      * ```typescript
      * process.on('SIGTERM', async () => {
      *   await closeConnections();
+     *   if (process.env.REDIS_ENABLED !== 'false') getRedisClient().quit();
      *   process.exit(0);
      * });
      * ```
@@ -441,7 +511,10 @@ declare module 'sqlcache' {
     export interface AutoInvalidationConfig {
         /** Enable auto invalidation */
         enabled?: boolean;
-        /** Table-specific invalidation patterns */
+        /**
+         * Table-specific invalidation patterns. A rule replaces the default `<table>_*` and
+         * `<table>:*` patterns for its table; keep `<table>:*` when you use automatic keys.
+         */
         tables?: Record<string, string | string[]>;
     }
 
@@ -455,11 +528,31 @@ declare module 'sqlcache' {
         autoInvalidation?: AutoInvalidationConfig;
     }
 
+    /**
+     * Options of configure(): like {@link CoreConfig}, and each feature also accepts a boolean.
+     */
+    export interface ConfigureOptions {
+        /** Auto key generation config, or `true`/`false` */
+        autoKey?: AutoKeyConfig | boolean;
+        /** Auto invalidation config, or `true`/`false` */
+        autoInvalidation?: AutoInvalidationConfig | boolean;
+    }
+
     /**
      * Enables auto cache key generation feature.
-     * When enabled, cacheName parameter becomes optional in getCacheQuery().
+     * When enabled, the cacheName parameter becomes optional in getCacheQuery() and
+     * tx.getCacheQuery(), and (v2.9.1) may be omitted in getCacheQueryPagination() and
+     * getCacheQueryWithTimeout(). Same as CORE_AUTO_FEATURES=true.
+     *
+     * **v2.9.1:** `enableAutoKey(false)` disables the feature (before 2.9.1 it enabled it). Queries
+     * without a detectable table (`CALL`, `SELECT fn(?)`) get the key `query:<sqlhash>:<paramhash>`,
+     * and BigInt parameters no longer throw.
+     *
+     * Keys are built from the table, the WHERE column names and a 32-bit parameter hash; the select
+     * list, ORDER BY, LIMIT, literal values and joins are not part of them. Use explicit cache names
+     * for queries that differ only in those, and for anything user-specific or sensitive.
      *
-     * @param config - Auto key configuration
+     * @param config - Auto key configuration, or `true`/`false`
      *
      * @example
      * ```typescript
@@ -469,35 +562,41 @@ declare module 'sqlcache' {
      * const users = await getCacheQuery('SELECT * FROM users WHERE id = ?', [123]);
      * ```
      */
-    export function enableAutoKey(config?: AutoKeyConfig): void;
+    export function enableAutoKey(config?: AutoKeyConfig | boolean): void;
 
     /**
      * Enables auto cache invalidation feature.
-     * When enabled, cache will be automatically cleared on write operations.
+     * When enabled, writes without a resetCacheName (QuaryCache, tx.query and, since v2.9.1,
+     * bulkInsert) clear the `<table>_*` and `<table>:*` keys of the table they write to. Same as
+     * CORE_AUTO_INVALIDATION=true; CORE_AUTO_FEATURES does not enable it.
      *
-     * @param config - Auto invalidation configuration
+     * **v2.9.1:** `enableAutoInvalidation(false)` disables the feature (before 2.9.1 it enabled it).
+     *
+     * @param config - Auto invalidation configuration, or `true`/`false`
      *
      * @example
      * ```typescript
      * enableAutoInvalidation({
      *     enabled: true,
      *     tables: {
-     *         users: ['users_*', 'profiles_*'],
-     *         orders: ['orders_*']
+     *         users: ['users:*', 'users_*', 'profiles_*'],
+     *         orders: ['orders:*', 'orders_*']
      *     }
      * });
      *
      * // Now resetCacheName is optional
      * await QuaryCache('INSERT INTO users...', [data]);
-     * // Auto-clears: users_*, profiles_*
+     * // Auto-clears: users:*, users_*, profiles_*
      * ```
      */
-    export function enableAutoInvalidation(config?: AutoInvalidationConfig): void;
+    export function enableAutoInvalidation(config?: AutoInvalidationConfig | boolean): void;
 
     /**
      * All-in-one configuration helper for v2.6.0 features.
+     * Each option is passed to enableAutoKey() / enableAutoInvalidation(); since v2.9.1 `false`
+     * disables the feature (e.g. `configure({ autoKey: false })`).
      *
-     * @param config - Core configuration object
+     * @param config - Configuration object
      *
      * @example
      * ```typescript
@@ -506,15 +605,15 @@ declare module 'sqlcache' {
      *     autoInvalidation: {
      *         enabled: true,
      *         tables: {
-     *             users: ['users_*', 'profiles_*']
+     *             users: ['users:*', 'users_*', 'profiles_*']
      *         }
      *     }
      * });
      * ```
      */
-    export function configure(config?: CoreConfig): void;
+    export function configure(config?: ConfigureOptions): void;
 
-    // ==================== TRANSACTION SUPPORT (v2.7.0+) ====================
+    // ==================== TRANSACTION SUPPORT (v2.6.0+) ====================
 
     /**
      * Transaction context object provided to transaction callback.
@@ -526,7 +625,7 @@ declare module 'sqlcache' {
          * Cache invalidation is buffered and applied only on successful commit.
          *
          * @param sql - SQL query to execute
-         * @param parameters - Query parameters
+         * @param parameters - Query parameters (optional)
          * @param resetCacheName - Optional cache patterns to invalidate on commit
          * @returns Promise resolving to query result
          *
@@ -538,16 +637,20 @@ declare module 'sqlcache' {
          */
         query<T = any>(
             sql: string,
-            parameters: any[],
+            parameters?: any[],
             resetCacheName?: string | string[] | null
         ): Promise<T>;
 
         /**
          * Executes a cached read query within the transaction.
-         * Note: Reads from cache but doesn't guarantee transaction isolation.
+         * Note: Reads from cache first, so a cache hit doesn't reflect the transaction's own changes;
+         * use query() for reads that decide a write (e.g. `SELECT ... FOR UPDATE`).
+         *
+         * **v2.9.1:** rows read on a cache miss are written to the cache only after the transaction
+         * commits; nothing is cached from a rolled-back transaction (2.9.0 cached them immediately).
          *
          * @param sql - SQL query to execute
-         * @param parameters - Query parameters
+         * @param parameters - Query parameters (optional)
          * @param cacheName - Cache key (optional if auto-key enabled)
          * @returns Promise resolving to query results
          *
@@ -558,7 +661,7 @@ declare module 'sqlcache' {
          */
         getCacheQuery<T = any>(
             sql: string,
-            parameters: any[],
+            parameters?: any[],
             cacheName?: string | null
         ): Promise<T[]>;
 
@@ -584,7 +687,7 @@ declare module 'sqlcache' {
      * Automatically commits on success or rolls back on error.
      * Cache invalidation is buffered and applied only on successful commit.
      *
-     * @param callback - Async function that receives transaction context
+     * @param callback - Function (usually async) that receives transaction context
      * @param options - Transaction options
      * @returns Promise resolving to callback return value
      * @throws Error if transaction fails or is rolled back
@@ -622,14 +725,20 @@ declare module 'sqlcache' {
      * ```
      */
     export function withTransaction<T = any>(
-        callback: (tx: TransactionContext) => Promise<T>,
+        callback: (tx: TransactionContext) => T | Promise<T>,
         options?: TransactionOptions
     ): Promise<T>;
 
     // ==================== BACKWARD COMPATIBILITY ====================
 
     /**
-     * Default export for backward compatibility with v2.4.x
+     * Default export for backward compatibility with v2.4.x.
+     *
+     * Since v2.9.1 the CommonJS module also has a non-enumerable `default` property, so
+     * `import sqlcache from 'sqlcache'` works without `esModuleInterop`; with 2.9.0 and earlier it
+     * needs `esModuleInterop` (or use `import sqlcache = require('sqlcache')`). Since v2.9.1 named
+     * imports also work in native ESM; with 2.9.0 and earlier, native ESM code should use the
+     * default import.
      *
      * @example
      * ```typescript
@@ -640,6 +749,10 @@ declare module 'sqlcache' {
      * // v2.5.0 style (recommended)
      * import { QuaryCache, getCacheQuery } from 'sqlcache';
      * QuaryCache(...);
+     *
+     * // Default import
+     * import sqlcache from 'sqlcache';
+     * sqlcache.getCacheQuery(...);
      * ```
      */
     const connector: {

package/index.js

@@ -3,40 +3,67 @@ const redisConnector = require('./redis.Connector');
 const { enableAutoKey } = require('./core/autoKey');
 const { enableAutoInvalidation } = require('./core/autoInvalidate');
 
+// Exported below as shorthand properties, which lets Node detect every name for ES module
+// named imports (import { getCacheQuery } from 'sqlcache')
+const {
+    QuaryCache,
+    getCacheQuery,
+    getCacheQueryPagination,
+    bulkInsert,
+    getCacheQueryWithTimeout,
+    closeConnections,
+    getPoolStats,
+    withTransaction
+} = dbConnector;
+const {
+    getArrayItem,
+    addArrayItem,
+    delKeyItem,
+    delPrefixKeyItem,
+    isRedisConnected,
+    getRedisClient
+} = redisConnector;
+
+// All-in-one configuration helper
+function configure(config = {}) {
+    if (config.autoKey !== undefined) {
+        enableAutoKey(config.autoKey);
+    }
+    if (config.autoInvalidation !== undefined) {
+        enableAutoInvalidation(config.autoInvalidation);
+    }
+}
+
 module.exports = {
     // Database functions
-    QuaryCache: dbConnector.QuaryCache,
-    getCacheQuery: dbConnector.getCacheQuery,
-    getCacheQueryPagination: dbConnector.getCacheQueryPagination,
+    QuaryCache,
+    getCacheQuery,
+    getCacheQueryPagination,
 
     // Production-grade features (v2.5.3+)
-    bulkInsert: dbConnector.bulkInsert,
-    getCacheQueryWithTimeout: dbConnector.getCacheQueryWithTimeout,
-    closeConnections: dbConnector.closeConnections,
-    getPoolStats: dbConnector.getPoolStats,
+    bulkInsert,
+    getCacheQueryWithTimeout,
+    closeConnections,
+    getPoolStats,
 
     // Transaction support (v2.7.0+)
-    withTransaction: dbConnector.withTransaction,
+    withTransaction,
 
     // Redis functions
-    getArrayItem: redisConnector.getArrayItem,
-    addArrayItem: redisConnector.addArrayItem,
-    delKeyItem: redisConnector.delKeyItem,
-    delPrefixKeyItem: redisConnector.delPrefixKeyItem,
-    isRedisConnected: redisConnector.isRedisConnected,
-    getRedisClient: redisConnector.getRedisClient,
+    getArrayItem,
+    addArrayItem,
+    delKeyItem,
+    delPrefixKeyItem,
+    isRedisConnected,
+    getRedisClient,
 
     // v2.6.0 Core Features (Opt-in)
     enableAutoKey,
     enableAutoInvalidation,
 
     // All-in-one configuration helper
-    configure(config = {}) {
-        if (config.autoKey !== undefined) {
-            enableAutoKey(config.autoKey);
-        }
-        if (config.autoInvalidation !== undefined) {
-            enableAutoInvalidation(config.autoInvalidation);
-        }
-    }
-};
+    configure
+};
+
+// import sqlcache from 'sqlcache' and require('sqlcache').default give the same object
+Object.defineProperty(module.exports, 'default', { value: module.exports, enumerable: false });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sqlcache",
-  "version": "2.9.0",
+  "version": "2.9.1",
   "description": "Read-through Redis caching for MySQL: invalidation, pagination, transactions, resilience, TypeScript (formerly node-caching-mysql-connector-with-redis)",
   "main": "index.js",
   "types": "index.d.ts",
@@ -24,9 +24,11 @@
     "auto-key",
     "auto-invalidation",
     "smart-cache",
-    "zero-config",
     "transaction",
-    "transactions"
+    "read-through",
+    "cache-invalidation",
+    "redis-cache",
+    "mysql-cache"
   ],
   "repository": {
     "type": "git",
@@ -48,16 +50,20 @@
   ],
   "dependencies": {
     "dotenv": "^16.0.3",
-    "mysql2": "^3.3.0",
+    "mysql2": "^3.23.1",
     "redis": "^3.1.2"
   },
   "devDependencies": {
+    "@types/node": "^22.20.5",
     "chai": "^4.3.6",
     "chai-http": "^4.3.0",
-    "mocha": "^9.2.1",
+    "mocha": "^10.8.2",
     "nyc": "^17.1.0",
     "proxyquire": "^2.1.3",
     "sinon": "^17.0.1",
     "sinon-chai": "^3.7.0"
+  },
+  "engines": {
+    "node": ">=14"
   }
 }