eyal.db

eyal.db is a high-performance wrapper around better-sqlite3, designed to make database operations faster and easier.

Features

• 🚀 High Performance: Optimized operations with batching and transactions
• 🔄 Operation Queue: Intelligent queuing system for optimal database performance
• 📦 Batch Operations: Insert multiple records efficiently
• 🛡️ Type Safety: Built with TypeScript for better development experience
• 💾 SQLite Optimized: Pre-configured SQLite settings for maximum performance

Installation

You can install eyal.db using npm or pnpm:

npm install eyal.db
# OR
pnpm add eyal.db

Quick Start

const { Database } = require("eyal.db");

async function main() {
  const db = new Database("myapp.db");

  // Create a table
  await db.table.create("users", {
    id: 2, // INTEGER
    name: 1, // TEXT
    email: 1, // TEXT
    active: 3, // BOOLEAN
    score: 2, // INTEGER
  });

  // Insert data
  await db.add("users", {
    id: 1,
    name: "John Doe",
    email: "[email protected]",
    active: true,
    score: 100,
  });

  // Query data
  const users = await db.all("users");
  console.log(users);

  // Close connection
  await db.close();
}

main();

API Documentation

• Database Constructor
• db.table.create()
• db.table.delete()
• db.add()
• db.addMany()
• db.all()
• db.has()
• db.set()
• db.delete()
• db.deleteall()
• db.datasize()
• db.type()
• db.transaction()
• db.batch()
• db.close()

Database Constructor

Creates a new database instance.

const { Database } = require("eyal.db");
const db = new Database("database.db"); // Optional filename, defaults to 'eyal.db'

createTable(name, columns)

Creates a new table in the database. Returns a Promise.

Column Types:

• 1 - TEXT
• 2 - INTEGER
• 3 - BOOLEAN (stored as 0/1)
• 4 - DATE
• 5 - DATETIME

Example:

await db.table.create("customers", {
  customerName: 1, // TEXT
  customerPaymentMethod: 1, // TEXT
  isPartner: 3, // BOOLEAN
  customerMonthlyPrice: 2, // INTEGER
});

deleteTable(name)

Deletes a table from the database. Returns a Promise.

Example:

await db.table.delete("customers");

add(table, data)

Inserts new data into a table. Returns a Promise.

Example:

await db.add("customers", {
  customerName: "Eyal",
  customerPaymentMethod: "card",
  isPartner: true,
  customerMonthlyPrice: 100,
});

addMany(table, records)

Efficiently inserts multiple records using a transaction. Returns a Promise.

Example:

const users = [
  { name: "Alice", email: "[email protected]", active: true },
  { name: "Bob", email: "[email protected]", active: false },
  { name: "Charlie", email: "[email protected]", active: true },
];

await db.addMany("users", users);

all(table)

Retrieves all rows from a table. Returns a Promise.

Example:

const customers = await db.all("customers");
console.log(customers);

has(table, criteria)

Checks if a record exists in a table. Returns a Promise<boolean>.

Example:

const exists = await db.has("customers", { customerName: "Eyal" });
console.log(exists); // true or false

set(table, data, where)

Updates existing data in a table. Returns a Promise.

Example:

await db.set(
  "customers",
  { customerMonthlyPrice: 200 }, // New data
  { customerName: "Eyal" } // Where condition
);

delete(table, criteria)

Deletes records from a table based on criteria. Returns a Promise.

Example:

await db.delete("customers", {
  customerName: "Eyal",
});

deleteall(table)

Deletes all records from a table. Returns a Promise.

Example:

await db.deleteall("customers");

datasize(table)

Returns the number of records in a table. Returns a Promise<number>.

Example:

const count = await db.datasize("customers");
console.log(`Total customers: ${count}`);

type(table, column)

Returns the type of a specific column. Returns a Promise<string>.

Example:

const columnType = await db.type("customers", "customerMonthlyPrice");
console.log(columnType); // "INTEGER"

transaction(callback)

Executes multiple operations within a transaction for better performance and atomicity. Returns a Promise.

Example:

await db.transaction(() => {
  // Multiple operations that will be executed as a single transaction
  db.add("users", { name: "Alice", email: "[email protected]" });
  db.add("users", { name: "Bob", email: "[email protected]" });
  db.set("users", { active: true }, { name: "Alice" });
});

batch(operations)

Executes multiple operations efficiently in batches. Returns a Promise.

Example:

const operations = [
  () => db.add("users", { name: "User1", email: "[email protected]" }),
  () => db.add("users", { name: "User2", email: "[email protected]" }),
  () => db.set("settings", { value: "enabled" }, { key: "notifications" }),
];

await db.batch(operations);

close()

Closes the database connection. Returns a Promise.

Example:

await db.close();

Advanced Usage

Performance Optimization

eyal.db automatically optimizes your database operations through:

• Operation Queuing: Batches operations for better performance
• Statement Caching: Reuses prepared statements
• Transaction Management: Groups operations when beneficial
• WAL Mode: Uses Write-Ahead Logging for concurrent access

Error Handling

try {
  await db.add("users", { name: "John", email: "[email protected]" });
} catch (error) {
  console.error("Database operation failed:", error.message);
}

Concurrent Operations

eyal.db handles concurrent operations safely:

// These will be queued and executed efficiently
const promises = [
  db.add("users", { name: "Alice" }),
  db.add("users", { name: "Bob" }),
  db.add("users", { name: "Charlie" }),
];

await Promise.all(promises);

Performance Benchmarks

eyal.db is optimized for speed. Here are some benchmark results:

• Individual Inserts: ~13ms for 100 records
• Batch Inserts: ~1ms for 100 records (1200% faster)
• Concurrent Queries: ~1ms for 50 parallel operations
• Bulk Operations: ~1ms for 100 transactions

TypeScript Support

eyal.db is built with TypeScript and provides full type definitions:

import { Database } from "eyal.db";

const db = new Database("myapp.db");

interface User {
  id: number;
  name: string;
  email: string;
  active: boolean;
}

const users: User[] = await db.all("users");

Credits

• eyal.db is a high-performance wrapper for better-sqlite3
• Built with 💖 by Eyal Green