@nyc-transit-kit/nyc-dot 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 nyc-transit-kit contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,5 @@
+# @nyc-transit-kit/nyc-dot
+
+Part of `nyc-transit-kit`, an Effect-native Bun toolkit for official NYC and MTA transit data APIs.
+
+See the repository README and docs/api-reference.md for public import paths, CLI commands, and release notes.

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@nyc-transit-kit/nyc-dot",
+  "version": "0.1.0",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": "./src/index.ts",
+    "./bus-lanes": "./src/bus-lanes.ts",
+    "./client": "./src/client.ts",
+    "./datasets": "./src/datasets.ts",
+    "./errors": "./src/errors.ts",
+    "./traffic-speeds": "./src/traffic-speeds.ts",
+    "./traffic-volume": "./src/traffic-volume.ts"
+  },
+  "types": "./src/index.ts",
+  "files": [
+    "LICENSE",
+    "README.md",
+    "src"
+  ],
+  "scripts": {
+    "build": "tsc -b",
+    "test": "bun test ./test"
+  },
+  "dependencies": {
+    "@nyc-transit-kit/contracts": "0.1.0",
+    "@nyc-transit-kit/soda3": "0.1.0",
+    "effect": "4.0.0-beta.83"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mannyc2/nyc-transit-kit.git",
+    "directory": "packages/nyc-dot"
+  },
+  "homepage": "https://github.com/mannyc2/nyc-transit-kit#readme",
+  "bugs": {
+    "url": "https://github.com/mannyc2/nyc-transit-kit/issues"
+  },
+  "keywords": [
+    "bun",
+    "effect",
+    "mta",
+    "nyc",
+    "socrata",
+    "transit"
+  ],
+  "engines": {
+    "bun": ">=1.3.14"
+  }
+}

package/src/bus-lanes.ts

@@ -0,0 +1,16 @@
+import { NycDotBusLaneRow } from "@nyc-transit-kit/contracts/nyc-dot"
+import * as Effect from "effect/Effect"
+import * as Schema from "effect/Schema"
+import { UnsupportedDatasetError } from "./errors"
+
+export const decodeBusLaneRow = (input: unknown) =>
+  Schema.decodeUnknownEffect(NycDotBusLaneRow)(input).pipe(
+    Effect.catchTag("SchemaError", (error) =>
+      Effect.fail(
+        UnsupportedDatasetError.make({
+          dataset: "bus-lanes-local-streets",
+          message: error.message
+        })
+      )
+    )
+  )

package/src/client.ts

@@ -0,0 +1,42 @@
+import { exportResponse } from "@nyc-transit-kit/soda3/export"
+import { queryRows } from "@nyc-transit-kit/soda3/query"
+import * as Effect from "effect/Effect"
+import { nycDotOpenDataDomain, requireNycDotDataset } from "./datasets"
+
+export const queryNycDotDataset = (input: {
+  readonly name: string
+  readonly query: string
+  readonly page?: {
+    readonly pageNumber: number
+    readonly pageSize: number
+  }
+}) =>
+  Effect.gen(function* () {
+    const dataset = yield* requireNycDotDataset(input.name)
+    return yield* queryRows({
+      domain: nycDotOpenDataDomain,
+      datasetId: String(dataset.id),
+      query: input.query,
+      ...(input.page === undefined ? {} : { page: input.page })
+    })
+  })
+
+export const exportNycDotDataset = (input: {
+  readonly name: string
+  readonly format: "csv" | "json" | "geojson"
+  readonly query?: string
+  readonly range?: {
+    readonly start: number
+    readonly end: number
+  }
+}) =>
+  Effect.gen(function* () {
+    const dataset = yield* requireNycDotDataset(input.name)
+    return yield* exportResponse({
+      domain: nycDotOpenDataDomain,
+      datasetId: String(dataset.id),
+      format: input.format,
+      ...(input.query === undefined ? {} : { query: input.query }),
+      ...(input.range === undefined ? {} : { range: input.range })
+    })
+  })

package/src/datasets.ts

@@ -0,0 +1,49 @@
+import { makeDescriptorRegistry } from "@nyc-transit-kit/contracts/descriptor-registry"
+import { NycDotDatasetDescriptor } from "@nyc-transit-kit/contracts/nyc-dot"
+import * as Effect from "effect/Effect"
+import * as Schema from "effect/Schema"
+import { UnsupportedDatasetError } from "./errors"
+import { nycDotDescriptorRecords } from "./internal/descriptor-records"
+
+export const nycDotOpenDataDomain = "data.cityofnewyork.us"
+
+const decodeDescriptor = Schema.decodeUnknownSync(NycDotDatasetDescriptor)
+const descriptorRegistry = makeDescriptorRegistry({
+  descriptors: nycDotDescriptorRecords.map((record) => decodeDescriptor(record)),
+  id: (dataset) => String(dataset.id),
+  lookupKeys: (dataset) => [String(dataset.name)]
+})
+
+const requireKnownNycDotDescriptor = (name: string) => {
+  const descriptor = descriptorRegistry.find(name)
+  if (descriptor === undefined) {
+    throw new Error(`Missing NYC DOT descriptor: ${name}`)
+  }
+  return descriptor
+}
+
+export const busLanesLocalStreets = requireKnownNycDotDescriptor("bus-lanes-local-streets")
+
+export const trafficSpeeds = requireKnownNycDotDescriptor("traffic-speeds")
+
+export const trafficVolumeCounts = requireKnownNycDotDescriptor("traffic-volume-counts")
+
+export const nycDotDatasets: ReadonlyArray<NycDotDatasetDescriptor> = descriptorRegistry.all
+
+export const initialDatasetIds = descriptorRegistry.ids
+
+export const findNycDotDataset = (name: string) => descriptorRegistry.find(name)
+
+export const requireNycDotDataset = (name: string) => {
+  const dataset = findNycDotDataset(name)
+  if (dataset !== undefined) {
+    return Effect.succeed(dataset)
+  }
+
+  return Effect.fail(
+    UnsupportedDatasetError.make({
+      dataset: name,
+      message: `Unsupported NYC DOT dataset: ${name}`
+    })
+  )
+}

package/src/errors.ts

@@ -0,0 +1,9 @@
+import * as Schema from "effect/Schema"
+
+export class UnsupportedDatasetError extends Schema.TaggedErrorClass<UnsupportedDatasetError>()(
+  "UnsupportedDatasetError",
+  {
+    dataset: Schema.String,
+    message: Schema.String
+  }
+) {}

package/src/index.ts

@@ -0,0 +1,16 @@
+export const packageName = "@nyc-transit-kit/nyc-dot"
+export { decodeBusLaneRow } from "./bus-lanes"
+export { exportNycDotDataset, queryNycDotDataset } from "./client"
+export {
+  busLanesLocalStreets,
+  findNycDotDataset,
+  initialDatasetIds,
+  nycDotDatasets,
+  nycDotOpenDataDomain,
+  requireNycDotDataset,
+  trafficSpeeds,
+  trafficVolumeCounts
+} from "./datasets"
+export { UnsupportedDatasetError } from "./errors"
+export { decodeTrafficSpeedRow } from "./traffic-speeds"
+export { decodeTrafficVolumeRow } from "./traffic-volume"

package/src/internal/descriptor-records.ts

@@ -0,0 +1,42 @@
+import type { NycDotDatasetDescriptorInput } from "@nyc-transit-kit/contracts/nyc-dot"
+
+export const nycDotDescriptorRecords = [
+  {
+    name: "bus-lanes-local-streets",
+    id: "ycrg-ses3",
+    title: "Bus Lanes - Local Streets",
+    domain: "data.cityofnewyork.us",
+    backing: "socrata",
+    description: "NYC DOT bus lane centerline dataset hosted on NYC Open Data.",
+    sourceUrl: "https://data.cityofnewyork.us/d/ycrg-ses3",
+    tags: ["transportation", "transit"],
+    adapterStatus: "row-schema",
+    lastVerified: "2026-06-16"
+  },
+  {
+    name: "traffic-speeds",
+    id: "i4gi-tjb9",
+    title: "DOT Traffic Speeds",
+    domain: "data.cityofnewyork.us",
+    backing: "socrata",
+    description: "NYC DOT realtime traffic speeds dataset hosted on NYC Open Data.",
+    sourceUrl: "https://data.cityofnewyork.us/d/i4gi-tjb9",
+    tags: ["transportation", "traffic"],
+    temporalFields: ["data_as_of"],
+    adapterStatus: "row-schema",
+    lastVerified: "2026-06-16"
+  },
+  {
+    name: "traffic-volume-counts",
+    id: "btm5-ppia",
+    title: "Traffic Volume Counts Historical",
+    domain: "data.cityofnewyork.us",
+    backing: "socrata",
+    description: "NYC DOT historical traffic volume counts dataset hosted on NYC Open Data.",
+    sourceUrl: "https://data.cityofnewyork.us/d/btm5-ppia",
+    tags: ["transportation", "traffic"],
+    temporalFields: ["count_date"],
+    adapterStatus: "row-schema",
+    lastVerified: "2026-06-16"
+  }
+] satisfies ReadonlyArray<NycDotDatasetDescriptorInput>

package/src/traffic-speeds.ts

@@ -0,0 +1,16 @@
+import { NycDotTrafficSpeedRow } from "@nyc-transit-kit/contracts/nyc-dot"
+import * as Effect from "effect/Effect"
+import * as Schema from "effect/Schema"
+import { UnsupportedDatasetError } from "./errors"
+
+export const decodeTrafficSpeedRow = (input: unknown) =>
+  Schema.decodeUnknownEffect(NycDotTrafficSpeedRow)(input).pipe(
+    Effect.catchTag("SchemaError", (error) =>
+      Effect.fail(
+        UnsupportedDatasetError.make({
+          dataset: "traffic-speeds",
+          message: error.message
+        })
+      )
+    )
+  )

package/src/traffic-volume.ts

@@ -0,0 +1,16 @@
+import { NycDotTrafficVolumeRow } from "@nyc-transit-kit/contracts/nyc-dot"
+import * as Effect from "effect/Effect"
+import * as Schema from "effect/Schema"
+import { UnsupportedDatasetError } from "./errors"
+
+export const decodeTrafficVolumeRow = (input: unknown) =>
+  Schema.decodeUnknownEffect(NycDotTrafficVolumeRow)(input).pipe(
+    Effect.catchTag("SchemaError", (error) =>
+      Effect.fail(
+        UnsupportedDatasetError.make({
+          dataset: "traffic-volume-counts",
+          message: error.message
+        })
+      )
+    )
+  )