database-sempai

2.7.0 verified Sat May 09 auth: no javascript

A TypeScript key-value storage library using JSON files, currently at version 2.7.0. It supports multiple tables, async file operations, and optional encryption. Unlike similar packages (e.g., lowdb, enmap), it offers built-in methods like filter, randomAt, and event-driven readiness via connect. The library is actively maintained with a stable release cadence, and ships TypeScript types.

Common errors

error TypeError: Cannot read properties of undefined (reading 'then') ↓

cause Calling an async method without await or .then(). All methods are async since v2.

fix

Add await before the method call, e.g., await db.set(...)

error Error: The table 'x' does not exist in the database. ↓

cause Referencing a table that hasn't been defined in the constructor or created at runtime.

fix

Add the table name to the 'table' array in the constructor, or use 'set' method which creates the table implicitly.

error Error: Encryption key not specified. ↓

cause Attempting to decrypt a previously encrypted database without providing the encryption key.

fix

Provide the exact same key used during encryption via the 'key' option in the constructor.

error Error: Invalid file extension: .xyz. Only .json, .sql, and .txt are allowed. ↓

cause Using an unsupported file extension in the 'extname' option.

fix

Use one of the supported extensions: '.json', '.sql', or '.txt' (though .sql is misleading, use .json).

Warnings

breaking In v2.0.0, all methods became async. Synchronous operations will return Promises. ↓

fix Use await or .then() for all method calls (set, get, delete, clear, all, etc.).

deprecated The 'table' option in the constructor is deprecated as of v2.5.0. Use the 'table' parameter in methods instead. ↓

fix Pass the table name directly to each method instead of relying on a default table from the constructor.

deprecated The method 'firtsKey' and 'firtsValue' are misspelled and deprecated since v2.5.5. Use 'firstKey' and 'firstValue' instead. ↓

fix Use firstKey() and firstValue() methods.

gotcha If you provide an encryption key in the config, all data is encrypted. However, without the exact same key, data becomes unreadable and errors will be thrown. ↓

fix Backup your key. If lost, delete the database files or reinitialize without encryption.

gotcha The 'extname' option defaults to '.sql' which may be misleading since the storage is JSON-based. This can cause confusion with actual SQL databases. ↓

fix Set extname to '.json' explicitly to avoid confusion.

gotcha Method 'includes' checks for a value, not a key. This is counterintuitive for a key-value store. ↓

fix Use 'get' to check if a key exists, or 'keys' to list all keys.

Install

npm install database-sempai

yarn add database-sempai

pnpm add database-sempai

Imports

CreateStorage
wrong
```
import CreateStorage from 'database-sempai'
```
correct
```
import { CreateStorage } from 'database-sempai'
```
The package exports CreateStorage as a named export. Default import will not work.

CreateStorage

wrong

const { CreateStorage } = require('database-sempai')

correct

import { CreateStorage } from 'database-sempai'

The package supports ESM only. CommonJS require is not supported.

type TableKey
wrong
```
import { TableKey } from 'database-sempai'
```
correct
```
import type { TableKey } from 'database-sempai'
```
TableKey is a type-only export. Use import type to avoid runtime errors in TypeScript's isolatedModules.

Quickstart

Creates a database, adds two entries, retrieves all, finds by value, deletes one, and shows the length.

import { CreateStorage } from 'database-sempai';

const db = new CreateStorage<string, string>({
  path: 'mydb',
  table: ['users'],
  extname: '.json',
});

await db.set('users', '1', 'Alice');
await db.set('users', '2', 'Bob');
const all = await db.all('users');
console.log(all); // { '1': 'Alice', '2': 'Bob' }

const found = await db.findByValue('users', 'Alice');
console.log(found); // { '1': 'Alice' }

await db.delete('users', '2');
console.log(await db.length('users')); // 1