@strav/search 0.3.19 → 0.3.21

package/src/drivers/embedded/filters/filter_compiler.ts

@@ -0,0 +1,136 @@
+import { UnsupportedFilterError } from '../errors.ts'
+import { quoteIdent } from '../engine/schema.ts'
+
+export interface CompiledFilter {
+  /** SQL fragment to splice into a WHERE clause (no leading 'WHERE'). Empty if no filter. */
+  sql: string
+  /** Bound parameters in the order their `?` placeholders appear. */
+  params: unknown[]
+}
+
+/**
+ * Compile a filter object into a parameterized SQL WHERE fragment.
+ *
+ * Supported value shapes for each key:
+ * - primitive (string/number/boolean/null) → `key = ?`
+ * - array of primitives → `key IN (?, ?, ?)`
+ * - operator object: `{ gt, gte, lt, lte, eq, neq, in }` → composed clauses
+ *
+ * Unknown keys are NOT validated against the field registry here — callers
+ * are expected to have configured `filterableAttributes` correctly. SQLite
+ * raises a clean error if the column doesn't exist.
+ */
+export function compileFilter(
+  filter: Record<string, unknown> | string | undefined,
+  filterableAttributes: ReadonlySet<string>
+): CompiledFilter {
+  if (!filter) return { sql: '', params: [] }
+
+  if (typeof filter === 'string') {
+    throw new UnsupportedFilterError(
+      'Raw string filters are not supported by the embedded driver. ' +
+        'Pass an object like `{ status: "published" }` instead.'
+    )
+  }
+
+  const clauses: string[] = []
+  const params: unknown[] = []
+
+  for (const [key, value] of Object.entries(filter)) {
+    if (value === undefined) continue
+
+    if (!filterableAttributes.has(key)) {
+      throw new UnsupportedFilterError(
+        `Field "${key}" is not in filterableAttributes. ` +
+          'Add it to the index settings before filtering on it.'
+      )
+    }
+
+    const col = quoteIdent(key)
+
+    if (value === null) {
+      clauses.push(`${col} IS NULL`)
+      continue
+    }
+
+    if (Array.isArray(value)) {
+      if (value.length === 0) {
+        clauses.push('1 = 0')
+      } else {
+        const placeholders = value.map(() => '?').join(', ')
+        clauses.push(`${col} IN (${placeholders})`)
+        params.push(...value.map(coerce))
+      }
+      continue
+    }
+
+    if (isOperatorObject(value)) {
+      for (const [op, opValue] of Object.entries(value)) {
+        const compiled = compileOperator(col, op, opValue)
+        clauses.push(compiled.sql)
+        params.push(...compiled.params)
+      }
+      continue
+    }
+
+    if (isPrimitive(value)) {
+      clauses.push(`${col} = ?`)
+      params.push(coerce(value))
+      continue
+    }
+
+    throw new UnsupportedFilterError(
+      `Unsupported filter value for key "${key}": ${JSON.stringify(value)}`
+    )
+  }
+
+  return { sql: clauses.join(' AND '), params }
+}
+
+function isOperatorObject(value: unknown): value is Record<string, unknown> {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) return false
+  return Object.keys(value).every(k => OPERATORS.has(k))
+}
+
+const OPERATORS = new Set(['eq', 'neq', 'gt', 'gte', 'lt', 'lte', 'in', 'nin'])
+
+function compileOperator(col: string, op: string, value: unknown): CompiledFilter {
+  switch (op) {
+    case 'eq':
+      return { sql: `${col} = ?`, params: [coerce(value)] }
+    case 'neq':
+      return { sql: `${col} <> ?`, params: [coerce(value)] }
+    case 'gt':
+      return { sql: `${col} > ?`, params: [coerce(value)] }
+    case 'gte':
+      return { sql: `${col} >= ?`, params: [coerce(value)] }
+    case 'lt':
+      return { sql: `${col} < ?`, params: [coerce(value)] }
+    case 'lte':
+      return { sql: `${col} <= ?`, params: [coerce(value)] }
+    case 'in': {
+      if (!Array.isArray(value) || value.length === 0) return { sql: '1 = 0', params: [] }
+      const ph = value.map(() => '?').join(', ')
+      return { sql: `${col} IN (${ph})`, params: value.map(coerce) }
+    }
+    case 'nin': {
+      if (!Array.isArray(value) || value.length === 0) return { sql: '1 = 1', params: [] }
+      const ph = value.map(() => '?').join(', ')
+      return { sql: `${col} NOT IN (${ph})`, params: value.map(coerce) }
+    }
+    default:
+      throw new UnsupportedFilterError(`Unknown operator "${op}"`)
+  }
+}
+
+function isPrimitive(value: unknown): boolean {
+  return (
+    typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean'
+  )
+}
+
+function coerce(value: unknown): unknown {
+  if (value === null || value === undefined) return null
+  if (typeof value === 'boolean') return value ? 1 : 0
+  return value
+}

package/src/drivers/embedded/index.ts

@@ -0,0 +1,3 @@
+export { EmbeddedDriver } from './embedded_driver.ts'
+export type { EmbeddedConfig, TypoToleranceMode, TypoToleranceSettings } from './types.ts'
+export { EmbeddedSearchError, IndexCorruptError, UnsupportedFilterError } from './errors.ts'

package/src/drivers/embedded/storage/paths.ts

@@ -0,0 +1,23 @@
+import { join, isAbsolute, resolve } from 'node:path'
+import { mkdirSync } from 'node:fs'
+import type { EmbeddedConfig } from '../types.ts'
+
+const MEMORY = ':memory:'
+
+/**
+ * Resolve the on-disk path for a given index, creating the parent directory
+ * if necessary. Returns ':memory:' verbatim when the config asks for it.
+ */
+export function resolveIndexPath(config: EmbeddedConfig, index: string): string {
+  const root = config.path ?? './storage/search'
+
+  if (root === MEMORY) return MEMORY
+
+  const dir = isAbsolute(root) ? root : resolve(process.cwd(), root)
+  mkdirSync(dir, { recursive: true })
+
+  const safeName = index.replace(/[^a-zA-Z0-9_.-]/g, '_')
+  return join(dir, `${safeName}.sqlite`)
+}
+
+export const MEMORY_PATH = MEMORY

package/src/drivers/embedded/types.ts

@@ -0,0 +1,34 @@
+import type { DriverConfig } from '../../types.ts'
+
+export type TypoToleranceMode = 'off' | 'auto'
+
+export interface TypoToleranceSettings {
+  /** Minimum token length to consider for fuzzy expansion (default 4). */
+  minTokenLength?: number
+  /** Maximum Levenshtein distance to tolerate (default 1; 2 is supported but slower). */
+  maxDistance?: number
+}
+
+export interface EmbeddedConfig extends DriverConfig {
+  driver: string
+  /** Directory holding the per-index `.sqlite` files. Use `:memory:` for tests. */
+  path?: string
+  /** SQLite synchronous pragma. Default 'NORMAL' (crash-safe, sub-second write loss possible). */
+  synchronous?: 'OFF' | 'NORMAL' | 'FULL'
+  /** Typo tolerance: 'off' disables; 'auto' uses defaults; object for fine-grained control. */
+  typoTolerance?: TypoToleranceMode | TypoToleranceSettings
+}
+
+/** Resolved typo tolerance settings (after defaults applied). */
+export interface ResolvedTypoTolerance {
+  enabled: boolean
+  minTokenLength: number
+  maxDistance: number
+}
+
+/** Internal row shape from the documents table. */
+export interface DocumentRow {
+  rowid: number
+  id: string
+  doc: string
+}

package/src/index.ts

@@ -12,6 +12,12 @@ export { MeilisearchDriver } from './drivers/meilisearch_driver.ts'
 export { TypesenseDriver } from './drivers/typesense_driver.ts'
 export { AlgoliaDriver } from './drivers/algolia_driver.ts'
 export { NullDriver } from './drivers/null_driver.ts'
+export { EmbeddedDriver } from './drivers/embedded/index.ts'
+export type {
+  EmbeddedConfig,
+  TypoToleranceMode,
+  TypoToleranceSettings,
+} from './drivers/embedded/index.ts'
 
 // Mixin
 export { searchable } from './searchable.ts'

package/src/search_manager.ts

@@ -5,6 +5,7 @@ import { MeilisearchDriver } from './drivers/meilisearch_driver.ts'
 import { TypesenseDriver } from './drivers/typesense_driver.ts'
 import { AlgoliaDriver } from './drivers/algolia_driver.ts'
 import { NullDriver } from './drivers/null_driver.ts'
+import { EmbeddedDriver } from './drivers/embedded/index.ts'
 
 @inject
 export default class SearchManager {
@@ -86,6 +87,8 @@ export default class SearchManager {
         return new TypesenseDriver(config)
       case 'algolia':
         return new AlgoliaDriver(config)
+      case 'embedded':
+        return new EmbeddedDriver(config)
       case 'null':
         return new NullDriver()
       default:

package/stubs/config/search.ts

@@ -28,5 +28,15 @@ export default {
       appId: env('ALGOLIA_APP_ID', ''),
       apiKey: env('ALGOLIA_SECRET', ''),
     },
+
+    embedded: {
+      driver: 'embedded',
+      /** Directory holding per-index `.sqlite` files. Use ':memory:' for tests. */
+      path: env('SEARCH_PATH', './storage/search'),
+      /** SQLite synchronous pragma. NORMAL is crash-safe with sub-second-of-writes loss. */
+      synchronous: env('SEARCH_SYNCHRONOUS', 'NORMAL'),
+      /** Typo tolerance: 'off' to disable, 'auto' for defaults, or { minTokenLength, maxDistance }. */
+      typoTolerance: env('SEARCH_TYPO_TOLERANCE', 'auto'),
+    },
   },
 }