@nyc-transit-kit/cli 0.1.0

package/src/commands/nyc-dot.ts

@@ -0,0 +1,212 @@
+import type { Soda3ExportFormat } from "@nyc-transit-kit/contracts/soda3"
+import { exportNycDotDataset, queryNycDotDataset } from "@nyc-transit-kit/nyc-dot/client"
+import {
+  findNycDotDataset,
+  nycDotDatasets,
+  nycDotOpenDataDomain
+} from "@nyc-transit-kit/nyc-dot/datasets"
+import * as Effect from "effect/Effect"
+import * as Command from "effect/unstable/cli/Command"
+import * as Flag from "effect/unstable/cli/Flag"
+import { failCommand, runEffect, soqlFromSelect, writeSuccess } from "./shared"
+import { writeResponseToFile, writeSoda3ExportDryRun, writeSoda3QueryDryRun } from "./soda3-shared"
+import { CliCommandContext } from "./types"
+
+export const nycDotCommandPaths: ReadonlyArray<ReadonlyArray<string>> = [
+  ["nyc-dot", "dataset", "list"],
+  ["nyc-dot", "dataset", "info"],
+  ["nyc-dot", "dataset", "query"],
+  ["nyc-dot", "dataset", "export"]
+]
+
+export const handleNycDotList = () =>
+  Effect.gen(function* () {
+    const context = yield* CliCommandContext
+    return yield* writeSuccess(context, "nyc-dot", {
+      datasets: nycDotDatasets
+    })
+  })
+
+export const handleNycDotInfo = (config: { readonly name: string }) =>
+  Effect.gen(function* () {
+    const context = yield* CliCommandContext
+    const descriptor = findNycDotDataset(config.name)
+
+    if (descriptor === undefined) {
+      return yield* failCommand(
+        context,
+        "nyc-dot",
+        "unsupported-dataset",
+        `Unsupported NYC DOT dataset: ${config.name}`,
+        ["nyc-dot", "dataset", "info"]
+      )
+    }
+
+    return yield* writeSuccess(context, "nyc-dot", descriptor)
+  })
+
+export const handleNycDotQuery = (config: {
+  readonly name: string
+  readonly select: string
+  readonly dryRun: boolean
+}) =>
+  Effect.gen(function* () {
+    const context = yield* CliCommandContext
+    const tokens = ["nyc-dot", "dataset", "query"]
+    const descriptor = findNycDotDataset(config.name)
+
+    if (descriptor === undefined) {
+      return yield* failCommand(
+        context,
+        "nyc-dot",
+        "unsupported-dataset",
+        `Unsupported NYC DOT dataset: ${config.name}`,
+        tokens
+      )
+    }
+
+    const request = {
+      name: config.name,
+      query: soqlFromSelect(config.select)
+    }
+
+    if (config.dryRun) {
+      return yield* writeSoda3QueryDryRun({
+        context,
+        apiFamily: "nyc-dot",
+        tokens,
+        domain: nycDotOpenDataDomain,
+        datasetId: String(descriptor.id),
+        query: request.query,
+        extra: {
+          dataset: descriptor
+        }
+      })
+    }
+
+    return yield* runEffect(
+      context,
+      "nyc-dot",
+      tokens,
+      queryNycDotDataset(request).pipe(Effect.provide(context.runtime.soda3Layer))
+    )
+  })
+
+export const handleNycDotExport = (config: {
+  readonly name: string
+  readonly format: Soda3ExportFormat
+  readonly output: string
+  readonly dryRun: boolean
+}) =>
+  Effect.gen(function* () {
+    const context = yield* CliCommandContext
+    const tokens = ["nyc-dot", "dataset", "export"]
+    const descriptor = findNycDotDataset(config.name)
+
+    if (descriptor === undefined) {
+      return yield* failCommand(
+        context,
+        "nyc-dot",
+        "unsupported-dataset",
+        `Unsupported NYC DOT dataset: ${config.name}`,
+        tokens
+      )
+    }
+
+    const request = {
+      name: config.name,
+      format: config.format
+    }
+
+    if (config.dryRun) {
+      return yield* writeSoda3ExportDryRun({
+        context,
+        apiFamily: "nyc-dot",
+        tokens,
+        domain: nycDotOpenDataDomain,
+        datasetId: String(descriptor.id),
+        format: request.format,
+        output: config.output,
+        extra: {
+          dataset: descriptor
+        }
+      })
+    }
+
+    return yield* runEffect(
+      context,
+      "nyc-dot",
+      tokens,
+      Effect.gen(function* () {
+        const response = yield* exportNycDotDataset(request).pipe(
+          Effect.provide(context.runtime.soda3Layer)
+        )
+        return yield* writeResponseToFile(config.output, response)
+      })
+    )
+  })
+
+const nycDotDatasetListCommand = Command.make("list", {}, handleNycDotList).pipe(
+  Command.withShortDescription("List curated NYC DOT dataset descriptors.")
+)
+
+const nycDotDatasetInfoCommand = Command.make(
+  "info",
+  {
+    name: Flag.string("name").pipe(
+      Flag.withDescription("Known NYC DOT dataset name, such as traffic-speeds.")
+    )
+  },
+  handleNycDotInfo
+).pipe(Command.withShortDescription("Show NYC DOT dataset metadata."))
+
+const nycDotDatasetQueryCommand = Command.make(
+  "query",
+  {
+    name: Flag.string("name").pipe(
+      Flag.withDescription("Known NYC DOT dataset name, such as traffic-speeds.")
+    ),
+    select: Flag.string("select").pipe(
+      Flag.withDescription("SoQL select expression or full SELECT query.")
+    ),
+    dryRun: Flag.boolean("dry-run").pipe(
+      Flag.withDescription("Print the planned request without contacting the provider.")
+    )
+  },
+  handleNycDotQuery
+).pipe(Command.withShortDescription("Run a NYC DOT SODA3 query."))
+
+const nycDotDatasetExportCommand = Command.make(
+  "export",
+  {
+    name: Flag.string("name").pipe(
+      Flag.withDescription("Known NYC DOT dataset name, such as traffic-speeds.")
+    ),
+    format: Flag.choice("format", ["csv", "json", "geojson"]).pipe(
+      Flag.withDefault("csv"),
+      Flag.withDescription("Export format. Defaults to csv.")
+    ),
+    output: Flag.string("output").pipe(
+      Flag.withDescription("Destination file path for the downloaded response body.")
+    ),
+    dryRun: Flag.boolean("dry-run").pipe(
+      Flag.withDescription("Print the planned request without contacting the provider.")
+    )
+  },
+  handleNycDotExport
+).pipe(Command.withShortDescription("Export a NYC DOT dataset."))
+
+const nycDotDatasetCommand = Command.make("dataset").pipe(
+  Command.withShortDescription("NYC DOT dataset commands."),
+  Command.withSubcommands([
+    nycDotDatasetListCommand,
+    nycDotDatasetInfoCommand,
+    nycDotDatasetQueryCommand,
+    nycDotDatasetExportCommand
+  ])
+)
+
+export const nycDotCommand = Command.make("nyc-dot").pipe(
+  Command.withShortDescription("NYC DOT commands."),
+  Command.withSubcommands([nycDotDatasetCommand])
+)

package/src/commands/nyc-open-data.ts

@@ -0,0 +1,243 @@
+import type { Soda3ExportFormat } from "@nyc-transit-kit/contracts/soda3"
+import { searchNycOpenDataCatalog } from "@nyc-transit-kit/nyc-open-data/catalog"
+import { exportNycOpenDataDataset } from "@nyc-transit-kit/nyc-open-data/client"
+import {
+  defaultDomain,
+  findNycOpenDataDataset,
+  knownNycOpenDataDatasets
+} from "@nyc-transit-kit/nyc-open-data/descriptors"
+import { queryNycOpenDataDataset } from "@nyc-transit-kit/nyc-open-data/query"
+import { buildCatalogSearchUrl } from "@nyc-transit-kit/soda3/endpoints"
+import * as Effect from "effect/Effect"
+import * as Command from "effect/unstable/cli/Command"
+import * as Flag from "effect/unstable/cli/Flag"
+import { runEffect, soqlFromSelect, writeSuccess } from "./shared"
+import { writeResponseToFile, writeSoda3ExportDryRun, writeSoda3QueryDryRun } from "./soda3-shared"
+import { CliCommandContext } from "./types"
+
+export const nycOpenDataCommandPaths: ReadonlyArray<ReadonlyArray<string>> = [
+  ["nyc-open-data", "catalog", "search"],
+  ["nyc-open-data", "dataset", "list"],
+  ["nyc-open-data", "dataset", "info"],
+  ["nyc-open-data", "dataset", "query"],
+  ["nyc-open-data", "dataset", "export"]
+]
+
+export const handleNycOpenDataCatalogSearch = (config: {
+  readonly query: string
+  readonly limit: number
+  readonly dryRun: boolean
+}) =>
+  Effect.gen(function* () {
+    const context = yield* CliCommandContext
+    const tokens = ["nyc-open-data", "catalog", "search"]
+    const request = {
+      query: config.query,
+      limit: config.limit
+    }
+
+    if (config.dryRun) {
+      return yield* runEffect(
+        context,
+        "nyc-open-data",
+        tokens,
+        buildCatalogSearchUrl({
+          domain: defaultDomain,
+          ...request
+        }).pipe(
+          Effect.map((url) => ({
+            dryRun: true,
+            method: "GET",
+            url: url.toString()
+          }))
+        )
+      )
+    }
+
+    return yield* runEffect(
+      context,
+      "nyc-open-data",
+      tokens,
+      searchNycOpenDataCatalog(request).pipe(Effect.provide(context.runtime.soda3Layer))
+    )
+  })
+
+export const handleNycOpenDataList = () =>
+  Effect.gen(function* () {
+    const context = yield* CliCommandContext
+    return yield* writeSuccess(context, "nyc-open-data", {
+      datasets: knownNycOpenDataDatasets
+    })
+  })
+
+export const handleNycOpenDataInfo = (config: { readonly datasetId: string }) =>
+  Effect.gen(function* () {
+    const context = yield* CliCommandContext
+    const descriptor = findNycOpenDataDataset(config.datasetId)
+
+    return yield* writeSuccess(context, "nyc-open-data", {
+      known: descriptor !== undefined,
+      descriptor:
+        descriptor === undefined
+          ? {
+              id: config.datasetId,
+              domain: defaultDomain,
+              backing: "socrata"
+            }
+          : descriptor
+    })
+  })
+
+export const handleNycOpenDataQuery = (config: {
+  readonly datasetId: string
+  readonly select: string
+  readonly dryRun: boolean
+}) =>
+  Effect.gen(function* () {
+    const context = yield* CliCommandContext
+    const tokens = ["nyc-open-data", "dataset", "query"]
+    const request = {
+      datasetId: config.datasetId,
+      query: soqlFromSelect(config.select)
+    }
+
+    if (config.dryRun) {
+      return yield* writeSoda3QueryDryRun({
+        context,
+        apiFamily: "nyc-open-data",
+        tokens,
+        domain: defaultDomain,
+        ...request
+      })
+    }
+
+    return yield* runEffect(
+      context,
+      "nyc-open-data",
+      tokens,
+      queryNycOpenDataDataset(request).pipe(Effect.provide(context.runtime.soda3Layer))
+    )
+  })
+
+export const handleNycOpenDataExport = (config: {
+  readonly datasetId: string
+  readonly format: Soda3ExportFormat
+  readonly output: string
+  readonly dryRun: boolean
+}) =>
+  Effect.gen(function* () {
+    const context = yield* CliCommandContext
+    const tokens = ["nyc-open-data", "dataset", "export"]
+    const request = {
+      datasetId: config.datasetId,
+      format: config.format
+    }
+
+    if (config.dryRun) {
+      return yield* writeSoda3ExportDryRun({
+        context,
+        apiFamily: "nyc-open-data",
+        tokens,
+        domain: defaultDomain,
+        output: config.output,
+        ...request
+      })
+    }
+
+    return yield* runEffect(
+      context,
+      "nyc-open-data",
+      tokens,
+      Effect.gen(function* () {
+        const response = yield* exportNycOpenDataDataset(request).pipe(
+          Effect.provide(context.runtime.soda3Layer)
+        )
+        return yield* writeResponseToFile(config.output, response)
+      })
+    )
+  })
+
+const nycOpenDataCatalogSearchCommand = Command.make(
+  "search",
+  {
+    query: Flag.string("query").pipe(Flag.withDescription("Search text for NYC Open Data.")),
+    limit: Flag.integer("limit").pipe(
+      Flag.withDefault(10),
+      Flag.withDescription("Maximum catalog results to request. Defaults to 10.")
+    ),
+    dryRun: Flag.boolean("dry-run").pipe(
+      Flag.withDescription("Print the planned request without contacting the provider.")
+    )
+  },
+  handleNycOpenDataCatalogSearch
+).pipe(Command.withShortDescription("Search the NYC Open Data catalog."))
+
+const nycOpenDataCatalogCommand = Command.make("catalog").pipe(
+  Command.withShortDescription("NYC Open Data catalog commands."),
+  Command.withSubcommands([nycOpenDataCatalogSearchCommand])
+)
+
+const nycOpenDataDatasetListCommand = Command.make("list", {}, handleNycOpenDataList).pipe(
+  Command.withShortDescription("List curated NYC Open Data descriptors.")
+)
+
+const nycOpenDataDatasetInfoCommand = Command.make(
+  "info",
+  {
+    datasetId: Flag.string("dataset").pipe(
+      Flag.withDescription("NYC Open Data Socrata dataset id.")
+    )
+  },
+  handleNycOpenDataInfo
+).pipe(Command.withShortDescription("Show NYC Open Data dataset metadata."))
+
+const nycOpenDataDatasetQueryCommand = Command.make(
+  "query",
+  {
+    datasetId: Flag.string("dataset").pipe(
+      Flag.withDescription("NYC Open Data Socrata dataset id.")
+    ),
+    select: Flag.string("select").pipe(
+      Flag.withDescription("SoQL select expression or full SELECT query.")
+    ),
+    dryRun: Flag.boolean("dry-run").pipe(
+      Flag.withDescription("Print the planned request without contacting the provider.")
+    )
+  },
+  handleNycOpenDataQuery
+).pipe(Command.withShortDescription("Run a NYC Open Data SODA3 query."))
+
+const nycOpenDataDatasetExportCommand = Command.make(
+  "export",
+  {
+    datasetId: Flag.string("dataset").pipe(
+      Flag.withDescription("NYC Open Data Socrata dataset id.")
+    ),
+    format: Flag.choice("format", ["csv", "json", "geojson"]).pipe(
+      Flag.withDefault("csv"),
+      Flag.withDescription("Export format. Defaults to csv.")
+    ),
+    output: Flag.string("output").pipe(
+      Flag.withDescription("Destination file path for the downloaded response body.")
+    ),
+    dryRun: Flag.boolean("dry-run").pipe(
+      Flag.withDescription("Print the planned request without contacting the provider.")
+    )
+  },
+  handleNycOpenDataExport
+).pipe(Command.withShortDescription("Export a NYC Open Data dataset."))
+
+const nycOpenDataDatasetCommand = Command.make("dataset").pipe(
+  Command.withShortDescription("NYC Open Data dataset commands."),
+  Command.withSubcommands([
+    nycOpenDataDatasetListCommand,
+    nycOpenDataDatasetInfoCommand,
+    nycOpenDataDatasetQueryCommand,
+    nycOpenDataDatasetExportCommand
+  ])
+)
+
+export const nycOpenDataCommand = Command.make("nyc-open-data").pipe(
+  Command.withShortDescription("NYC Open Data commands."),
+  Command.withSubcommands([nycOpenDataCatalogCommand, nycOpenDataDatasetCommand])
+)

package/src/commands/root.ts

@@ -0,0 +1,38 @@
+import * as Effect from "effect/Effect"
+import * as Command from "effect/unstable/cli/Command"
+import * as Flag from "effect/unstable/cli/Flag"
+import { localBinaryName } from "../index"
+import { catalogCommand } from "./catalog"
+import { mtaCommand } from "./mta"
+import { nycDotCommand } from "./nyc-dot"
+import { nycOpenDataCommand } from "./nyc-open-data"
+import { failCommand } from "./shared"
+import { socrataCommand } from "./socrata"
+import { CliCommandContext } from "./types"
+
+const handleMissingCommand = () =>
+  Effect.gen(function* () {
+    const context = yield* CliCommandContext
+    return yield* failCommand(
+      context,
+      "cli",
+      "missing-command",
+      `Run ${localBinaryName} --version --json for the current scaffold contract.`,
+      []
+    )
+  })
+
+export const rootCommand = Command.make("ntk", {}, handleMissingCommand).pipe(
+  Command.withSharedFlags({
+    json: Flag.boolean("json").pipe(
+      Flag.withDescription("Write the stable JSON envelope instead of human output.")
+    )
+  }),
+  Command.withSubcommands([
+    socrataCommand,
+    catalogCommand,
+    mtaCommand,
+    nycOpenDataCommand,
+    nycDotCommand
+  ])
+)

package/src/commands/shared.ts

@@ -0,0 +1,144 @@
+import * as Effect from "effect/Effect"
+import { errorEnvelope, successEnvelope } from "../output"
+import type { ApiFamily, CommandContext, CommandResult } from "./types"
+
+export const writeJson = (output: unknown) => {
+  console.log(JSON.stringify(output))
+}
+
+export const commandLabel = (tokens: ReadonlyArray<string>) =>
+  tokens.length > 0 ? tokens.join(" ") : "(missing command)"
+
+export const apiFamilyFor = (tokens: ReadonlyArray<string>): ApiFamily => {
+  switch (tokens[0]) {
+    case "socrata":
+    case "catalog":
+      return "socrata"
+    case "mta":
+      return "mta"
+    case "nyc-open-data":
+      return "nyc-open-data"
+    case "nyc-dot":
+      return "nyc-dot"
+    default:
+      return "cli"
+  }
+}
+
+export const failCommand = (
+  context: CommandContext,
+  apiFamily: ApiFamily,
+  code: string,
+  message: string,
+  tokens: ReadonlyArray<string>,
+  options?: {
+    readonly provider?: string
+    readonly retryable?: boolean
+  }
+) =>
+  Effect.sync(() => {
+    process.exitCode = 1
+    context.writeJson(
+      errorEnvelope(apiFamily, {
+        code,
+        message,
+        provider: options?.provider,
+        retryable: options?.retryable,
+        command: commandLabel(tokens)
+      })
+    )
+  })
+
+export const writeSuccess = (context: CommandContext, apiFamily: ApiFamily, data: unknown) =>
+  Effect.sync(() => {
+    context.writeJson(successEnvelope(apiFamily, data))
+  })
+
+const writeFailure = (
+  context: CommandContext,
+  apiFamily: ApiFamily,
+  code: string,
+  message: string,
+  tokens: ReadonlyArray<string>
+) =>
+  Effect.sync(() => {
+    process.exitCode = 1
+    context.writeJson(
+      errorEnvelope(apiFamily, {
+        code,
+        message,
+        command: commandLabel(tokens)
+      })
+    )
+  })
+
+export const missingOption = (
+  context: CommandContext,
+  tokens: ReadonlyArray<string>,
+  option: string
+) =>
+  failCommand(
+    context,
+    apiFamilyFor(tokens),
+    "missing-option",
+    `Missing required option --${option}.`,
+    tokens
+  )
+
+export const soqlFromSelect = (select: string) =>
+  select.trim().toUpperCase().startsWith("SELECT ") ? select : `SELECT ${select}`
+
+const taggedMessage = (error: unknown) => {
+  if (typeof error === "object" && error !== null && "message" in error) {
+    const message = error.message
+    if (typeof message === "string") {
+      return message
+    }
+  }
+
+  return "Command failed."
+}
+
+const taggedCode = (error: unknown) => {
+  if (typeof error === "object" && error !== null && "_tag" in error) {
+    const tag = error._tag
+    if (typeof tag === "string") {
+      return tag
+        .replace(/([a-z0-9])([A-Z])/g, "$1-$2")
+        .replace(/_/g, "-")
+        .toLowerCase()
+    }
+  }
+
+  return "command-failed"
+}
+
+export const runEffect = <A>(
+  context: CommandContext,
+  apiFamily: ApiFamily,
+  tokens: ReadonlyArray<string>,
+  effect: Effect.Effect<A, unknown>
+) =>
+  effect.pipe(
+    Effect.match({
+      onFailure: (error): CommandResult<A> => ({
+        _tag: "Failure",
+        error
+      }),
+      onSuccess: (data): CommandResult<A> => ({
+        _tag: "Success",
+        data
+      })
+    }),
+    Effect.flatMap((result) =>
+      result._tag === "Success"
+        ? writeSuccess(context, apiFamily, result.data)
+        : writeFailure(
+            context,
+            apiFamily,
+            taggedCode(result.error),
+            taggedMessage(result.error),
+            tokens
+          )
+    )
+  )