qumra-pos-storage 0.1.0

package/README.md

@@ -0,0 +1,128 @@
+# qumra-pos-storage
+
+Offline-first storage core for POS and local-first apps. All the logic lives in the
+core; the SQLite engine is a **swappable adapter**, so the same schema, migrations,
+repositories, outbox and sync engine run on **React Native, Web, Desktop (Electron)
+and Node** — you only pick the adapter per platform.
+
+Zero dependency on any other `@qumra` package. Only runtime dep is `uuidv7`.
+
+## Install
+
+```bash
+npm i qumra-pos-storage
+# or
+yarn add qumra-pos-storage
+# or
+pnpm add qumra-pos-storage
+```
+
+Then add the driver for your platform (only the one you use):
+
+| Platform | Driver (install yourself) | Import |
+| --- | --- | --- |
+| Node / Electron (main) | `better-sqlite3` | `qumra-pos-storage/better-sqlite3` |
+| React Native | `@op-engineering/op-sqlite` | `qumra-pos-storage/op-sqlite` |
+| Web | `wa-sqlite` (or any wasm SQLite) | `qumra-pos-storage/wa-sqlite` |
+
+`better-sqlite3` is an **optional peer dependency** — install it only for the Node/Electron adapter.
+
+## Quick start (Node / Electron)
+
+```ts
+import { createStorage } from "qumra-pos-storage";
+import { BetterSqlite3Adapter } from "qumra-pos-storage/better-sqlite3";
+
+const storage = await createStorage(
+  BetterSqlite3Adapter.open({ filename: "/path/to/pos.db" }),
+);
+
+const shift = await storage.shifts.open({ cashierId, openingCash: 10000 });
+await storage.orders.create({
+  shiftId: shift.id,
+  cashierId,
+  items: [{ productId, nameSnapshot: "Coffee", unitPrice: 2500, qty: 2 }],
+  payments: [{ method: "cash", amount: 5000 }],
+});
+```
+
+### React Native (op-sqlite) & Web (wa-sqlite)
+
+These adapters take a driver **you open and inject**, so the package never imports the
+native/wasm libraries directly:
+
+```ts
+// React Native
+import { open } from "@op-engineering/op-sqlite";
+import { openOpSqliteAdapter } from "qumra-pos-storage/op-sqlite";
+const storage = await createStorage(openOpSqliteAdapter(open({ name: "pos.db" })));
+
+// Web — wrap your wa-sqlite instance in a small { exec(sql, params) } object
+import { openWaSqliteAdapter } from "qumra-pos-storage/wa-sqlite";
+const storage = await createStorage(openWaSqliteAdapter(myWaSqliteDb));
+```
+
+## What you get
+
+- **`StorageAdapter` port** — four async methods (`execute`, `query`, `transaction`, `close`). Implement it once to support any engine.
+- **Schema + forward-only migrations** — `_migrations` bookkeeping, idempotent.
+- **Repositories** — `shifts`, `orders`, `products`, `reports`, `outbox`.
+- **Invariants enforced in the core** (not the UI): every write enqueues a `pending_operations` outbox row **in the same transaction**; `orders.create` rejects unless `sum(payments) === total`; money is integer piasters; IDs are UUIDv7 (chronological); items snapshot name + price at sale time.
+- **Sync engine** — `SyncEngine` drains the outbox (batched, idempotent, exponential backoff + jitter) and pulls reference data (delta + tombstones). **It never talks to your server** — you inject a `SyncTransport`.
+- **Conformance suite** — `qumra-pos-storage/conformance` exposes a battery every adapter must pass, so a new adapter is provably correct.
+
+## Sync engine — you own the network
+
+The engine handles batching, idempotency, UUIDv7 ordering, backoff and the outbox. It has
+**zero endpoint code**: you inject a `SyncTransport` (REST, GraphQL — your choice) and you
+hand it the auth token. The library takes a token from you and never contacts an auth
+server.
+
+```ts
+import { SyncEngine, SyncNetworkError, type SyncTransport } from "qumra-pos-storage";
+
+const transport: SyncTransport = {
+  // push the outbox — return one result per op: applied | duplicate | rejected
+  async pushBatch(ops, ctx) {
+    const res = await fetch("https://your-api/whatever", {
+      method: "POST",
+      headers: { "content-type": "application/json", authorization: `Bearer ${ctx.token}` },
+      body: JSON.stringify({ operations: ops }),
+    });
+    if (!res.ok) throw new SyncNetworkError(`HTTP ${res.status}`); // retryable → backoff
+    return res.json(); // { results: [{ idempotency_key, status, error? }] }
+  },
+  async pullDelta(resource, since, cursor, ctx) {
+    // your GET / GraphQL query …
+    return { changed: [], deleted: [], cursor: "", hasMore: false };
+  },
+};
+
+const engine = new SyncEngine(storage, {
+  transport,
+  getAuthToken: () => myToken, // ← you provide the token; null ⇒ sync pauses (not an error)
+});
+engine.start();
+engine.onStatusChange((s) => renderBar(s)); // { online, paused, pendingCount, failedOps, ... }
+```
+
+Rules: **throw** on network / 5xx (retryable, backoff); return a per-op
+`status: "rejected"` for a permanent business rejection (surfaces to the manager, the rest
+still syncs). REST vs GraphQL is entirely your call — the engine doesn't care.
+
+## Testing / adding an adapter
+
+```ts
+import { describe, it } from "vitest";
+import { runAdapterConformance } from "qumra-pos-storage/conformance";
+import { BetterSqlite3Adapter } from "qumra-pos-storage/better-sqlite3";
+
+runAdapterConformance("my-adapter", () => BetterSqlite3Adapter.open(), { describe, it });
+```
+
+## Publishing
+
+Ships dual **ESM + CJS + `.d.ts`** (built with tsup). To publish under a different name,
+change `name` in `package.json`. `npm publish` builds `dist` via `prepublishOnly`.
+
+MIT.

package/dist/StorageAdapter-B2IgHcUF.d.cts

@@ -0,0 +1,27 @@
+/**
+ * العقد الوحيد اللي كل محرك على أي منصة لازم يطبّقه. أربع دوال بس، مفيش أكتر.
+ *
+ * كل حاجة async حتى لو المحرك متزامن (better-sqlite3)، لأن wa-sqlite و op-sqlite
+ * async بطبيعتهم — التوحيد أهم من الأداء الطفيف هنا.
+ *
+ * دالتي execute/query مشتركة بين الـ adapter نفسه والـ Tx اللي بيتسلّم لدالة الـ
+ * transaction، فالـ repositories بتشتغل بنفس الكود جوه أو برا transaction.
+ */
+type SqlParam = string | number | bigint | null | Uint8Array;
+interface Tx {
+    /**
+     * تنفيذ أمر من غير نتيجة راجعة.
+     * - مع params: أمر واحد بمعاملات (prepare + run).
+     * - من غير params: ممكن يحتوي أكتر من أمر (بتستخدمها الـ migrations / DDL).
+     */
+    execute(sql: string, params?: SqlParam[]): Promise<void>;
+    /** تنفيذ استعلام وإرجاع كل الصفوف. استعلامات بمعاملات فقط — ممنوع string interpolation. */
+    query<T = Record<string, unknown>>(sql: string, params?: SqlParam[]): Promise<T[]>;
+}
+interface StorageAdapter extends Tx {
+    /** تنفيذ fn جوه transaction واحدة atomic. أي throw بيعمل rollback للكل. */
+    transaction<T>(fn: (tx: Tx) => Promise<T>): Promise<T>;
+    close(): Promise<void>;
+}
+
+export type { SqlParam as S, Tx as T, StorageAdapter as a };

package/dist/StorageAdapter-B2IgHcUF.d.ts

@@ -0,0 +1,27 @@
+/**
+ * العقد الوحيد اللي كل محرك على أي منصة لازم يطبّقه. أربع دوال بس، مفيش أكتر.
+ *
+ * كل حاجة async حتى لو المحرك متزامن (better-sqlite3)، لأن wa-sqlite و op-sqlite
+ * async بطبيعتهم — التوحيد أهم من الأداء الطفيف هنا.
+ *
+ * دالتي execute/query مشتركة بين الـ adapter نفسه والـ Tx اللي بيتسلّم لدالة الـ
+ * transaction، فالـ repositories بتشتغل بنفس الكود جوه أو برا transaction.
+ */
+type SqlParam = string | number | bigint | null | Uint8Array;
+interface Tx {
+    /**
+     * تنفيذ أمر من غير نتيجة راجعة.
+     * - مع params: أمر واحد بمعاملات (prepare + run).
+     * - من غير params: ممكن يحتوي أكتر من أمر (بتستخدمها الـ migrations / DDL).
+     */
+    execute(sql: string, params?: SqlParam[]): Promise<void>;
+    /** تنفيذ استعلام وإرجاع كل الصفوف. استعلامات بمعاملات فقط — ممنوع string interpolation. */
+    query<T = Record<string, unknown>>(sql: string, params?: SqlParam[]): Promise<T[]>;
+}
+interface StorageAdapter extends Tx {
+    /** تنفيذ fn جوه transaction واحدة atomic. أي throw بيعمل rollback للكل. */
+    transaction<T>(fn: (tx: Tx) => Promise<T>): Promise<T>;
+    close(): Promise<void>;
+}
+
+export type { SqlParam as S, Tx as T, StorageAdapter as a };

package/dist/better-sqlite3.cjs

@@ -0,0 +1,96 @@
+'use strict';
+
+var Database = require('better-sqlite3');
+
+function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
+
+var Database__default = /*#__PURE__*/_interopDefault(Database);
+
+// src/adapters/better-sqlite3/index.ts
+var Executor = class {
+  constructor(db) {
+    this.db = db;
+  }
+  db;
+  /**
+   * تنفيذ أوامر:
+   * INSERT
+   * UPDATE
+   * DELETE
+   * CREATE TABLE6
+   * ALTER TABLE
+   *
+   * إذا تم تمرير معاملات (params) يتم استخدام prepare().run().
+   * أما إذا لم توجد معاملات يتم استخدام exec() للسماح بتنفيذ
+   * أكثر من SQL statement في نفس النص (مفيد للـ migrations).
+   */
+  async execute(sql, params) {
+    if (params && params.length > 0) {
+      this.db.prepare(sql).run(...params);
+    } else {
+      this.db.exec(sql);
+    }
+  }
+  /**
+   * تنفيذ استعلام SELECT وإرجاع النتائج كمصفوفة.
+   *
+   * مثال:
+   * SELECT * FROM products
+   * SELECT * FROM orders WHERE id = ?
+   */
+  async query(sql, params) {
+    const stmt = this.db.prepare(sql);
+    const rows = params && params.length > 0 ? stmt.all(...params) : stmt.all();
+    return rows;
+  }
+};
+var BetterSqlite3Adapter = class _BetterSqlite3Adapter extends Executor {
+  constructor(db) {
+    super(db);
+  }
+  /**
+   * فتح قاعدة البيانات وإنشاء الـ Adapter.
+   */
+  static open(options = {}) {
+    const db = new Database__default.default(options.filename ?? ":memory:");
+    db.pragma("foreign_keys = ON");
+    if (options.wal ?? Boolean(options.filename)) {
+      db.pragma("journal_mode = WAL");
+    }
+    return new _BetterSqlite3Adapter(db);
+  }
+  /**
+   * تنفيذ مجموعة عمليات داخل Transaction واحدة.
+   *
+   * إذا نجحت جميع العمليات:
+   *   COMMIT
+   *
+   * إذا فشلت أي عملية:
+   *   ROLLBACK
+   *
+   * ملاحظة:
+   * نستخدم BEGIN / COMMIT / ROLLBACK يدويًا
+   * بدل db.transaction() لأن الـ callback هنا async.
+   */
+  async transaction(fn) {
+    this.db.exec("BEGIN");
+    try {
+      const result = await fn(new Executor(this.db));
+      this.db.exec("COMMIT");
+      return result;
+    } catch (err) {
+      this.db.exec("ROLLBACK");
+      throw err;
+    }
+  }
+  /**
+   * إغلاق اتصال قاعدة البيانات وتحرير الموارد.
+   */
+  async close() {
+    this.db.close();
+  }
+};
+
+exports.BetterSqlite3Adapter = BetterSqlite3Adapter;
+//# sourceMappingURL=better-sqlite3.cjs.map
+//# sourceMappingURL=better-sqlite3.cjs.map

package/dist/better-sqlite3.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/adapters/better-sqlite3/index.ts"],"names":["Database"],"mappings":";;;;;;;;;AAWA,IAAM,WAAN,MAA6B;AAAA,EAC3B,YAA+B,EAAA,EAAuB;AAAvB,IAAA,IAAA,CAAA,EAAA,GAAA,EAAA;AAAA,EAAwB;AAAA,EAAxB,EAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAc/B,MAAM,OAAA,CAAQ,GAAA,EAAa,MAAA,EAAoC;AAC7D,IAAA,IAAI,MAAA,IAAU,MAAA,CAAO,MAAA,GAAS,CAAA,EAAG;AAC/B,MAAA,IAAA,CAAK,GAAG,OAAA,CAAQ,GAAG,CAAA,CAAE,GAAA,CAAI,GAAG,MAAM,CAAA;AAAA,IACpC,CAAA,MAAO;AACL,MAAA,IAAA,CAAK,EAAA,CAAG,KAAK,GAAG,CAAA;AAAA,IAClB;AAAA,EACF;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EASA,MAAM,KAAA,CACJ,GAAA,EACA,MAAA,EACc;AACd,IAAA,MAAM,IAAA,GAAO,IAAA,CAAK,EAAA,CAAG,OAAA,CAAQ,GAAG,CAAA;AAEhC,IAAA,MAAM,IAAA,GACJ,MAAA,IAAU,MAAA,CAAO,MAAA,GAAS,CAAA,GACtB,IAAA,CAAK,GAAA,CAAI,GAAG,MAAM,CAAA,GAClB,IAAA,CAAK,GAAA,EAAI;AAEf,IAAA,OAAO,IAAA;AAAA,EACT;AACF,CAAA;AAmCO,IAAM,oBAAA,GAAN,MAAM,qBAAA,SACH,QAAA,CAEV;AAAA,EACU,YAAY,EAAA,EAAuB;AACzC,IAAA,KAAA,CAAM,EAAE,CAAA;AAAA,EACV;AAAA;AAAA;AAAA;AAAA,EAKA,OAAO,IAAA,CACL,OAAA,GAAgC,EAAC,EACX;AACtB,IAAA,MAAM,EAAA,GAAK,IAAIA,yBAAA,CAAS,OAAA,CAAQ,YAAY,UAAU,CAAA;AAQtD,IAAA,EAAA,CAAG,OAAO,mBAAmB,CAAA;AAU7B,IAAA,IAAI,OAAA,CAAQ,GAAA,IAAO,OAAA,CAAQ,OAAA,CAAQ,QAAQ,CAAA,EAAG;AAC5C,MAAA,EAAA,CAAG,OAAO,oBAAoB,CAAA;AAAA,IAChC;AAEA,IAAA,OAAO,IAAI,sBAAqB,EAAE,CAAA;AAAA,EACpC;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAeA,MAAM,YACJ,EAAA,EACY;AACZ,IAAA,IAAA,CAAK,EAAA,CAAG,KAAK,OAAO,CAAA;AAEpB,IAAA,IAAI;AACF,MAAA,MAAM,SAAS,MAAM,EAAA,CAAG,IAAI,QAAA,CAAS,IAAA,CAAK,EAAE,CAAC,CAAA;AAE7C,MAAA,IAAA,CAAK,EAAA,CAAG,KAAK,QAAQ,CAAA;AAErB,MAAA,OAAO,MAAA;AAAA,IACT,SAAS,GAAA,EAAK;AACZ,MAAA,IAAA,CAAK,EAAA,CAAG,KAAK,UAAU,CAAA;AAEvB,MAAA,MAAM,GAAA;AAAA,IACR;AAAA,EACF;AAAA;AAAA;AAAA;AAAA,EAKA,MAAM,KAAA,GAAuB;AAC3B,IAAA,IAAA,CAAK,GAAG,KAAA,EAAM;AAAA,EAChB;AACF","file":"better-sqlite3.cjs","sourcesContent":["import Database from \"better-sqlite3\";\nimport type { SqlParam, StorageAdapter, Tx } from \"../../ports/StorageAdapter\";\n\n/**\n * تنفيذ أوامر SQL المشتركة بين الـ Adapter والـ Transaction.\n *\n * مكتبة better-sqlite3 تعمل بشكل متزامن (Synchronous)،\n * لكن واجهة الـ Core تعتمد على Promise، لذلك نقوم بتغليف\n * النتائج داخل دوال async للحفاظ على نفس العقد (Contract)\n * بين جميع المنصات (Electron / Web / React Native).\n */\nclass Executor implements Tx {\n  constructor(protected readonly db: Database.Database) {}\n\n  /**\n   * تنفيذ أوامر:\n   * INSERT\n   * UPDATE\n   * DELETE\n   * CREATE TABLE6\n   * ALTER TABLE\n   *\n   * إذا تم تمرير معاملات (params) يتم استخدام prepare().run().\n   * أما إذا لم توجد معاملات يتم استخدام exec() للسماح بتنفيذ\n   * أكثر من SQL statement في نفس النص (مفيد للـ migrations).\n   */\n  async execute(sql: string, params?: SqlParam[]): Promise<void> {\n    if (params && params.length > 0) {\n      this.db.prepare(sql).run(...params);\n    } else {\n      this.db.exec(sql);\n    }\n  }\n\n  /**\n   * تنفيذ استعلام SELECT وإرجاع النتائج كمصفوفة.\n   *\n   * مثال:\n   * SELECT * FROM products\n   * SELECT * FROM orders WHERE id = ?\n   */\n  async query<T = Record<string, unknown>>(\n    sql: string,\n    params?: SqlParam[],\n  ): Promise<T[]> {\n    const stmt = this.db.prepare(sql);\n\n    const rows =\n      params && params.length > 0\n        ? stmt.all(...params)\n        : stmt.all();\n\n    return rows as T[];\n  }\n}\n\nexport interface BetterSqlite3Options {\n  /**\n   * مسار ملف قاعدة البيانات.\n   *\n   * إذا لم يتم تحديده سيتم استخدام \":memory:\"\n   * لإنشاء قاعدة بيانات داخل الذاكرة فقط.\n   *\n   * مفيد للاختبارات.\n   */\n  filename?: string;\n\n  /**\n   * تفعيل وضع WAL.\n   *\n   * افتراضيًا يتم تفعيله عند استخدام قاعدة بيانات\n   * محفوظة على القرص.\n   */\n  wal?: boolean;\n}\n\n/**\n * Adapter خاص بـ Electron يعتمد على better-sqlite3.\n *\n * هذا الكلاس هو الطبقة التي تربط الـ Core بقاعدة SQLite.\n *\n * الـ Core لا يعرف أي شيء عن SQLite أو Electron،\n * بل يتعامل فقط مع واجهة StorageAdapter.\n *\n * لذلك يمكن استبدال هذا الـ Adapter مستقبلًا بـ:\n * - wa-sqlite (Web)\n * - op-sqlite (React Native)\n * - أي محرك تخزين آخر\n */\nexport class BetterSqlite3Adapter\n  extends Executor\n  implements StorageAdapter\n{\n  private constructor(db: Database.Database) {\n    super(db);\n  }\n\n  /**\n   * فتح قاعدة البيانات وإنشاء الـ Adapter.\n   */\n  static open(\n    options: BetterSqlite3Options = {},\n  ): BetterSqlite3Adapter {\n    const db = new Database(options.filename ?? \":memory:\");\n\n    /**\n     * تفعيل Foreign Keys.\n     *\n     * SQLite لا يفرض العلاقات بشكل افتراضي،\n     * لذلك يجب تشغيلها يدويًا.\n     */\n    db.pragma(\"foreign_keys = ON\");\n\n    /**\n     * تفعيل WAL (Write Ahead Logging).\n     *\n     * فوائده:\n     * - تحسين الأداء.\n     * - السماح بالقراءة أثناء الكتابة.\n     * - تقليل قفل قاعدة البيانات.\n     */\n    if (options.wal ?? Boolean(options.filename)) {\n      db.pragma(\"journal_mode = WAL\");\n    }\n\n    return new BetterSqlite3Adapter(db);\n  }\n\n  /**\n   * تنفيذ مجموعة عمليات داخل Transaction واحدة.\n   *\n   * إذا نجحت جميع العمليات:\n   *   COMMIT\n   *\n   * إذا فشلت أي عملية:\n   *   ROLLBACK\n   *\n   * ملاحظة:\n   * نستخدم BEGIN / COMMIT / ROLLBACK يدويًا\n   * بدل db.transaction() لأن الـ callback هنا async.\n   */\n  async transaction<T>(\n    fn: (tx: Tx) => Promise<T>,\n  ): Promise<T> {\n    this.db.exec(\"BEGIN\");\n\n    try {\n      const result = await fn(new Executor(this.db));\n\n      this.db.exec(\"COMMIT\");\n\n      return result;\n    } catch (err) {\n      this.db.exec(\"ROLLBACK\");\n\n      throw err;\n    }\n  }\n\n  /**\n   * إغلاق اتصال قاعدة البيانات وتحرير الموارد.\n   */\n  async close(): Promise<void> {\n    this.db.close();\n  }\n}"]}

package/dist/better-sqlite3.d.cts

@@ -0,0 +1,94 @@
+import Database from 'better-sqlite3';
+import { T as Tx, S as SqlParam, a as StorageAdapter } from './StorageAdapter-B2IgHcUF.cjs';
+
+/**
+ * تنفيذ أوامر SQL المشتركة بين الـ Adapter والـ Transaction.
+ *
+ * مكتبة better-sqlite3 تعمل بشكل متزامن (Synchronous)،
+ * لكن واجهة الـ Core تعتمد على Promise، لذلك نقوم بتغليف
+ * النتائج داخل دوال async للحفاظ على نفس العقد (Contract)
+ * بين جميع المنصات (Electron / Web / React Native).
+ */
+declare class Executor implements Tx {
+    protected readonly db: Database.Database;
+    constructor(db: Database.Database);
+    /**
+     * تنفيذ أوامر:
+     * INSERT
+     * UPDATE
+     * DELETE
+     * CREATE TABLE6
+     * ALTER TABLE
+     *
+     * إذا تم تمرير معاملات (params) يتم استخدام prepare().run().
+     * أما إذا لم توجد معاملات يتم استخدام exec() للسماح بتنفيذ
+     * أكثر من SQL statement في نفس النص (مفيد للـ migrations).
+     */
+    execute(sql: string, params?: SqlParam[]): Promise<void>;
+    /**
+     * تنفيذ استعلام SELECT وإرجاع النتائج كمصفوفة.
+     *
+     * مثال:
+     * SELECT * FROM products
+     * SELECT * FROM orders WHERE id = ?
+     */
+    query<T = Record<string, unknown>>(sql: string, params?: SqlParam[]): Promise<T[]>;
+}
+interface BetterSqlite3Options {
+    /**
+     * مسار ملف قاعدة البيانات.
+     *
+     * إذا لم يتم تحديده سيتم استخدام ":memory:"
+     * لإنشاء قاعدة بيانات داخل الذاكرة فقط.
+     *
+     * مفيد للاختبارات.
+     */
+    filename?: string;
+    /**
+     * تفعيل وضع WAL.
+     *
+     * افتراضيًا يتم تفعيله عند استخدام قاعدة بيانات
+     * محفوظة على القرص.
+     */
+    wal?: boolean;
+}
+/**
+ * Adapter خاص بـ Electron يعتمد على better-sqlite3.
+ *
+ * هذا الكلاس هو الطبقة التي تربط الـ Core بقاعدة SQLite.
+ *
+ * الـ Core لا يعرف أي شيء عن SQLite أو Electron،
+ * بل يتعامل فقط مع واجهة StorageAdapter.
+ *
+ * لذلك يمكن استبدال هذا الـ Adapter مستقبلًا بـ:
+ * - wa-sqlite (Web)
+ * - op-sqlite (React Native)
+ * - أي محرك تخزين آخر
+ */
+declare class BetterSqlite3Adapter extends Executor implements StorageAdapter {
+    private constructor();
+    /**
+     * فتح قاعدة البيانات وإنشاء الـ Adapter.
+     */
+    static open(options?: BetterSqlite3Options): BetterSqlite3Adapter;
+    /**
+     * تنفيذ مجموعة عمليات داخل Transaction واحدة.
+     *
+     * إذا نجحت جميع العمليات:
+     *   COMMIT
+     *
+     * إذا فشلت أي عملية:
+     *   ROLLBACK
+     *
+     * ملاحظة:
+     * نستخدم BEGIN / COMMIT / ROLLBACK يدويًا
+     * بدل db.transaction() لأن الـ callback هنا async.
+     */
+    transaction<T>(fn: (tx: Tx) => Promise<T>): Promise<T>;
+    /**
+     * إغلاق اتصال قاعدة البيانات وتحرير الموارد.
+     */
+    close(): Promise<void>;
+}
+
+export { BetterSqlite3Adapter, type BetterSqlite3Options };

package/dist/better-sqlite3.d.ts

@@ -0,0 +1,94 @@
+import Database from 'better-sqlite3';
+import { T as Tx, S as SqlParam, a as StorageAdapter } from './StorageAdapter-B2IgHcUF.js';
+
+/**
+ * تنفيذ أوامر SQL المشتركة بين الـ Adapter والـ Transaction.
+ *
+ * مكتبة better-sqlite3 تعمل بشكل متزامن (Synchronous)،
+ * لكن واجهة الـ Core تعتمد على Promise، لذلك نقوم بتغليف
+ * النتائج داخل دوال async للحفاظ على نفس العقد (Contract)
+ * بين جميع المنصات (Electron / Web / React Native).
+ */
+declare class Executor implements Tx {
+    protected readonly db: Database.Database;
+    constructor(db: Database.Database);
+    /**
+     * تنفيذ أوامر:
+     * INSERT
+     * UPDATE
+     * DELETE
+     * CREATE TABLE6
+     * ALTER TABLE
+     *
+     * إذا تم تمرير معاملات (params) يتم استخدام prepare().run().
+     * أما إذا لم توجد معاملات يتم استخدام exec() للسماح بتنفيذ
+     * أكثر من SQL statement في نفس النص (مفيد للـ migrations).
+     */
+    execute(sql: string, params?: SqlParam[]): Promise<void>;
+    /**
+     * تنفيذ استعلام SELECT وإرجاع النتائج كمصفوفة.
+     *
+     * مثال:
+     * SELECT * FROM products
+     * SELECT * FROM orders WHERE id = ?
+     */
+    query<T = Record<string, unknown>>(sql: string, params?: SqlParam[]): Promise<T[]>;
+}
+interface BetterSqlite3Options {
+    /**
+     * مسار ملف قاعدة البيانات.
+     *
+     * إذا لم يتم تحديده سيتم استخدام ":memory:"
+     * لإنشاء قاعدة بيانات داخل الذاكرة فقط.
+     *
+     * مفيد للاختبارات.
+     */
+    filename?: string;
+    /**
+     * تفعيل وضع WAL.
+     *
+     * افتراضيًا يتم تفعيله عند استخدام قاعدة بيانات
+     * محفوظة على القرص.
+     */
+    wal?: boolean;
+}
+/**
+ * Adapter خاص بـ Electron يعتمد على better-sqlite3.
+ *
+ * هذا الكلاس هو الطبقة التي تربط الـ Core بقاعدة SQLite.
+ *
+ * الـ Core لا يعرف أي شيء عن SQLite أو Electron،
+ * بل يتعامل فقط مع واجهة StorageAdapter.
+ *
+ * لذلك يمكن استبدال هذا الـ Adapter مستقبلًا بـ:
+ * - wa-sqlite (Web)
+ * - op-sqlite (React Native)
+ * - أي محرك تخزين آخر
+ */
+declare class BetterSqlite3Adapter extends Executor implements StorageAdapter {
+    private constructor();
+    /**
+     * فتح قاعدة البيانات وإنشاء الـ Adapter.
+     */
+    static open(options?: BetterSqlite3Options): BetterSqlite3Adapter;
+    /**
+     * تنفيذ مجموعة عمليات داخل Transaction واحدة.
+     *
+     * إذا نجحت جميع العمليات:
+     *   COMMIT
+     *
+     * إذا فشلت أي عملية:
+     *   ROLLBACK
+     *
+     * ملاحظة:
+     * نستخدم BEGIN / COMMIT / ROLLBACK يدويًا
+     * بدل db.transaction() لأن الـ callback هنا async.
+     */
+    transaction<T>(fn: (tx: Tx) => Promise<T>): Promise<T>;
+    /**
+     * إغلاق اتصال قاعدة البيانات وتحرير الموارد.
+     */
+    close(): Promise<void>;
+}
+
+export { BetterSqlite3Adapter, type BetterSqlite3Options };

package/dist/better-sqlite3.js

@@ -0,0 +1,90 @@
+import Database from 'better-sqlite3';
+
+// src/adapters/better-sqlite3/index.ts
+var Executor = class {
+  constructor(db) {
+    this.db = db;
+  }
+  db;
+  /**
+   * تنفيذ أوامر:
+   * INSERT
+   * UPDATE
+   * DELETE
+   * CREATE TABLE6
+   * ALTER TABLE
+   *
+   * إذا تم تمرير معاملات (params) يتم استخدام prepare().run().
+   * أما إذا لم توجد معاملات يتم استخدام exec() للسماح بتنفيذ
+   * أكثر من SQL statement في نفس النص (مفيد للـ migrations).
+   */
+  async execute(sql, params) {
+    if (params && params.length > 0) {
+      this.db.prepare(sql).run(...params);
+    } else {
+      this.db.exec(sql);
+    }
+  }
+  /**
+   * تنفيذ استعلام SELECT وإرجاع النتائج كمصفوفة.
+   *
+   * مثال:
+   * SELECT * FROM products
+   * SELECT * FROM orders WHERE id = ?
+   */
+  async query(sql, params) {
+    const stmt = this.db.prepare(sql);
+    const rows = params && params.length > 0 ? stmt.all(...params) : stmt.all();
+    return rows;
+  }
+};
+var BetterSqlite3Adapter = class _BetterSqlite3Adapter extends Executor {
+  constructor(db) {
+    super(db);
+  }
+  /**
+   * فتح قاعدة البيانات وإنشاء الـ Adapter.
+   */
+  static open(options = {}) {
+    const db = new Database(options.filename ?? ":memory:");
+    db.pragma("foreign_keys = ON");
+    if (options.wal ?? Boolean(options.filename)) {
+      db.pragma("journal_mode = WAL");
+    }
+    return new _BetterSqlite3Adapter(db);
+  }
+  /**
+   * تنفيذ مجموعة عمليات داخل Transaction واحدة.
+   *
+   * إذا نجحت جميع العمليات:
+   *   COMMIT
+   *
+   * إذا فشلت أي عملية:
+   *   ROLLBACK
+   *
+   * ملاحظة:
+   * نستخدم BEGIN / COMMIT / ROLLBACK يدويًا
+   * بدل db.transaction() لأن الـ callback هنا async.
+   */
+  async transaction(fn) {
+    this.db.exec("BEGIN");
+    try {
+      const result = await fn(new Executor(this.db));
+      this.db.exec("COMMIT");
+      return result;
+    } catch (err) {
+      this.db.exec("ROLLBACK");
+      throw err;
+    }
+  }
+  /**
+   * إغلاق اتصال قاعدة البيانات وتحرير الموارد.
+   */
+  async close() {
+    this.db.close();
+  }
+};
+
+export { BetterSqlite3Adapter };
+//# sourceMappingURL=better-sqlite3.js.map
+//# sourceMappingURL=better-sqlite3.js.map

package/dist/better-sqlite3.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/adapters/better-sqlite3/index.ts"],"names":[],"mappings":";;;AAWA,IAAM,WAAN,MAA6B;AAAA,EAC3B,YAA+B,EAAA,EAAuB;AAAvB,IAAA,IAAA,CAAA,EAAA,GAAA,EAAA;AAAA,EAAwB;AAAA,EAAxB,EAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAc/B,MAAM,OAAA,CAAQ,GAAA,EAAa,MAAA,EAAoC;AAC7D,IAAA,IAAI,MAAA,IAAU,MAAA,CAAO,MAAA,GAAS,CAAA,EAAG;AAC/B,MAAA,IAAA,CAAK,GAAG,OAAA,CAAQ,GAAG,CAAA,CAAE,GAAA,CAAI,GAAG,MAAM,CAAA;AAAA,IACpC,CAAA,MAAO;AACL,MAAA,IAAA,CAAK,EAAA,CAAG,KAAK,GAAG,CAAA;AAAA,IAClB;AAAA,EACF;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EASA,MAAM,KAAA,CACJ,GAAA,EACA,MAAA,EACc;AACd,IAAA,MAAM,IAAA,GAAO,IAAA,CAAK,EAAA,CAAG,OAAA,CAAQ,GAAG,CAAA;AAEhC,IAAA,MAAM,IAAA,GACJ,MAAA,IAAU,MAAA,CAAO,MAAA,GAAS,CAAA,GACtB,IAAA,CAAK,GAAA,CAAI,GAAG,MAAM,CAAA,GAClB,IAAA,CAAK,GAAA,EAAI;AAEf,IAAA,OAAO,IAAA;AAAA,EACT;AACF,CAAA;AAmCO,IAAM,oBAAA,GAAN,MAAM,qBAAA,SACH,QAAA,CAEV;AAAA,EACU,YAAY,EAAA,EAAuB;AACzC,IAAA,KAAA,CAAM,EAAE,CAAA;AAAA,EACV;AAAA;AAAA;AAAA;AAAA,EAKA,OAAO,IAAA,CACL,OAAA,GAAgC,EAAC,EACX;AACtB,IAAA,MAAM,EAAA,GAAK,IAAI,QAAA,CAAS,OAAA,CAAQ,YAAY,UAAU,CAAA;AAQtD,IAAA,EAAA,CAAG,OAAO,mBAAmB,CAAA;AAU7B,IAAA,IAAI,OAAA,CAAQ,GAAA,IAAO,OAAA,CAAQ,OAAA,CAAQ,QAAQ,CAAA,EAAG;AAC5C,MAAA,EAAA,CAAG,OAAO,oBAAoB,CAAA;AAAA,IAChC;AAEA,IAAA,OAAO,IAAI,sBAAqB,EAAE,CAAA;AAAA,EACpC;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAeA,MAAM,YACJ,EAAA,EACY;AACZ,IAAA,IAAA,CAAK,EAAA,CAAG,KAAK,OAAO,CAAA;AAEpB,IAAA,IAAI;AACF,MAAA,MAAM,SAAS,MAAM,EAAA,CAAG,IAAI,QAAA,CAAS,IAAA,CAAK,EAAE,CAAC,CAAA;AAE7C,MAAA,IAAA,CAAK,EAAA,CAAG,KAAK,QAAQ,CAAA;AAErB,MAAA,OAAO,MAAA;AAAA,IACT,SAAS,GAAA,EAAK;AACZ,MAAA,IAAA,CAAK,EAAA,CAAG,KAAK,UAAU,CAAA;AAEvB,MAAA,MAAM,GAAA;AAAA,IACR;AAAA,EACF;AAAA;AAAA;AAAA;AAAA,EAKA,MAAM,KAAA,GAAuB;AAC3B,IAAA,IAAA,CAAK,GAAG,KAAA,EAAM;AAAA,EAChB;AACF","file":"better-sqlite3.js","sourcesContent":["import Database from \"better-sqlite3\";\nimport type { SqlParam, StorageAdapter, Tx } from \"../../ports/StorageAdapter\";\n\n/**\n * تنفيذ أوامر SQL المشتركة بين الـ Adapter والـ Transaction.\n *\n * مكتبة better-sqlite3 تعمل بشكل متزامن (Synchronous)،\n * لكن واجهة الـ Core تعتمد على Promise، لذلك نقوم بتغليف\n * النتائج داخل دوال async للحفاظ على نفس العقد (Contract)\n * بين جميع المنصات (Electron / Web / React Native).\n */\nclass Executor implements Tx {\n  constructor(protected readonly db: Database.Database) {}\n\n  /**\n   * تنفيذ أوامر:\n   * INSERT\n   * UPDATE\n   * DELETE\n   * CREATE TABLE6\n   * ALTER TABLE\n   *\n   * إذا تم تمرير معاملات (params) يتم استخدام prepare().run().\n   * أما إذا لم توجد معاملات يتم استخدام exec() للسماح بتنفيذ\n   * أكثر من SQL statement في نفس النص (مفيد للـ migrations).\n   */\n  async execute(sql: string, params?: SqlParam[]): Promise<void> {\n    if (params && params.length > 0) {\n      this.db.prepare(sql).run(...params);\n    } else {\n      this.db.exec(sql);\n    }\n  }\n\n  /**\n   * تنفيذ استعلام SELECT وإرجاع النتائج كمصفوفة.\n   *\n   * مثال:\n   * SELECT * FROM products\n   * SELECT * FROM orders WHERE id = ?\n   */\n  async query<T = Record<string, unknown>>(\n    sql: string,\n    params?: SqlParam[],\n  ): Promise<T[]> {\n    const stmt = this.db.prepare(sql);\n\n    const rows =\n      params && params.length > 0\n        ? stmt.all(...params)\n        : stmt.all();\n\n    return rows as T[];\n  }\n}\n\nexport interface BetterSqlite3Options {\n  /**\n   * مسار ملف قاعدة البيانات.\n   *\n   * إذا لم يتم تحديده سيتم استخدام \":memory:\"\n   * لإنشاء قاعدة بيانات داخل الذاكرة فقط.\n   *\n   * مفيد للاختبارات.\n   */\n  filename?: string;\n\n  /**\n   * تفعيل وضع WAL.\n   *\n   * افتراضيًا يتم تفعيله عند استخدام قاعدة بيانات\n   * محفوظة على القرص.\n   */\n  wal?: boolean;\n}\n\n/**\n * Adapter خاص بـ Electron يعتمد على better-sqlite3.\n *\n * هذا الكلاس هو الطبقة التي تربط الـ Core بقاعدة SQLite.\n *\n * الـ Core لا يعرف أي شيء عن SQLite أو Electron،\n * بل يتعامل فقط مع واجهة StorageAdapter.\n *\n * لذلك يمكن استبدال هذا الـ Adapter مستقبلًا بـ:\n * - wa-sqlite (Web)\n * - op-sqlite (React Native)\n * - أي محرك تخزين آخر\n */\nexport class BetterSqlite3Adapter\n  extends Executor\n  implements StorageAdapter\n{\n  private constructor(db: Database.Database) {\n    super(db);\n  }\n\n  /**\n   * فتح قاعدة البيانات وإنشاء الـ Adapter.\n   */\n  static open(\n    options: BetterSqlite3Options = {},\n  ): BetterSqlite3Adapter {\n    const db = new Database(options.filename ?? \":memory:\");\n\n    /**\n     * تفعيل Foreign Keys.\n     *\n     * SQLite لا يفرض العلاقات بشكل افتراضي،\n     * لذلك يجب تشغيلها يدويًا.\n     */\n    db.pragma(\"foreign_keys = ON\");\n\n    /**\n     * تفعيل WAL (Write Ahead Logging).\n     *\n     * فوائده:\n     * - تحسين الأداء.\n     * - السماح بالقراءة أثناء الكتابة.\n     * - تقليل قفل قاعدة البيانات.\n     */\n    if (options.wal ?? Boolean(options.filename)) {\n      db.pragma(\"journal_mode = WAL\");\n    }\n\n    return new BetterSqlite3Adapter(db);\n  }\n\n  /**\n   * تنفيذ مجموعة عمليات داخل Transaction واحدة.\n   *\n   * إذا نجحت جميع العمليات:\n   *   COMMIT\n   *\n   * إذا فشلت أي عملية:\n   *   ROLLBACK\n   *\n   * ملاحظة:\n   * نستخدم BEGIN / COMMIT / ROLLBACK يدويًا\n   * بدل db.transaction() لأن الـ callback هنا async.\n   */\n  async transaction<T>(\n    fn: (tx: Tx) => Promise<T>,\n  ): Promise<T> {\n    this.db.exec(\"BEGIN\");\n\n    try {\n      const result = await fn(new Executor(this.db));\n\n      this.db.exec(\"COMMIT\");\n\n      return result;\n    } catch (err) {\n      this.db.exec(\"ROLLBACK\");\n\n      throw err;\n    }\n  }\n\n  /**\n   * إغلاق اتصال قاعدة البيانات وتحرير الموارد.\n   */\n  async close(): Promise<void> {\n    this.db.close();\n  }\n}"]}

package/dist/chunk-CELALQHK.js

@@ -0,0 +1,38 @@
+// src/adapters/generic/GenericSqlAdapter.ts
+var GenericExecutor = class {
+  constructor(driver) {
+    this.driver = driver;
+  }
+  driver;
+  async execute(sql, params) {
+    if (params && params.length > 0) {
+      await this.driver.run(sql, params);
+    } else {
+      await this.driver.runBatch(sql);
+    }
+  }
+  async query(sql, params) {
+    const rows = await this.driver.select(sql, params ?? []);
+    return rows;
+  }
+};
+var GenericSqlAdapter = class extends GenericExecutor {
+  async transaction(fn) {
+    await this.driver.runBatch("BEGIN");
+    try {
+      const result = await fn(new GenericExecutor(this.driver));
+      await this.driver.runBatch("COMMIT");
+      return result;
+    } catch (err) {
+      await this.driver.runBatch("ROLLBACK");
+      throw err;
+    }
+  }
+  async close() {
+    await this.driver.close();
+  }
+};
+
+export { GenericSqlAdapter };
+//# sourceMappingURL=chunk-CELALQHK.js.map
+//# sourceMappingURL=chunk-CELALQHK.js.map

package/dist/chunk-CELALQHK.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/adapters/generic/GenericSqlAdapter.ts"],"names":[],"mappings":";AAkBA,IAAM,kBAAN,MAAoC;AAAA,EAClC,YAA+B,MAAA,EAAmB;AAAnB,IAAA,IAAA,CAAA,MAAA,GAAA,MAAA;AAAA,EAAoB;AAAA,EAApB,MAAA;AAAA,EAE/B,MAAM,OAAA,CAAQ,GAAA,EAAa,MAAA,EAAoC;AAC7D,IAAA,IAAI,MAAA,IAAU,MAAA,CAAO,MAAA,GAAS,CAAA,EAAG;AAC/B,MAAA,MAAM,IAAA,CAAK,MAAA,CAAO,GAAA,CAAI,GAAA,EAAK,MAAM,CAAA;AAAA,IACnC,CAAA,MAAO;AACL,MAAA,MAAM,IAAA,CAAK,MAAA,CAAO,QAAA,CAAS,GAAG,CAAA;AAAA,IAChC;AAAA,EACF;AAAA,EAEA,MAAM,KAAA,CACJ,GAAA,EACA,MAAA,EACc;AACd,IAAA,MAAM,IAAA,GAAO,MAAM,IAAA,CAAK,MAAA,CAAO,OAAO,GAAA,EAAK,MAAA,IAAU,EAAE,CAAA;AACvD,IAAA,OAAO,IAAA;AAAA,EACT;AACF,CAAA;AAOO,IAAM,iBAAA,GAAN,cAAgC,eAAA,CAA0C;AAAA,EAC/E,MAAM,YAAe,EAAA,EAAwC;AAC3D,IAAA,MAAM,IAAA,CAAK,MAAA,CAAO,QAAA,CAAS,OAAO,CAAA;AAClC,IAAA,IAAI;AACF,MAAA,MAAM,SAAS,MAAM,EAAA,CAAG,IAAI,eAAA,CAAgB,IAAA,CAAK,MAAM,CAAC,CAAA;AACxD,MAAA,MAAM,IAAA,CAAK,MAAA,CAAO,QAAA,CAAS,QAAQ,CAAA;AACnC,MAAA,OAAO,MAAA;AAAA,IACT,SAAS,GAAA,EAAK;AACZ,MAAA,MAAM,IAAA,CAAK,MAAA,CAAO,QAAA,CAAS,UAAU,CAAA;AACrC,MAAA,MAAM,GAAA;AAAA,IACR;AAAA,EACF;AAAA,EAEA,MAAM,KAAA,GAAuB;AAC3B,IAAA,MAAM,IAAA,CAAK,OAAO,KAAA,EAAM;AAAA,EAC1B;AACF","file":"chunk-CELALQHK.js","sourcesContent":["import type { SqlParam, StorageAdapter, Tx } from \"../../ports/StorageAdapter\";\n\n/**\n * منفذ رفيع لأي محرك SQLite async (op-sqlite على RN، wa-sqlite على الويب). كل\n * محرك بيوصّل الأربع دوال دي بس، والـ GenericSqlAdapter بيبني عليها عقد\n * StorageAdapter كامل (بما فيه الـ transactions) — فمنطق الـ BEGIN/COMMIT/ROLLBACK\n * يتكتب مرة واحدة ويتشارك بين المنصتين.\n */\nexport interface SqlDriver {\n  /** SELECT بمعاملات → صفوف ككائنات. */\n  select(sql: string, params: SqlParam[]): Promise<Record<string, unknown>[]>;\n  /** أمر واحد بمعاملات (INSERT/UPDATE/DELETE). */\n  run(sql: string, params: SqlParam[]): Promise<void>;\n  /** نص فيه أمر أو أكتر بدون معاملات (DDL/migrations، وBEGIN/COMMIT/ROLLBACK). */\n  runBatch(sql: string): Promise<void>;\n  close(): Promise<void>;\n}\n\nclass GenericExecutor implements Tx {\n  constructor(protected readonly driver: SqlDriver) {}\n\n  async execute(sql: string, params?: SqlParam[]): Promise<void> {\n    if (params && params.length > 0) {\n      await this.driver.run(sql, params);\n    } else {\n      await this.driver.runBatch(sql);\n    }\n  }\n\n  async query<T = Record<string, unknown>>(\n    sql: string,\n    params?: SqlParam[],\n  ): Promise<T[]> {\n    const rows = await this.driver.select(sql, params ?? []);\n    return rows as T[];\n  }\n}\n\n/**\n * StorageAdapter فوق SqlDriver. الـ transaction يدوي بـ BEGIN/COMMIT/ROLLBACK\n * (زي better-sqlite3 adapter) — بيخلّي الـ callback الـ async يشتغل صح. مفيش\n * transactions متداخلة (نفس حد المحركات التانية).\n */\nexport class GenericSqlAdapter extends GenericExecutor implements StorageAdapter {\n  async transaction<T>(fn: (tx: Tx) => Promise<T>): Promise<T> {\n    await this.driver.runBatch(\"BEGIN\");\n    try {\n      const result = await fn(new GenericExecutor(this.driver));\n      await this.driver.runBatch(\"COMMIT\");\n      return result;\n    } catch (err) {\n      await this.driver.runBatch(\"ROLLBACK\");\n      throw err;\n    }\n  }\n\n  async close(): Promise<void> {\n    await this.driver.close();\n  }\n}\n"]}