@cloudhal/storage

Storage interfaces and adapters for Cloudhal. The interface is shaped by the most constrained backend, Cloudflare D1: no interactive transactions, atomic batch() only, and D1's bind/size limits enforced by every adapter so local behaviour matches production (ADR-0002).

| Export | What | |---|---| | @cloudhal/storage | SqlDriver, BlobStore, limits, migrate(), migrations, MemoryBlobStore, SqlBlobStore (blobs in a SQL table, capped), LayeredBlobStore (read-only base under a writable upper), FetcherBlobStore (read-only, over a Worker ASSETS binding) | | @cloudhal/storage/sqlite | BetterSqlite3Driver — local files or :memory: | | @cloudhal/storage/d1 | D1Driver — Cloudflare D1 binding | | @cloudhal/storage/do-sqlite | DoSqliteDriver — a SQLite-backed Durable Object's ctx.storage (RFC-0036); batch runs in transactionSync | | @cloudhal/storage/fs | FsBlobStore — directory on disk | | @cloudhal/storage/r2 | R2BlobStore — Cloudflare R2 binding | | @cloudhal/storage/testing | conformance suites + Miniflare helpers (createMiniflareD1, createMiniflareR2, createMiniflareDoSqlite); needs vitest 3 or later, and miniflare for the helpers (optional peers) |

import { migrate, migrations } from "@cloudhal/storage";
import { BetterSqlite3Driver } from "@cloudhal/storage/sqlite";

const sql = await BetterSqlite3Driver.open("cloudhal.db");
await migrate(sql, migrations);
await sql.batch([
  { sql: "UPDATE nodes SET rev = rev + 1, body = ? WHERE id = ? AND rev = ?", params: [body, id, rev] },
]);

Migrations are TypeScript modules under migrations/ (plain SQL strings) so they bundle for Workers without filesystem access. Each migration is applied as one atomic batch.

Every adapter must pass describeSqlDriverConformance / describeBlobStoreConformance; the D1, R2 and Durable Object suites run against Miniflare (workerd in-process), so no Cloudflare account is needed. createMiniflareDoSqlite() runs DoSqliteDriver inside a test-only Durable Object and hands Node a driver whose every call is one request to it, over kept-alive connections, so any SqlDriver suite (core-ts's included) runs on Durable Object SQLite.

A whole site in one Durable Object (the playground's shape):

import { FetcherBlobStore, LayeredBlobStore, migrate, migrations, SqlBlobStore } from "@cloudhal/storage";
import { DoSqliteDriver } from "@cloudhal/storage/do-sqlite";

const sql = new DoSqliteDriver(ctx.storage);
await migrate(sql, migrations);
const blobs = new LayeredBlobStore(
  new FetcherBlobStore(env.ASSETS, "demo/"),             // read-only demo media
  new SqlBlobStore(sql, { maxBytes: 8 * 1024 * 1024 }), // the session's own blobs
);