@khanacademy/wonder-blocks-data 6.0.1 → 7.0.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @khanacademy/wonder-blocks-data
 
+## 7.0.0
+
+### Major Changes
+
+-   34407c4a: `useServerEffect` now has a `skip` option, preventing the request from getting tracked for server-side fulfillment
+
 ## 6.0.1
 
 ### Patch Changes

package/dist/es/index.js

@@ -600,21 +600,6 @@ class TrackData extends React.Component {
 
 }
 
-/**
- * Simple implementation to represent aborting.
- *
- * Other frameworks may provide this too, so we won't be sharing this with
- * the outside world. It's just a utility for test and internal use whenever
- * we need to represent the concept of aborted things.
- */
-class AbortError extends Error {
-  constructor(message) {
-    super(message);
-    this.name = "AbortError";
-  }
-
-}
-
 const loadingStatus = Object.freeze({
   status: "loading"
 });
@@ -728,22 +713,26 @@ const useRequestInterception = (requestId, handler) => {
  *
  * The asynchronous action is never invoked on the client-side.
  */
-const useServerEffect = (requestId, handler, hydrate = true) => {
-  // Plug in to the request interception framework for code that wants
+const useServerEffect = (requestId, handler, options = {}) => {
+  const {
+    hydrate = true,
+    skip = false
+  } = options; // Plug in to the request interception framework for code that wants
   // to use that.
+
   const interceptedHandler = useRequestInterception(requestId, handler); // If we're server-side or hydrating, we'll have a cached entry to use.
   // So we get that and use it to initialize our state.
   // This works in both hydration and SSR because the very first call to
   // this will have cached data in those cases as it will be present on the
   // initial render - and subsequent renders on the client it will be null.
 
-  const cachedResult = SsrCache.Default.getEntry(requestId); // We only track data requests when we are server-side and we don't
-  // already have a result, as given by the cachedData (which is also the
-  // initial value for the result state).
+  const cachedResult = SsrCache.Default.getEntry(requestId); // We only track data requests when we are server-side, we are not skipping
+  // the request, and we don't already have a result, as given by the
+  // cachedData (which is also the initial value for the result state).
 
   const maybeTrack = useContext(TrackerContext);
 
-  if (cachedResult == null && Server.isServerSide()) {
+  if (!skip && cachedResult == null && Server.isServerSide()) {
     maybeTrack == null ? void 0 : maybeTrack(requestId, interceptedHandler, hydrate);
   } // A null result means there was no result to hydrate.
 
@@ -992,10 +981,11 @@ const useHydratableEffect = (requestId, handler, options = {}) => {
   // When client-side, this will look up any response for hydration; it does
   // not invoke the handler.
 
-  const serverResult = useServerEffect(requestId, // If we're skipped (unlikely in server worlds, but maybe),
-  // just give an aborted response.
-  skip ? () => Promise.reject(new AbortError("skipped")) : handler, // Only hydrate if our behavior isn't telling us not to.
-  clientBehavior !== WhenClientSide.DoNotHydrate);
+  const serverResult = useServerEffect(requestId, handler, {
+    // Only hydrate if our behavior isn't telling us not to.
+    hydrate: clientBehavior !== WhenClientSide.DoNotHydrate,
+    skip
+  });
   const getDefaultCacheValue = React.useCallback(() => {
     // If we don't have a requestId, it's our first render, the one
     // where we hydrated. So defer to our clientBehavior value.

package/dist/index.js

@@ -82,7 +82,7 @@ module.exports =
 /******/
 /******/
 /******/ 	// Load entry module and return exports
-/******/ 	return __webpack_require__(__webpack_require__.s = 28);
+/******/ 	return __webpack_require__(__webpack_require__.s = 27);
 /******/ })
 /************************************************************************/
 /******/ ([
@@ -885,11 +885,9 @@ class RequestFulfillment {
 /* harmony export (binding) */ __webpack_require__.d(__webpack_exports__, "b", function() { return useHydratableEffect; });
 /* harmony import */ var react__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(0);
 /* harmony import */ var react__WEBPACK_IMPORTED_MODULE_0___default = /*#__PURE__*/__webpack_require__.n(react__WEBPACK_IMPORTED_MODULE_0__);
-/* harmony import */ var _util_abort_error_js__WEBPACK_IMPORTED_MODULE_1__ = __webpack_require__(24);
-/* harmony import */ var _use_server_effect_js__WEBPACK_IMPORTED_MODULE_2__ = __webpack_require__(14);
-/* harmony import */ var _use_shared_cache_js__WEBPACK_IMPORTED_MODULE_3__ = __webpack_require__(8);
-/* harmony import */ var _use_cached_effect_js__WEBPACK_IMPORTED_MODULE_4__ = __webpack_require__(15);
-
+/* harmony import */ var _use_server_effect_js__WEBPACK_IMPORTED_MODULE_1__ = __webpack_require__(14);
+/* harmony import */ var _use_shared_cache_js__WEBPACK_IMPORTED_MODULE_2__ = __webpack_require__(8);
+/* harmony import */ var _use_cached_effect_js__WEBPACK_IMPORTED_MODULE_3__ = __webpack_require__(15);
 
 
 
@@ -898,7 +896,7 @@ class RequestFulfillment {
 /**
  * Policies to define how a hydratable effect should behave client-side.
  */
-const WhenClientSide = __webpack_require__(29).Mirrored(["DoNotHydrate", "ExecuteWhenNoResult", "ExecuteWhenNoSuccessResult", "AlwaysExecute"]);
+const WhenClientSide = __webpack_require__(28).Mirrored(["DoNotHydrate", "ExecuteWhenNoResult", "ExecuteWhenNoSuccessResult", "AlwaysExecute"]);
 const DefaultScope = "useHydratableEffect";
 /**
  * Hook to execute an async operation on server and client.
@@ -922,10 +920,11 @@ const useHydratableEffect = (requestId, handler, options = {}) => {
   // When client-side, this will look up any response for hydration; it does
   // not invoke the handler.
 
-  const serverResult = Object(_use_server_effect_js__WEBPACK_IMPORTED_MODULE_2__[/* useServerEffect */ "a"])(requestId, // If we're skipped (unlikely in server worlds, but maybe),
-  // just give an aborted response.
-  skip ? () => Promise.reject(new _util_abort_error_js__WEBPACK_IMPORTED_MODULE_1__[/* AbortError */ "a"]("skipped")) : handler, // Only hydrate if our behavior isn't telling us not to.
-  clientBehavior !== WhenClientSide.DoNotHydrate);
+  const serverResult = Object(_use_server_effect_js__WEBPACK_IMPORTED_MODULE_1__[/* useServerEffect */ "a"])(requestId, handler, {
+    // Only hydrate if our behavior isn't telling us not to.
+    hydrate: clientBehavior !== WhenClientSide.DoNotHydrate,
+    skip
+  });
   const getDefaultCacheValue = react__WEBPACK_IMPORTED_MODULE_0__["useCallback"](() => {
     // If we don't have a requestId, it's our first render, the one
     // where we hydrated. So defer to our clientBehavior value.
@@ -965,11 +964,11 @@ const useHydratableEffect = (requestId, handler, options = {}) => {
   }, [serverResult]); // Instead of using state, which would be local to just this hook instance,
   // we use a shared in-memory cache.
 
-  Object(_use_shared_cache_js__WEBPACK_IMPORTED_MODULE_3__[/* useSharedCache */ "b"])(requestId, // The key of the cached item
+  Object(_use_shared_cache_js__WEBPACK_IMPORTED_MODULE_2__[/* useSharedCache */ "b"])(requestId, // The key of the cached item
   scope, // The scope of the cached items
   getDefaultCacheValue); // When we're client-side, we ultimately want the result from this call.
 
-  const clientResult = Object(_use_cached_effect_js__WEBPACK_IMPORTED_MODULE_4__[/* useCachedEffect */ "a"])(requestId, handler, {
+  const clientResult = Object(_use_cached_effect_js__WEBPACK_IMPORTED_MODULE_3__[/* useCachedEffect */ "a"])(requestId, handler, {
     skip,
     onResultChanged,
     retainResultOnChange,
@@ -1061,7 +1060,7 @@ const InterceptContext = /*#__PURE__*/react__WEBPACK_IMPORTED_MODULE_0__["create
 /* harmony import */ var react__WEBPACK_IMPORTED_MODULE_1___default = /*#__PURE__*/__webpack_require__.n(react__WEBPACK_IMPORTED_MODULE_1__);
 /* harmony import */ var _util_request_tracking_js__WEBPACK_IMPORTED_MODULE_2__ = __webpack_require__(7);
 /* harmony import */ var _util_ssr_cache_js__WEBPACK_IMPORTED_MODULE_3__ = __webpack_require__(5);
-/* harmony import */ var _util_result_from_cache_response_js__WEBPACK_IMPORTED_MODULE_4__ = __webpack_require__(25);
+/* harmony import */ var _util_result_from_cache_response_js__WEBPACK_IMPORTED_MODULE_4__ = __webpack_require__(24);
 /* harmony import */ var _use_request_interception_js__WEBPACK_IMPORTED_MODULE_5__ = __webpack_require__(16);
 
 
@@ -1085,22 +1084,26 @@ const InterceptContext = /*#__PURE__*/react__WEBPACK_IMPORTED_MODULE_0__["create
  *
  * The asynchronous action is never invoked on the client-side.
  */
-const useServerEffect = (requestId, handler, hydrate = true) => {
-  // Plug in to the request interception framework for code that wants
+const useServerEffect = (requestId, handler, options = {}) => {
+  const {
+    hydrate = true,
+    skip = false
+  } = options; // Plug in to the request interception framework for code that wants
   // to use that.
+
   const interceptedHandler = Object(_use_request_interception_js__WEBPACK_IMPORTED_MODULE_5__[/* useRequestInterception */ "a"])(requestId, handler); // If we're server-side or hydrating, we'll have a cached entry to use.
   // So we get that and use it to initialize our state.
   // This works in both hydration and SSR because the very first call to
   // this will have cached data in those cases as it will be present on the
   // initial render - and subsequent renders on the client it will be null.
 
-  const cachedResult = _util_ssr_cache_js__WEBPACK_IMPORTED_MODULE_3__[/* SsrCache */ "a"].Default.getEntry(requestId); // We only track data requests when we are server-side and we don't
-  // already have a result, as given by the cachedData (which is also the
-  // initial value for the result state).
+  const cachedResult = _util_ssr_cache_js__WEBPACK_IMPORTED_MODULE_3__[/* SsrCache */ "a"].Default.getEntry(requestId); // We only track data requests when we are server-side, we are not skipping
+  // the request, and we don't already have a result, as given by the
+  // cachedData (which is also the initial value for the result state).
 
   const maybeTrack = Object(react__WEBPACK_IMPORTED_MODULE_1__["useContext"])(_util_request_tracking_js__WEBPACK_IMPORTED_MODULE_2__[/* TrackerContext */ "b"]);
 
-  if (cachedResult == null && _khanacademy_wonder_blocks_core__WEBPACK_IMPORTED_MODULE_0__["Server"].isServerSide()) {
+  if (!skip && cachedResult == null && _khanacademy_wonder_blocks_core__WEBPACK_IMPORTED_MODULE_0__["Server"].isServerSide()) {
     maybeTrack == null ? void 0 : maybeTrack(requestId, interceptedHandler, hydrate);
   } // A null result means there was no result to hydrate.
 
@@ -1517,8 +1520,8 @@ const GqlRouter = ({
 /* harmony import */ var react__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(0);
 /* harmony import */ var react__WEBPACK_IMPORTED_MODULE_0___default = /*#__PURE__*/__webpack_require__.n(react__WEBPACK_IMPORTED_MODULE_0__);
 /* harmony import */ var _util_merge_gql_context_js__WEBPACK_IMPORTED_MODULE_1__ = __webpack_require__(18);
-/* harmony import */ var _use_gql_router_context_js__WEBPACK_IMPORTED_MODULE_2__ = __webpack_require__(26);
-/* harmony import */ var _util_get_gql_data_from_response_js__WEBPACK_IMPORTED_MODULE_3__ = __webpack_require__(27);
+/* harmony import */ var _use_gql_router_context_js__WEBPACK_IMPORTED_MODULE_2__ = __webpack_require__(25);
+/* harmony import */ var _util_get_gql_data_from_response_js__WEBPACK_IMPORTED_MODULE_3__ = __webpack_require__(26);
 
 
 
@@ -1562,27 +1565,6 @@ const useGql = (context = {}) => {
 /* 24 */
 /***/ (function(module, __webpack_exports__, __webpack_require__) {
 
-"use strict";
-/* harmony export (binding) */ __webpack_require__.d(__webpack_exports__, "a", function() { return AbortError; });
-/**
- * Simple implementation to represent aborting.
- *
- * Other frameworks may provide this too, so we won't be sharing this with
- * the outside world. It's just a utility for test and internal use whenever
- * we need to represent the concept of aborted things.
- */
-class AbortError extends Error {
-  constructor(message) {
-    super(message);
-    this.name = "AbortError";
-  }
-
-}
-
-/***/ }),
-/* 25 */
-/***/ (function(module, __webpack_exports__, __webpack_require__) {
-
 "use strict";
 /* harmony export (binding) */ __webpack_require__.d(__webpack_exports__, "a", function() { return resultFromCachedResponse; });
 /* harmony import */ var _status_js__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(4);
@@ -1620,7 +1602,7 @@ const resultFromCachedResponse = cacheEntry => {
 };
 
 /***/ }),
-/* 26 */
+/* 25 */
 /***/ (function(module, __webpack_exports__, __webpack_require__) {
 
 "use strict";
@@ -1672,7 +1654,7 @@ const useGqlRouterContext = (contextOverrides = {}) => {
 };
 
 /***/ }),
-/* 27 */
+/* 26 */
 /***/ (function(module, __webpack_exports__, __webpack_require__) {
 
 "use strict";
@@ -1742,7 +1724,7 @@ const getGqlDataFromResponse = async response => {
 };
 
 /***/ }),
-/* 28 */
+/* 27 */
 /***/ (function(module, __webpack_exports__, __webpack_require__) {
 
 "use strict";
@@ -1889,7 +1871,7 @@ const removeAllFromCache = predicate => _util_ssr_cache_js__WEBPACK_IMPORTED_MOD
 
 
 /***/ }),
-/* 29 */
+/* 28 */
 /***/ (function(module, exports, __webpack_require__) {
 
 "use strict";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@khanacademy/wonder-blocks-data",
-  "version": "6.0.1",
+  "version": "7.0.0",
   "design": "v1",
   "publishConfig": {
     "access": "public"

package/src/__docs__/exports.use-server-effect.stories.mdx

@@ -15,12 +15,24 @@ import {Meta} from "@storybook/addon-docs";
 function useServerEffect<TData: ValidCacheData>(
     requestId: string,
     handler: () => Promise<TData>,
-    hydrate: boolean = true,
+    options?: ServerEffectOptions,
 ): ?Result<TData>;
 ```
 
 The `useServerEffect` hook is an integral part of server-side rendering. It has different behavior depending on whether it is running on the server (and in what context) or the client.
 
+```ts
+type ServerEffectOptions = {|
+    skip?: boolean,
+    hydrate?: boolean,
+|};
+```
+
+| Option | Default | Description |
+| ------ | ------- | ----------- |
+| `hydrate` | `true` | When `true`, the result of the effect when fulfilled using Wonder Blocks Data will be stored in the hydration cache for hydrating client-side; otherwise, the result will be stored in the server-side-only cache. |
+| `skip` | `false` | When `true`, the effect will not be tracked for fulfillment; otherwise, the effect will be tracked for fulfillment. |
+
 ## Server-side behavior
 
 First, this hook checks the server-side rendering cache for the request identifier; if it finds a cached value, it will return that.

package/src/hooks/__tests__/use-hydratable-effect.test.js

@@ -107,34 +107,11 @@ describe("#useHydratableEffect", () => {
                 expect(useServerEffectSpy).toHaveBeenCalledWith(
                     "ID",
                     fakeHandler,
-                    hydrate,
+                    {hydrate, skip: false},
                 );
             },
         );
 
-        it("should pass an abort handler to useServerEffect when skip is true", async () => {
-            // Arrange
-            jest.spyOn(
-                UseRequestInterception,
-                "useRequestInterception",
-            ).mockReturnValue(jest.fn());
-            const fakeHandler = jest.fn();
-            const useServerEffectSpy = jest
-                .spyOn(UseServerEffect, "useServerEffect")
-                .mockReturnValue(null);
-
-            // Act
-            serverRenderHook(() =>
-                useHydratableEffect("ID", fakeHandler, {skip: true}),
-            );
-            const underTest = useServerEffectSpy.mock.calls[0][1]();
-
-            // Assert
-            await expect(underTest).rejects.toMatchInlineSnapshot(
-                `[AbortError: skipped]`,
-            );
-        });
-
         it.each`
             scope        | expectedScope
             ${undefined} | ${"useHydratableEffect"}
@@ -247,7 +224,7 @@ describe("#useHydratableEffect", () => {
                 expect(useServerEffectSpy).toHaveBeenCalledWith(
                     "ID",
                     fakeHandler,
-                    hydrate,
+                    {hydrate, skip: false},
                 );
             },
         );

package/src/hooks/__tests__/use-server-effect.test.js

@@ -109,6 +109,57 @@ describe("#useServerEffect", () => {
             );
         });
 
+        it("should not track the intercepted request if skip is true", () => {
+            // Arrange
+            const fakeHandler = jest.fn();
+            const interceptedHandler = jest.fn();
+            jest.spyOn(
+                UseRequestInterception,
+                "useRequestInterception",
+            ).mockReturnValue(interceptedHandler);
+            const trackDataRequestSpy = jest.spyOn(
+                RequestTracker.Default,
+                "trackDataRequest",
+            );
+
+            // Act
+            serverRenderHook(
+                () => useServerEffect("ID", fakeHandler, {skip: true}),
+                {
+                    wrapper: TrackData,
+                },
+            );
+
+            // Assert
+            expect(trackDataRequestSpy).not.toHaveBeenCalled();
+        });
+
+        it("should not track the intercepted request if there is a cached result", () => {
+            // Arrange
+            const fakeHandler = jest.fn();
+            const interceptedHandler = jest.fn();
+            jest.spyOn(SsrCache.Default, "getEntry").mockReturnValueOnce({
+                data: "DATA",
+                error: null,
+            });
+            jest.spyOn(
+                UseRequestInterception,
+                "useRequestInterception",
+            ).mockReturnValue(interceptedHandler);
+            const trackDataRequestSpy = jest.spyOn(
+                RequestTracker.Default,
+                "trackDataRequest",
+            );
+
+            // Act
+            serverRenderHook(() => useServerEffect("ID", fakeHandler), {
+                wrapper: TrackData,
+            });
+
+            // Assert
+            expect(trackDataRequestSpy).not.toHaveBeenCalled();
+        });
+
         it("should return data cached result", () => {
             // Arrange
             const fakeHandler = jest.fn();

package/src/hooks/use-hydratable-effect.js

@@ -1,8 +1,6 @@
 // @flow
 import * as React from "react";
 
-import {AbortError} from "../util/abort-error.js";
-
 import {useServerEffect} from "./use-server-effect.js";
 import {useSharedCache} from "./use-shared-cache.js";
 import {useCachedEffect} from "./use-cached-effect.js";
@@ -141,16 +139,11 @@ export const useHydratableEffect = <TData: ValidCacheData>(
     // Now we instruct the server to perform the operation.
     // When client-side, this will look up any response for hydration; it does
     // not invoke the handler.
-    const serverResult = useServerEffect(
-        requestId,
-
-        // If we're skipped (unlikely in server worlds, but maybe),
-        // just give an aborted response.
-        skip ? () => Promise.reject(new AbortError("skipped")) : handler,
-
+    const serverResult = useServerEffect(requestId, handler, {
         // Only hydrate if our behavior isn't telling us not to.
-        clientBehavior !== WhenClientSide.DoNotHydrate,
-    );
+        hydrate: clientBehavior !== WhenClientSide.DoNotHydrate,
+        skip,
+    });
 
     const getDefaultCacheValue: () => ?Result<TData> = React.useCallback(() => {
         // If we don't have a requestId, it's our first render, the one

package/src/hooks/use-server-effect.js

@@ -8,6 +8,29 @@ import {useRequestInterception} from "./use-request-interception.js";
 
 import type {Result, ValidCacheData} from "../util/types.js";
 
+type ServerEffectOptions = {|
+    /**
+     * When `true`, the result of the effect when fulfilled using Wonder Blocks
+     * Data will be stored in the hydration cache for hydrating client-side;
+     * otherwise, the result will be stored in the server-side-only cache.
+     *
+     * This should only be set to `false` if something else will be responsible
+     * for hydration of the data on the client-side (for example, if Apollo's
+     * hydration support is used).
+     *
+     * Default is `true`.
+     */
+    hydrate?: boolean,
+
+    /**
+     * When `true`, the effect will not be tracked for fulfillment; otherwise,
+     * the effect will be tracked for fulfillment.
+     *
+     * Default is `false`.
+     */
+    skip?: boolean,
+|};
+
 /**
  * Hook to perform an asynchronous action during server-side rendering.
  *
@@ -26,8 +49,10 @@ import type {Result, ValidCacheData} from "../util/types.js";
 export const useServerEffect = <TData: ValidCacheData>(
     requestId: string,
     handler: () => Promise<TData>,
-    hydrate: boolean = true,
+    options: ServerEffectOptions = ({}: $Shape<ServerEffectOptions>),
 ): ?Result<TData> => {
+    const {hydrate = true, skip = false} = options;
+
     // Plug in to the request interception framework for code that wants
     // to use that.
     const interceptedHandler = useRequestInterception(requestId, handler);
@@ -39,11 +64,11 @@ export const useServerEffect = <TData: ValidCacheData>(
     // initial render - and subsequent renders on the client it will be null.
     const cachedResult = SsrCache.Default.getEntry<TData>(requestId);
 
-    // We only track data requests when we are server-side and we don't
-    // already have a result, as given by the cachedData (which is also the
-    // initial value for the result state).
+    // We only track data requests when we are server-side, we are not skipping
+    // the request, and we don't already have a result, as given by the
+    // cachedData (which is also the initial value for the result state).
     const maybeTrack = useContext(TrackerContext);
-    if (cachedResult == null && Server.isServerSide()) {
+    if (!skip && cachedResult == null && Server.isServerSide()) {
         maybeTrack?.(requestId, interceptedHandler, hydrate);
     }
 

package/src/util/abort-error.js

@@ -1,15 +0,0 @@
-// @flow
-
-/**
- * Simple implementation to represent aborting.
- *
- * Other frameworks may provide this too, so we won't be sharing this with
- * the outside world. It's just a utility for test and internal use whenever
- * we need to represent the concept of aborted things.
- */
-export class AbortError extends Error {
-    constructor(message: string) {
-        super(message);
-        this.name = "AbortError";
-    }
-}