Typescript Bun Drizzle Quality

TypeScript Bun Drizzle Quality

Use this as an umbrella fullstack skill for Bun + TypeScript + Drizzle work.

For slop-reduction/refactor passes focused on deleting custom helpers/types/assertions, use ../desloppify/SKILL.md alongside this skill.

Deliver production-grade code by optimizing for:

• type safety and clarity
• predictable runtime behavior in Bun
• correct and reversible data changes with Drizzle
• clean contract boundaries between API, domain logic, and persistence

Repository Overrides (Required When Present)

Always follow repository-level agent rules (for example AGENTS.md) when they are stricter than this skill.

In this repository, enforce these defaults while using this skill:

• keep things in one function unless extraction is clearly reusable
• avoid try/catch where practical; prefer explicit control flow
• avoid else; prefer early returns
• avoid any and broad assertions
• prefer single-word names when possible
• avoid unnecessary destructuring; prefer dot access
• prefer functional array methods over loops when practical
• prefer Bun-native APIs like Bun.file() where practical
• run tests from package directories, not repository root, when root test is guarded

Track Selection

Choose the track before coding:

1. App/API logic track
   • Use when changing handlers, services, orchestration, auth, or domain rules.
2. Data layer track
   • Use when changing Drizzle schema, migrations, indexes, transactions, or query shape.
3. Fullstack integration track
   • Use when changes cross boundaries (API contract + domain behavior + database effects).

If multiple tracks apply, run App/API first, then Data layer, then Integration checks.

1) Define Constraints First

Before coding, pin down:

• runtime: Bun version and package manager commands
• database: SQL dialect (Postgres/MySQL/SQLite/Turso) and migration flow
• API shape: request/response contracts and error model
• compatibility: expected behavior changes vs strict backward compatibility

If context is missing, ask only for blocking details. Otherwise proceed with explicit assumptions.

2) Adapt to the Host Repository

Distill practices into the target repository instead of assuming fixed commands or structure.

Before implementation or review:

• inspect workspace scripts to discover quality gates (typecheck, lint/format, test)
• inspect CI workflows to confirm which checks are required in pull requests
• identify local test taxonomy and map commands to:
  • unit tests
  • integration tests
  • e2e tests
• run only the smallest relevant subset for touched code paths

Do not assume naming conventions like test:unit or test:e2e; infer from scripts and workflow usage.

3) Fullstack Testing with Bun (Required)

Treat test design and test execution as first-class implementation work.

Use this decision flow:

1. classify repository test commands by behavior into unit, integration, and e2e
2. map touched files/modules to the smallest package/service-local commands
3. if root test is guarded (for example intentionally fails), do not run tests from root
4. run required layers in order: unit -> integration -> e2e, based on scope/risk
5. ensure CI-required checks for pull requests are represented in local verification
6. if no explicit integration suite exists, treat boundary tests (API + real DB or equivalent) as integration coverage and call it out

Technical expectations for Bun repositories:

• use Bun test runner features intentionally (bun test, --watch, --preload, --timeout, path filters)
• keep unit tests deterministic and fast; avoid network and global time randomness
• for integration tests, run real migrations/schema setup and isolate test data
• for e2e, run realistic app wiring and capture artifacts on failure

Do not mark work complete unless one of these is true:

• relevant tests were executed and results were recorded
• execution was blocked by environment constraints and the block + residual risk were stated explicitly

For deeper guidance, read references/testing-patterns.md. For copyable boundary snippets, read references/examples/integration-boundary-test.md.