feat: 🎸 allowCache

.changeset/curly-pigs-float.md

@@ -0,0 +1,5 @@
+---
+'@ethlete/query': patch
+---
+
+use allowCache instead of skipCache and default to skipping the cache in exp query

apps/playground/src/app/app.component.ts

@@ -213,11 +213,11 @@ export class DynCompComponent {
   }
 
   execWherePostIdIs4() {
-    this.paged.execute({ where: (item) => item.id === 4, skipCache: true });
+    this.paged.execute({ where: (item) => item.id === 4 });
   }
 
   execAll() {
-    this.paged.execute({ skipCache: true });
+    this.paged.execute();
   }
 
   // id = computed(() => this.myPostQuery1.response()?.id);

libs/query/src/lib/experimental/http-request.ts

@@ -131,7 +131,7 @@ export type HttpRequestLoadingProgressState = {
 
 export type HttpRequest<TArgs extends QueryArgs> = {
   /** Executes the request */
-  execute: (options?: { skipCache?: boolean }) => boolean;
+  execute: (options?: { allowCache?: boolean }) => boolean;
 
   /** Destroys the request (cancels it if in progress) */
   destroy: () => boolean;
@@ -212,9 +212,9 @@ export const createHttpRequest = <TArgs extends QueryArgs>(options: CreateHttpRe
       }),
     );
 
-  const execute = (options?: { skipCache?: boolean }) => {
-    if (loading() || (!isStale() && !options?.skipCache)) {
-      // Do not execute if there is already a request in progress or the request is not stale
+  const execute = (options?: { allowCache?: boolean }) => {
+    if (loading() || (!isStale() && options?.allowCache)) {
+      // Do not execute if there is already a request in progress or caching is allowed
       return false;
     }
 

libs/query/src/lib/experimental/paged-query.ts

@@ -118,15 +118,15 @@ export type PagedQueryExecuteOptions<TArgs extends QueryArgs> = {
    * If not provided, all queries will be executed.
    *
    * @example
-   * myPagedQuery.execute({ where: (item) => item.id === 4, skipCache: true });
+   * myPagedQuery.execute({ where: (item) => item.id === 4 });
    */
   where?: (item: ResponseType<TArgs>, index: number, array: ResponseType<TArgs>[]) => boolean;
 
   /**
-   * If true, the cache will be skipped and the query will be executed.
+   * If true, the cache will be used (if not expired) and the request will not be made.
    * @default false
    */
-  skipCache?: boolean;
+  allowCache?: boolean;
 };
 
 export const createPagedQuery = <TArgs extends QueryArgs>(options: CreatePagedQueryOptions<TArgs>) => {
@@ -304,10 +304,10 @@ export const createPagedQuery = <TArgs extends QueryArgs>(options: CreatePagedQu
       }
 
       for (const query of queriesToExecute) {
-        query.execute({ options: { skipCache: options.skipCache } });
+        query.execute({ options: { allowCache: options.allowCache } });
       }
     } else {
-      stack.execute({ skipCache: options?.skipCache });
+      stack.execute({ allowCache: options?.allowCache });
     }
   };
 

libs/query/src/lib/experimental/query-errors.ts

@@ -28,7 +28,7 @@ export const enum RuntimeErrorCode {
 
   // Query Repository
   UNCACHEABLE_REQUEST_HAS_CACHE_KEY_PARAM = 300,
-  UNCACHEABLE_REQUEST_HAS_SKIP_CACHE_PARAM = 301,
+  UNCACHEABLE_REQUEST_HAS_ALLOW_CACHE_PARAM = 301,
 
   // Paged Query
   PAGED_QUERY_PAGE_BIGGER_THAN_TOTAL_PAGES = 400,
@@ -163,10 +163,10 @@ export const uncacheableRequestHasCacheKeyParam = (key: string) => {
   );
 };
 
-export const uncacheableRequestHasSkipCacheParam = () => {
+export const uncacheableRequestHasAllowCacheParam = () => {
   return new RuntimeError(
-    RuntimeErrorCode.UNCACHEABLE_REQUEST_HAS_SKIP_CACHE_PARAM,
-    `This request is uncacheable, but skipCache is set to true. Please remove it.`,
+    RuntimeErrorCode.UNCACHEABLE_REQUEST_HAS_ALLOW_CACHE_PARAM,
+    `This request is uncacheable, but allowCache is set to true. Please remove it.`,
   );
 };
 

libs/query/src/lib/experimental/query-execute-utils.ts

@@ -37,7 +37,7 @@ export const setupQueryExecuteState = (): QueryExecuteState => {
 };
 
 export type RunQueryExecuteOptions = {
-  skipCache?: boolean;
+  allowCache?: boolean;
 };
 
 export type QueryExecuteOptions<TArgs extends QueryArgs> = {

libs/query/src/lib/experimental/query-repository.spec.ts

@@ -96,20 +96,20 @@ describe('createQueryRepository', () => {
     expect(res4).toBe(false);
   });
 
-  it('skipCache should work', () => {
+  it('allowCache should work', () => {
     const req1 = repo.request({ destroyRef, method: 'GET', route: '/test' });
     const req2 = repo.request({ destroyRef, method: 'GET', route: '/test' });
 
     expect(req1.request).toBe(req2.request);
 
-    const req3 = repo.request({ destroyRef, method: 'GET', route: '/test', runQueryOptions: { skipCache: true } });
+    const req3 = repo.request({ destroyRef, method: 'GET', route: '/test', runQueryOptions: { allowCache: true } });
 
     expect(req3.request).toBe(req3.request);
   });
 
-  it('should throw if skipCache is used on a uncacheable request', () => {
+  it('should throw if allowCache is used on a uncacheable request', () => {
     expect(() =>
-      repo.request({ destroyRef, method: 'POST', route: '/test', runQueryOptions: { skipCache: true } }),
+      repo.request({ destroyRef, method: 'POST', route: '/test', runQueryOptions: { allowCache: true } }),
     ).toThrow();
   });
 

libs/query/src/lib/experimental/query-repository.ts

@@ -6,7 +6,7 @@ import { CreateHttpRequestClientOptions, HttpRequest, createHttpRequest } from '
 import { QueryArgs, RequestArgs } from './query';
 import { QueryClientConfig } from './query-client-config';
 import { QueryMethod, RouteType } from './query-creator';
-import { uncacheableRequestHasCacheKeyParam, uncacheableRequestHasSkipCacheParam } from './query-errors';
+import { uncacheableRequestHasAllowCacheParam, uncacheableRequestHasCacheKeyParam } from './query-errors';
 import { RunQueryExecuteOptions } from './query-execute-utils';
 
 export type QueryRepositoryRequestOptions<TArgs extends QueryArgs> = {
@@ -88,7 +88,7 @@ export const createQueryRepository = (config: QueryClientConfig): QueryRepositor
     const shouldCache = shouldCacheQuery(options.method);
 
     if (!shouldCache && options.key) throw uncacheableRequestHasCacheKeyParam(options.key);
-    if (!shouldCache && runQueryOptions?.skipCache) throw uncacheableRequestHasSkipCacheParam();
+    if (!shouldCache && runQueryOptions?.allowCache) throw uncacheableRequestHasAllowCacheParam();
 
     const route = buildRoute({
       base: config.baseUrl,
@@ -121,8 +121,8 @@ export const createQueryRepository = (config: QueryClientConfig): QueryRepositor
       if (cacheEntry) {
         bind(key, options.destroyRef, cacheEntry.request);
 
-        if (runQueryOptions?.skipCache || cacheEntry.request.isStale()) {
-          cacheEntry.request.execute({ skipCache: runQueryOptions?.skipCache });
+        if (!runQueryOptions?.allowCache || cacheEntry.request.isStale()) {
+          cacheEntry.request.execute({ allowCache: runQueryOptions?.allowCache });
         }
 
         return { key, request: cacheEntry.request as HttpRequest<TArgs> };

libs/query/src/lib/experimental/query-stack.ts

@@ -19,7 +19,7 @@ export type QueryStack<T extends AnyQuery, J = ReturnType<T['response']>[]> = {
   response: Signal<J>;
 
   /** Executes all queries in the stack. */
-  execute: (options?: { skipCache?: boolean }) => void;
+  execute: (options?: { allowCache?: boolean }) => void;
 
   /** Destroys all queries in the stack and empties it. This should only be used if `append` is true. */
   clear: () => void;
@@ -118,9 +118,9 @@ export const createQueryStack = <T extends AnyQuery, J = ReturnType<T['response'
     return transform?.(responses) ?? responses;
   }) as Signal<J>;
 
-  const execute = (options?: { skipCache?: boolean }) => {
+  const execute = (options?: { allowCache?: boolean }) => {
     for (const query of queries()) {
-      query.execute({ options: { skipCache: options?.skipCache } });
+      query.execute({ options: { allowCache: options?.allowCache } });
     }
   };