npm package: @kokolabs-io/db
Description: Pod-scoped SQLite database API for Koko with a Supabase-style query builder interface
Author: KokoLabs.io
Latest version: 1.0.0

# @kokolabs-io/db

Pod-scoped SQLite database API for Koko with a Supabase-style query builder interface.

## Features

- **Fluent Query Builder**: Chainable API for building SQL queries
- **CRUD Operations**: Full support for select, insert, update, and delete
- **Filter Operators**: eq, ne, gt, gte, lt, lte, like
- **Pagination**: limit, offset, and range methods
- **Database Management**: attach/detach databases
- **Type-Safe**: Full TypeScript support with generic types
- **Dual Mode**: Works in both native and remote environments

## Installation

```bash
pnpm add @kokolabs-io/db
```

## Usage

### Basic Queries

```typescript
import { db } from '@kokolabs-io/db';

// Select all records
const { data, error } = await db.from('users').select('*');

// Select with filter
const result = await db.from('users')
  .select('id, name, email')
  .eq('status', 'active')
  .limit(10);

// Single record
const user = await db.from('users')
  .select('*')
  .eq('id', 123)
  .single();
```

### Insert

```typescript
// Insert single record
const { data, error } = await db.from('users').insert({
  name: 'John Doe',
  email: 'john@example.com'
});

// Insert multiple records
await db.from('users').insert([
  { name: 'Alice', email: 'alice@example.com' },
  { name: 'Bob', email: 'bob@example.com' }
]);
```

### Update

```typescript
const { data, error } = await db.from('users')
  .update({ status: 'inactive' })
  .eq('last_login', null);
```

### Delete

```typescript
await db.from('users')
  .delete()
  .lt('created_at', '2025-01-01');
```

### Filter Operators

```typescript
// Equality
.eq('status', 'active')
.ne('role', 'guest')

// Comparison
.gt('age', 18)
.gte('score', 100)
.lt('price', 50)
.lte('quantity', 10)

// Pattern matching
.like('email', '%@example.com')
```

### Pagination

```typescript
// Limit and offset
await db.from('posts')
  .select('*')
  .limit(20)
  .offset(40);

// Range (inclusive)
await db.from('posts')
  .select('*')
  .range(0, 19); // First 20 records
```

### Raw SQL

```typescript
// Execute raw SQL
const result = await db.sql(
  'SELECT * FROM users WHERE age > ?',
  [18]
);
```

### Database Attachment

```typescript
// Attach another database
await db.attach('/path/to/other.db', 'other_db');

// Query from attached database
await db.from('other_db.table_name').select('*');

// Detach database
await db.detach('other_db');
```

### Custom Client

```typescript
import { createClient } from '@kokolabs-io/db';

const customDb = createClient({
  apiUrl: 'https://api.example.com',
  apiKey: 'your-api-key',
  dbId: 'your-db-id',
  preferRecords: true
});
```

## API Reference

### QueryBuilder Methods

- `select(columns?: string)` - Select columns
- `insert(data)` - Insert records
- `update(data)` - Update records
- `delete()` - Delete records
- `eq(col, value)` - Equal to
- `ne(col, value)` - Not equal to
- `gt(col, value)` - Greater than
- `gte(col, value)` - Greater than or equal
- `lt(col, value)` - Less than
- `lte(col, value)` - Less than or equal
- `like(col, value)` - Pattern match
- `limit(n)` - Limit results
- `offset(n)` - Skip results
- `range(from, to)` - Paginate with range
- `single()` - Return single record
- `maybeSingle()` - Return single or null

### Result Format

```typescript
interface DbResult<T> {
  data: T | null;
  error: unknown | null;
  count?: number | null;
  meta?: unknown;
}
```

## Build

Build from root:

```bash
pnpm -C .. build
```

Build this package only:

```bash
pnpm --filter @kokolabs-io/db build
```

## License

MIT - Copyright (c) 2026 KokoLabs.io