@cloudhal/storage 0.2.0 → 0.3.0

package/README.md

@@ -4,12 +4,13 @@ Storage interfaces and adapters for Cloudhal. The interface is shaped by the mos
 
 | Export | What |
 |---|---|
-| `@cloudhal/storage` | `SqlDriver`, `BlobStore`, limits, `migrate()`, `migrations`, `MemoryBlobStore` |
+| `@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`) |
+| `@cloudhal/storage/testing` | conformance suites + Miniflare helpers (`createMiniflareD1`, `createMiniflareR2`, `createMiniflareDoSqlite`) |
 
 ```ts
 import { migrate, migrations } from "@cloudhal/storage";
@@ -24,4 +25,18 @@ await sql.batch([
 
 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 and R2 suites run against Miniflare (workerd in-process), so no Cloudflare account is needed.
+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, so any `SqlDriver` suite (core-ts's included) runs on Durable Object SQLite.
+
+A whole site in one Durable Object (the playground's shape):
+
+```ts
+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
+);
+```

package/dist/src/blob/fetcher.d.ts

@@ -0,0 +1,24 @@
+import { type BlobMeta, type BlobStore } from "../types.js";
+/** The part of a Worker `Fetcher` binding (e.g. `ASSETS`) this store uses. */
+export interface BlobFetcher {
+    fetch(input: string): Promise<Response>;
+}
+export interface FetcherBlobStoreOptions {
+    /** Keys `list` reports (static assets cannot be listed). Default: none. */
+    readonly keys?: readonly string[];
+}
+/**
+ * A read-only `BlobStore` over static files (RFC-0036 §2): `key` is fetched as
+ * `/<prefix><key>` from the Worker's `ASSETS` binding. Writes throw `StorageError`. Used as the
+ * base layer of a `LayeredBlobStore` for demo media.
+ */
+export declare class FetcherBlobStore implements BlobStore {
+    #private;
+    readonly name = "fetcher";
+    constructor(fetcher: BlobFetcher, prefix: string, options?: FetcherBlobStoreOptions);
+    get(key: string): Promise<Uint8Array | null>;
+    head(key: string): Promise<BlobMeta | null>;
+    put(key: string): Promise<void>;
+    delete(key: string): Promise<void>;
+    list(prefix?: string): Promise<string[]>;
+}

package/dist/src/blob/fetcher.js

@@ -0,0 +1,73 @@
+import {
+  assertBlobKey,
+                
+                 
+  StorageError,
+  sha256OfBytes,
+} from "../types.js";
+
+/** The part of a Worker `Fetcher` binding (e.g. `ASSETS`) this store uses. */
+                              
+                                          
+ 
+
+                                          
+                                                                             
+                                    
+ 
+
+/**
+ * A read-only `BlobStore` over static files (RFC-0036 §2): `key` is fetched as
+ * `/<prefix><key>` from the Worker's `ASSETS` binding. Writes throw `StorageError`. Used as the
+ * base layer of a `LayeredBlobStore` for demo media.
+ */
+export class FetcherBlobStore                      {
+           name = "fetcher";
+           #fetcher             ;
+           #prefix        ;
+           #keys                   ;
+
+  constructor(fetcher             , prefix        , options                          = {}) {
+    this.#fetcher = fetcher;
+    this.#prefix = prefix.replace(/^\/+/, "");
+    this.#keys = [...(options.keys ?? [])].sort();
+  }
+
+  async #fetch(key        )                           {
+    assertBlobKey(key);
+    const res = await this.#fetcher.fetch(`https://assets.local/${this.#prefix}${key}`);
+    if (res.status === 404) return null;
+    if (!res.ok) throw new StorageError(`fetching ${key} failed with ${res.status}`);
+    return res;
+  }
+
+  async get(key        )                             {
+    const res = await this.#fetch(key);
+    return res ? new Uint8Array(await res.arrayBuffer()) : null;
+  }
+
+  async head(key        )                           {
+    // A full read: the size and SHA-256 must be exact, and demo media are small.
+    const res = await this.#fetch(key);
+    if (!res) return null;
+    const data = new Uint8Array(await res.arrayBuffer());
+    const ct = res.headers.get("content-type");
+    return {
+      size: data.byteLength,
+      sha256: await sha256OfBytes(data),
+      ...(ct ? { contentType: ct } : {}),
+    };
+  }
+
+  async put(key        )                {
+    throw new StorageError(`blob store "${this.name}" is read-only (put ${key})`);
+  }
+
+  async delete(key        )                {
+    throw new StorageError(`blob store "${this.name}" is read-only (delete ${key})`);
+  }
+
+  async list(prefix = "")                    {
+    return this.#keys.filter((k) => k.startsWith(prefix));
+  }
+}

package/dist/src/blob/layered.d.ts

@@ -0,0 +1,24 @@
+import { type BlobMeta, type BlobPutOptions, type BlobRange, type BlobStore, type BlobStream } from "../types.js";
+/**
+ * Reads `upper` first, then `base`; every write goes to `upper`; `list` merges both (RFC-0036 §2).
+ * The playground puts read-only demo media (`base`) under a writable per-session store (`upper`).
+ * `base` is never written: deleting a key only removes `upper`'s copy, so a base object stays
+ * readable after a delete.
+ */
+export declare class LayeredBlobStore implements BlobStore {
+    #private;
+    readonly name: string;
+    constructor(base: BlobStore, upper: BlobStore);
+    get(key: string): Promise<Uint8Array | null>;
+    head(key: string): Promise<BlobMeta | null>;
+    put(key: string, data: Uint8Array, options?: BlobPutOptions): Promise<void>;
+    putStream(key: string, data: ReadableStream<Uint8Array>, options: BlobPutOptions & {
+        size: number;
+        sha256: string;
+    }): Promise<void>;
+    getStream(key: string, options?: {
+        range?: BlobRange;
+    }): Promise<BlobStream | null>;
+    delete(key: string): Promise<void>;
+    list(prefix?: string): Promise<string[]>;
+}

package/dist/src/blob/layered.js

@@ -0,0 +1,85 @@
+import {
+  assertBlobKey,
+                
+                      
+                 
+                 
+                  
+  bytesStream,
+  resolveBlobRange,
+  StorageError,
+} from "../types.js";
+
+/**
+ * Reads `upper` first, then `base`; every write goes to `upper`; `list` merges both (RFC-0036 §2).
+ * The playground puts read-only demo media (`base`) under a writable per-session store (`upper`).
+ * `base` is never written: deleting a key only removes `upper`'s copy, so a base object stays
+ * readable after a delete.
+ */
+export class LayeredBlobStore                      {
+           name        ;
+           #base           ;
+           #upper           ;
+
+  constructor(base           , upper           ) {
+    this.#base = base;
+    this.#upper = upper;
+    this.name = `layered(${upper.name}/${base.name})`;
+  }
+
+  async get(key        )                             {
+    return (await this.#upper.get(key)) ?? this.#base.get(key);
+  }
+
+  async head(key        )                           {
+    return (await this.#upper.head(key)) ?? this.#base.head(key);
+  }
+
+  put(key        , data            , options                 )                {
+    return this.#upper.put(key, data, options);
+  }
+
+  async putStream(
+    key        ,
+    data                            ,
+    options                                                   ,
+  )                {
+    if (this.#upper.putStream) return this.#upper.putStream(key, data, options);
+    const bytes = new Uint8Array(await new Response(data).arrayBuffer());
+    return this.#upper.put(key, bytes, options);
+  }
+
+  async getStream(key        , options                        = {})                             {
+    assertBlobKey(key);
+    for (const store of [this.#upper, this.#base]) {
+      if (store.getStream) {
+        const s = await store.getStream(key, options);
+        if (s) return s;
+        continue;
+      }
+      const data = await store.get(key);
+      if (data) return streamOf(data, options.range);
+    }
+    return null;
+  }
+
+  delete(key        )                {
+    return this.#upper.delete(key);
+  }
+
+  async list(prefix = "")                    {
+    const [a, b] = await Promise.all([this.#upper.list(prefix), this.#base.list(prefix)]);
+    return [...new Set([...a, ...b])].sort();
+  }
+}
+
+function streamOf(data            , range                       )             {
+  if (!range) return { body: bytesStream(data), size: data.byteLength };
+  const r = resolveBlobRange(range, data.byteLength);
+  if (!r) throw new StorageError("range not satisfiable");
+  return {
+    body: bytesStream(data.slice(r.offset, r.offset + r.length)),
+    size: data.byteLength,
+    range: r,
+  };
+}

package/dist/src/blob/sql.d.ts

@@ -0,0 +1,32 @@
+import { type BlobMeta, type BlobPutOptions, type BlobRange, type BlobStore, type BlobStream, type SqlDriver } from "../types.js";
+export interface SqlBlobStoreOptions {
+    /** Cap on the sum of all object sizes; a put past it throws `StorageLimitError`. Default: none. */
+    readonly maxBytes?: number;
+    /** Cap on one object. Default 1 MiB, under DO SQLite's and D1's 2 MB value limit. */
+    readonly maxObjectBytes?: number;
+}
+/**
+ * A `BlobStore` kept in a table of the same SQL database (RFC-0036 §2): one database holds a
+ * whole site, as in a playground session's Durable Object. Works over any `SqlDriver`. Every put
+ * records the SHA-256 and checks a declared one; the total-size cap is checked in the same
+ * statement that writes, so concurrent puts cannot overshoot it.
+ */
+export declare class SqlBlobStore implements BlobStore {
+    #private;
+    readonly name = "sql";
+    constructor(sql: SqlDriver, options?: SqlBlobStoreOptions);
+    get(key: string): Promise<Uint8Array | null>;
+    head(key: string): Promise<BlobMeta | null>;
+    put(key: string, data: Uint8Array, options?: BlobPutOptions): Promise<void>;
+    putStream(key: string, data: ReadableStream<Uint8Array>, options: BlobPutOptions & {
+        size: number;
+        sha256: string;
+    }): Promise<void>;
+    getStream(key: string, options?: {
+        range?: BlobRange;
+    }): Promise<BlobStream | null>;
+    delete(key: string): Promise<void>;
+    list(prefix?: string): Promise<string[]>;
+    /** Sum of all object sizes, for usage displays and caps. */
+    totalBytes(): Promise<number>;
+}

package/dist/src/blob/sql.js

@@ -0,0 +1,167 @@
+import {
+  assertBlobKey,
+  BlobIntegrityError,
+                
+                      
+                 
+                 
+                  
+  bytesStream,
+  readAllBytes,
+  resolveBlobRange,
+                 
+  StorageError,
+  StorageLimitError,
+  sha256OfBytes,
+  verifyBlob,
+} from "../types.js";
+
+                                      
+                                                                                                     
+                             
+                                                                                       
+                                   
+ 
+
+const DDL =
+  "CREATE TABLE IF NOT EXISTS _blobs (key TEXT PRIMARY KEY, data BLOB NOT NULL, content_type TEXT, size INTEGER NOT NULL, sha256 TEXT NOT NULL)";
+
+/**
+ * A `BlobStore` kept in a table of the same SQL database (RFC-0036 §2): one database holds a
+ * whole site, as in a playground session's Durable Object. Works over any `SqlDriver`. Every put
+ * records the SHA-256 and checks a declared one; the total-size cap is checked in the same
+ * statement that writes, so concurrent puts cannot overshoot it.
+ */
+export class SqlBlobStore                      {
+           name = "sql";
+           #sql           ;
+           #maxBytes        ;
+           #maxObjectBytes        ;
+  #ready                           ;
+
+  constructor(sql           , options                      = {}) {
+    this.#sql = sql;
+    this.#maxBytes = options.maxBytes ?? Number.MAX_SAFE_INTEGER;
+    this.#maxObjectBytes = options.maxObjectBytes ?? 1024 * 1024;
+  }
+
+  #table()                {
+    this.#ready ??= this.#sql.exec(DDL).catch((e         ) => {
+      this.#ready = undefined;
+      throw e;
+    });
+    return this.#ready;
+  }
+
+  async get(key        )                             {
+    assertBlobKey(key);
+    await this.#table();
+    const row = await this.#sql.get                                    (
+      "SELECT data FROM _blobs WHERE key = ?",
+      [key],
+    );
+    return row ? new Uint8Array(row.data) : null;
+  }
+
+  async head(key        )                           {
+    assertBlobKey(key);
+    await this.#table();
+    const row = await this.#sql.get                                                               (
+      "SELECT size, content_type, sha256 FROM _blobs WHERE key = ?",
+      [key],
+    );
+    if (!row) return null;
+    return {
+      size: row.size,
+      sha256: row.sha256,
+      ...(row.content_type === null ? {} : { contentType: row.content_type }),
+    };
+  }
+
+  async put(key        , data            , options                 = {})                {
+    assertBlobKey(key);
+    if (options.sha256 !== undefined) await verifyBlob(data, options.sha256);
+    if (data.byteLength > this.#maxObjectBytes)
+      throw new StorageLimitError(
+        `blob is ${data.byteLength} bytes; the limit is ${this.#maxObjectBytes}`,
+      );
+    await this.#table();
+    const sha256 = options.sha256 ?? (await sha256OfBytes(data));
+    const res = await this.#sql.run(
+      `INSERT INTO _blobs (key, data, content_type, size, sha256)
+       SELECT ?, ?, ?, ?, ?
+       WHERE (SELECT coalesce(sum(size), 0) FROM _blobs WHERE key <> ?) + ? <= ?
+       ON CONFLICT (key) DO UPDATE SET data = excluded.data, content_type = excluded.content_type,
+         size = excluded.size, sha256 = excluded.sha256`,
+      [
+        key,
+        data,
+        options.contentType ?? null,
+        data.byteLength,
+        sha256,
+        key,
+        data.byteLength,
+        this.#maxBytes,
+      ],
+    );
+    if (res.changes === 0)
+      throw new StorageLimitError(`blob store is full (limit ${this.#maxBytes} bytes)`);
+  }
+
+  async putStream(
+    key        ,
+    data                            ,
+    options                                                   ,
+  )                {
+    assertBlobKey(key);
+    if (options.size > this.#maxObjectBytes)
+      throw new StorageLimitError(
+        `blob is ${options.size} bytes; the limit is ${this.#maxObjectBytes}`,
+      );
+    const bytes = await readAllBytes(data, options.size);
+    if (bytes.byteLength !== options.size)
+      throw new BlobIntegrityError(`expected ${options.size} bytes, got ${bytes.byteLength}`);
+    await this.put(key, bytes, options);
+  }
+
+  async getStream(key        , options                        = {})                             {
+    const data = await this.get(key);
+    if (!data) return null;
+    const meta = await this.head(key);
+    const ct = meta?.contentType === undefined ? {} : { contentType: meta.contentType };
+    const size = data.byteLength;
+    if (!options.range) return { body: bytesStream(data), size, ...ct };
+    const range = resolveBlobRange(options.range, size);
+    if (!range) throw new StorageError("range not satisfiable");
+    return {
+      body: bytesStream(data.slice(range.offset, range.offset + range.length)),
+      size,
+      range,
+      ...ct,
+    };
+  }
+
+  async delete(key        )                {
+    assertBlobKey(key);
+    await this.#table();
+    await this.#sql.run("DELETE FROM _blobs WHERE key = ?", [key]);
+  }
+
+  async list(prefix = "")                    {
+    await this.#table();
+    const rows = await this.#sql.all                 (
+      "SELECT key FROM _blobs WHERE substr(key, 1, ?) = ? ORDER BY key",
+      [prefix.length, prefix],
+    );
+    return rows.map((r) => r.key);
+  }
+
+  /** Sum of all object sizes, for usage displays and caps. */
+  async totalBytes()                  {
+    await this.#table();
+    const row = await this.#sql.get               (
+      "SELECT coalesce(sum(size), 0) AS n FROM _blobs",
+    );
+    return row?.n ?? 0;
+  }
+}

package/dist/src/index.d.ts

@@ -3,9 +3,13 @@
  *
  * Interfaces: `SqlDriver` (get/all/run/atomic batch/exec) and `BlobStore` (get/put/delete/list).
  * Adapters: `@cloudhal/storage/sqlite` (better-sqlite3), `@cloudhal/storage/d1`, `@cloudhal/storage/fs`,
- * `@cloudhal/storage/r2`, plus `MemoryBlobStore` here. Conformance suites: `@cloudhal/storage/testing`.
+ * `@cloudhal/storage/r2`, `@cloudhal/storage/do-sqlite` (Durable Object SQLite), plus `MemoryBlobStore`,
+ * `SqlBlobStore`, `LayeredBlobStore` and `FetcherBlobStore` here. Conformance suites: `@cloudhal/storage/testing`.
  */
 export { migrations } from "../migrations/index.js";
+export { type BlobFetcher, FetcherBlobStore, type FetcherBlobStoreOptions, } from "./blob/fetcher.js";
+export { LayeredBlobStore } from "./blob/layered.js";
 export { MemoryBlobStore } from "./blob/memory.js";
+export { SqlBlobStore, type SqlBlobStoreOptions } from "./blob/sql.js";
 export * from "./migrate.js";
 export * from "./types.js";

package/dist/src/index.js

@@ -3,10 +3,18 @@
  *
  * Interfaces: `SqlDriver` (get/all/run/atomic batch/exec) and `BlobStore` (get/put/delete/list).
  * Adapters: `@cloudhal/storage/sqlite` (better-sqlite3), `@cloudhal/storage/d1`, `@cloudhal/storage/fs`,
- * `@cloudhal/storage/r2`, plus `MemoryBlobStore` here. Conformance suites: `@cloudhal/storage/testing`.
+ * `@cloudhal/storage/r2`, `@cloudhal/storage/do-sqlite` (Durable Object SQLite), plus `MemoryBlobStore`,
+ * `SqlBlobStore`, `LayeredBlobStore` and `FetcherBlobStore` here. Conformance suites: `@cloudhal/storage/testing`.
  */
 
 export { migrations } from "../migrations/index.js";
+export {
+                   
+  FetcherBlobStore,
+                               
+} from "./blob/fetcher.js";
+export { LayeredBlobStore } from "./blob/layered.js";
 export { MemoryBlobStore } from "./blob/memory.js";
+export { SqlBlobStore,                          } from "./blob/sql.js";
 export * from "./migrate.js";
 export * from "./types.js";

package/dist/src/sql/do-sqlite.d.ts

@@ -0,0 +1,21 @@
+import { type RunResult, type SqlDriver, type SqlStatement, type SqlValue } from "../types.js";
+/**
+ * SQLite-backed Durable Object adapter (RFC-0036 §2) over `ctx.storage` of the DO that owns the
+ * database. Every call runs synchronously on the DO's own SQLite; the async signature is the
+ * `SqlDriver` contract. `batch` runs inside `transactionSync`, so a throw rolls every statement back;
+ * the transaction is never handed to callers, and `BEGIN` is refused by the runtime, so the
+ * batch-only rule holds here as on D1 (ADR-0002). D1's limits are enforced like on every adapter.
+ */
+export declare class DoSqliteDriver implements SqlDriver {
+    #private;
+    readonly name = "do-sqlite";
+    constructor(storage: DurableObjectStorage);
+    /** Bytes the database takes on disk (`ctx.storage.sql.databaseSize`), for size caps. */
+    get databaseSize(): number;
+    get<T extends Record<string, unknown>>(sql: string, params?: readonly SqlValue[]): Promise<T | undefined>;
+    all<T extends Record<string, unknown>>(sql: string, params?: readonly SqlValue[]): Promise<T[]>;
+    run(sql: string, params?: readonly SqlValue[]): Promise<RunResult>;
+    batch(statements: readonly SqlStatement[]): Promise<RunResult[]>;
+    exec(sql: string): Promise<void>;
+    close(): Promise<void>;
+}

package/dist/src/sql/do-sqlite.js

@@ -0,0 +1,94 @@
+import {
+  assertBatchLimits,
+  assertStatementLimits,
+                 
+                 
+                    
+                
+  StorageError,
+} from "../types.js";
+
+                                                    
+
+/**
+ * SQLite-backed Durable Object adapter (RFC-0036 §2) over `ctx.storage` of the DO that owns the
+ * database. Every call runs synchronously on the DO's own SQLite; the async signature is the
+ * `SqlDriver` contract. `batch` runs inside `transactionSync`, so a throw rolls every statement back;
+ * the transaction is never handed to callers, and `BEGIN` is refused by the runtime, so the
+ * batch-only rule holds here as on D1 (ADR-0002). D1's limits are enforced like on every adapter.
+ */
+export class DoSqliteDriver                      {
+           name = "do-sqlite";
+           #storage                      ;
+
+  constructor(storage                      ) {
+    this.#storage = storage;
+  }
+
+  /** Bytes the database takes on disk (`ctx.storage.sql.databaseSize`), for size caps. */
+  get databaseSize()         {
+    return this.#storage.sql.databaseSize;
+  }
+
+  #rows   (sql        , params                      = [])      {
+    assertStatementLimits(sql, params);
+    const cursor = this.#storage.sql.exec(sql, ...params.map(toBinding));
+    return cursor.toArray().map((row) => fromRow(row)     );
+  }
+
+  #run(sql        , params                      = [])            {
+    this.#rows(sql, params);
+    const meta = this.#storage.sql.exec("SELECT changes() AS c, last_insert_rowid() AS id").one();
+    const changes = Number(meta.c ?? 0);
+    return { changes, lastRowId: changes > 0 ? Number(meta.id) : null };
+  }
+
+  async get                                   (
+    sql        ,
+    params                      ,
+  )                         {
+    return this.#rows   (sql, params)[0];
+  }
+
+  async all                                   (
+    sql        ,
+    params                      ,
+  )               {
+    return this.#rows   (sql, params);
+  }
+
+  async run(sql        , params                      )                     {
+    return this.#run(sql, params);
+  }
+
+  async batch(statements                         )                       {
+    assertBatchLimits(statements);
+    try {
+      return this.#storage.transactionSync(() => statements.map((s) => this.#run(s.sql, s.params)));
+    } catch (cause) {
+      throw new StorageError(`batch failed: ${(cause         ).message}`, cause);
+    }
+  }
+
+  async exec(sql        )                {
+    this.#storage.sql.exec(sql);
+  }
+
+  async close()                {
+    // The database belongs to the Durable Object; nothing to release.
+  }
+}
+
+function toBinding(value          )          {
+  if (value instanceof Uint8Array)
+    return value.buffer.slice(value.byteOffset, value.byteOffset + value.byteLength)               ;
+  return value;
+}
+
+/** BLOB columns come back as ArrayBuffer; hand them out as Uint8Array like the other adapters. */
+function fromRow(row                                 )                          {
+  const out                          = {};
+  for (const [k, v] of Object.entries(row))
+    out[k] = v instanceof ArrayBuffer ? new Uint8Array(v) : v;
+  return out;
+}

package/dist/src/testing-do.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Test harness for `DoSqliteDriver` (RFC-0036 §2 invariant 6). A Miniflare Worker holds a test-only,
+ * SQLite-backed Durable Object that runs the real driver on its own `ctx.storage`; from Node, every
+ * `SqlDriver` call is one request to that object. Suites written for any `SqlDriver` (the storage
+ * conformance suite, core-ts's behavioural suite) thereby run against Durable Object SQLite.
+ */
+import { type SqlDriver } from "./types.js";
+/**
+ * Spins up a Miniflare Worker with a SQLite-backed Durable Object running `DoSqliteDriver`.
+ * `driver(db)` returns a driver for the object named `db` (a fresh, empty database per name).
+ */
+export declare function createMiniflareDoSqlite(): Promise<{
+    driver(db?: string): SqlDriver;
+    dispose(): Promise<void>;
+}>;

package/dist/src/testing-do.js

@@ -0,0 +1,146 @@
+/**
+ * Test harness for `DoSqliteDriver` (RFC-0036 §2 invariant 6). A Miniflare Worker holds a test-only,
+ * SQLite-backed Durable Object that runs the real driver on its own `ctx.storage`; from Node, every
+ * `SqlDriver` call is one request to that object. Suites written for any `SqlDriver` (the storage
+ * conformance suite, core-ts's behavioural suite) thereby run against Durable Object SQLite.
+ */
+import {
+  BlobIntegrityError,
+                 
+                 
+                    
+                
+  StorageError,
+  StorageLimitError,
+} from "./types.js";
+
+const WORKER = `
+import { DurableObject } from "cloudflare:workers";
+import { DoSqliteDriver } from "./sql/do-sqlite.EXT";
+const b64 = (u) => { let s = ""; for (const c of u) s += String.fromCharCode(c); return btoa(s); };
+const unb64 = (s) => Uint8Array.from(atob(s), (c) => c.charCodeAt(0));
+const revive = (_k, v) => (v && typeof v === "object" && typeof v.$b === "string" ? unb64(v.$b) : v);
+const encode = (v) => JSON.stringify(v ?? null, (_k, x) => (x instanceof Uint8Array ? { $b: b64(x) } : x));
+export class TestDb extends DurableObject {
+  constructor(ctx, env) { super(ctx, env); this.driver = new DoSqliteDriver(ctx.storage); }
+  async fetch(req) {
+    const { op, args } = JSON.parse(await req.text(), revive);
+    try {
+      return new Response(encode({ ok: await this.driver[op](...args) }));
+    } catch (e) {
+      return new Response(encode({ error: { name: e.name, message: e.message } }));
+    }
+  }
+}
+export default {
+  fetch(req, env) {
+    const db = new URL(req.url).searchParams.get("db") ?? "default";
+    return env.DB.get(env.DB.idFromName(db)).fetch(req);
+  },
+};
+`;
+
+const ERRORS                                                 = {
+  StorageError,
+  StorageLimitError,
+  BlobIntegrityError,
+};
+
+const toB64 = (u            ) => Buffer.from(u).toString("base64");
+const encode = (v         ) =>
+  JSON.stringify(v, (_k, x) => (x instanceof Uint8Array ? { $b: toB64(x) } : x));
+const revive = (_k        , v         ) =>
+  v && typeof v === "object" && typeof (v                    ).$b === "string"
+    ? new Uint8Array(Buffer.from((v                  ).$b, "base64"))
+    : v;
+
+                 
+              
+                                         
+                                          
+
+/** Node-side `SqlDriver` whose every call runs `DoSqliteDriver` inside the test Durable Object. */
+class RemoteDoSqliteDriver                      {
+           name = "do-sqlite";
+           #dispatch          ;
+           #db        ;
+
+  constructor(dispatch          , db        ) {
+    this.#dispatch = dispatch;
+    this.#db = db;
+  }
+
+  async #call   (op        , args           )             {
+    const res = await this.#dispatch(`http://do.test/?db=${encodeURIComponent(this.#db)}`, {
+      method: "POST",
+      body: encode({ op, args }),
+    });
+    const out = JSON.parse(await res.text(), revive)     
+             
+                                                
+     ;
+    if (out.error) {
+      const E = ERRORS[out.error.name] ?? Error;
+      throw new E(out.error.message);
+    }
+    return out.ok     ;
+  }
+
+  async get                                   (sql        , params                      ) {
+    return (await this.#call          ("get", [sql, params ?? []])) ?? undefined;
+  }
+  all                                   (sql        , params                      ) {
+    return this.#call     ("all", [sql, params ?? []]);
+  }
+  run(sql        , params                      ) {
+    return this.#call           ("run", [sql, params ?? []]);
+  }
+  batch(statements                         ) {
+    return this.#call             ("batch", [statements]);
+  }
+  async exec(sql        ) {
+    await this.#call("exec", [sql]);
+  }
+  async close() {}
+}
+
+/**
+ * Spins up a Miniflare Worker with a SQLite-backed Durable Object running `DoSqliteDriver`.
+ * `driver(db)` returns a driver for the object named `db` (a fresh, empty database per name).
+ */
+export async function createMiniflareDoSqlite()           
+                                 
+                           
+   {
+  const { Miniflare } = await import("miniflare");
+  const { readFile } = await import("node:fs/promises");
+  const { stripTypeScriptTypes } = await import("node:module");
+  const { fileURLToPath } = await import("node:url");
+  // Sources in the repo are TypeScript; the published package carries compiled JavaScript.
+  const ext = import.meta.url.endsWith(".ts") ? "ts" : "js";
+  const load = async (rel        ) => {
+    const text = await readFile(fileURLToPath(new URL(rel, import.meta.url).href), "utf8");
+    return ext === "ts" ? stripTypeScriptTypes(text) : text;
+  };
+  const root = fileURLToPath(new URL(".", import.meta.url).href);
+  const mf = new Miniflare({
+    compatibilityDate: "2026-07-01",
+    modulesRoot: root,
+    modules: [
+      { type: "ESModule", path: `${root}worker.js`, contents: WORKER.replace("EXT", ext) },
+      {
+        type: "ESModule",
+        path: `${root}sql/do-sqlite.${ext}`,
+        contents: await load(`./sql/do-sqlite.${ext}`),
+      },
+      { type: "ESModule", path: `${root}types.${ext}`, contents: await load(`./types.${ext}`) },
+    ],
+    durableObjects: { DB: { className: "TestDb", useSQLite: true } },
+  });
+  await mf.ready;
+  const dispatch           = (url, init) => mf.dispatchFetch(url, init);
+  return {
+    driver: (db = "default") => new RemoteDoSqliteDriver(dispatch, db),
+    dispose: () => mf.dispose(),
+  };
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@cloudhal/storage",
-  "version": "0.2.0",
-  "description": "Cloudhal storage interfaces (SQL driver, blob store) with Cloudflare D1/R2 and local SQLite/filesystem adapters",
+  "version": "0.3.0",
+  "description": "Cloudhal storage interfaces (SQL driver, blob store) with Cloudflare D1/R2/Durable Object SQLite and local SQLite/filesystem adapters",
   "license": "Apache-2.0",
   "homepage": "https://cloudhal.dev",
   "repository": {
@@ -26,6 +26,10 @@
       "types": "./dist/src/sql/d1.d.ts",
       "default": "./dist/src/sql/d1.js"
     },
+    "./do-sqlite": {
+      "types": "./dist/src/sql/do-sqlite.d.ts",
+      "default": "./dist/src/sql/do-sqlite.js"
+    },
     "./r2": {
       "types": "./dist/src/blob/r2.d.ts",
       "default": "./dist/src/blob/r2.js"
@@ -45,7 +49,7 @@
     "README.md"
   ],
   "dependencies": {
-    "@cloudhal/core-contracts": "0.2.0"
+    "@cloudhal/core-contracts": "0.3.0"
   },
   "peerDependencies": {
     "better-sqlite3": "^13.0.0"