@nshiab/simple-data-analysis-core 2.0.2 → 2.0.4

package/esm/methods/loadOpenStreetMap.js

@@ -0,0 +1,368 @@
+import { realpathSync, rmSync, statSync } from "node:fs";
+import { resolve } from "node:path";
+import SDAError from "../class/SDAError.js";
+import loadOsmFile from "../helpers/loadOsmFile.js";
+import { createOsmCacheId, useProcessedOsmCache } from "../helpers/osmCache.js";
+import { downloadOsmToTemporaryFile, formatBytes, getOsmFileSuffix, isRemoteOsmUrl, normalizeRemoteOsmUrl, sanitizeOsmUrl, } from "../helpers/osmFiles.js";
+import mergeOptions from "../helpers/mergeOptions.js";
+import prettyDuration from "../helpers/prettyDuration.js";
+import queryDB from "../helpers/queryDB.js";
+import quoteIdentifier from "../helpers/quoteIdentifier.js";
+import queueOp from "../helpers/queueOp.js";
+const DEFAULT_OVERPASS_ENDPOINT = "https://overpass-api.de/api/interpreter";
+const DEFAULT_REMOTE_FILE_TIMEOUT = 30 * 60;
+const QUERY_GENERATOR_VERSION = "overpass-ql-v1";
+export default function loadOpenStreetMap(table, source, options = {}) {
+    if (typeof source === "string") {
+        queueOpenStreetMapFileLoad(table, source, options);
+        return;
+    }
+    queueOverpassLoad(table, source, options);
+}
+function queueOpenStreetMapFileLoad(table, file, options) {
+    const suffix = getOsmFileSuffix(file);
+    if (suffix === null) {
+        throw new Error("loadOpenStreetMap() file paths and URLs must end with .osm or .osm.pbf.");
+    }
+    options = structuredClone(options);
+    assertOptions(options, false);
+    let remoteUrl;
+    if (isRemoteOsmUrl(file)) {
+        remoteUrl = normalizeRemoteOsmUrl(file);
+    }
+    else {
+        try {
+            const url = new URL(file);
+            if (url.protocol !== "http:" && url.protocol !== "https:") {
+                throw new Error("loadOpenStreetMap() URL sources must use HTTP or HTTPS.");
+            }
+        }
+        catch (error) {
+            if (error instanceof Error && error.message.includes("must use HTTP")) {
+                throw error;
+            }
+        }
+        if (options.retries !== undefined || options.retryDelay !== undefined) {
+            throw new Error("loadOpenStreetMap() options.retries and options.retryDelay are network-only and cannot be used with a local path.");
+        }
+    }
+    const parameters = { file, options };
+    queueOp(table, {
+        kind: "barrier",
+        method: "loadOpenStreetMap()",
+        parameters,
+        execute: () => executeOpenStreetMapFileLoad(table, remoteUrl ?? file, suffix, options, parameters),
+    });
+}
+async function executeOpenStreetMapFileLoad(table, file, suffix, options, parameters) {
+    const started = Date.now();
+    const verbose = options.verbose === true || table.sdb.cacheVerbose;
+    const remote = isRemoteOsmUrl(file);
+    const displayedSource = remote ? sanitizeOsmUrl(file) : resolve(file);
+    verbose && console.log(`loadOpenStreetMap(): loading ${displayedSource}`);
+    try {
+        if (remote) {
+            const cacheId = createOsmCacheId({ kind: "remote", url: file });
+            await useProcessedOsmCache(table, {
+                id: cacheId,
+                enabled: options.cache ?? true,
+                ttl: options.ttl,
+                verbose,
+                parameters,
+                compute: async () => {
+                    const temporaryFile = await downloadOsmToTemporaryFile(file, {
+                        suffix,
+                        prefix: cacheId,
+                        request: { headers: { "accept-encoding": "gzip" } },
+                        retries: options.retries,
+                        retryDelay: options.retryDelay,
+                        timeout: DEFAULT_REMOTE_FILE_TIMEOUT,
+                        verbose,
+                    });
+                    try {
+                        await processOsmFile(table, temporaryFile, parameters, verbose);
+                    }
+                    finally {
+                        rmSync(temporaryFile, { force: true });
+                        verbose && console.log("Removed the temporary raw OSM download.");
+                    }
+                },
+            });
+        }
+        else {
+            verbose &&
+                console.log("Resolving and fingerprinting the local OSM file...");
+            const fingerprintStarted = Date.now();
+            const resolvedPath = realpathSync(resolve(file));
+            const stat = statSync(resolvedPath, { bigint: true });
+            if (!stat.isFile()) {
+                throw new Error(`The OpenStreetMap source is not a file: ${resolvedPath}`);
+            }
+            verbose && console.log(`Resolved ${formatBytes(Number(stat.size))} and fingerprinted it in ${prettyDuration(fingerprintStarted)}.`);
+            const cacheId = createOsmCacheId({
+                kind: "local",
+                path: resolvedPath,
+                size: stat.size.toString(),
+                mtimeNs: stat.mtimeNs.toString(),
+            });
+            await useProcessedOsmCache(table, {
+                id: cacheId,
+                enabled: options.cache ?? true,
+                ttl: options.ttl,
+                verbose,
+                parameters,
+                compute: () => processOsmFile(table, resolvedPath, parameters, verbose),
+            });
+        }
+        verbose && console.log(`loadOpenStreetMap(): completed in ${prettyDuration(started)}.`);
+    }
+    catch (error) {
+        if (error instanceof SDAError)
+            throw error;
+        throw new SDAError({
+            method: "loadOpenStreetMap()",
+            parameters,
+            query: "",
+            cause: error,
+        });
+    }
+}
+function queueOverpassLoad(table, bbox, options) {
+    bbox = normalizeBoundingBox(bbox);
+    options = structuredClone(options);
+    assertOptions(options, true);
+    const endpoint = normalizeEndpoint(options.endpoint ?? DEFAULT_OVERPASS_ENDPOINT);
+    const filters = normalizeFilters(options.filters);
+    const query = generateOverpassQuery(bbox, filters, options.timeout);
+    const parameters = { bbox, options };
+    queueOp(table, {
+        kind: "barrier",
+        method: "loadOpenStreetMap()",
+        parameters,
+        execute: () => executeOverpassLoad(table, options, endpoint, query, parameters),
+    });
+}
+async function executeOverpassLoad(table, options, endpoint, query, parameters) {
+    const started = Date.now();
+    const verbose = options.verbose === true || table.sdb.cacheVerbose;
+    verbose && console.log(`loadOpenStreetMap(): querying ${sanitizeOsmUrl(endpoint)}`);
+    try {
+        const cacheId = createOsmCacheId({
+            kind: "overpass",
+            endpoint,
+            query,
+            queryGeneratorVersion: QUERY_GENERATOR_VERSION,
+        });
+        await useProcessedOsmCache(table, {
+            id: cacheId,
+            enabled: options.cache ?? true,
+            ttl: options.ttl,
+            verbose,
+            parameters,
+            compute: async () => {
+                const body = new URLSearchParams({ data: query });
+                const temporaryFile = await downloadOsmToTemporaryFile(endpoint, {
+                    suffix: ".osm",
+                    prefix: cacheId,
+                    request: {
+                        method: "POST",
+                        headers: {
+                            "accept-encoding": "gzip",
+                            "content-type": "application/x-www-form-urlencoded;charset=UTF-8",
+                            "user-agent": "simple-data-analysis-core (https://github.com/nshiab/simple-data-analysis-core)",
+                        },
+                        body,
+                    },
+                    retries: options.retries,
+                    retryDelay: options.retryDelay,
+                    timeout: options.timeout,
+                    overpass: true,
+                    verbose,
+                });
+                try {
+                    try {
+                        await assertSuccessfulOverpassResponse(temporaryFile);
+                    }
+                    catch (error) {
+                        const reason = error instanceof Error
+                            ? error.message
+                            : String(error);
+                        throw new Error(`${reason}\nNot retrying because the Overpass response was well-formed and reported a query error.\nNo invalid cached data was returned.`, { cause: error });
+                    }
+                    await processOsmFile(table, temporaryFile, parameters, verbose);
+                }
+                finally {
+                    rmSync(temporaryFile, { force: true });
+                    verbose &&
+                        console.log("Removed the temporary raw Overpass download.");
+                }
+            },
+        });
+        verbose && console.log(`loadOpenStreetMap(): completed in ${prettyDuration(started)}.`);
+    }
+    catch (error) {
+        if (error instanceof SDAError)
+            throw error;
+        throw new SDAError({
+            method: "loadOpenStreetMap()",
+            parameters,
+            query,
+            cause: error,
+        });
+    }
+}
+async function processOsmFile(table, file, parameters, verbose) {
+    verbose && console.log("Processing OSM data with Osmium...");
+    const started = Date.now();
+    try {
+        await loadOsmFile(table, file, {
+            method: "loadOpenStreetMap()",
+            parameters,
+        });
+    }
+    catch (error) {
+        const cause = error instanceof SDAError ? error.cause : error;
+        const reason = cause instanceof Error ? cause.message : String(cause);
+        throw new Error(`${reason}\nNot retrying because Osmium or a downstream DuckDB operation rejected the source data.\nNo invalid cached data was returned.`, { cause: error });
+    }
+    if (verbose) {
+        const data = await queryDB(table, `SELECT count(*)::DOUBLE AS count FROM ${quoteIdentifier(table.name)};`, mergeOptions(table, {
+            table: table.name,
+            method: "loadOpenStreetMap()",
+            parameters,
+            returnData: true,
+        }));
+        const count = Number(data?.[0]?.count ?? 0);
+        console.log(`Processed ${count.toLocaleString("en-US")} rows in ${prettyDuration(started)}.`);
+    }
+}
+async function assertSuccessfulOverpassResponse(file) {
+    const contents = await Deno.readTextFile(file);
+    const match = /<(remark|error)\b[^>]*>([\s\S]*?)(?:<\/\1\s*>|$)/i.exec(contents);
+    if (match === null)
+        return;
+    const message = match[2]
+        .replace(/<[^>]*>/g, " ")
+        .replace(/\s+/g, " ")
+        .trim()
+        .slice(0, 500);
+    throw new Error(message.length === 0
+        ? "The Overpass endpoint returned an error response."
+        : `The Overpass endpoint returned an error response: ${message}`);
+}
+export function generateOverpassQuery(bbox, filters, timeout) {
+    const box = `${bbox.south},${bbox.west},${bbox.north},${bbox.east}`;
+    const selections = filters.map((filter) => `nwr${filter}(${box});`);
+    const selection = selections.length === 1
+        ? selections[0]
+        : `(${selections.join("")});`;
+    return `[out:xml]${timeout === undefined ? "" : `[timeout:${timeout}]`};${selection}(._;>;);out body;`;
+}
+function normalizeBoundingBox(bbox) {
+    const normalized = structuredClone(bbox);
+    for (const [name, value] of Object.entries(normalized)) {
+        if (!Number.isFinite(value)) {
+            throw new Error(`loadOpenStreetMap() bbox.${name} must be a finite number.`);
+        }
+    }
+    if (normalized.west < -180 || normalized.west > 180) {
+        throw new Error("loadOpenStreetMap() bbox.west must be between -180 and 180.");
+    }
+    if (normalized.east < -180 || normalized.east > 180) {
+        throw new Error("loadOpenStreetMap() bbox.east must be between -180 and 180.");
+    }
+    if (normalized.south < -90 || normalized.south > 90) {
+        throw new Error("loadOpenStreetMap() bbox.south must be between -90 and 90.");
+    }
+    if (normalized.north < -90 || normalized.north > 90) {
+        throw new Error("loadOpenStreetMap() bbox.north must be between -90 and 90.");
+    }
+    if (normalized.west >= normalized.east) {
+        throw new Error("loadOpenStreetMap() bbox.west must be less than bbox.east.");
+    }
+    if (normalized.south >= normalized.north) {
+        throw new Error("loadOpenStreetMap() bbox.south must be less than bbox.north.");
+    }
+    normalized.west = Object.is(normalized.west, -0) ? 0 : normalized.west;
+    normalized.south = Object.is(normalized.south, -0) ? 0 : normalized.south;
+    normalized.east = Object.is(normalized.east, -0) ? 0 : normalized.east;
+    normalized.north = Object.is(normalized.north, -0) ? 0 : normalized.north;
+    return normalized;
+}
+function normalizeFilters(filters) {
+    if (typeof filters === "string") {
+        const filter = filters.trim();
+        if (filter.length === 0) {
+            throw new Error("loadOpenStreetMap() filters must contain at least one non-empty filter fragment.");
+        }
+        return [filter];
+    }
+    if (!Array.isArray(filters)) {
+        throw new TypeError("loadOpenStreetMap() options.filters is required.");
+    }
+    const tuples = isFilterTuple(filters) ? [filters] : filters;
+    const normalized = tuples.map(([key, value]) => {
+        if (typeof key !== "string" || typeof value !== "string") {
+            throw new TypeError("loadOpenStreetMap() filter tuples must contain two strings.");
+        }
+        if (key.length === 0) {
+            throw new Error("loadOpenStreetMap() filter keys must not be empty.");
+        }
+        return `[${JSON.stringify(key)}=${JSON.stringify(value)}]`;
+    });
+    if (normalized.length === 0) {
+        throw new Error("loadOpenStreetMap() filters must contain at least one filter tuple.");
+    }
+    return normalized;
+}
+function isFilterTuple(filters) {
+    return filters.length === 2 && typeof filters[0] === "string" &&
+        typeof filters[1] === "string";
+}
+function normalizeEndpoint(endpoint) {
+    try {
+        return normalizeRemoteOsmUrl(endpoint);
+    }
+    catch {
+        throw new Error("loadOpenStreetMap() endpoint must be a valid HTTP or HTTPS URL.");
+    }
+}
+function assertOptions(options, overpass) {
+    const allowed = new Set([
+        "cache",
+        "ttl",
+        "retries",
+        "retryDelay",
+        "verbose",
+        ...(overpass ? ["filters", "endpoint", "timeout"] : []),
+    ]);
+    const unsupported = Object.keys(options).filter((key) => !allowed.has(key));
+    if (unsupported.length > 0) {
+        throw new Error(`loadOpenStreetMap() does not support ${unsupported.map((key) => `options.${key}`).join(", ")} for this source. Apply filtering and projection with normal table methods after loading.`);
+    }
+    if (options.cache !== undefined && typeof options.cache !== "boolean") {
+        throw new TypeError("loadOpenStreetMap() options.cache must be a boolean.");
+    }
+    if (options.verbose !== undefined && typeof options.verbose !== "boolean") {
+        throw new TypeError("loadOpenStreetMap() options.verbose must be a boolean.");
+    }
+    if (options.ttl !== undefined &&
+        (!Number.isFinite(options.ttl) || options.ttl < 0)) {
+        throw new Error("loadOpenStreetMap() options.ttl must be a finite, non-negative number of seconds.");
+    }
+    if (options.cache === false && options.ttl !== undefined) {
+        throw new Error("loadOpenStreetMap() options.cache cannot be false when options.ttl is set.");
+    }
+    if (options.retries !== undefined &&
+        (!Number.isInteger(options.retries) || options.retries < 0)) {
+        throw new Error("loadOpenStreetMap() options.retries must be a non-negative integer.");
+    }
+    if (options.retryDelay !== undefined &&
+        (!Number.isFinite(options.retryDelay) || options.retryDelay < 0)) {
+        throw new Error("loadOpenStreetMap() options.retryDelay must be a finite, non-negative number of seconds.");
+    }
+    if (overpass && options.timeout !== undefined &&
+        (!Number.isInteger(options.timeout) || options.timeout <= 0)) {
+        throw new Error("loadOpenStreetMap() options.timeout must be a positive integer in seconds.");
+    }
+}

package/llm.md

@@ -1,5 +1,8 @@
 # The Simple Data Analysis (Core) Library
 
+- Package: `@nshiab/simple-data-analysis-core`
+- Version: `2.0.4`
+
 To install the library with Deno, use:
 
 ```bash
@@ -948,8 +951,9 @@ loadStatCanData(pid: string, options?: { lang?: "en" | "fr"; cache?: boolean; tt
 - **`options`**: Optional retrieval and cache settings.
 - **`options.lang`**: The language of the table data. Defaults to `"en"`.
 - **`options.cache`**: Whether to read and write the cache. Defaults to `true`.
-- **`options.ttl`**: Cache time to live in seconds. By default, cached data does
-  not expire. Use `0` to refresh and replace the cache entry.
+- **`options.ttl`**: Cache lifetime in seconds. Omit for no expiration, use `0`
+  to refresh the matching cache entry immediately, or provide a positive value
+  to refresh once the entry reaches that age.
 
 ##### Returns
 
@@ -977,9 +981,7 @@ await table
 
 #### `loadGeoData`
 
-Loads geospatial data from an external file or URL into the table. OpenStreetMap
-`.osm` and `.osm.pbf` files are loaded through DuckDB's Osmium community
-extension.
+Loads geospatial data from an external file or URL into the table.
 
 This method queues the operation; it runs when an async observer method (like
 `getData()` or `log()`) is awaited, or when `run()` is called.
@@ -992,8 +994,8 @@ loadGeoData(file: string, options?: { toEPSG4326?: boolean; columns?: string[];
 
 ##### Parameters
 
-- **`file`**: The URL or absolute path to the external file containing the
-  geospatial data.
+- **`file`**: The path or URL of the external file containing the geospatial
+  data.
 - **`options`**: An optional object with configuration options:
 - **`options.toEPSG4326`**: If `true`, the method will attempt to reproject the
   data to EPSG:4326 (WGS84).
@@ -1004,8 +1006,8 @@ loadGeoData(file: string, options?: { toEPSG4326?: boolean; columns?: string[];
   keyword, to filter source rows before materialization and reprojection. Uses
   the same syntax as `filter()`, including JavaScript operators. Can reference
   source columns excluded from `columns`. Geometry conditions use the source
-  coordinate system; OSM geometry is available as `geom` in EPSG:4326. Defaults
-  to no filtering; an empty string behaves the same as omitting this option.
+  coordinate system. Defaults to no filtering; an empty string behaves the same
+  as omitting this option.
 
 ##### Returns
 
@@ -1043,11 +1045,6 @@ await table.loadGeoData("./some-data/some-data.shp", { toEPSG4326: true })
 await table.loadGeoData("./some-data.shp.zip", { toEPSG4326: true }).log();
 ```
 
-```ts
-// Load OpenStreetMap XML or PBF data
-await table.loadGeoData("./montreal.osm.pbf").log();
-```
-
 ```ts
 // Filter on a source property without retaining it in the table
 await table
@@ -1058,22 +1055,29 @@ await table
   .log();
 ```
 
-#### `loadOSM`
+#### `loadOpenStreetMap`
 
-Downloads OpenStreetMap data and loads it as a geospatial table. The method
-queues the download and load; they run when an async observer method (like
-`getData()` or `log()`) is awaited, or when `run()` is called.
+Loads OpenStreetMap data into the table from a local `.osm` or `.osm.pbf` file,
+a remote file URL, or an Overpass bounding-box query. Pass a path or URL string
+to load an existing file, or pass a bounding box with `filters` to download
+matching features. The method queues the load; it runs when an async observer
+method (like `getData()` or `log()`) is awaited, or when `run()` is called.
 
 DuckDB's
 [Osmium community extension](https://duckdb.org/community_extensions/extensions/osmium)
-reconstructs the geometries, which are stored with the EPSG:4326 projection.
-
-Filters use the standard
+materializes the complete result and reconstructs `geom` as EPSG:4326. By
+default, that canonical result is cached as GeoParquet in `.sda-cache/osm`.
+Distinct paths, local file fingerprints, normalized URLs, endpoints, queries,
+and bounding boxes retain independent entries. The cache has no expiration
+unless `ttl` is set and can be cleared by removing `.sda-cache/osm`. Immutable
+URLs can safely use the default indefinite cache; mutable URLs should set a TTL.
+
+Bounding-box filters use the standard
 [Overpass QL filter syntax](https://wiki.openstreetmap.org/wiki/Overpass_API/Overpass_QL#Filters).
 Equality filters are passed as `[key, value]` tuples and serialized by the
 method. A raw filter fragment string can be used for advanced Overpass filters.
 
-The default endpoint is a shared public service. Follow the
+The default Overpass endpoint is a shared public service. Follow the
 [Overpass public-instance usage guidelines](https://dev.overpass-api.de/overpass-doc/en/preface/commons.html),
 and configure another endpoint or run your own instance for high-volume usage.
 
@@ -1087,33 +1091,48 @@ share-alike requirements.
 ##### Signature
 
 ```typescript
-loadOSM(bbox: { west: number; south: number; east: number; north: number }, options: { filters: string | [string, string] | [string, string][]; endpoint?: string; timeout?: number; cache?: boolean }): this;
+loadOpenStreetMap(source: string | { west: number; south: number; east: number; north: number }, options?: { filters?: string | [string, string] | [string, string][]; endpoint?: string; timeout?: number; cache?: boolean; ttl?: number; retries?: number; retryDelay?: number; verbose?: boolean }): this;
 ```
 
 ##### Parameters
 
-- **`bbox`**: The bounding box to query.
-- **`bbox.west`**: The western longitude, between -180 and 180 and less than
+- **`source`**: The local path or remote URL of an existing `.osm` or `.osm.pbf`
+  file, or a bounding box to query through Overpass.
+- **`source.west`**: The western longitude, between -180 and 180 and less than
   `east`.
-- **`bbox.south`**: The southern latitude, between -90 and 90 and less than
+- **`source.south`**: The southern latitude, between -90 and 90 and less than
   `north`.
-- **`bbox.east`**: The eastern longitude, between -180 and 180 and greater than
-  `west`.
-- **`bbox.north`**: The northern latitude, between -90 and 90 and greater than
+- **`source.east`**: The eastern longitude, between -180 and 180 and greater
+  than `west`.
+- **`source.north`**: The northern latitude, between -90 and 90 and greater than
   `south`.
-- **`options`**: Overpass request options.
-- **`options.filters`**: One `[key, value]` tuple or an array of tuples. Array
-  entries are combined as a union. A raw Overpass QL filter fragment string is
-  also accepted.
+- **`options`**: Loading options. When `source` is a bounding box,
+  `options.filters` must be provided.
+- **`options.filters`**: For a bounding-box query, one `[key, value]` tuple or
+  an array of tuples. Array entries are combined as a union. A raw Overpass QL
+  filter fragment string is also accepted.
 - **`options.endpoint`**: The Overpass interpreter endpoint. Defaults to
   `https://overpass-api.de/api/interpreter`.
 - **`options.timeout`**: A positive integer timeout in seconds, applied to both
   the Overpass query and HTTP request. If omitted, the endpoint's default query
   timeout applies and no HTTP request timeout is set.
-- **`options.cache`**: If `true`, reads and writes the processed GeoParquet
-  cache in `.sda-cache/osm`, which remains available until that directory is
-  removed. If `false`, always requests fresh data and does not read or write the
-  cache. Defaults to `true`.
+- **`options.cache`**: Whether to read and write the processed GeoParquet cache.
+  Defaults to `true`.
+- **`options.ttl`**: Cache lifetime in seconds. Omit for no expiration, use `0`
+  to refresh the matching cache entry immediately, or provide a positive value
+  to refresh once the processed entry reaches that age. Cannot be combined with
+  `cache: false`.
+- **`options.retries`**: Additional network retries after the initial request.
+  Defaults to `3`, for up to four attempts. Network-only; passing it for a local
+  path throws an error.
+- **`options.retryDelay`**: Base retry delay in seconds. Defaults to `5`,
+  producing deterministic delays of 5, 10, and 20 seconds. A longer valid
+  `Retry-After` value takes precedence. Network-only; passing it for a local
+  path throws an error.
+- **`options.verbose`**: Whether to log OpenStreetMap cache, network, Osmium,
+  cleanup, and timing lifecycle details. Defaults to `false`.
+  `SimpleDB({ cacheVerbose: true })` also enables these messages and is not
+  overridden by `verbose: false`.
 
 ##### Returns
 
@@ -1122,9 +1141,23 @@ The table, so methods can be chained.
 ##### Examples
 
 ```ts
-// Load features matching one equality filter
-const schools = await table
-  .loadOSM(
+// Load an existing local OpenStreetMap PBF file
+await table.loadOpenStreetMap("./montreal.osm.pbf").log();
+```
+
+```ts
+// Filter and project after the complete canonical source has loaded
+await table
+  .loadOpenStreetMap("./montreal.osm.pbf", { verbose: true })
+  .filter("tags['amenity'] = 'school'")
+  .selectColumns(["id", "tags", "geom"])
+  .log();
+```
+
+```ts
+// Download features matching one equality filter within a bounding box
+await table
+  .loadOpenStreetMap(
     { west: -73.587799, south: 45.445078, east: -73.552265, north: 45.471086 },
     { filters: ["amenity", "school"] },
   )
@@ -1132,8 +1165,8 @@ const schools = await table
 ```
 
 ```ts
-// Load features matching either equality filter
-await table.loadOSM(
+// Download features matching either equality filter
+await table.loadOpenStreetMap(
   { west: -73.587799, south: 45.445078, east: -73.552265, north: 45.471086 },
   {
     filters: [["amenity", "school"], ["amenity", "college"]],
@@ -1143,7 +1176,7 @@ await table.loadOSM(
 
 ```ts
 // Use a raw Overpass filter fragment for an advanced filter
-await table.loadOSM(
+await table.loadOpenStreetMap(
   { west: -73.587799, south: 45.445078, east: -73.552265, north: 45.471086 },
   { filters: `["amenity"~"school|college"]` },
 ).log();
@@ -7511,9 +7544,9 @@ async cache(compute: (table: this) => void | Promise<void>, options?: { inputs?:
   cache. Functions and class constructors are compared by source. `SimpleTable`
   dependencies read by `compute` are tracked automatically, and the table being
   cached is already tracked, so neither needs to be included here.
-- **`options.ttl`**: Time to live (in seconds). If the data in the cache is
-  older than this duration, the `compute` function will be executed again to
-  refresh the cache. By default, there is no TTL; the cache is invalidated when
+- **`options.ttl`**: Cache lifetime in seconds. Omit for no expiration, use `0`
+  to refresh the matching cache entry immediately, or provide a positive value
+  to refresh once the entry reaches that age. The cache is also invalidated when
   the `compute` function, the table, or an input changes.
 
 ##### Returns

package/llms.txt

@@ -2,6 +2,9 @@
 
 > Lightweight DuckDB-powered TypeScript library for tabular, SQL, CSV, Parquet, and geospatial data analysis on Deno, Node.js, and Bun.
 
+- Package: `@nshiab/simple-data-analysis-core`
+- Version: `2.0.4`
+
 Install with Deno: `deno add jsr:@nshiab/simple-data-analysis-core`
 
 Install with Node.js: `npm i @nshiab/simple-data-analysis-core`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nshiab/simple-data-analysis-core",
-  "version": "2.0.2",
+  "version": "2.0.4",
   "description": "Lightweight DuckDB-powered TypeScript library for tabular, SQL, CSV, Parquet, and geospatial data analysis on Deno, Node.js, and Bun.",
   "keywords": [
     "data-analysis",