@mmstack/resource 20.4.0 → 20.5.0

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2025-present Miha J. Mulec
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2025-present Miha J. Mulec
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,120 +1,120 @@
-# @mmstack/resource
-
-[![npm version](https://badge.fury.io/js/%40mmstack%2Fresource.svg)](https://www.npmjs.com/package/@mmstack/resource)
-[![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/mihajm/mmstack/blob/master/packages/resource/LICENSE)
-
-`@mmstack/resource` is an Angular library that provides powerful, signal-based primitives for managing asynchronous data fetching and mutations. It builds upon Angular's `httpResource` and offers features like caching, retries, refresh intervals, circuit breakers, and request deduplication, all while maintaining a fine-grained reactive graph. It's inspired by libraries like TanStack Query, but aims for a more Angular-idiomatic and signal-centric approach.
-
-## Features
-
-- **Signal-Based:** Fully integrates with Angular's signal system for efficient change detection and reactivity.
-- **Caching:** Built-in caching with configurable TTL (Time To Live) and stale-while-revalidate behavior. Supports custom cache key generation and respects HTTP caching headers.
-- **Retries:** Automatic retries on failure with configurable backoff strategies.
-- **Refresh Intervals:** Automatically refetch data at specified intervals.
-- **Circuit Breaker:** Protects your application from cascading failures by temporarily disabling requests to failing endpoints.
-- **Request Deduplication:** Avoids making multiple identical requests concurrently.
-- **Mutations:** Provides a dedicated `mutationResource` for handling data modifications, with callbacks for `onMutate`, `onError`, `onSuccess`, and `onSettled`.
-- **Prefetching:** Allows you to prefetch data into the cache, improving perceived performance.
-- **Extensible:** Designed to be modular and extensible. You can easily add your own custom features or integrate with other libraries.
-- **TypeScript Support:** A strong focus on typesafety
-
-## Quick Start
-
-1. Install mmstack-resource
-
-```bash
-npm install @mmstack/resource
-```
-
-2. Initialize the QueryCache & interceptors (optional)
-
-```typescript
-import { provideHttpClient, withInterceptors } from '@angular/common/http';
-import { ApplicationConfig } from '@angular/core';
-import { createCacheInterceptor, createDedupeRequestsInterceptor, provideQueryCache } from '@mmstack/resource';
-
-export const appConfig: ApplicationConfig = {
-  providers: [
-    // ..other providers
-    provideQueryCache(),
-
-    // --- Example of a more advanced setup ---
-    // provideQueryCache({
-    //   persist: true, // Enable IndexedDB persistence
-    //   version: 1,    // Version for the cache schema
-    //   syncTabs: true // enable BroadcastChannel
-    // }),
-
-    provideHttpClient(withInterceptors([createCacheInterceptor(), createDedupeRequestsInterceptor()])),
-  ],
-};
-```
-
-3. Use it :)
-
-```typescript
-import { Injectable, isDevMode, untracked } from '@angular/core';
-import { createCircuitBreaker, mutationResource, queryResource } from '@mmstack/resource';
-
-type Post = {
-  userId: number;
-  id: number;
-  title: string;
-  body: string;
-};
-
-@Injectable({
-  providedIn: 'root',
-})
-export class PostsService {
-  private readonly endpoint = 'https://jsonplaceholder.typicode.com/posts';
-  private readonly cb = createCircuitBreaker();
-  readonly posts = queryResource<Post[]>(
-    () => ({
-      url: this.endpoint,
-    }),
-    {
-      keepPrevious: true, // keep data between requests
-      refresh: 5 * 60 * 1000, // refresh every 5 minutes
-      circuitBreaker: this.cb, // use shared circuit breaker use true if not sharing
-      retry: 3, // retry 3 times on error using default backoff
-      onError: (err) => {
-        if (!isDevMode()) return;
-        console.error(err);
-      }, // log errors in dev mode
-      defaultValue: [],
-    },
-  );
-
-  private readonly createPostResource = mutationResource(
-    (post: Post) => ({
-      url: this.endpoint,
-      method: 'POST',
-      body: post,
-    }),
-    {
-      circuitBreaker: this.cb, // use shared circuit breaker use true if not sharing
-      onMutate: (post: Post) => {
-        const prev = untracked(this.posts.value);
-        this.posts.set([...prev, post]); // optimistically update
-        return prev;
-      },
-      onError: (err, prev) => {
-        if (isDevMode()) console.error(err);
-        this.posts.set(prev); // rollback on error
-      },
-      onSuccess: (next) => {
-        this.posts.update((posts) => posts.map((p) => (p.id === next.id ? next : p))); // replace with value from server
-      },
-    },
-  );
-
-  createPost(post: Post) {
-    this.createPostResource.mutate(post); // send the request
-  }
-}
-```
-
-## In-depth
-
-For an in-depth explanation of the primitives & how they work check out this article: [Fun-grained Reactivity in Angular: Part 3 - Resources](https://dev.to/mihamulec/fun-grained-reactivity-in-angular-part-3-client-side-http-57g4)
+# @mmstack/resource
+
+[![npm version](https://badge.fury.io/js/%40mmstack%2Fresource.svg)](https://www.npmjs.com/package/@mmstack/resource)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/mihajm/mmstack/blob/master/packages/resource/LICENSE)
+
+`@mmstack/resource` is an Angular library that provides powerful, signal-based primitives for managing asynchronous data fetching and mutations. It builds upon Angular's `httpResource` and offers features like caching, retries, refresh intervals, circuit breakers, and request deduplication, all while maintaining a fine-grained reactive graph. It's inspired by libraries like TanStack Query, but aims for a more Angular-idiomatic and signal-centric approach.
+
+## Features
+
+- **Signal-Based:** Fully integrates with Angular's signal system for efficient change detection and reactivity.
+- **Caching:** Built-in caching with configurable TTL (Time To Live) and stale-while-revalidate behavior. Supports custom cache key generation and respects HTTP caching headers.
+- **Retries:** Automatic retries on failure with configurable backoff strategies.
+- **Refresh Intervals:** Automatically refetch data at specified intervals.
+- **Circuit Breaker:** Protects your application from cascading failures by temporarily disabling requests to failing endpoints.
+- **Request Deduplication:** Avoids making multiple identical requests concurrently.
+- **Mutations:** Provides a dedicated `mutationResource` for handling data modifications, with callbacks for `onMutate`, `onError`, `onSuccess`, and `onSettled`.
+- **Prefetching:** Allows you to prefetch data into the cache, improving perceived performance.
+- **Extensible:** Designed to be modular and extensible. You can easily add your own custom features or integrate with other libraries.
+- **TypeScript Support:** A strong focus on typesafety
+
+## Quick Start
+
+1. Install mmstack-resource
+
+```bash
+npm install @mmstack/resource
+```
+
+2. Initialize the QueryCache & interceptors (optional)
+
+```typescript
+import { provideHttpClient, withInterceptors } from '@angular/common/http';
+import { ApplicationConfig } from '@angular/core';
+import { createCacheInterceptor, createDedupeRequestsInterceptor, provideQueryCache } from '@mmstack/resource';
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    // ..other providers
+    provideQueryCache(),
+
+    // --- Example of a more advanced setup ---
+    // provideQueryCache({
+    //   persist: true, // Enable IndexedDB persistence
+    //   version: 1,    // Version for the cache schema
+    //   syncTabs: true // enable BroadcastChannel
+    // }),
+
+    provideHttpClient(withInterceptors([createCacheInterceptor(), createDedupeRequestsInterceptor()])),
+  ],
+};
+```
+
+3. Use it :)
+
+```typescript
+import { Injectable, isDevMode, untracked } from '@angular/core';
+import { createCircuitBreaker, mutationResource, queryResource } from '@mmstack/resource';
+
+type Post = {
+  userId: number;
+  id: number;
+  title: string;
+  body: string;
+};
+
+@Injectable({
+  providedIn: 'root',
+})
+export class PostsService {
+  private readonly endpoint = 'https://jsonplaceholder.typicode.com/posts';
+  private readonly cb = createCircuitBreaker();
+  readonly posts = queryResource<Post[]>(
+    () => ({
+      url: this.endpoint,
+    }),
+    {
+      keepPrevious: true, // keep data between requests
+      refresh: 5 * 60 * 1000, // refresh every 5 minutes
+      circuitBreaker: this.cb, // use shared circuit breaker use true if not sharing
+      retry: 3, // retry 3 times on error using default backoff
+      onError: (err) => {
+        if (!isDevMode()) return;
+        console.error(err);
+      }, // log errors in dev mode
+      defaultValue: [],
+    },
+  );
+
+  private readonly createPostResource = mutationResource(
+    (post: Post) => ({
+      url: this.endpoint,
+      method: 'POST',
+      body: post,
+    }),
+    {
+      circuitBreaker: this.cb, // use shared circuit breaker use true if not sharing
+      onMutate: (post: Post) => {
+        const prev = untracked(this.posts.value);
+        this.posts.set([...prev, post]); // optimistically update
+        return prev;
+      },
+      onError: (err, prev) => {
+        if (isDevMode()) console.error(err);
+        this.posts.set(prev); // rollback on error
+      },
+      onSuccess: (next) => {
+        this.posts.update((posts) => posts.map((p) => (p.id === next.id ? next : p))); // replace with value from server
+      },
+    },
+  );
+
+  createPost(post: Post) {
+    this.createPostResource.mutate(post); // send the request
+  }
+}
+```
+
+## In-depth
+
+For an in-depth explanation of the primitives & how they work check out this article: [Fun-grained Reactivity in Angular: Part 3 - Resources](https://dev.to/mihamulec/fun-grained-reactivity-in-angular-part-3-client-side-http-57g4)

package/fesm2022/mmstack-resource.mjs

@@ -1,9 +1,9 @@
 import * as i0 from '@angular/core';
 import { isDevMode, untracked, computed, InjectionToken, inject, signal, effect, Injector, linkedSignal, Injectable, DestroyRef } from '@angular/core';
-import { takeUntilDestroyed, toObservable } from '@angular/core/rxjs-interop';
-import { of, tap, map, finalize, shareReplay, interval, firstValueFrom, catchError, combineLatestWith, filter } from 'rxjs';
+import { mutable, toWritable, sensor, nestedEffect } from '@mmstack/primitives';
 import { HttpHeaders, HttpResponse, HttpContextToken, HttpContext, HttpParams, httpResource, HttpClient } from '@angular/common/http';
-import { mutable, toWritable, sensor } from '@mmstack/primitives';
+import { of, tap, map, finalize, shareReplay, interval, firstValueFrom, catchError, combineLatestWith, filter } from 'rxjs';
+import { takeUntilDestroyed, toObservable } from '@angular/core/rxjs-interop';
 
 function createNoopDB() {
     return {
@@ -945,7 +945,12 @@ function createDedupeRequestsInterceptor(allowed = ['GET', 'DELETE', 'HEAD', 'OP
  * isPlainObject(new Date()) // => false
  */
 function isPlainObject(value) {
-    return (typeof value === 'object' && value !== null && value.constructor === Object);
+    if (value === null || typeof value !== 'object')
+        return false;
+    const proto = Object.getPrototypeOf(value);
+    if (proto === null)
+        return false; // remove Object.create(null);
+    return proto === Object.prototype;
 }
 /**
  * Internal helper to generate a stable JSON string from an array.
@@ -1173,15 +1178,21 @@ function hasSlowConnection() {
 
 function persist(src, equal) {
     // linkedSignal allows us to access previous source value
-    const persisted = linkedSignal({
-        source: () => src(),
-        computation: (next, prev) => {
-            if (next === undefined && prev !== undefined)
-                return prev.value;
-            return next;
-        },
-        equal,
-    });
+    const persisted = linkedSignal(...(ngDevMode ? [{ debugName: "persisted", source: () => src(),
+            computation: (next, prev) => {
+                if (next === undefined && prev !== undefined)
+                    return prev.value;
+                return next;
+            },
+            equal }] : [{
+            source: () => src(),
+            computation: (next, prev) => {
+                if (next === undefined && prev !== undefined)
+                    return prev.value;
+                return next;
+            },
+            equal,
+        }]));
     // if original value was WritableSignal then override linkedSignal methods to original...angular uses linkedSignal under the hood in ResourceImpl, this applies to that.
     if ('set' in src) {
         persisted.set = src.set;
@@ -1266,10 +1277,10 @@ function retryOnError(res, opt) {
 
 class ResourceSensors {
     networkStatus = sensor('networkStatus');
-    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "20.1.0", ngImport: i0, type: ResourceSensors, deps: [], target: i0.ɵɵFactoryTarget.Injectable });
-    static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "20.1.0", ngImport: i0, type: ResourceSensors, providedIn: 'root' });
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "20.3.17", ngImport: i0, type: ResourceSensors, deps: [], target: i0.ɵɵFactoryTarget.Injectable });
+    static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "20.3.17", ngImport: i0, type: ResourceSensors, providedIn: 'root' });
 }
-i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.1.0", ngImport: i0, type: ResourceSensors, decorators: [{
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.17", ngImport: i0, type: ResourceSensors, decorators: [{
             type: Injectable,
             args: [{
                     providedIn: 'root',
@@ -1335,7 +1346,12 @@ function queryResource(request, options) {
     const stableRequest = computed(() => {
         if (!networkAvailable() || cb.isOpen())
             return undefined;
-        return request() ?? undefined;
+        const req = request();
+        if (!req)
+            return undefined;
+        if (typeof req === 'string')
+            return { method: 'GET', url: req };
+        return req;
     }, ...(ngDevMode ? [{ debugName: "stableRequest", equal: (a, b) => {
                 if (eq)
                     return eq(a, b);
@@ -1388,27 +1404,45 @@ function queryResource(request, options) {
     resource = catchValueError(resource, options?.defaultValue);
     // get full HttpResonse from Cache
     const cachedEvent = cache.getEntryOrKey(cacheKey);
-    const cacheEntry = linkedSignal({
-        source: () => cachedEvent(),
-        computation: (entry, prev) => {
-            if (!entry)
-                return null;
-            if (typeof entry === 'string' &&
-                prev &&
-                prev.value !== null &&
-                prev.value.key === entry) {
-                return prev.value;
-            }
-            if (typeof entry === 'string')
-                return { key: entry, value: null };
-            if (!(entry.value instanceof HttpResponse))
-                return { key: entry.key, value: null };
-            return {
-                value: entry.value.body,
-                key: entry.key,
-            };
-        },
-    });
+    const cacheEntry = linkedSignal(...(ngDevMode ? [{ debugName: "cacheEntry", source: () => cachedEvent(),
+            computation: (entry, prev) => {
+                if (!entry)
+                    return null;
+                if (typeof entry === 'string' &&
+                    prev &&
+                    prev.value !== null &&
+                    prev.value.key === entry) {
+                    return prev.value;
+                }
+                if (typeof entry === 'string')
+                    return { key: entry, value: null };
+                if (!(entry.value instanceof HttpResponse))
+                    return { key: entry.key, value: null };
+                return {
+                    value: entry.value.body,
+                    key: entry.key,
+                };
+            } }] : [{
+            source: () => cachedEvent(),
+            computation: (entry, prev) => {
+                if (!entry)
+                    return null;
+                if (typeof entry === 'string' &&
+                    prev &&
+                    prev.value !== null &&
+                    prev.value.key === entry) {
+                    return prev.value;
+                }
+                if (typeof entry === 'string')
+                    return { key: entry, value: null };
+                if (!(entry.value instanceof HttpResponse))
+                    return { key: entry.key, value: null };
+                return {
+                    value: entry.value.body,
+                    key: entry.key,
+                };
+            },
+        }]));
     resource = refresh(resource, destroyRef, options?.refresh);
     resource = retryOnError(resource, options?.retry);
     resource = persistResourceValues(resource, options?.keepPrevious, options?.equal);
@@ -1477,9 +1511,10 @@ function queryResource(request, options) {
             if (!options?.cache || hasSlowConnection())
                 return Promise.resolve();
             const request = untracked(stableRequest);
+            const partialReq = typeof partial === 'string' ? { method: 'GET', url: partial } : partial;
             const prefetchRequest = {
                 ...request,
-                ...partial,
+                ...partialReq,
             };
             if (!prefetchRequest.url)
                 return Promise.resolve();
@@ -1523,6 +1558,46 @@ function queryResource(request, options) {
     };
 }
 
+function manualQueryResource(request, options) {
+    const trigger = signal({ epoch: 0 }, ...(ngDevMode ? [{ debugName: "trigger", equal: (a, b) => a.epoch === b.epoch }] : [{
+            equal: (a, b) => a.epoch === b.epoch,
+        }]));
+    const injector = options?.injector ?? inject(Injector);
+    const req = computed(() => {
+        const state = trigger();
+        if (state.epoch === 0)
+            return;
+        if (state.override)
+            return state.override;
+        return untracked(request);
+    }, ...(ngDevMode ? [{ debugName: "req", equal: () => false }] : [{
+            equal: () => false,
+        }]));
+    const resource = queryResource(req, options);
+    return {
+        ...resource,
+        trigger: (override, injectorOverride) => {
+            trigger.update((s) => ({
+                epoch: s.epoch + 1,
+                override,
+            }));
+            return new Promise((res, rej) => {
+                const watcher = nestedEffect(() => {
+                    const status = resource.status();
+                    if (status === 'resolved') {
+                        watcher.destroy();
+                        res(untracked(resource.value));
+                    }
+                    else if (status === 'error') {
+                        watcher.destroy();
+                        rej(untracked(resource.error));
+                    }
+                }, { injector: injectorOverride ?? injector });
+            });
+        },
+    };
+}
+
 /**
  * Creates a resource for performing mutations (e.g., POST, PUT, PATCH, DELETE requests).
  * Unlike `queryResource`, `mutationResource` is designed for one-off operations that change data.
@@ -1580,14 +1655,19 @@ function mutationResource(request, options = {}) {
     }, ...(ngDevMode ? [{ debugName: "req", equal: requestEqual }] : [{
             equal: requestEqual,
         }]));
-    const lastValue = linkedSignal({
-        source: next,
-        computation: (next, prev) => {
-            if (next === null && !!prev)
-                return prev.value;
-            return next;
-        },
-    });
+    const lastValue = linkedSignal(...(ngDevMode ? [{ debugName: "lastValue", source: next,
+            computation: (next, prev) => {
+                if (next === null && !!prev)
+                    return prev.value;
+                return next;
+            } }] : [{
+            source: next,
+            computation: (next, prev) => {
+                if (next === null && !!prev)
+                    return prev.value;
+                return next;
+            },
+        }]));
     const lastValueRequest = computed(() => {
         const nr = lastValue();
         if (!nr)
@@ -1661,5 +1741,5 @@ function mutationResource(request, options = {}) {
  * Generated bundle index. Do not edit.
  */
 
-export { Cache, createCacheInterceptor, createCircuitBreaker, createDedupeRequestsInterceptor, injectQueryCache, mutationResource, noDedupe, provideCircuitBreakerDefaultOptions, provideQueryCache, queryResource };
+export { Cache, createCacheInterceptor, createCircuitBreaker, createDedupeRequestsInterceptor, injectQueryCache, manualQueryResource, mutationResource, noDedupe, provideCircuitBreakerDefaultOptions, provideQueryCache, queryResource };
 //# sourceMappingURL=mmstack-resource.mjs.map