document-dataply 0.0.5-alpha.0 → 0.0.5

package/dist/cjs/index.js

@@ -5716,31 +5716,31 @@ var require_cjs = __commonJS({
       }
       return buffer;
     }
+    var tempBuffer = new ArrayBuffer(8);
+    var tempView = new DataView(tempBuffer);
+    var tempArray = new Uint8Array(tempBuffer);
     function bytesToNumber(bytes, offset = 0, length = bytes.length) {
-      if (length === 4) {
-        return (bytes[offset] | bytes[offset + 1] << 8 | bytes[offset + 2] << 16 | bytes[offset + 3] << 24) >>> 0;
-      }
-      if (length === 8) {
-        const low2 = (bytes[offset] | bytes[offset + 1] << 8 | bytes[offset + 2] << 16 | bytes[offset + 3] << 24) >>> 0;
-        const high = (bytes[offset + 4] | bytes[offset + 5] << 8 | bytes[offset + 6] << 16 | bytes[offset + 7] << 24) >>> 0;
-        return low2 + high * 4294967296;
+      tempArray.set(bytes.subarray(offset, offset + length));
+      switch (length) {
+        case 1:
+          return tempView.getUint8(0);
+        case 2:
+          return tempView.getUint16(0, true);
+        case 3:
+          return tempView.getUint16(0, true) + (tempView.getUint8(2) << 16);
+        case 4:
+          return tempView.getUint32(0, true);
+        case 5:
+          return tempView.getUint32(0, true) + tempView.getUint8(4) * 4294967296;
+        case 6:
+          return tempView.getUint32(0, true) + tempView.getUint16(4, true) * 4294967296;
+        case 7:
+          return tempView.getUint32(0, true) + (tempView.getUint16(4, true) + (tempView.getUint8(6) << 16)) * 4294967296;
+        case 8:
+          return tempView.getUint32(0, true) + tempView.getUint32(4, true) * 4294967296;
+        default:
+          return 0;
       }
-      let low = 0;
-      const lenLow = length < 4 ? length : 4;
-      for (let i = 0; i < lenLow; i++) {
-        low |= bytes[offset + i] << i * 8;
-      }
-      low >>>= 0;
-      if (length > 4) {
-        let high = 0;
-        const lenHigh = length < 8 ? length : 8;
-        for (let i = 4; i < lenHigh; i++) {
-          high |= bytes[offset + i] << (i - 4) * 8;
-        }
-        high >>>= 0;
-        return low + high * 4294967296;
-      }
-      return low;
     }
     function setBit(value, bitPos, flag) {
       if (flag) {
@@ -8294,7 +8294,7 @@ var require_cjs = __commonJS({
         this.maxBodySize = this.pfs.pageSize - DataPageManager.CONSTANT.SIZE_PAGE_HEADER;
         this.order = this.getOptimalOrder(pfs.pageSize, IndexPageManager.CONSTANT.SIZE_KEY, IndexPageManager.CONSTANT.SIZE_VALUE);
         this.strategy = new RowIdentifierStrategy(this.order, pfs, txContext);
-        const budget = import_node_os.default.freemem() * 0.1;
+        const budget = import_node_os.default.totalmem() * 0.1;
         const nodeMemory = this.order * 24 + 256;
         const capacity = Math.max(1e3, Math.min(1e6, Math.floor(budget / nodeMemory)));
         this.bptree = new BPTreeAsync2(
@@ -8679,41 +8679,44 @@ var require_cjs = __commonJS({
         if (pks.length === 0) {
           return [];
         }
+        const pkIndexMap = /* @__PURE__ */ new Map();
+        for (let i = 0, len = pks.length; i < len; i++) {
+          pkIndexMap.set(pks[i], i);
+        }
         const minPk = Math.min(...pks);
         const maxPk = Math.max(...pks);
-        const pkSet = new Set(pks);
-        const pkRidPairs = [];
+        const pkRidPairs = new Array(pks.length).fill(null);
         const btx = await this.getBPTreeTransaction(tx);
         const stream = btx.whereStream({ gte: minPk, lte: maxPk });
         for await (const [rid, pk] of stream) {
-          if (pkSet.has(pk)) {
-            pkRidPairs.push({ pk, rid });
+          const index = pkIndexMap.get(pk);
+          if (index !== void 0) {
+            pkRidPairs[index] = { pk, rid, index };
           }
         }
-        const resultMap = await this.fetchRowsByRids(pkRidPairs, tx);
-        return pks.map((pk) => resultMap.get(pk) ?? null);
+        return this.fetchRowsByRids(pkRidPairs, tx);
       }
       /**
        * Fetches multiple rows by their RID and PK combinations, grouping by page ID to minimize I/O.
        * @param pkRidPairs Array of {pk, rid} pairs
        * @param tx Transaction
-       * @returns Map of PK to row data
+       * @returns Array of row data in the same order as input PKs
        */
       async fetchRowsByRids(pkRidPairs, tx) {
-        const resultMap = /* @__PURE__ */ new Map();
-        if (pkRidPairs.length === 0) return resultMap;
+        const result = new Array(pkRidPairs.length).fill(null);
+        if (pkRidPairs.length === 0) return result;
         const pageGroupMap = /* @__PURE__ */ new Map();
         for (const pair of pkRidPairs) {
+          if (pair === null) continue;
           const rid = pair.rid;
           const slotIndex = rid % 65536;
           const pageId = Math.floor(rid / 65536);
           if (!pageGroupMap.has(pageId)) {
             pageGroupMap.set(pageId, []);
           }
-          pageGroupMap.get(pageId).push({ pk: pair.pk, slotIndex });
+          pageGroupMap.get(pageId).push({ pk: pair.pk, slotIndex, index: pair.index });
         }
-        const sortedPageEntries = Array.from(pageGroupMap.entries()).sort((a, b) => a[0] - b[0]);
-        await Promise.all(sortedPageEntries.map(async ([pageId, items]) => {
+        await Promise.all(Array.from(pageGroupMap).map(async ([pageId, items]) => {
           const page = await this.pfs.get(pageId, tx);
           if (!this.factory.isDataPage(page)) {
             throw new Error(`Page ${pageId} is not a data page`);
@@ -8722,17 +8725,17 @@ var require_cjs = __commonJS({
           for (const item of items) {
             const row = manager.getRow(page, item.slotIndex);
             if (this.rowManager.getDeletedFlag(row)) {
-              resultMap.set(item.pk, null);
+              result[item.index] = null;
             } else if (this.rowManager.getOverflowFlag(row)) {
               const overflowPageId = bytesToNumber(this.rowManager.getBody(row));
               const body = await this.pfs.getBody(overflowPageId, true, tx);
-              resultMap.set(item.pk, body);
+              result[item.index] = body;
             } else {
-              resultMap.set(item.pk, this.rowManager.getBody(row));
+              result[item.index] = this.rowManager.getBody(row);
             }
           }
         }));
-        return resultMap;
+        return result;
       }
       async fetchRowByRid(pk, rid, tx) {
         this.keyManager.setBufferFromKey(rid, this.ridBuffer);
@@ -9522,7 +9525,7 @@ __export(src_exports, {
 });
 module.exports = __toCommonJS(src_exports);
 
-// src/core/document.ts
+// src/core/documentAPI.ts
 var os = __toESM(require("node:os"));
 var import_dataply3 = __toESM(require_cjs());
 
@@ -9678,17 +9681,34 @@ var BinaryHeap = class {
   }
 };
 
-// src/core/document.ts
+// src/core/documentAPI.ts
 var DocumentDataplyAPI = class extends import_dataply3.DataplyAPI {
   indices = {};
   trees = /* @__PURE__ */ new Map();
   comparator = new DocumentValueComparator();
   pendingBackfillFields = [];
   lock;
+  indexedFields;
+  operatorConverters = {
+    equal: "primaryEqual",
+    notEqual: "primaryNotEqual",
+    lt: "primaryLt",
+    lte: "primaryLte",
+    gt: "primaryGt",
+    gte: "primaryGte",
+    or: "primaryOr",
+    like: "like"
+  };
   constructor(file, options) {
     super(file, options);
     this.trees = /* @__PURE__ */ new Map();
     this.lock = new import_dataply3.Ryoiki();
+    this.indexedFields = /* @__PURE__ */ new Set(["_id"]);
+    if (options?.indices) {
+      for (const field of Object.keys(options.indices)) {
+        this.indexedFields.add(field);
+      }
+    }
     this.hook.onceAfter("init", async (tx, isNewlyCreated) => {
       if (isNewlyCreated) {
         await this.initializeDocumentFile(tx);
@@ -9898,81 +9918,6 @@ var DocumentDataplyAPI = class extends import_dataply3.DataplyAPI {
   async updateDocumentInnerMetadata(metadata, tx) {
     await this.update(1, JSON.stringify(metadata), tx);
   }
-};
-var DocumentDataply = class _DocumentDataply {
-  /**
-   * Starts the database definition by setting the document type.
-   * This is used to ensure TypeScript type inference works correctly for the document structure.
-   * @template T The structure of the document to be stored.
-   */
-  static Define() {
-    return {
-      /**
-       * Sets the options for the database, such as index configurations and WAL settings.
-       * @template IC The configuration of indices.
-       * @param options The database initialization options.
-       */
-      Options: (options) => _DocumentDataply.Options(options)
-    };
-  }
-  /**
-   * Internal method used by the Define-chain to pass options.
-   */
-  static Options(options) {
-    return {
-      /**
-       * Creates or opens the database instance with the specified file path.
-       * @param file The path to the database file.
-       */
-      Open: (file) => _DocumentDataply.Open(file, options)
-    };
-  }
-  /**
-   * Internal method used to finalize construction and create the instance.
-   */
-  static Open(file, options) {
-    return new _DocumentDataply(file, options);
-  }
-  api;
-  indexedFields;
-  operatorConverters = {
-    equal: "primaryEqual",
-    notEqual: "primaryNotEqual",
-    lt: "primaryLt",
-    lte: "primaryLte",
-    gt: "primaryGt",
-    gte: "primaryGte",
-    or: "primaryOr",
-    like: "like"
-  };
-  constructor(file, options) {
-    this.api = new DocumentDataplyAPI(file, options ?? {});
-    this.indexedFields = /* @__PURE__ */ new Set(["_id"]);
-    if (options?.indices) {
-      for (const field of Object.keys(options.indices)) {
-        this.indexedFields.add(field);
-      }
-    }
-  }
-  /**
-   * Initialize the document database
-   */
-  async init() {
-    await this.api.init();
-    await this.api.backfillIndices();
-  }
-  /**
-   * Get the metadata of the document database
-   */
-  async getMetadata(tx) {
-    return this.api.runWithDefault((tx2) => this.api.getDocumentMetadata(tx2), tx);
-  }
-  /**
-   * Create a transaction
-   */
-  createTransaction() {
-    return this.api.createTransaction();
-  }
   verboseQuery(query) {
     const result = {};
     for (const field in query) {
@@ -10009,7 +9954,7 @@ var DocumentDataply = class _DocumentDataply {
   async getSelectivityCandidate(query, orderByField) {
     const candidates = [];
     for (const field in query) {
-      const tree = this.api.trees.get(field);
+      const tree = this.trees.get(field);
       if (!tree) continue;
       const condition = query[field];
       const treeTx = await tree.createTransaction();
@@ -10045,6 +9990,17 @@ var DocumentDataply = class _DocumentDataply {
       rollback
     };
   }
+  /**
+   * Get Free Memory Chunk Size
+   * @returns { verySmallChunkSize, smallChunkSize }
+   */
+  getFreeMemoryChunkSize() {
+    const freeMem = os.freemem();
+    const safeLimit = freeMem * 0.2;
+    const verySmallChunkSize = safeLimit * 0.05;
+    const smallChunkSize = safeLimit * 0.3;
+    return { verySmallChunkSize, smallChunkSize };
+  }
   /**
    * Get Primary Keys based on query and index selection.
    * Internal common method to unify query optimization.
@@ -10057,33 +10013,33 @@ var DocumentDataply = class _DocumentDataply {
       verbose,
       orderBy
     );
-    if (!selectivity) return /* @__PURE__ */ new Set();
+    if (!selectivity) return new Float64Array(0);
     const { driver, others, rollback } = selectivity;
     const isDriverOrderByField = orderBy === void 0 || driver.field === orderBy;
     if (isDriverOrderByField) {
-      let keys = await driver.tree.keys(driver.condition, void 0, sortOrder);
+      let keysSet = await driver.tree.keys(driver.condition, void 0, sortOrder);
       for (const { tree, condition } of others) {
-        keys = await tree.keys(condition, keys, sortOrder);
+        keysSet = await tree.keys(condition, keysSet, sortOrder);
       }
       rollback();
-      return keys;
+      return new Float64Array(keysSet);
     } else {
-      let keys = await driver.tree.keys(driver.condition, void 0);
+      let keysSet = await driver.tree.keys(driver.condition, void 0);
       for (const { tree, condition } of others) {
-        keys = await tree.keys(condition, keys);
+        keysSet = await tree.keys(condition, keysSet);
       }
       rollback();
-      return keys;
+      return new Float64Array(keysSet);
     }
   }
-  async insertDocument(document, tx) {
-    const metadata = await this.api.getDocumentInnerMetadata(tx);
+  async insertDocumentInternal(document, tx) {
+    const metadata = await this.getDocumentInnerMetadata(tx);
     const id = ++metadata.lastId;
-    await this.api.updateDocumentInnerMetadata(metadata, tx);
+    await this.updateDocumentInnerMetadata(metadata, tx);
     const dataplyDocument = Object.assign({
       _id: id
     }, document);
-    const pk = await this.api.insert(JSON.stringify(dataplyDocument), true, tx);
+    const pk = await super.insert(JSON.stringify(dataplyDocument), true, tx);
     return {
       pk,
       id,
@@ -10096,12 +10052,12 @@ var DocumentDataply = class _DocumentDataply {
    * @param tx The transaction to use
    * @returns The primary key of the inserted document
    */
-  async insert(document, tx) {
-    return this.api.writeLock(() => this.api.runWithDefault(async (tx2) => {
-      const { pk, document: dataplyDocument } = await this.insertDocument(document, tx2);
-      const flattenDocument = this.api.flattenDocument(dataplyDocument);
+  async insertSingleDocument(document, tx) {
+    return this.writeLock(() => this.runWithDefault(async (tx2) => {
+      const { pk, document: dataplyDocument } = await this.insertDocumentInternal(document, tx2);
+      const flattenDocument = this.flattenDocument(dataplyDocument);
       for (const field in flattenDocument) {
-        const tree = this.api.trees.get(field);
+        const tree = this.trees.get(field);
         if (!tree) continue;
         const v = flattenDocument[field];
         const [error] = await catchPromise(tree.insert(pk, { k: pk, v }));
@@ -10118,12 +10074,12 @@ var DocumentDataply = class _DocumentDataply {
    * @param tx The transaction to use
    * @returns The primary keys of the inserted documents
    */
-  async insertBatch(documents, tx) {
-    return this.api.writeLock(() => this.api.runWithDefault(async (tx2) => {
-      const metadata = await this.api.getDocumentInnerMetadata(tx2);
+  async insertBatchDocuments(documents, tx) {
+    return this.writeLock(() => this.runWithDefault(async (tx2) => {
+      const metadata = await this.getDocumentInnerMetadata(tx2);
       const startId = metadata.lastId + 1;
       metadata.lastId += documents.length;
-      await this.api.updateDocumentInnerMetadata(metadata, tx2);
+      await this.updateDocumentInnerMetadata(metadata, tx2);
       const ids = [];
       const dataplyDocuments = [];
       const flattenedData = [];
@@ -10134,15 +10090,15 @@ var DocumentDataply = class _DocumentDataply {
         }, documents[i]);
         const stringified = JSON.stringify(dataplyDocument);
         dataplyDocuments.push(stringified);
-        const flattenDocument = this.api.flattenDocument(dataplyDocument);
+        const flattenDocument = this.flattenDocument(dataplyDocument);
         flattenedData.push({ pk: -1, data: flattenDocument });
         ids.push(id);
       }
-      const pks = await this.api.insertBatch(dataplyDocuments, true, tx2);
+      const pks = await super.insertBatch(dataplyDocuments, true, tx2);
       for (let i = 0, len = pks.length; i < len; i++) {
         flattenedData[i].pk = pks[i];
       }
-      for (const [field, tree] of this.api.trees) {
+      for (const [field, tree] of this.trees) {
         const treeTx = await tree.createTransaction();
         for (let i = 0, len = flattenedData.length; i < len; i++) {
           const item = flattenedData[i];
@@ -10172,16 +10128,17 @@ var DocumentDataply = class _DocumentDataply {
     const pks = await this.getKeys(query);
     let updatedCount = 0;
     const treeTxs = /* @__PURE__ */ new Map();
-    for (const [field, tree] of this.api.trees) {
+    for (const [field, tree] of this.trees) {
       treeTxs.set(field, await tree.createTransaction());
     }
     treeTxs.delete("_id");
-    for (const pk of pks) {
-      const doc = await this.api.getDocument(pk, tx);
+    for (let i = 0, len = pks.length; i < len; i++) {
+      const pk = pks[i];
+      const doc = await this.getDocument(pk, tx);
       if (!doc) continue;
       const updatedDoc = computeUpdatedDoc(doc);
-      const oldFlatDoc = this.api.flattenDocument(doc);
-      const newFlatDoc = this.api.flattenDocument(updatedDoc);
+      const oldFlatDoc = this.flattenDocument(doc);
+      const newFlatDoc = this.flattenDocument(updatedDoc);
       for (const [field, treeTx] of treeTxs) {
         const oldV = oldFlatDoc[field];
         const newV = newFlatDoc[field];
@@ -10193,7 +10150,7 @@ var DocumentDataply = class _DocumentDataply {
           await treeTx.insert(pk, { k: pk, v: newV });
         }
       }
-      await this.api.update(pk, JSON.stringify(updatedDoc), tx);
+      await this.update(pk, JSON.stringify(updatedDoc), tx);
       updatedCount++;
     }
     for (const [field, treeTx] of treeTxs) {
@@ -10215,7 +10172,7 @@ var DocumentDataply = class _DocumentDataply {
    * @returns The number of updated documents
    */
   async fullUpdate(query, newRecord, tx) {
-    return await this.api.writeLock(() => this.api.runWithDefault(async (tx2) => {
+    return await this.writeLock(() => this.runWithDefault(async (tx2) => {
       return this.updateInternal(query, (doc) => {
         const newDoc = typeof newRecord === "function" ? newRecord(doc) : newRecord;
         return { _id: doc._id, ...newDoc };
@@ -10230,11 +10187,12 @@ var DocumentDataply = class _DocumentDataply {
    * @returns The number of updated documents
    */
   async partialUpdate(query, newRecord, tx) {
-    return this.api.writeLock(() => this.api.runWithDefault(async (tx2) => {
+    return this.writeLock(() => this.runWithDefault(async (tx2) => {
       return this.updateInternal(query, (doc) => {
-        const partialUpdate = typeof newRecord === "function" ? newRecord(doc) : newRecord;
-        delete partialUpdate._id;
-        return { ...doc, ...partialUpdate };
+        const partialUpdateContent = typeof newRecord === "function" ? newRecord(doc) : newRecord;
+        const finalUpdate = { ...partialUpdateContent };
+        delete finalUpdate._id;
+        return { ...doc, ...finalUpdate };
       }, tx2);
     }, tx));
   }
@@ -10244,20 +10202,21 @@ var DocumentDataply = class _DocumentDataply {
    * @param tx The transaction to use
    * @returns The number of deleted documents
    */
-  async delete(query, tx) {
-    return this.api.writeLock(() => this.api.runWithDefault(async (tx2) => {
+  async deleteDocuments(query, tx) {
+    return this.writeLock(() => this.runWithDefault(async (tx2) => {
       const pks = await this.getKeys(query);
       let deletedCount = 0;
-      for (const pk of pks) {
-        const doc = await this.api.getDocument(pk, tx2);
+      for (let i = 0, len = pks.length; i < len; i++) {
+        const pk = pks[i];
+        const doc = await this.getDocument(pk, tx2);
         if (!doc) continue;
-        const flatDoc = this.api.flattenDocument(doc);
-        for (const [field, tree] of this.api.trees) {
+        const flatDoc = this.flattenDocument(doc);
+        for (const [field, tree] of this.trees) {
           const v = flatDoc[field];
           if (v === void 0) continue;
           await tree.delete(pk, { k: pk, v });
         }
-        await this.api.delete(pk, true, tx2);
+        await super.delete(pk, true, tx2);
         deletedCount++;
       }
       return deletedCount;
@@ -10269,10 +10228,10 @@ var DocumentDataply = class _DocumentDataply {
    * @param tx The transaction to use
    * @returns The number of documents that match the query
    */
-  async count(query, tx) {
-    return this.api.readLock(() => this.api.runWithDefault(async (tx2) => {
+  async countDocuments(query, tx) {
+    return this.readLock(() => this.runWithDefault(async (tx2) => {
       const pks = await this.getKeys(query);
-      return pks.size;
+      return pks.length;
     }, tx));
   }
   /**
@@ -10283,7 +10242,7 @@ var DocumentDataply = class _DocumentDataply {
    * @returns The documents that match the query
    * @throws Error if query or orderBy contains non-indexed fields
    */
-  select(query, options = {}, tx) {
+  selectDocuments(query, options = {}, tx) {
     for (const field of Object.keys(query)) {
       if (!this.indexedFields.has(field)) {
         throw new Error(`Query field "${field}" is not indexed. Available indexed fields: ${Array.from(this.indexedFields).join(", ")}`);
@@ -10300,9 +10259,8 @@ var DocumentDataply = class _DocumentDataply {
       orderBy: orderByField
     } = options;
     const self = this;
-    const stream = this.api.streamWithDefault(async function* (tx2) {
-      const keySet = await self.getKeys(query, orderByField, sortOrder);
-      const keys = new Uint32Array(keySet);
+    const stream = this.streamWithDefault(async function* (tx2) {
+      const keys = await self.getKeys(query, orderByField, sortOrder);
       const totalKeys = keys.length;
       if (totalKeys === 0) return;
       const selectivity = await self.getSelectivityCandidate(
@@ -10313,72 +10271,73 @@ var DocumentDataply = class _DocumentDataply {
       if (selectivity) {
         selectivity.rollback();
       }
-      let CHUNK_SIZE = 100;
+      let currentChunkSize = self.options.pageSize;
       if (!isDriverOrderByField && orderByField) {
-        const isTopK = limit !== Infinity;
-        const heapSizeLimit = isTopK ? limit + offset : Infinity;
-        const heapComparator = (a, b) => {
-          const aVal = a[orderByField] ?? a._id;
-          const bVal = b[orderByField] ?? b._id;
-          const cmp = aVal < bVal ? -1 : aVal > bVal ? 1 : 0;
-          return sortOrder === "asc" ? -cmp : cmp;
-        };
-        const heap = isTopK ? new BinaryHeap(heapComparator) : null;
+        const topK = limit === Infinity ? Infinity : offset + limit;
+        let heap = null;
+        if (topK !== Infinity) {
+          const heapComparator = (a, b) => {
+            const aVal = a[orderByField] ?? a._id;
+            const bVal = b[orderByField] ?? b._id;
+            const cmp = aVal < bVal ? -1 : aVal > bVal ? 1 : 0;
+            return sortOrder === "asc" ? -cmp : cmp;
+          };
+          heap = new BinaryHeap(heapComparator);
+        }
         const results = [];
         let i = 0;
-        const firstChunk = Array.from(keys.subarray(i, i + 100));
-        const firstResults = await self.api.selectMany(firstChunk, false, tx2);
-        let totalBytes = 0;
-        let count = 0;
-        for (const s of firstResults) {
-          if (!s) continue;
-          totalBytes += s.length;
-          count++;
-          const doc = JSON.parse(s);
-          if (heap) {
-            if (heap.size < heapSizeLimit) {
-              heap.push(doc);
-            } else if (heapComparator(doc, heap.peek()) > 0) {
-              heap.replace(doc);
-            }
-          } else {
-            results.push(doc);
-          }
-        }
-        const avgSize = count > 0 ? totalBytes / count : 1024;
-        CHUNK_SIZE = Math.max(32, Math.floor(os.freemem() * 0.1 / avgSize));
-        i += firstChunk.length;
-        let nextSortChunkPromise = null;
+        let nextChunkPromise = null;
         if (i < totalKeys) {
-          const nextChunk = Array.from(keys.subarray(i, i + CHUNK_SIZE));
-          nextSortChunkPromise = self.api.selectMany(nextChunk, false, tx2);
-          i += nextChunk.length;
-        }
-        while (nextSortChunkPromise) {
-          const stringifiedResults = await nextSortChunkPromise;
+          const endIdx = Math.min(i + currentChunkSize, totalKeys);
+          const chunkKeys = keys.subarray(i, endIdx);
+          nextChunkPromise = self.selectMany(chunkKeys, false, tx2);
+          i = endIdx;
+        }
+        while (nextChunkPromise) {
+          const rawResults = await nextChunkPromise;
+          nextChunkPromise = null;
+          const { verySmallChunkSize, smallChunkSize } = self.getFreeMemoryChunkSize();
           if (i < totalKeys) {
-            const nextChunk = Array.from(keys.subarray(i, i + CHUNK_SIZE));
-            nextSortChunkPromise = self.api.selectMany(nextChunk, false, tx2);
-            i += nextChunk.length;
-          } else {
-            nextSortChunkPromise = null;
-          }
-          for (const stringified of stringifiedResults) {
-            if (!stringified) continue;
-            const doc = JSON.parse(stringified);
-            if (heap) {
-              if (heap.size < heapSizeLimit) {
-                heap.push(doc);
-              } else if (heapComparator(doc, heap.peek()) > 0) {
-                heap.replace(doc);
+            const endIdx = Math.min(i + currentChunkSize, totalKeys);
+            const chunkKeys = keys.subarray(i, endIdx);
+            nextChunkPromise = self.selectMany(chunkKeys, false, tx2);
+            i = endIdx;
+          }
+          let chunkTotalSize = 0;
+          for (let j = 0, len = rawResults.length; j < len; j++) {
+            const s = rawResults[j];
+            if (s) {
+              const doc = JSON.parse(s);
+              chunkTotalSize += s.length * 2;
+              if (heap) {
+                if (heap.size < topK) heap.push(doc);
+                else {
+                  const top = heap.peek();
+                  if (top) {
+                    const aVal = doc[orderByField] ?? doc._id;
+                    const bVal = top[orderByField] ?? top._id;
+                    const cmp = aVal < bVal ? -1 : aVal > bVal ? 1 : 0;
+                    const isBetter = sortOrder === "asc" ? cmp < 0 : cmp > 0;
+                    if (isBetter) {
+                      heap.replace(doc);
+                    }
+                  }
+                }
+              } else {
+                results.push(doc);
               }
-            } else {
-              results.push(doc);
+            }
+          }
+          if (chunkTotalSize > 0) {
+            if (chunkTotalSize < verySmallChunkSize) {
+              currentChunkSize = currentChunkSize * 2;
+            } else if (chunkTotalSize > smallChunkSize) {
+              currentChunkSize = Math.max(Math.floor(currentChunkSize / 2), 20);
             }
           }
         }
-        const finalResults = heap ? heap.toArray() : results;
-        finalResults.sort((a, b) => {
+        const finalDocs = heap ? heap.toArray() : results;
+        finalDocs.sort((a, b) => {
           const aVal = a[orderByField] ?? a._id;
           const bVal = b[orderByField] ?? b._id;
           const cmp = aVal < bVal ? -1 : aVal > bVal ? 1 : 0;
@@ -10386,58 +10345,46 @@ var DocumentDataply = class _DocumentDataply {
         });
         const start = offset;
         const end = limit === Infinity ? void 0 : start + limit;
-        const limitedResults = finalResults.slice(start, end);
-        for (const doc of limitedResults) {
-          yield doc;
+        const limitedResults = finalDocs.slice(start, end);
+        for (let j = 0, len = limitedResults.length; j < len; j++) {
+          yield limitedResults[j];
         }
       } else {
         let yieldedCount = 0;
         let i = offset;
-        if (i >= totalKeys || yieldedCount >= limit) return;
-        const pksToFetchCount = Math.min(100, limit - yieldedCount);
-        const firstChunk = Array.from(keys.subarray(i, i + pksToFetchCount));
-        const firstResults = await self.api.selectMany(firstChunk, false, tx2);
-        let totalBytes = 0;
-        let count = 0;
-        for (const s of firstResults) {
-          if (!s) continue;
-          yield JSON.parse(s);
-          yieldedCount++;
-          totalBytes += s.length;
-          count++;
-          if (yieldedCount >= limit) break;
-        }
-        const avgSize = count > 0 ? totalBytes / count : 1024;
-        CHUNK_SIZE = Math.max(32, Math.floor(os.freemem() * 0.1 / avgSize));
-        i += firstChunk.length;
-        let nextStreamChunkPromise = null;
-        if (i < totalKeys && yieldedCount < limit) {
-          const nextPksToFetchCount = Math.min(CHUNK_SIZE, limit - yieldedCount);
-          const nextChunk = Array.from(keys.subarray(i, i + nextPksToFetchCount));
-          nextStreamChunkPromise = self.api.selectMany(nextChunk, false, tx2);
-          i += nextChunk.length;
-        }
-        while (nextStreamChunkPromise) {
-          const stringifiedResults = await nextStreamChunkPromise;
-          if (i < totalKeys && yieldedCount < limit) {
-            const nextPksToFetchCount = Math.min(CHUNK_SIZE, limit - (yieldedCount + stringifiedResults.filter(Boolean).length));
-            if (nextPksToFetchCount > 0) {
-              const nextChunk = Array.from(keys.subarray(i, i + nextPksToFetchCount));
-              nextStreamChunkPromise = self.api.selectMany(nextChunk, false, tx2);
-              i += nextChunk.length;
-            } else {
-              nextStreamChunkPromise = null;
+        let nextChunkPromise = null;
+        if (yieldedCount < limit && i < totalKeys) {
+          const endIdx = Math.min(i + currentChunkSize, totalKeys);
+          const chunkKeys = keys.subarray(i, endIdx);
+          nextChunkPromise = self.selectMany(chunkKeys, false, tx2);
+          i = endIdx;
+        }
+        while (nextChunkPromise) {
+          const rawResults = await nextChunkPromise;
+          nextChunkPromise = null;
+          const { verySmallChunkSize, smallChunkSize } = self.getFreeMemoryChunkSize();
+          if (yieldedCount < limit && i < totalKeys) {
+            const endIdx = Math.min(i + currentChunkSize, totalKeys);
+            const chunkKeys = keys.subarray(i, endIdx);
+            nextChunkPromise = self.selectMany(chunkKeys, false, tx2);
+            i = endIdx;
+          }
+          let chunkTotalSize = 0;
+          for (let j = 0, len = rawResults.length; j < len; j++) {
+            const s = rawResults[j];
+            if (s) {
+              if (yieldedCount < limit) {
+                yield JSON.parse(s);
+                yieldedCount++;
+              }
+              chunkTotalSize += s.length * 2;
             }
-          } else {
-            nextStreamChunkPromise = null;
-          }
-          for (const stringified of stringifiedResults) {
-            if (!stringified) continue;
-            yield JSON.parse(stringified);
-            yieldedCount++;
-            if (yieldedCount >= limit) {
-              nextStreamChunkPromise = null;
-              break;
+          }
+          if (chunkTotalSize > 0) {
+            if (chunkTotalSize < verySmallChunkSize) {
+              currentChunkSize = currentChunkSize * 2;
+            } else if (chunkTotalSize > smallChunkSize) {
+              currentChunkSize = Math.max(Math.floor(currentChunkSize / 2), 20);
             }
           }
         }
@@ -10452,6 +10399,133 @@ var DocumentDataply = class _DocumentDataply {
     };
     return { stream, drain };
   }
+};
+
+// src/core/document.ts
+var DocumentDataply = class _DocumentDataply {
+  /**
+   * Starts the database definition by setting the document type.
+   * This is used to ensure TypeScript type inference works correctly for the document structure.
+   * @template T The structure of the document to be stored.
+   */
+  static Define() {
+    return {
+      /**
+       * Sets the options for the database, such as index configurations and WAL settings.
+       * @template IC The configuration of indices.
+       * @param options The database initialization options.
+       */
+      Options: (options) => _DocumentDataply.Options(options)
+    };
+  }
+  /**
+   * Internal method used by the Define-chain to pass options.
+   */
+  static Options(options) {
+    return {
+      /**
+       * Creates or opens the database instance with the specified file path.
+       * @param file The path to the database file.
+       */
+      Open: (file) => _DocumentDataply.Open(file, options)
+    };
+  }
+  /**
+   * Internal method used to finalize construction and create the instance.
+   */
+  static Open(file, options) {
+    return new _DocumentDataply(file, options);
+  }
+  api;
+  constructor(file, options) {
+    this.api = new DocumentDataplyAPI(file, options ?? {});
+  }
+  /**
+   * Initialize the document database
+   */
+  async init() {
+    await this.api.init();
+    await this.api.backfillIndices();
+  }
+  /**
+   * Get the metadata of the document database
+   */
+  async getMetadata(tx) {
+    return this.api.runWithDefault((tx2) => this.api.getDocumentMetadata(tx2), tx);
+  }
+  /**
+   * Create a transaction
+   */
+  createTransaction() {
+    return this.api.createTransaction();
+  }
+  /**
+   * Insert a document into the database
+   * @param document The document to insert
+   * @param tx The transaction to use
+   * @returns The primary key of the inserted document
+   */
+  async insert(document, tx) {
+    return this.api.insertSingleDocument(document, tx);
+  }
+  /**
+   * Insert a batch of documents into the database
+   * @param documents The documents to insert
+   * @param tx The transaction to use
+   * @returns The primary keys of the inserted documents
+   */
+  async insertBatch(documents, tx) {
+    return this.api.insertBatchDocuments(documents, tx);
+  }
+  /**
+   * Fully update documents from the database that match the query
+   * @param query The query to use (only indexed fields + _id allowed)
+   * @param newRecord Complete document to replace with, or function that receives current document and returns new document
+   * @param tx The transaction to use
+   * @returns The number of updated documents
+   */
+  async fullUpdate(query, newRecord, tx) {
+    return this.api.fullUpdate(query, newRecord, tx);
+  }
+  /**
+   * Partially update documents from the database that match the query
+   * @param query The query to use (only indexed fields + _id allowed)
+   * @param newRecord Partial document to merge, or function that receives current document and returns partial update
+   * @param tx The transaction to use
+   * @returns The number of updated documents
+   */
+  async partialUpdate(query, newRecord, tx) {
+    return this.api.partialUpdate(query, newRecord, tx);
+  }
+  /**
+   * Delete documents from the database that match the query
+   * @param query The query to use (only indexed fields + _id allowed)
+   * @param tx The transaction to use
+   * @returns The number of deleted documents
+   */
+  async delete(query, tx) {
+    return this.api.deleteDocuments(query, tx);
+  }
+  /**
+   * Count documents from the database that match the query
+   * @param query The query to use (only indexed fields + _id allowed)
+   * @param tx The transaction to use
+   * @returns The number of documents that match the query
+   */
+  async count(query, tx) {
+    return this.api.countDocuments(query, tx);
+  }
+  /**
+   * Select documents from the database
+   * @param query The query to use (only indexed fields + _id allowed)
+   * @param options The options to use
+   * @param tx The transaction to use
+   * @returns The documents that match the query
+   * @throws Error if query or orderBy contains non-indexed fields
+   */
+  select(query, options = {}, tx) {
+    return this.api.selectDocuments(query, options, tx);
+  }
   /**
    * Close the document database
    */

package/dist/types/core/bptree/documentStrategy.d.ts

@@ -1,6 +1,6 @@
 import type { DataplyTreeValue, Primitive } from '../../types';
 import { BPTreeNode, SerializeStrategyAsync, type SerializeStrategyHead } from 'dataply';
-import { DocumentDataplyAPI } from '../document';
+import { DocumentDataplyAPI } from '../documentAPI';
 export declare class DocumentSerializeStrategyAsync<T extends Primitive> extends SerializeStrategyAsync<number, DataplyTreeValue<T>> {
     protected readonly api: DocumentDataplyAPI<any, any>;
     protected readonly txContext: DocumentDataplyAPI<any, any>['txContext'];

package/dist/types/core/document.d.ts

@@ -1,39 +1,6 @@
-import type { DataplyTreeValue, DocumentDataplyInnerMetadata, DocumentDataplyOptions, DocumentJSON, FlattenedDocumentJSON, Primitive, DocumentDataplyQuery, DocumentDataplyIndexedQuery, DocumentDataplyCondition, DataplyDocument, DocumentDataplyMetadata, DocumentDataplyQueryOptions, IndexConfig } from '../types';
-import { DataplyAPI, Transaction, BPTreeAsync } from 'dataply';
-import { DocumentValueComparator } from './bptree/documentComparator';
-export declare class DocumentDataplyAPI<T extends DocumentJSON, IC extends IndexConfig<T>> extends DataplyAPI {
-    runWithDefault: <T_1>(callback: (tx: Transaction) => Promise<T_1>, tx?: Transaction) => Promise<T_1>;
-    streamWithDefault: <T_1>(callback: (tx: Transaction) => AsyncGenerator<T_1>, tx?: Transaction) => AsyncGenerator<T_1>;
-    indices: DocumentDataplyInnerMetadata['indices'];
-    readonly trees: Map<string, BPTreeAsync<number, DataplyTreeValue<Primitive>>>;
-    readonly comparator: DocumentValueComparator<DataplyTreeValue<Primitive>, Primitive>;
-    private pendingBackfillFields;
-    private readonly lock;
-    constructor(file: string, options: DocumentDataplyOptions<T, IC>);
-    getDocument(pk: number, tx?: Transaction): Promise<DataplyDocument<T>>;
-    readLock<T>(fn: () => T): Promise<T>;
-    writeLock<T>(fn: () => T): Promise<T>;
-    /**
-     * Backfill indices for fields that were added with `true` option after data was inserted.
-     * This method should be called after `init()` if you want to index existing documents
-     * for newly added index fields.
-     *
-     * @returns Number of documents that were backfilled
-     */
-    backfillIndices(tx?: Transaction): Promise<number>;
-    createDocumentInnerMetadata(indices: DocumentDataplyInnerMetadata['indices']): DocumentDataplyInnerMetadata;
-    initializeDocumentFile(tx: Transaction): Promise<void>;
-    verifyDocumentFile(tx: Transaction): Promise<boolean>;
-    /**
-     * returns flattened document
-     * @param document
-     * @returns
-     */
-    flattenDocument(document: T): FlattenedDocumentJSON;
-    getDocumentMetadata(tx: Transaction): Promise<DocumentDataplyMetadata>;
-    getDocumentInnerMetadata(tx: Transaction): Promise<DocumentDataplyInnerMetadata>;
-    updateDocumentInnerMetadata(metadata: DocumentDataplyInnerMetadata, tx: Transaction): Promise<void>;
-}
+import type { DocumentDataplyOptions, DocumentJSON, DocumentDataplyIndexedQuery, DataplyDocument, DocumentDataplyMetadata, DocumentDataplyQueryOptions, IndexConfig } from '../types';
+import { Transaction } from 'dataply';
+import { DocumentDataplyAPI } from './documentAPI';
 export declare class DocumentDataply<T extends DocumentJSON, IC extends IndexConfig<T>> {
     /**
      * Starts the database definition by setting the document type.
@@ -63,8 +30,6 @@ export declare class DocumentDataply<T extends DocumentJSON, IC extends IndexCon
      */
     private static Open;
     protected readonly api: DocumentDataplyAPI<T, IC>;
-    private readonly indexedFields;
-    private readonly operatorConverters;
     protected constructor(file: string, options?: DocumentDataplyOptions<T, IC>);
     /**
      * Initialize the document database
@@ -78,32 +43,6 @@ export declare class DocumentDataply<T extends DocumentJSON, IC extends IndexCon
      * Create a transaction
      */
     createTransaction(): Transaction;
-    private verboseQuery;
-    /**
-     * Get the selectivity candidate for the given query
-     * @param query The query conditions
-     * @param orderByField Optional field name for orderBy optimization
-     * @returns Driver and other candidates for query execution
-     */
-    getSelectivityCandidate<U extends Partial<DocumentDataplyIndexedQuery<T, IC>>, V extends DataplyTreeValue<U>>(query: Partial<DocumentDataplyQuery<V>>, orderByField?: string): Promise<{
-        driver: {
-            tree: BPTreeAsync<number, V>;
-            condition: Partial<DocumentDataplyCondition<U>>;
-            field: string;
-        };
-        others: {
-            tree: BPTreeAsync<number, V>;
-            condition: Partial<DocumentDataplyCondition<U>>;
-            field: string;
-        }[];
-        rollback: () => void;
-    } | null>;
-    /**
-     * Get Primary Keys based on query and index selection.
-     * Internal common method to unify query optimization.
-     */
-    private getKeys;
-    private insertDocument;
     /**
      * Insert a document into the database
      * @param document The document to insert
@@ -118,14 +57,6 @@ export declare class DocumentDataply<T extends DocumentJSON, IC extends IndexCon
      * @returns The primary keys of the inserted documents
      */
     insertBatch(documents: T[], tx?: Transaction): Promise<number[]>;
-    /**
-     * Internal update method used by both fullUpdate and partialUpdate
-     * @param query The query to use
-     * @param computeUpdatedDoc Function that computes the updated document from the original
-     * @param tx The transaction to use
-     * @returns The number of updated documents
-     */
-    private updateInternal;
     /**
      * Fully update documents from the database that match the query
      * @param query The query to use (only indexed fields + _id allowed)

package/dist/types/core/documentAPI.d.ts

@@ -0,0 +1,136 @@
+import type { DataplyTreeValue, DocumentDataplyInnerMetadata, DocumentDataplyOptions, DocumentJSON, FlattenedDocumentJSON, Primitive, DataplyDocument, DocumentDataplyMetadata, IndexConfig, DocumentDataplyQuery, DocumentDataplyIndexedQuery, DocumentDataplyCondition, DocumentDataplyQueryOptions } from '../types';
+import { DataplyAPI, Transaction, BPTreeAsync } from 'dataply';
+import { DocumentValueComparator } from './bptree/documentComparator';
+export declare class DocumentDataplyAPI<T extends DocumentJSON, IC extends IndexConfig<T>> extends DataplyAPI {
+    runWithDefault: <T_1>(callback: (tx: Transaction) => Promise<T_1>, tx?: Transaction) => Promise<T_1>;
+    streamWithDefault: <T_1>(callback: (tx: Transaction) => AsyncGenerator<T_1>, tx?: Transaction) => AsyncGenerator<T_1>;
+    indices: DocumentDataplyInnerMetadata['indices'];
+    readonly trees: Map<string, BPTreeAsync<number, DataplyTreeValue<Primitive>>>;
+    readonly comparator: DocumentValueComparator<DataplyTreeValue<Primitive>, Primitive>;
+    private pendingBackfillFields;
+    private readonly lock;
+    readonly indexedFields: Set<string>;
+    private readonly operatorConverters;
+    constructor(file: string, options: DocumentDataplyOptions<T, IC>);
+    getDocument(pk: number, tx?: Transaction): Promise<DataplyDocument<T>>;
+    readLock<T>(fn: () => T): Promise<T>;
+    writeLock<T>(fn: () => T): Promise<T>;
+    /**
+     * Backfill indices for fields that were added with `true` option after data was inserted.
+     * This method should be called after `init()` if you want to index existing documents
+     * for newly added index fields.
+     *
+     * @returns Number of documents that were backfilled
+     */
+    backfillIndices(tx?: Transaction): Promise<number>;
+    createDocumentInnerMetadata(indices: DocumentDataplyInnerMetadata['indices']): DocumentDataplyInnerMetadata;
+    initializeDocumentFile(tx: Transaction): Promise<void>;
+    verifyDocumentFile(tx: Transaction): Promise<boolean>;
+    /**
+     * returns flattened document
+     * @param document
+     * @returns
+     */
+    flattenDocument(document: T): FlattenedDocumentJSON;
+    getDocumentMetadata(tx: Transaction): Promise<DocumentDataplyMetadata>;
+    getDocumentInnerMetadata(tx: Transaction): Promise<DocumentDataplyInnerMetadata>;
+    updateDocumentInnerMetadata(metadata: DocumentDataplyInnerMetadata, tx: Transaction): Promise<void>;
+    verboseQuery<U extends Partial<DocumentDataplyIndexedQuery<T, IC>>, V extends DataplyTreeValue<U>>(query: Partial<DocumentDataplyQuery<U>>): Partial<DocumentDataplyQuery<V>>;
+    /**
+     * Get the selectivity candidate for the given query
+     * @param query The query conditions
+     * @param orderByField Optional field name for orderBy optimization
+     * @returns Driver and other candidates for query execution
+     */
+    getSelectivityCandidate<U extends Partial<DocumentDataplyIndexedQuery<T, IC>>, V extends DataplyTreeValue<U>>(query: Partial<DocumentDataplyQuery<V>>, orderByField?: string): Promise<{
+        driver: {
+            tree: BPTreeAsync<number, V>;
+            condition: Partial<DocumentDataplyCondition<U>>;
+            field: string;
+        };
+        others: {
+            tree: BPTreeAsync<number, V>;
+            condition: Partial<DocumentDataplyCondition<U>>;
+            field: string;
+        }[];
+        rollback: () => void;
+    } | null>;
+    /**
+     * Get Free Memory Chunk Size
+     * @returns { verySmallChunkSize, smallChunkSize }
+     */
+    getFreeMemoryChunkSize(): {
+        verySmallChunkSize: number;
+        smallChunkSize: number;
+    };
+    /**
+     * Get Primary Keys based on query and index selection.
+     * Internal common method to unify query optimization.
+     */
+    getKeys(query: Partial<DocumentDataplyIndexedQuery<T, IC>>, orderBy?: keyof IC | '_id', sortOrder?: 'asc' | 'desc'): Promise<Float64Array>;
+    private insertDocumentInternal;
+    /**
+     * Insert a document into the database
+     * @param document The document to insert
+     * @param tx The transaction to use
+     * @returns The primary key of the inserted document
+     */
+    insertSingleDocument(document: T, tx?: Transaction): Promise<number>;
+    /**
+     * Insert a batch of documents into the database
+     * @param documents The documents to insert
+     * @param tx The transaction to use
+     * @returns The primary keys of the inserted documents
+     */
+    insertBatchDocuments(documents: T[], tx?: Transaction): Promise<number[]>;
+    /**
+     * Internal update method used by both fullUpdate and partialUpdate
+     * @param query The query to use
+     * @param computeUpdatedDoc Function that computes the updated document from the original
+     * @param tx The transaction to use
+     * @returns The number of updated documents
+     */
+    private updateInternal;
+    /**
+     * Fully update documents from the database that match the query
+     * @param query The query to use (only indexed fields + _id allowed)
+     * @param newRecord Complete document to replace with, or function that receives current document and returns new document
+     * @param tx The transaction to use
+     * @returns The number of updated documents
+     */
+    fullUpdate(query: Partial<DocumentDataplyIndexedQuery<T, IC>>, newRecord: T | ((document: DataplyDocument<T>) => T), tx?: Transaction): Promise<number>;
+    /**
+     * Partially update documents from the database that match the query
+     * @param query The query to use (only indexed fields + _id allowed)
+     * @param newRecord Partial document to merge, or function that receives current document and returns partial update
+     * @param tx The transaction to use
+     * @returns The number of updated documents
+     */
+    partialUpdate(query: Partial<DocumentDataplyIndexedQuery<T, IC>>, newRecord: Partial<DataplyDocument<T>> | ((document: DataplyDocument<T>) => Partial<DataplyDocument<T>>), tx?: Transaction): Promise<number>;
+    /**
+     * Delete documents from the database that match the query
+     * @param query The query to use (only indexed fields + _id allowed)
+     * @param tx The transaction to use
+     * @returns The number of deleted documents
+     */
+    deleteDocuments(query: Partial<DocumentDataplyIndexedQuery<T, IC>>, tx?: Transaction): Promise<number>;
+    /**
+     * Count documents from the database that match the query
+     * @param query The query to use (only indexed fields + _id allowed)
+     * @param tx The transaction to use
+     * @returns The number of documents that match the query
+     */
+    countDocuments(query: Partial<DocumentDataplyIndexedQuery<T, IC>>, tx?: Transaction): Promise<number>;
+    /**
+     * Select documents from the database
+     * @param query The query to use (only indexed fields + _id allowed)
+     * @param options The options to use
+     * @param tx The transaction to use
+     * @returns The documents that match the query
+     * @throws Error if query or orderBy contains non-indexed fields
+     */
+    selectDocuments(query: Partial<DocumentDataplyIndexedQuery<T, IC>>, options?: DocumentDataplyQueryOptions<T, IC>, tx?: Transaction): {
+        stream: AsyncIterableIterator<DataplyDocument<T>>;
+        drain: () => Promise<DataplyDocument<T>[]>;
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "document-dataply",
-  "version": "0.0.5-alpha.0",
+  "version": "0.0.5",
   "description": "Simple and powerful JSON document database supporting complex queries and flexible indexing policies.",
   "license": "MIT",
   "author": "izure <admin@izure.org>",
@@ -42,7 +42,7 @@
     "dataply"
   ],
   "dependencies": {
-    "dataply": "^0.0.21-alpha.0"
+    "dataply": "^0.0.21"
   },
   "devDependencies": {
     "@types/jest": "^30.0.0",