@mdsrs/postgres-drizzle 0.0.0

package/README.md

@@ -0,0 +1,29 @@
+# @mdsrs/postgres-drizzle
+
+Postgres persistence adapter for the `@mdsrs/store` interface.
+
+This package is driver-agnostic: pass a Drizzle Postgres database instance that
+uses the exported `schema`.
+
+```ts
+import { createPostgresDrizzleStore, schema } from '@mdsrs/postgres-drizzle';
+
+const store = createPostgresDrizzleStore(db);
+
+await store.syncCards(cards);
+const queue = await store.getDueCards(cards);
+```
+
+Run the SQL in `migrations/0000_initial.sql` before using the adapter.
+
+## Integration Tests
+
+The default test suite does not require a running database. To exercise this
+adapter against real Postgres, set `MDSRS_POSTGRES_URL` and run:
+
+```sh
+pnpm --filter @mdsrs/postgres-drizzle test:integration
+```
+
+The integration test creates a temporary schema, runs the migration, and drops
+the schema when it finishes.

package/dist/index.d.ts

@@ -0,0 +1,33 @@
+import { type CardPerformance } from '@mdsrs/core';
+import { type CardStats, type SrsStore, type StoredCard, type StoredReview } from '@mdsrs/store';
+import { type SrsCardRow, type SrsReviewRow } from './schema.js';
+export { mdsrsCards, mdsrsReviews, schema, srsCards, srsReviews } from './schema.js';
+export type { MdsrsCardRow, MdsrsReviewRow, NewMdsrsCardRow, NewMdsrsReviewRow, NewSrsCardRow, NewSrsReviewRow, SrsCardRow, SrsReviewRow } from './schema.js';
+export interface DrizzlePostgresDatabase {
+    select: (fields?: unknown) => unknown;
+    insert: (table: unknown) => unknown;
+    update: (table: unknown) => unknown;
+}
+export declare const createPostgresDrizzleStore: (db: DrizzlePostgresDatabase) => SrsStore;
+export declare const rowToPerformance: (row: Pick<SrsCardRow, "lastReviewedAt" | "stability" | "difficulty" | "intervalRaw" | "intervalDays" | "dueDate" | "reviewCount">) => CardPerformance;
+export declare const rowToStoredCard: (row: SrsCardRow) => StoredCard;
+export declare const rowToStoredReview: (row: SrsReviewRow) => StoredReview;
+interface StatsRow {
+    cardHash: string;
+    reviewCount: number;
+    difficulty: number | null;
+    stability: number | null;
+    intervalDays: number | null;
+    dueDate: string | null;
+    lastReviewedAt: Date | string | null;
+    active: boolean;
+    forgotCount: number | string | bigint;
+    hardCount: number | string | bigint;
+    goodCount: number | string | bigint;
+    easyCount: number | string | bigint;
+}
+export declare const statsRowToCardStats: (row: StatsRow) => CardStats;
+export declare const migrations: {
+    initial: import("url").URL;
+};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAA+C,KAAK,eAAe,EAAc,MAAM,aAAa,CAAC;AAC5G,OAAO,EAEN,KAAK,SAAS,EACd,KAAK,QAAQ,EACb,KAAK,UAAU,EACf,KAAK,YAAY,EACjB,MAAM,cAAc,CAAC;AACtB,OAAO,EAIN,KAAK,UAAU,EACf,KAAK,YAAY,EAEjB,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACrF,YAAY,EACX,YAAY,EACZ,cAAc,EACd,eAAe,EACf,iBAAiB,EACjB,aAAa,EACb,eAAe,EACf,UAAU,EACV,YAAY,EACZ,MAAM,aAAa,CAAC;AAErB,MAAM,WAAW,uBAAuB;IACvC,MAAM,EAAE,CAAC,MAAM,CAAC,EAAE,OAAO,KAAK,OAAO,CAAC;IACtC,MAAM,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC;IACpC,MAAM,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC;CACpC;AAED,eAAO,MAAM,0BAA0B,GAAI,IAAI,uBAAuB,KAAG,QA2KvE,CAAC;AA4BH,eAAO,MAAM,gBAAgB,GAAI,KAAK,IAAI,CAAC,UAAU,EAAE,gBAAgB,GAAG,WAAW,GAAG,YAAY,GAAG,aAAa,GAAG,cAAc,GAAG,SAAS,GAAG,aAAa,CAAC,KAAG,eAQnK,CAAC;AAEH,eAAO,MAAM,eAAe,GAAI,KAAK,UAAU,KAAG,UAYhD,CAAC;AAEH,eAAO,MAAM,iBAAiB,GAAI,KAAK,YAAY,KAAG,YAUpD,CAAC;AAEH,UAAU,QAAQ;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,cAAc,EAAE,IAAI,GAAG,MAAM,GAAG,IAAI,CAAC;IACrC,MAAM,EAAE,OAAO,CAAC;IAChB,WAAW,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;IACtC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;IACpC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;IACpC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;CACpC;AAED,eAAO,MAAM,mBAAmB,GAAI,KAAK,QAAQ,KAAG,SAuBnD,CAAC;AAUF,eAAO,MAAM,UAAU;;CAEtB,CAAC"}

package/dist/index.js

@@ -0,0 +1,206 @@
+import { and, asc, eq, inArray, not, sql } from 'drizzle-orm';
+import { buildReviewQueue, scheduleReview } from '@mdsrs/core';
+import { CardNotFoundError } from '@mdsrs/store';
+import { srsCards, srsReviews } from './schema.js';
+export { mdsrsCards, mdsrsReviews, schema, srsCards, srsReviews } from './schema.js';
+export const createPostgresDrizzleStore = (db) => ({
+    async syncCards(cards, syncedAt = new Date()) {
+        const database = db;
+        if (cards.length === 0) {
+            await database.update(srsCards).set({ active: false });
+            return;
+        }
+        const cardHashes = cards.map((card) => card.hash);
+        await database
+            .insert(srsCards)
+            .values(cards.map((card) => ({
+            cardHash: card.hash,
+            deckName: card.deckName,
+            filePath: card.filePath,
+            familyHash: card.familyHash,
+            frontMarkdown: card.frontMarkdown,
+            backMarkdown: card.backMarkdown,
+            cardType: card.content.type,
+            active: true,
+            addedAt: syncedAt,
+            lastSeenAt: syncedAt
+        })))
+            .onConflictDoUpdate({
+            target: srsCards.cardHash,
+            set: {
+                deckName: sql `excluded.deck_name`,
+                filePath: sql `excluded.file_path`,
+                familyHash: sql `excluded.family_hash`,
+                frontMarkdown: sql `excluded.front_markdown`,
+                backMarkdown: sql `excluded.back_markdown`,
+                cardType: sql `excluded.card_type`,
+                active: true,
+                lastSeenAt: syncedAt
+            }
+        });
+        await database
+            .update(srsCards)
+            .set({ active: false })
+            .where(not(inArray(srsCards.cardHash, cardHashes)));
+    },
+    async getCards(cardHashes) {
+        const database = db;
+        const query = database.select().from(srsCards);
+        const rows = (cardHashes && cardHashes.length > 0
+            ? await query.where(inArray(srsCards.cardHash, cardHashes))
+            : await query);
+        return new Map(rows.map((row) => [row.cardHash, rowToStoredCard(row)]));
+    },
+    async getPerformances(cardHashes) {
+        if (cardHashes.length === 0)
+            return new Map();
+        const database = db;
+        const rows = (await database
+            .select()
+            .from(srsCards)
+            .where(and(inArray(srsCards.cardHash, cardHashes), eq(srsCards.active, true))));
+        return new Map(rows.map((row) => [row.cardHash, rowToPerformance(row)]));
+    },
+    async getDueCards(cards, options = {}) {
+        const activeCards = await this.getCards(cards.map((card) => card.hash));
+        const syncedCards = cards.filter((card) => activeCards.get(card.hash)?.active);
+        const performances = await this.getPerformances(syncedCards.map((card) => card.hash));
+        return buildReviewQueue(syncedCards, performances, options);
+    },
+    async reviewCard(cardHash, grade, reviewedAt = new Date()) {
+        const database = db;
+        const rows = (await database
+            .select()
+            .from(srsCards)
+            .where(and(eq(srsCards.cardHash, cardHash), eq(srsCards.active, true)))
+            .limit(1));
+        const row = rows[0];
+        if (!row)
+            throw new CardNotFoundError(cardHash);
+        const result = scheduleReview(rowToPerformance(row), grade, reviewedAt);
+        const reviewedAtDate = new Date(result.lastReviewedAt);
+        await database
+            .update(srsCards)
+            .set({
+            lastReviewedAt: reviewedAtDate,
+            stability: result.stability,
+            difficulty: result.difficulty,
+            intervalRaw: result.intervalRaw,
+            intervalDays: result.intervalDays,
+            dueDate: result.dueDate,
+            reviewCount: result.reviewCount
+        })
+            .where(eq(srsCards.cardHash, cardHash));
+        const review = {
+            reviewCardHash: cardHash,
+            reviewedAt: reviewedAtDate,
+            grade,
+            stability: result.stability,
+            difficulty: result.difficulty,
+            intervalRaw: result.intervalRaw,
+            intervalDays: result.intervalDays,
+            dueDate: result.dueDate
+        };
+        await database.insert(srsReviews).values(review);
+        return result;
+    },
+    async getReviews(cardHashes) {
+        const database = db;
+        const query = database.select().from(srsReviews);
+        const filtered = cardHashes && cardHashes.length > 0
+            ? query.where(inArray(srsReviews.reviewCardHash, cardHashes))
+            : query;
+        const rows = (await filtered.orderBy(asc(srsReviews.reviewedAt), asc(srsReviews.reviewId)));
+        return rows.map(rowToStoredReview);
+    },
+    async getCardStats(cardHashes) {
+        if (cardHashes.length === 0)
+            return new Map();
+        const database = db;
+        const rows = await database
+            .select({
+            cardHash: srsCards.cardHash,
+            reviewCount: srsCards.reviewCount,
+            difficulty: srsCards.difficulty,
+            stability: srsCards.stability,
+            intervalDays: srsCards.intervalDays,
+            dueDate: srsCards.dueDate,
+            lastReviewedAt: srsCards.lastReviewedAt,
+            active: srsCards.active,
+            forgotCount: sql `count(*) filter (where ${srsReviews.grade} = 'forgot')`,
+            hardCount: sql `count(*) filter (where ${srsReviews.grade} = 'hard')`,
+            goodCount: sql `count(*) filter (where ${srsReviews.grade} = 'good')`,
+            easyCount: sql `count(*) filter (where ${srsReviews.grade} = 'easy')`
+        })
+            .from(srsCards)
+            .leftJoin(srsReviews, eq(srsReviews.reviewCardHash, srsCards.cardHash))
+            .where(inArray(srsCards.cardHash, cardHashes))
+            .groupBy(srsCards.cardHash, srsCards.reviewCount, srsCards.difficulty, srsCards.stability, srsCards.intervalDays, srsCards.dueDate, srsCards.lastReviewedAt, srsCards.active);
+        return new Map(rows.map((row) => [row.cardHash, statsRowToCardStats(row)]));
+    }
+});
+export const rowToPerformance = (row) => ({
+    lastReviewedAt: toIsoString(row.lastReviewedAt),
+    stability: row.stability,
+    difficulty: row.difficulty,
+    intervalRaw: row.intervalRaw,
+    intervalDays: row.intervalDays,
+    dueDate: row.dueDate,
+    reviewCount: row.reviewCount
+});
+export const rowToStoredCard = (row) => ({
+    cardHash: row.cardHash,
+    deckName: row.deckName,
+    filePath: row.filePath,
+    familyHash: row.familyHash,
+    frontMarkdown: row.frontMarkdown,
+    backMarkdown: row.backMarkdown,
+    cardType: row.cardType === 'cloze' ? 'cloze' : 'basic',
+    active: row.active,
+    addedAt: toIsoString(row.addedAt) ?? new Date(0).toISOString(),
+    lastSeenAt: toIsoString(row.lastSeenAt) ?? new Date(0).toISOString(),
+    performance: rowToPerformance(row)
+});
+export const rowToStoredReview = (row) => ({
+    reviewId: row.reviewId,
+    cardHash: row.reviewCardHash,
+    reviewedAt: toIsoString(row.reviewedAt) ?? new Date(0).toISOString(),
+    grade: toGrade(row.grade),
+    stability: row.stability,
+    difficulty: row.difficulty,
+    intervalRaw: row.intervalRaw,
+    intervalDays: row.intervalDays,
+    dueDate: row.dueDate
+});
+export const statsRowToCardStats = (row) => {
+    const forgotCount = Number(row.forgotCount);
+    const hardCount = Number(row.hardCount);
+    const goodCount = Number(row.goodCount);
+    const easyCount = Number(row.easyCount);
+    const hitCount = hardCount + goodCount + easyCount;
+    return {
+        cardHash: row.cardHash,
+        reviewCount: row.reviewCount,
+        forgotCount,
+        hardCount,
+        goodCount,
+        easyCount,
+        hitRate: row.reviewCount === 0 ? null : hitCount / row.reviewCount,
+        missRate: row.reviewCount === 0 ? null : forgotCount / row.reviewCount,
+        difficulty: row.difficulty,
+        stability: row.stability,
+        intervalDays: row.intervalDays,
+        dueDate: row.dueDate,
+        lastReviewedAt: toIsoString(row.lastReviewedAt),
+        active: row.active
+    };
+};
+const toIsoString = (value) => value instanceof Date ? value.toISOString() : value;
+const toGrade = (value) => {
+    if (value === 'forgot' || value === 'hard' || value === 'good' || value === 'easy')
+        return value;
+    throw new Error(`Invalid review grade in database: ${value}`);
+};
+export const migrations = {
+    initial: new URL('../migrations/0000_initial.sql', import.meta.url)
+};