@objectql/driver-excel 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,215 @@
+/**
+ * Excel Driver for ObjectQL (Production-Ready)
+ *
+ * A driver for ObjectQL that reads and writes data from Excel (.xlsx) files.
+ * Each worksheet in the Excel file represents an object type, with the first row
+ * containing column headers (field names) and subsequent rows containing data.
+ *
+ * ✅ Features:
+ * - Read data from Excel files
+ * - Write data back to Excel files
+ * - Multiple sheets support (one sheet per object type)
+ * - Full CRUD operations
+ * - Query support (filters, sorting, pagination)
+ * - Automatic data type handling
+ * - Secure: Uses ExcelJS (no known vulnerabilities)
+ *
+ * Use Cases:
+ * - Import/export data from Excel spreadsheets
+ * - Use Excel as a simple database for prototyping
+ * - Data migration from Excel to other databases
+ * - Generate reports in Excel format
+ */
+import { Driver } from '@objectql/types';
+/**
+ * File storage mode for the Excel driver.
+ */
+export type FileStorageMode = 'single-file' | 'file-per-object';
+/**
+ * Configuration options for the Excel driver.
+ */
+export interface ExcelDriverConfig {
+    /**
+     * Path to the Excel file or directory.
+     * - In 'single-file' mode: Path to a single .xlsx file
+     * - In 'file-per-object' mode: Path to a directory where object files are stored
+     */
+    filePath: string;
+    /**
+     * File storage mode (default: 'single-file')
+     * - 'single-file': All object types stored as worksheets in one Excel file
+     * - 'file-per-object': Each object type stored in a separate Excel file
+     */
+    fileStorageMode?: FileStorageMode;
+    /** Optional: Auto-save changes to file (default: true) */
+    autoSave?: boolean;
+    /** Optional: Create file if it doesn't exist (default: true) */
+    createIfMissing?: boolean;
+    /** Optional: Enable strict mode (throw on missing objects) */
+    strictMode?: boolean;
+}
+/**
+ * Excel Driver Implementation
+ *
+ * Stores ObjectQL documents in Excel worksheets. Each object type is stored
+ * in a separate worksheet, with the first row containing column headers.
+ *
+ * Uses ExcelJS library for secure Excel file operations.
+ */
+export declare class ExcelDriver implements Driver {
+    private config;
+    private workbook;
+    private workbooks;
+    private data;
+    private idCounters;
+    private filePath;
+    private fileStorageMode;
+    constructor(config: ExcelDriverConfig);
+    /**
+     * Initialize the driver by loading the workbook from file.
+     * This must be called after construction before using the driver.
+     */
+    init(): Promise<void>;
+    /**
+     * Factory method to create and initialize the driver.
+     */
+    static create(config: ExcelDriverConfig): Promise<ExcelDriver>;
+    /**
+     * Load workbook from file or create a new one.
+     * Handles both single-file and file-per-object modes.
+     */
+    private loadWorkbook;
+    /**
+     * Load workbook in single-file mode (all objects in one Excel file).
+     */
+    private loadSingleFileWorkbook;
+    /**
+     * Load workbooks in file-per-object mode (each object in separate Excel file).
+     */
+    private loadFilePerObjectWorkbooks;
+    /**
+     * Load data from workbook into memory.
+     *
+     * Expected Excel format:
+     * - First row contains column headers (field names)
+     * - Subsequent rows contain data records
+     * - Each worksheet represents one object type
+     */
+    private loadDataFromWorkbook;
+    /**
+     * Load data from a single worksheet into memory.
+     */
+    private loadDataFromSingleWorksheet;
+    /**
+     * Update ID counter based on existing records.
+     *
+     * Attempts to extract counter from auto-generated IDs (format: objectName-timestamp-counter).
+     * If IDs don't follow this format, counter starts from existing record count.
+     */
+    private updateIdCounter;
+    /**
+     * Save workbook to file.
+     */
+    /**
+     * Save workbook to file.
+     * Handles both single-file and file-per-object modes.
+     */
+    private saveWorkbook;
+    /**
+     * Save workbook in single-file mode.
+     */
+    private saveSingleFileWorkbook;
+    /**
+     * Save workbook in file-per-object mode.
+     */
+    private saveFilePerObjectWorkbook;
+    /**
+     * Sync in-memory data to workbook.
+     *
+     * Creates or updates a worksheet for the given object type.
+     */
+    private syncToWorkbook;
+    /**
+     * Sync data to worksheet in single-file mode.
+     */
+    private syncToSingleFileWorkbook;
+    /**
+     * Sync data to separate file in file-per-object mode.
+     */
+    private syncToFilePerObjectWorkbook;
+    /**
+     * Find multiple records matching the query criteria.
+     */
+    find(objectName: string, query?: any, options?: any): Promise<any[]>;
+    /**
+     * Find a single record by ID or query.
+     */
+    findOne(objectName: string, id: string | number, query?: any, options?: any): Promise<any>;
+    /**
+     * Create a new record.
+     */
+    create(objectName: string, data: any, options?: any): Promise<any>;
+    /**
+     * Update an existing record.
+     */
+    update(objectName: string, id: string | number, data: any, options?: any): Promise<any>;
+    /**
+     * Delete a record.
+     */
+    delete(objectName: string, id: string | number, options?: any): Promise<any>;
+    /**
+     * Count records matching filters.
+     */
+    count(objectName: string, filters: any, options?: any): Promise<number>;
+    /**
+     * Get distinct values for a field.
+     */
+    distinct(objectName: string, field: string, filters?: any, options?: any): Promise<any[]>;
+    /**
+     * Create multiple records at once.
+     */
+    createMany(objectName: string, data: any[], options?: any): Promise<any>;
+    /**
+     * Update multiple records matching filters.
+     */
+    updateMany(objectName: string, filters: any, data: any, options?: any): Promise<any>;
+    /**
+     * Delete multiple records matching filters.
+     */
+    deleteMany(objectName: string, filters: any, options?: any): Promise<any>;
+    /**
+     * Manually save the workbook to file.
+     */
+    /**
+     * Manually save the workbook to file.
+     */
+    save(): Promise<void>;
+    /**
+     * Disconnect (flush any pending writes).
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Apply filters to an array of records (in-memory filtering).
+     */
+    private applyFilters;
+    /**
+     * Check if a single record matches the filter conditions.
+     */
+    private matchesFilters;
+    /**
+     * Evaluate a single filter condition.
+     */
+    private evaluateCondition;
+    /**
+     * Apply sorting to an array of records.
+     */
+    private applySort;
+    /**
+     * Project specific fields from a document.
+     */
+    private projectFields;
+    /**
+     * Generate a unique ID for a record.
+     */
+    private generateId;
+}