How andyruix1/db-sheets works
Project Type and Purpose
• This is an open-source Node.js / TypeScript library (“db-sheets”) whose sole responsibility is to provide a programmatic façade for Google Sheets.
• It exposes a single entry point (SheetsManager) that client code imports to connect, cache, read, write, update, and delete rows in Google Sheets.
File-Structure Analysis
• Top-level: configuration files (package.json, tsconfig.json, Jest, nodemon), build helper (post-compile.ts), lock files.
• src/index.ts exports the public API (SheetsManager).
• src/lib/: core modules –
• Cache.ts implements both “RAM” and “JSON file” caching strategies.
• Sheet.ts (or SheetsManager) contains the logic for all sheet operations.
• help.ts and util.ts hold low-level utilities (e.g., parsing cell coordinates, building request payloads).
• src/types/: TypeScript definitions for Cache and Sheet.
a. Client Application
– Imports and instantiates SheetsManager with credentials & options.
b. SheetsManager (API Layer / Facade)
– Exposes methods: setSheetInfo(), getTableHeaders(), getTableValues(), insertValues(), updateValues(), deleteRowsByFilter().
c. Cache Layer
– Two modes: in-memory (fast) or JSON file (persistent).
– Controls fetch/update frequency to minimize Google API calls.
d. Google Sheets REST API
– External service that actually stores the spreadsheet data.
e. File System (optional)
– Stores JSON cache files when “saveMode: 'json'” is selected.
Interactions & Data Flow
1. Client → SheetsManager: calls an operation (e.g., getTableValues).
2. SheetsManager → Cache Layer: asks “do I have fresh data?”
– If yes → Cache returns JSON objects → SheetsManager returns to Client.
– If no → SheetsManager → Google Sheets API: sends HTTP request.
• Google responds with raw ranges.
• SheetsManager transforms them into JSON objects via util.ts.
• SheetsManager → Cache Layer: store updated data.
• SheetsManager → Client: returns JSON.
3. For write/update/delete, the reverse: Client → SheetsManager → Google Sheets API → update remote → update cache.
Architectural Patterns & Principles
• Facade Pattern: SheetsManager provides a simplified interface over the complex Google Sheets API.
• Strategy Pattern: Cache.ts chooses between RAM or JSON-file strategies.
• Single Responsibility: each module handles one concern (caching vs. sheet-operations vs. utilities).
• Modular & Pluggable: low-level utilities separated for testability and reuse.