npm package: @firekid/forgedb
Description: Official JavaScript/TypeScript client for ForgeDB
Author: Firekid
Latest version: 1.0.1

# @firekid/forgedb

[![npm version](https://img.shields.io/npm/v/@firekid/forgedb?style=flat-square&color=CB3837)](https://npmjs.com/package/@firekid/forgedb)
[![License: MIT](https://img.shields.io/badge/License-MIT-22C55E?style=flat-square)](LICENSE)

Official JavaScript/TypeScript client for [ForgeDB](https://forgedb.name.ng). Powered by [`@firekid/hurl`](https://npmjs.com/package/@firekid/hurl) — zero extra dependencies.

---

## Install

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

---

## Quick Start

```ts
import { createClient } from '@firekid/forgedb'

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

Get your `projectId` and `apiKey` from the [ForgeDB dashboard](https://forgedb.name.ng/app/keys).

---

## Selecting Rows

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

### Filter

```ts
// 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

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

### Search

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

### Sort

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

### Get by ID

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

---

## Mutating Rows

### Insert

```ts
const user = await db.from('users').insert({
  name: 'John Doe',
  email: 'john@example.com',
})
```

### Update

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

### Delete

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

### Bulk Delete

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

---

## Raw SQL

```ts
// 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

```ts
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` |

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

---

## Error Handling

```ts
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](https://github.com/Firekid-is-him)