npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@statewalker/db-sqlite-do

v0.1.4

Published

Durable Object SQLite (ctx.storage) driver for @statewalker/db-api, with transactions through @statewalker/db-sqlite and a node:sqlite fake for tests.

Readme

@statewalker/db-sqlite-do

What it is

A driver that implements Db from @statewalker/db-api on a Durable Object's SQLite storage (ctx.storage), on Cloudflare or on celld. Its Db works with inTransaction from @statewalker/db-sqlite. The ./fake subpath gives a Node.js stand-in for ctx.storage with the same limits, for unit tests.

Why it exists

Code written against Db (search indexes, file stores) must run inside a Durable Object as it does on Node.js and in the browser. DO SQLite differs in ways that break such code silently: SQL BEGIN is rejected, transactionSync commits at the first await, BLOBs come back as ArrayBuffer. This driver hides those differences behind the same Db and transaction call.

How to use

pnpm add @statewalker/db-sqlite-do

| Import | Gives | Environment | | --- | --- | --- | | @statewalker/db-sqlite-do | newDoSqliteDb; types DoSqlStorage, DoSqlCursor, Db, DbEntry | Durable Object (Cloudflare, celld) | | @statewalker/db-sqlite-do/fake | newFakeDoStorage; type FakeDoStorage | Node.js 22.13 or later (tests) |

newDoSqliteDb(storage) returns a Db synchronously, so it can be created in the DO constructor. Use ? placeholders.

Examples

import { DurableObject } from "cloudflare:workers";
import { inTransaction } from "@statewalker/db-sqlite";
import { newDoSqliteDb } from "@statewalker/db-sqlite-do";

export class Notes extends DurableObject {
  db = newDoSqliteDb(this.ctx.storage);

  async add(body: string) {
    await this.db.exec("CREATE TABLE IF NOT EXISTS notes (id INTEGER PRIMARY KEY, body TEXT)");
    return inTransaction(this.db, (tx) =>
      tx.query<{ id: number }>("INSERT INTO notes (body) VALUES (?) RETURNING id", [body]),
    );
  }
}

In a Node.js test:

import { newDoSqliteDb } from "@statewalker/db-sqlite-do";
import { newFakeDoStorage } from "@statewalker/db-sqlite-do/fake";

const db = newDoSqliteDb(newFakeDoStorage());

How it is tested against a real Durable Object

pnpm test:do (from the repository root) builds the workspace, starts celld dev on packages/db-sqlite-do/test-do/ with a clean state on a free port, and runs, inside a real Durable Object, the shared Db conformance suite (through a small HTTP bridge), every scenario listed in test-do/scenarios.ts (the SQLite transaction scenarios a DO can meet), and a platform probe whose expectations the ./fake must also meet. It needs celld 0.6.x on PATH; with another version it stops at once with test:do needs celld 0.6.x on PATH, found "<version>". A celld that prints no ready line within 60 seconds fails the run with celld dev was not ready within 60 s. It stops only the celld process it started. It is not part of pnpm test: run it before a release. The same root pnpm test:do also runs @statewalker/db-sqlite-index's smoke scenarios in its own test-do/.

Internals

  • Transactions use storage.transaction(async fn). It rolls back on a throw even after awaits on timers or fetch. transactionSync is not used: given an async function it commits at the first await, so a later throw rolls nothing back. The platform can run the callback again, so it must be idempotent and do no external I/O.
  • Limits of DO SQLite, and what they look like: more than 100 bound parameters rejects with too many SQL variables (pass id lists as one JSON string to json_each(?)); a BLOB or string over about 2 MB rejects with string or blob too big (celld 0.6.2 accepts 1,900,000 bytes and rejects 2,500,000; the fake rejects above 2,000,000 bytes, measuring a string in UTF-8); BEGIN, SAVEPOINT and PRAGMA reject with not authorized.
  • ON CONFLICT ROLLBACK and RAISE(ROLLBACK) fail the whole DO call. Inside inTransaction on a Durable Object, a statement that makes SQLite itself end the transaction rolls the data back, but the call in flight rejects with a transaction rollback failed: … cannot rollback - no transaction is active instead of the constraint error, and the DO instance is reset (observed on celld 0.6.2; Cloudflare unverified). Use the default ABORT conflict resolution inside transactions. The fake rejects with the same message, so inTransaction callers see it in unit tests too. An operation that runs past the platform deadline (15 s on celld) is retried rather than failed, so keep each write step small.
  • BLOBs are converted both ways. Typed-array parameters are bound as ArrayBuffer; ArrayBuffer values read back become Uint8Array, as on every other SQLite driver.
  • Input handling comes from @statewalker/db-sqlite. query rejects a second statement and empty SQL before sql.exec sees it, and true/false, undefined and Date parameters bind as 1/0, NULL and ISO 8601 text, as on every SQLite driver. How DO SQLite itself binds a bigint and reads an integer above 2^53 is not probed yet: the fake reads such an integer as a bigint (as the other drivers do), and test:do skips that scenario (DO_UNPROBED_SCENARIOS in test-do/unsupported-scenarios.ts). The real-DO run of runDbConformance also skips the scenarios its harness cannot carry, since each call is a separate HTTP request with a JSON body (call order, close during a call, BLOB and bigint round trips: DO_REMOTE_UNSUPPORTED_DB_SCENARIOS); they run on the fake.
  • close() releases nothing. The storage belongs to the DO. It only makes later calls on this Db reject with db-sqlite: the database is closed.
  • Use one Db per DO. Calls are queued inside one Db; direct ctx.storage.sql calls made elsewhere in the DO bypass that queue.
  • The fake is strict where the platform is unknown. It rejects every PRAGMA (the platform allows a few) and typed-array BLOB parameters, so code that passes on the fake does not depend on them. Its limits are checked against real DO SQLite by pnpm test:do, which runs the same probe in a celld dev Durable Object.
  • Dependencies: @statewalker/db-sqlite (queue and transactions), @statewalker/db-api (types). ./fake uses Node.js's node:sqlite.

License

MIT