@mmstack/resource 21.1.2 → 21.2.1

package/README.md

@@ -123,15 +123,15 @@ All three return a signal-typed ref — `value()`, `status()`, `error()`, `heade
 
 When the cache interceptor is registered (`createCacheInterceptor()`) and a query resource opts in via `cache`, responses are stored in the shared `Cache` keyed by a string derived from the request.
 
-**Default key**: `${method} ${urlWithParams(request)}` — produced by `urlWithParams()` (`util/url-with-params.ts:24`). It includes method, URL path, and sorted query params. **It does not include headers, body, or `HttpContext`.**
+**Default key**: produced by `hashRequest()` (`util/hash-request.ts`). Composition is `${method}:${url}:${responseType}[:${params}][:${body}]` — sorted query params, stable body hashing (incl. `File`/`Blob`/`FormData`/`URLSearchParams`/`ArrayBuffer` markers). **It does not include headers or `HttpContext`.**
 
-If two requests should _not_ share a cache entry but the default key would collide (e.g. different `Authorization` headers, request body in a GET-equivalent POST), pass a custom hash:
+If two requests should _not_ share a cache entry but the default key would collide (e.g. different `Authorization` headers), pass a custom hash:
 
 ```typescript
 queryResource<Post>(() => ({ url, headers }), {
   cache: {
     hash: (req) =>
-      `${req.method}:${req.urlWithParams}:${req.headers.get('Authorization') ?? ''}`,
+      `${hashRequest(req)}:${(req.headers as HttpHeaders | undefined)?.get('Authorization') ?? ''}`,
   },
 });
 ```
@@ -321,7 +321,7 @@ provideQueryCache({
 | -------------------- | ------------------------ | -------------------------------------------------------------------------------------------------------------------- |
 | `staleTime`          | from `provideQueryCache` | Per-resource override.                                                                                               |
 | `ttl`                | from `provideQueryCache` | Per-resource override.                                                                                               |
-| `hash`               | `urlWithParams`          | Custom cache key function. See [cache + cache keys](#cache--cache-keys).                                             |
+| `hash`               | `hashRequest`            | Custom cache key function. See [cache + cache keys](#cache--cache-keys).                                             |
 | `persist`            | `false`                  | Mirror this resource's responses to IndexedDB (only effective if the cache itself was created with `persist: true`). |
 | `ignoreCacheControl` | `false`                  | Ignore HTTP `Cache-Control` directives and use only `staleTime`/`ttl`.                                               |
 

package/fesm2022/mmstack-resource.mjs

@@ -1,4 +1,4 @@
-import { HttpHeaders, HttpResponse, HttpContextToken, HttpContext, HttpParams, httpResource, HttpClient } from '@angular/common/http';
+import { HttpHeaders, HttpResponse, HttpParams, HttpContextToken, HttpContext, httpResource, HttpClient } from '@angular/common/http';
 import * as i0 from '@angular/core';
 import { isDevMode, untracked, computed, InjectionToken, inject, signal, effect, Injector, linkedSignal, Injectable, DestroyRef } from '@angular/core';
 import { mutable, toWritable, sensor, nestedEffect } from '@mmstack/primitives';
@@ -551,6 +551,173 @@ function injectQueryCache(injector) {
     return cache;
 }
 
+/**
+ * Returns `true` for any object-like value whose own enumerable keys should
+ * be sorted for stable hashing. Excludes arrays (positional), `Date`
+ * (handled by `toJSON`), `Map`/`Set` (handled explicitly), and binary types
+ * (`Blob`/`FormData`/`URLSearchParams`/`ArrayBuffer`/typed arrays — these
+ * should be branched on before reaching `hash()`, typically by `hashRequest`).
+ *
+ * Plain objects, class instances, and `Object.create(null)` all qualify.
+ */
+function isHashableObject(value) {
+    if (value === null || typeof value !== 'object')
+        return false;
+    if (Array.isArray(value))
+        return false;
+    if (value instanceof Date)
+        return false;
+    if (value instanceof Map)
+        return false;
+    if (value instanceof Set)
+        return false;
+    if (typeof Blob !== 'undefined' && value instanceof Blob)
+        return false;
+    if (typeof FormData !== 'undefined' && value instanceof FormData)
+        return false;
+    if (typeof URLSearchParams !== 'undefined' &&
+        value instanceof URLSearchParams)
+        return false;
+    if (value instanceof ArrayBuffer)
+        return false;
+    if (ArrayBuffer.isView(value))
+        return false;
+    return true;
+}
+function sortKeys(val) {
+    return Object.keys(val)
+        .toSorted()
+        .reduce((result, key) => {
+        result[key] = val[key];
+        return result;
+    }, {});
+}
+/**
+ * Internal helper to generate a stable JSON string from an array.
+ * - Object-like values (plain, class instances, null-proto) get their own
+ *   enumerable keys sorted alphabetically.
+ * - `Map` → marker object with sorted entries (sorted by `JSON.stringify(key)`).
+ * - `Set` → marker object with sorted values (sorted by `JSON.stringify(value)`).
+ * - Arrays preserve order. `Date` serializes via `toJSON`.
+ *
+ * @internal
+ */
+function hashKey(queryKey) {
+    return JSON.stringify(queryKey, (_, val) => {
+        if (val instanceof Map) {
+            // Schwartzian: compute each entry's sort key (recursive hash of the
+            // Map key) once, then sort by the cheap string compare.
+            const entries = [...val.entries()]
+                .map((e) => [hash(e[0]), e])
+                .sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0))
+                .map(([, e]) => e);
+            return { __map__: entries };
+        }
+        if (val instanceof Set) {
+            const values = [...val]
+                .map((v) => [hash(v), v])
+                .sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0))
+                .map(([, v]) => v);
+            return { __set__: values };
+        }
+        if (isHashableObject(val))
+            return sortKeys(val);
+        return val;
+    });
+}
+/**
+ * Generates a stable, unique string hash from one or more arguments.
+ * Useful for creating cache keys or identifiers where object key order shouldn't matter.
+ *
+ * How it works:
+ * - Object-like values (plain objects, class instances, `Object.create(null)`) have
+ *   their own enumerable keys sorted alphabetically before hashing. This ensures
+ *   `{ a: 1, b: 2 }` and `{ b: 2, a: 1 }` produce the same hash.
+ * - `Map` and `Set` are serialized via stable, sorted markers (`__map__` / `__set__`).
+ * - Arrays preserve positional order; `Date` uses its ISO string via `toJSON`.
+ *
+ * @param {...unknown} args Values to include in the hash.
+ * @returns A stable string hash representing the input arguments.
+ * @example
+ * hash('posts', 10);
+ * // => '["posts",10]'
+ *
+ * hash({ a: 1, b: 2 }) === hash({ b: 2, a: 1 }); // true
+ *
+ * hash(new Map([['a', 1]])) === hash(new Map([['a', 1]])); // true
+ *
+ * // Be mindful of values JSON.stringify cannot handle (functions, undefined, Symbols)
+ * // hash('a', undefined, function() {}) => '["a",null,null]'
+ */
+function hash(...args) {
+    return hashKey(args);
+}
+
+function normalizeParams(params) {
+    const p = params instanceof HttpParams
+        ? params
+        : new HttpParams({ fromObject: params });
+    return p
+        .keys()
+        .toSorted()
+        .map((key) => {
+        const encodedKey = encodeURIComponent(key);
+        return (p.getAll(key) ?? [])
+            .map((v) => `${encodedKey}=${encodeURIComponent(v)}`)
+            .join('&');
+    })
+        .join('&');
+}
+function hashBody(body) {
+    // File extends Blob — must check File first
+    if (typeof File !== 'undefined' && body instanceof File) {
+        return `File:${body.name}:${body.type}:${body.size}:${body.lastModified}`;
+    }
+    if (typeof Blob !== 'undefined' && body instanceof Blob) {
+        return `Blob:${body.type}:${body.size}`;
+    }
+    if (typeof FormData !== 'undefined' && body instanceof FormData) {
+        const entries = [];
+        body.forEach((value, key) => {
+            entries.push([key, hashBody(value)]);
+        });
+        entries.sort(([ak, av], [bk, bv]) => ak.localeCompare(bk) || av.localeCompare(bv));
+        return `FormData:${entries.map(([k, v]) => `${k}=${v}`).join('&')}`;
+    }
+    if (typeof URLSearchParams !== 'undefined' &&
+        body instanceof URLSearchParams) {
+        const sp = new URLSearchParams(body);
+        sp.sort();
+        return `URLSearchParams:${sp.toString()}`;
+    }
+    if (body instanceof ArrayBuffer) {
+        return `ArrayBuffer:${body.byteLength}`;
+    }
+    if (ArrayBuffer.isView(body)) {
+        return `${body.constructor.name}:${body.byteLength}`;
+    }
+    return hash(body);
+}
+/**
+ * Builds a stable cache/dedupe key from an HTTP request shape (accepts both
+ * `HttpRequest` and `HttpResourceRequest`).
+ *
+ * Key composition: `${method}:${url}:${responseType}[:${params}][:${body}]`
+ * - `method` defaults to `'GET'`, `responseType` to `'json'` (Angular defaults).
+ * - Query params are sorted alphabetically and URL-encoded for stability.
+ * - Body hashing handles `File`/`Blob`/`FormData`/`URLSearchParams`/`ArrayBuffer`
+ *   and typed arrays explicitly; everything else flows through key-sorted
+ *   `JSON.stringify` via `hash()`.
+ */
+function hashRequest(req) {
+    const method = req.method ?? 'GET';
+    const responseType = req.responseType ?? 'json';
+    const base = `${method}:${req.url}:${responseType}`;
+    const params = req.params ? `:${normalizeParams(req.params)}` : '';
+    const body = req.body != null ? `:${hashBody(req.body)}` : '';
+    return base + params + body;
+}
+
 const CACHE_CONTEXT = new HttpContextToken(() => ({
     cache: false,
 }));
@@ -694,7 +861,7 @@ function createCacheInterceptor(allowedMethods = ['GET', 'HEAD', 'OPTIONS']) {
         const opt = getCacheContext(req.context);
         if (!opt.cache)
             return next(req);
-        const key = opt.key ?? req.urlWithParams;
+        const key = opt.key ?? hashRequest(req);
         const entry = cache.getUntracked(key); // null if expired or not found
         // If the entry is not stale, return it
         if (entry && !entry.isStale)
@@ -977,6 +1144,9 @@ function noDedupe(ctx = new HttpContext()) {
  *
  * @param allowed - An array of HTTP methods for which deduplication should be enabled.
  *                  Defaults to `['GET', 'DELETE', 'HEAD', 'OPTIONS']`.
+ * @param keyFn - Optional function to compute the dedupe key from a request.
+ *                Defaults to `hashRequest`, which includes method, URL,
+ *                response type, params, and body.
  *
  * @returns An `HttpInterceptorFn` that implements the request deduplication logic.
  *
@@ -1000,97 +1170,22 @@ function noDedupe(ctx = new HttpContext()) {
  *   ],
  * };
  */
-function createDedupeRequestsInterceptor(allowed = ['GET', 'DELETE', 'HEAD', 'OPTIONS']) {
+function createDedupeRequestsInterceptor(allowed = ['GET', 'DELETE', 'HEAD', 'OPTIONS'], keyFn = hashRequest) {
     const inFlight = new Map();
     const DEDUPE_METHODS = new Set(allowed);
     return (req, next) => {
         if (!DEDUPE_METHODS.has(req.method) || req.context.get(NO_DEDUPE))
             return next(req);
-        const found = inFlight.get(req.urlWithParams);
+        const key = keyFn(req);
+        const found = inFlight.get(key);
         if (found)
             return found;
-        const request = next(req).pipe(finalize(() => inFlight.delete(req.urlWithParams)), shareReplay());
-        inFlight.set(req.urlWithParams, request);
+        const request = next(req).pipe(finalize(() => inFlight.delete(key)), shareReplay({ bufferSize: 1, refCount: true }));
+        inFlight.set(key, request);
         return request;
     };
 }
 
-/**
- * Checks if `value` is a plain JavaScript object (e.g., `{}` or `new Object()`).
- * Distinguishes from arrays, null, and class instances. Acts as a type predicate,
- * narrowing `value` to `UnknownObject` if `true`.
- *
- * @param value The value to check.
- * @returns {value is UnknownObject} `true` if `value` is a plain object, otherwise `false`.
- * @example
- * isPlainObject({}) // => true
- * isPlainObject([]) // => false
- * isPlainObject(null) // => false
- * isPlainObject(new Date()) // => false
- */
-function isPlainObject(value) {
-    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.
- * Sorts keys of plain objects within the array alphabetically before serialization
- * to ensure hash stability regardless of key order.
- *
- * @param queryKey The array of values to serialize.
- * @returns A stable JSON string representation.
- * @internal
- */
-function hashKey(queryKey) {
-    return JSON.stringify(queryKey, (_, val) => isPlainObject(val)
-        ? Object.keys(val)
-            .toSorted()
-            .reduce((result, key) => {
-            result[key] = val[key];
-            return result;
-        }, {})
-        : val);
-}
-/**
- * Generates a stable, unique string hash from one or more arguments.
- * Useful for creating cache keys or identifiers where object key order shouldn't matter.
- *
- * How it works:
- * - Plain objects within the arguments have their keys sorted alphabetically before hashing.
- * This ensures that `{ a: 1, b: 2 }` and `{ b: 2, a: 1 }` produce the same hash.
- * - Uses `JSON.stringify` internally with custom sorting for plain objects via `hashKey`.
- * - Non-plain objects (arrays, Dates, etc.) and primitives are serialized naturally.
- *
- * @param {...unknown} args Values to include in the hash.
- * @returns A stable string hash representing the input arguments.
- * @example
- * const userQuery = (id: number) => ['user', { id, timestamp: Date.now() }];
- *
- * const obj1 = { a: 1, b: 2 };
- * const obj2 = { b: 2, a: 1 }; // Same keys/values, different order
- *
- * hash('posts', 10);
- * // => '["posts",10]'
- *
- * hash('config', obj1);
- * // => '["config",{"a":1,"b":2}]'
- *
- * hash('config', obj2);
- * // => '["config",{"a":1,"b":2}]' (Same as above due to key sorting)
- *
- * hash(['todos', { status: 'done', owner: obj1 }]);
- * // => '[["todos",{"owner":{"a":1,"b":2},"status":"done"}]]'
- *
- * // Be mindful of values JSON.stringify cannot handle (functions, undefined, Symbols)
- * // hash('a', undefined, function() {}) => '["a",null,null]'
- */
-function hash(...args) {
-    return hashKey(args);
-}
 function equalTransferCache(a, b) {
     if (!a && !b)
         return true;
@@ -1330,7 +1425,7 @@ function retryOnError(res, opt, onError) {
         retries++;
         if (timeout)
             clearTimeout(timeout);
-        setTimeout(() => res.reload(), retries <= 0 ? 0 : backoff * Math.pow(2, retries - 1));
+        timeout = setTimeout(() => res.reload(), retries <= 0 ? 0 : backoff * Math.pow(2, retries - 1));
     };
     const onSuccess = () => {
         if (timeout)
@@ -1388,29 +1483,6 @@ function toResourceObject(res) {
     };
 }
 
-function normalizeParams(params) {
-    if (params instanceof HttpParams)
-        return params.toString();
-    const paramMap = new Map();
-    for (const [key, value] of Object.entries(params)) {
-        if (Array.isArray(value)) {
-            paramMap.set(key, value.map(encodeURIComponent).join(','));
-        }
-        else {
-            paramMap.set(key, encodeURIComponent(value.toString()));
-        }
-    }
-    return Array.from(paramMap.entries())
-        .sort(([a], [b]) => a.localeCompare(b))
-        .map(([key, value]) => `${key}=${value}`)
-        .join('&');
-}
-function urlWithParams(req) {
-    if (!req.params)
-        return req.url;
-    return `${req.url}?${normalizeParams(req.params)}`;
-}
-
 function queryResource(request, options) {
     const cache = injectQueryCache(options?.injector);
     const destroyRef = options?.injector
@@ -1448,8 +1520,8 @@ function queryResource(request, options) {
             return a === b;
         } });
     const hashFn = typeof options?.cache === 'object'
-        ? (options.cache.hash ?? urlWithParams)
-        : urlWithParams;
+        ? (options.cache.hash ?? hashRequest)
+        : hashRequest;
     const staleTime = typeof options?.cache === 'object' ? options.cache.staleTime : 0;
     const ttl = typeof options?.cache === 'object' ? options.cache.ttl : undefined;
     const cacheKey = computed(() => {
@@ -1646,6 +1718,7 @@ function manualQueryResource(request, options) {
     };
 }
 
+const NULL_VALUE = Symbol('@mmstack/resource:null');
 /**
  * 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.
@@ -1669,10 +1742,10 @@ function mutationResource(request, options = {}) {
     const { onMutate, onError, onSuccess, onSettled, equal, ...rest } = options;
     const requestEqual = createEqualRequest(equal);
     const eq = equal ?? Object.is;
-    const next = signal(null, { ...(ngDevMode ? { debugName: "next" } : /* istanbul ignore next */ {}), equal: (a, b) => {
-            if (!a && !b)
+    const next = signal(NULL_VALUE, { ...(ngDevMode ? { debugName: "next" } : /* istanbul ignore next */ {}), equal: (a, b) => {
+            if (a === NULL_VALUE && b === NULL_VALUE)
                 return true;
-            if (!a || !b)
+            if (a === NULL_VALUE || b === NULL_VALUE)
                 return false;
             return eq(a, b);
         } });
@@ -1680,28 +1753,36 @@ function mutationResource(request, options = {}) {
     let ctx = undefined;
     const queueRef = effect(() => {
         const nextInQueue = queue().at(0);
-        if (!nextInQueue || next() !== null)
+        if (nextInQueue === undefined || next() !== NULL_VALUE)
             return;
         queue.update((q) => q.slice(1));
         const [value, ictx] = nextInQueue;
-        ctx = onMutate?.(value, ictx);
-        next.set(value);
+        try {
+            ctx = onMutate?.(value, ictx);
+            next.set(value);
+        }
+        catch (mutationErr) {
+            ctx = undefined;
+            next.set(NULL_VALUE);
+            if (isDevMode())
+                console.error('[@mmstack/resource]: error thrown in onMutate hook, mutation was not applied', mutationErr);
+        }
     }, ...(ngDevMode ? [{ debugName: "queueRef" }] : /* istanbul ignore next */ []));
     const req = computed(() => {
         const nr = next();
-        if (!nr)
+        if (nr === NULL_VALUE)
             return;
         return request(nr) ?? undefined;
     }, { ...(ngDevMode ? { debugName: "req" } : /* istanbul ignore next */ {}), equal: requestEqual });
     const lastValue = linkedSignal({ ...(ngDevMode ? { debugName: "lastValue" } : /* istanbul ignore next */ {}), source: next,
         computation: (next, prev) => {
-            if (next === null && !!prev)
+            if (next === NULL_VALUE && !!prev)
                 return prev.value;
             return next;
         } });
     const lastValueRequest = computed(() => {
         const nr = lastValue();
-        if (!nr)
+        if (nr === NULL_VALUE)
             return;
         return request(nr) ?? undefined;
     }, { ...(ngDevMode ? { debugName: "lastValueRequest" } : /* istanbul ignore next */ {}), equal: requestEqual });
@@ -1711,13 +1792,13 @@ function mutationResource(request, options = {}) {
     const resource = queryResource(req, {
         ...rest,
         circuitBreaker: cb,
-        defaultValue: null, // doesnt matter since .value is not accessible
+        defaultValue: NULL_VALUE, // doesnt matter since .value is not accessible
     });
     const destroyRef = options.injector
         ? options.injector.get(DestroyRef)
         : inject(DestroyRef);
     const error$ = toObservable(resource.error);
-    const value$ = toObservable(resource.value).pipe(catchError(() => of(null)));
+    const value$ = toObservable(resource.value).pipe(catchError(() => of(NULL_VALUE)));
     const statusSub = toObservable(resource.status)
         .pipe(combineLatestWith(error$, value$), map(([status, error, value]) => {
         if (status === 'error' && error) {
@@ -1726,14 +1807,14 @@ function mutationResource(request, options = {}) {
                 error,
             };
         }
-        if (status === 'resolved' && value !== null) {
+        if (status === 'resolved' && value !== NULL_VALUE) {
             return {
                 status: 'resolved',
                 value,
             };
         }
-        return null;
-    }), filter((v) => v !== null), takeUntilDestroyed(destroyRef))
+        return NULL_VALUE;
+    }), filter((v) => v !== NULL_VALUE), takeUntilDestroyed(destroyRef))
         .subscribe((result) => {
         if (result.status === 'error')
             onError?.(result.error, ctx);
@@ -1741,7 +1822,7 @@ function mutationResource(request, options = {}) {
             onSuccess?.(result.value, ctx);
         onSettled?.(ctx);
         ctx = undefined;
-        next.set(null);
+        next.set(NULL_VALUE);
     });
     const shouldQueue = options.queue ?? false;
     return {
@@ -1756,11 +1837,22 @@ function mutationResource(request, options = {}) {
                 return queue.update((q) => [...q, [value, ictx]]);
             }
             else {
-                ctx = onMutate?.(value, ictx);
-                next.set(value);
+                try {
+                    ctx = onMutate?.(value, ictx);
+                    next.set(value);
+                }
+                catch (mutationErr) {
+                    ctx = undefined;
+                    next.set(NULL_VALUE);
+                    if (isDevMode())
+                        console.error('[@mmstack/resource]: error thrown in onMutate hook, mutation was not applied', mutationErr);
+                }
             }
         },
-        current: next,
+        current: computed(() => {
+            const nv = next();
+            return nv === NULL_VALUE ? null : nv;
+        }),
         // redeclare disabled with last value so that it is not affected by the resource's internal disablement logic
         disabled: computed(() => cb.isOpen() || lastValueRequest() === undefined),
     };