document-dataply 0.0.5-alpha.1 → 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) {
@@ -8681,8 +8681,7 @@ var require_cjs = __commonJS({
         }
         const pkIndexMap = /* @__PURE__ */ new Map();
         for (let i = 0, len = pks.length; i < len; i++) {
-          const pk = pks[i];
-          pkIndexMap.set(pk, i);
+          pkIndexMap.set(pks[i], i);
         }
         const minPk = Math.min(...pks);
         const maxPk = Math.max(...pks);
@@ -9526,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());
 
@@ -9617,17 +9616,99 @@ async function catchPromise(promise) {
   return promise.then((res) => [void 0, res]).catch((reason) => [reason]);
 }
 
-// src/core/document.ts
+// src/utils/heap.ts
+var BinaryHeap = class {
+  constructor(comparator) {
+    this.comparator = comparator;
+  }
+  heap = [];
+  get size() {
+    return this.heap.length;
+  }
+  peek() {
+    return this.heap[0];
+  }
+  push(value) {
+    this.heap.push(value);
+    this.bubbleUp(this.heap.length - 1);
+  }
+  pop() {
+    if (this.size === 0) return void 0;
+    const top = this.heap[0];
+    const bottom = this.heap.pop();
+    if (this.size > 0) {
+      this.heap[0] = bottom;
+      this.sinkDown(0);
+    }
+    return top;
+  }
+  /**
+   * Replace the root element with a new value and re-heapify.
+   * Faster than pop() followed by push().
+   */
+  replace(value) {
+    const top = this.heap[0];
+    this.heap[0] = value;
+    this.sinkDown(0);
+    return top;
+  }
+  toArray() {
+    return [...this.heap];
+  }
+  bubbleUp(index) {
+    while (index > 0) {
+      const parentIndex = Math.floor((index - 1) / 2);
+      if (this.comparator(this.heap[index], this.heap[parentIndex]) >= 0) break;
+      [this.heap[index], this.heap[parentIndex]] = [this.heap[parentIndex], this.heap[index]];
+      index = parentIndex;
+    }
+  }
+  sinkDown(index) {
+    while (true) {
+      let smallest = index;
+      const left = 2 * index + 1;
+      const right = 2 * index + 2;
+      if (left < this.size && this.comparator(this.heap[left], this.heap[smallest]) < 0) {
+        smallest = left;
+      }
+      if (right < this.size && this.comparator(this.heap[right], this.heap[smallest]) < 0) {
+        smallest = right;
+      }
+      if (smallest === index) break;
+      [this.heap[index], this.heap[smallest]] = [this.heap[smallest], this.heap[index]];
+      index = smallest;
+    }
+  }
+};
+
+// 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);
@@ -9837,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) {
@@ -9948,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();
@@ -9984,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.
@@ -10015,14 +10032,14 @@ var DocumentDataply = class _DocumentDataply {
       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,
@@ -10035,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 }));
@@ -10057,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 = [];
@@ -10073,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];
@@ -10111,17 +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 (let i = 0, len = pks.length; i < len; i++) {
       const pk = pks[i];
-      const doc = await this.api.getDocument(pk, tx);
+      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];
@@ -10133,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) {
@@ -10155,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 };
@@ -10170,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));
   }
@@ -10184,21 +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 (let i = 0, len = pks.length; i < len; i++) {
         const pk = pks[i];
-        const doc = await this.api.getDocument(pk, tx2);
+        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;
@@ -10210,8 +10228,8 @@ 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.length;
     }, tx));
@@ -10224,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(", ")}`);
@@ -10241,7 +10259,7 @@ var DocumentDataply = class _DocumentDataply {
       orderBy: orderByField
     } = options;
     const self = this;
-    const stream = this.api.streamWithDefault(async function* (tx2) {
+    const stream = this.streamWithDefault(async function* (tx2) {
       const keys = await self.getKeys(query, orderByField, sortOrder);
       const totalKeys = keys.length;
       if (totalKeys === 0) return;
@@ -10253,42 +10271,73 @@ var DocumentDataply = class _DocumentDataply {
       if (selectivity) {
         selectivity.rollback();
       }
-      let currentChunkSize = self.api.options.pageSize;
+      let currentChunkSize = self.options.pageSize;
       if (!isDriverOrderByField && orderByField) {
+        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;
         let nextChunkPromise = null;
         if (i < totalKeys) {
           const endIdx = Math.min(i + currentChunkSize, totalKeys);
           const chunkKeys = keys.subarray(i, endIdx);
-          nextChunkPromise = self.api.selectMany(chunkKeys, false, tx2);
+          nextChunkPromise = self.selectMany(chunkKeys, false, tx2);
           i = endIdx;
         }
         while (nextChunkPromise) {
           const rawResults = await nextChunkPromise;
           nextChunkPromise = null;
-          const freeMem = os.freemem();
-          const safeLimit = freeMem * 0.2;
+          const { verySmallChunkSize, smallChunkSize } = self.getFreeMemoryChunkSize();
           if (i < totalKeys) {
             const endIdx = Math.min(i + currentChunkSize, totalKeys);
             const chunkKeys = keys.subarray(i, endIdx);
-            nextChunkPromise = self.api.selectMany(chunkKeys, false, tx2);
+            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) {
-              results.push(JSON.parse(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);
+              }
             }
           }
           if (chunkTotalSize > 0) {
-            if (chunkTotalSize < safeLimit * 0.05) currentChunkSize = currentChunkSize * 2;
-            else if (chunkTotalSize > safeLimit * 0.3) currentChunkSize = Math.max(Math.floor(currentChunkSize / 2), 20);
+            if (chunkTotalSize < verySmallChunkSize) {
+              currentChunkSize = currentChunkSize * 2;
+            } else if (chunkTotalSize > smallChunkSize) {
+              currentChunkSize = Math.max(Math.floor(currentChunkSize / 2), 20);
+            }
           }
         }
-        results.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;
@@ -10296,7 +10345,7 @@ var DocumentDataply = class _DocumentDataply {
         });
         const start = offset;
         const end = limit === Infinity ? void 0 : start + limit;
-        const limitedResults = results.slice(start, end);
+        const limitedResults = finalDocs.slice(start, end);
         for (let j = 0, len = limitedResults.length; j < len; j++) {
           yield limitedResults[j];
         }
@@ -10307,18 +10356,17 @@ var DocumentDataply = class _DocumentDataply {
         if (yieldedCount < limit && i < totalKeys) {
           const endIdx = Math.min(i + currentChunkSize, totalKeys);
           const chunkKeys = keys.subarray(i, endIdx);
-          nextChunkPromise = self.api.selectMany(chunkKeys, false, tx2);
+          nextChunkPromise = self.selectMany(chunkKeys, false, tx2);
           i = endIdx;
         }
         while (nextChunkPromise) {
           const rawResults = await nextChunkPromise;
           nextChunkPromise = null;
-          const freeMem = os.freemem();
-          const safeLimit = freeMem * 0.2;
+          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.api.selectMany(chunkKeys, false, tx2);
+            nextChunkPromise = self.selectMany(chunkKeys, false, tx2);
             i = endIdx;
           }
           let chunkTotalSize = 0;
@@ -10333,8 +10381,11 @@ var DocumentDataply = class _DocumentDataply {
             }
           }
           if (chunkTotalSize > 0) {
-            if (chunkTotalSize < safeLimit * 0.05) currentChunkSize = currentChunkSize * 2;
-            else if (chunkTotalSize > safeLimit * 0.3) currentChunkSize = Math.max(Math.floor(currentChunkSize / 2), 20);
+            if (chunkTotalSize < verySmallChunkSize) {
+              currentChunkSize = currentChunkSize * 2;
+            } else if (chunkTotalSize > smallChunkSize) {
+              currentChunkSize = Math.max(Math.floor(currentChunkSize / 2), 20);
+            }
           }
         }
       }
@@ -10348,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.1",
+  "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.1"
+    "dataply": "^0.0.21"
   },
   "devDependencies": {
     "@types/jest": "^30.0.0",