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

package/esm/helpers/cacheTableDependencies.js

@@ -1,227 +0,0 @@
-import { AsyncLocalStorage } from "node:async_hooks";
-import referencedTables from "./referencedTables.js";
-import { getAsyncOperationFrame, runWhileDrainingAsyncOperationFrame, } from "./asyncOperationContext.js";
-import flushAllTables, { runExemptFromFlush } from "./flushAllTables.js";
-import quoteIdentifier from "./quoteIdentifier.js";
-import { getRegisteredTables, retainRegisteredTables, } from "./tableRegistry.js";
-import { getTableGeneration, peekTableGeneration, } from "./tableGeneration.js";
-const dependencyContext = new AsyncLocalStorage();
-/** Keeps deferred callbacks in their originating cache scope across observers. */
-export function captureCacheTableOperation(op) {
-    if (op.kind === "barrier" || op.kind === "asyncBarrier") {
-        return { ...op, execute: bindCacheContext(op.execute) };
-    }
-    if (op.kind === "source") {
-        return { ...op, buildSelect: bindCacheContext(op.buildSelect) };
-    }
-    return {
-        ...op,
-        buildSelect: bindCacheContext(op.buildSelect),
-        outputSchema: op.outputSchema === undefined
-            ? undefined
-            : bindCacheContext(op.outputSchema),
-        values: typeof op.values === "function"
-            ? bindCacheContext(op.values)
-            : op.values,
-    };
-}
-function bindCacheContext(callback) {
-    // Capture only the cache scope: a snapshot of all AsyncLocalStorage stores
-    // would also capture stale flush exemptions and async operation frames.
-    // An empty scope keeps unrelated work out of the observer's cache callback.
-    const frames = dependencyContext.getStore() ?? [];
-    return (...args) => dependencyContext.run(frames, () => callback(...args));
-}
-/** Rejects mutations before they can queue work or execute SQL. */
-export function assertCacheTableMutation(table) {
-    for (const frame of dependencyContext.getStore() ?? []) {
-        if (frame.open && table !== frame.cachedTable &&
-            frame.availableBeforeCompute.has(table)) {
-            throw new Error(cacheTableMutationMessage(frame.cachedTable, [table.name]));
-        }
-    }
-}
-/** Tracks callback-owned handles so failure cleanup does not touch other work. */
-export function recordCacheTableCreation(table) {
-    for (const frame of dependencyContext.getStore() ?? []) {
-        if (frame.open && table.sdb === frame.cachedTable.sdb &&
-            !frame.availableBeforeCompute.has(table)) {
-            frame.created.add(table);
-        }
-    }
-}
-/** Tracks queued work across nested callbacks, including async barriers. */
-export function recordCacheTableOperation(table, op) {
-    for (const frame of dependencyContext.getStore() ?? []) {
-        if (frame.open && table.sdb === frame.cachedTable.sdb) {
-            frame.queued.add(op.sequence);
-        }
-    }
-}
-/** Records a table read when a cache computation is observing dependencies. */
-export function recordCacheTableAccess(table) {
-    for (const frame of dependencyContext.getStore() ?? []) {
-        if (frame.open && table.sdb === frame.cachedTable.sdb) {
-            frame.accessed.add(table);
-        }
-    }
-}
-/** Records registered tables named in user-supplied SQL fragments. */
-export function recordCacheTableReferences(table, sql) {
-    if (dependencyContext.getStore() === undefined) {
-        return;
-    }
-    for (const candidate of referencedTables(sql, table.sdb)) {
-        recordCacheTableAccess(candidate);
-    }
-}
-/** Runs a cache computation while collecting the tables it reads. */
-export async function captureCacheTableDependencies(cachedTable, compute) {
-    const availableBeforeCompute = new Map(getRegisteredTables(cachedTable.sdb).map((table) => [
-        table,
-        {
-            tableName: table.name,
-            generationId: peekTableGeneration(table),
-        },
-    ]));
-    const accessed = new Set();
-    const frame = {
-        cachedTable,
-        availableBeforeCompute,
-        accessed,
-        created: new Set(),
-        queued: new Set(),
-        open: true,
-    };
-    try {
-        await dependencyContext.run([...(dependencyContext.getStore() ?? []), frame], async () => {
-            await compute();
-            // A callback can queue a whole computation without observing it.
-            // Reject leaked handles before executing that pending computation.
-            assertCacheTableCleanup(frame);
-            await flushAllTables(cachedTable.sdb);
-            // Async barriers may create tables during the final flush.
-            assertCacheTableCleanup(frame);
-        });
-    }
-    catch (error) {
-        await cleanupCacheComputation(frame);
-        throw error;
-    }
-    finally {
-        frame.open = false;
-    }
-    return [...accessed]
-        .filter((table) => table !== cachedTable && availableBeforeCompute.has(table))
-        .map((table) => {
-        const snapshot = availableBeforeCompute.get(table);
-        if (snapshot === undefined) {
-            throw new Error("A cache table dependency snapshot is missing.");
-        }
-        return {
-            tableName: snapshot.tableName,
-            generationId: snapshot.generationId ?? getTableGeneration(table),
-        };
-    })
-        .sort((left, right) => left.tableName.localeCompare(right.tableName));
-}
-function assertCacheTableCleanup(frame) {
-    const created = getRegisteredTables(frame.cachedTable.sdb)
-        .filter((table) => frame.created.has(table));
-    if (created.length > 0) {
-        throw new Error(cacheTableCleanupMessage(created.map((table) => table.name)));
-    }
-}
-async function cleanupCacheComputation(frame) {
-    const sdb = frame.cachedTable.sdb;
-    // Drop only this callback's pending operations, preserving other queues and
-    // their database-wide ordering. A nested failure also discards work captured
-    // by an enclosing async barrier, which is stored outside pendingOps.
-    for (const table of getRegisteredTables(sdb)) {
-        const retained = table.pendingOps.filter((op) => !frame.queued.has(op.sequence));
-        sdb.pendingCount -= table.pendingOps.length - retained.length;
-        table.pendingOps.splice(0, table.pendingOps.length, ...retained);
-    }
-    const operationFrame = getAsyncOperationFrame(sdb);
-    if (operationFrame !== undefined) {
-        operationFrame.entries = operationFrame.entries.filter((entry) => !frame.queued.has(entry.op.sequence));
-    }
-    const created = getRegisteredTables(sdb)
-        .filter((table) => frame.created.has(table));
-    if (created.length === 0)
-        return;
-    // Observers inside compute may already have materialized temporary tables.
-    // Cleanup must not flush work requeued after an execution error.
-    const removeCreatedTables = () => runExemptFromFlush(sdb, async () => {
-        for (const table of created) {
-            await sdb.customQuery(`DROP TABLE IF EXISTS ${quoteIdentifier(table.name)};`);
-        }
-    });
-    if (operationFrame === undefined) {
-        await removeCreatedTables();
-    }
-    else {
-        // Async frames take precedence over the database-wide flush exemption.
-        // Suppress their drain too, without consuming unrelated captured work.
-        await runWhileDrainingAsyncOperationFrame(operationFrame, removeCreatedTables);
-    }
-    retainRegisteredTables(sdb, (table) => !frame.created.has(table));
-}
-function cacheTableMutationMessage(cachedTable, changedTables) {
-    const tables = changedTables.map((name) => JSON.stringify(name)).join(", ");
-    const cachedTableName = JSON.stringify(cachedTable.name);
-    if (changedTables.length === 1) {
-        return `cache() called on ${cachedTableName} cannot modify pre-existing table ${tables}. Modify ${tables} outside this cache() call.`;
-    }
-    return `cache() called on ${cachedTableName} cannot modify pre-existing tables ${tables}. Modify these tables outside this cache() call.`;
-}
-function cacheTableCleanupMessage(createdTables) {
-    const tables = createdTables.map((name) => JSON.stringify(name)).join(", ");
-    if (createdTables.length === 1) {
-        return `cache() created table ${tables} but did not remove it. Call removeTable() on ${tables} before the callback finishes to avoid downstream errors when the cache is loaded and this table is not recreated.`;
-    }
-    return `cache() created tables ${tables} but did not remove them. Call removeTable() on these tables before the callback finishes to avoid downstream errors when the cache is loaded and these tables are not recreated.`;
-}
-/** Checks persisted dependencies against the current registered tables. */
-export function cacheTableDependenciesMatch(cachedTable, dependencies) {
-    if (dependencies === undefined) {
-        return false;
-    }
-    const registered = getRegisteredTables(cachedTable.sdb);
-    return dependencies.every((dependency) => {
-        const table = registered.find((candidate) => candidate.name === dependency.tableName);
-        return table !== undefined &&
-            getTableGeneration(table) === dependency.generationId;
-    });
-}
-/** Describes changed or unavailable table dependencies for verbose logging. */
-export function changedCacheTableDependenciesMessage(cachedTable, dependencies) {
-    const registered = getRegisteredTables(cachedTable.sdb);
-    const changed = [];
-    const unchanged = [];
-    for (const dependency of dependencies) {
-        const table = registered.find((candidate) => candidate.name === dependency.tableName);
-        if (table === undefined ||
-            getTableGeneration(table) !== dependency.generationId) {
-            changed.push(dependency);
-        }
-        else {
-            unchanged.push(dependency);
-        }
-    }
-    return [
-        cacheTableDependencyStatusMessage("changed", changed),
-        cacheTableDependencyStatusMessage("unchanged", unchanged),
-    ].filter((message) => message.length > 0).join("\n");
-}
-/** Lists unchanged dependencies for cache-hit verbose logging. */
-export function unchangedCacheTableDependenciesMessage(dependencies) {
-    return cacheTableDependencyStatusMessage("unchanged", dependencies);
-}
-function cacheTableDependencyStatusMessage(status, dependencies) {
-    if (dependencies.length === 0) {
-        return "";
-    }
-    return `Table dependencies ${status}: ${dependencies.map((dependency) => JSON.stringify(dependency.tableName))
-        .join(", ")}.`;
-}

package/esm/helpers/camelCase.d.ts

@@ -1,32 +0,0 @@
-/**
- * Converts a string into camelCase. This is useful for creating variable
- * names or object keys from human-readable text.
- *
- * @example
- * ```ts
- * // Basic conversion
- * const result1 = camelCase("hello world");
- * console.log(result1); // "helloWorld"
- * ```
- *
- * @example
- * ```ts
- * // With punctuation and mixed case
- * const result2 = camelCase("  --Some@Thing is- happening--  ");
- * console.log(result2); // "someThingIsHappening"
- * ```
- *
- * @example
- * ```ts
- * // With a single word
- * const result3 = camelCase("Journalism");
- * console.log(result3); // "journalism"
- * ```
- *
- * @param input - The string to convert to camelCase. It can contain spaces,
- *   punctuation, and mixed casing.
- *
- * @returns The camelCased version of the input string.
- */
-export default function camelCase(input: string): string;
-//# sourceMappingURL=camelCase.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"camelCase.d.ts","sourceRoot":"","sources":["../../src/helpers/camelCase.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,CAAC,OAAO,UAAU,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAiBvD"}

package/esm/helpers/camelCase.js

@@ -1,47 +0,0 @@
-import capitalize from "./capitalize.js";
-/**
- * Converts a string into camelCase. This is useful for creating variable
- * names or object keys from human-readable text.
- *
- * @example
- * ```ts
- * // Basic conversion
- * const result1 = camelCase("hello world");
- * console.log(result1); // "helloWorld"
- * ```
- *
- * @example
- * ```ts
- * // With punctuation and mixed case
- * const result2 = camelCase("  --Some@Thing is- happening--  ");
- * console.log(result2); // "someThingIsHappening"
- * ```
- *
- * @example
- * ```ts
- * // With a single word
- * const result3 = camelCase("Journalism");
- * console.log(result3); // "journalism"
- * ```
- *
- * @param input - The string to convert to camelCase. It can contain spaces,
- *   punctuation, and mixed casing.
- *
- * @returns The camelCased version of the input string.
- */
-export default function camelCase(input) {
-    const words = input
-        .replace(/[^a-zA-Z0-9\s]/g, " ")
-        .split(/\s+/)
-        .filter((d) => d !== "");
-    const camelCaseString = words
-        .map((word, index) => {
-        word = word.toLowerCase();
-        if (index > 0) {
-            word = capitalize(word);
-        }
-        return word;
-    })
-        .join("");
-    return camelCaseString;
-}

package/esm/helpers/capitalize.d.ts

@@ -1,30 +0,0 @@
-/**
- * Capitalizes the first letter of a given string.
- *
- * @example
- * ```ts
- * // Basic usage
- * const capitalized = capitalize("hello world");
- * console.log(capitalized); // "Hello world"
- * ```
- *
- * @example
- * ```ts
- * // With an already capitalized string
- * const alreadyCapitalized = capitalize("Journalism");
- * console.log(alreadyCapitalized); // "Journalism"
- * ```
- *
- * @example
- * ```ts
- * // With a single character
- * const singleChar = capitalize("a");
- * console.log(singleChar); // "A"
- * ```
- *
- * @param string - The string to be capitalized.
- *
- * @returns A new string with the first letter in uppercase.
- */
-export default function capitalize(string: string): string;
-//# sourceMappingURL=capitalize.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"capitalize.d.ts","sourceRoot":"","sources":["../../src/helpers/capitalize.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,CAAC,OAAO,UAAU,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAMzD"}

package/esm/helpers/capitalize.js

@@ -1,35 +0,0 @@
-/**
- * Capitalizes the first letter of a given string.
- *
- * @example
- * ```ts
- * // Basic usage
- * const capitalized = capitalize("hello world");
- * console.log(capitalized); // "Hello world"
- * ```
- *
- * @example
- * ```ts
- * // With an already capitalized string
- * const alreadyCapitalized = capitalize("Journalism");
- * console.log(alreadyCapitalized); // "Journalism"
- * ```
- *
- * @example
- * ```ts
- * // With a single character
- * const singleChar = capitalize("a");
- * console.log(singleChar); // "A"
- * ```
- *
- * @param string - The string to be capitalized.
- *
- * @returns A new string with the first letter in uppercase.
- */
-export default function capitalize(string) {
-    if (string.length === 0) {
-        return string;
-    }
-    const first = string[0];
-    return first.toUpperCase() + string.slice(1);
-}

package/esm/helpers/cleanCache.d.ts

@@ -1,3 +0,0 @@
-import type SimpleDB from "../class/SimpleDB.js";
-export default function cleanCache(sdb: SimpleDB, log?: (message: string) => void): void;
-//# sourceMappingURL=cleanCache.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"cleanCache.d.ts","sourceRoot":"","sources":["../../src/helpers/cleanCache.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,QAAQ,MAAM,sBAAsB,CAAC;AAEjD,MAAM,CAAC,OAAO,UAAU,UAAU,CAChC,GAAG,EAAE,QAAQ,EACb,GAAG,GAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAkB,QAoB7C"}

package/esm/helpers/cleanCache.js

@@ -1,17 +0,0 @@
-import { readFileSync, unlinkSync, writeFileSync } from "node:fs";
-export default function cleanCache(sdb, log = console.log) {
-    if (sdb.cacheSourcesUsed.length > 0) {
-        const cacheSources = JSON.parse(readFileSync(".sda-cache/sources.json", "utf-8"));
-        for (const cacheId of Object.keys(cacheSources)) {
-            if (!sdb.cacheSourcesUsed.includes(cacheId)) {
-                if (cacheSources[cacheId].file !== null) {
-                    sdb.cacheVerbose &&
-                        log(`Removing unused file from cache: ${cacheSources[cacheId].file}`);
-                    unlinkSync(cacheSources[cacheId].file);
-                }
-                delete cacheSources[cacheId];
-            }
-        }
-        writeFileSync(".sda-cache/sources.json", JSON.stringify(cacheSources));
-    }
-}

package/esm/helpers/cleanPath.d.ts

@@ -1,2 +0,0 @@
-export default function cleanPath(file: string): string;
-//# sourceMappingURL=cleanPath.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"cleanPath.d.ts","sourceRoot":"","sources":["../../src/helpers/cleanPath.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,OAAO,UAAU,SAAS,CAAC,IAAI,EAAE,MAAM,UAE7C"}

package/esm/helpers/cleanPath.js

@@ -1,3 +0,0 @@
-export default function cleanPath(file) {
-    return file.replaceAll("'", "''");
-}

package/esm/helpers/cleanSQL.d.ts

@@ -1,2 +0,0 @@
-export default function cleanSQL(query: string, syntax?: "js" | "sql"): string;
-//# sourceMappingURL=cleanSQL.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"cleanSQL.d.ts","sourceRoot":"","sources":["../../src/helpers/cleanSQL.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,OAAO,UAAU,QAAQ,CAC9B,KAAK,EAAE,MAAM,EACb,MAAM,GAAE,IAAI,GAAG,KAAY,GAC1B,MAAM,CAqRR"}