Registry / database / database-js-xlsx

database-js-xlsx

JSON →
library1.0.6jsnpmunverified

The `database-js-xlsx` package provides a robust `database-js` compatible interface for interacting with Microsoft Excel XLSX files, acting as a crucial bridge between SQL-like queries and spreadsheet data. It is built upon the `xlsx-populate` library for efficient in-memory spreadsheet manipulation and utilizes `node-sqlparser` to interpret SQL commands. Currently stable at version 1.0.6, its release cadence is tied to its underlying dependencies and the `database-js` ecosystem, rather than a fixed schedule. A key advantage of `database-js-xlsx` is its cross-platform compatibility, a significant improvement over Windows-specific drivers within the `database-js` family, such as `database-js-adodb`. Developers should note that the library works with an in-memory copy of the spreadsheet; all changes are buffered and written back to disk only when the connection is explicitly closed. This design means any external modifications to the file during an active connection will be overwritten. The SQL capabilities are limited, supporting SELECT, UPDATE, INSERT, and DELETE statements with functional WHERE clauses, but explicitly prohibiting JOINs and currently lacking support for GROUP BY. Furthermore, LIMIT and OFFSET operations are consolidated into a single `LIMIT [offset,]number` syntax, requiring developers to adapt their pagination strategies accordingly. This package is ideal for Node.js applications needing to perform basic CRUD operations on Excel data programmatically without complex setup or platform restrictions.

npm install database-js-xlsx
INSTALL
IMPORT
SIG · DATABASE-JS-XLSX
D
database-js-xlsx
databasejavascriptv1.0.6
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

Database
const Database = require('database-js');
const Database = require('database-js2');
The `Database` class is provided by the `database-js` package. The README's example contains a likely typo using 'database-js2', which does not exist on npm.
driver registration
require('database-js-xlsx');
Importing `database-js-xlsx` registers its driver with `database-js`, enabling connection strings like 'database-js-xlsx:///file.xlsx'. This import is typically done for its side effects.

Demonstrates connecting to an XLSX file, performing CRUD (Create, Read, Update, Delete) operations, and properly closing the connection using `database-js-xlsx`. It also includes handling for initial file creation and path resolution.

const Database = require('database-js'); const path = require('path'); // This import is crucial for the 'database-js-xlsx' driver to be available require('database-js-xlsx'); (async () => { let connection, statement, rows; const filePath = path.join(__dirname, 'test.xlsx'); // For a new file, 'test.xlsx' will be created on connection.close() connection = new Database(`database-js-xlsx:///${filePath}`); try { console.log("Connected to XLSX file. Initializing with sample data if new."); // Example: Create/Ensure Sheet1 has columns if it's a new file // Note: This operation may implicitly create Sheet1 and its headers if not present try { await connection.prepareStatement("CREATE TABLE IF NOT EXISTS Sheet1 (Name TEXT, City TEXT, State TEXT, Age INTEGER)"); } catch (e) { // CREATE TABLE is not directly supported, but the first INSERT will define schema console.log("CREATE TABLE is not supported, proceeding with inserts to define schema."); } // Example: Insert data (if no data exists for 'Alice') console.log("\nInserting new data into Sheet1 (if not exists)..."); statement = await connection.prepareStatement("INSERT OR IGNORE INTO Sheet1 (Name, City, State, Age) VALUES (?, ?, ?, ?)"); await statement.query('Alice Smith', 'Anytown', 'CA', 25); await statement.query('Bob Johnson', 'Otherville', 'NY', 32); console.log("Sample data ensured."); // Example: Select data statement = await connection.prepareStatement("SELECT * FROM Sheet1 WHERE State = ?"); rows = await statement.query('CA'); console.log("\nQuery Results for 'CA':"); console.log(rows); // Example: Update data console.log("\nUpdating Alice Smith's age..."); statement = await connection.prepareStatement("UPDATE Sheet1 SET Age = ? WHERE Name = ?"); await statement.query(26, 'Alice Smith'); console.log("Alice Smith's age updated."); // Verify changes statement = await connection.prepareStatement("SELECT * FROM Sheet1 WHERE Name = ?"); rows = await statement.query('Alice Smith'); console.log("\nVerifying updated data for Alice Smith:"); console.log(rows); // Example: Delete data console.log("\nDeleting Bob Johnson's data..."); statement = await connection.prepareStatement("DELETE FROM Sheet1 WHERE Name = ?"); await statement.query('Bob Johnson'); console.log("Bob Johnson's data deleted."); } catch (error) { console.error("An error occurred:", error); } finally { if (connection) { console.log(`\nClosing connection and saving changes to '${filePath}'...`); await connection.close(); console.log("Connection closed and file saved."); } } })();
Debug
Known issues
gotchaThe README example for importing the `Database` class uses `require('database-js2')`. This is a typo, as `database-js2` does not exist on npm. The correct package to import for the `Database` class is `database-js`.
fix
Change `require('database-js2')` to `require('database-js')` in your code.
affects: >=1.0.0
gotchaThis library operates on an in-memory copy of the XLSX file. Any changes made to the physical file on disk by external processes while a connection is open will be overwritten when `connection.close()` is called, as the in-memory state is written back to the original file path.
fix
Ensure exclusive access to the XLSX file while a connection is active, or implement a rigorous concurrency strategy if shared access is required (which is not directly supported by this library's design).
affects: >=1.0.0
gotchaThe SQL parser has significant limitations. Specifically, `JOIN` clauses are not supported, and `GROUP BY` is not yet implemented. Complex queries requiring these features must be broken down and processed in application logic.
fix
Refactor SQL queries to avoid `JOIN` and `GROUP BY`. Perform data aggregation or merging of results programmatically in JavaScript/TypeScript after fetching the base data.
affects: >=1.0.0
gotchaThe `LIMIT` and `OFFSET` SQL clauses are combined into a single `LIMIT [offset,]number` syntax. This deviates from standard SQL and requires careful attention when implementing pagination.
fix
Adjust pagination queries to use `LIMIT [offset,]number` where `offset` is optional. For example, `SELECT * FROM Sheet1 LIMIT 10` for the first 10 rows, or `SELECT * FROM Sheet1 LIMIT 10, 20` for 20 rows starting after the first 10.
affects: >=1.0.0
Errors
Common errors & fixes
Error: Cannot find module 'database-js2'
The official README example for `database-js-xlsx` contains a typo, instructing users to `require('database-js2')` instead of the correct `database-js` package.
fix
Update your `require` statement from `require('database-js2')` to `require('database-js')`.
Error: "JOIN" is not allowed
The underlying SQL parser (`node-sqlparser`) used by `database-js-xlsx` explicitly does not support SQL JOIN clauses for combining data from multiple tables/sheets.
fix
Refactor your query to avoid `JOIN` operations. Instead, perform multiple `SELECT` statements and merge the results in your application logic.
Error: "GROUP BY" is not supported
The `database-js-xlsx` library, via `node-sqlparser`, currently lacks support for the `GROUP BY` SQL clause, preventing server-side aggregation.
fix
Retrieve the necessary data without `GROUP BY` and then perform the aggregation (e.g., summing, counting) programmatically in your JavaScript/TypeScript code.
TypeError: connection.prepareStatement is not a function
The `database-js-xlsx` driver has not been correctly registered with the `database-js` core library, likely because `require('database-js-xlsx')` was omitted or occurred after the connection attempt.
fix
Ensure that `require('database-js-xlsx');` is executed early in your application's lifecycle, preferably before any `new Database(...)` calls, to register the XLSX driver.
Upgrade
Version history
1.0.6latest on npm
Audit
Dependencies
database-jsrequiredCore dependency providing the common database interface that this package extends.
xlsx-populaterequiredUnderlying library used for reading, writing, and manipulating XLSX files.
node-sqlparserrequiredUsed for parsing SQL queries into a structured format for execution against the spreadsheet.
Agent activity
13 hits · last 30 days
node
12
OpenAI (training)
1
Resources