@cloudhal/storage 0.0.0-stage → 0.1.0

package/dist/src/types.d.ts

@@ -0,0 +1,131 @@
+/**
+ * Storage interfaces. Deliberately tiny and shaped by the most constrained backend
+ * (Cloudflare D1): no interactive transactions, atomic `batch()` only, ≤100 bound
+ * parameters per statement, ≤100 KB per statement, ≤1000 statements per batch.
+ * Every adapter, including the local SQLite one, enforces the same limits so nothing
+ * "works locally but not on Cloudflare" (ADR-0002).
+ */
+/** Values that can be bound to SQL parameters on every backend. Booleans are stored as 0/1 by callers. */
+export type SqlValue = string | number | null | Uint8Array;
+export interface SqlStatement {
+    readonly sql: string;
+    readonly params?: readonly SqlValue[];
+}
+export interface RunResult {
+    /** Rows changed by an INSERT/UPDATE/DELETE (0 for reads). */
+    readonly changes: number;
+    /** ROWID of the last inserted row, when the backend reports it. */
+    readonly lastRowId: number | null;
+}
+export interface SqlDriver {
+    readonly name: string;
+    /** First row of a query, or `undefined`. */
+    get<T extends Record<string, unknown> = Record<string, unknown>>(sql: string, params?: readonly SqlValue[]): Promise<T | undefined>;
+    /** All rows of a query. */
+    all<T extends Record<string, unknown> = Record<string, unknown>>(sql: string, params?: readonly SqlValue[]): Promise<T[]>;
+    /** Execute one write statement. */
+    run(sql: string, params?: readonly SqlValue[]): Promise<RunResult>;
+    /**
+     * Execute statements atomically: either all succeed or none are applied.
+     * This is the only multi-statement write primitive; there is no `transaction()`.
+     */
+    batch(statements: readonly SqlStatement[]): Promise<RunResult[]>;
+    /** Run raw multi-statement SQL (DDL in migrations). Not atomic on every backend; use `batch` for data. */
+    exec(sql: string): Promise<void>;
+    close(): Promise<void>;
+}
+export interface BlobMeta {
+    readonly size: number;
+    readonly contentType?: string;
+    /** Lower-case hex SHA-256, when the backend recorded one (R2 checksums, RFC-0004 §4.1). */
+    readonly sha256?: string;
+}
+export interface BlobPutOptions {
+    readonly contentType?: string;
+    /**
+     * Lower-case hex SHA-256 the data must have. On a mismatch the adapter throws
+     * `BlobIntegrityError` and stores nothing (RFC-0004 §4.1).
+     */
+    readonly sha256?: string;
+}
+/** A byte range: `offset` (+ `length`), or the last `suffix` bytes. */
+export type BlobRange = {
+    offset: number;
+    length?: number;
+} | {
+    suffix: number;
+};
+export interface BlobStream {
+    readonly body: ReadableStream<Uint8Array>;
+    /** Size of the whole object. */
+    readonly size: number;
+    /** The part `body` carries, when a range was asked for. */
+    readonly range?: {
+        offset: number;
+        length: number;
+    };
+    readonly contentType?: string;
+}
+/** Content store keyed by path-like strings ("nodes/<hash>.json"). Mirrors the R2 surface. */
+export interface BlobStore {
+    readonly name: string;
+    get(key: string): Promise<Uint8Array | null>;
+    head(key: string): Promise<BlobMeta | null>;
+    put(key: string, data: Uint8Array, options?: BlobPutOptions): Promise<void>;
+    delete(key: string): Promise<void>;
+    /** Keys under `prefix`, sorted ascending. */
+    list(prefix?: string): Promise<string[]>;
+    /**
+     * Streams exactly `size` bytes to `key` and verifies `sha256` before the object becomes visible;
+     * a short, long or mismatching stream stores nothing. Optional: callers fall back to buffered
+     * `put` (RFC-0004 §4.1).
+     */
+    putStream?(key: string, data: ReadableStream<Uint8Array>, options: BlobPutOptions & {
+        size: number;
+        sha256: string;
+    }): Promise<void>;
+    /** Streams an object, or a range of it. Optional: callers fall back to `get`. */
+    getStream?(key: string, options?: {
+        range?: BlobRange;
+    }): Promise<BlobStream | null>;
+}
+/** The data did not have the SHA-256 (or size) the caller declared; nothing was stored. */
+export declare class BlobIntegrityError extends Error {
+    readonly name = "BlobIntegrityError";
+}
+/**
+ * Blob keys are path-like and built from validated parts only: `[A-Za-z0-9._-/]`, no empty, `.`
+ * or `..` segment, at most 512 characters. Every adapter calls this (RFC-0004 §4.1), so a key can
+ * never escape its prefix on the filesystem or address another site's objects by traversal.
+ */
+export declare function assertBlobKey(key: string): void;
+/** Resolves a range against an object size; undefined when it cannot be satisfied (416). */
+export declare function resolveBlobRange(range: BlobRange, size: number): {
+    offset: number;
+    length: number;
+} | undefined;
+/** Lower-case hex SHA-256 of bytes (WebCrypto: Node and Workers). */
+export declare function sha256OfBytes(data: Uint8Array): Promise<string>;
+/** Reads a stream into memory, failing once it carries more than `max` bytes. */
+export declare function readAllBytes(stream: ReadableStream<Uint8Array>, max: number): Promise<Uint8Array>;
+/** A stream over bytes (the buffered fallback of `getStream`). */
+export declare function bytesStream(data: Uint8Array): ReadableStream<Uint8Array>;
+export declare const SHA256_HEX: RegExp;
+/** Throws BlobIntegrityError unless `data` is `size` bytes (when given) with SHA-256 `sha256`. */
+export declare function verifyBlob(data: Uint8Array, sha256: string, size?: number): Promise<void>;
+/** D1 limits, enforced by every SQL adapter. */
+export declare const SQL_LIMITS: {
+    readonly maxBoundParams: 100;
+    readonly maxStatementBytes: 100000;
+    readonly maxBatchStatements: 1000;
+};
+export declare class StorageLimitError extends Error {
+    readonly name = "StorageLimitError";
+}
+export declare class StorageError extends Error {
+    readonly name = "StorageError";
+    constructor(message: string, cause?: unknown);
+}
+/** Throws `StorageLimitError` when a statement would be rejected by D1. */
+export declare function assertStatementLimits(sql: string, params?: readonly SqlValue[]): void;
+export declare function assertBatchLimits(statements: readonly SqlStatement[]): void;

package/dist/src/types.js

@@ -0,0 +1,235 @@
+/**
+ * Storage interfaces. Deliberately tiny and shaped by the most constrained backend
+ * (Cloudflare D1): no interactive transactions, atomic `batch()` only, ≤100 bound
+ * parameters per statement, ≤100 KB per statement, ≤1000 statements per batch.
+ * Every adapter, including the local SQLite one, enforces the same limits so nothing
+ * "works locally but not on Cloudflare" (ADR-0002).
+ */
+
+/** Values that can be bound to SQL parameters on every backend. Booleans are stored as 0/1 by callers. */
+                                                           
+
+                               
+                       
+                                        
+ 
+
+                            
+                                                               
+                           
+                                                                     
+                                    
+ 
+
+                            
+                        
+                                              
+                                                                   
+                
+                                 
+                            
+                             
+                                                                   
+                
+                                 
+                  
+                                     
+                                                                     
+     
+                                                                           
+                                                                                   
+     
+                                                                   
+                                                                                                            
+                                   
+                         
+ 
+
+                           
+                        
+                                
+                                                                                             
+                           
+ 
+
+                                 
+                                
+     
+                                                                                
+                                                             
+     
+                           
+ 
+
+/** A byte range: `offset` (+ `length`), or the last `suffix` bytes. */
+                                                                                 
+
+                             
+                                            
+                                  
+                        
+                                                             
+                                                      
+                                
+ 
+
+/** Content store keyed by path-like strings ("nodes/<hash>.json"). Mirrors the R2 surface. */
+                            
+                        
+                                               
+                                              
+                                                                              
+                                     
+                                               
+                                           
+     
+                                                                                                   
+                                                                                                
+                           
+     
+             
+                
+                                     
+                                                               
+                   
+                                                                                   
+                                                                                       
+ 
+
+/** The data did not have the SHA-256 (or size) the caller declared; nothing was stored. */
+export class BlobIntegrityError extends Error {
+                    name = "BlobIntegrityError";
+}
+
+const KEY_RE = /^[A-Za-z0-9._\-/]+$/;
+
+/**
+ * Blob keys are path-like and built from validated parts only: `[A-Za-z0-9._-/]`, no empty, `.`
+ * or `..` segment, at most 512 characters. Every adapter calls this (RFC-0004 §4.1), so a key can
+ * never escape its prefix on the filesystem or address another site's objects by traversal.
+ */
+export function assertBlobKey(key        )       {
+  if (
+    typeof key !== "string" ||
+    key.length === 0 ||
+    key.length > 512 ||
+    !KEY_RE.test(key) ||
+    key.split("/").some((seg) => seg === "" || seg === "." || seg === "..")
+  ) {
+    throw new StorageError(`invalid blob key "${String(key).slice(0, 80)}"`);
+  }
+}
+
+/** Resolves a range against an object size; undefined when it cannot be satisfied (416). */
+export function resolveBlobRange(
+  range           ,
+  size        ,
+)                                                 {
+  if ("suffix" in range) {
+    if (!Number.isInteger(range.suffix) || range.suffix <= 0 || size === 0) return undefined;
+    const length = Math.min(range.suffix, size);
+    return { offset: size - length, length };
+  }
+  const { offset } = range;
+  if (!Number.isInteger(offset) || offset < 0 || offset >= size) return undefined;
+  const max = size - offset;
+  const length = range.length === undefined ? max : Math.min(range.length, max);
+  if (!Number.isInteger(length) || length <= 0) return undefined;
+  return { offset, length };
+}
+
+/** Lower-case hex SHA-256 of bytes (WebCrypto: Node and Workers). */
+export async function sha256OfBytes(data            )                  {
+  const digest = await crypto.subtle.digest("SHA-256", data                           );
+  return Array.from(new Uint8Array(digest), (b) => b.toString(16).padStart(2, "0")).join("");
+}
+
+/** Reads a stream into memory, failing once it carries more than `max` bytes. */
+export async function readAllBytes(
+  stream                            ,
+  max        ,
+)                      {
+  const reader = stream.getReader();
+  const chunks               = [];
+  let total = 0;
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    total += value.byteLength;
+    if (total > max) {
+      await reader.cancel().catch(() => {});
+      throw new BlobIntegrityError(`stream is longer than ${max} bytes`);
+    }
+    chunks.push(value);
+  }
+  const out = new Uint8Array(total);
+  let at = 0;
+  for (const c of chunks) {
+    out.set(c, at);
+    at += c.byteLength;
+  }
+  return out;
+}
+
+/** A stream over bytes (the buffered fallback of `getStream`). */
+export function bytesStream(data            )                             {
+  return new ReadableStream            ({
+    start(controller) {
+      if (data.byteLength > 0) controller.enqueue(data);
+      controller.close();
+    },
+  });
+}
+
+export const SHA256_HEX = /^[0-9a-f]{64}$/;
+
+/** Throws BlobIntegrityError unless `data` is `size` bytes (when given) with SHA-256 `sha256`. */
+export async function verifyBlob(data            , sha256        , size         )                {
+  if (!SHA256_HEX.test(sha256)) throw new BlobIntegrityError("sha256 must be 64 lower-case hex");
+  if (size !== undefined && data.byteLength !== size)
+    throw new BlobIntegrityError(`expected ${size} bytes, got ${data.byteLength}`);
+  if ((await sha256OfBytes(data)) !== sha256)
+    throw new BlobIntegrityError("data does not match the declared sha256");
+}
+
+/** D1 limits, enforced by every SQL adapter. */
+export const SQL_LIMITS = {
+  maxBoundParams: 100,
+  maxStatementBytes: 100_000,
+  maxBatchStatements: 1000,
+}         ;
+
+export class StorageLimitError extends Error {
+                    name = "StorageLimitError";
+}
+
+export class StorageError extends Error {
+                    name = "StorageError";
+  constructor(message        , cause          ) {
+    super(message, cause === undefined ? undefined : { cause });
+  }
+}
+
+const encoder = new TextEncoder();
+
+/** Throws `StorageLimitError` when a statement would be rejected by D1. */
+export function assertStatementLimits(sql        , params                      = [])       {
+  if (params.length > SQL_LIMITS.maxBoundParams) {
+    throw new StorageLimitError(
+      `statement binds ${params.length} parameters; the limit is ${SQL_LIMITS.maxBoundParams} (chunk the write)`,
+    );
+  }
+  if (encoder.encode(sql).byteLength > SQL_LIMITS.maxStatementBytes) {
+    throw new StorageLimitError(`statement exceeds ${SQL_LIMITS.maxStatementBytes} bytes`);
+  }
+}
+
+export function assertBatchLimits(statements                         )       {
+  if (statements.length === 0) throw new StorageError("batch requires at least one statement");
+  if (statements.length > SQL_LIMITS.maxBatchStatements) {
+    throw new StorageLimitError(
+      `batch has ${statements.length} statements; the limit is ${SQL_LIMITS.maxBatchStatements}`,
+    );
+  }
+  for (const s of statements) assertStatementLimits(s.sql, s.params);
+}

package/package.json

@@ -1,6 +1,79 @@
 {
   "name": "@cloudhal/storage",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Cloudhal storage interfaces (SQL driver, blob store) with Cloudflare D1/R2 and local SQLite/filesystem adapters",
+  "license": "Apache-2.0",
+  "homepage": "https://cloudhal.dev",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cloudhal-dev/cloudhal.git",
+    "directory": "packages/storage"
+  },
+  "bugs": {
+    "url": "https://github.com/cloudhal-dev/cloudhal/issues"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "default": "./dist/src/index.js"
+    },
+    "./sqlite": {
+      "types": "./dist/src/sql/better-sqlite3.d.ts",
+      "default": "./dist/src/sql/better-sqlite3.js"
+    },
+    "./d1": {
+      "types": "./dist/src/sql/d1.d.ts",
+      "default": "./dist/src/sql/d1.js"
+    },
+    "./r2": {
+      "types": "./dist/src/blob/r2.d.ts",
+      "default": "./dist/src/blob/r2.js"
+    },
+    "./fs": {
+      "types": "./dist/src/blob/fs.d.ts",
+      "default": "./dist/src/blob/fs.js"
+    },
+    "./testing": {
+      "types": "./dist/src/testing.d.ts",
+      "default": "./dist/src/testing.js"
+    },
+    "./migrations/*": "./dist/migrations/*"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "dependencies": {
+    "@cloudhal/core-contracts": "0.1.0"
+  },
+  "peerDependencies": {
+    "better-sqlite3": "^13.0.0"
+  },
+  "peerDependenciesMeta": {
+    "better-sqlite3": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@cloudflare/workers-types": "^5.20261007.1",
+    "@types/better-sqlite3": "^9.6.0",
+    "@types/node": "^26.6.5",
+    "better-sqlite3": "13.0.3",
+    "miniflare": "4.20260730.0",
+    "tsx": "^4.23.15",
+    "typescript": "7.0.2",
+    "vitest": "5.0.3"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "vitest run",
+    "check": "pnpm typecheck && pnpm test"
+  }
 }