ws-dottie/dist/index.d.ts

Your friendly TypeScript companion for Washington State transportation APIs - WSDOT and WSF data with smart caching and React Query integration

import { F as FetchEndpoint } from './types--a4yiYtQ.js';
import 'zod';

/**
 * Configuration manager object
 *
 * This object provides a convenient interface for accessing and
 * modifying WS-Dottie configuration settings.
 */
declare const configManager: {
    getApiKey: () => string;
    getDomain: () => string;
    setApiKey: (apiKey: string) => void;
    setBaseUrl: (domain: string) => void;
};

/**
 * Converts a JavaScript Date to ISO date stamp (YYYY-MM-DD)
 *
 * This function formats a JavaScript Date object as an ISO date string
 * in YYYY-MM-DD format, which is commonly used in API requests.
 *
 * @param date - The JavaScript Date object to convert
 * @returns ISO date string in YYYY-MM-DD format
 * @example
 * ```typescript
 * jsDateToYyyyMmDd(new Date(2024, 0, 15)) // Returns "2024-01-15"
 * ```
 */
declare const jsDateToYyyyMmDd: (date: Date) => string;
/**
 * Date helper functions for runtime evaluation
 *
 * These functions return YYYY-MM-DD date strings when called, ensuring they are
 * evaluated at runtime rather than build time. This is useful for
 * generating dynamic dates in API requests and sample data.
 */
declare const datesHelper: {
    /** Returns tomorrow's date as YYYY-MM-DD string */
    readonly tomorrow: () => string;
    /** Returns the day after tomorrow's date as YYYY-MM-DD string */
    readonly dayAfterTomorrow: () => string;
    /** Returns today's date as YYYY-MM-DD string */
    readonly today: () => string;
    /** Returns yesterday's date as YYYY-MM-DD string */
    readonly yesterday: () => string;
    /** Returns August 1, 2025 (start of month for sample data) as YYYY-MM-DD string */
    readonly startOfMonth: () => string;
    /** Returns August 31, 2025 (end of month for sample data) as YYYY-MM-DD string */
    readonly endOfMonth: () => string;
};

/**
 * @fileoverview Simplified Shared Types for WS-Dottie
 *
 * Consolidated type definitions without over-engineering.
 */
/**
 * Logging verbosity levels for WS-Dottie
 *
 * Controls the amount of logging output during API operations.
 * - none: No logging output
 * - info: Basic information about API calls and results
 * - debug: Detailed logging including performance metrics
 */
type LoggingMode = "none" | "info" | "debug";
/**
 * Fetch strategy for data fetching
 *
 * Defines the underlying transport mechanism used to fetch data.
 * - native: Uses standard fetch API (works in Node.js and modern browsers)
 * - jsonp: Uses JSONP callbacks (browser-only, bypasses CORS)
 */
type FetchStrategy = "native" | "jsonp";

/**
 * Parameters for the fetchDottie function
 *
 * @template TInput - The input parameters type
 * @template TOutput - The output response type
 */
interface FetchDottieParams<TInput = never, TOutput = unknown> {
    /** Minimal endpoint object containing only fetching-necessary fields */
    endpoint: FetchEndpoint<TInput, TOutput>;
    /** Optional input parameters */
    params?: TInput;
    /** Fetch strategy - how to fetch the data (default: "native") */
    fetchMode?: FetchStrategy;
    /** Logging verbosity level (default: "none") */
    logMode?: LoggingMode;
    /** Whether to validate input/output with Zod schemas (default: false) */
    validate?: boolean;
}

/**
 * @fileoverview Unified Fetch Tool for WS-Dottie
 *
 * This module provides a single, unified fetch function that combines
 * transport strategy (native vs JSONP) and validation strategy (with/without Zod)
 * into one easy-to-use interface.
 */

/**
 * Unified fetch function for WS-Dottie APIs
 *
 * This function provides a single entry point for all API calls with clear
 * control over fetch strategy and validation approach. It replaces the four
 * separate fetch functions with a more flexible and maintainable interface.
 *
 * @template TInput - The input parameters type
 * @template TOutput - The output response type
 * @param options - Configuration object with endpoint, params, and options
 * @returns Promise resolving to response data (validated and transformed as configured)
 *
 * @example
 * ```typescript
 * // Fetch without validation
 * const data = await fetchDottie({
 *   endpoint: myEndpoint,
 *   params: { route: "SEA-BI" },
 *   fetchMode: "native",
 *   logMode: "info"
 * });
 *
 * // Fetch with validation
 * const validatedData = await fetchDottie({
 *   endpoint: myEndpoint,
 *   params: { route: "SEA-BI" },
 *   validate: true
 * });
 * ```
 */
declare const fetchDottie: <TInput = never, TOutput = unknown>({ endpoint, params, fetchMode, logMode, validate, }: FetchDottieParams<TInput, TOutput>) => Promise<TOutput>;

/**
 * @fileoverview Simplified Error Handling for WS-Dottie
 *
 * This module provides streamlined error handling for WS-Dottie API operations,
 * focusing on preserving actual error information while providing useful context.
 * It includes a simple ApiError class that passes through real error messages
 * while adding relevant context for debugging and logging.
 */
/**
 * Context information for error reporting
 *
 * Contains additional context about errors that occurred during
 * API operations, useful for debugging and error reporting.
 */
interface ErrorContext {
    /** The URL that was being accessed when the error occurred */
    url?: string;
    /** HTTP status code if available */
    status?: number;
    /** The API endpoint that was being called */
    endpoint?: string;
    /** Timestamp when the error occurred */
    timestamp: Date;
}
/**
 * API error type for strongly-typed error handling
 *
 * A POJO (Plain Old JavaScript Object) that represents API errors with
 * context information. This approach is more functional and aligns with
 * modern TypeScript patterns while preserving the original error messages
 * for better debugging.
 */
interface ApiError {
    /** Error name for type identification */
    readonly name: "ApiError";
    /** Human-readable error message (preserves original error) */
    readonly message: string;
    /** HTTP status code if available */
    readonly status?: number;
    /** Additional context information about the error */
    readonly context: ErrorContext;
}

export { type ApiError, type ErrorContext, configManager, datesHelper, fetchDottie, jsDateToYyyyMmDd };