@khanacademy/wonder-blocks-data 14.1.4 → 14.1.6

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # @khanacademy/wonder-blocks-data
 
+## 14.1.6
+
+### Patch Changes
+
+- 642b5d7: Update docs to provide clearer details on fetch policy behaviors
+
+## 14.1.5
+
+### Patch Changes
+
+- Updated dependencies [1334e74]
+    - @khanacademy/wonder-blocks-core@12.4.0
+
 ## 14.1.4
 
 ### Patch Changes

package/dist/hooks/use-cached-effect.d.ts

@@ -5,9 +5,27 @@ type CachedEffectOptions<TData extends ValidCacheData> = {
      * The policy to use when determining how to retrieve the request data from
      * cache and network.
      *
+     * Inflight requests are shared so that multiple requests for the same
+     * resource do not cause multiple fetches while one fetch is already in
+     * progress.
+     *
+     * Network requests update the cache on return, regardless of which policy
+     * initiated the request.
+     *
+     * For fetch policies that use the cache, if the cache does not yet have
+     * the data, then a `no-data` status is returned.
+     *
+     * The `FetchPolicy.NetworkOnly`  and `FetchPolicy.CacheAndNetwork` only
+     * fetch the data once and then reuse that result, unless a re-fetch is
+     * explicitly triggered via the fetch function in the returned tuple.
+     *
+     * For `FetchPolicy.NetworkOnly`, the cache is ignored (but the cache
+     * is still updated with the fetched value). Until a value is available,
+     * a `loading` status is returned for this policy.
+     *
      * Defaults to `FetchPolicy.CacheBeforeNetwork`.
      */
-    fetchPolicy?: (typeof FetchPolicy)[keyof typeof FetchPolicy];
+    fetchPolicy?: FetchPolicy;
     /**
      * When `true`, the effect will not be executed; otherwise, the effect will
      * be executed.

package/dist/util/types.d.ts

@@ -1,24 +1,43 @@
 import type { Metadata } from "@khanacademy/wonder-stuff-core";
 /**
  * Defines the various fetch policies that can be applied to requests.
+ *
+ * If a policy fetches from the server, then the cache will be updated with
+ * the result of that fetch, once it completes. Inflight fetches are shared
+ * so that multiple requests for the same resource do not cause multiple
+ * fetches while one fetch is already in progress.
+ *
+ * It is up to the implementation to decide how to handle cache misses, but
+ * most cases likely return a `no-data` or, in the case of a network-only
+ * policy, `loading` result, depending on the policy.
  */
 export declare enum FetchPolicy {
     /**
-     * If the data is in the cache, return that; otherwise, fetch from the
-     * server.
+     * If the data is in the cache, use that data and do not fetch.
+     * Otherwise, provide `no-data` while data is fetched from the server.
+     *
+     * This is usually the policy you want. It means the value is retrieved
+     * once and then reused from cache thereafter.
      */
     CacheBeforeNetwork = "CacheBeforeNetwork",
     /**
-     * If the data is in the cache, return that; always fetch from the server
-     * regardless of cache.
+     * If the data is in the cache, use that data, but also fetch an update
+     * from the server if one was not already fetched.
+     * Otherwise, provide `no-data` while data is fetched from the server.
+     *
+     * If there is no cached data, this behaves like `NetworkOnly` while
+     * data is being fetched. If there is cached data, this behaves like
+     * `CacheOnly` while data is being fetched, and then updates the cache
+     * when the fetch completes, before acting like `NetworkOnly` thereafter.
      */
     CacheAndNetwork = "CacheAndNetwork",
     /**
-     * If the data is in the cache, return that; otherwise, do nothing.
+     * If the data is in the cache, use that; otherwise, provide `no-data`.
      */
     CacheOnly = "CacheOnly",
     /**
-     * Ignore any existing cached result; always fetch from the server.
+     * Ignore any existing cached result; fetch data from the server, if it
+     * wasn't already fetched. While there is no data, provide `loading`.
      */
     NetworkOnly = "NetworkOnly"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@khanacademy/wonder-blocks-data",
-  "version": "14.1.4",
+  "version": "14.1.6",
   "design": "v1",
   "publishConfig": {
     "access": "public"
@@ -10,7 +10,7 @@
   "module": "dist/es/index.js",
   "types": "dist/index.d.ts",
   "dependencies": {
-    "@khanacademy/wonder-blocks-core": "12.3.0"
+    "@khanacademy/wonder-blocks-core": "12.4.0"
   },
   "peerDependencies": {
     "@khanacademy/wonder-stuff-core": "^1.5.4",
@@ -18,7 +18,7 @@
   },
   "devDependencies": {
     "@khanacademy/wonder-stuff-testing": "^3.0.5",
-    "@khanacademy/wb-dev-build-settings": "3.0.0",
+    "@khanacademy/wb-dev-build-settings": "3.2.0",
     "@khanacademy/wonder-blocks-testing-core": "3.0.1"
   },
   "author": "",