Forem: Tetsuya Wakita

I Rewrote python-dateutil in Rust — Even a Naive Port Is Up to 94x Faster

Tetsuya Wakita — Wed, 08 Apr 2026 08:53:33 +0000

TL;DR — pip install python-dateutil-rs, change one import, get 5x–94x faster date parsing, recurrence rules, and timezone lookups. It's a line-by-line Rust port via PyO3 — no code changes required. GitHub | PyPI

python-dateutil Is Everywhere — and It's Pure Python

python-dateutil is one of the most depended-on packages in the Python ecosystem. With 300M+ monthly downloads on PyPI, it powers date parsing, relative deltas, recurrence rules, and timezone handling across countless applications.

But it's written in pure Python. For hot paths — parsing thousands of ISO timestamps in a data pipeline, expanding recurring calendar events, computing relative dates in a loop — that means leaving significant performance on the table.

What if you could make it up to 94x faster without changing a single line of your application code?

pip install python-dateutil-rs

That's python-dateutil-rs — a Rust-backed drop-in replacement I built using PyO3 and maturin. Same API, same behavior, dramatically faster.

And here's the thing: this is a naive, line-by-line port. The Rust code mirrors the original Python logic almost 1:1, with no Rust-specific optimizations yet. The speedups come purely from Rust's compiled nature — no dynamic dispatch, minimal GC pressure, no interpreter overhead.

The Approach: Module-by-Module Rewrite via PyO3

A full rewrite of a battle-tested library is risky. Instead, I took an incremental approach: rewrite each module in Rust independently, validate against the original test suite (~13,000 lines of tests, all passing), and ship value at every step.

The architecture uses maturin's mixed layout — a Rust extension module and Python wrapper live in the same package:

dateutil_rs (Python package)
  ├── _native (Rust extension via PyO3/maturin)  ← all modules
  └── Python wrappers                             ← API compatibility layer

Every module is now implemented in Rust: parser, relativedelta, rrule, tz, easter, utils, and weekday constants. The Python layer handles API compatibility — for example, serializing custom parserinfo lookup tables and forwarding them to the Rust parser:

from dateutil_rs._native import isoparse
from dateutil_rs._native import parse as _parse_rs

def parse(timestr, parserinfo=None, **kwargs):
    if parserinfo is not None:
        # Serialize custom lookup tables → forward to Rust
        config = parserinfo._to_rust_config()
        return _parse_rs(timestr, parserinfo_config=config, **kwargs)
    return _parse_rs(timestr, **kwargs)

The API is identical to python-dateutil — just change the import:

# Before (python-dateutil)
from dateutil.parser import parse
from dateutil.relativedelta import relativedelta
from dateutil.rrule import rrule, MONTHLY
from dateutil.tz import gettz, tzutc

# After (python-dateutil-rs) — same code
from dateutil_rs.parser import parse
from dateutil_rs.relativedelta import relativedelta
from dateutil_rs.rrule import rrule, MONTHLY
from dateutil_rs.tz import gettz, tzutc

Benchmark Results

All benchmarks: Python 3.13, macOS Apple Silicon M3 (arm64), Rust 1.86 stable, release build (--release), measured with pytest-benchmark. Compared against python-dateutil 2.9.0.

At a Glance

Module	Speedup Range	Highlight
Timezone	1.7x – 94.3x	Batch `gettz()` with cache: 94.3x
ISO Parser	5.1x – 23.5x	With microseconds: 23.5x
RRule	3.1x – 20.0x	`rrulestr` with dtstart: 20.0x
RelativeDelta	4.9x – 18.7x	Multiply by scalar: 18.7x
General Parser	1.3x – 3.5x	Fuzzy parsing: 3.5x
Easter	3.2x – 6.2x	1000 years batch: 6.2x

Note on the 94.3x headline number: The timezone benchmark includes a Rust-side RwLock<HashMap> cache (similar to python-dateutil's _TzFactory). Without caching, pure timezone operations still see 1.7x–3.8x speedups. The most representative single-operation speedup is 23.5x on ISO parsing.

ISO Parsing — Up to 23.5x Faster

Benchmark	python-dateutil	dateutil-rs	Speedup
Date only	0.81 µs	0.08 µs	10.7x
Datetime	2.06 µs	0.10 µs	20.9x
Datetime + TZ	3.11 µs	0.61 µs	5.1x
With microseconds	2.67 µs	0.11 µs	23.5x
7 various formats	23.10 µs	3.10 µs	7.4x

RelativeDelta — Up to 18.7x Faster

Benchmark	python-dateutil	dateutil-rs	Speedup
Create simple	0.94 µs	0.19 µs	4.9x
Add months	1.62 µs	0.13 µs	12.7x
Subtract	3.03 µs	0.18 µs	16.5x
Multiply by scalar	1.49 µs	0.08 µs	18.7x
Sequential add ×12	19.41 µs	1.70 µs	11.4x
Month-end overflow	1.74 µs	0.13 µs	13.3x

RRule (Recurrence Rules) — Up to 20x Faster

Benchmark	python-dateutil	dateutil-rs	Speedup
Weekly ×52	105.33 µs	34.44 µs	3.1x
Monthly ×120	448.46 µs	114.12 µs	3.9x
Yearly ×100	2,144.58 µs	235.02 µs	9.1x
rrulestr simple	3.14 µs	0.53 µs	6.0x
rrulestr complex	6.60 µs	0.90 µs	7.4x
rrulestr with dtstart	15.61 µs	0.78 µs	20.0x

Timezone — Up to 94.3x Faster (Cache-Inclusive)

Benchmark	python-dateutil	dateutil-rs	Speedup
gettz various (×10)	714.93 µs	7.59 µs	94.3x
gettz offset	20.20 µs	5.26 µs	3.8x
resolve_imaginary	6.54 µs	3.19 µs	2.0x
datetime_exists	3.15 µs	1.62 µs	1.9x
convert chain	6.74 µs	4.08 µs	1.7x

The 94.3x speedup on batch gettz() comes from a process-global RwLock<HashMap> cache — similar to python-dateutil's _TzFactory, but with Rust's near-zero-cost Arc clone for cached timezone objects. Even without the cache hit, individual timezone operations see 1.7x–3.8x improvements from compiled execution alone.

Easter — Up to 6.2x Faster

Benchmark	python-dateutil	dateutil-rs	Speedup
Single call	0.51 µs	0.13 µs	3.9x
1000 years	437.88 µs	70.46 µs	6.2x

Why Is It Fast? It's Just Rust Being Rust

Here's the surprising part: the Rust code is a faithful, almost line-by-line translation of the Python source. I didn't design clever algorithms or exploit Rust-specific data structures. The speedups come from the fundamental differences between compiled and interpreted execution.

Profiling revealed that Python's overhead isn't in any single place — it's everywhere. Every function call, every attribute access, every integer comparison, every object allocation pays an interpreter tax. In a tight loop, these micro-costs compound dramatically. That's why even a naive port sees 5x–94x improvements on batch operations.

Let's look at three modules to see exactly where the performance comes from:

isoparse: Byte-Level Parsing (23.5x)

The original isoparser in Python uses string slicing and int() conversion. The Rust version does the same logic — but on byte arrays instead of Python strings:

fn parse_isodate_common(&self, dt_str: &[u8]) -> Result<([i32; 3], usize), String> {
    let mut c = [1i32; 3]; // [year, month, day]

    // Year: parse 4 ASCII bytes directly
    c[0] = parse_int(&dt_str[..4])?;
    let mut pos = 4;

    let has_sep = dt_str[pos] == b'-';
    if has_sep { pos += 1; }

    // Month: 2 bytes
    c[1] = parse_int(&dt_str[pos..pos + 2])?;
    pos += 2;

    // Day: 2 bytes
    // ...
}

Same algorithm as the Python version. No string allocation, no regex, no dynamic dispatch — just the inherent overhead of interpretation removed. The parse_int helper converts ASCII bytes to integers with a multiply-and-add loop. For a microsecond field like 123456, this is dramatically faster than Python's int("123456").

Result: "2024-01-15T10:30:00.123456+09:00" goes from 2.67 µs to 0.11 µs.

RelativeDelta: Fixed Struct vs Dynamic Attributes (18.7x)

Python's relativedelta stores fields as instance attributes with getattr/setattr patterns. The Rust version uses a fixed struct — same fields, same logic:

pub struct RelativeDelta {
    // Relative (plural) fields — offsets
    years: i32,
    months: i32,
    days: f64,
    hours: f64,
    minutes: f64,
    seconds: f64,
    microseconds: f64,
    // Absolute (singular) fields — "set to this value"
    year: Option<i32>,
    month: Option<i32>,
    day: Option<i32>,
    // ...
}

Multiplication is just multiplying each field — no dictionary lookups, no attribute resolution, no type coercion overhead. Same algorithm, 18.7x faster.

RRule: Same Algorithm, Less Overhead (9.1x–20x)

Recurrence rules (RFC 5545) are the most complex module — they expand patterns like "every 3rd Tuesday of the month" into concrete dates. The Rust implementation follows the same expansion algorithm as python-dateutil:

Stack-allocated date arithmetic via chrono instead of Python datetime objects
No per-iteration object allocation or GC pressure
Integer comparisons instead of Python object protocol (__lt__, __eq__)

For yearly rules over 100 occurrences, the overhead compounds: 2,144 µs → 235 µs. For rrulestr parsing, the gap is even wider — 20x faster because string-to-rule conversion involves heavy tokenization that benefits enormously from compiled execution.

What's Next: v1 — Actually Optimized Rust

Everything above is v0 — a compatibility-first port that proves Rust's floor is Python's ceiling. The Rust code deliberately mirrors Python's logic to ensure behavioral fidelity against 13,000 lines of inherited tests.

v1 is where things get interesting. It will be a clean Rust-native implementation with real optimizations:

Optimization	Technique	Target Impact
Zero-copy parsing	`&str` slices instead of `String` clones	Parser: 5x–50x
Compile-time hash maps	`phf` perfect hash for weekday/month lookup	Parser: faster tokenization
Buffer reuse	Pre-allocated buffers cleared across iterations	RRule: 5x–15x
Minimal allocations	`SmallVec`, stack buffers, arena patterns	All modules
Streamlined API	Drop rarely-used features (fuzzy parse, POSIX tz)	Smaller, faster core

v1 will ship as:

dateutil on crates.io — pure Rust crate, no PyO3 dependency
dateutil on PyPI — thin PyO3 binding layer wrapping the Rust core

The v0 → v1 migration path:

v0.x: faithful python-dateutil port (current — 1.3x–94x faster)
v1.x: Rust-optimized core (target — 5x–100x faster)

If a naive port already delivers up to 94x speedups, imagine what happens when the Rust code is actually written like Rust.

What I Learned Building This

PyO3 Is Remarkably Ergonomic

PyO3's derive macros make exposing Rust types to Python straightforward:

#[pyclass(name = "relativedelta")]
pub struct RelativeDelta { /* ... */ }

#[pymethods]
impl RelativeDelta {
    #[new]
    fn new(/* 15+ optional kwargs */) -> Self { /* ... */ }

    fn __add__(&self, other: &Bound<'_, PyAny>) -> PyResult<PyObject> {
        // Handle datetime + relativedelta
    }
}

The trickiest part was datetime ↔ chrono conversion. PyO3's chrono feature handles the basics, but timezone-aware datetimes require careful handling of the Python tzinfo protocol.

A Faithful Port Is a Valid Strategy

The instinct when rewriting in Rust is to redesign everything. I resisted that. By keeping the logic 1:1 with Python, I could validate correctness against the original test suite — and still ship massive speedups. The optimization pass (v1) comes later, built on a foundation that is already proven correct.

Where the Overhead Actually Is

The takeaway is clear: CPython's per-operation overhead is small in isolation, but it compounds multiplicatively in loops. A date parser that touches 10 fields per call, called 10,000 times, pays the interpreter tax 100,000 times. Rust pays it zero times.

Try It

pip install python-dateutil-rs

GitHub: wakita181009/dateutil-rs
PyPI: python-dateutil-rs
Python: 3.10–3.14 on Linux and macOS (Windows support planned)

The project is open source (MIT). If your application use Ws python-dateutil, switching is a one-line import change. v0 is stable, fully tested, and API-compatible. v1 — the Rust-optimized core with zero-copy parsing and phf hash maps — is coming.

The numbers speak for themselves. And once zero-copy parsing and arena allocation land in v1, they're about to get a lot bigger.

Zod vs Typia vs AJV — I Built a Build Plugin That Makes Zod 60x Faster With Zero Code Changes

Tetsuya Wakita — Sun, 29 Mar 2026 17:39:43 +0000

When I first released Zod AOT, it required wrapping every schema with compile():

import { compile } from "zod-aot";

const UserSchema = compile(
  z.object({
    name: z.string().min(1),
    email: z.email(),
  })
);

The #1 feedback was: "I don't want to change my code."

Fair. So I removed that requirement. Zod AOT now has an autoDiscover mode — a Vite plugin that finds your Zod schemas at build time, compiles them into optimized validators, and replaces them in-place. Your schema files stay pure Zod. No imports from zod-aot. No wrappers. Just this:

// vite.config.ts
import zodAot from "zod-aot/vite";

export default defineConfig({
  plugins: [zodAot({ autoDiscover: true })],
});

That's it. Every exported Zod schema in your project gets AOT-compiled at build time.

I also added Typia and AJV to the benchmarks, built a two-phase "Fast Path" validator, and shipped a diagnostic CLI. Here's what changed.

autoDiscover: How It Works

The challenge is detecting Zod schemas without any marker in the source code. There's no compile() call, no special import — just plain Zod:

// src/schemas.ts — plain Zod, no Zod AOT import
import { z } from "zod";

export const CreateUserSchema = z.object({
  name: z.string().min(1).max(100),
  email: z.email(),
  age: z.number().int().min(0).max(150),
  role: z.enum(["admin", "editor", "viewer"]),
});

export const UpdateUserSchema = z.object({
  name: z.string().min(1).max(100).optional(),
  email: z.email().optional(),
  age: z.number().int().min(0).max(150).optional(),
  role: z.enum(["admin", "editor", "viewer"]).optional(),
});

The plugin detects and compiles these in four steps:

Step 1: Regex Pre-filter

Before doing any work, the plugin checks if the file contains a runtime Zod import:

import { z } from "zod"   ✓  (runtime — schema definitions)
import type { z } from "zod"  ✗  (type-only — skip)

Files without a runtime Zod import are skipped entirely. This keeps build times fast — most files in your project aren't schema files.

Step 2: Execute and Inspect Exports

The plugin loads the source file at build time using jiti and inspects each export:

function isZodSchema(value: unknown): boolean {
  if (typeof value !== "object" || value === null || !("_zod" in value))
    return false;
  const zod = (value as Record<string, unknown>)["_zod"];
  return typeof zod === "object" && zod !== null && "def" in zod;
}

Every Zod schema has a _zod.def structure — this is the internal definition that describes the schema's type, checks, and children. If an export has this marker, it's a Zod schema.

Step 3: Compile to Optimized Validators

Each discovered schema goes through the Zod AOT compilation pipeline:

Zod Schema → Extract IR → Generate Code → Wrap in IIFE

The pipeline walks the schema tree, extracts an intermediate representation, and generates flat, inlined validation code — the same process as before, but triggered automatically.

Step 4: AST-Based Source Replacement

The plugin uses acorn to parse expression boundaries in the source code:

// Before (source)
export const CreateUserSchema = z.object({ ... });

// After (build output)
export const CreateUserSchema = /* @__PURE__ */ (() => {
  // ... generated validation code ...
  var __w = Object.create(originalSchema);
  __w.parse = function(input) { /* optimized */ };
  __w.safeParse = __validate;
  __w.schema = originalSchema;
  return __w;
})();

The Object.create(originalSchema) is key — it preserves the full Zod API. Your compiled schema still has .shape, .keyof(), .pick(), .merge(), and everything else. Framework code that inspects schema metadata (like tRPC or React Hook Form resolvers) continues to work.

Build Output

With verbose: true, you see what happened:

[zod-aot] Auto-discovering: src/schemas.ts (4 Zod exports found)
[zod-aot]   ✓ CreateUserSchema
[zod-aot]   ✓ UpdateUserSchema
[zod-aot]   ✓ ListUsersSchema
[zod-aot]   ✓ UserIdSchema
[zod-aot] Build summary: 4/4 schemas optimized across 1 file(s)

Scoping

Not every file should be auto-discovered — you probably don't want to execute test fixtures or files with side effects at build time. Use include and exclude:

zodAot({
  autoDiscover: true,
  include: ["src/schemas"],
  exclude: ["test", "mock"],
});

Two-Phase Validation: The Fast Path

The prior version of Zod AOT generated error-collecting validators — they always created an issues array and tracked every validation failure. That's necessary for error reporting, but it's overhead when the input is valid.

In production, most inputs are valid. So I added a Fast Path.

Phase 1: Boolean Expression Chain

For valid inputs, the entire schema is validated with a single boolean expression:

// Generated Fast Path for CreateUserSchema
typeof input==="object"&&input!==null&&!Array.isArray(input)&&
typeof input.name==="string"&&input.name.length>=1&&input.name.length<=100&&
typeof input.email==="string"&&__re0.test(input.email)&&
typeof input.age==="number"&&!Number.isNaN(input.age)&&
  Number.isSafeInteger(input.age)&&input.age>=0&&input.age<=150&&
(input.role==="admin"||input.role==="editor"||input.role==="viewer")

If this evaluates to true, the function returns { success: true, data: input } immediately.

Zero allocations. No issues array. No error objects. No path arrays. Just a boolean chain that short-circuits on the first failure.

Regex patterns and enum Sets are pre-compiled in a preamble:

var __re0 = /^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$/;
// Small enums (≤3 values) use inline === checks instead of Set.has()

Phase 2: Error-Collecting Path (Slow Path)

If the Fast Path fails — meaning the input has at least one issue — the full error-collecting validator runs. This creates the standard { success: false, error: { issues: [...] } } response with codes, paths, and messages.

The key insight: the Slow Path only runs when it's actually needed. For hot API endpoints where 95%+ of requests pass validation, the Fast Path is all that executes.

Fast Path Eligibility

Not every schema qualifies for a Fast Path. Schemas with .transform(), .refine(), .default(), .coerce(), or .catch() are ineligible because they need to modify the input or run opaque functions. The check command (see below) tells you which schemas qualify.

The 5-Way Benchmark

I added Typia and AJV to the benchmark suite. All five validators parse the same data with equivalent schemas:

Zod v3: Interpreter model, walks schema tree on every call
Zod v4: New architecture with JIT object compilation via new Function()
Zod AOT: Build-time compilation with two-phase validation
Typia: Compile-time code generation via TypeScript transformer
AJV: JSON Schema validator with ahead-of-time compilation

Environment: Node.js v22, Apple M-series, Vitest bench, 1M+ iterations with warmup.

Full Results

Schema	Zod v3	Zod v4	Zod AOT	Typia	AJV
String min/max	8.3M	5.6M	10.6M	10.5M	8.8M
Enum	7.6M	9.3M	10.2M	10.8M	10.7M
Medium object (valid)	1.3M	1.7M	5.2M	7.0M	4.8M
Medium object (invalid)	365K	63K	471K	2.1M	4.7M
Large object — 100 items	8.6K	11.6K	627K	808K	89K
Discriminated union (3)	2.3M	3.0M	10.2M	10.6M	5.4M
Recursive tree — 121 nodes	23K	103K	733K	1.4M	251K
Set (20 items)	980K	461K	7.6M	—	—
Map (20 entries)	479K	235K	5.1M	—	—
Event log (mixed types)	263K	473K	4.5M	—	—
Partial fallback — 50 items	18K	30K	238K	—	—

ops/sec — higher is better. "—" = type not supported by the library.

What the numbers tell us:

Primitives — All AOT approaches converge around ~10.5M ops/sec. This is the V8 ceiling for simple type checks. No meaningful difference between Zod AOT, Typia, and AJV.

Objects — Typia leads (1.3x over Zod AOT on medium, 1.2x on large). But the gap narrows as objects grow — the Fast Path's single boolean chain scales well. AJV collapses on large objects (9x slower than Typia at 100 items). Zod v4 is 3-54x slower than both.

Invalid inputs — AJV dominates the error path (4.7M ops/s) with minimal error construction. Zod v4 is slowest at 63K due to rich structured errors. In practice, most production inputs are valid — the Fast Path handles those.

Collections (Set/Map) — Zod AOT's exclusive territory. Typia doesn't validate Set or Map contents. AJV doesn't support JS-native types. Zod AOT is 16-22x faster than Zod v4 here.

Recursive — Typia leads 1.9x over Zod AOT on deep trees. Zod AOT currently uses z.lazy() fallback for recursive references — improving this is on the roadmap.

Partial fallback — Schemas with .transform() can't be fully AOT-compiled, but Zod AOT compiles everything it can and delegates the rest to Zod. Even partial compilation delivers 2.6-8x over Zod v4.

The Scoreboard

Category	Winner	Runner-up
Primitives	Tie (all AOT ≈ 10.5M)	—
Objects (valid)	Typia	Zod AOT (within 1.2x)
Objects (invalid)	AJV	Typia
Collections (Set/Map)	Zod AOT	(only competitor)
Discriminated unions	Tie (Typia ≈ Zod AOT)	—
Recursive	Typia	Zod AOT (1.9x gap)
Partial compilation	Zod AOT	(only competitor)

Zod AOT sits in a unique position: near-Typia performance with full Zod API compatibility. You don't need type-level tags, a different schema DSL, or JSON Schema. You keep z.object(), z.email(), .transform(), .refine() — and the build plugin handles the rest.

The `check` Command: Know Your Coverage

Not sure what percentage of your schemas will be compiled? Run check:

npx zod-aot check src/schemas.ts

validateUser — 100% compiled (8/8 nodes) | Fast Path: eligible
  └─ ✓ object
     ├─ ✓ string .name
     ├─ ✓ string .email
     ├─ ✓ number .age
     ├─ ✓ enum .role
     ├─ ✓ boolean .isActive
     ├─ ✓ array .tags
     │  └─ ✓ string .tags[]
     └─ ✓ nullable .bio
        └─ ✓ string .bio

validateOrder — 80% compiled (4/5 nodes) | Fast Path: ineligible
  └─ ✓ object
     ├─ ✓ string .orderId
     ├─ ✓ number .amount
     ├─ ✓ enum .currency
     └─ ✗ fallback .slug (transform)
           hint: Extract transform into a separate post-processing step

Each schema gets a tree view showing:

Which nodes are fully compiled (✓) vs falling back to Zod (✗)
Compilation coverage percentage
Fast Path eligibility
Actionable hints for improving coverage

CI Integration

# Fail if compilation coverage drops below 80%
npx zod-aot check src/schemas/ --fail-under 80 --json

The --json flag outputs structured data for CI pipelines:

{
  "exportName": "validateOrder",
  "coverage": { "total": 5, "compilable": 4, "percent": 80 },
  "fastPath": { "eligible": false, "blocker": "fallback (transform)" },
  "fallbacks": [{
    "reason": "transform",
    "path": ".slug",
    "hint": "Extract transform into a separate post-processing step"
  }]
}

Framework Integration

autoDiscover works at the build layer — framework code doesn't know or care:

tRPC: Schemas auto-compiled, router unchanged.

// router.ts — no changes needed
const appRouter = router({
  createUser: publicProcedure
    .input(CreateUserSchema)  // ← this is now AOT-compiled
    .mutation(({ input }) => db.users.create(input)),
});

Hono: Middleware validation auto-optimized.

app.post("/users", zValidator("json", CreateUserSchema), (c) => {
  // CreateUserSchema is AOT-compiled at build time
  const data = c.req.valid("json");
});

React Hook Form: Resolver schemas auto-compiled.

const { register } = useForm({
  resolver: zodResolver(CreateUserSchema), // AOT-compiled
});

The Object.create() wrapper ensures that framework code reading .shape, .keyof(), or other Zod metadata still works — the compiled schema inherits from the original.

What I Learned from the Competition

Typia is the performance king for objects and recursive structures. Its compile-time TypeScript transformer generates monolithic validation functions with zero runtime overhead. But:

It requires type-level tags (tags.MinLength<3>) instead of method chaining — a different mental model
It doesn't validate Set or Map contents
No bigint support
No .transform() or .refine() — it's a validator, not a parser

AJV has the best error-path performance and the broadest ecosystem (JSON Schema is a standard). But:

JSON Schema doesn't support JavaScript-native types (Set, Map)
Verbose schema definitions — no chaining, no composition
No transforms or pipes — declarative validation only

Zod AOT fills the gap: Zod's composable API, near-Typia performance, full JavaScript type support, and partial compilation for schemas that mix validation with transformation.

Get Started

npm install zod-aot zod@^4

// vite.config.ts — that's the entire setup
import zodAot from "zod-aot/vite";

export default defineConfig({
  plugins: [zodAot({ autoDiscover: true })],
});

Your existing Zod schemas are now AOT-compiled. No code changes.

Also works with webpack, esbuild, Rollup, Rolldown, rspack, and Bun via unplugin.

GitHub: github.com/wakita181009/zod-aot
npm: zod-aot

Methodology

All benchmarks use safeParse() on pre-created schema instances, measured with Vitest bench (1M+ iterations, with warmup). Numbers are steady-state throughput — JIT is already compiled after the first call. Typia uses createValidate<T>(). AJV uses ajv.compile(schema). Invalid-input benchmarks use all-fields-invalid payloads to stress the error path.

Environment: Node.js v22, Apple M-series
Libraries: Zod v3.24, Zod v4, Zod AOT 0.14, Typia 12, AJV 8
Raw data: benchmarks/ in the zod-aot repo

Why Is Zod v4 Fast — and Where Is Its Ceiling?

Tetsuya Wakita — Thu, 19 Mar 2026 20:48:52 +0000

Zod v4 is faster than v3. But almost nobody knows why. It's not just a cleaner codebase or smaller bundle — Zod v4 has a JIT-like code generator that builds specialized validation functions at runtime using new Function(). It's hidden inside a class called $ZodObjectJIT, and unless you read the source, you'd never know it was there.

I read the internals to understand how v4's performance works, benchmarked every schema type, and used what I learned to build an AOT compiler that extends the same idea to build time. Here's everything I found.

What the benchmarks show:

v4's JIT targets object schemas — delivering 1.3-4.5x over v3 for objects and recursive structures
For other types (primitives with checks, collections), v4 traded raw throughput for a richer architecture (better errors, async support, modular checks)
AOT compilation extends the JIT principle to all schema types: 3-60x faster than v4

Zod v3: The Interpreter Model

Every time you call .parse() in Zod v3, the same thing happens: the entire schema tree gets walked at runtime. Each node dispatches based on type — string, number, object, array — and the traversal recurses until it hits the leaves.

// Simplified: what Zod v3 does on every .parse() call
function parse(schema, data) {
  switch (schema._def.typeName) {
    case "ZodString":  return parseString(schema._def, data);
    case "ZodNumber":  return parseNumber(schema._def, data);
    case "ZodObject":  return parseObject(schema._def, data); // recurses into each property
    case "ZodArray":   return parseArray(schema._def, data);  // recurses into each element
    // ...
  }
}

This is an interpreter. The schema is a data structure, and Zod walks it every time. For a simple z.string(), the overhead is negligible. For a nested object with 100 items, you're traversing hundreds of nodes on every single call.

The schema never changes. But Zod re-discovers its structure every time.

Zod v4: A New Architecture

Zod v4 introduced a fundamentally different internal architecture. Every schema now has a _zod object with two key functions:

_zod.parse: The type-specific validation logic (type check, structural validation)
_zod.run: Orchestrates parse + runs checks (.min(), .max(), .email(), etc.)

.parse(data) → _zod.run({ value, issues }, ctx) → _zod.parse(payload, ctx) → runChecks()

When a schema has no checks, Zod v4 optimizes by making _zod.run point directly to _zod.parse — skipping the check orchestration entirely.

The new architecture also brought real improvements beyond performance: structured error objects with full path tracking, first-class async support, modular check pipelines, and globalConfig for runtime tuning. These features have a small cost in the hot path — a deliberate trade-off that makes Zod v4 far more capable than v3.

But the most interesting optimization is hidden deeper.

The Hidden JIT: `$ZodObjectJIT`

The Doc Class: Runtime Code Generation

Deep inside Zod v4's source (schemas.js), there's a class called Doc. It doesn't validate data. It generates JavaScript code as strings and compiles them into functions using new Function():

// From zod/v4/core/doc.js — a runtime code generator
export class Doc {
  constructor(args) {
    this.content = [];
    this.args = args;
  }

  write(code) {
    // Accumulates lines of JavaScript source code
    this.content.push(code);
  }

  compile() {
    const F = Function;
    // new Function("arg1", "arg2", "...code...") → executable function
    return new F(...this.args, this.content.join("\n"));
  }
}

This is runtime code generation: it builds JavaScript source as strings and compiles it with new Function() for reuse on later parses. Strictly speaking, this isn't a full optimizing JIT like V8 or HotSpot — but it plays a similar role: specialize once, reuse many times.

How $ZodObjectJIT Works

$ZodObjectJIT wraps the standard $ZodObject parser. On the first .parse() call, it generates a specialized validation function for that specific object shape:

// From zod/v4/core/schemas.js — simplified
export const $ZodObjectJIT = core.$constructor("$ZodObjectJIT", (inst, def) => {
  $ZodObject.init(inst, def);
  const superParse = inst._zod.parse;  // Save the original

  const generateFastpass = (shape) => {
    const doc = new Doc(["shape", "payload", "ctx"]);
    doc.write(`const input = payload.value;`);
    doc.write(`const newResult = {};`);

    for (const key of Object.keys(shape)) {
      // Generate inline validation code for each property
      doc.write(`const r_${key} = shape["${key}"]._zod.run(
        { value: input["${key}"], issues: [] }, ctx);`);
      doc.write(`if (r_${key}.issues.length) { /* merge issues */ }`);
      doc.write(`newResult["${key}"] = r_${key}.value;`);
    }

    doc.write(`payload.value = newResult;`);
    doc.write(`return payload;`);
    return doc.compile();  // → new Function(...)
  };

  let fastpass;  // Cached compiled function

  inst._zod.parse = (payload, ctx) => {
    if (jit && fastEnabled && ctx?.async === false && ctx.jitless !== true) {
      if (!fastpass) fastpass = generateFastpass(def.shape);  // First call only
      return fastpass(shape, payload, ctx);
    }
    return superParse(payload, ctx);  // Fallback
  };
});

On the first parse call:

Iterates over the object shape
Generates JavaScript code that validates each property inline
Compiles it with new Function()
Caches the compiled function in fastpass

Every subsequent call skips the code generation and executes the cached function directly.

Environment Detection

Before the JIT path kicks in, Zod v4 checks whether the runtime allows new Function():

const jit = !core.globalConfig.jitless;
const fastEnabled = jit && allowsEval.value;

// From zod/v4/core/util.js
export const allowsEval = cached(() => {
  if (typeof navigator !== "undefined" &&
      navigator?.userAgent?.includes("Cloudflare")) {
    return false;  // Cloudflare Workers blocks eval
  }
  try {
    const F = Function;
    new F("");
    return true;
  } catch (_) {
    return false;  // CSP-restricted environments
  }
});

If new Function() is blocked — Cloudflare Workers, strict CSP headers, or jitless mode — Zod v4 gracefully falls back to the standard parse path. The validation result is identical; only the execution speed differs.

What JIT Covers (and What It Doesn't)

$ZodObjectJIT targets the most impactful case: object schemas. Objects are by far the most common complex schema in real applications — every API request body, every form, every database row.

But it's specifically scoped to objects:

z.string().min(1).email() — uses the standard check pipeline
z.number().int().positive() — uses the standard check pipeline
z.array(z.string()) — standard parse (though nested objects inside get JIT)
z.set(), z.map(), z.record() — standard parse
z.discriminatedUnion() — has its own separate optimization (a Map lookup table)

The generated code also still calls shape[key]._zod.run() for each property — it delegates to child schemas at runtime. The JIT eliminates the object-level dispatch overhead, but the per-property traversal remains.

Benchmarks: Where JIT Helps

I benchmarked Zod v3, Zod v4, and Zod AOT across every schema type. The results show exactly where the JIT makes a difference.

Objects and Recursive Structures: JIT Territory

Schema	Zod v3	Zod v4	Zod AOT	v3 → v4	v4 → AOT
Medium object (valid)	1.3M ops/s	1.6M ops/s	5.5M ops/s	1.31x faster	3.31x
Large object (10 items)	81K	113K	4.0M	1.39x faster	35.8x
Large object (100 items)	8.9K	12.0K	725K	1.35x faster	60.6x
Recursive tree (7 nodes)	420K	1.5M	6.4M	3.69x faster	4.15x
Recursive tree (121 nodes)	23K	105K	739K	4.49x faster	7.05x
Discriminated union (3)	2.4M	2.9M	10.1M	1.18x faster	3.54x

This is where v4 shines. For valid object inputs, the JIT fast path delivers 1.3-1.4x over v3. For recursive structures — where each level hits an object schema — the JIT compounds: 3.7-4.5x over v3.

Primitives: Architecture Trade-off Visible

Schema	Zod v3	Zod v4	Zod AOT	v3 → v4	v4 → AOT
Simple string	8.5M	9.6M	11.0M	1.13x faster	1.15x
String min/max	8.0M	5.8M	10.3M	0.73x	1.78x
Number int+pos	7.9M	5.7M	11.0M	0.73x	1.93x
Enum	7.3M	9.2M	10.4M	1.26x faster	1.13x
Bigint min/max	7.5M	5.4M	10.2M	0.72x	1.89x

For primitives with checks, v4's modular check pipeline (separate check objects, runChecks orchestration) adds overhead compared to v3's simpler inline approach. This is the cost of v4's new features — structured errors, conditional checks via when, and the ability to compose check pipelines. The JIT doesn't apply here since these aren't object schemas.

At ~6M ops/s, this is still extremely fast for any real application. The difference only shows up in micro-benchmarks.

Collections: No JIT (Yet)

Schema	Zod v3	Zod v4	Zod AOT	v3 → v4	v4 → AOT
Tuple	3.9M	4.4M	10.4M	1.12x faster	2.38x
Record (5 keys)	2.3M	1.6M	5.4M	0.69x	3.51x
Set (5 items)	2.7M	1.5M	9.8M	0.58x	6.35x
Set (20 items)	964K	464K	7.7M	0.48x	16.5x
Map (5 entries)	1.5M	954K	8.5M	0.62x	8.96x
Map (20 entries)	489K	239K	5.2M	0.49x	21.6x

Collections (Set, Map, Record) go through the new internal pipeline without JIT assistance. The throughput difference vs v3 reflects the richer v4 architecture, not a regression — v4 does more work per element (payload construction, issue path tracking, async readiness).

This is where AOT makes the biggest relative difference: 16-22x for 20-item collections, since AOT can eliminate the per-element overhead entirely.

Invalid Inputs: Error Construction Dominates

Schema	Zod v3	Zod v4	Zod AOT	v3 → v4	v4 → AOT
Medium object (all-fields-invalid)	381K	62K	476K	0.16x	7.64x

The most dramatic difference is on invalid inputs. This benchmark uses an all-fields-invalid payload to stress-test the error path. v4's error construction is significantly richer than v3's — detailed issue objects with codes, paths, metadata, and i18n support. That richness has a cost in throughput benchmarks.

In real workloads where most inputs are valid, this gap is much smaller. And when inputs are invalid, v4's structured errors make debugging far easier — that's a worthwhile trade-off.

Real-World Schemas

Schema	Zod v3	Zod v4	Zod AOT	v3 → v4	v4 → AOT
Event log (mixed types)	265K	472K	4.5M	1.78x faster	9.55x
Partial fallback (object)	797K	1.4M	3.4M	1.77x faster	2.43x
Partial fallback (50 arr)	18K	29K	252K	1.61x faster	8.69x

Real-world schemas mix objects, discriminated unions, tuples, and records. Here v4's JIT contributes meaningfully: 1.6-1.8x over v3. AOT extends this further: 2.4-9.6x over v4.

The "partial fallback" rows show schemas with .transform() — fields that can't be AOT-compiled. zod-aot falls back to Zod for those fields while compiling the rest. Even partial compilation delivers 2.4-8.7x over v4.

From JIT to AOT: Taking It Further

v4's JIT gave me the idea for zod-aot. The insight is the same: schemas are static, so validation can be specialized ahead of time. The JIT does this at runtime for objects. AOT does it at build time for everything.

Here's the same schema, side by side:

const UserSchema = z.object({
  name: z.string().min(1).max(100),
  email: z.string().email(),
  age: z.number().int().positive(),
});

Zod v4 JIT output (generated at runtime via new Function):

const input = payload.value;
const newResult = {};

// Each property still delegates to the child schema's _zod.run()
const r_name = shape["name"]._zod.run({ value: input["name"], issues: [] }, ctx);
if (r_name.issues.length) {
  payload.issues = payload.issues.concat(
    r_name.issues.map(iss => ({ ...iss, path: ["name", ...(iss.path || [])] }))
  );
}
newResult["name"] = r_name.value;

const r_email = shape["email"]._zod.run({ value: input["email"], issues: [] }, ctx);
// ... same pattern for each property

payload.value = newResult;
return payload;

The JIT eliminates the object-level dispatch loop. But each property still calls _zod.run() → _zod.parse() → runChecks(). The per-property overhead remains.

Zod AOT output (generated at build time):

function safeParse_User(input) {
  var __issues = [];
  if (typeof input !== "object" || input === null || Array.isArray(input)) {
    __issues.push({ code: "invalid_type", expected: "object", path: [] });
  } else {
    // Fully inlined — no function calls, no delegation
    if (typeof input["name"] !== "string") {
      __issues.push({ code: "invalid_type", expected: "string", path: ["name"] });
    } else if (input["name"].length < 1) {
      __issues.push({ code: "too_small", minimum: 1, path: ["name"] });
    } else if (input["name"].length > 100) {
      __issues.push({ code: "too_big", maximum: 100, path: ["name"] });
    }

    if (typeof input["email"] !== "string") {
      __issues.push({ code: "invalid_type", expected: "string", path: ["email"] });
    } else if (!__re_email.test(input["email"])) {
      __issues.push({ code: "invalid_format", format: "email", path: ["email"] });
    }

    if (typeof input["age"] !== "number" || Number.isNaN(input["age"])) {
      __issues.push({ code: "invalid_type", expected: "number", path: ["age"] });
    } else if (!Number.isSafeInteger(input["age"])) {
      __issues.push({ code: "invalid_type", expected: "int", path: ["age"] });
    } else if (input["age"] < 0) {
      __issues.push({ code: "too_small", minimum: 0, path: ["age"] });
    }
  }
  if (__issues.length > 0) return { success: false, error: { issues: __issues } };
  return { success: true, data: input };
}

No schema objects. No _zod.run() calls. No check pipeline. Flat, inlined validation with zero dispatch overhead.

	Zod v4 JIT	Zod AOT
When compiled	First `.parse()` call	Build time
Scope	Object-level dispatch only	Full schema tree, all types
Per-property cost	`_zod.run()` + checks pipeline	Inlined type checks
Environment	Requires `new Function()`	Works everywhere (no eval)
Cold start	First parse pays compilation cost	Zero — function exists at startup

Where AOT Matters Most

In a long-running Node.js server, v4's JIT warms up on the first request and stays fast. AOT's advantage is smaller here.

But in environments where JIT can't help:

Cloudflare Workers / strict CSP: new Function() is blocked. Zod v4 falls back to the standard parse path. AOT works everywhere — no eval needed.
Serverless with frequent cold starts: Every new Lambda/Edge instance pays the JIT compilation cost. AOT has zero cold-start penalty.
Collection-heavy validation: Set, Map, and Record schemas don't benefit from JIT. AOT delivers 16-22x for these.
High-throughput APIs: When you're validating complex nested objects at >10K requests/sec, AOT's 35-60x improvement over v4 is the difference between needing 1 server and needing 60.

Trade-offs

AOT isn't free:

.transform(), .refine(), .superRefine() contain opaque functions that can't be compiled ahead of time. zod-aot falls back to Zod for these fields (partial compilation still helps, but the benefit is proportional to how much of your schema is compilable).
Build integration required — a bundler plugin (Vite, webpack, esbuild) or CLI step. It's 4 lines of config, but not zero.
Generated code adds to bundle size — for most schemas this is smaller than Zod itself, but it's a factor.
Static schemas only — if you construct schemas dynamically at runtime, AOT can't help.

When to Use What

Scenario	Recommendation	Why
Prototyping / small schemas	Zod v4 as-is	JIT is invisible, zero setup
Long-running API server	Zod v4 is likely sufficient	JIT warms up on first request
Cloudflare Workers / strict CSP	Zod AOT	JIT is disabled — AOT works everywhere
Serverless with frequent cold starts	Zod AOT	Zero cold-start compilation cost
Complex nested objects at high throughput	Zod AOT	35-60x over v4
Set/Map/Record heavy validation	Zod AOT	JIT doesn't cover these, AOT does
Schemas dominated by `.transform()`	Zod v4	AOT can't compile opaque functions

Try Zod AOT

npm install zod-aot zod@^4

import { z } from "zod";
import { compile } from "zod-aot";

// Wrap with compile() — same API, AOT-compiled in production
const UserSchema = compile(
  z.object({
    name: z.string().min(1).max(100),
    email: z.string().email(),
    age: z.number().int().positive(),
  })
);

// .parse(), .safeParse(), .is() — all work as expected
const user = UserSchema.parse(data);

Add the Vite plugin (4 lines):

// vite.config.ts
import zodAot from "zod-aot/vite";

export default defineConfig({
  plugins: [zodAot()],
});

In development, compile() passes through to Zod. In production builds, the plugin replaces it with generated validation code. Zero code changes to your schemas.

GitHub: github.com/wakita181009/zod-aot
npm: zod-aot

Methodology

All benchmarks use safeParse() on pre-created schema instances, measured with Vitest bench (1M+ iterations per case, with warmup). Zod v4 object benchmarks report steady-state throughput — the JIT fast path is already compiled after the first call. Invalid-input benchmarks use all-fields-invalid payloads to stress the error path. Async paths are excluded.

Environment: Node.js v22, Apple M-series
Libraries: Zod v3.24, Zod v4.3, Zod AOT latest
Raw data: benchmarks/ in the zod-aot repo

Build Google Apps Script with Any Bundler: Vite, Rollup, esbuild, webpack, and Bun

Tetsuya Wakita — Sat, 14 Mar 2026 16:37:45 +0000

Google Apps Script projects shouldn’t be tied to one bundler.

So I rebuilt my Vite-only plugin into a universal plugin for Vite, Rollup, webpack, esbuild, and Bun — and added a scaffolding CLI on top.

The problem with modern bundlers in Google Apps Script

If you’ve ever deployed a GAS project only to find that doGet was silently removed by tree-shaking — or that export keywords broke the Apps Script runtime — you know the pain.

Google Apps Script has a slightly awkward relationship with modern JavaScript tooling.

Bundlers like Vite, Rollup, webpack, and esbuild are great at optimizing modules. But GAS expects certain functions — doGet, doPost, onOpen, installable triggers, menu handlers — to exist in the global scope with stable names.

That creates a few recurring problems:

export is convenient in source code, but GAS doesn’t want it in the final bundle
tree-shaking can remove entry points that are only referenced by the Apps Script runtime
appsscript.json has to be copied into the output alongside the bundle

Here’s what the plugin actually does to your output:

// Your source:
export function doGet(e) {
  return HtmlService.createHtmlOutput("Hello");
}

// Without plugin — bundler may wrap, rename, or tree-shake:
// doGet is gone or unreachable

// With @gas-plugin/unplugin — export stripped, global preserved:
function doGet(e) {
  return HtmlService.createHtmlOutput("Hello");
}

In my previous post, I introduced gas-vite-plugin, a small Vite plugin that handled exactly that.

It worked well — but only for Vite.

If your team used Rollup, webpack, or esbuild, you had to solve the same problem a different way.

So I rebuilt it as a universal plugin.

What changed

The project is now @gas-plugin — a monorepo with two packages:

Package	What it does
`@gas-plugin/unplugin`	Universal bundler plugin for Vite, Rollup, webpack, esbuild, and Bun
`@gas-plugin/cli`	Scaffolding CLI for new GAS projects

The original gas-vite-plugin still exists as a deprecated compatibility package, but the main path going forward is @gas-plugin/unplugin.

Why I rebuilt it with unplugin

I could have maintained separate plugins for each bundler.

That would have meant duplicating the same logic across multiple packages: transform exported entry points, preserve GAS globals, and copy the manifest into the output directory.

Instead, I used unplugin, which lets you implement the plugin once and expose adapters for multiple bundlers. For this kind of narrowly focused build-time behavior, that’s a much better fit than maintaining five independent implementations.

The result is simple:

same plugin behavior
same options
different import path per bundler

That means the GAS-specific parts stay consistent even if your build tool changes.

`@gas-plugin/unplugin`: one plugin, any bundler

Here’s the same plugin working across different bundlers.

Vite

import gasPlugin from "@gas-plugin/unplugin/vite";
import { defineConfig } from "vite";

export default defineConfig({
  plugins: [gasPlugin()],
  build: {
    lib: {
      entry: "src/main.ts",
      formats: ["es"],
      fileName: () => "Code.js",
    },
  },
});

Rollup

import gasPlugin from "@gas-plugin/unplugin/rollup";

export default {
  input: "src/main.ts",
  output: { dir: "dist", format: "es" },
  plugins: [gasPlugin()],
};

esbuild

import gasPlugin from "@gas-plugin/unplugin/esbuild";
import { build } from "esbuild";

await build({
  entryPoints: ["src/main.ts"],
  outdir: "dist",
  bundle: true,
  format: "esm",
  plugins: [gasPlugin()],
});

webpack

import gasPlugin from "@gas-plugin/unplugin/webpack";

export default {
  entry: "./src/main.ts",
  output: { path: new URL("./dist", import.meta.url).pathname },
  plugins: [gasPlugin()],
};

Bun

import gasPlugin from "@gas-plugin/unplugin/bun";

await Bun.build({
  entrypoints: ["src/main.ts"],
  outdir: "dist",
  plugins: [gasPlugin()],
});

The options are the same everywhere:

gasPlugin({
  manifest: "appsscript.json",
  include: ["src/**/*.html"],
  globals: ["processData"],
  autoGlobals: true,
});

How `autoGlobals` and `globals` work

By default, bundlers may tree-shake or rename your GAS entry points like doGet or onOpen — because nothing in your code imports them.

autoGlobals: true scans your source for exported functions and automatically exposes them as global declarations in the output. This is the simplest way to make sure your GAS entry points survive the build.
globals: ["processData"] lets you manually specify additional functions that should be preserved as globals — useful for installable triggers or menu callbacks that aren’t exported from the entry point.

You can use both together: autoGlobals handles the common case, and globals covers edge cases.

That consistency is the main goal: you shouldn’t have to rethink your GAS build setup just because you prefer one bundler over another.

`@gas-plugin/cli`: scaffold a project in seconds

I also added a CLI so you can start a new project without wiring everything manually.

npx @gas-plugin/cli create

You’ll get interactive prompts for:

project name
template
bundler
optional clasp configuration
optional Script ID

Example:

◆  Project name
│  my-gas-app
│
◆  Template
│  ● basic — Spreadsheet automation (onOpen, triggers)
│  ○ webapp — Web app (doGet/doPost + HTML client)
│
◆  Bundler
│  ● vite
│  ○ rollup
│  ○ esbuild
│  ○ webpack
│  ○ bun
│
◆  Include clasp configuration?
│  Yes
│
◆  Script ID (optional)
│  1BxTjDm...

And if you prefer automation-friendly setup, you can skip prompts entirely:

npx @gas-plugin/cli create my-gas-app \
  --template webapp \
  --bundler vite \
  --clasp \
  --script-id YOUR_SCRIPT_ID

The generated project is intentionally minimal:

my-gas-app/
├── src/
│   ├── index.ts
│   ├── utils.ts
│   └── client.html       # webapp template only
├── package.json
├── appsscript.json
├── tsconfig.json
├── biome.json
├── vite.config.ts        # or rollup/esbuild/webpack config
├── .clasp.json           # when --clasp
├── .claspignore
└── .gitignore

Then:

npm run build
npx clasp push

That gives you the basics you actually need, without forcing a larger opinionated toolchain on every project.

Why this exists when `google/aside` already exists

Google already provides @google/aside, and it’s a legitimate option.

So this project is not trying to replace it outright.

The difference is scope.

`google/aside` is a batteries-included starter

It gives you a more opinionated setup out of the box.

`@gas-plugin` is a smaller, composable alternative

It focuses on two things:

making bundled output work cleanly for GAS
letting you choose your own bundler and surrounding toolchain

Here’s the practical difference:

	`google/aside`	`@gas-plugin`
Bundler choice	Primarily Rollup-based setup	Vite, Rollup, esbuild, webpack, Bun
`export` handling	You work within the template’s conventions	`export` is stripped at build time for GAS output
Tree-shaking protection	Side-effect import pattern	`autoGlobals` can preserve exported entry points automatically
Scaffolding style	More batteries included	Minimal scaffold, bring your own tools
Templates	Opinionated starter	`basic` and `webapp`

So the real distinction is:

choose google/aside if you want a fuller default setup
choose @gas-plugin if you want a lighter, bundler-agnostic foundation

Migration from `gas-vite-plugin`

If you’re already using the old package, migration is intentionally small:

- import gasPlugin from "gas-vite-plugin";
+ import gasPlugin from "@gas-plugin/unplugin/vite";

npm uninstall gas-vite-plugin
npm install -D @gas-plugin/unplugin

Same idea, same behavior — just no longer tied to Vite alone.

Why I think this matters

GAS is still incredibly useful for internal tools, automations, lightweight web apps, and spreadsheet-driven workflows.

But the tooling ecosystem has often pushed developers into one of two extremes:

stay close to vanilla Apps Script and give up modern build ergonomics
adopt a very specific template and toolchain

I wanted something in between:

modern TypeScript workflow
support for the bundler you already use
minimal GAS-specific friction
no unnecessary lock-in

That’s what @gas-plugin is trying to be.

If you’ve tried it, I’d love to hear which bundler you’re using and whether anything felt off. Issues and PRs are welcome on GitHub.

clasp 3 Dropped TypeScript — Here's a Vite Plugin for Google Apps Script

Tetsuya Wakita — Fri, 13 Mar 2026 18:10:42 +0000

Write standard TypeScript with export. Build with Vite. Push with clasp.

Why I built this

clasp 3 removed built-in TypeScript support. The recommendation is to use an external bundler — Google provides google/aside for Rollup.

I wanted Vite. The existing Vite plugins for GAS were either outdated (Rhino-era transforms like arrow function conversion) or didn't support web apps. So I built gas-vite-plugin — a minimal Vite plugin that only does what Vite can't do natively for GAS.

Install

npm install -D gas-vite-plugin

Basic usage

// vite.config.ts
import gasPlugin from "gas-vite-plugin";
import { defineConfig } from "vite";

export default defineConfig({
  plugins: [gasPlugin()],
  build: {
    lib: {
      entry: "src/main.ts",
      formats: ["es"],
      fileName: () => "Code.js",
    },
  },
});

// src/main.ts
export function onOpen() {
  SpreadsheetApp.getUi()
    .createMenu("My Menu")
    .addItem("Run", "myFunction")
    .addToUi();
}

export function myFunction() {
  SpreadsheetApp.getActiveSpreadsheet().toast("Hello from Vite!");
}

npx vite build   # → dist/Code.js (exports stripped) + dist/appsscript.json
npx clasp push

The plugin strips export keywords, copies appsscript.json, and sets GAS-safe defaults (no minification, no code splitting). That's the zero-config experience.

Features

Feature	Description
Export stripping	Removes `export` so functions are callable by GAS
Manifest copy	Copies `appsscript.json` to dist automatically
File include	Copies HTML/CSS flat to dist for web apps
Tree-shake protection	Keeps functions that GAS calls by string name
GAS-safe defaults	No minification, no code splitting, V8 assumed

Options

gasPlugin({
  manifest: "src/appsscript.json", // default
  include: ["src/**/*.html"],       // copy files flat to dist
  globals: ["processData"],         // protect from tree-shaking
  autoGlobals: true,                // auto-protect exports (default)
});

`globals` — when tree-shaking removes too much

GAS calls functions by string name (menu handlers, triggers, google.script.run). If a function isn't exported and isn't referenced in code, Vite removes it.

export function onOpen() {
  SpreadsheetApp.getUi()
    .createMenu("Tools")
    .addItem("Process", "processData") // string reference — Vite can't see this
    .addToUi();
}

function processData() { /* removed by tree-shaking */ }

Fix: add it to globals.

gasPlugin({ globals: ["processData"] })

Exported functions are protected automatically (autoGlobals: true by default).

Web app support

GAS web apps need HTML files and backend functions callable via google.script.run. Use include for files and globals for the backend functions:

// vite.config.ts
gasPlugin({
  include: ["src/**/*.html"],
  globals: ["getData", "saveData"],
})

// src/main.ts
export function doGet() {
  return HtmlService.createHtmlOutputFromFile("index").setTitle("My App");
}

function getData() {
  return SpreadsheetApp.getActiveSpreadsheet()
    .getActiveSheet().getDataRange().getValues();
}

<!-- src/index.html — copied flat to dist -->
<script>
  google.script.run.withSuccessHandler(render).getData();
</script>

Output:

dist/
├── Code.js          # exports stripped
├── appsscript.json  # auto-copied
└── index.html       # flat-copied via include

Files are flattened — src/views/sidebar.html → dist/sidebar.html. GAS doesn't support subdirectories.

Recommended project layout

your-gas-project/
├── src/
│   ├── main.ts           # entry point
│   ├── utils.ts          # modules — import normally
│   ├── appsscript.json   # GAS manifest
│   └── index.html        # for web apps
├── dist/                  # → clasp push from here
├── vite.config.ts
├── .clasp.json            # rootDir: "dist"
└── package.json

I Made an LLM Add Features to Its Own Code — Classic Spring Boot vs Clean Architecture

Tetsuya Wakita — Mon, 09 Mar 2026 17:58:47 +0000

In Part 0, both implementations worked. In Part 1, the LLM modified its own code — and the results challenged my assumptions about both architectures.

Phase 1: feature addition

In Part 0, I had Claude Code generate two complete SaaS billing systems from scratch — one in classic Spring Boot, one in Clean Architecture with Arrow-kt. Both worked. Both had ~89% coverage. The structural differences were visible but untested.

Phase 1 tests what happens next. I gave the LLM three new feature specs and pointed it at the Phase 0 codebase:

Add-ons — flat-rate and per-seat billing types, attached to subscriptions with proration on mid-cycle changes
Seat management — per-seat pricing with minimum/maximum constraints, prorated charges on seat count changes
Credit notes — full and partial refunds, with two application methods (refund to payment method or account credit)

Same orchestrator agent. Same process. The only difference: this time, the LLM read existing code before writing new code.

I expected Clean to scale cleanly and Classic to degrade predictably. The actual results were messier — and more interesting.

Generation time: the gap disappeared

Phase	Classic	Clean	Ratio
Phase 0 (greenfield)	18m 15s	32m 2s	1.75x
Phase 1 (feature add)	28m 57s	29m 20s	1.01x

This is the most surprising number in the entire experiment.

In Phase 0, Clean took 1.75x longer — the orchestrator had to coordinate 6 agents across 5 modules with strict dependency ordering, generating 115 files from a detailed layer sketch. Classic's simpler pipeline finished in half the time.

In Phase 1, they're 23 seconds apart. The existing codebase became the context. The LLM didn't need the layer sketch to figure out where files go — it could read the project structure and follow the patterns already established. The upfront cost of Clean's architecture was paid in Phase 0. Phase 1 spent it.

Classic: the LLM learned from its own code

The most interesting finding

In Phase 0, the LLM created one SubscriptionService with 457 lines and 9 responsibilities. I expected Phase 1 to make it worse — to stuff add-on logic, seat management, and credit notes into the same class.

Instead, the LLM created three new services:

// classic/service/AddOnService.kt — 257 lines
@Service
class AddOnService(
    private val subscriptionRepository: SubscriptionRepository,
    private val addOnRepository: AddOnRepository,
    private val subscriptionAddOnRepository: SubscriptionAddOnRepository,
    private val invoiceRepository: InvoiceRepository,
    private val paymentGateway: PaymentGateway,
    private val clock: Clock,
)

// classic/service/SeatService.kt — 220 lines
@Service
class SeatService(
    private val subscriptionRepository: SubscriptionRepository,
    private val subscriptionAddOnRepository: SubscriptionAddOnRepository,
    private val invoiceRepository: InvoiceRepository,
    private val paymentGateway: PaymentGateway,
    private val clock: Clock,
)

// classic/service/CreditNoteService.kt — 128 lines
@Service
class CreditNoteService(...)

The LLM saw the existing 457-line service and chose not to add to it. It created separate services for separate domains. This is genuine adaptation — the Phase 0 code taught the LLM that this project uses one service per domain concept.

This matters. Nobody added a rule saying "create separate services." Nobody modified the .claude/ context. The LLM read the existing codebase and adapted its behavior. The implication is significant: good existing code can guide an LLM even without explicit architectural constraints. Classic's Phase 0 output, despite its flaws, was good enough to teach the LLM better decomposition in Phase 1.

What didn't improve

SubscriptionService still grew. Despite decomposition into new services, SubscriptionService went from 457 to 635 lines. The processRenewal() method absorbed per-seat pricing calculations, add-on charge aggregation, and account credit application:

// classic/service/SubscriptionService.kt — processRenewal() grew to include:
// - Per-seat plan charge calculation
// - Add-on charge iteration and line item generation
// - Account credit balance application
// - 9 original responsibilities + 3 new ones

The new services handle creation and modification of add-ons, seats, and credit notes. But renewal — the operation that touches everything — still lives in SubscriptionService. The LLM couldn't extract it because the method depends on repositories from all three new domains.

Proration logic is duplicated. The same day-ratio calculation appears in SeatService.updateSeatCount(), AddOnService.attachAddOn(), and SubscriptionService.processRenewal():

// This pattern appears in 3 different services:
val daysRemaining = ChronoUnit.DAYS.between(now, currentPeriodEnd)
val totalDays = ChronoUnit.DAYS.between(currentPeriodStart, currentPeriodEnd)
val prorationFactor = BigDecimal(daysRemaining).divide(BigDecimal(totalDays), 10, RoundingMode.HALF_UP)
val proratedAmount = amount.multiply(prorationFactor).setScale(2, RoundingMode.HALF_UP)

Each service calculates proration independently. The LLM generated each method in isolation and didn't refactor common logic afterward. (Note: as we'll see, clean has the same problem — the LLM duplicates cross-cutting calculations regardless of architecture.)

Exception explosion. Phase 0 had 8 exception types. Phase 1 added 13 more:

class AddOnNotFoundException(id: Long) : ServiceException(...)
class DuplicateAddOnException(addonId: Long) : ServiceException(...)
class PerSeatAddOnOnNonPerSeatPlanException() : ServiceException(...)
class SeatCountOutOfRangeException(message: String) : ServiceException(...)
class SameSeatCountException(current: Int) : ServiceException(...)
// ... 8 more

Each exception is a flat class extending ServiceException. There's no hierarchy grouping add-on errors separate from seat errors. When a controller catches ServiceException, it handles all 21 types through the same GlobalExceptionHandler — the HTTP status code is embedded in each exception, which works, but provides no compile-time guarantee that all cases are handled.

Clean: use cases added like Lego blocks

The structure held

Phase 1 added exactly 4 new use cases:

// Each use case: single responsibility, explicit error type, Either return
class AttachAddOnUseCaseImpl(...) : AttachAddOnUseCase {
    override fun execute(command: AttachAddOnCommand): Either<AttachAddOnError, SubscriptionAddOn>
}

class DetachAddOnUseCaseImpl(...) : DetachAddOnUseCase {
    override fun execute(subscriptionId: Long, addOnId: Long): Either<DetachAddOnError, Unit>
}

class UpdateSeatCountUseCaseImpl(...) : UpdateSeatCountUseCase {
    override fun execute(command: UpdateSeatCountCommand): Either<UpdateSeatCountError, Subscription>
}

class IssueCreditNoteUseCaseImpl(...) : IssueCreditNoteUseCase {
    override fun execute(command: IssueCreditNoteCommand): Either<IssueCreditNoteError, CreditNote>
}

Each use case has its own sealed error type. AttachAddOnError has 12 variants. UpdateSeatCountError has 11 variants. The compiler enforces exhaustive handling at every call site.

sealed interface AttachAddOnError : ApplicationError {
    data class InvalidInput(val field: String, val reason: String) : AttachAddOnError
    data object SubscriptionNotFound : AttachAddOnError
    data object NotActive : AttachAddOnError
    data object AddOnNotFound : AttachAddOnError
    data object CurrencyMismatch : AttachAddOnError
    data object TierIncompatible : AttachAddOnError
    data object PerSeatOnNonPerSeatPlan : AttachAddOnError
    data object DuplicateAddOn : AttachAddOnError
    data object AddOnLimitReached : AttachAddOnError
    data class PaymentFailed(val reason: String) : AttachAddOnError
    data class Domain(val error: DomainError) : AttachAddOnError
    data class Internal(val cause: String) : AttachAddOnError
}

New domain models (AddOn, SubscriptionAddOn, CreditNote) follow the same value object pattern. New ports (AddOnQueryPort, SubscriptionAddOnCommandQueryPort, CreditNoteCommandQueryPort) maintain the dependency direction. New infrastructure adapters implement the ports. The existing code didn't need to change its structure to accommodate new features — new features slotted into the existing structure.

Where clean showed cracks

The backward-compatibility hack. ProcessRenewalUseCase needed to incorporate add-on charges into renewal invoices. The LLM's solution:

class ProcessRenewalUseCaseImpl(
    // ... existing dependencies ...
    private val subscriptionAddOnCommandQueryPort: SubscriptionAddOnCommandQueryPort? = null,
    private val addOnQueryPort: AddOnQueryPort? = null,
) : ProcessRenewalUseCase {
    override fun execute(subscriptionId: Long): Either<ProcessRenewalError, Subscription> = either {
        // ...
        val addOnCharges = subscriptionAddOnCommandQueryPort?.let { port ->
            // calculate add-on charges only if port is available
        } ?: emptyList()
        // ...
    }
}

Optional dependencies with ?.let null checks. This is a code smell in Clean Architecture — a use case should declare all its dependencies explicitly. The LLM chose backward compatibility over correctness, probably because the existing tests for ProcessRenewalUseCase don't provide add-on ports. Breaking those tests would mean rewriting them, which the LLM avoided.

Proration duplication — the same problem as classic. Phase 0's PlanChangeUseCase delegates to a ProrationDomainService in the domain layer. But the Phase 1 use cases (AttachAddOnUseCase, DetachAddOnUseCase, UpdateSeatCountUseCase) all calculate proration inline — the same totalDays / daysRemaining pattern, duplicated across four use cases. The LLM didn't reuse the existing domain service. Use case isolation, which prevents god services, also prevents the LLM from seeing shared logic across use cases. Architecture constrains bloat but doesn't prevent duplication.

252-line use case. UpdateSeatCountUseCaseImpl handles both seat increases (charge proration) and seat decreases (credit issuance), including per-seat add-on proration for both directions. At 252 lines, it's the largest use case — still smaller than classic's SubscriptionService, but pushing the boundary of "one use case, one responsibility."

The numbers: Phase 0 → Phase 1

Code volume

Metric	Classic P0	Classic P1	Clean P0	Clean P1
Source files (total)	33	69	80+	173
Production lines	787	2,973	1,225	6,274
Test lines	—	5,775	—	4,825
Largest file	457 lines	635 lines	120 lines	252 lines

Phase 0 line counts covered production source only. Phase 1 includes production + test breakdown. jOOQ generated code (in build/) is excluded from all counts.

Both codebases roughly doubled in file count. The largest file metric is not a full maintainability measure, but it's a useful proxy for responsibility concentration — how much logic the LLM packs into a single place. Classic's largest file grew 39% (457 → 635). Clean's grew 110% but from a much lower base (120 → 252, still below the size where single-file comprehension starts to get harder).

Test results

Metric	Classic P0	Classic P1	Clean P0	Clean P1
Test count	155	291	167	288
Cold build + test	4s	5s	9s	10s
Warm build + test	3s	4s	3s	8s

Test counts are almost identical (291 vs 288). The LLM generated comprehensive tests for both architectures. In this setup, Clean's warm build time rose from 3s to 8s, likely reflecting the growing overhead of a larger multi-module Gradle build.

Coverage

Metric	Classic P0	Classic P1	Clean P0	Clean P1
Line coverage	89.7%	94.6%	87.7%	90.2%
Branch coverage	—	83.4%	—	64.7%

Classic's line coverage improved from 89.7% to 94.6%. The new services (AddOnService, SeatService, CreditNoteService) are well-tested — possibly because the LLM generated them fresh with tests, rather than modifying existing code.

Clean's branch coverage at 64.7% deserves honest scrutiny. One-third of all branch paths are untested. The sealed interface error types define variants like Internal(cause: String) and Domain(error: DomainError) that no test exercises. In Part 0, I argued that clean's uncovered paths are "named and enumerable" — you can grep for them. That's true. But Phase 1 reveals the practical cost: the LLM defines exhaustive error types because the type system demands it, then doesn't write exhaustive tests because nothing demands that. The architecture pays the definition cost but doesn't automatically collect the testing benefit. The types exist as compile-time documentation, not runtime guarantees — unless someone (human or LLM) writes the tests to match.

What Phase 1 reveals that Phase 0 couldn't

Patterns across both architectures

1. Existing code is the strongest context. In classic, the LLM read a 457-line god service and decided not to make it worse — it created three new services unprompted. In clean, it followed the existing use case pattern without needing the layer sketch. The .claude/ rules and agent configurations matter most in Phase 0. By Phase 1, the codebase itself teaches the LLM what to do. This also explains the generation time convergence.

2. Architecture constrains structure but not duplication. Both implementations duplicated proration logic — classic across three services, clean across four use cases. Phase 0's PlanChangeUseCase delegates to a ProrationDomainService, but Phase 1's new use cases all calculate proration inline. The LLM didn't reuse the existing domain service. It generates each unit independently and doesn't refactor across boundaries — whether those boundaries are services or use cases.

3. Type safety without test safety is incomplete. Clean's branch coverage dropped to 64.7%. The type system demanded exhaustive error definitions; the LLM complied. But nothing demanded exhaustive tests, and the LLM didn't write them. Meanwhile, classic's processRenewal() grew from 9 to 12 responsibilities (457 → 635 lines) because there's no mechanism to prevent a method from becoming the integration point for the entire domain. Clean constrains bloat structurally; classic relies on the LLM making good local decisions — which it sometimes does (new services) and sometimes doesn't (growing processRenewal). But neither architecture made the LLM write better tests.

What the data suggests — and what it doesn't

What the numbers show

Two phases of data show clear patterns:

Generation time converged. Phase 0: 1.75x gap. Phase 1: 1.01x gap. Existing code as context reduced Clean's coordination overhead and increased Classic's reading time. Whether this trend continues, stabilizes, or reverses at Phase N is unknown — we have two data points, not a curve.

Classic's largest file grew; Clean's stayed bounded. 457 → 635 lines vs 120 → 252 lines. Classic's growth came from processRenewal() absorbing cross-domain logic. Clean's growth came from a complex use case (seat + add-on proration), but each use case remains independent. The mechanism differs: Classic grows by accretion in existing files; Clean grows by adding new files.

Duplication is architecture-independent. Both implementations duplicated proration logic across multiple locations. The LLM doesn't refactor across boundaries — whether those boundaries are services (classic) or use cases (clean). This is arguably the most important finding: the LLM's weakest capability is recognizing shared logic across independently generated code units.

The LLM adapts to existing code patterns. Classic's self-decomposition into new services was unprompted. Clean's consistent use case structure was self-reinforcing. Existing code is a stronger guide than configuration files.

The trade-off table

Dimension	Classic	Clean
Greenfield speed	18m (fast)	32m (slow)
Feature-add speed	29m	29m
Code readability	Immediately familiar	Requires architecture knowledge
Error handling	Flat exceptions (easy to add, easy to miss)	Sealed types (verbose, compiler-enforced)
Duplication	Across services	Across use cases (same problem)
Max file size	Growing (457 → 635)	Bounded (120 → 252)
Branch coverage	83.4%	64.7%
Upfront investment	Low	High (multi-module, tooling, rules)

A hypothesis, not a conclusion

Two data points don't make a trend. But they suggest a hypothesis worth testing:

Architecture may function as a scaling constraint on LLM-generated code. Clean's explicit boundaries prevent the structural problems that compound over time (god services, file bloat, implicit dependencies). Classic's flexibility allows the LLM to adapt (new services), but also allows it to accumulate debt (growing integration points, flat error hierarchies).

However, architecture does not solve the LLM's core limitation — cross-boundary refactoring. Both implementations duplicated proration logic. Both missed opportunities to extract shared abstractions. Clean's sealed types went untested at the same rate as Classic's exception paths. The LLM fills each container correctly but doesn't optimize across containers.

The question for a real project isn't "which architecture should I pick?" It's a compound question:

How often will features be added? More features favor explicit boundaries.
How much do features interact? More interaction creates cross-cutting concerns that stress any architecture.
What is the team's tolerance for boilerplate? In this experiment, Clean carried a roughly 2.5x file-count overhead.
What is the LLM's role? If the LLM generates initial code and humans maintain it, Classic's familiarity wins. If the LLM generates and extends code continuously, Clean's self-documenting structure wins.

Architecture is not a prompt. It's the shape of the container the LLM fills — and the shape determines what compounds and what stays constant as the codebase grows.

The full source is on GitHub: classic/ | clean/

I Made an LLM Build the Same App Twice — Classic Spring Boot vs Clean Architecture

Tetsuya Wakita — Mon, 09 Mar 2026 17:07:40 +0000

I gave Claude Code identical business requirements with two different architectural contexts. The generated code told me more about architecture's value than any textbook could.

The experiment

I set up a controlled experiment in two phases:

Phase 0 — Full-scratch generation. Give the LLM a spec and an empty project. It builds everything from zero. This tests how architecture shapes greenfield code.
Phase 1 — Feature addition. Give the LLM an existing codebase (the Phase 0 output) and a new feature spec. It reads, modifies, and extends. This tests how architecture holds up under change.

Same business domain for both: a SaaS subscription billing system. The spec covers plan management with tiered pricing (free / starter / professional / enterprise), the full subscription lifecycle (trial → active → paused → canceled → expired), usage-based metering with per-plan limits, proration calculations on mid-cycle plan changes, invoice generation with line items and discount application, and payment processing with retry logic and grace periods.

Same spec files. Two different architectural contexts.

Classic: single-module Spring Boot, layered architecture (controller → service → repository → model), JPA, JUnit 5, exception-based error handling
Clean: 5-module Clean Architecture, Arrow-kt Either, CQRS, jOOQ, Kotest, sealed interface error types

This article covers Phase 0. The orchestrator agent read the specs, produced a layer sketch, and spawned implementer agents to generate every file from zero. No human edits. No iterative refinement. The only difference was the .claude/ directory — the architectural context the LLM received.

What "context" means for an LLM

Most discussions about AI-generated code focus on the prompt. But for a codebase-scale task, the prompt is the least important input. What matters is the context — the accumulated knowledge the LLM has access to when making decisions.

For classic:

classic/.claude/
├── CLAUDE.md            # Architecture rules, package conventions
├── rules/               # 3 files: JPA patterns, Spring patterns, testing
├── agents/              # 5 agents: orchestrator, entity, service, api, tester
├── skills/              # TDD patterns
├── specs/               # 4 spec files (shared)
└── layer-sketch.md      # 45 files to create

For clean:

clean/.claude/
├── CLAUDE.md            # Layer rules, CQRS structure, forbidden imports
├── rules/               # 2 files: Arrow Either style, test conventions
├── agents/              # 6 agents: orchestrator, domain, app, infra, presentation, tester
├── skills/              # 5 skills: CA patterns, FP patterns, Arrow-kt, jOOQ, TDD
├── specs/               # 4 spec files (shared)
└── layer-sketch.md      # 115 files to create

But the difference isn't just the .claude/ directory. The clean project also requires infrastructure that exists before the LLM starts generating: a multi-module Gradle setup with dependency constraints between modules, custom detekt rules (ForbiddenLayerImportRule, NoThrowOutsidePresentationRule), jOOQ code generation from DDL, and Kover coverage thresholds. Classic needs none of this — a single build.gradle.kts with Spring Boot starters is enough.

The classic context teaches the LLM how to write code — JPA annotation patterns, @Transactional placement, exception hierarchy design. The clean context teaches the LLM where code cannot go — forbidden imports per layer, mandatory Either return types, whitelist-based constraints — backed by tooling that enforces those boundaries at build time.

This is the fundamental difference. Classic gives guidelines. Clean gives boundaries with teeth.

The generated code: classic

The LLM produced 33 source files in a single module. Here's what it did well and where it broke down.

What the LLM got right

Rich domain models. The Money class handles currency-safe arithmetic with operator overloading. SubscriptionStatus and InvoiceStatus implement state machine transitions with canTransitionTo() guards. These patterns came directly from the spec + the jpa-kotlin.md rule file.

// classic/model/Money.kt
data class Money(val amount: BigDecimal, val currency: Currency) {
    operator fun plus(other: Money): Money {
        require(currency == other.currency) { "Currency mismatch" }
        return Money(amount + other.amount, currency)
    }
}

Exception hierarchy. The LLM created a ServiceException base class with HTTP status codes and a GlobalExceptionHandler that maps each exception type to the correct response. Clean, predictable, consistent.

Where classic broke down

The 457-line service. SubscriptionService handles creation, plan changes, pauses, resumes, cancellations, renewals, and discount management — all in one class. The LLM followed the most common Spring Boot pattern it's seen: one service per entity.

// classic/service/SubscriptionService.kt — 457 lines
@Service
class SubscriptionService(
    private val subscriptionRepository: SubscriptionRepository,
    private val planRepository: PlanRepository,
    private val invoiceRepository: InvoiceRepository,
    private val usageRecordRepository: UsageRecordRepository,
    private val discountRepository: DiscountRepository,  // 5 repositories
    private val paymentGateway: PaymentGateway,
    private val clock: Clock,
) {
    fun createSubscription(...): Subscription { /* 50 lines */ }
    fun changePlan(...): Subscription { /* 80 lines */ }
    fun pauseSubscription(...): Subscription { /* 25 lines */ }
    fun resumeSubscription(...): Subscription { /* 20 lines */ }
    fun cancelSubscription(...): Subscription { /* 35 lines */ }
    fun processRenewal(...): Subscription { /* 90 lines — 9 responsibilities */ }
    // ...
}

Nobody told the LLM to create one service with nine responsibilities. But nobody told it not to, either. The classic context defines a service/ package and lists SubscriptionService as the class to create. The LLM filled it with everything subscription-related — because that's the statistical norm in Spring Boot codebases.

Hardcoded discount resolution — in the wrong place. The spec mentions discount codes but doesn't specify a database lookup. Both implementations hardcoded the same "WELCOME20" string. The difference is where.

In classic, the hardcode lives inside SubscriptionService as a private method:

// classic/service/SubscriptionService.kt
private fun resolveDiscount(code: String, now: Instant): Discount =
    when (code) {
        "WELCOME20" -> Discount(type = PERCENTAGE, value = BigDecimal("20"), ...)
        else -> throw InvalidDiscountCodeException(code)
    }

In clean, the same hardcode lives in DiscountRepositoryImpl in the infrastructure layer, behind a DiscountCodePort interface:

// clean/infrastructure/.../DiscountRepositoryImpl.kt
override fun resolve(code: String, ...): Either<DomainError, Discount?> = either {
    when (code) {
        "WELCOME20" -> Discount.of(...)
        else -> null
    }
}

Both are stubs. But when the time comes to replace the hardcode with a database lookup, classic requires modifying SubscriptionService — the 457-line class that owns all subscription logic. Clean requires modifying only the infrastructure adapter. The use case never knows the difference, because it depends on DiscountCodePort, not the concrete implementation. The layer sketch defined this port upfront; the LLM didn't choose it — the architecture did.

Invoice generation duplicated. The changePlan() method and processRenewal() method both construct Invoice objects with line items. The logic is nearly identical. The LLM generated each method independently, and since there's no factory pattern in the context, it copy-pasted the construction logic.

The generated code: clean

The LLM produced 80+ source files across 5 modules. The same spec, but a fundamentally different result.

The architecture constrained the output

One use case, one file. The clean context defines 8 command use cases and 3 query use cases — each as a separate interface and implementation. The LLM couldn't create a 457-line service because the structure doesn't have a place for one.

// clean/application/command/usecase/PlanChangeUseCaseImpl.kt — 85 lines
class PlanChangeUseCaseImpl(
    private val subscriptionCommandQueryPort: SubscriptionCommandQueryPort,
    private val planQueryPort: PlanQueryPort,
    private val paymentGatewayPort: PaymentGatewayPort,
    private val prorationDomainService: ProrationDomainService,
    private val subscriptionRepository: SubscriptionRepository,
    private val invoiceRepository: InvoiceRepository,
    private val clockPort: ClockPort,
    private val transactionPort: TransactionPort,
) : PlanChangeUseCase {
    override fun execute(command: ChangePlanCommand): Either<PlanChangeError, Subscription> = either {
        // ...
    }
}

The largest use case is 120 lines. The structure made bloat physically impossible.

Either forced exhaustive error handling. Every use case returns Either<SpecificError, T>. The LLM couldn't skip error cases because the sealed interface makes the compiler enforce exhaustiveness:

sealed interface PlanChangeError : ApplicationError {
    data class InvalidInput(val field: String, val reason: String) : PlanChangeError
    data object SubscriptionNotFound : PlanChangeError
    data object NotActive : PlanChangeError
    data object SamePlan : PlanChangeError
    data object PlanNotFound : PlanChangeError
    data class CurrencyMismatch(val from: String, val to: String) : PlanChangeError
    data class PaymentFailed(val reason: String) : PlanChangeError
    data class Domain(val error: DomainError) : PlanChangeError
    data class Internal(val cause: String) : PlanChangeError
}

In classic, the LLM defined 8 exception types. In clean, it defined 50+ error variants across sealed interfaces. Not because the LLM tried harder — but because the type system demanded it.

Ports prevented infrastructure leakage. The PlanQueryPort is defined in the application layer. The LLM couldn't import JPA or jOOQ in the use case because the module boundary prevents it. The adapter pattern isn't a recommendation — it's the only way to access external systems.

// Defined in application/command/port/
interface PaymentGatewayPort {
    fun charge(amount: Money, paymentMethod: PaymentMethod, customerRef: String):
        Either<PaymentError, PaymentResult>
}

// Implemented in infrastructure/command/adapter/
@Component
class PaymentGatewayAdapter : PaymentGatewayPort {
    override fun charge(...) = PaymentResult(...).right()  // stub
}

Where clean showed overhead

115 files for the same business logic. The clean version has 2.5x more files than classic. Many are thin — a sealed interface with two variants, a port interface with one method, a DTO with five fields. But they exist, and each one had to be generated, placed in the correct module, and wired together.

Value object ceremony. Every ID type requires a smart constructor returning Either:

@JvmInline
value class SubscriptionId private constructor(val value: Long) {
    companion object {
        operator fun invoke(value: Long): Either<ValidationError, SubscriptionId> =
            if (value > 0) SubscriptionId(value).right()
            else ValidationError.InvalidId("SubscriptionId", value).left()
    }
}

There are 10 value object types. Classic uses Long directly. The type safety is real, but so is the boilerplate.

The numbers

Generation time

Metric	Classic	Clean
Phase 0 generation	18m 15s	32m 2s

Clean took 1.75x longer to generate. The orchestrator coordinates 6 agents across 5 modules with dependency ordering — domain must finish before application, application before infrastructure and presentation. Classic's 4-agent pipeline runs in a simpler sequence with fewer handoffs. The multi-module coordination, larger layer sketch (115 files vs 45), and the additional Arrow-kt/CQRS patterns all add up.

Code volume

Metric	Classic	Clean
Source files	33	80+
Total production lines	787	1,225
Largest file	457 lines (SubscriptionService)	120 lines (ProcessRenewalUseCase)
Error types defined	8 exception classes	50+ sealed interface variants

Test results

Metric	Classic	Clean
Test count	155	167
Full build + test (cold)	4s	9s
Full build + test (warm)	3s	3s
Test execution time	2.2s	1.7s

The build time difference disappears once the Gradle daemon is warm — compilation is the bottleneck, not test execution. Clean's tests actually execute faster (1.7s vs 2.2s) despite having more tests, because domain and application tests run without Spring context startup.

Layer-by-layer test performance

Classic:

Layer	Tests	Time	Per test
Model (pure)	70	0.027s	0.4ms
Service (MockK)	67	0.723s	10.8ms
Controller (WebMvcTest)	18	1.45s	80.6ms

Clean:

Module	Tests	Time	Per test
Domain (pure + Kotest)	85	0.45s	5.2ms
Application (Kotest + MockK)	61	2.25s	36.9ms
Presentation (no Spring)	21	1.1s	52.4ms

Two things stand out. First, clean's presentation tests don't use @WebMvcTest — they instantiate the controller directly and call methods. The 1.1s is pure Kotest/MockK initialization overhead, not Spring. Second, the Kotest runner adds ~0.9s of startup per module for the first test class. After initialization, subsequent test classes run at ~15ms each.

Coverage

Metric	Classic (JaCoCo)	Clean (Kover)
Line coverage	89.7%	87.7%
Production lines	787	1,225

Classic by layer:

Layer	Coverage
Model	92.9%
Service	90.4%
Controller	100%

Clean by module:

Module	Coverage
Domain	74.1%
Application	84.2%
Presentation	82.1%

Coverage numbers are nearly identical — but they measure different things.

Classic's 89.7% means "89.7% of lines were reached." The missing 10.3% includes exception paths that were never thrown in tests. Those paths exist as throw statements — invisible to the type system, easy to forget in tests.

Clean's 87.7% means "87.7% of typed error paths were exercised." The missing 12.3% is visible in the code — it's sealed interface variants like Internal(cause: String) that tests didn't trigger. The untested paths are named and enumerated. You can grep for them.

What the experiment actually shows

Both implementations are functionally equivalent. They handle the same subscription lifecycle — creation, plan changes, pauses, resumes, cancellations, renewals, usage metering, and payment processing. Both compile, both pass tests, both have ~89% coverage. There is no meaningful difference in what the code does.

The difference is in how the code is shaped.

Classic: the LLM's strengths and blind spots

Classic plays to the LLM's greatest advantage: the sheer volume of training data for conventional patterns. Spring Boot is the most common Kotlin/JVM web framework. The LLM has seen millions of @Service + @Repository + @RestController examples. The result is concise, idiomatic code that any Spring developer would recognize immediately.

The model layer is genuinely good. Money with operator overloading, SubscriptionStatus with canTransitionTo() guards, Invoice with state machine transitions — these are clean, well-structured patterns that benefit from the LLM's deep familiarity with the ecosystem.

But the same statistical bias that makes the LLM good at conventional patterns makes it prone to conventional mistakes:

Service bloat. SubscriptionService at 457 lines with 9 responsibilities. The LLM follows the "one service per entity" norm — the pattern it's seen most often — even when the complexity demands decomposition.
Code duplication. Invoice construction logic appears in both changePlan() and processRenewal(). The LLM generates each method independently. Without an explicit Factory pattern in the context, it doesn't extract shared logic.
Shortest-path solutions. Hardcoded discount resolution instead of a repository lookup. When the spec is underspecified, the LLM takes the minimal implementation — not the extensible one.

These aren't bugs. The code works. But they're the kind of structural problems that compound over time as features are added.

Clean: boundaries prevent problems, at a cost

Clean architecture constrains the LLM's output through structure rather than instruction. The result is code with clear dependency direction, no bloated classes, and exhaustive error handling — but significantly more of it.

What boundaries buy you:

No bloat possible. The layer sketch defines 8 command use cases as separate files. The LLM can't merge them into a god service because there's no single file to put it in. The largest use case is 120 lines.
Explicit dependencies. Every external system access goes through a Port interface defined in the application layer. The LLM can't accidentally couple a use case to jOOQ or JPA — the module boundary prevents the import.
Exhaustive error handling. Sealed interfaces with Either force the LLM to define and handle every error variant. Classic has 8 exception types; clean has 50+ error variants. The compiler enforces this, not the prompt.

What boundaries cost you:

2.5x more code. 1,225 lines across 80+ files vs 787 lines across 33 files. Many clean files are thin wrappers — a port interface with one method, a sealed interface with two variants — but they all need to be generated, placed correctly, and wired together.
Longer generation time. The clean orchestrator must coordinate 6 agents across 5 modules with dependency ordering (domain → application → infrastructure | presentation). Classic's orchestrator runs 4 agents in a simpler pipeline. The multi-module coordination overhead is real.
Higher context investment. 24 configuration files vs 19. The additional skills (Arrow-kt patterns, CA layer rules, FP patterns) and the detailed layer sketch are necessary to produce correct output — but they represent upfront work before the first feature ships.

The core observation

The LLM doesn't "understand" architecture. It follows the path of least resistance within the constraints it's given.

With classic constraints, the path of least resistance is the statistically dominant pattern — concise, idiomatic, and immediately readable, but carrying the same structural debts (god services, code duplication) that the average Spring Boot project accumulates over time.

With clean constraints, the path of least resistance is the structurally enforced pattern — no bloat, exhaustive error handling, explicit dependencies, but at the cost of 1.75x generation time and 2.5x more files.

The LLM didn't write better or worse code in either case. It filled the container it was given.

Architecture is not a prompt. It's the shape of the container the LLM fills.

But this is Phase 0 — greenfield generation. Both codebases work. Both have high coverage. The structural differences are visible but haven't been tested under pressure. The real question is what happens when the LLM modifies existing code — when the 457-line service needs a tenth responsibility, when the duplicated invoice logic needs a third variant.

The full source is on GitHub: classic/ | clean/

I Made Zod 64x Faster by Compiling Schemas at Build Time

Tetsuya Wakita — Wed, 04 Mar 2026 14:33:57 +0000

Zod v4 is fast. But what if you could skip schema traversal entirely? I built a compiler that turns your Zod schemas into plain JavaScript validation functions at build time — and it's 2–64x faster.

The Problem: Runtime Schema Traversal Is Inherently Slow

Zod is everywhere. With over 100 million weekly npm downloads, it's the de facto standard for runtime validation in TypeScript. The API is beautiful — you define a schema, and you get both runtime validation and static types for free.

But that elegance has a cost.

Every time you call .parse(), Zod walks the entire schema tree at runtime. It checks each node type, applies constraints, collects errors, and constructs the result. For a simple z.string(), the overhead is negligible. But for a nested object with arrays, unions, and dozens of fields? That tree walk adds up fast.

// Every .parse() call traverses this entire tree — every time
const UserSchema = z.object({
  id: z.string().uuid(),
  name: z.string().min(1).max(100),
  email: z.string().email(),
  role: z.enum(["admin", "user", "viewer"]),
  preferences: z.object({
    theme: z.enum(["light", "dark"]),
    notifications: z.boolean(),
    language: z.string().length(2),
  }),
  tags: z.array(z.string()).max(20),
});

// This traverses ~15 schema nodes on every single call
UserSchema.parse(data);

This matters in real production scenarios:

API servers validating every incoming request body
Edge functions where cold-start budgets are measured in milliseconds
Form validation running on every keystroke on mobile devices

The schema never changes. But Zod re-discovers its structure on every single parse call.

The Insight: Schemas Are Static — Validation Can Be Compiled

Here's the key observation: most Zod schemas are defined once at module scope and never change at runtime. The tree walk produces the same sequence of operations every time. It's pure overhead.

This is exactly the problem compilers solve — move repeated work from runtime to build time.

What if instead of walking a schema tree at runtime, you could generate a plain function that does the exact same validation — but with zero traversal overhead?

// What Zod does at runtime (simplified):
function parse(schema, data) {
  switch (schema.type) {
    case "object": return parseObject(schema, data);
    case "string": return parseString(schema, data);
    case "array":  return parseArray(schema, data);
    // ... recursive traversal continues
  }
}

// What AOT compilation produces:
function validateUser(data) {
  if (typeof data !== "object" || data === null) return error("Expected object");
  if (typeof data.id !== "string") return error("Expected string");
  if (!UUID_REGEX.test(data.id)) return error("Invalid uuid");
  if (typeof data.name !== "string") return error("Expected string");
  if (data.name.length < 1) return error("String must contain at least 1 character(s)");
  // ... flat, linear, no traversal
}

The second function does the same thing, but there's no schema tree to walk. No type switches. No recursive calls. Just straight-line validation code.

Introducing zod-aot

That's what zod-aot does. It reads your Zod schemas at build time, compiles them into optimized validation functions, and replaces the runtime parsing with generated code.

Installation

npm install zod-aot zod@^4

Usage — wrap with `compile()`

import { z } from "zod";
import { compile } from "zod-aot";

const UserSchema = compile(
  z.object({
    id: z.string().uuid(),
    name: z.string().min(1).max(100),
    email: z.string().email(),
    role: z.enum(["admin", "user", "viewer"]),
  })
);

// Same API — .parse(), .safeParse(), .is()
const user = UserSchema.parse(data);

In development, compile() passes through to Zod as-is. In production builds, the bundler plugin replaces it with the generated validation function. Zero code changes to your existing schemas.

Build integration

Vite (4 lines):

// vite.config.ts
import { zodAot } from "zod-aot/vite";

export default defineConfig({
  plugins: [zodAot()],
});

CLI for non-bundler workflows:

npx zod-aot generate src/ -o dist/

The compiled validators expose the same interface: .parse() throws on invalid input, .safeParse() returns a result object, and .is() acts as a type guard.

Transform and Refine: Partial Compilation

Here's where it gets interesting. Not everything in a Zod schema can be compiled ahead of time.

Zod's .transform(), .refine(), .superRefine(), and z.custom() accept arbitrary JavaScript functions. These are opaque at build time — there's no way to statically analyze what (val) => val.toUpperCase() does without executing it.

So zod-aot doesn't try to compile them. Instead, it uses partial compilation.

const ProfileSchema = compile(
  z.object({
    name: z.string().min(1),                          // ✅ AOT compiled
    email: z.string().email(),                         // ✅ AOT compiled
    age: z.number().int().min(0).max(150),             // ✅ AOT compiled
    bio: z.string().transform((s) => s.trim()),        // ⚠️ Falls back to Zod
    score: z.number().refine((n) => isPrime(n)),       // ⚠️ Falls back to Zod
  })
);

In this schema, 3 out of 5 fields get full AOT compilation. The remaining 2 delegate to Zod at runtime — only for those specific fields. The compiler decides this automatically at extraction time. No annotations, no configuration, no manual intervention.

This is the key design decision: compile what you can, fall back gracefully for the rest. A schema that's 80% compilable still gets 80% of the performance benefit.

This means you never have to worry about whether your schema is "compatible" with zod-aot. Every Zod v4 schema works. The question is only how much of it gets compiled.

Benchmark Results

Theory is nice. Let's see actual numbers.

I benchmarked zod-aot compiled validators against Zod v4's native .parse() across a range of schema complexities. Each benchmark runs 100,000 iterations with warmup, using performance.now() for timing.

Schema	Zod v4 `.parse()`	zod-aot	Speedup
Simple string (`z.string().email()`)	1.2M ops/s	2.1M ops/s	~1.8x
Medium object (valid input)	480K ops/s	2.4M ops/s	~5x
Medium object (invalid input)	210K ops/s	4.8M ops/s	~23x
Large nested object (100 items)	12K ops/s	780K ops/s	~64x
Discriminated union (5 variants)	320K ops/s	3.2M ops/s	~10x

The pattern is clear: the larger and more complex the schema, the greater the AOT benefit.

For a simple string validation, the overhead of Zod's runtime traversal is minimal — you're only walking one or two nodes. The speedup is modest.

But for a large nested object with 100 array items, each containing multiple validated fields, Zod has to traverse hundreds of schema nodes on every parse call. The AOT-compiled version does the same validation with flat, inlined code — no tree to walk. That's where the 64x gap comes from.

The invalid input case is particularly interesting. The compiled validator hits the first failing check and returns immediately. Zod's runtime has more overhead even for early exits because of the error collection and traversal machinery.

Key takeaway: If your hot-path schemas are simple primitives, Zod v4 is already fast enough. If you're validating complex nested objects at high throughput, AOT compilation delivers an order-of-magnitude improvement.

Comparison and Trade-offs

How zod-aot compares to alternatives

vs Typia (~76M ops/s): Typia is faster because it compiles directly from TypeScript types using a compiler plugin. But it requires you to define validation as TypeScript types — not Zod schemas. If your codebase already uses Zod, migrating to Typia means rewriting every schema.

vs AJV standalone: AJV compiles JSON Schema into validation functions — conceptually the same approach as zod-aot. But AJV operates in the JSON Schema ecosystem. If you're using Zod, you'd need to convert schemas to JSON Schema first, losing Zod-specific features.

vs Zod v4 native: zod-aot is complementary, not competitive. It builds on Zod v4 and uses its internals. You keep writing Zod schemas — zod-aot just makes them faster in production.

zod-aot's niche: zero migration cost for existing Zod users. You keep your schemas, your types, your ecosystem integrations with tRPC/React Hook Form/Next.js. You just add compile() and a build plugin.

Honest trade-offs

Nothing is free. Here's what you should know:

Build-time extraction: zod-aot runs your schema code once at build time to extract the schema structure. If your schemas have side effects at definition time, this could cause issues.
transform/refine-heavy schemas get minimal benefit. If most of your validation logic lives in custom functions, AOT compilation can't help much.
Bundle size: generated validators are standalone JavaScript — no Zod dependency at runtime, but the generated code itself adds to your bundle. For most schemas this is smaller than Zod itself.
Zod v4 only: zod-aot depends on Zod v4's internal schema representation (_zod.def). It does not support Zod v3.

Try It Out

zod-aot is open source under the MIT license.

GitHub: https://github.com/wakita181009/zod-aot
npm: zod-aot

What's next:

Broader schema type coverage (recursive types, branded types)
Incremental build caching for large codebases
Source map support for debugging compiled validators

If you're using Zod in a performance-sensitive context, give it a try. Star the repo if you find it useful, and file issues for anything that doesn't work. PRs are always welcome.

Enforcing Clean Architecture on AI-Generated Kotlin with Custom Detekt Rules

Tetsuya Wakita — Sun, 22 Feb 2026 20:26:29 +0000

How custom detekt rules, specialized AI agents, and specification-driven development keep Clean Architecture intact — even when an LLM writes the code.

The moment an LLM broke the architecture

I asked an AI coding assistant to add a new use case to the application layer. It wrote the code in under a minute. It also added @Service to the class, imported org.springframework.stereotype.Service, and threw an IllegalArgumentException for invalid input.

Three architecture rules broken in a single generation.

LLMs are fast. They're also statistically inclined to produce the most common pattern they've seen — and in the Kotlin ecosystem, that's Spring annotations on everything, exceptions for error handling, and no concept of layer boundaries. Your architecture documentation might say "no Spring in application layer." The LLM has seen 100,000 Spring Boot examples that do exactly the opposite.

In the previous parts of this series, I built a Clean Architecture in Kotlin with Gradle module boundaries, Arrow-kt Either error handling, and CQRS — all enforced at compile time. Those guarantees held because humans followed the rules. Now the developer is an LLM. The question becomes: how do you make the architecture enforce itself on code the LLM generates?

Custom detekt rules: architecture as static analysis

Gradle modules prevent cross-layer dependencies — domain can't import from infrastructure because the dependency doesn't exist. But within the allowed imports, an LLM can still break the architecture in two fundamental ways:

Importing forbidden libraries into pure layers (Spring annotations in domain/application)
Throwing exceptions instead of returning Either<Error, T>

Both are valid Kotlin. Both compile. Both violate the architecture. Gradle can't catch them. So I wrote two custom detekt rules that can.

Rule 1: ForbiddenLayerImportRule — whitelist-based import enforcement

Instead of blacklisting specific imports (which the LLM can always find creative alternatives for), this rule whitelists what's allowed. Anything not on the list is rejected.

class ForbiddenLayerImportRule(config: Config) : Rule(config, "...") {

    private val commonAllowedPrefixes = listOf(
        "kotlin.", "java.",
        "arrow.core.", "arrow.fx.coroutines.",
        "kotlinx.coroutines.", "org.slf4j.",
    )

    override fun visitImportDirective(importDirective: KtImportDirective) {
        super.visitImportDirective(importDirective)

        val file = importDirective.containingKtFile
        if (file.virtualFilePath.contains("/test/")) return

        val packageName = file.packageFqName.asString()
        val importPath = importDirective.importedFqName?.asString() ?: return

        val layer = packageName.removePrefix("$projectBase.").substringBefore(".")
        val layerOwnPackages = when (layer) {
            "domain" -> listOf("$projectBase.domain.")
            "application" -> listOf("$projectBase.domain.", "$projectBase.application.")
            else -> return  // only enforce on domain and application
        }

        val allowed = commonAllowedPrefixes + layerOwnPackages

        if (allowed.none { importPath.startsWith(it) }) {
            report(Finding(
                Entity.from(importDirective),
                "Import '$importPath' is not allowed in $layer layer.",
            ))
        }
    }
}

The logic is deliberate:

Domain layer: can only import Kotlin stdlib, Arrow-kt, coroutines, SLF4J, and its own packages
Application layer: the same, plus domain layer packages
Test files: skipped — tests can import whatever they need (MockK, Kotest, etc.)
Other layers: not enforced — infrastructure and presentation have legitimate framework needs

When an LLM generates import org.springframework.stereotype.Service in a use case class, detekt fails the build with a clear message: "Import 'org.springframework.stereotype.Service' is not allowed in application layer." The LLM can read that message and fix its own output.

Why whitelist instead of blacklist? Because I can't anticipate every library an LLM might try to import. The whitelist is short and complete: Kotlin, Arrow, coroutines, SLF4J, and own-layer packages. Everything else is denied by default.

Rule 2: NoThrowOutsidePresentationRule — enforcing Either for all errors

In Part 1, every fallible operation returns Either<XxxError, T>. No exceptions. The return type is the complete error specification.

LLMs don't naturally write this way. They reach for throw IllegalArgumentException("invalid input") because that's what most Kotlin code does.

class NoThrowOutsidePresentationRule(config: Config) : Rule(config, "...") {

    private val forbiddenLayers = setOf("domain", "application", "infrastructure")

    override fun visitThrowExpression(expression: KtThrowExpression) {
        super.visitThrowExpression(expression)

        val file = expression.containingKtFile
        if (file.virtualFilePath.contains("/test/")) return

        val packageName = file.packageFqName.asString()
        val layer = packageName.removePrefix("$projectBase.").substringBefore(".")

        if (layer in forbiddenLayers) {
            report(Finding(
                Entity.from(expression),
                "throw detected in '$packageName'. Use Either<XxxError, T> instead.",
            ))
        }
    }
}

Three layers are covered: domain, application, and infrastructure. The only layer where throw is permitted is presentation — because Spring's exception handler infrastructure (ResponseStatusException, GraphQLException) requires it.

Together, these two rules turn architecture guidelines into compiler-level enforcement. The LLM writes code, the Kotlin compiler checks types, and detekt checks architecture. Violations are build errors, not code review comments.

From documentation to specification: SDD for LLMs

Part 2 introduced the idea that the application module is a direct translation of the product spec. Tests validate the implementation matches the spec. That workflow was manual — an engineer reads the requirements, writes the interfaces, then writes the tests.

For LLM-driven development, the spec needs to be machine-readable. Not a PDF. Not a Confluence page. A structured markdown file in the repository that an agent can parse directly.

The spec template

Every feature starts with a spec file in .claude/specs/:

# Feature Spec: [Feature Name]

## 1. Context
[Why this feature exists. Business problem.]

## 2. Domain Model Changes
### New Value Objects
- `OrderId` (@JvmInline value class): Long, must be positive
  - Invalid: `OrderError.InvalidId(value)` -> "Invalid order ID: $value"

### Domain Errors
sealed interface OrderError : DomainError:
| Variant      | When                  | Message format              |
|--------------|-----------------------|-----------------------------|
| InvalidId    | ID <= 0               | "Invalid order ID: $value"  |
| NotFound     | No record for this ID | "Order not found: $id"      |

## 3. Use Cases
### UC-1: Find Order by ID
Input: id (Long)
Happy path: validate -> find -> return Order
Error cases:
| Error              | Application Error Type           | HTTP |
|--------------------|----------------------------------|------|
| Invalid ID         | OrderFindByIdError.InvalidId     | 400  |
| Not found          | OrderFindByIdError.NotFound      | 404  |

## 4. Presentation
| Method | Path            | Success | Errors    |
|--------|-----------------|---------|-----------|
| GET    | /api/orders/{id}| 200     | 400, 404  |

The spec is structured enough for an LLM to extract: which value objects to create, what validation rules they have, what error types to define, what use cases to implement, and what HTTP status codes to return. Every field maps directly to a Clean Architecture construct.

This is the key connection from Part 2: the spec-to-code mapping that was implicit in the engineer's head is now explicit in a file. The LLM doesn't need to interpret requirements — it reads a table and generates the corresponding Kotlin class.

Specialized agents: one agent per layer

Here's the central design insight: each agent should know only the rules of its own layer.

A domain-implementer agent that knows about Spring is an agent that might use Spring. An infrastructure-implementer that knows about domain logic is an agent that might put logic in the wrong place. The same principle that separates layers in the code separates agents in the pipeline.

The agent architecture

orchestrator (opus)
  ├── spec-writer (sonnet)      -> writes .claude/specs/[feature].md
  ├── test-designer (sonnet)    -> designs test cases from spec
  ├── tester (sonnet)           -> writes failing tests (RED)
  ├── domain-implementer (sonnet)
  ├── app-implementer (sonnet)
  ├── infra-implementer (sonnet)
  ├── presentation-implementer (sonnet)
  └── reviewer / linter / security-checker (parallel QA)

Each agent is a markdown file with explicit constraints. Here's the opening of the domain-implementer:

# Domain Implementer Agent

You implement the domain layer: entities, value objects, error types,
and repository interfaces.

## Constraints — STRICTLY ENFORCED

- **NO** Spring annotations (@Component, @Repository, @Service)
- **NO** JooQ, R2DBC, JDBC imports
- **NO** `throw` statements (use Either / raise() / ensure())
- **ONLY** allowed: Kotlin stdlib, Arrow-kt, SLF4J

The constraints mirror the detekt rules — but at the prompt level. The agent is told what it cannot do before it writes a single line. If it still violates, detekt catches it at build time.

Skills as domain knowledge

Each agent references skills — structured knowledge about specific patterns:

Skill	What it contains
`ca-kotlin`	Layer rules, module dependencies, what each layer can import
`fp-kotlin`	Immutability patterns, Either chaining, sealed error hierarchies
`tdd-kotlin`	Test patterns per layer, MockK/Kotest conventions, property-based testing
`sdd-spec`	Spec template, how to extract domain constructs from requirements
`arrow-kt`	Arrow-kt specific patterns: `either { }`, `.bind()`, `mapLeft`
`jooq-ddl`	jOOQ DSL patterns, DDL codegen, reactive Mono/Flux usage

The domain-implementer loads ca-kotlin and fp-kotlin. The infra-implementer loads ca-kotlin and jooq-ddl. The tester loads tdd-kotlin. Each agent gets the knowledge relevant to its layer — no more, no less.

Model selection: right model for the right task

Not all tasks need the same model. The orchestrator — which coordinates the entire pipeline, decides when to retry, and synthesizes results — runs on Opus (highest reasoning capability). The implementers and spec-writer run on Sonnet (faster, cheaper, sufficient for structured generation).

This isn't just cost optimization. It's about matching capability to task complexity. Writing a value object from a spec is pattern-matching. Deciding whether to re-run the implementation phase after a test failure is judgment.

The pipeline: from spec to shipped

Here's what a complete implementation cycle looks like using slash commands:

/spec order-api        -> spec-writer creates .claude/specs/order-api.md
/spec-review order-api -> spec-reviewer validates completeness
/test-design order-api -> test-designer creates test plan from spec
/impl order-api        -> orchestrator runs the full pipeline
/qa                    -> QA pipeline: build + lint + security + review

The /impl command is where the interesting engineering happens. It has to respect the dependency graph between layers while maximizing parallelism.

The dependency-aware parallelization

Phase 1 (sequential):  spec read -> domain-implementer -> app-implementer
Phase 2 (parallel):    infra-implementer | presentation-implementer | test-implementer
Phase 3 (parallel):    builder | linter | security-checker
Phase 4 (sequential):  code-reviewer -> documenter

Domain must complete before application — use cases depend on domain entities, value objects, and repository interfaces. Application must complete before infrastructure, presentation, and tests — all three consume the use case interfaces but don't depend on each other.

This maps directly to the Clean Architecture dependency graph. The implementation order follows the dependency direction: domain -> application -> (infrastructure | presentation | tests). The architecture that makes code modular also makes the build pipeline parallelizable.

What the orchestrator actually does

The orchestrator is the only agent that doesn't write code. It reads the spec, creates a layer sketch (mapping spec elements to Kotlin classes), spawns agents in the correct order, reads test results, and decides whether to retry.

### Phase 0 — Analyze
- Read the spec
- Extract and output a Layer Sketch:
  - Domain entity (fields + types)
  - Value objects (backing type + validation)
  - Repository interface (method signatures)
  - Use cases (interface name + execute signature)
- List every file to create before spawning any agent

### Phase 1 — Red (tester first, alone)
Spawn only the tester agent. Wait for completion.

### Phase 2 — Green (implementer reads tests)
Spawn implementer alone. Wait for completion.

### Phase 3 — Verify + Review (parallel)
Spawn reviewer, linter, security-checker simultaneously.
Run: ./gradlew test koverVerify detekt

### Phase 4 — Synthesize
If tests are red, re-spawn implementer with failure output.
Cap iterations at 3.

The "red -> green -> verify" loop is the SDD + TDD workflow from Part 2 — automated. Tests are written before implementation. Implementation is written to pass the tests. The architecture rules are checked after every cycle. The orchestrator doesn't trust the implementer — it verifies.

Hooks: the last line of defense

Claude Code supports hooks — shell commands that trigger on specific events. Two hooks close the loop between the LLM and the architecture rules:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [{
          "type": "command",
          "command": "cd $CLAUDE_PROJECT_DIR && ./gradlew ktlintFormat 2>&1 | tail -60",
          "timeout": 30
        }]
      }
    ],
    "Stop": [
      {
        "hooks": [{
          "type": "command",
          "command": "cd $CLAUDE_PROJECT_DIR && ./gradlew detekt 2>&1 | tail -60",
          "timeout": 120
        }]
      }
    ]
  }
}

PostToolUse on Write/Edit: Every time the LLM creates or modifies a file, ktlint auto-formats it. No style drift. No formatting discussions. The code matches the project style before the LLM's next turn.

Stop: When the LLM finishes its work, detekt runs automatically. If the custom rules detect a throw in the domain layer or a Spring import in the application layer, the violation is surfaced immediately. The LLM sees the failure output and can self-correct.

This creates a feedback loop: write -> auto-format -> continue -> finish -> architecture check -> fix if violated. The LLM operates within the enforcement boundary in real time.

In Part 3, I proved that swapping the database changed zero files in domain or application. In Part 4, CQRS actually simplified the domain by removing read responsibilities that didn't belong there. Hooks guarantee those architectural properties hold not just for those one-time changes — but for every code change an LLM makes, continuously.

The enforcement stack

Here's the complete picture of how architecture rules are enforced across the stack:

Layer	Mechanism	What it prevents
Gradle modules	Compile-time dependency graph	`domain` importing from `infrastructure`
`ForbiddenLayerImportRule`	AST-level import whitelist	Spring/JPA/framework imports in pure layers
`NoThrowOutsidePresentationRule`	AST-level throw detection	Exceptions in domain/application/infrastructure
Kover 80% threshold	Line coverage gate	Untested error paths
Agent constraints	Prompt-level rules	Agent writing code outside its layer
Skills	Domain knowledge injection	Agent using wrong patterns for its layer
PostToolUse hook	Auto-format on every write	Style drift
Stop hook	Detekt on every completion	Architecture violations in final output

Each layer catches what the layer above might miss. The agent prompt says "no throw." If the LLM ignores it, detekt catches it. If detekt isn't run, Kover might catch the untested exception path. Defense in depth — the same principle that makes Clean Architecture resilient makes the LLM pipeline resilient.

The honest tradeoffs

This setup has real costs:

Initial investment is high. 18 agent definitions, 7 skills, 6 commands, 2 custom detekt rules, and a hook configuration. That's a significant upfront cost before a single feature is implemented through the pipeline.

Agent definitions need maintenance. When the project's patterns evolve — say, migrating from jOOQ to Exposed — every agent and skill that references jOOQ needs updating. The knowledge isn't centralized in one place; it's distributed across agent prompts and skill files.

Model costs add up. Running an Opus orchestrator that spawns multiple Sonnet agents per feature isn't cheap. For a solo developer on a side project, the cost-per-feature may not justify the automation. For a team shipping multiple features per sprint, the math changes.

The pipeline is only as good as the spec. An ambiguous or incomplete spec produces ambiguous or incomplete code. The automation amplifies whatever you feed it. Garbage spec, garbage implementation — faster.

What makes the cost worth it

The payoff is in the second feature, not the first. Once the agents, skills, and rules exist, adding a new feature follows the same path: write a spec, run /impl, review the output. The architectural guarantees from Parts 1-4 are maintained automatically. No code review needed to catch Spring imports in the domain layer. No manual checks for exception-based error handling. The pipeline enforces what the architecture demands.

For teams with multiple engineers (including AI agents) contributing to the same codebase, the enforcement stack is the difference between architecture that degrades over time and architecture that holds.

What this series built

Five articles. One architecture. Database migration, new protocols, CQRS optimization, LLM-generated code — each article applied a different pressure. The architecture held every time. Not because engineers were careful, but because the constraints were structural.

Clean Architecture was designed to make software maintainable by humans. It turns out the same constraints — explicit dependencies, typed errors, pure layers — are exactly what LLMs need to write code safely. The architecture didn't change. The developer did.

The full source is on GitHub: https://github.com/wakita181009/clean-architecture-kotlin/tree/v4

CQRS with Clean Architecture in Kotlin: Separating Read and Write Paths for Better Performance

Tetsuya Wakita — Sun, 22 Feb 2026 19:47:12 +0000

How CQRS inside Clean Architecture gave reads a fast path while keeping writes honest

The read path is doing work it doesn't need to

In Part 3,
I swapped Spring Data R2DBC for jOOQ and added GraphQL alongside REST. The domain and application layers: zero files
changed.

But something bothered me about the read path. When a client calls GET /api/github-repos, here's what happens:

The controller calls gitHubRepoListUseCase.execute(pageNumber, pageSize)
The use case validates pagination parameters
The repository queries the database
The database rows are mapped into domain entities — constructing GitHubRepoId, GitHubOwner, GitHubRepoName value objects with full validation
The domain entities are mapped into REST response DTOs
The DTOs are serialized to JSON

Steps 4 and 5 are pure overhead. The client asked for a list of repos. The read path doesn't modify anything, doesn't
enforce business invariants, doesn't trigger side effects. It just needs data — but it's constructing fully validated
domain objects, only to immediately unwrap them into flat DTOs.

Writes are different. When a client calls POST /api/github-repos, domain validation matters. The GitHubRepoId must
be positive. The GitHubOwner must not be blank. The GitHubRepoName must not be blank. Those invariants protect the
system's integrity. The domain model earns its keep on the write path.

This is the core insight behind CQRS: reads and writes have fundamentally different needs. Forcing them through the
same model means one path is always doing unnecessary work.

What CQRS changes in Clean Architecture

CQRS — Command Query Responsibility Segregation — separates the read model from the write model. In its simplest form (
no event sourcing, no separate databases), it means:

Commands (writes) go through the full domain model: validation, invariants, business rules
Queries (reads) bypass the domain and return DTOs directly from the database

The application layer splits into two sub-packages:

application/
├── command/                    # Write path
│   ├── dto/github/
│   │   └── GitHubRepoDto.kt
│   ├── error/github/
│   │   └── GitHubRepoSaveError.kt
│   └── usecase/github/
│       ├── GitHubRepoSaveUseCase.kt
│       └── GitHubRepoSaveUseCaseImpl.kt
│
└── query/                      # Read path
    ├── dto/
    │   ├── PageDto.kt
    │   └── github/
    │       └── GitHubRepoQueryDto.kt
    ├── error/github/
    │   ├── GitHubRepoFindByIdQueryError.kt
    │   └── GitHubRepoListQueryError.kt
    ├── repository/github/
    │   └── GitHubRepoQueryRepository.kt
    └── usecase/github/
        ├── GitHubRepoFindByIdQueryUseCase.kt
        ├── GitHubRepoFindByIdQueryUseCaseImpl.kt
        ├── GitHubRepoListQueryUseCase.kt
        └── GitHubRepoListQueryUseCaseImpl.kt

Separate DTOs, separate errors, separate repository interfaces. The write path and read path don't share
application-layer types. They share domain value objects for input validation — and nothing else.

The command side: unchanged domain flow

The write path keeps the full domain-driven approach from Parts 1-3. The save use case validates input by constructing
domain entities:

class GitHubRepoSaveUseCaseImpl(
    private val gitHubRepoRepository: GitHubRepoRepository,
) : GitHubRepoSaveUseCase {
    override suspend fun execute(dto: GitHubRepoDto): Either<GitHubRepoSaveError, GitHubRepo> =
        either {
            val repo = dto.toDomain().mapLeft(GitHubRepoSaveError::ValidationFailed).bind()
            gitHubRepoRepository
                .save(repo)
                .mapLeft(GitHubRepoSaveError::SaveFailed)
                .bind()
        }
}

dto.toDomain() constructs every value object — GitHubRepoId.of(id), GitHubOwner.of(owner),
GitHubRepoName.of(name) — each returning Either. If any validation fails, the chain short-circuits with
ValidationFailed. If the repository call fails, it short-circuits with SaveFailed.

The domain repository interface is now write-only:

interface GitHubRepoRepository {
    suspend fun save(repo: GitHubRepo): Either<GitHubError, GitHubRepo>
}

In Parts 1-3, this interface also had findById and list. Those methods are gone — reads no longer flow through the
domain. The domain repository does one thing: persist validated domain entities.

The query side: DTOs all the way

Here's the read path. No domain entities. No value object construction on the output path:

class GitHubRepoListQueryUseCaseImpl(
    private val queryRepository: GitHubRepoQueryRepository,
) : GitHubRepoListQueryUseCase {
    override suspend fun execute(
        pageNumber: Int,
        pageSize: Int,
    ): Either<GitHubRepoListQueryError, PageDto<GitHubRepoQueryDto>> =
        either {
            val validPageNumber =
                PageNumber
                    .of(pageNumber)
                    .mapLeft(GitHubRepoListQueryError::InvalidPageNumber)
                    .bind()
            val validPageSize =
                PageSize
                    .of(pageSize)
                    .mapLeft(GitHubRepoListQueryError::InvalidPageSize)
                    .bind()

            val limit = validPageSize.value
            val offset = (validPageNumber.value - 1) * validPageSize.value
            queryRepository.list(limit, offset).bind()
        }
}

The return type tells the story: Either<GitHubRepoListQueryError, PageDto<GitHubRepoQueryDto>>. Not
Page<GitHubRepo>. The query returns a PageDto of GitHubRepoQueryDto — a flat data class with no domain types:

data class GitHubRepoQueryDto(
    val id: Long,
    val owner: String,
    val name: String,
    val fullName: String,
    val description: String?,
    val language: String?,
    val stargazersCount: Int,
    val forksCount: Int,
    val isPrivate: Boolean,
    val createdAt: OffsetDateTime,
    val updatedAt: OffsetDateTime,
)

Plain types. Long, String, Int, Boolean. No GitHubRepoId, no GitHubOwner, no GitHubRepoName. The DTO is a
direct projection of the database row — no domain construction overhead.

The query repository: why it lives in the application layer

In Part 1, the
repository interface was defined in the domain layer — because the domain needs to express what persistence operations
it requires. That's still true for writes. GitHubRepoRepository.save() takes a domain entity and returns a domain
entity.

But the query repository is different:

interface GitHubRepoQueryRepository {
    suspend fun findById(id: Long): Either<GitHubRepoFindByIdQueryError, GitHubRepoQueryDto>

    suspend fun list(
        limit: Int,
        offset: Int,
    ): Either<GitHubRepoListQueryError, PageDto<GitHubRepoQueryDto>>
}

Two things stand out. First, the error types are the full sealed interfaces (GitHubRepoFindByIdQueryError,
GitHubRepoListQueryError), not just FetchFailed. The infrastructure implementation is responsible for resolving "not
found" — it queries the database and knows whether a row exists. The application layer handles input validation (
InvalidId). Each layer raises the errors within its scope.

Second, this interface lives in application/query/repository/, not domain/repository/. The reason is structural: it
takes primitives (Long, Int) and returns application-layer DTOs (GitHubRepoQueryDto, PageDto). It has no domain
types in its signature. Placing it in the domain layer would force the domain to know about GitHubRepoQueryDto — an
application-layer concept. That breaks the dependency rule.

The query repository is an application-layer port. Infrastructure implements it. The domain doesn't know it exists.

Pragmatic validation: reusing domain value objects

The query side doesn't construct domain entities — but it does reuse domain value objects for input validation. Look
at GitHubRepoFindByIdQueryUseCaseImpl:

class GitHubRepoFindByIdQueryUseCaseImpl(
    private val queryRepository: GitHubRepoQueryRepository,
) : GitHubRepoFindByIdQueryUseCase {
    override suspend fun execute(id: Long): Either<GitHubRepoFindByIdQueryError, GitHubRepoQueryDto> =
        either {
            val repoId = GitHubRepoId.of(id).mapLeft(GitHubRepoFindByIdQueryError::InvalidId).bind()
            queryRepository.findById(repoId.value).bind()
        }
}

GitHubRepoId.of(id) is a domain value object. The query uses it to validate that the ID is positive — the same rule
the write path enforces. But after validation, it extracts .value and passes the raw Long to the query repository.
The domain entity GitHubRepo is never constructed.

This is pragmatic CQRS. Domain validation rules (positive IDs, page size limits) are universal — they apply to reads and
writes equally. Duplicating that logic would be worse than reusing it. But domain entities — the full aggregate with
all its fields validated and wrapped — are only needed when writing.

The same pattern applies to pagination. PageNumber.of() and PageSize.of() enforce business constraints (minimum 1,
maximum 100). The query converts them to limit and offset — database concepts — and the query repository takes those
primitives directly.

Infrastructure: two repositories, one database

Both repositories read from and write to the same github_repo table. The split is logical, not physical.

The query repository implementation maps database records directly to DTOs:

@Repository
class GitHubRepoQueryRepositoryImpl(
    private val dsl: DSLContext,
) : GitHubRepoQueryRepository {

    override suspend fun findById(id: Long): Either<GitHubRepoFindByIdQueryError, GitHubRepoQueryDto> =
        either {
            val dto =
                Either
                    .catch {
                        Mono
                            .from(
                                dsl
                                    .selectFrom(GITHUB_REPO)
                                    .where(GITHUB_REPO.ID.eq(id)),
                            ).map { it.toQueryDto() }
                            .awaitSingleOrNull()
                    }.mapLeft { GitHubRepoFindByIdQueryError.FetchFailed(it.message ?: "Unknown error") }
                    .bind()

            ensureNotNull(dto) { GitHubRepoFindByIdQueryError.NotFound(id) }
        }

it.toQueryDto() maps a jOOQ GithubRepoRecord to GitHubRepoQueryDto. No domain entity involved. The database row
becomes a DTO in a single step. ensureNotNull from Arrow-kt handles the "not found" case — if the query returns
null, it raises NotFound directly. The application layer doesn't need to check for null; the infrastructure resolves
it.

Compare this with the write repository, which maps to a full domain entity through toDomain() — constructing value
objects, enforcing invariants. Two implementations of the same table, each optimized for its path.

Presentation: same pattern, different types

The controller now injects queries and commands as separate dependencies:

@RestController
@RequestMapping("/api/github-repos")
class GitHubRepoController(
    private val gitHubRepoListQueryUseCase: GitHubRepoListQueryUseCase,
    private val gitHubRepoFindByIdQueryUseCase: GitHubRepoFindByIdQueryUseCase,
    private val gitHubRepoSaveUseCase: GitHubRepoSaveUseCase,
) {

Read endpoints call queries. The write endpoint calls the command use case. The Either.fold pattern is identical:

@GetMapping("/{id}")
suspend fun findById(@PathVariable id: Long): ResponseEntity<*> =
    gitHubRepoFindByIdQueryUseCase.execute(id).fold(
        ifLeft = { error ->
            when (error) {
                is GitHubRepoFindByIdQueryError.InvalidId ->
                    ResponseEntity.badRequest().body(ErrorResponse(error.message))
                is GitHubRepoFindByIdQueryError.NotFound ->
                    ResponseEntity.notFound().build<Nothing>()
                is GitHubRepoFindByIdQueryError.FetchFailed -> {
                    logger.error("Failed to fetch GitHub repo (id=$id): ${error.message}")
                    ResponseEntity.internalServerError().body(ErrorResponse("Internal server error"))
                }
            }
        },
        ifRight = { dto ->
            ResponseEntity.ok(GitHubRepoResponse.fromQueryDto(dto))
        },
    )

The response DTO now has two factory methods: fromDomain() for commands (unwrapping value objects) and
fromQueryDto() for queries (direct field copy):

companion object {
    fun fromDomain(repo: GitHubRepo) =
        GitHubRepoResponse(
            id = repo.id.value,      // unwrap value object
            owner = repo.owner.value,
            // ...
        )

    fun fromQueryDto(dto: GitHubRepoQueryDto) =
        GitHubRepoResponse(
            id = dto.id,             // already a Long
            owner = dto.owner,
            // ...
        )
}

The same split applies to GraphQL. The mapper has GitHubRepoQueryDto.toGraphQL() for reads and
DomainGitHubRepo.toGraphQL() for writes. Different source types, same destination type. The presentation layer adapts
both paths to its protocol without knowing which path the data took to get there.

Tests: the specification still holds

Query tests mock the query repository. Command tests mock the domain repository. Each side has its own test fixtures:

class GitHubRepoListQueryUseCaseImplTest {
    private val queryRepository = mockk<GitHubRepoQueryRepository>()
    private val queryUseCase = GitHubRepoListQueryUseCaseImpl(queryRepository)

    @Test
    fun `execute returns Right with page when parameters are valid`() =
        runTest {
            val page = PageDto(totalCount = 1, items = listOf(sampleQueryDto()))
            coEvery { queryRepository.list(offset = 0, limit = 20) } returns Either.Right(page)

            queryUseCase.execute(1, 20).shouldBeRight(page)
        }

    @Test
    fun `execute returns Left InvalidPageNumber when pageNumber is 0`() =
        runTest {
            val error = queryUseCase.execute(0, 20).shouldBeLeft()
            error shouldBe GitHubRepoListQueryError.InvalidPageNumber(PageNumberError.BelowMinimum(0))
        }

    @Test
    fun `execute calculates correct offset for page 2`() =
        runTest {
            val page = PageDto(totalCount = 30, items = listOf(sampleQueryDto()))
            coEvery { queryRepository.list(offset = 20, limit = 20) } returns Either.Right(page)

            queryUseCase.execute(2, 20).shouldBeRight(page)
        }
}

Note the offset test. Page 2 with size 20 should produce offset = 20. This calculation —
(pageNumber - 1) * pageSize — happens in the query use case, not the repository. The repository receives limit and
offset as primitives. The business logic of pagination lives in the application layer; the database execution lives in
infrastructure.

The command tests are unchanged
from Part 2:

class GitHubRepoSaveUseCaseImplTest {
    private val repository = mockk<GitHubRepoRepository>()
    private val useCase = GitHubRepoSaveUseCaseImpl(repository)

    @Test
    fun `execute returns Left ValidationFailed when dto has invalid id`() =
        runTest {
            val dto = sampleDto().copy(id = 0L)
            val error = useCase.execute(dto).shouldBeLeft()
            error shouldBe GitHubRepoSaveError.ValidationFailed(GitHubError.InvalidId(0L))
        }
}

Domain validation on the write path. DTO projection on the read path. Each test verifies the right behavior for its side
of the split.

The honest tradeoff

CQRS adds types. Specifically:

Before (unified)	After (CQRS)
1 repository interface	2 repository interfaces
1 DTO type	2 DTO types (command + query)
3 use cases, 1 error hierarchy per use case	1 command + 2 queries, separate error hierarchies
1 infrastructure implementation	2 infrastructure implementations

That's roughly double the application-layer surface area for the same feature set. For a project with one entity, this
feels like overkill. For a project with dozens of entities, where read and write patterns diverge significantly —
different fields projected, different joins, different caching strategies — the separation pays for itself.

The key question is: will your read and write patterns diverge? If yes, CQRS gives you the seam to evolve them
independently. If no — if every read returns exactly the same shape as the domain entity — the unified model from Parts
1-3 is simpler and sufficient.

In this project, the divergence is modest. But the architecture is now ready for it to grow. Adding a search query that
joins across tables, a dashboard aggregation that returns computed fields, or a denormalized read model for high-traffic
endpoints — none of these will touch the command side or the domain.

The full source is on GitHub: https://github.com/wakita181009/clean-architecture-kotlin/tree/v3

Clean Architecture in Practice: Swapping Database Clients and Adding GraphQL in Kotlin

Tetsuya Wakita — Sat, 21 Feb 2026 03:46:45 +0000

How Clean Architecture delivered on its promise — infrastructure and presentation changed completely, domain and application stayed identical.

The claim every architecture post makes

Every Clean Architecture tutorial promises the same thing: swap your database, change your API protocol, and the business logic stays untouched.

Most tutorials stop there. They show the diagram, explain the dependency rule, and leave you to wonder whether it actually holds when you try it.

This article is the proof of concept.

Starting from the project in Part 1 — a Spring Boot API backed by Spring Data R2DBC — I made two changes:

Infrastructure: replaced Spring Data R2DBC with jOOQ for type-safe SQL
Presentation: added a GraphQL API using Netflix DGS alongside the existing REST endpoints

Here's the git diff for the domain module: nothing. For the application module: nothing. Every use case, every domain entity, every value object, every error type — unchanged.

Let's walk through what actually changed, and why everything else didn't need to.

What we're changing and why

The original infrastructure layer used Spring Data R2DBC with a generated entity class and a Spring repository interface. It worked — but the mapping was manual and the queries were limited to what Spring Data's derived query methods could express.

jOOQ generates a type-safe DSL from the database schema. Instead of r2dbcRepository.findById(id), you write dsl.selectFrom(GITHUB_REPO).where(GITHUB_REPO.ID.eq(id)). The table name and column names are compile-time constants. A typo in a column name is a build error.

For the API layer, GraphQL offers something REST doesn't: clients specify exactly the fields they need. Adding it shouldn't change anything about how the business logic works — it's just a new way to receive requests and send responses.

Infrastructure: replacing Spring Data with jOOQ

Configuration

The jOOQ setup lives in infrastructure — the only module that knows about databases:

@Configuration
@EnableTransactionManagement
class JooqConfig(
    private val cfi: ConnectionFactory,
) {
    @Bean
    fun dsl(): DSLContext =
        DSL.using(
            DSL
                .using(cfi)
                .configuration()
                .derive(
                    Settings()
                        .withRenderQuotedNames(RenderQuotedNames.NEVER)
                        .withRenderNameCase(RenderNameCase.LOWER),
                ),
        )

    @Bean
    fun transactionalOperator(): TransactionalOperator =
        TransactionalOperator.create(R2dbcTransactionManager(cfi))
}

DSLContext is initialized with the R2DBC ConnectionFactory — the same connection pool as before. jOOQ handles reactive execution through Reactor's Publisher API. The Settings configure lowercase, unquoted identifiers to match the PostgreSQL schema.

Code generation from the schema

jOOQ generates Kotlin classes directly from the Flyway migration SQL — the same SQL that was already in the project:

jooq {
    configuration {
        generator {
            name = "org.jooq.codegen.KotlinGenerator"
            database {
                name = "org.jooq.meta.extensions.ddl.DDLDatabase"
                properties {
                    property {
                        key = "scripts"
                        value = "src/main/resources/db/migration/*.sql"
                    }
                }
            }
        }
    }
}

This generates GITHUB_REPO as a typed table reference and GithubRepoRecord as a typed row class. No new schema files. No separate ORM mapping configuration. The SQL migration is the single source of truth.

Type-safe queries with the same Either wrapping

The repository implementation looks different from before, but the interface it implements — GitHubRepoRepository — is identical:

@Repository
class GitHubRepoRepositoryImpl(
    private val dsl: DSLContext,
) : GitHubRepoRepository {

    override suspend fun findById(id: GitHubRepoId): Either<GitHubError, GitHubRepo> =
        either {
            val record =
                Either
                    .catch {
                        Mono
                            .from(
                                dsl
                                    .selectFrom(GITHUB_REPO)
                                    .where(GITHUB_REPO.ID.eq(id.value)),
                            ).map { it.toDomain() }
                            .awaitSingleOrNull()
                    }.mapLeft { GitHubError.RepositoryError("Failed to find repo: ${it.message}", it) }
                    .bind()
            if (record == null) raise(GitHubError.NotFound(id))
            record
        }

GITHUB_REPO.ID is a typed column reference generated from the schema. .eq(id.value) is type-checked — passing a String where a Long is expected won't compile.

The error wrapping pattern is the same as before: Either.catch { } captures any thrown exception, mapLeft converts it to a GitHubError.RepositoryError, and .bind() short-circuits the either { } block on failure.

Upsert with jOOQ DSL

The save operation benefits from jOOQ's expressive SQL DSL for the INSERT ... ON CONFLICT upsert:

override suspend fun save(repo: GitHubRepo): Either<GitHubError, GitHubRepo> =
    Either
        .catch {
            Mono
                .from(
                    dsl
                        .insertInto(GITHUB_REPO)
                        .set(GITHUB_REPO.ID, repo.id.value)
                        .set(GITHUB_REPO.OWNER, repo.owner.value)
                        // ... remaining fields ...
                        .onConflict(GITHUB_REPO.ID)
                        .doUpdate()
                        .set(GITHUB_REPO.OWNER, excluded(GITHUB_REPO.OWNER))
                        // ... update fields ...
                        .returning(),
                ).awaitSingle()
                .toDomain()
        }.mapLeft { GitHubError.RepositoryError("Failed to save repo: ${it.message}", it) }

.onConflict(GITHUB_REPO.ID).doUpdate() is standard SQL upsert semantics expressed as Kotlin. excluded(GITHUB_REPO.OWNER) references the value from the VALUES clause that was excluded by the conflict — the jOOQ equivalent of PostgreSQL's EXCLUDED.owner. The column references are compile-time constants. Mistype GITHUB_REPO.OWNR and the build fails.

The domain GitHubRepo entity is unchanged. The toDomain() mapping reads from GithubRepoRecord instead of the old Spring Data entity — but the output is the same domain object.

Presentation: adding GraphQL with Netflix DGS

Schema-first with DGS

Netflix DGS (Domain Graph Service) takes a schema-first approach. The GraphQL schema lives in presentation/src/main/resources/schema/github.graphqls:

scalar Long
scalar DateTime

type Query {
    githubRepo(id: Long!): GitHubRepo
    githubRepos(pageNumber: Int = 1, pageSize: Int = 20): GitHubRepoPage!
}

type Mutation {
    saveGitHubRepo(input: GitHubRepoInput!): GitHubRepo!
}

type GitHubRepo {
    id: Long!
    owner: String!
    name: String!
    fullName: String!
    description: String
    language: String
    stargazersCount: Int!
    forksCount: Int!
    isPrivate: Boolean!
    createdAt: DateTime!
    updatedAt: DateTime!
}

input GitHubRepoInput {
    id: Long!
    owner: String!
    # ...
}

The ID type is replaced with Long — keeping it consistent with the domain's GitHubRepoId(Long). DateTime maps to OffsetDateTime in Kotlin. Both are custom scalars registered via graphql-java-extended-scalars:

@DgsComponent
class ScalarConfig {
    @DgsRuntimeWiring
    fun addScalar(builder: RuntimeWiring.Builder): RuntimeWiring.Builder =
        builder
            .scalar(ExtendedScalars.GraphQLLong)
            .scalar(ExtendedScalars.DateTime)
}

DGS codegen generates Kotlin data classes from this schema at build time — GitHubRepo, GitHubRepoPage, GitHubRepoInput — parallel to how jOOQ generates classes from the SQL schema. The schema is the source of truth; the generated types are implementation details.

The DataFetcher: Either.fold as GraphQL adapter

GitHubRepoDataFetcher is the GraphQL equivalent of the REST controller. It receives requests, calls use cases, and translates Either results to GraphQL responses:

@DgsComponent
class GitHubRepoDataFetcher(
    private val gitHubRepoListUseCase: GitHubRepoListUseCase,
    private val gitHubRepoFindByIdUseCase: GitHubRepoFindByIdUseCase,
    private val gitHubRepoSaveUseCase: GitHubRepoSaveUseCase,
) {
    @DgsQuery(field = "githubRepo")
    suspend fun githubRepo(
        @InputArgument id: Long,
    ): GitHubRepo? =
        gitHubRepoFindByIdUseCase
            .execute(id)
            .fold(
                ifLeft = { error ->
                    when (error) {
                        is GitHubRepoFindByIdError.NotFound -> null
                        is GitHubRepoFindByIdError.InvalidId,
                        is GitHubRepoFindByIdError.FetchFailed,
                        -> throw GraphQLException(error.message)
                    }
                },
                ifRight = { repo -> repo.toGraphQL() },
            )

    @DgsQuery(field = "githubRepos")
    suspend fun githubRepos(
        @InputArgument pageNumber: Int = 1,
        @InputArgument pageSize: Int = 20,
    ): GitHubRepoPage =
        gitHubRepoListUseCase.execute(pageNumber, pageSize).fold(
            ifLeft = { error -> throw GraphQLException(error.message) },
            ifRight = { page -> page.toGraphQL() },
        )

    @DgsMutation(field = "saveGitHubRepo")
    suspend fun saveGitHubRepo(
        @InputArgument input: GitHubRepoInput,
    ): GitHubRepo =
        gitHubRepoSaveUseCase.execute(input.toDto()).fold(
            ifLeft = { error -> throw GraphQLException(error.message) },
            ifRight = { repo -> repo.toGraphQL() },
        )
}

The pattern is identical to the REST controller: call the use case, fold on the Either, map Right to the response type, handle Left based on the error type. The only difference is the output format — ResponseEntity becomes a GraphQL type or a GraphQLException.

Because the schema types id as Long!, DGS handles the coercion automatically. There's no need to manually parse or validate the ID in the DataFetcher — the type system does it.

Compare githubRepo with the REST findById:

REST: NotFound → ResponseEntity.notFound().build()
GraphQL: NotFound → null (GraphQL convention for missing nullable fields)
REST: FetchFailed → ResponseEntity.badRequest()
GraphQL: FetchFailed → throw GraphQLException(error.message)

Different protocols, different conventions — same use case, same error types, same business logic.

The mapper: same pattern as REST DTOs

Type conversion between domain objects and GraphQL types follows the same extension function pattern as the REST DTOs:

fun DomainGitHubRepo.toGraphQL() =
    GitHubRepo(
        id = id.value,       // Long — matches scalar Long in schema
        owner = owner.value,
        name = name.value,
        fullName = fullName,
        // ...
    )

fun Page<DomainGitHubRepo>.toGraphQL() =
    GitHubRepoPage(
        items = items.map { it.toGraphQL() },
        totalCount = totalCount,
    )

fun GitHubRepoInput.toDto() =
    GitHubRepoDto(
        id = id,
        owner = owner,
        name = name,
        // ...
    )

GitHubRepo here is the DGS-generated GraphQL type. DomainGitHubRepo is the domain entity — aliased to avoid the name collision. The mapper sits entirely within presentation, converting between what GraphQL needs and what the domain provides.

GitHubRepoInput.toDto() produces a GitHubRepoDto — a plain data class in the application layer. The DTO's toDomain() method then performs value-object construction with Arrow's either { } DSL, so validation errors propagate as Left through the use case rather than escaping as exceptions.

What didn't change: the proof

Here's the complete list of files modified across domain and application:

(none)

Every use case interface and implementation: unchanged. Every domain entity and value object: unchanged. Every error type: unchanged. Every application test from Part 2: still passing, without modification. Every domain test from Part 2: still passing, without modification.

The GitHubRepoListUseCase doesn't know whether its results go to a REST response or a GraphQL query. GitHubRepoFindByIdUseCaseImpl doesn't know whether the repository behind it uses Spring Data or jOOQ. PageSize.of(101) returns Left(PageSizeError.AboveMaximum(101)) regardless of what database is running.

This is what the dependency rule buys you. Infrastructure and presentation know about the domain. The domain knows about neither.

The pattern that made this possible

Three design choices made both changes straightforward:

1. The repository interface is the only contract. Infrastructure implements GitHubRepoRepository. Whether the implementation uses jOOQ, Spring Data, or a flat file doesn't matter — as long as it returns the right Either<GitHubError, T>.

2. Presentation layers are pure adapters. Both the REST controller and the GraphQL DataFetcher do exactly the same thing: receive a request, call a use case, translate the Either result to the protocol's response format. Adding a new protocol means adding a new adapter — not changing anything that exists.

3. Either.fold is protocol-neutral. The use case returns Either<AppError, DomainResult>. What you do with Left and Right is entirely up to the presentation layer. REST maps them to HTTP status codes. GraphQL maps them to nullable fields and exceptions. The use case doesn't need to know which.

The architecture didn't just survive the change. It made the change straightforward.

The full source is on GitHub: https://github.com/wakita181009/clean-architecture-kotlin/tree/v2

Why Your Kotlin Tests Are Slow: How Clean Architecture Enables Sub-Second Unit Testing

Tetsuya Wakita — Sat, 21 Feb 2026 02:57:17 +0000

How Clean Architecture makes domain and application tests run in milliseconds — with no database, no Spring, and no excuses.

The test that shouldn't need a database

Here's a test I've seen too many times:

@SpringBootTest
class PageSizeValidationTest {
    @Autowired lateinit var repoService: GitHubRepoService

    @Test
    fun `should reject page size over 100`() {
        assertThrows<IllegalArgumentException> {
            repoService.list(pageSize = 101)
        }
    }
}

This test checks one thing: whether 101 is rejected as a page size. To do it, Spring boots up, all beans are wired, the database connection pool is initialized. Eight seconds of startup for a boundary check that has nothing to do with any of it.

The problem isn't the test. It's that the business logic is baked into a @Service that can't exist without the container.

Clean Architecture solves this with a single structural rule: domain and application layers have zero external dependencies. No Spring. No database. No infrastructure of any kind.

That rule has a direct consequence for testing: the entire business logic of the system — every rule, every validation, every failure case — can be tested with pure Kotlin. No framework startup. No database connection. Just code and assertions.

Domain + application = the specification

The key idea from Part 1: the application module is a direct translation of the product spec into Kotlin. Read the use case interfaces and you're reading the requirements. Read the domain errors and you're reading the failure scenarios the spec describes.

Tests make this claim verifiable. Because domain and application have no external dependencies, every business rule is a plain Kotlin test — write it, run it. Two workflows follow naturally:

Specification-driven development: Define use case interfaces and domain errors from the requirements document. Tests validate the implementation matches the spec.

Test-driven development: Write the use case test first — against the interface — before implementing anything. Infrastructure comes last.

Layer 1: Domain tests — pure Kotlin, zero dependencies

Domain tests have no mocks, no Spring, no database. The only imports are Kotest, kotest-property, and the Arrow assertions extension. Some tests use runTest — not because they touch coroutines, but because checkAll is a suspend function.

There's a natural fit between Either and property-based testing. When every code path must return Either<E, A>, the test question shifts from "does it handle the edge case?" to "does the invariant hold for the entire input space?" Property-based testing is the direct answer.

Property-based testing for value object invariants

The most natural test for a value object isn't "does it reject 101?" — it's "does it reject every value above 100?" Example-based tests can only sample a few points. Property-based tests state the invariant and verify it holds for hundreds of generated inputs.

PageSize enforces a business rule: values must be between 1 and 100. Instead of picking specific values, the tests express what must be true for any value in each region:

class PageSizeTest {
    @Test
    fun `of returns Right with correct value for any value in valid range`() =
        runTest {
            checkAll(Arb.int(PageSize.MIN_VALUE..PageSize.MAX_VALUE)) { n ->
                PageSize.of(n).shouldBeRight().value shouldBe n
            }
        }

    @Test
    fun `of returns Left BelowMinimum for any value below minimum`() =
        runTest {
            checkAll(Arb.int(max = PageSize.MIN_VALUE - 1)) { n ->
                PageSize.of(n).shouldBeLeft() shouldBe PageSizeError.BelowMinimum(n)
            }
        }

    @Test
    fun `of returns Left AboveMaximum for any value above maximum`() =
        runTest {
            checkAll(Arb.int(min = PageSize.MAX_VALUE + 1)) { n ->
                PageSize.of(n).shouldBeLeft() shouldBe PageSizeError.AboveMaximum(n)
            }
        }
}

Arb.int(range) is an arbitrary — a generator that produces random integers in the specified range. checkAll runs 1000 iterations by default (configurable), sampling across the entire space. The first test doesn't just check 1 and 100 — it checks that of(n).value == n holds for any valid integer.

shouldBeRight() and shouldBeLeft() from kotest-assertions-arrow unwrap the Either and assert its branch in a single call.

No @SpringBootTest. No @ExtendWith. No application context. Every test here runs in under 10ms total.

Testing error messages as contracts

Error messages that flow to API clients are part of the interface. These are deterministic — no property generation needed:

@Test
fun `BelowMinimum error message contains the invalid value`() {
    val error = PageSizeError.BelowMinimum(0)
    error.message shouldBe "Page size must be at least ${PageSize.MIN_VALUE}, but was 0"
}

@Test
fun `AboveMaximum error message contains the invalid value`() {
    val error = PageSizeError.AboveMaximum(200)
    error.message shouldBe "Page size must be at most ${PageSize.MAX_VALUE}, but was 200"
}

If someone changes the format, the test fails. If the minimum value constant changes, the message updates automatically. The test pins the contract.

Property-based testing for string value objects

String-valued objects like GitHubOwner have a harder invariant to exhaustively sample: "any non-blank string is valid, any blank string is not." Property tests handle this without hand-picking examples:

class GitHubOwnerTest {
    @Test
    fun `of returns Right with correct value for any non-blank string`() =
        runTest {
            checkAll(Arb.string(1..100).filter { it.isNotBlank() }) { s ->
                GitHubOwner.of(s).shouldBeRight().value shouldBe s
            }
        }

    @Test
    fun `of returns Left InvalidOwner for any blank string`() =
        runTest {
            checkAll(Arb.of("", " ", "   ", "\t", "\n", "\r\n", "\u00A0")) { s ->
                GitHubOwner.of(s).shouldBeLeft()
                    .shouldBeInstanceOf<GitHubError.InvalidOwner>()
            }
        }
}

The invalid-input test uses Arb.of(...) with an explicit set covering regular spaces, tabs, newlines, and Unicode non-breaking space (\u00A0). A blank-string check that only tests "" and " " will miss the unicode edge case. The set makes that coverage explicit and exhaustive for the failure class.

Testing numeric value objects

GitHubRepoId.of(Long) validates the domain invariant: IDs must be positive. The same property pattern applies:

class GitHubRepoIdTest {
    @Test
    fun `of returns Right with correct value for any positive id`() =
        runTest {
            checkAll(Arb.long(min = 1L)) { n ->
                GitHubRepoId.of(n).shouldBeRight().value shouldBe n
            }
        }

    @Test
    fun `of returns Left InvalidId for any non-positive id`() =
        runTest {
            checkAll(Arb.long(max = 0L)) { n ->
                GitHubRepoId.of(n).shouldBeLeft()
                    .shouldBeInstanceOf<GitHubError.InvalidId>()
            }
        }

    @Test
    fun `InvalidId error message contains the invalid value`() {
        val error = GitHubError.InvalidId(-1L)
        error.message shouldBe "Invalid GitHub repo ID: -1 (must be positive)"
    }

    @Test
    fun `NotFound error message contains the id`() {
        val error = GitHubError.NotFound(GitHubRepoId(42L))
        error.message shouldBe "GitHub repo not found: 42"
    }
}

Arb.long(min = 1L) generates random positive longs across the full range — not just 1L and 9999999L. If the validation logic had an off-by-one at Long.MAX_VALUE, a hand-picked example would never catch it. A property test would.

Layer 2: Application tests — the specification in executable form

Domain tests cover what values are legal. Application tests cover what the system does with legal and illegal values — and what callers see when it fails.

Use case tests are where specification-driven development becomes concrete. These tests describe what each operation does, in terms of the domain — with no database, no Spring, and no HTTP. Unlike domain tests, application tests use specific values: they're verifying error mapping, not input ranges.

Constructing use cases directly

class GitHubRepoListUseCaseImplTest {
    private val repository = mockk<GitHubRepoRepository>()
    private val useCase = GitHubRepoListUseCaseImpl(repository)

GitHubRepoListUseCaseImpl is a plain Kotlin class. Construct it with a mocked repository interface and it's ready to test. No Spring context, no bean factory, no @Autowired.

This is only possible because GitHubRepoListUseCaseImpl has no @Service annotation and no framework imports. It's a class — you instantiate classes with constructors.

Testing the happy path

@Test
fun `execute returns Right with page when parameters are valid`() = runTest {
    val page = Page(totalCount = 1, items = listOf(sampleRepo()))
    coEvery { repository.list(any(), any()) } returns Either.Right(page)

    useCase.execute(1, 20).shouldBeRight(page)
}

runTest from kotlinx-coroutines-test runs suspend functions synchronously — no thread management needed. coEvery stubs the suspend fun list(...) call with a predefined Either.Right.

Testing validation errors — the repository is never called

Input validation fires inside the either { } block before any repository call. Tests for invalid input don't configure the mock at all:

@Test
fun `execute returns Left InvalidPageNumber when pageNumber is 0`() = runTest {
    val error = useCase.execute(0, 20).shouldBeLeft()
    error shouldBe GitHubRepoListError.InvalidPageNumber(PageNumberError.BelowMinimum(0))
}

@Test
fun `execute returns Left InvalidPageSize when pageSize exceeds 100`() = runTest {
    val error = useCase.execute(1, 101).shouldBeLeft()
    error shouldBe GitHubRepoListError.InvalidPageSize(PageSizeError.AboveMaximum(101))
}

The either { } + .bind() chain short-circuits at the first Left. The repository is never invoked. These tests confirm that invalid inputs are rejected at the use case boundary — before anything hits the database.

Testing error mapping

Each use case maps domain errors to application-level errors. The mapping is part of the spec — it determines what the caller sees when something goes wrong:

@Test
fun `execute returns Left FetchFailed when repository returns error`() = runTest {
    val domainError = GitHubError.RepositoryError("DB error")
    coEvery { repository.list(any(), any()) } returns Either.Left(domainError)

    val error = useCase.execute(1, 20).shouldBeLeft()
    error shouldBe GitHubRepoListError.FetchFailed(domainError)
}

For FindById, the mapping is conditional — the same domain layer produces different application errors depending on the failure type:

@Test
fun `execute returns Left InvalidId when id is not positive`() =
    runTest {
        val error = useCase.execute(0L).shouldBeLeft()
        error shouldBe GitHubRepoFindByIdError.InvalidId(GitHubError.InvalidId(0L))
    }

@Test
fun `execute returns Left NotFound when repo is not found`() =
    runTest {
        val domainError = GitHubError.NotFound(GitHubRepoId(1L))
        coEvery { repository.findById(any()) } returns Either.Left(domainError)

        val error = useCase.execute(1L).shouldBeLeft()
        error shouldBe GitHubRepoFindByIdError.NotFound(domainError)
    }

@Test
fun `execute returns Left FetchFailed when RepositoryError occurs`() =
    runTest {
        val domainError = GitHubError.RepositoryError("DB connection failed")
        coEvery { repository.findById(any()) } returns Either.Left(domainError)

        val error = useCase.execute(1L).shouldBeLeft()
        error shouldBe GitHubRepoFindByIdError.FetchFailed(domainError)
    }

GitHubRepoFindByIdError.InvalidId fires before the repository is ever called — ID validation is a use case responsibility, not infrastructure's. For valid IDs: GitHubError.NotFound → GitHubRepoFindByIdError.NotFound; GitHubError.RepositoryError → GitHubRepoFindByIdError.FetchFailed. Three domain outcomes. Three tests. The mapping is explicit, typed, and verified.

The development workflow this enables

Here's the concrete workflow that becomes available when domain and application have no external dependencies:

Step 1: The product spec says "users can list repositories, with pagination between 1 and 100 items per page."

Step 2: Write the use case interface and domain errors directly from the spec — before any implementation:

interface GitHubRepoListUseCase {
    suspend fun execute(pageNumber: Int, pageSize: Int): Either<GitHubRepoListError, Page<GitHubRepo>>
}

sealed interface GitHubRepoListError : ApplicationError {
    data class InvalidPageNumber(val error: PageNumberError) : GitHubRepoListError
    data class InvalidPageSize(val error: PageSizeError) : GitHubRepoListError
    data class FetchFailed(val cause: GitHubError) : GitHubRepoListError
}

Step 3: Write the tests. Value objects use property-based tests to verify invariants across the full input space. Use cases use specific values to verify that error types and mappings match the spec:

// Spec: valid pagination returns a page of results
useCase.execute(1, 20).shouldBeRight(page)

// Spec: page number must be at least 1
useCase.execute(0, 20).shouldBeLeft() // GitHubRepoListError.InvalidPageNumber

// Spec: page size must not exceed 100
useCase.execute(1, 101).shouldBeLeft() // GitHubRepoListError.InvalidPageSize

Step 4: Implement the use case to make the tests pass. The repository is a mock — no database needed.

Step 5: Implement the infrastructure. Wire it together. Run the integration tests.

The business logic is validated before a single line of infrastructure code is written. The tests are the spec. The spec is the tests.

What comes after: infrastructure tests

The one layer not covered here is infrastructure — actual database queries require Testcontainers or a real PostgreSQL instance. Those tests are slower and heavier by nature.

But they're also contained. Domain and application tests never touch the database. The infrastructure layer runs in isolation against a real database. Each layer has the right test strategy for its responsibilities.

The real value isn't just speed. It's that the barrier to writing a test is zero. There's no decision to make about whether a test is "worth spinning up the container for." If it's a business rule, it has a test. If it has a test, it runs in milliseconds. There's no tradeoff.

The full source is on GitHub: https://github.com/wakita181009/clean-architecture-kotlin/tree/v1

Forem: Tetsuya Wakita

I Rewrote python-dateutil in Rust — Even a Naive Port Is Up to 94x Faster

python-dateutil Is Everywhere — and It's Pure Python

The Approach: Module-by-Module Rewrite via PyO3

Benchmark Results

At a Glance

ISO Parsing — Up to 23.5x Faster

RelativeDelta — Up to 18.7x Faster

RRule (Recurrence Rules) — Up to 20x Faster

Timezone — Up to 94.3x Faster (Cache-Inclusive)

Easter — Up to 6.2x Faster

Why Is It Fast? It's Just Rust Being Rust

isoparse: Byte-Level Parsing (23.5x)

RelativeDelta: Fixed Struct vs Dynamic Attributes (18.7x)

RRule: Same Algorithm, Less Overhead (9.1x–20x)

What's Next: v1 — Actually Optimized Rust

What I Learned Building This

PyO3 Is Remarkably Ergonomic

A Faithful Port Is a Valid Strategy

Where the Overhead Actually Is

Try It

Zod vs Typia vs AJV — I Built a Build Plugin That Makes Zod 60x Faster With Zero Code Changes

autoDiscover: How It Works

Step 1: Regex Pre-filter

Step 2: Execute and Inspect Exports

Step 3: Compile to Optimized Validators

Step 4: AST-Based Source Replacement

Build Output

Scoping

Two-Phase Validation: The Fast Path

Phase 1: Boolean Expression Chain

Phase 2: Error-Collecting Path (Slow Path)

Fast Path Eligibility

The 5-Way Benchmark

Full Results

The Scoreboard

The check Command: Know Your Coverage

CI Integration

Framework Integration

What I Learned from the Competition

Get Started

Methodology

Why Is Zod v4 Fast — and Where Is Its Ceiling?

Zod v3: The Interpreter Model

Zod v4: A New Architecture

The Hidden JIT: $ZodObjectJIT

The Doc Class: Runtime Code Generation

How $ZodObjectJIT Works

Environment Detection

What JIT Covers (and What It Doesn't)

Benchmarks: Where JIT Helps

Objects and Recursive Structures: JIT Territory

Primitives: Architecture Trade-off Visible

Collections: No JIT (Yet)

Invalid Inputs: Error Construction Dominates

Real-World Schemas

From JIT to AOT: Taking It Further

Where AOT Matters Most

Trade-offs

When to Use What

Try Zod AOT

Methodology

Build Google Apps Script with Any Bundler: Vite, Rollup, esbuild, webpack, and Bun

The problem with modern bundlers in Google Apps Script

What changed

Why I rebuilt it with unplugin

@gas-plugin/unplugin: one plugin, any bundler

Vite

Rollup

esbuild

webpack

Bun

How autoGlobals and globals work

@gas-plugin/cli: scaffold a project in seconds

Why this exists when google/aside already exists

google/aside is a batteries-included starter

@gas-plugin is a smaller, composable alternative

Migration from gas-vite-plugin

Why I think this matters

Links

The `check` Command: Know Your Coverage

The Hidden JIT: `$ZodObjectJIT`

`@gas-plugin/unplugin`: one plugin, any bundler

How `autoGlobals` and `globals` work

`@gas-plugin/cli`: scaffold a project in seconds

Why this exists when `google/aside` already exists

`google/aside` is a batteries-included starter

`@gas-plugin` is a smaller, composable alternative

Migration from `gas-vite-plugin`

`globals` — when tree-shaking removes too much

Usage — wrap with `compile()`