@atcute/jetstream 1.0.1 → 1.1.0

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 CHANGED
@@ -1,17 +1,14 @@
1
- Permission is hereby granted, free of charge, to any person obtaining a copy
2
- of this software and associated documentation files (the "Software"), to deal
3
- in the Software without restriction, including without limitation the rights
4
- to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
5
- copies of the Software, and to permit persons to whom the Software is
6
- furnished to do so, subject to the following conditions:
1
+ BSD Zero Clause License
7
2
 
8
- The above copyright notice and this permission notice shall be included in all
9
- copies or substantial portions of the Software.
3
+ Copyright (c) 2025 Mary
10
4
 
11
- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
12
- IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
13
- FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
14
- AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
15
- LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
16
- OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
17
- SOFTWARE.
5
+ Permission to use, copy, modify, and/or distribute this software for any
6
+ purpose with or without fee is hereby granted.
7
+
8
+ THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
9
+ REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
10
+ AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
11
+ INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
12
+ LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
13
+ OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
14
+ PERFORMANCE OF THIS SOFTWARE.
@@ -3,20 +3,20 @@ import { EventIterator } from '@mary-ext/event-iterator';
3
3
  import type { CloseEvent, ErrorEvent, Options } from 'partysocket/ws';
4
4
  import type { ReadonlyDeep } from 'type-fest';
5
5
  export interface JetstreamSubscriptionOptions {
6
- url: string;
6
+ url: string | string[];
7
7
  cursor?: number;
8
8
  /**
9
- * Array of collection NSIDs that you're interested in receiving commit events
9
+ * array of collection NSIDs that you're interested in receiving commit events
10
10
  * for, pass in an empty array for no commit events.
11
11
  */
12
12
  wantedCollections?: string[];
13
13
  /**
14
- * Array of account DIDs that you're interested in receiving commit events
14
+ * array of account DIDs that you're interested in receiving commit events
15
15
  * for, pass in an empty array for no commit events.
16
16
  */
17
17
  wantedDids?: Did[];
18
18
  /**
19
- * Whether to validate Jetstream's events, you'd still need to validate the records.
19
+ * whether to validate Jetstream's events, you'd still need to validate the records.
20
20
  * @default true
21
21
  */
22
22
  validateEvents?: boolean;
@@ -9,9 +9,14 @@ export class JetstreamSubscription {
9
9
  #emitter = new SimpleEventEmitter();
10
10
  #options;
11
11
  #cursor;
12
+ #lastUsedUrl;
12
13
  constructor(options) {
13
14
  this.#options = options;
14
15
  this.#cursor = options.cursor ?? Date.now() * 1_000;
16
+ // initialize to empty string for URL arrays to trigger cursor rollback on
17
+ // first connection since we don't know which instance the cursor came
18
+ // from in a previous session
19
+ this.#lastUsedUrl = Array.isArray(options.url) ? '' : undefined;
15
20
  }
16
21
  #sendOptionsUpdate() {
17
22
  const ws = this.#ws;
@@ -31,12 +36,25 @@ export class JetstreamSubscription {
31
36
  if (this.#ws !== undefined) {
32
37
  return;
33
38
  }
34
- const { url: wsUrl, ws: wsOptions, validateEvents = true, onConnectionClose, onConnectionError, onConnectionOpen, } = this.#options;
39
+ const { url: wsUrls, ws: wsOptions, validateEvents = true, onConnectionClose, onConnectionError, onConnectionOpen, } = this.#options;
35
40
  const emitter = this.#emitter;
41
+ let selectedUrl;
36
42
  const getUrl = () => {
37
- const url = new URL('/subscribe', wsUrl);
43
+ if (typeof wsUrls === 'string') {
44
+ selectedUrl = wsUrls;
45
+ }
46
+ else {
47
+ selectedUrl = wsUrls[Math.floor(Math.random() * wsUrls.length)];
48
+ }
49
+ let cursor = this.#cursor;
50
+ if (this.#lastUsedUrl !== undefined && this.#lastUsedUrl !== selectedUrl) {
51
+ // rollback cursor by 10 seconds when switching to a different instance
52
+ // to ensure we don't miss any events due to clock differences
53
+ cursor = Math.max(0, cursor - 10_000_000);
54
+ }
55
+ const url = new URL('/subscribe', selectedUrl);
38
56
  url.searchParams.set('requireHello', 'true');
39
- url.searchParams.set('cursor', '' + this.#cursor);
57
+ url.searchParams.set('cursor', '' + cursor);
40
58
  return url.toString();
41
59
  };
42
60
  const ws = new ReconnectingWebSocket(getUrl, null, wsOptions);
@@ -61,7 +79,12 @@ export class JetstreamSubscription {
61
79
  else {
62
80
  event = raw;
63
81
  }
64
- this.#cursor = event.time_us;
82
+ if (event.time_us > this.#cursor) {
83
+ this.#cursor = event.time_us;
84
+ // set `lastUsedUrl` now that we've passed the stored cursor.
85
+ // ensures we cursor rollback still happens during a reconnection.
86
+ this.#lastUsedUrl = selectedUrl;
87
+ }
65
88
  emitter.emit(event);
66
89
  };
67
90
  }
@@ -1 +1 @@
1
- {"version":3,"file":"subscription.js","sourceRoot":"","sources":["../lib/subscription.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"subscription.js","sourceRoot":"","sources":["../lib/subscription.ts"],"names":[],"mappings":"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"}
@@ -11,23 +11,23 @@ import type { ReadonlyDeep } from 'type-fest';
11
11
  import { jetstreamEventSchema, type JetstreamEvent, type JetstreamProcedure } from './types.js';
12
12
 
13
13
  export interface JetstreamSubscriptionOptions {
14
- url: string;
14
+ url: string | string[];
15
15
 
16
16
  cursor?: number;
17
17
 
18
18
  /**
19
- * Array of collection NSIDs that you're interested in receiving commit events
19
+ * array of collection NSIDs that you're interested in receiving commit events
20
20
  * for, pass in an empty array for no commit events.
21
21
  */
22
22
  wantedCollections?: string[];
23
23
  /**
24
- * Array of account DIDs that you're interested in receiving commit events
24
+ * array of account DIDs that you're interested in receiving commit events
25
25
  * for, pass in an empty array for no commit events.
26
26
  */
27
27
  wantedDids?: Did[];
28
28
 
29
29
  /**
30
- * Whether to validate Jetstream's events, you'd still need to validate the records.
30
+ * whether to validate Jetstream's events, you'd still need to validate the records.
31
31
  * @default true
32
32
  */
33
33
  validateEvents?: boolean;
@@ -52,10 +52,16 @@ export class JetstreamSubscription {
52
52
 
53
53
  #options: JetstreamSubscriptionOptions;
54
54
  #cursor: number;
55
+ #lastUsedUrl?: string;
55
56
 
56
57
  constructor(options: JetstreamSubscriptionOptions) {
57
58
  this.#options = options;
58
59
  this.#cursor = options.cursor ?? Date.now() * 1_000;
60
+
61
+ // initialize to empty string for URL arrays to trigger cursor rollback on
62
+ // first connection since we don't know which instance the cursor came
63
+ // from in a previous session
64
+ this.#lastUsedUrl = Array.isArray(options.url) ? '' : undefined;
59
65
  }
60
66
 
61
67
  #sendOptionsUpdate() {
@@ -81,7 +87,7 @@ export class JetstreamSubscription {
81
87
  }
82
88
 
83
89
  const {
84
- url: wsUrl,
90
+ url: wsUrls,
85
91
  ws: wsOptions,
86
92
  validateEvents = true,
87
93
  onConnectionClose,
@@ -90,10 +96,25 @@ export class JetstreamSubscription {
90
96
  } = this.#options;
91
97
  const emitter = this.#emitter;
92
98
 
99
+ let selectedUrl: string;
100
+
93
101
  const getUrl = () => {
94
- const url = new URL('/subscribe', wsUrl);
102
+ if (typeof wsUrls === 'string') {
103
+ selectedUrl = wsUrls;
104
+ } else {
105
+ selectedUrl = wsUrls[Math.floor(Math.random() * wsUrls.length)];
106
+ }
107
+
108
+ let cursor = this.#cursor;
109
+ if (this.#lastUsedUrl !== undefined && this.#lastUsedUrl !== selectedUrl) {
110
+ // rollback cursor by 10 seconds when switching to a different instance
111
+ // to ensure we don't miss any events due to clock differences
112
+ cursor = Math.max(0, cursor - 10_000_000);
113
+ }
114
+
115
+ const url = new URL('/subscribe', selectedUrl);
95
116
  url.searchParams.set('requireHello', 'true');
96
- url.searchParams.set('cursor', '' + this.#cursor);
117
+ url.searchParams.set('cursor', '' + cursor);
97
118
 
98
119
  return url.toString();
99
120
  };
@@ -126,7 +147,14 @@ export class JetstreamSubscription {
126
147
  event = raw;
127
148
  }
128
149
 
129
- this.#cursor = event.time_us;
150
+ if (event.time_us > this.#cursor) {
151
+ this.#cursor = event.time_us;
152
+
153
+ // set `lastUsedUrl` now that we've passed the stored cursor.
154
+ // ensures we cursor rollback still happens during a reconnection.
155
+ this.#lastUsedUrl = selectedUrl;
156
+ }
157
+
130
158
  emitter.emit(event);
131
159
  };
132
160
  }
package/package.json CHANGED
@@ -1,9 +1,9 @@
1
1
  {
2
2
  "type": "module",
3
3
  "name": "@atcute/jetstream",
4
- "version": "1.0.1",
4
+ "version": "1.1.0",
5
5
  "description": "lightweight and cute Jetstream subscriber for AT Protocol",
6
- "license": "MIT",
6
+ "license": "0BSD",
7
7
  "repository": {
8
8
  "url": "https://github.com/mary-ext/atcute",
9
9
  "directory": "packages/clients/jetstream"
@@ -18,17 +18,17 @@
18
18
  ".": "./dist/index.js"
19
19
  },
20
20
  "dependencies": {
21
- "@badrap/valita": "^0.4.2",
21
+ "@badrap/valita": "^0.4.6",
22
22
  "@mary-ext/event-iterator": "^1.0.0",
23
23
  "@mary-ext/simple-event-emitter": "^1.0.0",
24
- "partysocket": "^1.1.4",
24
+ "partysocket": "^1.1.5",
25
25
  "type-fest": "^4.41.0",
26
26
  "yocto-queue": "^1.2.1",
27
- "@atcute/lexicons": "^1.0.1"
27
+ "@atcute/lexicons": "^1.1.1"
28
28
  },
29
29
  "devDependencies": {
30
- "@vitest/coverage-v8": "^3.0.4",
31
- "vitest": "^3.0.4"
30
+ "@vitest/coverage-v8": "^3.2.4",
31
+ "vitest": "^3.2.4"
32
32
  },
33
33
  "scripts": {
34
34
  "build": "tsc --project tsconfig.build.json",