@nomideusz/svelte-search 0.1.0

package/dist/core/indexer.js

@@ -0,0 +1,302 @@
+// ============================================================
+// @nomideusz/svelte-search — Indexer
+// ============================================================
+// Generic trigram indexing and FTS maintenance, driven by SchemaAdapter.
+//
+// Dialect support:
+//   - 'sqlite' (default): custom trigram tables, FTS5 rebuild
+//   - 'postgres': pg_trgm extension (no custom trigram tables needed),
+//                 tsvector column update
+import { normalize as normalizeText, trigrams } from './normalize.js';
+// ── Create indexer ─────────────────────────────────────────
+export function createIndexer(config) {
+    const { db, adapter, locale, dialect = 'sqlite' } = config;
+    const { tables, columns, trigramColumns } = adapter;
+    // ── SQLite trigram indexing ─────────────────────────────
+    /**
+     * Index trigrams for a single entity (SQLite only).
+     * For PostgreSQL, pg_trgm handles this automatically via GIN indexes.
+     */
+    async function indexTrigrams(entityId, entity) {
+        if (dialect === 'postgres')
+            return; // pg_trgm handles this
+        await db.execute({
+            sql: `DELETE FROM ${tables.trigrams} WHERE ${trigramColumns.entityId} = ?`,
+            args: [entityId],
+        });
+        const entries = [];
+        for (const { text, field } of adapter.trigramFields(entity)) {
+            if (!text)
+                continue;
+            for (const t of trigrams(text, locale)) {
+                entries.push({ trigram: t, field });
+            }
+        }
+        const BATCH = 100;
+        for (let i = 0; i < entries.length; i += BATCH) {
+            const chunk = entries.slice(i, i + BATCH);
+            const ph = chunk.map(() => '(?,?,?)').join(',');
+            const args = chunk.flatMap(e => [e.trigram, entityId, e.field]);
+            await db.execute({
+                sql: `INSERT OR IGNORE INTO ${tables.trigrams} (${trigramColumns.trigram}, ${trigramColumns.entityId}, ${trigramColumns.field}) VALUES ${ph}`,
+                args,
+            });
+        }
+    }
+    /** Rebuild all trigrams from scratch (SQLite only). */
+    async function reindexAllTrigrams() {
+        if (dialect === 'postgres')
+            return 0; // pg_trgm handles this
+        const result = await db.execute({ sql: `SELECT * FROM ${tables.entities}`, args: [] });
+        let count = 0;
+        for (const row of result.rows) {
+            const id = row[columns.id];
+            await indexTrigrams(id, row);
+            count++;
+        }
+        return count;
+    }
+    /** Rebuild FTS index. */
+    async function rebuildFts() {
+        if (dialect === 'postgres') {
+            // PostgreSQL: no separate FTS rebuild needed — tsvector column is maintained
+            // by triggers or updated via updateSearchVector()
+            return;
+        }
+        // SQLite FTS5 rebuild
+        await db.execute({
+            sql: `INSERT INTO ${tables.fts}(${tables.fts}) VALUES('rebuild')`,
+            args: [],
+        });
+    }
+    /** Check if FTS index is in sync with entities table. */
+    async function checkFtsSync() {
+        if (dialect === 'postgres') {
+            // PostgreSQL: check for entities with NULL search vectors
+            const tsCol = tables.fts;
+            const [entityCount, missingCount] = await Promise.all([
+                db.execute({ sql: `SELECT COUNT(*) as c FROM ${tables.entities}`, args: [] }),
+                db.execute({ sql: `SELECT COUNT(*) as c FROM ${tables.entities} WHERE ${tsCol} IS NULL`, args: [] }),
+            ]);
+            const total = Number(entityCount.rows[0].c);
+            const missing = Number(missingCount.rows[0].c);
+            return {
+                inEntities: total,
+                inFts: total - missing,
+                missingFromFts: missing,
+                orphanedInFts: 0,
+            };
+        }
+        // SQLite FTS5 sync check
+        const [entityCount, ftsCount, missing, orphaned] = await Promise.all([
+            db.execute({ sql: `SELECT COUNT(*) as c FROM ${tables.entities}`, args: [] }),
+            db.execute({ sql: `SELECT COUNT(*) as c FROM ${tables.fts}`, args: [] }),
+            db.execute({ sql: `SELECT COUNT(*) as c FROM ${tables.entities} s LEFT JOIN ${tables.fts} f ON s.rowid = f.rowid WHERE f.rowid IS NULL`, args: [] }),
+            db.execute({ sql: `SELECT COUNT(*) as c FROM ${tables.fts} f LEFT JOIN ${tables.entities} s ON f.rowid = s.rowid WHERE s.rowid IS NULL`, args: [] }),
+        ]);
+        return {
+            inEntities: Number(entityCount.rows[0].c),
+            inFts: Number(ftsCount.rows[0].c),
+            missingFromFts: Number(missing.rows[0].c),
+            orphanedInFts: Number(orphaned.rows[0].c),
+        };
+    }
+    /**
+     * Update the tsvector search column for a single entity (PostgreSQL only).
+     * Call after inserting/updating an entity.
+     *
+     * @param entityId - Primary key value
+     * @param searchText - Concatenated text to index (name + description + location + categories etc.)
+     * @param tsConfig - PostgreSQL text search config (default: 'simple')
+     */
+    async function updateSearchVector(entityId, searchText, tsConfig = 'simple') {
+        if (dialect !== 'postgres')
+            return;
+        const tsCol = tables.fts;
+        await db.execute({
+            sql: `UPDATE ${tables.entities} SET ${tsCol} = to_tsvector($1, $2) WHERE ${columns.id} = $3`,
+            args: [tsConfig, searchText, entityId],
+        });
+    }
+    /**
+     * Rebuild all search vectors (PostgreSQL only).
+     * Uses the adapter's trigramFields to build search text.
+     */
+    async function rebuildAllSearchVectors(tsConfig = 'simple') {
+        if (dialect !== 'postgres')
+            return 0;
+        const result = await db.execute({ sql: `SELECT * FROM ${tables.entities}`, args: [] });
+        let count = 0;
+        for (const row of result.rows) {
+            const id = row[columns.id];
+            const textParts = adapter.trigramFields(row).map(f => f.text).filter(Boolean);
+            const searchText = textParts.join(' ');
+            await updateSearchVector(id, searchText, tsConfig);
+            count++;
+        }
+        return count;
+    }
+    /**
+     * Re-derive all normalized columns from source data.
+     * Call after changing the normalize() function or locale.
+     */
+    async function renormalizeAll(updateRow) {
+        const result = await db.execute({ sql: `SELECT * FROM ${tables.entities}`, args: [] });
+        let count = 0;
+        for (const row of result.rows) {
+            await updateRow(db, row);
+            if (dialect === 'sqlite') {
+                const id = row[columns.id];
+                await indexTrigrams(id, row);
+            }
+            count++;
+        }
+        if (dialect === 'sqlite') {
+            await rebuildFts();
+        }
+        else {
+            await rebuildAllSearchVectors();
+        }
+        return count;
+    }
+    /**
+     * Set up PostgreSQL extensions and indexes needed for search.
+     * Call once during schema setup / migration.
+     */
+    async function setupPostgresExtensions() {
+        if (dialect !== 'postgres')
+            return;
+        // Enable pg_trgm extension
+        await db.execute({ sql: 'CREATE EXTENSION IF NOT EXISTS pg_trgm', args: [] });
+        // Create GIN index on the tsvector column for full-text search
+        const tsCol = tables.fts;
+        await db.execute({
+            sql: `CREATE INDEX IF NOT EXISTS idx_${tables.entities}_fts ON ${tables.entities} USING GIN (${tsCol})`,
+            args: [],
+        });
+        // Create GIN trigram indexes on normalized text columns
+        const trgmCols = [columns.nameNormalized];
+        if (columns.categoriesNormalized)
+            trgmCols.push(columns.categoriesNormalized);
+        if (columns.locationNormalized)
+            trgmCols.push(columns.locationNormalized);
+        for (const col of trgmCols) {
+            await db.execute({
+                sql: `CREATE INDEX IF NOT EXISTS idx_${tables.entities}_${col}_trgm ON ${tables.entities} USING GIN (${col} gin_trgm_ops)`,
+                args: [],
+            });
+        }
+    }
+    return {
+        indexTrigrams,
+        reindexAllTrigrams,
+        rebuildFts,
+        checkFtsSync,
+        updateSearchVector,
+        rebuildAllSearchVectors,
+        renormalizeAll,
+        setupPostgresExtensions,
+    };
+}
+export function createLookupsLoader(config) {
+    let _cached = null;
+    let _cacheTime = 0;
+    let _pending = null;
+    const ttl = config.cacheTtlMs ?? 5 * 60 * 1000;
+    async function load() {
+        const now = Date.now();
+        if (_cached && (now - _cacheTime) < ttl)
+            return _cached;
+        if (_pending)
+            return _pending;
+        _pending = reload();
+        try {
+            return await _pending;
+        }
+        finally {
+            _pending = null;
+        }
+    }
+    async function reload() {
+        const { db, locale } = config;
+        // Locations
+        const locationMap = new Map();
+        const locationEntityCount = new Map();
+        const locationGeo = new Map();
+        const locRows = await db.execute({ sql: config.locations.sql, args: [] });
+        for (const row of locRows.rows) {
+            locationMap.set(row[config.locations.nameNormalizedCol], row[config.locations.slugCol]);
+            if (config.locations.countCol) {
+                locationEntityCount.set(row[config.locations.slugCol], row[config.locations.countCol] ?? 0);
+            }
+            if (config.locations.latCol && config.locations.lngCol && config.locations.nameCol) {
+                const lat = row[config.locations.latCol];
+                const lng = row[config.locations.lngCol];
+                if (lat != null && lng != null) {
+                    locationGeo.set(row[config.locations.slugCol], {
+                        lat, lng, name: row[config.locations.nameCol],
+                    });
+                }
+            }
+        }
+        // Categories
+        const categoryMap = new Map();
+        const catRows = await db.execute({ sql: config.categories.sql, args: [] });
+        for (const row of catRows.rows) {
+            const nameN = row[config.categories.nameNormalizedCol];
+            const slug = row[config.categories.slugCol];
+            categoryMap.set(nameN, slug);
+            for (const word of nameN.split(/\s+/)) {
+                if (word && word.length > 2 && !categoryMap.has(word)) {
+                    categoryMap.set(word, slug);
+                }
+            }
+            if (config.categories.aliasesNormalizedCol) {
+                const aliasesN = row[config.categories.aliasesNormalizedCol] || '';
+                for (const alias of aliasesN.split(/\s+/)) {
+                    if (alias)
+                        categoryMap.set(alias, slug);
+                }
+            }
+        }
+        // Synonym expansion
+        if (config.synonymsSql) {
+            const synRows = await db.execute({ sql: config.synonymsSql, args: [] });
+            for (const row of synRows.rows) {
+                const alias = normalize(row.alias, locale);
+                const canonical = normalize(row.canonical, locale);
+                const category = row.category;
+                if (category === 'city' || category === 'location') {
+                    const slug = locationMap.get(canonical);
+                    if (slug)
+                        locationMap.set(alias, slug);
+                }
+                else if (category === 'style' || category === 'category') {
+                    const slug = categoryMap.get(canonical);
+                    if (slug)
+                        categoryMap.set(alias, slug);
+                }
+            }
+        }
+        // Areas/districts
+        const areaMap = new Map();
+        if (config.areas) {
+            const areaRows = await db.execute({ sql: config.areas.sql, args: [] });
+            for (const row of areaRows.rows) {
+                const locSlug = row[config.areas.locationSlugCol];
+                const areasJson = row[config.areas.areasJsonCol] || '[]';
+                const areas = JSON.parse(areasJson);
+                areaMap.set(locSlug, areas.map(a => normalize(a, locale)));
+            }
+        }
+        _cached = { locationMap, categoryMap, areaMap, locationEntityCount, locationGeo };
+        _cacheTime = Date.now();
+        return _cached;
+    }
+    function invalidate() {
+        _cached = null;
+        _cacheTime = 0;
+    }
+    return { load, invalidate };
+}
+const normalize = normalizeText;

package/dist/core/normalize.d.ts

@@ -0,0 +1,30 @@
+import type { SearchLocale } from './types.js';
+/** Strip diacritics using Unicode NFD decomposition (generic, all languages). */
+export declare function stripDiacriticsGeneric(text: string): string;
+/** Full normalization: lowercase + strip diacritics + collapse whitespace. */
+export declare function normalize(text: string, locale?: SearchLocale): string;
+/** Generate trigrams from text. "hatha" → ["hat","ath","tha"] */
+export declare function trigrams(text: string, locale?: SearchLocale): string[];
+/** Trigram similarity (Jaccard coefficient). 0..1, higher = more similar. */
+export declare function trigramSimilarity(a: string, b: string, locale?: SearchLocale): number;
+/** Levenshtein distance between two strings. */
+export declare function levenshtein(a: string, b: string): number;
+/** Normalized Levenshtein similarity. 0..1, higher = more similar. */
+export declare function levenshteinSimilarity(a: string, b: string, locale?: SearchLocale): number;
+/** Detect postcode format: XX-XXX or XXXXX (Polish default, override via locale). */
+export declare function isPostcode(text: string): boolean;
+/** Detect "near me" intent using locale geo patterns. */
+export declare function hasGeoIntent(query: string, locale?: SearchLocale): boolean;
+/** Remove geo-intent phrases from query. */
+export declare function stripGeoIntent(query: string, locale?: SearchLocale): string;
+/**
+ * Strip stop words/phrases from a NORMALIZED string.
+ * Strips geo intent phrases first, then multi-word stop phrases,
+ * then single stop tokens.
+ */
+export declare function stripStopWords(normalized: string, locale?: SearchLocale): string;
+/**
+ * Minimum token length for substring/prefix matching.
+ * Tokens shorter than this are too ambiguous for client-side matching.
+ */
+export declare const MIN_SEARCH_TOKEN_LENGTH = 3;

package/dist/core/normalize.js

@@ -0,0 +1,128 @@
+// ============================================================
+// @nomideusz/svelte-search — Text normalization
+// ============================================================
+// Generic normalization, trigrams, and similarity functions.
+// Locale-specific logic (diacritics, stop words) is injected
+// via SearchLocale.
+// ── Default diacritics (NFD decomposition) ─────────────────
+/** Strip diacritics using Unicode NFD decomposition (generic, all languages). */
+export function stripDiacriticsGeneric(text) {
+    return text.normalize('NFD').replace(/[\u0300-\u036f]/g, '');
+}
+/** Full normalization: lowercase + strip diacritics + collapse whitespace. */
+export function normalize(text, locale) {
+    if (!text)
+        return '';
+    const stripped = locale ? locale.stripDiacritics(text) : stripDiacriticsGeneric(text);
+    return stripped
+        .toLowerCase()
+        .replace(/[^a-z0-9\s-]/g, ' ')
+        .replace(/\s+/g, ' ')
+        .trim();
+}
+// ── Trigrams ───────────────────────────────────────────────
+/** Generate trigrams from text. "hatha" → ["hat","ath","tha"] */
+export function trigrams(text, locale) {
+    const n = normalize(text, locale);
+    if (n.length < 3)
+        return n ? [n] : [];
+    const result = [];
+    for (const word of n.split(/\s+/)) {
+        if (word.length < 3) {
+            result.push(word);
+            continue;
+        }
+        for (let i = 0; i <= word.length - 3; i++)
+            result.push(word.slice(i, i + 3));
+    }
+    return [...new Set(result)];
+}
+// ── Similarity ─────────────────────────────────────────────
+/** Trigram similarity (Jaccard coefficient). 0..1, higher = more similar. */
+export function trigramSimilarity(a, b, locale) {
+    const tA = new Set(trigrams(a, locale));
+    const tB = new Set(trigrams(b, locale));
+    if (tA.size === 0 && tB.size === 0)
+        return 1;
+    if (tA.size === 0 || tB.size === 0)
+        return 0;
+    let intersection = 0;
+    for (const t of tA)
+        if (tB.has(t))
+            intersection++;
+    return intersection / (tA.size + tB.size - intersection);
+}
+/** Levenshtein distance between two strings. */
+export function levenshtein(a, b) {
+    if (a.length === 0)
+        return b.length;
+    if (b.length === 0)
+        return a.length;
+    let prev = Array.from({ length: b.length + 1 }, (_, i) => i);
+    let curr = new Array(b.length + 1);
+    for (let i = 1; i <= a.length; i++) {
+        curr[0] = i;
+        for (let j = 1; j <= b.length; j++) {
+            curr[j] = Math.min(prev[j] + 1, curr[j - 1] + 1, prev[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+        }
+        [prev, curr] = [curr, prev];
+    }
+    return prev[b.length];
+}
+/** Normalized Levenshtein similarity. 0..1, higher = more similar. */
+export function levenshteinSimilarity(a, b, locale) {
+    const na = normalize(a, locale), nb = normalize(b, locale);
+    const max = Math.max(na.length, nb.length);
+    return max === 0 ? 1 : 1 - levenshtein(na, nb) / max;
+}
+/** Detect postcode format: XX-XXX or XXXXX (Polish default, override via locale). */
+export function isPostcode(text) {
+    return /^\d{2}-?\d{3}$/.test(text.trim());
+}
+// ── Geo intent ─────────────────────────────────────────────
+/** Detect "near me" intent using locale geo patterns. */
+export function hasGeoIntent(query, locale) {
+    if (!locale)
+        return false;
+    const n = locale.stripDiacritics(query).toLowerCase();
+    return locale.geoPatterns.some(p => p.test(n));
+}
+/** Remove geo-intent phrases from query. */
+export function stripGeoIntent(query, locale) {
+    if (!locale)
+        return query;
+    let q = locale.stripDiacritics(query).toLowerCase();
+    for (const p of locale.geoPatterns)
+        q = q.replace(p, '');
+    return q.replace(/\s+/g, ' ').trim();
+}
+// ── Stop words ─────────────────────────────────────────────
+/**
+ * Strip stop words/phrases from a NORMALIZED string.
+ * Strips geo intent phrases first, then multi-word stop phrases,
+ * then single stop tokens.
+ */
+export function stripStopWords(normalized, locale) {
+    if (!locale)
+        return normalized;
+    let result = normalized;
+    // Geo intent phrases first (before single-token stripping splits them)
+    for (const p of locale.geoPatterns)
+        result = result.replace(p, ' ');
+    // Multi-word stop phrases (longest first to avoid partial stripping)
+    const sorted = [...locale.stopPhrases].sort((a, b) => b.length - a.length);
+    for (const phrase of sorted) {
+        result = result.replace(new RegExp(`\\b${phrase}\\b`, 'g'), ' ');
+    }
+    // Single-word stop tokens
+    result = result
+        .split(/\s+/)
+        .filter(t => !locale.stopTokens.has(t))
+        .join(' ');
+    return result.replace(/\s+/g, ' ').trim();
+}
+/**
+ * Minimum token length for substring/prefix matching.
+ * Tokens shorter than this are too ambiguous for client-side matching.
+ */
+export const MIN_SEARCH_TOKEN_LENGTH = 3;

package/dist/core/resolver.d.ts

@@ -0,0 +1,41 @@
+import type { SearchLocale, ResolverLookups } from './types.js';
+interface TokenMatch {
+    matched: string;
+    slug: string;
+    original: string;
+}
+export interface ParsedQuery {
+    /** Original normalized query */
+    normalized: string;
+    /** Query after stop word removal */
+    working: string;
+    /** Whether geo intent was detected */
+    geoIntent: boolean;
+    /** Extracted postal code, if any */
+    postal: string | undefined;
+    /** Matched location token */
+    location: TokenMatch | null;
+    /** Matched category token */
+    category: TokenMatch | null;
+    /** Remaining unclassified tokens */
+    rest: string[];
+}
+/**
+ * Parse and classify a raw search query.
+ * Reusable by any app — the classification is the same,
+ * only the dispatch logic differs.
+ */
+export declare function parseQuery(raw: string, lookups: ResolverLookups, locale?: SearchLocale): ParsedQuery;
+/** Check if query matches an area/district in the given location. */
+export declare function findMatchingArea(query: string, locationSlug: string, lookups: ResolverLookups, locale?: SearchLocale): string | null;
+/**
+ * Find the nearest location that has entities.
+ * Useful for "no results" states.
+ */
+export declare function findNearestLocationWithEntities(lat: number, lng: number, lookups: ResolverLookups, excludeSlug?: string): {
+    name: string;
+    slug: string;
+    distanceKm: number;
+    count: number;
+} | null;
+export {};

package/dist/core/resolver.js

@@ -0,0 +1,107 @@
+// ============================================================
+// @nomideusz/svelte-search — Resolver framework
+// ============================================================
+// Generic query resolver: classifies tokens (location, category,
+// area, unclassified) and dispatches to page-specific handlers.
+// Apps provide their own dispatch rules via createResolver().
+import { normalize, hasGeoIntent, stripGeoIntent, stripStopWords, isPostcode } from './normalize.js';
+function matchToken(tokens, lookup, locale) {
+    // Try bigrams first
+    for (let i = 0; i < tokens.length - 1; i++) {
+        const bigram = `${tokens[i]} ${tokens[i + 1]}`;
+        const slug = lookup.get(bigram);
+        if (slug)
+            return { matched: bigram, slug, original: bigram };
+    }
+    // Single tokens (with optional locale stemming)
+    for (const t of tokens) {
+        const slug = lookup.get(t);
+        if (slug)
+            return { matched: t, slug, original: t };
+        // Try locale-specific stems (e.g. Polish case forms)
+        if (locale?.locationStems) {
+            for (const stem of locale.locationStems(t)) {
+                if (stem === t)
+                    continue;
+                const stemSlug = lookup.get(stem);
+                if (stemSlug)
+                    return { matched: t, slug: stemSlug, original: t };
+            }
+        }
+    }
+    return null;
+}
+function matchesArea(query, area) {
+    if (query === area)
+        return true;
+    const re = new RegExp(`(?:^|\\s)${area.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}(?:\\s|$)`);
+    return re.test(query);
+}
+/**
+ * Parse and classify a raw search query.
+ * Reusable by any app — the classification is the same,
+ * only the dispatch logic differs.
+ */
+export function parseQuery(raw, lookups, locale) {
+    const normalized = normalize(raw, locale);
+    if (!normalized) {
+        return { normalized: '', working: '', geoIntent: false, postal: undefined, location: null, category: null, rest: [] };
+    }
+    let working = stripStopWords(normalized, locale);
+    if (!working) {
+        return { normalized, working: '', geoIntent: false, postal: undefined, location: null, category: null, rest: [] };
+    }
+    // Geo intent
+    const geoIntent = hasGeoIntent(raw, locale);
+    if (geoIntent) {
+        working = stripGeoIntent(working, locale);
+    }
+    // Postal code
+    const postalMatch = working.match(/\b(\d{2})-?(\d{3})\b/);
+    let postal;
+    if (postalMatch) {
+        postal = `${postalMatch[1]}-${postalMatch[2]}`;
+        working = working.replace(postalMatch[0], '').replace(/\s+/g, ' ').trim();
+    }
+    if (!working) {
+        return { normalized, working: '', geoIntent, postal, location: null, category: null, rest: [] };
+    }
+    // Tokenize and classify
+    const tokens = working.split(/\s+/).filter(Boolean);
+    const location = matchToken(tokens, lookups.locationMap, locale);
+    const category = matchToken(tokens, lookups.categoryMap, locale);
+    const rest = tokens.filter(t => t !== location?.matched && t !== category?.matched);
+    return { normalized, working, geoIntent, postal, location, category, rest };
+}
+// ── Dispatch helpers ───────────────────────────────────────
+// Common action patterns used by app-specific resolvers.
+/** Check if query matches an area/district in the given location. */
+export function findMatchingArea(query, locationSlug, lookups, locale) {
+    const areas = lookups.areaMap.get(locationSlug) ?? [];
+    const normalized = normalize(query, locale);
+    return areas.find(a => matchesArea(normalized, a)) ?? null;
+}
+/**
+ * Find the nearest location that has entities.
+ * Useful for "no results" states.
+ */
+export function findNearestLocationWithEntities(lat, lng, lookups, excludeSlug) {
+    if (!lookups.locationEntityCount || !lookups.locationGeo)
+        return null;
+    let best = null;
+    let bestDist = Infinity;
+    for (const [slug, geo] of lookups.locationGeo) {
+        const count = lookups.locationEntityCount.get(slug) ?? 0;
+        if (count === 0 || slug === excludeSlug)
+            continue;
+        const dlat = (geo.lat - lat) * Math.PI / 180;
+        const dlng = (geo.lng - lng) * Math.PI / 180;
+        const a = Math.sin(dlat / 2) ** 2 + Math.cos(lat * Math.PI / 180) * Math.cos(geo.lat * Math.PI / 180) * Math.sin(dlng / 2) ** 2;
+        const d = 6371 * 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1 - a));
+        if (d < bestDist) {
+            bestDist = d;
+            best = { slug, name: geo.name, count, distanceKm: Math.round(d) };
+        }
+    }
+    return best;
+}

package/dist/core/track.d.ts

@@ -0,0 +1,10 @@
+import type { TrackSearchEvent } from './types.js';
+export interface TrackerConfig {
+    /** API endpoint to POST events to (default: '/api/search-events') */
+    endpoint?: string;
+    /** sessionStorage key (default: 'search_sid') */
+    sessionKey?: string;
+}
+export declare function createTracker(config?: TrackerConfig): {
+    track: (event: TrackSearchEvent) => void;
+};

package/dist/core/track.js

@@ -0,0 +1,40 @@
+// ============================================================
+// @nomideusz/svelte-search — Search event tracker
+// ============================================================
+// Lightweight fire-and-forget search analytics.
+// No PII — sessionId is a random UUID in sessionStorage.
+export function createTracker(config = {}) {
+    const endpoint = config.endpoint ?? '/api/search-events';
+    const sessionKey = config.sessionKey ?? 'search_sid';
+    function getSessionId() {
+        if (typeof sessionStorage === 'undefined')
+            return '';
+        let sid = sessionStorage.getItem(sessionKey);
+        if (!sid) {
+            sid = crypto.randomUUID();
+            sessionStorage.setItem(sessionKey, sid);
+        }
+        return sid;
+    }
+    function track(event) {
+        try {
+            const body = { ...event, sessionId: getSessionId() };
+            const payload = JSON.stringify(body);
+            if (typeof navigator !== 'undefined' && navigator.sendBeacon) {
+                navigator.sendBeacon(endpoint, new Blob([payload], { type: 'application/json' }));
+            }
+            else if (typeof fetch !== 'undefined') {
+                fetch(endpoint, {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json' },
+                    body: payload,
+                    keepalive: true,
+                }).catch(() => { });
+            }
+        }
+        catch {
+            // Never fail the user experience for tracking
+        }
+    }
+    return { track };
+}