@ignite-ember/extension-bridge 0.2.0 → 0.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/src/contract.ts CHANGED
@@ -44,17 +44,34 @@ export interface Bridge<
44
44
  * than a CSS variable — a canvas, a chart library.
45
45
  */
46
46
  readonly tokens: ThemeTokens;
47
- /** Call a backend RPC. Rejects with the host's refusal, as a sentence. */
47
+ /**
48
+ * Call a backend RPC. Rejects with the host's refusal, as a sentence.
49
+ *
50
+ * @param method — the method to call, as `ext.<extension-id>.<method>`
51
+ * names it.
52
+ * @param args — the method's arguments, by name.
53
+ * @param timeoutMs — how long to wait for the answer before giving up,
54
+ * in milliseconds. The host has a timeout of its own, and the
55
+ * shorter of the two is the one that fires.
56
+ */
48
57
  rpc<T = unknown>(
49
58
  method: string,
50
59
  args?: RpcArgs,
51
60
  timeoutMs?: number,
52
61
  ): Promise<T>;
53
- /** Ask the host app to navigate. It decides whether to. */
62
+ /**
63
+ * Ask the host app to navigate. It decides whether to.
64
+ *
65
+ * @param to — the page to go to; the host decides whether it exists.
66
+ */
54
67
  navigate(to: string): void;
55
68
  /** Tell the host this surface is finished. */
56
69
  close(): void;
57
- /** Follow the host's theme. Returns an unsubscribe. */
70
+ /**
71
+ * Follow the host's theme. Returns an unsubscribe.
72
+ *
73
+ * @param fn — called with the theme whenever it changes.
74
+ */
58
75
  onTheme(fn: (theme: string) => void): () => void;
59
76
  /**
60
77
  * Follow the launch parameters.
@@ -67,6 +84,8 @@ export interface Bridge<
67
84
  *
68
85
  * Fires only on change, never for the initial value; read
69
86
  * {@link params} for that.
87
+ *
88
+ * @param fn — called with the parameters whenever they change.
70
89
  */
71
90
  onParams(fn: (params: P) => void): () => void;
72
91
  /**
@@ -82,12 +101,15 @@ export interface Bridge<
82
101
  * Strings only, and keep it small — it ends up in the host's URL.
83
102
  * Call it when the user lands somewhere worth returning to, not on
84
103
  * every keystroke.
104
+ *
105
+ * @param state — where inside the extension the user is now, in
106
+ * strings, for the host to fold into its own URL.
85
107
  */
86
108
  setLocation(state: LocationState): void;
87
109
 
88
110
  /**
89
111
  * igni, as this extension sees it: the host object model
90
- * (`docs/HOST_OBJECT_MODEL.md` in igni). The same model the
112
+ * (igni-core's `docs/HOST_OBJECT_MODEL.md` (https://github.com/ignite-ember/igni-core/blob/main/docs/HOST_OBJECT_MODEL.md)). The same model the
91
113
  * extension's process reaches as `ext.host`.
92
114
  *
93
115
  * const busy = await bridge.host.chat.processing.get();
@@ -106,6 +128,11 @@ export interface Bridge<
106
128
  * one unsubscribes. A signal whose object is not granted never
107
129
  * arrives; the refusal goes to `onRefused`, or to the console when
108
130
  * there is none. Returns an unsubscribe.
131
+ *
132
+ * @param signal — the host signal to follow.
133
+ * @param fn — called with the signal's value each time it arrives.
134
+ * @param onRefused — called with the refusal when the host will not
135
+ * grant the signal; without one the refusal goes to the console.
109
136
  */
110
137
  on<T>(
111
138
  signal: Signal<T>,
@@ -115,7 +142,7 @@ export interface Bridge<
115
142
 
116
143
  /**
117
144
  * The extension's own service, reached directly, as the signed-in
118
- * person:
145
+ * person.
119
146
  *
120
147
  * const res = await bridge.service.fetch("/v1/notes");
121
148
  * const socket = await bridge.service.websocket("/v1/rooms/a");
@@ -123,7 +150,7 @@ export interface Bridge<
123
150
  * The host fetches a token whose audience is this extension's service
124
151
  * and nothing else; it is kept and renewed before it expires. No
125
152
  * `permissions.host` grant: having a service is the grant — see
126
- * `docs/HOST_OBJECT_MODEL.md` in igni. `url` is `null` when the
153
+ * igni-core's `docs/HOST_OBJECT_MODEL.md` (https://github.com/ignite-ember/igni-core/blob/main/docs/HOST_OBJECT_MODEL.md). `url` is `null` when the
127
154
  * extension has none.
128
155
  */
129
156
  readonly service: ServiceBridge;
package/src/correlator.ts CHANGED
@@ -52,7 +52,14 @@ export class Correlator {
52
52
  reject,
53
53
  timer,
54
54
  });
55
- post(id);
55
+ try {
56
+ post(id);
57
+ } catch (error) {
58
+ // Nothing was sent, so no reply will come: do not leave the
59
+ // waiter and its timer behind for a request that never left.
60
+ this.take(id);
61
+ throw error;
62
+ }
56
63
  });
57
64
  }
58
65