Drizzle-Castor

Installation

You can install Drizzle-Castor from either NPM or JSR depending on your environment preference.

Via NPM

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-castor

Via JSR

Available 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

Features

• 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., RETURNING clauses 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.

Technology Stack

• 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)

Getting Started

Prerequisites

• Bun v1.0+ or Node.js
• Database of your choice (SQLite PostgreSQL or MySQL)

Installation

bun add @fajarnugraha37/drizzle-castor drizzle-orm

Documentation

For detailed architectural diagrams and internal mechanics, refer to the following documentation:

• Project Architecture Blueprint
• How It Works
• Coding Standards
• Typescript Type
• Testing

Quick Usage

[!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");

Project

Architecture

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 ]

Directory Structure

├───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

Development Workflow & Testing

Building the Project

The project uses tsup for bundling into ESM and CJS formats.

bun run build

Testing

Testing 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:sqlite

Contributing

Contributions are welcome! Please follow these guidelines:

1. Adhere to the "No God File" rule (files should not exceed 300 lines).
2. Do not bypass the internal AST generators or Executor strategies.
3. Any new filter operators must include corresponding unit and integration tests across all dialects.

License

This project is licensed under the MIT License.