@mmstack/resource 20.4.1 → 20.5.1

package/index.d.ts

@@ -1,4 +1,4 @@
-import { HttpResponse, HttpInterceptorFn, HttpContext, HttpResourceOptions, HttpResourceRequest, HttpResourceRef, HttpHeaders } from '@angular/common/http';
+import { HttpResponse, HttpInterceptorFn, HttpContext, HttpResourceRef, HttpHeaders, HttpResourceRequest, HttpResourceOptions } from '@angular/common/http';
 import { Signal, Injector, Provider, WritableSignal, ValueEqualityFn } from '@angular/core';
 
 type StoredEntry<T> = Omit<CacheEntry<T>, 'timeout'>;
@@ -516,16 +516,27 @@ type QueryResourceRef<TResult> = Omit<HttpResourceRef<TResult>, 'headers' | 'sta
      * @param req - Optional partial request parameters to use for the prefetch.  This allows you
      *              to prefetch data with different parameters than the main resource request.
      */
-    prefetch: (req?: Partial<HttpResourceRequest>) => Promise<void>;
+    prefetch: (req?: Partial<HttpResourceRequest> | string) => Promise<void>;
 };
-declare function queryResource<TResult, TRaw = TResult>(request: () => HttpResourceRequest | undefined | void, options: QueryResourceOptions<TResult, TRaw> & {
+/**
+ * Creates an HTTP resource with features like caching, retries, refresh intervals, circuit breaker, and optimistic updates. Without additional options it is equivalent to simply calling `httpResource`.
+ * This overload is for when a `defaultValue` is provided, ensuring that the resource's value is always defined.
+ * @param request A function that returns the `HttpResourceRequest` or a URL string to be made.  This function
+ *               is called reactively, so the request can change over time.  If the function
+ *              returns `undefined`, the resource is considered "disabled" and no request will be made.
+ * @param options Configuration options for the resource.  These options extend the basic
+ *               `HttpResourceOptions` and add features like `keepPrevious`, `refresh`, `retry`,
+ *                `onError`, `circuitBreaker`, and `cache`.  Additionally, when a `defaultValue` is provided, the resource's value will always be defined, even if the underlying HTTP request fails or is disabled.
+ * @returns An `QueryResourceRef` instance, which extends the basic `HttpResourceRef` with additional features.
+ */
+declare function queryResource<TResult, TRaw = TResult>(request: () => HttpResourceRequest | string | undefined | void, options: QueryResourceOptions<TResult, TRaw> & {
     defaultValue: NoInfer<TResult>;
 }): QueryResourceRef<TResult>;
 /**
  * Creates an extended HTTP resource with features like caching, retries, refresh intervals,
  * circuit breaker, and optimistic updates. Without additional options it is equivalent to simply calling `httpResource`.
  *
- * @param request A function that returns the `HttpResourceRequest` to be made.  This function
+ * @param request A function that returns the `HttpResourceRequest` or a URL string to be made.  This function
  *                is called reactively, so the request can change over time.  If the function
  *                returns `undefined`, the resource is considered "disabled" and no request will be made.
  * @param options Configuration options for the resource.  These options extend the basic
@@ -533,7 +544,43 @@ declare function queryResource<TResult, TRaw = TResult>(request: () => HttpResou
  *                `onError`, `circuitBreaker`, and `cache`.
  * @returns An `QueryResourceRef` instance, which extends the basic `HttpResourceRef` with additional features.
  */
-declare function queryResource<TResult, TRaw = TResult>(request: () => HttpResourceRequest | undefined | void, options?: QueryResourceOptions<TResult, TRaw>): QueryResourceRef<TResult | undefined>;
+declare function queryResource<TResult, TRaw = TResult>(request: () => HttpResourceRequest | string | undefined | void, options?: QueryResourceOptions<TResult, TRaw>): QueryResourceRef<TResult | undefined>;
+
+/**
+ * A reference to a manually triggered query resource.  This type extends the standard `QueryResourceRef`
+ * with an additional `trigger` method that allows you to manually trigger the resource request.
+ * @see QueryResourceRef
+ */
+type ManualQueryResourceRef<TResult> = QueryResourceRef<TResult> & {
+    trigger: (req?: HttpResourceRequest | string, injector?: Injector) => Promise<TResult>;
+};
+/**
+ * Creates a manually triggered HTTP resource with features like caching, retries, refresh intervals, circuit breaker, and optimistic updates. Without additional options it is equivalent to simply calling `httpResource`.
+ * This overload is for when a `defaultValue` is provided, ensuring that the resource's value is always defined.
+ * @param request A function that returns the `HttpResourceRequest` or a URL string to be made.  This function
+ *               is called reactively, so the request can change over time.  If the function
+ *              returns `undefined`, the resource is considered "disabled" and no request will be made.
+ * @param options Configuration options for the resource.  These options extend the basic
+ *               `HttpResourceOptions` and add features like `keepPrevious`, `refresh`, `retry`,
+ *                `onError`, `circuitBreaker`, and `cache`.  Additionally, when a `defaultValue` is provided, the resource's value will always be defined, even if the underlying HTTP request fails or is disabled.
+ * @returns An `ManualQueryResourceRef` instance, which extends the basic `QueryResourceRef` with additional features.
+ */
+declare function manualQueryResource<TResult, TRaw = TResult>(request: () => HttpResourceRequest | string | undefined | void, options: QueryResourceOptions<TResult, TRaw> & {
+    defaultValue: NoInfer<TResult>;
+}): ManualQueryResourceRef<TResult>;
+/**
+ * Creates a manually triggered extended HTTP resource with features like caching, retries, refresh intervals,
+ * circuit breaker, and optimistic updates. Without additional options it is equivalent to simply calling `httpResource`.
+ *
+ * @param request A function that returns the `HttpResourceRequest` or a URL string to be made.  This function
+ *                is called reactively, so the request can change over time.  If the function
+ *                returns `undefined`, the resource is considered "disabled" and no request will be made.
+ * @param options Configuration options for the resource.  These options extend the basic
+ *                `HttpResourceOptions` and add features like `keepPrevious`, `refresh`, `retry`,
+ *                `onError`, `circuitBreaker`, and `cache`.
+ * @returns An `ManualQueryResourceRef` instance, which extends the basic `QueryResourceRef` with additional features.
+ */
+declare function manualQueryResource<TResult, TRaw = TResult>(request: () => HttpResourceRequest | string | undefined | void, options?: QueryResourceOptions<TResult, TRaw>): ManualQueryResourceRef<TResult | undefined>;
 
 /**
  * @internal
@@ -552,7 +599,7 @@ type NextRequest<TMethod extends HttpResourceRequest['method'], TMutation> = TMe
  * @typeParam TRaw - The raw response type from the HTTP request (defaults to TResult).
  * @typeParam TCTX - The type of the context value returned by `onMutate`.
  */
-type MutationResourceOptions<TResult, TRaw = TResult, TMutation = TResult, TCTX = void, TICTX = TCTX> = Omit<QueryResourceOptions<TResult, TRaw>, 'equal' | 'onError' | 'keepPrevious' | 'refresh' | 'cache'> & {
+type MutationResourceOptions<TResult, TRaw = TResult, TMutation = TResult, TCTX = void, TICTX = TCTX, TError = unknown> = Omit<QueryResourceOptions<TResult, TRaw>, 'equal' | 'onError' | 'keepPrevious' | 'refresh' | 'cache'> & {
     /**
      * A callback function that is called before the mutation request is made.
      * @param value The value being mutated (the `body` of the request).
@@ -565,13 +612,13 @@ type MutationResourceOptions<TResult, TRaw = TResult, TMutation = TResult, TCTX
      * @param error The error that occurred.
      * @param ctx The context value returned by the `onMutate` callback (or `undefined` if `onMutate` was not provided or returned `undefined`).
      */
-    onError?: (error: unknown, ctx: NoInfer<TCTX>) => void;
+    onError?: (error: TError, ctx: NoInfer<TCTX>) => void;
     /**
      * A callback function that is called if the mutation request succeeds.
      * @param value The result of the mutation (the parsed response body).
      * @param ctx The context value returned by the `onMutate` callback (or `undefined` if `onMutate` was not provided or returned `undefined`).
      */
-    onSuccess?: (value: NoInfer<TResult>, ctx: NoInfer<TCTX>) => void;
+    onSuccess?: (value: TResult, ctx: NoInfer<TCTX>) => void;
     /**
      * A callback function that is called when the mutation request settles (either succeeds or fails).
      * @param ctx The context value returned by the `onMutate` callback (or `undefined` if `onMutate` was not provided or returned `undefined`).
@@ -625,5 +672,5 @@ type MutationResourceRef<TResult, TMutation = TResult, TICTX = void> = Omit<Quer
  */
 declare function mutationResource<TResult, TRaw = TResult, TMutation = TResult, TCTX = void, TICTX = TCTX, TMethod extends HttpResourceRequest['method'] = HttpResourceRequest['method']>(request: (params: TMutation) => Omit<NextRequest<TMethod, TMutation>, 'body'> | undefined | void, options?: MutationResourceOptions<TResult, TRaw, TMutation, TCTX, TICTX>): MutationResourceRef<TResult, TMutation, TICTX>;
 
-export { Cache, createCacheInterceptor, createCircuitBreaker, createDedupeRequestsInterceptor, injectQueryCache, mutationResource, noDedupe, provideCircuitBreakerDefaultOptions, provideQueryCache, queryResource };
-export type { MutationResourceOptions, MutationResourceRef, QueryResourceOptions, QueryResourceRef };
+export { Cache, createCacheInterceptor, createCircuitBreaker, createDedupeRequestsInterceptor, injectQueryCache, manualQueryResource, mutationResource, noDedupe, provideCircuitBreakerDefaultOptions, provideQueryCache, queryResource };
+export type { ManualQueryResourceRef, MutationResourceOptions, MutationResourceRef, QueryResourceOptions, QueryResourceRef };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mmstack/resource",
-  "version": "20.4.1",
+  "version": "20.5.1",
   "keywords": [
     "angular",
     "signals",
@@ -17,7 +17,7 @@
   },
   "homepage": "https://github.com/mihajm/mmstack/blob/master/packages/resource",
   "dependencies": {
-    "@mmstack/primitives": "^20.4.1",
+    "@mmstack/primitives": "^20.5.0",
     "tslib": "^2.3.0"
   },
   "peerDependencies": {