@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.
- package/LICENSE +21 -21
- package/README.md +208 -150
- package/dist/definitions/fragments.d.ts +6 -0
- package/dist/definitions/fragments.js +10 -0
- package/dist/definitions/fragments.js.map +1 -0
- package/dist/definitions/mirrors.d.ts +38 -0
- package/dist/definitions/mirrors.js +78 -0
- package/dist/definitions/mirrors.js.map +1 -0
- package/dist/definitions/requiredMirrors/index.d.ts +2 -0
- package/dist/definitions/requiredMirrors/index.js +19 -0
- package/dist/definitions/requiredMirrors/index.js.map +1 -0
- package/dist/definitions/requiredMirrors/settings.d.ts +1 -0
- package/dist/definitions/requiredMirrors/settings.js +32 -0
- package/dist/definitions/requiredMirrors/settings.js.map +1 -0
- package/dist/definitions/requiredMirrors/systemSettings.d.ts +1 -0
- package/dist/definitions/requiredMirrors/systemSettings.js +30 -0
- package/dist/definitions/requiredMirrors/systemSettings.js.map +1 -0
- package/dist/definitions/subscriptions/activecounter.d.ts +1 -0
- package/dist/definitions/subscriptions/activecounter.js +18 -0
- package/dist/definitions/subscriptions/activecounter.js.map +1 -0
- package/dist/definitions/subscriptions/activecycles.d.ts +1 -0
- package/dist/definitions/subscriptions/activecycles.js +25 -0
- package/dist/definitions/subscriptions/activecycles.js.map +1 -0
- package/dist/definitions/subscriptions/activesteps.d.ts +1 -0
- package/dist/definitions/subscriptions/activesteps.js +29 -0
- package/dist/definitions/subscriptions/activesteps.js.map +1 -0
- package/dist/definitions/subscriptions/batterypercent.d.ts +1 -0
- package/dist/definitions/subscriptions/batterypercent.js +18 -0
- package/dist/definitions/subscriptions/batterypercent.js.map +1 -0
- package/dist/definitions/subscriptions/calculatedodometer.d.ts +1 -0
- package/dist/definitions/subscriptions/calculatedodometer.js +18 -0
- package/dist/definitions/subscriptions/calculatedodometer.js.map +1 -0
- package/dist/definitions/subscriptions/connected.d.ts +1 -0
- package/dist/definitions/subscriptions/connected.js +17 -0
- package/dist/definitions/subscriptions/connected.js.map +1 -0
- package/dist/definitions/subscriptions/cycles.d.ts +1 -0
- package/dist/definitions/subscriptions/cycles.js +81 -0
- package/dist/definitions/subscriptions/cycles.js.map +1 -0
- package/dist/definitions/subscriptions/gps.d.ts +1 -0
- package/dist/definitions/subscriptions/gps.js +36 -0
- package/dist/definitions/subscriptions/gps.js.map +1 -0
- package/dist/definitions/subscriptions/groups.d.ts +1 -0
- package/dist/definitions/subscriptions/groups.js +21 -0
- package/dist/definitions/subscriptions/groups.js.map +1 -0
- package/dist/definitions/subscriptions/index.d.ts +31 -0
- package/dist/definitions/subscriptions/index.js +48 -0
- package/dist/definitions/subscriptions/index.js.map +1 -0
- package/dist/definitions/subscriptions/internalvoltage.d.ts +1 -0
- package/dist/definitions/subscriptions/internalvoltage.js +19 -0
- package/dist/definitions/subscriptions/internalvoltage.js.map +1 -0
- package/dist/definitions/subscriptions/jobs.d.ts +1 -0
- package/dist/definitions/subscriptions/jobs.js +68 -0
- package/dist/definitions/subscriptions/jobs.js.map +1 -0
- package/dist/definitions/subscriptions/linkconnected.d.ts +1 -0
- package/dist/definitions/subscriptions/linkconnected.js +17 -0
- package/dist/definitions/subscriptions/linkconnected.js.map +1 -0
- package/dist/definitions/subscriptions/lostTransmitters.d.ts +1 -0
- package/dist/definitions/subscriptions/lostTransmitters.js +40 -0
- package/dist/definitions/subscriptions/lostTransmitters.js.map +1 -0
- package/dist/definitions/subscriptions/meshDiagnostics.d.ts +1 -0
- package/dist/definitions/subscriptions/meshDiagnostics.js +34 -0
- package/dist/definitions/subscriptions/meshDiagnostics.js.map +1 -0
- package/dist/definitions/subscriptions/meshdisconnectslasthour.d.ts +1 -0
- package/dist/definitions/subscriptions/meshdisconnectslasthour.js +18 -0
- package/dist/definitions/subscriptions/meshdisconnectslasthour.js.map +1 -0
- package/dist/definitions/subscriptions/meshscanner.d.ts +1 -0
- package/dist/definitions/subscriptions/meshscanner.js +18 -0
- package/dist/definitions/subscriptions/meshscanner.js.map +1 -0
- package/dist/definitions/subscriptions/messages.d.ts +1 -0
- package/dist/definitions/subscriptions/messages.js +32 -0
- package/dist/definitions/subscriptions/messages.js.map +1 -0
- package/dist/definitions/subscriptions/referenceGeoLinks.d.ts +1 -0
- package/dist/definitions/subscriptions/referenceGeoLinks.js +23 -0
- package/dist/definitions/subscriptions/referenceGeoLinks.js.map +1 -0
- package/dist/definitions/subscriptions/referenceLinks.d.ts +1 -0
- package/dist/definitions/subscriptions/referenceLinks.js +24 -0
- package/dist/definitions/subscriptions/referenceLinks.js.map +1 -0
- package/dist/definitions/subscriptions/references.d.ts +1 -0
- package/dist/definitions/subscriptions/references.js +111 -0
- package/dist/definitions/subscriptions/references.js.map +1 -0
- package/dist/definitions/subscriptions/reports.d.ts +1 -0
- package/dist/definitions/subscriptions/reports.js +20 -0
- package/dist/definitions/subscriptions/reports.js.map +1 -0
- package/dist/definitions/subscriptions/servicePlans.d.ts +1 -0
- package/dist/definitions/subscriptions/servicePlans.js +47 -0
- package/dist/definitions/subscriptions/servicePlans.js.map +1 -0
- package/dist/definitions/subscriptions/temperature.d.ts +1 -0
- package/dist/definitions/subscriptions/temperature.js +18 -0
- package/dist/definitions/subscriptions/temperature.js.map +1 -0
- package/dist/definitions/subscriptions/trackerLinks.d.ts +1 -0
- package/dist/definitions/subscriptions/trackerLinks.js +23 -0
- package/dist/definitions/subscriptions/trackerLinks.js.map +1 -0
- package/dist/definitions/subscriptions/trackers.d.ts +1 -0
- package/dist/definitions/subscriptions/trackers.js +26 -0
- package/dist/definitions/subscriptions/trackers.js.map +1 -0
- package/dist/definitions/subscriptions/tripignition.d.ts +1 -0
- package/dist/definitions/subscriptions/tripignition.js +19 -0
- package/dist/definitions/subscriptions/tripignition.js.map +1 -0
- package/dist/definitions/subscriptions/trips.d.ts +1 -0
- package/dist/definitions/subscriptions/trips.js +41 -0
- package/dist/definitions/subscriptions/trips.js.map +1 -0
- package/dist/definitions/subscriptions/unplug.d.ts +1 -0
- package/dist/definitions/subscriptions/unplug.js +19 -0
- package/dist/definitions/subscriptions/unplug.js.map +1 -0
- package/dist/definitions/subscriptions/voltage.d.ts +1 -0
- package/dist/definitions/subscriptions/voltage.js +19 -0
- package/dist/definitions/subscriptions/voltage.js.map +1 -0
- package/dist/definitions/subscriptions/workignition.d.ts +1 -0
- package/dist/definitions/subscriptions/workignition.js +19 -0
- package/dist/definitions/subscriptions/workignition.js.map +1 -0
- package/dist/definitions/subscriptions/workseconds.d.ts +1 -0
- package/dist/definitions/subscriptions/workseconds.js +18 -0
- package/dist/definitions/subscriptions/workseconds.js.map +1 -0
- package/dist/definitions/tempSubscriptions/index.d.ts +1 -0
- package/dist/definitions/tempSubscriptions/index.js +5 -0
- package/dist/definitions/tempSubscriptions/index.js.map +1 -0
- package/dist/index.d.ts +2 -0
- package/dist/index.js +16 -1
- package/dist/index.js.map +1 -1
- package/dist-compat/index.js +985 -3
- package/dist-compat/index.js.map +1 -1
- 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
|
-
###
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
*
|
|
118
|
-
*
|
|
119
|
-
*
|
|
120
|
-
*
|
|
121
|
-
*
|
|
122
|
-
* error
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
*
|
|
128
|
-
*
|
|
129
|
-
*
|
|
130
|
-
*
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
*
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
*
|
|
137
|
-
*
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
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,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 }";
|