Jsonjsdb Builder

0.6.11 · active · verified Wed Apr 22

The `jsonjsdb-builder` package, currently at version 0.6.11, is a development tool that transforms structured data, primarily from Excel (.xlsx) files and Markdown documents, into two JSON-based formats. It generates a compact `.json.js` file (an array of arrays) optimized for efficient, server-less loading in web browsers (e.g., via `file://`), and a standard `.json` file (an array of objects) for general tooling and readability. This package is part of the broader `jsonjsdb` ecosystem, including a Python component. Its release cadence is driven by bug fixes and developer experience improvements, such as recent patches to prevent unnecessary database rewrites during development. A key differentiator is its tight integration with front-end build systems like Vite, offering automated data regeneration and hot-reloading, which streamlines the development of applications leveraging local, structured data.

Common errors

```
TypeError: JsonjsdbBuilder is not a constructor
```
cause Attempted to use 'JsonjsdbBuilder' as a named import or with CommonJS 'require()' syntax.

fix Use the default import syntax: `import JsonjsdbBuilder from 'jsonjsdb-builder'`.
```
ReferenceError: initJsonjsdbBuilder is not defined
```
cause Attempted to use a named export like `initJsonjsdbBuilder` without proper destructuring in the import statement.

fix Use named import syntax: `import { initJsonjsdbBuilder } from 'jsonjsdb-builder'`.
```
Error: ENOENT: no such file or directory, stat '<path>'
```
cause The specified input or output directory path provided to a builder method (e.g., `setOutputDb`, `updateDb`) does not exist or is misspelled.

fix Ensure all directory paths provided to builder methods either exist or are accessible for creation by the builder process.
```
Error [ERR_REQUIRE_ESM]: require() of ES Module <path> from <path> not supported.
```
cause The `jsonjsdb-builder` package is published as an ES Module (ESM), but it is being imported using CommonJS `require()` syntax.

fix Convert your module to use ES Module syntax with `import` statements, or configure your environment to correctly handle ESM packages.

Warnings

gotcha When integrating with Vite, `vite-plugin-full-reload` is a required development dependency. Forgetting to install it will lead to build failures.
Fix: Ensure `vite-plugin-full-reload` is installed: `npm install -D vite-plugin-full-reload`.
gotcha The builder methods like `updateDb()` and `updateMdDir()` implicitly expect source files (e.g., .xlsx or .md) to be present within the specified input directory. An empty directory will result in no output.
Fix: Verify that the input directory (e.g., 'db' or 'markdown') contains the necessary source files before running builder commands.
gotcha Versions of `jsonjsdb-builder` prior to 0.6.11 might perform unnecessary table regenerations, potentially increasing build times, especially during development with a watcher.
Fix: Upgrade to `jsonjsdb-builder` version 0.6.11 or newer to benefit from optimizations that prevent redundant file rewrites when source content is identical.

Install

npm install jsonjsdb-builder npm
yarn add jsonjsdb-builder yarn
pnpm add jsonjsdb-builder pnpm

Imports

JsonjsdbBuilder

wrong:

import { JsonjsdbBuilder } from 'jsonjsdb-builder'

correct:

import JsonjsdbBuilder from 'jsonjsdb-builder'

This is the default export for the main builder class.

initJsonjsdbBuilder

wrong:

import initJsonjsdbBuilder from 'jsonjsdb-builder'

correct:

import { initJsonjsdbBuilder } from 'jsonjsdb-builder'

Used for integrating the builder with Vite, it's a named export.

jsonjsdbToObjects

wrong:

const { jsonjsdbToObjects } = require('jsonjsdb-builder')

correct:

import { jsonjsdbToObjects } from 'jsonjsdb-builder'

One of several low-level utility functions, all are named exports.

Quickstart

This quickstart demonstrates how to initialize the `JsonjsdbBuilder` class, set up a temporary output directory for generated JSON files, and show where Excel source files would be specified for conversion. It illustrates the basic API usage for setting up the builder environment.

import JsonjsdbBuilder from 'jsonjsdb-builder';
import path from 'path';
import { fileURLToPath } from 'url';
import { dirname } from 'path';
import { mkdtemp, rm } from 'fs/promises';
import os from 'os';

const __filename = fileURLToPath(import.meta.url);
const __dirname = dirname(__filename);

async function runQuickstart() {
  let tempDir;
  try {
    tempDir = await mkdtemp(path.join(os.tmpdir(), 'jsonjsdb-builder-'));
    const outputDbPath = path.join(tempDir, 'app_db');
    const sourceDbPath = path.join(tempDir, 'db');

    // In a real scenario, place .xlsx files in 'sourceDbPath' (e.g., path.join(sourceDbPath, 'users.xlsx'))
    // The builder will read these files and generate JSON outputs.
    
    console.log(`Simulating JSONJSDB build process:`)
    console.log(`  Output directory: ${outputDbPath}`);
    console.log(`  Source Excel directory: ${sourceDbPath}`);

    const builder = new JsonjsdbBuilder();
    await builder.setOutputDb(outputDbPath);
    // To actually process files, ensure 'sourceDbPath' contains .xlsx files.
    // await builder.updateDb(sourceDbPath); 
    console.log('Builder initialized and output directory set. Call builder.updateDb() with your source Excel directory.');
    console.log('Generated .json.js and .json files would appear in the output directory.');

  } catch (error) {
    console.error('Quickstart failed:', error);
  } finally {
    if (tempDir) {
      console.log(`Cleaning up temporary directory: ${tempDir}`);
      await rm(tempDir, { recursive: true, force: true });
    }
  }
}

runQuickstart();

view raw JSON →