Add ROADMAP.md with user issues, Express.js, and detailed TypeScript sections

[Copilot]

Renames Roadmap.md → ROADMAP.md and expands it significantly to cover user-reported bugs, Express.js integration guidance, and a phased TypeScript plan with honest tradeoffs.

Changes

• Guiding principles — stability-first, callback-API compatibility, framework safety, incremental delivery

• User-reported issues (P0/P1/P2) — all referenced issues (Issue with blobs not returning, query callback is never ran #387, Problem with pool connections hanging after idle time in v1.1.9 #357, Error when getting connection from pool #343, sequentially - Reached heap limit Allocation failed #313, If <sql> RETURNING COL fails for some reason (e.g., PK, FK, DEADLOCK conflict), any other query will throw an uncaught error #341, pool may close and delete idleConnection #329, does node-firebird supports to use LIST function on sql? #353, Is protocol version hard coded? #348, BLOB data loading very slowly #335, Request: Add de option to set the default encoding from utf-8 to latin1 #336, Error when using the LIKE clause in a SELECT #332, deno #320) organized by priority with per-item goals and deliverables

• Express.js support — documents safe-by-default patterns (single pool, finally-guarded release, transaction middleware, BLOB streaming); proposes optional pool.withConnection / db.withTransaction helpers with two acceptance-criteria examples

• TypeScript roadmap (Phase A/B/C) — expands beyond benefits to include real constraints:

  • Phase A: .d.ts typings for current API; notes on dynamic result shapes, blob-as-function quirk, drift risk
  • Phase B: promise wrappers alongside callbacks; flags UnhandledPromiseRejection differences and serialization hazards
  • Phase C: ESM/generics; calls out breaking-change risk and SQL-compile-time limitation

• In-flight PRs — tracks use native BigInt instead of the big-integer library #385 (native BigInt) and Implement IEEE 754-2008 DECFLOAT support for Firebird 4.0+ Protocol 16/17 #383 (DECFLOAT)

• Release buckets table — maps all work to next patch / minor / future major

• Incomplete-list note at the top linking to GitHub Issues

Original prompt

Repository to confirm: hgourvest/node-firebird.

Please create a pull request that adds a new ROADMAP.md file to the root of the repository.

Goals for ROADMAP.md

Improve/introduce a roadmap that includes:

1. User-indicated issues: explicitly list/track user-reported open issues as roadmap items, prioritized.
2. Express.js support: add a roadmap section describing first-class Express integration support (docs + optional helper utilities), with clear deliverables and acceptance criteria.
3. Detailed TypeScript roadmap: include more detailed plans for future TypeScript support, including tradeoffs/constraints (not only benefits).

Context / current state

• ROADMAP.md does not currently exist.
• The repo has an extensive README.md describing usage and Firebird protocol support.
• There are open issues and PRs that should be referenced in the roadmap (at minimum, include these known items and links):
  • Issue Issue with blobs not returning, query callback is never ran #387 (BLOB callback never runs)
  • Issue Problem with pool connections hanging after idle time in v1.1.9 #357 (pool connections hanging after idle time)
  • Issue Error when getting connection from pool #343 (pool connection errors)
  • Issue sequentially - Reached heap limit Allocation failed #313 (sequentially heap limit)
  • Issue If <sql> RETURNING COL fails for some reason (e.g., PK, FK, DEADLOCK conflict), any other query will throw an uncaught error #341 (RETURNING failure leads to uncaught error)
  • Issue pool may close and delete idleConnection #329 (pool idle connection deletion)
  • Issue does node-firebird supports to use LIST function on sql? #353 (LIST function question)
  • Issue Is protocol version hard coded? #348 (protocol version hard coded?)
  • Issue BLOB data loading very slowly #335 (BLOB loading slowly)
  • Issue Request: Add de option to set the default encoding from utf-8 to latin1 #336 (default encoding option)
  • Issue Error when using the LIKE clause in a SELECT #332 (LIKE clause error)
  • Issue deno #320 (Deno)
  • PR use native BigInt instead of the big-integer library #385 (native BigInt)
  • PR Implement IEEE 754-2008 DECFLOAT support for Firebird 4.0+ Protocol 16/17 #383 (DECFLOAT)

Requirements

• Add ROADMAP.md with a clear structure:
  • Guiding principles
  • Sections for: User-reported issues (P0/P1/P2), Express.js support, TypeScript roadmap (Phase A/B/C), In-flight PRs
  • Include links to issues/PRs.
  • Include a brief note that lists may be incomplete and encourage readers to check GitHub issues.
• Keep wording concise and project-appropriate.
• Do not break existing docs; only add the new file.

Output

• Open a PR with the new ROADMAP.md.
• PR title suggestion: Add ROADMAP.md.

The following is the prior conversation context from the user's chat exploration (may be truncated):

User: Could you improve roadmap with these indication:

1. include issues that users are indicate
2. include a express.js support
3. some more detailed information about future typescript version (non only benefits)

Assistant: Below is an improved Roadmap draft you can paste into the repo (e.g., in README.md under a new “Roadmap” section, or as a new ROADMAP.md). It incorporates: (1) user-indicated issues, (2) Express.js support, (3) more detailed TypeScript plans.

Notes:

• I couldn’t find an existing ROADMAP.md in the repo (fetch failed), so this is structured as a new section/file.
• The issues list I could fetch from the API is limited and may be incomplete; please review all open issues in the GitHub UI and extend the “User-reported” list as needed: https://github.com/hgourvest/node-firebird/issues

---

Roadmap (Draft)

Guiding principles

• Stability first: fix hangs, leaks, and “callback never called” scenarios before adding new API surface.
• Compatibility: keep the current callback API stable while adding promise/TypeScript improvements.
• Framework-friendly: make it straightforward to use in web frameworks (Express) without connection leaks.

---

1) User-reported issues (prioritized)

These items come directly from current open issues/PRs and should be tracked as roadmap deliverables.

P0 — Correctness / “hang” / “never returns”

• Issue Issue with blobs not returning, query callback is never ran #387 — “blobs not returning, query callback never ran”
  Goal: ensure query callbacks always settle (success/error) and that BLOB streaming cannot stall silently.
  Deliverables:

  • Add internal timeouts / watchdog for pending requests (opt-in first, then default).
  • Add debug logging hooks (connection + statement lifecycle) to diagnose stalls.
  • Add regression test: BLOB read path must either resolve or error deterministically.
    Link: Issue with blobs not returning, query callback is never ran #387

• Issue Problem with pool connections hanging after idle time in v1.1.9 #357 — “pool connections hanging after idle time”
  Goal: pool should detect dead sockets and recover cleanly.
  Deliverables:

  • Health-check on checkout (ping/lightweight op).
  • Better handling of server disconnects + reconnect backoff.
  • Ensure db.detach() always returns connection to pool in all code paths.
    Link: Problem with pool connections hanging after idle time in v1.1.9 #357

• Issue Error when getting connection from pool #343 — “Error when getting connection from pool”
  Goal: pool should provide reliable acquisition and clear errors.
  Deliverables:

  • Clarify pool error semantics + add retry strategy options.
  • Add tests for pool exhaustion and stale idle connections.
    Link: Error when getting connection from pool #343

• Issue sequentially - Reached heap limit Allocation failed #313 — “sequentially heap limit / allocation failed”
  Goal: reduce memory pressure and document safe usage patterns.
  Deliverables:

  • Validate that sequentially does not reta...

This pull request was created from Copilot chat.