Add getCalendars, unfiltered getCalendarDates, getFeedInfo, getFrequencies

Closes #46. Four read-only accessors covering tables that were imported
but unreachable through the query API:

- getCalendars(filters?): bulk read of calendar (serviceId, limit)
- getCalendarDates(filters?): now optional (serviceId, date, limit);
  the legacy getCalendarDates('SERVICE_ID') string form still works
- getFeedInfo(): feed_info rows as an array (spec allows multiple rows)
- getFrequencies(filters?): frequencies (tripId, limit); exact_times: 0
  is preserved, not coerced to undefined

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MNBx9fdd9ks7ppr6Vjd4mZ

Author: chtitux

.claude/skills/gtfs-sqljs/SKILL.md

@@ -252,10 +252,22 @@ const geojson = await gtfs.getShapesToGeojson({ routeId: 'ROUTE_1' });
 
 // Calendar
 const serviceIds = await gtfs.getActiveServiceIds('20240115'); // YYYYMMDD
+const calendars = await gtfs.getCalendars();                   // whole calendar table
+const someCalendars = await gtfs.getCalendars({ serviceId: ['WEEKDAY', 'WEEKEND'] });
 const calendar = await gtfs.getCalendarByServiceId('WEEKDAY');
-const exceptions = await gtfs.getCalendarDates('WEEKDAY');
+const allExceptions = await gtfs.getCalendarDates();           // whole calendar_dates table
+const exceptions = await gtfs.getCalendarDates({ serviceId: 'WEEKDAY' });
 const exceptionsForDate = await gtfs.getCalendarDatesForDate('20240115');
 
+// Feed info (array — the spec allows multiple rows, e.g. translations)
+const [feedInfo] = await gtfs.getFeedInfo();
+feedInfo?.feed_start_date; feedInfo?.feed_end_date; feedInfo?.feed_version;
+
+// Frequencies — if a trip appears here, its stop_times are offsets from each
+// start_time, not absolute times (exact_times 0 or undefined = frequency-based)
+const frequencies = await gtfs.getFrequencies();
+const tripFrequencies = await gtfs.getFrequencies({ tripId: 'TRIP_1' });
+
 // Build ordered stop list across multiple trip variants (express/local, etc.)
 const orderedStops = await gtfs.buildOrderedStopList(['TRIP_1', 'TRIP_2', 'TRIP_3']);
 

CHANGELOG.md

@@ -3,6 +3,10 @@
 ## Upcoming release
 
 - Fix: `ProgressInfo` and `ProgressCallback` types are now exported from the package entry point, as documented in the README (`import { type ProgressInfo } from 'gtfs-sqljs'` previously failed).
+- **Add `getCalendars(filters?)`** — bulk read of the `calendar` table (filters: `serviceId` single value or array, `limit`). `getCalendarByServiceId()` remains as a convenience wrapper. ([#46](https://github.com/sysdevrun/gtfs-sqljs/issues/46))
+- **`getCalendarDates()` no longer requires a service id** — it now accepts an optional filters object (`serviceId`, `date`, `limit`) and returns the whole `calendar_dates` table when called without arguments. The legacy `getCalendarDates('SERVICE_ID')` string form is still accepted. ([#46](https://github.com/sysdevrun/gtfs-sqljs/issues/46))
+- **Add `getFeedInfo()`** — returns the `feed_info` rows (an array, since the spec allows multiple rows). Useful for `feed_start_date`/`feed_end_date` bounds and `feed_version` display/cache keys. ([#46](https://github.com/sysdevrun/gtfs-sqljs/issues/46))
+- **Add `getFrequencies(filters?)`** — read the `frequencies` table (filters: `tripId` single value or array, `limit`), e.g. to detect frequency-based trips whose `stop_times` are offsets from `start_time`. `exact_times: 0` is preserved (not coerced to `undefined`). ([#46](https://github.com/sysdevrun/gtfs-sqljs/issues/46))
 
 ## 0.8.0
 

README.md

@@ -169,9 +169,14 @@ All methods support flexible filtering with both single values and arrays:
 #### Calendar Methods
 - `getActiveServiceIds(date)` - Get active service IDs for a date (YYYYMMDD format)
 - `getCalendars(filters?)` - Get calendars (filters: serviceId, limit)
-- `getCalendarDates(serviceId)` - Get calendar date exceptions for a service
+- `getCalendarByServiceId(serviceId)` - Get a single calendar entry
+- `getCalendarDates(filters?)` - Get calendar date exceptions (filters: serviceId, date, limit; a plain serviceId string is still accepted)
 - `getCalendarDatesForDate(date)` - Get calendar exceptions for a specific date
 
+#### Feed Info and Frequency Methods
+- `getFeedInfo()` - Get feed_info rows (array — the spec allows multiple rows)
+- `getFrequencies(filters?)` - Get headway-based service patterns (filters: tripId, limit). If a trip appears here, its stop_times are offsets from each `start_time` rather than absolute times.
+
 #### GTFS Realtime Methods
 - `fetchRealtimeData(urls?)` - Fetch and load RT data from protobuf feeds
 - `clearRealtimeData()` - Clear all realtime data from database

src/gtfs-sqljs.ts

@@ -22,10 +22,15 @@ import { getStops, type StopFilters } from './queries/stops';
 import { getRoutes, type RouteFilters } from './queries/routes';
 import {
   getActiveServiceIds,
+  getCalendars,
   getCalendarByServiceId,
   getCalendarDates,
   getCalendarDatesForDate,
+  type CalendarFilters,
+  type CalendarDateFilters,
 } from './queries/calendar';
+import { getFeedInfo } from './queries/feed-info';
+import { getFrequencies, type FrequencyFilters } from './queries/frequencies';
 import { getTrips, type TripFilters, type TripWithRealtime } from './queries/trips';
 import { getStopTimes, buildOrderedStopList, type StopTimeFilters, type StopTimeWithRealtime } from './queries/stop-times';
 import { getTripSchedules, type TripScheduleFilters, type TripSchedule, type TripScheduleStop } from './queries/trip-schedules';
@@ -37,11 +42,11 @@ import { getTripUpdates, getAllTripUpdates, type TripUpdateFilters } from './que
 import { getStopTimeUpdates, getAllStopTimeUpdates, type StopTimeUpdateFilters } from './queries/rt-stop-time-updates';
 
 // Types
-import type { Agency, Stop, Route, Trip, StopTime, Calendar, CalendarDate, Shape } from './types/gtfs';
+import type { Agency, Stop, Route, Trip, StopTime, Calendar, CalendarDate, Shape, FeedInfo, Frequency } from './types/gtfs';
 import type { Alert, VehiclePosition, TripUpdate, StopTimeUpdate } from './types/gtfs-rt';
 
 // Export filter types for users
-export type { AgencyFilters, StopFilters, RouteFilters, TripFilters, StopTimeFilters, ShapeFilters, AlertFilters, VehiclePositionFilters, TripUpdateFilters, StopTimeUpdateFilters, TripScheduleFilters };
+export type { AgencyFilters, StopFilters, RouteFilters, TripFilters, StopTimeFilters, ShapeFilters, CalendarFilters, CalendarDateFilters, FrequencyFilters, AlertFilters, VehiclePositionFilters, TripUpdateFilters, StopTimeUpdateFilters, TripScheduleFilters };
 // Export RT types
 export type { Alert, VehiclePosition, TripUpdate, TripWithRealtime, StopTimeWithRealtime, TripSchedule, TripScheduleStop };
 // Export GeoJSON types
@@ -677,6 +682,15 @@ export class GtfsSqlJs {
     return getActiveServiceIds(this.db, date);
   }
 
+  /**
+   * Get calendar entries with optional filters
+   * Pass serviceId filter to get specific calendars
+   */
+  async getCalendars(filters?: CalendarFilters): Promise<Calendar[]> {
+    if (!this.db) throw new Error('Database not initialized');
+    return getCalendars(this.db, filters);
+  }
+
   /**
    * Get calendar entry by service_id
    */
@@ -686,11 +700,18 @@ export class GtfsSqlJs {
   }
 
   /**
-   * Get calendar date exceptions for a service
+   * Get calendar date exceptions with optional filters
+   * Accepts a filters object; a plain service_id string is still supported
+   * for backward compatibility.
    */
-  async getCalendarDates(serviceId: string): Promise<CalendarDate[]> {
+  async getCalendarDates(filters?: CalendarDateFilters): Promise<CalendarDate[]>;
+  async getCalendarDates(serviceId: string): Promise<CalendarDate[]>;
+  async getCalendarDates(filtersOrServiceId?: CalendarDateFilters | string): Promise<CalendarDate[]> {
     if (!this.db) throw new Error('Database not initialized');
-    return getCalendarDates(this.db, serviceId);
+    const filters = typeof filtersOrServiceId === 'string'
+      ? { serviceId: filtersOrServiceId }
+      : filtersOrServiceId;
+    return getCalendarDates(this.db, filters);
   }
 
   /**
@@ -701,6 +722,27 @@ export class GtfsSqlJs {
     return getCalendarDatesForDate(this.db, date);
   }
 
+  // ==================== Feed Info Methods ====================
+
+  /**
+   * Get feed_info rows (the GTFS spec allows multiple rows, e.g. translations)
+   */
+  async getFeedInfo(): Promise<FeedInfo[]> {
+    if (!this.db) throw new Error('Database not initialized');
+    return getFeedInfo(this.db);
+  }
+
+  // ==================== Frequency Methods ====================
+
+  /**
+   * Get frequencies with optional filters
+   * Pass tripId filter to get frequencies for specific trips
+   */
+  async getFrequencies(filters?: FrequencyFilters): Promise<Frequency[]> {
+    if (!this.db) throw new Error('Database not initialized');
+    return getFrequencies(this.db, filters);
+  }
+
   // ==================== Trip Methods ====================
 
   /**

src/index.ts

@@ -16,6 +16,9 @@ export {
   type TripFilters,
   type StopTimeFilters,
   type ShapeFilters,
+  type CalendarFilters,
+  type CalendarDateFilters,
+  type FrequencyFilters,
   type AlertFilters,
   type VehiclePositionFilters,
   type TripUpdateFilters,

src/queries/calendar.ts

@@ -5,6 +5,17 @@
 import type { GtfsDatabase, Row } from '../adapters/types';
 import type { Calendar, CalendarDate } from '../types/gtfs';
 
+export interface CalendarFilters {
+  serviceId?: string | string[];
+  limit?: number;
+}
+
+export interface CalendarDateFilters {
+  serviceId?: string | string[];
+  date?: string;
+  limit?: number;
+}
+
 /**
  * Get active service IDs for a given date
  */
@@ -56,6 +67,50 @@ export async function getActiveServiceIds(db: GtfsDatabase, date: string): Promi
   return Array.from(serviceIds);
 }
 
+/**
+ * Get calendar entries with optional filters
+ * - Filters support both single values and arrays
+ */
+export async function getCalendars(db: GtfsDatabase, filters: CalendarFilters = {}): Promise<Calendar[]> {
+  const { serviceId, limit } = filters;
+
+  const conditions: string[] = [];
+  const params: (string | number)[] = [];
+
+  if (serviceId) {
+    const serviceIds = Array.isArray(serviceId) ? serviceId : [serviceId];
+    if (serviceIds.length > 0) {
+      const placeholders = serviceIds.map(() => '?').join(', ');
+      conditions.push(`service_id IN (${placeholders})`);
+      params.push(...serviceIds);
+    }
+  }
+
+  let sql = 'SELECT * FROM calendar';
+  if (conditions.length > 0) {
+    sql += ' WHERE ' + conditions.join(' AND ');
+  }
+  sql += ' ORDER BY service_id';
+  if (limit) {
+    sql += ' LIMIT ?';
+    params.push(limit);
+  }
+
+  const stmt = await db.prepare(sql);
+  if (params.length > 0) {
+    await stmt.bind(params);
+  }
+
+  const calendars: Calendar[] = [];
+  while (await stmt.step()) {
+    const row = await stmt.getAsObject();
+    calendars.push(rowToCalendar(row));
+  }
+
+  await stmt.free();
+  return calendars;
+}
+
 /**
  * Get calendar entry by service_id
  */
@@ -74,11 +129,43 @@ export async function getCalendarByServiceId(db: GtfsDatabase, serviceId: string
 }
 
 /**
- * Get calendar date exceptions for a service
+ * Get calendar date exceptions with optional filters
+ * - Filters support both single values and arrays
  */
-export async function getCalendarDates(db: GtfsDatabase, serviceId: string): Promise<CalendarDate[]> {
-  const stmt = await db.prepare('SELECT * FROM calendar_dates WHERE service_id = ? ORDER BY date');
-  await stmt.bind([serviceId]);
+export async function getCalendarDates(db: GtfsDatabase, filters: CalendarDateFilters = {}): Promise<CalendarDate[]> {
+  const { serviceId, date, limit } = filters;
+
+  const conditions: string[] = [];
+  const params: (string | number)[] = [];
+
+  if (serviceId) {
+    const serviceIds = Array.isArray(serviceId) ? serviceId : [serviceId];
+    if (serviceIds.length > 0) {
+      const placeholders = serviceIds.map(() => '?').join(', ');
+      conditions.push(`service_id IN (${placeholders})`);
+      params.push(...serviceIds);
+    }
+  }
+
+  if (date) {
+    conditions.push('date = ?');
+    params.push(date);
+  }
+
+  let sql = 'SELECT * FROM calendar_dates';
+  if (conditions.length > 0) {
+    sql += ' WHERE ' + conditions.join(' AND ');
+  }
+  sql += ' ORDER BY service_id, date';
+  if (limit) {
+    sql += ' LIMIT ?';
+    params.push(limit);
+  }
+
+  const stmt = await db.prepare(sql);
+  if (params.length > 0) {
+    await stmt.bind(params);
+  }
 
   const dates: CalendarDate[] = [];
   while (await stmt.step()) {
@@ -94,17 +181,7 @@ export async function getCalendarDates(db: GtfsDatabase, serviceId: string): Pro
  * Get calendar date exceptions for a specific date
  */
 export async function getCalendarDatesForDate(db: GtfsDatabase, date: string): Promise<CalendarDate[]> {
-  const stmt = await db.prepare('SELECT * FROM calendar_dates WHERE date = ?');
-  await stmt.bind([date]);
-
-  const dates: CalendarDate[] = [];
-  while (await stmt.step()) {
-    const row = await stmt.getAsObject();
-    dates.push(rowToCalendarDate(row));
-  }
-
-  await stmt.free();
-  return dates;
+  return getCalendarDates(db, { date });
 }
 
 /**

src/queries/feed-info.ts

@@ -0,0 +1,40 @@
+/**
+ * Feed Info Query Methods
+ */
+
+import type { GtfsDatabase, Row } from '../adapters/types';
+import type { FeedInfo } from '../types/gtfs';
+
+/**
+ * Get feed_info rows
+ * - The GTFS spec allows multiple rows (e.g. translations), so an array is returned
+ */
+export async function getFeedInfo(db: GtfsDatabase): Promise<FeedInfo[]> {
+  const stmt = await db.prepare('SELECT * FROM feed_info');
+
+  const feedInfos: FeedInfo[] = [];
+  while (await stmt.step()) {
+    const row = await stmt.getAsObject();
+    feedInfos.push(rowToFeedInfo(row));
+  }
+
+  await stmt.free();
+  return feedInfos;
+}
+
+/**
+ * Convert database row to FeedInfo object
+ */
+function rowToFeedInfo(row: Row): FeedInfo {
+  return {
+    feed_publisher_name: String(row.feed_publisher_name),
+    feed_publisher_url: String(row.feed_publisher_url),
+    feed_lang: String(row.feed_lang),
+    default_lang: row.default_lang ? String(row.default_lang) : undefined,
+    feed_start_date: row.feed_start_date ? String(row.feed_start_date) : undefined,
+    feed_end_date: row.feed_end_date ? String(row.feed_end_date) : undefined,
+    feed_version: row.feed_version ? String(row.feed_version) : undefined,
+    feed_contact_email: row.feed_contact_email ? String(row.feed_contact_email) : undefined,
+    feed_contact_url: row.feed_contact_url ? String(row.feed_contact_url) : undefined,
+  };
+}