chore: Scaffold @launchdarkly/eventsource with transport-independent core modules

.github/workflows/eventsource.yml

@@ -0,0 +1,27 @@
+name: shared/eventsource
+
+on:
+  push:
+    branches: [main, 'feat/**']
+    paths-ignore:
+      - '**.md' #Do not need to run CI for markdown changes.
+  pull_request:
+    branches: [main, 'feat/**']
+    paths-ignore:
+      - '**.md'
+
+jobs:
+  build-test-eventsource:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: ./actions/setup-yarn
+        with:
+          node-version: 24.x
+          registry-url: 'https://registry.npmjs.org'
+      - id: shared
+        name: Shared CI Steps
+        uses: ./actions/ci
+        with:
+          workspace_name: '@launchdarkly/eventsource'
+          workspace_path: packages/shared/eventsource

package.json

@@ -10,6 +10,7 @@
     "packages/shared/sdk-server-edge",
     "packages/shared/akamai-edgeworker-sdk",
     "packages/shared/openfeature-server-common",
+    "packages/shared/eventsource",
     "packages/sdk/server-node",
     "packages/sdk/server-node/contract-tests",
     "packages/sdk/server-node/examples/features/custom-socks-proxy",

packages/shared/eventsource/CHANGELOG.md

@@ -0,0 +1,4 @@
+# Changelog
+
+All notable changes to `@launchdarkly/eventsource` will be documented in this file. This
+project adheres to [Semantic Versioning](http://semver.org).

packages/shared/eventsource/LICENSE

@@ -0,0 +1,70 @@
+Copyright 2026 Catamorphic, Co.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+-------------------------------------------------------------------------------
+
+Third-party notices
+
+Portions of this package are derived from the "eventsource" npm package,
+used under the following license:
+
+The MIT License
+
+Copyright (c) EventSource GitHub organisation
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+-------------------------------------------------------------------------------
+
+Portions of this package (the stream parser at src/parser) are derived from
+the "eventsource-parser" npm package, used under the following license:
+
+MIT License
+
+Copyright (c) 2026 Espen Hovlandsdal <espen@hovlandsdal.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

packages/shared/eventsource/__tests__/capacity.test.ts

@@ -0,0 +1,35 @@
+import calculateCapacity from '../src/capacity';
+
+const maxOverAllocation = 1024 * 1024;
+
+it('uses the minimum capacity', () => {
+  const [resize, newCapacity] = calculateCapacity(0, 1, maxOverAllocation);
+  expect(resize).toBe(true);
+  // The minimum is a fixed design constant. It must not track the host's Buffer.poolSize,
+  // which changed between Node versions and does not exist in a browser.
+  expect(newCapacity).toEqual(8192);
+});
+
+it('does not increase capacity when there is sufficient capacity', () => {
+  const [resize, newCapacity] = calculateCapacity(1024, 1023, maxOverAllocation);
+  expect(resize).toBe(false);
+  expect(newCapacity).toEqual(0);
+});
+
+it('uses exponential doubling capacity scaling', () => {
+  expect(calculateCapacity(8192, 8193, maxOverAllocation)).toEqual([true, 16384]);
+  expect(calculateCapacity(16384, 16385, maxOverAllocation)).toEqual([true, 32768]);
+});
+
+it('uses required capacity when it exceeds doubling', () => {
+  const [resize, newCapacity] = calculateCapacity(1024, 16384, maxOverAllocation);
+  expect(resize).toBe(true);
+  expect(newCapacity).toEqual(16384);
+});
+
+it('does not exceed max over allocation', () => {
+  const capacity = 1024 * 1024 * 3;
+  const [resize, newCapacity] = calculateCapacity(capacity, capacity + 1, maxOverAllocation);
+  expect(resize).toBe(true);
+  expect(newCapacity).toEqual(capacity + maxOverAllocation + 1);
+});

packages/shared/eventsource/__tests__/listenerRegistry.test.ts

@@ -0,0 +1,80 @@
+import { createDefaultEventRegistry } from '../src/listenerRegistry';
+
+it('dispatches an event to each listener registered for its type', () => {
+  const registry = createDefaultEventRegistry();
+  const received: unknown[] = [];
+  registry.addEventListener('greeting', (e) => received.push(e));
+  registry.addEventListener('greeting', (e) => received.push(e));
+  const event = { type: 'greeting', data: 'hello' };
+  registry.dispatch('greeting', event);
+  expect(received).toEqual([event, event]);
+});
+
+it('does not dispatch to listeners registered for another type', () => {
+  const registry = createDefaultEventRegistry();
+  const received: unknown[] = [];
+  registry.addEventListener('other', (e) => received.push(e));
+  registry.dispatch('greeting', { type: 'greeting' });
+  expect(received).toEqual([]);
+});
+
+it('does nothing when dispatching a type with no listeners', () => {
+  const registry = createDefaultEventRegistry();
+  expect(() => registry.dispatch('greeting', { type: 'greeting' })).not.toThrow();
+});
+
+it('removes a registered listener', () => {
+  const registry = createDefaultEventRegistry();
+  const received: unknown[] = [];
+  const listener = (e: unknown) => received.push(e);
+  registry.addEventListener('greeting', listener);
+  registry.removeEventListener('greeting', listener);
+  registry.dispatch('greeting', { type: 'greeting' });
+  expect(received).toEqual([]);
+});
+
+it('removes at most one registration of a listener that registered twice', () => {
+  const registry = createDefaultEventRegistry();
+  let count = 0;
+  const listener = () => {
+    count += 1;
+  };
+  registry.addEventListener('greeting', listener);
+  registry.addEventListener('greeting', listener);
+  registry.removeEventListener('greeting', listener);
+  registry.dispatch('greeting', {});
+  expect(count).toEqual(1);
+});
+
+it('does nothing when removing a listener that never registered', () => {
+  const registry = createDefaultEventRegistry();
+  expect(() => registry.removeEventListener('greeting', () => {})).not.toThrow();
+});
+
+it('dispatches to a snapshot of the listener list', () => {
+  const registry = createDefaultEventRegistry();
+  const calls: string[] = [];
+  const second = () => calls.push('second');
+  registry.addEventListener('greeting', () => {
+    calls.push('first');
+    // Removed during this dispatch: still runs for this dispatch.
+    registry.removeEventListener('greeting', second);
+    // Added during this dispatch: does not run until the next dispatch.
+    registry.addEventListener('greeting', () => calls.push('third'));
+  });
+  registry.addEventListener('greeting', second);
+  registry.dispatch('greeting', {});
+  expect(calls).toEqual(['first', 'second']);
+});
+
+it('treats prototype-chain names as ordinary event types', () => {
+  const registry = createDefaultEventRegistry();
+  // The server controls event type names through the SSE `event:` field, so names that collide
+  // with Object.prototype members must behave like any other type.
+  expect(() => registry.dispatch('__proto__', {})).not.toThrow();
+  expect(() => registry.dispatch('constructor', {})).not.toThrow();
+  const received: unknown[] = [];
+  registry.addEventListener('__proto__', (e) => received.push(e));
+  registry.dispatch('__proto__', { type: '__proto__' });
+  expect(received).toEqual([{ type: '__proto__' }]);
+});