keepset 0.42.0 → 0.43.0

package/dist/browser/entry.d.ts

@@ -0,0 +1,55 @@
+import { z as Dataset } from "../categories-BG8lRjy8.js";
+import { a as FetchPort, c as Provenance, d as fetchDataset$1, f as fetchEntry$1, i as FetchOptions, l as RoundTripReport, n as Download, o as FetchedDataset, p as roundTripEntry$1, r as DownloadProvenance, s as FilesProvenance, t as DigestPort, u as downloadUrl } from "../fetch-HjZj2roj.js";
+//#region src/browser/download.d.ts
+/** How long a request may take in all, at any point of a download, before it is given up as dead. The platform `fetch` reports progress to no one, so the stall watch of the Node downloader becomes a whole-request deadline here; a healthy server of the open data portals recipes read answers well inside it. */
+export declare const STALL_MILLISECONDS = 120000;
+/** How many times a download is tried when its connection fails, and how long each retry waits for the one before it (the delay times the attempt number), the policy the Node downloader keeps. */
+export declare const DOWNLOAD_ATTEMPTS = 3;
+export declare const RETRY_DELAY_MILLISECONDS = 3000;
+/** Options for one download: the signal that aborts it, and the deadlines only a test shortens. */
+interface DownloadInit {
+  readonly signal?: AbortSignal;
+  readonly stallMilliseconds?: number;
+  readonly retryDelayMilliseconds?: number;
+}
+/**
+ * Downloads a URL's bytes, following redirects as the platform does. See the module comment for the one difference from the Node downloader no browser can avoid.
+ * @param url - An http or https URL.
+ * @param init - The request options.
+ * @returns A Response holding the bytes the platform delivers, with the final status.
+ * @throws KeepsetError when the URL is not http or https, or the request passes its deadline; the connection's failure, after the tries, when it keeps failing.
+ */
+export declare function downloadRaw(url: string, init: DownloadInit): Promise<Response>;
+//#endregion
+//#region src/browser/entry.d.ts
+export type BrowserFetchOptions = Omit<FetchOptions, "fetch" | "digest">;
+/**
+ * Fetches a dataset of the bundled catalogue by id through the platform's downloader and digest. See `../fetch`'s `fetchEntry` for what a fetch does; see `./download` for the one way the platform's bytes can differ from Node's.
+ * @param id - The entry id.
+ * @param options - An abort signal and the clock.
+ * @returns The fetched dataset.
+ */
+export declare function fetchDataset(id: string, options: BrowserFetchOptions): Promise<Awaited<ReturnType<typeof fetchDataset$1>>>;
+/**
+ * Fetches a dataset object through the platform's downloader and digest.
+ * @param dataset - A dataset from any catalogue.
+ * @param options - An abort signal and the clock.
+ * @returns The fetched dataset.
+ */
+export declare function fetchEntry(dataset: Dataset, options: BrowserFetchOptions): Promise<Awaited<ReturnType<typeof fetchEntry$1>>>;
+/**
+ * Checks a dataset's crosswalk on its real data through the platform's ports.
+ * @param dataset - A dataset from any catalogue.
+ * @param options - An abort signal and the clock.
+ * @returns Whether the round trip holds.
+ */
+export declare function roundTripEntry(dataset: Dataset, options: BrowserFetchOptions): Promise<Awaited<ReturnType<typeof roundTripEntry$1>>>;
+/**
+ * Runs `roundTripEntry` on a dataset of the bundled catalogue by id.
+ * @param id - The entry id.
+ * @param options - An abort signal and the clock.
+ * @returns Whether the round trip holds.
+ */
+export declare function roundTripDataset(id: string, options: BrowserFetchOptions): Promise<Awaited<ReturnType<typeof roundTripEntry$1>>>;
+//#endregion
+export { type DigestPort, type Download, type DownloadInit, type DownloadProvenance, type FetchOptions, type FetchPort, type FetchedDataset, type FilesProvenance, type Provenance, type RoundTripReport, downloadUrl };

package/dist/browser/entry.js

@@ -0,0 +1,107 @@
+import { ft as KeepsetError } from "../bundled-OrF_TPDq.js";
+import { i as roundTripEntry$1, n as fetchDataset$1, r as fetchEntry$1, t as downloadUrl } from "../fetch-A4VG2QuN.js";
+//#region src/browser/download.ts
+/** How long a request may take in all, at any point of a download, before it is given up as dead. The platform `fetch` reports progress to no one, so the stall watch of the Node downloader becomes a whole-request deadline here; a healthy server of the open data portals recipes read answers well inside it. */
+const STALL_MILLISECONDS = 12e4;
+/** How many times a download is tried when its connection fails, and how long each retry waits for the one before it (the delay times the attempt number), the policy the Node downloader keeps. */
+const DOWNLOAD_ATTEMPTS = 3;
+const RETRY_DELAY_MILLISECONDS = 3e3;
+/**
+* Downloads a URL's bytes, following redirects as the platform does. See the module comment for the one difference from the Node downloader no browser can avoid.
+* @param url - An http or https URL.
+* @param init - The request options.
+* @returns A Response holding the bytes the platform delivers, with the final status.
+* @throws KeepsetError when the URL is not http or https, or the request passes its deadline; the connection's failure, after the tries, when it keeps failing.
+*/
+async function downloadRaw(url, init) {
+	return await tryDownload(url, init, 1);
+}
+/**
+* One try of a download, and the tries after it while the connection fails.
+* @param url - The URL.
+* @param init - The request options.
+* @param attempt - Which try this is, from 1.
+* @returns The response.
+* @throws The last failure when the tries are used up, or at once for a failure that is not the connection's.
+*/
+async function tryDownload(url, init, attempt) {
+	const parsed = new URL(url);
+	if (parsed.protocol !== "http:" && parsed.protocol !== "https:") throw new KeepsetError(`${url} is not an http or https URL`);
+	const deadline = new AbortController();
+	const timer = setTimeout(() => {
+		deadline.abort(new KeepsetError(`${url} did not finish within ${String(init.stallMilliseconds ?? 12e4)} milliseconds, so the request was given up as dead`));
+	}, init.stallMilliseconds ?? 12e4);
+	const abort = () => {
+		deadline.abort(init.signal?.reason);
+	};
+	init.signal?.addEventListener("abort", abort, { once: true });
+	try {
+		return await fetch(url, {
+			signal: deadline.signal,
+			headers: { accept: "*/*" }
+		});
+	} catch (error) {
+		if (init.signal?.aborted === true) throw init.signal.reason;
+		if (attempt >= 3) throw error;
+		await new Promise((resolve) => {
+			setTimeout(resolve, (init.retryDelayMilliseconds ?? 3e3) * attempt);
+		});
+		return await tryDownload(url, init, attempt + 1);
+	} finally {
+		clearTimeout(timer);
+		init.signal?.removeEventListener("abort", abort);
+	}
+}
+//#endregion
+//#region src/browser/entry.ts
+/** The radix of one byte's two hex characters, and their count. */
+const HEX_RADIX = 16;
+const HEX_DIGITS = 2;
+/** The platform's SHA-256, which SubtleCrypto answers; a copy, so the hash reads an ArrayBuffer even when the bytes arrived as a view over a SharedArrayBuffer. */
+const digest = async (bytes) => {
+	const hashed = await crypto.subtle.digest("SHA-256", new Uint8Array(bytes));
+	return [...new Uint8Array(hashed)].map((byte) => byte.toString(HEX_RADIX).padStart(HEX_DIGITS, "0")).join("");
+};
+const ports = (options) => ({
+	...options,
+	fetch: downloadRaw,
+	digest
+});
+/**
+* Fetches a dataset of the bundled catalogue by id through the platform's downloader and digest. See `../fetch`'s `fetchEntry` for what a fetch does; see `./download` for the one way the platform's bytes can differ from Node's.
+* @param id - The entry id.
+* @param options - An abort signal and the clock.
+* @returns The fetched dataset.
+*/
+async function fetchDataset(id, options) {
+	return fetchDataset$1(id, ports(options));
+}
+/**
+* Fetches a dataset object through the platform's downloader and digest.
+* @param dataset - A dataset from any catalogue.
+* @param options - An abort signal and the clock.
+* @returns The fetched dataset.
+*/
+async function fetchEntry(dataset, options) {
+	return fetchEntry$1(dataset, ports(options));
+}
+/**
+* Checks a dataset's crosswalk on its real data through the platform's ports.
+* @param dataset - A dataset from any catalogue.
+* @param options - An abort signal and the clock.
+* @returns Whether the round trip holds.
+*/
+async function roundTripEntry(dataset, options) {
+	return roundTripEntry$1(dataset, ports(options));
+}
+/**
+* Runs `roundTripEntry` on a dataset of the bundled catalogue by id.
+* @param id - The entry id.
+* @param options - An abort signal and the clock.
+* @returns Whether the round trip holds.
+*/
+async function roundTripDataset(id, options) {
+	return roundTripEntry$1((await import("../bundled-OrF_TPDq.js").then((n) => n.t)).getDataset(id), ports(options));
+}
+//#endregion
+export { DOWNLOAD_ATTEMPTS, RETRY_DELAY_MILLISECONDS, STALL_MILLISECONDS, downloadRaw, downloadUrl, fetchDataset, fetchEntry, roundTripDataset, roundTripEntry };

package/dist/{bundled-B1094k0B.js → bundled-OrF_TPDq.js}

@@ -1,5 +1,17 @@
 import { CrosswalkSchema, validateCrosswalk } from "crossmap";
 import { z } from "zod";
+//#region \0rolldown/runtime.js
+var __defProp = Object.defineProperty;
+var __exportAll = (all, no_symbols) => {
+	let target = {};
+	for (var name in all) __defProp(target, name, {
+		get: all[name],
+		enumerable: true
+	});
+	if (!no_symbols) __defProp(target, Symbol.toStringTag, { value: "Module" });
+	return target;
+};
+//#endregion
 //#region src/errors.ts
 /** The root of this package's error taxonomy: every error keepset throws is a `KeepsetError`, so callers can catch the family with one check. */
 var KeepsetError = class extends Error {
@@ -68812,6 +68824,12 @@ var catalogue_default = {
 };
 //#endregion
 //#region src/bundled.ts
+var bundled_exports = /* @__PURE__ */ __exportAll({
+	getDataset: () => getDataset,
+	getManifest: () => getManifest,
+	listDatasets: () => listDatasets,
+	listNamespaces: () => listNamespaces
+});
 let bundled;
 /** The catalogue shipped in this package, assembled from catalogue/ by the build and parsed on first use, so importing the package costs nothing until a query runs. */
 function catalogue() {
@@ -68848,4 +68866,4 @@ function getManifest() {
 	return catalogue().manifest;
 }
 //#endregion
-export { TaskSchema as $, SourceRecipeSchema as A, groupsOf as B, LicenceSchema as C, RecipeSchema as D, RESERVED_META_KEYS as E, rawSnapshotUrl as F, countedKeys as G, getOwn as H, readsCollection as I, getStreamedShape as J, getCategory as K, toIssues as L, SubjectSchema as M, WaybackTimestampSchema as N, RelativePathSchema as O, parseEntry as P, listCategories as Q, waybackUrl as R, IdSchema as S, ParserSchema as T, CategoryIdSchema as U, namesOf as V, countTarget as W, isStreamable as X, getTarget as Y, kindOf as Z, ColumnNameSchema as _, CatalogueIndexSchema as a, GraphV1Schema as at, FilesRecipeSchema as b, ManifestSchema as c, CatalogueSyntaxError as ct, AliasSchema as d, KeepsetError as dt, TasksMetaSchema as et, ArchiveMemberSchema as f, NativeParseError as ft, CollectionFileSchema as g, CollectionArchiveSchema as h, listNamespaces as i, GraphNodeSchema as it, SourceSchema as j, SnapshotSchema as k, SemVerSchema as l, DatasetAmbiguousError as lt, CitationSchema as m, UnknownCategoryError as mt, getManifest as n, collectionOf as nt, createCatalogue as o, JsonScalarSchema as ot, ArchiveSchema as p, RecipeError as pt, getCollectionTarget as q, listDatasets as r, GraphEdgeSchema as rt, LineageSchema as s, ArchiveError as st, getDataset as t, TasksV1Schema as tt, parseManifest as u, DatasetNotFoundError as ut, CrosswalkReferenceSchema as v, NamespaceSchema as w, HttpUrlSchema as x, EntrySchema as y, NAME_SEPARATOR as z };
+export { listCategories as $, SnapshotSchema as A, NAME_SEPARATOR as B, IdSchema as C, RESERVED_META_KEYS as D, ParserSchema as E, parseEntry as F, countTarget as G, namesOf as H, rawSnapshotUrl as I, getCollectionTarget as J, countedKeys as K, readsCollection as L, SourceSchema as M, SubjectSchema as N, RecipeSchema as O, WaybackTimestampSchema as P, kindOf as Q, toIssues as R, HttpUrlSchema as S, NamespaceSchema as T, getOwn as U, groupsOf as V, CategoryIdSchema as W, getTarget as X, getStreamedShape as Y, isStreamable as Z, CollectionFileSchema as _, listNamespaces as a, GraphNodeSchema as at, EntrySchema as b, LineageSchema as c, ArchiveError as ct, parseManifest as d, DatasetNotFoundError as dt, TaskSchema as et, AliasSchema as f, KeepsetError as ft, CollectionArchiveSchema as g, CitationSchema as h, UnknownCategoryError as ht, listDatasets as i, GraphEdgeSchema as it, SourceRecipeSchema as j, RelativePathSchema as k, ManifestSchema as l, CatalogueSyntaxError as lt, ArchiveSchema as m, RecipeError as mt, getDataset as n, TasksV1Schema as nt, CatalogueIndexSchema as o, GraphV1Schema as ot, ArchiveMemberSchema as p, NativeParseError as pt, getCategory as q, getManifest as r, collectionOf as rt, createCatalogue as s, JsonScalarSchema as st, bundled_exports as t, TasksMetaSchema as tt, SemVerSchema as u, DatasetAmbiguousError as ut, ColumnNameSchema as v, LicenceSchema as w, FilesRecipeSchema as x, CrosswalkReferenceSchema as y, waybackUrl as z };