@cloudhal/storage 0.0.0-stage → 0.1.1

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

@@ -0,0 +1,18 @@
+import { type BlobMeta, type BlobPutOptions, type BlobRange, type BlobStore, type BlobStream } from "../types.js";
+/** In-memory blob store for tests and ephemeral runs. */
+export declare class MemoryBlobStore implements BlobStore {
+    #private;
+    readonly name = "memory";
+    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/memory.js

@@ -0,0 +1,79 @@
+import {
+  assertBlobKey,
+                
+                      
+                 
+                 
+                  
+  bytesStream,
+  readAllBytes,
+  resolveBlobRange,
+  StorageError,
+  verifyBlob,
+} from "../types.js";
+
+/** In-memory blob store for tests and ephemeral runs. */
+export class MemoryBlobStore                      {
+           name = "memory";
+           #objects = new Map                                                    ();
+
+  async get(key        )                             {
+    assertBlobKey(key);
+    const o = this.#objects.get(key);
+    return o ? new Uint8Array(o.data) : null;
+  }
+
+  async head(key        )                           {
+    assertBlobKey(key);
+    const o = this.#objects.get(key);
+    if (!o) return null;
+    return o.contentType === undefined
+      ? { size: o.data.byteLength }
+      : { size: o.data.byteLength, contentType: o.contentType };
+  }
+
+  async put(key        , data            , options                 = {})                {
+    assertBlobKey(key);
+    if (options.sha256 !== undefined) await verifyBlob(data, options.sha256);
+    const entry                                             = { data: new Uint8Array(data) };
+    if (options.contentType !== undefined) entry.contentType = options.contentType;
+    this.#objects.set(key, entry);
+  }
+
+  async putStream(
+    key        ,
+    data                            ,
+    options                                                   ,
+  )                {
+    assertBlobKey(key);
+    const bytes = await readAllBytes(data, options.size);
+    await verifyBlob(bytes, options.sha256, options.size);
+    await this.put(key, bytes, options);
+  }
+
+  async getStream(key        , options                        = {})                             {
+    assertBlobKey(key);
+    const o = this.#objects.get(key);
+    if (!o) return null;
+    const size = o.data.byteLength;
+    const ct = o.contentType === undefined ? {} : { contentType: o.contentType };
+    if (!options.range) return { body: bytesStream(new Uint8Array(o.data)), size, ...ct };
+    const range = resolveBlobRange(options.range, size);
+    if (!range) throw new StorageError("range not satisfiable");
+    return {
+      body: bytesStream(o.data.slice(range.offset, range.offset + range.length)),
+      size,
+      range,
+      ...ct,
+    };
+  }
+
+  async delete(key        )                {
+    assertBlobKey(key);
+    this.#objects.delete(key);
+  }
+
+  async list(prefix = "")                    {
+    return [...this.#objects.keys()].filter((k) => k.startsWith(prefix)).sort();
+  }
+}

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

@@ -0,0 +1,19 @@
+import { type BlobMeta, type BlobPutOptions, type BlobRange, type BlobStore, type BlobStream } from "../types.js";
+/** Cloudflare R2 adapter over an `R2Bucket` binding. */
+export declare class R2BlobStore implements BlobStore {
+    #private;
+    readonly name = "r2";
+    constructor(bucket: R2Bucket);
+    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/r2.js

@@ -0,0 +1,146 @@
+import {
+  assertBlobKey,
+  BlobIntegrityError,
+                
+                      
+                 
+                 
+                  
+  readAllBytes,
+  resolveBlobRange,
+  SHA256_HEX,
+  StorageError,
+} from "../types.js";
+
+const hex = (buf             ) =>
+  Array.from(new Uint8Array(buf), (b) => b.toString(16).padStart(2, "0")).join("");
+
+/** R2 refuses a put whose checksum does not match; its error names the mismatch. */
+function isChecksumError(e         )          {
+  return /checksum|digest|sha-?256|does not match|BadDigest/i.test(
+    e instanceof Error ? e.message : String(e),
+  );
+}
+
+/** Cloudflare R2 adapter over an `R2Bucket` binding. */
+export class R2BlobStore                      {
+           name = "r2";
+           #bucket          ;
+
+  constructor(bucket          ) {
+    this.#bucket = bucket;
+  }
+
+  async get(key        )                             {
+    assertBlobKey(key);
+    const obj = await this.#bucket.get(key);
+    if (!obj) return null;
+    return new Uint8Array(await obj.arrayBuffer());
+  }
+
+  async head(key        )                           {
+    assertBlobKey(key);
+    const obj = await this.#bucket.head(key);
+    if (!obj) return null;
+    const ct = obj.httpMetadata?.contentType;
+    const sha = obj.checksums?.sha256;
+    return {
+      size: obj.size,
+      ...(ct === undefined ? {} : { contentType: ct }),
+      ...(sha ? { sha256: hex(sha) } : {}),
+    };
+  }
+
+  async put(key        , data            , options                 = {})                {
+    assertBlobKey(key);
+    if (options.sha256 !== undefined && !SHA256_HEX.test(options.sha256))
+      throw new BlobIntegrityError("sha256 must be 64 lower-case hex");
+    try {
+      await this.#bucket.put(key, data, {
+        ...(options.contentType ? { httpMetadata: { contentType: options.contentType } } : {}),
+        // R2 verifies the checksum and stores nothing on a mismatch (RFC-0004 §4.1).
+        ...(options.sha256 ? { sha256: options.sha256 } : {}),
+      });
+    } catch (e) {
+      if (options.sha256 && isChecksumError(e))
+        throw new BlobIntegrityError("data does not match the declared sha256");
+      throw e;
+    }
+  }
+
+  async putStream(
+    key        ,
+    data                            ,
+    options                                                   ,
+  )                {
+    assertBlobKey(key);
+    if (!SHA256_HEX.test(options.sha256))
+      throw new BlobIntegrityError("sha256 must be 64 lower-case hex");
+    const Fixed = (
+      globalThis                
+                                                                                       
+       
+    ).FixedLengthStream;
+    if (!Fixed) {
+      // Outside workerd (Miniflare's Node proxy): buffer, bounded by the declared size.
+      const bytes = await readAllBytes(data, options.size);
+      if (bytes.byteLength !== options.size)
+        throw new BlobIntegrityError(`expected ${options.size} bytes, got ${bytes.byteLength}`);
+      return this.put(key, bytes, options);
+    }
+    // FixedLengthStream errors on a short or long body, and R2 checks the SHA-256 before the
+    // object becomes visible, so nothing is stored under a wrong name.
+    const fixed = new Fixed(options.size);
+    const piped = data.pipeTo(fixed.writable).catch((e         ) => e);
+    try {
+      await this.#bucket.put(key, fixed.readable                             , {
+        sha256: options.sha256,
+        ...(options.contentType ? { httpMetadata: { contentType: options.contentType } } : {}),
+      });
+    } catch (e) {
+      if (isChecksumError(e))
+        throw new BlobIntegrityError("data does not match the declared sha256");
+      throw new BlobIntegrityError(
+        `upload failed: ${e instanceof Error ? e.message : String(e)}`.slice(0, 200),
+      );
+    }
+    const pipeError = await piped;
+    if (pipeError) throw new BlobIntegrityError("stream did not carry the declared size");
+  }
+
+  async getStream(key        , options                        = {})                             {
+    assertBlobKey(key);
+    let range                                                ;
+    if (options.range) {
+      const head = await this.#bucket.head(key);
+      if (!head) return null;
+      range = resolveBlobRange(options.range, head.size);
+      if (!range) throw new StorageError("range not satisfiable");
+    }
+    const obj = await this.#bucket.get(key, range ? { range } : {});
+    if (!obj || !("body" in obj)) return null;
+    const ct = obj.httpMetadata?.contentType;
+    return {
+      body: obj.body                                         ,
+      size: obj.size,
+      ...(range ? { range } : {}),
+      ...(ct === undefined ? {} : { contentType: ct }),
+    };
+  }
+
+  async delete(key        )                {
+    assertBlobKey(key);
+    await this.#bucket.delete(key);
+  }
+
+  async list(prefix = "")                    {
+    const keys           = [];
+    let cursor                    ;
+    do {
+      const page = await this.#bucket.list(cursor ? { prefix, cursor } : { prefix });
+      for (const o of page.objects) keys.push(o.key);
+      cursor = page.truncated ? page.cursor : undefined;
+    } while (cursor);
+    return keys.sort();
+  }
+}

package/dist/src/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @cloudhal/storage — storage interfaces and adapters.
+ *
+ * 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`.
+ */
+export { migrations } from "../migrations/index.js";
+export { MemoryBlobStore } from "./blob/memory.js";
+export * from "./migrate.js";
+export * from "./types.js";

package/dist/src/index.js

@@ -0,0 +1,12 @@
+/**
+ * @cloudhal/storage — storage interfaces and adapters.
+ *
+ * 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`.
+ */
+
+export { migrations } from "../migrations/index.js";
+export { MemoryBlobStore } from "./blob/memory.js";
+export * from "./migrate.js";
+export * from "./types.js";

package/dist/src/migrate.d.ts

@@ -0,0 +1,17 @@
+import { type SqlDriver } from "./types.js";
+export interface Migration {
+    /** Unique, sortable name, e.g. "0001_init". */
+    readonly name: string;
+    /** One or more SQL statements separated by `;` at end of line. No semicolons inside string literals. */
+    readonly sql: string;
+}
+/** Splits a migration file into statements (semicolon at end of line, comments stripped). */
+export declare function splitStatements(sql: string): string[];
+/**
+ * Applies pending migrations in order. Each migration is one atomic `batch` (its statements plus the
+ * bookkeeping row), so a failing migration leaves the database at the previous migration.
+ */
+export declare function migrate(driver: SqlDriver, migrations: readonly Migration[]): Promise<{
+    applied: string[];
+}>;
+export declare function appliedMigrations(driver: SqlDriver): Promise<string[]>;

package/dist/src/migrate.js

@@ -0,0 +1,67 @@
+import {                                    StorageError } from "./types.js";
+
+                            
+                                                 
+                        
+                                                                                                          
+                       
+ 
+
+const MIGRATIONS_TABLE = "_migrations";
+
+/** Splits a migration file into statements (semicolon at end of line, comments stripped). */
+export function splitStatements(sql        )           {
+  return sql
+    .split("\n")
+    .filter((line) => !line.trim().startsWith("--"))
+    .join("\n")
+    .split(/;\s*(?:\n|$)/)
+    .map((s) => s.trim())
+    .filter((s) => s.length > 0);
+}
+
+/**
+ * Applies pending migrations in order. Each migration is one atomic `batch` (its statements plus the
+ * bookkeeping row), so a failing migration leaves the database at the previous migration.
+ */
+export async function migrate(
+  driver           ,
+  migrations                      ,
+)                                 {
+  await driver.exec(
+    `CREATE TABLE IF NOT EXISTS ${MIGRATIONS_TABLE} (name TEXT PRIMARY KEY, applied_at TEXT NOT NULL)`,
+  );
+  const rows = await driver.all                  (
+    `SELECT name FROM ${MIGRATIONS_TABLE} ORDER BY name`,
+  );
+  const done = new Set(rows.map((r) => r.name));
+  const sorted = [...migrations].sort((a, b) => a.name.localeCompare(b.name));
+  const names = new Set        ();
+  for (const m of sorted) {
+    if (names.has(m.name)) throw new StorageError(`duplicate migration name "${m.name}"`);
+    names.add(m.name);
+  }
+  const applied           = [];
+  for (const m of sorted) {
+    if (done.has(m.name)) continue;
+    const statements                 = splitStatements(m.sql).map((sql) => ({ sql }));
+    statements.push({
+      sql: `INSERT INTO ${MIGRATIONS_TABLE} (name, applied_at) VALUES (?, ?)`,
+      params: [m.name, new Date().toISOString()],
+    });
+    try {
+      await driver.batch(statements);
+    } catch (cause) {
+      throw new StorageError(`migration "${m.name}" failed: ${(cause         ).message}`, cause);
+    }
+    applied.push(m.name);
+  }
+  return { applied };
+}
+
+export async function appliedMigrations(driver           )                    {
+  const rows = await driver
+    .all                  (`SELECT name FROM ${MIGRATIONS_TABLE} ORDER BY name`)
+    .catch(() => []);
+  return rows.map((r) => r.name);
+}

package/dist/src/sql/better-sqlite3.d.ts

@@ -0,0 +1,23 @@
+import type Database from "better-sqlite3";
+import { type RunResult, type SqlDriver, type SqlStatement, type SqlValue } from "../types.js";
+export interface BetterSqlite3DriverOptions {
+    /** Enforce D1 limits locally (default true). Turn off only for one-off maintenance scripts. */
+    readonly enforceLimits?: boolean;
+}
+/**
+ * Local SQLite adapter over better-sqlite3 (synchronous under the hood, async interface).
+ * `batch` runs inside a SQLite transaction so it is atomic like D1's batch.
+ */
+export declare class BetterSqlite3Driver implements SqlDriver {
+    #private;
+    readonly name = "better-sqlite3";
+    constructor(db: Database.Database, options?: BetterSqlite3DriverOptions);
+    /** Open a database file (or ":memory:") and wrap it. */
+    static open(filename: string, options?: BetterSqlite3DriverOptions): Promise<BetterSqlite3Driver>;
+    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/better-sqlite3.js

@@ -0,0 +1,104 @@
+                                           
+import {
+  assertBatchLimits,
+  assertStatementLimits,
+                 
+                 
+                    
+                
+  StorageError,
+} from "../types.js";
+
+                                             
+                                                                                                 
+                                   
+ 
+
+function toParams(params                                 )             {
+  return params ? [...params] : [];
+}
+
+/**
+ * Local SQLite adapter over better-sqlite3 (synchronous under the hood, async interface).
+ * `batch` runs inside a SQLite transaction so it is atomic like D1's batch.
+ */
+export class BetterSqlite3Driver                      {
+           name = "better-sqlite3";
+           #db                   ;
+           #enforce         ;
+
+  constructor(db                   , options                             = {}) {
+    this.#db = db;
+    this.#enforce = options.enforceLimits ?? true;
+    this.#db.pragma("journal_mode = WAL");
+    this.#db.pragma("foreign_keys = ON");
+    // D1 rejects BEGIN from user SQL; mirror that so code never depends on it.
+  }
+
+  /** Open a database file (or ":memory:") and wrap it. */
+  static async open(
+    filename        ,
+    options                             = {},
+  )                               {
+    const mod = await import("better-sqlite3");
+    const db = new mod.default(filename);
+    return new BetterSqlite3Driver(db, options);
+  }
+
+  #check(sql        , params                      )       {
+    if (this.#enforce) assertStatementLimits(sql, params);
+    if (/^\s*(BEGIN|COMMIT|ROLLBACK|SAVEPOINT|RELEASE)\b/i.test(sql)) {
+      throw new StorageError(
+        "interactive transactions are not supported (D1 parity); use batch() for atomic writes",
+      );
+    }
+  }
+
+  async get                                   (
+    sql        ,
+    params                      ,
+  )                         {
+    this.#check(sql, params);
+    return this.#db.prepare(sql).get(...toParams(params))                 ;
+  }
+
+  async all                                   (
+    sql        ,
+    params                      ,
+  )               {
+    this.#check(sql, params);
+    return this.#db.prepare(sql).all(...toParams(params))       ;
+  }
+
+  async run(sql        , params                      )                     {
+    this.#check(sql, params);
+    return this.#runSync(params ? { sql, params } : { sql });
+  }
+
+  #runSync(statement              )            {
+    const stmt = this.#db.prepare(statement.sql);
+    if (stmt.reader) {
+      stmt.all(...toParams(statement.params));
+      return { changes: 0, lastRowId: null };
+    }
+    const info = stmt.run(...toParams(statement.params));
+    return { changes: info.changes, lastRowId: Number(info.lastInsertRowid) };
+  }
+
+  async batch(statements                         )                       {
+    if (this.#enforce) assertBatchLimits(statements);
+    for (const s of statements) this.#check(s.sql, s.params);
+    const tx = this.#db.transaction((stmts                         ) =>
+      stmts.map((s) => this.#runSync(s)),
+    );
+    return tx(statements);
+  }
+
+  async exec(sql        )                {
+    this.#db.exec(sql);
+  }
+
+  async close()                {
+    this.#db.close();
+  }
+}

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

@@ -0,0 +1,13 @@
+import { type RunResult, type SqlDriver, type SqlStatement, type SqlValue } from "../types.js";
+/** Cloudflare D1 adapter. Expects the `D1Database` binding from the Worker environment. */
+export declare class D1Driver implements SqlDriver {
+    #private;
+    readonly name = "d1";
+    constructor(db: D1Database);
+    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/d1.js

@@ -0,0 +1,70 @@
+import {
+  assertBatchLimits,
+  assertStatementLimits,
+                 
+                 
+                    
+                
+  StorageError,
+} from "../types.js";
+
+/** Cloudflare D1 adapter. Expects the `D1Database` binding from the Worker environment. */
+export class D1Driver                      {
+           name = "d1";
+           #db            ;
+
+  constructor(db            ) {
+    this.#db = db;
+  }
+
+  #prepare(sql        , params                      = [])                      {
+    assertStatementLimits(sql, params);
+    return this.#db.prepare(sql).bind(...params);
+  }
+
+  async get                                   (
+    sql        ,
+    params                      ,
+  )                         {
+    const row = await this.#prepare(sql, params).first   ();
+    return row ?? undefined;
+  }
+
+  async all                                   (
+    sql        ,
+    params                      ,
+  )               {
+    const res = await this.#prepare(sql, params).all   ();
+    return res.results;
+  }
+
+  async run(sql        , params                      )                     {
+    const res = await this.#prepare(sql, params).run();
+    return toRunResult(res);
+  }
+
+  async batch(statements                         )                       {
+    assertBatchLimits(statements);
+    const prepared = statements.map((s) => this.#prepare(s.sql, s.params));
+    let results            ;
+    try {
+      results = await this.#db.batch(prepared);
+    } catch (cause) {
+      throw new StorageError(`batch failed: ${(cause         ).message}`, cause);
+    }
+    return results.map(toRunResult);
+  }
+
+  async exec(sql        )                {
+    await this.#db.exec(sql);
+  }
+
+  async close()                {
+    // D1 bindings are owned by the runtime; nothing to release.
+  }
+}
+
+function toRunResult(res          )            {
+  const meta = res.meta                                              ;
+  return { changes: meta.changes ?? 0, lastRowId: meta.last_row_id ?? null };
+}