WebSQL API Implementation for Node.js

Common errors

• SQLITE_CANTOPEN: unable to open database file

  cause The Node.js process lacks write permissions to the directory where the database file is being created, or the specified path is invalid.
  fix Ensure the Node.js process has appropriate write permissions to the specified database directory. Use an absolute path or a path relative to the process's working directory, or use `:memory:` for an in-memory database.

• TypeError: db.transaction is not a function

  cause The `db` object returned by `openDatabase` might not be correctly initialized, or `openDatabase` failed to return a valid database instance.
  fix Verify that `openDatabase` completed successfully and returned a valid database object. Check for any errors during the `openDatabase` call and ensure you're calling transaction methods on the correctly initialized `db` object.

• Error: Cannot find module 'sqlite3'

  cause `node-sqlite3`, the default backend for `websql`, is not installed as a dependency or failed to compile during installation.
  fix Ensure `sqlite3` is installed as a direct dependency: `npm install sqlite3`. If it's a native module compilation issue, verify your environment meets `node-gyp` requirements (e.g., Python, C++ build tools).

Warnings

• breaking The underlying WebSQL Database API is a deprecated standard and is not recommended for new development. This library is primarily intended for bridging legacy WebSQL code to Node.js environments.
  Fix: For new projects, consider modern alternatives like IndexedDB or client-side SQLite libraries that are actively maintained.
• gotcha The `version`, `description`, and `size` parameters in `openDatabase()` are ignored by this library for compatibility reasons. Database versioning and migrations are not supported.
  Fix: Manage database schema versions and migrations separately in your application logic, or ensure your legacy code does not rely on WebSQL's internal versioning.
• gotcha This library does not extend the WebSQL API with new features such as `BLOB` support, encryption, or database deletion, strictly adhering to the original WebSQL specification.
  Fix: Do not expect modern SQLite features or extensions. If these are required, `websql` may not be suitable, and a direct `sqlite3` integration might be necessary.
• gotcha When used in the browser, this library transparently falls back to `window.openDatabase`, meaning its functionality is subject to the browser's native WebSQL support (which is deprecated and often limited to Chrome/Safari).
  Fix: Ensure target browser environments have WebSQL support if relying on browser fallback. For broader cross-browser compatibility, consider other storage solutions like IndexedDB.

Install

• npm install websql npm
• yarn add websql yarn
• pnpm add websql pnpm

Imports

• openDatabase
  wrong:

  const openDatabase = require('websql').openDatabase;

  correct:

  import openDatabase from 'websql';

  The primary function for opening a WebSQL database. While the package's README shows CommonJS `require`, modern Node.js and bundlers support ESM `import`.
• customOpenDatabase
  wrong:

  const customOpenDatabase = require('websql');

  correct:

  import customOpenDatabase from 'websql/custom';

  Used to provide a custom `SQLiteDatabase` implementation, allowing you to swap out the default `node-sqlite3` binding for alternatives.
• Database
  wrong:

  import { Database } from 'websql';

  correct:

  const db = openDatabase('mydb.db', '1.0', 'description', 1);

  The actual database instance returned by `openDatabase` is an object that exposes WebSQL transaction methods like `transaction()` and `readTransaction()`. The `Database` class itself is not directly exported for instantiation.

Quickstart

Demonstrates how to open a WebSQL database, create a table, insert data, and query it using the `transaction` API.

import openDatabase from 'websql'; // Or `const openDatabase = require('websql');` for CommonJS

async function initializeDatabase() {
  // Create a SQLite3 database file called 'mydb.db'
  const db = openDatabase('mydb.db', '1.0', 'My Test Database', 1 * 1024 * 1024); // Size in bytes

  console.log('Database opened successfully.');

  // Perform a transaction to create a table and insert data
  return new Promise((resolve, reject) => {
    db.transaction((tx) => {
      tx.executeSql(
        'CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT, age INTEGER)',
        [],
        () => {
          console.log('Table "users" created or already exists.');
          tx.executeSql(
            'INSERT INTO users (name, age) VALUES (?, ?)',
            ['Alice', 30],
            () => {
              console.log('Inserted Alice.');
              tx.executeSql(
                'INSERT INTO users (name, age) VALUES (?, ?)',
                ['Bob', 24],
                () => {
                  console.log('Inserted Bob.');
                  tx.executeSql(
                    'SELECT * FROM users',
                    [],
                    (_, result) => {
                      console.log('Users:', Array.from(result.rows).map(row => row));
                      resolve(true);
                    },
                    (_, error) => {
                      console.error('Error selecting users:', error.message);
                      reject(error);
                    }
                  );
                },
                (_, error) => {
                  console.error('Error inserting Bob:', error.message);
                  reject(error);
                }
              );
            },
            (_, error) => {
              console.error('Error inserting Alice:', error.message);
              reject(error);
            }
          );
        },
        (_, error) => {
          console.error('Error creating table:', error.message);
          reject(error);
        }
      );
    });
  });
}

initializeDatabase().catch(console.error);