{"id":17563,"library":"database-js-json","title":"JSON File Driver for Database-JS","description":"database-js-json is a driver for the database-js2 ecosystem, enabling SQL-like querying of local JSON files. It wraps the jl-sql-api library to provide its core parsing and querying capabilities. The current stable version is 1.2.1, with releases adhering to Semantic Versioning. This package distinguishes itself by allowing developers to treat JSON documents as a data source queryable via a familiar SQL syntax, integrating seamlessly with the database-js2 connection abstraction. Key features include configurable character sets and file existence checks through URL-style connection string options. It's designed for scenarios requiring direct interaction with JSON data files using a standardized database interface, primarily for read operations.","status":"active","version":"1.2.1","language":"javascript","source_language":"en","source_url":null,"tags":["javascript","database-js-json","database-js","json","database","sql","query","driver"],"install":[{"cmd":"npm install database-js-json","lang":"bash","label":"npm"},{"cmd":"yarn add database-js-json","lang":"bash","label":"yarn"},{"cmd":"pnpm add database-js-json","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency for the core Connection class and to register the 'json://' protocol driver.","package":"database-js2","optional":false},{"reason":"Core dependency providing the SQL-like query parsing and execution against JSON data.","package":"jl-sql-api","optional":false}],"imports":[{"note":"While `database-js-json` enables JSON support, the primary `Connection` class is imported from its peer dependency `database-js2`. This package is a driver for `database-js2`.","wrong":"import { Connection } from 'database-js';","symbol":"Connection","correct":"import { Connection } from 'database-js2';"},{"note":"For CommonJS environments, `Connection` is imported from `database-js2`. The quickstart initially shows `var Connection = require('database-js2').Connection;`, but modern practice favors `const` and destructuring.","wrong":"var Connection = require('database-js').Connection;","symbol":"Connection","correct":"const { Connection } = require('database-js2');"},{"note":"Installing and `require`ing `database-js-json` (even without assigning its exports to a variable) registers the `json://` protocol with `database-js2`. This package is primarily a driver for its side-effect registration, and direct symbol imports from `database-js-json` are uncommon for general usage.","wrong":"import { JsonConnection } from 'database-js-json';","symbol":"(Side Effect)","correct":"require('database-js-json');"}],"quickstart":{"code":"const { Connection } = require('database-js2');\nrequire('database-js-json'); // Ensure the driver is loaded and registers itself\n\n(async () => {\n    // Create a dummy JSON file for demonstration\n    require('fs').writeFileSync('test.json', JSON.stringify([\n        { \"id\": 1, \"user_name\": \"alpha_user\", \"email\": \"alpha@example.com\" },\n        { \"id\": 2, \"user_name\": \"beta_user\", \"email\": \"beta@example.com\" },\n        { \"id\": 3, \"user_name\": \"not_so_secret_user\", \"email\": \"secret@example.com\" }\n    ], null, 2));\n\n    const connection = new Connection( 'json:///test.json' );\n    \n    try {\n        console.log('Connecting to json:///test.json...');\n        // Query with a prepared statement\n        let statement = await connection.prepareStatement(\"SELECT * WHERE user_name = ?\");\n        let rows = await statement.query('not_so_secret_user');\n        console.log('Query result for \"not_so_secret_user\":', rows);\n        console.log(`Found ${rows.length} user(s) matching the criteria.`);\n\n        // Fetch all data\n        let allRows = await connection.query(\"SELECT id, user_name FROM * LIMIT 2\");\n        console.log('First 2 entries:', allRows);\n\n    } catch (error) {\n        console.error('An error occurred:', error);\n    } finally {\n        await connection.close();\n        console.log('Connection closed.');\n        // Clean up the dummy file\n        require('fs').unlinkSync('test.json');\n    }\n} )();","lang":"javascript","description":"Demonstrates connecting to a JSON file, querying data with a prepared statement, and closing the connection, including setup for a dummy JSON file."},"warnings":[{"fix":"Ensure `database-js2` is installed via `npm install database-js2` and that `Connection` is imported from `'database-js2'`, not `'database-js'`.","message":"This driver is specifically designed for `database-js2`, a modern fork of `database-js`. Attempting to use it with the original `database-js` package will result in errors due to incompatible APIs and protocol registration mechanisms.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Format connection strings correctly, for example: `json:///file.json?charset=utf-16&sortOptions.inMemoryBufferSize=32000`.","message":"Configuration options (e.g., `charset`, `checkOnConnect`) are passed directly in the connection string as URL query parameters. For nested options originating from `jl-sql-api`, dot notation is required (e.g., `sortOptions.inMemoryBufferSize`).","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"To suppress the file existence check, append `?checkOnConnect=false` to your connection string: `json:///test.json?checkOnConnect=false`.","message":"By default (`checkOnConnect=true`), the driver will throw an error if the specified JSON file does not exist upon connection. This can be problematic if the file is expected to be created later or if its initial absence should be ignored.","severity":"gotcha","affected_versions":">=1.1.0"}],"env_vars":null,"last_verified":"2026-04-23T00:00:00.000Z","next_check":"2026-07-22T00:00:00.000Z","problems":[{"fix":"Verify the JSON file exists at the specified path relative to your application's execution context, or append `?checkOnConnect=false` to the connection string to bypass the check.","cause":"The specified JSON file path is incorrect or the file does not exist, and the `checkOnConnect` option is implicitly or explicitly set to `true`.","error":"Error: ENOENT: no such file or directory, open 'test.json'"},{"fix":"Ensure `database-js-json` is installed (`npm install database-js-json`) and explicitly required or imported in your application's entry point: `require('database-js-json');`.","cause":"The `database-js-json` driver has not been properly loaded or required, thus `database-js2` is unaware of how to handle the `json://` connection protocol.","error":"Error: Protocol 'json' not found"},{"fix":"Review the query syntax against the `jl-sql-api` documentation for supported grammar and operations. Ensure proper quotation for string literals and valid identifiers.","cause":"The SQL-like query provided is syntactically incorrect or uses features not supported by the underlying `jl-sql-api` parser.","error":"Error: SQL parse error: Unexpected token: <token>"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}