@vue-skuilder/db 0.1.6 → 0.1.8-0

package/src/impl/couch/courseAPI.ts

@@ -6,10 +6,11 @@ import { NameSpacer, ShapeDescriptor } from '@vue-skuilder/common';
 import { CourseConfig, DataShape } from '@vue-skuilder/common';
 import { CourseElo, blankCourseElo, toCourseElo } from '@vue-skuilder/common';
 import { CourseDB, createTag } from './courseDB';
-import { CardData, DisplayableData, DocType, Tag } from '../../core/types/types-legacy';
+import { CardData, DisplayableData, DocType, Tag, DocTypePrefixes } from '../../core/types/types-legacy';
 import { prepareNote55 } from '@vue-skuilder/common';
 import { BaseUser } from '../common';
 import { logger } from '@db/util/logger';
+import { v4 as uuidv4 } from 'uuid';
 
 /**
  *
@@ -33,9 +34,8 @@ export async function addNote55(
 ): Promise<PouchDB.Core.Response> {
   const db = getCourseDB(courseID);
   const payload = prepareNote55(courseID, codeCourse, shape, data, author, tags, uploads);
-  // [ ] NAMESPACING: consider put( _id: "displayable_data-uuid")
-  //     consider also semantic hashing
-  const result = await db.post<DisplayableData>(payload);
+  const _id = `${DocTypePrefixes[DocType.DISPLAYABLE_DATA]}-${uuidv4()}`;
+  const result = await db.put<DisplayableData>({ ...payload, _id });
 
   const dataShapeId = NameSpacer.getDataShapeString({
     course: codeCourse,
@@ -153,9 +153,10 @@ async function addCard(
   tags: string[],
   author: string
 ): Promise<PouchDB.Core.Response> {
-  // [ ] NAMESPACING: consider put( _id: "card-uuid")
   const db = getCourseDB(courseID);
-  const card = await db.post<CardData>({
+  const _id = `${DocTypePrefixes[DocType.CARD]}-${uuidv4()}`;
+  const card = await db.put<CardData>({
+    _id,
     course,
     id_displayable_data,
     id_view,

package/src/impl/couch/courseLookupDB.ts

@@ -97,6 +97,30 @@ export default class CourseLookup {
     return resp.id;
   }
 
+  /**
+   * Adds a new course to the lookup database with a specific courseID
+   * @param courseId The specific course ID to use
+   * @param courseName The course name
+   * @param disambiguator Optional disambiguator
+   * @returns Promise<void>
+   */
+  static async addWithId(
+    courseId: string, 
+    courseName: string, 
+    disambiguator?: string
+  ): Promise<void> {
+    const doc: Omit<CourseLookupDoc, '_rev'> = {
+      _id: courseId,
+      name: courseName,
+    };
+    
+    if (disambiguator) {
+      doc.disambiguator = disambiguator;
+    }
+
+    await CourseLookup._db.put(doc);
+  }
+
   /**
    * Removes a course from the index
    * @param courseID

package/src/impl/couch/index.ts

@@ -1,5 +1,11 @@
 import { ENV } from '@db/factory';
-import { DocType, GuestUsername, log, SkuilderCourseData } from '../../core/types/types-legacy';
+import {
+  DocType,
+  DocTypePrefixes,
+  GuestUsername,
+  log,
+  SkuilderCourseData,
+} from '../../core/types/types-legacy';
 // import { getCurrentUser } from '../../stores/useAuthStore';
 import moment, { Moment } from 'moment';
 import { logger } from '@db/util/logger';
@@ -155,7 +161,6 @@ export async function getRandomCards(courseIDs: string[]) {
   }
 }
 
-export const REVIEW_PREFIX: string = 'card_review_';
 export const REVIEW_TIME_FORMAT: string = 'YYYY-MM-DD--kk:mm:ss-SSS';
 
 export function getCouchUserDB(username: string): PouchDB.Database {
@@ -191,11 +196,11 @@ export function scheduleCardReview(review: {
   const now = moment.utc();
   logger.info(`Scheduling for review in: ${review.time.diff(now, 'h') / 24} days`);
   void getCouchUserDB(review.user).put<ScheduledCard>({
-    _id: REVIEW_PREFIX + review.time.format(REVIEW_TIME_FORMAT),
+    _id: DocTypePrefixes[DocType.SCHEDULED_CARD] + review.time.format(REVIEW_TIME_FORMAT),
     cardId: review.card_id,
-    reviewTime: review.time,
+    reviewTime: review.time.toISOString(),
     courseId: review.course_id,
-    scheduledAt: now,
+    scheduledAt: now.toISOString(),
     scheduledFor: review.scheduledFor,
     schedulingAgentId: review.schedulingAgentId,
   });

package/src/impl/couch/updateQueue.ts

@@ -12,7 +12,8 @@ export default class UpdateQueue extends Loggable {
     [index: string]: boolean;
   } = {};
 
-  private db: PouchDB.Database;
+  private readDB: PouchDB.Database; // Database for read operations
+  private writeDB: PouchDB.Database; // Database for write operations (local-first)
 
   public update<T extends PouchDB.Core.Document<object>>(
     id: PouchDB.Core.DocumentId,
@@ -27,21 +28,24 @@ export default class UpdateQueue extends Loggable {
     return this.applyUpdates<T>(id);
   }
 
-  constructor(db: PouchDB.Database) {
+  constructor(readDB: PouchDB.Database, writeDB?: PouchDB.Database) {
     super();
     // PouchDB.debug.enable('*');
-    this.db = db;
+    this.readDB = readDB;
+    this.writeDB = writeDB || readDB; // Default to readDB if writeDB not provided
     logger.debug(`UpdateQ initialized...`);
-    void this.db.info().then((i) => {
+    void this.readDB.info().then((i) => {
       logger.debug(`db info: ${JSON.stringify(i)}`);
     });
   }
 
-  private async applyUpdates<T extends PouchDB.Core.Document<object>>(id: string): Promise<T> {
+  private async applyUpdates<T extends PouchDB.Core.Document<object>>(
+    id: string
+  ): Promise<T & PouchDB.Core.GetMeta & PouchDB.Core.RevisionIdMeta> {
     logger.debug(`Applying updates on doc: ${id}`);
     if (this.inprogressUpdates[id]) {
       // console.log(`Updates in progress...`);
-      await this.db.info(); // stall for a round trip
+      await this.readDB.info(); // stall for a round trip
       // console.log(`Retrying...`);
       return this.applyUpdates<T>(id);
     } else {
@@ -49,7 +53,7 @@ export default class UpdateQueue extends Loggable {
         this.inprogressUpdates[id] = true;
 
         try {
-          let doc = await this.db.get<T>(id);
+          let doc = await this.readDB.get<T>(id);
           logger.debug(`Retrieved doc: ${id}`);
           while (this.pendingUpdates[id].length !== 0) {
             const update = this.pendingUpdates[id].splice(0, 1)[0];
@@ -66,7 +70,7 @@ export default class UpdateQueue extends Loggable {
           //   console.log(`${k}: ${typeof k}`);
           // }
           // console.log(`Applied updates to doc: ${JSON.stringify(doc)}`);
-          await this.db.put<T>(doc);
+          await this.writeDB.put<T>(doc);
           logger.debug(`Put doc: ${id}`);
 
           if (this.pendingUpdates[id].length === 0) {

package/src/impl/couch/user-course-relDB.ts

@@ -4,20 +4,18 @@ import {
   UserCourseSettings,
   UsrCrsDataInterface,
 } from '@db/core';
+
 import moment, { Moment } from 'moment';
-import { getStartAndEndKeys, REVIEW_PREFIX, REVIEW_TIME_FORMAT } from '.';
-import { CourseDB } from './courseDB';
-import { User } from './userDB';
+
+import { UserDBInterface } from '@db/core';
 import { logger } from '../../util/logger';
 
 export class UsrCrsData implements UsrCrsDataInterface {
-  private user: User;
-  private course: CourseDB;
+  private user: UserDBInterface;
   private _courseId: string;
 
-  constructor(user: User, courseId: string) {
+  constructor(user: UserDBInterface, courseId: string) {
     this.user = user;
-    this.course = new CourseDB(courseId, async () => this.user);
     this._courseId = courseId;
   }
 
@@ -47,32 +45,24 @@ export class UsrCrsData implements UsrCrsDataInterface {
     }
   }
   public updateCourseSettings(updates: UserCourseSetting[]): void {
-    void this.user.updateCourseSettings(this._courseId, updates);
+    // TODO: Add updateCourseSettings method to UserDBInterface
+    // For now, we'll need to cast to access the concrete implementation
+    if ('updateCourseSettings' in this.user) {
+      void (this.user as any).updateCourseSettings(this._courseId, updates);
+    }
   }
 
   private async getReviewstoDate(targetDate: Moment) {
-    const keys = getStartAndEndKeys(REVIEW_PREFIX);
-
-    const reviews = await this.user.remote().allDocs<ScheduledCard>({
-      startkey: keys.startkey,
-      endkey: keys.endkey,
-      include_docs: true,
-    });
+    // Use the interface method instead of direct database access
+    const allReviews = await this.user.getPendingReviews(this._courseId);
 
     logger.debug(
       `Fetching ${this.user.getUsername()}'s scheduled reviews for course ${this._courseId}.`
     );
-    return reviews.rows
-      .filter((r) => {
-        if (r.id.startsWith(REVIEW_PREFIX)) {
-          const date = moment.utc(r.id.substr(REVIEW_PREFIX.length), REVIEW_TIME_FORMAT);
-          if (targetDate.isAfter(date)) {
-            if (this._courseId === undefined || r.doc!.courseId === this._courseId) {
-              return true;
-            }
-          }
-        }
-      })
-      .map((r) => r.doc!);
+
+    return allReviews.filter((review: ScheduledCard) => {
+      const reviewTime = moment.utc(review.reviewTime);
+      return targetDate.isAfter(reviewTime);
+    });
   }
 }

package/src/impl/static/NoOpSyncStrategy.ts

@@ -17,6 +17,11 @@ export class NoOpSyncStrategy implements SyncStrategy {
     return getLocalUserDB(username);
   }
 
+  getWriteDB(username: string): PouchDB.Database {
+    // In static mode, always write to local database
+    return getLocalUserDB(username);
+  }
+
   startSync(_localDB: PouchDB.Database, _remoteDB: PouchDB.Database): void {
     // No-op - in static mode, local and remote are the same database instance
     // PouchDB sync with itself is harmless and efficient

package/src/impl/static/StaticDataUnpacker.ts

@@ -2,7 +2,7 @@
 
 import { StaticCourseManifest, ChunkMetadata } from '../../util/packer/types';
 import { logger } from '../../util/logger';
-import { DocType } from '@db/core';
+import { DocType, DocTypePrefixes } from '@db/core';
 
 // Browser-compatible path utilities
 const pathUtils = {
@@ -151,57 +151,38 @@ export class StaticDataUnpacker {
     return (await this.loadIndex('tags')) as TagsIndex;
   }
 
+  private getDocTypeFromId(id: string): DocType | undefined {
+    for (const docTypeKey in DocTypePrefixes) {
+      const prefix = DocTypePrefixes[docTypeKey as DocType];
+      if (id.startsWith(`${prefix}-`)) {
+        return docTypeKey as DocType;
+      }
+    }
+    return undefined;
+  }
+
   /**
    * Find which chunk contains a specific document ID
    */
   private async findChunkForDocument(docId: string): Promise<ChunkMetadata | undefined> {
-    // Determine document type from ID pattern by checking all DocType enum members
-    let expectedDocType: DocType | undefined = undefined;
-
-    // Check for ID prefixes matching any DocType enum value
-    for (const docType of Object.values(DocType)) {
-      if (docId.startsWith(`${docType}-`)) {
-        expectedDocType = docType;
-        break;
-      }
-    }
+    const expectedDocType = this.getDocTypeFromId(docId);
 
-    if (expectedDocType !== undefined) {
-      // Use chunk filtering by docType for documents with recognized prefixes
+    if (expectedDocType) {
       const typeChunks = this.manifest.chunks.filter((c) => c.docType === expectedDocType);
 
       for (const chunk of typeChunks) {
         if (docId >= chunk.startKey && docId <= chunk.endKey) {
-          // Verify document actually exists in chunk
           const exists = await this.verifyDocumentInChunk(docId, chunk);
           if (exists) {
             return chunk;
           }
         }
       }
-
-      return undefined;
     } else {
-      // Fall back to trying all chunk types with strict verification
-      // Since card IDs and displayable data IDs can overlap in range, we need to verify actual existence
-
-      // First try DISPLAYABLE_DATA chunks (most likely for documents without prefixes)
-      const displayableChunks = this.manifest.chunks.filter(
-        (c) => c.docType === 'DISPLAYABLE_DATA'
-      );
-      for (const chunk of displayableChunks) {
-        if (docId >= chunk.startKey && docId <= chunk.endKey) {
-          // Verify document actually exists in chunk
-          const exists = await this.verifyDocumentInChunk(docId, chunk);
-          if (exists) {
-            return chunk;
-          }
-        }
-      }
-
-      // Then try CARD chunks (for legacy card IDs without prefixes)
-      const cardChunks = this.manifest.chunks.filter((c) => c.docType === 'CARD');
-      for (const chunk of cardChunks) {
+      // Fallback for documents without recognized prefixes (e.g., CourseConfig, or old documents)
+      // This part remains for backward compatibility and non-prefixed documents.
+      // It's less efficient but necessary if not all document types are prefixed.
+      for (const chunk of this.manifest.chunks) {
         if (docId >= chunk.startKey && docId <= chunk.endKey) {
           // Verify document actually exists in chunk
           const exists = await this.verifyDocumentInChunk(docId, chunk);
@@ -227,6 +208,7 @@ export class StaticDataUnpacker {
 
       return undefined;
     }
+    return undefined;
   }
 
   /**

package/src/impl/static/courseDB.ts

@@ -15,6 +15,7 @@ import { DataLayerResult } from '../../core/types/db';
 import { ContentNavigationStrategyData } from '../../core/types/contentNavigationStrategy';
 import { ScheduledCard } from '../../core/types/user';
 import { Navigators } from '../../core/navigators';
+import { logger } from '../../util/logger';
 
 export class StaticCourseDB implements CourseDBInterface {
   constructor(
@@ -41,10 +42,15 @@ export class StaticCourseDB implements CourseDBInterface {
   }
 
   async getCourseInfo(): Promise<CourseInfo> {
-    // This would need to be pre-computed in the manifest
+    // Count only cards, not all documents
+    // Use chunks metadata to count card documents specifically
+    const cardCount = this.manifest.chunks
+      .filter((chunk) => chunk.docType === DocType.CARD)
+      .reduce((total, chunk) => total + chunk.documentCount, 0);
+
     return {
-      cardCount: 0, // Would come from manifest
-      registeredUsers: 0,
+      cardCount,
+      registeredUsers: 0, // Always 0 in static mode
     };
   }
 
@@ -158,13 +164,61 @@ export class StaticCourseDB implements CourseDBInterface {
     }));
   }
 
-  async getAppliedTags(_cardId: string): Promise<PouchDB.Query.Response<TagStub>> {
-    // Would need to query the tag index
-    return {
-      total_rows: 0,
-      offset: 0,
-      rows: [],
-    };
+  async getAppliedTags(cardId: string): Promise<PouchDB.Query.Response<TagStub>> {
+    try {
+      const tagsIndex = await this.unpacker.getTagsIndex();
+      const cardTags = tagsIndex.byCard[cardId] || [];
+
+      const rows = await Promise.all(
+        cardTags.map(async (tagName) => {
+          const tagId = `${DocType.TAG}-${tagName}`;
+
+          try {
+            // Try to get the full tag document
+            const tagDoc = await this.unpacker.getDocument(tagId);
+            return {
+              id: tagId,
+              key: cardId,
+              value: {
+                name: tagDoc.name,
+                snippet: tagDoc.snippet,
+                count: tagDoc.taggedCards?.length || 0,
+              },
+            };
+          } catch (error) {
+            if (error && (error as PouchDB.Core.Error).status === 404) {
+              logger.warn(`Tag document not found for ${tagName}, creating stub`);
+            } else {
+              logger.error(`Error getting tag document for ${tagName}:`, error);
+              throw error;
+            }
+            // If tag document not found, create a minimal stub
+            return {
+              id: tagId,
+              key: cardId,
+              value: {
+                name: tagName,
+                snippet: `Tag: ${tagName}`,
+                count: tagsIndex.byTag[tagName]?.length || 0,
+              },
+            };
+          }
+        })
+      );
+
+      return {
+        total_rows: rows.length,
+        offset: 0,
+        rows,
+      };
+    } catch (error) {
+      logger.error(`Error getting applied tags for card ${cardId}:`, error);
+      return {
+        total_rows: 0,
+        offset: 0,
+        rows: [],
+      };
+    }
   }
 
   async addTagToCard(_cardId: string, _tagId: string): Promise<PouchDB.Core.Response> {
@@ -188,12 +242,76 @@ export class StaticCourseDB implements CourseDBInterface {
   }
 
   async getCourseTagStubs(): Promise<PouchDB.Core.AllDocsResponse<Tag>> {
-    // Would query all tag documents
-    return {
-      total_rows: 0,
-      offset: 0,
-      rows: [],
-    };
+    try {
+      const tagsIndex = await this.unpacker.getTagsIndex();
+
+      if (!tagsIndex || !tagsIndex.byTag) {
+        logger.warn('Tags index not found or empty');
+        return {
+          total_rows: 0,
+          offset: 0,
+          rows: [],
+        };
+      }
+
+      // Create tag stubs from the index
+      const tagNames = Object.keys(tagsIndex.byTag);
+      const rows = await Promise.all(
+        tagNames.map(async (tagName) => {
+          const cardIds = tagsIndex.byTag[tagName] || [];
+          const tagId = `${DocType.TAG}-${tagName}`;
+
+          try {
+            // Try to get the full tag document
+            const tagDoc = await this.unpacker.getDocument(tagId);
+            return {
+              id: tagId,
+              key: tagId,
+              value: { rev: '1-static' },
+              doc: tagDoc,
+            };
+          } catch (error) {
+            // If tag document not found, create a minimal stub
+            if (error && (error as PouchDB.Core.Error).status === 404) {
+              logger.warn(`Tag document not found for ${tagName}, creating stub`);
+              const stubDoc = {
+                _id: tagId,
+                _rev: '1-static',
+                course: this.courseId,
+                docType: DocType.TAG,
+                name: tagName,
+                snippet: `Tag: ${tagName}`,
+                wiki: '',
+                taggedCards: cardIds,
+                author: 'system',
+              };
+              return {
+                id: tagId,
+                key: tagId,
+                value: { rev: '1-static' },
+                doc: stubDoc,
+              };
+            } else {
+              logger.error(`Error getting tag document for ${tagName}:`, error);
+              throw error;
+            }
+          }
+        })
+      );
+
+      return {
+        total_rows: rows.length,
+        offset: 0,
+        rows,
+      };
+    } catch (error) {
+      logger.error('Failed to get course tag stubs:', error);
+      return {
+        total_rows: 0,
+        offset: 0,
+        rows: [],
+      };
+    }
   }
 
   async addNote(
@@ -256,7 +374,7 @@ export class StaticCourseDB implements CourseDBInterface {
   }
 
   // Attachment helper methods (internal use, not part of interface)
-  
+
   /**
    * Get attachment URL for a document and attachment name
    * Internal helper method for static attachment serving

package/src/util/dataDirectory.test.ts

@@ -0,0 +1,53 @@
+// Test suite for cross-platform data directory utilities
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import * as os from 'os';
+import * as path from 'path';
+import { getAppDataDirectory, getDbPath, ensureAppDataDirectory } from './dataDirectory';
+
+describe('dataDirectory utilities', () => {
+  const originalHomedir = os.homedir;
+  const testHome = '/test/home';
+
+  beforeEach(() => {
+    // Mock os.homedir for consistent testing
+    (os as any).homedir = () => testHome;
+  });
+
+  afterEach(() => {
+    // Restore original function
+    os.homedir = originalHomedir;
+  });
+
+  describe('getAppDataDirectory', () => {
+    it('should return correct path using home directory', () => {
+      const result = getAppDataDirectory();
+      expect(result).toBe(path.join(testHome, '.tuilder'));
+    });
+  });
+
+  describe('getDbPath', () => {
+    it('should return correct database path', () => {
+      const dbName = 'userdb-testuser';
+      const result = getDbPath(dbName);
+      expect(result).toBe(path.join(testHome, '.tuilder', dbName));
+    });
+
+    it('should handle special characters in username', () => {
+      const dbName = 'userdb-test@user.com';
+      const result = getDbPath(dbName);
+      expect(result).toBe(path.join(testHome, '.tuilder', dbName));
+    });
+  });
+
+  describe('ensureAppDataDirectory', () => {
+    it('should handle path creation gracefully', async () => {
+      // Note: This test doesn't actually create directories since we're testing logic
+      // In a real test environment, you'd want to use a temp directory
+      expect(typeof ensureAppDataDirectory).toBe('function');
+      
+      // Test the function exists and returns a promise
+      const result = ensureAppDataDirectory();
+      expect(result).toBeInstanceOf(Promise);
+    });
+  });
+});

package/src/util/dataDirectory.ts

@@ -0,0 +1,52 @@
+// Cross-platform data directory utilities for PouchDB
+// Provides OS-appropriate application data directories
+
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+import { logger } from './tuiLogger';
+
+/**
+ * Get the application data directory for the current platform
+ * Uses ~/.tuilder as requested by user for simplicity
+ */
+export function getAppDataDirectory(): string {
+  return path.join(os.homedir(), '.tuilder');
+}
+
+/**
+ * Ensure the application data directory exists
+ * Creates directory recursively if it doesn't exist
+ */
+export async function ensureAppDataDirectory(): Promise<string> {
+  const appDataDir = getAppDataDirectory();
+  
+  try {
+    await fs.promises.mkdir(appDataDir, { recursive: true });
+  } catch (err: any) {
+    if (err.code !== 'EEXIST') {
+      throw new Error(`Failed to create app data directory ${appDataDir}: ${err.message}`);
+    }
+  }
+  
+  return appDataDir;
+}
+
+/**
+ * Get the full path for a PouchDB database file
+ * @param dbName - The database name (e.g., 'userdb-Colin')
+ */
+export function getDbPath(dbName: string): string {
+  return path.join(getAppDataDirectory(), dbName);
+}
+
+/**
+ * Initialize data directory for PouchDB usage
+ * Should be called once at application startup
+ */
+export async function initializeDataDirectory(): Promise<void> {
+  await ensureAppDataDirectory();
+  
+  // Log initialization
+  logger.info(`PouchDB data directory initialized: ${getAppDataDirectory()}`);
+}

package/src/util/index.ts

@@ -1,2 +1,5 @@
 export * from './Loggable';
 export * from './packer';
+export * from './migrator';
+export * from './dataDirectory';
+export * from './tuiLogger';