@byline/search-mysql 4.9.0

package/dist/errors.js

@@ -0,0 +1,22 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+export class SearchAnalyzerMismatchError extends Error {
+    collectionPath;
+    expectedFingerprint;
+    actualFingerprint;
+    code = 'SEARCH_INDEX_REINDEX_REQUIRED';
+    constructor(collectionPath, expectedFingerprint, actualFingerprint) {
+        super(`Search index for collection "${collectionPath}" uses analyzer fingerprint ` +
+            `"${actualFingerprint ?? '(missing)'}", but "${expectedFingerprint}" is configured. ` +
+            'Clear and rebuild this collection before searching or indexing it.');
+        this.collectionPath = collectionPath;
+        this.expectedFingerprint = expectedFingerprint;
+        this.actualFingerprint = actualFingerprint;
+        this.name = 'SearchAnalyzerMismatchError';
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,28 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+import type { SearchProvider } from '@byline/core';
+import { type PortableSearchAnalyzer } from '@byline/search-analysis';
+import type { Pool } from 'mysql2/promise';
+export { buildIndexRow, type IndexRow, type WeightClass, weightClass } from './build-index-row.js';
+export { SearchAnalyzerMismatchError } from './errors.js';
+export { type MigrateOptions, type MigrateResult, migrate } from './migrate.js';
+export { MySqlSearchProvider } from './mysql-search-provider.js';
+export interface MySqlSearchOptions {
+    /** The host's existing mysql2 promise pool, normally `db.pool`. */
+    pool: Pool;
+    /** Development convenience; production should await `migrate(pool)`. */
+    autoMigrate?: boolean;
+    /** Portable analyzer fallback locale. Defaults to `en`. */
+    defaultLocale?: string;
+    /** Custom versioned portable analyzer. */
+    analyzer?: PortableSearchAnalyzer;
+    /** Optional migration progress sink. */
+    log?: (message: string) => void;
+}
+/** Construct the MySQL FULLTEXT provider while reusing the host pool. */
+export declare function mysqlSearch(options: MySqlSearchOptions): SearchProvider;

package/dist/index.js

@@ -0,0 +1,28 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+import { createPortableSearchAnalyzer } from '@byline/search-analysis';
+import { migrate } from './migrate.js';
+import { MySqlSearchProvider } from './mysql-search-provider.js';
+export { buildIndexRow, weightClass } from './build-index-row.js';
+export { SearchAnalyzerMismatchError } from './errors.js';
+export { migrate } from './migrate.js';
+export { MySqlSearchProvider } from './mysql-search-provider.js';
+/** Construct the MySQL FULLTEXT provider while reusing the host pool. */
+export function mysqlSearch(options) {
+    const analyzer = options.analyzer ?? createPortableSearchAnalyzer({ defaultLocale: options.defaultLocale });
+    if (options.autoMigrate === true) {
+        void migrate(options.pool, { log: options.log }).catch((error) => {
+            const message = `[search-mysql] autoMigrate failed: ${error.message}`;
+            if (options.log)
+                options.log(message);
+            else
+                console.error(message);
+        });
+    }
+    return new MySqlSearchProvider(options.pool, analyzer);
+}

package/dist/migrate.d.ts

@@ -0,0 +1,20 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+import type { Pool } from 'mysql2/promise';
+export interface MigrateOptions {
+    log?: (message: string) => void;
+}
+export interface MigrateResult {
+    applied: number[];
+}
+/**
+ * Apply the driver-owned numbered migrations. MySQL DDL auto-commits, so an
+ * advisory lock plus idempotent statements serialize concurrent runners; the
+ * ledger row is written only after every statement in a migration succeeds.
+ */
+export declare function migrate(pool: Pool, options?: MigrateOptions): Promise<MigrateResult>;

package/dist/migrate.js

@@ -0,0 +1,68 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+import { MIGRATIONS } from './migrations-data.js';
+const MIGRATION_LOCK = 'byline-search-mysql-migrations';
+/**
+ * Apply the driver-owned numbered migrations. MySQL DDL auto-commits, so an
+ * advisory lock plus idempotent statements serialize concurrent runners; the
+ * ledger row is written only after every statement in a migration succeeds.
+ */
+export async function migrate(pool, options = {}) {
+    const connection = await pool.getConnection();
+    const log = options.log ?? (() => { });
+    try {
+        const [lockRows] = await connection.query('SELECT GET_LOCK(?, 30) AS acquired', [
+            MIGRATION_LOCK,
+        ]);
+        if (lockRows[0]?.acquired !== 1) {
+            throw new Error('[search-mysql] timed out waiting for the migration lock');
+        }
+        await connection.query(`
+      CREATE TABLE IF NOT EXISTS byline_search_migrations (
+        version    int       NOT NULL,
+        applied_at datetime(6) NOT NULL DEFAULT CURRENT_TIMESTAMP(6),
+        PRIMARY KEY (version)
+      ) ENGINE=InnoDB
+    `);
+        const [rows] = await connection.query('SELECT version FROM byline_search_migrations');
+        const done = new Set(rows.map((row) => Number(row.version)));
+        const applied = [];
+        for (const migration of [...MIGRATIONS].sort((left, right) => left.version - right.version)) {
+            if (done.has(migration.version))
+                continue;
+            try {
+                for (const statement of splitStatements(migration.sql)) {
+                    await connection.query(statement);
+                }
+                await connection.query('INSERT INTO byline_search_migrations (version) VALUES (?)', [
+                    migration.version,
+                ]);
+                applied.push(migration.version);
+                log(`[search-mysql] applied migration ${migration.name}`);
+            }
+            catch (error) {
+                throw new Error(`[search-mysql] migration ${migration.name} failed: ${error.message}`, { cause: error });
+            }
+        }
+        return { applied };
+    }
+    finally {
+        try {
+            await connection.query('SELECT RELEASE_LOCK(?)', [MIGRATION_LOCK]);
+        }
+        finally {
+            connection.release();
+        }
+    }
+}
+function splitStatements(sql) {
+    return sql
+        .split(';')
+        .map((statement) => statement.trim())
+        .filter((statement) => statement.length > 0);
+}

package/dist/migrations-data.d.ts

@@ -0,0 +1,13 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+export interface EmbeddedMigration {
+    version: number;
+    name: string;
+    sql: string;
+}
+export declare const MIGRATIONS: EmbeddedMigration[];

package/dist/migrations-data.js

@@ -0,0 +1,55 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+export const MIGRATIONS = [
+    {
+        version: 1,
+        name: '0001_init.sql',
+        sql: `-- @byline/search-mysql — 0001_init
+--
+-- Disposable portable full-text index. One row per
+-- (collection_path, document_id, locale). Every searchable logical token is
+-- encoded by @byline/search-analysis before MySQL's parser sees it, avoiding
+-- language-specific stopword and minimum-token divergence.
+
+CREATE TABLE IF NOT EXISTS byline_search_documents (
+  collection_path      varchar(191) CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL,
+  document_id          varchar(191) CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL,
+  locale               varchar(35)  CHARACTER SET ascii   COLLATE ascii_bin   NOT NULL,
+  status               varchar(64)  CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL,
+  zones                json                                                   NOT NULL,
+  title                text CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci  NOT NULL,
+  path                 text CHARACTER SET utf8mb4 COLLATE utf8mb4_bin,
+  body                 longtext CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci NOT NULL,
+  search_text          longtext CHARACTER SET ascii COLLATE ascii_bin         NOT NULL,
+  search_a             longtext CHARACTER SET ascii COLLATE ascii_bin         NOT NULL,
+  search_b             longtext CHARACTER SET ascii COLLATE ascii_bin         NOT NULL,
+  search_c             longtext CHARACTER SET ascii COLLATE ascii_bin         NOT NULL,
+  search_d             longtext CHARACTER SET ascii COLLATE ascii_bin         NOT NULL,
+  analyzer_fingerprint varchar(512) CHARACTER SET ascii COLLATE ascii_bin      NOT NULL,
+  facets               json                                                   NOT NULL,
+  filters              json                                                   NOT NULL,
+  updated_at           datetime(6)                                            NOT NULL,
+  PRIMARY KEY (collection_path, document_id, locale),
+  KEY byline_search_documents_collection_idx (collection_path, status),
+  FULLTEXT KEY byline_search_documents_text_idx (search_text),
+  FULLTEXT KEY byline_search_documents_a_idx (search_a),
+  FULLTEXT KEY byline_search_documents_b_idx (search_b),
+  FULLTEXT KEY byline_search_documents_c_idx (search_c),
+  FULLTEXT KEY byline_search_documents_d_idx (search_d)
+) ENGINE=InnoDB;
+
+CREATE TABLE IF NOT EXISTS byline_search_index_metadata (
+  collection_path      varchar(191) CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL,
+  analyzer_fingerprint varchar(512) CHARACTER SET ascii COLLATE ascii_bin      NOT NULL,
+  zones                json                                                   NOT NULL,
+  updated_at           datetime(6)                                            NOT NULL,
+  PRIMARY KEY (collection_path)
+) ENGINE=InnoDB;
+`,
+    },
+];

package/dist/migrations-data.test.node.d.ts

@@ -0,0 +1,8 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+export {};

package/dist/migrations-data.test.node.js

@@ -0,0 +1,32 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+import { readdirSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+import { MIGRATIONS } from './migrations-data.js';
+const migrationsDir = join(dirname(fileURLToPath(import.meta.url)), '../migrations');
+describe('embedded migrations vs the .sql files', () => {
+    const sqlFiles = readdirSync(migrationsDir)
+        .filter((file) => file.endsWith('.sql'))
+        .sort();
+    it('embeds exactly the .sql files that ship in the package', () => {
+        expect(MIGRATIONS.map((migration) => migration.name).sort()).toEqual(sqlFiles);
+    });
+    it.each(sqlFiles)('embedded SQL for %s matches the file on disk', (name) => {
+        const onDisk = readFileSync(join(migrationsDir, name), 'utf8');
+        const embedded = MIGRATIONS.find((migration) => migration.name === name);
+        expect(embedded, `no embedded migration named ${name}`).toBeDefined();
+        expect(embedded?.sql.trim()).toBe(onDisk.trim());
+    });
+    it('numbers each migration from its filename prefix', () => {
+        for (const migration of MIGRATIONS) {
+            expect(migration.version).toBe(Number.parseInt(migration.name.split('_')[0] ?? '', 10));
+        }
+    });
+});

package/dist/mysql-search-provider.d.ts

@@ -0,0 +1,28 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+import type { SearchCapabilities, SearchDocument, SearchProvider, SearchQuery, SearchResults } from '@byline/core';
+import { type PortableSearchAnalyzer } from '@byline/search-analysis';
+import type { Pool } from 'mysql2/promise';
+/** MySQL FULLTEXT implementation over portable parser-safe logical tokens. */
+export declare class MySqlSearchProvider implements SearchProvider {
+    private readonly pool;
+    private readonly analyzer;
+    readonly capabilities: SearchCapabilities;
+    constructor(pool: Pool, analyzer: PortableSearchAnalyzer);
+    upsert(doc: SearchDocument): Promise<void>;
+    remove(ref: {
+        collectionPath: string;
+        documentId: string;
+        locale?: string;
+    }): Promise<void>;
+    reindex(opts?: {
+        collectionPath?: string;
+    }): Promise<void>;
+    search(query: SearchQuery): Promise<SearchResults>;
+    private assertAnalyzerFingerprint;
+}

package/dist/mysql-search-provider.js

@@ -0,0 +1,300 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+import { highlightPortableText } from '@byline/search-analysis';
+import { buildIndexRow } from './build-index-row.js';
+import { SearchAnalyzerMismatchError } from './errors.js';
+import { buildPortableMySqlIndexDocument } from './portable-index-document.js';
+import { buildPortableMySqlQuery } from './portable-query.js';
+const CAPABILITIES = {
+    facets: false,
+    typoTolerance: false,
+    semantic: false,
+    bm25: false,
+    weighting: true,
+    highlights: true,
+    fullText: {
+        nativeAnalysis: false,
+        portableAnalysis: true,
+        allTerms: true,
+        anyTerms: true,
+        minimumShouldMatch: true,
+        phrase: true,
+    },
+};
+/** MySQL FULLTEXT implementation over portable parser-safe logical tokens. */
+export class MySqlSearchProvider {
+    pool;
+    analyzer;
+    capabilities = CAPABILITIES;
+    constructor(pool, analyzer) {
+        this.pool = pool;
+        this.analyzer = analyzer;
+    }
+    async upsert(doc) {
+        const row = buildIndexRow(doc);
+        const indexDocument = buildPortableMySqlIndexDocument(row, this.analyzer);
+        const connection = await this.pool.getConnection();
+        try {
+            await connection.beginTransaction();
+            await connection.query(`INSERT INTO byline_search_index_metadata
+           (collection_path, analyzer_fingerprint, zones, updated_at)
+         VALUES (?, ?, ?, UTC_TIMESTAMP(6))
+         ON DUPLICATE KEY UPDATE collection_path = collection_path`, [row.collectionPath, indexDocument.analyzerFingerprint, JSON.stringify(row.zones)]);
+            const [metadata] = await connection.query(`SELECT analyzer_fingerprint, zones
+         FROM byline_search_index_metadata
+         WHERE collection_path = ?
+         FOR UPDATE`, [row.collectionPath]);
+            const actualFingerprint = metadata[0]?.analyzer_fingerprint ?? null;
+            if (actualFingerprint !== indexDocument.analyzerFingerprint) {
+                throw new SearchAnalyzerMismatchError(row.collectionPath, indexDocument.analyzerFingerprint, actualFingerprint);
+            }
+            const zones = [
+                ...new Set([...(parseJsonStringArray(metadata[0]?.zones) ?? []), ...row.zones]),
+            ];
+            await connection.query(`UPDATE byline_search_index_metadata
+         SET zones = ?, updated_at = UTC_TIMESTAMP(6)
+         WHERE collection_path = ?`, [JSON.stringify(zones), row.collectionPath]);
+            await connection.query(UPSERT_SQL, upsertParams(row, indexDocument));
+            await connection.commit();
+        }
+        catch (error) {
+            await rollback(connection);
+            throw error;
+        }
+        finally {
+            connection.release();
+        }
+    }
+    async remove(ref) {
+        if (ref.locale != null) {
+            await this.pool.query(`DELETE FROM byline_search_documents
+         WHERE collection_path = ? AND document_id = ? AND locale = ?`, [ref.collectionPath, ref.documentId, ref.locale]);
+        }
+        else {
+            await this.pool.query(`DELETE FROM byline_search_documents
+         WHERE collection_path = ? AND document_id = ?`, [ref.collectionPath, ref.documentId]);
+        }
+    }
+    async reindex(opts = {}) {
+        const connection = await this.pool.getConnection();
+        try {
+            await connection.beginTransaction();
+            if (opts.collectionPath != null) {
+                await connection.query('DELETE FROM byline_search_documents WHERE collection_path = ?', [
+                    opts.collectionPath,
+                ]);
+                await connection.query('DELETE FROM byline_search_index_metadata WHERE collection_path = ?', [opts.collectionPath]);
+            }
+            else {
+                await connection.query('DELETE FROM byline_search_documents');
+                await connection.query('DELETE FROM byline_search_index_metadata');
+            }
+            await connection.commit();
+        }
+        catch (error) {
+            await rollback(connection);
+            throw error;
+        }
+        finally {
+            connection.release();
+        }
+    }
+    async search(query) {
+        const plan = this.analyzer.analyzeQuery({
+            query: query.query,
+            locale: query.locale,
+            matching: query.matching,
+        });
+        const translated = buildPortableMySqlQuery(plan);
+        if (translated.rankingQuery.length === 0)
+            return { hits: [], total: 0 };
+        await this.assertAnalyzerFingerprint(query);
+        const lexical = buildLexicalPredicate(translated);
+        const where = [lexical.sql];
+        const whereParams = [...lexical.params];
+        appendScopeFilters(query, whereParams, where, true);
+        const whereSql = where.join(' AND ');
+        const [countRows] = await this.pool.query(`SELECT COUNT(*) AS total
+       FROM byline_search_documents d
+       WHERE ${whereSql}`, whereParams);
+        const total = Number(countRows[0]?.total ?? 0);
+        const scoreSql = [
+            '8 * MATCH(d.search_a) AGAINST (? IN BOOLEAN MODE)',
+            '4 * MATCH(d.search_b) AGAINST (? IN BOOLEAN MODE)',
+            '2 * MATCH(d.search_c) AGAINST (? IN BOOLEAN MODE)',
+            '1 * MATCH(d.search_d) AGAINST (? IN BOOLEAN MODE)',
+        ].join(' + ');
+        const limit = query.limit ?? 20;
+        const offset = query.offset ?? 0;
+        const [hitRows] = await this.pool.query(`SELECT d.collection_path, d.document_id, d.locale, d.title, d.path, d.body,
+              (${scoreSql}) AS score
+       FROM byline_search_documents d
+       WHERE ${whereSql}
+       ORDER BY score DESC, d.updated_at DESC,
+                d.collection_path, d.document_id, d.locale
+       LIMIT ? OFFSET ?`, [
+            translated.rankingQuery,
+            translated.rankingQuery,
+            translated.rankingQuery,
+            translated.rankingQuery,
+            ...whereParams,
+            limit,
+            offset,
+        ]);
+        const hits = hitRows.map((row) => {
+            const highlight = highlightPortableText({
+                text: row.body,
+                plan,
+                analyzer: this.analyzer,
+            });
+            return {
+                collectionPath: row.collection_path,
+                documentId: row.document_id,
+                locale: row.locale,
+                title: row.title,
+                path: row.path,
+                score: Number(row.score),
+                ...(highlight == null ? {} : { highlights: { body: [highlight] } }),
+            };
+        });
+        return { hits, total };
+    }
+    async assertAnalyzerFingerprint(query) {
+        const params = [this.analyzer.fingerprint];
+        const where = ['m.analyzer_fingerprint <> ?'];
+        appendMetadataScopeFilters(query, params, where);
+        const [rows] = await this.pool.query(`SELECT m.collection_path, m.analyzer_fingerprint
+       FROM byline_search_index_metadata m
+       WHERE ${where.join(' AND ')}
+       LIMIT 1`, params);
+        const row = rows[0];
+        if (row != null) {
+            throw new SearchAnalyzerMismatchError(row.collection_path, this.analyzer.fingerprint, row.analyzer_fingerprint);
+        }
+    }
+}
+function appendMetadataScopeFilters(query, params, where) {
+    if (query.collectionPath != null) {
+        params.push(query.collectionPath);
+        where.push('m.collection_path = ?');
+    }
+    if (query.zone != null) {
+        params.push(query.zone);
+        where.push('JSON_CONTAINS(m.zones, JSON_ARRAY(?))');
+    }
+}
+function parseJsonStringArray(value) {
+    if (value == null)
+        return undefined;
+    if (Array.isArray(value))
+        return value;
+    const parsed = JSON.parse(value);
+    return Array.isArray(parsed) && parsed.every((item) => typeof item === 'string')
+        ? parsed
+        : undefined;
+}
+function upsertParams(row, indexDocument) {
+    const updatedAt = new Date(row.updatedAt);
+    if (Number.isNaN(updatedAt.valueOf())) {
+        throw new TypeError(`Search document updatedAt is invalid: ${row.updatedAt}`);
+    }
+    return [
+        row.collectionPath,
+        row.documentId,
+        row.locale,
+        row.status,
+        JSON.stringify(row.zones),
+        row.title,
+        row.path,
+        row.body,
+        indexDocument.searchText,
+        indexDocument.weighted.A,
+        indexDocument.weighted.B,
+        indexDocument.weighted.C,
+        indexDocument.weighted.D,
+        indexDocument.analyzerFingerprint,
+        JSON.stringify(row.facets),
+        JSON.stringify(row.filters),
+        updatedAt,
+    ];
+}
+function buildLexicalPredicate(query) {
+    const params = [];
+    const match = (value) => {
+        params.push(value);
+        return 'MATCH(d.search_text) AGAINST (? IN BOOLEAN MODE) > 0';
+    };
+    const concepts = query.conceptQueries.map(match);
+    let conceptSql;
+    if (query.minimumShouldMatch != null) {
+        params.push(query.minimumShouldMatch);
+        conceptSql = `(${concepts.map((sql) => `IF(${sql}, 1, 0)`).join(' + ')}) >= ?`;
+    }
+    else {
+        const operator = query.operator === 'all' ? ' AND ' : ' OR ';
+        conceptSql = `(${concepts.join(operator)})`;
+    }
+    if (query.gramQueries.length > 0) {
+        conceptSql = `(${conceptSql} OR ${query.gramQueries.map(match).join(' OR ')})`;
+    }
+    const clauses = [conceptSql];
+    for (const phraseAlternatives of query.phraseQueries) {
+        if (phraseAlternatives.length === 0) {
+            clauses.push('(FALSE)');
+            continue;
+        }
+        clauses.push(`(${phraseAlternatives.map(match).join(' OR ')})`);
+    }
+    return { sql: clauses.join(' AND '), params };
+}
+function appendScopeFilters(query, params, where, includeStatus) {
+    if (query.collectionPath != null) {
+        params.push(query.collectionPath);
+        where.push('d.collection_path = ?');
+    }
+    if (query.zone != null) {
+        params.push(query.zone);
+        where.push("JSON_CONTAINS(d.zones, JSON_QUOTE(?), '$') = 1");
+    }
+    if (query.locale != null) {
+        params.push(query.locale);
+        where.push('d.locale = ?');
+    }
+    if (includeStatus && query.status !== 'any') {
+        params.push('published');
+        where.push('d.status = ?');
+    }
+}
+async function rollback(connection) {
+    try {
+        await connection.rollback();
+    }
+    catch {
+        // Preserve the original operation error.
+    }
+}
+const UPSERT_SQL = `INSERT INTO byline_search_documents
+  (collection_path, document_id, locale, status, zones, title, path, body,
+   search_text, search_a, search_b, search_c, search_d, analyzer_fingerprint,
+   facets, filters, updated_at)
+ VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+ ON DUPLICATE KEY UPDATE
+   status = VALUES(status),
+   zones = VALUES(zones),
+   title = VALUES(title),
+   path = VALUES(path),
+   body = VALUES(body),
+   search_text = VALUES(search_text),
+   search_a = VALUES(search_a),
+   search_b = VALUES(search_b),
+   search_c = VALUES(search_c),
+   search_d = VALUES(search_d),
+   analyzer_fingerprint = VALUES(analyzer_fingerprint),
+   facets = VALUES(facets),
+   filters = VALUES(filters),
+   updated_at = VALUES(updated_at)`;

package/dist/portable-index-document.d.ts

@@ -0,0 +1,21 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+import { type PortableSearchAnalyzer } from '@byline/search-analysis';
+import type { IndexRow, WeightClass } from './build-index-row.js';
+export interface PortableMySqlIndexDocument {
+    searchText: string;
+    weighted: Record<WeightClass, string>;
+    analyzerFingerprint: string;
+}
+/**
+ * Encode portable logical terms into text streams consumed by MySQL FULLTEXT.
+ * Separate exact, expansion-kind, and Han-gram streams preserve adjacency for
+ * phrase matching without letting phrases cross weight classes or token
+ * streams.
+ */
+export declare function buildPortableMySqlIndexDocument(row: Pick<IndexRow, 'locale' | 'weighted'>, analyzer: PortableSearchAnalyzer): PortableMySqlIndexDocument;