@thyn-ai/fuse-mojo-core 0.1.7

package/NOTICE

@@ -0,0 +1,16 @@
+NOTICE
+======
+
+@thyn-ai/fuse-mojo-core includes a vendored copy of Fuse.js v7.1.0
+(vendor/fuse.basic.cjs), used as the pure-JavaScript fallback backend on
+platforms without a prebuilt native kernel, and as the reference oracle in
+the differential test suite.
+
+Fuse.js — Lightweight fuzzy-search
+Copyright (c) Kiro Risk (http://kiro.me)
+Licensed under the Apache License, Version 2.0
+http://www.apache.org/licenses/LICENSE-2.0
+https://github.com/krisk/Fuse
+
+The remainder of this package is Copyright (c) 2026 Algenta,
+Apache License, Version 2.0.

package/index.cjs

@@ -0,0 +1,147 @@
+'use strict'
+
+/**
+ * @thyn-ai/fuse-mojo-core — drop-in faster replacement for Fuse.js v7 fuzzy search.
+ *
+ * The heavy Bitap matching runs on a native Mojo kernel when its shared
+ * library is available (macOS arm64 / Linux x64 platform packages); on any
+ * load failure the package transparently falls back to the vendored Fuse.js
+ * implementation (Apache-2.0, see vendor/ and NOTICE), so results are
+ * identical on every platform.
+ */
+
+const {
+  DEFAULT_CONFIG,
+  UnsupportedOptionError,
+  validateOptions,
+  createKeyStore,
+} = require('./src/options.cjs')
+const { buildEngine, nativeSearch } = require('./src/engine.cjs')
+const {
+  NativeIndex,
+  NativeUnavailable,
+  nativeAvailable,
+  backendInfo,
+} = require('./src/native.cjs')
+const VendorFuse = require('./vendor/fuse.basic.cjs')
+
+class FuseMojo {
+  /**
+   * @param {Array} docs string list or array of objects
+   * @param {object} options Fuse.js-compatible options (see README for the
+   *   supported subset; unsupported options throw UnsupportedOptionError)
+   */
+  constructor(docs, options = {}, index) {
+    if (index !== undefined) {
+      throw new UnsupportedOptionError('external index (Fuse.createIndex/parseIndex)')
+    }
+    this.options = { ...DEFAULT_CONFIG, ...options }
+    if (this.options.keys === undefined) {
+      this.options.keys = []
+    }
+    validateOptions(this.options)
+    this._keyStore = createKeyStore(this.options.keys)
+    this._fallback = null
+    this._engine = null
+    this._nativeIndex = null
+    this.setCollection(docs)
+  }
+
+  setCollection(docs, index) {
+    if (index !== undefined) {
+      throw new UnsupportedOptionError('external index (Fuse.createIndex/parseIndex)')
+    }
+    this._docs = docs
+    this._destroyNative()
+    this._fallback = null
+    this._engine = null
+    this._nativeIndex = null
+    try {
+      this._engine = buildEngine(docs, this._keyStore, this.options)
+      const nativeOptions = {
+        location: this.options.location,
+        distance: this.options.distance,
+        threshold: this.options.threshold,
+        minMatchCharLength: Math.max(this.options.minMatchCharLength, 0),
+        findAllMatches: this.options.findAllMatches,
+        ignoreLocation: this.options.ignoreLocation,
+        computeMatches: this.options.minMatchCharLength > 1 || this.options.includeMatches,
+        includeMatches: this.options.includeMatches,
+      }
+      this._nativeIndex = new NativeIndex(this._engine.chars, this._engine.offsets, nativeOptions)
+      this._backend = 'native'
+    } catch (err) {
+      if (!(err instanceof NativeUnavailable)) {
+        throw err
+      }
+      this._engine = null
+      this._nativeIndex = null
+      this._fallback = new VendorFuse(docs, this.options)
+      this._backend = 'fallback'
+      this._fallbackError = err.message
+    }
+    return this
+  }
+
+  /**
+   * @param {string} pattern search pattern (extended-search syntax is not
+   *   supported; non-string patterns throw)
+   * @param {{limit?: number}} opts
+   * @returns {Array<{item: any, refIndex: number, score?: number, matches?: Array}>}
+   */
+  search(pattern, { limit = -1 } = {}) {
+    if (typeof pattern !== 'string') {
+      throw new UnsupportedOptionError(
+        `non-string query (${typeof pattern === 'object' && pattern !== null ? 'logical $and/$or query' : typeof pattern})`
+      )
+    }
+    if (this._backend === 'native') {
+      return nativeSearch(this._engine, this._nativeIndex, pattern, limit, this.options)
+    }
+    return this._fallback.search(pattern, { limit })
+  }
+
+  /** Which backend serves this instance: "native" or "fallback". */
+  get backend() {
+    return this._backend
+  }
+
+  /** Free the native index handle (also freed automatically on GC). */
+  destroy() {
+    this._destroyNative()
+  }
+
+  _destroyNative() {
+    if (this._nativeIndex) {
+      this._nativeIndex.destroy()
+      this._nativeIndex = null
+    }
+  }
+
+  static createIndex() {
+    throw new UnsupportedOptionError('Fuse.createIndex')
+  }
+
+  static parseIndex() {
+    throw new UnsupportedOptionError('Fuse.parseIndex')
+  }
+
+  static nativeAvailable() {
+    return nativeAvailable()
+  }
+
+  static backendInfo() {
+    return backendInfo()
+  }
+}
+
+FuseMojo.config = DEFAULT_CONFIG
+FuseMojo.version = require('./package.json').version
+
+module.exports = FuseMojo
+module.exports.default = FuseMojo
+module.exports.Fuse = FuseMojo
+module.exports.FuseMojo = FuseMojo
+module.exports.nativeAvailable = nativeAvailable
+module.exports.backendInfo = backendInfo
+module.exports.UnsupportedOptionError = UnsupportedOptionError

package/index.d.ts

@@ -0,0 +1,87 @@
+// Type definitions for the supported drop-in surface of @thyn-ai/fuse-mojo-core.
+// Mirrors the Fuse.js v7 API shape for the supported option subset.
+
+declare namespace FuseMojo {
+  interface FuseKeyObject {
+    name: string | string[]
+    weight?: number
+  }
+
+  interface FuseOptions {
+    /** List of properties to search (dotted paths supported). */
+    keys?: Array<string | string[] | FuseKeyObject>
+    /** Give up threshold in [0, 1]; 0.0 requires a perfect match. Default 0.6. */
+    threshold?: number
+    /** Approximately where in the text the pattern is expected. Default 0. */
+    location?: number
+    /** How close the match must be to `location`. Default 100. */
+    distance?: number
+    /** Minimum matched-run length for a result to count. Default 1. */
+    minMatchCharLength?: number
+    /** Include the score in results. Default false. */
+    includeScore?: boolean
+    /** Include matched character index ranges in results. Default false. */
+    includeMatches?: boolean
+    /** Sort results by score. Default true. */
+    shouldSort?: boolean
+    /** Ignore `location`/`distance` when scoring. Default false. */
+    ignoreLocation?: boolean
+    /** Case-sensitive matching. Default false. */
+    isCaseSensitive?: boolean
+    /** Keep searching after a perfect match. Default false. */
+    findAllMatches?: boolean
+    /** Ignore the field-length norm in scoring. Default false. */
+    ignoreFieldNorm?: boolean
+    /** Field-length norm weight. Default 1. */
+    fieldNormWeight?: number
+  }
+
+  interface FuseSearchOptions {
+    limit?: number
+  }
+
+  type FuseIndexRange = [number, number]
+
+  interface FuseResultMatch {
+    indices: FuseIndexRange[]
+    value: string
+    key?: string | string[]
+    refIndex?: number
+  }
+
+  interface FuseResult<T> {
+    item: T
+    refIndex: number
+    score?: number
+    matches?: FuseResultMatch[]
+  }
+
+  interface BackendInfo {
+    native_available: boolean
+    native_source: string | null
+    abi_version_expected: number
+    abi_version_native: number | null
+    disabled_by_env: boolean
+    platform: string
+    arch: string
+    error: string | null
+  }
+}
+
+declare class FuseMojo<T = any> {
+  constructor(list: ReadonlyArray<T>, options?: FuseMojo.FuseOptions)
+  options: FuseMojo.FuseOptions
+  search(pattern: string, opts?: FuseMojo.FuseSearchOptions): Array<FuseMojo.FuseResult<T>>
+  setCollection(docs: ReadonlyArray<T>): this
+  readonly backend: 'native' | 'fallback'
+  destroy(): void
+
+  static config: FuseMojo.FuseOptions
+  static version: string
+  static nativeAvailable(): boolean
+  static backendInfo(): FuseMojo.BackendInfo
+  static createIndex(): never
+  static parseIndex(): never
+}
+
+export = FuseMojo

package/index.mjs

@@ -0,0 +1,7 @@
+import FuseMojo from './index.cjs'
+
+export default FuseMojo
+export const Fuse = FuseMojo
+export const nativeAvailable = FuseMojo.nativeAvailable
+export const backendInfo = FuseMojo.backendInfo
+export const UnsupportedOptionError = FuseMojo.UnsupportedOptionError

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@thyn-ai/fuse-mojo-core",
+  "version": "0.1.7",
+  "description": "Drop-in faster replacement for Fuse.js, powered by a Mojo kernel (pure-JS fallback included).",
+  "license": "Apache-2.0",
+  "author": "Algenta",
+  "keywords": [
+    "fuse",
+    "fuzzy",
+    "search",
+    "bitap",
+    "mojo",
+    "fuse.js"
+  ],
+  "type": "commonjs",
+  "main": "index.cjs",
+  "types": "index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.mjs",
+      "require": "./index.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "index.cjs",
+    "index.mjs",
+    "index.d.ts",
+    "src/",
+    "vendor/",
+    "NOTICE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "koffi": "^3.3.1"
+  },
+  "optionalDependencies": {
+    "@thyn-ai/fuse-mojo-darwin-arm64": "0.1.7",
+    "@thyn-ai/fuse-mojo-linux-x64": "0.1.7"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/thyn-ai/mojo-kernels"
+  }
+}

package/src/engine.cjs

@@ -0,0 +1,314 @@
+'use strict'
+
+/**
+ * Index construction and search orchestration for the native backend.
+ *
+ * The engine extracts every searchable string from the document collection
+ * (replicating the reference's index records, including the reversed order of
+ * array-valued sub-records), lowercases them once at build time, and hands a
+ * flat UTF-16 buffer to the native kernel. Each search call then maps to one
+ * kernel call per pattern chunk and combines per-text results exactly like
+ * the reference's BitapSearch/Fuse pipeline.
+ */
+
+const { fuseGet, isBlank, createNormGetter, defaultSortFn } = require('./options.cjs')
+
+const MAX_BITS = 32
+const INT32_MAX = 0x7fffffff
+
+class EngineBuildError extends Error {
+  constructor(message) {
+    super(message)
+    this.name = 'EngineBuildError'
+    this.code = 'FUSE_MOJO_ENGINE_BUILD'
+  }
+}
+
+/**
+ * Split a (lowered) pattern into <=32-code-unit chunks, mirroring the
+ * reference: full chunks of 32, with the final chunk of `remainder` units
+ * taken from the tail so it always has length 32 when possible.
+ */
+function chunkPattern(pattern) {
+  const len = pattern.length
+  const chunks = []
+  if (len > MAX_BITS) {
+    let i = 0
+    const remainder = len % MAX_BITS
+    const end = len - remainder
+    while (i < end) {
+      chunks.push({ text: pattern.slice(i, i + MAX_BITS), startIndex: i })
+      i += MAX_BITS
+    }
+    if (remainder) {
+      const startIndex = len - MAX_BITS
+      chunks.push({ text: pattern.slice(startIndex), startIndex })
+    }
+  } else {
+    chunks.push({ text: pattern, startIndex: 0 })
+  }
+  return chunks
+}
+
+function toU16(str) {
+  const out = new Uint16Array(str.length)
+  for (let i = 0; i < str.length; i += 1) {
+    out[i] = str.charCodeAt(i)
+  }
+  return out
+}
+
+/**
+ * Build the searchable-text engine. Every entry corresponds to one string the
+ * reference would run Bitap on, in the reference's iteration order:
+ *   string list: one entry per non-blank document
+ *   object list: per document, per configured key, one entry per value
+ *                (array values contribute one entry per element, in the
+ *                reversed order produced by the reference's stack DFS)
+ */
+function buildEngine(docs, keyStore, options) {
+  const normOf = createNormGetter(options.fieldNormWeight, 3)
+  const nDocs = docs && typeof docs.length === 'number' ? docs.length : 0
+  const mode = typeof docs[0] === 'string' ? 'string' : 'object'
+  const entries = []
+
+  if (mode === 'string') {
+    for (let i = 0; i < nDocs; i += 1) {
+      const doc = docs[i]
+      if (doc === undefined || doc === null) {
+        continue
+      }
+      if (isBlank(doc)) {
+        continue
+      }
+      entries.push({ docIdx: i, keyIdx: -1, arrIdx: -1, value: doc, norm: normOf(doc) })
+    }
+  } else {
+    for (let i = 0; i < nDocs; i += 1) {
+      const doc = docs[i]
+      for (let k = 0; k < keyStore.length; k += 1) {
+        const key = keyStore[k]
+        const value = fuseGet(doc, key.path)
+        if (value === undefined || value === null) {
+          continue
+        }
+        if (Array.isArray(value)) {
+          // Reference _addObject: stack-based DFS pops later elements first,
+          // so sub-records come out reversed relative to document order.
+          const stack = [{ nestedArrIndex: -1, value }]
+          while (stack.length) {
+            const { nestedArrIndex, value: v } = stack.pop()
+            if (v === undefined || v === null) {
+              continue
+            }
+            if (typeof v === 'string' && !isBlank(v)) {
+              entries.push({ docIdx: i, keyIdx: k, arrIdx: nestedArrIndex, value: v, norm: normOf(v) })
+            } else if (Array.isArray(v)) {
+              for (let kk = 0; kk < v.length; kk += 1) {
+                stack.push({ nestedArrIndex: kk, value: v[kk] })
+              }
+            }
+            // Non-string leaves are silently ignored, as in the reference.
+          }
+        } else if (typeof value === 'string' && !isBlank(value)) {
+          entries.push({ docIdx: i, keyIdx: k, arrIdx: -1, value, norm: normOf(value) })
+        }
+      }
+    }
+  }
+
+  // Flatten the lowered texts into one UTF-16 buffer.
+  const loweredStrings = new Array(entries.length)
+  let total = 0
+  for (let e = 0; e < entries.length; e += 1) {
+    const s = options.isCaseSensitive ? entries[e].value : entries[e].value.toLowerCase()
+    loweredStrings[e] = s
+    total += s.length
+  }
+  if (total > INT32_MAX) {
+    throw new EngineBuildError(
+      `collection too large for the native kernel: ${total} UTF-16 code units (> 2^31)`
+    )
+  }
+  const chars = new Uint16Array(total)
+  const offsets = new Int32Array(entries.length + 1)
+  let off = 0
+  for (let e = 0; e < entries.length; e += 1) {
+    const s = loweredStrings[e]
+    for (let k = 0; k < s.length; k += 1) {
+      chars[off + k] = s.charCodeAt(k)
+    }
+    off += s.length
+    offsets[e + 1] = off
+  }
+
+  return { mode, entries, loweredStrings, chars, offsets, docs, keyStore }
+}
+
+/**
+ * Run a search on the native backend and format results identically to the
+ * reference `Fuse#search`.
+ */
+function nativeSearch(engine, nativeIndex, pattern, limit, options) {
+  const { entries, loweredStrings, docs, keyStore } = engine
+  const nEntries = entries.length
+
+  const loweredPattern = options.isCaseSensitive ? pattern : pattern.toLowerCase()
+  if (!loweredPattern.length) {
+    return []
+  }
+  const chunks = chunkPattern(loweredPattern)
+  const singleChunk = chunks.length === 1
+  const includeMatches = options.includeMatches
+
+  const totalScore = new Float64Array(nEntries)
+  const hasMatch = new Uint8Array(nEntries)
+  const indicesByEntry = includeMatches ? new Array(nEntries).fill(null) : null
+
+  for (const chunk of chunks) {
+    const chunkU16 = toU16(chunk.text)
+    const { totalPairs, scores, isMatch, idxOffsets } = nativeIndex.searchChunk(
+      chunkU16,
+      chunk.startIndex,
+      singleChunk
+    )
+    let pairs = null
+    if (includeMatches && totalPairs > 0) {
+      pairs = nativeIndex.copyIndices(totalPairs)
+    }
+    for (let e = 0; e < nEntries; e += 1) {
+      // The reference folds every chunk's (clamped) score into the average,
+      // even for chunks that did not match.
+      totalScore[e] += scores[e]
+      if (isMatch[e]) {
+        hasMatch[e] = 1
+        if (includeMatches) {
+          const from = idxOffsets[e]
+          const to = idxOffsets[e + 1]
+          if (to > from) {
+            let arr = indicesByEntry[e]
+            if (arr === null) {
+              arr = []
+              indicesByEntry[e] = arr
+            }
+            for (let p = from; p < to; p += 1) {
+              arr.push([pairs[p * 2], pairs[p * 2 + 1]])
+            }
+          }
+        }
+      }
+    }
+  }
+
+  // Whole-pattern exact-equality fast path. For single-chunk patterns the
+  // kernel already applied it; for multi-chunk patterns it is replicated here
+  // (the reference checks pattern === text before running any chunk).
+  if (!singleChunk) {
+    for (let e = 0; e < nEntries; e += 1) {
+      if (loweredStrings[e] === loweredPattern) {
+        hasMatch[e] = 1
+        totalScore[e] = 0
+        if (includeMatches) {
+          indicesByEntry[e] = [[0, loweredStrings[e].length - 1]]
+        }
+      }
+    }
+  }
+
+  // Assemble per-document results with reference match-record shapes.
+  const results = []
+  if (engine.mode === 'string') {
+    for (let e = 0; e < nEntries; e += 1) {
+      if (!hasMatch[e]) continue
+      const entry = entries[e]
+      results.push({
+        idx: entry.docIdx,
+        matches: [
+          {
+            score: totalScore[e] / chunks.length,
+            value: entry.value,
+            norm: entry.norm,
+            indices: includeMatches ? indicesByEntry[e] || [] : undefined,
+          },
+        ],
+      })
+    }
+  } else {
+    let current = null
+    let currentDoc = -1
+    for (let e = 0; e < nEntries; e += 1) {
+      if (!hasMatch[e]) continue
+      const entry = entries[e]
+      const match = {
+        score: totalScore[e] / chunks.length,
+        key: keyStore[entry.keyIdx],
+        value: entry.value,
+        norm: entry.norm,
+        indices: includeMatches ? indicesByEntry[e] || [] : undefined,
+      }
+      if (entry.arrIdx > -1) {
+        match.idx = entry.arrIdx
+      }
+      if (entry.docIdx !== currentDoc) {
+        current = { idx: entry.docIdx, matches: [] }
+        results.push(current)
+        currentDoc = entry.docIdx
+      }
+      current.matches.push(match)
+    }
+  }
+
+  // Practical scoring: product over matches of score^(weight * norm).
+  for (const result of results) {
+    let score = 1
+    for (const match of result.matches) {
+      const weight = match.key ? match.key.weight : null
+      score *= Math.pow(
+        match.score === 0 && weight ? Number.EPSILON : match.score,
+        (weight || 1) * (options.ignoreFieldNorm ? 1 : match.norm)
+      )
+    }
+    result.score = score
+  }
+
+  if (options.shouldSort) {
+    results.sort(defaultSortFn)
+  }
+
+  if (typeof limit === 'number' && limit > -1) {
+    return formatResults(results.slice(0, limit), docs, options)
+  }
+  return formatResults(results, docs, options)
+}
+
+function formatResults(results, docs, options) {
+  const { includeMatches, includeScore } = options
+  return results.map((result) => {
+    const data = {
+      item: docs[result.idx],
+      refIndex: result.idx,
+    }
+    if (includeMatches) {
+      data.matches = []
+      for (const match of result.matches) {
+        if (!match.indices || !match.indices.length) {
+          continue
+        }
+        const obj = { indices: match.indices, value: match.value }
+        if (match.key) {
+          obj.key = match.key.src
+        }
+        if (match.idx > -1) {
+          obj.refIndex = match.idx
+        }
+        data.matches.push(obj)
+      }
+    }
+    if (includeScore) {
+      data.score = result.score
+    }
+    return data
+  })
+}
+
+module.exports = { buildEngine, nativeSearch, chunkPattern, EngineBuildError }