ausecon 0.1.0 → 0.2.0

package/README.md

@@ -41,7 +41,10 @@ Read a watch list of series IDs from any catalogue numbers:
 ausecon abs get --series A2603039T --series A2454446F
 ```
 
-Print only the series ID, date, and value as JSON:
+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
@@ -52,13 +55,13 @@ Pass exactly one of `--catalogue` or `--series`. `--table` needs
 
 ## 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.   |
+| 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
 

package/dist/main.mjs

@@ -1,43 +1,96 @@
 #!/usr/bin/env node
 import { NodeRuntime, NodeServices } from "@effect/platform-node";
-import { Cause, Config, Console, Effect, Exit, Match, Option, Runtime, Schema, Stdio, Struct } from "effect";
+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";
-import { AbsRequest, Observation, ObservationValue, readAbs } from "@ausecon/core";
 // package.json
-var version = "0.1.0";
+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 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);
+/**
+* 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
+});
 /**
-* Build a renderer of observations for stdout.
+* Render Series 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.
+* 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 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.
+* @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 renderObservations = (format, isTerminal) => (columns, rows) => format === "csv" ? toCsv(columns, rows) : JSON.stringify(rows, null, isTerminal ? 2 : void 0);
+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")),
-	shouldOmitMetadata: Flag.Boolean("no-metadata").pipe(Flag.withDescription("Write only series ID, date, and value."), Flag.withoutNegation, Flag.withDefault(false))
+	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 }));
 /**
@@ -56,9 +109,12 @@ const requestOf = (input) => Option.match(input.catalogue, {
 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);
+	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([
@@ -76,7 +132,7 @@ const absGet = Command.make("get", flags, get).pipe(Command.validate((input) =>
 	},
 	{
 		command: "ausecon abs get --catalogue 6345.0 --format json --no-metadata",
-		description: "Print only series ID, date, and value as JSON"
+		description: "Print each series ID and its observations as JSON, without metadata"
 	}
 ]));
 // src/commands/abs.ts
@@ -92,7 +148,7 @@ const EXIT_CODE = {
 	failure: 1,
 	usage: 2,
 	notFound: 3,
-	network: 4
+	unavailable: 4
 };
 const outcome = (exitCode, message, nextStep) => ({
 	exitCode,
@@ -102,12 +158,14 @@ 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.`;
 /**
-* 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.
+* 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 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);
+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,
@@ -123,14 +181,14 @@ const describeCliError = (formatter) => Match.type().pipe(Match.tag("ShowHelp",
 * 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);
+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, network and HTTP errors 4, and any
-* other failure 1.
+* 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.
@@ -231,5 +289,5 @@ 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 }));
+}).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.1.0",
+  "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.1.0",
+    "@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"
   }