@forthtilliath/expo-test-kit 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Forthtilliath
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,104 @@
+# @forthtilliath/expo-test-kit
+
+Test helpers for Expo/Drizzle apps: a real in-memory SQLite database (via libsql) to exercise a Drizzle repository's actual SQL, and a lightweight `expo-file-system` fake — both extracted from patterns that were duplicated across test files rather than shared.
+
+## Install
+
+```bash
+npm install --save-dev @forthtilliath/expo-test-kit drizzle-orm @libsql/client
+```
+
+Or, from within this monorepo, as a workspace dependency:
+
+```json
+{
+  "devDependencies": {
+    "@forthtilliath/expo-test-kit": "workspace:*"
+  }
+}
+```
+
+`drizzle-orm` and `@libsql/client` are peer dependencies — install them if not already present. Both are dev-only: `expo-test-kit` doesn't touch your app's production `expo-sqlite` driver, it's a separate in-memory database used only while testing.
+
+## Usage
+
+Each function is its own module — import the file you need directly:
+
+```ts
+import {
+  createTestDb,
+  type TestDb,
+} from "@forthtilliath/expo-test-kit/createTestDb";
+import { closeTestDb } from "@forthtilliath/expo-test-kit/closeTestDb";
+import { resetTestDb } from "@forthtilliath/expo-test-kit/resetTestDb";
+import { mockDbClient } from "@forthtilliath/expo-test-kit/mockDbClient";
+```
+
+### `createTestDb(schema, migrationsFolder)` / `closeTestDb(db)` / `resetTestDb(db, tables)`
+
+A real SQLite database (via `libsql`, in a temp file — not `:memory:`, since some internal libsql connections reopen the database separately) with your actual Drizzle migrations replayed against it, and foreign keys enforced. Lets a repository's tests hit real SQL (constraints, transactions) instead of a mocked driver.
+
+```ts
+import * as schema from "./schema";
+
+let testDb: TestDb<typeof schema>;
+
+beforeAll(async () => {
+  testDb = await createTestDb(schema, path.join(__dirname, "../../drizzle"));
+});
+
+afterAll(() => {
+  closeTestDb(testDb);
+});
+
+beforeEach(async () => {
+  // Order matters for foreign keys in "restrict" mode: children before parents.
+  await resetTestDb(testDb, [schema.tags, schema.items]);
+});
+```
+
+### `mockDbClient(doMock, modulePath, testDb)`
+
+Substitutes a `TestDb` for the real client exported by a module (typically `"./client"` or `"@/db/client"`), for test files importing a repository built on that client. `doMock` is your test runner's own mock function (`jest.doMock` or `vi.doMock`) — this package has no opinion on which one you use.
+
+```ts
+beforeAll(async () => {
+  testDb = await createTestDb(schema, migrationsFolder);
+  mockDbClient(jest.doMock, "./client", testDb); // or vi.doMock
+  repo = require("./repository"); // after mockDbClient, not hoisted like jest.mock
+});
+```
+
+### `createFakeExpoFileSystem()` / `getFakeExpoFileSystem()`
+
+A minimal in-memory `File`/`Paths` fake — enough to test code that reads/writes files via `expo-file-system`, without the native filesystem (unavailable under Jest/Vitest).
+
+```ts
+import {
+  createFakeExpoFileSystem,
+  getFakeExpoFileSystem,
+} from "@forthtilliath/expo-test-kit/createFakeExpoFileSystem";
+
+// jest.mock's factory can't reference an outer variable, so stash + retrieve
+// instead of closing over one:
+jest.mock("expo-file-system", () => createFakeExpoFileSystem());
+
+let fakeFs: ReturnType<typeof getFakeExpoFileSystem>;
+
+beforeAll(() => {
+  fakeFs = getFakeExpoFileSystem();
+});
+```
+
+## Scripts
+
+```bash
+pnpm run dev            # tsc --watch -> dist/
+pnpm run build          # tsc -> dist/
+pnpm run check-types    # tsc --noEmit
+pnpm run lint           # eslint
+pnpm run test           # vitest run
+pnpm run test:watch     # vitest
+```
+
+Built to `dist/` (see the `exports` field in `package.json`), so run `pnpm run build` (or `dev`) after source changes for consumers to see them.

package/dist/closeTestDb.d.ts

@@ -0,0 +1,3 @@
+import { type TestDb } from "./createTestDb.js";
+export declare function closeTestDb(db: TestDb<Record<string, unknown>>): void;
+//# sourceMappingURL=closeTestDb.d.ts.map

package/dist/closeTestDb.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"closeTestDb.d.ts","sourceRoot":"","sources":["../src/closeTestDb.ts"],"names":[],"mappings":"AAEA,OAAO,EAAiB,KAAK,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAM/D,wBAAgB,WAAW,CAAC,EAAE,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,QAc9D"}

package/dist/closeTestDb.js

@@ -0,0 +1,22 @@
+import fs from "node:fs";
+import { tempFilesByDb } from "./createTestDb.js";
+// À appeler dans un afterAll : ferme la connexion native libsql (sans quoi le
+// test runner ne se termine pas proprement) et supprime le fichier temporaire
+// (et ses éventuels compagnons -wal/-shm) pour ne pas accumuler des bases de
+// test dans le dossier temp à chaque exécution.
+export function closeTestDb(db) {
+    db.$client.close();
+    const dbFile = tempFilesByDb.get(db);
+    if (!dbFile)
+        return;
+    for (const file of [dbFile, `${dbFile}-wal`, `${dbFile}-shm`]) {
+        try {
+            fs.rmSync(file, { force: true });
+        }
+        catch {
+            // Best effort : sur Windows le handle natif peut rester verrouillé
+            // brièvement après close(), un fichier de test qui persiste n'est pas
+            // grave (dossier temp, nettoyé de toute façon par l'OS).
+        }
+    }
+}

package/dist/createFakeExpoFileSystem.d.ts

@@ -0,0 +1,25 @@
+export interface FakeFile {
+    uri: string;
+    exists: boolean;
+    create: () => void;
+    write: (content: string) => void;
+    delete: () => void;
+    text: () => Promise<string>;
+}
+export interface FakeExpoFileSystem {
+    store: Map<string, string>;
+    File: new (...parts: (string | {
+        uri: string;
+    })[]) => FakeFile;
+    Paths: {
+        cache: {
+            uri: string;
+        };
+        document: {
+            uri: string;
+        };
+    };
+}
+export declare function createFakeExpoFileSystem(): FakeExpoFileSystem;
+export declare function getFakeExpoFileSystem(): FakeExpoFileSystem;
+//# sourceMappingURL=createFakeExpoFileSystem.d.ts.map

package/dist/createFakeExpoFileSystem.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createFakeExpoFileSystem.d.ts","sourceRoot":"","sources":["../src/createFakeExpoFileSystem.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,QAAQ;IACvB,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,OAAO,CAAC;IAChB,MAAM,EAAE,MAAM,IAAI,CAAC;IACnB,KAAK,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACjC,MAAM,EAAE,MAAM,IAAI,CAAC;IACnB,IAAI,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;CAC7B;AAED,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC3B,IAAI,EAAE,KAAK,GAAG,KAAK,EAAE,CAAC,MAAM,GAAG;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC,EAAE,KAAK,QAAQ,CAAC;IAC/D,KAAK,EAAE;QAAE,KAAK,EAAE;YAAE,GAAG,EAAE,MAAM,CAAA;SAAE,CAAC;QAAC,QAAQ,EAAE;YAAE,GAAG,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE,CAAC;CAC9D;AAWD,wBAAgB,wBAAwB,IAAI,kBAAkB,CAsC7D;AAED,wBAAgB,qBAAqB,IAAI,kBAAkB,CAS1D"}

package/dist/createFakeExpoFileSystem.js

@@ -0,0 +1,52 @@
+const GLOBAL_KEY = "__forthtilliathFakeExpoFileSystem";
+// Double léger d'expo-file-system : un simple magasin clé/valeur en mémoire,
+// suffisant pour tester du code lisant/écrivant des fichiers via `File`/
+// `Paths`, sans dépendre du système de fichiers natif (indisponible en
+// Jest/Vitest). Stashé sur `globalThis` plutôt que capturé par une closure,
+// car `jest.mock("expo-file-system", () => ...)` interdit de référencer une
+// variable hors-scope dans sa factory — `getFakeExpoFileSystem()` récupère
+// l'instance après coup, une fois le mock enregistré.
+export function createFakeExpoFileSystem() {
+    const store = new Map();
+    class File {
+        uri;
+        constructor(...parts) {
+            this.uri = parts
+                .map((p) => (typeof p === "string" ? p : p.uri))
+                .join("/");
+        }
+        get exists() {
+            return store.has(this.uri);
+        }
+        create() {
+            store.set(this.uri, "");
+        }
+        write(content) {
+            store.set(this.uri, content);
+        }
+        delete() {
+            store.delete(this.uri);
+        }
+        text() {
+            const content = store.get(this.uri);
+            if (content === undefined) {
+                return Promise.reject(new Error(`Fake file not found: ${this.uri}`));
+            }
+            return Promise.resolve(content);
+        }
+    }
+    const fakeFs = {
+        store,
+        File,
+        Paths: { cache: { uri: "cache" }, document: { uri: "document" } },
+    };
+    globalThis[GLOBAL_KEY] = fakeFs;
+    return fakeFs;
+}
+export function getFakeExpoFileSystem() {
+    const fakeFs = globalThis[GLOBAL_KEY];
+    if (!fakeFs) {
+        throw new Error("getFakeExpoFileSystem() called before createFakeExpoFileSystem() ran.");
+    }
+    return fakeFs;
+}

package/dist/createTestDb.d.ts

@@ -0,0 +1,8 @@
+import { type Client } from "@libsql/client";
+import { type LibSQLDatabase } from "drizzle-orm/libsql";
+export type TestDb<TSchema extends Record<string, unknown>> = LibSQLDatabase<TSchema> & {
+    $client: Client;
+};
+export declare const tempFilesByDb: WeakMap<object, string>;
+export declare function createTestDb<TSchema extends Record<string, unknown>>(schema: TSchema, migrationsFolder: string): Promise<TestDb<TSchema>>;
+//# sourceMappingURL=createTestDb.d.ts.map

package/dist/createTestDb.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createTestDb.d.ts","sourceRoot":"","sources":["../src/createTestDb.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,MAAM,EAAgB,MAAM,gBAAgB,CAAC;AAC3D,OAAO,EAAW,KAAK,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAMlE,MAAM,MAAM,MAAM,CAAC,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IACxD,cAAc,CAAC,OAAO,CAAC,GAAG;IACxB,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAKJ,eAAO,MAAM,aAAa,yBAAgC,CAAC;AAS3D,wBAAsB,YAAY,CAAC,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACxE,MAAM,EAAE,OAAO,EACf,gBAAgB,EAAE,MAAM,GACvB,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAa1B"}

package/dist/createTestDb.js

@@ -0,0 +1,29 @@
+import { createClient } from "@libsql/client";
+import { drizzle } from "drizzle-orm/libsql";
+import { migrate } from "drizzle-orm/libsql/migrator";
+import { randomUUID } from "node:crypto";
+import os from "node:os";
+import path from "node:path";
+// Chemin du fichier temporaire associé à chaque instance, pour le nettoyer
+// dans closeTestDb() sans changer la forme de la valeur retournée par
+// createTestDb() (qui doit rester une TestDb utilisable directement).
+export const tempFilesByDb = new WeakMap();
+// Base SQLite en mémoire (libsql) utilisable dans les tests pour exercer la
+// vraie logique SQL d'un repository Drizzle (contraintes de clé étrangère,
+// transactions...) sans dépendre d'expo-sqlite, indisponible hors d'une
+// app Expo/RN réelle. Contrairement à better-sqlite3/sql.js, le driver
+// libsql de drizzle est en mode "async" comme celui d'expo-sqlite : les
+// transactions avec callback `async (tx) => {...}` fonctionnent donc à
+// l'identique en test et en production.
+export async function createTestDb(schema, migrationsFolder) {
+    // Un fichier réel (et non ":memory:") : certaines connexions internes du
+    // client libsql ré-ouvrent la base séparément (transactions, migrations),
+    // ce qui repartirait sur une base vide à chaque fois avec ":memory:".
+    const dbFile = path.join(os.tmpdir(), `expo-test-kit-${randomUUID()}.sqlite`);
+    const client = createClient({ url: `file:${dbFile}` });
+    const db = drizzle(client, { schema });
+    await migrate(db, { migrationsFolder });
+    await client.execute("PRAGMA foreign_keys = ON;");
+    tempFilesByDb.set(db, dbFile);
+    return db;
+}

package/dist/mockDbClient.d.ts

@@ -0,0 +1,2 @@
+export declare function mockDbClient(doMock: (moduleId: string, factory: () => unknown) => void, modulePath: string, testDb: unknown): void;
+//# sourceMappingURL=mockDbClient.d.ts.map

package/dist/mockDbClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mockDbClient.d.ts","sourceRoot":"","sources":["../src/mockDbClient.ts"],"names":[],"mappings":"AAOA,wBAAgB,YAAY,CAC1B,MAAM,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,OAAO,KAAK,IAAI,EAC1D,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,OAAO,QAGhB"}

package/dist/mockDbClient.js

@@ -0,0 +1,10 @@
+// Substitue une TestDb à l'instance réelle exportée par un module (typiquement
+// "./client" ou "@/db/client"), pour les fichiers de test important un
+// repository construit sur ce client. `doMock` reste au choix de l'appelant
+// (`jest.doMock` ou `vi.doMock`) plutôt que codé en dur, ce module n'ayant pas
+// d'opinion sur le test runner utilisé. À appeler dans un beforeAll, avant le
+// require()/import() du module testé : `doMock` n'est pas hoisté comme
+// `jest.mock`/`vi.mock`, donc l'ordre d'appel est respecté.
+export function mockDbClient(doMock, modulePath, testDb) {
+    doMock(modulePath, () => ({ db: testDb }));
+}

package/dist/resetTestDb.d.ts

@@ -0,0 +1,4 @@
+import type { SQLiteTable } from "drizzle-orm/sqlite-core";
+import type { TestDb } from "./createTestDb.js";
+export declare function resetTestDb(db: TestDb<Record<string, unknown>>, tablesInDeleteOrder: SQLiteTable[]): Promise<void>;
+//# sourceMappingURL=resetTestDb.d.ts.map

package/dist/resetTestDb.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resetTestDb.d.ts","sourceRoot":"","sources":["../src/resetTestDb.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAE3D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAOhD,wBAAsB,WAAW,CAC/B,EAAE,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACnC,mBAAmB,EAAE,WAAW,EAAE,GACjC,OAAO,CAAC,IAAI,CAAC,CAIf"}

package/dist/resetTestDb.js

@@ -0,0 +1,10 @@
+// Vide les tables données entre deux tests, dans l'ordre fourni — c'est à
+// l'appelant de placer en premier les tables dont une contrainte de clé
+// étrangère en "restrict" empêche la suppression tant qu'une autre table les
+// référence encore (les relations en "set null"/"cascade" n'ont pas cette
+// contrainte d'ordre).
+export async function resetTestDb(db, tablesInDeleteOrder) {
+    for (const table of tablesInDeleteOrder) {
+        await db.delete(table);
+    }
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@forthtilliath/expo-test-kit",
+  "version": "0.2.0",
+  "type": "module",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Forthtilliath/turborepo.git",
+    "directory": "packages/expo-test-kit"
+  },
+  "homepage": "https://github.com/Forthtilliath/turborepo/tree/main/packages/expo-test-kit#readme",
+  "bugs": "https://github.com/Forthtilliath/turborepo/issues",
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    "./*": "./dist/*.js"
+  },
+  "peerDependencies": {
+    "@libsql/client": ">=0.14.0",
+    "drizzle-orm": ">=0.44.0"
+  },
+  "devDependencies": {
+    "@libsql/client": "^0.17.4",
+    "@types/node": "^26.1.1",
+    "drizzle-orm": "^0.45.2",
+    "eslint": "10.7.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.10",
+    "@forthtilliath/typescript-config": "0.0.0",
+    "@forthtilliath/eslint-config": "0.0.0"
+  },
+  "scripts": {
+    "lint": "eslint . --max-warnings 0",
+    "check-types": "tsc --noEmit",
+    "clean": "rm -rf dist",
+    "dev": "tsc --watch -p tsconfig.build.json",
+    "build": "pnpm run clean && tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}