database-sempai

library2.7.0jsnpmunverified

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.

database serialization auth-security

npm install database-sempai

github ↗package ↗

INSTALL

IMPORT

SIG · DATABASE-SEMPAI

database-sempai

databasejavascriptv2.7.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

CreateStorage

✓ import { CreateStorage } from 'database-sempai'

✗ import CreateStorage from 'database-sempai'

The package exports CreateStorage as a named export. Default import will not work.

CreateStorage

✓ import { CreateStorage } from 'database-sempai'

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

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

type TableKey

✓ import type { TableKey } from 'database-sempai'

✗ import { TableKey } from 'database-sempai'

TableKey is a type-only export. Use import type to avoid runtime errors in TypeScript's isolatedModules.

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

Debug

Known issues

breakingIn 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.).

affects: >=2.0.0

deprecatedThe '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.

affects: >=2.5.0

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

fix

Use firstKey() and firstValue() methods.

affects: >=2.5.5

gotchaIf 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.

affects: >=1.0.0

gotchaThe '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.

affects: >=1.0.0

gotchaMethod '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.

affects: >=1.0.0

Errors

Common errors & fixes

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

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: The table 'x' does not exist in the database.

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: Encryption key not specified.

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: Invalid file extension: .xyz. Only .json, .sql, and .txt are allowed.

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).

Upgrade

Version history

2.7.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

20 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/Sempai-07/database-sempai ↗

packagehttps://www.npmjs.com/package/database-sempai ↗