@torquedev/ext-search

Full-text search service for Torque, backed by SQLite FTS5 with a pluggable adapter pattern. Provides cross-domain search, autocomplete, and BM25 ranking with zero infrastructure required.

Install

npm install github:michaeljabbour/torque-ext-search

Peer dependencies: @torquedev/core >=0.1.0, better-sqlite3 >=11.0.0

Usage

import { SearchService } from '@torquedev/ext-search';

const searchService = new SearchService({ db, config: {
  adapter: 'fts5',  // default
}});

coordinator.registerService('search', searchService);

Bundles register searchable domains at boot:

const search = coordinator.service('search');
search.register('entities', ['name', 'type', 'status']);

Index records on write:

search.index('entities', record.id, { name: 'Acme Corp', type: 'company', status: 'active' });

Search across all domains:

search.query('acme corp');
// [{ domain: 'entities', record_id: '...', snippet: '<b>Acme</b> Corp', rank: -12.5 }]

API

register(domain, columns, options?)

Register a domain for full-text indexing. Called once per domain at bundle boot.

• domain -- lowercase identifier (validated against /^[a-z][a-z0-9_]*$/)
• columns -- array of column names to index
• options.weights -- per-column ranking weights, e.g. { name: 10, status: 1 }
• options.displayColumn -- column to return in autocomplete results

index(domain, id, fields)

Index or re-index a record. Replaces any existing entry with the same ID (upsert).

remove(domain, id)

Remove a record from the search index.

query(text, options?)

Full-text search across one or more domains. Returns results ranked by BM25 relevance.

• options.domains -- restrict to specific domains (default: all)
• options.limit -- max results (default: 20)
• options.offset -- pagination offset

Returns: Array<{ domain, record_id, snippet, rank }>

autocomplete(prefix, options?)

Prefix search for typeahead. Uses FTS5 prefix queries.

• options.domains -- restrict to specific domains
• options.limit -- max results (default: 10)

Returns: Array<{ domain, record_id, text }>

reindex(domain, records)

Rebuild the entire index for a domain from an array of { id, fields } objects. Runs inside a transaction.

domains()

Returns an array of registered domain names.

domainInfo(domain)

Returns { columns, options } for a registered domain, or null.

Security

Domain names are validated against /^[a-z][a-z0-9_]*$/ before interpolation into SQL, preventing injection through domain names.

Exports

import { SearchService } from '@torquedev/ext-search';

Testing

npm test

ESM-only. Requires Node.js with the built-in test runner.

License

MIT