JSPM – workers-qb@1.11.2

Package Exports

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (workers-qb) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

Zero-dependency Query Builder for Cloudflare Workers

Overview

workers-qb is a lightweight query builder designed specifically for Cloudflare Workers. It provides a simple, standardized interface while maintaining the performance benefits of raw queries over traditional ORMs.

📚 Read the full documentation

Key Differences from ORMs

Focused on direct SQL access with convenient wrapper methods
Maintains raw query performance
Zero dependencies
Lightweight and Worker-optimized

Supported Databases

Features

Core Features

Zero dependencies
Full TypeScript support
Database schema migrations
Type checking for data reads
Lazy row loading

Query Operations

Table operations (create/drop)
CRUD operations (insert/update/select/delete)
Bulk inserts
JOIN queries
Subqueries
Modular SELECT queries
ON CONFLICT handling
UPSERT support

Installation

npm install workers-qb --save

Usage Examples

Cloudflare D1

import { D1QB } from 'workers-qb'

export interface Env {
  DB: D1Database
}

export default {
  async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
    const qb = new D1QB(env.DB)

    type Employee = {
      name: string
      role: string
      level: number
    }

    // Using object syntax
    const employeeList = await qb
      .fetchAll<Employee>({
        tableName: 'employees',
        where: {
          conditions: 'active = ?1',
          params: [true],
        },
      })
      .execute()

    // Using method chaining
    const employeeListModular = await qb
      .select<Employee>('employees')
      .where('active = ?', true)
      .execute()

    return Response.json({
      activeEmployees: employeeList.results?.length || 0,
    })
  },
}

Cloudflare Durable Objects

import { DOQB } from 'workers-qb'

export class DOSRS extends DurableObject {
  getEmployees() {
    const qb = new DOQB(this.ctx.storage.sql)
    
    return qb
      .fetchAll({
        tableName: 'employees',
      })
      .execute()
      .results
  }
}

PostgreSQL Integration

First, install the required PostgreSQL client:

npm install pg --save

Enable Node compatibility in wrangler.toml:

node_compat = true

Example usage:

import { PGQB } from 'workers-qb'
import { Client } from 'pg'

export interface Env {
  DB_URL: string
}

export default {
  async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
    const qb = new PGQB(new Client(env.DB_URL))
    await qb.connect()

    const fetched = await qb
      .fetchOne({
        tableName: 'employees',
        fields: 'count(*) as count',
        where: {
          conditions: 'active = ?1',
          params: [true],
        },
      })
      .execute()

    // Important: Close the connection
    ctx.waitUntil(qb.close())
    
    return Response.json({
      activeEmployees: fetched.results?.count || 0,
    })
  },
}

Documentation

Visit our comprehensive documentation for detailed information about:

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.