@vue-skuilder/db 0.1.4 → 0.1.6

package/CLAUDE.md

@@ -0,0 +1,43 @@
+# @vue-skuilder/db Package
+
+Database abstraction layer providing unified interfaces for CouchDB/PouchDB and static data providers.
+
+## Commands
+- Build: `yarn workspace @vue-skuilder/db build`
+- Dev (watch): `yarn workspace @vue-skuilder/db dev`
+- Lint: `yarn workspace @vue-skuilder/db lint:fix`
+- Type check: `tsc --noEmit` (no dedicated script)
+
+## Build System
+Uses **tsup** for dual CommonJS/ESM output:
+- **ESM**: `dist/index.mjs` (primary)
+- **CommonJS**: `dist/index.js` (Jest compatibility)
+- **Types**: `dist/index.d.ts`
+
+## Package Exports
+Multiple entry points for different use cases:
+- **Main**: Core interfaces and factory
+- **Core**: Core types and interfaces only
+- **Pouch**: PouchDB implementation
+- **Packer**: Static data packing utilities  
+- **Static**: Static data provider implementation
+
+## Dependencies
+- `@vue-skuilder/common` - Shared types and utilities
+- `pouchdb` - Client-side database
+- `pouchdb-find` - Query plugin
+- `@nilock2/pouchdb-authentication` - Auth plugin
+
+## Architecture
+- **Interfaces**: Abstract DB layer contracts (`core/interfaces/`)
+- **Implementations**: 
+  - CouchDB/PouchDB provider (`impl/couch/`)
+  - Static data provider (`impl/static/`)
+- **Study System**: Spaced repetition logic (`study/`)
+- **Utilities**: Logging, packing tools (`util/`)
+
+## Key Features
+- **Provider Pattern**: Switchable backend implementations
+- **Dual Export**: Works in both Node.js and browser environments  
+- **Type Safety**: Full TypeScript coverage with strict mode
+- **Sync Strategy**: Configurable online/offline data synchronization

package/dist/SyncStrategy-DnJRj-Xp.d.mts

@@ -0,0 +1,74 @@
+import { Status } from '@vue-skuilder/common';
+
+/**
+ * Common types used by UserDB implementations across different sync strategies
+ */
+
+/**
+ * Result type for account creation operations
+ */
+interface AccountCreationResult {
+    status: Status;
+    error?: string;
+}
+/**
+ * Result type for authentication operations
+ */
+interface AuthenticationResult {
+    ok: boolean;
+    error?: string;
+}
+
+/**
+ * Strategy interface for handling user data synchronization
+ * Different implementations handle remote sync vs local-only storage
+ */
+interface SyncStrategy {
+    /**
+     * Set up the remote database for a user
+     * @param username The username to set up remote DB for
+     * @returns PouchDB database instance (may be same as local for no-op)
+     */
+    setupRemoteDB(username: string): PouchDB.Database;
+    /**
+     * Start synchronization between local and remote databases
+     * @param localDB The local PouchDB instance
+     * @param remoteDB The remote PouchDB instance
+     */
+    startSync(localDB: PouchDB.Database, remoteDB: PouchDB.Database): void;
+    /**
+     * Stop synchronization (optional - for cleanup)
+     */
+    stopSync?(): void;
+    /**
+     * Whether this strategy supports account creation
+     */
+    canCreateAccount(): boolean;
+    /**
+     * Whether this strategy supports authentication
+     */
+    canAuthenticate(): boolean;
+    /**
+     * Create a new user account (if supported)
+     * @param username The username for the new account
+     * @param password The password for the new account
+     */
+    createAccount?(username: string, password: string): Promise<AccountCreationResult>;
+    /**
+     * Authenticate a user (if supported)
+     * @param username The username to authenticate
+     * @param password The password to authenticate with
+     */
+    authenticate?(username: string, password: string): Promise<AuthenticationResult>;
+    /**
+     * Log out the current user (if supported)
+     */
+    logout?(): Promise<AuthenticationResult>;
+    /**
+     * Get the current logged-in username
+     * Returns the username if logged in, or a default guest username
+     */
+    getCurrentUsername(): Promise<string>;
+}
+
+export type { AccountCreationResult as A, SyncStrategy as S, AuthenticationResult as a };

package/dist/SyncStrategy-DnJRj-Xp.d.ts

@@ -0,0 +1,74 @@
+import { Status } from '@vue-skuilder/common';
+
+/**
+ * Common types used by UserDB implementations across different sync strategies
+ */
+
+/**
+ * Result type for account creation operations
+ */
+interface AccountCreationResult {
+    status: Status;
+    error?: string;
+}
+/**
+ * Result type for authentication operations
+ */
+interface AuthenticationResult {
+    ok: boolean;
+    error?: string;
+}
+
+/**
+ * Strategy interface for handling user data synchronization
+ * Different implementations handle remote sync vs local-only storage
+ */
+interface SyncStrategy {
+    /**
+     * Set up the remote database for a user
+     * @param username The username to set up remote DB for
+     * @returns PouchDB database instance (may be same as local for no-op)
+     */
+    setupRemoteDB(username: string): PouchDB.Database;
+    /**
+     * Start synchronization between local and remote databases
+     * @param localDB The local PouchDB instance
+     * @param remoteDB The remote PouchDB instance
+     */
+    startSync(localDB: PouchDB.Database, remoteDB: PouchDB.Database): void;
+    /**
+     * Stop synchronization (optional - for cleanup)
+     */
+    stopSync?(): void;
+    /**
+     * Whether this strategy supports account creation
+     */
+    canCreateAccount(): boolean;
+    /**
+     * Whether this strategy supports authentication
+     */
+    canAuthenticate(): boolean;
+    /**
+     * Create a new user account (if supported)
+     * @param username The username for the new account
+     * @param password The password for the new account
+     */
+    createAccount?(username: string, password: string): Promise<AccountCreationResult>;
+    /**
+     * Authenticate a user (if supported)
+     * @param username The username to authenticate
+     * @param password The password to authenticate with
+     */
+    authenticate?(username: string, password: string): Promise<AuthenticationResult>;
+    /**
+     * Log out the current user (if supported)
+     */
+    logout?(): Promise<AuthenticationResult>;
+    /**
+     * Get the current logged-in username
+     * Returns the username if logged in, or a default guest username
+     */
+    getCurrentUsername(): Promise<string>;
+}
+
+export type { AccountCreationResult as A, SyncStrategy as S, AuthenticationResult as a };

package/dist/core/index.d.mts

@@ -1,3 +1,91 @@
-export { V as ActivityRecord, A as AdminDBInterface, g as AssignedCard, d as AssignedContent, f as AssignedCourse, e as AssignedTag, a7 as BulkCardProcessorConfig, H as CardData, O as CardHistory, C as CardRecord, b as ClassroomDBInterface, w as ClassroomRegistration, v as ClassroomRegistrationDesignation, x as ClassroomRegistrationDoc, a3 as ContentNavigator, n as ContentSourceID, r as CourseDBInterface, q as CourseInfo, I as CourseListData, W as CourseRegistration, X as CourseRegistrationDoc, p as CoursesDBInterface, D as DataLayerProvider, M as DataShapeData, J as DisplayableData, z as DocType, K as Field, G as GuestUsername, a6 as ImportResult, L as Loggable, a2 as Navigators, Q as QuestionData, P as QuestionRecord, Y as ScheduledCard, B as SkuilderCourseData, c as StudentClassroomDBInterface, a as StudyContentSource, h as StudySessionFailedItem, i as StudySessionFailedNewItem, j as StudySessionFailedReviewItem, S as StudySessionItem, k as StudySessionNewItem, l as StudySessionReviewItem, E as Tag, F as TagStub, T as TeacherClassroomDBInterface, R as UserConfig, t as UserCourseSetting, s as UserCourseSettings, U as UserDBInterface, u as UsrCrsDataInterface, Z as areQuestionRecords, N as cardHistoryPrefix, a1 as docIsDeleted, $ as getCardHistoryID, o as getStudySource, a4 as importParsedCards, _ as isQuestionRecord, m as isReview, y as log, a0 as parseCardHistoryID, a5 as validateProcessorConfig } from '../index-QMtzQI65.mjs';
-import '@vue-skuilder/common';
+import { c as StudyContentSource, U as UserDBInterface, C as CourseDBInterface, H as ContentNavigationStrategyData, m as StudySessionReviewItem, D as ScheduledCard, l as StudySessionNewItem } from '../userDB-31gsvxyd.mjs';
+export { y as ActivityRecord, A as AdminDBInterface, h as AssignedCard, e as AssignedContent, g as AssignedCourse, f as AssignedTag, b as ClassroomDBInterface, v as ClassroomRegistration, u as ClassroomRegistrationDesignation, w as ClassroomRegistrationDoc, o as ContentSourceID, q as CourseInfo, z as CourseRegistration, B as CourseRegistrationDoc, a as CoursesDBInterface, d as StudentClassroomDBInterface, i as StudySessionFailedItem, j as StudySessionFailedNewItem, k as StudySessionFailedReviewItem, S as StudySessionItem, T as TeacherClassroomDBInterface, x as UserConfig, s as UserCourseSetting, r as UserCourseSettings, t as UsrCrsDataInterface, p as getStudySource, n as isReview } from '../userDB-31gsvxyd.mjs';
+export { D as DataLayerProvider } from '../dataLayerProvider-BZmLyBVw.mjs';
+import { g as CardHistory, C as CardRecord, h as QuestionRecord } from '../types-legacy-WPe8CtO-.mjs';
+export { b as CardData, c as CourseListData, e as DataShapeData, d as DisplayableData, D as DocType, F as Field, G as GuestUsername, Q as QuestionData, S as SkuilderCourseData, T as Tag, a as TagStub, f as cardHistoryPrefix, l as log } from '../types-legacy-WPe8CtO-.mjs';
+import { DataShape, ParsedCard } from '@vue-skuilder/common';
 import 'moment';
+
+declare abstract class Loggable {
+    protected abstract readonly _className: string;
+    protected log(...args: unknown[]): void;
+    protected error(...args: unknown[]): void;
+}
+
+declare function areQuestionRecords(h: CardHistory<CardRecord>): h is CardHistory<QuestionRecord>;
+declare function isQuestionRecord(c: CardRecord): c is QuestionRecord;
+declare function getCardHistoryID(courseID: string, cardID: string): PouchDB.Core.DocumentId;
+declare function parseCardHistoryID(id: string): {
+    courseID: string;
+    cardID: string;
+};
+interface PouchDBError extends Error {
+    error?: string;
+    reason?: string;
+}
+declare function docIsDeleted(e: PouchDBError): boolean;
+
+declare enum Navigators {
+    ELO = "elo"
+}
+/**
+ * A content-navigator provides runtime steering of study sessions.
+ */
+declare abstract class ContentNavigator implements StudyContentSource {
+    /**
+     *
+     * @param user
+     * @param strategyData
+     * @returns the runtime object used to steer a study session.
+     */
+    static create(user: UserDBInterface, course: CourseDBInterface, strategyData: ContentNavigationStrategyData): Promise<ContentNavigator>;
+    abstract getPendingReviews(): Promise<(StudySessionReviewItem & ScheduledCard)[]>;
+    abstract getNewCards(n?: number): Promise<StudySessionNewItem[]>;
+}
+
+/**
+ * Interface representing the result of a bulk import operation for a single card
+ */
+interface ImportResult {
+    /** The original text input for the card */
+    originalText: string;
+    /** Status of the import operation */
+    status: 'success' | 'error';
+    /** Message describing the result or error */
+    message: string;
+    /** ID of the newly created card (only for success) */
+    cardId?: string;
+}
+/**
+ * Configuration for the bulk card processor
+ */
+interface BulkCardProcessorConfig {
+    /** The data shape to use for the cards */
+    dataShape: DataShape;
+    /** The course code used for adding notes */
+    courseCode: string;
+    /** The username of the current user */
+    userName: string;
+}
+
+/**
+ * Processes multiple cards from bulk text input
+ *
+ * @param parsedCards - Array of parsed cards to import
+ * @param courseDB - Course database interface
+ * @param config - Configuration for the card processor
+ * @returns Array of import results
+ */
+declare function importParsedCards(parsedCards: ParsedCard[], courseDB: CourseDBInterface, config: BulkCardProcessorConfig): Promise<ImportResult[]>;
+/**
+ * Validates the configuration for bulk card processing
+ *
+ * @param config - Configuration to validate
+ * @returns Object with validation result and error message if any
+ */
+declare function validateProcessorConfig(config: Partial<BulkCardProcessorConfig>): {
+    isValid: boolean;
+    errorMessage?: string;
+};
+
+export { type BulkCardProcessorConfig, CardHistory, CardRecord, ContentNavigator, CourseDBInterface, type ImportResult, Loggable, Navigators, QuestionRecord, ScheduledCard, StudyContentSource, StudySessionNewItem, StudySessionReviewItem, UserDBInterface, areQuestionRecords, docIsDeleted, getCardHistoryID, importParsedCards, isQuestionRecord, parseCardHistoryID, validateProcessorConfig };

package/dist/core/index.d.ts

@@ -1,3 +1,91 @@
-export { V as ActivityRecord, A as AdminDBInterface, g as AssignedCard, d as AssignedContent, f as AssignedCourse, e as AssignedTag, a7 as BulkCardProcessorConfig, H as CardData, O as CardHistory, C as CardRecord, b as ClassroomDBInterface, w as ClassroomRegistration, v as ClassroomRegistrationDesignation, x as ClassroomRegistrationDoc, a3 as ContentNavigator, n as ContentSourceID, r as CourseDBInterface, q as CourseInfo, I as CourseListData, W as CourseRegistration, X as CourseRegistrationDoc, p as CoursesDBInterface, D as DataLayerProvider, M as DataShapeData, J as DisplayableData, z as DocType, K as Field, G as GuestUsername, a6 as ImportResult, L as Loggable, a2 as Navigators, Q as QuestionData, P as QuestionRecord, Y as ScheduledCard, B as SkuilderCourseData, c as StudentClassroomDBInterface, a as StudyContentSource, h as StudySessionFailedItem, i as StudySessionFailedNewItem, j as StudySessionFailedReviewItem, S as StudySessionItem, k as StudySessionNewItem, l as StudySessionReviewItem, E as Tag, F as TagStub, T as TeacherClassroomDBInterface, R as UserConfig, t as UserCourseSetting, s as UserCourseSettings, U as UserDBInterface, u as UsrCrsDataInterface, Z as areQuestionRecords, N as cardHistoryPrefix, a1 as docIsDeleted, $ as getCardHistoryID, o as getStudySource, a4 as importParsedCards, _ as isQuestionRecord, m as isReview, y as log, a0 as parseCardHistoryID, a5 as validateProcessorConfig } from '../index-QMtzQI65.js';
-import '@vue-skuilder/common';
+import { c as StudyContentSource, U as UserDBInterface, C as CourseDBInterface, H as ContentNavigationStrategyData, m as StudySessionReviewItem, D as ScheduledCard, l as StudySessionNewItem } from '../userDB-D9EuWTp1.js';
+export { y as ActivityRecord, A as AdminDBInterface, h as AssignedCard, e as AssignedContent, g as AssignedCourse, f as AssignedTag, b as ClassroomDBInterface, v as ClassroomRegistration, u as ClassroomRegistrationDesignation, w as ClassroomRegistrationDoc, o as ContentSourceID, q as CourseInfo, z as CourseRegistration, B as CourseRegistrationDoc, a as CoursesDBInterface, d as StudentClassroomDBInterface, i as StudySessionFailedItem, j as StudySessionFailedNewItem, k as StudySessionFailedReviewItem, S as StudySessionItem, T as TeacherClassroomDBInterface, x as UserConfig, s as UserCourseSetting, r as UserCourseSettings, t as UsrCrsDataInterface, p as getStudySource, n as isReview } from '../userDB-D9EuWTp1.js';
+export { D as DataLayerProvider } from '../dataLayerProvider-BuntXkCs.js';
+import { g as CardHistory, C as CardRecord, h as QuestionRecord } from '../types-legacy-WPe8CtO-.js';
+export { b as CardData, c as CourseListData, e as DataShapeData, d as DisplayableData, D as DocType, F as Field, G as GuestUsername, Q as QuestionData, S as SkuilderCourseData, T as Tag, a as TagStub, f as cardHistoryPrefix, l as log } from '../types-legacy-WPe8CtO-.js';
+import { DataShape, ParsedCard } from '@vue-skuilder/common';
 import 'moment';
+
+declare abstract class Loggable {
+    protected abstract readonly _className: string;
+    protected log(...args: unknown[]): void;
+    protected error(...args: unknown[]): void;
+}
+
+declare function areQuestionRecords(h: CardHistory<CardRecord>): h is CardHistory<QuestionRecord>;
+declare function isQuestionRecord(c: CardRecord): c is QuestionRecord;
+declare function getCardHistoryID(courseID: string, cardID: string): PouchDB.Core.DocumentId;
+declare function parseCardHistoryID(id: string): {
+    courseID: string;
+    cardID: string;
+};
+interface PouchDBError extends Error {
+    error?: string;
+    reason?: string;
+}
+declare function docIsDeleted(e: PouchDBError): boolean;
+
+declare enum Navigators {
+    ELO = "elo"
+}
+/**
+ * A content-navigator provides runtime steering of study sessions.
+ */
+declare abstract class ContentNavigator implements StudyContentSource {
+    /**
+     *
+     * @param user
+     * @param strategyData
+     * @returns the runtime object used to steer a study session.
+     */
+    static create(user: UserDBInterface, course: CourseDBInterface, strategyData: ContentNavigationStrategyData): Promise<ContentNavigator>;
+    abstract getPendingReviews(): Promise<(StudySessionReviewItem & ScheduledCard)[]>;
+    abstract getNewCards(n?: number): Promise<StudySessionNewItem[]>;
+}
+
+/**
+ * Interface representing the result of a bulk import operation for a single card
+ */
+interface ImportResult {
+    /** The original text input for the card */
+    originalText: string;
+    /** Status of the import operation */
+    status: 'success' | 'error';
+    /** Message describing the result or error */
+    message: string;
+    /** ID of the newly created card (only for success) */
+    cardId?: string;
+}
+/**
+ * Configuration for the bulk card processor
+ */
+interface BulkCardProcessorConfig {
+    /** The data shape to use for the cards */
+    dataShape: DataShape;
+    /** The course code used for adding notes */
+    courseCode: string;
+    /** The username of the current user */
+    userName: string;
+}
+
+/**
+ * Processes multiple cards from bulk text input
+ *
+ * @param parsedCards - Array of parsed cards to import
+ * @param courseDB - Course database interface
+ * @param config - Configuration for the card processor
+ * @returns Array of import results
+ */
+declare function importParsedCards(parsedCards: ParsedCard[], courseDB: CourseDBInterface, config: BulkCardProcessorConfig): Promise<ImportResult[]>;
+/**
+ * Validates the configuration for bulk card processing
+ *
+ * @param config - Configuration to validate
+ * @returns Object with validation result and error message if any
+ */
+declare function validateProcessorConfig(config: Partial<BulkCardProcessorConfig>): {
+    isValid: boolean;
+    errorMessage?: string;
+};
+
+export { type BulkCardProcessorConfig, CardHistory, CardRecord, ContentNavigator, CourseDBInterface, type ImportResult, Loggable, Navigators, QuestionRecord, ScheduledCard, StudyContentSource, StudySessionNewItem, StudySessionReviewItem, UserDBInterface, areQuestionRecords, docIsDeleted, getCardHistoryID, importParsedCards, isQuestionRecord, parseCardHistoryID, validateProcessorConfig };