firebird-wasm 0.7.0 → 0.9.0

package/CHANGELOG.md

@@ -4,6 +4,272 @@ All notable changes to `firebird-wasm`. This project follows
 [semantic versioning](https://semver.org/); while the major version is 0 the
 API may still move between minor releases.
 
+## 0.9.0 — 2026-10-19
+
+### Changed
+
+- **Closing the last database frees the engine.** A module used to stay for
+  the life of the page or process; now the transports count the databases
+  that use one, and the last `close()` disposes it, unless whoever called
+  `loadFirebirdWasm()` still owns it. The next database loads a new module
+  (0.33–0.43 s without threads, about 1 s threaded); to keep one loaded
+  across closes, call `loadFirebirdWasm()` once, which owns it. A `memory://` database
+  went with its `close()` already; nothing else kept state in the module. An
+  `opfs://` database's access handle is now closed on `close()` too, so the
+  same Worker can open it again.
+- **The build without threads is the default.** `wasmGlueFile()`,
+  `loadFirebirdWasm()`, `DirectTransport` and `cdnArtifacts()` now pick
+  `firebird-embedded-st` unless asked for threads, in Node and in a cross-origin
+  isolated page too; until now `'auto'` picked the threaded build wherever it
+  could run. The build without threads needs no `SharedArrayBuffer` and no
+  Worker, starts in about a third of the time (0.33–0.43 s against
+  0.87–1.06 s), and was not slower in anything measured; `firebird-quake2`
+  plays the same on it (a 5 ms tic on demo1 either way). What it gives up is
+  statement and idle timeouts. To keep the threaded build, ask for it:
+  `wasmGlueFile(true)` (or `wasmGlueFile(self.crossOriginIsolated)` for
+  threads where the page allows them), `loadFirebirdWasm({ threads: true })`,
+  `new DirectTransport({ threads: true })`, `cdnArtifacts({ threads: true })`.
+
+### Added
+
+- **`disposeFirebirdWasm(mod)`** ends a module and lets it go: every database
+  detached, the engine shut down (`_fb_dispose`, which calls `fb_shutdown`),
+  the threaded build's workers terminated, and the module out of the cache.
+  Two things held a dropped threaded module: its 32 workers (about 400 MB in
+  Node) and the main thread's `Atomics.waitAsync` on its mailbox. Over ten
+  load/dispose cycles in Node, RSS levels off at about 200 MB without threads
+  and 300 MB threaded. Needs a rebuilt artifact.
+- **Bytes as parameters.** A `Uint8Array` or `ArrayBuffer` binds as its own
+  bytes into a `BLOB` or a `BINARY` / `VARBINARY` (`OCTETS`) column, on both
+  backends and by every route (`exec`, `query`, transactions, `execBatch`).
+  The browser engine marks the bytes as bytes, so any other column refuses
+  them instead of reading them as text; `FirebirdLite` hands them to the
+  driver as a `Buffer`. They used to throw.
+- **`bytea` syncs.** `firebird-wasm/electric` decodes Electric's `\x…` hex
+  into bytes, and `tableFromSchema` maps `bytea` to `BLOB SUB_TYPE BINARY`
+  (`VARCHAR(255) CHARACTER SET OCTETS` in a key). The shape server serves a
+  binary `BLOB`, `BINARY` and `VARBINARY` as `bytea`, byte for byte.
+- **`syncShapesToTables`: several tables, one transaction per batch.** The
+  shapes are followed together and each batch is applied to every table in
+  one Firebird transaction with every shape's position, so a Postgres
+  transaction that wrote to two tables never shows in one of them alone. A
+  batch waits until every shape has reached up-to-date after its last change,
+  and until all are at the same `global_last_seen_lsn` where the server sends
+  it; a shape behind is refreshed. The shape server now sends
+  `global_last_seen_lsn` (its log position) as Electric does.
+  `syncShapeToTable` is the one-shape case of the same code.
+- **A write path: `createWriteQueue`.** `insert`, `update` and `delete`
+  apply to the synced table at once and are recorded in `ELECTRIC_WRITES`
+  in the same transaction (so they survive a reload and an offline spell),
+  then go to the app's API through `send`, in order, retried on failure. A
+  sync given `writes` applies the pending writes again after every batch, so
+  the source's older state never shows over them, and drops each write once
+  its change comes back: by the transaction id `send` returned (Electric's
+  `txids`, which the shape server now sends too), by the row changing, or
+  after `confirmTimeoutMs`. A `WriteRejected` rolls the write back by
+  fetching the table's shape again. Syncs and the queue now run their
+  transactions on a database one at a time.
+- **The shape server takes `where`, pages its snapshots, prunes its log,
+  wakes on events, and runs beside others.**
+  - `where` (and Electric's `params[n]`) is parsed and written as Firebird
+    SQL with every value bound; functions, casts and subqueries are refused
+    with a 400. Each `where` and `columns` is a shape with its own handle,
+    and a row that stops matching leaves as a delete.
+  - Snapshots are served `snapshotPageRows` (10 000) rows a response, by
+    key.
+  - The log is pruned of changes older than `retainLogMs` (7 days), or by
+    `prune(before)`; a client further behind is sent back to a snapshot.
+  - Commits wake live requests through the `ELECTRIC_CHANGES` event, with
+    polling (now every 1 s) as the fallback.
+  - Numbering takes a lock, so several servers can serve one database.
+- **An example app that syncs from two servers:
+  [`examples/electric`](./examples/electric).** Two lists of notes, each a
+  table in the page's Firebird: one follows Postgres through Electric, the
+  other a Firebird server through `firebird-wasm/electric-server`. Writes go
+  to the source and come back down the shape; `db.live()` draws the lists;
+  `<firebird-repl>` queries the local copy. A Node server and a
+  `docker-compose.yml` run the sources. CI runs it in Chromium against real
+  containers, with both engine builds.
+
+### Fixed
+
+- **The statement cache sees DDL it did not run.** It emptied itself before
+  DDL the bridge ran, but not for DDL inside `EXECUTE STATEMENT`, a
+  procedure, or another attachment: a kept `SELECT` of a table dropped that
+  way went on returning the dropped table's rows, and a kept call of a
+  procedure altered that way ran its old body. The engine now counts each
+  committed metadata change (patch 0007), and a database's kept statements go
+  when the count has moved. Reads and writes never move it, so the cache
+  works as before for them; `_fb_metadata_commits()` reads the count.
+  Calling `_fb_statement_cache()` after such DDL is no longer needed. Needs a
+  rebuilt artifact.
+- **`EXECUTE STATEMENT` runs in the browser engine.** It did nothing, without
+  an error: an `INSERT` through it inserted no row, `INTO` gave `NULL`, and
+  `FOR EXECUTE STATEMENT … DO` gave no rows. It runs through Firebird's
+  External Data Sources (`jrd/extds`) even without `ON EXTERNAL`, and the
+  build replaced that directory with no-op stubs. It is compiled now, so
+  parameters, `WITH AUTONOMOUS TRANSACTION` and the caller's transaction work
+  as in Firebird, and its errors are reported.
+  Needs a rebuilt artifact: 170–200 KB larger, 54–55 KB gzipped (+2 %).
+- **The browser engine reads `BINARY` and `VARBINARY` (`OCTETS`) values as
+  bytes**, as it reads a binary `BLOB`: base64 by default, a `Uint8Array`
+  with `types: { binary: true }`. They were read as text, which turned bytes
+  that are not UTF-8 into replacement characters (`GEN_UUID()` among them).
+- **Two `syncShapeToTable` calls started together on a new database no
+  longer stop one of them.** Both found no `ELECTRIC_SHAPES` table and both
+  created it; the second creation failed ("unsuccessful metadata update")
+  and that sync stopped before it began. The loser now looks again and goes
+  on with the table the other made. Found by the example, which starts its
+  two syncs at once.
+- **Closing a shape server while a live request waits no longer crashes the
+  process.** `close()` disconnected at once, and a waiting live request's next
+  poll started a transaction on the closed connection, where the native
+  client segfaults rather than throwing. `close()` now waits for whatever is
+  running on the connection, and the requests still waiting end with a 503.
+  Found as an intermittent crash of `browser-firebird-shapes.spec.ts`, which
+  closes its server while the browser is still following it.
+
+## 0.8.0 — 2026-10-18
+
+### Security
+
+- **Importing the library no longer starts an engine server, and a page's
+  window is never served.** `firebird-wasm/browser` re-exported
+  `serveEngine` from the Worker entry, which started serving as soon as it
+  was loaded wherever `self.postMessage` existed, and a page's `window` has
+  one. So every page that imported the library listened for engine requests
+  on its window. With the engine on the page thread (the build without
+  threads, new in 0.7.0) that listener shared the page's engine, and any
+  window able to `postMessage` to the page, a frame or an opener of another
+  origin, could run SQL against its databases. With the engine in a Worker it
+  had no engine to reach. Now `serveEngine` lives in a module without side
+  effects, the Worker entry starts only in a dedicated Worker, and
+  `serveEngine` refuses a scope that has a `document`. Upgrade from 0.7.0 if
+  you run the engine on the page thread.
+
+### Added
+
+- **`firebird-wasm/electric-server`: a Firebird server's tables over
+  Electric's protocol.** `createShapeServer({ database, tables })` returns a
+  Node HTTP handler that `syncShapeToTable` syncs from as it would from
+  Electric, so a table on a Firebird server reaches Firebird in the browser
+  with no Postgres. Triggers log each changed row's key; the server numbers
+  the log in commit order before every read, so a transaction that wrote
+  first and committed last is never skipped, and a connection opened before
+  the capture was installed is captured too. Tested on Firebird 3, 4 and 5,
+  and end to end into the engine in Chromium.
+- **`firebird-wasm/electric`: sync a Postgres table through Electric.**
+  `syncShapeToTable(db, { shape, table, shapeKey })` keeps a Firebird table in
+  step with an Electric shape: each batch Electric marks up-to-date applied in
+  one transaction with the sync position, a resume from that position after a
+  reload, a full reload in one transaction on must-refetch, Postgres text
+  converted exactly per column type (and unmapped types refused by name), and
+  an event per batch for `live()` and the hooks. `tableFromSchema()` writes a
+  `CREATE TABLE` from a shape's schema to review. Read-only, as Electric is.
+  `@electric-sql/client` is an optional peer dependency. Tested against a real
+  Postgres and Electric in CI. A Postgres `int8` is bound as its text, which
+  converts into `BIGINT` exactly and which the Node driver can bind.
+- **`firebird-wasm/repl`: a SQL console as a custom element.**
+  `defineFirebirdRepl()` registers `<firebird-repl>`; give it a database
+  through its `db` property. Ctrl+Enter runs a script statement by statement
+  (`SET TERM` included) and stops at the first error; rows show as a table,
+  other statements with the rows they changed; ArrowUp and ArrowDown walk the
+  history. Values are drawn as text, never as HTML. A `db` set before the
+  element was defined, as frameworks do, is kept.
+- **`firebird-wasm/react` and `firebird-wasm/vue`.** `useQuery` runs a
+  statement and re-runs it when its SQL or parameters change by value;
+  `useLiveQuery` re-runs it each time one of its events fires (`live()`
+  under a hook). Both give `rows`, `error`, `loading` and `refresh()`, keep
+  the previous rows while the next ones load, drop results that arrive after
+  the component moved on, and unsubscribe on unmount, StrictMode's double
+  mount included. React through `FirebirdProvider`, Vue through
+  `provideFirebird(db)` or `app.provide(FIREBIRD, db)`; the statement and
+  parameters may be refs or getters in Vue. React 18+ and Vue 3.3+ are
+  optional peer dependencies.
+- **`examples/vite` and `examples/webpack`.** Minimal apps built by their own
+  bundlers from the package, run by CI in Chromium with and without
+  cross-origin isolation.
+
+### Fixed
+
+- **`FirebirdLite` binds a string into a DATE, TIME or TIMESTAMP parameter,
+  exactly.** The native driver takes a JS `Date` there and failed on a string
+  (`date.getFullYear is not a function`), so `firebird-wasm/electric`'s
+  `syncShapeToTable`, which sends dates and times as text, could not write to
+  a `FirebirdLite` database. Such a string is now sent as text and Firebird
+  converts it, as the browser engine does: to 1/10000 s, with no detour
+  through milliseconds or the process's time zone, and `WITH TIME ZONE` too
+  (with a Firebird 4 or later client library). A `Date` binds as before.
+- **`FirebirdLite` binds a string into an integer or NUMERIC parameter digit
+  for digit.** The driver binds those as doubles: `'9007199254740993'` into
+  a BIGINT arrived as 9007199254740992, and `syncShapeToTable` sends `int8`
+  and `numeric` as text. Such a string is now sent as text too; a JS number
+  is unchanged, and `execBatch` declares a block's parameter as the column's
+  own type rather than DOUBLE PRECISION.
+- **A bad parameter beside a BLOB no longer kills the process.** The driver
+  wrote a BLOB parameter while encoding the others, under a `Promise.all`
+  that rejected as soon as one failed, and the transaction was rolled back
+  under the blob's native calls: a date as a string, or a string too long for
+  its VARCHAR, beside a BLOB ended Node with a segmentation fault (seen in
+  Jest syncing a shape into a `FirebirdLite` database). `FirebirdLite` now
+  writes the blob before the driver encodes anything, so the failure is the
+  error it should be.
+- **An event posted right after subscribing is no longer lost.** A
+  subscription's first delivery from the engine is a baseline, not news, and
+  the bridge absorbed whatever it said. With threads that delivery comes from
+  the engine's watcher thread some time after the subscription returns, so a
+  `POST_EVENT` that committed first was folded into it and never reported: a
+  `live()` query missed its first change in about one browser run in three.
+  Subscribing now waits for the baseline before returning (the build without
+  threads delivered it in time already).
+- **`live()` no longer drops an event heard during a refresh.** It ran one
+  refresh at a time by ignoring events while one ran, but that refresh may
+  have read before the change committed, so the rows stayed stale until some
+  later event. An event during a refresh now earns exactly one more. `live()`
+  also subscribes before its first query rather than after, so a change
+  committed between the two is no longer in neither, and releases the
+  subscription if that query fails.
+- **`FirebirdLite` binds a string into a BLOB parameter.** The native driver
+  takes a `Buffer` there and refused a string ("Unrecognized type used as
+  BLOB"); a string bound to a BLOB parameter is now passed as its UTF-8
+  bytes, in `exec`, `query`, transactions and `execBatch`. The browser engine
+  had the same gap, fixed above.
+- **A string binds into a BLOB parameter.** `INSERT INTO notes (body) VALUES
+  (?)` with a `BLOB SUB_TYPE TEXT` column failed in the browser engine ("BLOB
+  and array data types are not supported for move operation"): a BLOB
+  parameter takes a blob's id, and the bridge only converted values. It now
+  writes the text as a blob in the statement's transaction and binds its id,
+  through `exec`, `query`, transactions and `execBatch` alike, with no size
+  limit of its own (text parameters were capped at 64 KB). A batch with a
+  BLOB parameter runs as one execute per row, since Firebird's batch takes no
+  blob written outside it.
+- **`firebird-wasm/browser/worker-entry` can be imported.** The package's
+  `exports` did not list it, so the import the integration guide showed failed
+  in any bundler that honours `exports` (Vite and webpack both). It is now
+  exported, and so is `./package.json`.
+- **`firebird-wasm/browser/worker-entry` imported with a bundler.** In a
+  Worker that imported the library before setting
+  `FIREBIRD_WORKER_OPTIONS`, the side effect above started the engine without
+  them, so its `.wasm` was looked for next to the Worker script.
+- **A `CHAR(n)` in UTF-8 reads back as n characters.** Firebird pads a
+  `CHAR` to its length in bytes, four a character in UTF-8, and the browser
+  engine returned all of them: a `CHAR(36)` holding a uuid came back as the
+  uuid and 108 spaces. It is now cut to n characters, its own padding kept
+  (`'ab'` in a `CHAR(5)` is `'ab   '`, `'žš'` is `'žš   '`), as other
+  Firebird drivers return it. `OCTETS` and `NONE` columns, one byte a
+  character, are unchanged.
+
+### Changed
+
+- **A quoted column name keeps its case in results.** `query` upper-cased
+  every column name, so `SELECT title AS "title"` gave `TITLE`, unlike what
+  the integration guide said, and `SELECT "camelCase" FROM t` gave
+  `CAMELCASE`. Names are now as Firebird reports them, in the browser engine
+  and in `FirebirdLite` alike: unquoted names are still upper case (Firebird
+  folds them), so only quoted names change. Code that read a quoted name by
+  its upper-cased key (`row.CAMELCASE`) must use the name as written
+  (`row.camelCase`), or drop the quotes from the alias.
+
 ## 0.7.0 — 2026-10-18
 
 ### Fixed

package/README.md

@@ -51,11 +51,13 @@ const { rows } = await db.query('SELECT * FROM notes');
 // [{ ID: 1, TITLE: 'Hello' }]
 ```
 
-Two constraints are structural for the default, threaded build: the page must
+The default build, `firebird-embedded-st.js`, has no threads: it needs no
+`SharedArrayBuffer`, so no cross-origin isolation, and can run without a
+Worker. The threaded build (`wasmGlueFile(true)`, `threads: true`) adds
+statement and idle timeouts, and has two structural constraints: the page must
 be [cross-origin isolated](../../docs/integration.md#2-the-two-hard-requirements-and-the-build-without-them),
 and the engine must run in a Worker — it blocks on mutexes, and a browser main
-thread may not block. `firebird-embedded-st.js`, the build without threads,
-has neither constraint and gives up statement and idle timeouts.
+thread may not block. Until 0.9.0 the threaded build was the default.
 
 ## Quick start
 
@@ -114,7 +116,7 @@ Execute a query and return a `QueryResult<T>`:
 
 ```ts
 interface QueryResult<T> {
-  rows: T[];       // result rows keyed by UPPER-CASE column name
+  rows: T[];       // result rows keyed by column name (upper case unless quoted)
   fields: FieldInfo[];  // column metadata
 }
 ```
@@ -155,8 +157,7 @@ FIREBIRD_PASSWORD=masterkey npm test
 
 ## Roadmap
 
-Shipped in 0.1.0 — every item the previous roadmap listed as pending, except
-the last:
+Shipped in 0.1.0:
 
 - [x] True WASM build — Firebird 6.0 compiled with Emscripten
 - [x] Browser support via the WASM bundle, with the engine in a Web Worker
@@ -167,19 +168,34 @@ the last:
       letting it overwrite the first
 - [x] The prebuilt engine on npm, so using it needs no Emscripten
 
+Shipped since:
+
+- [x] Live queries built on Firebird's `POST_EVENT` (`live()`, `listen()`,
+      `notify()`)
+- [x] Multi-tab *sharing* (`multiTab: 'shared'`): one tab runs the engine,
+      the others are served by it
+- [x] OPFS backend (`opfs://name`), with no image copy and no persist step
+- [x] A build without `SharedArrayBuffer` (`firebird-embedded-st`), for pages
+      served without COOP/COEP headers
+- [x] React and Vue hooks (`firebird-wasm/react`, `firebird-wasm/vue`) and a
+      REPL element (`firebird-wasm/repl`)
+- [x] ElectricSQL sync, read path: a shape from Postgres through Electric
+      (`firebird-wasm/electric`), or from a Firebird server
+      (`firebird-wasm/electric-server`), with an example app syncing from
+      both ([`examples/electric`](../../examples/electric)), `bytea`
+      included, and several tables in one transaction
+      (`syncShapesToTables`)
+- [x] ElectricSQL writes: `createWriteQueue` applies a write at once, sends
+      it to the app's API, and keeps it over the sync until it comes back
+- [x] Module disposal: `disposeFirebirdWasm()`, and closing the last
+      database frees the engine's memory
+
 Next:
 
-- [ ] Live queries built on Firebird's `POST_EVENT`
-- [ ] Multi-tab *sharing* — a `SharedWorker` leader, so a second tab is served
-      rather than refused
-- [ ] OPFS backend — a better match for page-oriented I/O than IndexedDB
 - [ ] A typed binary result ABI, so exact numerics need not travel as strings
-- [ ] Module disposal — `close()` does not currently release the WASM heap
-- [ ] Loadable character sets. `src/intl` compiles under Emscripten and costs
-      +245 KB gzipped, measured; what is missing is a way for `IntlManager`
-      to reach it without `dlopen`. See
+- [ ] UNICODE collations (case- and accent-insensitive comparison), which
+      need ICU collation data in the build. See
       [docs/roadmap.md](../../docs/roadmap.md)
-- [ ] ElectricSQL sync
 
 **"Firebird 4 & 5 support" is gone from this list because it was never the
 gap.** The build tracks Firebird `master` and the shipped engine reports