drizzle-castor is a type-safe CRUD library and Data Access Object (DAO) abstraction designed to simplify database operations over Drizzle ORM. It provides a JSON-based querying syntax, an extensible middleware pipeline, unified Role-Based Access Control (RBAC), and multi-dialect execution strategies.
You can install Drizzle-Castor from either NPM or JSR depending on your environment preference.
Available under the @fajarnugraha37 scope:
# Using bun (recommended)
bun add @fajarnugraha37/drizzle-castor
# Using npm
npm install @fajarnugraha37/drizzle-castor
# Using pnpm
pnpm add @fajarnugraha37/drizzle-castor
# Using yarn
yarn add @fajarnugraha37/drizzle-castorAvailable under the @fajar scope. Recommended for Deno or ESM-first projects:
# Using bun
bunx jsr add @fajar/drizzle-castor
# Using npx
npx jsr add @fajar/drizzle-castor
# Using deno
deno add jsr:@fajar/drizzle-castor- JSON-Based Querying (AST Translation): Filter, sort, and project relational data using intuitive JSON payloads (e.g.,
{ filter: { "posts.title": { $like: "%Drizzle%" } } }). - Unified RBAC Engine: Built-in, middleware-driven Role-Based Access Control. Secure operations at the action and field levels (Intelligent Data Trimming) with support for Declarative (Map) and Imperative (Async Callbacks) policies.
- Unified Middleware Pipeline: Adopts the Koa-style Onion Model for absolute control flow (
await next()) on every request. - Event-Driven Telemetry: Integrated system using
mitt. Emits structured, non-blocking events for execution performance, security audits, and data mutations. - Hybrid Logging: Quarkus-style pattern-based logging powered by
pino. Supports context injection (traceId, parameters) and nested object traversal in log patterns. - Dialect Agnostic: Supports PostgreSQL, MySQL, and SQLite. Handles complex dialect-specific logic under the hood (e.g.,
RETURNINGclauses vs. Temporary Tables for atomic mutations). - Native Soft Deletes: Declarative soft-delete capabilities that implicitly apply safety filters to queries and joins.
- Safe Pagination (Split Queries): Leverages Common Table Expressions (CTEs) to prevent Cartesian fan-out when paginating one-to-many or many-to-many relationships.
- Language: TypeScript
- Runtime: Bun & Node.js
- ORM: Drizzle ORM
- Logging: Pino
- Event Bus: Mitt
- Validation/Typing: Zod
- Testing: Bun Test, Node Test Runner, Testcontainers (for integration tests)
- Bun v1.0+ or Node.js
- Database of your choice (SQLite PostgreSQL or MySQL)
bun add @fajarnugraha37/drizzle-castor drizzle-ormFor detailed architectural diagrams and internal mechanics, refer to the following documentation:
Note
For a more detailed guide on setup, relations, and policy definitions, please refer to the Quick Start Guide.
import { drizzle } from "drizzle-orm/bun-sqlite";
import { createSchemaBuilder } from "@fajarnugraha37/drizzle-castor";
import { usersTable } from "./schema";
const db = drizzle("sqlite.db");
// 1. Initialize Builder
const builder = createSchemaBuilder(db, [usersTable] as const, "strict")
.profiles(['admin', 'user'] as const) // Define valid profiles for type-safety
.withLogger({ level: 'DEBUG', pattern: '%d [%p] (%t) %s' }) // Configure Hybrid Logger
.policies('users', {
admin: { allowedActions: "*", allowedProjections: "*", allowedFilters: "*" },
user: async (ctx) => ({ allowedActions: ["read"], allowedProjections: ["name"] }) // Imperative policy
});
// 2. Subscribe to Telemetry
builder.on('execution', (ev) => {
console.log(`${ev.action} on ${ev.tableName} took ${ev.duration}ms`);
});
const metadata = builder.build();
// 3. Create Repository
const userRepo = metadata.repoFactory("users");
// 4. Execute Type-Safe Queries
const results = await userRepo.searchMany({
filter: { "name": { $eq: "John Doe" } }
}, "admin");The library implements a Middleware-Driven Repository Pattern functioning as an Abstract Syntax Tree (AST) transpiler.
[ Application Logic ]
│
▼
[ Repository Interface ] (createOne, searchMany, etc.)
│
▼
[ Middleware Pipeline ] (Execution Context, RBAC, Custom Plugins)
│
▼
[ Executor Engine ] (single-executor, batch-executor)
│ (Uses Query Parser for AST compilation)
▼
[ Drizzle ORM ] -> [ Database Engine ]
├───src/ # Main library source code
│ ├───context/ # Execution context manager (Thread-local state)
│ ├───errors/ # Custom error classes (Security, Parsing, Mutation)
│ ├───helper/ # Shared utilities (Dialect, Assertions, Types)
│ ├───middleware/ # Koa-style pipeline and Unified RBAC engine
│ ├───mutations/ # Physical executors for INSERT, UPDATE, DELETE
│ ├───queries/ # Physical executors for SELECT and Hydration
│ ├───query-parser/ # AST Translators (JSON -> Drizzle SQL)
│ ├───types/ # TypeScript interfaces and global definitions
│ ├───schema-metadata.ts # Repository factory implementation
│ └───index.ts # Public API exports
└───tests/ # Test suites
The project uses tsup for bundling into ESM and CJS formats.
bun run buildTesting is divided into isolated unit tests (via Bun) and integration tests against real databases (via Testcontainers).
# Run isolated Unit Tests (Bun)
bun run test --isolate
# Run PostgreSQL Integration Tests (Node Test Runner + Testcontainers)
node --import tsx --test .\tests\integration\postgresql\*.test.ts
# Run MySQL Integration Tests (Node Test Runner + Testcontainers)
node --import tsx --test .\tests\integration\mysql\*.test.ts
# Run SQLite Integration Tests
bun run test:sqliteContributions are welcome! Please follow these guidelines:
- Adhere to the "No God File" rule (files should not exceed 300 lines).
- Do not bypass the internal AST generators or Executor strategies.
- Any new filter operators must include corresponding unit and integration tests across all dialects.
This project is licensed under the MIT License.