ausecon 0.0.0 → 0.1.0

package/README.md

@@ -7,14 +7,6 @@ It ports the `readabs` and `readrba` R packages and uses
 
 ---
 
-## Status
-
-The tool is in development. No release exists.
-
-The first release reads ABS time series by catalogue number and table number,
-or by series ID. The tool now runs `--help`, `--version`, and shell
-completions only.
-
 ## Install
 
 The tool needs Node 22.18 or later.
@@ -24,9 +16,59 @@ npm install --global ausecon
 ausecon --help
 ```
 
+## Read ABS Time Series
+
+`ausecon abs get` reads ABS time series from the latest release and writes
+the observations to stdout as CSV. Messages and errors go to stderr, so you
+can redirect the data to a file.
+
+Save every table of the Wage Price Index:
+
+```shell
+ausecon abs get --catalogue 6345.0 > wages.csv
+```
+
+Read only tables 1 and 12 of the Labour Force release. Large catalogue
+numbers such as 6202.0 have many tables, so pass table numbers:
+
+```shell
+ausecon abs get --catalogue 6202.0 --table 1 --table 12
+```
+
+Read a watch list of series IDs from any catalogue numbers:
+
+```shell
+ausecon abs get --series A2603039T --series A2454446F
+```
+
+Print only the series ID, date, and value as JSON:
+
+```shell
+ausecon abs get --catalogue 6345.0 --format json --no-metadata
+```
+
+Pass exactly one of `--catalogue` or `--series`. `--table` needs
+`--catalogue`. Run `ausecon abs get --help` for every flag.
+
+## Exit Codes
+
+| Code | Meaning                                                      |
+| ---- | ------------------------------------------------------------ |
+| 0    | The read succeeded.                                          |
+| 1    | An unexpected failure, such as a table layout change.        |
+| 2    | A usage error, such as a missing flag or an invalid value.   |
+| 3    | No such catalogue number, table number, or series ID.        |
+| 4    | A network failure, or the ABS answered with an HTTP error.   |
+
+## Shell Completions
+
+`ausecon --completions <shell>` prints a completion script for `bash`, `zsh`,
+`fish`, `sh`, `powershell`, or `pwsh`.
+
 ## Links
 
 - [Source and glossary](https://github.com/jackemcpherson/ausecon)
+- [Changelog](https://github.com/jackemcpherson/ausecon/blob/main/CHANGELOG.md)
 - [`readabs` R package](https://github.com/MattCowgill/readabs)
 - [`readrba` R package](https://github.com/MattCowgill/readrba)
 

package/dist/main.mjs

@@ -1,12 +1,235 @@
 #!/usr/bin/env node
 import { NodeRuntime, NodeServices } from "@effect/platform-node";
-import { Effect } from "effect";
-import { Command } from "effect/cli";
+import { Cause, Config, Console, Effect, Exit, Match, Option, Runtime, Schema, Stdio, Struct } from "effect";
+import { FetchHttpClient } from "effect/http";
+import { CliError, CliOutput, Command, Flag } from "effect/cli";
+import { AbsRequest, Observation, ObservationValue, readAbs } from "@ausecon/core";
 // package.json
-var version = "0.0.0";
+var version = "0.1.0";
+// src/output.ts
+/** The output formats, in the order help lists them. */
+const OUTPUT_FORMATS = ["csv", "json"];
+/** The fields of an observation with metadata, in spec table order. */
+const METADATA_COLUMNS = Struct.keys(Observation.fields);
+/** The fields of an observation without metadata. */
+const VALUE_COLUMNS = Struct.keys(ObservationValue.fields);
+/** Quote a CSV field when it holds a comma, a quote, or a line break (RFC 4180). */
+const csvField = (value) => {
+	const text = `${value}`;
+	return /[",\r\n]/u.test(text) ? `"${text.replaceAll("\"", "\"\"")}"` : text;
+};
+const toCsv = (columns, rows) => [columns.join(","), ...rows.map((row) => columns.map((column) => csvField(row[column])).join(","))].join("\n");
+/**
+* Build a renderer of observations for stdout.
+*
+* CSV has a header row and one line per observation, with `\n` line endings on
+* every platform. JSON is one array, indented only for a terminal.
+*
+* @param format - The output format.
+* @param isTerminal - Whether stdout is a terminal.
+* @returns A function of the fields to write, in order, and the observations,
+* that returns the text to write to stdout.
+*/
+const renderObservations = (format, isTerminal) => (columns, rows) => format === "csv" ? toCsv(columns, rows) : JSON.stringify(rows, null, isTerminal ? 2 : void 0);
+// src/commands/abs-get.ts
+const flags = {
+	catalogue: Flag.String("catalogue").pipe(Flag.withDescription("Catalogue number to read, such as 6345.0."), Flag.optional),
+	table: Flag.String("table").pipe(Flag.withDescription("Table number to read, such as 1 or 7a. Repeat for more tables."), Flag.atLeast(0)),
+	series: Flag.String("series").pipe(Flag.withDescription("Series ID to read, such as A2603039T. Repeat for more series."), Flag.atLeast(0)),
+	format: Flag.Literals("format", OUTPUT_FORMATS).pipe(Flag.withDescription("Output format: csv or json."), Flag.withDefault("csv")),
+	shouldOmitMetadata: Flag.Boolean("no-metadata").pipe(Flag.withDescription("Write only series ID, date, and value."), Flag.withoutNegation, Flag.withDefault(false))
+};
+const usageError = (message) => Effect.fail(new CliError.ValidationError({ message }));
+/**
+* Build the read request from the flags, or fail with a usage error.
+*
+* `--catalogue` and `--series` exclude each other, and one of them is needed.
+* `--table` needs `--catalogue`.
+*/
+const requestOf = (input) => Option.match(input.catalogue, {
+	onNone: () => input.table.length > 0 ? usageError("--table needs --catalogue <catalogue number>.") : input.series.length === 0 ? usageError("Pass --catalogue <catalogue number> or --series <series ID>.") : Effect.succeed(AbsRequest.Series({ seriesIds: input.series })),
+	onSome: (catalogueNumber) => input.series.length > 0 ? usageError("Pass --catalogue or --series, not both.") : Effect.succeed(AbsRequest.Catalogue({
+		catalogueNumber,
+		tableNumbers: input.table
+	}))
+});
+const get = Effect.fn("absGet")(function* (input) {
+	const request = yield* requestOf(input);
+	const isTerminal = yield* (yield* Stdio.Stdio).stdoutIsTerminal;
+	const render = renderObservations(input.format, isTerminal);
+	const output = input.shouldOmitMetadata ? render(VALUE_COLUMNS, yield* readAbs(request, { hasMetadata: false })) : render(METADATA_COLUMNS, yield* readAbs(request));
+	yield* Console.log(output);
+});
+/** The `ausecon abs get` command: read ABS time series to stdout. */
+const absGet = Command.make("get", flags, get).pipe(Command.validate((input) => Effect.asVoid(requestOf(input))), Command.withDescription("Read ABS time series from the latest release and write the observations to stdout. Large catalogue numbers such as 6202.0 have many pages and tables, so pass table numbers or series IDs."), Command.withExamples([
+	{
+		command: "ausecon abs get --catalogue 6345.0 > wages.csv",
+		description: "Save every table of the Wage Price Index as CSV"
+	},
+	{
+		command: "ausecon abs get --catalogue 6202.0 --table 1 --table 12",
+		description: "Read only tables 1 and 12 of the Labour Force release"
+	},
+	{
+		command: "ausecon abs get --series A2603039T --series A2454446F",
+		description: "Read a watch list of series IDs from any catalogue numbers"
+	},
+	{
+		command: "ausecon abs get --catalogue 6345.0 --format json --no-metadata",
+		description: "Print only series ID, date, and value as JSON"
+	}
+]));
+// src/commands/abs.ts
+/** The `ausecon abs` noun: Australian Bureau of Statistics data. */
+const abs = Command.make("abs").pipe(Command.withDescription("Read data from the Australian Bureau of Statistics (ABS)."), Command.withSubcommands([absGet]));
 // src/commands/ausecon.ts
 /** The root `ausecon` command. Subcommands attach here. */
-const ausecon = Command.make("ausecon").pipe(Command.withDescription("Read Australian economic data from the ABS and RBA."));
+const ausecon = Command.make("ausecon").pipe(Command.withDescription("Read Australian economic data from the ABS and RBA."), Command.withSubcommands([abs]));
+// src/failure.ts
+/** Exit codes of the tool. */
+const EXIT_CODE = {
+	success: 0,
+	failure: 1,
+	usage: 2,
+	notFound: 3,
+	network: 4
+};
+const outcome = (exitCode, message, nextStep) => ({
+	exitCode,
+	message: Option.some(`ausecon: ${message}\n${nextStep}`)
+});
+const USAGE_HINT = "Run `ausecon abs get --help` for usage and examples.";
+const ISSUES = "https://github.com/jackemcpherson/ausecon/issues";
+/** The table, and the sheet if known, that a layout error names. */
+const layoutSubject = (error) => error.sheet === void 0 ? `Table ${error.tableId}` : `Table ${error.tableId}, sheet ${error.sheet},`;
+/**
+* The next step for an HTTP failure. Only a transport error points at the
+* network. A status code means the ABS answered, and a response the tool
+* cannot read is a fault to report.
+*/
+const httpNextStep = Match.type().pipe(Match.tag("TransportError", () => "Check your network connection, then try again. The ABS website may be down."), Match.tag("StatusCodeError", () => `Try again later. The ABS website may be down, or the data may have moved: if the error stays, report it at ${ISSUES}.`), Match.tag("DecodeError", "EmptyBodyError", "EncodeError", "InvalidUrlError", () => `Report this at ${ISSUES} with the command you ran.`), Match.exhaustive);
+/** Describe a command-line usage error, or a help request, for a terminal user. */
+const describeCliError = (formatter) => Match.type().pipe(Match.tag("ShowHelp", (error) => error.errors.length === 0 ? {
+	exitCode: EXIT_CODE.success,
+	message: Option.none()
+} : {
+	exitCode: EXIT_CODE.usage,
+	message: Option.some(formatter.formatErrors(error.errors))
+}), Match.orElse((error) => ({
+	exitCode: EXIT_CODE.usage,
+	message: Option.some(formatter.formatError(error))
+})));
+/**
+* Describe a failed read for a terminal user. The match is exhaustive, so a new
+* `ReadAbsError` does not compile until it has an exit code and a next step.
+*/
+const describeReadError = Match.type().pipe(Match.tag("InvalidRequest", (error) => outcome(EXIT_CODE.usage, error.message, USAGE_HINT)), Match.tag("CatalogueNotFound", (error) => outcome(EXIT_CODE.notFound, `The Time Series Directory has no series for catalogue number ${error.catalogueNumber}.`, "Check the catalogue number on the ABS website, such as 6345.0 for the Wage Price Index.")), Match.tag("TableNotFound", (error) => outcome(EXIT_CODE.notFound, `Catalogue number ${error.catalogueNumber} has no table numbered ${error.tableNumbers.join(", ")}.`, "Leave out --table to read every table, then pick table numbers from the tableTitle column.")), Match.tag("SeriesNotFound", (error) => outcome(EXIT_CODE.notFound, `The Time Series Directory has no record of series ID ${error.seriesIds.join(", ")}.`, "Check the series ID in the ABS table that holds it.")), Match.tag("HttpClientError", (error) => outcome(EXIT_CODE.network, `Could not read from the ABS: ${error.message}`, httpNextStep(error.reason))), Match.tag("WorkbookLayoutError", (error) => outcome(EXIT_CODE.failure, `${layoutSubject(error)} does not have the ABS time series layout: ${error.reason}`, `Report this at ${ISSUES} with the command you ran.`)), Match.exhaustive);
+/** Describe a failed command for a terminal user. */
+const describeError = (formatter) => (error) => CliError.isCliError(error) ? describeCliError(formatter)(error) : describeReadError(error);
+/**
+* Decide the exit code and stderr message for a finished command.
+*
+* Usage errors exit 2, missing data 3, network and HTTP errors 4, and any
+* other failure 1.
+*
+* @param exit - The result of running the command.
+* @param formatter - The help formatter, used for `effect/cli` errors.
+* @returns The exit code and the message for stderr.
+*/
+const outcomeOf = (exit, formatter) => Exit.match(exit, {
+	onSuccess: () => ({
+		exitCode: EXIT_CODE.success,
+		message: Option.none()
+	}),
+	onFailure: (cause) => Option.match(Cause.findErrorOption(cause), {
+		onSome: describeError(formatter),
+		onNone: () => outcome(EXIT_CODE.failure, `failed unexpectedly.\n${Cause.pretty(cause)}`, `Report this at ${ISSUES}.`)
+	})
+});
+// src/help.ts
+/**
+* Build the help formatter, which puts examples before everything else.
+*
+* The default `effect/cli` formatter prints examples last. Users learn a
+* command fastest from its examples, so this formatter moves them to the top.
+*
+* @param hasColours - Whether to style the help with ANSI colours.
+* @returns The formatter.
+*/
+const helpFormatter = (hasColours) => {
+	const base = CliOutput.defaultFormatter({ colors: hasColours });
+	const bold = (text) => hasColours ? `\u001B[1m${text}\u001B[0m` : text;
+	return {
+		...base,
+		formatHelpDoc: (doc) => {
+			const examples = doc.examples ?? [];
+			const rest = base.formatHelpDoc({
+				...doc,
+				examples: []
+			});
+			return examples.length === 0 ? rest : [
+				bold("EXAMPLES"),
+				...examples.flatMap((example) => [...example.description === void 0 ? [] : [`  # ${example.description}`], `  ${example.command}`]),
+				"",
+				rest
+			].join("\n");
+		}
+	};
+};
+// src/run.ts
+/**
+* Colour is on only when stdout and stderr are terminals and `NO_COLOR` is
+* unset or empty.
+*
+* The default covers an unset `NO_COLOR`, but a config provider can still fail
+* to read its source. Colour then stays off, because help without colour
+* serves every user and the command itself does not need the variable.
+*/
+const hasColours = Effect.gen(function* () {
+	const stdio = yield* Stdio.Stdio;
+	const noColor = yield* Config.String("NO_COLOR").pipe(Config.withDefault(""));
+	return (yield* stdio.stdoutIsTerminal) && (yield* stdio.stderrIsTerminal) && noColor === "";
+}).pipe(Effect.catchTag("ConfigError", () => Effect.succeed(false)));
+/** A console that holds `log` output in `held` and passes every other call to `console`. */
+const holding = (console, held) => Object.assign(Object.create(console), { log: (...args) => {
+	held.push(args);
+} });
+/**
+* Run `ausecon` with the given arguments and return its exit code.
+*
+* Everything the command writes with `Console.log` is held back until it
+* finishes. On success it goes to stdout. On a failure it goes to stderr,
+* with the error message and a next step, so stdout never holds partial data
+* or help text.
+*
+* @param argv - The arguments after `ausecon`.
+* @param version - The version that `--version` prints.
+* @returns An Effect that yields the exit code.
+*/
+const runAusecon = Effect.fn("runAusecon")(function* (argv, version) {
+	const formatter = helpFormatter(yield* hasColours);
+	const console = yield* Console.Console;
+	const held = [];
+	const exit = yield* Command.runWith(ausecon, {
+		version,
+		renderErrors: false
+	})(argv).pipe(Effect.provideService(Console.Console, holding(console, held)), Effect.provideService(CliOutput.Formatter, formatter), Effect.exit);
+	const outcome = outcomeOf(exit, formatter);
+	const write = outcome.exitCode === EXIT_CODE.success ? Console.log : Console.error;
+	yield* Effect.forEach(held, (args) => write(...args), { discard: true });
+	if (Option.isSome(outcome.message)) yield* Console.error(outcome.message.value);
+	return outcome.exitCode;
+});
 // src/main.ts
-Command.run(ausecon, { version }).pipe(Effect.provide(NodeServices.layer), NodeRuntime.runMain);
+/** Ends the process with a non-zero exit code. `runAusecon` has already written the message. */
+var ExitCode = class extends Schema.TaggedError()("ExitCode", { code: Schema.Number }) {
+	get [Runtime.errorExitCode]() {
+		return this.code;
+	}
+};
+Effect.gen(function* () {
+	const argv = yield* (yield* Stdio.Stdio).args;
+	const code = yield* runAusecon(argv, version);
+	if (code !== 0) return yield* new ExitCode({ code });
+}).pipe(Effect.provide([NodeServices.layer, FetchHttpClient.layer]), NodeRuntime.runMain({ disableErrorReporting: true }));
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ausecon",
-  "version": "0.0.0",
+  "version": "0.1.0",
   "description": "Read Australian economic data from the ABS and RBA in your terminal.",
   "license": "MIT",
   "repository": {
@@ -19,7 +19,7 @@
     "build": "vp pack"
   },
   "dependencies": {
-    "@ausecon/core": "0.0.0",
+    "@ausecon/core": "0.1.0",
     "@effect/platform-node": "4.0.6",
     "effect": "4.0.6"
   },