document-dataply 0.0.9-alpha.1 → 0.0.9-alpha.11

package/dist/cjs/index.js

@@ -873,7 +873,7 @@ var require_cjs = __commonJS({
     };
     var AsyncMVCCStrategy = class extends MVCCStrategy {
     };
-    var Ryoiki2 = class _Ryoiki {
+    var Ryoiki = class _Ryoiki {
       readings;
       writings;
       readQueue;
@@ -1130,7 +1130,7 @@ var require_cjs = __commonJS({
       }
     };
     var AsyncMVCCTransaction = class _AsyncMVCCTransaction extends MVCCTransaction {
-      lock = new Ryoiki2();
+      lock = new Ryoiki();
       async writeLock(fn) {
         let lockId;
         return this.lock.writeLock(async (_lockId) => {
@@ -1580,83 +1580,217 @@ var require_cjs = __commonJS({
           return regexp.test(nodeValue);
         }
       };
-      verifierStartNode = {
-        gt: (v) => this.insertableNodeByPrimary(v),
-        gte: (v) => this.insertableNodeByPrimary(v),
-        lt: (v) => this.insertableNodeByPrimary(v),
-        lte: (v) => this.insertableRightestNodeByPrimary(v),
-        equal: (v) => this.insertableNodeByPrimary(v),
-        notEqual: (v) => this.leftestNode(),
-        or: (v) => this.insertableNodeByPrimary(this.lowestPrimaryValue(this.ensureValues(v))),
-        primaryGt: (v) => this.insertableNodeByPrimary(v),
-        primaryGte: (v) => this.insertableNodeByPrimary(v),
-        primaryLt: (v) => this.insertableNodeByPrimary(v),
-        primaryLte: (v) => this.insertableRightestNodeByPrimary(v),
-        primaryEqual: (v) => this.insertableNodeByPrimary(v),
-        primaryNotEqual: (v) => this.leftestNode(),
-        primaryOr: (v) => this.insertableNodeByPrimary(this.lowestPrimaryValue(this.ensureValues(v))),
-        like: (v) => this.leftestNode()
-      };
-      verifierEndNode = {
-        gt: (v) => null,
-        gte: (v) => null,
-        lt: (v) => null,
-        lte: (v) => null,
-        equal: (v) => this.insertableEndNode(v, this.verifierDirection.equal),
-        notEqual: (v) => null,
-        or: (v) => this.insertableEndNode(
-          this.highestValue(this.ensureValues(v)),
-          this.verifierDirection.or
-        ),
-        primaryGt: (v) => null,
-        primaryGte: (v) => null,
-        primaryLt: (v) => null,
-        primaryLte: (v) => null,
-        primaryEqual: (v) => this.insertableRightestEndNodeByPrimary(v),
-        primaryNotEqual: (v) => null,
-        primaryOr: (v) => this.insertableRightestEndNodeByPrimary(
-          this.highestPrimaryValue(this.ensureValues(v))
-        ),
-        like: (v) => null
-      };
-      verifierDirection = {
-        gt: 1,
-        gte: 1,
-        lt: -1,
-        lte: -1,
-        equal: 1,
-        notEqual: 1,
-        or: 1,
-        primaryGt: 1,
-        primaryGte: 1,
-        primaryLt: -1,
-        primaryLte: -1,
-        primaryEqual: 1,
-        primaryNotEqual: 1,
-        primaryOr: 1,
-        like: 1
-      };
-      /**
-       * Determines whether early termination is allowed for each condition.
-       * When true, the search will stop once a match is found and then a non-match is encountered.
-       * Only applicable for conditions that guarantee contiguous matches in a sorted B+Tree.
-       */
-      verifierEarlyTerminate = {
-        gt: false,
-        gte: false,
-        lt: false,
-        lte: false,
-        equal: true,
-        notEqual: false,
-        or: false,
-        primaryGt: false,
-        primaryGte: false,
-        primaryLt: false,
-        primaryLte: false,
-        primaryEqual: true,
-        primaryNotEqual: false,
-        primaryOr: false,
-        like: false
+      searchConfigs = {
+        gt: {
+          asc: {
+            start: (tx, v) => tx.insertableNodeByPrimary(v[0]),
+            end: () => null,
+            direction: 1,
+            earlyTerminate: false
+          },
+          desc: {
+            start: (tx) => tx.rightestNode(),
+            end: (tx, v) => tx.insertableEndNode(v[0], -1),
+            direction: -1,
+            earlyTerminate: true
+          }
+        },
+        gte: {
+          asc: {
+            start: (tx, v) => tx.insertableNodeByPrimary(v[0]),
+            end: () => null,
+            direction: 1,
+            earlyTerminate: false
+          },
+          desc: {
+            start: (tx) => tx.rightestNode(),
+            end: (tx, v) => tx.insertableEndNode(v[0], -1),
+            direction: -1,
+            earlyTerminate: true
+          }
+        },
+        lt: {
+          asc: {
+            start: (tx) => tx.leftestNode(),
+            end: (tx, v) => tx.insertableEndNode(v[0], 1),
+            direction: 1,
+            earlyTerminate: true
+          },
+          desc: {
+            start: (tx, v) => tx.insertableNodeByPrimary(v[0]),
+            end: () => null,
+            direction: -1,
+            earlyTerminate: false
+          }
+        },
+        lte: {
+          asc: {
+            start: (tx) => tx.leftestNode(),
+            end: (tx, v) => tx.insertableEndNode(v[0], 1),
+            direction: 1,
+            earlyTerminate: true
+          },
+          desc: {
+            start: (tx, v) => tx.insertableRightestNodeByPrimary(v[0]),
+            end: () => null,
+            direction: -1,
+            earlyTerminate: false
+          }
+        },
+        equal: {
+          asc: {
+            start: (tx, v) => tx.insertableNodeByPrimary(v[0]),
+            end: (tx, v) => tx.insertableEndNode(v[0], 1),
+            direction: 1,
+            earlyTerminate: true
+          },
+          desc: {
+            start: (tx, v) => tx.insertableEndNode(v[0], 1),
+            end: (tx, v) => tx.insertableEndNode(v[0], -1),
+            direction: -1,
+            earlyTerminate: true
+          }
+        },
+        notEqual: {
+          asc: {
+            start: (tx) => tx.leftestNode(),
+            end: () => null,
+            direction: 1,
+            earlyTerminate: false
+          },
+          desc: {
+            start: (tx) => tx.rightestNode(),
+            end: () => null,
+            direction: -1,
+            earlyTerminate: false
+          }
+        },
+        or: {
+          asc: {
+            start: (tx, v) => tx.insertableNodeByPrimary(tx.lowestValue(v)),
+            end: (tx, v) => tx.insertableEndNode(tx.highestValue(v), 1),
+            direction: 1,
+            earlyTerminate: false
+          },
+          desc: {
+            start: (tx, v) => tx.insertableEndNode(tx.highestValue(v), 1),
+            end: (tx, v) => tx.insertableEndNode(tx.lowestValue(v), -1),
+            direction: -1,
+            earlyTerminate: false
+          }
+        },
+        primaryGt: {
+          asc: {
+            start: (tx, v) => tx.insertableRightestEndNodeByPrimary(v[0]),
+            end: () => null,
+            direction: 1,
+            earlyTerminate: false
+          },
+          desc: {
+            start: (tx) => tx.rightestNode(),
+            end: (tx, v) => tx.insertableEndNode(v[0], -1),
+            direction: -1,
+            earlyTerminate: true
+          }
+        },
+        primaryGte: {
+          asc: {
+            start: (tx, v) => tx.insertableNodeByPrimary(v[0]),
+            end: () => null,
+            direction: 1,
+            earlyTerminate: false
+          },
+          desc: {
+            start: (tx) => tx.rightestNode(),
+            end: (tx, v) => tx.insertableEndNode(v[0], -1),
+            direction: -1,
+            earlyTerminate: true
+          }
+        },
+        primaryLt: {
+          asc: {
+            start: (tx) => tx.leftestNode(),
+            end: (tx, v) => tx.insertableEndNode(v[0], 1),
+            direction: 1,
+            earlyTerminate: true
+          },
+          desc: {
+            start: (tx, v) => tx.insertableNodeByPrimary(v[0]),
+            end: () => null,
+            direction: -1,
+            earlyTerminate: false
+          }
+        },
+        primaryLte: {
+          asc: {
+            start: (tx) => tx.leftestNode(),
+            end: (tx, v) => tx.insertableEndNode(v[0], 1),
+            direction: 1,
+            earlyTerminate: true
+          },
+          desc: {
+            start: (tx, v) => tx.insertableRightestNodeByPrimary(v[0]),
+            end: () => null,
+            direction: -1,
+            earlyTerminate: false
+          }
+        },
+        primaryEqual: {
+          asc: {
+            start: (tx, v) => tx.insertableNodeByPrimary(v[0]),
+            end: (tx, v) => tx.insertableRightestEndNodeByPrimary(v[0]),
+            direction: 1,
+            earlyTerminate: true
+          },
+          desc: {
+            start: (tx, v) => tx.insertableRightestEndNodeByPrimary(v[0]),
+            end: (tx, v) => tx.insertableEndNode(v[0], -1),
+            direction: -1,
+            earlyTerminate: true
+          }
+        },
+        primaryNotEqual: {
+          asc: {
+            start: (tx) => tx.leftestNode(),
+            end: () => null,
+            direction: 1,
+            earlyTerminate: false
+          },
+          desc: {
+            start: (tx) => tx.rightestNode(),
+            end: () => null,
+            direction: -1,
+            earlyTerminate: false
+          }
+        },
+        primaryOr: {
+          asc: {
+            start: (tx, v) => tx.insertableNodeByPrimary(tx.lowestPrimaryValue(v)),
+            end: (tx, v) => tx.insertableRightestEndNodeByPrimary(tx.highestPrimaryValue(v)),
+            direction: 1,
+            earlyTerminate: false
+          },
+          desc: {
+            start: (tx, v) => tx.insertableRightestEndNodeByPrimary(tx.highestPrimaryValue(v)),
+            end: (tx, v) => tx.insertableEndNode(tx.lowestPrimaryValue(v), -1),
+            direction: -1,
+            earlyTerminate: false
+          }
+        },
+        like: {
+          asc: {
+            start: (tx) => tx.leftestNode(),
+            end: () => null,
+            direction: 1,
+            earlyTerminate: false
+          },
+          desc: {
+            start: (tx) => tx.rightestNode(),
+            end: () => null,
+            direction: -1,
+            earlyTerminate: false
+          }
+        }
       };
       /**
        * Priority map for condition types.
@@ -2086,7 +2220,7 @@ var require_cjs = __commonJS({
         return this.getNode(node.next);
       }
       insertableEndNode(value, direction) {
-        const insertableNode = this.insertableNode(value);
+        const insertableNode = direction === -1 ? this.insertableNodeByPrimary(value) : this.insertableRightestNodeByPrimary(value);
         let key;
         switch (direction) {
           case -1:
@@ -2267,16 +2401,20 @@ var require_cjs = __commonJS({
         const driverKey = this.getDriverKey(condition);
         if (!driverKey) return;
         const value = condition[driverKey];
-        let startNode = this.verifierStartNode[driverKey](value);
-        let endNode = this.verifierEndNode[driverKey](value);
-        let direction = this.verifierDirection[driverKey];
+        const v = this.ensureValues(value);
+        const config = this.searchConfigs[driverKey][order];
+        let startNode = config.start(this, v);
+        let endNode = config.end(this, v);
+        const direction = config.direction;
+        const earlyTerminate = config.earlyTerminate;
+        if (order === "desc" && !startNode) {
+          startNode = this.rightestNode();
+        }
+        if (order === "asc" && !startNode) {
+          startNode = this.leftestNode();
+        }
+        if (!startNode) return;
         const comparator = this.verifierMap[driverKey];
-        const earlyTerminate = this.verifierEarlyTerminate[driverKey];
-        if (order === "desc") {
-          startNode = endNode ?? this.rightestNode();
-          endNode = null;
-          direction *= -1;
-        }
         const generator = this.getPairsGenerator(
           value,
           startNode,
@@ -2288,7 +2426,7 @@ var require_cjs = __commonJS({
         let count = 0;
         const intersection = filterValues && filterValues.size > 0 ? filterValues : null;
         for (const pair of generator) {
-          const [k, v] = pair;
+          const [k, v2] = pair;
           if (intersection && !intersection.has(k)) {
             continue;
           }
@@ -2297,7 +2435,7 @@ var require_cjs = __commonJS({
             if (key === driverKey) continue;
             const verify = this.verifierMap[key];
             const condValue = condition[key];
-            if (!verify(v, condValue)) {
+            if (!verify(v2, condValue)) {
               isMatch = false;
               break;
             }
@@ -2752,7 +2890,7 @@ var require_cjs = __commonJS({
         }
       }
     };
-    var Ryoiki22 = class _Ryoiki2 {
+    var Ryoiki2 = class _Ryoiki2 {
       readings;
       writings;
       readQueue;
@@ -3019,7 +3157,7 @@ var require_cjs = __commonJS({
           comparator,
           option
         );
-        this.lock = new Ryoiki22();
+        this.lock = new Ryoiki2();
       }
       async writeLock(id, fn) {
         let lockId;
@@ -3210,7 +3348,7 @@ var require_cjs = __commonJS({
         return await this.getNode(node.next);
       }
       async insertableEndNode(value, direction) {
-        const insertableNode = await this.insertableNode(value);
+        const insertableNode = direction === -1 ? await this.insertableNodeByPrimary(value) : await this.insertableRightestNodeByPrimary(value);
         let key;
         switch (direction) {
           case -1:
@@ -3397,16 +3535,20 @@ var require_cjs = __commonJS({
         const driverKey = this.getDriverKey(condition);
         if (!driverKey) return;
         const value = condition[driverKey];
-        let startNode = await this.verifierStartNode[driverKey](value);
-        let endNode = await this.verifierEndNode[driverKey](value);
-        let direction = this.verifierDirection[driverKey];
+        const v = this.ensureValues(value);
+        const config = this.searchConfigs[driverKey][order];
+        let startNode = await config.start(this, v);
+        let endNode = await config.end(this, v);
+        const direction = config.direction;
+        const earlyTerminate = config.earlyTerminate;
+        if (order === "desc" && !startNode) {
+          startNode = await this.rightestNode();
+        }
+        if (order === "asc" && !startNode) {
+          startNode = await this.leftestNode();
+        }
+        if (!startNode) return;
         const comparator = this.verifierMap[driverKey];
-        const earlyTerminate = this.verifierEarlyTerminate[driverKey];
-        if (order === "desc") {
-          startNode = endNode ?? await this.rightestNode();
-          endNode = null;
-          direction *= -1;
-        }
         const generator = this.getPairsGenerator(
           value,
           startNode,
@@ -3418,7 +3560,7 @@ var require_cjs = __commonJS({
         let count = 0;
         const intersection = filterValues && filterValues.size > 0 ? filterValues : null;
         for await (const pair of generator) {
-          const [k, v] = pair;
+          const [k, v2] = pair;
           if (intersection && !intersection.has(k)) {
             continue;
           }
@@ -3427,7 +3569,7 @@ var require_cjs = __commonJS({
             if (key === driverKey) continue;
             const verify = this.verifierMap[key];
             const condValue = condition[key];
-            if (!verify(v, condValue)) {
+            if (!verify(v2, condValue)) {
               isMatch = false;
               break;
             }
@@ -3957,7 +4099,7 @@ var require_cjs = __commonJS({
       }
     };
     var SerializeStrategyAsync2 = class extends SerializeStrategy {
-      lock = new Ryoiki22();
+      lock = new Ryoiki2();
       async acquireLock(action) {
         let lockId;
         return this.lock.writeLock((_lockId) => {
@@ -8038,9 +8180,6 @@ var require_cjs = __commonJS({
        */
       async write(pageId, data) {
         const pageStartPos = pageId * this.pageSize;
-        if (pageStartPos + this.pageSize > 512 * 1024 * 1024) {
-          throw new Error(`[Safety Limit] File write exceeds 512MB limit at position ${pageStartPos}`);
-        }
         const dataCopy = new Uint8Array(this.pageSize);
         dataCopy.set(data);
         this.dirtyPages.set(pageId, dataCopy);
@@ -8067,6 +8206,22 @@ var require_cjs = __commonJS({
           this.dirtyPages.delete(pageId);
         }
       }
+      /**
+       * 지정된 페이지들만 디스크에 기록합니다.
+       * WAL 없이 트랜잭션 커밋 시, 해당 트랜잭션의 dirty pages만 선택적으로 flush합니다.
+       * @param pages 기록할 페이지 맵 (PageID -> PageData)
+       */
+      async flushPages(pages) {
+        if (pages.size === 0) {
+          return;
+        }
+        const sortedPageIds = Array.from(pages.keys()).sort((a, b) => a - b);
+        for (const pageId of sortedPageIds) {
+          const data = pages.get(pageId);
+          const position = pageId * this.pageSize;
+          await this._writeToDisk(data, position);
+        }
+      }
       /**
        * 메인 DB 파일의 물리적 동기화를 수행합니다 (fsync).
        */
@@ -8342,7 +8497,7 @@ var require_cjs = __commonJS({
       /**
        * Appends and inserts a new page.
        * If a free page is available in the free list, it reuses it.
-       * Otherwise, it appends a new page to the end of the file.
+       * Otherwise, it preallocates `pagePreallocationCount` pages to support sequential reads.
        * @returns Created or reused page ID
        */
       async appendNewPage(pageType = PageManager.CONSTANT.PAGE_TYPE_EMPTY, tx) {
@@ -8357,20 +8512,32 @@ var require_cjs = __commonJS({
           const nextFreePageId = reusedPageManager.getNextPageId(reusedPage);
           metadataManager.setFreePageId(metadata, nextFreePageId);
           await this.setPage(0, metadata, tx);
-          await this.updateBitmap(reusedPageId, false, tx);
           const manager2 = this.pageFactory.getManagerFromType(pageType);
           const newPage2 = manager2.create(this.pageSize, reusedPageId);
           await this.setPage(reusedPageId, newPage2, tx);
           return reusedPageId;
         }
+        const preallocationCount = this.options.pagePreallocationCount;
         const pageCount = metadataManager.getPageCount(metadata);
         const newPageIndex = pageCount;
-        const newTotalCount = pageCount + 1;
+        const newTotalCount = pageCount + preallocationCount;
         const manager = this.pageFactory.getManagerFromType(pageType);
         const newPage = manager.create(this.pageSize, newPageIndex);
         await this.setPage(newPageIndex, newPage, tx);
+        const emptyManager = this.pageFactory.getManagerFromType(PageManager.CONSTANT.PAGE_TYPE_EMPTY);
+        const firstFreeIndex = newPageIndex + 1;
+        const lastFreeIndex = newPageIndex + preallocationCount - 1;
         metadataManager.setPageCount(metadata, newTotalCount);
+        if (preallocationCount > 1) {
+          metadataManager.setFreePageId(metadata, firstFreeIndex);
+        }
         await this.setPage(0, metadata, tx);
+        for (let i = firstFreeIndex; i <= lastFreeIndex; i++) {
+          const emptyPage = emptyManager.create(this.pageSize, i);
+          const nextId = i < lastFreeIndex ? i + 1 : -1;
+          emptyManager.setNextPageId(emptyPage, nextId);
+          await this.setPage(i, emptyPage, tx);
+        }
         return newPageIndex;
       }
       /**
@@ -8467,7 +8634,6 @@ var require_cjs = __commonJS({
         const emptyPage = emptyPageManager.create(this.pageSize, pageId);
         emptyPageManager.setNextPageId(emptyPage, currentHeadFreePageId);
         await this.setPage(pageId, emptyPage, tx);
-        await this.updateBitmap(pageId, true, tx);
         metadataManager.setFreePageId(metadata, pageId);
         await this.setPage(0, metadata, tx);
       }
@@ -9168,7 +9334,9 @@ var require_cjs = __commonJS({
           }
           pageGroupMap.get(pageId).push({ pk: pair.pk, slotIndex, index: pair.index });
         }
-        await Promise.all(Array.from(pageGroupMap).map(async ([pageId, items]) => {
+        const sortedPageIds = Array.from(pageGroupMap.keys()).sort((a, b) => a - b);
+        await Promise.all(sortedPageIds.map(async (pageId) => {
+          const items = pageGroupMap.get(pageId);
           const page = await this.pfs.get(pageId, tx);
           if (!this.factory.isDataPage(page)) {
             throw new Error(`Page ${pageId} is not a data page`);
@@ -9302,6 +9470,8 @@ var require_cjs = __commonJS({
       commitHooks = [];
       /** Page MVCC Strategy for disk access */
       pageStrategy;
+      /** Release function for global write lock, set by DataplyAPI */
+      _writeLockRelease = null;
       /**
        * Sets the BPTree transaction.
        * @param tx BPTree transaction
@@ -9336,6 +9506,19 @@ var require_cjs = __commonJS({
       onCommit(hook) {
         this.commitHooks.push(hook);
       }
+      /**
+       * Sets the global write lock release function.
+       * Called by DataplyAPI.runWithDefaultWrite when acquiring the lock.
+       */
+      __setWriteLockRelease(release) {
+        this._writeLockRelease = release;
+      }
+      /**
+       * Returns whether this transaction already has a write lock.
+       */
+      __hasWriteLockRelease() {
+        return this._writeLockRelease !== null;
+      }
       /**
        * Reads a page. Uses dirty buffer if available, otherwise disk.
        * @param pageId Page ID
@@ -9381,44 +9564,60 @@ var require_cjs = __commonJS({
        * Commits the transaction.
        */
       async commit() {
-        await this.context.run(this, async () => {
-          for (const hook of this.commitHooks) {
-            await hook();
-          }
-        });
-        let shouldTriggerCheckpoint = false;
-        await this.pfs.runGlobalLock(async () => {
-          if (this.pfs.wal && this.dirtyPages.size > 0) {
-            await this.pfs.wal.prepareCommit(this.dirtyPages);
-            await this.pfs.wal.writeCommitMarker();
-          }
-          for (const [pageId, data] of this.dirtyPages) {
-            await this.pageStrategy.write(pageId, data);
-          }
-          if (this.pfs.wal) {
-            this.pfs.wal.incrementWrittenPages(this.dirtyPages.size);
-            if (this.pfs.wal.shouldCheckpoint(this.pfs.options.walCheckpointThreshold)) {
-              shouldTriggerCheckpoint = true;
+        try {
+          await this.context.run(this, async () => {
+            for (const hook of this.commitHooks) {
+              await hook();
+            }
+          });
+          let shouldTriggerCheckpoint = false;
+          await this.pfs.runGlobalLock(async () => {
+            if (this.pfs.wal && this.dirtyPages.size > 0) {
+              await this.pfs.wal.prepareCommit(this.dirtyPages);
+              await this.pfs.wal.writeCommitMarker();
+            }
+            for (const [pageId, data] of this.dirtyPages) {
+              await this.pageStrategy.write(pageId, data);
+            }
+            if (!this.pfs.wal) {
+              await this.pfs.strategy.flushPages(this.dirtyPages);
+            } else {
+              this.pfs.wal.incrementWrittenPages(this.dirtyPages.size);
+              if (this.pfs.wal.shouldCheckpoint(this.pfs.options.walCheckpointThreshold)) {
+                shouldTriggerCheckpoint = true;
+              }
             }
+          });
+          if (shouldTriggerCheckpoint) {
+            await this.pfs.checkpoint();
+          }
+          this.dirtyPages.clear();
+          this.undoPages.clear();
+          this.releaseAllLocks();
+        } finally {
+          if (this._writeLockRelease) {
+            this._writeLockRelease();
+            this._writeLockRelease = null;
           }
-        });
-        if (shouldTriggerCheckpoint) {
-          await this.pfs.checkpoint();
         }
-        this.dirtyPages.clear();
-        this.undoPages.clear();
-        this.releaseAllLocks();
       }
       /**
        * Rolls back the transaction.
        */
       async rollback() {
-        if (this.bptreeTx) {
-          this.bptreeTx.rollback();
+        try {
+          if (this.bptreeTx) {
+            this.bptreeTx.rollback();
+          }
+          this.dirtyPages.clear();
+          this.undoPages.clear();
+          this.releaseAllLocks();
+        } finally {
+          if (this._writeLockRelease) {
+            this._writeLockRelease();
+            this._writeLockRelease = null;
+          }
         }
-        this.dirtyPages.clear();
-        this.undoPages.clear();
-        this.releaseAllLocks();
       }
       /**
        * Returns the dirty pages map.
@@ -9495,6 +9694,8 @@ var require_cjs = __commonJS({
       /** Whether the database was created this time. */
       isNewlyCreated;
       txIdCounter;
+      /** Promise-chain mutex for serializing write operations */
+      writeQueue = Promise.resolve();
       /**
        * Verifies if the page file is a valid Dataply file.
        * The metadata page must be located at the beginning of the Dataply file.
@@ -9519,6 +9720,7 @@ var require_cjs = __commonJS({
         return Object.assign({
           pageSize: 8192,
           pageCacheCapacity: 1e4,
+          pagePreallocationCount: 1e3,
           wal: null,
           walCheckpointThreshold: 1e3
         }, options);
@@ -9651,6 +9853,52 @@ var require_cjs = __commonJS({
        * @param tx The transaction to use. If not provided, a new transaction is created.
        * @returns The result of the callback function.
        */
+      /**
+       * Acquires the global write lock.
+       * Returns a release function that MUST be called to unlock.
+       * Used internally by runWithDefaultWrite.
+       * @returns A release function
+       */
+      acquireWriteLock() {
+        const previous = this.writeQueue;
+        let release;
+        this.writeQueue = new Promise((resolve) => {
+          release = resolve;
+        });
+        return previous.then(() => release);
+      }
+      /**
+       * Runs a write callback within a transaction context with global write serialization.
+       * If no transaction is provided, a new transaction is created, committed on success, rolled back on error.
+       * If a transaction is provided (external), the write lock is acquired on first call and held until commit/rollback.
+       * Subclasses MUST use this method for all write operations instead of runWithDefault.
+       * @param callback The callback function to run.
+       * @param tx Optional external transaction.
+       * @returns The result of the callback.
+       */
+      async runWithDefaultWrite(callback, tx) {
+        if (!tx) {
+          const release = await this.acquireWriteLock();
+          const internalTx = this.createTransaction();
+          internalTx.__setWriteLockRelease(release);
+          const [error2, result2] = await catchPromise2(this.txContext.run(internalTx, () => callback(internalTx)));
+          if (error2) {
+            await internalTx.rollback();
+            throw error2;
+          }
+          await internalTx.commit();
+          return result2;
+        }
+        if (!tx.__hasWriteLockRelease()) {
+          const release = await this.acquireWriteLock();
+          tx.__setWriteLockRelease(release);
+        }
+        const [error, result] = await catchPromise2(this.txContext.run(tx, () => callback(tx)));
+        if (error) {
+          throw error;
+        }
+        return result;
+      }
       async runWithDefault(callback, tx) {
         const isInternalTx = !tx;
         if (!tx) {
@@ -9722,7 +9970,7 @@ var require_cjs = __commonJS({
         if (!this.initialized) {
           throw new Error("Dataply instance is not initialized");
         }
-        return this.runWithDefault(async (tx2) => {
+        return this.runWithDefaultWrite(async (tx2) => {
           incrementRowCount = incrementRowCount ?? true;
           if (typeof data === "string") {
             data = this.textCodec.encode(data);
@@ -9742,7 +9990,7 @@ var require_cjs = __commonJS({
         if (!this.initialized) {
           throw new Error("Dataply instance is not initialized");
         }
-        return this.runWithDefault(async (tx2) => {
+        return this.runWithDefaultWrite(async (tx2) => {
           incrementRowCount = incrementRowCount ?? true;
           if (typeof data === "string") {
             data = this.textCodec.encode(data);
@@ -9763,7 +10011,7 @@ var require_cjs = __commonJS({
         if (!this.initialized) {
           throw new Error("Dataply instance is not initialized");
         }
-        return this.runWithDefault(async (tx2) => {
+        return this.runWithDefaultWrite(async (tx2) => {
           incrementRowCount = incrementRowCount ?? true;
           const encodedList = dataList.map(
             (data) => typeof data === "string" ? this.textCodec.encode(data) : data
@@ -9781,7 +10029,7 @@ var require_cjs = __commonJS({
         if (!this.initialized) {
           throw new Error("Dataply instance is not initialized");
         }
-        return this.runWithDefault(async (tx2) => {
+        return this.runWithDefaultWrite(async (tx2) => {
           if (typeof data === "string") {
             data = this.textCodec.encode(data);
           }
@@ -9798,7 +10046,7 @@ var require_cjs = __commonJS({
         if (!this.initialized) {
           throw new Error("Dataply instance is not initialized");
         }
-        return this.runWithDefault(async (tx2) => {
+        return this.runWithDefaultWrite(async (tx2) => {
           decrementRowCount = decrementRowCount ?? true;
           await this.rowTableEngine.delete(pk, decrementRowCount, tx2);
         }, tx);
@@ -9990,6 +10238,11 @@ var DocumentSerializeStrategyAsync = class extends import_dataply.SerializeStrat
     this.txContext = txContext;
     this.treeKey = treeKey;
   }
+  /**
+   * readHead에서 할당된 headPk를 캐싱하여
+   * writeHead에서 AsyncLocalStorage 컨텍스트 유실 시에도 사용할 수 있도록 함
+   */
+  cachedHeadPk = null;
   async id(isLeaf) {
     const tx = this.txContext.get();
     const pk = await this.api.insertAsOverflow("__BPTREE_NODE_PLACEHOLDER__", false, tx);
@@ -10022,20 +10275,25 @@ var DocumentSerializeStrategyAsync = class extends import_dataply.SerializeStrat
       const pk = await this.api.insertAsOverflow("__BPTREE_HEAD_PLACEHOLDER__", false, tx);
       metadata.indices[this.treeKey][0] = pk;
       await this.api.updateDocumentInnerMetadata(metadata, tx);
+      this.cachedHeadPk = pk;
       return null;
     }
+    this.cachedHeadPk = headPk;
     const row = await this.api.select(headPk, false, tx);
     if (row === null || row === "" || row.startsWith("__BPTREE_")) return null;
     return JSON.parse(row);
   }
   async writeHead(head) {
     const tx = this.txContext.get();
-    const metadata = await this.api.getDocumentInnerMetadata(tx);
-    const indexInfo = metadata.indices[this.treeKey];
-    if (!indexInfo) {
-      throw new Error(`Index info not found for tree: ${this.treeKey}. Initialization should be handled outside.`);
+    let headPk = this.cachedHeadPk;
+    if (headPk === null) {
+      const metadata = await this.api.getDocumentInnerMetadata(tx);
+      const indexInfo = metadata.indices[this.treeKey];
+      if (!indexInfo) {
+        throw new Error(`Index info not found for tree: ${this.treeKey}. Initialization should be handled outside.`);
+      }
+      headPk = indexInfo[0];
     }
-    const headPk = indexInfo[0];
     const json = JSON.stringify(head);
     await this.api.update(headPk, json, tx);
   }
@@ -10071,9 +10329,24 @@ function compareValue(a, b) {
   }
   return aList.length - bList.length;
 }
+function comparePrimaryValue(a, b) {
+  const aArr = Array.isArray(a);
+  const bArr = Array.isArray(b);
+  if (!aArr && !bArr) {
+    return comparePrimitive(a, b);
+  }
+  const aList = aArr ? a : [a];
+  const bList = bArr ? b : [b];
+  const len = Math.min(aList.length, bList.length);
+  for (let i = 0; i < len; i++) {
+    const diff = comparePrimitive(aList[i], bList[i]);
+    if (diff !== 0) return diff;
+  }
+  return 0;
+}
 var DocumentValueComparator = class extends import_dataply2.ValueComparator {
   primaryAsc(a, b) {
-    return compareValue(a.v, b.v);
+    return comparePrimaryValue(a.v, b.v);
   }
   asc(a, b) {
     const diff = compareValue(a.v, b.v);
@@ -10194,7 +10467,6 @@ var DocumentDataplyAPI = class extends import_dataply3.DataplyAPI {
   trees = /* @__PURE__ */ new Map();
   comparator = new DocumentValueComparator();
   pendingBackfillFields = [];
-  lock;
   _initialized = false;
   indexedFields;
   /**
@@ -10225,7 +10497,6 @@ var DocumentDataplyAPI = class extends import_dataply3.DataplyAPI {
   constructor(file, options) {
     super(file, options);
     this.trees = /* @__PURE__ */ new Map();
-    this.lock = new import_dataply3.Ryoiki();
     this.indexedFields = /* @__PURE__ */ new Set(["_id"]);
     this.hook.onceAfter("init", async (tx, isNewlyCreated) => {
       if (isNewlyCreated) {
@@ -10235,8 +10506,12 @@ var DocumentDataplyAPI = class extends import_dataply3.DataplyAPI {
         throw new Error("Document metadata verification failed");
       }
       const metadata = await this.getDocumentInnerMetadata(tx);
-      const targetIndices = /* @__PURE__ */ new Map();
-      targetIndices.set("_id", { type: "btree", fields: ["_id"] });
+      const targetIndices = /* @__PURE__ */ new Map([
+        ["_id", { type: "btree", fields: ["_id"] }]
+      ]);
+      for (const [name, info] of Object.entries(metadata.indices)) {
+        targetIndices.set(name, info[1]);
+      }
       for (const [name, option] of this.pendingCreateIndices) {
         const config = this.toIndexMetaConfig(option);
         targetIndices.set(name, config);
@@ -10326,7 +10601,7 @@ var DocumentDataplyAPI = class extends import_dataply3.DataplyAPI {
       const existing = this.registeredIndices.get(name);
       if (JSON.stringify(existing) === JSON.stringify(config)) return;
     }
-    await this.runWithDefault(async (tx2) => {
+    await this.runWithDefaultWrite(async (tx2) => {
       const metadata = await this.getDocumentInnerMetadata(tx2);
       metadata.indices[name] = [-1, config];
       await this.updateDocumentInnerMetadata(metadata, tx2);
@@ -10374,7 +10649,7 @@ var DocumentDataplyAPI = class extends import_dataply3.DataplyAPI {
     if (!this.registeredIndices.has(name)) {
       throw new Error(`Index '${name}' does not exist`);
     }
-    await this.runWithDefault(async (tx2) => {
+    await this.runWithDefaultWrite(async (tx2) => {
       const config = this.registeredIndices.get(name);
       const metadata = await this.getDocumentInnerMetadata(tx2);
       delete metadata.indices[name];
@@ -10403,19 +10678,39 @@ var DocumentDataplyAPI = class extends import_dataply3.DataplyAPI {
    * Convert CreateIndexOption to IndexMetaConfig for metadata storage.
    */
   toIndexMetaConfig(option) {
+    if (!option || typeof option !== "object") {
+      throw new Error("Index option must be a non-null object");
+    }
+    if (!option.type) {
+      throw new Error('Index option must have a "type" property ("btree" or "fts")');
+    }
     if (option.type === "btree") {
+      if (!Array.isArray(option.fields) || option.fields.length === 0) {
+        throw new Error('btree index requires a non-empty "fields" array');
+      }
+      for (let i = 0; i < option.fields.length; i++) {
+        if (typeof option.fields[i] !== "string" || option.fields[i].length === 0) {
+          throw new Error(`btree index "fields[${i}]" must be a non-empty string, got: ${JSON.stringify(option.fields[i])}`);
+        }
+      }
       return {
         type: "btree",
         fields: option.fields
       };
     }
     if (option.type === "fts") {
+      if (typeof option.fields !== "string" || option.fields.length === 0) {
+        throw new Error(`fts index requires a non-empty string "fields", got: ${JSON.stringify(option.fields)}`);
+      }
       if (option.tokenizer === "ngram") {
+        if (typeof option.gramSize !== "number" || option.gramSize < 1) {
+          throw new Error(`fts ngram index requires a positive "gramSize" number, got: ${JSON.stringify(option.gramSize)}`);
+        }
         return {
           type: "fts",
           fields: option.fields,
           tokenizer: "ngram",
-          gramSize: option.ngram
+          gramSize: option.gramSize
         };
       }
       return {
@@ -10489,24 +10784,6 @@ var DocumentDataplyAPI = class extends import_dataply3.DataplyAPI {
       return JSON.parse(row);
     }, tx);
   }
-  async readLock(fn) {
-    let lockId;
-    return this.lock.readLock(async (_lockId) => {
-      lockId = _lockId;
-      return await fn();
-    }).finally(() => {
-      this.lock.readUnlock(lockId);
-    });
-  }
-  async writeLock(fn) {
-    let lockId;
-    return this.lock.writeLock(async (_lockId) => {
-      lockId = _lockId;
-      return await fn();
-    }).finally(() => {
-      this.lock.writeUnlock(lockId);
-    });
-  }
   /**
    * Backfill indices for newly created indices after data was inserted.
    * This method should be called after `init()`.
@@ -10514,7 +10791,7 @@ var DocumentDataplyAPI = class extends import_dataply3.DataplyAPI {
    * @returns Number of documents that were backfilled
    */
   async backfillIndices(tx) {
-    return this.runWithDefault(async (tx2) => {
+    return this.runWithDefaultWrite(async (tx2) => {
       if (this.pendingBackfillFields.length === 0) {
         return 0;
       }
@@ -10523,8 +10800,7 @@ var DocumentDataplyAPI = class extends import_dataply3.DataplyAPI {
       if (metadata.lastId === 0) {
         return 0;
       }
-      const indexTxMap = {};
-      const indexEntryMap = /* @__PURE__ */ new Map();
+      let indexTxMap = {};
       for (const indexName of backfillTargets) {
         const tree = this.trees.get(indexName);
         if (tree && indexName !== "_id") {
@@ -10532,6 +10808,8 @@ var DocumentDataplyAPI = class extends import_dataply3.DataplyAPI {
         }
       }
       let backfilledCount = 0;
+      let chunkCount = 0;
+      const CHUNK_SIZE = 1e3;
       const idTree = this.trees.get("_id");
       if (!idTree) {
         throw new Error("ID tree not found");
@@ -10560,10 +10838,6 @@ var DocumentDataplyAPI = class extends import_dataply3.DataplyAPI {
               const keyToInsert = this.getTokenKey(k, token);
               const entry = { k, v: token };
               batchInsertData.push([keyToInsert, entry]);
-              if (!indexEntryMap.has(btx)) {
-                indexEntryMap.set(btx, []);
-              }
-              indexEntryMap.get(btx).push({ k: keyToInsert, v: entry });
             }
             await btx.batchInsert(batchInsertData);
           } else {
@@ -10571,34 +10845,42 @@ var DocumentDataplyAPI = class extends import_dataply3.DataplyAPI {
             if (indexVal === void 0) continue;
             const entry = { k, v: indexVal };
             const batchInsertData = [[k, entry]];
-            if (!indexEntryMap.has(btx)) {
-              indexEntryMap.set(btx, []);
-            }
-            indexEntryMap.get(btx).push(entry);
             await btx.batchInsert(batchInsertData);
           }
         }
         backfilledCount++;
-      }
-      const btxs = Object.values(indexTxMap);
-      const success = [];
-      try {
-        for (const btx of btxs) {
-          await btx.commit();
-          success.push(btx);
-        }
-      } catch (err) {
-        for (const btx of btxs) {
-          await btx.rollback();
+        chunkCount++;
+        if (chunkCount >= CHUNK_SIZE) {
+          try {
+            for (const btx of Object.values(indexTxMap)) {
+              await btx.commit();
+            }
+          } catch (err) {
+            for (const btx of Object.values(indexTxMap)) {
+              await btx.rollback();
+            }
+            throw err;
+          }
+          for (const indexName of backfillTargets) {
+            const tree = this.trees.get(indexName);
+            if (tree && indexName !== "_id") {
+              indexTxMap[indexName] = await tree.createTransaction();
+            }
+          }
+          chunkCount = 0;
         }
-        for (const btx of success) {
-          const entries = indexEntryMap.get(btx);
-          if (!entries) continue;
-          for (const entry of entries) {
-            await btx.delete(entry.k, entry);
+      }
+      if (chunkCount > 0) {
+        try {
+          for (const btx of Object.values(indexTxMap)) {
+            await btx.commit();
+          }
+        } catch (err) {
+          for (const btx of Object.values(indexTxMap)) {
+            await btx.rollback();
           }
+          throw err;
         }
-        throw err;
       }
       this.pendingBackfillFields = [];
       return backfilledCount;
@@ -10687,14 +10969,15 @@ var DocumentDataplyAPI = class extends import_dataply3.DataplyAPI {
    * @param tx Optional transaction
    */
   async migration(version, callback, tx) {
-    await this.runWithDefault(async (tx2) => {
+    await this.runWithDefaultWrite(async (tx2) => {
       const innerMetadata = await this.getDocumentInnerMetadata(tx2);
       const currentVersion = innerMetadata.schemeVersion ?? 0;
       if (currentVersion < version) {
         await callback(tx2);
-        innerMetadata.schemeVersion = version;
-        innerMetadata.updatedAt = Date.now();
-        await this.updateDocumentInnerMetadata(innerMetadata, tx2);
+        const freshMetadata = await this.getDocumentInnerMetadata(tx2);
+        freshMetadata.schemeVersion = version;
+        freshMetadata.updatedAt = Date.now();
+        await this.updateDocumentInnerMetadata(freshMetadata, tx2);
       }
     }, tx);
   }
@@ -10755,27 +11038,61 @@ var DocumentDataplyAPI = class extends import_dataply3.DataplyAPI {
         const condition = query[primaryField];
         const treeTx = await tree.createTransaction();
         let score = 0;
-        const coveredFields = config.fields.filter((f) => queryFields.has(f));
-        score += coveredFields.length;
-        if (condition) {
-          if (typeof condition !== "object" || condition === null) {
-            score += 100;
-          } else if ("primaryEqual" in condition || "equal" in condition) {
-            score += 100;
-          } else if ("primaryGte" in condition || "primaryLte" in condition || "primaryGt" in condition || "primaryLt" in condition || "gte" in condition || "lte" in condition || "gt" in condition || "lt" in condition) {
-            score += 50;
-          } else if ("primaryOr" in condition || "or" in condition) {
-            score += 20;
-          } else if ("like" in condition) {
-            score += 15;
-          } else {
-            score += 10;
+        let isConsecutive = true;
+        const coveredFields = [];
+        const compositeVerifyFields = [];
+        for (const field of config.fields) {
+          if (!queryFields.has(field)) {
+            isConsecutive = false;
+            continue;
+          }
+          coveredFields.push(field);
+          if (field !== primaryField) {
+            compositeVerifyFields.push(field);
+          }
+          score += 1;
+          if (isConsecutive) {
+            const cond = query[field];
+            if (cond !== void 0) {
+              if (typeof cond !== "object" || cond === null) {
+                score += 100;
+              } else if ("primaryEqual" in cond || "equal" in cond) {
+                score += 100;
+              } else if ("primaryGte" in cond || "primaryLte" in cond || "primaryGt" in cond || "primaryLt" in cond || "gte" in cond || "lte" in cond || "gt" in cond || "lt" in cond) {
+                score += 50;
+                isConsecutive = false;
+              } else if ("primaryOr" in cond || "or" in cond) {
+                score += 20;
+                isConsecutive = false;
+              } else if ("like" in cond) {
+                score += 15;
+                isConsecutive = false;
+              } else {
+                score += 10;
+                isConsecutive = false;
+              }
+            }
           }
         }
-        if (orderByField && primaryField === orderByField) {
-          score += 200;
+        let isIndexOrderSupported = false;
+        if (orderByField) {
+          for (const field of config.fields) {
+            if (field === orderByField) {
+              isIndexOrderSupported = true;
+              break;
+            }
+            const cond = query[field];
+            let isExactMatch = false;
+            if (cond !== void 0) {
+              if (typeof cond !== "object" || cond === null) isExactMatch = true;
+              else if ("primaryEqual" in cond || "equal" in cond) isExactMatch = true;
+            }
+            if (!isExactMatch) break;
+          }
+          if (isIndexOrderSupported) {
+            score += 200;
+          }
         }
-        const compositeVerifyFields = coveredFields.filter((f) => f !== primaryField);
         candidates.push({
           tree: treeTx,
           condition,
@@ -10783,7 +11100,8 @@ var DocumentDataplyAPI = class extends import_dataply3.DataplyAPI {
           indexName,
           isFtsMatch: false,
           score,
-          compositeVerifyFields
+          compositeVerifyFields,
+          isIndexOrderSupported
         });
       } else if (config.type === "fts") {
         const field = config.fields;
@@ -10801,7 +11119,8 @@ var DocumentDataplyAPI = class extends import_dataply3.DataplyAPI {
           isFtsMatch: true,
           matchTokens,
           score: 90,
-          compositeVerifyFields: []
+          compositeVerifyFields: [],
+          isIndexOrderSupported: false
         });
       }
     }
@@ -10844,33 +11163,30 @@ var DocumentDataplyAPI = class extends import_dataply3.DataplyAPI {
   getTokenKey(pk, token) {
     return pk + ":" + token;
   }
-  async applyCandidateByFTS(candidate, matchedTokens, filterValues, order) {
+  async *applyCandidateByFTSStream(candidate, matchedTokens, filterValues, order) {
     const keys = /* @__PURE__ */ new Set();
     for (let i = 0, len = matchedTokens.length; i < len; i++) {
       const token = matchedTokens[i];
-      const pairs = await candidate.tree.where(
+      for await (const pair of candidate.tree.whereStream(
         { primaryEqual: { v: token } },
-        {
-          order
+        { order }
+      )) {
+        const pk = pair[1].k;
+        if (filterValues && !filterValues.has(pk)) continue;
+        if (!keys.has(pk)) {
+          keys.add(pk);
+          yield pk;
         }
-      );
-      for (const pair of pairs.values()) {
-        if (filterValues && !filterValues.has(pair.k)) continue;
-        keys.add(pair.k);
       }
     }
-    return keys;
   }
   /**
    * 특정 인덱스 후보를 조회하여 PK 집합을 필터링합니다.
    */
-  async applyCandidate(candidate, filterValues, order) {
-    return await candidate.tree.keys(
+  applyCandidateStream(candidate, filterValues, order) {
+    return candidate.tree.keysStream(
       candidate.condition,
-      {
-        filterValues,
-        order
-      }
+      { filterValues, order }
     );
   }
   /**
@@ -10886,30 +11202,34 @@ var DocumentDataplyAPI = class extends import_dataply3.DataplyAPI {
     );
     if (!selectivity) return new Float64Array(0);
     const { driver, others, rollback } = selectivity;
-    const useIndexOrder = orderBy === void 0 || driver.field === orderBy;
+    const useIndexOrder = orderBy === void 0 || driver.isIndexOrderSupported;
     const candidates = [driver, ...others];
     let keys = void 0;
     for (let i = 0, len = candidates.length; i < len; i++) {
       const candidate = candidates[i];
       const currentOrder = useIndexOrder ? sortOrder : void 0;
       if (candidate.isFtsMatch && candidate.matchTokens && candidate.matchTokens.length > 0) {
-        keys = await this.applyCandidateByFTS(
+        const stream = this.applyCandidateByFTSStream(
           candidate,
           candidate.matchTokens,
           keys,
           currentOrder
         );
+        keys = /* @__PURE__ */ new Set();
+        for await (const pk of stream) keys.add(pk);
       } else {
-        keys = await this.applyCandidate(candidate, keys, currentOrder);
+        const stream = this.applyCandidateStream(candidate, keys, currentOrder);
+        keys = /* @__PURE__ */ new Set();
+        for await (const pk of stream) keys.add(pk);
       }
     }
     rollback();
     return new Float64Array(Array.from(keys || []));
   }
   /**
-   * 드라이버 인덱스만으로 PK를 가져옵니다. (교집합 없이)
+   * 드라이버 인덱스만으로 PK 스트림을 가져옵니다. (교집합 없이)
    * selectDocuments에서 사용하며, 나머지 조건(others)은 스트리밍 중 tree.verify()로 검증합니다.
-   * @returns 드라이버 키 배열, others 후보 목록, rollback 함수. 또는 null.
+   * @returns 드라이버 키 스트림, others 후보 목록, rollback 함수. 또는 null.
    */
   async getDriverKeys(query, orderBy, sortOrder = "asc") {
     const isQueryEmpty = Object.keys(query).length === 0;
@@ -10920,21 +11240,21 @@ var DocumentDataplyAPI = class extends import_dataply3.DataplyAPI {
     );
     if (!selectivity) return null;
     const { driver, others, compositeVerifyConditions, rollback } = selectivity;
-    const useIndexOrder = orderBy === void 0 || driver.field === orderBy;
+    const useIndexOrder = orderBy === void 0 || driver.isIndexOrderSupported;
     const currentOrder = useIndexOrder ? sortOrder : void 0;
-    let keys;
+    let keysStream;
     if (driver.isFtsMatch && driver.matchTokens && driver.matchTokens.length > 0) {
-      keys = await this.applyCandidateByFTS(
+      keysStream = this.applyCandidateByFTSStream(
         driver,
         driver.matchTokens,
         void 0,
         currentOrder
       );
     } else {
-      keys = await this.applyCandidate(driver, void 0, currentOrder);
+      keysStream = this.applyCandidateStream(driver, void 0, currentOrder);
     }
     return {
-      keys: new Float64Array(Array.from(keys)),
+      keysStream,
       others,
       compositeVerifyConditions,
       isDriverOrderByField: useIndexOrder,
@@ -10962,7 +11282,7 @@ var DocumentDataplyAPI = class extends import_dataply3.DataplyAPI {
    * @returns The primary key of the inserted document
    */
   async insertSingleDocument(document, tx) {
-    return this.writeLock(() => this.runWithDefault(async (tx2) => {
+    return this.runWithDefaultWrite(async (tx2) => {
       const { pk: dpk, document: dataplyDocument } = await this.insertDocumentInternal(document, tx2);
       const flattenDocument = this.flattenDocument(dataplyDocument);
       for (const [indexName, config] of this.registeredIndices) {
@@ -10988,7 +11308,7 @@ var DocumentDataplyAPI = class extends import_dataply3.DataplyAPI {
         }
       }
       return dataplyDocument._id;
-    }, tx));
+    }, tx);
   }
   /**
    * Insert a batch of documents into the database
@@ -10997,7 +11317,7 @@ var DocumentDataplyAPI = class extends import_dataply3.DataplyAPI {
    * @returns The primary keys of the inserted documents
    */
   async insertBatchDocuments(documents, tx) {
-    return this.writeLock(() => this.runWithDefault(async (tx2) => {
+    return this.runWithDefaultWrite(async (tx2) => {
       const metadata = await this.getDocumentInnerMetadata(tx2);
       const startId = metadata.lastId + 1;
       metadata.lastId += documents.length;
@@ -11056,7 +11376,7 @@ var DocumentDataplyAPI = class extends import_dataply3.DataplyAPI {
         }
       }
       return ids;
-    }, tx));
+    }, tx);
   }
   /**
    * Internal update method used by both fullUpdate and partialUpdate
@@ -11137,12 +11457,12 @@ var DocumentDataplyAPI = class extends import_dataply3.DataplyAPI {
    * @returns The number of updated documents
    */
   async fullUpdate(query, newRecord, tx) {
-    return await this.writeLock(() => this.runWithDefault(async (tx2) => {
+    return this.runWithDefaultWrite(async (tx2) => {
       return this.updateInternal(query, (doc) => {
         const newDoc = typeof newRecord === "function" ? newRecord(doc) : newRecord;
         return { _id: doc._id, ...newDoc };
       }, tx2);
-    }, tx));
+    }, tx);
   }
   /**
    * Partially update documents from the database that match the query
@@ -11152,14 +11472,14 @@ var DocumentDataplyAPI = class extends import_dataply3.DataplyAPI {
    * @returns The number of updated documents
    */
   async partialUpdate(query, newRecord, tx) {
-    return this.writeLock(() => this.runWithDefault(async (tx2) => {
+    return this.runWithDefaultWrite(async (tx2) => {
       return this.updateInternal(query, (doc) => {
         const partialUpdateContent = typeof newRecord === "function" ? newRecord(doc) : newRecord;
         const finalUpdate = { ...partialUpdateContent };
         delete finalUpdate._id;
         return { ...doc, ...finalUpdate };
       }, tx2);
-    }, tx));
+    }, tx);
   }
   /**
    * Delete documents from the database that match the query
@@ -11168,7 +11488,7 @@ var DocumentDataplyAPI = class extends import_dataply3.DataplyAPI {
    * @returns The number of deleted documents
    */
   async deleteDocuments(query, tx) {
-    return this.writeLock(() => this.runWithDefault(async (tx2) => {
+    return this.runWithDefaultWrite(async (tx2) => {
       const pks = await this.getKeys(query);
       let deletedCount = 0;
       for (let i = 0, len = pks.length; i < len; i++) {
@@ -11198,7 +11518,7 @@ var DocumentDataplyAPI = class extends import_dataply3.DataplyAPI {
         deletedCount++;
       }
       return deletedCount;
-    }, tx));
+    }, tx);
   }
   /**
    * Count documents from the database that match the query
@@ -11207,10 +11527,10 @@ var DocumentDataplyAPI = class extends import_dataply3.DataplyAPI {
    * @returns The number of documents that match the query
    */
   async countDocuments(query, tx) {
-    return this.readLock(() => this.runWithDefault(async (tx2) => {
+    return this.runWithDefault(async (tx2) => {
       const pks = await this.getKeys(query);
       return pks.length;
-    }, tx));
+    }, tx);
   }
   /**
    * FTS 조건에 대해 문서가 유효한지 검증합니다.
@@ -11284,28 +11604,17 @@ var DocumentDataplyAPI = class extends import_dataply3.DataplyAPI {
     return currentChunkSize;
   }
   /**
-   * Prefetch 방식으로 키 배열을 청크 단위로 조회하여 문서를 순회합니다.
+   * Prefetch 방식으로 키 스트림을 청크 단위로 조회하여 문서를 순회합니다.
    * FTS 검증, 복합 인덱스 검증, others 후보에 대한 tree.verify() 검증을 통과한 문서만 yield 합니다.
    */
-  async *processChunkedKeysWithVerify(keys, startIdx, initialChunkSize, ftsConditions, compositeVerifyConditions, others, tx) {
+  async *processChunkedKeysWithVerify(keysStream, startIdx, initialChunkSize, ftsConditions, compositeVerifyConditions, others, tx) {
     const verifyOthers = others.filter((o) => !o.isFtsMatch);
-    let i = startIdx;
-    const totalKeys = keys.length;
     let currentChunkSize = initialChunkSize;
-    let nextChunkPromise = null;
-    if (i < totalKeys) {
-      const endIdx = Math.min(i + currentChunkSize, totalKeys);
-      nextChunkPromise = this.selectMany(keys.subarray(i, endIdx), false, tx);
-      i = endIdx;
-    }
-    while (nextChunkPromise) {
-      const rawResults = await nextChunkPromise;
-      nextChunkPromise = null;
-      if (i < totalKeys) {
-        const endIdx = Math.min(i + currentChunkSize, totalKeys);
-        nextChunkPromise = this.selectMany(keys.subarray(i, endIdx), false, tx);
-        i = endIdx;
-      }
+    let chunk = [];
+    let dropped = 0;
+    const processChunk = async (pks) => {
+      const docs = [];
+      const rawResults = await this.selectMany(new Float64Array(pks), false, tx);
       let chunkTotalSize = 0;
       for (let j = 0, len = rawResults.length; j < len; j++) {
         const s = rawResults[j];
@@ -11332,9 +11641,26 @@ var DocumentDataplyAPI = class extends import_dataply3.DataplyAPI {
           }
           if (!passed) continue;
         }
-        yield doc;
+        docs.push(doc);
       }
       currentChunkSize = this.adjustChunkSize(currentChunkSize, chunkTotalSize);
+      return docs;
+    };
+    for await (const pk of keysStream) {
+      if (dropped < startIdx) {
+        dropped++;
+        continue;
+      }
+      chunk.push(pk);
+      if (chunk.length >= currentChunkSize) {
+        const docs = await processChunk(chunk);
+        for (let j = 0; j < docs.length; j++) yield docs[j];
+        chunk = [];
+      }
+    }
+    if (chunk.length > 0) {
+      const docs = await processChunk(chunk);
+      for (let j = 0; j < docs.length; j++) yield docs[j];
     }
   }
   /**
@@ -11382,11 +11708,7 @@ var DocumentDataplyAPI = class extends import_dataply3.DataplyAPI {
       }
       const driverResult = await self.getDriverKeys(query, orderByField, sortOrder);
       if (!driverResult) return;
-      const { keys, others, compositeVerifyConditions, isDriverOrderByField, rollback } = driverResult;
-      if (keys.length === 0) {
-        rollback();
-        return;
-      }
+      const { keysStream, others, compositeVerifyConditions, isDriverOrderByField, rollback } = driverResult;
       try {
         if (!isDriverOrderByField && orderByField) {
           const topK = limit === Infinity ? Infinity : offset + limit;
@@ -11401,7 +11723,7 @@ var DocumentDataplyAPI = class extends import_dataply3.DataplyAPI {
           }
           const results = [];
           for await (const doc of self.processChunkedKeysWithVerify(
-            keys,
+            keysStream,
             0,
             self.options.pageSize,
             ftsConditions,
@@ -11437,16 +11759,23 @@ var DocumentDataplyAPI = class extends import_dataply3.DataplyAPI {
             yield limitedResults[j];
           }
         } else {
+          const hasFilters = ftsConditions.length > 0 || compositeVerifyConditions.length > 0 || others.length > 0;
+          const startIdx = hasFilters ? 0 : offset;
           let yieldedCount = 0;
+          let skippedCount = hasFilters ? 0 : offset;
           for await (const doc of self.processChunkedKeysWithVerify(
-            keys,
-            offset,
+            keysStream,
+            startIdx,
             self.options.pageSize,
             ftsConditions,
             compositeVerifyConditions,
             others,
             tx2
           )) {
+            if (skippedCount < offset) {
+              skippedCount++;
+              continue;
+            }
             if (yieldedCount >= limit) break;
             yield doc;
             yieldedCount++;