@sebwojtasik/polodb v0.0.2

PoloDB Node.js Bindings

PoloDB is a lightweight embedded database that provides MongoDB-like syntax. This package provides Node.js bindings for PoloDB, allowing you to use PoloDB in your Node.js applications.

Installation

pnpm add @sebwojtasik/polodb

Quick Start

import { PoloDbClient } from '@sebwojtasik/polodb'

// Create a new database or connect to an existing one
const client = new PoloDbClient('path/to/database.db')

// Get a collection
const collection = client.collection('users')

// Insert a document
await collection.insertOne({ name: 'John', age: 30 })

// Query documents
const user = await collection.findOne({ name: 'John' })

API Reference

PoloDbClient

The main client class for interacting with PoloDB.

const client = new PoloDbClient(path: string);

Collection Operations

Inserting Documents

// Insert a single document
const user = await collection.insertOne({
  name: 'John Doe',
  age: 30,
  email: 'john@example.com',
  createdAt: new Date(),
})

// Insert multiple documents
const users = await collection.insertMany([
  { name: 'Jane Doe', age: 25, email: 'jane@example.com' },
  { name: 'Bob Smith', age: 35, email: 'bob@example.com' },
  { name: 'Alice Johnson', age: 28, email: 'alice@example.com' },
])

Querying Documents

// Find one document
const user = await collection.findOne({ name: 'John Doe' })

// Find with complex conditions
const seniorUser = await collection.findOne({
  age: { $gte: 30 },
  email: { $regex: '@example.com$' },
})

// Find multiple documents
const activeUsers = await collection
  .find({
    lastLoginDate: { $gte: new Date('2024-01-01') },
    status: 'active',
  })
  .toArray()

// Find with $or operator
const results = await collection
  .find({
    $or: [{ age: { $lt: 25 } }, { premium: true }],
  })
  .toArray()

Updating Documents

// Update one document
const updateResult = await collection.updateOne(
  { email: 'john@example.com' },
  {
    $set: { lastLoginDate: new Date() },
    $inc: { loginCount: 1 },
  },
)

// Update multiple documents
const bulkUpdate = await collection.updateMany(
  { age: { $lt: 30 } },
  {
    $set: { category: 'young' },
    $inc: { age: 1 },
  },
)

// Update with multiple operators
const complexUpdate = await collection.updateOne(
  { userId: '123' },
  {
    $set: { updatedAt: new Date() },
    $inc: { points: 10 },
    $max: { highScore: 1000 },
    $rename: { oldField: 'newField' },
    $unset: { temporaryFlag: '' },
  },
)

Deleting Documents

// Delete one document
const deleteOne = await collection.deleteOne({
  email: 'john@example.com',
})

// Delete multiple documents
const deleteInactive = await collection.deleteMany({
  lastLoginDate: { $lt: new Date('2023-01-01') },
  status: 'inactive',
})

// Delete with complex conditions
const deleteBulk = await collection.deleteMany({
  $or: [{ status: 'deleted' }, { expirationDate: { $lt: new Date() } }],
})

Cursor Operations

The cursor returned by find() supports several operations:

// Sorting, limiting, and skipping results
const topUsers = await collection
  .find({ status: 'active' })
  .sort({ score: -1 }) // -1 for descending order
  .limit(10)
  .toArray()

// Pagination example
const pageSize = 20
const pageNumber = 2
const paginatedUsers = await collection
  .find({ age: { $gte: 18 } })
  .sort({ createdAt: -1 })
  .skip((pageNumber - 1) * pageSize)
  .limit(pageSize)
  .toArray()

// Complex query with multiple operations
const filteredUsers = await collection
  .find({
    age: { $gte: 18, $lte: 65 },
    status: 'active',
    subscriptionLevel: { $in: ['premium', 'pro'] },
  })
  .sort({
    subscriptionLevel: -1,
    createdAt: 1,
  })
  .skip(100)
  .limit(50)
  .toArray()

Advanced features

Transactions, indexes and aggregation are currently not supported. I have no plan to support them for now.

TypeScript Support

PoloDB bindings are written in TypeScript and provide (some) type safety. You can specify the document type when creating a collection:

interface User {
  name: string
  age: number
  email: string
  createdAt: Date
  lastLoginDate?: Date
  status: 'active' | 'inactive'
  subscriptionLevel?: 'free' | 'premium' | 'pro'
  points?: number
  highScore?: number
}

const users = client.collection<User>('users')

// TypeScript will now provide type checking and autocompletion
const newUser = await users.insertOne({
  name: 'John Doe',
  age: 30,
  email: 'john@example.com',
  createdAt: new Date(),
  status: 'active',
})

License

Binding code is released under the MIT license.