@maschinenlesbar.org/pegel-online-cli 0.0.8 → 0.2.0

package/README.md

@@ -86,16 +86,20 @@ level); other codes include `Q` (flow/discharge), `WT` (water temperature), and
 | `--waters <shortname>` | filter by water shortname (see `waters`) |
 | `--fuzzy-id <id>` | fuzzy match against short/long name |
 | `--include-timeseries` | embed each station's timeseries list |
-| `--include-current` | embed the current measurement |
-| `--include-characteristic` | embed characteristic (gauge-mark) values |
+| `--include-current` | embed the current measurement in each timeseries (implies `--include-timeseries`) |
+| `--include-characteristic` | embed characteristic (gauge-mark) values in each timeseries (implies `--include-timeseries`) |
 
 ### `stations get` options
 
 | Flag | Meaning |
 | --- | --- |
 | `--include-timeseries` | embed the station's timeseries list |
-| `--include-current` | embed the current measurement |
-| `--include-characteristic` | embed characteristic (gauge-mark) values |
+| `--include-current` | embed the current measurement in each timeseries (implies `--include-timeseries`) |
+| `--include-characteristic` | embed characteristic (gauge-mark) values in each timeseries (implies `--include-timeseries`) |
+
+The API nests the current measurement and the gauge marks *inside* each
+timeseries and drops them without the timeseries list, so `--include-current` and
+`--include-characteristic` turn on `--include-timeseries` themselves.
 
 ### `measurements` options
 
@@ -187,15 +191,23 @@ both `pegel --compact waters` and `pegel waters --compact` do the same thing.
   `PATH`. Run `npm bin -g` to find it and add it, or run via
   `npx @maschinenlesbar.org/pegel-online-cli …`.
 - **Exit `2` / "invalid argument"** — check the command syntax: a `<station>`
-  argument is required, and `--start` / `--end` must be valid ISO-8601 instants or
-  periods (e.g. `P7D`). Run `pegel <command> --help` for the exact signature.
-- **Exit `4` / "not found"** — the station shortname or id doesn't exist. Run
-  `pegel stations list --fuzzy-id <name>` or `pegel waters` to find the right
-  shortname.
+  argument is required, and no argument or option value may be blank (or `.` /
+  `..` for an id). Run `pegel <command> --help` for the exact signature.
+- **Exit `4` / "not found"** — the station shortname or id doesn't exist, or the
+  station doesn't publish the requested series (`Timeseries does not exist.` /
+  `Current measurement does not exist.`). Run `pegel stations list --fuzzy-id <name>`
+  or `pegel waters` to find the right shortname, and
+  `pegel stations get <station> --include-timeseries | jq -r '.timeseries[].shortname'`
+  to see which series codes it exposes.
+- **Exit `1` / `HTTP 400` on `measurements`** — `--start` / `--end` are not checked
+  locally; the API rejects a value that is not an ISO-8601 instant or period
+  (`Given start parameter is neither a valid ISO date time, nor an ISO period.`) and
+  a window whose start is not before its end (e.g. a start in the future). Use
+  `P7D`, not `7d`.
+- **Empty `[]` from `measurements`** — the window lies outside the data the API
+  keeps (about the last month), e.g. a date from earlier in the year.
 - **Exit `1` / network error** — connectivity, DNS, or a timeout. Try again, or
   raise the limit with `--timeout 60000`.
-- **Empty `timeseries` array** — the station doesn't publish the requested series.
-  Run `pegel timeseries <station>` to see which codes it actually exposes.
 
 ## Global options
 
@@ -206,10 +218,10 @@ These apply to every command and may be given before *or* after it:
 | `-V, --version` | Print the version number |
 | `-h, --help` | Show help for the program or a command |
 | `--compact` | Print JSON on a single line instead of pretty-printed |
-| `--base-url <url>` | API base URL (default `https://www.pegelonline.wsv.de`) |
+| `--base-url <url>` | API base URL (default `https://www.pegelonline.wsv.de`); http(s) only, a path prefix is fine, no query (`?`), fragment (`#`), whitespace or control characters; userinfo is sent as Basic auth but shown as `***` in messages |
 | `--timeout <ms>` | Time limit per request in milliseconds, reading the whole response included (default `30000`; at most `2147483647`) |
-| `--user-agent <ua>` | `User-Agent` header value |
-| `--max-retries <n>` | Retries for transient `429`/`503` responses (default `2`) |
+| `--user-agent <ua>` | `User-Agent` header value (not blank; Latin-1, no control characters) |
+| `--max-retries <n>` | Retries for transient `429`/`503` responses, `0`–`10` (default `2`); each waits the server's `Retry-After` (up to 30 s; a longer one is not retried), else 200 ms × attempt |
 | `--max-response-bytes <n>` | Cap response body size in bytes (`0` = unlimited; default 100 MiB) |
 
 ## Learn more

package/dist/src/cli/commands/stations.d.ts

@@ -1,4 +1,3 @@
 import type { Command } from "commander";
 import type { CliDeps } from "../io.js";
 export declare function registerStationCommands(program: Command, deps: CliDeps): void;
-//# sourceMappingURL=stations.d.ts.map

package/dist/src/cli/commands/stations.js

@@ -1,5 +1,5 @@
 import { Option } from "commander";
-import { action, parseNonEmpty, renderJson, requireArg } from "../shared.js";
+import { STATION_HELP, action, parseNonEmpty, parsePathArg, renderJson } from "../shared.js";
 /** commander accumulator for a repeatable string option. */
 function collect(value, previous = []) {
     return previous.concat([parseNonEmpty(value)]);
@@ -15,8 +15,8 @@ function includesFrom(opts) {
 function addIncludeOptions(cmd) {
     return cmd
         .addOption(new Option("--include-timeseries", "embed each station's timeseries list"))
-        .addOption(new Option("--include-current", "embed the current measurement"))
-        .addOption(new Option("--include-characteristic", "embed characteristic (gauge-mark) values"));
+        .addOption(new Option("--include-current", "embed the current measurement in each timeseries (implies --include-timeseries)"))
+        .addOption(new Option("--include-characteristic", "embed characteristic (gauge-mark) values in each timeseries (implies --include-timeseries)"));
 }
 export function registerStationCommands(program, deps) {
     const stations = program.command("stations").description("Measuring stations");
@@ -36,10 +36,10 @@ export function registerStationCommands(program, deps) {
         renderJson(deps, global, await client.stations.list(params));
     }));
     const get = stations
-        .command("get <station>")
+        .command("get")
+        .argument("<station>", STATION_HELP, parsePathArg)
         .description("Get one station by uuid/number/shortname/longname");
     addIncludeOptions(get).action(action(deps, async ({ client, global, opts }, [station]) => {
-        renderJson(deps, global, await client.stations.get(requireArg("station", station), includesFrom(opts)));
+        renderJson(deps, global, await client.stations.get(station, includesFrom(opts)));
     }));
 }
-//# sourceMappingURL=stations.js.map

package/dist/src/cli/commands/timeseries.d.ts

@@ -1,4 +1,3 @@
 import type { Command } from "commander";
 import type { CliDeps } from "../io.js";
 export declare function registerTimeseriesCommands(program: Command, deps: CliDeps): void;
-//# sourceMappingURL=timeseries.d.ts.map

package/dist/src/cli/commands/timeseries.js

@@ -1,32 +1,31 @@
-import { action, parseNonEmpty, renderJson, requireArg, timeseriesOr } from "../shared.js";
-const STATION_HELP = "station uuid, number, shortname or longname";
+import { STATION_HELP, action, parseNonEmpty, parsePathArg, renderJson, timeseriesOr } from "../shared.js";
 const TIMESERIES_HELP = "timeseries shortname, e.g. W (water level) or Q (flow)";
 export function registerTimeseriesCommands(program, deps) {
     program
         .command("timeseries")
-        .argument("<station>", STATION_HELP)
-        .argument("[timeseries]", TIMESERIES_HELP, parseNonEmpty)
+        .argument("<station>", STATION_HELP, parsePathArg)
+        .argument("[timeseries]", TIMESERIES_HELP, parsePathArg)
         .description("Timeseries metadata (timeseries defaults to 'W' = water level)")
         .action(action(deps, async ({ client, global }, [station, ts]) => {
-        renderJson(deps, global, await client.timeseries.get(requireArg("station", station), timeseriesOr(ts)));
+        renderJson(deps, global, await client.timeseries.get(station, timeseriesOr(ts)));
     }));
     program
         .command("current")
-        .argument("<station>", STATION_HELP)
-        .argument("[timeseries]", TIMESERIES_HELP, parseNonEmpty)
+        .argument("<station>", STATION_HELP, parsePathArg)
+        .argument("[timeseries]", TIMESERIES_HELP, parsePathArg)
         .description("The current measurement (timeseries defaults to 'W')")
         .action(action(deps, async ({ client, global }, [station, ts]) => {
-        renderJson(deps, global, await client.timeseries.currentMeasurement(requireArg("station", station), timeseriesOr(ts)));
+        renderJson(deps, global, await client.timeseries.currentMeasurement(station, timeseriesOr(ts)));
     }));
     program
         .command("measurements")
-        .argument("<station>", STATION_HELP)
-        .argument("[timeseries]", TIMESERIES_HELP, parseNonEmpty)
+        .argument("<station>", STATION_HELP, parsePathArg)
+        .argument("[timeseries]", TIMESERIES_HELP, parsePathArg)
         .description("A window of measurements (timeseries defaults to 'W')")
         .option("--start <iso>", "window start: ISO-8601 instant, or a period like P7D", parseNonEmpty)
         .option("--end <iso>", "window end: ISO-8601 instant", parseNonEmpty)
         .action(action(deps, async ({ client, global, opts }, [station, ts]) => {
-        renderJson(deps, global, await client.timeseries.measurements(requireArg("station", station), timeseriesOr(ts), {
+        renderJson(deps, global, await client.timeseries.measurements(station, timeseriesOr(ts), {
             start: opts["start"],
             end: opts["end"],
         }));
@@ -38,4 +37,3 @@ export function registerTimeseriesCommands(program, deps) {
         renderJson(deps, global, await client.waters());
     }));
 }
-//# sourceMappingURL=timeseries.js.map

package/dist/src/cli/index.d.ts

@@ -1,3 +1,2 @@
 #!/usr/bin/env node
 export {};
-//# sourceMappingURL=index.d.ts.map

package/dist/src/cli/index.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 // Binary entry point. Thin shim around run(); all logic lives in run.ts/program.ts.
+import { handleOutputErrors } from "./io.js";
 import { run } from "./run.js";
+handleOutputErrors();
 const exitCode = await run(process.argv.slice(2));
 process.exitCode = exitCode;
-//# sourceMappingURL=index.js.map

package/dist/src/cli/io.d.ts

@@ -9,5 +9,21 @@ export interface CliDeps {
     /** Build a client from the resolved global options (injectable for tests). */
     createClient(options: EngineOptions): PegelOnlineClient;
 }
+/** The two process streams, as far as `handleOutputErrors` needs them. */
+export interface OutputStreams {
+    stdout: Pick<NodeJS.WriteStream, "on">;
+    stderr: Pick<NodeJS.WriteStream, "on">;
+}
+/**
+ * Handle write errors on stdout/stderr, which Node otherwise reports as an
+ * unhandled 'error' event: a raw stack trace and exit 1.
+ *
+ * A reader that stops early — `| head`, `| jq` exiting on the first match, a closed
+ * pager — closes the pipe while the CLI is still writing, and the next write fails
+ * with EPIPE. That is ordinary use, so the process exits 0 at once, quietly. Any
+ * other stdout error prints one `Output error: <message>` line to stderr and exits
+ * 1; any other stderr error exits 1 silently (there is nowhere left to report it).
+ * The bin shim installs this once, before `run()`.
+ */
+export declare function handleOutputErrors(streams?: OutputStreams, exit?: (code: number) => void): void;
 export declare const defaultIO: CliIO;
-//# sourceMappingURL=io.d.ts.map

package/dist/src/cli/io.js

@@ -1,7 +1,28 @@
 // I/O seam for the CLI. Everything the CLI writes goes through a CliIO object so
 // tests can capture output instead of hitting the real stdout/stderr.
+/**
+ * Handle write errors on stdout/stderr, which Node otherwise reports as an
+ * unhandled 'error' event: a raw stack trace and exit 1.
+ *
+ * A reader that stops early — `| head`, `| jq` exiting on the first match, a closed
+ * pager — closes the pipe while the CLI is still writing, and the next write fails
+ * with EPIPE. That is ordinary use, so the process exits 0 at once, quietly. Any
+ * other stdout error prints one `Output error: <message>` line to stderr and exits
+ * 1; any other stderr error exits 1 silently (there is nowhere left to report it).
+ * The bin shim installs this once, before `run()`.
+ */
+export function handleOutputErrors(streams = process, exit = (code) => process.exit(code)) {
+    streams.stdout.on("error", (err) => {
+        if (err.code === "EPIPE")
+            return exit(0);
+        process.stderr.write(`Output error: ${err.message}\n`);
+        exit(1);
+    });
+    streams.stderr.on("error", (err) => {
+        exit(err.code === "EPIPE" ? 0 : 1);
+    });
+}
 export const defaultIO = {
     out: (text) => process.stdout.write(text + "\n"),
     err: (text) => process.stderr.write(text + "\n"),
 };
-//# sourceMappingURL=io.js.map

package/dist/src/cli/program.d.ts

@@ -4,4 +4,3 @@ export declare const VERSION: string;
 /** Default dependencies: real client + real stdout/stderr/filesystem. */
 export declare const defaultDeps: CliDeps;
 export declare function buildProgram(deps?: CliDeps): Command;
-//# sourceMappingURL=program.d.ts.map

package/dist/src/cli/program.js

@@ -7,7 +7,8 @@ import { Command } from "commander";
 import { defaultIO } from "./io.js";
 import { PegelOnlineClient } from "../client/client.js";
 import { MAX_TIMEOUT_MS } from "../client/http.js";
-import { parseBoundedInt, parseIntArg, parseBaseUrl } from "./shared.js";
+import { MAX_RETRIES } from "../client/engine.js";
+import { parseBoundedInt, parseIntArg, parseBaseUrl, parseHeaderValue } from "./shared.js";
 import { registerStationCommands } from "./commands/stations.js";
 import { registerTimeseriesCommands } from "./commands/timeseries.js";
 /**
@@ -41,8 +42,8 @@ export function buildProgram(deps = defaultDeps) {
         .version(VERSION)
         .option("--base-url <url>", "API base URL", parseBaseUrl, "https://www.pegelonline.wsv.de")
         .option("--timeout <ms>", "time limit per request in milliseconds, whole response included", parseBoundedInt(0, MAX_TIMEOUT_MS))
-        .option("--user-agent <ua>", "User-Agent header value")
-        .option("--max-retries <n>", "retries for transient 429/503 responses", parseIntArg)
+        .option("--user-agent <ua>", "User-Agent header value", parseHeaderValue)
+        .option("--max-retries <n>", "retries for transient 429/503 responses (0..10; each waits the server's Retry-After, up to 30 s)", parseBoundedInt(0, MAX_RETRIES))
         .option("--max-response-bytes <n>", "cap response body size in bytes (0 = unlimited; default 100 MiB)", parseIntArg)
         .option("--compact", "print JSON on a single line instead of pretty-printed")
         .showHelpAfterError();
@@ -50,4 +51,3 @@ export function buildProgram(deps = defaultDeps) {
     registerTimeseriesCommands(program, deps);
     return program;
 }
-//# sourceMappingURL=program.js.map

package/dist/src/cli/run.d.ts

@@ -1,3 +1,2 @@
 import type { CliDeps } from "./io.js";
 export declare function run(argv: string[], deps?: CliDeps): Promise<number>;
-//# sourceMappingURL=run.d.ts.map

package/dist/src/cli/run.js

@@ -3,7 +3,7 @@
 // captured output and exit code without spawning a subprocess.
 import { CommanderError } from "commander";
 import { buildProgram, defaultDeps } from "./program.js";
-import { PegelApiError, PegelError } from "../client/errors.js";
+import { PegelApiError, PegelError, PegelValidationError } from "../client/errors.js";
 /**
  * Apply exitOverride + output redirection to every command in the tree.
  * commander does not propagate these to subcommands, so a parse error on a
@@ -51,6 +51,12 @@ export async function run(argv, deps = defaultDeps) {
                 return 4;
             return 1;
         }
+        if (err instanceof PegelValidationError) {
+            // An input the library rejected before any request: a usage error, the same
+            // exit code as commander's own parse errors.
+            deps.io.err(`Error: ${err.message}`);
+            return USAGE_EXIT;
+        }
         if (err instanceof PegelError) {
             deps.io.err(`Error: ${err.message}`);
             return 1;
@@ -59,4 +65,3 @@ export async function run(argv, deps = defaultDeps) {
         return 1;
     }
 }
-//# sourceMappingURL=run.js.map

package/dist/src/cli/shared.d.ts

@@ -1,29 +1,41 @@
 import type { CliDeps } from "./io.js";
 import type { EngineOptions } from "../client/engine.js";
+/** Help text of every `<station>` positional. */
+export declare const STATION_HELP = "station uuid, number, shortname or longname";
 /** commander value-parser: a non-negative integer. */
 export declare function parseIntArg(value: string): number;
 /** Build a commander value-parser for an integer constrained to [min, max]. */
 export declare function parseBoundedInt(min: number, max: number): (value: string) => number;
 /**
- * commander value-parser: a value that is not blank. A blank filter would
- * otherwise be dropped and the command would silently run unfiltered.
+ * commander value-parser: a value that is not blank. The rule is the library's
+ * nonEmptyProblem, which the client enforces on every filter value too (the API
+ * reads an empty parameter as no filter); here it only turns a blank value into an
+ * early usage error.
  */
 export declare function parseNonEmpty(value: string): string;
 /**
- * commander value-parser for `--base-url`: reject anything that is not a parseable
- * absolute `http:`/`https:` URL at *parse* time, so a bad scheme (`file:`, `ftp:`)
- * or malformed URL exits 2 (usage) — consistent with the blueprint — instead of
- * surfacing later as a runtime PegelNetworkError (exit 1). The transport still
- * enforces the same allowlist as the authoritative egress control; this only moves
- * the user-facing rejection earlier and to the correct exit code.
+ * commander value-parser for a value that ends up in an HTTP header (`--user-agent`):
+ * the library's headerValueProblem rule (not blank, no control character except tab,
+ * nothing above U+00FF), which the engine enforces when the client is built; here it
+ * only turns a bad value into an early usage error.
  */
-export declare function parseBaseUrl(value: string): string;
+export declare function parseHeaderValue(value: string): string;
+/**
+ * commander value-parser for an id that becomes a URL path segment (the
+ * `<station>` and `[timeseries]` positionals): not blank (which would build
+ * `/stations//W/...`), and not "." / "..", which
+ * encodeURIComponent leaves untouched and URL parsing would resolve, sending the
+ * request to a different resource. A usage error, before any request.
+ */
+export declare function parsePathArg(value: string): string;
 /**
- * Validate a required positional argument: reject an empty/blank value rather
- * than forwarding it into the URL path (which would produce a malformed request
- * like `/stations//W/...`). Returns the trimmed value.
+ * commander value-parser for `--base-url`: the library's baseUrlProblem rule (no
+ * whitespace or control characters, an absolute http(s) URL, no query or
+ * fragment), reported at *parse* time as a usage error (exit 2). The engine
+ * enforces the same rule when the client is built, and the transport still gates
+ * the scheme on every hop as the authoritative egress control.
  */
-export declare function requireArg(name: string, value: string | undefined): string;
+export declare function parseBaseUrl(value: string): string;
 /**
  * Default an omitted optional `[timeseries]` positional to "W" (water level),
  * matching the documented default. A blank value never reaches here: the
@@ -65,4 +77,3 @@ export interface ActionContext {
  * the trailing options object and command instance to recover the positionals.
  */
 export declare function action(deps: CliDeps, fn: (ctx: ActionContext, positionals: string[]) => Promise<void>): (...args: unknown[]) => Promise<void>;
-//# sourceMappingURL=shared.d.ts.map

package/dist/src/cli/shared.js

@@ -2,6 +2,9 @@
 // option resolver, and the JSON result renderer.
 import { InvalidArgumentError } from "commander";
 import { PegelError } from "../client/errors.js";
+import { baseUrlProblem, headerValueProblem, nonEmptyProblem } from "../client/validate.js";
+/** Help text of every `<station>` positional. */
+export const STATION_HELP = "station uuid, number, shortname or longname";
 /** commander value-parser: a non-negative integer. */
 export function parseIntArg(value) {
     // Require a plain decimal integer. Reject blank/whitespace ("" and " " coerce
@@ -28,52 +31,56 @@ export function parseBoundedInt(min, max) {
     };
 }
 /**
- * commander value-parser: a value that is not blank. A blank filter would
- * otherwise be dropped and the command would silently run unfiltered.
+ * commander value-parser: a value that is not blank. The rule is the library's
+ * nonEmptyProblem, which the client enforces on every filter value too (the API
+ * reads an empty parameter as no filter); here it only turns a blank value into an
+ * early usage error.
  */
 export function parseNonEmpty(value) {
-    if (value.trim() === "") {
-        throw new InvalidArgumentError("Expected a non-empty value.");
-    }
+    const reason = nonEmptyProblem(value);
+    if (reason !== undefined)
+        throw new InvalidArgumentError(reason);
     return value;
 }
 /**
- * commander value-parser for `--base-url`: reject anything that is not a parseable
- * absolute `http:`/`https:` URL at *parse* time, so a bad scheme (`file:`, `ftp:`)
- * or malformed URL exits 2 (usage) — consistent with the blueprint — instead of
- * surfacing later as a runtime PegelNetworkError (exit 1). The transport still
- * enforces the same allowlist as the authoritative egress control; this only moves
- * the user-facing rejection earlier and to the correct exit code.
+ * commander value-parser for a value that ends up in an HTTP header (`--user-agent`):
+ * the library's headerValueProblem rule (not blank, no control character except tab,
+ * nothing above U+00FF), which the engine enforces when the client is built; here it
+ * only turns a bad value into an early usage error.
  */
-export function parseBaseUrl(value) {
-    let url;
-    try {
-        url = new URL(value);
-    }
-    catch {
-        throw new InvalidArgumentError("Expected an absolute http(s) URL.");
-    }
-    if (url.protocol !== "http:" && url.protocol !== "https:") {
-        throw new InvalidArgumentError("Only http and https URLs are supported.");
-    }
+export function parseHeaderValue(value) {
+    const reason = headerValueProblem(value);
+    if (reason !== undefined)
+        throw new InvalidArgumentError(reason);
     return value;
 }
 /**
- * Validate a required positional argument: reject an empty/blank value rather
- * than forwarding it into the URL path (which would produce a malformed request
- * like `/stations//W/...`). Returns the trimmed value.
+ * commander value-parser for an id that becomes a URL path segment (the
+ * `<station>` and `[timeseries]` positionals): not blank (which would build
+ * `/stations//W/...`), and not "." / "..", which
+ * encodeURIComponent leaves untouched and URL parsing would resolve, sending the
+ * request to a different resource. A usage error, before any request.
  */
-export function requireArg(name, value) {
-    if (value === undefined || value.trim() === "") {
-        throw new PegelError(`Missing required <${name}> argument.`);
-    }
-    // Reject "." / ".." which encodeURIComponent leaves untouched and which would
-    // otherwise inject a relative path segment into the request URL.
+export function parsePathArg(value) {
+    parseNonEmpty(value);
     if (value === "." || value === "..") {
-        throw new PegelError(`Invalid <${name}> argument: "${value}".`);
+        throw new InvalidArgumentError('"." and ".." cannot be used as an id.');
     }
     return value;
 }
+/**
+ * commander value-parser for `--base-url`: the library's baseUrlProblem rule (no
+ * whitespace or control characters, an absolute http(s) URL, no query or
+ * fragment), reported at *parse* time as a usage error (exit 2). The engine
+ * enforces the same rule when the client is built, and the transport still gates
+ * the scheme on every hop as the authoritative egress control.
+ */
+export function parseBaseUrl(value) {
+    const reason = baseUrlProblem(value);
+    if (reason !== undefined)
+        throw new InvalidArgumentError(reason);
+    return value;
+}
 /**
  * Default an omitted optional `[timeseries]` positional to "W" (water level),
  * matching the documented default. A blank value never reaches here: the
@@ -116,9 +123,29 @@ export function escapeControlChars(json) {
     }
     return from === 0 ? json : result + json.slice(from);
 }
+/**
+ * JSON.stringify, pretty or compact. A deeply nested value (a hostile or broken
+ * response) overflows the stack — the pretty form far sooner than the compact one,
+ * which is why the message suggests --compact. The RangeError becomes a PegelError so
+ * the CLI prints a clear message instead of "Unexpected error: Maximum call stack
+ * size exceeded".
+ */
+function stringifyJson(value, compact) {
+    try {
+        return compact ? JSON.stringify(value) : JSON.stringify(value, null, 2);
+    }
+    catch (err) {
+        if (err instanceof RangeError) {
+            throw new PegelError(compact
+                ? "The response is nested too deeply to print."
+                : "The response is nested too deeply to pretty-print; try --compact.", { cause: err });
+        }
+        throw err;
+    }
+}
 /** Render a JSON value to stdout, pretty by default, compact with --compact. */
 export function renderJson(deps, global, value) {
-    const text = escapeControlChars(global.compact ? JSON.stringify(value) : JSON.stringify(value, null, 2));
+    const text = escapeControlChars(stringifyJson(value, global.compact === true));
     deps.io.out(text);
 }
 /**
@@ -138,4 +165,3 @@ export function action(deps, fn) {
         await fn({ client, global, opts: command.opts() }, positionals);
     };
 }
-//# sourceMappingURL=shared.js.map

package/dist/src/client/client.d.ts

@@ -4,6 +4,11 @@ import type { Station, Water, TimeseriesInfo, CurrentMeasurement, Measurement, S
 declare class StationsResource {
     private readonly e;
     constructor(e: RequestEngine);
+    /**
+     * Rejects (PegelValidationError, no request) a blank `waters` or `fuzzyId`, a
+     * blank `ids` entry and an empty `ids` array: the API reads an empty parameter as
+     * no filter and would answer with every station.
+     */
     list(params?: StationListParams): Promise<Station[]>;
     get(station: string, params?: IncludeParams): Promise<Station>;
 }
@@ -14,6 +19,7 @@ declare class TimeseriesResource {
     /** Timeseries metadata (e.g. "W" = water level, "Q" = flow). */
     get(station: string, timeseries?: string, params?: IncludeParams): Promise<TimeseriesInfo>;
     currentMeasurement(station: string, timeseries?: string): Promise<CurrentMeasurement>;
+    /** Rejects (PegelValidationError, no request) a blank `start` or `end`. */
     measurements(station: string, timeseries?: string, params?: MeasurementsParams): Promise<Measurement[]>;
 }
 export declare class PegelOnlineClient {
@@ -25,4 +31,3 @@ export declare class PegelOnlineClient {
     waters(): Promise<Water[]>;
 }
 export {};
-//# sourceMappingURL=client.d.ts.map