@nyc-transit-kit/soda3 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/soda3
+
+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/soda3",
+  "version": "0.1.0",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": "./src/index.ts",
+    "./catalog": "./src/catalog.ts",
+    "./client": "./src/client.ts",
+    "./endpoints": "./src/endpoints.ts",
+    "./errors": "./src/errors.ts",
+    "./export": "./src/export.ts",
+    "./query": "./src/query.ts",
+    "./soql": "./src/soql.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",
+    "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/soda3"
+  },
+  "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/catalog.ts

@@ -0,0 +1,28 @@
+import type { Soda3CatalogSearchRequestInput } from "@nyc-transit-kit/contracts/soda3"
+import * as Effect from "effect/Effect"
+import * as HttpClientRequest from "effect/unstable/http/HttpClientRequest"
+import { buildCatalogSearchUrl } from "./endpoints"
+import { decodeCatalogSearchResponse, decodeJson } from "./internal/responses"
+import { Soda3ClientConfig } from "./internal/services"
+import { addHeaders, executeRequest, requestWithPolicy } from "./internal/transport"
+
+export { buildCatalogSearchUrl } from "./endpoints"
+export type { Soda3CatalogSearchRequestInput }
+
+export const catalogSearch = Effect.fn("Soda3.catalogSearch")(function* (
+  input: Soda3CatalogSearchRequestInput
+) {
+  const config = yield* Soda3ClientConfig
+  const url = yield* buildCatalogSearchUrl(input)
+  const request = HttpClientRequest.get(url, {
+    headers: addHeaders(config)
+  })
+
+  return yield* requestWithPolicy(
+    "catalog",
+    executeRequest("catalog", request).pipe(
+      Effect.flatMap((response) => decodeJson("catalog", response)),
+      Effect.flatMap(decodeCatalogSearchResponse)
+    )
+  )
+})

package/src/client.ts

@@ -0,0 +1,6 @@
+export { catalogSearch } from "./catalog"
+export { exportResponse } from "./export"
+export { Soda3HttpLive } from "./internal/http"
+export type { Soda3ClientConfigShape } from "./internal/services"
+export { Soda3ClientConfig, Soda3Live } from "./internal/services"
+export { queryRows } from "./query"

package/src/endpoints.ts

@@ -0,0 +1,98 @@
+import {
+  Soda3CatalogSearchRequest,
+  type Soda3CatalogSearchRequestInput,
+  Soda3ExportRequest,
+  type Soda3ExportRequestInput,
+  Soda3QueryRequest,
+  type Soda3QueryRequestInput
+} from "@nyc-transit-kit/contracts/soda3"
+import * as Effect from "effect/Effect"
+import * as Schema from "effect/Schema"
+import { InvalidInputError } from "./errors"
+
+export const socrataApiVersion = "v3"
+export const defaultSocrataProtocol = "https"
+export const discoveryApiHost = "api.us.socrata.com"
+
+const decodeQueryRequest = (input: unknown) =>
+  Schema.decodeUnknownEffect(Soda3QueryRequest)(input).pipe(
+    Effect.catchTag("SchemaError", (error) =>
+      Effect.fail(
+        InvalidInputError.make({
+          operation: "query",
+          message: error.message
+        })
+      )
+    )
+  )
+
+const decodeExportRequest = (input: unknown) =>
+  Schema.decodeUnknownEffect(Soda3ExportRequest)(input).pipe(
+    Effect.catchTag("SchemaError", (error) =>
+      Effect.fail(
+        InvalidInputError.make({
+          operation: "export",
+          message: error.message
+        })
+      )
+    )
+  )
+
+const decodeCatalogSearchRequest = (input: unknown) =>
+  Schema.decodeUnknownEffect(Soda3CatalogSearchRequest)(input).pipe(
+    Effect.catchTag("SchemaError", (error) =>
+      Effect.fail(
+        InvalidInputError.make({
+          operation: "catalog",
+          message: error.message
+        })
+      )
+    )
+  )
+
+const viewUrl = (domain: string, datasetId: string, suffix: string) => {
+  const url = new URL(`${defaultSocrataProtocol}://${domain}`)
+  url.pathname = `/api/${socrataApiVersion}/views/${datasetId}/${suffix}`
+  return url
+}
+
+export const buildQueryUrl = Effect.fn("Soda3.buildQueryUrl")(function* (
+  input: Soda3QueryRequestInput
+) {
+  const request = yield* decodeQueryRequest(input)
+  return viewUrl(request.domain, request.datasetId, "query.json")
+})
+
+export const buildExportUrl = Effect.fn("Soda3.buildExportUrl")(function* (
+  input: Soda3ExportRequestInput
+) {
+  const request = yield* decodeExportRequest(input)
+  return viewUrl(request.domain, request.datasetId, `export.${request.format}`)
+})
+
+export const buildCatalogSearchUrl = Effect.fn("Soda3.buildCatalogSearchUrl")(function* (
+  input: Soda3CatalogSearchRequestInput
+) {
+  const request = yield* decodeCatalogSearchRequest(input)
+  const url = new URL(`${defaultSocrataProtocol}://${discoveryApiHost}`)
+  url.pathname = "/api/catalog/v1"
+  url.searchParams.set("domains", request.domain)
+  url.searchParams.set("search_context", request.domain)
+  url.searchParams.set("only", "dataset")
+
+  if (request.query !== undefined) {
+    url.searchParams.set("search", request.query)
+  }
+  if (request.limit !== undefined) {
+    url.searchParams.set("limit", request.limit.toString())
+  }
+  if (request.offset !== undefined) {
+    url.searchParams.set("offset", request.offset.toString())
+  }
+
+  return url
+})
+
+export const decodeSoda3QueryRequest = decodeQueryRequest
+export const decodeSoda3ExportRequest = decodeExportRequest
+export const decodeSoda3CatalogSearchRequest = decodeCatalogSearchRequest

package/src/errors.ts

@@ -0,0 +1,51 @@
+import * as Schema from "effect/Schema"
+
+export class InvalidInputError extends Schema.TaggedErrorClass<InvalidInputError>()(
+  "InvalidInputError",
+  {
+    operation: Schema.String,
+    message: Schema.String
+  }
+) {}
+
+export class ProviderHttpError extends Schema.TaggedErrorClass<ProviderHttpError>()(
+  "ProviderHttpError",
+  {
+    operation: Schema.String,
+    status: Schema.Number,
+    statusText: Schema.String,
+    retryable: Schema.Boolean
+  }
+) {}
+
+export class ProviderContractError extends Schema.TaggedErrorClass<ProviderContractError>()(
+  "ProviderContractError",
+  {
+    operation: Schema.String,
+    message: Schema.String
+  }
+) {}
+
+export class TimeoutError extends Schema.TaggedErrorClass<TimeoutError>()("TimeoutError", {
+  operation: Schema.String,
+  timeoutMs: Schema.Number
+}) {}
+
+export class RetryExhaustedError extends Schema.TaggedErrorClass<RetryExhaustedError>()(
+  "RetryExhaustedError",
+  {
+    operation: Schema.String,
+    attempts: Schema.Number,
+    message: Schema.String
+  }
+) {}
+
+export type Soda3ClientError =
+  | InvalidInputError
+  | ProviderHttpError
+  | ProviderContractError
+  | TimeoutError
+  | RetryExhaustedError
+
+export const isRetryableProviderError = (error: Soda3ClientError): error is ProviderHttpError =>
+  error._tag === "ProviderHttpError" && error.retryable

package/src/export.ts

@@ -0,0 +1,41 @@
+import type { Soda3ExportRequestInput } from "@nyc-transit-kit/contracts/soda3"
+import * as Effect from "effect/Effect"
+import * as HttpClientRequest from "effect/unstable/http/HttpClientRequest"
+import { buildExportUrl, decodeSoda3ExportRequest } from "./endpoints"
+import { InvalidInputError } from "./errors"
+import { rangeHeader, toExportBody } from "./internal/bodies"
+import { toWebResponse } from "./internal/http"
+import { Soda3ClientConfig } from "./internal/services"
+import { addHeaders, executeRequest, requestWithPolicy } from "./internal/transport"
+
+export type { Soda3ExportRequestInput }
+
+export const exportResponse = Effect.fn("Soda3.exportResponse")(function* (
+  input: Soda3ExportRequestInput
+) {
+  const config = yield* Soda3ClientConfig
+  const exportRequest = yield* decodeSoda3ExportRequest(input)
+  const url = yield* buildExportUrl(exportRequest)
+  const headers = addHeaders(config)
+  const range = rangeHeader(exportRequest)
+
+  const request = yield* HttpClientRequest.post(url, {
+    headers: {
+      ...headers,
+      range
+    }
+  }).pipe(
+    HttpClientRequest.bodyJson(toExportBody(exportRequest)),
+    Effect.mapError(() =>
+      InvalidInputError.make({
+        operation: "export",
+        message: "SODA3 export body was not JSON serializable"
+      })
+    )
+  )
+
+  return yield* requestWithPolicy(
+    "export",
+    executeRequest("export", request).pipe(Effect.flatMap(toWebResponse))
+  )
+})

package/src/index.ts

@@ -0,0 +1,50 @@
+export const packageName = "@nyc-transit-kit/soda3"
+export { buildCatalogSearchUrl, catalogSearch } from "./catalog"
+export type { Soda3ClientConfigShape } from "./client"
+export { Soda3ClientConfig, Soda3HttpLive, Soda3Live } from "./client"
+export {
+  buildExportUrl,
+  buildQueryUrl,
+  decodeSoda3CatalogSearchRequest,
+  decodeSoda3ExportRequest,
+  decodeSoda3QueryRequest,
+  defaultSocrataProtocol,
+  discoveryApiHost,
+  socrataApiVersion
+} from "./endpoints"
+export type { Soda3ClientError } from "./errors"
+export {
+  InvalidInputError,
+  isRetryableProviderError,
+  ProviderContractError,
+  ProviderHttpError,
+  RetryExhaustedError,
+  TimeoutError
+} from "./errors"
+export { exportResponse } from "./export"
+export { queryRows } from "./query"
+export type {
+  SocrataTimestampWindow,
+  SocrataYearMonth,
+  SoqlFragment,
+  SoqlParameters,
+  SoqlSortDirection
+} from "./soql"
+export {
+  socrataDateWindow,
+  socrataMonthWindow,
+  socrataTimestamp,
+  soqlAnd,
+  soqlEq,
+  soqlIdentifier,
+  soqlIn,
+  soqlIsNotNull,
+  soqlLimit,
+  soqlMonthWindow,
+  soqlOrderBy,
+  soqlParameter,
+  soqlParameterName,
+  soqlSelectAll,
+  soqlTimestampRange,
+  soqlYearMonthRange
+} from "./soql"

package/src/internal/bodies.ts

@@ -0,0 +1,21 @@
+import type { Soda3ExportRequest, Soda3QueryRequest } from "@nyc-transit-kit/contracts/soda3"
+
+export const toQueryBody = (request: Soda3QueryRequest) => ({
+  query: request.query,
+  page: request.page,
+  parameters: request.parameters,
+  timeout: request.timeout,
+  includeSystem: request.includeSystem,
+  includeSynthetic: request.includeSynthetic,
+  orderingSpecifier: request.orderingSpecifier
+})
+
+export const toExportBody = (request: Soda3ExportRequest) => ({
+  query: request.query,
+  parameters: request.parameters,
+  timeout: request.timeout,
+  serializationOptions: request.serializationOptions
+})
+
+export const rangeHeader = (request: Soda3ExportRequest) =>
+  request.range === undefined ? undefined : `bytes=${request.range.start}-${request.range.end}`

package/src/internal/http.ts

@@ -0,0 +1,42 @@
+import * as Effect from "effect/Effect"
+import * as Stream from "effect/Stream"
+import * as FetchHttpClient from "effect/unstable/http/FetchHttpClient"
+import type * as HttpClientError from "effect/unstable/http/HttpClientError"
+import type * as HttpClientResponse from "effect/unstable/http/HttpClientResponse"
+import { ProviderHttpError } from "../errors"
+
+export const Soda3HttpLive = FetchHttpClient.layer
+
+export const retryableStatus = (status: number) => status === 429 || status >= 500
+
+const httpStatusText = (status: number) => `HTTP ${status}`
+
+export const toWebResponse = (response: HttpClientResponse.HttpClientResponse) =>
+  Effect.map(
+    Stream.toReadableStreamEffect(response.stream),
+    (body) =>
+      new Response(body, {
+        status: response.status,
+        headers: response.headers
+      })
+  )
+
+export const mapHttpClientError = (operation: string, error: HttpClientError.HttpClientError) => {
+  const response = error.response
+
+  if (response !== undefined) {
+    return ProviderHttpError.make({
+      operation,
+      status: response.status,
+      statusText: httpStatusText(response.status),
+      retryable: retryableStatus(response.status)
+    })
+  }
+
+  return ProviderHttpError.make({
+    operation,
+    status: 0,
+    statusText: error.message,
+    retryable: true
+  })
+}

package/src/internal/responses.ts

@@ -0,0 +1,56 @@
+import {
+  Soda3CatalogSearchResponse,
+  Soda3QueryResponse,
+  Soda3Row
+} from "@nyc-transit-kit/contracts/soda3"
+import * as Effect from "effect/Effect"
+import * as Schema from "effect/Schema"
+import type * as HttpClientResponse from "effect/unstable/http/HttpClientResponse"
+import { ProviderContractError } from "../errors"
+
+const providerRows = Schema.Array(Soda3Row)
+
+export const decodeJson = (operation: string, response: HttpClientResponse.HttpClientResponse) =>
+  response.json.pipe(
+    Effect.catchTag("HttpClientError", () =>
+      Effect.fail(
+        ProviderContractError.make({
+          operation,
+          message: "Provider response was not valid JSON"
+        })
+      )
+    )
+  )
+
+export const decodeQueryResponse = (input: unknown) =>
+  Schema.decodeUnknownEffect(Soda3QueryResponse)(input).pipe(
+    Effect.catchTag("SchemaError", (error) =>
+      Schema.decodeUnknownEffect(providerRows)(input).pipe(
+        Effect.map((rows) =>
+          Soda3QueryResponse.make({
+            rows
+          })
+        ),
+        Effect.catchTag("SchemaError", () =>
+          Effect.fail(
+            ProviderContractError.make({
+              operation: "query",
+              message: error.message
+            })
+          )
+        )
+      )
+    )
+  )
+
+export const decodeCatalogSearchResponse = (input: unknown) =>
+  Schema.decodeUnknownEffect(Soda3CatalogSearchResponse)(input).pipe(
+    Effect.catchTag("SchemaError", (error) =>
+      Effect.fail(
+        ProviderContractError.make({
+          operation: "catalog",
+          message: error.message
+        })
+      )
+    )
+  )

package/src/internal/services.ts

@@ -0,0 +1,19 @@
+import * as Context from "effect/Context"
+import * as Layer from "effect/Layer"
+import { Soda3HttpLive } from "./http"
+
+export interface Soda3ClientConfigShape {
+  readonly appToken?: string
+  readonly retryTimes?: number
+  readonly timeoutMs?: number
+}
+
+export class Soda3ClientConfig extends Context.Service<Soda3ClientConfig, Soda3ClientConfigShape>()(
+  "@nyc-transit-kit/soda3/Soda3ClientConfig"
+) {
+  static readonly Default = Layer.succeed(Soda3ClientConfig)({
+    retryTimes: 0
+  })
+}
+
+export const Soda3Live = Layer.mergeAll(Soda3ClientConfig.Default, Soda3HttpLive)

package/src/internal/transport.ts

@@ -0,0 +1,87 @@
+import * as Effect from "effect/Effect"
+import * as HttpClient from "effect/unstable/http/HttpClient"
+import type * as HttpClientRequest from "effect/unstable/http/HttpClientRequest"
+import type { Soda3ClientError } from "../errors"
+import {
+  isRetryableProviderError,
+  ProviderHttpError,
+  RetryExhaustedError,
+  TimeoutError
+} from "../errors"
+import { mapHttpClientError, retryableStatus } from "./http"
+import { Soda3ClientConfig, type Soda3ClientConfigShape } from "./services"
+
+export const addHeaders = (config: Soda3ClientConfigShape) => ({
+  accept: "application/json",
+  ...(config.appToken !== undefined && config.appToken.length > 0
+    ? { "X-App-Token": config.appToken }
+    : {})
+})
+
+export { retryableStatus }
+
+export const requestWithPolicy = <A>(
+  operation: string,
+  effect: Effect.Effect<A, Soda3ClientError, HttpClient.HttpClient | Soda3ClientConfig>
+) =>
+  Effect.gen(function* () {
+    const config = yield* Soda3ClientConfig
+    const retryTimes = config.retryTimes ?? 0
+    const retried =
+      retryTimes > 0
+        ? effect.pipe(
+            Effect.retry({
+              times: retryTimes,
+              while: isRetryableProviderError
+            }),
+            Effect.catchIf(isRetryableProviderError, (error) =>
+              Effect.fail(
+                RetryExhaustedError.make({
+                  operation,
+                  attempts: retryTimes + 1,
+                  message: `Retry attempts exhausted after provider status ${error.status}`
+                })
+              )
+            )
+          )
+        : effect
+
+    const timeoutMs = config.timeoutMs
+    const timed =
+      timeoutMs === undefined
+        ? retried
+        : retried.pipe(
+            Effect.timeoutOrElse({
+              duration: timeoutMs,
+              orElse: () =>
+                Effect.fail(
+                  TimeoutError.make({
+                    operation,
+                    timeoutMs
+                  })
+                )
+            })
+          )
+
+    return yield* timed
+  })
+
+const httpStatusText = (status: number) => `HTTP ${status}`
+
+export const executeRequest = (operation: string, request: HttpClientRequest.HttpClientRequest) =>
+  Effect.gen(function* () {
+    const response = yield* HttpClient.execute(request).pipe(
+      Effect.mapError((error) => mapHttpClientError(operation, error))
+    )
+
+    if (response.status < 200 || response.status >= 300) {
+      return yield* ProviderHttpError.make({
+        operation,
+        status: response.status,
+        statusText: httpStatusText(response.status),
+        retryable: retryableStatus(response.status)
+      })
+    }
+
+    return response
+  })

package/src/query.ts

@@ -0,0 +1,36 @@
+import type { Soda3QueryRequestInput } from "@nyc-transit-kit/contracts/soda3"
+import * as Effect from "effect/Effect"
+import * as HttpClientRequest from "effect/unstable/http/HttpClientRequest"
+import { buildQueryUrl, decodeSoda3QueryRequest } from "./endpoints"
+import { InvalidInputError } from "./errors"
+import { toQueryBody } from "./internal/bodies"
+import { decodeJson, decodeQueryResponse } from "./internal/responses"
+import { Soda3ClientConfig } from "./internal/services"
+import { addHeaders, executeRequest, requestWithPolicy } from "./internal/transport"
+
+export type { Soda3QueryRequestInput }
+
+export const queryRows = Effect.fn("Soda3.queryRows")(function* (input: Soda3QueryRequestInput) {
+  const config = yield* Soda3ClientConfig
+  const queryRequest = yield* decodeSoda3QueryRequest(input)
+  const url = yield* buildQueryUrl(queryRequest)
+  const request = yield* HttpClientRequest.post(url, {
+    headers: addHeaders(config)
+  }).pipe(
+    HttpClientRequest.bodyJson(toQueryBody(queryRequest)),
+    Effect.mapError(() =>
+      InvalidInputError.make({
+        operation: "query",
+        message: "SODA3 query body was not JSON serializable"
+      })
+    )
+  )
+
+  return yield* requestWithPolicy(
+    "query",
+    executeRequest("query", request).pipe(
+      Effect.flatMap((response) => decodeJson("query", response)),
+      Effect.flatMap(decodeQueryResponse)
+    )
+  )
+})

package/src/soql.ts

@@ -0,0 +1,353 @@
+import { IsoDate } from "@nyc-transit-kit/contracts/ids"
+import { PositiveInteger } from "@nyc-transit-kit/contracts/soda3"
+import * as Effect from "effect/Effect"
+import * as Schema from "effect/Schema"
+import { InvalidInputError } from "./errors"
+
+export const soqlSelectAll = "SELECT *"
+
+export type SoqlParameters = Readonly<Record<string, unknown>>
+
+export type SoqlFragment = {
+  readonly text: string
+  readonly parameters?: SoqlParameters
+}
+
+export type SocrataTimestampWindow = {
+  readonly start: string
+  readonly end: string
+}
+
+export type SocrataYearMonth = {
+  readonly year: number
+  readonly month: number
+}
+
+const soqlIdentifierPattern = /^[A-Za-z_][A-Za-z0-9_]*$/
+const soqlParameterNamePattern = /^[A-Za-z_][A-Za-z0-9_]*$/
+const isoDatePartsPattern = /^(\d{4})-(\d{2})-(\d{2})$/
+
+const SoqlIdentifier = Schema.String.pipe(
+  Schema.check(
+    Schema.isPattern(soqlIdentifierPattern, {
+      message: "Expected a SoQL identifier such as route_id"
+    })
+  )
+)
+
+const SoqlParameterName = Schema.String.pipe(
+  Schema.check(
+    Schema.isPattern(soqlParameterNamePattern, {
+      message: "Expected a SoQL parameter name such as route"
+    })
+  )
+)
+
+const SoqlSortDirection = Schema.Literals(["ASC", "DESC"])
+export type SoqlSortDirection = typeof SoqlSortDirection.Type
+
+const SocrataYear = Schema.Int.pipe(
+  Schema.check(Schema.isGreaterThanOrEqualTo(1900)),
+  Schema.check(Schema.isLessThanOrEqualTo(9999))
+)
+
+const SocrataMonth = Schema.Int.pipe(
+  Schema.check(Schema.isGreaterThanOrEqualTo(1)),
+  Schema.check(Schema.isLessThanOrEqualTo(12))
+)
+
+const SocrataYearMonthSchema = Schema.Struct({
+  year: SocrataYear,
+  month: SocrataMonth
+})
+
+const invalidQueryInput = (message: string) =>
+  InvalidInputError.make({
+    operation: "query",
+    message
+  })
+
+const decodeQueryInput =
+  <S extends Schema.Top>(schema: S) =>
+  (input: unknown) =>
+    Schema.decodeUnknownEffect(schema)(input).pipe(
+      Effect.catchTag("SchemaError", (error) => Effect.fail(invalidQueryInput(error.message)))
+    )
+
+const decodeLimit = decodeQueryInput(PositiveInteger)
+const decodeIdentifier = decodeQueryInput(SoqlIdentifier)
+const decodeParameterName = decodeQueryInput(SoqlParameterName)
+const decodeSortDirection = decodeQueryInput(SoqlSortDirection)
+const decodeIsoDate = decodeQueryInput(IsoDate)
+const decodeYear = decodeQueryInput(SocrataYear)
+const decodeMonth = decodeQueryInput(SocrataMonth)
+const decodeYearMonth = decodeQueryInput(SocrataYearMonthSchema)
+
+const withParameters = (
+  text: string,
+  parameters: Readonly<Record<string, unknown>>
+): SoqlFragment => ({
+  text,
+  parameters
+})
+
+const withoutParameters = (text: string): SoqlFragment => ({
+  text
+})
+
+const mergeParameters = (fragments: ReadonlyArray<SoqlFragment>) =>
+  Effect.gen(function* () {
+    const parameters: Record<string, unknown> = {}
+
+    for (const fragment of fragments) {
+      for (const [key, value] of Object.entries(fragment.parameters ?? {})) {
+        if (Object.hasOwn(parameters, key)) {
+          return yield* invalidQueryInput(`Duplicate SoQL parameter name: ${key}`)
+        }
+        parameters[key] = value
+      }
+    }
+
+    return Object.keys(parameters).length === 0 ? undefined : parameters
+  })
+
+const pad2 = (value: number) => value.toString().padStart(2, "0")
+
+const timestampFromParts = (year: number, month: number, day: number) =>
+  `${year.toString().padStart(4, "0")}-${pad2(month)}-${pad2(day)}T00:00:00`
+
+const dateParts = (value: string) =>
+  Effect.gen(function* () {
+    const match = isoDatePartsPattern.exec(value)
+    if (match === null) {
+      return yield* invalidQueryInput("Expected an ISO calendar date in YYYY-MM-DD format")
+    }
+
+    const yearText = match[1]
+    const monthText = match[2]
+    const dayText = match[3]
+    if (yearText === undefined || monthText === undefined || dayText === undefined) {
+      return yield* invalidQueryInput("Expected an ISO calendar date in YYYY-MM-DD format")
+    }
+
+    return {
+      year: Number(yearText),
+      month: Number(monthText),
+      day: Number(dayText)
+    }
+  })
+
+const utcTimestampFromDate = (date: Date) =>
+  Effect.gen(function* () {
+    if (Number.isNaN(date.getTime())) {
+      return yield* invalidQueryInput("Expected a valid Date")
+    }
+
+    return timestampFromParts(date.getUTCFullYear(), date.getUTCMonth() + 1, date.getUTCDate())
+  })
+
+const epochDay = (value: string) =>
+  Effect.gen(function* () {
+    const parts = yield* dateParts(value)
+    return Date.UTC(parts.year, parts.month - 1, parts.day)
+  })
+
+export const soqlLimit = Effect.fn("Soda3.soqlLimit")(function* (query: string, limit: unknown) {
+  const decodedLimit = yield* decodeLimit(limit)
+  return `${query} LIMIT ${decodedLimit}`
+})
+
+export const soqlIdentifier = Effect.fn("Soda3.soqlIdentifier")(function* (input: unknown) {
+  return yield* decodeIdentifier(input)
+})
+
+export const soqlParameterName = Effect.fn("Soda3.soqlParameterName")(function* (input: unknown) {
+  return yield* decodeParameterName(input)
+})
+
+export const soqlParameter = Effect.fn("Soda3.soqlParameter")(function* (
+  name: unknown,
+  value: unknown
+) {
+  const decodedName = yield* decodeParameterName(name)
+  return withParameters(`:${decodedName}`, {
+    [decodedName]: value
+  })
+})
+
+export const soqlEq = Effect.fn("Soda3.soqlEq")(function* (
+  column: unknown,
+  parameterName: unknown,
+  value: unknown
+) {
+  const decodedColumn = yield* decodeIdentifier(column)
+  const decodedParameterName = yield* decodeParameterName(parameterName)
+
+  return withParameters(`${decodedColumn} = :${decodedParameterName}`, {
+    [decodedParameterName]: value
+  })
+})
+
+export const soqlIn = Effect.fn("Soda3.soqlIn")(function* (
+  column: unknown,
+  parameterBaseName: unknown,
+  values: ReadonlyArray<unknown>
+) {
+  const decodedColumn = yield* decodeIdentifier(column)
+  const decodedParameterBaseName = yield* decodeParameterName(parameterBaseName)
+
+  if (values.length === 0) {
+    return yield* invalidQueryInput("SoQL IN predicates require at least one value")
+  }
+
+  const parameters: Record<string, unknown> = {}
+  const placeholders: Array<string> = []
+
+  for (let index = 0; index < values.length; index += 1) {
+    const parameterName = `${decodedParameterBaseName}_${index + 1}`
+    parameters[parameterName] = values[index]
+    placeholders.push(`:${parameterName}`)
+  }
+
+  return withParameters(`${decodedColumn} IN (${placeholders.join(", ")})`, parameters)
+})
+
+export const soqlIsNotNull = Effect.fn("Soda3.soqlIsNotNull")(function* (column: unknown) {
+  const decodedColumn = yield* decodeIdentifier(column)
+  return withoutParameters(`${decodedColumn} IS NOT NULL`)
+})
+
+export const soqlAnd = Effect.fn("Soda3.soqlAnd")(function* (
+  fragments: ReadonlyArray<SoqlFragment>
+) {
+  if (fragments.length === 0) {
+    return yield* invalidQueryInput("SoQL AND composition requires at least one fragment")
+  }
+
+  const parameters = yield* mergeParameters(fragments)
+  const text = fragments.map((fragment) => `(${fragment.text})`).join(" AND ")
+
+  return parameters === undefined ? withoutParameters(text) : withParameters(text, parameters)
+})
+
+export const soqlOrderBy = Effect.fn("Soda3.soqlOrderBy")(function* (
+  column: unknown,
+  direction: unknown = "ASC"
+) {
+  const decodedColumn = yield* decodeIdentifier(column)
+  const decodedDirection = yield* decodeSortDirection(direction)
+  return withoutParameters(`ORDER BY ${decodedColumn} ${decodedDirection}`)
+})
+
+export const socrataTimestamp = Effect.fn("Soda3.socrataTimestamp")(function* (
+  date: string | Date
+) {
+  if (date instanceof Date) {
+    return yield* utcTimestampFromDate(date)
+  }
+
+  const decodedDate = yield* decodeIsoDate(date)
+  const parts = yield* dateParts(decodedDate)
+  return timestampFromParts(parts.year, parts.month, parts.day)
+})
+
+export const socrataMonthWindow = Effect.fn("Soda3.socrataMonthWindow")(function* (
+  year: unknown,
+  month: unknown
+) {
+  const decodedYear = yield* decodeYear(year)
+  const decodedMonth = yield* decodeMonth(month)
+  const endYear = decodedMonth === 12 ? decodedYear + 1 : decodedYear
+  const endMonth = decodedMonth === 12 ? 1 : decodedMonth + 1
+
+  return {
+    start: timestampFromParts(decodedYear, decodedMonth, 1),
+    end: timestampFromParts(endYear, endMonth, 1)
+  }
+})
+
+export const socrataDateWindow = Effect.fn("Soda3.socrataDateWindow")(function* (
+  startDate: unknown,
+  endDate: unknown
+) {
+  const decodedStartDate = yield* decodeIsoDate(startDate)
+  const decodedEndDate = yield* decodeIsoDate(endDate)
+  const startEpochDay = yield* epochDay(decodedStartDate)
+  const endEpochDay = yield* epochDay(decodedEndDate)
+
+  if (startEpochDay >= endEpochDay) {
+    return yield* invalidQueryInput("Socrata date windows require startDate before endDate")
+  }
+
+  return {
+    start: yield* socrataTimestamp(decodedStartDate),
+    end: yield* socrataTimestamp(decodedEndDate)
+  }
+})
+
+export const soqlTimestampRange = Effect.fn("Soda3.soqlTimestampRange")(function* (
+  column: unknown,
+  startParameterName: unknown,
+  endParameterName: unknown,
+  window: SocrataTimestampWindow
+) {
+  const decodedColumn = yield* decodeIdentifier(column)
+  const decodedStartParameterName = yield* decodeParameterName(startParameterName)
+  const decodedEndParameterName = yield* decodeParameterName(endParameterName)
+
+  if (decodedStartParameterName === decodedEndParameterName) {
+    return yield* invalidQueryInput(`Duplicate SoQL parameter name: ${decodedStartParameterName}`)
+  }
+
+  return withParameters(
+    `${decodedColumn} >= :${decodedStartParameterName} AND ${decodedColumn} < :${decodedEndParameterName}`,
+    {
+      [decodedStartParameterName]: window.start,
+      [decodedEndParameterName]: window.end
+    }
+  )
+})
+
+export const soqlMonthWindow = Effect.fn("Soda3.soqlMonthWindow")(function* (
+  column: unknown,
+  year: unknown,
+  month: unknown,
+  parameterBaseName: unknown
+) {
+  const decodedParameterBaseName = yield* decodeParameterName(parameterBaseName)
+  const window = yield* socrataMonthWindow(year, month)
+  return yield* soqlTimestampRange(
+    column,
+    `${decodedParameterBaseName}_start`,
+    `${decodedParameterBaseName}_end`,
+    window
+  )
+})
+
+export const soqlYearMonthRange = Effect.fn("Soda3.soqlYearMonthRange")(function* (
+  yearColumn: unknown,
+  monthColumn: unknown,
+  start: unknown,
+  end: unknown
+) {
+  const decodedYearColumn = yield* decodeIdentifier(yearColumn)
+  const decodedMonthColumn = yield* decodeIdentifier(monthColumn)
+  const decodedStart = yield* decodeYearMonth(start)
+  const decodedEnd = yield* decodeYearMonth(end)
+  const startOrder = decodedStart.year * 12 + decodedStart.month
+  const endOrder = decodedEnd.year * 12 + decodedEnd.month
+
+  if (startOrder > endOrder) {
+    return yield* invalidQueryInput("SoQL year/month ranges require start before end")
+  }
+
+  return withParameters(
+    `(${decodedYearColumn} > :start_year OR (${decodedYearColumn} = :start_year AND ${decodedMonthColumn} >= :start_month)) AND (${decodedYearColumn} < :end_year OR (${decodedYearColumn} = :end_year AND ${decodedMonthColumn} <= :end_month))`,
+    {
+      start_year: decodedStart.year,
+      start_month: decodedStart.month,
+      end_year: decodedEnd.year,
+      end_month: decodedEnd.month
+    }
+  )
+})