ausecon 0.0.1 → 0.2.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,62 @@ 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
+```
+
+CSV has one row per observation, with the 12 `readabs` columns. JSON is a
+list of series, each with its metadata, its table, and its observations as
+`date` and `value` pairs. `--no-metadata` writes only series ID, date, and
+value as CSV, and only the series ID and observations of each series 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    | A fault to report, such as a Time Series Directory error or a 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    | The ABS gave no response, or answered with a status outside 2xx.             |
+
+## 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,293 @@
 #!/usr/bin/env node
 import { NodeRuntime, NodeServices } from "@effect/platform-node";
-import { Effect } from "effect";
-import { Command } from "effect/cli";
+import { Cause, Config, Console, Context, Effect, Exit, Layer, Match, Option, Runtime, Schema, Stdio } from "effect";
+import { FetchHttpClient } from "effect/http";
+import { AbsRequest, readAbs } from "@ausecon/core";
+import { CliError, CliOutput, Command, Flag } from "effect/cli";
 // package.json
-var version = "0.0.1";
+var version = "0.2.0";
+// src/reader.ts
+/**
+* Reads ABS time series for the tool.
+*
+* Commands read through this service, so tests can hand in Series or a chosen
+* failure without an HTTP fixture. The entry point provides `AbsReader.layer`.
+*/
+var AbsReader = class AbsReader extends Context.Service()("ausecon/AbsReader") {
+	/** The live reader: `readAbs` over the `HttpClient` in context. */
+	static layer = Layer.effect(AbsReader, Effect.map(Effect.context(), (context) => ({ read: (request) => readAbs(request).pipe(Effect.provideContext(context)) })));
+};
+// src/output.ts
+/** The output formats, in the order help lists them. */
+const OUTPUT_FORMATS = ["csv", "json"];
+/**
+* The CSV columns: the 12 `readabs` columns in camelCase, in the v0.1.0
+* order. The tool owns this list, so a change to the library cannot alter it.
+*/
+const CSV_COLUMNS = [
+	"tableId",
+	"sheet",
+	"tableTitle",
+	"date",
+	"seriesDescription",
+	"value",
+	"seriesType",
+	"dataType",
+	"collectionMonth",
+	"frequency",
+	"seriesId",
+	"unit"
+];
+/** The CSV columns with `--no-metadata`. */
+const CSV_COLUMNS_WITHOUT_METADATA = [
+	"seriesId",
+	"date",
+	"value"
+];
+/** Flatten Series into one row per observation. An absent table title is empty. */
+const csvRows = (series) => series.flatMap((one) => one.observations.map(({ date, value }) => ({
+	tableId: one.table.tableId,
+	sheet: one.sheet,
+	tableTitle: one.table.tableTitle ?? "",
+	date,
+	seriesDescription: one.seriesDescription,
+	value,
+	seriesType: one.seriesType,
+	dataType: one.dataType,
+	collectionMonth: one.collectionMonth,
+	frequency: one.frequency,
+	seriesId: one.seriesId,
+	unit: one.unit
+})));
+/** 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");
+/** A Series without its metadata, as `--no-metadata` writes it in JSON. */
+const withoutMetadata = ({ seriesId, observations }) => ({
+	seriesId,
+	observations
+});
+/**
+* Render Series for stdout.
+*
+* CSV has a header row and one line per observation, with `\n` line endings on
+* every platform. JSON is the Series list, indented only for a terminal.
+* Without metadata, CSV holds series ID, date, and value, and each JSON Series
+* holds only its series ID and observations.
+*
+* @param series - The Series to write.
+* @param options - The output format, whether to write metadata, and whether
+* stdout is a terminal.
+* @returns The text to write to stdout.
+*/
+const renderSeries = (series, options) => options.format === "csv" ? toCsv(options.hasMetadata ? CSV_COLUMNS : CSV_COLUMNS_WITHOUT_METADATA, csvRows(series)) : JSON.stringify(options.hasMetadata ? series : series.map(withoutMetadata), null, options.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")),
+	hasMetadata: Flag.Boolean("no-metadata").pipe(Flag.withDescription("Leave out the metadata: write series ID, date, and value as CSV, or series ID and observations as JSON."), Flag.withoutNegation, Flag.withDefault(false), Flag.map((hasNoMetadata) => !hasNoMetadata))
+};
+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 series = yield* (yield* AbsReader).read(request);
+	yield* Console.log(renderSeries(series, {
+		format: input.format,
+		hasMetadata: input.hasMetadata,
+		isTerminal
+	}));
+});
+/** 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 each series ID and its observations as JSON, without metadata"
+	}
+]));
+// 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,
+	unavailable: 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},`;
+const REPORT_IT = `Report this at ${ISSUES} with the command you ran.`;
+/**
+* Describe an ABS request that failed. The library words the detail, status
+* included, so the message only adds the URL. A status means the ABS
+* answered, so the next step is to wait or report moved data. No status
+* points at the network.
+*/
+const describeUnavailable = (error) => outcome(EXIT_CODE.unavailable, `Could not read ${error.url}: ${error.detail}`, error.status === void 0 ? "Check your network connection, then try again. The ABS website may be down." : `Try again later. The ABS website may be down, or the data may have moved: if the error stays, report it at ${ISSUES}.`);
+/** 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, `Found no series ID ${error.seriesIds.join(", ")} in the Time Series Directory or the table it names.`, "Check the series ID in the ABS table that holds it.")), Match.tag("AbsUnavailable", describeUnavailable), Match.tag("TimeSeriesDirectoryError", (error) => outcome(EXIT_CODE.failure, `Time Series Directory fault at ${error.url}: ${error.reason}`, REPORT_IT)), Match.tag("TableLayoutError", (error) => outcome(EXIT_CODE.failure, `${layoutSubject(error)} does not have the ABS time series layout: ${error.reason}`, REPORT_IT)), 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, an unavailable ABS 4, and any other
+* failure 1, including a Time Series Directory or table layout fault.
+*
+* @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, AbsReader.layer.pipe(Layer.provide(FetchHttpClient.layer))]), NodeRuntime.runMain({ disableErrorReporting: true }));
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ausecon",
-  "version": "0.0.1",
+  "version": "0.2.0",
   "description": "Read Australian economic data from the ABS and RBA in your terminal.",
   "license": "MIT",
   "repository": {
@@ -19,10 +19,13 @@
     "build": "vp pack"
   },
   "dependencies": {
-    "@ausecon/core": "0.0.1",
+    "@ausecon/core": "0.2.0",
     "@effect/platform-node": "4.0.6",
     "effect": "4.0.6"
   },
+  "devDependencies": {
+    "@ausecon/testkit": "0.0.0"
+  },
   "engines": {
     "node": ">=22.18.0"
   }