feat: getFn null return, escaped pipe in extended search, empty query returns all

krisk · claude · krisk · commit d33b735f62ae · 2026-04-02T16:54:47.000-07:00
Three small features: - Allow key-level getFn to return null/undefined (closes #800) - Support \| to search literal pipe in extended search (closes #765) - Empty string query returns all docs with refIndex (closes #728) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
diff --git a/dist/fuse.basic.cjs b/dist/fuse.basic.cjs
@@ -1294,6 +1294,20 @@ var Fuse = /*#__PURE__*/function () {
         shouldSort = _this$options.shouldSort,
         sortFn = _this$options.sortFn,
         ignoreFieldNorm = _this$options.ignoreFieldNorm;
+
+      // Empty string query returns all docs (useful for search UIs)
+      if (isString(query) && !query.trim()) {
+        var docs = this._docs.map(function (item, idx) {
+          return {
+            item: item,
+            refIndex: idx
+          };
+        });
+        if (isNumber(limit) && limit > -1) {
+          docs = docs.slice(0, limit);
+        }
+        return docs;
+      }
       var useHeap = isNumber(limit) && limit > 0 && isString(query);
       var results;
       if (useHeap) {
diff --git a/dist/fuse.basic.js b/dist/fuse.basic.js
@@ -1298,6 +1298,20 @@
           shouldSort = _this$options.shouldSort,
           sortFn = _this$options.sortFn,
           ignoreFieldNorm = _this$options.ignoreFieldNorm;
+
+        // Empty string query returns all docs (useful for search UIs)
+        if (isString(query) && !query.trim()) {
+          var docs = this._docs.map(function (item, idx) {
+            return {
+              item: item,
+              refIndex: idx
+            };
+          });
+          if (isNumber(limit) && limit > -1) {
+            docs = docs.slice(0, limit);
+          }
+          return docs;
+        }
         var useHeap = isNumber(limit) && limit > 0 && isString(query);
         var results;
         if (useHeap) {
diff --git a/dist/fuse.basic.min.cjs b/dist/fuse.basic.min.cjs
diff --git a/dist/fuse.basic.min.js b/dist/fuse.basic.min.js
diff --git a/dist/fuse.basic.min.mjs b/dist/fuse.basic.min.mjs
diff --git a/dist/fuse.basic.mjs b/dist/fuse.basic.mjs
@@ -1064,6 +1064,18 @@ class Fuse {
       sortFn,
       ignoreFieldNorm
     } = this.options;
+
+    // Empty string query returns all docs (useful for search UIs)
+    if (isString(query) && !query.trim()) {
+      let docs = this._docs.map((item, idx) => ({
+        item,
+        refIndex: idx
+      }));
+      if (isNumber(limit) && limit > -1) {
+        docs = docs.slice(0, limit);
+      }
+      return docs;
+    }
     const useHeap = isNumber(limit) && limit > 0 && isString(query);
     let results;
     if (useHeap) {
diff --git a/dist/fuse.cjs b/dist/fuse.cjs
@@ -1374,6 +1374,7 @@ var IncludeMatch = /*#__PURE__*/function (_BaseMatch) {
 // ❗Order is important. DO NOT CHANGE.
 var searchers = [ExactMatch, IncludeMatch, PrefixExactMatch, InversePrefixExactMatch, InverseSuffixExactMatch, SuffixExactMatch, InverseExactMatch, FuzzyMatch];
 var searchersLen = searchers.length;
+var ESCAPED_PIPE = "\0"; // placeholder for escaped \|
 var OR_TOKEN = '|';
 
 // Tokenize a query string into individual search terms.
@@ -1428,8 +1429,12 @@ function tokenize(pattern) {
 // "^core go$ | rb$ | py$ xy$" => [["^core", "go$"], ["rb$"], ["py$", "xy$"]]
 function parseQuery(pattern) {
   var options = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {};
-  return pattern.split(OR_TOKEN).map(function (item) {
-    var query = tokenize(item.trim()).filter(function (item) {
+  // Replace escaped \| with placeholder before splitting on |
+  var escaped = pattern.replace(/\\\|/g, ESCAPED_PIPE);
+  return escaped.split(OR_TOKEN).map(function (item) {
+    // Restore escaped pipes in each OR group
+    var restored = item.replace(/\u0000/g, '|');
+    var query = tokenize(restored.trim()).filter(function (item) {
       return item && !!item.trim();
     });
     var results = [];
@@ -1919,6 +1924,20 @@ var Fuse = /*#__PURE__*/function () {
         shouldSort = _this$options.shouldSort,
         sortFn = _this$options.sortFn,
         ignoreFieldNorm = _this$options.ignoreFieldNorm;
+
+      // Empty string query returns all docs (useful for search UIs)
+      if (isString(query) && !query.trim()) {
+        var docs = this._docs.map(function (item, idx) {
+          return {
+            item: item,
+            refIndex: idx
+          };
+        });
+        if (isNumber(limit) && limit > -1) {
+          docs = docs.slice(0, limit);
+        }
+        return docs;
+      }
       var useHeap = isNumber(limit) && limit > 0 && isString(query);
       var results;
       if (useHeap) {
diff --git a/dist/fuse.d.ts b/dist/fuse.d.ts
@@ -12,15 +12,15 @@ interface Searcher {
 interface FuseOptionKeyObject<T> {
     name: string | string[];
     weight?: number;
-    getFn?: (obj: T) => ReadonlyArray<string> | string;
+    getFn?: (obj: T) => ReadonlyArray<string> | string | null | undefined;
 }
 type FuseOptionKey<T> = FuseOptionKeyObject<T> | string | string[];
 interface KeyObject {
     path: string[];
     id: string;
     weight: number;
     src: string | string[];
-    getFn?: ((obj: any) => ReadonlyArray<string> | string) | null;
+    getFn?: ((obj: any) => ReadonlyArray<string> | string | null | undefined) | null;
 }
 type FuseGetFunction<T> = (obj: T, path: string | string[]) => ReadonlyArray<string> | string;
 type GetFunction = (obj: any, path: string | string[]) => any;
diff --git a/dist/fuse.js b/dist/fuse.js
@@ -1378,6 +1378,7 @@
   // ❗Order is important. DO NOT CHANGE.
   var searchers = [ExactMatch, IncludeMatch, PrefixExactMatch, InversePrefixExactMatch, InverseSuffixExactMatch, SuffixExactMatch, InverseExactMatch, FuzzyMatch];
   var searchersLen = searchers.length;
+  var ESCAPED_PIPE = "\0"; // placeholder for escaped \|
   var OR_TOKEN = '|';
 
   // Tokenize a query string into individual search terms.
@@ -1432,8 +1433,12 @@
   // "^core go$ | rb$ | py$ xy$" => [["^core", "go$"], ["rb$"], ["py$", "xy$"]]
   function parseQuery(pattern) {
     var options = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {};
-    return pattern.split(OR_TOKEN).map(function (item) {
-      var query = tokenize(item.trim()).filter(function (item) {
+    // Replace escaped \| with placeholder before splitting on |
+    var escaped = pattern.replace(/\\\|/g, ESCAPED_PIPE);
+    return escaped.split(OR_TOKEN).map(function (item) {
+      // Restore escaped pipes in each OR group
+      var restored = item.replace(/\u0000/g, '|');
+      var query = tokenize(restored.trim()).filter(function (item) {
         return item && !!item.trim();
       });
       var results = [];
@@ -1923,6 +1928,20 @@
           shouldSort = _this$options.shouldSort,
           sortFn = _this$options.sortFn,
           ignoreFieldNorm = _this$options.ignoreFieldNorm;
+
+        // Empty string query returns all docs (useful for search UIs)
+        if (isString(query) && !query.trim()) {
+          var docs = this._docs.map(function (item, idx) {
+            return {
+              item: item,
+              refIndex: idx
+            };
+          });
+          if (isNumber(limit) && limit > -1) {
+            docs = docs.slice(0, limit);
+          }
+          return docs;
+        }
         var useHeap = isNumber(limit) && limit > 0 && isString(query);
         var results;
         if (useHeap) {
diff --git a/dist/fuse.min.cjs b/dist/fuse.min.cjs
diff --git a/dist/fuse.min.js b/dist/fuse.min.js
diff --git a/dist/fuse.min.mjs b/dist/fuse.min.mjs
diff --git a/dist/fuse.mjs b/dist/fuse.mjs
@@ -1026,6 +1026,7 @@ class IncludeMatch extends BaseMatch {
 // ❗Order is important. DO NOT CHANGE.
 const searchers = [ExactMatch, IncludeMatch, PrefixExactMatch, InversePrefixExactMatch, InverseSuffixExactMatch, SuffixExactMatch, InverseExactMatch, FuzzyMatch];
 const searchersLen = searchers.length;
+const ESCAPED_PIPE = '\u0000'; // placeholder for escaped \|
 const OR_TOKEN = '|';
 
 // Tokenize a query string into individual search terms.
@@ -1079,8 +1080,12 @@ function tokenize(pattern) {
 // Example:
 // "^core go$ | rb$ | py$ xy$" => [["^core", "go$"], ["rb$"], ["py$", "xy$"]]
 function parseQuery(pattern, options = {}) {
-  return pattern.split(OR_TOKEN).map(item => {
-    const query = tokenize(item.trim()).filter(item => item && !!item.trim());
+  // Replace escaped \| with placeholder before splitting on |
+  const escaped = pattern.replace(/\\\|/g, ESCAPED_PIPE);
+  return escaped.split(OR_TOKEN).map(item => {
+    // Restore escaped pipes in each OR group
+    const restored = item.replace(/\u0000/g, '|');
+    const query = tokenize(restored.trim()).filter(item => item && !!item.trim());
     const results = [];
     for (let i = 0, len = query.length; i < len; i += 1) {
       const queryItem = query[i];
@@ -1521,6 +1526,18 @@ class Fuse {
       sortFn,
       ignoreFieldNorm
     } = this.options;
+
+    // Empty string query returns all docs (useful for search UIs)
+    if (isString(query) && !query.trim()) {
+      let docs = this._docs.map((item, idx) => ({
+        item,
+        refIndex: idx
+      }));
+      if (isNumber(limit) && limit > -1) {
+        docs = docs.slice(0, limit);
+      }
+      return docs;
+    }
     const useHeap = isNumber(limit) && limit > 0 && isString(query);
     let results;
     if (useHeap) {
diff --git a/src/core/index.ts b/src/core/index.ts
@@ -137,6 +137,18 @@ export default class Fuse<T> {
       ignoreFieldNorm
     } = this.options
 
+    // Empty string query returns all docs (useful for search UIs)
+    if (isString(query) && !query.trim()) {
+      let docs: FuseResult<T>[] = this._docs.map((item, idx) => ({
+        item,
+        refIndex: idx
+      }))
+      if (isNumber(limit) && limit > -1) {
+        docs = docs.slice(0, limit)
+      }
+      return docs
+    }
+
     const useHeap = isNumber(limit) && limit > 0 && isString(query)
 
     let results: InternalResult[]
diff --git a/src/search/extended/parseQuery.ts b/src/search/extended/parseQuery.ts
@@ -22,6 +22,7 @@ const searchers: Array<typeof BaseMatch> = [
 
 const searchersLen = searchers.length
 
+const ESCAPED_PIPE = '\u0000'  // placeholder for escaped \|
 const OR_TOKEN = '|'
 
 // Tokenize a query string into individual search terms.
@@ -78,8 +79,13 @@ function tokenize(pattern: string): string[] {
 // Example:
 // "^core go$ | rb$ | py$ xy$" => [["^core", "go$"], ["rb$"], ["py$", "xy$"]]
 export default function parseQuery(pattern: string, options: any = {}): BaseMatch[][] {
-  return pattern.split(OR_TOKEN).map((item) => {
-    const query = tokenize(item.trim()).filter((item) => item && !!item.trim())
+  // Replace escaped \| with placeholder before splitting on |
+  const escaped = pattern.replace(/\\\|/g, ESCAPED_PIPE)
+
+  return escaped.split(OR_TOKEN).map((item) => {
+    // Restore escaped pipes in each OR group
+    const restored = item.replace(/\u0000/g, '|')
+    const query = tokenize(restored.trim()).filter((item) => item && !!item.trim())
 
     const results: BaseMatch[] = []
     for (let i = 0, len = query.length; i < len; i += 1) {
diff --git a/src/types.ts b/src/types.ts
@@ -24,7 +24,7 @@ export interface SearcherConstructor {
 export interface FuseOptionKeyObject<T> {
   name: string | string[]
   weight?: number
-  getFn?: (obj: T) => ReadonlyArray<string> | string
+  getFn?: (obj: T) => ReadonlyArray<string> | string | null | undefined
 }
 
 export type FuseOptionKey<T> = FuseOptionKeyObject<T> | string | string[]
@@ -34,7 +34,7 @@ export interface KeyObject {
   id: string
   weight: number
   src: string | string[]
-  getFn?: ((obj: any) => ReadonlyArray<string> | string) | null
+  getFn?: ((obj: any) => ReadonlyArray<string> | string | null | undefined) | null
 }
 
 // ── Get function ───────────────────────────────────────────────────
diff --git a/test/extended-search.test.js b/test/extended-search.test.js
@@ -88,6 +88,37 @@ describe('Searching using extended search', () => {
   })
 })
 
+describe('Escaped pipe character in extended search', () => {
+  const list = [
+    { text: 'foo | bar' },
+    { text: 'foo or bar' },
+    { text: 'baz | qux' }
+  ]
+
+  const options = {
+    useExtendedSearch: true,
+    keys: ['text']
+  }
+  const fuse = new Fuse(list, options)
+
+  test('Search: escaped pipe in include-match', () => {
+    const result = fuse.search("'foo \\| bar")
+    expect(result).toHaveLength(1)
+    expect(result[0].item.text).toBe('foo | bar')
+  })
+
+  test('Search: escaped pipe in exact-match', () => {
+    const result = fuse.search('="foo \\| bar"')
+    expect(result).toHaveLength(1)
+    expect(result[0].item.text).toBe('foo | bar')
+  })
+
+  test('Search: unescaped pipe still works as OR', () => {
+    const result = fuse.search("'foo | 'qux")
+    expect(result).toHaveLength(3)
+  })
+})
+
 describe('Searching with quoted tokens containing spaces and inner quotes', () => {
   const list = [
     { text: 'said "test' },
diff --git a/test/fuzzy-search.test.js b/test/fuzzy-search.test.js
@@ -15,6 +15,26 @@ describe('Flat list of strings: ["Apple", "Orange", "Banana"]', () => {
   let fuse
   beforeEach(() => (fuse = setup()))
 
+  describe('When searching with an empty string', () => {
+    test('returns all items', () => {
+      const result = fuse.search('')
+      expect(result).toHaveLength(3)
+      expect(result[0].item).toBe('Apple')
+      expect(result[1].item).toBe('Orange')
+      expect(result[2].item).toBe('Banana')
+    })
+
+    test('returns all items for whitespace-only query', () => {
+      const result = fuse.search('   ')
+      expect(result).toHaveLength(3)
+    })
+
+    test('respects limit option', () => {
+      const result = fuse.search('', { limit: 2 })
+      expect(result).toHaveLength(2)
+    })
+  })
+
   describe('When searching for the term "Apple"', () => {
     let result
     beforeEach(() => (result = fuse.search('Apple')))
