Warehouse JSON Database

6.0.0 · active · verified Wed Apr 22

Warehouse is a simple JSON-based database library for Node.js, providing a robust interface for managing data through Models, Schemas, and a flexible querying system. It is notably the underlying data store for the Hexo static site generator. The current stable version is 6.0.0, released recently in 2024, indicating active development. The project maintains a consistent release cadence with significant updates, including performance improvements and type refinements in recent major versions. Key differentiators include its focus on a structured schema-driven approach for JSON data, a powerful query engine, and strong TypeScript support, making it suitable for applications requiring local data persistence and structured access without a full-fledged SQL or NoSQL server. It has dropped support for older Node.js versions, currently requiring Node.js 18 or higher.

Common errors

```
RangeError: Invalid string length
```
cause An internal issue with JSONStream re-implementation in early 4.x versions could lead to this error when handling large data sets.

fix Upgrade to Warehouse v4.0.2 or higher to resolve the underlying bug related to JSONStream handling.
```
TypeError: Database is not a constructor
```
cause This error typically occurs if you attempt to use `Database` as a function or if the import mechanism (CommonJS vs. ESM) is incorrectly applied, especially after v3.0.0's switch to class declarations.

fix Ensure you are importing `Database` correctly for your module system (`require('warehouse')` or `import Database from 'warehouse'`) and that you are instantiating it with the `new` keyword (e.g., `const db = new Database();`).
```
Error: Node.js version not supported
```
cause The installed version of Warehouse requires a newer Node.js runtime than the one currently in use. For example, v6.0.0 requires Node.js 18+.

fix Upgrade your Node.js environment to meet the minimum version specified in the `engines` field of the `warehouse` package's `package.json` file.

Warnings

breaking Warehouse v6.0.0 dropped support for Node.js 16.
Fix: Upgrade your Node.js environment to version 18 or higher before upgrading to Warehouse v6.0.0.
breaking In Warehouse v3.0.0, the constructor for `Database` and custom `SchemaType` classes changed from a function declaration to a class declaration.
Fix: Refactor any direct `Database` instantiations or custom `SchemaType` definitions to use modern JavaScript class syntax (`class MyClass extends Base { ... }`). Refer to the official documentation or release notes for examples.
breaking Warehouse v4.0.0 replaced the `exportAsync()` method.
Fix: Review your model export logic and replace deprecated `exportAsync()` calls with the new API methods introduced in v4.0.0 as per the documentation.
gotcha Warehouse frequently updates its minimum Node.js version requirement between major releases, potentially breaking CI/CD pipelines or deployments if not monitored.
Fix: Always check the `engines` field in `package.json` or the release notes (`BREAKING CHANGES`) before upgrading major versions of 'warehouse' to ensure Node.js compatibility and update your environment accordingly.

Install

npm install warehouse npm
yarn add warehouse yarn
pnpm add warehouse pnpm

Imports

Database

wrong:

import { Database } from 'warehouse'; // Incorrect for default export
const { Database } = require('warehouse'); // Incorrect for default export

correct:

import Database from 'warehouse'; // ESM
const Database = require('warehouse'); // CommonJS

The `Database` class is the primary export. Instantiation requires the `new` keyword. Since v3.0.0, it is implemented as a class, not a constructor function.

SchemaType

wrong:

import { SchemaType } from 'warehouse'; // Incorrect import path
const SchemaType = require('warehouse'); // Incorrect import path

correct:

import SchemaType from 'warehouse/schematype'; // ESM
const SchemaType = require('warehouse/schematype'); // CommonJS

The `SchemaType` base class, used for defining custom schema types, is located in a dedicated submodule. Since v3.0.0, custom SchemaTypes must extend a class declaration.

Model, Schema
```
import type { Model, Schema, Database } from 'warehouse';
```
For TypeScript, core interfaces like `Model` and `Schema`, as well as the `Database` class type, are typically imported as named types from the main 'warehouse' package.

Quickstart

Initializes a Warehouse database, defines a 'Post' model with a schema including a default date, and demonstrates inserting a new post.

const Database = require('warehouse');
const db = new Database();

const Post = db.model('posts', {
  title: String,
  created: {type: Date, default: Date.now}
});

Post.insert({
  title: 'Hello world'
}).then(function(post){
  console.log('New post created:', post);
}).catch(err => {
  console.error('Error creating post:', err.message);
});

view raw JSON →