sqlcache 2.9.0 → 2.9.1

package/.env.example

@@ -1,3 +1,7 @@
+# Template for sqlcache settings. Copy it to .env in your app's working directory
+# (in an installed project: cp node_modules/sqlcache/.env.example .env).
+# Only .env is loaded, and ${VAR} references are not expanded.
+
 # ============================================
 # MySQL Database Configuration (REQUIRED)
 # ============================================
@@ -21,10 +25,10 @@ DB_NAME=my_database
 # Connection Pool Settings (OPTIONAL)
 # ============================================
 
-# Maximum number of connections in pool (default: 500)
-# Optimized for high-traffic applications (adjust based on your server capacity)
-# Recommended range: 100-1000 for production
-DB_CONNECTION_LIMIT=500
+# Maximum number of connections in the pool, per process (default: 151)
+# Keep instances x workers x DB_CONNECTION_LIMIT, plus other clients, below MySQL's
+# max_connections (MySQL's default is also 151)
+DB_CONNECTION_LIMIT=151
 
 # Maximum number of queued connection requests (default: 0 = unlimited)
 # 0 = unlimited queue (recommended - waits when pool is full)
@@ -45,14 +49,19 @@ DB_IDLE_TIMEOUT=60000
 # Time to wait for initial database connection before throwing error
 DB_CONNECT_TIMEOUT=10000
 
-# Allow multiple SQL statements in a single query (default: true for backward compatibility)
-# WARNING: Only disable if you have security concerns (SQL injection risk)
-DB_MULTIPLE_STATEMENTS=true
+# Allow multiple SQL statements in a single query (default when unset: true, for backward
+# compatibility). false is recommended for new projects: with true, an SQL injection can run
+# additional statements. Set true only if you send several statements in one query.
+DB_MULTIPLE_STATEMENTS=false
 
 # Concurrent cache misses for the same key, database, SQL and parameters share one
 # database query; each caller still gets its own copy of the rows (default: true)
 # DB_COALESCE_QUERIES=true
 
+# Max time (ms) a caller waits for such a shared query before running its own, which protects
+# against a stuck connection; it still takes the shared result if that arrives first (default: 10000)
+# DB_COALESCE_MAX_WAIT=10000
+
 # getCacheQueryPagination: reuse the COUNT(*) total of one page for the other pages of the same
 # query until its cache name is invalidated, instead of counting on every page miss. Totals can
 # then lag behind writes that do not invalidate the cache name (default: false)
@@ -73,12 +82,14 @@ REDIS_SERVER=localhost
 REDIS_PORT=6379
 
 # Redis password (leave empty if no password)
+# Cached rows are served as stored, so treat Redis as a trusted store: use AUTH and a private network
 REDIS_PASSWORD=
 
 # Redis virtual host / namespace prefix
-# All cache keys will be prefixed with this value
-# Useful for multi-tenant applications or separate environments
-# Example: REDIS_VHOST=app1: will create keys like "app1:users-cache"
+# All cache keys will be prefixed with this value and a colon
+# Useful to separate applications or environments that share one Redis
+# Set it once per process; do not change it at runtime (for example per tenant request)
+# Example: REDIS_VHOST=app1 will create keys like "app1:users-cache"
 REDIS_VHOST=
 
 # ============================================
@@ -117,12 +128,13 @@ TIMEZONE=+00:00
 # v2.6.0 Smart Features (OPTIONAL) 🚀
 # ============================================
 
-# Enable ALL auto features at once (recommended for new projects)
-# This enables: auto key generation + auto invalidation
+# Automatic cache keys: generate a cache key when cacheName is omitted
+# This enables auto keys only, NOT auto invalidation (set CORE_AUTO_INVALIDATION for that)
 CORE_AUTO_FEATURES=false
 
-# Or enable features individually:
-# CORE_AUTO_INVALIDATION=false
+# Automatic invalidation: after INSERT/UPDATE/DELETE/REPLACE (and, since 2.9.1, bulkInsert)
+# without a resetCacheName, delete the table's <table>_* and <table>:* keys
+CORE_AUTO_INVALIDATION=false
 
 # ============================================
 # Example Configurations for Different Environments
@@ -138,13 +150,15 @@ CORE_AUTO_FEATURES=false
 # DB_HOST=mysql-prod.example.com
 # DB_USERNAME=prod_user
 # DB_PASSWORD=strong_password_here
-# DB_CONNECTION_LIMIT=500                 # Default (adjust based on load testing)
+# DB_CONNECTION_LIMIT=50                  # Per process: instances x workers x limit < max_connections
 # DB_QUEUE_LIMIT=0                        # Unlimited queue (recommended)
 # DB_CONNECT_TIMEOUT=10000                # 10 seconds
+# DB_MULTIPLE_STATEMENTS=false
 # REDIS_SERVER=redis-prod.example.com
 # REDIS_PASSWORD=redis_password_here
-# REDIS_VHOST=prod:
-# CORE_AUTO_FEATURES=true                 # Enable smart features
+# REDIS_VHOST=prod
+# CORE_AUTO_FEATURES=true                 # Automatic cache keys
+# CORE_AUTO_INVALIDATION=true             # Automatic invalidation
 
 # Docker Environment:
 # DB_HOST=mysql

package/{readme.md → README.md}

@@ -38,7 +38,9 @@ MySQL fail.
 
 ## Requirements
 
-- Node.js 10 or newer (the test suite runs on Node 22)
+- Node.js 14 or newer (tested on Node 18–26)
+- mysql2 3.23.1 or newer, installed as a dependency (older versions have security advisories,
+  including critical ones)
 - MySQL 5.7 or 8.x (tested with 8.0)
 - Redis 2.8 or newer for `SCAN` (tested with 7); optional, see `REDIS_ENABLED`
 
@@ -52,7 +54,8 @@ npm install sqlcache
 
 The package is configured with environment variables. It loads a `.env` file from the working
 directory and validates the settings when it is first required, with an error that lists what is
-missing.
+missing. Only `.env` is read (not `.env.production` and the like), and `${VAR}` references in it are
+not expanded. A commented template of every setting is in `node_modules/sqlcache/.env.example`.
 
 ```bash
 # .env
@@ -74,6 +77,7 @@ await QuaryCache('UPDATE users SET name = ? WHERE id = ?', ['Ada', 42], 'user:')
 ```
 
 > `QuaryCache` is the function's published name (with this spelling) and is kept for compatibility.
+> The examples use `await`; in CommonJS, run them inside an `async` function.
 
 ## Usage
 
@@ -86,10 +90,15 @@ const rows = await getCacheQuery(sql, params, cacheName, database);
 - **Cache hit:** the rows come from Redis.
 - **Cache miss:** the query runs on MySQL, and the rows are cached for 40,000 s (about 11 h) before
   the promise resolves. Keep cached data fresh through invalidation; there is no per-call TTL.
-- **Empty results** are not served from the cache, so a query that returned no rows runs again on
-  the next call.
+- **Empty results** are not served from the cache (and since 2.9.1 not written to it either), so a
+  query that returned no rows runs again on the next call.
 - **Concurrent misses** for the same key, database, SQL and parameters share one query, and each
-  caller receives its own copy of the rows. Set `DB_COALESCE_QUERIES=false` to turn this off.
+  caller receives its own copy of the rows. Set `DB_COALESCE_QUERIES=false` to turn this off. A caller
+  that has waited `DB_COALESCE_MAX_WAIT` ms (default 10000) for the shared query starts its own.
+- **Cache hits are JSON round trips:** a `Date` comes back as an ISO string and a `Buffer` as
+  `{ type, data }`, while a miss returns mysql2's types. Normalize such columns in your code.
+- **Stale reads:** since 2.9.1 a slow read does not re-cache data that was invalidated while it ran in
+  the same process. Across processes a short window remains.
 
 ### Writing and invalidation
 
@@ -98,9 +107,9 @@ const result = await QuaryCache(sql, params, resetCacheName, database);
 // result: rows for SELECT, or { insertId, affectedRows, ... } for writes
 ```
 
-After the statement succeeds, every key that starts with `resetCacheName` is deleted.
-`resetCacheName` can be a string or an array of prefixes. The call resolves once the invalidation
-has finished.
+`QuaryCache` never reads the cache. After the statement succeeds, every key that starts with
+`resetCacheName` is deleted. `resetCacheName` can be a string or an array of prefixes. The call
+resolves once the invalidation has finished.
 
 ### Pagination
 
@@ -116,8 +125,8 @@ const { totalCount, pageCount, detail } = await getCacheQueryPagination(
 
 - Each page is cached as `<cacheName>:page<n>:size<m>`, so `QuaryCache(..., 'orders:customer:7')`
   clears every page.
-- The total is counted with `SELECT COUNT(*)` only when the page is full; a short page is the last
-  one and already gives the total.
+- The total is counted with `SELECT COUNT(*)` only when the page is full or is an empty page past the
+  end; a short page is the last one and already gives the total.
 - With `DB_PAGINATION_REUSE_TOTAL=true`, the total is counted once and reused for the other pages
   until the cache name is invalidated.
 
@@ -134,8 +143,11 @@ const orderId = await withTransaction(async (tx) => {
 ```
 
 The transaction commits when the callback resolves and rolls back when it throws. Cache invalidations
-from `tx.query` are buffered and applied only after a successful commit. `tx.getCacheQuery` reads
-through the cache inside the transaction, and `tx.getConnection()` returns the raw mysql2 connection.
+from `tx.query` are buffered and applied only after a successful commit. `tx.getCacheQuery` checks
+the cache first and otherwise reads on the transaction's connection; since 2.9.1 it writes what it
+read to the cache only after the commit, so nothing is cached from a rolled-back transaction. A cache
+hit does not reflect the transaction's own changes, so use `tx.query` for reads that decide a write
+(for example `SELECT ... FOR UPDATE`). `tx.getConnection()` returns the raw mysql2 connection.
 
 ### Bulk insert
 
@@ -148,7 +160,16 @@ const { insertedRows, chunks } = await bulkInsert('events', records, {
 ```
 
 Without `transaction`, each chunk commits on its own. If a connection error interrupts the insert,
-the retry continues from the first chunk that was not acknowledged.
+the retry continues from the first chunk that was not acknowledged. With `transaction: true`, an error
+from `COMMIT` is not retried and carries `err.commitOutcomeUnknown = true`: the rows may or may not
+have been written.
+
+- **Columns come from the first record**, and the table and column names go into the SQL as-is.
+  Since 2.9.1 an invalid name is rejected with a `TypeError` before anything is sent. Never pass
+  untrusted keys: map request or CSV input onto a fixed list of columns.
+- **Invalidation:** `resetCacheName` prefixes are deleted after the insert. Since 2.9.1, without
+  `resetCacheName` auto-invalidation (if enabled) clears the table's keys as a `QuaryCache` write would,
+  and invalidation also runs when the insert fails after rows may have been written.
 
 ### Query timeouts
 
@@ -161,7 +182,9 @@ const rows = await getCacheQueryWithTimeout(sql, params, 'report:daily', {
 
 The call rejects with `Query timeout exceeded`. If it timed out before its query started (for example
 while waiting for a pool connection), the query is not run. Without `cancelOnTimeout`, a query that
-was already running finishes on the server and its result is cached.
+was already running finishes on the server and its result is cached. With it, since 2.9.1 the
+connection whose query was killed is discarded instead of being returned to the pool, and at most 4
+cancellations run at once.
 
 ### Several databases
 
@@ -172,7 +195,13 @@ await getCacheQuery('SELECT * FROM users', [], 'tenant7:users', 'tenant_7');
 ```
 
 Pass the database per call. Do not change `process.env` per request: environment variables are
-shared by all concurrent requests.
+shared by all concurrent requests, so a per-request `REDIS_VHOST` mixes tenants' cache entries
+(2.9.1 logs a warning when it changes at runtime). For multi-tenant apps:
+
+- Take the tenant from the authenticated session and check it against an allowlist, never from a raw
+  request header.
+- Pass the tenant's database per call; automatic keys then end with `@<database>`. Put the tenant in
+  explicit cache names too, such as `tenant7:users`.
 
 ### Redis helpers
 
@@ -190,22 +219,35 @@ None of these throw when Redis is unavailable: reads return `[]`, writes return
 caching it, and deletes are retried when Redis is back. `getRedisClient()` returns the underlying
 node-redis v3 client.
 
+Treat Redis as a trusted store: cached rows are served without checks, so protect it with AUTH and a
+private network, and give the app its own `REDIS_VHOST` or Redis database.
+
 ### Health checks and shutdown
 
 ```javascript
+const { isRedisConnected, getPoolStats, closeConnections, getRedisClient } = require('sqlcache');
+
 app.get('/health', (req, res) => res.json({ redis: isRedisConnected(), mysql: getPoolStats() }));
 // getPoolStats(): { totalConnections, activeConnections, freeConnections, queuedRequests }
 
 process.on('SIGTERM', async () => {
     await closeConnections(); // closes the MySQL pool; new queries are rejected afterwards
+    if (process.env.REDIS_ENABLED !== 'false') getRedisClient().quit(); // Redis is not closed by closeConnections()
 });
 ```
 
+Without the `quit()`, the open Redis connection keeps the process alive. With `REDIS_ENABLED=false`,
+`isRedisConnected()` returns `false` without opening a connection (since 2.9.1).
+
 ## Cache keys and invalidation
 
 All keys are prefixed with `REDIS_VHOST:` when `REDIS_VHOST` is set. Invalidation always works by
 prefix, so give related keys a common prefix, such as `user:42` and `user:list`.
 
+Prefixes passed to `resetCacheName` or `delPrefixKeyItem` are Redis glob patterns: escape `*`, `?`,
+`[`, `]` and `\` in any user-supplied part. An empty prefix without `REDIS_VHOST` deletes every key in
+that Redis database.
+
 ### Automatic keys and invalidation (opt-in)
 
 ```bash
@@ -220,18 +262,33 @@ const { configure } = require('sqlcache');
 
 configure({
     autoKey: { enabled: true },
-    autoInvalidation: { enabled: true, tables: { users: ['users:*', 'profiles:*'] } } // optional custom rules
+    autoInvalidation: { enabled: true, tables: { users: ['users:*', 'users_*', 'profiles:*'] } } // optional custom rules
 });
 
 const users = await getCacheQuery('SELECT * FROM users WHERE company_id = ?', [5]); // key users:company_id:<hash>
-await QuaryCache('UPDATE users SET active = 0 WHERE id = ?', [9]);                // clears users:* and users_*
+await QuaryCache('UPDATE users SET active = 0 WHERE id = ?', [9]);                // clears users:*, users_* and profiles:*
 ```
 
+`configure({ autoKey: false })`, `enableAutoKey(false)` and `enableAutoInvalidation(false)` turn a
+feature off (since 2.9.1; earlier versions turned it on).
+
 - **How keys are built:** from the table name, the `WHERE` column names and a hash of the parameters,
-  for example `users:company_id:a7b3c2d1`, or `users:all` without a `WHERE`. Calls that pass a
+  for example `users:company_id:a7b3c2d1`, or `users:all` without a `WHERE`. With four or more
+  parameters the column names are left out (`users:<hash>`). Queries without a detectable table
+  (`CALL`, `SELECT fn(?)`) get `query:<sqlhash>:<paramhash>` (since 2.9.1). Calls that pass a
   `database` get an `@<database>` suffix.
-- **Caveat:** the key does not include the selected columns, `ORDER BY` or `LIMIT`. If two queries on
-  the same table and `WHERE` columns differ only in those, pass explicit cache names.
+- **Caveats:** without a `WHERE`, the key is `<table>:all` whatever the SQL. The select list,
+  `ORDER BY`, `LIMIT`, literal values and joined tables are not part of the key, and the parameter
+  hash is 32-bit, so different queries can share a key. Pass explicit cache names for aggregates,
+  joins, `LIMIT`/`ORDER BY` variants, time-relative SQL (`NOW()`, `CURDATE()`) and anything
+  user-specific or sensitive.
+- **Custom rules** (`tables`) replace the default `<table>_*` and `<table>:*` patterns, so include
+  `<table>:*` when you use automatic keys. A `resetCacheName` passed to a call also replaces the
+  automatic patterns for that call.
+- **What auto-invalidation sees:** only statements that start with `INSERT`, `UPDATE`, `DELETE` or
+  `REPLACE`, and only the first table they name. Statements behind a leading comment or `WITH`,
+  `CALL`, multi-table `UPDATE`/`DELETE`, `db.table` names, tables joined into cached reads and writes
+  from other applications need an explicit `resetCacheName`.
 
 ## Configuration
 
@@ -242,26 +299,27 @@ await QuaryCache('UPDATE users SET active = 0 WHERE id = ?', [9]);
 | `DB_PASSWORD` | `''` | MySQL password |
 | `DB_NAME` | *required* | Default database |
 | `DB_PORT` | `3306` | MySQL port |
-| `DB_CONNECTION_LIMIT` | `151` | Max connections per process (MySQL's default `max_connections` is also 151) |
+| `DB_CONNECTION_LIMIT` | `151` | Max connections per process. Keep instances × workers × this limit, plus other clients, below MySQL's `max_connections` (default 151) |
 | `DB_QUEUE_LIMIT` | `0` | Max requests queued for a connection (`0` = unlimited) |
 | `DB_MAX_IDLE` | `10` | Idle connections kept open |
 | `DB_IDLE_TIMEOUT` | `60000` | ms before idle connections above `DB_MAX_IDLE` close |
 | `DB_CONNECT_TIMEOUT` | `10000` | ms to establish a connection |
-| `DB_MULTIPLE_STATEMENTS` | `true` | Allow several statements per query |
+| `DB_MULTIPLE_STATEMENTS` | `true` | Allow several statements per query (`false` is recommended for new projects) |
 | `TIMEZONE` | `+00:00` | Connection time zone |
 | `DB_COALESCE_QUERIES` | `true` | Share one query between concurrent identical cache misses |
+| `DB_COALESCE_MAX_WAIT` | `10000` | ms a caller waits for a shared query before running its own (2.9.1) |
 | `DB_PAGINATION_REUSE_TOTAL` | `false` | Reuse a paginated query's total across its pages |
-| `REDIS_ENABLED` | `true` | `false` runs every query on MySQL without caching; Redis is only connected if you call a Redis helper |
+| `REDIS_ENABLED` | `true` | `false` runs every query on MySQL without caching; Redis is only connected if you call a Redis helper (`isRedisConnected()` does not connect since 2.9.1) |
 | `REDIS_SERVER` | *required if enabled* | Redis host |
 | `REDIS_PORT` | `6379` | Redis port |
 | `REDIS_PASSWORD` | none | Redis password |
-| `REDIS_VHOST` | none | Prefix for every key (`<vhost>:<key>`) |
+| `REDIS_VHOST` | none | Prefix for every key (`<vhost>:<key>`); set once per process |
 | `REDIS_WAIT_TIMEOUT` | `10000` | ms an operation waits for Redis to (re)connect |
 | `REDIS_FAIL_FAST` | `true` | After `REDIS_WAIT_TIMEOUT` of downtime, stop waiting and fall back immediately |
 | `REDIS_COMMAND_TIMEOUT` | `max(REDIS_WAIT_TIMEOUT, 10000)` | ms a cache read/write may stay unanswered (`0` = off) |
 | `REDIS_RECONNECT_MAX_DELAY` | `5000` | Max ms between reconnect attempts |
 | `REDIS_SCAN_COUNT` | `1000` | Keys examined per `SCAN` round trip during invalidation |
-| `CORE_AUTO_FEATURES` | `false` | Automatic cache keys |
+| `CORE_AUTO_FEATURES` | `false` | Automatic cache keys only (not invalidation) |
 | `CORE_AUTO_INVALIDATION` | `false` | Automatic invalidation after writes |
 
 [docs/CONFIGURATION.md](docs/CONFIGURATION.md) covers pool tuning, bursty traffic and troubleshooting.
@@ -273,9 +331,12 @@ await QuaryCache('UPDATE users SET active = 0 WHERE id = ?', [9]);
 | Redis down | Reads go to MySQL and results are not cached. Calls wait up to `REDIS_WAIT_TIMEOUT` for a reconnect, then fall back immediately for the rest of the outage. Invalidations that could not run are replayed when Redis is back. |
 | Redis connection hangs | Cache reads and writes time out after `REDIS_COMMAND_TIMEOUT`, and a connection that stops answering is reopened. |
 | Redis restarts | Reconnects with exponential backoff and jitter, capped at `REDIS_RECONNECT_MAX_DELAY`, and never gives up. |
-| MySQL connection errors | On `ECONNREFUSED`, `ETIMEDOUT`, `ENOTFOUND`, `PROTOCOL_CONNECTION_LOST` or `ER_CON_COUNT_ERROR` a call is attempted up to 3 times, waiting 1 s and then 2 s (plus jitter). The whole statement is retried, so make writes idempotent where a duplicate would matter. |
+| MySQL connection errors | On `ECONNREFUSED`, `ETIMEDOUT`, `ENOTFOUND`, `PROTOCOL_CONNECTION_LOST` or `ER_CON_COUNT_ERROR` a call is attempted up to 3 times, waiting 1 s and then 2 s (plus jitter). The whole statement is retried, including `QuaryCache` and `bulkInsert` writes, which may then run twice: make writes idempotent. An error from `COMMIT` in `bulkInsert({ transaction: true })` is not retried and carries `err.commitOutcomeUnknown = true`. |
 | Error inside `withTransaction` | The transaction is rolled back and buffered invalidations are dropped. |
 
+mysql2 errors carry `err.sql` with the parameter values filled in. Do not send whole error objects to
+logs or clients you do not trust.
+
 The resilience behavior is covered by unit tests, integration tests against real MySQL and Redis,
 and 18 Docker chaos scenarios. These include killing Redis and MySQL mid-operation, 30-second
 outages, network partitions, pool exhaustion, thundering herds and both services down at once.
@@ -303,14 +364,20 @@ Tips:
 Type definitions ship with the package:
 
 ```typescript
-import { getCacheQuery, getCacheQueryPagination } from 'sqlcache';
+import { getCacheQuery, getCacheQueryPagination, QuaryCache } from 'sqlcache';
 
 interface User { id: number; name: string; }
 
 const users = await getCacheQuery<User>('SELECT id, name FROM users WHERE active = ?', [1], 'users:active');
 const page = await getCacheQueryPagination<User>('SELECT id, name FROM users', [], 'users:list', 0, 50);
+const rows = await QuaryCache<User[]>('SELECT id, name FROM users WHERE id = ?', [1]); // result type
 ```
 
+Since 2.9.1, named imports also work in native ESM (`import { getCacheQuery } from 'sqlcache'`), and
+`import sqlcache from 'sqlcache'` works without `esModuleInterop`. On 2.9.0 and earlier, use the
+default import in native ESM, and named imports or `import sqlcache = require('sqlcache')` in
+CommonJS builds without `esModuleInterop`.
+
 ## Upgrading
 
 ### From `node-caching-mysql-connector-with-redis`
@@ -325,6 +392,12 @@ Then replace `require('node-caching-mysql-connector-with-redis')` and TypeScript
 release, which forwards to `sqlcache`, so existing projects get the same code. The old name is
 deprecated and receives no new major versions.
 
+### From v2.9.0
+
+v2.9.1 is a patch release: it requires Node.js 14+ and mysql2 3.23.1+, fixes ESM and TypeScript
+imports, and changes some caching edge cases. [docs/MIGRATION.md](docs/MIGRATION.md#v290--v291)
+lists every difference.
+
 ### From v2.8.x
 
 v2.9.0 does not change the API. [docs/MIGRATION.md](docs/MIGRATION.md#v28x--v290-performance--resilience)
@@ -333,13 +406,18 @@ lists every behavior difference from v2.8.x and the settings that restore the ol
 ## Development
 
 ```bash
+npm ci                                         # install dependencies (node_modules is not committed)
 npm test                                       # unit tests
+npx -p typescript@5 tsc -p test/types          # type definitions check
 INTEGRATION=1 npm test                         # also integration tests: Redis on 127.0.0.1:6399, MySQL on 127.0.0.1:3399
 INTEGRATION=1 node test/chaos.test.js          # Redis chaos suite (Docker containers test-redis / test-mysql)
 INTEGRATION=1 node test/chaos-mysql.test.js    # MySQL chaos suite
 ```
 
-The test suite uses mocha 9, which runs on Node 22 but does not start on Node 26.
+The integration tests run Docker commands through `DOCKER_BIN` (default `docker`) on the container
+named by `REDIS_CONTAINER` (default `test-redis`); the chaos suites also use `DOCKER_BIN`. CI runs the unit tests on Node 18, 20, 22, 24 and
+26 and against the minimum dependency versions, plus the type check and the integration tests
+against MySQL 8.0 and Redis 7.
 See [docs/CONTRIBUTING.md](docs/CONTRIBUTING.md) for contribution guidelines.
 
 ## Documentation

package/core/autoInvalidate.js

@@ -10,12 +10,12 @@ let invalidationRules = {};
 
 /**
  * Enables auto invalidation feature
- * @param {Object} config - Configuration options
+ * @param {Object|boolean} config - Configuration options, or true/false to enable/disable
  * @param {boolean} config.enabled - Enable/disable auto invalidation
  * @param {Object} config.tables - Table-specific invalidation patterns
  */
 function enableAutoInvalidation(config = {}) {
-    autoInvalidationEnabled = config.enabled !== false;
+    autoInvalidationEnabled = typeof config === 'boolean' ? config : config.enabled !== false;
     invalidationRules = config.tables || {};
 }
 
@@ -123,6 +123,16 @@ function determineInvalidationPatterns(sql, manualPattern = null) {
 
 const GLOB_SPECIAL_CHARS = /[*?[\]\\]/;
 
+/**
+ * The pattern without its trailing '*' characters (a loop: /\*+$/ is quadratic on long runs of
+ * '*' inside the pattern)
+ */
+function stripTrailingStars(pattern) {
+    let end = pattern.length;
+    while (end > 0 && pattern.charCodeAt(end - 1) === 42 /* '*' */) end--;
+    return end === pattern.length ? pattern : pattern.slice(0, end);
+}
+
 /**
  * Reduces a list of prefix patterns to fewer Redis SCAN passes, without changing which keys
  * they match. Patterns are prefixes (delPrefixKeyItem appends '*'), so trailing '*' do not
@@ -139,7 +149,7 @@ function mergeInvalidationPatterns(patterns) {
     const literals = [];
     for (const pattern of patterns) {
         if (typeof pattern !== 'string') continue;
-        const literal = pattern.replace(/\*+$/, '');
+        const literal = stripTrailingStars(pattern);
         if (literal && !GLOB_SPECIAL_CHARS.test(literal)) literals.push(literal);
     }
 
@@ -148,7 +158,7 @@ function mergeInvalidationPatterns(patterns) {
     const seen = new Set();
 
     for (const pattern of patterns) {
-        const literal = typeof pattern === 'string' ? pattern.replace(/\*+$/, '') : null;
+        const literal = typeof pattern === 'string' ? stripTrailingStars(pattern) : null;
         if (!literal || GLOB_SPECIAL_CHARS.test(literal)) {
             result.push(pattern);
             continue;

package/core/autoKey.js

@@ -11,10 +11,10 @@ let autoKeyEnabled = false;
 
 /**
  * Enables auto key generation feature
- * @param {Object} config - Configuration options
+ * @param {Object|boolean} config - Configuration options, or true/false to enable/disable
  */
 function enableAutoKey(config = {}) {
-    autoKeyEnabled = config.enabled !== false;
+    autoKeyEnabled = typeof config === 'boolean' ? config : config.enabled !== false;
 }
 
 /**
@@ -24,6 +24,26 @@ function isAutoKeyEnabled() {
     return autoKeyEnabled || process.env.CORE_AUTO_FEATURES === 'true';
 }
 
+/**
+ * JSON.stringify replacer for parameters: JSON.stringify throws on a BigInt, so it is encoded
+ * as {"$bigint":"<digits>"}. Every other value is returned as is (unchanged hashes).
+ */
+function bigIntReplacer(name, value) {
+    return typeof value === 'bigint' ? { $bigint: value.toString() } : value;
+}
+
+/**
+ * JSON of the parameters for hashing. The replacer is only used when plain JSON.stringify
+ * throws (a replacer function takes V8 off its fast path for every other call).
+ */
+function serializeParameters(parameters) {
+    try {
+        return JSON.stringify(parameters);
+    } catch (_) {
+        return JSON.stringify(parameters, bigIntReplacer);
+    }
+}
+
 /**
  * Creates a short hash from parameters
  * @param {Array} parameters - Query parameters
@@ -36,7 +56,7 @@ function createParameterHash(parameters) {
 
     return crypto
         .createHash('md5')
-        .update(JSON.stringify(parameters))
+        .update(serializeParameters(parameters))
         .digest('hex')
         .substring(0, 8);
 }
@@ -80,8 +100,9 @@ function extractWhereConditions(sql) {
 
     const whereClause = whereMatch[1].trim();
 
-    // Split by AND/OR but preserve the column names
-    const conditions = whereClause.split(/\s+(AND|OR)\s+/i)
+    // Split by AND/OR but preserve the column names. A match only starts where a whitespace
+    // run starts (same splits as /\s+(AND|OR)\s+/i, which is quadratic on long whitespace runs)
+    const conditions = whereClause.split(/(?<!\s)\s+(AND|OR)\s+/i)
         .filter(part => !/^(AND|OR)$/i.test(part.trim()));
 
     return conditions.map(c => c.trim());
@@ -100,7 +121,8 @@ function extractColumnNames(conditions) {
         // Match: column_name > ?
         // Match: column_name IN (?)
         // Match: column_name LIKE ?
-        const columnMatch = condition.match(/(\w+)\s*(?:=|>|<|>=|<=|!=|<>|IN|LIKE|NOT\s+IN|NOT\s+LIKE)/i);
+        // (\b: the match always starts at a word start anyway; without it, long words are quadratic)
+        const columnMatch = condition.match(/\b(\w+)\s*(?:=|>|<|>=|<=|!=|<>|IN|LIKE|NOT\s+IN|NOT\s+LIKE)/i);
 
         if (columnMatch) {
             columns.push(columnMatch[1].toLowerCase());
@@ -155,6 +177,20 @@ function analyzeSql(sql) {
     return analysis;
 }
 
+/**
+ * Key of SQL without a detectable table: the SQL hash, plus the parameter hash when there are
+ * parameters, so that e.g. CALL get_user(?) for two different users never shares a key
+ * @param {string} queryKey - 'query:<sqlhash>'
+ * @param {Array} parameters - Query parameters
+ * @returns {string} - Cache key
+ */
+function queryKeyWithParameters(queryKey, parameters) {
+    if (!parameters || parameters.length === 0) {
+        return queryKey;
+    }
+    return `${queryKey}:${createParameterHash(parameters)}`;
+}
+
 /**
  * Generates cache key with detailed column information
  * @param {string} sql - SQL query
@@ -165,7 +201,7 @@ function generateDetailedKey(sql, parameters) {
     const { tableName, hasConditions, columnPart, queryKey } = analyzeSql(sql);
 
     if (!tableName) {
-        return queryKey;
+        return queryKeyWithParameters(queryKey, parameters);
     }
 
     if (!hasConditions) {
@@ -196,7 +232,7 @@ function generateSimpleKey(sql, parameters) {
     const { tableName, queryKey } = analyzeSql(sql);
 
     if (!tableName) {
-        return queryKey;
+        return queryKeyWithParameters(queryKey, parameters);
     }
 
     const paramHash = createParameterHash(parameters);