event-storage 1.0.0 → 1.2.0

package/src/Partition/ReadablePartition.js

@@ -1,7 +1,9 @@
 import fs from 'fs';
 import path from 'path';
 import events from 'events';
-import { assert, alignTo, hash, binarySearch } from '../util.js';
+import { assert, alignTo, hash, binarySearch } from '../utils/util.js';
+
+
 
 const DEFAULT_READ_BUFFER_SIZE = 64 * 1024;
 const DOCUMENT_HEADER_SIZE = 16;
@@ -114,10 +116,10 @@ class ReadablePartition extends events.EventEmitter {
         fs.readSync(this.fd, headerBuffer, 0, 8 + 4, 0);
         const headerMagic = headerBuffer.toString('utf8', 0, 8);
 
-        assert(headerMagic.substr(0, 6) === HEADER_MAGIC.substr(0, 6), `Invalid file header in partition ${this.name}.`);
+        assert(headerMagic.substring(0, 6) === HEADER_MAGIC.substring(0, 6), `Invalid file header in partition ${this.name}.`);
 
         this.header = headerMagic;
-        assert(headerMagic === HEADER_MAGIC, `Invalid file version. The partition ${this.name} was created with a different library version (${headerMagic.substr(6)}).`);
+        assert(headerMagic === HEADER_MAGIC, `Invalid file version. The partition ${this.name} was created with a different library version (${headerMagic.substring(6)}).`);
 
         const metadataSize = headerBuffer.readUInt32BE(8);
         assert(metadataSize > 2 && metadataSize <= 4096, 'Invalid metadata size.');
@@ -200,51 +202,35 @@ class ReadablePartition extends events.EventEmitter {
         const dataSize = buffer.readUInt32BE(offset + 0);
         assert(dataSize > 0 && dataSize <= 64 * 1024 * 1024, `Error reading document size from ${position}, got ${dataSize}.`);
 
-        if (size && dataSize !== size) {
-            throw new InvalidDataSizeError(`Invalid document size ${dataSize} at position ${position}, expected ${size}.`);
-        }
+        assert(!size || dataSize === size, `Invalid document size ${dataSize} at position ${position}, expected ${size}.`, InvalidDataSizeError);
 
         const sequenceNumber = buffer.readUInt32BE(offset + 4);
         const time64 = buffer.readDoubleBE(offset + 8);
         return ({ dataSize, sequenceNumber, time64 });
     }
 
-    /**
-     * Prepare the read buffer for reading from the specified position.
-     *
-     * @protected
-     * @param {number} position The position in the file to prepare the read buffer for reading from.
-     * @returns {{ buffer: Buffer|null, cursor: number, length: number }} A reader object with properties `buffer`, `cursor` and `length`.
-     */
-    prepareReadBuffer(position) {
-        if (position + DOCUMENT_HEADER_SIZE >= this.size) {
-            return ({ buffer: null, cursor: 0, length: 0 });
-        }
-        let bufferCursor = position - this.readBufferPos;
-        if (this.readBufferPos < 0 || bufferCursor < 0 || bufferCursor + DOCUMENT_HEADER_SIZE + DOCUMENT_ALIGNMENT > this.readBufferLength) {
-            this.fillBuffer(position);
-            bufferCursor = 0;
-        }
-        return ({ buffer: this.readBuffer, cursor: bufferCursor, length: this.readBufferLength });
+    resolveIterationPosition(position) {
+        return position < 0 ? this.size + position + 1 : position;
     }
 
-    /**
-     * Prepare the read buffer for reading *before* the specified position. Don't try to reader *after* the returned cursor.
-     *
-     * @protected
-     * @param {number} position The position in the file to prepare the read buffer for reading before.
-     * @returns {{ buffer: Buffer|null, cursor: number, length: number }} A reader object with properties `buffer`, `cursor` and `length`.
-     */
-    prepareReadBufferBackwards(position) {
-        if (position < 0) {
-            return ({ buffer: null, cursor: 0, length: 0 });
+    selectReader(position, size, backwardsHint) {
+        if (size > 0 && backwardsHint) {
+            const bufferOffset = DOCUMENT_HEADER_SIZE + size;
+            const reader = this.prepareReadBufferBackwards(position + bufferOffset, bufferOffset);
+            return { reader, bufferOffset };
         }
-        let bufferCursor = position - this.readBufferPos;
-        if (this.readBufferPos < 0 || (this.readBufferPos > 0 && bufferCursor < DOCUMENT_FOOTER_SIZE) || bufferCursor > this.readBufferLength) {
-            this.fillBuffer(Math.max(position - this.readBuffer.byteLength, 0));
-            bufferCursor = position - this.readBufferPos;
+        return { reader: this.prepareReadBuffer(position), bufferOffset: 0 };
+    }
+
+    assignHeaderOutput(headerOut, header) {
+        if (headerOut === null) {
+            return;
         }
-        return ({ buffer: this.readBuffer, cursor: bufferCursor, length: this.readBufferLength });
+        headerOut.dataSize = header.dataSize;
+        headerOut.sequenceNumber = header.sequenceNumber;
+        // Denormalize time64 relative to this partition's epoch so callers can compare
+        // timestamps across partitions without needing to know the epoch value.
+        headerOut.time64 = this.metadata.epoch + header.time64;
     }
 
     /**
@@ -255,39 +241,37 @@ class ReadablePartition extends events.EventEmitter {
      * @param {number} [size] The expected byte size of the document at the given position.
      * @param {object|null} [headerOut] Optional object to populate with the document header fields
      *   (`dataSize`, `sequenceNumber`, `time64`). Pass an existing object to avoid extra allocation.
-     * @returns {string|boolean} The data stored at the given position or false if no data could be read.
+     * @param {boolean} [backwardsHint] If set to true, will optimize buffering for backwards reads.
+     * @returns {Buffer|boolean} The data stored at the given position or false if no data could be read.
      * @throws {Error} if the storage entry at the given position is corrupted.
      * @throws {InvalidDataSizeError} if the document size at the given position does not match the provided size.
      * @throws {CorruptFileError} if the document at the given position can not be read completely.
      */
-    readFrom(position, size = 0, headerOut = null) {
+    readFrom(position, size = 0, headerOut = null, backwardsHint = false) {
         assert(this.fd, 'Partition is not opened.');
         assert((position % DOCUMENT_ALIGNMENT) === 0, `Invalid read position ${position}. Needs to be a multiple of ${DOCUMENT_ALIGNMENT}.`);
 
-        const reader = this.prepareReadBuffer(position);
-        if (reader.length < size + DOCUMENT_HEADER_SIZE) {
+        const { reader, bufferOffset } = this.selectReader(position, size, backwardsHint);
+        if (reader.length < DOCUMENT_HEADER_SIZE) {
             return false;
         }
 
+        // prepareReadBufferBackwards positions the cursor at position + bufferOffset (the end of
+        // the document data), so the previous document in file order lands inside the buffer on the next
+        // backwards read. Adjust the cursor back to the document header start before reading.
+        reader.cursor -= bufferOffset;
         let dataPosition = reader.cursor + DOCUMENT_HEADER_SIZE;
-        const { dataSize, sequenceNumber, time64 } = this.readDocumentHeader(reader.buffer, reader.cursor, position, size);
-        if (headerOut !== null) {
-            headerOut.dataSize = dataSize;
-            headerOut.sequenceNumber = sequenceNumber;
-            headerOut.time64 = time64;
-        }
+        const header = this.readDocumentHeader(reader.buffer, reader.cursor, position, size);
+        const dataSize = header.dataSize;
+        this.assignHeaderOutput(headerOut, header);
 
-        // TODO: This should only be checked on opening
         const writeSize = this.documentWriteSize(dataSize);
-        if (position + writeSize > this.size) {
-            throw new CorruptFileError(`Invalid document at position ${position}. This may be caused by an unfinished write.`);
-        }
+        assert(position + writeSize <= this.size, `Invalid document at position ${position}. This may be caused by an unfinished write.`, CorruptFileError);
 
         if (dataSize + DOCUMENT_HEADER_SIZE > reader.buffer.byteLength) {
-            //console.log('sync read for large document size', dataLength, 'at position', position);
             const tempReadBuffer = Buffer.allocUnsafe(dataSize);
             fs.readSync(this.fd, tempReadBuffer, 0, dataSize, this.headerSize + position + DOCUMENT_HEADER_SIZE);
-            return tempReadBuffer.toString('utf8');
+            return tempReadBuffer;
         }
 
         if (reader.cursor > 0 && dataPosition + dataSize > reader.length) {
@@ -295,7 +279,48 @@ class ReadablePartition extends events.EventEmitter {
             dataPosition = DOCUMENT_HEADER_SIZE;
         }
 
-        return reader.buffer.toString('utf8', dataPosition, dataPosition + dataSize);
+        // reader.buffer is a shared buffer filled by fillBuffer; callers must consume the returned
+        // view before the next readFrom call (which may fill the same buffer region).
+        return reader.buffer.subarray(dataPosition, dataPosition + dataSize);
+    }
+
+    /**
+     * Prepare the read buffer for reading from the specified position.
+     *
+     * @protected
+     * @param {number} position The position in the file to prepare the read buffer for reading from.
+     * @returns {{ buffer: Buffer|null, cursor: number, length: number }} A reader object with properties `buffer`, `cursor` and `length`.
+     */
+    prepareReadBuffer(position) {
+        if (position + DOCUMENT_HEADER_SIZE >= this.size) {
+            return ({ buffer: null, cursor: 0, length: 0 });
+        }
+        let bufferCursor = position - this.readBufferPos;
+        if (this.readBufferPos < 0 || bufferCursor < 0 || bufferCursor + DOCUMENT_HEADER_SIZE + DOCUMENT_ALIGNMENT > this.readBufferLength) {
+            this.fillBuffer(position);
+            bufferCursor = 0;
+        }
+        return ({ buffer: this.readBuffer, cursor: bufferCursor, length: this.readBufferLength });
+    }
+
+    /**
+     * Prepare the read buffer for reading *before* the specified position. Don't try to read *after* the returned cursor.
+     *
+     * @protected
+     * @param {number} position The position in the file to prepare the read buffer for reading before.
+     * @param {number} [size] The amount of bytes that need to be buffered before position. By default, only guarantees that the document footer can be read.
+     * @returns {{ buffer: Buffer|null, cursor: number, length: number }} A reader object with properties `buffer`, `cursor` and `length`.
+     */
+    prepareReadBufferBackwards(position, size = 0) {
+        if (position < 0) {
+            return ({ buffer: null, cursor: 0, length: 0 });
+        }
+        let bufferCursor = position - this.readBufferPos;
+        if (this.readBufferPos < 0 || (this.readBufferPos > 0 && bufferCursor < size + DOCUMENT_FOOTER_SIZE) || bufferCursor > this.readBufferLength) {
+            this.fillBuffer(Math.max(position - this.readBuffer.byteLength, 0));
+            bufferCursor = position - this.readBufferPos;
+        }
+        return ({ buffer: this.readBuffer, cursor: bufferCursor, length: this.readBufferLength });
     }
 
     /**
@@ -307,7 +332,7 @@ class ReadablePartition extends events.EventEmitter {
      */
     findDocumentPositionBefore(position) {
         assert(this.fd, 'Partition is not opened.');
-        position -= (position % DOCUMENT_ALIGNMENT);
+        if (position > 0) position -= (position % DOCUMENT_ALIGNMENT);
         if (position <= 0) {
             return false;
         }
@@ -373,49 +398,49 @@ class ReadablePartition extends events.EventEmitter {
     }
 
     /**
-     * Find the first document whose sequenceNumber is >= the given value.
+     * Find a document around the target sequence number using one of two binary-search modes.
      * Uses readLast() to short-circuit when the partition contains no such document.
      * Uses a binary search over file positions via readDocumentBefore() to locate the
-     * document. The search tracks both the lower bound (position just after the last
-     * confirmed "< sequenceNumber" doc) and the upper bound (minimum position of any
-     * probed doc with sequenceNumber >= target). The upper bound, when available, is
-     * the exact target document, so no further linear scan is needed.
+     * document and tracks nearest candidates on both sides of the target.
      *
      * @api
      * @param {number} sequenceNumber The 0-based sequence number to search for.
-     * @returns {{ reader: Generator<string>, headerOut: object, data: string }|null}
-     *   The matched document with its reader and shared headerOut, or null if no such document exists.
+     * @param {boolean} [min=true] When true, returns the first document with sequenceNumber >= target.
+     *   When false, returns the last document with sequenceNumber <= target.
+     * @returns {{ data: Buffer, header: object, position: number }|null}
+     *   The matched document with its header and position, or null if no such document exists.
      */
-    findDocument(sequenceNumber) {
+    findDocument(sequenceNumber, min = true) {
         const last = this.readLast();
-        if (!last || last.header.sequenceNumber < sequenceNumber) {
+        if (!last) {
             return null;
         }
 
-        let startPosition = this.size;
-        binarySearch(
+        if (min && last.header.sequenceNumber < sequenceNumber) {
+            return null;
+        }
+
+        const [low, high] = binarySearch(
             sequenceNumber,
             this.size,
             (pos) => {
                 const doc = this.readDocumentBefore(pos);
-                if (!doc) return sequenceNumber;
-                if (doc.header.sequenceNumber < sequenceNumber) {
-                    startPosition = Math.max(startPosition, doc.position + this.documentWriteSize(doc.header.dataSize));
-                } else {
-                    startPosition = Math.min(startPosition, doc.position);
-                }
-                return doc.header.sequenceNumber;
+                return doc ? doc.header.sequenceNumber : Number.MIN_SAFE_INTEGER;
             }
         );
 
-        const headerOut = {};
-        const data = this.readFrom(startPosition, 0, headerOut);
+        const position = this.findDocumentPositionBefore(min ? low : high);
+        if (position === false || position < 0) {
+            return null;
+        }
+
+        const header = {};
+        const data = this.readFrom(position, 0, header);
         /* istanbul ignore if */
         if (data === false) {
             return null;
         }
-        headerOut.position = startPosition;
-        return { headerOut, data };
+        return { data, header, position };
     }
 
     /**
@@ -424,10 +449,10 @@ class ReadablePartition extends events.EventEmitter {
      * @param {object|null} [headerOut] Optional object to populate with document header fields
      *   (`dataSize`, `sequenceNumber`, `time64`, `position`) on each yield. Pass an existing object
      *   to avoid extra allocation. The object is mutated in place before each yield.
-     * @returns {Generator<string>} A generator that returns all documents in this partition.
+     * @returns {Generator<Buffer>} A generator that returns all documents in this partition.
      */
     *readAll(after = 0, headerOut = null) {
-        let position = after < 0 ? this.size + after + 1 : after;
+        let position = this.resolveIterationPosition(after);
         const internalHeader = headerOut !== null ? headerOut : {};
         let data;
         while ((data = this.readFrom(position, 0, internalHeader)) !== false) {
@@ -442,16 +467,59 @@ class ReadablePartition extends events.EventEmitter {
     /**
      * @api
      * @param {number} [before] The document position to start reading backward from.
-     * @returns {Generator<string>} A generator that returns all documents in this partition in reverse order.
+     * @param {object|null} [headerOut] Optional object to populate with document header fields
+     *   (`dataSize`, `sequenceNumber`, `time64`, `position`) on each yield.
+     * @returns {Generator<Buffer>} A generator that returns all documents in this partition in reverse order.
      */
-    *readAllBackwards(before = -1) {
-        let position = before < 0 ? this.size + before + 1 : before;
+    *readAllBackwards(before = -1, headerOut = null) {
+        let position = this.resolveIterationPosition(before);
+        const internalHeader = headerOut !== null ? headerOut : {};
         while ((position = this.findDocumentPositionBefore(position)) !== false) {
-            const data = this.readFrom(position);
+            const data = this.readFrom(position, 0, internalHeader, true);
+            if (headerOut !== null) {
+                headerOut.position = position;
+            }
             yield data;
         }
     }
+
+    /**
+     * Read documents with sequenceNumber in the inclusive range [from, until].
+     * If from > until, documents are yielded in reverse order.
+     *
+     * @api
+     * @param {number} [from=0]
+     * @param {number} [until=Number.MAX_SAFE_INTEGER]
+     * @returns {Generator<{ data: Buffer, header: object, entry: object }>}
+     */
+    *readRange(from = 0, until = Number.MAX_SAFE_INTEGER) {
+        const forwards = from <= until;
+        const lo = Math.min(from, until);
+        const hi = Math.max(from, until);
+        const found = this.findDocument(forwards ? lo : hi, forwards);
+        if (!found || found.header.sequenceNumber < lo || found.header.sequenceNumber > hi) {
+            return;
+        }
+
+        const entry = { partition: this.id };
+        const header = {};
+        const iterator = forwards
+            ? this.readAll(found.position, header)
+            : this.readAllBackwards(found.position + this.documentWriteSize(found.header.dataSize), header);
+
+        for (const data of iterator) {
+            if (header.sequenceNumber < lo || header.sequenceNumber > hi) {
+                return;
+            }
+            entry.number = header.sequenceNumber;
+            entry.position = header.position;
+            entry.size = header.dataSize;
+            yield { data, header, entry };
+        }
+    }
+
+
 }
 
 export default ReadablePartition;
-export { CorruptFileError, InvalidDataSizeError, HEADER_MAGIC, DOCUMENT_SEPARATOR, DOCUMENT_ALIGNMENT, DOCUMENT_HEADER_SIZE, DOCUMENT_FOOTER_SIZE };
+export { CorruptFileError, InvalidDataSizeError, HEADER_MAGIC, DOCUMENT_SEPARATOR, DOCUMENT_ALIGNMENT, DOCUMENT_HEADER_SIZE, DOCUMENT_FOOTER_SIZE };

package/src/Partition/WritablePartition.js

@@ -1,6 +1,8 @@
 import fs from 'fs';
 import ReadablePartition, { CorruptFileError, HEADER_MAGIC, DOCUMENT_ALIGNMENT, DOCUMENT_SEPARATOR, DOCUMENT_HEADER_SIZE, DOCUMENT_FOOTER_SIZE } from './ReadablePartition.js';
-import { assert, buildMetadataHeader, alignTo, ensureDirectory } from '../util.js';
+import { assert, alignTo } from '../utils/util.js';
+import { buildMetadataHeader } from '../utils/metadataUtil.js';
+import { ensureDirectory } from '../utils/fsUtil.js';
 import Clock from '../Clock.js';
 
 const DEFAULT_WRITE_BUFFER_SIZE = 16 * 1024;
@@ -175,22 +177,34 @@ class WritablePartition extends ReadablePartition {
      * @returns {number} The size of the document header
      */
     writeDocumentHeader(buffer, offset, dataSize, sequenceNumber = null, time64 = null) {
-        if (sequenceNumber === null) {
-            sequenceNumber = 0;
-        }
-        if (time64 === null) {
-            time64 = this.clock.time();
-        }
+        ({ sequenceNumber, time64 } = this.normalizeWriteMetadata(sequenceNumber, time64));
         /* istanbul ignore if */
-        if (time64 < 0) {
-            throw new Error('Time may not be negative!');
-        }
+        assert(time64 >= 0, 'Time may not be negative!');
+
         buffer.writeUInt32BE(dataSize, offset);
         buffer.writeUInt32BE(sequenceNumber, offset + 4);
         buffer.writeDoubleBE(time64, offset + 8);
         return DOCUMENT_HEADER_SIZE;
     }
 
+    normalizeWriteMetadata(sequenceNumber, time64) {
+        return {
+            sequenceNumber: sequenceNumber === null ? 0 : sequenceNumber,
+            time64: time64 === null ? this.clock.time() : time64
+        };
+    }
+
+    normalizeWriteArguments(sequenceNumber, callback) {
+        if (typeof sequenceNumber === 'function') {
+            return { sequenceNumber: null, callback: sequenceNumber };
+        }
+        return { sequenceNumber, callback };
+    }
+
+    shouldWriteUnbuffered(dataSize) {
+        return dataSize + DOCUMENT_HEADER_SIZE >= this.writeBuffer.byteLength * 4 / 5;
+    }
+
     /**
      * Write the given data to the partition without buffering.
      * @private
@@ -208,7 +222,7 @@ class WritablePartition extends ReadablePartition {
         bytesWritten += fs.writeSync(this.fd, this.writeMetaBuffer, 0, DOCUMENT_HEADER_SIZE);
         bytesWritten += fs.writeSync(this.fd, data);
         const padSize = alignTo(dataSize + DOCUMENT_FOOTER_SIZE, DOCUMENT_ALIGNMENT);
-        bytesWritten += fs.writeSync(this.fd, DOCUMENT_PAD.substr(0, padSize));
+        bytesWritten += fs.writeSync(this.fd, DOCUMENT_PAD.substring(0, padSize));
         this.writeMetaBuffer.writeUInt32BE(dataSize, 0);
         bytesWritten += fs.writeSync(this.fd, this.writeMetaBuffer, 0, 4);
         bytesWritten += fs.writeSync(this.fd, DOCUMENT_SEPARATOR);
@@ -235,7 +249,7 @@ class WritablePartition extends ReadablePartition {
         bytesWritten += this.writeDocumentHeader(this.writeBuffer, this.writeBufferCursor, dataSize, sequenceNumber);
         bytesWritten += this.writeBuffer.write(data, this.writeBufferCursor + bytesWritten, 'utf8');
         const padSize = alignTo(dataSize + DOCUMENT_FOOTER_SIZE, DOCUMENT_ALIGNMENT);
-        bytesWritten += this.writeBuffer.write(DOCUMENT_PAD.substr(0, padSize), this.writeBufferCursor + bytesWritten, 'utf8');
+        bytesWritten += this.writeBuffer.write(DOCUMENT_PAD.substring(0, padSize), this.writeBufferCursor + bytesWritten, 'utf8');
         this.writeBuffer.writeUInt32BE(dataSize, this.writeBufferCursor + bytesWritten);
         bytesWritten += 4;
         bytesWritten += this.writeBuffer.write(DOCUMENT_SEPARATOR, this.writeBufferCursor + bytesWritten, 'utf8');
@@ -257,15 +271,12 @@ class WritablePartition extends ReadablePartition {
      */
     write(data, sequenceNumber, callback) {
         assert(this.fd, 'Partition is not opened.');
-        if (typeof sequenceNumber === 'function') {
-            callback = sequenceNumber;
-            sequenceNumber = null;
-        }
+        ({ sequenceNumber, callback } = this.normalizeWriteArguments(sequenceNumber, callback));
         const dataSize = Buffer.byteLength(data, 'utf8');
         assert(dataSize <= 64 * 1024 * 1024, 'Document is too large! Maximum is 64 MB');
 
         const dataPosition = this.size;
-        if (dataSize + DOCUMENT_HEADER_SIZE >= this.writeBuffer.byteLength * 4 / 5) {
+        if (this.shouldWriteUnbuffered(dataSize)) {
             this.size += this.writeUnbuffered(data, dataSize, sequenceNumber, callback);
         } else {
             this.size += this.writeBuffered(data, dataSize, sequenceNumber, callback);
@@ -298,15 +309,16 @@ class WritablePartition extends ReadablePartition {
      *
      * @protected
      * @param {number} position The position in the file to prepare the read buffer for reading before.
+     * @param {number} [size] The amount of bytes that need to be buffered before position. By default, only guarantees that the document footer can be read.
      * @returns {object} A reader object with properties `buffer`, `cursor` and `length`.
      */
-    prepareReadBufferBackwards(position) {
+    prepareReadBufferBackwards(position, size = 0) {
         const bufferPos = this.size - this.writeBufferCursor;
         // Handle the case when data that is still in write buffer is supposed to be read backwards
         if (this.dirtyReads && this.writeBufferCursor > 0 && position > bufferPos) {
             return { buffer: this.writeBuffer, cursor: position - bufferPos, length: this.writeBufferCursor };
         }
-        return super.prepareReadBufferBackwards(position);
+        return super.prepareReadBufferBackwards(position, size);
     }
 
     /**
@@ -315,16 +327,17 @@ class WritablePartition extends ReadablePartition {
      *
      * @api
      * @param {number} [before] The document position to start reading backward from.
-     * @returns {Generator<string>} A generator that returns all documents in this partition in reverse order.
+     * @param {object|null} [headerOut] Optional object to populate with document header fields on each yield.
+     * @returns {Generator<Buffer>} A generator that returns all documents in this partition in reverse order.
      */
-    *readAllBackwards(before = -1) {
+    *readAllBackwards(before = -1, headerOut = null) {
         if (!this.dirtyReads && this.writeBufferCursor > 0) {
             const flushedSize = this.size - this.writeBufferCursor;
             const clampedBefore = before < 0 ? flushedSize : Math.min(before, flushedSize);
-            yield* super.readAllBackwards(clampedBefore);
+            yield* super.readAllBackwards(clampedBefore, headerOut);
             return;
         }
-        yield* super.readAllBackwards(before);
+        yield* super.readAllBackwards(before, headerOut);
     }
 
     /**
@@ -386,9 +399,7 @@ class WritablePartition extends ReadablePartition {
         try {
             this.readFrom(after);
         } catch (e) {
-            if (!(e instanceof CorruptFileError)) {
-                throw new Error('Can only truncate on valid document boundaries.');
-            }
+            assert(e instanceof CorruptFileError, 'Can only truncate on valid document boundaries.');
         }
 
         fs.truncateSync(this.fileName, this.headerSize + after);

package/src/PartitionPool.js

@@ -0,0 +1,149 @@
+/**
+ * A fixed-capacity registry of partitions with LRU eviction of open file handles.
+ *
+ * All partitions are stored by their numeric id and may be queried at any time.
+ * The pool additionally tracks which partitions currently have an open file descriptor
+ * in LRU (least-recently-used) order.  When the pool is asked to open a partition and
+ * doing so would exceed the configured cap, the least-recently-used open partition is
+ * closed first to stay within the limit.
+ *
+ * Setting the cap to 0 disables eviction: all partitions are allowed to remain open
+ * simultaneously, which matches the uncapped behaviour of the original implementation.
+ */
+class PartitionPool {
+
+    /**
+     * @param {number} [maxOpen=0] Maximum number of simultaneously open partition file
+     *   handles.  0 disables the limit (no eviction).
+     */
+    constructor(maxOpen = 0) {
+        this.maxOpen = maxOpen;
+        /** Registry of all known partitions keyed by id. */
+        this.registry = Object.create(null);
+        /**
+         * Insertion-order map used for LRU tracking of open file handles.
+         * Key = partition id, value = true.
+         * Oldest (least-recently-used) entry is first; newest (most-recently-used) is last.
+         */
+        this.handles = new Map();
+    }
+
+    /**
+     * Register a partition under the given id.
+     *
+     * @param {number|string} id
+     * @param {object} partition
+     */
+    add(id, partition) {
+        this.registry[id] = partition;
+    }
+
+    /**
+     * Retrieve a registered partition without opening it.
+     *
+     * @param {number|string} id
+     * @returns {object|undefined}
+     */
+    get(id) {
+        return this.registry[id];
+    }
+
+    /**
+     * Check whether a partition with the given id is registered in the pool.
+     *
+     * @param {number|string} id
+     * @returns {boolean}
+     */
+    has(id) {
+        return id in this.registry;
+    }
+
+    /**
+     * Open the partition with the given id, applying LRU eviction if necessary.
+     *
+     * If the partition is not yet open and adding it would exceed `maxOpen`, the
+     * least-recently-used open partition is closed first.  Stale entries (partitions
+     * that were closed externally) are discarded from the LRU map as they are
+     * encountered; if all tracked entries turn out to be stale the loop exits without
+     * closing any partition — the handle count stays temporarily inflated (bounded by
+     * the number of external closes since the last `open()` call) but correctness is
+     * preserved.
+     *
+     * @param {number|string} id
+     * @returns {object} The opened partition.
+     */
+    open(id) {
+        const partition = this.registry[id];
+
+        if (this.maxOpen > 0) {
+            // Remove id first — this may already bring the handle count below the cap.
+            this.handles.delete(id);
+            if (this.handles.size >= this.maxOpen) {
+                for (const [lruId] of this.handles) {
+                    this.handles.delete(lruId);
+                    const lruPartition = this.registry[lruId];
+                    if (lruPartition && lruPartition.isOpen()) {
+                        lruPartition.close();
+                        break;
+                    }
+                }
+            }
+            // (Re-)add id at the MRU end of the map.
+            this.handles.set(id, true);
+        }
+
+        partition.open();
+        return partition;
+    }
+
+    /**
+     * Invoke `callback` for every registered partition.
+     *
+     * @param {function(object): void} callback
+     */
+    forEach(callback) {
+        for (const id of Object.keys(this.registry)) {
+            callback(this.registry[id]);
+        }
+    }
+
+    /**
+     * Yield every registered partition object.
+     *
+     * @returns {Generator<object>}
+     */
+    *values() {
+        for (const id of Object.keys(this.registry)) {
+            yield this.registry[id];
+        }
+    }
+
+    /**
+     * The total number of registered partitions.
+     * @returns {number}
+     */
+    get count() {
+        return Object.keys(this.registry).length;
+    }
+
+    /**
+     * The number of open partition file handles currently tracked by the pool.
+     * @returns {number}
+     */
+    get openCount() {
+        return this.handles.size;
+    }
+
+    /**
+     * Reset the open-handle tracking without closing any partitions.
+     *
+     * Call this after externally closing all partitions (e.g. after
+     * `checkTornWrites`) to keep the pool's LRU state consistent with reality.
+     */
+    clearOpenHandles() {
+        this.handles.clear();
+    }
+
+}
+
+export default PartitionPool;