@minnowdb/core 0.7.0 → 0.7.1

package/dist/storage/toolkit/sync-file.js

@@ -1,50 +1,42 @@
-/**
- * Writes the complete buffer, retrying the short transfers permitted by sync-access handles.
- * The common path is one `write` call; retries pass subarray views and never copy payload bytes.
- */
-export function writeFully(handle, buffer, at, operation = "writing file bytes") {
-    assertTransferRange(at, buffer.byteLength, "write", operation);
-    let transferred = 0;
-    while (transferred < buffer.byteLength) {
-        const remaining = buffer.byteLength - transferred;
-        const chunk = transferred === 0 ? buffer : buffer.subarray(transferred);
-        const count = handle.write(chunk, { at: at + transferred });
-        assertTransferCount(count, remaining, "write", operation, at + transferred);
-        if (count === 0) {
-            throw new Error(`OPFS write made no progress while ${operation}: wrote ${String(transferred)} of ` +
-                `${String(buffer.byteLength)} bytes (stalled at file offset ${String(at + transferred)})`);
-        }
-        transferred += count;
+function writeFully(handle, buffer, at, operation = "writing file bytes") {
+  assertTransferRange(at, buffer.byteLength, "write", operation);
+  let transferred = 0;
+  while (transferred < buffer.byteLength) {
+    const remaining = buffer.byteLength - transferred;
+    const chunk = transferred === 0 ? buffer : buffer.subarray(transferred);
+    const count = handle.write(chunk, { at: at + transferred });
+    assertTransferCount(count, remaining, "write", operation, at + transferred);
+    if (count === 0) {
+      throw new Error(`OPFS write made no progress while ${operation}: wrote ${String(transferred)} of ${String(buffer.byteLength)} bytes (stalled at file offset ${String(at + transferred)})`);
     }
+    transferred += count;
+  }
 }
-/**
- * Reads exactly `buffer.byteLength` bytes, retrying short transfers without copying data. A zero
- * transfer before the requested range is complete is an unexpected EOF, not a successful read.
- */
-export function readFully(handle, buffer, at, operation = "reading file bytes") {
-    assertTransferRange(at, buffer.byteLength, "read", operation);
-    let transferred = 0;
-    while (transferred < buffer.byteLength) {
-        const remaining = buffer.byteLength - transferred;
-        const chunk = transferred === 0 ? buffer : buffer.subarray(transferred);
-        const count = handle.read(chunk, { at: at + transferred });
-        assertTransferCount(count, remaining, "read", operation, at + transferred);
-        if (count === 0) {
-            throw new Error(`Unexpected EOF while ${operation}: read ${String(transferred)} of ` +
-                `${String(buffer.byteLength)} bytes (EOF at file offset ${String(at + transferred)})`);
-        }
-        transferred += count;
+function readFully(handle, buffer, at, operation = "reading file bytes") {
+  assertTransferRange(at, buffer.byteLength, "read", operation);
+  let transferred = 0;
+  while (transferred < buffer.byteLength) {
+    const remaining = buffer.byteLength - transferred;
+    const chunk = transferred === 0 ? buffer : buffer.subarray(transferred);
+    const count = handle.read(chunk, { at: at + transferred });
+    assertTransferCount(count, remaining, "read", operation, at + transferred);
+    if (count === 0) {
+      throw new Error(`Unexpected EOF while ${operation}: read ${String(transferred)} of ${String(buffer.byteLength)} bytes (EOF at file offset ${String(at + transferred)})`);
     }
+    transferred += count;
+  }
 }
 function assertTransferRange(at, length, kind, operation) {
-    if (!Number.isSafeInteger(at) || at < 0 || length > Number.MAX_SAFE_INTEGER - at) {
-        throw new RangeError(`Invalid OPFS ${kind} range while ${operation}: ${String(at)}+${String(length)} ` +
-            `must be a non-negative safe-integer byte range`);
-    }
+  if (!Number.isSafeInteger(at) || at < 0 || length > Number.MAX_SAFE_INTEGER - at) {
+    throw new RangeError(`Invalid OPFS ${kind} range while ${operation}: ${String(at)}+${String(length)} must be a non-negative safe-integer byte range`);
+  }
 }
 function assertTransferCount(count, remaining, kind, operation, at) {
-    if (!Number.isSafeInteger(count) || count < 0 || count > remaining) {
-        throw new Error(`Invalid OPFS ${kind} result while ${operation}: handle reported ${String(count)} bytes ` +
-            `for a ${String(remaining)}-byte request at file offset ${String(at)}`);
-    }
+  if (!Number.isSafeInteger(count) || count < 0 || count > remaining) {
+    throw new Error(`Invalid OPFS ${kind} result while ${operation}: handle reported ${String(count)} bytes for a ${String(remaining)}-byte request at file offset ${String(at)}`);
+  }
 }
+export {
+  readFully,
+  writeFully
+};

package/dist/storage/toolkit/wal.js

@@ -1,141 +1,106 @@
 import { crc32 } from "../../block-format/index.js";
 import { decodeRecordJson, encodeRecordJson } from "./wire.js";
 import { readFully, writeFully } from "./sync-file.js";
-/**
- * The write-ahead log, framed over one synchronous file handle its single writer holds open.
- *
- * Frame layout, little-endian: `u32 magic | u32 payloadLength | u32 crc32(payload) | payload`.
- * An append is one complete synchronous transfer at the tail — normally one microsecond-scale
- * write on a held handle, with retries if the platform reports a short transfer. The only
- * artifact a crash can leave is a truncated final frame, which reads as "not written". A
- * complete frame with foreign marker or checksum-invalid bytes is corruption and fails closed.
- * Frames carry a global sequence number inside the payload; the file is truncated to zero only
- * after a checkpoint covering every frame has been flushed, so replay is always
- * newest-checkpoint-plus-tail.
- */
-const FRAME_MAGIC = 0x4c574e4d; // "MNWL"
+const FRAME_MAGIC = 1280790093;
 const FRAME_HEADER_BYTES = 12;
-/**
- * A WAL frame is control data, never bulk block data.  Bounding it prevents a corrupt length
- * field (or an accidentally enormous catalog mutation) from turning recovery into an
- * unbounded allocation.  Snapshot/block payloads live in extents, so 64 MiB leaves generous
- * headroom for legitimate schema and transaction records.
- */
-export const MAX_WAL_FRAME_BYTES = 64 * 1024 * 1024;
-export class WalWriter {
-    #handle;
-    #offset;
-    constructor(handle, offset) {
-        if (!Number.isSafeInteger(offset) || offset < 0) {
-            throw new RangeError("WAL offset is outside the safe integer range");
-        }
-        this.#handle = handle;
-        this.#offset = offset;
+const MAX_WAL_FRAME_BYTES = 64 * 1024 * 1024;
+class WalWriter {
+  #handle;
+  #offset;
+  constructor(handle, offset) {
+    if (!Number.isSafeInteger(offset) || offset < 0) {
+      throw new RangeError("WAL offset is outside the safe integer range");
     }
-    get byteLength() {
-        return this.#offset;
+    this.#handle = handle;
+    this.#offset = offset;
+  }
+  get byteLength() {
+    return this.#offset;
+  }
+  append(payload, flush) {
+    const bytes = encodeRecordJson(payload);
+    if (bytes.byteLength > MAX_WAL_FRAME_BYTES) {
+      throw new RangeError(`WAL frame payload exceeds the ${String(MAX_WAL_FRAME_BYTES)} byte limit: ` + String(bytes.byteLength));
     }
-    /** Appends one frame; with `flush`, durable before return. Synchronous — never yields. */
-    append(payload, flush) {
-        const bytes = encodeRecordJson(payload);
-        if (bytes.byteLength > MAX_WAL_FRAME_BYTES) {
-            throw new RangeError(`WAL frame payload exceeds the ${String(MAX_WAL_FRAME_BYTES)} byte limit: ` +
-                String(bytes.byteLength));
-        }
-        const frame = new Uint8Array(FRAME_HEADER_BYTES + bytes.byteLength);
-        if (this.#offset > Number.MAX_SAFE_INTEGER - frame.byteLength) {
-            throw new RangeError("WAL offset exceeds the safe integer range");
-        }
-        const view = new DataView(frame.buffer);
-        view.setUint32(0, FRAME_MAGIC, true);
-        view.setUint32(4, bytes.byteLength, true);
-        view.setUint32(8, crc32(bytes), true);
-        frame.set(bytes, FRAME_HEADER_BYTES);
-        const start = this.#offset;
-        try {
-            writeFully(this.#handle, frame, start, "appending a WAL frame");
-            if (flush)
-                this.#handle.flush();
-            this.#offset = start + frame.byteLength;
-        }
-        catch (error) {
-            // A complete write followed by a failed flush is not an acknowledged frame either.
-            // Remove it before unpublished extent bytes are rolled back.  If truncation itself
-            // fails, recovery will fail closed when it verifies the frame's referenced payloads.
-            try {
-                this.#handle.truncate(start);
-            }
-            catch {
-                // Preserve the original quota/I/O error.
-            }
-            throw error;
-        }
+    const frame = new Uint8Array(FRAME_HEADER_BYTES + bytes.byteLength);
+    if (this.#offset > Number.MAX_SAFE_INTEGER - frame.byteLength) {
+      throw new RangeError("WAL offset exceeds the safe integer range");
     }
-    /** Empties the log after a flushed checkpoint has covered every frame in it. */
-    reset() {
-        this.#handle.truncate(0);
-        // truncate() already changed the handle's logical file position. Keep the writer aligned
-        // with it even if the durability flush is refused; a later append must start at zero rather
-        // than leave a sparse, unreplayable gap after the checkpoint.
-        this.#offset = 0;
+    const view = new DataView(frame.buffer);
+    view.setUint32(0, FRAME_MAGIC, true);
+    view.setUint32(4, bytes.byteLength, true);
+    view.setUint32(8, crc32(bytes), true);
+    frame.set(bytes, FRAME_HEADER_BYTES);
+    const start = this.#offset;
+    try {
+      writeFully(this.#handle, frame, start, "appending a WAL frame");
+      if (flush)
         this.#handle.flush();
+      this.#offset = start + frame.byteLength;
+    } catch (error) {
+      try {
+        this.#handle.truncate(start);
+      } catch {
+      }
+      throw error;
     }
-    flush() {
-        this.#handle.flush();
-    }
-    close() {
-        this.#handle.close();
-    }
+  }
+  reset() {
+    this.#handle.truncate(0);
+    this.#offset = 0;
+    this.#handle.flush();
+  }
+  flush() {
+    this.#handle.flush();
+  }
+  close() {
+    this.#handle.close();
+  }
 }
-/**
- * Reads every whole, checksum-valid frame from the handle's current content, in order. A
- * truncated final frame is ignored; complete foreign or corrupt bytes are rejected. Returns the
- * payloads and the byte offset where appending should resume (the end of the last valid frame —
- * a truncated tail is overwritten).
- */
-export function replayWalFrames(handle) {
-    const payloads = [];
-    const frameEnds = [];
-    let endOffset = 0;
-    for (const frame of iterateWalFrames(handle)) {
-        payloads.push(frame.payload);
-        frameEnds.push(frame.frameEnd);
-        endOffset = frame.frameEnd;
-    }
-    return { payloads, frameEnds, endOffset };
+function replayWalFrames(handle) {
+  const payloads = [];
+  const frameEnds = [];
+  let endOffset = 0;
+  for (const frame of iterateWalFrames(handle)) {
+    payloads.push(frame.payload);
+    frameEnds.push(frame.frameEnd);
+    endOffset = frame.frameEnd;
+  }
+  return { payloads, frameEnds, endOffset };
 }
-/**
- * Streams checksum-valid frames with O(max-frame) memory. A truncated final frame is ignored;
- * complete foreign or checksum-invalid bytes are corruption and fail closed.
- */
-export function* iterateWalFrames(handle) {
-    const size = handle.getSize();
-    if (!Number.isSafeInteger(size) || size < 0) {
-        throw new Error(`Invalid WAL byte length: ${String(size)}`);
+function* iterateWalFrames(handle) {
+  const size = handle.getSize();
+  if (!Number.isSafeInteger(size) || size < 0) {
+    throw new Error(`Invalid WAL byte length: ${String(size)}`);
+  }
+  const header = new Uint8Array(FRAME_HEADER_BYTES);
+  const headerView = new DataView(header.buffer);
+  let offset = 0;
+  while (offset + FRAME_HEADER_BYTES <= size) {
+    readFully(handle, header, offset, "reading a WAL frame header for recovery");
+    if (headerView.getUint32(0, true) !== FRAME_MAGIC) {
+      throw new Error(`WAL frame marker mismatch at offset ${String(offset)}`);
+    }
+    const length = headerView.getUint32(4, true);
+    const checksum = headerView.getUint32(8, true);
+    if (length > MAX_WAL_FRAME_BYTES) {
+      throw new Error(`WAL frame at offset ${String(offset)} exceeds the ${String(MAX_WAL_FRAME_BYTES)} byte limit: ${String(length)}`);
     }
-    const header = new Uint8Array(FRAME_HEADER_BYTES);
-    const headerView = new DataView(header.buffer);
-    let offset = 0;
-    while (offset + FRAME_HEADER_BYTES <= size) {
-        readFully(handle, header, offset, "reading a WAL frame header for recovery");
-        if (headerView.getUint32(0, true) !== FRAME_MAGIC) {
-            throw new Error(`WAL frame marker mismatch at offset ${String(offset)}`);
-        }
-        const length = headerView.getUint32(4, true);
-        const checksum = headerView.getUint32(8, true);
-        if (length > MAX_WAL_FRAME_BYTES) {
-            throw new Error(`WAL frame at offset ${String(offset)} exceeds the ${String(MAX_WAL_FRAME_BYTES)} ` +
-                `byte limit: ${String(length)}`);
-        }
-        const end = offset + FRAME_HEADER_BYTES + length;
-        if (!Number.isSafeInteger(end) || end > size)
-            break;
-        const payloadBytes = new Uint8Array(length);
-        readFully(handle, payloadBytes, offset + FRAME_HEADER_BYTES, "reading a WAL frame payload for recovery");
-        if (crc32(payloadBytes) !== checksum) {
-            throw new Error(`WAL frame checksum mismatch at offset ${String(offset)}`);
-        }
-        yield { payload: decodeRecordJson(payloadBytes), frameEnd: end };
-        offset = end;
+    const end = offset + FRAME_HEADER_BYTES + length;
+    if (!Number.isSafeInteger(end) || end > size)
+      break;
+    const payloadBytes = new Uint8Array(length);
+    readFully(handle, payloadBytes, offset + FRAME_HEADER_BYTES, "reading a WAL frame payload for recovery");
+    if (crc32(payloadBytes) !== checksum) {
+      throw new Error(`WAL frame checksum mismatch at offset ${String(offset)}`);
     }
+    yield { payload: decodeRecordJson(payloadBytes), frameEnd: end };
+    offset = end;
+  }
 }
+export {
+  MAX_WAL_FRAME_BYTES,
+  WalWriter,
+  iterateWalFrames,
+  replayWalFrames
+};