DEV Community: websilvercraft

Python's match-case is not a switch statement (it's better)

websilvercraft — Tue, 18 Aug 2026 08:36:00 +0000

When match-case landed in Python 3.10, half the internet said "finally, Python has switch." That framing undersells it badly. If you use match as a switch, you'll conclude it's pointless — if/elif did that already.

What match actually does: it checks the shape of your data and destructures it in the same step. That's a different tool, and for certain code — API payloads, command parsers, state machines — it's a dramatically better one.

The switch part (30 seconds)

Yes, it does the boring thing:

match command:
    case "quit":
        save_and_exit()
    case "help":
        show_help()
    case _:                    # wildcard: matches anything
        print(f"Unknown command: {command}")

Fine. if/elif is just as good here. Moving on.

The real feature: matching structure

Say you're handling webhook events. The if version:

def handle(event):
    if isinstance(event, dict) and event.get("type") == "user.created":
        payload = event.get("payload")
        if payload is not None:
            create_user(payload)
    elif isinstance(event, dict) and event.get("type") == "invoice.failed":
        ...

The match version says the same thing the way you'd describe it out loud:

def handle(event):
    match event:
        case {"type": "user.created", "payload": payload}:
            create_user(payload)
        case {"type": "invoice.failed", "invoice_id": inv_id}:
            alert_finance(inv_id)
        case {"type": str(other_type)}:
            log.warning("unhandled event type %s", other_type)
        case _:
            raise ValueError(f"malformed event: {event!r}")

Each case simultaneously:

checks the value is a dict,
checks the keys and any literal values,
binds the parts you care about to names (payload, inv_id).

The type check, the key check, and the unpacking collapse into one readable line. Extra keys in the dict are ignored — exactly what you want for API payloads that grow fields over time.

Sequences, classes, and guards

Sequences destructure like unpacking, with literals mixed in:

match args:
    case []:
        show_usage()
    case ["--version"]:
        print(VERSION)
    case ["run", script, *rest]:
        run(script, extra_args=rest)

Class patterns match attributes — clean over dataclasses:

@dataclass
class Click:
    x: int
    y: int
    button: str = "left"

match event:
    case Click(x=0, y=0):
        print("origin clicked")
    case Click(x=x, y=y, button="right"):
        open_context_menu(x, y)
    case KeyPress(key="q"):
        quit()

Guards bolt a boolean condition onto a structural match:

match order:
    case {"items": items, "total": total} if total > 10_000:
        require_manual_review(order)
    case {"items": []}:
        raise EmptyOrderError

Alternatives with | share one body:

case "y" | "yes" | "ok":
    proceed()

The classic gotcha

A bare name in a pattern is a capture, not a comparison:

RED = "red"

match color:
    case RED:          # does NOT compare against "red" —
        stop()         # it matches ANYTHING and rebinds RED to it
    case "blue":       # Python even raises SyntaxError here:
        go()           # "name capture 'RED' makes remaining patterns unreachable"

To compare against a constant, use a dotted name — that's the rule the language chose:

class Color:
    RED = "red"
    BLUE = "blue"

match color:
    case Color.RED:      # dotted = lookup and compare ✓
        stop()
    case Color.BLUE:
        go()

Ruff and recent Python versions warn about suspicious always-true capture patterns, but knowing the rule beats trusting the linter.

When to still use if/elif

Comparing one value against a few literals with no destructuring — if is simpler and works on every Python version.
Conditions on different variables per branch (if x > 3 ... elif name == "bob") — that's not what match is for.
Your code must run on Python < 3.10.

The sweet spot for match is exactly: "the shape of this data determines what happens next." Parsers, event handlers, recursive tree walks, REPL commands. In that territory it deletes entire pyramids of isinstance/.get() boilerplate.

The Python GIL, explained without the hand-waving

websilvercraft — Fri, 14 Aug 2026 07:27:00 +0000

Every Python developer eventually hits this conversation:

"Just use threads to speed it up."
"Python threads don't run in parallel. The GIL."
"So threads are useless in Python?"
"No, they're great for—"
"You just said they don't run in parallel!"

Both people are half right. Here's the actual model, and the decision rules that follow from it.

What the GIL actually is

The Global Interpreter Lock is a mutex inside CPython that allows only one thread to execute Python bytecode at any moment. Ten threads can exist, be scheduled by the OS, and hold live stack frames — but only the thread holding the GIL advances Python code. The interpreter forces a handoff every few milliseconds, so threads interleave rapidly rather than run simultaneously.

Why does CPython have it? Memory management. CPython uses reference counting; every object carries a counter that threads would corrupt if two of them incremented/decremented it at once. One big lock around the interpreter makes every refcount operation safe — and, as a bonus, makes single-threaded code (the vast majority of Python ever run) faster than fine-grained locking would.

The part everyone skips: the GIL is released constantly

The GIL is only required while executing Python bytecode. Blocking operations release it:

Waiting on I/O — network calls, file reads, time.sleep, database queries: the waiting thread gives up the GIL and another thread runs.
Heavy C-extension work — NumPy matrix multiplication, hashing, compression, image transforms in Pillow: these release the GIL around their C loops.

This is why the "threads are useless" take is wrong. The real rule:

Threads give you parallel waiting, not parallel computing.

See it in numbers

CPU-bound work — threads buy you nothing:

import time
from concurrent.futures import ThreadPoolExecutor

def crunch():
    return sum(i * i for i in range(10_000_000))

start = time.perf_counter()
crunch(); crunch()
print(f"serial:  {time.perf_counter() - start:.1f}s")   # ~2.0s

start = time.perf_counter()
with ThreadPoolExecutor() as pool:
    list(pool.map(lambda _: crunch(), range(2)))
print(f"threads: {time.perf_counter() - start:.1f}s")   # ~2.0s — no gain

I/O-bound work — threads shine:

import urllib.request

def fetch(url):
    return urllib.request.urlopen(url).read()

urls = ["https://example.com"] * 20

# serial: ~20 × latency.  threads: ~1 × latency.
with ThreadPoolExecutor(max_workers=20) as pool:
    pages = list(pool.map(fetch, urls))

Twenty threads all waiting on sockets coexist happily — the GIL is free while they wait.

The decision table

Your workload	Use	Why
Many network calls / file ops	`threading` or `asyncio`	GIL released while waiting
Very many (1000s) of connections	`asyncio`	Threads get heavy; the event loop multiplexes one thread
CPU-heavy pure Python	`multiprocessing` / `ProcessPoolExecutor`	Each process has its own GIL
CPU-heavy numeric code	NumPy / Numba / Cython	C code releases the GIL, parallelism inside one process
Mixed pipeline	Processes for compute + threads/async for I/O	Compose them

The one-liner upgrade when you need real parallelism:

from concurrent.futures import ProcessPoolExecutor  # was ThreadPoolExecutor

with ProcessPoolExecutor() as pool:                 # same API, real cores
    results = list(pool.map(crunch, range(8)))

Mind the caveats: processes don't share memory, arguments get pickled across, and on Windows/macOS you need the if __name__ == "__main__": guard.

"But I heard they're removing the GIL"

Sort of, and it's genuinely exciting — but slowly. PEP 703 made a free-threaded build of CPython official as an experimental option (the python3.13t/3.14t builds). It removes the GIL at the cost of some single-threaded overhead, and it only pays off once the packages you depend on ship free-threaded wheels. The default CPython you get from python.org or your distro still has the GIL, and will for years.

So for code you ship today, the mental model above is the one that matters.

What to remember

The GIL serializes Python bytecode, not your program's waiting time.
Threads are for I/O-bound work. They're not broken; they're specialized.
Processes (or C extensions) are for CPU-bound work.
asyncio competes with threads for I/O concurrency, not with processes for parallelism.

ModuleNotFoundError: No module named 'X' — a debugging checklist that actually works

websilvercraft — Tue, 11 Aug 2026 07:18:00 +0000

You ran pip install pandas. You're sure you did. And yet:

Traceback (most recent call last):
  File "analysis.py", line 1, in <module>
    import pandas
ModuleNotFoundError: No module named 'pandas'

This is one of the most-Googled Python errors, and it almost never means what beginners think it means ("pip is broken"). It means one specific thing: the interpreter that ran your script can't see the package — which is usually a different interpreter than the one pip installed into.

Here's the checklist I use, in the order that catches the most cases fastest.

1. Find out which Python is actually running

The single most useful command in this situation:

python -c "import sys; print(sys.executable)"

Then compare it with where pip installed the package:

pip show pandas   # look at the Location: line

If sys.executable says /usr/bin/python3 but pip installed into ~/venvs/myproject/..., there's your bug. You have multiple Pythons, and the wrong one is running your code.

The bulletproof fix — install with the same interpreter that runs your script:

python -m pip install pandas

Using python -m pip instead of bare pip removes an entire category of this error, because pip on your PATH can belong to a different Python than python does.

2. Is your virtual environment actually active?

Everyone forgets this at least weekly:

source .venv/bin/activate      # macOS/Linux
.venv\Scripts\activate         # Windows
which python                   # should point inside .venv

Special cases that bite people:

IDEs run their own interpreter. VS Code and PyCharm pick an interpreter per-project — check the interpreter selector (bottom bar in VS Code) and point it at your venv.
Jupyter kernels are their own thing. The notebook can run a completely different environment than your terminal. !{sys.executable} -m pip install pandas inside a cell installs into the kernel's environment, guaranteed.
sudo pip install installs somewhere else. Don't. Use a venv.

3. Check for name shadowing (the sneaky one)

If the missing module is one you know is installed — or worse, part of the standard library — look at your own filenames:

myproject/
├── random.py        <- congratulations, you've shadowed the stdlib
└── main.py          <- 'import random' now imports YOUR file

A local file named random.py, queue.py, email.py, or test.py silently wins over the real module and produces baffling errors — sometimes ModuleNotFoundError for things the real module imports internally, sometimes AttributeError. The same happens with a folder named like a package you installed.

Quick diagnosis:

import random
print(random.__file__)   # is this YOUR file? rename it.

4. Import name ≠ install name

Some packages install under one name and import under another:

You install	You import
`pip install pillow`	`import PIL`
`pip install beautifulsoup4`	`import bs4`
`pip install opencv-python`	`import cv2`
`pip install scikit-learn`	`import sklearn`
`pip install pyyaml`	`import yaml`

If you're staring at No module named 'PIL', installing a package literally named PIL is not the fix (and may install something malicious — typosquatting on exactly this confusion is a known attack vector). Check the package's PyPI page for the correct pairing.

5. Importing your own code? It's a path problem

For your own modules, ModuleNotFoundError means the directory containing the module isn't on sys.path:

import sys
print(sys.path)  # the directories Python searches, in order

The clean fixes, best first:

Run from the project root as a module: python -m mypackage.main instead of python mypackage/main.py — this keeps package-relative imports working.
Install your project in editable mode: pip install -e . with a minimal pyproject.toml. This is the grown-up solution; your package imports the same way everywhere.
As a last resort, PYTHONPATH=. python main.py — works, but it's a workaround, not a fix.

The 30-second version

python -c "import sys; print(sys.executable)"  # which Python is this?
python -m pip show PACKAGE                     # is it installed HERE?
python -m pip install PACKAGE                  # install into THIS Python
python -c "import PACKAGE; print(PACKAGE.__file__)"  # shadowed by a local file?

Nine times out of ten, the story is "pip installed into Python A, the script ran under Python B." Make them the same Python and the error disappears.

Java Generics, Union Types, and the “String OR Integer” Problem

websilvercraft — Mon, 10 Aug 2026 06:58:44 +0000

The motivating problem

Consider this seemingly simple requirement:

“I want a single method that accepts either an array of Integer or an array of String, but nothing else.”

In a HackerRank-style problem, this shows up as:

Integer[] intArray = {1, 2, 3};
String[] stringArray = {"Hello", "World"};

myPrinter.printArray(intArray);
myPrinter.printArray(stringArray);

You’re explicitly not allowed to overload methods, so this is illegal:

void printArray(Integer[] a) { }
void printArray(String[] a) { } // ❌ rejected

Naturally, this leads to the question:

“Can I restrict a generic method to only String and Integer?”

Let’s explore what is possible, what is not, and why Java behaves this way.

The obvious (working) solutions

1. The generic solution (recommended)

class Printer {
    public <T> void printArray(T[] array) {
        for (T element : array) {
            System.out.println(element);
        }
    }
}

What this allows

Integer[]
String[]
Any other reference type

Pros

Type-safe
Idiomatic Java
Clean and flexible

Cons

Does not restrict the types at all

This is the expected answer for most interview and coding-challenge scenarios.

2. The `Object[]` solution (works, but weaker)

class Printer {
    public void printArray(Object[] items) {
        for (Object item : items) {
            System.out.println(item);
        }
    }
}

Why this works

Integer[] and String[] are both subtypes of Object[]
Only one method → no overloading violation

Downside

Loses compile-time type safety
You can now pass anything:

  Object[] mixed = {1, "hello", new Date()};

This is acceptable for printing, but not ideal for real APIs.

The thing people want to write (but can’t)

Union type bound (not supported)

public <T extends String | Integer> void printArray(T[] array) {
    ...
}

This feels intuitive — but Java does not support union types.

Why this is impossible in Java

1. Java generics do not support OR constraints

Java allows intersection types (AND):

<T extends InterfaceA & InterfaceB>

But Java does not allow:

<T extends A | B>   // ❌ no union types

The type system only understands:

“T must satisfy all of these”
Never “T must satisfy one of these”

2. `String` and `Integer` are both `final`

You might think:

class StringOrInteger { }

and then:

<T extends StringOrInteger>

But this fails immediately because:

class MyString extends String {}   // ❌ illegal
class MyInteger extends Integer {} // ❌ illegal

Both String and Integer are final, so they cannot share a custom superclass.

The only common superclass they do share is:

Object

Which is… too broad to be useful.

What can be done (with trade-offs)

Option 1: Runtime checks (not type-safe)

public void printArray(Object[] items) {
    for (Object item : items) {
        if (!(item instanceof String || item instanceof Integer)) {
            throw new IllegalArgumentException("Only String or Integer allowed");
        }
        System.out.println(item);
    }
}

Pros

Enforces the rule

Cons

Errors occur at runtime, not compile time
Easy to misuse

Option 2: Wrapper + marker interface (type-safe, but heavy)

interface IntOrString { }

class MyString implements IntOrString {
    String value;
    MyString(String value) { this.value = value; }
    public String toString() { return value; }
}

class MyInteger implements IntOrString {
    Integer value;
    MyInteger(Integer value) { this.value = value; }
    public String toString() { return value.toString(); }
}

public <T extends IntOrString> void printArray(T[] array) {
    for (T t : array) {
        System.out.println(t);
    }
}

Pros

Compile-time restriction
Clean type system

Cons

Requires wrapping values
Overkill for simple tasks

Why Java is like this (design philosophy)

Java’s generics were designed to:

Be backward compatible
Avoid runtime overhead
Keep the type system simple and predictable

Union types introduce:

Complex overload resolution
Ambiguous method selection
Harder type inference

Java chose simplicity and safety over expressiveness here.

How other languages handle this

Kotlin (yes, but indirectly)

fun printArray(arr: Array<out Any>) {
    arr.forEach { println(it) }
}

Kotlin still lacks true union types, but:

Has better variance (out, in)
Stronger type inference

Scala (much more powerful)

def printArray(arr: Array[String | Int]): Unit =
  arr.foreach(println)

Scala supports union types directly.

TypeScript (designed for unions)

function printArray(arr: (string | number)[]) {
    arr.forEach(console.log);
}

This is exactly what you wanted Java to do.

Swift

func printArray(_ arr: [Any]) {
    for item in arr {
        print(item)
    }
}

Swift allows this but relies on runtime checks unless you use enums.

The final takeaway

In Java:

❌ You cannot restrict generics to “String OR Integer”
❌ You cannot create a union superclass
❌ You cannot express OR constraints in type bounds
✅ You can use unrestricted generics
✅ You can enforce rules at runtime
✅ You can redesign with wrappers if needed

That’s why the best Java answer to this problem remains:

public <T> void printArray(T[] array)

So remember, if you were thinking about union types, congrats.
You’re already thinking beyond Java’s surface level and into type system design, which is exactly where strong developers end up.

How does Drizzle handle migrations - Part 2: Changing database structure

websilvercraft — Mon, 10 Aug 2026 06:49:02 +0000

Drizzle is built for that. You change the TypeScript schema, Drizzle generates a new migration that alters your SQLite/D1 tables, and you apply it with Wrangler. High-level loop:

Edit TS schema (add/rename/drop columns, tables, indexes, constraints).
npx drizzle-kit generate → emits a new migrations/00xx_*.sql diff.
Review the SQL (important for destructive changes).
Apply it: wrangler d1 execute DB --local/--remote --file migrations/00xx_*.sql.

Because D1 is SQLite, some changes are done via table rebuilds under the hood (SQLite can’t do every ALTER TABLE). Drizzle handles that by:

creating a temp table with the new shape,
copying data over (mapping/transforming columns),
dropping the old table,
renaming the temp table.

So yes-schema changes work; just be mindful of data migrations. Here are common recipes:

Add a column (safe)

TS:

creditDelta: integer('credit_delta').notNull().default(0)

Run drizzle-kit generate. It will emit ALTER TABLE ... ADD COLUMN credit_delta INTEGER NOT NULL DEFAULT 0; (or a rebuild if needed). Apply with Wrangler.

Make a column NOT NULL (with data)

Backfill a default in a migration:

UPDATE billing_price_map SET credit_delta = 0 WHERE credit_delta IS NULL;

Then change TS to .notNull() (and maybe .default(0)), generate migration. Drizzle will rebuild the table so the constraint holds.

Rename a column

Change the field name in TS and use .as('old_column_name')? (Not needed.) For SQLite, Drizzle will usually rebuild the table and map old → new:

You’ll see a create/copy/drop sequence in the generated SQL.
If you also need to transform data, add a custom UPDATE new_table SET new_col = old_col step between copy and drop (or tweak the generated SQL before applying).

Change a column type

Again, SQLite → rebuild.

Drizzle generates new table, copies data (SQLite will try to coerce).
If you need specific transforms, add an UPDATE in the migration file.

Drop a column

SQLite can’t drop columns directly → rebuild.

Be careful: verify you don’t rely on that data anymore.
Consider doing a two-step “soft drop” (stop using it, deploy; later actually drop).

Add / drop unique constraints or indexes

Update TS (.unique(), .uniqueIndex(), .index()), generate, apply.
Drizzle will CREATE UNIQUE INDEX / DROP INDEX or rebuild to embed constraints.

Rename a table

Change sqliteTable('new_name', ...). Drizzle will create new, copy, drop old.
If you want to preserve the exact name, do it in two steps or edit the generated SQL.

Data migrations alongside structure

Drizzle generates structure changes; you can (and often should) append your own SQL to the same migration:

-- backfill new column based on price_id
UPDATE billing_price_map
SET credit_delta = CASE provider_price_id
  WHEN 'pri_...' THEN 100
  WHEN 'pri_...' THEN 1000
  ELSE 0
END;

This is how you keep credits consistent when changing mappings.

D1-specific tips

Apply order matters: migrations are numbered; run all in order for each env.
Review generated SQL: especially rebuilds-make sure the copy step includes all columns you care about.
Idempotency: use IF NOT EXISTS / INSERT OR IGNORE for seeds.
Prod safety: for breaking changes, do “expand → backfill → switch → contract”:
- Add new columns/tables (expand).
- Dual-write or backfill.
- Switch code to read new fields.
- Drop old columns later (contract).

Workflow you can stick to

Update src/db/schema*.ts.
npx drizzle-kit generate (commits new SQL).
(Optional) Edit the generated SQL to add backfills/transforms.
Dev DB: npm run db:migrate:local (your wrapper over Wrangler).
Test app.
Prod DB: npm run db:migrate:remote.

That’s it. If you tell me the exact structural change you have in mind (e.g., “split transactions into invoice + payments” or “rename provider_price_id to price_id and make it NOT NULL”), I’ll draft the precise TS change and the migration SQL you should expect (including safe backfills).

Agentic patterns and architectural approaches in AI

websilvercraft — Sun, 07 Dec 2025 09:15:35 +0000

Below is a set of commonly discussed agentic patterns and architectural approaches in the field of AI. These patterns often appear in intelligent agent design, multi-agent systems, and autonomous decision-making frameworks. While some patterns originate from theoretical foundations, others stem from well-known implementations and best practices.

1. Reactive (Reflex) Agents

Simple Reflex Agents:
Agents that directly map percepts to actions without internal models. They respond immediately based on current input alone (e.g., a thermostat controlling temperature by simple rules).
Model-Based Reflex Agents:
Agents that maintain an internal model of the environment to handle partially observable states. They update their model based on incoming perceptions, enabling more nuanced immediate reactions.

2. Goal-Based Agents

Goal-Directed Reasoning:
Agents that select actions by considering their goals and how each potential action might help achieve them. Their patterns involve search, planning, and heuristic evaluation to determine which action leads them closer to their objectives.
Constraint-Solving Agents:
Agents that represent their environment and objectives as constraints and explore feasible solutions that satisfy these constraints. Their decision-making pattern focuses on reducing the search space to find valid goal states.

3. Utility-Based Agents

Decision-Theoretic Agents:
Agents that assign a utility value (or expected utility) to potential outcomes and choose actions that maximize long-term expected utility. This pattern commonly appears in economic modeling and complex decision-making tasks.
MDP/RL-Based Agents (Markov Decision Processes / Reinforcement Learning):
Agents that frame their interactions as sequential decision problems, using methods like Q-learning, policy gradients, or value iteration to maximize expected rewards over time.

4. Belief-Desire-Intention (BDI) Agents

Cognitive Architectures (BDI):
Agents that maintain explicit representations of their beliefs (information about the world), desires (long-term objectives), and intentions (committed plans of action). These patterns follow philosophical foundations of rational agency, enabling modular reasoning and more naturalistic decision-making.
Layered Reasoning in BDI Systems:
Hierarchical patterns that separate high-level abstract reasoning about goals and beliefs from low-level execution details. For example, the PRS (Procedural Reasoning System) framework.

5. Hybrid Architectures

Layered Architectures (e.g., Touring Machines, InteRRaP):
Agents that combine reactive and deliberative layers. A reactive layer handles immediate responses while a higher-level reasoning or planning layer manages longer-term strategic goals. This pattern ensures responsiveness while still accommodating complex planning.
Three-Layer Architectures (Reactive, Sequencing, Deliberative):
A commonly cited pattern in robotics and AI that has a bottom reactive layer (fast control loops), a middle sequencing or skill management layer, and a top deliberative or planning layer.

6. Multi-Agent Interaction Patterns

Contract Net Protocol:
A decentralized pattern where agents announce tasks, and other agents bid for them. The "manager" agent chooses the best bid, exemplifying a market-based mechanism for task allocation.
Coordinator/Facilitator Patterns:
A designated agent or set of agents coordinates the activities of others, handling negotiation, resource distribution, or conflict resolution.
Blackboard Architectures:
A pattern where multiple specialized agents read and write knowledge to a shared data structure (a "blackboard"). Agents trigger each other’s actions by posting partial solutions or data that others can build upon.

7. Adaptive and Self-Organizing Patterns

Stigmergic Coordination:
Agents coordinate indirectly via modifications to a shared environment (e.g., ants depositing pheromones). This pattern emerges in swarm intelligence and behavior-based robotics.
Evolutionary Agent Populations:
Patterns where agent behavior is optimized through evolutionary computation or genetic algorithms, ensuring a population of agents adapt over time.

8. Service-Oriented and Ontology-Based Agent Patterns

Agent-Oriented Software Engineering (AOSE) Frameworks:
Patterns that follow methodologies (e.g., Gaia, Tropos) to define roles, interactions, and organizational rules that shape agent behavior.
Ontology-Driven Agents:
Agents that rely on shared semantic vocabularies for communication and coordination, enabling interoperability and modular composition of knowledge bases.

These patterns offer a conceptual toolkit for designing, analyzing, and implementing intelligent agents and multi-agent systems. Designers often combine multiple patterns—for instance, layering a BDI reasoning process atop a reactive framework or incorporating utility-based decision-making into a multi-agent negotiation protocol—to address complex, dynamic environments.

How does Drizzle handle migrations - Part 1

websilvercraft — Thu, 09 Oct 2025 15:56:09 +0000

Drizzle keeps a local snapshot of the previous schema and diffs the current TS schema against that snapshot when generating migrations.

Here’s how it works:

The source of truth: the TypeScript schema files (e.g. src/db/schema.ts, schema.billing.ts).
Drizzle’s stored “old state”: a small meta snapshot that lives next to the migrations, typically under something like:

  migrations/
    0001_init.sql
    0002_billing.sql
    ...
    meta/
      _journal.json
      _meta.json

(Exact file names can vary by Drizzle version, but there’s always a meta folder with the snapshot/journal.)

When you run drizzle-kit generate: Drizzle reads:

your current TS schema
the previous meta snapshot …and produces a new 00xx_*.sql migration that transforms the old snapshot into the new schema. It also updates the meta files.

What the DB stores: In the database, Drizzle keeps a tiny migrations journal table (e.g. __drizzle_migrations / similar) that tracks which migration files were applied. It’s not used for schema diffing-only for apply-order / applied-state when you execute migrations.

If things get out of sync

Lost meta folder? You can introspect the DB to recreate a baseline schema (Drizzle has an introspect command) or generate a new “initial” migration matching the current DB, then continue forward.
Edited an old migration? Don’t. Migrations should be immutable once applied. If you must, expect to reconcile by fixing your meta and/or DB to match.
DB drifted from code? Either:
- Update your TS schema to match and generate the next migration, or
- Use introspection to realign the local snapshot with the live DB, then proceed.

TL;DR

Drizzle diffs TS schema vs. its local meta snapshot, not the live DB.
The DB only tracks which migrations ran, not the structure for diffing.
If the snapshot is missing/outdated, use introspection to rebuild a baseline or create a new initial migration that matches the current DB, then keep going.

What is Zod and what does it bring over typescript type definitions

websilvercraft — Wed, 27 Aug 2025 10:52:07 +0000

Zod is a framework that covers a gap that happens because typescript gets compiled into javascript. Typescript being strongly typed, but java not, you are covered are compile-time for type checks, but that is lost at run time. Zod is here to do perform type checks at runtime plus adding data validations and even transformation.

The Core Difference: Compile-Time vs Runtime

TypeScript Types = Compile-Time Only

// This type disappears after compilation
interface User {
  name: string;
  age: number;
}

// TypeScript thinks this is fine at compile time
const userData: User = await fetch('/api/user').then(r => r.json());
console.log(userData.name); // 💥 Runtime error if API returns { username: "John" }

Zod = Runtime Validation + Type Inference

import { z } from 'zod';

// This exists at runtime AND generates TypeScript types
const UserSchema = z.object({
  name: z.string(),
  age: z.number()
});

// This will throw at runtime if data doesn't match
const userData = UserSchema.parse(await fetch('/api/user').then(r => r.json()));
console.log(userData.name); // ✅ Guaranteed to exist and be a string

What Zod Adds: The Advantages

1. Runtime Safety for External Data

// ❌ TypeScript alone - false confidence
interface APIResponse {
  users: Array<{ id: number; email: string }>;
}

// TypeScript: "Looks good!" 
// Reality: API might return { users: null } or { data: [...] }
const response: APIResponse = await fetchAPI();
response.users.map(...); // 💥 Cannot read property 'map' of null

// ✅ With Zod - actual validation
const APIResponseSchema = z.object({
  users: z.array(z.object({
    id: z.number(),
    email: z.string().email() // Even validates email format!
  }))
});

try {
  const response = APIResponseSchema.parse(await fetchAPI());
  response.users.map(...); // ✅ Guaranteed safe
} catch (error) {
  // Handle malformed response
}

2. Single Source of Truth

// ❌ TypeScript - duplicate definitions
interface User {
  email: string;
  age: number;
}

function validateUser(data: any): data is User {
  return typeof data.email === 'string' && 
         typeof data.age === 'number' &&
         data.age >= 0; // Oops, forgot this in the type!
}

// ✅ Zod - one definition, both type and validation
const UserSchema = z.object({
  email: z.string().email(),
  age: z.number().min(0)
});

type User = z.infer<typeof UserSchema>; // Type derived from schema
const isValid = UserSchema.safeParse(data).success; // Validation from same source

3. Rich Validation Beyond Types

// ❌ TypeScript can't express these constraints
interface Password {
  value: string; // Can't say "min 8 chars, must have uppercase"
}

// ✅ Zod can validate complex rules
const PasswordSchema = z.string()
  .min(8, "Password must be at least 8 characters")
  .regex(/[A-Z]/, "Must contain uppercase letter")
  .regex(/[0-9]/, "Must contain number")
  .regex(/[^A-Za-z0-9]/, "Must contain special character");

4. Transformation and Coercion

// ✅ Zod can transform data while validating
const ConfigSchema = z.object({
  port: z.string().transform(Number), // "3000" → 3000
  enabled: z.string().transform(s => s === "true"), // "true" → true
  createdAt: z.string().pipe(z.coerce.date()), // "2024-01-01" → Date object
  email: z.string().toLowerCase().trim().email() // Clean and validate
});

// URL params, form data, environment variables - all strings!
const config = ConfigSchema.parse({
  port: "3000",
  enabled: "true", 
  createdAt: "2024-01-01",
  email: "  USER@EXAMPLE.COM  "
});
// Result: { port: 3000, enabled: true, createdAt: Date, email: "user@example.com" }

5. Better Error Messages

// ❌ TypeScript at runtime
JSON.parse(apiResponse); // Error: Unexpected token < in JSON at position 0

// ✅ Zod validation errors
UserSchema.parse(data);
/* ZodError: {
  "issues": [{
    "path": ["email"],
    "message": "Invalid email format"
  }, {
    "path": ["age"],
    "message": "Expected number, received string"
  }]
} */

6. Composability

// Build complex schemas from simple ones
const AddressSchema = z.object({
  street: z.string(),
  city: z.string(),
  zip: z.string().regex(/^\d{5}$/)
});

const PersonSchema = z.object({
  name: z.string(),
  addresses: z.array(AddressSchema), // Reuse schemas
  primaryAddress: AddressSchema.optional()
});

const CompanySchema = z.object({
  employees: z.array(PersonSchema), // Compose further
  headquarters: AddressSchema
});

Real-World Example: Your HeadingAnalyzer

// What could go wrong without runtime validation?

// 1. DOM parsing might produce unexpected results
const heading = {
  level: 7, // ❌ TypeScript won't catch this at runtime
  text: null, // ❌ Might be null instead of empty string
  position: -1, // ❌ Could be negative
  id: undefined // ❌ Might be undefined instead of null
};

// 2. Cloudflare Worker receives malformed data
const apiResponse = await fetch('/analyze');
const data: HeadingAnalysisResult = await apiResponse.json();
// TypeScript: "Looks good!"
// Reality: Could be { error: "Rate limited" } or literally anything

// 3. With Zod, you catch these issues immediately
const HeadingInfoSchema = z.object({
  level: z.number().min(1).max(6), // Must be 1-6
  text: z.string(), // Coerces null to empty string
  position: z.number().int().nonnegative(), // Must be positive integer
  id: z.string().nullable() // Explicitly nullable, not undefined
});

When You NEED Zod

API Boundaries: Validating external API responses
User Input: Form data, URL params, file uploads
Config Files: Environment variables, JSON configs
Database Results: Ensuring DB schema matches expectations
Webhooks: Third-party services sending data
localStorage/sessionStorage: Stored data might be corrupted

When TypeScript Types Are Enough

Internal Code: Functions calling other functions you control
Build-Time Known: Imported JSON, constants
Trusted Sources: Your own internal services with guaranteed contracts
Performance Critical: Hot paths where validation overhead matters

In conclusion, TypeScript protects you from yourself (typos, wrong types in your code). Zod protects you from the world (APIs, users, databases, external systems).

Same Fetch, Different Streams: duplex: 'half' in Node vs Cloudflare Workers

websilvercraft — Sat, 23 Aug 2025 10:25:09 +0000

In the last post What’s the Request object in the browser, Cloudflare, and Node?, I detailed the how the Request class is the same regardless the implementation. However, when handling streams, there are some practical differences, even though both runtimes expose the same Fetch API.

What differs with streams

Stream types available
- Cloudflare Workers: only Web Streams (ReadableStream, WritableStream, TransformStream).
- Node 18+: has both classic Node streams and Web Streams. fetch uses Web Streams, but Node lets you pass a Node Readable as a request body.
Streaming request bodies (uploads)
- Node: if the request body is a stream, you must set duplex: 'half' in the init/options. If you forget, you’ll get: “duplex option is required when sending a body that is a ReadableStream”.
- Workers: no duplex flag; just pass a Web ReadableStream.
Bridging between stream kinds (Node only)
- Convert Node → Web: Readable.toWeb(nodeWritable) / Readable.from(nodeReadable) (or Readable.fromWeb).
- You’ll use this when adapting http.IncomingMessage ↔︎ Fetch.
Response bodies (downloads)
- Both return a Web ReadableStream at response.body.
- In Node, to send it to http.ServerResponse, convert the Node writable to a Web Writable and pipeTo.

Tiny patterns

Node: adapt `IncomingMessage` → `Request` (streaming upload)

import { Readable } from 'node:stream'

const request = new Request(url, {
  method,
  headers,
  body: hasBody ? (req as unknown as Readable) : undefined, // Node stream ok
  // Node/undici requirement for streamed bodies:
  // @ts-expect-error undici extension
  duplex: hasBody ? 'half' : undefined,
})

Node: write a streamed `Response` back to `ServerResponse`

import { Readable } from 'node:stream'

const response = await fetchHandler(request)

res.statusCode = response.status
response.headers.forEach((v, k) => res.setHeader(k, v))

if (response.body) {
  // pipe Web ReadableStream → Node ServerResponse
  // @ts-ignore types can lag behind
  await response.body.pipeTo(Readable.toWeb(res))
} else {
  res.end()
}

Workers: streaming is Web-Streams-native

export default {
  async fetch(req: Request) {
    // req.body is a Web ReadableStream (or null)
    return new Response(req.body) // streams through unchanged
  }
}

Rules of thumb

Use Web Streams as your common denominator.
In Node, add duplex: 'half' only when the request body is a stream.
Convert between Node and Web streams only at the edges (the Node HTTP adapter). Your itty router can stay pure-Fetch/Web-Streams and run the same on Workers and Node.

What’s the `Request` object in the browser, Cloudflare, and Node?

websilvercraft — Sat, 23 Aug 2025 10:15:20 +0000

I’ve been building a tiny API with itty-router that I want to run unchanged on Cloudflare Workers and a plain Node server. itty is fetch-native—it speaks in terms of fetch(req), Request, and Response. That’s awesome for portability, but it also means the whole trick hinges on the Request object being consistent across runtimes.

Before I wired everything up, I needed to check if I can use on the same Request objects in cloudflare and node environments.

The Request to use with fetch is part of the WHATWG Fetch Standard—a web platform spec that defines fetch, Request, Response, Headers, etc. All three environments expose the same API surface (with minor runtime quirks), so code written against the spec tends to work everywhere.

Where it comes from

Browser Request is a built-in global provided by the browser. No imports.

  const req = new Request('/api', { method: 'POST' })
  const res = await fetch(req)

Cloudflare Workers Workers implement the same Fetch standard. Request is global here too.

  export default {
    async fetch(req) {
      // req is already a Request
      return new Response('ok')
    }
  }

Node.js (v18+) Node ships a Fetch implementation (via undici) and sets Request as a global alongside fetch, Response, and Headers. You don’t need to import anything.

  // Node 18+:
  const req = new Request('https://example.com')
  const res = await fetch(req)
  console.log(res.status)

Why you don’t import it in Node

Because Node 18+ defines Request on globalThis just like the browser/Workers. Older Node versions didn’t have it—you had to polyfill (e.g., node-fetch or undici). On current Node, it’s simply available.

TypeScript tip

For Node projects, add DOM libs so the Request type is known at compile time:

// tsconfig.json
{
  "compilerOptions": {
    "lib": ["ES2022", "DOM"]
  }
}

A tiny sanity check

console.log(typeof Request)           // "function" in all three
console.log(globalThis.Request === Request) // true

When streams are involved there are a few practical differences, even though both runtimes expose the same Fetch API. For example, in Node, if you construct a Request from a Node stream, you’ll include duplex: 'half' in the init. For ordinary JSON bodies/strings, you can ignore this. Details about the streams related fidderences, in the next post: Same Fetch, Different Streams: duplex: 'half' in Node vs Cloudflare Workers.

One router, two runtimes: itty-router on Cloudflare Workers and Node

websilvercraft — Sat, 23 Aug 2025 09:30:26 +0000

I wanted one tiny router that runs unchanged on Cloudflare Workers and a plain Node HTTP server. The secret sauce is itty-router + the Fetch standard (Request/Response). Here’s how I wired it up, plus a quick note on the “do Node and Cloudflare use the same Response?” question.

Do Node and Cloudflare use the same Response object?
Short answer: not literally the same object, but the same Fetch standard Response API, compatible classes with different under the hood implementations.
– Cloudflare Workers exposes a Response that follows the WHATWG Fetch spec.
– Modern Node (v18+) also exposes a Fetch-compatible Response (implemented by undici).

So they’re API-compatible (same props/methods: status, headers, text(), json(), arrayBuffer(), body as a Web ReadableStream, new Response(), etc.), but they’re different implementations under the hood—don’t rely on brand checks like mixing realms or instanceof across runtimes.

A few practical gotchas:
– Streaming: both use Web Streams; in Node you sometimes convert to/from Node streams (Readable.fromWeb, Readable.toWeb) when bridging to http.ServerResponse.
– Node-only quirks (Requests): when you construct a Request with a Node stream body, Node needs duplex: 'half'. This is not needed/used in Workers. (Doesn’t affect Response itself.)
– Helpers: Response.json() exists in Workers and in recent Node. If you need to support older Node, fallback to new Response(JSON.stringify(data), { headers: { 'content-type': 'application/json; charset=utf-8' } }).

If you stick to the spec surface (like in the router below), you can reuse the same code in both environments. For a more detailed explanation, check What’s the Request object in the browser, Cloudflare, and Node?.

The shared router (one codepath)

itty-router’s AutoRouter can produce a single fetch handler. Keep the routes and tiny HTTP helpers here.

// src/router.ts
import { AutoRouter } from 'itty-router'

// tiny helpers
const withCORS = (res: Response, status = res.status) =>
  new Response(res.body, {
    status,
    headers: {
      'content-type': res.headers.get('content-type') ?? 'application/json; charset=utf-8',
      'access-control-allow-origin': '*',
      'access-control-allow-methods': 'GET,POST,OPTIONS',
      'access-control-allow-headers': 'content-type',
    },
  })

const ok = (data: unknown) => withCORS(Response.json(data))
const badRequest = (msg: string) => withCORS(Response.json({ error: msg }), 400)
const noContent = () => withCORS(new Response(null, { status: 204 }), 204)

const router = AutoRouter({ base: '/' })

// CORS preflight
router.options('/*', () => noContent())

// sample routes (keep it simple)
router.get('/hello', () => ok({ hello: 'world' }))

router.post('/echo', async (req: Request) => {
  try {
    const body = await req.json()
    return ok({ youSent: body })
  } catch {
    return badRequest('Expected JSON body')
  }
})

// 404
router.all('*', () => withCORS(Response.json({ error: 'Not found' }), 404))

// export a single fetch (works on Workers; reusable in Node)
export default { fetch: router.fetch }

That’s it. This fetch function is our “universal” entry point.

Cloudflare Worker entry (zero glue)

Cloudflare Workers already speak fetch:

// src/worker.ts
import router from './router'

export default {
  fetch: router.fetch,
}

Deploy with your usual Wrangler config.

Node adapter (a tiny bridge)

For Node, we just translate IncomingMessage ⟶ Request, call the shared fetch, then write the Response back.

// src/node-server.ts
/// <reference types="node" />
import http from 'node:http'
import { Readable } from 'node:stream'
import router from './router'

const PORT = Number(process.env.PORT ?? 8787)

http.createServer(async (req, res) => {
  try {
    const url = new URL(req.url ?? '/', `http://${req.headers.host ?? 'localhost'}`)
    const method = req.method ?? 'GET'

    // build Headers
    const headers = new Headers()
    for (const [k, v] of Object.entries(req.headers)) {
      if (Array.isArray(v)) v.forEach(vv => headers.append(k, vv))
      else if (v != null) headers.set(k, String(v))
    }

    // only attach a body for non-GET/HEAD
    const hasBody = !['GET', 'HEAD'].includes(method.toUpperCase())
    const body = hasBody ? (req as unknown as Readable) : undefined

    const request = new Request(url.toString(), {
      method,
      headers,
      body,
      // Node (undici) quirk when passing a stream body:
      // @ts-expect-error undici extension
      duplex: hasBody ? 'half' : undefined,
    })

    const response = await router.fetch(request)

    res.statusCode = response.status
    response.headers.forEach((v, k) => res.setHeader(k, v))

    if (!response.body) return res.end()

    // stream to Node
    // @ts-ignore types for toWeb are a bit behind
    await (response.body as any).pipeTo(Readable.toWeb(res) as any)
  } catch (err: any) {
    res.statusCode = 500
    res.setHeader('content-type', 'application/json; charset=utf-8')
    res.end(JSON.stringify({ error: 'Internal error', detail: String(err?.message ?? err) }))
  }
}).listen(PORT, () => {
  console.log(`Node server: http://localhost:${PORT}`)
})

TypeScript tip

Make sure your tsconfig.json includes DOM types so Request/Response are available in Node:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "Bundler",
    "lib": ["ES2022", "DOM"],
    "strict": true
  }
}

Why this works so well

Single mental model: you write to the Fetch standard once. itty-router just plugs in.
No “environment if”s: the router and helpers are runtime-agnostic.
Portability: same handler can move to other Fetch runtimes (Bun, Deno Deploy, etc.) with little/no glue.

Quick curl test

# Node server
curl http://localhost:8787/hello
# => {"hello":"world"}

curl -X POST http://localhost:8787/echo -H 'content-type: application/json' -d '{"x":1}'
# => {"youSent":{"x":1}}

For Workers, hit your deployed URL with the same requests.

Gotchas & guardrails

Don’t do instanceof Response checks across runtimes—treat them as structurally compatible, not identical classes.
When constructing a Request from a Node stream, pass duplex: 'half'.
If you need cookies or advanced streaming, test both runtimes—semantics are compatible, but edge cases differ.

How to Protect Email Addresses from Spam Bots

websilvercraft — Wed, 09 Apr 2025 19:18:07 +0000

Email addresses on websites are prime targets for spam bots that crawl the web looking for this valuable data. If you have a contact page with email addresses displayed in plain text, you're practically inviting unwanted spam. Here are several effective methods to protect your email addresses while keeping them accessible to human visitors.

1. JavaScript Email Obfuscation

Replace plain text email addresses with JavaScript that dynamically constructs the email when needed:

document.addEventListener('DOMContentLoaded', function() {
  const emailElements = document.querySelectorAll('.email-protect');
  emailElements.forEach(element => {
    const username = element.getAttribute('data-user');
    const domain = element.getAttribute('data-domain');
    element.addEventListener('click', function(e) {
      e.preventDefault();
      window.location.href = `mailto:${username}@${domain}`;
    });
    element.innerHTML = `${username}@${domain}`;
  });
});

Then in your HTML:

<a href="#" class="email-protect" data-user="info" data-domain="example.com">Contact Us</a>

2. HTML Entity Encoding

Convert the email address characters to HTML entities to confuse bots:

<a href="&#109;&#97;&#105;&#108;&#116;&#111;&#58;&#105;&#110;&#102;&#111;&#64;&#101;&#120;&#97;&#109;&#112;&#108;&#101;&#46;&#99;&#111;&#109;">&#105;&#110;&#102;&#111;&#64;&#101;&#120;&#97;&#109;&#112;&#108;&#101;&#46;&#99;&#111;&#109;</a>

This renders as a normal "info@example.com" link to humans but is harder for bots to parse.

3. CSS Direction Reversal

Use CSS to display the email in reverse and then flip it with CSS:

<style>
  .email-reverse {
    unicode-bidi: bidi-override;
    direction: rtl;
    display: inline-block;
  }
</style>
<span class="email-reverse">moc.elpmaxe@ofni</span>

4. Image Replacement

Replace text emails with images containing the address:

<img src="/images/contact-email.png" alt="Contact our team" width="180" height="20">

Remember to provide alternative text for accessibility.

5. Contact Forms: The Best Solution

The most effective approach is to use a contact form instead of displaying email addresses directly. This provides several benefits:

No email addresses are exposed in the HTML

You can implement CAPTCHA or other bot prevention

Forms can include validation and required fields

You can direct inquiries to the right department automatically

6. Implementation Example

Here's a complete example you can adapt for your site:

document.addEventListener('DOMContentLoaded', function() {
  // Email protection function
  function setupEmailProtection() {
    const emailMap = {
      'info': ['info', 'example.com'],
      'support': ['support', 'example.com'],
      'sales': ['sales', 'example.com']
    };

    for (const [id, parts] of Object.entries(emailMap)) {
      const element = document.getElementById(`email-${id}`);
      if (element) {
        // Create a text node with the email address
        const emailText = document.createTextNode(`${parts[0]}@${parts[1]}`);
        element.appendChild(emailText);

        // Set up the click handler
        element.addEventListener('click', function(e) {
          e.preventDefault();
          window.location.href = `mailto:${parts[0]}@${parts[1]}`;
        });
      }
    }
  }

  // Call function when page loads
  setupEmailProtection();
});

Protecting your email addresses from spam bots is an essential part of maintaining a professional web presence. By implementing one or more of these techniques, you can significantly reduce unwanted spam while keeping your contact information accessible to legitimate users.

At the end of the day, no solution is 100% bot-proof, so consider using multiple layers of protection for sensitive contact information. For critical applications, contact forms with proper spam protection remain the gold standard.

DEV Community: websilvercraft

Python's match-case is not a switch statement (it's better)

The switch part (30 seconds)

The real feature: matching structure

Sequences, classes, and guards

The classic gotcha

When to still use if/elif

The Python GIL, explained without the hand-waving

What the GIL actually is

The part everyone skips: the GIL is released constantly

See it in numbers

The decision table

"But I heard they're removing the GIL"

What to remember

ModuleNotFoundError: No module named 'X' — a debugging checklist that actually works

1. Find out which Python is actually running

2. Is your virtual environment actually active?

3. Check for name shadowing (the sneaky one)

4. Import name ≠ install name

5. Importing your own code? It's a path problem

The 30-second version

Java Generics, Union Types, and the “String OR Integer” Problem

The motivating problem

The obvious (working) solutions

1. The generic solution (recommended)

2. The Object[] solution (works, but weaker)

The thing people want to write (but can’t)

Union type bound (not supported)

Why this is impossible in Java

1. Java generics do not support OR constraints

2. String and Integer are both final

What can be done (with trade-offs)

Option 1: Runtime checks (not type-safe)

Option 2: Wrapper + marker interface (type-safe, but heavy)

Why Java is like this (design philosophy)

How other languages handle this

Kotlin (yes, but indirectly)

Scala (much more powerful)

TypeScript (designed for unions)

Swift

The final takeaway

How does Drizzle handle migrations - Part 2: Changing database structure

Add a column (safe)

Make a column NOT NULL (with data)

Rename a column

Change a column type

Drop a column

Add / drop unique constraints or indexes

Rename a table

Data migrations alongside structure

D1-specific tips

Workflow you can stick to

Agentic patterns and architectural approaches in AI

How does Drizzle handle migrations - Part 1

If things get out of sync

TL;DR

What is Zod and what does it bring over typescript type definitions

The Core Difference: Compile-Time vs Runtime

TypeScript Types = Compile-Time Only

Zod = Runtime Validation + Type Inference

What Zod Adds: The Advantages

1. Runtime Safety for External Data

2. Single Source of Truth

3. Rich Validation Beyond Types

4. Transformation and Coercion

5. Better Error Messages

6. Composability

Real-World Example: Your HeadingAnalyzer

When You NEED Zod

When TypeScript Types Are Enough

Same Fetch, Different Streams: duplex: 'half' in Node vs Cloudflare Workers

What differs with streams

Tiny patterns

Node: adapt IncomingMessage → Request (streaming upload)

Node: write a streamed Response back to ServerResponse

Workers: streaming is Web-Streams-native

Rules of thumb

What’s the `Request` object in the browser, Cloudflare, and Node?

Where it comes from

Why you don’t import it in Node

2. The `Object[]` solution (works, but weaker)

2. `String` and `Integer` are both `final`

Node: adapt `IncomingMessage` → `Request` (streaming upload)

Node: write a streamed `Response` back to `ServerResponse`