DEV Community: zintrust Zin

Cloudflare Queues + Real Job Queue Features (without Redis)

zintrust Zin — Fri, 12 Jun 2026 09:51:53 +0000

f you build on Cloudflare Workers today and you need background jobs, you have probably had the following conversation:

"We can use Cloudflare Queues for delivery, it's basically free and global."
"Yeah but then how do we know which jobs are pending? How do we do repeatables? Rate limiting per tenant? Proper backoff with visibility?"

The honest answer used to be: "you stand up Redis (or SQS) for that part."

@zintrust/queue-cloudflare is our attempt to make the honest answer better.

Two usage modes

1. Dead simple (no extra state)

import { Queue } from '@zintrust/core/queue';

await Queue.enqueue('EMAIL_QUEUE', { to: user.email, template: 'welcome' }, 'cloudflare');

This just uses Cloudflare Queues directly (via binding or the REST API). Great for fire-and-forget or when you already have your own tracking.

2. Full state layer (the interesting one)

import { CloudflareQueues } from '@zintrust/queue-cloudflare';

const queue = CloudflareQueues.create({
  driver: 'cloudflare',
  bindingName: 'EMAIL_QUEUE',
  state: {
    d1BindingName: 'QUEUE_DB',
    kvBindingName: 'QUEUE_KV',           // optional but recommended
    coordinatorBindingName: 'QUEUE_COORDINATOR',
  },
});

const job = await queue.add('email-jobs', 'send-welcome', data, {
  attempts: 5,
  backoff: { type: 'exponential', delay: 2000 },
  delay: 60_000,
  deduplication: { id: `welcome:${user.id}`, ttl: 86_400_000 },
});

await queue.getJobCounts('email-jobs', 'waiting', 'active', 'failed');
await job.updateProgress({ step: 'rendering' });
await job.log('template loaded', { templateId: 42 });

Under the hood:

A tiny envelope (protocol + jobId + queue + attempt + availableAt) is what actually travels through Cloudflare Queues.
The full job row, attempts, progress, result, error, logs, and flow links live in D1.
Coordination (leases, heartbeats, rate limiting, pause gate) happens in a Durable Object with SQLite storage.
The scheduler (delayed + repeatables + stalled reconciliation) runs from your cron trigger and reads/writes D1.

What you actually get

Job lifecycle you can query and act on (getJob, retry, promote, remove, clean)
Repeatable jobs via cron or fixed interval + limit
Parent/child flows (createFlow + automatic parent release)
Per-job progress + structured logs
Token-bucket rate limiting + queue pause/resume (enforced before dispatch)
Stalled job recovery
Retention policies (removeOnComplete / removeOnFail)
Clean consumer helper that gives you updateProgress, log, and heartbeat in context
DLQ integration (recommended)
Same API surface whether you're running locally with zin s or in Workers with --wg

The limits (read these)

Cloudflare Queues is an at-least-once system with its own constraints. We document the practical trade-offs directly so you don’t get surprised in production.

Important realities:

At-least-once. Your job processors must be idempotent. Use the jobId, deduplication, and DLQ tooling we give you.
128 KB maximum size for messages on Cloudflare Queues. Keep envelopes small. (limits)
Retention on the queue itself is configurable up to 14 days (4 days default on paid plans; 24h non-configurable on the free plan). (limits, configuration)
Scheduling and reconciliation run on whatever cron you configure (commonly every minute). You can add DO alarms for finer grain if you need it.
Pause/resume is a dispatch gate. Already-delivered messages in a batch will still execute.
You must provision and bind: the Queue(s), a D1, the coordinator Durable Object, a cron, and (strongly recommended) a DLQ.
This is not Redis. Some things (exact priority ordering without multiple queues or scheduler dispatch, sandboxed processors, sub-second timing) are different by design.

If those constraints are acceptable, the upside is huge: you stay inside the Cloudflare billing and operational model instead of running a second stateful system whose only job is "be a queue."

Recommended minimal production wiring (wrangler.jsonc sketch)

{
  "queues": {
    "producers": [{ "queue": "email-jobs", "binding": "EMAIL_QUEUE" }],
    "consumers": [{
      "queue": "email-jobs",
      "max_batch_size": 10,
      "max_retries": 3,
      "dead_letter_queue": "email-dlq"
    }]
  },
  "d1_databases": [{ "binding": "QUEUE_DB", "database_name": "zintrust-queue" }],
  "kv_namespaces": [{ "binding": "QUEUE_KV", "id": "..." }],
  "durable_objects": {
    "bindings": [{ "name": "QUEUE_COORDINATOR", "class_name": "CloudflareQueueCoordinator" }]
  },
  "migrations": [{ "tag": "queue-cloudflare-v1", "new_sqlite_classes": ["CloudflareQueueCoordinator"] }],
  "triggers": { "crons": ["* * * * *"] }
}

Run the migration once:

zin migrate:queue-cloudflare --database zintrust-queue --remote

Then in your consumer Worker use the provided createConsumer helper.

When to use this vs something else

Use it when:

The majority of your stack is already Cloudflare-native.
You want observable, controllable background work without introducing Redis/SQS as a hard dependency.
Your jobs are naturally idempotent or can be made so.
1-minute scheduling granularity is acceptable (the common case for notifications, reports, syncs, cleanups, etc.).

Reach for Redis/BullMQ or SQS instead when:

You have hard sub-second or sub-10s scheduling SLAs.
You need very high fan-out or per-queue throughput beyond current Cloudflare limits.
You want a true drop-in replacement for an existing heavy BullMQ workload with minimal changes.
Sandboxed / untrusted processor execution is a hard requirement.

Try it

npm install @zintrust/queue-cloudflare
# or inside a ZinTrust project:
zin add queue:cloudflare

The package is small, the surface is explicit, and the docs try very hard not to lie to you.

If you're doing real work on Cloudflare and queues are still the annoying exception in your architecture diagram, this might be worth an afternoon.

Feedback, real-world patterns, and "here's where it broke our assumptions" stories are extremely welcome in the repo or Discord.

The package README and https://zintrust.com/package-queue-cloudflare contain the full current guidance.

Package: https://www.npmjs.com/package/@zintrust/queue-cloudflare

Core docs: https://zintrust.com/package-queue-cloudflare

The package page includes setup, consumer patterns, wrangler examples, and the documented limitations.

# Stop Flying Blind: Why Your Next Framework Needs a Built-In Debugger (Meet ZinTrust Trace)

zintrust Zin — Mon, 13 Apr 2026 07:10:58 +0000

Let’s be honest: back-end debugging can sometimes feel like a dark art. We've all been there—sprinkling console.log() across five different files, hunting through messy terminal output, or trying to stitch together logs from completely separate external services just to figure out why a single API request taking too long.

It disrupts your flow, kills your productivity, and makes finding application bugs exhausting.

Enter ZinTrust Trace.

ZinTrust Trace is our built-in observability dashboard designed specifically for the ZinTrust framework. It gives you an immediate, beautiful, and deeply integrated view into everything happening inside your application—from database queries and caching to middleware execution and background jobs.

Looking at the Trace dashboard, you instantly get the full story. Instead of guessing, you can see that a request took 31ms, and exactly how much time was spent in your RateLimit or XSS middleware down to the millisecond.

But why should you care if your MVC framework has an in-built debugger instead of just plugging in a third-party tool?

Here are 5 reasons it will completely change the way you code:

1. Zero Setup, Instant Context

Third-party observability tools are powerful, but they require agents, API keys, complicated configurations, and usually a hit to your budget. With an in-built tool like ZinTrust Trace, you get enterprise-grade visibility right out of the box. Start the server, and immediately see your auth events, exceptions, cache hits, and queries.

2. A Truly Holistic View of the Request Lifecycle

External loggers mostly just see raw "text" or isolated network requests. ZinTrust Trace understands your framework's actual architecture. It intuitively knows the difference between a MIDDLEWARE execution, a background JOB, a MAIL dispatch, and an ORM MODEL event. It groups everything tied to a single request life-cycle, giving you the complete narrative without you having to stitch it together.

3. Spot Bottlenecks Instantly

Performance issues love to hide in plain sight. Because Trace is natively hooked into the ZinTrust ORM and routing layers, it logs the exact millisecond duration of every step. Whether your auth middleware took 9ms or a complex SQL query took 100ms, you'll catch sluggish routes and N+1 query problems during development, long before they affect your users.

4. Leaner Stack, Fewer Dependencies

Every external tracking agent you bolt onto your app introduces overhead, bloat, and a maintenance tax. Relying on a deeply integrated debugger means your stack stays remarkably lean. Your application runs lighter, and you spend less time wrestling with third-party logging SDKs.

5. Code and Refactor with Absolute Confidence

When you make a large refactoring change, your automated tests only tell you if the final output is correct. ZinTrust Trace tells you if the runtime behavior is correct. Did that new service class accidentally trigger 15,000 cache reads? Did a queued job fail silently? With Trace running alongside your dev environment, you get instant behavioral feedback, making you a faster, more confident developer.

Ready to see what your code is really doing?
Level up your back-end development experience today with ZinTrust. Clean code, fast execution, and unparalleled visibility—right out of the box.

Website: zintrust.com
Documentation: zintrust.com/package-trace
NPM Package: @zintrust/trace

ZinTrust #WebDevelopment #Backend #TypeScript #Debugging #MVC #WebDev #SoftwareEngineering #DeveloperTools

Migrate MySQL, Postgres, SQLite, or SQL Server to Cloudflare D1 — with checkpoints and integrity checks

zintrust Zin — Tue, 17 Mar 2026 07:40:34 +0000

Moving an existing database to Cloudflare D1 sounds simple until you hit type mismatches, partial failures halfway through a million-row import, or find out afterwards that 3,000 rows silently didn't land.

We built @zintrust/d1-migrator to solve exactly that.

What it does

Migrates MySQL, PostgreSQL, SQLite, or SQL Server → Cloudflare D1
Resumable — checkpoints every N rows so a failure doesn't mean starting from zero
Data integrity verified — row counts + checksums validated after every batch
Dry-run mode — preview the full migration without touching D1
Interactive mode — guided prompts for tables with D1 compatibility warnings
Zero downtime — runs against your live database
TypeScript-first — full types, works with @zintrust/core

Install

npm install @zintrust/d1-migrator

Quickest possible migration (1-line CLI)

DB_CONNECTION=mysql DB_READ_HOSTS=127.0.0.1 DB_PORT=3306 DB_DATABASE=mydb DB_USERNAME=root DB_PASSWORD=secret D1_TARGET_DB=my-d1-db zin migrate-to-d1

All values can also be passed as explicit CLI flags. The order of precedence is: CLI flag → env var → default.

TypeScript API

import { D1Migrator } from '@zintrust/d1-migrator';

const progress = await D1Migrator.DataMigrator.migrateData({
  sourceConnection: 'mysql://user:password@localhost:3306/mydb',
  sourceDriver: 'mysql',
  targetDatabase: 'my-d1-db',
  targetType: 'd1',
  batchSize: 1000,
  checkpointInterval: 10000,
});

console.log(`Migrated: ${progress.processedRows} rows`);

Type conversions handled automatically

Source	D1 / SQLite	Notes
DATETIME	TEXT (ISO 8601)	Auto-converted
BIGINT	TEXT	Precision preserved
DECIMAL	TEXT	Precision preserved
JSON	TEXT	Serialized JSON string
BLOB	BLOB	Binary preserved

Resuming after a failure

zin migrate-to-d1 --resume --migration-id <id>

Checkpoints are stored in .wrangler/state/v3/migrations/ — only unprocessed rows are re-migrated.

D1 Remote Modes: How Cloudflare D1 Balances Security and DX

zintrust Zin — Mon, 02 Mar 2026 15:49:38 +0000

Ever wondered how to connect securely to Cloudflare D1 while maintaining a good developer experience? The D1RemoteAdapter implements a clever dual-mode approach that automatically adapts to your environment.

🛡️ Registry Mode: Production Security

In production, the adapter uses registry mode - a security-first approach:

// No raw SQL ever leaves your application
const result = await d1.query('SELECT * FROM users');
// Becomes: POST /zin/d1/statement { statementId: "abc123...", params: [] }

The system hashes your SQL and looks it up in a pre-approved allowlist. This means:

✅ Zero SQL Injection Risk at the network level
✅ Maximum Security even with compromised credentials
❌ Higher friction for query changes

🔧 SQL Mode: Developer Experience

In development, you get SQL mode for maximum flexibility:

// Raw SQL sent directly
const result = await d1.query('SELECT * FROM users WHERE id = ?', [userId]);
// Becomes: POST /zin/d1/query "SELECT * FROM users WHERE id = ?"

Benefits:

✅ Zero friction - write code, run immediately
✅ Migration friendly - dynamic SQL works perfectly
✅ Rapid iteration - no configuration needed

🎯 Smart Auto-Detection

The adapter automatically chooses the right mode:

Environment	Mode	Why
Production	Registry	Security first
Development	SQL	DX first
Test	SQL	Flexibility first

🚀 Why This Design Matters

This dual-mode approach solves a real problem: production apps need security, dev apps need flexibility. Instead of forcing you to choose one or the other, you get both automatically.

The registry mode's allowlist system is particularly clever - it prevents network-level SQL injection while still allowing your application to work normally. Even if attackers steal your API keys, they're limited to queries you've explicitly approved.

For anyone building production apps with D1, this pattern provides enterprise-grade security without sacrificing developer productivity.

Cloudflare #D1 #DatabaseSecurity #NodeJS #TypeScript #WebDev

ZinTrust: a TypeScript backend framework for structure without decorators

zintrust Zin — Wed, 07 Jan 2026 08:22:44 +0000

ZinTrust: structure without the ceremony (and without decorators)

If you’ve built TypeScript APIs for a while, you’ve probably felt the pull in two directions:

Super flexible stacks where structure can drift over time.
Highly opinionated frameworks where decorators/DI patterns can feel heavy (depending on your team).

I wanted a middle ground—clear structure, explicit wiring, and a minimal core.

So I’ve been building ZinTrust: a production-grade TypeScript backend framework with no Express/Fastify as the core, plus adapters you add when you need them.

Docs: https://zintrust.com
Repo: https://github.com/ZinTrust/ZinTrust
X: https://x.com/zintrustjs

What “minimal core” means (in practice)

For me it’s about:

Explicit wiring you can trace when debugging.
Composability (add what you need; avoid pulling in the world by default).
Type-first ergonomics without leaning on magic.

A tiny routing example

Here’s the style of routing / grouping:

import { Router, type IRouter } from '@zintrust/core';

export function registerRoutes(router: IRouter): void {
  Router.group(router, '/api/v1', (r) => {
    Router.resource(r, '/users', { index, show, store, update, destroy });
  });
}

Quickstart

If you want to kick the tires quickly:

npm i -g @zintrust/core
zin new my-app
cd my-app
zin start

The feedback I want (seriously)

This is the phase where docs and onboarding matter more than “features”. If you try it, I’d love blunt feedback on:

Where do you get stuck in the quickstart?
Which concepts feel unclear (routing, structure, ORM, config, etc.)?
What would make you confident this is production-ready?

Reply here, open an issue, or join the community:

If you only look at one thing

If you only have 2 minutes, check the docs and tell me what’s confusing:

https://zintrust.com

Thanks for reading—and if you try it, thank you even more for the critique.