document-dataply 0.0.6 → 0.0.7-alpha.1

package/dist/cjs/index.js

@@ -1757,6 +1757,39 @@ var require_cjs = __commonJS({
         }
         return true;
       }
+      /**
+       * Inserts a key-value pair into an already-cloned leaf node in-place.
+       * Unlike _insertAtLeaf, this does NOT clone or update the node via MVCC.
+       * Used by batchInsert to batch multiple insertions with a single clone/update.
+       * @returns true if the leaf was modified, false if the key already exists.
+       */
+      _insertValueIntoLeaf(leaf, key, value) {
+        if (leaf.values.length) {
+          for (let i = 0, len = leaf.values.length; i < len; i++) {
+            const nValue = leaf.values[i];
+            if (this.comparator.isSame(value, nValue)) {
+              if (leaf.keys[i].includes(key)) {
+                return false;
+              }
+              leaf.keys[i].push(key);
+              return true;
+            } else if (this.comparator.isLower(value, nValue)) {
+              leaf.values.splice(i, 0, value);
+              leaf.keys.splice(i, 0, [key]);
+              return true;
+            } else if (i + 1 === leaf.values.length) {
+              leaf.values.push(value);
+              leaf.keys.push([key]);
+              return true;
+            }
+          }
+        } else {
+          leaf.values = [value];
+          leaf.keys = [[key]];
+          return true;
+        }
+        return false;
+      }
       _cloneNode(node) {
         return JSON.parse(JSON.stringify(node));
       }
@@ -2213,17 +2246,24 @@ var require_cjs = __commonJS({
         }
         return void 0;
       }
-      *keysStream(condition, filterValues, limit, order = "asc") {
-        const stream = this.whereStream(condition, limit, order);
+      *keysStream(condition, options) {
+        const { filterValues, limit, order = "asc" } = options ?? {};
+        const stream = this.whereStream(condition, options);
         const intersection = filterValues && filterValues.size > 0 ? filterValues : null;
+        let count = 0;
         for (const [key] of stream) {
           if (intersection && !intersection.has(key)) {
             continue;
           }
           yield key;
+          count++;
+          if (limit !== void 0 && count >= limit) {
+            break;
+          }
         }
       }
-      *whereStream(condition, limit, order = "asc") {
+      *whereStream(condition, options) {
+        const { filterValues, limit, order = "asc" } = options ?? {};
         const driverKey = this.getDriverKey(condition);
         if (!driverKey) return;
         const value = condition[driverKey];
@@ -2246,8 +2286,12 @@ var require_cjs = __commonJS({
           earlyTerminate
         );
         let count = 0;
+        const intersection = filterValues && filterValues.size > 0 ? filterValues : null;
         for (const pair of generator) {
           const [k, v] = pair;
+          if (intersection && !intersection.has(k)) {
+            continue;
+          }
           let isMatch = true;
           for (const key in condition) {
             if (key === driverKey) continue;
@@ -2267,16 +2311,16 @@ var require_cjs = __commonJS({
           }
         }
       }
-      keys(condition, filterValues, order = "asc") {
+      keys(condition, options) {
         const set = /* @__PURE__ */ new Set();
-        for (const key of this.keysStream(condition, filterValues, void 0, order)) {
+        for (const key of this.keysStream(condition, options)) {
           set.add(key);
         }
         return set;
       }
-      where(condition, order = "asc") {
+      where(condition, options) {
         const map = /* @__PURE__ */ new Map();
-        for (const [key, value] of this.whereStream(condition, void 0, order)) {
+        for (const [key, value] of this.whereStream(condition, options)) {
           map.set(key, value);
         }
         return map;
@@ -2304,6 +2348,50 @@ var require_cjs = __commonJS({
           this._insertInParent(before, after.values[0], after);
         }
       }
+      batchInsert(entries) {
+        if (entries.length === 0) return;
+        const sorted = [...entries].sort((a, b) => this.comparator.asc(a[1], b[1]));
+        let currentLeaf = null;
+        let modified = false;
+        for (const [key, value] of sorted) {
+          const targetLeaf = this.insertableNode(value);
+          if (currentLeaf !== null && currentLeaf.id === targetLeaf.id) {
+          } else {
+            if (currentLeaf !== null && modified) {
+              this._updateNode(currentLeaf);
+            }
+            currentLeaf = this._cloneNode(targetLeaf);
+            modified = false;
+          }
+          const changed = this._insertValueIntoLeaf(currentLeaf, key, value);
+          modified = modified || changed;
+          if (currentLeaf.values.length === this.order) {
+            this._updateNode(currentLeaf);
+            let after = this._createNode(
+              true,
+              [],
+              [],
+              currentLeaf.parent,
+              null,
+              null
+            );
+            const mid = Math.ceil(this.order / 2) - 1;
+            after = this._cloneNode(after);
+            after.values = currentLeaf.values.slice(mid + 1);
+            after.keys = currentLeaf.keys.slice(mid + 1);
+            currentLeaf.values = currentLeaf.values.slice(0, mid + 1);
+            currentLeaf.keys = currentLeaf.keys.slice(0, mid + 1);
+            this._updateNode(currentLeaf);
+            this._updateNode(after);
+            this._insertInParent(currentLeaf, after.values[0], after);
+            currentLeaf = null;
+            modified = false;
+          }
+        }
+        if (currentLeaf !== null && modified) {
+          this._updateNode(currentLeaf);
+        }
+      }
       _deleteEntry(node, key) {
         if (!node.leaf) {
           let keyIndex = -1;
@@ -2655,6 +2743,14 @@ var require_cjs = __commonJS({
           throw new Error(`Transaction failed: ${result.error || "Commit failed due to conflict"}`);
         }
       }
+      batchInsert(entries) {
+        const tx = this.createTransaction();
+        tx.batchInsert(entries);
+        const result = tx.commit();
+        if (!result.success) {
+          throw new Error(`Transaction failed: ${result.error || "Commit failed due to conflict"}`);
+        }
+      }
     };
     var Ryoiki22 = class _Ryoiki2 {
       readings;
@@ -3280,17 +3376,24 @@ var require_cjs = __commonJS({
         }
         return void 0;
       }
-      async *keysStream(condition, filterValues, limit, order = "asc") {
-        const stream = this.whereStream(condition, limit, order);
+      async *keysStream(condition, options) {
+        const { filterValues, limit, order = "asc" } = options ?? {};
+        const stream = this.whereStream(condition, options);
         const intersection = filterValues && filterValues.size > 0 ? filterValues : null;
+        let count = 0;
         for await (const [key] of stream) {
           if (intersection && !intersection.has(key)) {
             continue;
           }
           yield key;
+          count++;
+          if (limit !== void 0 && count >= limit) {
+            break;
+          }
         }
       }
-      async *whereStream(condition, limit, order = "asc") {
+      async *whereStream(condition, options) {
+        const { filterValues, limit, order = "asc" } = options ?? {};
         const driverKey = this.getDriverKey(condition);
         if (!driverKey) return;
         const value = condition[driverKey];
@@ -3313,8 +3416,12 @@ var require_cjs = __commonJS({
           earlyTerminate
         );
         let count = 0;
+        const intersection = filterValues && filterValues.size > 0 ? filterValues : null;
         for await (const pair of generator) {
           const [k, v] = pair;
+          if (intersection && !intersection.has(k)) {
+            continue;
+          }
           let isMatch = true;
           for (const key in condition) {
             if (key === driverKey) continue;
@@ -3334,16 +3441,16 @@ var require_cjs = __commonJS({
           }
         }
       }
-      async keys(condition, filterValues, order = "asc") {
+      async keys(condition, options) {
         const set = /* @__PURE__ */ new Set();
-        for await (const key of this.keysStream(condition, filterValues, void 0, order)) {
+        for await (const key of this.keysStream(condition, options)) {
           set.add(key);
         }
         return set;
       }
-      async where(condition, order = "asc") {
+      async where(condition, options) {
         const map = /* @__PURE__ */ new Map();
-        for await (const [key, value] of this.whereStream(condition, void 0, order)) {
+        for await (const [key, value] of this.whereStream(condition, options)) {
           map.set(key, value);
         }
         return map;
@@ -3373,6 +3480,52 @@ var require_cjs = __commonJS({
           }
         });
       }
+      async batchInsert(entries) {
+        if (entries.length === 0) return;
+        return this.writeLock(0, async () => {
+          const sorted = [...entries].sort((a, b) => this.comparator.asc(a[1], b[1]));
+          let currentLeaf = null;
+          let modified = false;
+          for (const [key, value] of sorted) {
+            const targetLeaf = await this.insertableNode(value);
+            if (currentLeaf !== null && currentLeaf.id === targetLeaf.id) {
+            } else {
+              if (currentLeaf !== null && modified) {
+                await this._updateNode(currentLeaf);
+              }
+              currentLeaf = this._cloneNode(targetLeaf);
+              modified = false;
+            }
+            const changed = this._insertValueIntoLeaf(currentLeaf, key, value);
+            modified = modified || changed;
+            if (currentLeaf.values.length === this.order) {
+              await this._updateNode(currentLeaf);
+              let after = await this._createNode(
+                true,
+                [],
+                [],
+                currentLeaf.parent,
+                null,
+                null
+              );
+              const mid = Math.ceil(this.order / 2) - 1;
+              after = this._cloneNode(after);
+              after.values = currentLeaf.values.slice(mid + 1);
+              after.keys = currentLeaf.keys.slice(mid + 1);
+              currentLeaf.values = currentLeaf.values.slice(0, mid + 1);
+              currentLeaf.keys = currentLeaf.keys.slice(0, mid + 1);
+              await this._updateNode(currentLeaf);
+              await this._updateNode(after);
+              await this._insertInParent(currentLeaf, after.values[0], after);
+              currentLeaf = null;
+              modified = false;
+            }
+          }
+          if (currentLeaf !== null && modified) {
+            await this._updateNode(currentLeaf);
+          }
+        });
+      }
       async _deleteEntry(node, key) {
         if (!node.leaf) {
           let keyIndex = -1;
@@ -3730,6 +3883,16 @@ var require_cjs = __commonJS({
           }
         });
       }
+      async batchInsert(entries) {
+        return this.writeLock(1, async () => {
+          const tx = await this.createTransaction();
+          await tx.batchInsert(entries);
+          const result = await tx.commit();
+          if (!result.success) {
+            throw new Error(`Transaction failed: ${result.error || "Commit failed due to conflict"}`);
+          }
+        });
+      }
     };
     var SerializeStrategy = class {
       order;
@@ -8704,6 +8867,7 @@ var require_cjs = __commonJS({
         if (!this.factory.isDataPage(lastInsertDataPage)) {
           throw new Error(`Last insert page is not data page`);
         }
+        const batchInsertData = [];
         for (const data of dataList) {
           const pk = ++lastPk;
           const willRowSize = this.getRequiredRowSize(data);
@@ -8748,9 +8912,10 @@ var require_cjs = __commonJS({
               await this.pfs.setPage(lastInsertDataPageId, lastInsertDataPage, tx);
             }
           }
-          await btx.insert(this.getRID(), pk);
+          batchInsertData.push([this.getRID(), pk]);
           pks.push(pk);
         }
+        await btx.batchInsert(batchInsertData);
         tx.__markBPTreeDirty();
         const freshMetadataPage = await this.pfs.getMetadata(tx);
         this.metadataPageManager.setLastInsertPageId(freshMetadataPage, lastInsertDataPageId);
@@ -9953,6 +10118,45 @@ var BinaryHeap = class {
   }
 };
 
+// src/utils/tokenizer.ts
+function whitespaceTokenize(text) {
+  if (typeof text !== "string") return [];
+  return Array.from(new Set(text.split(/\s+/).filter(Boolean)));
+}
+function ngramTokenize(text, gramSize) {
+  if (typeof text !== "string") return [];
+  const tokens = /* @__PURE__ */ new Set();
+  const words = text.split(/\s+/).filter(Boolean);
+  for (const word of words) {
+    if (word.length < gramSize) {
+      if (word.length > 0) tokens.add(word);
+      continue;
+    }
+    for (let i = 0; i <= word.length - gramSize; i++) {
+      tokens.add(word.slice(i, i + gramSize));
+    }
+  }
+  return Array.from(tokens);
+}
+function tokenize(text, options) {
+  if (options.tokenizer === "whitespace") {
+    return whitespaceTokenize(text);
+  }
+  if (options.tokenizer === "ngram") {
+    return ngramTokenize(text, options.gramSize);
+  }
+  return [];
+}
+
+// src/utils/hash.ts
+function fastStringHash(str) {
+  let hash = 0;
+  for (let i = 0; i < str.length; i++) {
+    hash = (hash << 5) - hash + str.charCodeAt(i) | 0;
+  }
+  return hash >>> 0;
+}
+
 // src/core/documentAPI.ts
 var DocumentDataplyAPI = class extends import_dataply3.DataplyAPI {
   indices = {};
@@ -10008,7 +10212,7 @@ var DocumentDataplyAPI = class extends import_dataply3.DataplyAPI {
         } else {
           const [_pk, isMetaBackfillEnabled] = existingIndex;
           if (isBackfillEnabled && !isMetaBackfillEnabled) {
-            metadata.indices[field][1] = true;
+            metadata.indices[field][1] = isBackfillEnabled;
             isMetadataChanged = true;
             backfillTargets.push(field);
           } else if (!isBackfillEnabled && isMetaBackfillEnabled) {
@@ -10111,12 +10315,23 @@ var DocumentDataplyAPI = class extends import_dataply3.DataplyAPI {
           }
           const v = flatDoc[field];
           const btx = fieldTxMap[field];
-          const entry = { k, v };
-          await btx.insert(k, entry);
-          if (!fieldMap.has(btx)) {
-            fieldMap.set(btx, []);
+          const indexConfig = metadata.indices[field]?.[1];
+          const isFts = typeof indexConfig === "object" && indexConfig?.type === "fts" && typeof v === "string";
+          let tokens = [v];
+          if (isFts) {
+            tokens = tokenize(v, indexConfig);
+          }
+          const batchInsertData = [];
+          for (const token of tokens) {
+            const keyToInsert = isFts ? this.getTokenKey(k, token) : k;
+            const entry = { k, v: token };
+            batchInsertData.push([keyToInsert, entry]);
+            if (!fieldMap.has(btx)) {
+              fieldMap.set(btx, []);
+            }
+            fieldMap.get(btx).push({ k: keyToInsert, v: entry });
           }
-          fieldMap.get(btx).push(entry);
+          await btx.batchInsert(batchInsertData);
         }
         backfilledCount++;
       }
@@ -10210,6 +10425,11 @@ var DocumentDataplyAPI = class extends import_dataply3.DataplyAPI {
   async updateDocumentInnerMetadata(metadata, tx) {
     await this.update(1, JSON.stringify(metadata), tx);
   }
+  /**
+   * Transforms a query object into a verbose query object
+   * @param query The query object to transform
+   * @returns The verbose query object
+   */
   verboseQuery(query) {
     const result = {};
     for (const field in query) {
@@ -10223,7 +10443,12 @@ var DocumentDataplyAPI = class extends import_dataply3.DataplyAPI {
           const before = operator;
           const after = this.operatorConverters[before];
           const v = conditions[before];
-          if (!after) continue;
+          if (!after) {
+            if (before === "match") {
+              newConditions[before] = v;
+            }
+            continue;
+          }
           if (before === "or" && Array.isArray(v)) {
             newConditions[after] = v.map((val) => ({ v: val }));
           } else if (before === "like") {
@@ -10245,12 +10470,26 @@ var DocumentDataplyAPI = class extends import_dataply3.DataplyAPI {
    */
   async getSelectivityCandidate(query, orderByField) {
     const candidates = [];
+    const metadata = await this.getDocumentInnerMetadata(this.txContext.get());
     for (const field in query) {
       const tree = this.trees.get(field);
       if (!tree) continue;
       const condition = query[field];
       const treeTx = await tree.createTransaction();
-      candidates.push({ tree: treeTx, condition, field });
+      const indexConfig = metadata.indices[field]?.[1];
+      let isFtsMatch = false;
+      let matchTokens;
+      if (typeof indexConfig === "object" && indexConfig?.type === "fts" && condition.match) {
+        isFtsMatch = true;
+        matchTokens = tokenize(condition.match, indexConfig);
+      }
+      candidates.push({
+        tree: treeTx,
+        condition,
+        field,
+        isFtsMatch,
+        matchTokens
+      });
     }
     const rollback = () => {
       for (const { tree } of candidates) {
@@ -10293,36 +10532,69 @@ var DocumentDataplyAPI = class extends import_dataply3.DataplyAPI {
     const smallChunkSize = safeLimit * 0.3;
     return { verySmallChunkSize, smallChunkSize };
   }
+  getTokenKey(pk, token) {
+    return fastStringHash(pk + ":" + token);
+  }
+  async applyCandidateByFTS(candidate, matchedTokens, filterValues, order) {
+    const keys = /* @__PURE__ */ new Set();
+    for (const token of matchedTokens) {
+      const pairs = await candidate.tree.where(
+        { primaryEqual: { v: token } },
+        { order }
+      );
+      for (const c of pairs.values()) {
+        if (!c || typeof c.k !== "number") continue;
+        const dpk = c.k;
+        if (filterValues === void 0 || filterValues.has(dpk)) {
+          keys.add(dpk);
+        }
+      }
+    }
+    return keys;
+  }
+  /**
+   * 특정 인덱스 후보를 조회하여 PK 집합을 필터링합니다.
+   */
+  async applyCandidate(candidate, filterValues, order) {
+    return await candidate.tree.keys(
+      candidate.condition,
+      {
+        filterValues,
+        order
+      }
+    );
+  }
   /**
-   * Get Primary Keys based on query and index selection.
-   * Internal common method to unify query optimization.
+   * 쿼리와 인덱스 선택을 기반으로 기본 키(Primary Keys)를 가져옵니다.
+   * 쿼리 최적화를 통합하기 위한 내부 공통 메서드입니다.
    */
   async getKeys(query, orderBy, sortOrder = "asc") {
     const isQueryEmpty = Object.keys(query).length === 0;
     const normalizedQuery = isQueryEmpty ? { _id: { gte: 0 } } : query;
-    const verbose = this.verboseQuery(normalizedQuery);
     const selectivity = await this.getSelectivityCandidate(
-      verbose,
+      this.verboseQuery(normalizedQuery),
       orderBy
     );
     if (!selectivity) return new Float64Array(0);
     const { driver, others, rollback } = selectivity;
-    const isDriverOrderByField = orderBy === void 0 || driver.field === orderBy;
-    if (isDriverOrderByField) {
-      let keysSet = await driver.tree.keys(driver.condition, void 0, sortOrder);
-      for (const { tree, condition } of others) {
-        keysSet = await tree.keys(condition, keysSet, sortOrder);
-      }
-      rollback();
-      return new Float64Array(keysSet);
-    } else {
-      let keysSet = await driver.tree.keys(driver.condition, void 0);
-      for (const { tree, condition } of others) {
-        keysSet = await tree.keys(condition, keysSet);
+    const useIndexOrder = orderBy === void 0 || driver.field === orderBy;
+    const candidates = [driver, ...others];
+    let keys = void 0;
+    for (const candidate of candidates) {
+      const currentOrder = useIndexOrder ? sortOrder : void 0;
+      if (candidate.isFtsMatch && candidate.matchTokens && candidate.matchTokens.length > 0) {
+        keys = await this.applyCandidateByFTS(
+          candidate,
+          candidate.matchTokens,
+          keys,
+          currentOrder
+        );
+      } else {
+        keys = await this.applyCandidate(candidate, keys, currentOrder);
       }
-      rollback();
-      return new Float64Array(keysSet);
     }
+    rollback();
+    return new Float64Array(Array.from(keys || []));
   }
   async insertDocumentInternal(document, tx) {
     const metadata = await this.getDocumentInnerMetadata(tx);
@@ -10346,15 +10618,25 @@ var DocumentDataplyAPI = class extends import_dataply3.DataplyAPI {
    */
   async insertSingleDocument(document, tx) {
     return this.writeLock(() => this.runWithDefault(async (tx2) => {
-      const { pk, document: dataplyDocument } = await this.insertDocumentInternal(document, tx2);
+      const { pk: dpk, document: dataplyDocument } = await this.insertDocumentInternal(document, tx2);
+      const metadata = await this.getDocumentInnerMetadata(tx2);
       const flattenDocument = this.flattenDocument(dataplyDocument);
       for (const field in flattenDocument) {
         const tree = this.trees.get(field);
         if (!tree) continue;
         const v = flattenDocument[field];
-        const [error] = await catchPromise(tree.insert(pk, { k: pk, v }));
-        if (error) {
-          console.error(`BPTree indexing failed for field: ${field}`, error);
+        const indexConfig = metadata.indices[field]?.[1];
+        let tokens = [v];
+        const isFts = typeof indexConfig === "object" && indexConfig?.type === "fts" && typeof v === "string";
+        if (isFts) {
+          tokens = tokenize(v, indexConfig);
+        }
+        for (const token of tokens) {
+          const keyToInsert = isFts ? this.getTokenKey(dpk, token) : dpk;
+          const [error] = await catchPromise(tree.insert(keyToInsert, { k: dpk, v: token }));
+          if (error) {
+            throw error;
+          }
         }
       }
       return dataplyDocument._id;
@@ -10392,14 +10674,25 @@ var DocumentDataplyAPI = class extends import_dataply3.DataplyAPI {
       }
       for (const [field, tree] of this.trees) {
         const treeTx = await tree.createTransaction();
+        const indexConfig = metadata.indices[field]?.[1];
+        const batchInsertData = [];
         for (let i = 0, len = flattenedData.length; i < len; i++) {
           const item = flattenedData[i];
           const v = item.data[field];
           if (v === void 0) continue;
-          const [error] = await catchPromise(treeTx.insert(item.pk, { k: item.pk, v }));
-          if (error) {
-            console.error(`BPTree indexing failed for field: ${field}`, error);
+          const isFts = typeof indexConfig === "object" && indexConfig?.type === "fts" && typeof v === "string";
+          let tokens = [v];
+          if (isFts) {
+            tokens = tokenize(v, indexConfig);
           }
+          for (const token of tokens) {
+            const keyToInsert = isFts ? this.getTokenKey(item.pk, token) : item.pk;
+            batchInsertData.push([keyToInsert, { k: item.pk, v: token }]);
+          }
+        }
+        const [error] = await catchPromise(treeTx.batchInsert(batchInsertData));
+        if (error) {
+          throw error;
         }
         const res = await treeTx.commit();
         if (!res.success) {
@@ -10431,15 +10724,34 @@ var DocumentDataplyAPI = class extends import_dataply3.DataplyAPI {
       const updatedDoc = computeUpdatedDoc(doc);
       const oldFlatDoc = this.flattenDocument(doc);
       const newFlatDoc = this.flattenDocument(updatedDoc);
+      const metadata = await this.getDocumentInnerMetadata(tx);
       for (const [field, treeTx] of treeTxs) {
         const oldV = oldFlatDoc[field];
         const newV = newFlatDoc[field];
         if (oldV === newV) continue;
+        const indexConfig = metadata.indices[field]?.[1];
+        const isFts = typeof indexConfig === "object" && indexConfig?.type === "fts";
         if (field in oldFlatDoc) {
-          await treeTx.delete(pk, { k: pk, v: oldV });
+          let oldTokens = [oldV];
+          if (isFts && typeof oldV === "string") {
+            oldTokens = tokenize(oldV, indexConfig);
+          }
+          for (const oldToken of oldTokens) {
+            const keyToDelete = isFts ? this.getTokenKey(pk, oldToken) : pk;
+            await treeTx.delete(keyToDelete, { k: pk, v: oldToken });
+          }
         }
         if (field in newFlatDoc) {
-          await treeTx.insert(pk, { k: pk, v: newV });
+          let newTokens = [newV];
+          if (isFts && typeof newV === "string") {
+            newTokens = tokenize(newV, indexConfig);
+          }
+          const batchInsertData = [];
+          for (const newToken of newTokens) {
+            const keyToInsert = isFts ? this.getTokenKey(pk, newToken) : pk;
+            batchInsertData.push([keyToInsert, { k: pk, v: newToken }]);
+          }
+          await treeTx.batchInsert(batchInsertData);
         }
       }
       await this.update(pk, JSON.stringify(updatedDoc), tx);
@@ -10503,10 +10815,20 @@ var DocumentDataplyAPI = class extends import_dataply3.DataplyAPI {
         const doc = await this.getDocument(pk, tx2);
         if (!doc) continue;
         const flatDoc = this.flattenDocument(doc);
+        const metadata = await this.getDocumentInnerMetadata(tx2);
         for (const [field, tree] of this.trees) {
           const v = flatDoc[field];
           if (v === void 0) continue;
-          await tree.delete(pk, { k: pk, v });
+          const indexConfig = metadata.indices[field]?.[1];
+          const isFts = typeof indexConfig === "object" && indexConfig?.type === "fts" && typeof v === "string";
+          let tokens = [v];
+          if (isFts) {
+            tokens = tokenize(v, indexConfig);
+          }
+          for (const token of tokens) {
+            const keyToDelete = isFts ? this.getTokenKey(pk, token) : pk;
+            await tree.delete(keyToDelete, { k: pk, v: token });
+          }
         }
         await super.delete(pk, true, tx2);
         deletedCount++;
@@ -10526,6 +10848,63 @@ var DocumentDataplyAPI = class extends import_dataply3.DataplyAPI {
       return pks.length;
     }, tx));
   }
+  /**
+   * FTS 조건에 대해 문서가 유효한지 검증합니다.
+   */
+  verifyFts(doc, ftsConditions) {
+    for (const { field, matchTokens } of ftsConditions) {
+      const docValue = this.flattenDocument(doc)[field];
+      if (typeof docValue !== "string") return false;
+      for (const token of matchTokens) {
+        if (!docValue.includes(token)) return false;
+      }
+    }
+    return true;
+  }
+  /**
+   * 메모리 기반으로 청크 크기를 동적 조절합니다.
+   */
+  adjustChunkSize(currentChunkSize, chunkTotalSize) {
+    if (chunkTotalSize <= 0) return currentChunkSize;
+    const { verySmallChunkSize, smallChunkSize } = this.getFreeMemoryChunkSize();
+    if (chunkTotalSize < verySmallChunkSize) return currentChunkSize * 2;
+    if (chunkTotalSize > smallChunkSize) return Math.max(Math.floor(currentChunkSize / 2), 20);
+    return currentChunkSize;
+  }
+  /**
+   * Prefetch 방식으로 키 배열을 청크 단위로 조회하여 문서를 순회합니다.
+   * FTS 검증을 통과한 문서만 yield 합니다.
+   */
+  async *processChunkedKeys(keys, startIdx, initialChunkSize, ftsConditions, tx) {
+    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 chunkTotalSize = 0;
+      for (let j = 0, len = rawResults.length; j < len; j++) {
+        const s = rawResults[j];
+        if (!s) continue;
+        const doc = JSON.parse(s);
+        chunkTotalSize += s.length * 2;
+        if (!this.verifyFts(doc, ftsConditions)) continue;
+        yield { doc, rawSize: s.length * 2 };
+      }
+      currentChunkSize = this.adjustChunkSize(currentChunkSize, chunkTotalSize);
+    }
+  }
   /**
    * Select documents from the database
    * @param query The query to use (only indexed fields + _id allowed)
@@ -10552,80 +10931,57 @@ var DocumentDataplyAPI = class extends import_dataply3.DataplyAPI {
     } = options;
     const self = this;
     const stream = this.streamWithDefault(async function* (tx2) {
+      const metadata = await self.getDocumentInnerMetadata(tx2);
+      const ftsConditions = [];
+      for (const field in query) {
+        const q = query[field];
+        if (q && typeof q === "object" && "match" in q && typeof q.match === "string") {
+          const indexConfig = metadata.indices[field]?.[1];
+          if (typeof indexConfig === "object" && indexConfig?.type === "fts") {
+            ftsConditions.push({ field, matchTokens: tokenize(q.match, indexConfig) });
+          }
+        }
+      }
       const keys = await self.getKeys(query, orderByField, sortOrder);
-      const totalKeys = keys.length;
-      if (totalKeys === 0) return;
+      if (keys.length === 0) return;
       const selectivity = await self.getSelectivityCandidate(
         self.verboseQuery(query),
         orderByField
       );
       const isDriverOrderByField = orderByField === void 0 || selectivity && selectivity.driver.field === orderByField;
-      if (selectivity) {
-        selectivity.rollback();
-      }
-      let currentChunkSize = self.options.pageSize;
+      if (selectivity) selectivity.rollback();
       if (!isDriverOrderByField && orderByField) {
         const topK = limit === Infinity ? Infinity : offset + limit;
         let heap = null;
         if (topK !== Infinity) {
-          const heapComparator = (a, b) => {
+          heap = new BinaryHeap((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.selectMany(chunkKeys, false, tx2);
-          i = endIdx;
-        }
-        while (nextChunkPromise) {
-          const rawResults = await nextChunkPromise;
-          nextChunkPromise = null;
-          const { verySmallChunkSize, smallChunkSize } = self.getFreeMemoryChunkSize();
-          if (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) {
-              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);
+        for await (const { doc } of self.processChunkedKeys(
+          keys,
+          0,
+          self.options.pageSize,
+          ftsConditions,
+          tx2
+        )) {
+          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;
+                if (sortOrder === "asc" ? cmp < 0 : cmp > 0) heap.replace(doc);
               }
             }
-          }
-          if (chunkTotalSize > 0) {
-            if (chunkTotalSize < verySmallChunkSize) {
-              currentChunkSize = currentChunkSize * 2;
-            } else if (chunkTotalSize > smallChunkSize) {
-              currentChunkSize = Math.max(Math.floor(currentChunkSize / 2), 20);
-            }
+          } else {
+            results.push(doc);
           }
         }
         const finalDocs = heap ? heap.toArray() : results;
@@ -10635,50 +10991,23 @@ var DocumentDataplyAPI = class extends import_dataply3.DataplyAPI {
           const cmp = aVal < bVal ? -1 : aVal > bVal ? 1 : 0;
           return sortOrder === "asc" ? cmp : -cmp;
         });
-        const start = offset;
-        const end = limit === Infinity ? void 0 : start + limit;
-        const limitedResults = finalDocs.slice(start, end);
+        const end = limit === Infinity ? void 0 : offset + limit;
+        const limitedResults = finalDocs.slice(offset, end);
         for (let j = 0, len = limitedResults.length; j < len; j++) {
           yield limitedResults[j];
         }
       } else {
         let yieldedCount = 0;
-        let i = offset;
-        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;
-            }
-          }
-          if (chunkTotalSize > 0) {
-            if (chunkTotalSize < verySmallChunkSize) {
-              currentChunkSize = currentChunkSize * 2;
-            } else if (chunkTotalSize > smallChunkSize) {
-              currentChunkSize = Math.max(Math.floor(currentChunkSize / 2), 20);
-            }
-          }
+        for await (const { doc } of self.processChunkedKeys(
+          keys,
+          offset,
+          self.options.pageSize,
+          ftsConditions,
+          tx2
+        )) {
+          if (yieldedCount >= limit) break;
+          yield doc;
+          yieldedCount++;
         }
       }
     }, tx);

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

@@ -35,6 +35,11 @@ export declare class DocumentDataplyAPI<T extends DocumentJSON, IC extends Index
     getDocumentMetadata(tx: Transaction): Promise<DocumentDataplyMetadata>;
     getDocumentInnerMetadata(tx: Transaction): Promise<DocumentDataplyInnerMetadata>;
     updateDocumentInnerMetadata(metadata: DocumentDataplyInnerMetadata, tx: Transaction): Promise<void>;
+    /**
+     * Transforms a query object into a verbose query object
+     * @param query The query object to transform
+     * @returns The verbose query object
+     */
     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
@@ -47,11 +52,15 @@ export declare class DocumentDataplyAPI<T extends DocumentJSON, IC extends Index
             tree: BPTreeAsync<number, V>;
             condition: Partial<DocumentDataplyCondition<U>>;
             field: string;
+            isFtsMatch?: boolean;
+            matchTokens?: string[];
         };
         others: {
             tree: BPTreeAsync<number, V>;
             condition: Partial<DocumentDataplyCondition<U>>;
             field: string;
+            isFtsMatch?: boolean;
+            matchTokens?: string[];
         }[];
         rollback: () => void;
     } | null>;
@@ -63,9 +72,15 @@ export declare class DocumentDataplyAPI<T extends DocumentJSON, IC extends Index
         verySmallChunkSize: number;
         smallChunkSize: number;
     };
+    private getTokenKey;
+    private applyCandidateByFTS;
     /**
-     * Get Primary Keys based on query and index selection.
-     * Internal common method to unify query optimization.
+     * 특정 인덱스 후보를 조회하여 PK 집합을 필터링합니다.
+     */
+    private applyCandidate;
+    /**
+     * 쿼리와 인덱스 선택을 기반으로 기본 키(Primary Keys)를 가져옵니다.
+     * 쿼리 최적화를 통합하기 위한 내부 공통 메서드입니다.
      */
     getKeys(query: Partial<DocumentDataplyIndexedQuery<T, IC>>, orderBy?: keyof IC | '_id', sortOrder?: 'asc' | 'desc'): Promise<Float64Array>;
     private insertDocumentInternal;
@@ -121,6 +136,19 @@ export declare class DocumentDataplyAPI<T extends DocumentJSON, IC extends Index
      * @returns The number of documents that match the query
      */
     countDocuments(query: Partial<DocumentDataplyIndexedQuery<T, IC>>, tx?: Transaction): Promise<number>;
+    /**
+     * FTS 조건에 대해 문서가 유효한지 검증합니다.
+     */
+    private verifyFts;
+    /**
+     * 메모리 기반으로 청크 크기를 동적 조절합니다.
+     */
+    private adjustChunkSize;
+    /**
+     * Prefetch 방식으로 키 배열을 청크 단위로 조회하여 문서를 순회합니다.
+     * FTS 검증을 통과한 문서만 yield 합니다.
+     */
+    private processChunkedKeys;
     /**
      * Select documents from the database
      * @param query The query to use (only indexed fields + _id allowed)

package/dist/types/types/index.d.ts

@@ -16,7 +16,17 @@ export interface DocumentDataplyInnerMetadata {
     updatedAt: number;
     lastId: number;
     indices: {
-        [key: string]: [number, boolean];
+        [key: string]: [
+            number,
+            boolean | {
+                type: 'fts';
+                tokenizer: 'whitespace';
+            } | {
+                type: 'fts';
+                tokenizer: 'ngram';
+                gramSize: number;
+            }
+        ];
     };
 }
 export interface DocumentDataplyMetadata {
@@ -46,6 +56,7 @@ export type DocumentDataplyCondition<V> = {
     notEqual?: Partial<V>;
     or?: Partial<V>[];
     like?: string;
+    match?: string;
 };
 export type DocumentDataplyQuery<T> = {
     [key in keyof T]?: T[key] | DocumentDataplyCondition<T[key]>;
@@ -110,10 +121,18 @@ export type DocumentDataplyIndices<T extends DocumentJSON, IC extends IndexConfi
     [key in keyof IC & keyof FinalFlatten<T>]: GetTypeByPath<T, key>;
 };
 /**
- * Index configuration type - keys are field names, values are boolean
+ * Index configuration type
  */
+export type FTSConfig = {
+    type: 'fts';
+    tokenizer: 'whitespace';
+} | {
+    type: 'fts';
+    tokenizer: 'ngram';
+    gramSize: number;
+};
 export type IndexConfig<T> = Partial<{
-    [key in keyof FinalFlatten<T>]: boolean;
+    [key in keyof FinalFlatten<T>]: boolean | FTSConfig;
 }>;
 /**
  * Extract index keys from IndexConfig

package/dist/types/utils/hash.d.ts

@@ -0,0 +1 @@
+export declare function fastStringHash(str: string): number;

package/dist/types/utils/tokenizer.d.ts

@@ -0,0 +1,4 @@
+import { FTSConfig } from '../types';
+export declare function whitespaceTokenize(text: string): string[];
+export declare function ngramTokenize(text: string, gramSize: number): string[];
+export declare function tokenize(text: string, options: FTSConfig): string[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "document-dataply",
-  "version": "0.0.6",
+  "version": "0.0.7-alpha.1",
   "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.22"
+    "dataply": "^0.0.23-alpha.2"
   },
   "devDependencies": {
     "@types/jest": "^30.0.0",