@statewalker/webrun-files-sqlite 0.10.0

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { SqliteFilesApi, type SqliteFilesApiOptions } from "./blocks/sqlite-files-api.js";
+export { type PakoStreamModule, pakoDeflateCodec, type StreamCodec, webDeflateCodec, } from "./blocks/stream-codec.js";
+export { type Codec, defaultCodec, type PakoModule, pakoCodec, rawCodec, webCodec, } from "./codec.js";
+export { type D1Database, D1SqlDriver, DoSqlDriver, type DoStorage, NodeSqlDriver, type NodeSqliteDatabase, } from "./drivers.js";
+export type { SqlDriver, SqlStatement } from "./sql.types.js";
+export { SqlarFilesApi, type SqlarFilesApiOptions } from "./sqlar-files-api.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,KAAK,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AAC1F,OAAO,EACL,KAAK,gBAAgB,EACrB,gBAAgB,EAChB,KAAK,WAAW,EAChB,eAAe,GAChB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,KAAK,KAAK,EACV,YAAY,EACZ,KAAK,UAAU,EACf,SAAS,EACT,QAAQ,EACR,QAAQ,GACT,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,KAAK,UAAU,EACf,WAAW,EACX,WAAW,EACX,KAAK,SAAS,EACd,aAAa,EACb,KAAK,kBAAkB,GACxB,MAAM,cAAc,CAAC;AACtB,YAAY,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9D,OAAO,EAAE,aAAa,EAAE,KAAK,oBAAoB,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/sql.types.d.ts

@@ -0,0 +1,25 @@
+/** One statement of a transaction. */
+export interface SqlStatement {
+    sql: string;
+    params?: unknown[];
+}
+/**
+ * The SQL port. Each method may be sync or async, so node:sqlite, a Durable
+ * Object's storage and D1 all satisfy it through a thin driver.
+ */
+export interface SqlDriver {
+    /** Rows as objects keyed by column name. */
+    all<T = Record<string, unknown>>(sql: string, ...params: unknown[]): T[] | Promise<T[]>;
+    /** Execute one statement for its effect. */
+    run(sql: string, ...params: unknown[]): void | Promise<void>;
+    /**
+     * Run the statements in order as one transaction: all apply or none do, and
+     * a failure rethrows after rolling back. Returns, per statement, a count that
+     * is zero exactly when that statement changed nothing.
+     *
+     * No statement may depend on reading another's result — D1's `batch()` cannot
+     * pass results along — so conditions belong in SQL (`WHERE EXISTS …`).
+     */
+    transaction(statements: SqlStatement[]): number[] | Promise<number[]>;
+}
+//# sourceMappingURL=sql.types.d.ts.map

package/dist/sql.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sql.types.d.ts","sourceRoot":"","sources":["../src/sql.types.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,CAAC,EAAE,OAAO,EAAE,CAAC;CACpB;AAED;;;GAGG;AACH,MAAM,WAAW,SAAS;IACxB,4CAA4C;IAC5C,GAAG,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG,CAAC,EAAE,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC;IACxF,4CAA4C;IAC5C,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7D;;;;;;;OAOG;IACH,WAAW,CAAC,UAAU,EAAE,YAAY,EAAE,GAAG,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;CACvE"}

package/dist/sqlar-files-api.d.ts

@@ -0,0 +1,52 @@
+import type { FileInfo, FileStats, FilesApi, ListOptions, ReadOptions } from "@statewalker/webrun-files";
+import { type Codec } from "./codec.js";
+import type { SqlDriver } from "./sql.types.js";
+export interface SqlarFilesApiOptions {
+    /** Defaults to {@link defaultCodec}. */
+    codec?: Codec;
+}
+/**
+ * A FilesApi whose whole state is one SQLite Archive table.
+ *
+ * SQLAR can also hold symlinks, which `FileKind` cannot express. The FilesApi
+ * view follows them the way POSIX `stat()` does — an unresolvable link is a
+ * missing path — and {@link symlink} / {@link readlink} expose the link itself.
+ */
+export declare class SqlarFilesApi implements FilesApi {
+    #private;
+    constructor(sql: SqlDriver, opts?: SqlarFilesApiOptions);
+    /** Creates the table if it is missing. Await it before any other call. */
+    init(): Promise<void>;
+    /** A missing path or a directory yields nothing; a file yields one chunk. */
+    read(path: string, options?: ReadOptions): AsyncIterable<Uint8Array>;
+    write(path: string, content: Iterable<Uint8Array> | AsyncIterable<Uint8Array>): Promise<void>;
+    /** `sz = 0` with `data IS NULL` is the format's only marker for a directory. */
+    mkdir(path: string): Promise<void>;
+    /** Writes a symlink row: `sz = -1`, the target verbatim as TEXT. */
+    symlink(path: string, target: string): Promise<void>;
+    /** The stored target of a symlink, or `undefined` for anything else. */
+    readlink(path: string): Promise<string | undefined>;
+    stats(path: string): Promise<FileStats | undefined>;
+    exists(path: string): Promise<boolean>;
+    /**
+     * SQLAR is a flat keyspace, so the tree is derived from names: a path that
+     * only exists as a prefix of other names is yielded as a directory, once,
+     * before anything under it. Link entries report their target's stats; a
+     * recursive listing never descends through one, which rules out cycles.
+     */
+    /**
+     * Rows come back in name order, but implicit directories and resolved links
+     * do not sit where `comparePaths` puts them, so the entries are collected,
+     * sorted and filtered by `after`. This backend already loads every row of
+     * the directory; sorting them costs no extra reads.
+     */
+    list(path: string, options?: ListOptions): AsyncIterable<FileInfo>;
+    remove(path: string): Promise<boolean>;
+    /**
+     * Rows are copied verbatim — mode, sz and the stored data — so a compressed
+     * row is never inflated and deflated again. Only mtime is fresh.
+     */
+    copy(source: string, target: string): Promise<boolean>;
+    move(source: string, target: string): Promise<boolean>;
+}
+//# sourceMappingURL=sqlar-files-api.d.ts.map

package/dist/sqlar-files-api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sqlar-files-api.d.ts","sourceRoot":"","sources":["../src/sqlar-files-api.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,QAAQ,EACR,SAAS,EACT,QAAQ,EACR,WAAW,EACX,WAAW,EACZ,MAAM,2BAA2B,CAAC;AAGnC,OAAO,EAAE,KAAK,KAAK,EAAgB,MAAM,YAAY,CAAC;AACtD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAuBhD,MAAM,WAAW,oBAAoB;IACnC,wCAAwC;IACxC,KAAK,CAAC,EAAE,KAAK,CAAC;CACf;AAED;;;;;;GAMG;AACH,qBAAa,aAAc,YAAW,QAAQ;;IAI5C,YAAY,GAAG,EAAE,SAAS,EAAE,IAAI,GAAE,oBAAyB,EAG1D;IAED,0EAA0E;IACpE,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAE1B;IAED,6EAA6E;IACtE,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,WAAgB,GAAG,aAAa,CAAC,UAAU,CAAC,CAe9E;IAEK,KAAK,CACT,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,QAAQ,CAAC,UAAU,CAAC,GAAG,aAAa,CAAC,UAAU,CAAC,GACxD,OAAO,CAAC,IAAI,CAAC,CAYf;IAED,gFAAgF;IAC1E,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAKvC;IAED,oEAAoE;IAC9D,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAIzD;IAED,wEAAwE;IAClE,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAGxD;IAEK,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC,CAExD;IAEK,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAE3C;IAED;;;;;OAKG;IACH;;;;;OAKG;IACI,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,WAAgB,GAAG,aAAa,CAAC,QAAQ,CAAC,CAO5E;IAwCK,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAU3C;IAED;;;OAGG;IACG,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAsB3D;IAEK,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAI3D;CAwEF"}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@statewalker/webrun-files-sqlite",
+  "version": "0.10.0",
+  "private": false,
+  "type": "module",
+  "description": "SQLite-backed FilesApi implementations",
+  "homepage": "https://github.com/statewalker/webrun-files",
+  "author": {
+    "name": "Mikhail Kotelnikov",
+    "email": "mikhail.kotelnikov@gmail.com"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git@github.com:statewalker/webrun-files.git"
+  },
+  "main": "./dist/cjs/index.cjs",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/esm/index.js",
+      "require": "./dist/cjs/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "dependencies": {
+    "@statewalker/webrun-files": "0.10.0"
+  },
+  "devDependencies": {
+    "@types/node": "^26.2.0",
+    "pako": "^3.0.2",
+    "rimraf": "^6.1.3",
+    "rolldown": "^1.2.4",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.10",
+    "@statewalker/webrun-files-tests": "3.0.0"
+  },
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "rimraf dist && rolldown -c && tsc --emitDeclarationOnly --declaration",
+    "test": "vitest run",
+    "lint": "biome lint src tests"
+  }
+}

package/src/blocks/byte-reader.ts

@@ -0,0 +1,64 @@
+/**
+ * Pull bytes from a chunk source in bounded pieces.
+ *
+ * `read(max)` hands out at most `max` bytes as a zero-copy view of the current
+ * source chunk, and pulls the next chunk only when the current one is spent.
+ * The source is therefore never read ahead of its consumer: this is the
+ * backpressure boundary between a caller's stream and block storage.
+ */
+export class ByteReader {
+  readonly #iterator: AsyncIterator<Uint8Array> | Iterator<Uint8Array>;
+  #chunk: Uint8Array | undefined;
+  #done = false;
+
+  constructor(source: Iterable<Uint8Array> | AsyncIterable<Uint8Array>) {
+    this.#iterator =
+      Symbol.asyncIterator in source
+        ? source[Symbol.asyncIterator]()
+        : (source as Iterable<Uint8Array>)[Symbol.iterator]();
+  }
+
+  /** At most `max` bytes, or `undefined` once the source is exhausted. */
+  async read(max: number): Promise<Uint8Array | undefined> {
+    while (!this.#chunk || this.#chunk.length === 0) {
+      if (this.#done) return undefined;
+      const next = await this.#iterator.next();
+      if (next.done) {
+        this.#done = true;
+        this.#chunk = undefined;
+        return undefined;
+      }
+      this.#chunk = next.value;
+    }
+    const piece = this.#chunk.subarray(0, max);
+    this.#chunk = this.#chunk.subarray(piece.length);
+    return piece;
+  }
+
+  /** Release the source early, as `break` in a `for await` would. */
+  async close(): Promise<void> {
+    if (this.#done) return;
+    this.#done = true;
+    this.#chunk = undefined;
+    await this.#iterator.return?.();
+  }
+}
+
+/** One Uint8Array from a stream's chunks — only ever used on a single block's worth. */
+export async function collectBlock(chunks: AsyncIterable<Uint8Array>): Promise<Uint8Array> {
+  const parts: Uint8Array[] = [];
+  let total = 0;
+  for await (const chunk of chunks) {
+    parts.push(chunk);
+    total += chunk.length;
+  }
+  // Always a copy: a piece may be a view into a caller's buffer, which a binding
+  // could read whole and a caller could reuse once we pull again.
+  const out = new Uint8Array(total);
+  let at = 0;
+  for (const part of parts) {
+    out.set(part, at);
+    at += part.length;
+  }
+  return out;
+}

package/src/blocks/sha256.ts

@@ -0,0 +1,116 @@
+/**
+ * Incremental SHA-256 (FIPS 180-4). WebCrypto only hashes a whole buffer, and
+ * content here arrives as a stream it must never be collected from.
+ */
+
+const K = new Uint32Array([
+  0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1, 0x923f82a4, 0xab1c5ed5,
+  0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3, 0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174,
+  0xe49b69c1, 0xefbe4786, 0x0fc19dc6, 0x240ca1cc, 0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da,
+  0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7, 0xc6e00bf3, 0xd5a79147, 0x06ca6351, 0x14292967,
+  0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13, 0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85,
+  0xa2bfe8a1, 0xa81a664b, 0xc24b8b70, 0xc76c51a3, 0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070,
+  0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a, 0x5b9cca4f, 0x682e6ff3,
+  0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208, 0x90befffa, 0xa4506ceb, 0xbef9a3f7, 0xc67178f2,
+]);
+
+export class Sha256 {
+  readonly #state = new Uint32Array([
+    0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a, 0x510e527f, 0x9b05688c, 0x1f83d9ab, 0x5be0cd19,
+  ]);
+  readonly #buffer = new Uint8Array(64);
+  readonly #words = new Uint32Array(80);
+  #buffered = 0;
+  #length = 0;
+  #finished = false;
+
+  update(bytes: Uint8Array): this {
+    if (this.#finished) throw new Error("Sha256: already digested");
+    this.#length += bytes.length;
+    let at = 0;
+    if (this.#buffered > 0) {
+      const take = Math.min(64 - this.#buffered, bytes.length);
+      this.#buffer.set(bytes.subarray(0, take), this.#buffered);
+      this.#buffered += take;
+      at = take;
+      if (this.#buffered < 64) return this;
+      this.#compress(this.#buffer, 0);
+      this.#buffered = 0;
+    }
+    for (; at + 64 <= bytes.length; at += 64) this.#compress(bytes, at);
+    if (at < bytes.length) {
+      this.#buffer.set(bytes.subarray(at));
+      this.#buffered = bytes.length - at;
+    }
+    return this;
+  }
+
+  /** Finalises the hash; the instance cannot be used afterwards. */
+  digestHex(): string {
+    if (this.#finished) throw new Error("Sha256: already digested");
+    const bitLength = this.#length * 8;
+    const padding = new Uint8Array((this.#buffered < 56 ? 56 : 120) - this.#buffered + 8);
+    padding[0] = 0x80;
+    const view = new DataView(padding.buffer);
+    view.setUint32(padding.length - 8, Math.floor(bitLength / 2 ** 32));
+    view.setUint32(padding.length - 4, bitLength >>> 0);
+    this.update(padding);
+    this.#finished = true;
+    let hex = "";
+    for (const word of this.#state) hex += word.toString(16).padStart(8, "0");
+    return hex;
+  }
+
+  #compress(bytes: Uint8Array, at: number): void {
+    const w = this.#words;
+    for (let i = 0; i < 16; i++) {
+      const j = at + i * 4;
+      w[i] = (bytes[j] << 24) | (bytes[j + 1] << 16) | (bytes[j + 2] << 8) | bytes[j + 3];
+    }
+    for (let i = 16; i < 64; i++) {
+      const a = w[i - 15];
+      const b = w[i - 2];
+      const s0 = ((a >>> 7) | (a << 25)) ^ ((a >>> 18) | (a << 14)) ^ (a >>> 3);
+      const s1 = ((b >>> 17) | (b << 15)) ^ ((b >>> 19) | (b << 13)) ^ (b >>> 10);
+      w[i] = (s1 + w[i - 7] + s0 + w[i - 16]) | 0;
+    }
+    const h = this.#state;
+    let a = h[0],
+      b = h[1],
+      c = h[2],
+      d = h[3],
+      e = h[4],
+      f = h[5],
+      g = h[6],
+      k = h[7];
+    for (let i = 0; i < 64; i++) {
+      const t1 =
+        (k +
+          (((e >>> 6) | (e << 26)) ^ ((e >>> 11) | (e << 21)) ^ ((e >>> 25) | (e << 7))) +
+          ((e & f) ^ (~e & g)) +
+          K[i] +
+          w[i]) |
+        0;
+      const t2 =
+        ((((a >>> 2) | (a << 30)) ^ ((a >>> 13) | (a << 19)) ^ ((a >>> 22) | (a << 10))) +
+          ((a & b) ^ (a & c) ^ (b & c))) |
+        0;
+      k = g;
+      g = f;
+      f = e;
+      e = (d + t1) | 0;
+      d = c;
+      c = b;
+      b = a;
+      a = (t1 + t2) | 0;
+    }
+    h[0] += a;
+    h[1] += b;
+    h[2] += c;
+    h[3] += d;
+    h[4] += e;
+    h[5] += f;
+    h[6] += g;
+    h[7] += k;
+  }
+}