sqlcache 2.9.0 → 2.9.1

package/docs/README.tr.md

@@ -26,7 +26,7 @@ if (!cachedUsers) {
 await db.query('UPDATE users SET status = ? WHERE id = ?', ['inactive', 123]);
 await redis.del('users-active'); // Unutmak çok kolay!
 
-// ✅ Bu paketle – Sıfır konfigürasyon
+// ✅ Bu paketle – CORE_AUTO_FEATURES=true ve CORE_AUTO_INVALIDATION=true ile
 const users = await getCacheQuery('SELECT * FROM users WHERE status = ?', ['active']);
 await QuaryCache('UPDATE users SET status = ? WHERE id = ?', ['inactive', 123]);
 // Cache otomatik temizlenir! ✨
@@ -42,6 +42,13 @@ await QuaryCache('UPDATE users SET status = ? WHERE id = ?', ['inactive', 123]);
 npm install sqlcache
 ```
 
+### Gereksinimler
+
+- Node.js 14 veya üzeri (Node 18–26 üzerinde test edildi)
+- mysql2 3.23.1 veya üzeri (bağımlılık olarak kurulur; eski sürümlerde kritik olanlar dahil güvenlik
+  açıkları var)
+- MySQL 5.7 veya 8.x; Redis 2.8 veya üzeri (opsiyonel, bkz. `REDIS_ENABLED`)
+
 ### Temel Kullanım
 
 ```bash
@@ -52,9 +59,15 @@ DB_PASSWORD=secret
 DB_NAME=mydb
 REDIS_SERVER=localhost
 REDIS_PORT=6379
-CORE_AUTO_FEATURES=true  # Akıllı özellikleri etkinleştir 🎯
+CORE_AUTO_FEATURES=true      # Otomatik cache anahtarları 🎯
+CORE_AUTO_INVALIDATION=true  # Yazmalardan sonra otomatik cache temizleme
 ```
 
+`CORE_AUTO_FEATURES` yalnızca otomatik cache anahtarlarını açar; otomatik temizleme için
+`CORE_AUTO_INVALIDATION=true` gerekir. Paket yalnızca çalışma dizinindeki `.env` dosyasını okur
+(`${VAR}` ifadeleri açılmaz); tüm ayarların açıklamalı şablonu `node_modules/sqlcache/.env.example`
+dosyasındadır.
+
 ```javascript
 const { getCacheQuery, QuaryCache, withTransaction } = require('sqlcache');
 
@@ -72,7 +85,10 @@ await withTransaction(async (tx) => {
 ```
 
 **Hepsi bu kadar!**
-Manuel cache key, manuel invalidation veya transaction yönetimi gerekmez.
+Basit sorgular için manuel cache key veya manuel invalidation, transaction için de manuel
+BEGIN/COMMIT gerekmez. Join, aggregate (`COUNT(*)` vb.), `LIMIT`/`ORDER BY` varyantları ve kullanıcıya
+özel veya hassas veriler için açık cache adı verin: otomatik anahtar yalnızca tabloyu, `WHERE`
+sütunlarını ve parametrelerin 32 bitlik özetini içerir.
 
 ---
 
@@ -92,9 +108,10 @@ Manuel cache key, manuel invalidation veya transaction yönetimi gerekmez.
 * ✅ **Bulk İşlemler** – 100K+ kayıt için otomatik parçalara bölme
 * ✅ **Timeout Koruması** – Uzun süren sorguların sistemi bloklamasını önler
 * ✅ **Connection Pool İzleme** – Aktif bağlantı sayısı ve durum takibi
-* ✅ **Graceful Shutdown** – Kapanışta temiz bağlantı kapatma
+* ✅ **Graceful Shutdown** – `closeConnections()` MySQL havuzunu kapatır; Redis açıksa ardından
+  `getRedisClient().quit()` çağırın, yoksa açık Redis bağlantısı süreci ayakta tutar
 * ✅ **TypeScript Desteği** – Tam IntelliSense ve tip tanımları
-* ✅ **%100 Geriye Dönük Uyumluluk** – Hiçbir breaking change yok
+* ✅ **API Uyumluluğu** – API değişmedi; sürümler arası davranış farkları [MIGRATION.md](MIGRATION.md) dosyasında
 
 ---
 
@@ -136,7 +153,7 @@ const posts = await getCacheQuery(
   [userId]
 );
 
-// Yeni gönderi oluştur – cache otomatik temizlenir
+// Yeni gönderi oluştur – posts:* cache'i otomatik temizlenir (CORE_AUTO_INVALIDATION=true)
 await QuaryCache('INSERT INTO posts (user_id, content) VALUES (?, ?)', [userId, content]);
 ```
 
@@ -146,14 +163,14 @@ await QuaryCache('INSERT INTO posts (user_id, content) VALUES (?, ?)', [userId,
 
 ```javascript
 // Ana fonksiyonlar
-getCacheQuery(sql, params, cacheName?, database?)
-QuaryCache(sql, params, resetCacheName?, database?)
+getCacheQuery(sql, params?, cacheName?, database?)
+QuaryCache(sql, params?, resetCacheName?, database?)   // cache okumaz; başarılı yazmadan sonra prefix ile temizler
 withTransaction(callback, options?)
 
 // Yardımcılar
 bulkInsert(table, records, options?)
-getCacheQueryWithTimeout(sql, params, cacheName, options?)
-getCacheQueryPagination(sql, params, cacheName, page, pageSize?, database?)
+getCacheQueryWithTimeout(sql, params?, cacheName?, options?)
+getCacheQueryPagination(sql, params, cacheName, page, pageSize?, database?)  // page 0'dan başlar → { totalCount, pageCount, detail }
 closeConnections()
 getPoolStats()
 
@@ -162,6 +179,13 @@ getArrayItem(key)
 addArrayItem(key, data, expiry?)
 delKeyItem(keys)
 delPrefixKeyItem(patterns)
+isRedisConnected()
+getRedisClient()
+
+// Otomatik özellikler
+configure({ autoKey, autoInvalidation })
+enableAutoKey(config?)
+enableAutoInvalidation(config?)
 ```
 
 📚 **[Detaylı API Dokümantasyonu →](API.md)**
@@ -175,28 +199,31 @@ delPrefixKeyItem(patterns)
 ```bash
 DB_HOST=localhost
 DB_USERNAME=root
-DB_PASSWORD=secret
 DB_NAME=mydb
 
-REDIS_SERVER=localhost
-REDIS_PORT=6379
+REDIS_SERVER=localhost   # REDIS_ENABLED=false değilse zorunlu
 ```
 
 ### Opsiyonel Akıllı Özellikler
 
 ```bash
-CORE_AUTO_FEATURES=true
+CORE_AUTO_FEATURES=true      # Otomatik cache anahtarları (temizlemeyi açmaz)
+CORE_AUTO_INVALIDATION=true  # Yazmalardan sonra otomatik cache temizleme
 ```
 
 ### Gelişmiş Ayarlar
 
 ```bash
+DB_PASSWORD=secret              # Varsayılan: boş
 DB_PORT=3306
-DB_CONNECTION_LIMIT=10
+DB_CONNECTION_LIMIT=10          # Süreç başına (varsayılan: 151); örnek × worker × limit + diğer istemciler, MySQL max_connections (varsayılan 151) altında kalmalı
 DB_QUEUE_LIMIT=0
 DB_CONNECT_TIMEOUT=10000
+DB_MULTIPLE_STATEMENTS=false    # Varsayılan: true (geriye uyumluluk); yeni projelerde false önerilir
 TIMEZONE=+00:00
+REDIS_PORT=6379
 REDIS_PASSWORD=secret
+REDIS_VHOST=my_app              # Tüm anahtarların öneki; süreç başına bir kez ayarlayın, istek başına değiştirmeyin
 REDIS_ENABLED=true
 ```
 
@@ -204,6 +231,7 @@ REDIS_ENABLED=true
 
 ```bash
 DB_COALESCE_QUERIES=true          # Aynı anda gelen aynı cache-miss'ler tek sorguyu paylaşır (varsayılan: true)
+DB_COALESCE_MAX_WAIT=10000        # Paylaşılan sorgu için en fazla bekleme, sonra yeni sorgu başlar, ms (varsayılan: 10000, v2.9.1)
 DB_PAGINATION_REUSE_TOTAL=false   # Sayfalama toplamını aynı sorgunun diğer sayfalarında yeniden kullan (varsayılan: false)
 REDIS_WAIT_TIMEOUT=10000          # Redis'in (yeniden) bağlanması için en fazla bekleme, ms (varsayılan: 10000)
 REDIS_FAIL_FAST=true              # Bu süre kadar kesintiden sonra cache okuma/yazma beklemeden devam eder (varsayılan: true)
@@ -214,6 +242,9 @@ REDIS_SCAN_COUNT=1000             # Prefix silmede SCAN başına incelenen anaht
 
 v2.8.x davranışına dönmek ve değişikliklerin listesi için: [MIGRATION.md](MIGRATION.md#v28x--v290-performance--resilience)
 
+v2.9.1 değişiklikleri (Node.js 14+, mysql2 3.23.1+, ESM/TypeScript import düzeltmeleri, cache
+ayrıntıları): [MIGRATION.md](MIGRATION.md#v290--v291)
+
 ---
 
 ## 🔄 Geriye Dönük Uyumluluk
@@ -221,34 +252,36 @@ v2.8.x davranışına dönmek ve değişikliklerin listesi için: [MIGRATION.md]
 v2.5.3 kodunuz **hiçbir değişiklik olmadan** çalışmaya devam eder:
 
 ```javascript
-await getCacheQuery('SELECT * FROM users', [], 'my-key');
+await getCacheQuery('SELECT * FROM users', [], 'users_all');
 await QuaryCache('INSERT INTO users...', [data], 'users_*');
 ```
 
-Yeni sürümde `CORE_AUTO_FEATURES=true` yaparsanız:
+Yeni sürümde `CORE_AUTO_FEATURES=true` ve `CORE_AUTO_INVALIDATION=true` yaparsanız:
 
 ```javascript
-await getCacheQuery('SELECT * FROM users', []);  // Otomatik cache key ✨
-await QuaryCache('INSERT INTO users...', [data]); // Otomatik invalidation ✨
+await getCacheQuery('SELECT * FROM users', []);  // Otomatik cache key (users:all) ✨
+await QuaryCache('INSERT INTO users...', [data]); // Otomatik invalidation (users:* ve users_*) ✨
 ```
 
+Bir yazmaya `resetCacheName` verirseniz o çağrıda otomatik desenlerin yerine geçer: yalnızca
+`'users_*'` temizleyen eski yazmalar yeni `users:...` anahtarlarını silmez.
+
 ---
 
 ## 🧪 Test
 
 ```bash
+npm ci
 npm test
 npm run coverage
 ```
 
-**Kapsama:** %98.07 | **Test:** 215 geçiyor ✅
-
 ---
 
 ## 📝 TypeScript Desteği
 
 ```typescript
-import { getCacheQuery, withTransaction, TransactionContext } from 'sqlcache';
+import { getCacheQuery, withTransaction, type TransactionContext } from 'sqlcache';
 
 interface User {
   id: number;
@@ -256,7 +289,7 @@ interface User {
   email: string;
 }
 
-const users = await getCacheQuery<User[]>('SELECT * FROM users WHERE id = ?', [123]);
+const users = await getCacheQuery<User>('SELECT * FROM users WHERE id = ?', [123], 'user:123'); // User[]
 
 await withTransaction(async (tx: TransactionContext) => {
   const result = await tx.query<{ insertId: number }>('INSERT INTO users...', [data]);
@@ -264,27 +297,42 @@ await withTransaction(async (tx: TransactionContext) => {
 });
 ```
 
+v2.9.1'den itibaren isimli import'lar native ESM'de de çalışır (`import { getCacheQuery } from
+'sqlcache'`) ve `import sqlcache from 'sqlcache'` için `esModuleInterop` gerekmez. 2.9.0 ve öncesinde
+native ESM'de varsayılan import'u (`import sqlcache from 'sqlcache'`) kullanın.
+
 ---
 
 ## ⚠️ Önemli Notlar
 
 * Okuma ağırlıklı sistemler için idealdir
-* Varsayılan TTL: 40.000 saniye (~11 saat)
+* Varsayılan TTL: 40.000 saniye (~11 saat); çağrı başına TTL yoktur
+* Cache isabetleri JSON'dan döner: `Date` ISO metne, `Buffer` `{ type, data }` nesnesine dönüşür;
+  cache'te bulunmayıp MySQL'den okunan sonuçlar ise mysql2 tiplerini taşır
 * `REDIS_ENABLED=false` ile cache devre dışı bırakılabilir
-* Transaction içinde `tx.query()` kullanarak veri bütünlüğü sağlanır
+* Transaction içinde kararı etkileyen okumalar için `tx.query()` kullanın: `tx.getCacheQuery()` önce
+  cache'e bakar (v2.9.1'den itibaren okuduğunu yalnızca commit'ten sonra cache'e yazar)
+* `bulkInsert` tablo adını ve ilk kaydın anahtarlarını (sütun adları) SQL'e olduğu gibi koyar:
+  istek veya CSV verisini sabit bir sütun listesine eşleyin
+* Çok kiracılı uygulamalarda kiracıyı oturumdan alıp izin listesiyle doğrulayın, `database`
+  parametresini çağrı başına verin; `REDIS_VHOST` değerini istek başına değiştirmeyin
+* Redis güvenilen bir depodur: AUTH ve özel ağ kullanın. `resetCacheName` / `delPrefixKeyItem`
+  önekleri Redis glob desenidir; kullanıcı girdisindeki `* ? [ ] \` karakterlerini kaçırın
+* mysql2 hataları parametre değerleri doldurulmuş `err.sql` içerir; hata nesnelerini güvenmediğiniz
+  log'lara veya istemcilere göndermeyin
 
 ---
 
 ## 🤝 Katkıda Bulunma
 
 Katkılar memnuniyetle karşılanır!
-Ayrıntılar için [CONTRIBUTING.md](../CONTRIBUTING.md) dosyasına göz atın.
+Ayrıntılar için [CONTRIBUTING.md](CONTRIBUTING.md) dosyasına göz atın.
 
 ---
 
 ## 📄 Lisans
 
-MIT © [Ali Hayati Keleş](https://github.com/hayatialikeles)
+MIT © [Hayati Ali Keleş](https://github.com/hayatialikeles)
 
 ---
 

package/docs/USE-CASE-BULK.md

@@ -1,16 +1,29 @@
 # Bulk Operations Use Case
 
+`bulkInsert` takes its columns from the keys of the first record and puts the table and column
+names into the SQL as-is (since v2.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, as below.
+
+Without `transaction: true`, each chunk commits on its own and a connection error retries from the
+first unacknowledged chunk, so a chunk can be inserted twice. With `transaction: true`, all chunks
+commit together; an error from `COMMIT` is not retried and carries `err.commitOutcomeUnknown = true`.
+
 ## Import Large Dataset
 
 ```javascript
 const { bulkInsert } = require('sqlcache');
 
 app.post('/import/products', async (req, res) => {
-    const products = req.body.products; // 100K+ records
+    // Copy only the known columns: bulkInsert uses the first record's keys as column names
+    const products = req.body.products.map(p => ({ // 100K+ records
+        sku: String(p.sku),
+        name: String(p.name),
+        price: Number(p.price)
+    }));
 
     const result = await bulkInsert('products', products, {
         chunkSize: 1000,           // Insert 1000 at a time
-        resetCacheName: 'products' // Clear product cache after
+        resetCacheName: 'products' // Clear product cache after (every key starting with "products")
     });
 
     res.json({
@@ -33,12 +46,17 @@ setInterval(async () => {
     const events = eventBuffer;
     eventBuffer = [];
 
-    await bulkInsert('analytics_events', events, {
-        chunkSize: 5000
-    });
+    try {
+        await bulkInsert('analytics_events', events, {
+            chunkSize: 5000
+        });
+    } catch (err) {
+        // An unhandled rejection would stop the process; log without err.sql (it holds the values)
+        console.error('Event flush failed:', err.code, err.message);
+    }
 }, 10000);
 
-// Track event
+// Track event (the record has fixed keys; only the values come from the request)
 app.post('/track', (req, res) => {
     eventBuffer.push({
         event_type: req.body.type,
@@ -56,17 +74,29 @@ app.post('/track', (req, res) => {
 const csv = require('csv-parser');
 const fs = require('fs');
 
+// The only columns written. The keys of a parsed CSV row come from the uploaded file's
+// header line, so they must never reach bulkInsert as they are.
+const IMPORT_COLUMNS = ['name', 'email', 'city'];
+
 app.post('/import/csv', async (req, res) => {
     const records = [];
 
     fs.createReadStream(req.file.path)
         .pipe(csv())
-        .on('data', (row) => records.push(row))
+        .on('data', (row) => {
+            const record = {};
+            for (const column of IMPORT_COLUMNS) record[column] = row[column] ?? null;
+            records.push(record);
+        })
         .on('end', async () => {
-            const result = await bulkInsert('imports', records, {
-                chunkSize: 2000
-            });
-            res.json(result);
+            try {
+                const result = await bulkInsert('imports', records, {
+                    chunkSize: 2000
+                });
+                res.json(result);
+            } catch (err) {
+                res.status(500).json({ error: 'Import failed' });
+            }
         });
 });
 ```
@@ -80,11 +110,12 @@ app.post('/import/csv', async (req, res) => {
 | 100K+ | 5000 | High |
 
 ```javascript
-// For very large imports, process in streams
-const chunkSize = 5000;
-for (let i = 0; i < records.length; i += chunkSize) {
-    const chunk = records.slice(i, i + chunkSize);
-    await bulkInsert('table', chunk);
-    console.log(`Processed ${i + chunk.length}/${records.length}`);
+// For very large imports, insert in batches to report progress
+// (each bulkInsert call is retried and invalidated on its own)
+const batchSize = 5000;
+for (let i = 0; i < records.length; i += batchSize) {
+    const batch = records.slice(i, i + batchSize);
+    await bulkInsert('table', batch);
+    console.log(`Processed ${i + batch.length}/${records.length}`);
 }
 ```

package/docs/USE-CASE-ECOMMERCE.md

@@ -1,5 +1,8 @@
 # E-Commerce Use Case
 
+The writes below rely on automatic invalidation, so set `CORE_AUTO_INVALIDATION=true` (it is not
+enabled by `CORE_AUTO_FEATURES`, which only generates cache keys).
+
 ## Order Creation with Transaction
 
 ```javascript
@@ -42,7 +45,9 @@ const { getCacheQuery } = require('sqlcache');
 
 app.get('/products', async (req, res) => {
     const products = await getCacheQuery(
-        'SELECT * FROM products WHERE active = 1 ORDER BY created_at DESC'
+        'SELECT * FROM products WHERE active = 1 ORDER BY created_at DESC',
+        [],
+        'products:active' // under products:, so product writes clear it
     );
     res.json(products);
 });
@@ -64,4 +69,5 @@ app.post('/cart/add', async (req, res) => {
 
 - **Transaction**: Order + items + stock update all succeed or all fail
 - **Cache**: Product listings served from Redis
-- **Auto-invalidation**: Cart/product changes clear related cache
+- **Auto-invalidation** (`CORE_AUTO_INVALIDATION=true`): writes to `cart` and `products` clear
+  `cart:*`/`cart_*` and `products:*`/`products_*`; inside the transaction, after the commit

package/docs/USE-CASE-REALTIME.md

@@ -1,9 +1,14 @@
 # Real-Time Apps Use Case
 
+These examples omit cache names and invalidation prefixes, so they need both
+`CORE_AUTO_FEATURES=true` (automatic keys) and `CORE_AUTO_INVALIDATION=true` (automatic
+invalidation). Without the second, new messages would not show up until the cached list expires
+(40000 s).
+
 ## Chat Messages
 
 ```javascript
-const { getCacheQuery, QuaryCache } = require('sqlcache');
+const { getCacheQuery, QuaryCache, getArrayItem, addArrayItem } = require('sqlcache');
 
 // Get messages (cached)
 app.get('/chat/:roomId/messages', async (req, res) => {
@@ -58,7 +63,8 @@ app.post('/notifications/:id/read', async (req, res) => {
 ## Online Status
 
 ```javascript
-// Update last seen
+// Update last seen. With automatic invalidation every heartbeat clears all users:* and users_*
+// keys; if you cache other user queries, keep presence in a table of its own.
 app.post('/heartbeat', async (req, res) => {
     await QuaryCache(
         'UPDATE users SET last_seen = NOW() WHERE id = ?',
@@ -67,11 +73,17 @@ app.post('/heartbeat', async (req, res) => {
     res.json({ ok: true });
 });
 
-// Get online users (cached 30s)
+// Get online users, cached for 30 s. getCacheQuery has no per-call TTL (it caches for 40000 s),
+// so read with QuaryCache, which does not use the cache, and cache the rows by hand.
 app.get('/online', async (req, res) => {
-    const users = await getCacheQuery(
-        'SELECT id, name FROM users WHERE last_seen > DATE_SUB(NOW(), INTERVAL 5 MINUTE)'
-    );
+    let users = await getArrayItem('online-users');
+    if (users.length === 0) {
+        users = await QuaryCache(
+            'SELECT id, name FROM users WHERE last_seen > DATE_SUB(NOW(), INTERVAL 5 MINUTE)',
+            []
+        );
+        await addArrayItem('online-users', users, 30); // TTL in seconds
+    }
     res.json(users);
 });
 ```

package/docs/USE-CASE-SAAS.md

@@ -5,58 +5,67 @@
 ```javascript
 const { getCacheQuery, QuaryCache } = require('sqlcache');
 
-// Middleware: Extract tenant
+// Middleware: take the tenant from the authenticated session (set by your auth middleware)
+// and check it against an allowlist. Never build the database name from a raw request header.
+const TENANT_DATABASES = new Set(['tenant_1', 'tenant_2', 'tenant_3']);
+
 app.use((req, res, next) => {
-    req.tenantDb = `tenant_${req.headers['x-tenant-id']}`;
+    const tenantDb = req.user && `tenant_${req.user.tenantId}`;
+    if (!tenantDb || !TENANT_DATABASES.has(tenantDb)) {
+        return res.status(403).json({ error: 'Unknown tenant' });
+    }
+    req.tenantDb = tenantDb;
     next();
 });
 
-// Read from tenant database
+// Read from tenant database, cached under a tenant-prefixed name
 app.get('/users', async (req, res) => {
     const users = await getCacheQuery(
         'SELECT * FROM users WHERE active = 1',
         [],
-        null,
+        `${req.tenantDb}:users:active`,
         req.tenantDb  // 4th param = database
     );
     res.json(users);
 });
 
-// Write to tenant database
+// Write to tenant database and clear only this tenant's user caches
 app.post('/users', async (req, res) => {
     await QuaryCache(
         'INSERT INTO users (name, email) VALUES (?, ?)',
         [req.body.name, req.body.email],
-        null,
+        `${req.tenantDb}:users`,
         req.tenantDb
     );
     res.json({ success: true });
 });
 ```
 
+With automatic keys (`null` as the cache name and `CORE_AUTO_FEATURES=true`), keys end with
+`@<database>`, for example `users:active:all@tenant_1`, so tenants never share an entry; automatic
+invalidation then clears `users:*` of every tenant.
+
 ## Namespace per Tenant
 
 ```bash
-# .env
+# .env, only when each tenant runs in its own process
 REDIS_VHOST=tenant_123
 ```
 
-Or dynamically:
-
-```javascript
-// Each tenant gets isolated cache namespace
-process.env.REDIS_VHOST = `tenant_${tenantId}`;
-```
+`REDIS_VHOST` applies to the whole process. Never change it per request
+(`process.env.REDIS_VHOST = ...`): concurrent requests share it, so one tenant's request can read or
+write another tenant's entries. v2.9.1 logs a warning when it changes at runtime. Within one process,
+use the `database` argument and tenant-prefixed cache names as shown above.
 
 ## Cross-Tenant Admin Query
 
 ```javascript
 app.get('/admin/all-users', async (req, res) => {
-    const tenants = ['tenant_1', 'tenant_2', 'tenant_3'];
+    const tenants = [...TENANT_DATABASES];
 
     const results = await Promise.all(
         tenants.map(db =>
-            getCacheQuery('SELECT * FROM users', [], null, db)
+            getCacheQuery('SELECT * FROM users', [], `${db}:users:all`, db)
         )
     );