Pluggable DB adapter: async API, sql.js becomes opt-in

[chtitux]

Summary

Implements documents/pluggable-db-adapter.md.

• Core library no longer imports sql.js. GtfsSqlJs talks to a narrow async GtfsDatabase interface.
• sql.js adapter ships at subpath gtfs-sqljs/adapters/sql-js (createSqlJsAdapter). Other drivers (better-sqlite3, op-sqlite, expo-sqlite) plug in via the same interface.
• Reference BetterSqlite3Adapter in examples/adapters/, exercised by a new CI end-to-end test (tests/e2e-better-sqlite3.test.ts).
• New GtfsSqlJs.attach(db, options?) entry point for caller-managed handles (file-backed drivers).
• sql.js moves from dependencies to optional peerDependency; better-sqlite3 added to devDependencies.

Breaking changes

• Every gtfs.* query method is now async / returns Promise<T> — call sites must await.

• options.adapter is required on fromZip / fromZipData / fromDatabase. The sql.js migration is:

  - const gtfs = await GtfsSqlJs.fromZip(url, { locateFile });
  - const routes = gtfs.getRoutes();
  + import { createSqlJsAdapter } from 'gtfs-sqljs/adapters/sql-js';
  + const gtfs = await GtfsSqlJs.fromZip(url, { adapter: await createSqlJsAdapter({ locateFile }) });
  + const routes = await gtfs.getRoutes();

• SQL / locateFile removed from GtfsSqlJsOptions (moved onto createSqlJsAdapter).

• sql.js type re-exports dropped from the public surface; consumers migrate to GtfsDatabase or import from sql.js directly.

• Cache layer catches ExportNotSupportedError from adapters that cannot serialize in-memory and logs a warning instead of failing — file-backed drivers persist their own DB on disk.

Test plan

• npm run lint — clean
• npm run typecheck — clean
• npm test — 143 tests passing across sql.js + better-sqlite3 adapters
• npm run build — clean (dist/index.js + dist/adapters/sql-js/index.js)
• CI green on Node 18 / 20 / 21

🤖 Generated with Claude Code