@nshiab/simple-data-analysis-core 2.1.11 → 2.1.13

package/esm/helpers/buildUmapGraph.js

@@ -1,61 +0,0 @@
-import readScalarNumber from "./readScalarNumber.js";
-import buildVectorNeighbors from "./buildVectorNeighbors.js";
-export default async function buildUmapGraph(connection, input, options, names) {
-    await buildVectorNeighbors(connection, {
-        count: input.count,
-        dimensions: input.dimensions,
-        neighborCount: input.neighbors,
-    }, { ...options, includeSelf: true }, { ...names, neighbors: names.knn });
-    await buildFuzzyGraph(connection, input.neighbors, names);
-    const edges = await readScalarNumber(connection, `SELECT count(*) FROM ${names.graph}`);
-    const source = new Uint32Array(edges), target = new Uint32Array(edges), weight = new Float64Array(edges);
-    const rows = await connection.stream(`SELECT source,target,weight FROM ${names.graph} ORDER BY source,target`);
-    let edge = 0;
-    while (true) {
-        const chunk = await rows.fetchChunk();
-        if (!chunk || chunk.rowCount === 0)
-            break;
-        chunk.visitColumnValues(0, (value, row) => source[edge + row] = Number(value));
-        chunk.visitColumnValues(1, (value, row) => target[edge + row] = Number(value));
-        chunk.visitColumnValues(2, (value, row) => weight[edge + row] = Number(value));
-        edge += chunk.rowCount;
-    }
-    if (edge !== edges)
-        throw new Error("Graph changed during transfer.");
-    return { source, target, weight };
-}
-async function buildFuzzyGraph(connection, neighbors, names) {
-    // Smooth-kNN with local_connectivity=1, bandwidth=1, 64 bisection steps,
-    // tolerance 1e-5 and the reference's 1e-3 minimum-distance scale.
-    await connection.run(`CREATE OR REPLACE TEMP TABLE ${names.scales} AS
-    SELECT source, coalesce(min(distance) FILTER(WHERE distance>0),0) AS rho,
-      avg(distance) AS mean_distance, 0::DOUBLE AS lo, 'Infinity'::DOUBLE AS hi,
-      1::DOUBLE AS sigma, false AS done FROM ${names.knn} GROUP BY source`);
-    for (let iteration = 0; iteration < 64; iteration++) {
-        await connection.run(`CREATE OR REPLACE TEMP TABLE ${names.scales} AS
-      WITH sums AS (
-        SELECT s.*, (SELECT sum(CASE WHEN n.distance <= s.rho THEN 1
-          ELSE exp(-(n.distance-s.rho)/s.sigma) END)
-          FROM ${names.knn} n WHERE n.source=s.source AND n.target != n.source) AS mass
-        FROM ${names.scales} s
-      ), bounds AS (
-        SELECT * EXCLUDE(lo,hi,done),
-          CASE WHEN NOT done AND mass < log2(${neighbors}) THEN sigma ELSE lo END AS lo,
-          CASE WHEN NOT done AND mass > log2(${neighbors}) THEN sigma ELSE hi END AS hi,
-          done OR abs(mass-log2(${neighbors})) < 1e-5 AS done FROM sums
-      ) SELECT source,rho,mean_distance,lo,hi,
-        CASE WHEN done THEN sigma WHEN isinf(hi) THEN sigma*2 ELSE (lo+hi)/2 END AS sigma,
-        done FROM bounds`);
-    }
-    await connection.run(`UPDATE ${names.scales} SET sigma=greatest(sigma,0.001 *
-    CASE WHEN rho>0 THEN mean_distance ELSE (SELECT avg(distance) FROM ${names.knn}) END);
-    CREATE OR REPLACE TEMP TABLE ${names.directed} AS
-    SELECT n.source,n.target,CASE WHEN n.distance<=s.rho OR s.sigma=0 THEN 1
-      ELSE exp(-(n.distance-s.rho)/s.sigma) END AS weight
-    FROM ${names.knn} n JOIN ${names.scales} s USING(source) WHERE n.source != n.target;
-    CREATE OR REPLACE TEMP TABLE ${names.graph} AS
-    SELECT coalesce(a.source,b.target) AS source, coalesce(a.target,b.source) AS target,
-      coalesce(a.weight,0)+coalesce(b.weight,0)-coalesce(a.weight*b.weight,0) AS weight
-    FROM ${names.directed} a FULL OUTER JOIN ${names.directed} b
-      ON a.source=b.target AND a.target=b.source`);
-}

package/esm/helpers/buildVectorNeighbors.d.ts

@@ -1,45 +0,0 @@
-import type { DuckDBConnection } from "@duckdb/node-api";
-/** Private, already-quoted relation names owned and cleaned up by the caller. */
-export type VectorNeighborTables = {
-    rows: string;
-    neighbors: string;
-    search: string;
-    hnsw: string;
-    candidates: string;
-};
-type NeighborInput = {
-    count: number;
-    dimensions: number;
-    neighborCount: number;
-};
-type NeighborOptions = {
-    metric: "euclidean" | "cosine";
-    search: "exact" | "hnsw";
-    includeSelf: boolean;
-    hnsw?: {
-        efConstruction: number;
-        efSearch: number;
-        connectivity: number;
-        candidateCount: number;
-        singleThreaded: boolean;
-        cosineAsL2: boolean;
-    };
-};
-/**
- * Materialize ranked vector neighbors without moving source vectors into JS.
- *
- * `neighborCount` is the number of rows produced per source. When `includeSelf`
- * is true, the source is rank 0 and consumes one of those rows. Otherwise all
- * rows are other points. Ranks are zero-based and ties use target id order.
- * Input rows have unique contiguous `vertex` ids from 0 through count-1 and
- * validated, non-null, fixed-size DOUBLE `vec` values. Cosine preparation may
- * rescale this private vec column, preserving direction.
- *
- * The caller owns every supplied scratch relation and must drop them after
- * success or failure. Approximate search only approximates candidate retrieval;
- * candidate distances are recomputed from the DOUBLE source vectors before
- * stable final ranking.
- */
-export default function buildVectorNeighbors(connection: DuckDBConnection, input: NeighborInput, options: NeighborOptions, names: VectorNeighborTables): Promise<void>;
-export {};
-//# sourceMappingURL=buildVectorNeighbors.d.ts.map

package/esm/helpers/buildVectorNeighbors.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"buildVectorNeighbors.d.ts","sourceRoot":"","sources":["../../src/helpers/buildVectorNeighbors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAMzD,iFAAiF;AACjF,MAAM,MAAM,oBAAoB,GAAG;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,KAAK,aAAa,GAAG;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF,KAAK,eAAe,GAAG;IACrB,MAAM,EAAE,WAAW,GAAG,QAAQ,CAAC;IAC/B,MAAM,EAAE,OAAO,GAAG,MAAM,CAAC;IACzB,WAAW,EAAE,OAAO,CAAC;IACrB,IAAI,CAAC,EAAE;QACL,cAAc,EAAE,MAAM,CAAC;QACvB,QAAQ,EAAE,MAAM,CAAC;QACjB,YAAY,EAAE,MAAM,CAAC;QACrB,cAAc,EAAE,MAAM,CAAC;QACvB,cAAc,EAAE,OAAO,CAAC;QACxB,UAAU,EAAE,OAAO,CAAC;KACrB,CAAC;CACH,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,wBAA8B,oBAAoB,CAChD,UAAU,EAAE,gBAAgB,EAC5B,KAAK,EAAE,aAAa,EACpB,OAAO,EAAE,eAAe,EACxB,KAAK,EAAE,oBAAoB,GAC1B,OAAO,CAAC,IAAI,CAAC,CAqHf"}

package/esm/helpers/buildVectorNeighbors.js

@@ -1,170 +0,0 @@
-import readScalarNumber from "./readScalarNumber.js";
-import vectorDistanceExpression from "./vectorDistanceExpression.js";
-import stabilizeCosineVectors from "./stabilizeCosineVectors.js";
-import validateVectorRowIds from "./validateVectorRowIds.js";
-/**
- * Materialize ranked vector neighbors without moving source vectors into JS.
- *
- * `neighborCount` is the number of rows produced per source. When `includeSelf`
- * is true, the source is rank 0 and consumes one of those rows. Otherwise all
- * rows are other points. Ranks are zero-based and ties use target id order.
- * Input rows have unique contiguous `vertex` ids from 0 through count-1 and
- * validated, non-null, fixed-size DOUBLE `vec` values. Cosine preparation may
- * rescale this private vec column, preserving direction.
- *
- * The caller owns every supplied scratch relation and must drop them after
- * success or failure. Approximate search only approximates candidate retrieval;
- * candidate distances are recomputed from the DOUBLE source vectors before
- * stable final ranking.
- */
-export default async function buildVectorNeighbors(connection, input, options, names) {
-    const { count, dimensions, neighborCount } = input;
-    await validateVectorRowIds(connection, names.rows, count);
-    if (!Number.isSafeInteger(dimensions) || dimensions < 1) {
-        throw new Error("Vector dimensions must be a positive safe integer.");
-    }
-    const maximum = count - (options.includeSelf ? 0 : 1);
-    if (!Number.isSafeInteger(neighborCount) || neighborCount < 1 ||
-        neighborCount > maximum) {
-        throw new Error(`Neighbor count must be a safe integer between 1 and ${maximum}.`);
-    }
-    if (options.metric === "cosine") {
-        await stabilizeCosineVectors(connection, names.rows);
-    }
-    // FLOAT representation limits apply only to the HNSW search vectors.
-    // Exact Euclidean distance does not require representable squared norms.
-    if (options.search === "hnsw") {
-        const normExpression = `array_inner_product(vec::FLOAT[${dimensions}],vec::FLOAT[${dimensions}])`;
-        if (await readScalarNumber(connection, `SELECT count(*) FROM ${names.rows} WHERE NOT isfinite(${normExpression})
-          ${options.metric === "cosine" ? `OR ${normExpression}=0` : ""}`)) {
-            throw new Error("HNSW requires vectors with finite FLOAT norms (and nonzero cosine norms).");
-        }
-    }
-    const distanceFunction = options.metric === "cosine"
-        ? "array_cosine_distance"
-        : "array_distance";
-    // Equal vectors must have exactly zero cosine distance. Positive roundoff can
-    // otherwise alter downstream density estimates. Clamp negative roundoff too.
-    const exactDistance = vectorDistanceExpression("a.vec", "b.vec", options.metric);
-    const otherCount = neighborCount - (options.includeSelf ? 1 : 0);
-    await connection.run(`CREATE OR REPLACE TEMP TABLE ${names.candidates}
-    (source INTEGER, target INTEGER, distance DOUBLE)`);
-    if (otherCount > 0) {
-        if (options.search === "exact") {
-            // O(n²d) work with a bounded source batch and top-k heaps. The full
-            // distance matrix is never materialized.
-            await buildExactCandidates(connection, input, names, exactDistance, otherCount);
-        }
-        else {
-            await buildHnswCandidates(connection, input, options, names, distanceFunction, exactDistance, otherCount);
-        }
-    }
-    if (await readScalarNumber(connection, `SELECT count(*) FROM ${names.candidates} WHERE distance IS NULL OR NOT isfinite(distance)`)) {
-        throw new Error("Distance computation returned a non-finite value.");
-    }
-    const selfRows = options.includeSelf
-        ? `SELECT vertex AS source,vertex AS target,0::DOUBLE AS distance FROM ${names.rows}`
-        : "SELECT NULL::INTEGER AS source,NULL::INTEGER AS target,NULL::DOUBLE AS distance WHERE false";
-    const rankOrder = options.includeSelf
-        ? "CASE WHEN source=target THEN 0 ELSE 1 END,distance,target"
-        : "distance,target";
-    await connection.run(`CREATE OR REPLACE TEMP TABLE ${names.neighbors} AS
-    SELECT source,target,
-      (row_number() OVER (PARTITION BY source ORDER BY ${rankOrder})-1)::INTEGER AS rank,
-      greatest(0,distance)::DOUBLE AS distance
-    FROM (${selfRows} UNION ALL
-      SELECT source,target,distance FROM ${names.candidates})
-    QUALIFY row_number() OVER (PARTITION BY source ORDER BY ${rankOrder})
-      <= ${neighborCount}`);
-    const produced = await readScalarNumber(connection, `SELECT count(*) FROM ${names.neighbors}`);
-    if (produced !== count * neighborCount) {
-        throw new Error(`Neighbor search returned ${produced} rows; ${count * neighborCount} were required.`);
-    }
-    if (await readScalarNumber(connection, `SELECT count(*) FROM ${names.neighbors} WHERE NOT isfinite(distance)`)) {
-        throw new Error("Distance computation returned a non-finite value.");
-    }
-}
-async function buildHnswCandidates(connection, input, options, names, distanceFunction, exactDistance, otherCount) {
-    const { count, dimensions, neighborCount } = input;
-    const settings = options.hnsw;
-    const cosineAsL2 = options.metric === "cosine" && settings?.cosineAsL2;
-    // Euclidean distance on unit vectors has the same mathematical ordering as
-    // cosine. Computing differences avoids FLOAT dot-product cancellation for
-    // near-collinear vectors; final metric distances still use source DOUBLEs.
-    const searchVector = cosineAsL2
-        ? "list_transform(vec,x -> x/sqrt(array_inner_product(vec,vec)))"
-        : "vec";
-    const previousThreads = Number((await connection.runAndReadAll("SELECT current_setting('threads')")).getRowsJS()[0][0]);
-    try {
-        if (settings?.singleThreaded)
-            await connection.run("SET threads=1");
-        await connection.run(`INSTALL vss; LOAD vss;
-      CREATE OR REPLACE TEMP TABLE ${names.search} AS
-      SELECT vertex,${searchVector}::FLOAT[${dimensions}] AS vec
-      FROM ${names.rows} ORDER BY vertex;
-      CREATE INDEX ${names.hnsw} ON ${names.search} USING HNSW(vec)
-      WITH (metric='${options.metric === "cosine" && !cosineAsL2 ? "cosine" : "l2sq"}',
-        ef_construction=${settings?.efConstruction ?? 128},
-        ef_search=${settings?.efSearch ?? 128},M=${settings?.connectivity ?? 16})`);
-    }
-    finally {
-        if (settings?.singleThreaded) {
-            await connection.run(`SET threads=${previousThreads}`);
-        }
-    }
-    const previous = String((await connection.runAndReadAll("SELECT current_setting('disabled_optimizers')")).getRowsJS()[0][0]);
-    const disabled = [
-        ...new Set([
-            ...previous.split(",").filter(Boolean),
-            "top_n_window_elimination",
-        ]),
-    ].join(",");
-    try {
-        await connection.run(`SET disabled_optimizers='${disabled.replaceAll("'", "''")}'`);
-        // Preserve UMAP's established candidate budget when self is included.
-        // Excluding self needs one extra result because HNSW normally returns it.
-        const candidateCount = settings?.candidateCount ??
-            (options.includeSelf
-                ? Math.max(otherCount + 1, Math.min(neighborCount + 1, count - 1))
-                : Math.min(otherCount + 1, count));
-        const candidateDistanceFunction = cosineAsL2
-            ? "array_distance"
-            : distanceFunction;
-        const query = `SELECT a.vertex AS source,b.vertex AS target,b.distance
-      FROM ${names.search} a,LATERAL (
-        SELECT vertex,${candidateDistanceFunction}(vec,a.vec) AS distance
-        FROM ${names.search} ORDER BY distance LIMIT ${candidateCount}
-      ) b`;
-        // Carry ids and scalar distances through the candidate relation. Recompute
-        // in DOUBLE against source rows to isolate ANN retrieval from precision.
-        const candidates = `SELECT q.source,q.target,${exactDistance} AS distance
-      FROM (${query}) q JOIN ${names.rows} a ON q.source=a.vertex
-      JOIN ${names.rows} b ON q.target=b.vertex WHERE q.source != q.target`;
-        const plan = JSON.stringify((await connection.runAndReadAll(`EXPLAIN ${candidates}`)).getRowsJS());
-        if (!plan.includes("HNSW_INDEX_JOIN")) {
-            if (count <= 1000) {
-                return await buildExactCandidates(connection, input, names, exactDistance, otherCount);
-            }
-            throw new Error("DuckDB could not use its vector index for neighbor search.");
-        }
-        await connection.run(`INSERT INTO ${names.candidates} ${candidates}`);
-    }
-    finally {
-        await connection.run(`SET disabled_optimizers='${previous.replaceAll("'", "''")}'`);
-    }
-}
-async function buildExactCandidates(connection, input, names, exactDistance, otherCount) {
-    for (let offset = 0; offset < input.count; offset += 32) {
-        const query = `SELECT source,item.target,item.distance FROM (
-      SELECT a.vertex AS source,
-        CASE WHEN bool_and(isfinite(${exactDistance})) THEN
-        min_by(struct_pack(target := b.vertex,distance := ${exactDistance}),
-          struct_pack(distance := ${exactDistance},target := b.vertex),
-          ${otherCount}) ELSE error('Distance computation returned a non-finite value.') END AS closest
-      FROM ${names.rows} a CROSS JOIN ${names.rows} b
-      WHERE a.vertex >= ${offset} AND a.vertex < ${offset + 32}
-        AND a.vertex != b.vertex GROUP BY a.vertex
-      ),UNNEST(closest) AS t(item)`;
-        await connection.run(`INSERT INTO ${names.candidates} ${query}`);
-    }
-}

package/esm/helpers/buildWeakGraphComponentsSql.d.ts

@@ -1,3 +0,0 @@
-/** Builds weak component labels and zero-based IDs from bidirectional edges. */
-export default function buildWeakGraphComponentsSql(edges: string, nodes: string, labels: string, roots: string): string;
-//# sourceMappingURL=buildWeakGraphComponentsSql.d.ts.map

package/esm/helpers/buildWeakGraphComponentsSql.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"buildWeakGraphComponentsSql.d.ts","sourceRoot":"","sources":["../../src/helpers/buildWeakGraphComponentsSql.ts"],"names":[],"mappings":"AAEA,gFAAgF;AAChF,MAAM,CAAC,OAAO,UAAU,2BAA2B,CACjD,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,GACZ,MAAM,CA6BR"}

package/esm/helpers/buildWeakGraphComponentsSql.js

@@ -1,32 +0,0 @@
-import quoteIdentifier from "./quoteIdentifier.js";
-/** Builds weak component labels and zero-based IDs from bidirectional edges. */
-export default function buildWeakGraphComponentsSql(edges, nodes, labels, roots) {
-    const q = quoteIdentifier;
-    return `${labels}(
-      ${q("node")}, ${q("__node_key")}, ${q("__root_key")}
-    ) USING KEY(${q("__node_key")}) AS (
-      SELECT ${q("node")}, ${q("__key")}, ${q("__key")}
-      FROM ${nodes}
-      UNION
-      SELECT ${q("edges")}.${q("__to")},
-        ${q("edges")}.${q("__to_key")},
-        MIN(${q("reached")}.${q("__root_key")})
-      FROM ${labels} AS ${q("reached")}
-      INNER JOIN ${edges} AS ${q("edges")}
-        ON ${q("reached")}.${q("__node_key")} =
-          ${q("edges")}.${q("__from_key")}
-      INNER JOIN recurring.${labels} AS ${q("best")}
-        ON ${q("edges")}.${q("__to_key")} =
-          ${q("best")}.${q("__node_key")}
-      GROUP BY ${q("edges")}.${q("__to")},
-        ${q("edges")}.${q("__to_key")}, ${q("best")}.${q("__root_key")}
-      HAVING MIN(${q("reached")}.${q("__root_key")}) <
-        ${q("best")}.${q("__root_key")}
-    ), ${roots} AS (
-      SELECT ${q("__root_key")},
-        CAST(row_number() OVER (ORDER BY ${q("__root_key")}) - 1 AS BIGINT)
-          AS ${q("componentId")}
-      FROM (SELECT DISTINCT ${q("__root_key")} FROM ${labels})
-        AS ${q("distinct_roots")}
-    )`;
-}

package/esm/helpers/cacheDatabase.d.ts

@@ -1,5 +0,0 @@
-import type SimpleTable from "../class/SimpleTable.js";
-import type { IndexDefinition } from "./indexDefinitions.js";
-export declare function writeCacheDatabase(table: SimpleTable, file: string, indexes: IndexDefinition[]): Promise<void>;
-export declare function loadCacheDatabase(table: SimpleTable, file: string, indexes: IndexDefinition[], geo: boolean): Promise<void>;
-//# sourceMappingURL=cacheDatabase.d.ts.map

package/esm/helpers/cacheDatabase.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"cacheDatabase.d.ts","sourceRoot":"","sources":["../../src/helpers/cacheDatabase.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,WAAW,MAAM,yBAAyB,CAAC;AACvD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAU7D,wBAAsB,kBAAkB,CACtC,KAAK,EAAE,WAAW,EAClB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,eAAe,EAAE,GACzB,OAAO,CAAC,IAAI,CAAC,CA0Cf;AASD,wBAAsB,iBAAiB,CACrC,KAAK,EAAE,WAAW,EAClB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,eAAe,EAAE,EAC1B,GAAG,EAAE,OAAO,GACX,OAAO,CAAC,IAAI,CAAC,CAiCf"}

package/esm/helpers/cacheDatabase.js

@@ -1,111 +0,0 @@
-import { existsSync, renameSync, rmSync } from "node:fs";
-import { getIndexCacheStrategy } from "./indexDefinitions.js";
-import buildCreateIndexQuery from "./indexQueries.js";
-import cleanPath from "./cleanPath.js";
-import quoteIdentifier from "./quoteIdentifier.js";
-const CACHE_DATABASE = "__sda_cache_entry";
-export async function writeCacheDatabase(table, file, indexes) {
-    const temporaryFile = `${file}.${crypto.randomUUID()}.tmp.db`;
-    const cacheDatabase = quoteIdentifier(CACHE_DATABASE);
-    const currentDatabase = quoteIdentifier(await getCurrentDatabase(table));
-    const persistedIndexes = indexes.filter((index) => getIndexCacheStrategy(index) === "persist");
-    await loadIndexExtensions(table, persistedIndexes);
-    try {
-        await table.sdb.customQuery(`ATTACH '${cleanPath(temporaryFile)}' AS ${cacheDatabase}
-        (STORAGE_VERSION 'latest');
-      CREATE TABLE ${cacheDatabase}.${quoteIdentifier(table.name)} AS
-        SELECT * FROM ${quoteIdentifier(table.name)};`);
-        if (persistedIndexes.length > 0) {
-            await table.sdb.customQuery(`USE ${cacheDatabase};`);
-            await table.sdb.customQuery(buildIndexQueries(table.name, persistedIndexes));
-            await table.sdb.customQuery(`USE ${currentDatabase};`);
-        }
-        await table.sdb.customQuery(`CHECKPOINT ${cacheDatabase};
-      DETACH ${cacheDatabase};`);
-        try {
-            renameSync(temporaryFile, file);
-        }
-        catch (error) {
-            if (!isReplaceRenameError(error) || !existsSync(file)) {
-                throw error;
-            }
-            rmSync(file);
-            renameSync(temporaryFile, file);
-        }
-    }
-    catch (error) {
-        await restoreDatabaseAfterFailure(table, currentDatabase, cacheDatabase);
-        if (existsSync(temporaryFile)) {
-            rmSync(temporaryFile);
-        }
-        throw error;
-    }
-}
-function isReplaceRenameError(error) {
-    if (!(error instanceof Error) || !("code" in error)) {
-        return false;
-    }
-    return error.code === "EEXIST" || error.code === "EPERM";
-}
-export async function loadCacheDatabase(table, file, indexes, geo) {
-    const cacheDatabase = quoteIdentifier(CACHE_DATABASE);
-    const currentDatabase = quoteIdentifier(await getCurrentDatabase(table));
-    if (geo) {
-        await table.sdb.customQuery("INSTALL spatial; LOAD spatial;");
-    }
-    await loadIndexExtensions(table, indexes);
-    table.indexes = [];
-    const dropFts = `DROP SCHEMA IF EXISTS ${quoteIdentifier(`fts_main_${table.name}`)} CASCADE;`;
-    try {
-        await table.sdb.customQuery(`${dropFts}
-      DROP TABLE IF EXISTS ${quoteIdentifier(table.name)};
-      ATTACH '${cleanPath(file)}' AS ${cacheDatabase} (READ_ONLY);
-      COPY FROM DATABASE ${cacheDatabase} TO ${currentDatabase};
-      DETACH ${cacheDatabase};`);
-        const indexesToRebuild = indexes.filter((index) => getIndexCacheStrategy(index) === "rebuild");
-        const indexQueries = buildIndexQueries(table.name, indexesToRebuild);
-        if (indexQueries.length > 0) {
-            await table.sdb.customQuery(indexQueries);
-        }
-    }
-    catch (error) {
-        await restoreDatabaseAfterFailure(table, currentDatabase, cacheDatabase);
-        throw error;
-    }
-    table.indexes = structuredClone(indexes);
-}
-async function getCurrentDatabase(table) {
-    const rows = await table.sdb.customQuery("SELECT current_database() AS database_name;", { returnData: true });
-    return rows[0].database_name;
-}
-async function loadIndexExtensions(table, indexes) {
-    const queries = [];
-    if (indexes.some((index) => index.kind === "vss")) {
-        queries.push("INSTALL vss; LOAD vss;");
-    }
-    if (indexes.some((index) => index.kind === "fts")) {
-        queries.push("INSTALL fts; LOAD fts;");
-    }
-    if (queries.length > 0) {
-        await table.sdb.customQuery(queries.join("\n"));
-    }
-}
-function buildIndexQueries(table, indexes) {
-    return indexes.map((index) => `${index.kind === "vss"
-        ? "SET hnsw_enable_experimental_persistence = true;\n"
-        : ""}${buildCreateIndexQuery(table, index)}`).join("\n");
-}
-async function restoreDatabaseAfterFailure(table, currentDatabase, cacheDatabase) {
-    try {
-        await table.sdb.customQuery(`USE ${currentDatabase};`);
-    }
-    catch {
-        // Preserve the original cache error.
-    }
-    try {
-        await table.sdb.customQuery(`DETACH ${cacheDatabase};`);
-    }
-    catch {
-        // The cache database may not have been attached yet.
-    }
-}

package/esm/helpers/cacheDiagnostics.d.ts

@@ -1,4 +0,0 @@
-export declare function cacheEntryExpired(creation: number, ttl: number | undefined, now: number): boolean;
-export declare function cacheTtlMessage(creation: number, ttl: number, now: number, expired: boolean): string;
-export declare function cacheLoadMessage(start: number, end: number, cachedDuration: number | undefined): string;
-//# sourceMappingURL=cacheDiagnostics.d.ts.map

package/esm/helpers/cacheDiagnostics.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"cacheDiagnostics.d.ts","sourceRoot":"","sources":["../../src/helpers/cacheDiagnostics.ts"],"names":[],"mappings":"AAGA,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM,GAAG,SAAS,EACvB,GAAG,EAAE,MAAM,GACV,OAAO,CAET;AAED,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,OAAO,GACf,MAAM,CAgBR;AAED,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,MAAM,EACX,cAAc,EAAE,MAAM,GAAG,SAAS,GACjC,MAAM,CAQR"}

package/esm/helpers/cacheDiagnostics.js

@@ -1,21 +0,0 @@
-import formatDate from "./formatDate.js";
-import prettyDuration from "./prettyDuration.js";
-export function cacheEntryExpired(creation, ttl, now) {
-    return ttl !== undefined && now - creation >= ttl * 1000;
-}
-export function cacheTtlMessage(creation, ttl, now, expired) {
-    const creationDate = formatDate(new Date(creation), "Month DD, YYYY, at HH:MM period");
-    const ttlDuration = prettyDuration(0, { end: ttl * 1000 });
-    if (expired) {
-        return `TTL of ${ttlDuration} has expired.\nThe creation date is ${creationDate}.\nIt was created ${prettyDuration(creation, { end: now })} ago.`;
-    }
-    const ttlLimit = creation + ttl * 1000;
-    return `TTL of ${ttlDuration} has not expired.\nThe creation date is ${creationDate}.\nThere are ${prettyDuration(now, { end: ttlLimit })} left.`;
-}
-export function cacheLoadMessage(start, end, cachedDuration) {
-    const loaded = `Data loaded in ${prettyDuration(start, { end })}.`;
-    if (cachedDuration === undefined) {
-        return loaded;
-    }
-    return `${loaded}\nRunning computations previously took ${prettyDuration(0, { end: cachedDuration })}.\nYou saved ${prettyDuration(end - start, { end: cachedDuration })}.`;
-}

package/esm/helpers/cacheTableDependencies.d.ts

@@ -1,28 +0,0 @@
-import type SimpleTable from "../class/SimpleTable.js";
-import type { PendingOp, PendingOpInput } from "./pendingOps.js";
-import { type TableGenerationId } from "./tableGeneration.js";
-export type CacheTableDependency = {
-    tableName: string;
-    generationId: TableGenerationId;
-};
-/** Keeps deferred callbacks in their originating cache scope across observers. */
-export declare function captureCacheTableOperation(op: PendingOpInput): PendingOpInput;
-/** Rejects mutations before they can queue work or execute SQL. */
-export declare function assertCacheTableMutation(table: SimpleTable): void;
-/** Tracks callback-owned handles so failure cleanup does not touch other work. */
-export declare function recordCacheTableCreation(table: SimpleTable): void;
-/** Tracks queued work across nested callbacks, including async barriers. */
-export declare function recordCacheTableOperation(table: SimpleTable, op: PendingOp): void;
-/** Records a table read when a cache computation is observing dependencies. */
-export declare function recordCacheTableAccess(table: SimpleTable): void;
-/** Records registered tables named in user-supplied SQL fragments. */
-export declare function recordCacheTableReferences(table: SimpleTable, sql: readonly string[]): void;
-/** Runs a cache computation while collecting the tables it reads. */
-export declare function captureCacheTableDependencies(cachedTable: SimpleTable, compute: () => Promise<void>): Promise<CacheTableDependency[]>;
-/** Checks persisted dependencies against the current registered tables. */
-export declare function cacheTableDependenciesMatch(cachedTable: SimpleTable, dependencies: readonly CacheTableDependency[] | undefined): boolean;
-/** Describes changed or unavailable table dependencies for verbose logging. */
-export declare function changedCacheTableDependenciesMessage(cachedTable: SimpleTable, dependencies: readonly CacheTableDependency[]): string;
-/** Lists unchanged dependencies for cache-hit verbose logging. */
-export declare function unchangedCacheTableDependenciesMessage(dependencies: readonly CacheTableDependency[]): string;
-//# sourceMappingURL=cacheTableDependencies.d.ts.map

package/esm/helpers/cacheTableDependencies.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"cacheTableDependencies.d.ts","sourceRoot":"","sources":["../../src/helpers/cacheTableDependencies.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,WAAW,MAAM,yBAAyB,CAAC;AACvD,OAAO,KAAK,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAWjE,OAAO,EAGL,KAAK,iBAAiB,EACvB,MAAM,sBAAsB,CAAC;AAE9B,MAAM,MAAM,oBAAoB,GAAG;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,iBAAiB,CAAC;CACjC,CAAC;AAkBF,kFAAkF;AAClF,wBAAgB,0BAA0B,CAAC,EAAE,EAAE,cAAc,GAAG,cAAc,CAiB7E;AAYD,mEAAmE;AACnE,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI,CAWjE;AAED,kFAAkF;AAClF,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI,CASjE;AAED,4EAA4E;AAC5E,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,WAAW,EAClB,EAAE,EAAE,SAAS,GACZ,IAAI,CAMN;AAED,+EAA+E;AAC/E,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI,CAM/D;AAED,sEAAsE;AACtE,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,WAAW,EAClB,GAAG,EAAE,SAAS,MAAM,EAAE,GACrB,IAAI,CAON;AAED,qEAAqE;AACrE,wBAAsB,6BAA6B,CACjD,WAAW,EAAE,WAAW,EACxB,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAC3B,OAAO,CAAC,oBAAoB,EAAE,CAAC,CAsDjC;AA4ED,2EAA2E;AAC3E,wBAAgB,2BAA2B,CACzC,WAAW,EAAE,WAAW,EACxB,YAAY,EAAE,SAAS,oBAAoB,EAAE,GAAG,SAAS,GACxD,OAAO,CAYT;AAED,+EAA+E;AAC/E,wBAAgB,oCAAoC,CAClD,WAAW,EAAE,WAAW,EACxB,YAAY,EAAE,SAAS,oBAAoB,EAAE,GAC5C,MAAM,CAsBR;AAED,kEAAkE;AAClE,wBAAgB,sCAAsC,CACpD,YAAY,EAAE,SAAS,oBAAoB,EAAE,GAC5C,MAAM,CAER"}