Jijel

A lightweight TypeScript database library with multiple storage options and type-safe queries.

Features

• Multiple Storage Options: In-memory, file system (with B-tree indexing), and browser storage
• Type Safety: Built with TypeScript and Zod for schema validation
• Fluent Query API: Build queries with a clean, chainable interface
• Extensible: Designed to be easily extended with plugins

Installation

npm install jijel zod

Quick Start

import { Database, Schema } from "jijel";
import { z } from "zod";

// Define a schema
const userSchema = new Schema({
  name: z.string(),
  email: z.string().email(),
  age: z.number().min(0).optional(),
});

async function main() {
  // Initialize the database
  const db = new Database({
    name: "my-app",
    storage: "memory", // Options: 'memory', 'file', 'browser'
  });

  await db.connect();

  // Create a table
  const userTable = db.table("users", userSchema);

  // Insert a record
  const user = await db.query(userTable).create({
    name: "John Doe",
    email: "[email protected]",
    age: 30,
  });

  console.log("Created user:", user);

  // Query records
  const adults = await db.query(userTable).where("age", "gte", 18).find();

  console.log("Adult users:", adults);

  // Update a record
  await db.query(userTable).updateOne(user.id, { age: 31 });

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

main().catch(console.error);

Storage Options

In-Memory Storage

Best for testing or small applications:

const db = new Database({
  name: "my-app",
  storage: "memory",
});

File Storage

Persists data to the file system using a B-tree for efficient indexing:

const db = new Database({
  name: "my-app",
  storage: "file",
  path: "./data",
});

Browser Storage

Uses localStorage or sessionStorage in browser environments:

const db = new Database({
  name: "my-app",
  storage: "browser",
});

API Reference

Database

• new Database(options): Create a new database instance
• connect(): Initialize the database connection
• table(name, schema): Define a table with the given schema
• query(table): Create a query builder for the table
• close(): Close the database connection

Query Builder

• where(field, operator, value): Add a filter condition
• limit(count): Limit the number of results
• skip(count): Skip the first N results
• sort(field, order): Sort the results
• find(): Execute the query and return all matching records
• findOne(): Execute the query and return the first matching record
• count(): Count matching records
• create(data): Insert a new record
• update(data): Update all matching records
• updateOne(id, data): Update a specific record
• delete(): Delete all matching records
• deleteOne(id): Delete a specific record

Supported Operators

• eq: Equal
• neq: Not equal
• gt: Greater than
• gte: Greater than or equal
• lt: Less than
• lte: Less than or equal
• in: In array
• nin: Not in array
• contains: String contains

Extending Jijel

Jijel is designed to be extensible. Here's an example of creating a plugin:

// Custom plugin for encryption
import { StorageAdapter } from "jijel";

class EncryptionPlugin {
  constructor(secretKey) {
    this.secretKey = secretKey;
  }

  wrapStorage(storage: StorageAdapter): StorageAdapter {
    // Return a wrapped storage adapter with encryption
    return {
      // Implement the StorageAdapter interface with encryption
      // ...
    };
  }
}

// Using the plugin
const storage = new MemoryStorageAdapter();
const plugin = new EncryptionPlugin("secret-key");
const encryptedStorage = plugin.wrapStorage(storage);

const db = new Database({
  name: "secure-db",
  storage: "memory",
  _storage: encryptedStorage, // Use the wrapped storage
});

License

MIT