Database-js INI File Driver

Common errors

• Error: Protocol 'database-js-ini' not found in connection string.

  cause The `database-js-ini` driver was not properly loaded or registered with the `database-js` core. This can happen if the package is not installed or if there's an environment issue.
  fix Ensure `database-js-ini` is installed (`npm install database-js-ini`) and that `database-js` is able to discover and load it. In some environments, an explicit `require('database-js-ini');` (even without assigning to a variable) might be needed to trigger driver registration.

• TypeError: Connection is not a constructor

  cause The `Connection` symbol was imported incorrectly or from the wrong package. The common mistake is trying to `require` from `database-js2` as seen in the package's old README, while having installed `database-js`.
  fix Verify that you are importing `Connection` from the correct `database-js` package you have installed. Use `import { Connection } from 'database-js';` for ESM or `const { Connection } = require('database-js');` for CommonJS.

• Error: ENOENT: no such file or directory, open '/path/to/your/test.ini'

  cause The INI file specified in the connection string (`database-js-ini:///path/to/your/test.ini`) does not exist or the path is incorrect relative to where your application is run.
  fix Ensure the INI file exists at the specified path and that your application has read permissions for it. Use an absolute path or verify the relative path from your execution context.

Warnings

• gotcha The `README` example provided with `database-js-ini` uses `require('database-js2').Connection;`. The standard core package for this ecosystem is `database-js`. Using `database-js2` might lead to unexpected behavior or an inability to resolve the module if `database-js` is what you have installed.
  Fix: Always import `Connection` from `database-js` unless you explicitly intend to use a variant named `database-js2` (which is not the official core package). Example: `import { Connection } from 'database-js';` or `const Connection = require('database-js').Connection;`.
• gotcha The 'About' section in the `database-js-ini` README contains a copy-paste error, referencing `database-js-mysql` instead of `database-js-ini`. This indicates potentially outdated or poorly maintained documentation.
  Fix: Exercise caution when referring to documentation within the package's `README`. Always cross-reference with the main `database-js` project documentation for accurate information on driver usage and capabilities.
• gotcha This package provides a simplified SQL-like interface for INI files. It treats sections as tables and properties as columns. Advanced SQL features such as complex joins, subqueries, aggregate functions, or full data type support (beyond basic string interpretation) are not available. It is best suited for straightforward configuration data retrieval.
  Fix: Manage expectations for the complexity of queries. For more complex data manipulation or robust database features, consider a full-fledged database system and its corresponding `database-js` driver.
• gotcha The `database-js-ini` package version 1.0.1 appears to be quite old (e.g., GitHub activity on `package.json` suggests ~9 years ago). While this might imply stability, it also means it may not receive updates for modern JavaScript features, security patches, or compatibility with newer Node.js versions.
  Fix: Carefully test its compatibility with your specific Node.js environment and consider potential security implications for long-term production use. Evaluate if a more actively maintained INI parser (e.g., `npm/ini`) directly integrated into your application might be a better choice for critical projects.

Install

• npm install database-js-ini npm
• yarn add database-js-ini yarn
• pnpm add database-js-ini pnpm

Imports

• Connection
  wrong:

  const Connection = require('database-js2').Connection;

  correct:

  import { Connection } from 'database-js';

  Users primarily interact with the `Connection` object from the `database-js` core package. `database-js-ini` registers itself as a driver implicitly upon installation, allowing `database-js` to use it when a connection string with the `database-js-ini:///` protocol is provided. The `database-js2` import seen in some examples is likely a legacy artifact or a specific fork; `database-js` is the standard and correct core package.

Quickstart

This quickstart demonstrates how to use `database-js-ini` to connect to and query data from a simple INI file. It creates a temporary `config.ini` file, establishes a `database-js` connection, executes `SELECT` queries against different INI sections, and logs the results before cleaning up.

import { Connection } from 'database-js';
import * as fs from 'fs';

const iniContent = `
[SERVER]
port=8080
host=localhost

[DATABASE]
type=sqlite
filepath=/tmp/data.db
`;

const iniFilePath = './config.ini';

// Create a temporary INI file for the example
fs.writeFileSync(iniFilePath, iniContent, 'utf8');

(async () => {
    let connection: Connection | null = null;
    try {
        // Connect using the database-js-ini protocol and specify the INI file path
        connection = new Connection(`database-js-ini:///${iniFilePath}`);
        
        // Query all properties from the [SERVER] section
        let statement = await connection.prepareStatement("SELECT port, host FROM SERVER");
        let serverSettings = await statement.query();
        console.log('Server Settings:', serverSettings);

        // Query all properties from the [DATABASE] section
        statement = await connection.prepareStatement("SELECT type, filepath FROM DATABASE");
        let databaseSettings = await statement.query();
        console.log('Database Settings:', databaseSettings);

    } catch (error) {
        console.error('An error occurred during INI file access:', error);
    } finally {
        if (connection) {
            await connection.close();
        }
        // Clean up the temporary INI file
        if (fs.existsSync(iniFilePath)) {
            fs.unlinkSync(iniFilePath);
        }
    }
})();