eden-db

Firebase-style PostgreSQL wrapper for Node.js + TypeScript. Zero-config collections with auto-migration, transactions, and type-safe queries.

Installation

npm install eden-db pg

Quick Start

import { db } from 'eden-db'

// Connect (auto-creates tables on first use)
await db.connect({ url: process.env.DATABASE_URL })

// Insert
const user = await db.collection('users').insert({
  name: 'Alice',
  email: '[email protected]',
  role: 'admin',
})

// Find all
const users = await db.collection('users').find()

// Find by ID
const one = await db.collection('users').findById(user.id)

// Query with filters
const admins = await db.collection('users').find({
  where: { role: 'admin' },
  orderBy: { field: 'createdAt', direction: 'desc' },
  limit: 10,
})

// Count
const total = await db.collection('users').count({ role: 'admin' })

// Update
await db.collection('users').update(user.id, { name: 'Alice Smith' })

// Delete
await db.collection('users').delete(user.id)

API Reference

db.connect(options)

await db.connect({
  url: 'postgresql://user:pass@localhost:5432/db',
  // or individual fields:
  host: 'localhost',
  port: 5432,
  database: 'mydb',
  user: 'admin',
  password: 'secret',
})

Collection Methods

| Method | Signature | Description | |--------|-----------|-------------| | .insert(data) | insert<T>(data: T) => Promise<T & { id }> | Insert a record | | .find() | find<T>(opts?) => Promise<T[]> | Find all or filtered | | .findById(id) | findById<T>(id) => Promise<T> | Find by primary key | | .update(id, data) | update<T>(id, data) => Promise<T> | Update by ID | | .delete(id) | delete(id) => Promise<void> | Delete by ID | | .count(where?) | count(where?) => Promise<number> | Count matching records |

Query Options

interface QueryOptions {
  where?: Record<string, any>    // { status: 'active', role: 'admin' }
  orderBy?: {
    field: string                  // 'createdAt'
    direction?: 'asc' | 'desc'      // default: 'asc'
  }
  limit?: number                  // default: unlimited
  offset?: number                 // for pagination
}

Transactions

await db.transaction(async (client) => {
  const user = await db.collection('users').insert({ name: 'Bob' }, client)
  await db.collection('logs').insert({ action: 'user_created', userId: user.id }, client)
})

Raw Queries

const result = await db.query('SELECT * FROM users WHERE role = $1', ['admin'])

Migrations

Auto-run on startup

import { runMigrations } from 'eden-db'

await runMigrations(db.internalPool!, './migrations')

Migration files

Create .sql files in your migrations folder:

-- migrations/001_init.sql
CREATE TABLE IF NOT EXISTS users (
  id SERIAL PRIMARY KEY,
  name TEXT NOT NULL,
  email TEXT UNIQUE,
  created_at TIMESTAMP DEFAULT NOW()
);

Applied migrations are tracked in the eden_migrations table automatically.

Environment Setup

# .env
DATABASE_URL=postgresql://user:password@localhost:5432/mydb

License

MIT