@nomideusz/svelte-search 0.1.0

package/dist/core/types.d.ts

@@ -0,0 +1,206 @@
+/** SQL dialect for query generation. */
+export type SqlDialect = 'sqlite' | 'postgres';
+export interface DatabaseClient {
+    execute(query: {
+        sql: string;
+        args: unknown[];
+    } | string): Promise<{
+        rows: Record<string, unknown>[];
+        lastInsertRowid?: bigint | number;
+    }>;
+}
+export interface SchemaAdapter<TResult extends SearchResult = SearchResult> {
+    /** Table names in your database */
+    tables: {
+        /** Main entities table (e.g. "schools", "tours", "listings") */
+        entities: string;
+        /** Trigram index table (e.g. "school_trigrams", "tour_trigrams") */
+        trigrams: string;
+        /** FTS5 virtual table (e.g. "schools_fts", "tours_fts") */
+        fts: string;
+        /** Synonyms table (e.g. "search_synonyms") */
+        synonyms: string;
+    };
+    /** Column names in the entities table */
+    columns: {
+        /** Primary key column */
+        id: string;
+        /** Display name column */
+        name: string;
+        /** Normalized name column (for matching) */
+        nameNormalized: string;
+        /** URL slug column */
+        slug: string;
+        /** Latitude column (null if no geo) */
+        lat: string | null;
+        /** Longitude column (null if no geo) */
+        lng: string | null;
+        /** Location slug column (e.g. "city_slug", "destination_slug") */
+        locationSlug: string | null;
+        /** Normalized categories column (e.g. "styles_n", "categories_n") */
+        categoriesNormalized: string | null;
+        /** Normalized location name (e.g. "city_n", "destination_n") */
+        locationNormalized: string | null;
+        /** Normalized district/area column (e.g. "district_n", "area_n") */
+        areaNormalized: string | null;
+    };
+    /** Trigram table columns */
+    trigramColumns: {
+        /** Trigram value column */
+        trigram: string;
+        /** Foreign key to entity */
+        entityId: string;
+        /** Field name column (e.g. "name", "city", "style") */
+        field: string;
+    };
+    /** Convert a raw DB row to a typed SearchResult */
+    toResult(row: Record<string, unknown>, lat?: number, lng?: number): TResult;
+    /** Fields to extract trigrams from when indexing an entity */
+    trigramFields(entity: Record<string, unknown>): Array<{
+        text: string | null | undefined;
+        field: string;
+    }>;
+}
+export interface SearchParams {
+    /** User's search query */
+    query: string;
+    /** Restrict to this location slug (e.g. city) */
+    locationSlug?: string;
+    /** Restrict to this category slug (e.g. style) */
+    categorySlug?: string;
+    /** User's latitude for geo proximity */
+    lat?: number;
+    /** User's longitude for geo proximity */
+    lng?: number;
+    /** Max results to return */
+    limit?: number;
+    /** Offset for pagination */
+    offset?: number;
+}
+export interface SearchResult {
+    id: string;
+    name: string;
+    slug: string;
+    lat: number | null;
+    lng: number | null;
+    distanceKm: number | null;
+    walkingMin: number | null;
+    score: number;
+    /** @internal FTS match flag for quality gate */
+    _hasFts?: boolean;
+    /** @internal Normalized name for quality check */
+    _nameN?: string;
+    /** @internal Normalized location for quality check */
+    _locationN?: string;
+    /** @internal Normalized categories for quality check */
+    _categoriesN?: string;
+}
+export interface SearchResponse<TResult extends SearchResult = SearchResult> {
+    /** Primary results (within relevance boundary) */
+    results: TResult[];
+    /** "Also within reach" results (just outside primary radius) */
+    nearby: TResult[];
+    /** True if we had location intent but found nothing nearby */
+    noLocalResults: boolean;
+    /** The place the user searched for */
+    searchedPlace: string | null;
+    /** Nearest location that has entities (when noLocalResults=true) */
+    nearestLocationWithEntities: {
+        name: string;
+        slug: string;
+        distanceKm: number;
+        count: number;
+    } | null;
+    /** Total matched before pagination */
+    totalFound: number;
+}
+export interface AutocompleteResult {
+    text: string;
+    type: string;
+    slug?: string;
+}
+export interface SearchLocale {
+    /** Strip diacritics specific to this locale */
+    stripDiacritics(text: string): string;
+    /** Stop words to remove from queries */
+    stopTokens: Set<string>;
+    /** Multi-word stop phrases (checked before single tokens) */
+    stopPhrases: string[];
+    /** Geo intent patterns (e.g. "near me", "blisko") */
+    geoPatterns: RegExp[];
+    /** Stem location names to nominative form. Returns [original, ...stems] */
+    locationStems?(token: string): string[];
+}
+export interface ResolverContext {
+    page: string;
+    [key: string]: unknown;
+}
+export interface ResolverLookups {
+    /** Normalized location name → slug */
+    locationMap: Map<string, string>;
+    /** Normalized category name/alias → slug */
+    categoryMap: Map<string, string>;
+    /** locationSlug → list of normalized area/district names */
+    areaMap: Map<string, string[]>;
+    /** locationSlug → entity count */
+    locationEntityCount?: Map<string, number>;
+    /** locationSlug → { lat, lng, name } */
+    locationGeo?: Map<string, {
+        lat: number;
+        lng: number;
+        name: string;
+    }>;
+}
+export type ResolverAction = {
+    action: 'route_to_location';
+    locationSlug: string;
+    categoryFilter?: string;
+} | {
+    action: 'route_to_category';
+    categorySlug: string;
+    locationFilter?: string;
+} | {
+    action: 'route_to_entity';
+    entitySlug: string;
+} | {
+    action: 'filter';
+    query: string;
+} | {
+    action: 'filter_area';
+    area: string;
+} | {
+    action: 'filter_postcode';
+    postcode: string;
+    filter?: string;
+} | {
+    action: 'sort_by_distance';
+    filter?: string;
+} | {
+    action: 'show_all';
+} | {
+    action: 'location_switch_prompt';
+    targetName: string;
+    targetSlug: string;
+    categoryFilter?: string;
+    address?: string;
+} | {
+    action: 'already_here';
+} | {
+    action: 'needs_server';
+    query: string;
+} | {
+    action: 'geocode_address';
+    address: string;
+    locationSlug: string;
+};
+export interface TrackSearchEvent {
+    query: string;
+    queryNormalized?: string;
+    page: string;
+    locationContext?: string;
+    action: string;
+    layer?: 'client' | 'server' | 'google' | 'none';
+    resultCount?: number;
+    clickedType?: string;
+    clickedId?: string;
+}

package/dist/core/types.js

@@ -0,0 +1,6 @@
+// ============================================================
+// @nomideusz/svelte-search — Core types
+// ============================================================
+// Generic search types. Apps provide a SchemaAdapter to map
+// their DB schema to these interfaces.
+export {};

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export type { SqlDialect, DatabaseClient, SchemaAdapter, SearchParams, SearchResult, SearchResponse, AutocompleteResult, SearchLocale, ResolverContext, ResolverLookups, ResolverAction, TrackSearchEvent, } from './core/types.js';
+export { haversineKm, walkingMinutes, boundingBox, formatDistance, formatWalkingTime, walkingRoute, } from './core/geo.js';
+export { normalize, stripDiacriticsGeneric, trigrams, trigramSimilarity, levenshtein, levenshteinSimilarity, isPostcode, hasGeoIntent, stripGeoIntent, stripStopWords, MIN_SEARCH_TOKEN_LENGTH, } from './core/normalize.js';
+export { createSearchEngine, type SearchEngineConfig } from './core/engine.js';
+export { createIndexer, createLookupsLoader, type IndexerConfig, type LoadLookupsConfig } from './core/indexer.js';
+export { parseQuery, findMatchingArea, findNearestLocationWithEntities, type ParsedQuery } from './core/resolver.js';
+export { createTracker, type TrackerConfig } from './core/track.js';

package/dist/index.js

@@ -0,0 +1,14 @@
+// @nomideusz/svelte-search — Public API
+// ============================================================
+// Geo utilities
+export { haversineKm, walkingMinutes, boundingBox, formatDistance, formatWalkingTime, walkingRoute, } from './core/geo.js';
+// Normalization & similarity
+export { normalize, stripDiacriticsGeneric, trigrams, trigramSimilarity, levenshtein, levenshteinSimilarity, isPostcode, hasGeoIntent, stripGeoIntent, stripStopWords, MIN_SEARCH_TOKEN_LENGTH, } from './core/normalize.js';
+// Search engine
+export { createSearchEngine } from './core/engine.js';
+// Indexer
+export { createIndexer, createLookupsLoader } from './core/indexer.js';
+// Resolver
+export { parseQuery, findMatchingArea, findNearestLocationWithEntities } from './core/resolver.js';
+// Tracker
+export { createTracker } from './core/track.js';

package/dist/locales/pl.d.ts

@@ -0,0 +1,11 @@
+import type { SearchLocale } from '../core/types.js';
+declare function stripPolishDiacritics(text: string): string;
+declare function polishLocationStems(token: string): string[];
+declare const LOCATIVE_IRREGULARS: Record<string, string>;
+/**
+ * Polish locative case for city names.
+ * "Kraków" → "Krakowie", used in "w Krakowie" (in Kraków).
+ */
+export declare function polishLocative(city: string): string;
+export declare const plLocale: SearchLocale;
+export { polishLocationStems, stripPolishDiacritics, LOCATIVE_IRREGULARS };

package/dist/locales/pl.js

@@ -0,0 +1,266 @@
+// ============================================================
+// @nomideusz/svelte-search — Polish locale
+// ============================================================
+// Polish-specific search features: diacritics, stop words,
+// geo intent patterns, city name stemming, locative case.
+// ── Diacritics ─────────────────────────────────────────────
+const PL_DIACRITICS = {
+    'ą': 'a', 'Ą': 'A', 'ć': 'c', 'Ć': 'C', 'ę': 'e', 'Ę': 'E',
+    'ł': 'l', 'Ł': 'L', 'ń': 'n', 'Ń': 'N', 'ó': 'o', 'Ó': 'O',
+    'ś': 's', 'Ś': 'S', 'ź': 'z', 'Ź': 'Z', 'ż': 'z', 'Ż': 'Z',
+};
+function stripPolishDiacritics(text) {
+    let r = '';
+    for (const c of text)
+        r += PL_DIACRITICS[c] ?? c;
+    return r.normalize('NFD').replace(/[\u0300-\u036f]/g, '');
+}
+// ── Stop words ─────────────────────────────────────────────
+const PL_STOP_PHRASES = [
+    'szkola jogi', 'szkoly jogi',
+    'studio jogi', 'studia jogi',
+    'zajecia jogi', 'lekcje jogi', 'klasy jogi',
+    'yoga studio', 'yoga school', 'yoga class',
+];
+const PL_STOP_TOKENS = new Set([
+    // Site-generic
+    'joga', 'yoga',
+    // Polish prepositions & particles
+    'w', 'z', 'na', 'do', 'od', 'dla', 'i', 'o', 'u', 'ze',
+    'przy', 'po', 'pod', 'nad', 'za', 'przed', 'miedzy', 'lub',
+    // Common filler words
+    'sie', 'jak', 'co', 'to', 'jest', 'sa', 'nie', 'tak', 'czy',
+    'tu', 'tam', 'ten', 'ta', 'te',
+    // Common in location queries
+    'okolicy', 'okolice', 'okolica', 'okolicach', 'okolicami',
+    'poblizu', 'rejon', 'rejonie', 'rejonu',
+    'sasiedztwie', 'centrum', 'okolo',
+    'praca', 'kurs', 'kursy', 'lekcje', 'zajecia', 'treningi',
+]);
+// ── Geo intent patterns ────────────────────────────────────
+const PL_GEO_PATTERNS = [
+    /\bblisko\s+mnie\b/i,
+    /\bblisko\b/i,
+    /\bniedaleko\b/i,
+    /\bw\s+poblizu\b/i,
+    /\bobok\b/i,
+    /\bw\s+okolic\w*\b/i,
+    /\bnajblizej\b/i,
+    /\bnajblizsz\w*/i,
+    /\bkolo\s+mnie\b/i,
+    /\bw\s+sasiedztwie\b/i,
+    /\bw\s+moim\s+rejonie\b/i,
+    // English (universal)
+    /\bnear\s*me\b/i,
+    /\bnearby\b/i,
+    /\bclosest\b/i,
+    /\baround\s+me\b/i,
+];
+// ── City name stemming ─────────────────────────────────────
+const STEM_RULES = [
+    [/owie$/, 'ow'],
+    [/odzi$/, 'odz'],
+    [/owej$/, 'owa'],
+    [/ach$/, ''],
+    [/ami$/, ''],
+    [/nie$/, 'n'],
+    [/cie$/, 'c'],
+    [/zie$/, 'z'],
+    [/skie$/, 'sk'],
+    [/y$/, ''],
+    [/i$/, ''],
+    [/e$/, ''],
+    [/u$/, ''],
+];
+function stemWord(word) {
+    const stems = [word];
+    for (const [re, replacement] of STEM_RULES) {
+        if (re.test(word)) {
+            const stem = word.replace(re, replacement);
+            if (stem.length >= 3 && stem !== word)
+                stems.push(stem);
+        }
+    }
+    return stems;
+}
+function polishLocationStems(token) {
+    const words = token.split(/\s+/);
+    if (words.length === 1)
+        return stemWord(token);
+    const wordStems = words.map(w => stemWord(w));
+    const results = new Set([token]);
+    function combine(idx, current) {
+        if (idx === wordStems.length) {
+            results.add(current.join(' '));
+            return;
+        }
+        for (const stem of wordStems[idx]) {
+            current.push(stem);
+            combine(idx + 1, current);
+            current.pop();
+        }
+    }
+    combine(0, []);
+    return [...results];
+}
+// ── Polish locative case ───────────────────────────────────
+// Used for display: "w Krakowie", "w Łodzi", "w Warszawie"
+const LOCATIVE_IRREGULARS = {
+    'Kraków': 'Krakowie',
+    'Wrocław': 'Wrocławiu',
+    'Łódź': 'Łodzi',
+    'Poznań': 'Poznaniu',
+    'Gdańsk': 'Gdańsku',
+    'Gdynia': 'Gdyni',
+    'Szczecin': 'Szczecinie',
+    'Bydgoszcz': 'Bydgoszczy',
+    'Lublin': 'Lublinie',
+    'Białystok': 'Białymstoku',
+    'Katowice': 'Katowicach',
+    'Częstochowa': 'Częstochowie',
+    'Radom': 'Radomiu',
+    'Sosnowiec': 'Sosnowcu',
+    'Toruń': 'Toruniu',
+    'Kielce': 'Kielcach',
+    'Rzeszów': 'Rzeszowie',
+    'Gliwice': 'Gliwicach',
+    'Olsztyn': 'Olsztynie',
+    'Zabrze': 'Zabrzu',
+    'Opole': 'Opolu',
+    'Tychy': 'Tychach',
+    'Płock': 'Płocku',
+    'Elbląg': 'Elblągu',
+    'Tarnów': 'Tarnowie',
+    'Chorzów': 'Chorzowie',
+    'Bytom': 'Bytomiu',
+    'Piła': 'Pile',
+    'Legnica': 'Legnicy',
+    'Jaworzno': 'Jaworznie',
+    'Siedlce': 'Siedlcach',
+    'Mysłowice': 'Mysłowicach',
+    'Konin': 'Koninie',
+    'Inowrocław': 'Inowrocławiu',
+    'Skierniewice': 'Skierniewicach',
+    'Sopot': 'Sopocie',
+    'Warszawa': 'Warszawie',
+    'Bełchatów': 'Bełchatowie',
+    'Bielany Wrocławskie': 'Bielanach Wrocławskich',
+    'Borkowo': 'Borkowie',
+    'Brzozówka': 'Brzozówce',
+    'Czeladź': 'Czeladzi',
+    'Górki': 'Górkach',
+    'Kamionki': 'Kamionkach',
+    'Komorniki': 'Komornikach',
+    'Konstantynów Łódzki': 'Konstantynowie Łódzkim',
+    'Kowale': 'Kowalach',
+    'Koziegłowy': 'Koziegłowach',
+    'Luboń': 'Luboniu',
+    'Mierzyn': 'Mierzynie',
+    'Mikołów': 'Mikołowie',
+    'Monte': 'Monte',
+    'Niemcz': 'Niemczu',
+    'Osielsko': 'Osielsku',
+    'Owińska': 'Owińskach',
+    'Piekary Śląskie': 'Piekarach Śląskich',
+    'Pilchowice': 'Pilchowicach',
+    'Plewiska': 'Plewiskach',
+    'Przeźmierowo': 'Przeźmierowie',
+    'Sierosław': 'Sierosławiu',
+    'Skórzewo': 'Skórzewie',
+    'Suchy Dwór': 'Suchym Dworze',
+    'Suchy Las': 'Suchym Lesie',
+    'Wiry': 'Wirach',
+    'Wola Kopcowa': 'Woli Kopcowej',
+    'Wysoka': 'Wysokiej',
+    'Zgierz': 'Zgierzu',
+    // Adjective-level irregulars (for multi-word names)
+    'Ruda': 'Rudzie', 'Wola': 'Woli', 'Dąbrowa': 'Dąbrowie',
+    'Nowy': 'Nowym', 'Nowa': 'Nowej', 'Stary': 'Starym', 'Stara': 'Starej',
+    'Wielka': 'Wielkiej', 'Wielki': 'Wielkim',
+    'Mały': 'Małym', 'Mała': 'Małej',
+    'Dolna': 'Dolnej', 'Dolny': 'Dolnym',
+    'Górna': 'Górnej', 'Górny': 'Górnym',
+    'Suchy': 'Suchym', 'Sucha': 'Suchej',
+};
+function locativeWord(w) {
+    if (LOCATIVE_IRREGULARS[w])
+        return LOCATIVE_IRREGULARS[w];
+    // Adjective endings
+    if (w.endsWith('owa'))
+        return w.slice(0, -1) + 'ej';
+    if (w.endsWith('owy'))
+        return w.slice(0, -1) + 'ym';
+    if (w.endsWith('ska'))
+        return w.slice(0, -1) + 'iej';
+    if (w.endsWith('cka'))
+        return w.slice(0, -1) + 'iej';
+    if (w.endsWith('ski') || w.endsWith('cki'))
+        return w + 'm';
+    if (w.endsWith('na'))
+        return w.slice(0, -1) + 'ej';
+    if (w.endsWith('ny'))
+        return w.slice(0, -1) + 'ym';
+    if (w.endsWith('cza'))
+        return w.slice(0, -1) + 'ej';
+    if (w.endsWith('sza'))
+        return w.slice(0, -1) + 'ej';
+    if (w.endsWith('ła'))
+        return w.slice(0, -1) + 'ej';
+    if (w.endsWith('ły'))
+        return w.slice(0, -1) + 'ym';
+    // Noun endings
+    if (w.endsWith('ów'))
+        return w.slice(0, -2) + 'owie';
+    if (w.endsWith('ław'))
+        return w + 'iu';
+    if (w.endsWith('in') || w.endsWith('yn'))
+        return w + 'ie';
+    if (w.endsWith('ań') || w.endsWith('eń') || w.endsWith('uń'))
+        return w.slice(0, -1) + 'niu';
+    if (w.endsWith('ek'))
+        return w.slice(0, -2) + 'ku';
+    if (w.endsWith('ice') || w.endsWith('yce'))
+        return w.slice(0, -1) + 'ach';
+    if (w.endsWith('la'))
+        return w.slice(0, -1) + 'i';
+    if (w.endsWith('a'))
+        return w.slice(0, -1) + 'ie';
+    if (w.endsWith('o'))
+        return w.slice(0, -1) + 'ie';
+    if (w.endsWith('e'))
+        return w.slice(0, -1) + 'u';
+    if (w.endsWith('y'))
+        return w.slice(0, -1) + 'ach';
+    if (/(?:k|g|ch|sz|cz|rz|ż|ąg|ąk)$/.test(w))
+        return w + 'u';
+    return w + 'ie';
+}
+/**
+ * Polish locative case for city names.
+ * "Kraków" → "Krakowie", used in "w Krakowie" (in Kraków).
+ */
+export function polishLocative(city) {
+    const c = city.trim();
+    if (LOCATIVE_IRREGULARS[c])
+        return LOCATIVE_IRREGULARS[c];
+    // Multi-word names: decline each word separately
+    const parts = c.split(/(\s+|-)/);
+    if (parts.filter(p => p.trim() && p !== '-').length > 1) {
+        return parts.map(p => {
+            if (!p.trim() || p === '-')
+                return p;
+            return locativeWord(p);
+        }).join('');
+    }
+    return locativeWord(c);
+}
+// ── Export locale ──────────────────────────────────────────
+export const plLocale = {
+    stripDiacritics: stripPolishDiacritics,
+    stopTokens: PL_STOP_TOKENS,
+    stopPhrases: PL_STOP_PHRASES,
+    geoPatterns: PL_GEO_PATTERNS,
+    locationStems: polishLocationStems,
+};
+// Re-export individual pieces for apps that need them directly
+export { polishLocationStems, stripPolishDiacritics, LOCATIVE_IRREGULARS };

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@nomideusz/svelte-search",
+  "version": "0.1.0",
+  "description": "Full-text search engine for Svelte 5 apps — FTS5, trigram fuzzy matching, geo proximity, autocomplete, Polish locale support.",
+  "type": "module",
+  "license": "MIT",
+  "svelte": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "svelte": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./locales/pl": {
+      "types": "./dist/locales/pl.d.ts",
+      "default": "./dist/locales/pl.js"
+    }
+  },
+  "files": [
+    "dist",
+    "CHANGELOG.md",
+    "!dist/**/*.test.*",
+    "!dist/**/*.spec.*"
+  ],
+  "peerDependencies": {
+    "svelte": "^5.0.0"
+  },
+  "devDependencies": {
+    "@sveltejs/adapter-auto": "^7.0.0",
+    "@sveltejs/kit": "^2.50.2",
+    "@sveltejs/package": "^2.5.7",
+    "@sveltejs/vite-plugin-svelte": "^6.2.4",
+    "svelte": "^5.51.0",
+    "svelte-check": "^4.3.6",
+    "typescript": "^5.9.3",
+    "vite": "^7.3.1",
+    "vitest": "^4.0.18"
+  },
+  "keywords": [
+    "svelte",
+    "search",
+    "fts5",
+    "trigram",
+    "fuzzy",
+    "geo",
+    "autocomplete",
+    "polish",
+    "sqlite",
+    "postgres"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nomideusz/asini"
+  },
+  "scripts": {
+    "dev": "vite dev",
+    "build": "vite build",
+    "package": "svelte-kit sync && svelte-package",
+    "preview": "vite preview",
+    "check": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json",
+    "check:watch": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json --watch",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}