@firekid/forgedb

Official JavaScript/TypeScript client for ForgeDB. Powered by @firekid/hurl — zero extra dependencies.

Install

npm install @firekid/forgedb
pnpm add @firekid/forgedb
yarn add @firekid/forgedb

Quick Start

import { createClient } from '@firekid/forgedb'

const db = createClient({
  projectId: 'your-project-id',
  apiKey: 'sk_live_...',
})

Get your projectId and apiKey from the ForgeDB dashboard.

Selecting Rows

const { rows, total, totalPages } = await db.from('users').select()

Filter

// Equality shorthand
const { rows } = await db.from('users').where('active', true).select()

// With operator — supports: = | != | > | < | >= | <= | like | in
const { rows } = await db.from('users').where('age', '>', 18).select()

// Chain multiple filters (AND)
const { rows } = await db.from('users')
  .where('active', true)
  .where('age', '>=', 18)
  .select()

Pagination

const { rows } = await db.from('users').page(2).limit(20).select()

Search

const { rows } = await db.from('users').search('john').select()

Sort

const { rows } = await db.from('users').orderBy('createdAt', 'desc').select()

Get by ID

const user = await db.from('users').selectById(1)

Mutating Rows

Insert

const user = await db.from('users').insert({
  name: 'John Doe',
  email: '[email protected]',
})

Update

const user = await db.from('users').update(1, { name: 'Jane Doe' })

Delete

await db.from('users').delete(1)

Bulk Delete

await db.from('users').bulkDelete([1, 2, 3])

Raw SQL

// Single statement
const result = await db.sql('SELECT * FROM users WHERE age > 18')
console.log(result.rows)

// Multiple statements
const result = await db.sql(`
  INSERT INTO logs (event) VALUES ('signup');
  SELECT COUNT(*) as total FROM users;
`)
console.log(result.statements) // 2
console.log(result.message)    // "2 statements executed · 1 row affected"

TypeScript

interface User {
  id: number
  name: string
  email: string
  age: number
  active: boolean
  createdAt: string
  updatedAt: string
}

const { rows } = await db.from<User>('users').select()
// rows → User[]

const user = await db.from<User>('users').selectById(1)
// user → User

Environments

The client automatically detects the environment from your API key:

| Key prefix | Environment | |-------------------|-------------| | sk_live_ / fk_live_ | prod | | sk_test_ / fk_test_ | test |

console.log(db.environment) // 'prod' or 'test'

Error Handling

import { createClient, ForgeDBError } from '@firekid/forgedb'

try {
  await db.from('users').insert({ name: 'John' })
} catch (err) {
  if (err instanceof ForgeDBError) {
    console.log(err.message) // human-readable message
    console.log(err.code)    // e.g. 'VALIDATION_ERROR'
    console.log(err.status)  // HTTP status code
    console.log(err.line)    // SQL line (for query errors)
    console.log(err.token)   // offending token (for query errors)
  }
}

License

MIT © Firekid