refactor: update forwarder module to TS by jaissica12 · Pull Request #1260 · mParticle/mparticle-web-sdk

jaissica12 · 2026-05-12T21:41:32Z

Background

Continuing the effort to migrate remaining JavaScript modules to TypeScript for improved type safety and developer experience across the SDK codebase.

What Has Changed

Converted src/forwarders.js to src/forwarders.ts with full type annotations on all methods, parameters, and return types
Updated src/forwarders.interfaces.ts with corrected and expanded interface definitions to support the conversion
Updated src/sdkRuntimeModels.ts with type adjustments needed for forwarder-related models
Updated src/store.ts with type refinements required by the forwarder module

Screenshots/Video

Checklist

I have performed a self-review of my own code.
I have made corresponding changes to the documentation.
I have added tests that prove my fix is effective or that my feature works.
I have tested this locally.

Additional Notes

Reference Issue (For employees only. Ignore if you are an outside contributor)

Closes https://go/j/SDKE-1109

cursor · 2026-05-21T02:45:20Z

PR Summary

Medium Risk
Touches core kit forwarding, filtering, and batch paths; risk is mainly compile-time/cast regressions rather than intentional logic changes.

Overview
Migrates the kit forwarder implementation from JavaScript to TypeScript: forwarders.js becomes forwarders.ts with typed constructor (this: IForwarders), instance dependencies (IMParticleWebSDKInstance, KitBlocker), and annotations on event/batch forwarding, kit configuration (UI-enabled, sideloaded, pixels), and forwarding-stats upload.

forwarders.interfaces.ts gains a full IForwarders contract plus supporting types (SideloadedKit, expanded imports). ConfiguredKit now documents optional processBatch, initialized, and logger. sdkRuntimeModels adds optional filterUserIdentities on SDKHelpersApi to align helpers typing with forwarder usage.

Implementation detail: several internal calls use (method as Function)(...) and as unknown as ConfiguredKit[] so the legacy constructor pattern type-checks; sendBatchToForwarders switches from for...of to an indexed loop (same behavior).

^{Reviewed by Cursor Bugbot for commit e820005. Bugbot is set up for automated code reviews on this repo. Configure here.}

alexs-mparticle · 2026-05-21T13:28:30Z

+import { Batch } from '@mparticle/event-models';
+import { IMParticleUser, ISDKUserIdentity } from './identity-user-interfaces';
+import KitBlocker from './kitBlocking';
+import { Dictionary } from './utils';


Clean up these imports

alexs-mparticle · 2026-05-21T13:29:30Z

                    }
                    if (
-                        !self.isEnabledForUserAttributes(
+                        !(this.isEnabledForUserAttributes as Function)(


Why do we need as Function?

The method is defined later in the constructor body but called here, TS can't verify it exists at this point. Cast has no runtime effect, it's a TS workaround for the constructor-function pattern.

alexs-mparticle · 2026-05-21T13:30:39Z


                // Check user attribute filtering rules
-                clonedEvent.UserAttributes = KitFilterHelper.filterUserAttributes(
+                clonedEvent.UserAttributes = (KitFilterHelper.filterUserAttributes as Function)(


Same here. This feels like we're trying to bypass type safety.

Type mismatch: UserAttributes is string | string[] | null values, but filterUserAttributes expects string only. Cast avoids the TS error, I thought fixing the signature in KitFilterHelper is out of scope for this migration.

alexs-mparticle · 2026-05-21T13:35:27Z

        }

-        for (const forwarder of mpInstance._Store.activeForwarders) {
+        for (


Is there a reason we needed to change this to a standard for loop?

Reverted to the original for...of loop.

alexs-mparticle · 2026-05-21T13:36:36Z


                if (result) {
-                    mpInstance.Logger.verbose(result);
+                    mpInstance.Logger.verbose(result as string);


Isn't this already a string?

Good catch, forwarder.process() and forwarder.processBatch() already return string per the interface, so as string is unnecessary there. Removed it from processBatch.

alexs-mparticle · 2026-05-21T13:37:47Z

    // sideloaded kits, this will need to be refactored.
-    this.processSideloadedKits = function(mpConfig) {
+    this.processSideloadedKits = function(
+        mpConfig: IConfigResponse & { sideloadedKits?: { kitInstance: { register: Function; name: string }; filterDictionary: IKitFilterSettings }[] }


If we don't have a type for this, let's make one.

Created a SideloadedKit interface in forwarders.interfaces.ts that reuses the existing UnregisteredKit type. Replaced the inline type.

alexs-mparticle · 2026-05-21T13:39:32Z

    endSession(): void;
    init(apiKey: string, config: SDKInitConfig, instanceName?: string): void;
-    _getActiveForwarders(): ConfiguredKit[];
+    _getActiveForwarders(): MPForwarder[];


Let's be careful with this because MPForwarder and ConfiguredKit might have specific "contracts".

Good catch, reverted to ConfiguredKit[]. Active forwarders have gone through configuration, so ConfiguredKit is the correct contract. The MPForwarder (Dictionary) type was too loose.

alexs-mparticle · 2026-05-21T13:40:05Z

        name: string
    ): Dictionary<string> | null;
+    filterUserIdentities?(
+        userIdentitiesObject: Record<string, string>,


I think we may have this type defined for this.

Updated to use Dictionary, which is already used in kitFilterHelper.ts for the same purpose and is already imported in this file.

cursor · 2026-05-25T23:17:15Z

+    filterUserIdentities?(
+        userIdentitiesObject: Dictionary<string>,
+        filterList: number[]
+    ): ISDKUserIdentity[];


Wrong parameter type for filterUserIdentities declaration

Medium Severity

The newly added filterUserIdentities type declaration specifies userIdentitiesObject: Dictionary<string> as its first parameter, but all callers in forwarders.ts pass ISDKUserIdentity[] (an array of user identity objects, not a string dictionary). This incorrect type definition misrepresents the actual API contract and will mislead any future TypeScript consumer relying on this interface for type checking.

Additional Locations (1)

src/forwarders.ts#L96-L100

^{Reviewed by Cursor Bugbot for commit d614b96. Configure here.}

The Dictionary type matches the actual implementation in helpers.js - it iterates with for...in and Object.keys(), expecting an object like { email: "foo@bar.com" }. The callers in forwarders.ts pass ISDKUserIdentity[] which is a pre-existing type mismatch in the JS codebase - the as Function casts already bypass the type check. Fixing this properly would require refactoring helpers.filterUserIdentities to accept both shapes, which is out of scope for this migration.

cursor

Cursor Bugbot has reviewed your changes and found 1 potential issue.

There are 3 total unresolved issues (including 2 from previous reviews).

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 1ba077d. Configure here.}

…arders

…Forwarders

sonarqubecloud · 2026-05-26T01:00:33Z

Quality Gate passed

Issues
15 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

jaissica12 marked this pull request as ready for review May 21, 2026 02:45

jaissica12 requested a review from a team as a code owner May 21, 2026 02:45

alexs-mparticle requested changes May 21, 2026

View reviewed changes

rmi22186 and others added 5 commits May 21, 2026 20:38

feat: Report deprecated method usage through logging dispatcher (#1270)

2578b9a

refactor: update forwarder module to TS

1634b3a

fix failing tests

2660da1

remove self=this pattern

6dcf6be

fix: address PR review feedback

d614b96

jaissica12 force-pushed the refactor/SDKE-1109-update-forwarders-to-TS branch from 94f8634 to d614b96 Compare May 25, 2026 23:10

cursor Bot reviewed May 25, 2026

View reviewed changes

fix activeForwarders type in store

1ba077d

cursor Bot reviewed May 26, 2026

View reviewed changes

Comment thread src/forwarders.ts

jaissica12 added 3 commits May 25, 2026 20:42

preserve ConfiguredKit[] type for activeForwarders and _getActiveForw…

aa30167

…arders

restore original loop styles in sendEventToForwarders and sendBatchTo…

cea16d6

…Forwarders

fix failing tests

e820005

jaissica12 requested a review from alexs-mparticle May 26, 2026 11:33

rmi22186 force-pushed the development branch from bfe52c3 to 44cd55d Compare May 26, 2026 16:03

Conversation

jaissica12 commented May 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Background

What Has Changed

Screenshots/Video

Checklist

Additional Notes

Reference Issue (For employees only. Ignore if you are an outside contributor)

Uh oh!

cursor Bot commented May 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Summary

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cursor Bot May 25, 2026

Choose a reason for hiding this comment

Wrong parameter type for filterUserIdentities declaration

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

sonarqubecloud Bot commented May 26, 2026

Quality Gate passed

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

jaissica12 commented May 12, 2026 •

edited

Loading

cursor Bot commented May 21, 2026 •

edited

Loading

Wrong parameter type for `filterUserIdentities` declaration