JSON File Database for Node.js

Common errors

• TypeError: (0 , json_file_database__WEBPACK_IMPORTED_MODULE_0__.connect) is not a function

  cause This error typically occurs when attempting to use a CommonJS `require` statement or an incorrect import syntax in an environment that expects ESM (ECMAScript Modules) for `json-file-database`.
  fix Ensure your project uses `import { connect } from 'json-file-database'` syntax. If using Node.js, ensure your `package.json` has `"type": "module"` or you are saving your files with a `.mjs` extension for ESM support. If using `require`, you might need to configure your bundler (e.g., Webpack, Rollup) or Babel to handle ESM modules correctly.

• Argument of type '{ name: string; }' is not assignable to parameter of type 'CollectionConfig<T>'. Property 'primaryKey' is missing in type '{ name: string; }' but required in type 'CollectionConfig<T>'.

  cause Since version 2.x, the `primaryKey` option is mandatory when calling `db<T>()` to define a collection, and this TypeScript error indicates it's missing.
  fix Add the `primaryKey` property to your collection configuration object, specifying the name of the property that acts as the unique identifier for elements in that collection. For example: `db<User>({ name: 'users', primaryKey: 'id' })`.

• Error: The primary key 'X' already exists. Cannot insert duplicate.

  cause Attempting to insert an object into a collection where an object with the same `primaryKey` value already exists.
  fix Before inserting, check if an element with the desired `primaryKey` already exists using `collection.has()`. If you intend to update, use `collection.update()` instead of `collection.insert()`. The `insert` method returns `false` if a duplicate exists, allowing for programmatic handling.

Warnings

• breaking Version 2.x introduced a breaking change requiring explicit specification of the `primaryKey` when defining a collection. Previously, it defaulted to 'id'.
  Fix: When initializing a collection via `db<T>({})`, ensure you pass the `primaryKey` option, e.g., `db<User>({ name: 'users', primaryKey: 'id' })`. If your data uses a different unique identifier, specify that property name.
• gotcha The `init` property in the `connect` function is only applied if the specified database file does not exist. If the file already exists, the `init` data is ignored, and the existing file's content is used.
  Fix: Be aware that `init` is for first-time setup. To reset the database for development, manually delete the `db.json` file. For production, ensure your initialization logic handles existing data appropriately, perhaps by performing migrations or checks.
• gotcha Elements stored in collections must have a unique property designated as the `primaryKey`. Inserting an element with a duplicate `primaryKey` value will result in a failed insertion or an error, as the library uses this key for uniqueness and sorting.
  Fix: Ensure all objects you insert or update into a collection have a unique value for the property specified as the `primaryKey`. Validate uniqueness before insertion, or handle the `false` return value from `insert` and `update` methods indicating failure.

Install

• npm install json-file-database npm
• yarn add json-file-database yarn
• pnpm add json-file-database pnpm

Imports

• connect
  wrong:

  const connect = require('json-file-database').connect

  correct:

  import { connect } from 'json-file-database'

  The `connect` function is the primary entry point. `json-file-database` is a modern, TypeScript-first package and is primarily used with ESM imports. CommonJS `require` might lead to issues or require specific configuration for transpilation.
• ConnectOptions
  wrong:

  import { ConnectOptions } from 'json-file-database'

  correct:

  import type { ConnectOptions } from 'json-file-database'

  Use `import type` for importing interfaces or types to ensure they are removed during transpilation, preventing runtime errors in some environments and clarifying intent. This type defines the configuration object for the `connect` function.
• CollectionConfig
  wrong:

  import { CollectionConfig } from 'json-file-database'

  correct:

  import type { CollectionConfig } from 'json-file-database'

  Use `import type` for importing interfaces. This type defines the configuration for a specific collection, including its `name` and the `primaryKey` property. It's essential for properly configuring and typing collections within the database instance.

Quickstart

This quickstart demonstrates how to connect to a JSON file database, initialize it with data, create a typed collection, and perform basic CRUD (Create, Read, Update, Delete) operations using the library's API.

import { connect } from 'json-file-database'

/**
 * Define the shape of your data. It must include the primary key property.
 */
type User = { id: number, name: string, email: string }

/**
 * Connect to the database file. If it doesn't exist, it will be created.
 * The `init` property provides initial data if the file is new.
 */
const db = connect({
  file: './my-app-db.json',
  init: {
    users: [
      { id: 1, name: 'Alice', email: 'alice@example.com' },
      { id: 2, name: 'Bob', email: 'bob@example.com' },
    ],
    products: [
      { id: 101, name: 'Laptop', price: 1200 },
    ]
  }
})

/**
 * Get a typed collection instance, specifying the data type and primary key.
 * For v2+, the `primaryKey` option is mandatory if it's not 'id'.
 */
const users = db<User>({
  name: 'users',
  primaryKey: 'id',
})

// --- Perform CRUD operations ---

// Find by primary key
console.log('User with id 1:', users.find({ id: 1 }))

// Insert a new user
const newUser: User = { id: 3, name: 'Charlie', email: 'charlie@example.com' }
console.log('Inserting new user:', users.insert(newUser))

// List all users
console.log('All users:', Array.from(users))

// Update an existing user
console.log('Updating user 1:', users.update({ id: 1, name: 'Alicia', email: 'alicia@example.com' }))

// Remove a user
console.log('Removing user 2:', users.remove({ id: 2 }))

// Verify the changes
console.log('Users after operations:', Array.from(users))