@nshiab/simple-data-analysis-core 2.1.12 → 2.1.14

package/src/helpers/buildUmapGraph.ts

@@ -0,0 +1,85 @@
+import type { DuckDBConnection } from "@duckdb/node-api";
+import readScalarNumber from "./readScalarNumber.ts";
+import buildVectorNeighbors, { type VectorNeighborTables } from "./buildVectorNeighbors.ts";
+
+// All relation names are private, already-quoted SQL identifiers supplied by
+// the owning UMAP operation. No input vectors cross the JS boundary.
+export type UmapTables = Omit<VectorNeighborTables, "neighbors"> & {
+  knn: string;
+  scales: string;
+  directed: string;
+  graph: string;
+};
+
+export default async function buildUmapGraph(
+  connection: DuckDBConnection,
+  input: { count: number; dimensions: number; neighbors: number },
+  options: { metric: "euclidean" | "cosine"; search: "exact" | "hnsw" },
+  names: UmapTables,
+) {
+  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: DuckDBConnection, neighbors: number, names: UmapTables) {
+  // 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/src/helpers/buildVectorNeighbors.ts

@@ -0,0 +1,248 @@
+import type { DuckDBConnection } from "@duckdb/node-api";
+import readScalarNumber from "./readScalarNumber.ts";
+import vectorDistanceExpression from "./vectorDistanceExpression.ts";
+import stabilizeCosineVectors from "./stabilizeCosineVectors.ts";
+import validateVectorRowIds from "./validateVectorRowIds.ts";
+
+/** 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 async function buildVectorNeighbors(
+  connection: DuckDBConnection,
+  input: NeighborInput,
+  options: NeighborOptions,
+  names: VectorNeighborTables,
+): Promise<void> {
+  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: DuckDBConnection,
+  input: NeighborInput,
+  options: NeighborOptions,
+  names: VectorNeighborTables,
+  distanceFunction: string,
+  exactDistance: string,
+  otherCount: number,
+): Promise<void> {
+  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 = (
+    await connection.runAndReadAll("SELECT current_setting('disabled_optimizers')")
+  ).getRowsJS()[0][0];
+  if (typeof previous !== "string") throw new Error("Expected disabled_optimizers to be a string.");
+  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: DuckDBConnection,
+  input: NeighborInput,
+  names: VectorNeighborTables,
+  exactDistance: string,
+  otherCount: number,
+): Promise<void> {
+  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/src/helpers/buildWeakGraphComponentsSql.ts

@@ -0,0 +1,38 @@
+import quoteIdentifier from "./quoteIdentifier.ts";
+
+/** Builds weak component labels and zero-based IDs from bidirectional edges. */
+export default function buildWeakGraphComponentsSql(
+  edges: string,
+  nodes: string,
+  labels: string,
+  roots: string,
+): string {
+  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/src/helpers/cacheDatabase.ts

@@ -0,0 +1,146 @@
+import { existsSync, renameSync, rmSync } from "node:fs";
+import type SimpleTable from "../class/SimpleTable.ts";
+import type { IndexDefinition } from "./indexDefinitions.ts";
+import { getIndexCacheStrategy } from "./indexDefinitions.ts";
+import buildCreateIndexQuery from "./indexQueries.ts";
+import cleanPath from "./cleanPath.ts";
+import quoteIdentifier from "./quoteIdentifier.ts";
+
+const CACHE_DATABASE = "__sda_cache_entry";
+
+type DatabaseRow = { database_name: string };
+
+export async function writeCacheDatabase(
+  table: SimpleTable,
+  file: string,
+  indexes: IndexDefinition[],
+): Promise<void> {
+  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: unknown): boolean {
+  if (!(error instanceof Error) || !("code" in error)) {
+    return false;
+  }
+  return error.code === "EEXIST" || error.code === "EPERM";
+}
+
+export async function loadCacheDatabase(
+  table: SimpleTable,
+  file: string,
+  indexes: IndexDefinition[],
+  geo: boolean,
+): Promise<void> {
+  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: SimpleTable): Promise<string> {
+  const rows = (await table.sdb.customQuery("SELECT current_database() AS database_name;", {
+    returnData: true,
+  })) as DatabaseRow[];
+  return rows[0].database_name;
+}
+
+async function loadIndexExtensions(table: SimpleTable, indexes: IndexDefinition[]): Promise<void> {
+  const queries: string[] = [];
+  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: string, indexes: IndexDefinition[]): string {
+  return indexes
+    .map(
+      (index) =>
+        `${
+          index.kind === "vss" ? "SET hnsw_enable_experimental_persistence = true;\n" : ""
+        }${buildCreateIndexQuery(table, index)}`,
+    )
+    .join("\n");
+}
+
+async function restoreDatabaseAfterFailure(
+  table: SimpleTable,
+  currentDatabase: string,
+  cacheDatabase: string,
+): Promise<void> {
+  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/src/helpers/cacheDiagnostics.ts

@@ -0,0 +1,42 @@
+import formatDate from "./formatDate.ts";
+import prettyDuration from "./prettyDuration.ts";
+
+export function cacheEntryExpired(creation: number, ttl: number | undefined, now: number): boolean {
+  return ttl !== undefined && now - creation >= ttl * 1000;
+}
+
+export function cacheTtlMessage(
+  creation: number,
+  ttl: number,
+  now: number,
+  expired: boolean,
+): string {
+  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: number,
+  end: number,
+  cachedDuration: number | undefined,
+): string {
+  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 })}.`;
+}