gtfs-sqljs

library0.7.0jsnpmunverified

A TypeScript library for loading GTFS (General Transit Feed Specification) data into a SQLite database, queryable in browser, Node.js, and React Native environments. v0.7.0 stable with monthly releases. Differentiates from node-gtfs by offering pluggable database adapters (sql.js, better-sqlite3, op-sqlite, expo-sqlite) and first-class browser support via WASM. Features progress tracking, GTFS-RT realtime feeds, and optional caching with platform-specific stores. Fully typed, ESM-only, Node >=18.

storage maps

npm install gtfs-sqljs

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · GTFS-SQLJS

gtfs-sqljs

storagejavascriptv0.7.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

GtfsSqlJs

✓ import { GtfsSqlJs } from 'gtfs-sqljs'

✗ const gtfsSqlJs = require('gtfs-sqljs')

ESM-only since v0.6, no CJS export.

createSqlJsAdapter

✓ import { createSqlJsAdapter } from 'gtfs-sqljs/adapters/sql-js'

✗ import { createSqlJsAdapter } from 'gtfs-sqljs'

Adapter functions are in subpath exports 'gtfs-sqljs/adapters/*'.

GtfsSqlJs (attach)

✓ import { GtfsSqlJs } from 'gtfs-sqljs'; const db = new GtfsSqlJs(); db.attach(sqliteDbHandle)

✗ GtfsSqlJs.attach(sqliteDbHandle)

attach() is an instance method, not static in v0.6+.

Demonstrates loading a GTFS ZIP file with better-sqlite3 adapter, skipping shapes, and querying bus routes.

import { GtfsSqlJs } from 'gtfs-sqljs'; import { createBetterSqlite3Adapter } from 'gtfs-sqljs/adapters/better-sqlite3'; async function main() { const gtfs = await GtfsSqlJs.fromZip('https://transit.land/example-feed.zip', { adapter: createBetterSqlite3Adapter(), skipFiles: ['shapes.txt'], onProgress: (pct: number) => console.log(`Loading: ${pct}%`), }); const routes = await gtfs.queryRoutes({ route_type: 3 }); console.log(routes); } main().catch(console.error);

Debug

Known issues

breakingv0.6 removed automatic sql.js dependency; adapter must be provided explicitly

fix

Install sql.js or better-sqlite3 as peer dep and pass adapter to fromZip/fromZipData/fromDatabase.

affects: >=0.6.0

breakingv0.6 changed all query methods to async, returning Promise<T>

fix

Add await or .then() to all query calls (e.g., await gtfs.queryRoutes()).

affects: >=0.6.0

breakingv0.6 attach() is an instance method, not static

fix

Create instance first: const gtfs = new GtfsSqlJs(); gtfs.attach(dbHandle);

affects: >=0.6.0

deprecatedImporting from 'gtfs-sqljs' without subpath may resolve entire bundle

fix

Use subpath imports: 'gtfs-sqljs/adapters/sql-js' for adapters.

affects: <0.7

gotchaFiles larger than 256 MB may cause out-of-memory in browser WASM (sql.js)

fix

Use better-sqlite3 in Node or stream data with custom adapter.

affects: *

gotchaCaching is optional and not included; must copy from examples/cache/

fix

Copy IndexedDBCacheStore or FileSystemCacheStore into your project.

affects: *

Errors

Common errors & fixes

TypeError: GtfsSqlJs.fromZip is not a function

Importing default instead of named export, or using old ESM version without destructuring.

fix

import { GtfsSqlJs } from 'gtfs-sqljs'; (named import, not default)

Error: No adapter provided. Use adapter option in fromZip or call attach()

Using fromZip without adapter in v0.6+

fix

Pass adapter option: await GtfsSqlJs.fromZip(url, { adapter: createSqlJsAdapter() })

Cannot find module 'gtfs-sqljs/adapters/better-sqlite3'

Subpath exports not supported by older bundlers or CJS resolution.

fix

Ensure bundler supports package.json exports field, or use direct path: 'gtfs-sqljs/dist/adapters/better-sqlite3/index.js'

SQLITE_ERROR: no such table: agency

Querying before data is fully loaded, or skipping required files.

fix

Ensure fromZip() completes before querying, and do not skip 'agency.txt'.

Upgrade

Version history

0.7.0latest on npm

Audit

Dependencies

better-sqlite3optionalRequired for native Node.js adapter (peer dep, >=10)

sql.jsoptionalRequired for WASM adapter (peer dep, 1.x)

Agent activity

39 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/sysdevrun/gtfs-sqljs ↗

packagegtfs-sqljs ↗

homepagehttps://github.com/sysdevrun/gtfs-sqljs#readme ↗