feat(sdk): make initial fetch optional on subscriptions

[MartianGreed]

Summary

Adds a fetchInitialData option to subscribeEntityQuery() and subscribeEventQuery(). When set to false, the initial getEntities/getEventMessages call is skipped and only the gRPC subscription is opened.

Closes #461

Changes

• Added fetchInitialData?: boolean to SubscribeParams<T> interface (defaults to true)
• Updated subscribeEntityQuery to conditionally skip initial getEntities fetch
• Updated subscribeEventQuery to conditionally skip initial getEventMessages fetch
• Added test for fetchInitialData: false behavior
• When skipped, returns empty pagination with an empty items array

Usage

// Default behavior (unchanged) - fetches initial data
const [data, sub] = await sdk.subscribeEntityQuery({
    query: myQuery,
    callback: onUpdate,
});

// Skip initial fetch - only subscribe to updates
const [emptyData, sub] = await sdk.subscribeEntityQuery({
    query: myQuery,
    callback: onUpdate,
    fetchInitialData: false,
});

Backward Compatibility

Default is true, so existing code works without changes.

Summary by CodeRabbit

• New Features

  • Added optional fetchInitialData flag to subscriptions, allowing you to skip initial data fetching and open only the subscription stream. Defaults to true for backward compatibility.

• Tests

  • Added test coverage for the new fetchInitialData flag behavior.

[coderabbitai]

📝 Walkthrough

Walkthrough

Introduces an optional fetchInitialData parameter to subscribeEntityQuery and subscribeEventQuery functions. When set to false, skips the initial data fetch and returns only a subscription handle with empty items. Defaults to true, maintaining backward compatibility. Includes type definitions and comprehensive test coverage.

Changes

Cohort / File(s)	Summary
Type Definitions packages/internal/src/types.ts	Added optional fetchInitialData?: boolean field to SubscribeParams<T> to control initial data fetch behavior.
Implementation packages/sdk/src/createSDK.ts	Updated subscribeEntityQuery and subscribeEventQuery to conditionally fetch initial data based on the fetchInitialData flag; when false, skips gRPC query and returns empty items list with subscription.
Tests packages/sdk/src/__tests__/createSDK.test.ts	Added test cases validating that fetchInitialData: false skips the initial gRPC call, invokes the callback, and returns empty items with a subscription handle.
Changeset .changeset/optional-initial-fetch.md	Documents feature introduction with minor version bumps for @dojoengine/sdk and @dojoengine/internal.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Poem

🐰 A choice now given, a skip or a go,
Fetch or not fetch—the subscription will flow,
Less resource spent when you know what you need,
Backward compatible—a thoughtful deed! 🎉

🚥 Pre-merge checks | ✅ 5 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Merge Conflict Detection	⚠️ Warning	❌ Merge conflicts detected (14 files): ⚔️ example/core/dojo/index.ts (content) ⚔️ example/frameworks/node/src/index.ts (content) ⚔️ example/frameworks/react/src/effect/atoms/index.ts (content) ⚔️ example/frameworks/react/src/pages/EntitiesUpdates.tsx (content) ⚔️ example/frameworks/react/src/pages/Events.tsx (content) ⚔️ example/frameworks/react/src/pages/Home.tsx (content) ⚔️ example/frameworks/react/src/pages/TokenBalances.tsx (content) ⚔️ example/frameworks/react/src/pages/Tokens.tsx (content) ⚔️ example/frameworks/vue/src/App.vue (content) ⚔️ packages/internal/src/types.ts (content) ⚔️ packages/react/src/effect/atoms/entities.ts (content) ⚔️ packages/sdk/src/__tests__/createSDK.test.ts (content) ⚔️ packages/sdk/src/createSDK.ts (content) ⚔️ packages/state/src/__tests__/recs-implementation.test.ts (content) These conflicts must be resolved before merging into main.	Resolve conflicts locally and push changes to this branch.

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the main change: making initial fetch optional on SDK subscriptions.
Description check	✅ Passed	The PR description covers the main changes, includes implementation details, usage examples, and confirms backward compatibility, but the checklist section is missing.
Linked Issues check	✅ Passed	The PR fully implements the requested feature from #461: adds fetchInitialData option to both subscribeEntityQuery and subscribeEventQuery with proper default behavior.
Out of Scope Changes check	✅ Passed	All changes are directly related to the linked issue #461 objective of making initial fetch optional on subscriptions with no unrelated modifications.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch feat/optional-initial-fetch

⚔️ Resolve merge conflicts (beta)

• Auto-commit resolved conflicts to branch feat/optional-initial-fetch
• Create stacked PR with resolved conflicts
• Post resolved changes as copyable diffs in a comment

---

No actionable comments were generated in the recent review. 🎉

🧹 Recent nitpick comments

packages/sdk/src/__tests__/createSDK.test.ts (1)

367-412: Consider adding a test for subscribeEventQuery with fetchInitialData: false.

The new test covers subscribeEntityQuery but subscribeEventQuery also gained the same feature. A symmetric test would confirm getEventMessages is skipped and onEventMessageUpdated is still invoked.

Would you like me to generate the test case for subscribeEventQuery with fetchInitialData: false?

packages/sdk/src/createSDK.ts (1)

254-284: Subscription setup is duplicated across both branches.

The onEntityUpdated call is identical in both the fetchInitialData and !fetchInitialData paths. Consider extracting the subscription promise to reduce duplication.

♻️ Suggested refactor

         subscribeEntityQuery: async ({
             query,
             callback,
             fetchInitialData = true,
         }) => {
             const q = query.build();
 
+            const subscription = await grpcClientInstance.onEntityUpdated(
+                q.clause,
+                q.world_addresses,
+                subscribeQueryModelCallback(callback)
+            );
+
             if (fetchInitialData) {
                 const entities = await sdkClient.getEntities(q);
                 const parsedEntities = parseEntities<T>(entities.items);
                 return [
                     Pagination.fromQuery(query, entities.next_cursor).withItems(
                         parsedEntities
                     ),
-                    await grpcClientInstance.onEntityUpdated(
-                        q.clause,
-                        q.world_addresses,
-                        subscribeQueryModelCallback(callback)
-                    ),
+                    subscription,
                 ];
             }
 
             return [
                 Pagination.fromQuery(query, undefined).withItems([]),
-                await grpcClientInstance.onEntityUpdated(
-                    q.clause,
-                    q.world_addresses,
-                    subscribeQueryModelCallback(callback)
-                ),
+                subscription,
             ];
         },

The same refactor applies to subscribeEventQuery (lines 292-322).

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}