Deliver held outcomes to a definition that arrives after configure()

CHANGELOG.md

@@ -116,6 +116,22 @@ pending until the returned function is called, so a test can model a native
 that is slow to answer. Later enqueues wait behind it, as they do on a
 device.
 
+A key that `define()` registers after `configure()` now receives its held
+outcomes in the same session. Before, an outcome that replayed before its
+key had a definition emitted the `unhandled-key` row and then waited for the
+next launch. This happened when a bundler loaded a module lazily, such as
+Metro with `inlineRequires`. The outcomes of one id and key still deliver
+in order; across keys, the key defined first delivers first. The
+`unhandled-key` row is not followed by a new `state` row when the outcome is
+handled. `cancel(id)` drops the held outcomes of that id. An outcome whose
+key is never defined stays unacknowledged, as before.
+
+`configure()` takes an optional `definitions` list, the handles that
+`define()` returned. Listing a handle imports its module, so its `define()`
+runs before the replay. In development, a later `define()` of a key that is
+not listed logs a warning. Nothing else changes: an unlisted key still
+receives its outcomes. The new `AnyDefined` type names one entry of the list.
+
 ## 11.1.0
 
 Added `takeDiagnostics()`. On Android it returns the module's recent

README.md

@@ -293,13 +293,25 @@ while the app was dead from being sent twice.
    outcomes wait too. They stay journaled and unacknowledged, so none is
    lost.
 5. **Replay starts after `configure()`.** Outcomes journaled by a dead session
-   deliver then. Call every `define()` first.
-6. **Unknown key is loud.** An outcome whose key has no definition stays
-   unacknowledged and reaches `state` listeners with `reason: 'unhandled-key'`.
+   deliver then. Call every `define()` first. A bundler that loads modules
+   lazily, such as Metro with `inlineRequires`, can run a `define()` later.
+   That key then receives its held outcomes when its `define()` runs, in the
+   same session and in their original order per id. Order holds among the
+   outcomes of one key. Across keys, the key defined first delivers first.
+   `cancel(id)` drops the held outcomes of that id.
+6. **Unknown key is loud.** An outcome whose key has no definition reaches
+   `state` listeners with `reason: 'unhandled-key'`, and the library holds it.
+   When no `define()` of the key comes in this session, it stays
+   unacknowledged and redelivers at the next launch. When a later `define()`
+   handles it, no new `state` row replaces the `unhandled-key` row. After the
+   ack, a `completed` or `cancelled` entry leaves `getRequests()` without a
+   `state` event, and an `error` entry stays with its `error` row.
 7. **Completed entries are forgotten after ack.** Row and bytes go. An `error`
    or `expired` entry keeps both until `cancel()` or a same-id `mutate()`.
 8. **Ordering holds per id only.** The outcomes of one id are delivered in
-   order. There is no ordering guarantee between different ids.
+   order. One exception: when one id has held outcomes under two keys, the
+   key defined first delivers first (rule 5). There is no ordering guarantee
+   between different ids.
 9. **`attempt` events are live-only.** They are never journaled or replayed.
 
 Retry classes:
@@ -401,10 +413,13 @@ whose `request` takes no vars, call `mutate()` with no arguments; native stores
 ### `configure(options): void`
 
 Call one time at boot, after every `define()`. Starts replay of journaled
-outcomes. A second call updates the settings and does not replay again.
+outcomes. A second call updates the settings and does not replay again. A
+`define()` that runs after `configure()` still receives the outcomes that
+reached its key before it; see rule 5 of "Reliable delivery".
 
 | Option | Notes |
 | --- | --- |
+| `definitions` | Optional. Every definition, as `define()` returned it. Listing a handle imports its module, so its `define()` runs before replay starts. In development, a later `define()` of a key that is not listed logs a warning. That key still receives its outcomes, and `mutate()` works for it. Throws when it is not an array of handles. |
 | `lifetimeMs` | Default `expiresAt` distance. Default 14 days. |
 | `maxVarsBytes` | Cap on the JSON length of `vars`. Default 1 MB. `mutate()` rejects above it. JS-side only. |
 | `retry` | `{ backoff?: { baseMs, maxMs, jitter }, terminalHttp?: { exempt }, transient?: Array<{ status, bodyIncludes?, maxRetries? }> }`. Each object is optional, but one you give must be complete. Defaults 1 s, 2 h, 0.2, `[404]`, `[]`. A descriptor's `retry` replaces each field it names. |