@basolt/db

A lightweight and modern TypeScript library for interacting with Basolt DB, a NoSQL document database.

Installation

npm install @basolt/db

Usage

First, initialize the DB with your project's public key.

import { DB } from '@basolt/db';

const db = new DB({ publicKey: 'YOUR_PUBLIC_KEY' });

Then, select a collection to perform CRUD operations.

const users = db.collection('users');

// Create a new record
const { data: newUser, error: createError } = await users.create({
  name: 'John Doe',
  email: 'john.doe@example.com',
});

if (createError) {
  console.error(createError.message);
} else {
  console.log('Created user:', newUser);
}

// Find records
const { data: foundUsers, error: findError } = await users.find({
  email: 'john.doe@example.com',
});

// Update a record
const { data: updatedUser, error: updateError } = await users
  .update({ name: 'Johnathan Doe' })
  .eq('id', newUser.id);

// Delete a record
const { data: deletedResult, error: deleteError } = await users
  .delete()
  .eq('id', newUser.id);

API

new DB({ publicKey })

Creates a new DB instance.

• publicKey (string, required): Your Basolt project's public API key.

db.collection(name)

Selects a collection to perform operations on.

• name (string, required): The name of the collection.

collection.create(data)

Creates a new record.

• data (object, required): The data for the new record.

collection.find(columns)

Initiates a query to find records. This method returns a QueryBuilder instance, which allows you to chain filters, sorting, and pagination methods.

• columns (string, optional): A comma-separated list of columns to retrieve. Defaults to * (all columns).

Once you have built your query, you can await the chain to execute it and get the results.

Example:

const { data, error } = await db
  .collection('users')
  .find('id, name, email')
  .eq('status', 'active')
  .order('createdAt', { ascending: false })
  .limit(10);

Update Records

Update records in a collection. The update method returns a MutationBuilder instance that allows you to chain filters to specify which records to update.

// Update records matching a filter
const { data, error } = await db
  .collection('users')
  .update({ status: 'active' })
  .eq('is_verified', false);

Delete Records

Delete records from a collection. The delete method returns a MutationBuilder instance that allows you to chain filters to specify which records to delete.

// Delete records matching a filter
const { data, error } = await db
  .collection('users')
  .delete()
  .eq('status', 'inactive');

QueryBuilder Methods

• .eq(column, value): Finds all rows where column is equal to value.
• .neq(column, value): Finds all rows where column is not equal to value.
• .gt(column, value): Finds all rows where column is greater than value.
• .lt(column, value): Finds all rows where column is less than value.
• .gte(column, value): Finds all rows where column is greater than or equal to value.
• .lte(column, value): Finds all rows where column is less than or equal to value.
• .order(column, { ascending }): Orders the results by column. ascending defaults to true.
• .limit(count): Limits the number of returned rows to count.
• .offset(count): Skips count rows.
• .single(): Fetches a single record instead of an array. If no record is found, it returns null. This is a convenience method that sets the limit to 1.