https://github.com/tonaxis/tona-db-mini
Tona-DB mini is a JavaScript library for simulating small local databases in JSON
https://github.com/tonaxis/tona-db-mini
database file-based json jsondb lightweight lowdb minimal node offline storage typescript
Last synced: 16 days ago
JSON representation
Tona-DB mini is a JavaScript library for simulating small local databases in JSON
- Host: GitHub
- URL: https://github.com/tonaxis/tona-db-mini
- Owner: Tonaxis
- License: mit
- Created: 2025-05-22T19:10:50.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-11-02T04:01:37.000Z (9 months ago)
- Last Synced: 2025-11-02T06:03:01.385Z (9 months ago)
- Topics: database, file-based, json, jsondb, lightweight, lowdb, minimal, node, offline, storage, typescript
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/tona-db-mini
- Size: 394 KB
- Stars: 3
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
**A simple library to store and retrieve JSON data**
[](https://opensource.org/licenses/MIT)
[](https://github.com/tonaxis/tona-db-mini/releases)
## Summary
- [Summary](#summary)
- [Explanation](#explanation)
- [Installation](#installation)
- [Configuration](#configuration)
- [Usages](#usages)
- [Basic Usage](#basic-usage)
- [Add data to collection](#add-data-to-collection)
- [Get data from collection](#get-data-from-collection)
- [Update data in collection](#update-data-in-collection)
- [Delete data from collection](#delete-data-from-collection)
- [Filters](#filters)
- [Compatibility](#compatibility)
- [Example in CommonJS](#example-in-commonjs)
## Explanation
**Tona DB mini** is a Node module written in TypeScript that provides the ability to store, update, and retrieve data persistently, much like a database would. It is designed to be simple to use and quick to set up, making it easy to integrate into a small project that requires data persistence without the need to implement a traditional and complex database.
Data is stored in JSON format, which makes it easy to manipulate and migrate between projects. The module simulates a non-relational database with a system of **collections**.
> Note: This project still under development. Many features are planned for future releases.
## Installation
Simply run the following command to install the module from npm:
```shell
npm install tona-db-mini
```
## Configuration
To configure the module, you can create a configuration file named `tdb-mini.config.json` in the root directory of your project. This file should contain the following properties:
```json
{
"dbPath": "./tdb-mini-data",
"prettyJson": false
}
```
- `dbPath` - The path to the database folder.
- `prettyJson` - A boolean value that determines whether the JSON data should be formatted with indentation.
## Usages
### Basic Usage
```ts
import db from "tona-db-mini";
// Create your type for your collection
type User = {
name: string;
age: number;
};
const users = db.collection("users");
// Add a new user
users.add({ name: "John Doe", age: 30 });
// Get user by name
const user = users.get({ name: "John Doe" });
```
### Add data to collection
To add data to a collection, you can use the `add` method.
The `add` method takes an object or an array of objects as an argument.
```ts
import db from "tona-db-mini";
// Create your type for your collection
type User = {
name: string;
age: number;
};
const users = db.collection("users");
// Add a new user
users.add({ name: "John Doe", age: 30 });
// Add multiple users
users.add([{ name: "Jane Doe", age: 25 }, { name: "Bob Smith", age: 35 }]);
```
### Get data from collection
To get data from a collection, you can use the `get` method.
The `get` method takes an [Filter](#filters) as an argument. If no filter is provided, it will return all data from the collection.
```ts
import db from "tona-db-mini";
// Create your type for your collection
type User = {
name: string;
age: number;
};
const users = db.collection("users");
// Get data from collection
const specificUser = users.get({ name: "John Doe" });
// Get all data from collection
const allUsers = users.get();
```
### Update data in collection
To update data in a collection, you can use the `update` method.
The `update` method takes a [Filter](#filters) and a partial data object as arguments.
```ts
import db from "tona-db-mini";
// Create your type for your collection
type User = {
name: string;
age: number;
};
const users = db.collection("users");
// Update data in collection
users.update({ name: "John Doe" }, { age: 31 });
```
### Delete data from collection
To delete data from a collection, you can use the `del` method.
The `del` method takes an [Filter](#filters) as an argument. If no filter is provided, it will delete all data from the collection.
```ts
import db from "tona-db-mini";
// Create your type for your collection
type User = {
name: string;
age: number;
};
const users = db.collection("users");
// Delete data from collection
users.del({ name: "John Doe" });
// Delete all data from collection
users.del();
```
### Filters
You can use a filter to specify which data you want to **get**, **update**, or **delete** from a collection. The filter can be an object or a predicate function.
```ts
import db from "tona-db-mini";
// Create your type for your collection
type User = {
name: string;
age: number;
};
const users = db.collection("users");
// Get user with name "John Doe"
const specificUser = users.get({ name: "John Doe" });
// Get users with age greater than 30
const olderUsers = users.get((user) => user.age > 30);
```
## Compatibility
**Tona DB mini** is a very flexible JavaScript/TypeScript module: it works in **Node.js** (backend, scripts, serverless), in **Deno**, with the older **CommonJS** format (`require`), and even with a **TypeScript runtime** like `tsx` without a build step. In short, it fits smoothly into most modern or existing stacks.
| Environment / stack | Supported? | Usage notes |
| ------------------------ | ---------- | --------------------------------------------- |
| **Node.js** | ✅ | Backend apps, scripts, serverless |
| **Deno** | ✅ | URL imports, secure runtime |
| **CommonJS** (`require`) | ✅ | No need to migrate to ES Modules |
| **TS runtime (tsx)** | ✅ | Run TypeScript directly, no build step needed |
### Example in CommonJS
```js
const db = require("tona-db-mini").default;
const users = db.collection("users");
// Add a new user
users.add({ name: "John Doe", age: 30 });
// Get user by name
const user = users.get({ name: "John Doe" });
```