feat: expose cache entry on shouldUpdateScript

.changeset/rude-cows-shake.md

@@ -0,0 +1,5 @@
+---
+"@callstack/repack": minor
+---
+
+Expose cached data on shouldUpdateScript in order to enable more custom cache resolution

packages/repack/src/modules/ScriptManager/ScriptManager.ts

@@ -505,7 +505,8 @@ export class ScriptManager extends EventEmitter {
       const fetch = await locator.shouldUpdateScript(
         scriptId,
         caller,
-        script.shouldUpdateCache(this.cache[cacheKey])
+        script.shouldUpdateCache(this.cache[cacheKey]),
+        this.cache[cacheKey]
       );
 
       // If it returns true, we need to fetch the script

packages/repack/src/modules/ScriptManager/types.ts

@@ -1,3 +1,5 @@
+import type { NormalizedScriptLocator } from './NativeScriptManager.js';
+
 /**
  * Interface specifying how to fetch a script.
  * It represents the output of {@link ScriptLocatorResolver} function used by {@link ScriptManager}.
@@ -132,7 +134,11 @@ export interface ScriptLocator {
   shouldUpdateScript?: (
     scriptId?: string,
     caller?: string,
-    isScriptCacheOutdated?: boolean
+    isScriptCacheOutdated?: boolean,
+    cachedData?: Pick<
+      NormalizedScriptLocator,
+      'method' | 'url' | 'query' | 'headers' | 'body'
+    >
   ) => Promise<boolean> | boolean;
 }
 

website/src/latest/api/runtime/script-manager.md

@@ -256,6 +256,43 @@ ScriptManager.shared.hooks.afterResolve(async (args) => {
 });
 ```
 
+### Override shouldUpdateScript logic
+
+```js
+ScriptManager.shared.hooks.afterResolve(async (args) => {
+  const { locator } = args;
+  locator.shouldUpdateScript = async (scriptId, caller, isScriptCacheOutdated, cachedData) => {
+    // Custom logic to determine if the script should be updated
+    if (isScriptCacheOutdated) {
+      return true;
+    }
+    return false;
+  };
+  return args;
+});
+```
+
+`shouldUpdateScript` also exposes the cached script locator data for more advanced comparison:
+
+> **Note:** The `shallowEqual` function is a utility for comparing two objects' keys and values. You can use your own implementation or import one from a utility library.
+
+```js
+ScriptManager.shared.hooks.afterResolve(async (args) => {
+  const { locator } = args;
+  locator.shouldUpdateScript = async (scriptId, caller, isScriptCacheOutdated, cachedData) => {
+    // Custom logic to determine if the script should be updated
+    return (
+        cachedData.method !== locator.method ||
+        cachedData.url !== locator.url ||
+        cachedData.query !== locator.query ||
+        !shallowEqual(cachedData.headers, locator.headers) ||
+        cachedData.body !== locator.body
+      );
+  };
+  return args;
+});
+```
+
 ### Override script locator URL after resolution
 
 ```js