Imported from relsunkaev/effect-qb (AGENTS.md). Install upstream with npx skills add relsunkaev/effect-qb. Copyright stays with the author.

Default to using Bun instead of Node.js.

Use bun <file> instead of node <file> or ts-node <file>
Use bun test instead of jest or vitest
Use bun build <file.html|file.ts|file.css> instead of webpack or esbuild
Use bun install instead of npm install or yarn install or pnpm install
Use bun run <script> instead of npm run <script> or yarn run <script> or pnpm run <script>
Bun automatically loads .env, so don't use dotenv.

TypeScript

This project should use tsgo for TypeScript compilation and typechecking.

Use bunx tsgo instead of tsc
Use bunx tsgo -p <tsconfig> for project typechecks
Prefer existing repo scripts that already invoke tsgo
Do not introduce new tsc-based scripts or documentation unless there is a specific, documented reason

APIs

Bun.serve() supports WebSockets, HTTPS, and routes. Don't use express.
bun:sqlite for SQLite. Don't use better-sqlite3.
Bun.redis for Redis. Don't use ioredis.
Bun.sql for Postgres. Don't use pg or postgres.js.
WebSocket is built-in. Don't use ws.
Prefer Bun.file over node:fs's readFile/writeFile
Bun.$ls instead of execa.

Testing

Use bun test to run tests.

import { test, expect } from "bun:test";

test("hello world", () => {
  expect(1).toBe(1);
});

Frontend

Use HTML imports with Bun.serve(). Don't use vite. HTML imports fully support React, CSS, Tailwind.

Server:

import index from "./index.html"

Bun.serve({
  routes: {
    "/": index,
    "/api/users/:id": {
      GET: (req) => {
        return new Response(JSON.stringify({ id: req.params.id }));
      },
    },
  },
  // optional websocket support
  websocket: {
    open: (ws) => {
      ws.send("Hello, world!");
    },
    message: (ws, message) => {
      ws.send(message);
    },
    close: (ws) => {
      // handle close
    }
  },
  development: {
    hmr: true,
    console: true,
  }
})

HTML files can import .tsx, .jsx or .js files directly and Bun's bundler will transpile & bundle automatically. <link> tags can point to stylesheets and Bun's CSS bundler will bundle.

<html>
  <body>
    <h1>Hello, world!</h1>
    <script type="module" src="./frontend.tsx"></script>
  </body>
</html>

With the following frontend.tsx:

import React from "react";

// import .css files directly and it works
import './index.css';

import { createRoot } from "react-dom/client";

const root = createRoot(document.body);

export default function Frontend() {
  return <h1>Hello, world!</h1>;
}

root.render(<Frontend />);

Then, run index.ts

bun --hot ./index.ts

For more information, read the Bun API docs in node_modules/bun-types/docs/**.md.

Git

Do not prefix branch names with codex/.

Runtime and build boundaries

Keep Bun as the workspace package manager and tooling runtime.
Keep published effect-qb and effect-db runtime behavior Node.js-native.
Prefer Effect Platform services for filesystem, path, terminal, process, and other host capabilities. Keep Node-specific implementations at the runtime assembly boundary with NodeServices and NodeRuntime.
Assume consumer code is bundled or built with esbuild. Do not add a runtime TypeScript loader solely to support unbuilt TypeScript syntax.

Querybuilder public API boundaries

Keep property-path JSON navigation such as jsonColumn.someArray[2].someField. Reusable focuses and pipeable mutations supplement that API.
JSON paths and mutations use stored encoded shapes and return stored values. Whole-column selection retains schema decoding.
JSON transport is explicit: default PostgreSQL/MySQL clients return decoded JSON; SQLite JSON-valued paths return serialized JSON and decode once. Custom driver representations use value-mapping overrides, not content guessing.
Expose native division only through dialect function modules. Keep numeric cast witnesses unqualified engine casts; portable precision/scale is not a contract. Column DDL precision remains separate.
Use PostgreSQL 16.x and MySQL 8.4.x as the initial coercion support baseline; verify SQLite per supported driver. Reject unsupported modeled built-in cast pairs; custom metadata remains a caller assertion.
Prefer pipeable Effect transforms for result cardinality instead of adding convenience methods to executors. Keep result metadata on executors because the driver owns that contract.
Standard query and function exports must have supported syntax and compatible runtime semantics across PostgreSQL, MySQL, and SQLite. Otherwise expose the capability only from the applicable dialect module.
Keep pagination ordering, seek predicates, limits, and cursor policy explicit and composable. Do not add a compound keyset modifier without a reviewed pagination contract.

Beads Issue Tracker

This project uses bd (beads) for issue tracking. Run bd prime to see full workflow context and commands.

Quick Reference

bd ready              # Find available work
bd show <id>          # View issue details
bd update <id> --claim  # Claim work
bd close <id>         # Complete work

Rules

Use bd for ALL task tracking — do NOT use TodoWrite, TaskCreate, or markdown TODO lists
Run bd prime for detailed command reference and session close protocol
Use bd remember for persistent knowledge — do NOT use MEMORY.md files

Session Completion

When ending a work session, you MUST complete ALL steps below. Work is NOT complete until git push succeeds.

MANDATORY WORKFLOW:

File issues for remaining work - Create issues for anything that needs follow-up
Run quality gates (if code changed) - Tests, linters, builds
Update issue status - Close finished work, update in-progress items

PUSH TO REMOTE - This is MANDATORY:

git pull --rebase
bd dolt push
git push
git status  # MUST show "up to date with origin"

Clean up - Clear stashes, prune remote branches
Verify - All changes committed AND pushed
Hand off - Provide context for next session

CRITICAL RULES:

Work is NOT complete until git push succeeds
NEVER stop before pushing - that leaves work stranded locally
NEVER say "ready to push when you are" - YOU must push
If push fails, resolve and retry until it succeeds

effect-qb

About