@nshiab/simple-data-analysis-core 1.0.0 → 2.0.0

package/script/helpers/ensureSpatial.js

@@ -0,0 +1,23 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = ensureSpatial;
+const mergeOptions_js_1 = __importDefault(require("./mergeOptions.js"));
+const queryDB_js_1 = __importDefault(require("./queryDB.js"));
+/**
+ * Loads the spatial extension once per connection, so geospatial operations
+ * can fuse as plain SELECT fragments instead of each being multi-statement.
+ */
+async function ensureSpatial(simpleTable) {
+    if (simpleTable.sdb.spatialLoaded) {
+        return;
+    }
+    await (0, queryDB_js_1.default)(simpleTable, `INSTALL spatial; LOAD spatial; SET geometry_always_xy = true;`, (0, mergeOptions_js_1.default)(simpleTable, {
+        table: null,
+        method: null,
+        parameters: null,
+    }));
+    simpleTable.sdb.spatialLoaded = true;
+}

package/script/helpers/extractTypes.d.ts

@@ -1,5 +1,5 @@
 export default function extractTypes(types: {
-    [key: string]: string | number | boolean | Date | null;
+    [key: string]: unknown;
 }[] | null): {
     [key: string]: string;
 };

package/script/helpers/extractTypes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"extractTypes.d.ts","sourceRoot":"","sources":["../../src/helpers/extractTypes.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,OAAO,UAAU,YAAY,CAClC,KAAK,EAAE;IACL,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG,IAAI,CAAC;CACxD,EAAE,GAAG,IAAI;;EAaX"}
+{"version":3,"file":"extractTypes.d.ts","sourceRoot":"","sources":["../../src/helpers/extractTypes.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,OAAO,UAAU,YAAY,CAClC,KAAK,EAAE;IACL,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB,EAAE,GAAG,IAAI;;EAaX"}

package/script/helpers/extractZipEntryToFile.d.ts

@@ -0,0 +1,3 @@
+/** Extracts one entry from a non-ZIP64, single-disk ZIP without buffering it. */
+export default function extractZipEntryToFile(archive: string, wantedName: string, output: string): Promise<void>;
+//# sourceMappingURL=extractZipEntryToFile.d.ts.map

package/script/helpers/extractZipEntryToFile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extractZipEntryToFile.d.ts","sourceRoot":"","sources":["../../src/helpers/extractZipEntryToFile.ts"],"names":[],"mappings":"AAgDA,iFAAiF;AACjF,wBAA8B,qBAAqB,CACjD,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,IAAI,CAAC,CAyEf"}

package/script/helpers/extractZipEntryToFile.js

@@ -0,0 +1,229 @@
+"use strict";
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
+    if (kind === "m") throw new TypeError("Private method is not writable");
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
+    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
+};
+var _ChecksumTransform_crc;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = extractZipEntryToFile;
+const node_fs_1 = require("node:fs");
+const promises_1 = require("node:fs/promises");
+const node_stream_1 = require("node:stream");
+const promises_2 = require("node:stream/promises");
+const node_zlib_1 = require("node:zlib");
+/*
+ * Adapted from the ZIP reader in @nshiab/journalism-web-scraping. This
+ * version streams the selected entry to disk so complete StatCan tables do
+ * not need to be buffered in JavaScript memory.
+ */
+const END_OF_CENTRAL_DIRECTORY = 0x0605_4b50;
+const CENTRAL_DIRECTORY_ENTRY = 0x0201_4b50;
+const LOCAL_FILE_HEADER = 0x0403_4b50;
+const MAX_COMMENT_LENGTH = 0xffff;
+const MAX_END_RECORD_LENGTH = 22 + MAX_COMMENT_LENGTH;
+const CRC_TABLE = createCrcTable();
+class ChecksumTransform extends node_stream_1.Transform {
+    constructor() {
+        super(...arguments);
+        _ChecksumTransform_crc.set(this, 0xffff_ffff);
+        Object.defineProperty(this, "size", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 0
+        });
+    }
+    get crc32() {
+        return (__classPrivateFieldGet(this, _ChecksumTransform_crc, "f") ^ 0xffff_ffff) >>> 0;
+    }
+    _transform(chunk, _encoding, callback) {
+        for (const byte of chunk) {
+            __classPrivateFieldSet(this, _ChecksumTransform_crc, CRC_TABLE[(__classPrivateFieldGet(this, _ChecksumTransform_crc, "f") ^ byte) & 0xff] ^ (__classPrivateFieldGet(this, _ChecksumTransform_crc, "f") >>> 8), "f");
+        }
+        this.size += chunk.byteLength;
+        callback(null, chunk);
+    }
+}
+_ChecksumTransform_crc = new WeakMap();
+/** Extracts one entry from a non-ZIP64, single-disk ZIP without buffering it. */
+async function extractZipEntryToFile(archive, wantedName, output) {
+    const entry = await findZipEntry(archive, wantedName);
+    if (entry === undefined) {
+        throw new Error(`No ${wantedName} in the zipped file.`);
+    }
+    if (entry.compressionMethod !== 0 && entry.compressionMethod !== 8) {
+        throw new Error(`ZIP entry ${wantedName} uses unsupported compression method ${entry.compressionMethod}.`);
+    }
+    const file = await (0, promises_1.open)(archive, "r");
+    let operationError;
+    try {
+        const localHeader = new Uint8Array(30);
+        await readExactly(file, localHeader, entry.localHeaderOffset);
+        const view = new DataView(localHeader.buffer);
+        assertSignature(view, 0, LOCAL_FILE_HEADER, "local file header");
+        const fileNameLength = view.getUint16(26, true);
+        const extraLength = view.getUint16(28, true);
+        const dataOffset = entry.localHeaderOffset + 30 + fileNameLength +
+            extraLength;
+        const checksum = new ChecksumTransform();
+        const source = (0, node_fs_1.createReadStream)(archive, {
+            start: dataOffset,
+            end: dataOffset + entry.compressedSize - 1,
+        });
+        const streams = entry.compressionMethod === 8
+            ? [
+                source,
+                (0, node_zlib_1.createInflateRaw)(),
+                checksum,
+                (0, node_fs_1.createWriteStream)(output, {
+                    flags: "wx",
+                }),
+            ]
+            : [source, checksum, (0, node_fs_1.createWriteStream)(output, { flags: "wx" })];
+        await (0, promises_2.pipeline)(streams);
+        if (checksum.size !== entry.uncompressedSize) {
+            throw new Error(`ZIP entry ${wantedName} has an invalid size.`);
+        }
+        if (checksum.crc32 !== entry.expectedCrc) {
+            throw new Error(`ZIP entry ${wantedName} failed its CRC check.`);
+        }
+    }
+    catch (error) {
+        operationError = error;
+    }
+    try {
+        await file.close();
+    }
+    catch (closeError) {
+        operationError = operationError === undefined
+            ? closeError
+            : new AggregateError([operationError, closeError], "Extracting and closing the ZIP archive both failed.", { cause: operationError });
+    }
+    if (operationError !== undefined) {
+        try {
+            await (0, promises_1.rm)(output, { force: true });
+        }
+        catch (cleanupError) {
+            throw new AggregateError([operationError, cleanupError], "Extracting and cleaning up the ZIP entry both failed.", { cause: operationError });
+        }
+        throw operationError;
+    }
+}
+async function findZipEntry(archive, wantedName) {
+    const file = await (0, promises_1.open)(archive, "r");
+    try {
+        const size = (await (0, promises_1.stat)(archive)).size;
+        const tailLength = Math.min(size, MAX_END_RECORD_LENGTH);
+        const tail = new Uint8Array(tailLength);
+        await readExactly(file, tail, size - tailLength);
+        const tailView = new DataView(tail.buffer);
+        const endOffset = findEndOfCentralDirectory(tailView);
+        const diskNumber = tailView.getUint16(endOffset + 4, true);
+        const centralDirectoryDisk = tailView.getUint16(endOffset + 6, true);
+        const entriesOnDisk = tailView.getUint16(endOffset + 8, true);
+        const entryCount = tailView.getUint16(endOffset + 10, true);
+        const centralDirectorySize = tailView.getUint32(endOffset + 12, true);
+        const centralDirectoryOffset = tailView.getUint32(endOffset + 16, true);
+        if (diskNumber !== 0 || centralDirectoryDisk !== 0 ||
+            entriesOnDisk !== entryCount) {
+            throw new Error("Multi-disk ZIP archives are not supported.");
+        }
+        if (entryCount === 0xffff || centralDirectorySize === 0xffff_ffff ||
+            centralDirectoryOffset === 0xffff_ffff) {
+            throw new Error("ZIP64 archives are not supported.");
+        }
+        if (centralDirectoryOffset + centralDirectorySize > size) {
+            throw new Error("Invalid ZIP archive: truncated central directory.");
+        }
+        const centralDirectory = new Uint8Array(centralDirectorySize);
+        await readExactly(file, centralDirectory, centralDirectoryOffset);
+        const view = new DataView(centralDirectory.buffer);
+        let offset = 0;
+        for (let index = 0; index < entryCount; index++) {
+            assertSignature(view, offset, CENTRAL_DIRECTORY_ENTRY, "central directory");
+            assertRange(centralDirectory, offset, 46, "central directory entry");
+            const flags = view.getUint16(offset + 8, true);
+            const compressionMethod = view.getUint16(offset + 10, true);
+            const expectedCrc = view.getUint32(offset + 16, true);
+            const compressedSize = view.getUint32(offset + 20, true);
+            const uncompressedSize = view.getUint32(offset + 24, true);
+            const fileNameLength = view.getUint16(offset + 28, true);
+            const extraLength = view.getUint16(offset + 30, true);
+            const commentLength = view.getUint16(offset + 32, true);
+            const localHeaderOffset = view.getUint32(offset + 42, true);
+            const entryLength = 46 + fileNameLength + extraLength + commentLength;
+            assertRange(centralDirectory, offset, entryLength, "central directory entry");
+            const name = new TextDecoder().decode(centralDirectory.subarray(offset + 46, offset + 46 + fileNameLength));
+            if (name === wantedName) {
+                if ((flags & 1) !== 0) {
+                    throw new Error(`ZIP entry ${wantedName} is encrypted.`);
+                }
+                if (compressedSize === 0xffff_ffff ||
+                    uncompressedSize === 0xffff_ffff ||
+                    localHeaderOffset === 0xffff_ffff) {
+                    throw new Error("ZIP64 archives are not supported.");
+                }
+                return {
+                    compressionMethod,
+                    compressedSize,
+                    uncompressedSize,
+                    expectedCrc,
+                    localHeaderOffset,
+                };
+            }
+            offset += entryLength;
+        }
+        return undefined;
+    }
+    finally {
+        await file.close();
+    }
+}
+async function readExactly(file, buffer, position) {
+    let offset = 0;
+    while (offset < buffer.byteLength) {
+        const { bytesRead } = await file.read(buffer, offset, buffer.byteLength - offset, position + offset);
+        if (bytesRead === 0) {
+            throw new Error("Invalid ZIP archive: unexpected end of file.");
+        }
+        offset += bytesRead;
+    }
+}
+function findEndOfCentralDirectory(view) {
+    for (let offset = view.byteLength - 22; offset >= 0; offset--) {
+        if (view.getUint32(offset, true) === END_OF_CENTRAL_DIRECTORY &&
+            offset + 22 + view.getUint16(offset + 20, true) === view.byteLength) {
+            return offset;
+        }
+    }
+    throw new Error("Invalid ZIP archive: end of central directory not found.");
+}
+function assertSignature(view, offset, expected, description) {
+    if (offset < 0 || offset + 4 > view.byteLength) {
+        throw new Error(`Invalid ZIP archive: truncated ${description}.`);
+    }
+    if (view.getUint32(offset, true) !== expected) {
+        throw new Error(`Invalid ZIP archive: malformed ${description}.`);
+    }
+}
+function assertRange(data, offset, length, description) {
+    if (offset < 0 || length < 0 || offset + length > data.byteLength) {
+        throw new Error(`Invalid ZIP archive: truncated ${description}.`);
+    }
+}
+function createCrcTable() {
+    return Uint32Array.from({ length: 256 }, (_, index) => {
+        let value = index;
+        for (let bit = 0; bit < 8; bit++) {
+            value = (value >>> 1) ^ (0xedb8_8320 & -(value & 1));
+        }
+        return value >>> 0;
+    });
+}

package/script/helpers/fileCache.d.ts

@@ -0,0 +1,15 @@
+import type SimpleTable from "../class/SimpleTable.js";
+export declare function createFileCacheId(prefix: string, identity: unknown): string;
+export default function fileCache(table: SimpleTable, options: {
+    directory: string;
+    enabled: boolean;
+    extension: string;
+    formatVersion: string;
+    id: string;
+    method: string;
+    ttl?: number;
+    load: (file: string) => Promise<void>;
+    compute: () => Promise<void>;
+    write: (file: string) => Promise<void>;
+}): Promise<void>;
+//# sourceMappingURL=fileCache.d.ts.map

package/script/helpers/fileCache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fileCache.d.ts","sourceRoot":"","sources":["../../src/helpers/fileCache.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,WAAW,MAAM,yBAAyB,CAAC;AAiBvD,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,GAAG,MAAM,CAK3E;AAED,wBAA8B,SAAS,CACrC,KAAK,EAAE,WAAW,EAClB,OAAO,EAAE;IACP,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACtC,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7B,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACxC,GACA,OAAO,CAAC,IAAI,CAAC,CAef"}

package/script/helpers/fileCache.js

@@ -0,0 +1,135 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createFileCacheId = createFileCacheId;
+exports.default = fileCache;
+const node_crypto_1 = __importDefault(require("node:crypto"));
+const node_fs_1 = require("node:fs");
+const cacheDiagnostics_js_1 = require("./cacheDiagnostics.js");
+const prettyDuration_js_1 = __importDefault(require("./prettyDuration.js"));
+function createFileCacheId(prefix, identity) {
+    const hash = node_crypto_1.default.createHash("sha256")
+        .update(JSON.stringify(identity))
+        .digest("hex");
+    return `${prefix}.${hash}`;
+}
+async function fileCache(table, options) {
+    if (!options.enabled) {
+        logFileCacheDisabled(table, options.method);
+    }
+    else if (await loadFileCache(table, options)) {
+        return;
+    }
+    const start = Date.now();
+    await options.compute();
+    if (options.enabled) {
+        await writeFileCache(table, {
+            ...options,
+            duration: Date.now() - start,
+        });
+    }
+}
+async function loadFileCache(table, options) {
+    const sourcesFile = `${options.directory}/sources.json`;
+    const sources = readFileCacheSources(sourcesFile);
+    const source = sources[options.id];
+    const now = Date.now();
+    if (table.sdb.cacheVerbose) {
+        console.log(`\n${options.method} cache for ${table.name}`);
+    }
+    if (source === undefined) {
+        logCacheMiss(table, "No matching cache entry exists.");
+        return false;
+    }
+    if (source.formatVersion !== options.formatVersion) {
+        logCacheMiss(table, "The cache format changed.");
+        return false;
+    }
+    if (source.file === null || !(0, node_fs_1.existsSync)(source.file)) {
+        logCacheMiss(table, "The cached file is missing.");
+        return false;
+    }
+    if (options.ttl !== undefined &&
+        (0, cacheDiagnostics_js_1.cacheEntryExpired)(source.creation, options.ttl, now)) {
+        table.sdb.cacheVerbose &&
+            console.log(`Cache entry is stale.\n${(0, cacheDiagnostics_js_1.cacheTtlMessage)(source.creation, options.ttl, now, true)}\nFetching fresh data and refreshing the cache entry.`);
+        return false;
+    }
+    if (table.sdb.cacheVerbose) {
+        console.log("Cache hit.");
+        if (options.ttl !== undefined) {
+            console.log((0, cacheDiagnostics_js_1.cacheTtlMessage)(source.creation, options.ttl, now, false));
+        }
+    }
+    const start = Date.now();
+    try {
+        await options.load(source.file);
+    }
+    catch {
+        (0, node_fs_1.rmSync)(source.file, { force: true });
+        delete sources[options.id];
+        writeFileCacheSources(options.directory, sourcesFile, sources);
+        table.sdb.cacheVerbose &&
+            console.log("Could not load cached data. Fetching fresh data...");
+        return false;
+    }
+    const end = Date.now();
+    if (table.sdb.cacheVerbose) {
+        console.log(`${(0, cacheDiagnostics_js_1.cacheLoadMessage)(start, end, source.duration)}\n`);
+        if (source.duration !== undefined) {
+            table.sdb.cacheTimeSaved += source.duration - (end - start);
+        }
+    }
+    return true;
+}
+async function writeFileCache(table, options) {
+    (0, node_fs_1.mkdirSync)(options.directory, { recursive: true });
+    const file = `${options.directory}/${options.id}.${options.extension}`;
+    const temporaryFile = `${file}.${node_crypto_1.default.randomUUID()}.tmp.${options.extension}`;
+    table.sdb.cacheVerbose &&
+        console.log(`Computations done in ${(0, prettyDuration_js_1.default)(0, { end: options.duration })}.`);
+    const start = Date.now();
+    try {
+        await options.write(temporaryFile);
+        (0, node_fs_1.rmSync)(file, { force: true });
+        (0, node_fs_1.renameSync)(temporaryFile, file);
+    }
+    catch (error) {
+        (0, node_fs_1.rmSync)(temporaryFile, { force: true });
+        throw error;
+    }
+    const end = Date.now();
+    const sourcesFile = `${options.directory}/sources.json`;
+    const sources = readFileCacheSources(sourcesFile);
+    sources[options.id] = {
+        file,
+        creation: Date.now(),
+        duration: options.duration,
+        formatVersion: options.formatVersion,
+    };
+    writeFileCacheSources(options.directory, sourcesFile, sources);
+    if (table.sdb.cacheVerbose) {
+        console.log(`Wrote in cache in ${(0, prettyDuration_js_1.default)(start, { end })}.\n`);
+        table.sdb.cacheTimeWriting += end - start;
+    }
+}
+function logFileCacheDisabled(table, method) {
+    table.sdb.cacheVerbose &&
+        console.log(`\n${method} cache for ${table.name}\nCache disabled.\nFetching fresh data without storing a cache entry.`);
+}
+function logCacheMiss(table, reason) {
+    table.sdb.cacheVerbose &&
+        console.log(`Cache miss.\n${reason}\nFetching fresh data and storing a new cache entry.`);
+}
+function readFileCacheSources(sourcesFile) {
+    if (!(0, node_fs_1.existsSync)(sourcesFile)) {
+        return {};
+    }
+    return JSON.parse((0, node_fs_1.readFileSync)(sourcesFile, "utf-8"));
+}
+function writeFileCacheSources(directory, sourcesFile, sources) {
+    (0, node_fs_1.mkdirSync)(directory, { recursive: true });
+    (0, node_fs_1.writeFileSync)(sourcesFile, JSON.stringify(sources));
+}

package/script/helpers/findGeoColumn.d.ts

@@ -1,3 +1,15 @@
 import type SimpleTable from "../class/SimpleTable.js";
-export default function findGeoColumn(SimpleTable: SimpleTable): Promise<string>;
+/**
+ * Returns the only geometry column in a table.
+ *
+ * @param simpleTable - The table to inspect.
+ * @param method - The SDA method requesting a geometry column.
+ * @returns A promise resolving to the name of the only geometry column.
+ *
+ * @example
+ * ```ts
+ * const column = await findGeoColumn(table, "getGeoData()");
+ * ```
+ */
+export default function findGeoColumn(simpleTable: SimpleTable, method: string): Promise<string>;
 //# sourceMappingURL=findGeoColumn.d.ts.map

package/script/helpers/findGeoColumn.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"findGeoColumn.d.ts","sourceRoot":"","sources":["../../src/helpers/findGeoColumn.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,WAAW,MAAM,yBAAyB,CAAC;AAEvD,wBAA8B,aAAa,CAAC,WAAW,EAAE,WAAW,mBAsBnE"}
+{"version":3,"file":"findGeoColumn.d.ts","sourceRoot":"","sources":["../../src/helpers/findGeoColumn.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,WAAW,MAAM,yBAAyB,CAAC;AAEvD;;;;;;;;;;;GAWG;AACH,wBAA8B,aAAa,CACzC,WAAW,EAAE,WAAW,EACxB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,MAAM,CAAC,CAMjB"}

package/script/helpers/findGeoColumn.js

@@ -1,21 +1,22 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.default = findGeoColumn;
-async function findGeoColumn(SimpleTable) {
-    let column;
-    const types = await SimpleTable.getTypes();
-    const geometries = Object.values(types).filter((d) => d.toLowerCase().includes("geometry"));
-    if (geometries.length === 0) {
-        throw new Error("Table contains no geometry columns.");
-    }
-    else if (geometries.length > 1) {
-        throw new Error("More than one column storing geometries. If the method allows to specify one, do it. Otherwise, use the selectColumns methods beforehand.");
-    }
-    else {
-        column = Object.keys(types).find((d) => types[d].toLowerCase().includes("geometry"));
-    }
-    if (typeof column !== "string") {
-        throw new Error("No column");
-    }
-    return column;
+const findGeoColumnFromSchema_js_1 = __importDefault(require("./findGeoColumnFromSchema.js"));
+/**
+ * Returns the only geometry column in a table.
+ *
+ * @param simpleTable - The table to inspect.
+ * @param method - The SDA method requesting a geometry column.
+ * @returns A promise resolving to the name of the only geometry column.
+ *
+ * @example
+ * ```ts
+ * const column = await findGeoColumn(table, "getGeoData()");
+ * ```
+ */
+async function findGeoColumn(simpleTable, method) {
+    return (0, findGeoColumnFromSchema_js_1.default)(await simpleTable.getTypes(), method, simpleTable.name);
 }

package/script/helpers/findGeoColumnFromSchema.d.ts

@@ -0,0 +1,20 @@
+import type { TableSchema } from "./pendingOps.js";
+/**
+ * Returns the only geometry column in a table schema.
+ *
+ * @param types - The table schema to inspect.
+ * @param method - The SDA method requesting a geometry column.
+ * @param tableName - The name of the table represented by the schema.
+ * @returns The name of the only geometry column.
+ *
+ * @example
+ * ```ts
+ * const column = findGeoColumnFromSchema(
+ *   { geom: "GEOMETRY('EPSG:4326')" },
+ *   "area()",
+ *   "places",
+ * );
+ * ```
+ */
+export default function findGeoColumnFromSchema(types: TableSchema, method: string, tableName: string): string;
+//# sourceMappingURL=findGeoColumnFromSchema.d.ts.map

package/script/helpers/findGeoColumnFromSchema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"findGeoColumnFromSchema.d.ts","sourceRoot":"","sources":["../../src/helpers/findGeoColumnFromSchema.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAEnD;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,OAAO,UAAU,uBAAuB,CAC7C,KAAK,EAAE,WAAW,EAClB,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,GAChB,MAAM,CAoBR"}

package/script/helpers/findGeoColumnFromSchema.js

@@ -0,0 +1,34 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = findGeoColumnFromSchema;
+const quoteIdentifier_js_1 = __importDefault(require("./quoteIdentifier.js"));
+/**
+ * Returns the only geometry column in a table schema.
+ *
+ * @param types - The table schema to inspect.
+ * @param method - The SDA method requesting a geometry column.
+ * @param tableName - The name of the table represented by the schema.
+ * @returns The name of the only geometry column.
+ *
+ * @example
+ * ```ts
+ * const column = findGeoColumnFromSchema(
+ *   { geom: "GEOMETRY('EPSG:4326')" },
+ *   "area()",
+ *   "places",
+ * );
+ * ```
+ */
+function findGeoColumnFromSchema(types, method, tableName) {
+    const geometryColumns = Object.keys(types).filter((column) => types[column].toLowerCase().includes("geometry")).sort();
+    if (geometryColumns.length === 0) {
+        throw new Error(`${method} could not find a geometry column in table ${(0, quoteIdentifier_js_1.default)(tableName)}. Specify a geometry column explicitly, or add one to the table first.`);
+    }
+    else if (geometryColumns.length > 1) {
+        throw new Error(`${method} found ${geometryColumns.length} geometry columns in table ${(0, quoteIdentifier_js_1.default)(tableName)}: ${geometryColumns.map(quoteIdentifier_js_1.default).join(", ")}. Specify one explicitly.`);
+    }
+    return geometryColumns[0];
+}

package/script/helpers/flushAllTables.d.ts

@@ -0,0 +1,23 @@
+import type SimpleDB from "../class/SimpleDB.js";
+/**
+ * Runs `fn` with `sdb` exempt from the top-level flush. Queries issued by an
+ * asynchronous barrier can still drain operations queued inside that barrier.
+ * Used by the flush itself and by connection setup, whose queries must run
+ * before any queued operation.
+ */
+export declare function runExemptFromFlush<T>(sdb: SimpleDB, fn: () => Promise<T>): Promise<T>;
+/**
+ * Executes the pending operations of all tables in program order: every
+ * queued operation carries a database-wide sequence number, so operations
+ * on different tables replay exactly in the order the user queued them,
+ * like immediate execution would. Consecutive fusable operations on the
+ * same table compose as CTEs into a single statement; barriers execute
+ * in order between fused segments.
+ *
+ * Every query execution point goes through this (via queryDB). Only one
+ * flush runs at a time: concurrent observers wait for the in-flight flush,
+ * then flush whatever queued in the meantime, so an awaited observer always
+ * answers from fully executed state.
+ */
+export default function flushAllTables(sdb: SimpleDB): Promise<void>;
+//# sourceMappingURL=flushAllTables.d.ts.map

package/script/helpers/flushAllTables.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flushAllTables.d.ts","sourceRoot":"","sources":["../../src/helpers/flushAllTables.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,QAAQ,MAAM,sBAAsB,CAAC;AAiCjD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAClC,GAAG,EAAE,QAAQ,EACb,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACnB,OAAO,CAAC,CAAC,CAAC,CAIZ;AAED;;;;;;;;;;;;GAYG;AACH,wBAA8B,cAAc,CAAC,GAAG,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAgCzE"}