@mdsrs/store 0.0.0

package/README.md

@@ -0,0 +1,18 @@
+# @mdsrs/store
+
+Persistence interface and in-memory implementation for `mdsrs`.
+
+`@mdsrs/store` defines the contract that durable adapters, such as a future
+Postgres adapter, should implement.
+
+## Example
+
+```ts
+import { createMemoryStore } from '@mdsrs/store';
+
+const store = createMemoryStore();
+
+await store.syncCards(cards);
+const queue = await store.getDueCards(cards);
+await store.reviewCard(queue[0].card.hash, 'good');
+```

package/dist/index.d.ts

@@ -0,0 +1,66 @@
+import { type BuildReviewQueueOptions, type BuildCollectionStatsOptions, type Card, type CardPerformance, type CollectionStats, type DeckTreeNode, type Grade, type ReviewQueueItem, type ReviewResult } from '@mdsrs/core';
+export interface StoredCard {
+    cardHash: string;
+    deckName: string;
+    filePath: string;
+    familyHash: string | null;
+    frontMarkdown: string;
+    backMarkdown: string;
+    cardType: Card['content']['type'];
+    active: boolean;
+    addedAt: string;
+    lastSeenAt: string;
+    performance: CardPerformance;
+}
+export interface StoredReview {
+    reviewId: number;
+    cardHash: string;
+    reviewedAt: string;
+    grade: Grade;
+    stability: number;
+    difficulty: number;
+    intervalRaw: number;
+    intervalDays: number;
+    dueDate: string;
+}
+export interface CardStats {
+    cardHash: string;
+    reviewCount: number;
+    forgotCount: number;
+    hardCount: number;
+    goodCount: number;
+    easyCount: number;
+    hitRate: number | null;
+    missRate: number | null;
+    difficulty: number | null;
+    stability: number | null;
+    intervalDays: number | null;
+    dueDate: string | null;
+    lastReviewedAt: string | null;
+    active: boolean;
+}
+export interface SrsStore {
+    syncCards(cards: Card[], syncedAt?: Date): Promise<void>;
+    getCards(cardHashes?: string[]): Promise<Map<string, StoredCard>>;
+    getPerformances(cardHashes: string[]): Promise<Map<string, CardPerformance>>;
+    getDueCards(cards: Card[], options?: BuildReviewQueueOptions): Promise<ReviewQueueItem[]>;
+    reviewCard(cardHash: string, grade: Grade, reviewedAt?: Date): Promise<ReviewResult>;
+    /** Returns reviews oldest-to-newest by reviewedAt, then reviewId. */
+    getReviews(cardHashes?: string[]): Promise<StoredReview[]>;
+    getCardStats(cardHashes: string[]): Promise<Map<string, CardStats>>;
+}
+export declare const getCollectionStats: (store: SrsStore, cards: Card[], deckTree: DeckTreeNode[], options?: BuildCollectionStatsOptions) => Promise<CollectionStats>;
+export interface MemoryStoreSnapshot {
+    cards: StoredCard[];
+    reviews: StoredReview[];
+    nextReviewId: number;
+}
+export declare class CardNotFoundError extends Error {
+    readonly cardHash: string;
+    constructor(cardHash: string);
+}
+export declare const createMemoryStore: (snapshot?: Partial<MemoryStoreSnapshot>) => SrsStore & {
+    snapshot(): MemoryStoreSnapshot;
+};
+export declare const isOverdue: (performance: Pick<CardPerformance, "dueDate">, now?: Date) => boolean;
+//# 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":"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"}

package/dist/index.js

@@ -0,0 +1,188 @@
+import { buildCollectionStats, buildReviewQueue, scheduleReview, toDateString, toTimestamp } from '@mdsrs/core';
+export const getCollectionStats = async (store, cards, deckTree, options = {}) => {
+    const cardHashes = cards.map((card) => card.hash);
+    const [storedCards, reviews] = await Promise.all([
+        store.getCards(cardHashes),
+        store.getReviews(cardHashes)
+    ]);
+    return buildCollectionStats(cards, deckTree, [...storedCards.values()].map((card) => ({
+        cardHash: card.cardHash,
+        active: card.active,
+        addedAt: card.addedAt,
+        dueDate: card.performance.dueDate,
+        reviewCount: card.performance.reviewCount
+    })), reviews.map((review) => ({
+        cardHash: review.cardHash,
+        reviewedAt: review.reviewedAt,
+        grade: review.grade
+    })), options);
+};
+export class CardNotFoundError extends Error {
+    cardHash;
+    constructor(cardHash) {
+        super(`Card is not synced: ${cardHash}`);
+        this.cardHash = cardHash;
+    }
+}
+export const createMemoryStore = (snapshot) => {
+    const cards = new Map((snapshot?.cards ?? []).map((card) => [card.cardHash, cloneStoredCard(card)]));
+    const reviews = (snapshot?.reviews ?? []).map(cloneStoredReview);
+    let nextReviewId = snapshot?.nextReviewId ??
+        reviews.reduce((next, review) => Math.max(next, review.reviewId + 1), 1);
+    const store = {
+        async syncCards(sourceCards, syncedAt = new Date()) {
+            const lastSeenAt = toTimestamp(syncedAt);
+            const seenHashes = new Set();
+            for (const card of sourceCards) {
+                seenHashes.add(card.hash);
+                const existing = cards.get(card.hash);
+                const addedAt = existing?.addedAt ?? lastSeenAt;
+                cards.set(card.hash, {
+                    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,
+                    lastSeenAt,
+                    performance: existing?.performance
+                        ? clonePerformance(existing.performance)
+                        : emptyPerformance()
+                });
+            }
+            for (const [cardHash, card] of cards) {
+                if (!seenHashes.has(cardHash)) {
+                    cards.set(cardHash, {
+                        ...card,
+                        active: false
+                    });
+                }
+            }
+        },
+        async getCards(cardHashes) {
+            const wanted = cardHashes ? new Set(cardHashes) : null;
+            return new Map([...cards.entries()]
+                .filter(([cardHash]) => wanted == null || wanted.has(cardHash))
+                .map(([cardHash, card]) => [cardHash, cloneStoredCard(card)]));
+        },
+        async getPerformances(cardHashes) {
+            const performances = new Map();
+            for (const cardHash of cardHashes) {
+                const card = cards.get(cardHash);
+                if (card?.active)
+                    performances.set(cardHash, clonePerformance(card.performance));
+            }
+            return performances;
+        },
+        async getDueCards(sourceCards, options = {}) {
+            const activeHashes = new Set([...cards.values()].filter((card) => card.active).map((card) => card.cardHash));
+            const syncedCards = sourceCards.filter((card) => activeHashes.has(card.hash));
+            const performances = await this.getPerformances(syncedCards.map((card) => card.hash));
+            return buildReviewQueue(syncedCards, performances, options);
+        },
+        async reviewCard(cardHash, grade, reviewedAt = new Date()) {
+            const card = cards.get(cardHash);
+            if (!card?.active)
+                throw new CardNotFoundError(cardHash);
+            const result = scheduleReview(card.performance, grade, reviewedAt);
+            const performance = reviewResultToPerformance(result);
+            cards.set(cardHash, {
+                ...card,
+                performance
+            });
+            reviews.push({
+                reviewId: nextReviewId++,
+                cardHash,
+                reviewedAt: result.lastReviewedAt,
+                grade,
+                stability: result.stability,
+                difficulty: result.difficulty,
+                intervalRaw: result.intervalRaw,
+                intervalDays: result.intervalDays,
+                dueDate: result.dueDate
+            });
+            return result;
+        },
+        async getReviews(cardHashes) {
+            const wanted = cardHashes ? new Set(cardHashes) : null;
+            return reviews
+                .filter((review) => wanted == null || wanted.has(review.cardHash))
+                .sort(compareReviews)
+                .map(cloneStoredReview);
+        },
+        async getCardStats(cardHashes) {
+            const stats = new Map();
+            for (const cardHash of cardHashes) {
+                const card = cards.get(cardHash);
+                if (!card)
+                    continue;
+                const cardReviews = reviews.filter((review) => review.cardHash === cardHash);
+                const forgotCount = countGrade(cardReviews, 'forgot');
+                const hardCount = countGrade(cardReviews, 'hard');
+                const goodCount = countGrade(cardReviews, 'good');
+                const easyCount = countGrade(cardReviews, 'easy');
+                const hitCount = hardCount + goodCount + easyCount;
+                const reviewCount = card.performance.reviewCount;
+                stats.set(cardHash, {
+                    cardHash,
+                    reviewCount,
+                    forgotCount,
+                    hardCount,
+                    goodCount,
+                    easyCount,
+                    hitRate: reviewCount === 0 ? null : hitCount / reviewCount,
+                    missRate: reviewCount === 0 ? null : forgotCount / reviewCount,
+                    difficulty: card.performance.difficulty,
+                    stability: card.performance.stability,
+                    intervalDays: card.performance.intervalDays,
+                    dueDate: card.performance.dueDate,
+                    lastReviewedAt: card.performance.lastReviewedAt,
+                    active: card.active
+                });
+            }
+            return stats;
+        },
+        snapshot() {
+            return {
+                cards: [...cards.values()].map(cloneStoredCard),
+                reviews: reviews.map(cloneStoredReview),
+                nextReviewId
+            };
+        }
+    };
+    return store;
+};
+const emptyPerformance = () => ({
+    lastReviewedAt: null,
+    stability: null,
+    difficulty: null,
+    intervalRaw: null,
+    intervalDays: null,
+    dueDate: null,
+    reviewCount: 0
+});
+const reviewResultToPerformance = (result) => ({
+    lastReviewedAt: result.lastReviewedAt,
+    stability: result.stability,
+    difficulty: result.difficulty,
+    intervalRaw: result.intervalRaw,
+    intervalDays: result.intervalDays,
+    dueDate: result.dueDate,
+    reviewCount: result.reviewCount
+});
+const clonePerformance = (performance) => ({
+    ...performance
+});
+const cloneStoredCard = (card) => ({
+    ...card,
+    performance: clonePerformance(card.performance)
+});
+const cloneStoredReview = (review) => ({
+    ...review
+});
+const compareReviews = (left, right) => left.reviewedAt.localeCompare(right.reviewedAt) || left.reviewId - right.reviewId;
+const countGrade = (reviews, grade) => reviews.filter((review) => review.grade === grade).length;
+export const isOverdue = (performance, now = new Date()) => performance.dueDate != null && performance.dueDate < toDateString(now);

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@mdsrs/store",
+  "version": "0.0.0",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@mdsrs/core": "0.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "typescript": "^6.0.3",
+    "vitest": "^4.0.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
+}