@motiontr/motiondb 1.0.0

package/README.md

@@ -0,0 +1,328 @@
+# motiondb
+
+Discord botları için **tek dosyalık, atomik ve hızlı** JSON veritabanı.
+`discord.js` ile birlikte kullanılmak üzere tasarlandı, ama framework'ten bağımsızdır.
+
+```json
+{
+  "guilds": {
+    "123456789012345678": { "prefix": "!", "welcome": { "channelId": "987654321098765432" } }
+  },
+  "users": {
+    "555555555555555555": { "coins": 250, "inventory": ["ticket", "vip"] }
+  },
+  "cooldowns": { "555555555555555555:daily": 1730000000000 }
+}
+```
+
+---
+
+## Kurulum
+
+```bash
+npm install
+npm run build        # TypeScript derleme -> dist/
+npm test             # 49 test (23 çekirdek + 26 API)
+npm run example      # examples/basic.js
+npm run example:api  # examples/api.js (MotionDB API turu)
+```
+
+Kendi projenizde:
+
+```bash
+npm install @motiontr/motiondb
+```
+
+```ts
+import { MotionDB, JSONDatabase } from '@motiontr/motiondb';
+
+const db = new JSONDatabase({ path: './data/db.json' });
+```
+
+---
+
+## MotionDB API (asenkron, tablo tabanlı)
+
+İkinci katman: tek JSON dosyasında **tablolar**, `await`'li ve dot-notation
+destekli arayüz. Discord botlarında kullanıcı/sunucu verisi için ideal:
+
+```ts
+import { MotionDB } from '@motiontr/motiondb';
+
+const db = new MotionDB({ filePath: './data.json' });
+await db.init();                                  // dosyayı yükler/oluşturur
+
+// ---- okuma / yazma ----
+await db.set('myKey', 'myValue');                 // → 'myValue'
+await db.get('myKey');                            // → 'myValue'
+await db.get('olmayan');                          // → null
+await db.has('myKey');                            // → true
+await db.delete('myKey');                         // → 1  (yoksa 0)
+await db.ensure('ayarlar', { prefix: '!' });      // yoksa oluşturur
+
+// ---- dot notation: iç içe nesneler ----
+await db.set('myUser.balance', 700);
+await db.get('myUser.balance');                   // → 700
+await db.get('myUser');                           // → { balance: 700 }
+
+// ---- sayılar ----
+await db.add('myUser.balance', 100);              // → 800
+await db.sub('myUser.balance', 50);               // → 750
+await db.increment('sayac', 1);                   // → add kısayolu
+await db.decrement('sayac', 1);                   // → sub kısayolu
+
+// ---- diziler ----
+await db.set('myUser.items', ['Sword', 'Shield']);
+await db.push('myUser.items', 'Armor');           // → [..., 'Armor']
+await db.unshift('myUser.items', 'Helm');         // → başa ekler
+await db.pull('myUser.items', 'Shield');          // → siler
+await db.pull('myUser.items', (i) => i.length < 5, true); // once: ilk eşleşen
+await db.pop('myUser.items');                     // → son eleman
+await db.shift('myUser.items');                   // → ilk eleman
+
+// ---- sorgular ----
+await db.all();                                   // → [{ id, value }, ...]
+await db.startsWith('userInfo_');                 // → [{ id, value }, ...]
+await db.startsWith('x', 'bazıSatırListesi');     // → ikinci parametre anahtar
+await db.count();                                 // → satır sayısı
+
+// ---- tablolar (aynı dosyada ayrı bölüm) ----
+const guilds = db.table('guilds');
+await guilds.set('1552239063984246784.prefix', '!');
+await db.deleteAll();                             // → silinen satır sayısı
+db.useNormalKeys(true);                           // nokta literal anahtar yapsın
+```
+
+### Seçenekler
+
+```ts
+new MotionDB({
+  filePath: './data.json', // dosya yolu (varsayılan './data.json')
+  table: 'json',           // kök bölüm adı (varsayılan 'json')
+  normalKeys: false,       // true ise nokta ayracı değil, literal anahtar
+  deferWrites: false,      // true ise diske yazmayı erteler → flush() gerekir
+  spaces: 2,               // JSON girintisi
+  onCorrupt: 'throw',      // 'throw' | 'reset'
+});
+```
+
+### Metot özeti
+
+| Kategori | Metot | Dönüş |
+| --- | --- | --- |
+| Okuma | `get(key)` | değer veya `null` |
+| | `has(key)` | `boolean` |
+| | `all()` | `{ id, value }[]` |
+| | `startsWith(query, key?)` | `{ id, value }[]` |
+| | `count()` | `number` |
+| Yazma | `set(key, value)` | yazılan değer |
+| | `ensure(key, varsayılan)` | değer |
+| | `delete(key)` | `1` / `0` |
+| | `deleteAll()` | silinen satır sayısı |
+| Sayı | `add`, `sub`, `increment`, `decrement` | yeni sayı |
+| Dizi | `push`, `unshift`, `pop`, `shift`, `pull` | dizi / eleman |
+| Tablo | `table(name)` | yeni `MotionDB` |
+| | `createSingleton(options)` | tek instance |
+| | `useNormalKeys(bool)` | `void` |
+| Kalıcılık | `init()`, `flush()`, `flushSync()` | — |
+| Olay | `on('save' \| 'load' \| 'change' \| 'error', fn)` | `this` |
+
+**Hata mesajları** (geçersiz kullanımda):
+
+- `First argument (key) needs to be a string`
+- `Missing second argument (value)` (`set(key, null)` gibi)
+- `Current value with key: (x) is not an array` (`push` ile dizi olmayana)
+- `Current value with key: (x) is not a number...` (`add` ile sayı olmayana)
+
+**Dosya biçimi**
+
+```json
+{
+  "json":   { "myKey": "myValue", "myUser": { "balance": 750 } },
+  "guilds": { "1552239063984246784": { "prefix": "!" } }
+}
+```
+
+> Aynı dosyayı paylaşan tüm `MotionDB` instance'ları (`table()` dahil) tek
+> motor kullanır; birbirinin yazdığını silmezler.
+> `deferWrites: true` ile her işlemde diske yazmayı erteleyip toplu işlerde
+> `await db.flush()` çağırabilirsiniz.
+
+---
+
+## Hızlı başlangıç
+
+```ts
+const db = new JSONDatabase({ path: './data/db.json' });
+db.registerShutdownHooks(); // kapanışta bekleyen yazışları diske atar
+
+// oku / yaz (dot-path)
+db.set('guilds.123456789012345678.prefix', '!');
+db.get('guilds.123456789012345678.prefix');      // '!'
+db.get('guilds.olmayan.prefix', '?');             // '?'  (fallback)
+
+// yoksa oluştur
+db.ensure('users.555555555555555555', { coins: 0, inventory: [] });
+
+// sayaç
+db.increment('users.555555555555555555.coins', 250);
+
+// dizi
+db.push('guilds.123.roles.moderator', '111111111111111111');
+db.pull('guilds.123.roles.moderator', '111111111111111111');
+
+// sil / kontrol
+db.has('users.555555555555555555');   // true
+db.delete('users.555555555555555555.oldKey');
+```
+
+---
+
+## Seçenekler
+
+```ts
+new JSONDatabase({
+  path: './data/bot.json', // dosya yolu (varsayılan './db.json')
+  spaces: 2,               // girinti sayısı (varsayılan 2)
+  debounce: 50,            // değişiklikten sonra yazma gecikmesi ms (varsayılan 50)
+  autosave: true,          // false ise yalnızca save()/flushSync() yazar
+  createIfMissing: true,   // dosya yoksa oluştur
+  onCorrupt: 'throw',      // 'throw' | 'reset' (bozuk dosyayı yedekleyip sıfırlar)
+  backupOnLoad: false,     // ilk yüklemde otomatik yedek al
+  backupDir: './data/backups',
+});
+```
+
+> `debounce: 0` yaparsanız her değişiklikte anında yazar. Varsayılan `50` ms,
+> bir komut içindeki 50 yazımı tek dosya işlemine indirger.
+
+---
+
+## API
+
+### Okuma
+
+| Metod | Açıklama |
+| --- | --- |
+| `get(path, fallback?)` | Değeri okur, yoksa `fallback` döner |
+| `has(path)` | Yol var mı? |
+| `all()` | Kök nesnenin canlı referansı |
+| `toJSON()` | Kök nesnenin kopyası |
+| `keys()` | Kök kategoriler (`['guilds', 'users', ...]`) |
+| `category(name, fallback?)` | Bir kategorinin tamamı (`db.category('guilds')`) |
+
+### Yazma
+
+| Metod | Açıklama |
+| --- | --- |
+| `set(path, value)` | Değer yazar |
+| `ensure(path, defaultValue)` | Yoksa oluşturur, varsa mevcut değeri döner |
+| `delete(path)` | Anahtarı siler, silindiyse `true` |
+| `push(path, ...values)` | Diziye ekler (dizi yoksa oluşturur) |
+| `pull(path, value \| fn)` | Diziden eşleşeni çıkarır (derin karşılaştırma) |
+| `increment(path, amount?)` | Sayısal değeri artırır, yeni değeri döner |
+| `decrement(path, amount?)` | Sayısal değeri azaltır |
+| `edit(fn, path?)` | Ham düzenleme — verinin tamamına erişip değiştirin |
+| `clear()` | Tüm veriyi siler |
+
+### Path sözdizimi
+
+```ts
+db.get('guilds.123.prefix');              // nokta ile
+db.get('items[0].name');                  // dizi indeksi
+db.get('users["a.b"].coins');             // nokta içeren anahtar
+db.get(['users', 'a.b', 'coins']);        // segment dizisi (en hızlısı)
+```
+
+> **Not:** Discord snowflake ID'leri `Number`'a çevrilmez (yok olurlardı),
+> tüm segmentler string olarak tutulur.
+
+### Kalıcılık
+
+| Metod | Açıklama |
+| --- | --- |
+| `save()` / `flush()` | Değişiklikleri atomik olarak yazar (Promise) |
+| `flushSync()` | Anında senkron yazar — çıkış öncesi çağırın |
+| `load(force?)` | Dosyayı okur (ilk çağrıda otomatik) |
+| `reload()` | Bellek değişimlerini atıp dosyayı yeniden okur |
+| `registerShutdownHooks()` | `SIGINT`/`SIGTERM`/`exit` → `flushSync()` |
+
+### Yedekleme
+
+```ts
+const file = db.backup('before-migration'); // path döner
+db.listBackups();                           // yeniden eskiye tüm yedekler
+```
+
+### Olaylar
+
+```ts
+db.on('change', (c) => console.log(c.type, c.path.join('.'))); // set | delete | clear | edit
+db.on('save', (file) => console.log('yazıldı:', file));
+db.on('load', (file) => console.log('yüklendi:', file));
+db.on('corrupt', (backupPath) => console.log('bozuk dosya yedeklendi:', backupPath));
+db.on('error', (err) => console.error(err)); // yazma hataları
+```
+
+---
+
+## discord.js örneği
+
+```ts
+import { Client, GatewayIntentBits, Events } from 'discord.js';
+import { JSONDatabase } from '@motiontr/motiondb';
+
+const db = new JSONDatabase({ path: './data/db.json', backupOnLoad: true });
+db.registerShutdownHooks();
+
+const client = new Client({
+  intents: [GatewayIntentBits.Guilds, GatewayIntentBits.GuildMessages, GatewayIntentBits.MessageContent],
+});
+
+client.on(Events.MessageCreate, (message) => {
+  if (message.author.bot || !message.guild) return;
+
+  const prefix = db.get(`guilds.${message.guild.id}.prefix`, '!');
+  if (!message.content.startsWith(prefix)) return;
+
+  const [cmd, ...args] = message.content.slice(prefix.length).trim().split(/\s+/);
+
+  if (cmd === 'prefix') {
+    db.set(`guilds.${message.guild.id}.prefix`, args[0]);
+    message.reply(`Ön ek ${args[0]} olarak ayarlandı.`);
+  }
+});
+```
+
+---
+
+## Sınırlar ve iyi pratikler
+
+- **Tek süreç içindir.** Aynı dosyayı 2+ process (ör. shard cluster) aynı anda
+  yazarsa son yazan kazanır. Sharding yapıyorsanız process başına ayrı dosya
+  (`data/shard-0.json`) veya harici bir DB (SQLite/Redis) kullanın.
+- **Orta ölçek için uygundur:** birkaç MB'a kadar veri rahatça çalışır;
+- tüm veri bellekte tutulur, okuma O(1)'dir, yazma ise atomiktir
+  (tmp dosya + `rename`, yarım kayıt olmaz).
+- **Büyük veritabanlarda** (on binlerce sunucu + yüksek write I/O) JSON yerine
+  SQLite geçmeyi düşünün.
+- Process `SIGKILL` ile öldürülürse son `debounce` penceresindeki değişiklikler
+  kaybolabilir; kritik işlemlerden sonra `await db.flush()` çağırın.
+
+---
+
+## Proje yapısı
+
+```
+src/
+  index.ts        dışa aktarımlar (MotionDB, JSONDatabase)
+  MotionDB.ts     asenkron tablo API (get/set/push/pull/table/all/...)
+  Database.ts     JSONDatabase çekirdeği (atomik yazma, yedek, olaylar)
+  path.ts         dot-path çözümleyici ve okuma/yazma yardımcıları
+examples/
+  basic.js        çekirdek database özellikleri turu
+  api.js          MotionDB API turu
+tests/
+  db.test.js        `npm test` — 23 test (çekirdek)
+  motiondb.test.js  `npm test` — 26 test (API)
+```

package/dist/Database.d.ts

@@ -0,0 +1,137 @@
+import { EventEmitter } from 'node:events';
+import { PathInput, PathSegment } from './path';
+export type CorruptPolicy = 'throw' | 'reset';
+export interface DatabaseOptions {
+    /** JSON dosyasının yolu. Varsayılan: `./db.json` */
+    path?: string;
+    /** Kaydedilirken kullanılacak girinti (boşluk) sayısı. Varsayılan: `2` */
+    spaces?: number;
+    /**
+     * Değişiklikten sonra dosyaya yazılana kadar beklenecek süre (ms).
+     * `0` ise her değişiklikte anında yazar. Varsayılan: `50`
+     */
+    debounce?: number;
+    /** `false` ise dosya yalnızca `save()` / `flushSync()` çağrısında yazılır. Varsayılan: `true` */
+    autosave?: boolean;
+    /** Dosya yoksa oluştur. Varsayılan: `true` */
+    createIfMissing?: boolean;
+    /** JSON bozulursa ne yapılsın: fırlat (`throw`) veya yedekleyip sıfırla (`reset`). Varsayılan: `throw` */
+    onCorrupt?: CorruptPolicy;
+    /** İlk yüklemeden önce otomatik yedek al. Varsayılan: `false` */
+    backupOnLoad?: boolean;
+    /** Yedek dosyalarının konacağı klasör. Varsayılan: dosyanın yanındaki `backups/` */
+    backupDir?: string;
+}
+export interface DatabaseChange {
+    type: 'set' | 'delete' | 'clear' | 'edit';
+    path: PathSegment[];
+    value?: unknown;
+}
+export interface DatabaseEvents {
+    change: [DatabaseChange];
+    save: [string];
+    load: [string];
+    corrupt: [string];
+    error: [Error];
+}
+/**
+ * Tek dosyalık, bellekte çalışan JSON veritabanı.
+ *
+ * Veri tek bir JSON dosyasında "kategoriler" halinde tutulur:
+ * `{ "guilds": {...}, "users": {...}, "cooldowns": {...} }`
+ *
+ * - Tüm değişiklikler bellekte yapılır (çok hızlı), dosyaya atomik yazılır.
+ * - Yazma işlemi tmp dosya + `rename` ile yapılır, bu sayede yarım kayıt riski yoktur.
+ */
+export declare class JSONDatabase<T extends object = Record<string, unknown>> extends EventEmitter {
+    /** Veri dosyasının mutlak yolu */
+    readonly file: string;
+    /** Yedek dosyalarının klasörü */
+    readonly backupDir: string;
+    private readonly spaces;
+    private readonly debounceMs;
+    private readonly autosave;
+    private readonly createIfMissing;
+    private readonly corruptPolicy;
+    private readonly backupOnLoad;
+    private store;
+    private loaded;
+    private dirty;
+    private timer;
+    private chain;
+    constructor(options?: DatabaseOptions);
+    /** Dosyayı okur. İlk çağrıda otomatik olarak yapılır. */
+    load(force?: boolean): this;
+    /** Bellekteki değişiklikleri atıp dosyayı yeniden okur. */
+    reload(): this;
+    private handleCorrupt;
+    /** Değişiklikleri diske yazar (atomik). Yazma sırası korunur. */
+    save(): Promise<void>;
+    /** `save()` kısayolu. */
+    flush(): Promise<void>;
+    /** Değişiklikleri hemen senkron olarak diske yazar (ör. kapanış öncesi). */
+    flushSync(): this;
+    private write;
+    private writeSync;
+    private markDirty;
+    /** Yazmayı planlar: `debounce` süresi içindeki tüm değişiklikler tek dosyaya yazılır. */
+    private scheduleSave;
+    private cancelTimer;
+    private handleError;
+    /** Bir değeri okur. Bulunamazsa `fallback` döner. */
+    get<D = unknown>(key: PathInput, fallback?: D): D;
+    /** Bir değeri yazar ve diske kaydeder. */
+    set(key: PathInput, value: unknown): this;
+    /** Yol var mı? (undefined olmayan değer) */
+    has(key: PathInput): boolean;
+    /** Bir anahtarı siler. Silindiyse `true` döner. */
+    delete(key: PathInput): boolean;
+    /** Değer yoksa varsayılanı yazar ve onu döner (varsayılan nesneler için ideal). */
+    ensure<D>(key: PathInput, defaultValue: D): D;
+    /** Dizinin sonuna değer(ler) ekler. Dizi yoksa oluşturur. */
+    push<D>(key: PathInput, ...values: D[]): D[];
+    /** Diziden eşleşen değeri(leri) çıkarır. Fonksiyon verilirse predicate olarak kullanılır. */
+    pull(key: PathInput, matcher: unknown | ((value: unknown) => boolean)): unknown[];
+    /** Sayısal değeri artırır/sıfırlar. Yeni değeri döner. */
+    increment(key: PathInput, amount?: number): number;
+    /** Sayaç azaltma kısayolu. */
+    decrement(key: PathInput, amount?: number): number;
+    /** Kök nesnenin tamamını döner (canlı referans). */
+    all(): T;
+    /** Kök nesnenin kopyasını döner. */
+    toJSON(): T;
+    /** Kök anahtarların listesi (kategoriler). */
+    keys(): string[];
+    /** Bir kategorinin (ör. `guilds`) tamamını döner. */
+    category<D = Record<string, unknown>>(name: string, fallback?: D): D;
+    /** Tüm veriyi temizler (dosyayı boşaltır). */
+    clear(): this;
+    /**
+     * Ham düzenleme: verinin tamamına erişip doğrudan değiştirin.
+     * `path` verilmezse tüm kök değişim olarak işaretlenir.
+     *
+     * ```ts
+     * db.edit((data) => {
+     *   data.guilds ??= {};
+     *   data.guilds[id].prefix = '!';
+     * });
+     * ```
+     */
+    edit<D = T>(mutator: (data: D) => void, key?: PathInput): this;
+    /**
+     * Mevcut dosyanın kopyasını alır ve yedek yolunu döner.
+     * @param label Dosya adına eklenecek etiket (ör. `"before-migration"`).
+     */
+    backup(label?: string): string;
+    /** Var olan tüm yedek dosyalarını (yeniden eskiye) listeler. */
+    listBackups(): string[];
+    /**
+     * `SIGINT` / `SIGTERM` / `exit` anlarında bekleyen değişiklikleri diske yazar.
+     * Botunuzda bir kez çağırın.
+     */
+    registerShutdownHooks(): this;
+    on<K extends keyof DatabaseEvents>(event: K, listener: (...args: DatabaseEvents[K]) => void): this;
+    on(event: string | symbol, listener: (...args: any[]) => void): this;
+    emit<K extends keyof DatabaseEvents>(event: K, ...args: DatabaseEvents[K]): boolean;
+    emit(event: string | symbol, ...args: any[]): boolean;
+}