From d91888da7199cdde7662910debfffaa758b8a128 Mon Sep 17 00:00:00 2001 From: nsfisis Date: Sun, 7 Dec 2025 19:03:12 +0900 Subject: feat(client): add Dexie.js setup for IndexedDB local storage MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Set up Dexie database with LocalDeck, LocalCard, and LocalReviewLog tables for offline support. Each entity includes _synced flag for tracking synchronization status. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- src/client/db/index.test.ts | 307 ++++++++++++++++++++++++++++++++++++++++++++ src/client/db/index.ts | 129 +++++++++++++++++++ 2 files changed, 436 insertions(+) create mode 100644 src/client/db/index.test.ts create mode 100644 src/client/db/index.ts (limited to 'src') diff --git a/src/client/db/index.test.ts b/src/client/db/index.test.ts new file mode 100644 index 0000000..c1a62f5 --- /dev/null +++ b/src/client/db/index.test.ts @@ -0,0 +1,307 @@ +/** + * @vitest-environment jsdom + */ +import "fake-indexeddb/auto"; +import { afterEach, beforeEach, describe, expect, it } from "vitest"; +import { + CardState, + db, + type LocalCard, + type LocalDeck, + type LocalReviewLog, + Rating, +} from "./index"; + +describe("KiokuDatabase", () => { + beforeEach(async () => { + // Clear database before each test + await db.decks.clear(); + await db.cards.clear(); + await db.reviewLogs.clear(); + }); + + afterEach(async () => { + // Clean up after tests + await db.decks.clear(); + await db.cards.clear(); + await db.reviewLogs.clear(); + }); + + describe("database initialization", () => { + it("should have decks table", () => { + expect(db.decks).toBeDefined(); + }); + + it("should have cards table", () => { + expect(db.cards).toBeDefined(); + }); + + it("should have reviewLogs table", () => { + expect(db.reviewLogs).toBeDefined(); + }); + + it("should be named kioku", () => { + expect(db.name).toBe("kioku"); + }); + }); + + describe("decks table", () => { + const testDeck: LocalDeck = { + id: "deck-1", + userId: "user-1", + name: "Test Deck", + description: "A test deck", + newCardsPerDay: 20, + createdAt: new Date("2024-01-01"), + updatedAt: new Date("2024-01-01"), + deletedAt: null, + syncVersion: 0, + _synced: false, + }; + + it("should add and retrieve a deck", async () => { + await db.decks.add(testDeck); + const retrieved = await db.decks.get("deck-1"); + expect(retrieved).toEqual(testDeck); + }); + + it("should find unsynced decks", async () => { + await db.decks.add(testDeck); + await db.decks.add({ + ...testDeck, + id: "deck-2", + name: "Synced Deck", + _synced: true, + }); + + const unsynced = await db.decks.filter((d) => !d._synced).toArray(); + expect(unsynced).toHaveLength(1); + expect(unsynced[0]?.id).toBe("deck-1"); + }); + + it("should find decks by userId", async () => { + await db.decks.add(testDeck); + await db.decks.add({ + ...testDeck, + id: "deck-2", + userId: "user-2", + }); + + const userDecks = await db.decks + .where("userId") + .equals("user-1") + .toArray(); + expect(userDecks).toHaveLength(1); + expect(userDecks[0]?.id).toBe("deck-1"); + }); + + it("should update a deck", async () => { + await db.decks.add(testDeck); + await db.decks.update("deck-1", { + name: "Updated Deck", + _synced: false, + }); + + const updated = await db.decks.get("deck-1"); + expect(updated?.name).toBe("Updated Deck"); + }); + + it("should delete a deck", async () => { + await db.decks.add(testDeck); + await db.decks.delete("deck-1"); + + const deleted = await db.decks.get("deck-1"); + expect(deleted).toBeUndefined(); + }); + }); + + describe("cards table", () => { + const testCard: LocalCard = { + id: "card-1", + deckId: "deck-1", + front: "Question", + back: "Answer", + state: CardState.New, + due: new Date("2024-01-01"), + stability: 0, + difficulty: 0, + elapsedDays: 0, + scheduledDays: 0, + reps: 0, + lapses: 0, + lastReview: null, + createdAt: new Date("2024-01-01"), + updatedAt: new Date("2024-01-01"), + deletedAt: null, + syncVersion: 0, + _synced: false, + }; + + it("should add and retrieve a card", async () => { + await db.cards.add(testCard); + const retrieved = await db.cards.get("card-1"); + expect(retrieved).toEqual(testCard); + }); + + it("should find cards by deckId", async () => { + await db.cards.add(testCard); + await db.cards.add({ + ...testCard, + id: "card-2", + deckId: "deck-2", + }); + + const deckCards = await db.cards + .where("deckId") + .equals("deck-1") + .toArray(); + expect(deckCards).toHaveLength(1); + expect(deckCards[0]?.id).toBe("card-1"); + }); + + it("should find due cards", async () => { + const now = new Date(); + const past = new Date(now.getTime() - 1000 * 60 * 60); + const future = new Date(now.getTime() + 1000 * 60 * 60); + + await db.cards.add({ ...testCard, id: "card-past", due: past }); + await db.cards.add({ ...testCard, id: "card-future", due: future }); + + const dueCards = await db.cards.where("due").belowOrEqual(now).toArray(); + expect(dueCards).toHaveLength(1); + expect(dueCards[0]?.id).toBe("card-past"); + }); + + it("should find cards by state", async () => { + await db.cards.add(testCard); + await db.cards.add({ + ...testCard, + id: "card-2", + state: CardState.Review, + }); + + const newCards = await db.cards + .where("state") + .equals(CardState.New) + .toArray(); + expect(newCards).toHaveLength(1); + expect(newCards[0]?.id).toBe("card-1"); + }); + + it("should find unsynced cards", async () => { + await db.cards.add(testCard); + await db.cards.add({ + ...testCard, + id: "card-2", + _synced: true, + }); + + const unsynced = await db.cards.filter((c) => !c._synced).toArray(); + expect(unsynced).toHaveLength(1); + expect(unsynced[0]?.id).toBe("card-1"); + }); + }); + + describe("reviewLogs table", () => { + const testReviewLog: LocalReviewLog = { + id: "review-1", + cardId: "card-1", + userId: "user-1", + rating: Rating.Good, + state: CardState.New, + scheduledDays: 1, + elapsedDays: 0, + reviewedAt: new Date("2024-01-01"), + durationMs: 5000, + syncVersion: 0, + _synced: false, + }; + + it("should add and retrieve a review log", async () => { + await db.reviewLogs.add(testReviewLog); + const retrieved = await db.reviewLogs.get("review-1"); + expect(retrieved).toEqual(testReviewLog); + }); + + it("should find review logs by cardId", async () => { + await db.reviewLogs.add(testReviewLog); + await db.reviewLogs.add({ + ...testReviewLog, + id: "review-2", + cardId: "card-2", + }); + + const cardReviews = await db.reviewLogs + .where("cardId") + .equals("card-1") + .toArray(); + expect(cardReviews).toHaveLength(1); + expect(cardReviews[0]?.id).toBe("review-1"); + }); + + it("should find review logs by userId", async () => { + await db.reviewLogs.add(testReviewLog); + await db.reviewLogs.add({ + ...testReviewLog, + id: "review-2", + userId: "user-2", + }); + + const userReviews = await db.reviewLogs + .where("userId") + .equals("user-1") + .toArray(); + expect(userReviews).toHaveLength(1); + expect(userReviews[0]?.id).toBe("review-1"); + }); + + it("should find unsynced review logs", async () => { + await db.reviewLogs.add(testReviewLog); + await db.reviewLogs.add({ + ...testReviewLog, + id: "review-2", + _synced: true, + }); + + const unsynced = await db.reviewLogs.filter((r) => !r._synced).toArray(); + expect(unsynced).toHaveLength(1); + expect(unsynced[0]?.id).toBe("review-1"); + }); + + it("should order review logs by reviewedAt", async () => { + const earlier = new Date("2024-01-01"); + const later = new Date("2024-01-02"); + + await db.reviewLogs.add({ + ...testReviewLog, + id: "review-later", + reviewedAt: later, + }); + await db.reviewLogs.add({ + ...testReviewLog, + id: "review-earlier", + reviewedAt: earlier, + }); + + const sorted = await db.reviewLogs.orderBy("reviewedAt").toArray(); + expect(sorted[0]?.id).toBe("review-earlier"); + expect(sorted[1]?.id).toBe("review-later"); + }); + }); + + describe("constants", () => { + it("should export CardState enum", () => { + expect(CardState.New).toBe(0); + expect(CardState.Learning).toBe(1); + expect(CardState.Review).toBe(2); + expect(CardState.Relearning).toBe(3); + }); + + it("should export Rating enum", () => { + expect(Rating.Again).toBe(1); + expect(Rating.Hard).toBe(2); + expect(Rating.Good).toBe(3); + expect(Rating.Easy).toBe(4); + }); + }); +}); diff --git a/src/client/db/index.ts b/src/client/db/index.ts new file mode 100644 index 0000000..4c381d2 --- /dev/null +++ b/src/client/db/index.ts @@ -0,0 +1,129 @@ +import Dexie, { type EntityTable } from "dexie"; + +/** + * Card states for FSRS algorithm + */ +export const CardState = { + New: 0, + Learning: 1, + Review: 2, + Relearning: 3, +} as const; + +export type CardStateType = (typeof CardState)[keyof typeof CardState]; + +/** + * Rating values for reviews + */ +export const Rating = { + Again: 1, + Hard: 2, + Good: 3, + Easy: 4, +} as const; + +export type RatingType = (typeof Rating)[keyof typeof Rating]; + +/** + * Local deck stored in IndexedDB + * Includes _synced flag for offline sync tracking + */ +export interface LocalDeck { + id: string; + userId: string; + name: string; + description: string | null; + newCardsPerDay: number; + createdAt: Date; + updatedAt: Date; + deletedAt: Date | null; + syncVersion: number; + _synced: boolean; +} + +/** + * Local card stored in IndexedDB + * Includes _synced flag for offline sync tracking + */ +export interface LocalCard { + id: string; + deckId: string; + front: string; + back: string; + + // FSRS fields + state: CardStateType; + due: Date; + stability: number; + difficulty: number; + elapsedDays: number; + scheduledDays: number; + reps: number; + lapses: number; + lastReview: Date | null; + + createdAt: Date; + updatedAt: Date; + deletedAt: Date | null; + syncVersion: number; + _synced: boolean; +} + +/** + * Local review log stored in IndexedDB + * Includes _synced flag for offline sync tracking + * ReviewLog is append-only (no conflicts possible) + */ +export interface LocalReviewLog { + id: string; + cardId: string; + userId: string; + rating: RatingType; + state: CardStateType; + scheduledDays: number; + elapsedDays: number; + reviewedAt: Date; + durationMs: number | null; + syncVersion: number; + _synced: boolean; +} + +/** + * Kioku local database using Dexie (IndexedDB wrapper) + * + * This database stores decks, cards, and review logs locally for offline support. + * Each entity has a _synced flag to track whether it has been synchronized with the server. + */ +export class KiokuDatabase extends Dexie { + decks!: EntityTable; + cards!: EntityTable; + reviewLogs!: EntityTable; + + constructor() { + super("kioku"); + + this.version(1).stores({ + // Primary key is 'id', indexed fields follow + // userId: for filtering by user + // updatedAt: for sync ordering + // Note: _synced is not indexed (boolean fields can't be indexed in IndexedDB) + // Use .filter() to find unsynced items + decks: "id, userId, updatedAt", + + // deckId: for filtering cards by deck + // due: for finding due cards + // state: for filtering by card state + cards: "id, deckId, updatedAt, due, state", + + // cardId: for finding reviews for a card + // userId: for filtering by user + // reviewedAt: for ordering reviews + reviewLogs: "id, cardId, userId, reviewedAt", + }); + } +} + +/** + * Singleton instance of the Kioku database + */ +export const db = new KiokuDatabase(); -- cgit v1.2.3-70-g09d2