@nanolink/mirrors 1.0.35 → 1.0.37

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.
Files changed (122) hide show
  1. package/LICENSE +21 -21
  2. package/README.md +208 -150
  3. package/dist/definitions/fragments.d.ts +6 -0
  4. package/dist/definitions/fragments.js +10 -0
  5. package/dist/definitions/fragments.js.map +1 -0
  6. package/dist/definitions/mirrors.d.ts +38 -0
  7. package/dist/definitions/mirrors.js +78 -0
  8. package/dist/definitions/mirrors.js.map +1 -0
  9. package/dist/definitions/requiredMirrors/index.d.ts +2 -0
  10. package/dist/definitions/requiredMirrors/index.js +19 -0
  11. package/dist/definitions/requiredMirrors/index.js.map +1 -0
  12. package/dist/definitions/requiredMirrors/settings.d.ts +1 -0
  13. package/dist/definitions/requiredMirrors/settings.js +32 -0
  14. package/dist/definitions/requiredMirrors/settings.js.map +1 -0
  15. package/dist/definitions/requiredMirrors/systemSettings.d.ts +1 -0
  16. package/dist/definitions/requiredMirrors/systemSettings.js +30 -0
  17. package/dist/definitions/requiredMirrors/systemSettings.js.map +1 -0
  18. package/dist/definitions/subscriptions/activecounter.d.ts +1 -0
  19. package/dist/definitions/subscriptions/activecounter.js +18 -0
  20. package/dist/definitions/subscriptions/activecounter.js.map +1 -0
  21. package/dist/definitions/subscriptions/activecycles.d.ts +1 -0
  22. package/dist/definitions/subscriptions/activecycles.js +25 -0
  23. package/dist/definitions/subscriptions/activecycles.js.map +1 -0
  24. package/dist/definitions/subscriptions/activesteps.d.ts +1 -0
  25. package/dist/definitions/subscriptions/activesteps.js +29 -0
  26. package/dist/definitions/subscriptions/activesteps.js.map +1 -0
  27. package/dist/definitions/subscriptions/batterypercent.d.ts +1 -0
  28. package/dist/definitions/subscriptions/batterypercent.js +18 -0
  29. package/dist/definitions/subscriptions/batterypercent.js.map +1 -0
  30. package/dist/definitions/subscriptions/calculatedodometer.d.ts +1 -0
  31. package/dist/definitions/subscriptions/calculatedodometer.js +18 -0
  32. package/dist/definitions/subscriptions/calculatedodometer.js.map +1 -0
  33. package/dist/definitions/subscriptions/connected.d.ts +1 -0
  34. package/dist/definitions/subscriptions/connected.js +17 -0
  35. package/dist/definitions/subscriptions/connected.js.map +1 -0
  36. package/dist/definitions/subscriptions/cycles.d.ts +1 -0
  37. package/dist/definitions/subscriptions/cycles.js +81 -0
  38. package/dist/definitions/subscriptions/cycles.js.map +1 -0
  39. package/dist/definitions/subscriptions/gps.d.ts +1 -0
  40. package/dist/definitions/subscriptions/gps.js +36 -0
  41. package/dist/definitions/subscriptions/gps.js.map +1 -0
  42. package/dist/definitions/subscriptions/groups.d.ts +1 -0
  43. package/dist/definitions/subscriptions/groups.js +21 -0
  44. package/dist/definitions/subscriptions/groups.js.map +1 -0
  45. package/dist/definitions/subscriptions/index.d.ts +31 -0
  46. package/dist/definitions/subscriptions/index.js +48 -0
  47. package/dist/definitions/subscriptions/index.js.map +1 -0
  48. package/dist/definitions/subscriptions/internalvoltage.d.ts +1 -0
  49. package/dist/definitions/subscriptions/internalvoltage.js +19 -0
  50. package/dist/definitions/subscriptions/internalvoltage.js.map +1 -0
  51. package/dist/definitions/subscriptions/jobs.d.ts +1 -0
  52. package/dist/definitions/subscriptions/jobs.js +68 -0
  53. package/dist/definitions/subscriptions/jobs.js.map +1 -0
  54. package/dist/definitions/subscriptions/linkconnected.d.ts +1 -0
  55. package/dist/definitions/subscriptions/linkconnected.js +17 -0
  56. package/dist/definitions/subscriptions/linkconnected.js.map +1 -0
  57. package/dist/definitions/subscriptions/lostTransmitters.d.ts +1 -0
  58. package/dist/definitions/subscriptions/lostTransmitters.js +40 -0
  59. package/dist/definitions/subscriptions/lostTransmitters.js.map +1 -0
  60. package/dist/definitions/subscriptions/meshDiagnostics.d.ts +1 -0
  61. package/dist/definitions/subscriptions/meshDiagnostics.js +34 -0
  62. package/dist/definitions/subscriptions/meshDiagnostics.js.map +1 -0
  63. package/dist/definitions/subscriptions/meshdisconnectslasthour.d.ts +1 -0
  64. package/dist/definitions/subscriptions/meshdisconnectslasthour.js +18 -0
  65. package/dist/definitions/subscriptions/meshdisconnectslasthour.js.map +1 -0
  66. package/dist/definitions/subscriptions/meshscanner.d.ts +1 -0
  67. package/dist/definitions/subscriptions/meshscanner.js +18 -0
  68. package/dist/definitions/subscriptions/meshscanner.js.map +1 -0
  69. package/dist/definitions/subscriptions/messages.d.ts +1 -0
  70. package/dist/definitions/subscriptions/messages.js +32 -0
  71. package/dist/definitions/subscriptions/messages.js.map +1 -0
  72. package/dist/definitions/subscriptions/referenceGeoLinks.d.ts +1 -0
  73. package/dist/definitions/subscriptions/referenceGeoLinks.js +23 -0
  74. package/dist/definitions/subscriptions/referenceGeoLinks.js.map +1 -0
  75. package/dist/definitions/subscriptions/referenceLinks.d.ts +1 -0
  76. package/dist/definitions/subscriptions/referenceLinks.js +24 -0
  77. package/dist/definitions/subscriptions/referenceLinks.js.map +1 -0
  78. package/dist/definitions/subscriptions/references.d.ts +1 -0
  79. package/dist/definitions/subscriptions/references.js +111 -0
  80. package/dist/definitions/subscriptions/references.js.map +1 -0
  81. package/dist/definitions/subscriptions/reports.d.ts +1 -0
  82. package/dist/definitions/subscriptions/reports.js +20 -0
  83. package/dist/definitions/subscriptions/reports.js.map +1 -0
  84. package/dist/definitions/subscriptions/servicePlans.d.ts +1 -0
  85. package/dist/definitions/subscriptions/servicePlans.js +47 -0
  86. package/dist/definitions/subscriptions/servicePlans.js.map +1 -0
  87. package/dist/definitions/subscriptions/temperature.d.ts +1 -0
  88. package/dist/definitions/subscriptions/temperature.js +18 -0
  89. package/dist/definitions/subscriptions/temperature.js.map +1 -0
  90. package/dist/definitions/subscriptions/trackerLinks.d.ts +1 -0
  91. package/dist/definitions/subscriptions/trackerLinks.js +23 -0
  92. package/dist/definitions/subscriptions/trackerLinks.js.map +1 -0
  93. package/dist/definitions/subscriptions/trackers.d.ts +1 -0
  94. package/dist/definitions/subscriptions/trackers.js +26 -0
  95. package/dist/definitions/subscriptions/trackers.js.map +1 -0
  96. package/dist/definitions/subscriptions/tripignition.d.ts +1 -0
  97. package/dist/definitions/subscriptions/tripignition.js +19 -0
  98. package/dist/definitions/subscriptions/tripignition.js.map +1 -0
  99. package/dist/definitions/subscriptions/trips.d.ts +1 -0
  100. package/dist/definitions/subscriptions/trips.js +41 -0
  101. package/dist/definitions/subscriptions/trips.js.map +1 -0
  102. package/dist/definitions/subscriptions/unplug.d.ts +1 -0
  103. package/dist/definitions/subscriptions/unplug.js +19 -0
  104. package/dist/definitions/subscriptions/unplug.js.map +1 -0
  105. package/dist/definitions/subscriptions/voltage.d.ts +1 -0
  106. package/dist/definitions/subscriptions/voltage.js +19 -0
  107. package/dist/definitions/subscriptions/voltage.js.map +1 -0
  108. package/dist/definitions/subscriptions/workignition.d.ts +1 -0
  109. package/dist/definitions/subscriptions/workignition.js +19 -0
  110. package/dist/definitions/subscriptions/workignition.js.map +1 -0
  111. package/dist/definitions/subscriptions/workseconds.d.ts +1 -0
  112. package/dist/definitions/subscriptions/workseconds.js +18 -0
  113. package/dist/definitions/subscriptions/workseconds.js.map +1 -0
  114. package/dist/definitions/tempSubscriptions/index.d.ts +1 -0
  115. package/dist/definitions/tempSubscriptions/index.js +5 -0
  116. package/dist/definitions/tempSubscriptions/index.js.map +1 -0
  117. package/dist/index.d.ts +2 -0
  118. package/dist/index.js +16 -1
  119. package/dist/index.js.map +1 -1
  120. package/dist-compat/index.js +985 -3
  121. package/dist-compat/index.js.map +1 -1
  122. package/package.json +2 -2
package/LICENSE CHANGED
@@ -1,21 +1,21 @@
1
- MIT License
2
-
3
- Copyright (c) 2024
4
-
5
- Permission is hereby granted, free of charge, to any person obtaining a copy
6
- of this software and associated documentation files (the "Software"), to deal
7
- in the Software without restriction, including without limitation the rights
8
- to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
- copies of the Software, and to permit persons to whom the Software is
10
- furnished to do so, subject to the following conditions:
11
-
12
- The above copyright notice and this permission notice shall be included in all
13
- copies or substantial portions of the Software.
14
-
15
- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
- IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
- FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
- AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
- LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
- OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
- SOFTWARE.
1
+ MIT License
2
+
3
+ Copyright (c) 2024
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,150 +1,208 @@
1
- # @nanolink/mirrors
2
-
3
- GraphQL subscription client + in‑memory mirror synchronization utilities. Optimized for incremental change streams that send START / UPDATED / DELETED / DONE / VERSION_ERROR frames.
4
-
5
- ## Features
6
- * Lightweight `SubscriptionClient` around `graphql-ws` with explicit connect, controlled reconnect, and small event surface.
7
- * Dual version support in `MirrorSync` (`version` numeric + optional `opVersion` string) for hybrid sequence + causality ordering (either dimension can drive resync logic when present).
8
- * Stale delete & update guards: ignores events older in either version dimension to prevent resurrecting removed or outdated entities.
9
- * Efficient updates: UPDATED replaces item wholesale only when newer; no deep merge overhead.
10
- * Full sync cycle handling via START/DONE gates; `loaded` promise resolves after first DONE and re-arms on VERSION_ERROR.
11
- * Automatic resubscribe after reconnect using last known versions (no duplicate inserts).
12
- * Read‑only delegated map interface for consumers (prevents accidental mutation of internal state).
13
- * `Connection` helper manages multiple mirrors, re‑emitting namespaced events (`mirror:start`, `mirror:updated`, ...).
14
- * Proxy-aware WebSocket resolution: if proxy env vars are present (ALL_PROXY / HTTPS_PROXY / HTTP_PROXY / GLOBAL_AGENT_HTTP_PROXY) the client prefers the Node `ws` implementation; otherwise uses existing global WebSocket (browser / Node >=18) or falls back to `ws`.
15
- * Minimal dependencies; event system via `eventemitter3`.
16
-
17
- ## Install
18
- ```bash
19
- npm install @nanolink/mirrors
20
- ```
21
-
22
- Optional (proxy via global-agent for generic HTTP(S) requests—WebSocket selection is still handled automatically as described):
23
- ```js
24
- // enableProxy.js
25
- import 'global-agent/bootstrap';
26
- process.env.GLOBAL_AGENT_HTTP_PROXY = 'http://proxy:3128';
27
- ```
28
- Run with:
29
- ```bash
30
- node -r global-agent/bootstrap app.js
31
- ```
32
-
33
- ## Usage
34
- ### Quick (multi‑mirror connection)
35
- ```ts
36
- import { Connection } from '@nanolink/mirrors';
37
-
38
- const conn = new Connection('https://api.example.com', 'TOKEN');
39
- conn.connect();
40
-
41
- conn.on('connected', () => console.log('socket up'));
42
- conn.on('mirror:updated', e => console.log('updated', e.mirrorName, e.item.id));
43
-
44
- async function main() {
45
- const users = await conn.getMirror('users', /* GraphQL subscription */ `
46
- subscription Users($version: Long, $opVersion: String) {
47
- users(version: $version, opVersion: $opVersion) {
48
- type
49
- total
50
- deleteId
51
- deleteVersion
52
- deleteOpVersion
53
- data { id version opVersion name }
54
- }
55
- }
56
- `, {});
57
-
58
- console.log('Initial size', users.size);
59
- for (const user of users.values()) {
60
- console.log(user);
61
- }
62
- }
63
- main();
64
- ```
65
-
66
- ### Direct low‑level client
67
- ### Numeric‑only subscriptions (most common)
68
- Most Nanolink GraphQL subscription fields expose only a numeric `version` and omit `opVersion`. `MirrorSync` handles this seamlessly: pass just `$version` in the query and the server responses won’t include `opVersion` / `deleteOpVersion` fields.
69
-
70
- ```ts
71
- // Numeric-only example
72
- const products = await conn.getMirror('products', `
73
- subscription Products($version: Long) {
74
- products(version: $version) {
75
- type
76
- total
77
- deleteId
78
- deleteVersion
79
- data { id version title }
80
- }
81
- }
82
- `, {});
83
-
84
- await products.loaded; // after first DONE
85
- console.log('Products count', products.size);
86
- ```
87
-
88
- When `opVersion` fields are absent they are simply ignored; ordering & stale protections rely on numeric `version` only.
89
-
90
- ```ts
91
- import { SubscriptionClient } from '@nanolink/mirrors';
92
-
93
- const sc = new SubscriptionClient({ url: 'https://api.example.com', maxReconnectAttempts: 10 });
94
- sc.connect();
95
- sc.on('connected', () => {
96
- const dispose = sc.subscribe({
97
- query: 'subscription Ping { ping }'
98
- }, {
99
- next: (msg) => console.log(msg),
100
- error: (e) => console.error('err', e),
101
- complete: () => console.log('done')
102
- });
103
- });
104
- ```
105
-
106
- ## Events
107
- `SubscriptionClient` emits:
108
- * connecting
109
- * connected (first successful connect)
110
- * reconnected (subsequent successful connect after a disconnect)
111
- * disconnected ({ code, reason, wasClean })
112
- * retry ({ attempt }) before a reconnect attempt delay
113
- * error (network/protocol)
114
-
115
- `Connection` re‑emits mirror events as `mirror:<event>` with payload `{ mirrorName, ... }`:
116
- * start
117
- * updated (only when a newer item actually replaced stored data)
118
- * deleted
119
- * done (end of full sync batch)
120
- * versionError (triggered resync)
121
- * resubscribe (automatic after reconnect)
122
- * error
123
- * removed (mirror explicitly removed)
124
- * cleared (mirror internal state cleared)
125
-
126
- ## API Surface
127
- * `SubscriptionClient` – low level websocket subscription wrapper.
128
- * `MirrorSync` single mirror controller (dual version tracking).
129
- * `Connection` manages multiple mirrors + namespaced events.
130
- * `ReadonlyMapView` – immutable view returned by `getMirror()` / `MirrorSync.load()`.
131
-
132
- ## Notes
133
- * Always call `connect()` explicitly; no implicit lazy connect.
134
- * VERSION_ERROR triggers automatic full resync (re-arms `loaded`).
135
- * First top-level field in GraphQL subscription payload is treated as the sync envelope.
136
- * Provide `webSocketImpl` manually if bundling for environments without a global WebSocket and you do NOT want `ws` as fallback.
137
- * When proxy env vars are set in Node, `SubscriptionClient` prefers `ws` (allowing external agent configuration); browsers ignore these env vars.
138
-
139
- ## Build & Publish
140
- TypeScript sources compile to `dist/`.
141
-
142
- Scripts:
143
- ```bash
144
- npm run build # compile
145
- npm run publish:dry # preview publish contents
146
- npm run release # build + publish (public)
147
- ```
148
-
149
- ## License
150
- MIT
1
+ # @nanolink/mirrors
2
+
3
+ GraphQL subscription client + in‑memory mirror synchronization utilities. Optimized for incremental change streams that send START / UPDATED / DELETED / DONE / VERSION_ERROR frames.
4
+
5
+ ## Features
6
+ * Lightweight `SubscriptionClient` around `graphql-ws` with explicit connect, controlled reconnect, and small event surface.
7
+ * Dual version support in `MirrorSync` (`version` numeric + optional `opVersion` string) for hybrid sequence + causality ordering (either dimension can drive resync logic when present).
8
+ * Stale delete & update guards: ignores events older in either version dimension to prevent resurrecting removed or outdated entities.
9
+ * Efficient updates: UPDATED replaces item wholesale only when newer; no deep merge overhead.
10
+ * Full sync cycle handling via START/DONE gates; `loaded` promise resolves after first DONE and re-arms on VERSION_ERROR.
11
+ * Automatic resubscribe after reconnect using last known versions (no duplicate inserts).
12
+ * Read‑only delegated map interface for consumers (prevents accidental mutation of internal state).
13
+ * `Connection` helper manages multiple mirrors, re‑emitting namespaced events (`mirror:start`, `mirror:updated`, ...).
14
+ * Proxy-aware WebSocket resolution: if proxy env vars are present (ALL_PROXY / HTTPS_PROXY / HTTP_PROXY / GLOBAL_AGENT_HTTP_PROXY) the client prefers the Node `ws` implementation; otherwise uses existing global WebSocket (browser / Node >=18) or falls back to `ws`.
15
+ * Minimal dependencies; event system via `eventemitter3`.
16
+
17
+ ## Install
18
+ ```bash
19
+ npm install @nanolink/mirrors
20
+ ```
21
+
22
+ Optional (proxy via global-agent for generic HTTP(S) requests—WebSocket selection is still handled automatically as described):
23
+ ```js
24
+ // enableProxy.js
25
+ import 'global-agent/bootstrap';
26
+ process.env.GLOBAL_AGENT_HTTP_PROXY = 'http://proxy:3128';
27
+ ```
28
+ Run with:
29
+ ```bash
30
+ node -r global-agent/bootstrap app.js
31
+ ```
32
+
33
+ ## Usage
34
+ ### Quick (multi‑mirror connection)
35
+ ```ts
36
+ import { Connection } from '@nanolink/mirrors';
37
+
38
+ const conn = new Connection('https://api.example.com', 'TOKEN');
39
+ conn.connect();
40
+
41
+ conn.on('connected', () => console.log('socket up'));
42
+ conn.on('mirror:updated', e => console.log('updated', e.mirrorName, e.item.id));
43
+
44
+ async function main() {
45
+ const users = await conn.getMirror('users', /* GraphQL subscription */ `
46
+ subscription Users($version: Long, $opVersion: String) {
47
+ users(version: $version, opVersion: $opVersion) {
48
+ type
49
+ total
50
+ deleteId
51
+ deleteVersion
52
+ deleteOpVersion
53
+ data { id version opVersion name }
54
+ }
55
+ }
56
+ `, {});
57
+
58
+ console.log('Initial size', users.size);
59
+ for (const user of users.values()) {
60
+ console.log(user);
61
+ }
62
+ }
63
+ main();
64
+ ```
65
+
66
+ ### Recommended: use `getPredefinedMirror()`
67
+ ```ts
68
+ // preferred helper uses predefined subscription templates from `src/definitions`
69
+ const devices = await conn.getPredefinedMirror('trackers');
70
+ await devices.loaded;
71
+ console.log('Trackers count', devices.size);
72
+ devices.on('updated', e => console.log('tracker updated', e.item.id));
73
+ ```
74
+
75
+ ### Direct low‑level client
76
+ ### Numeric‑only subscriptions (most common)
77
+ Most Nanolink GraphQL subscription fields expose only a numeric `version` and omit `opVersion`. `MirrorSync` handles this seamlessly: pass just `$version` in the query and the server responses won’t include `opVersion` / `deleteOpVersion` fields.
78
+
79
+ ```ts
80
+ // Numeric-only example
81
+ const products = await conn.getMirror('products', `
82
+ subscription Products($version: Long) {
83
+ products(version: $version) {
84
+ type
85
+ total
86
+ deleteId
87
+ deleteVersion
88
+ data { id version title }
89
+ }
90
+ }
91
+ `, {});
92
+
93
+ await products.loaded; // after first DONE
94
+ console.log('Products count', products.size);
95
+ ```
96
+
97
+ When `opVersion` fields are absent they are simply ignored; ordering & stale protections rely on numeric `version` only.
98
+
99
+ ```ts
100
+ import { SubscriptionClient } from '@nanolink/mirrors';
101
+
102
+ const sc = new SubscriptionClient({ url: 'https://api.example.com', maxReconnectAttempts: 10 });
103
+ sc.connect();
104
+ sc.on('connected', () => {
105
+ const dispose = sc.subscribe({
106
+ query: 'subscription Ping { ping }'
107
+ }, {
108
+ next: (msg) => console.log(msg),
109
+ error: (e) => console.error('err', e),
110
+ complete: () => console.log('done')
111
+ });
112
+ });
113
+ ```
114
+
115
+ ## Events
116
+ `SubscriptionClient` emits:
117
+ * connecting
118
+ * connected (first successful connect)
119
+ * reconnected (subsequent successful connect after a disconnect)
120
+ * disconnected ({ code, reason, wasClean })
121
+ * retry ({ attempt }) before a reconnect attempt delay
122
+ * error (network/protocol)
123
+
124
+ `Connection` re‑emits mirror events as `mirror:<event>` with payload `{ mirrorName, ... }`:
125
+ * start
126
+ * updated (only when a newer item actually replaced stored data)
127
+ * deleted
128
+ * done (end of full sync batch)
129
+ * versionError (triggered resync)
130
+ * resubscribe (automatic after reconnect)
131
+ * error
132
+ * removed (mirror explicitly removed)
133
+ * cleared (mirror internal state cleared)
134
+
135
+ ## API Surface
136
+ * `SubscriptionClient` low level websocket subscription wrapper.
137
+ * `MirrorSync` single mirror controller (dual version tracking).
138
+ * `Connection` – manages multiple mirrors + namespaced events.
139
+ * `ReadonlyMapView` immutable view returned by `getMirror()` / `MirrorSync.load()`.
140
+
141
+ Note about mirror helpers
142
+ -------------------------
143
+ `getMirror()` is available for custom ad-hoc mirrors but is seldom used in most integrations. The more commonly used helper is `getPredefinedMirror()` which returns mirrors for known server-side definitions (IDs and field payload shapes) and avoids having to supply the raw GraphQL subscription yourself. Check `src/definitions` for available predefined mirror names and subscription fragments.
144
+
145
+ ## Notes
146
+ * Always call `connect()` explicitly; no implicit lazy connect.
147
+ * VERSION_ERROR triggers automatic full resync (re-arms `loaded`).
148
+ * First top-level field in GraphQL subscription payload is treated as the sync envelope.
149
+ * Provide `webSocketImpl` manually if bundling for environments without a global WebSocket and you do NOT want `ws` as fallback.
150
+ * When proxy env vars are set in Node, `SubscriptionClient` prefers `ws` (allowing external agent configuration); browsers ignore these env vars.
151
+
152
+ ## Build & Publish
153
+ TypeScript sources compile to `dist/`.
154
+
155
+ Scripts:
156
+ ```bash
157
+ npm run build # compile
158
+ npm run publish:dry # preview publish contents
159
+ npm run release # build + publish (public)
160
+ ```
161
+
162
+ Developer notes (recent refactor)
163
+ ---------------------------------
164
+ This repository recently split GraphQL subscription template literals into per-property modules to make maintenance easier:
165
+
166
+ - Subscription templates: `src/definitions/subscriptions/*.ts` — one file per subscription property.
167
+ - Shared fragments: `src/definitions/fragments.ts` — common fragment string constants used by the subscription files.
168
+ - Compatibility surface: `src/definitions/mirrors.ts` now re-exports the assembled `Subscriptions`, `RequiredMirrors`, `TempSubscriptions`, and the fragment constants to preserve the original API.
169
+
170
+ Packaging and what is published
171
+ --------------------------------
172
+ - The npm package only ships the compiled build output. `package.json` lists `dist` and `dist-compat` in the `files` field, so the raw TypeScript source files under `src/` (including `src/definitions/subscriptions/*.ts`) are not included in the published package by default.
173
+ - The TypeScript compiler emits JavaScript (to `dist`) and declaration files (`.d.ts`) when you run the build; those compiled artifacts are what go into the package.
174
+
175
+ How to verify locally (PowerShell)
176
+ ----------------------------------
177
+ 1) Build the project:
178
+
179
+ ```powershell
180
+ npm run build
181
+ ```
182
+
183
+ 2) Inspect the compiled `dist` tree to see the compiled outputs for the subscription modules:
184
+
185
+ ```powershell
186
+ Get-ChildItem -Recurse .\dist | Select-Object FullName
187
+ ```
188
+
189
+ 3) See exactly what would be published (dry-run):
190
+
191
+ ```powershell
192
+ npm pack --dry-run
193
+ ```
194
+
195
+ If you want `.ts` sources included in the published package, add `src` to the `files` array in `package.json` or add a copy step that places sources in `dist`/`dist-compat` before publishing; then verify with `npm pack --dry-run`.
196
+
197
+ ## CI / GitHub Actions
198
+
199
+ This repository includes a workflow that publishes the package to npm when changes are pushed to `main` and when a GitHub Release is published. The workflow expects a repository secret named `NPM_TOKEN` containing a valid npm automation token.
200
+
201
+ To create and add the secret:
202
+ 1. Generate an npm token on https://www.npmjs.com/ under your account settings (Access Tokens -> Automation).
203
+ 2. In the GitHub repository, go to Settings → Secrets → Actions and add a new secret named `NPM_TOKEN` with the token value.
204
+
205
+ The workflow builds both `dist` and `dist-compat` and then runs `npm publish --access public`. If you need to restrict publishing (for example, to skip on regular pushes), adjust the workflow triggers in `.github/workflows/publish.yml`.
206
+
207
+ ## License
208
+ MIT
@@ -0,0 +1,6 @@
1
+ export declare const commonFields = "id:idStr version createdDateTime";
2
+ export declare const commonReferenceFields = "groupId groupName groupPath labels canAnonymize tokenCount";
3
+ export declare const lastLogFields = "id eventCode stamp serviceDataId userId comment";
4
+ export declare const serviceDataCommonFields = "id createdDateTime servicePlanId userId lastServiceDate lastLog {id eventCode stamp serviceDataId userId comment}";
5
+ export declare const mCommonFields = "type total deleteId deleteVersion";
6
+ export declare const mServiceCommonFields = "name description createdDate createdBy id:idStr version createdDateTime";
@@ -0,0 +1,10 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.mServiceCommonFields = exports.mCommonFields = exports.serviceDataCommonFields = exports.lastLogFields = exports.commonReferenceFields = exports.commonFields = void 0;
4
+ exports.commonFields = 'id:idStr version createdDateTime';
5
+ exports.commonReferenceFields = 'groupId groupName groupPath labels canAnonymize tokenCount';
6
+ exports.lastLogFields = 'id eventCode stamp serviceDataId userId comment';
7
+ exports.serviceDataCommonFields = `id createdDateTime servicePlanId userId lastServiceDate lastLog {${exports.lastLogFields}}`;
8
+ exports.mCommonFields = 'type total deleteId deleteVersion';
9
+ exports.mServiceCommonFields = `name description createdDate createdBy ${exports.commonFields}`;
10
+ //# sourceMappingURL=fragments.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"fragments.js","sourceRoot":"","sources":["../../src/definitions/fragments.ts"],"names":[],"mappings":";;;AAAa,QAAA,YAAY,GAAG,kCAAkC,CAAA;AACjD,QAAA,qBAAqB,GAAG,4DAA4D,CAAA;AACpF,QAAA,aAAa,GAAG,iDAAiD,CAAA;AACjE,QAAA,uBAAuB,GAAG,oEAAoE,qBAAa,GAAG,CAAA;AAC9G,QAAA,aAAa,GAAG,mCAAmC,CAAA;AACnD,QAAA,oBAAoB,GAAG,0CAA0C,oBAAY,EAAE,CAAA"}
@@ -0,0 +1,38 @@
1
+ export declare const Subscriptions: {
2
+ references: string;
3
+ trackers: string;
4
+ groups: string;
5
+ servicePlans: string;
6
+ trackerLinks: string;
7
+ referenceLinks: string;
8
+ lostTransmitters: string;
9
+ reports: string;
10
+ jobs: string;
11
+ cycles: string;
12
+ meshDiagnostics: string;
13
+ gps: string;
14
+ linkconnected: string;
15
+ connected: string;
16
+ voltage: string;
17
+ internalvoltage: string;
18
+ unplug: string;
19
+ temperature: string;
20
+ meshscanner: string;
21
+ meshdisconnectslasthour: string;
22
+ activecounter: string;
23
+ workseconds: string;
24
+ calculatedodometer: string;
25
+ batterypercent: string;
26
+ workignition: string;
27
+ tripignition: string;
28
+ activecycles: string;
29
+ activesteps: string;
30
+ referenceGeoLinks: string;
31
+ trips: string;
32
+ messages: string;
33
+ };
34
+ export declare const RequiredMirrors: {
35
+ systemSettings: string;
36
+ settings: string;
37
+ };
38
+ export declare const TempSubscriptions: {};
@@ -0,0 +1,78 @@
1
+ "use strict";
2
+ var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
3
+ if (k2 === undefined) k2 = k;
4
+ var desc = Object.getOwnPropertyDescriptor(m, k);
5
+ if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
6
+ desc = { enumerable: true, get: function() { return m[k]; } };
7
+ }
8
+ Object.defineProperty(o, k2, desc);
9
+ }) : (function(o, m, k, k2) {
10
+ if (k2 === undefined) k2 = k;
11
+ o[k2] = m[k];
12
+ }));
13
+ var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
14
+ Object.defineProperty(o, "default", { enumerable: true, value: v });
15
+ }) : function(o, v) {
16
+ o["default"] = v;
17
+ });
18
+ var __importStar = (this && this.__importStar) || (function () {
19
+ var ownKeys = function(o) {
20
+ ownKeys = Object.getOwnPropertyNames || function (o) {
21
+ var ar = [];
22
+ for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
23
+ return ar;
24
+ };
25
+ return ownKeys(o);
26
+ };
27
+ return function (mod) {
28
+ if (mod && mod.__esModule) return mod;
29
+ var result = {};
30
+ if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
31
+ __setModuleDefault(result, mod);
32
+ return result;
33
+ };
34
+ })();
35
+ Object.defineProperty(exports, "__esModule", { value: true });
36
+ exports.TempSubscriptions = exports.RequiredMirrors = exports.Subscriptions = void 0;
37
+ const subs = __importStar(require("./subscriptions"));
38
+ const req = __importStar(require("./requiredMirrors/index"));
39
+ const temp = __importStar(require("./tempSubscriptions/index"));
40
+ exports.Subscriptions = {
41
+ references: subs.references,
42
+ trackers: subs.trackers,
43
+ groups: subs.groups,
44
+ servicePlans: subs.servicePlans,
45
+ trackerLinks: subs.trackerLinks,
46
+ referenceLinks: subs.referenceLinks,
47
+ lostTransmitters: subs.lostTransmitters,
48
+ reports: subs.reports,
49
+ jobs: subs.jobs,
50
+ cycles: subs.cycles,
51
+ meshDiagnostics: subs.meshDiagnostics,
52
+ gps: subs.gps,
53
+ linkconnected: subs.linkconnected,
54
+ connected: subs.connected,
55
+ voltage: subs.voltage,
56
+ internalvoltage: subs.internalvoltage,
57
+ unplug: subs.unplug,
58
+ temperature: subs.temperature,
59
+ meshscanner: subs.meshscanner,
60
+ meshdisconnectslasthour: subs.meshdisconnectslasthour,
61
+ activecounter: subs.activecounter,
62
+ workseconds: subs.workseconds,
63
+ calculatedodometer: subs.calculatedodometer,
64
+ batterypercent: subs.batterypercent,
65
+ workignition: subs.workignition,
66
+ tripignition: subs.tripignition,
67
+ activecycles: subs.activecycles,
68
+ activesteps: subs.activesteps,
69
+ referenceGeoLinks: subs.referenceGeoLinks,
70
+ trips: subs.trips,
71
+ messages: subs.messages
72
+ };
73
+ exports.RequiredMirrors = {
74
+ systemSettings: req.systemSettings,
75
+ settings: req.settings
76
+ };
77
+ exports.TempSubscriptions = temp.TempSubscriptions;
78
+ //# sourceMappingURL=mirrors.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"mirrors.js","sourceRoot":"","sources":["../../src/definitions/mirrors.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,sDAAuC;AACvC,6DAA8C;AAC9C,gEAAiD;AAEpC,QAAA,aAAa,GAAG;IAC3B,UAAU,EAAE,IAAI,CAAC,UAAU;IAC3B,QAAQ,EAAE,IAAI,CAAC,QAAQ;IACvB,MAAM,EAAE,IAAI,CAAC,MAAM;IACnB,YAAY,EAAE,IAAI,CAAC,YAAY;IAC/B,YAAY,EAAE,IAAI,CAAC,YAAY;IAC/B,cAAc,EAAE,IAAI,CAAC,cAAc;IACnC,gBAAgB,EAAE,IAAI,CAAC,gBAAgB;IACvC,OAAO,EAAE,IAAI,CAAC,OAAO;IACrB,IAAI,EAAE,IAAI,CAAC,IAAI;IACf,MAAM,EAAE,IAAI,CAAC,MAAM;IACnB,eAAe,EAAE,IAAI,CAAC,eAAe;IACrC,GAAG,EAAE,IAAI,CAAC,GAAG;IACb,aAAa,EAAE,IAAI,CAAC,aAAa;IACjC,SAAS,EAAE,IAAI,CAAC,SAAS;IACzB,OAAO,EAAE,IAAI,CAAC,OAAO;IACrB,eAAe,EAAE,IAAI,CAAC,eAAe;IACrC,MAAM,EAAE,IAAI,CAAC,MAAM;IACnB,WAAW,EAAE,IAAI,CAAC,WAAW;IAC7B,WAAW,EAAE,IAAI,CAAC,WAAW;IAC7B,uBAAuB,EAAE,IAAI,CAAC,uBAAuB;IACrD,aAAa,EAAE,IAAI,CAAC,aAAa;IACjC,WAAW,EAAE,IAAI,CAAC,WAAW;IAC7B,kBAAkB,EAAE,IAAI,CAAC,kBAAkB;IAC3C,cAAc,EAAE,IAAI,CAAC,cAAc;IACnC,YAAY,EAAE,IAAI,CAAC,YAAY;IAC/B,YAAY,EAAE,IAAI,CAAC,YAAY;IAC/B,YAAY,EAAE,IAAI,CAAC,YAAY;IAC/B,WAAW,EAAE,IAAI,CAAC,WAAW;IAC7B,iBAAiB,EAAE,IAAI,CAAC,iBAAiB;IACzC,KAAK,EAAE,IAAI,CAAC,KAAK;IACjB,QAAQ,EAAE,IAAI,CAAC,QAAQ;CACxB,CAAA;AAEY,QAAA,eAAe,GAAG;IAC7B,cAAc,EAAE,GAAG,CAAC,cAAc;IAClC,QAAQ,EAAE,GAAG,CAAC,QAAQ;CACvB,CAAA;AAEY,QAAA,iBAAiB,GAAG,IAAI,CAAC,iBAAiB,CAAA"}
@@ -0,0 +1,2 @@
1
+ export * from './systemSettings';
2
+ export * from './settings';
@@ -0,0 +1,19 @@
1
+ "use strict";
2
+ var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
3
+ if (k2 === undefined) k2 = k;
4
+ var desc = Object.getOwnPropertyDescriptor(m, k);
5
+ if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
6
+ desc = { enumerable: true, get: function() { return m[k]; } };
7
+ }
8
+ Object.defineProperty(o, k2, desc);
9
+ }) : (function(o, m, k, k2) {
10
+ if (k2 === undefined) k2 = k;
11
+ o[k2] = m[k];
12
+ }));
13
+ var __exportStar = (this && this.__exportStar) || function(m, exports) {
14
+ for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
15
+ };
16
+ Object.defineProperty(exports, "__esModule", { value: true });
17
+ __exportStar(require("./systemSettings"), exports);
18
+ __exportStar(require("./settings"), exports);
19
+ //# sourceMappingURL=index.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/definitions/requiredMirrors/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,mDAAgC;AAChC,6CAA0B"}
@@ -0,0 +1 @@
1
+ export declare const settings = "\n subscription settings($version: Int!){\n mcommon_settings(version: $version, subscribe: true) {\n type\n total\n deleteId\n data {\n id: groupId\n version\n groupName\n settings {\n id\n name\n level\n parent\n valueOrigin\n value {\n isVisible\n hasChildren\n settingValue\n type\n }\n inputHtml\n } \n }\n deleteVersion\n }\n }";
@@ -0,0 +1,32 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.settings = void 0;
4
+ exports.settings = `
5
+ subscription settings($version: Int!){
6
+ mcommon_settings(version: $version, subscribe: true) {
7
+ type
8
+ total
9
+ deleteId
10
+ data {
11
+ id: groupId
12
+ version
13
+ groupName
14
+ settings {
15
+ id
16
+ name
17
+ level
18
+ parent
19
+ valueOrigin
20
+ value {
21
+ isVisible
22
+ hasChildren
23
+ settingValue
24
+ type
25
+ }
26
+ inputHtml
27
+ }
28
+ }
29
+ deleteVersion
30
+ }
31
+ }`;
32
+ //# sourceMappingURL=settings.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"settings.js","sourceRoot":"","sources":["../../../src/definitions/requiredMirrors/settings.ts"],"names":[],"mappings":";;;AAAa,QAAA,QAAQ,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;IA2BpB,CAAA"}
@@ -0,0 +1 @@
1
+ export declare const systemSettings = "subscription systemsetting($version: Int!) {\n mcommon_systemsettings(version: $version, subscribe: true) {\n type\n total\n deleteId\n data {\n version\n id: groupName\n settings {\n id\n name\n level\n parent\n valueOrigin\n value {\n isVisible\n hasChildren\n settingValue\n type\n }\n inputHtml\n } \n }\n deleteVersion\n }\n }";