@warp-drive/core 5.7.0-alpha.23 → 5.7.0-alpha.25

package/declarations/reactive/-private/schema.d.ts

@@ -301,6 +301,12 @@ export declare class SchemaService implements SchemaServiceInterface {
 	* @internal
 	*/
 	_kind<T extends keyof KindFns>(mode: string, kind: T): KindFns[T];
+	/**
+	* Registers a {@link HashFn} for use with a {@link HashField} for
+	* either {@link ObjectSchema} identity or polymorphic type calculation.
+	*
+	* @public
+	*/
 	registerHashFn<T extends object>(hashFn: HashFn<T>): void;
 	fields({ type }: {
 		type: string;

package/declarations/request/-private/manager.d.ts

@@ -1,5 +1,5 @@
 import type { RequestKey } from "../../types/identifier.js";
-import type { RequestInfo } from "../../types/request.js";
+import { type RequestInfo } from "../../types/request.js";
 import type { CacheHandler, Future, GenericCreateArgs, Handler, ManagedRequestPriority } from "./types.js";
 import { IS_CACHE_HANDLER } from "./utils.js";
 /**
@@ -90,7 +90,7 @@ import { IS_CACHE_HANDLER } from "./utils.js";
 * type StructuredDocument<T> = StructuredDataDocument<T> | StructuredErrorDocument;
 * ```
 *
-* @class RequestManager
+* @hideconstructor
 * @public
 */
 export declare class RequestManager {
@@ -132,8 +132,6 @@ export declare class RequestManager {
 	* curry the request, or pass along a modified request.
 	*
 	* @public
-	* @param {Handler[]} newHandlers
-	* @return {ThisType}
 	*/
 	use(newHandlers: Handler[]): this;
 	/**
@@ -142,8 +140,6 @@ export declare class RequestManager {
 	* Returns a Future that fulfills with a StructuredDocument
 	*
 	* @public
-	* @param {RequestInfo} request
-	* @return {Future}
 	*/
 	request<RT>(request: RequestInfo<RT>): Future<RT>;
 	/**

package/declarations/request/-private/types.d.ts

@@ -1,6 +1,8 @@
 /* eslint-disable no-irregular-whitespace */
+import type { Store } from "../../store/-private.js";
 import type { RequestKey } from "../../types/identifier.js";
 import type { IS_FUTURE, RequestContext, RequestInfo, ResponseInfo, StructuredDataDocument } from "../../types/request.js";
+import type { RequestManager } from "./manager.js";
 export interface GodContext {
 	controller: AbortController;
 	response: ResponseInfo | null;
@@ -8,6 +10,7 @@ export interface GodContext {
 	hasRequestedStream: boolean;
 	id: number;
 	identifier: RequestKey | null;
+	requester: RequestManager | Store;
 }
 export type Deferred<T> = {
 	resolve(v: T): void;
@@ -32,10 +35,14 @@ export type DeferredStream = {
 * @public
 */
 export interface Future<T> extends Promise<StructuredDataDocument<T>> {
+	/** @internal */
 	[IS_FUTURE]: true;
 	/**
 	* Cancel this request by firing the {@link AbortController}'s signal.
 	*
+	* This method can be used as an action or event handler as its
+	* context is bound to the Future instance.
+	*
 	* @privateRemarks
 	* [MDN Reference](https://developer.mozilla.org/docs/Web/API/AbortController/abort)
 	*
@@ -46,8 +53,10 @@ export interface Future<T> extends Promise<StructuredDataDocument<T>> {
 	/**
 	* Get the response stream, if any, once made available.
 	*
+	* This method can be used as an action or event handler as its
+	* context is bound to the Future instance.
+	*
 	* @public
-	* @return {Promise<ReadableStream | null>}
 	*/
 	getStream(): Promise<ReadableStream | null>;
 	/**
@@ -55,28 +64,27 @@ export interface Future<T> extends Promise<StructuredDataDocument<T>> {
 	*  mostly useful for instrumentation and infrastructure.
 	*
 	* @param cb the callback to run
-	* @public
-	* @return {void}
 	*/
 	onFinalize(cb: () => void): void;
 	/**
 	* The identifier of the associated request, if any, as
 	* assigned by the CacheHandler.
-	*
-	* @property lid
-	* @type {RequestKey | null}
-	* @public
 	*/
 	lid: RequestKey | null;
 	/**
 	* The id of the associated request, if any, as assigned
 	* by the RequestManager
 	*
-	* @property id
-	* @type {Number}
-	* @public
+	* This is not unique across Manager instances and cannot
+	* be used to identify or dedupe requests.
 	*/
 	id: number;
+	/**
+	* The RequestManager or Store that initiated this request.
+	*
+	* @private
+	*/
+	requester: RequestManager | Store;
 }
 export type DeferredFuture<T> = {
 	resolve(v: StructuredDataDocument<T>): void;
@@ -191,8 +199,6 @@ const manager = new RequestManager()
 
 Handlers will be invoked in the order they are registered ("fifo", first-in first-out), and may only be registered up until the first request is made. It is recommended but not required to register all handlers at one time in order to ensure explicitly visible handler ordering.
 
-
-@class (Interface) Handler
 @public
 */
 export interface Handler {
@@ -202,20 +208,17 @@ export interface Handler {
 	* other handlers.
 	*
 	* @public
-	* @param context
-	* @param next
 	*/
 	request<T = unknown>(context: RequestContext, next: NextFn<T>): Promise<T | StructuredDataDocument<T>> | Future<T>;
 }
 /**
-* The CacheHandler is identical to other handlers ecxept that it
+* The CacheHandler is identical to other handlers except that it
 * is allowed to return a value synchronously. This is useful for
 * features like reducing microtask queueing when de-duping.
 *
 * A RequestManager may only have one CacheHandler, registered via
 * `manager.useCache(CacheHandler)`.
 *
-* @class (Interface) CacheHandler
 * @public
 */
 export interface CacheHandler {
@@ -225,8 +228,6 @@ export interface CacheHandler {
 	* other handlers.
 	*
 	* @public
-	* @param context
-	* @param next
 	*/
 	request<T = unknown>(context: RequestContext, next: NextFn<T>): Promise<T | StructuredDataDocument<T>> | Future<T> | T;
 }

package/declarations/store/-private/new-core-tmp/reactivity/internal.d.ts

@@ -1,6 +1,10 @@
 import { ARRAY_SIGNAL, OBJECT_SIGNAL, type SignalRef } from "./configure.js";
 export type { SignalRef };
 export { ARRAY_SIGNAL, OBJECT_SIGNAL };
+interface Initializer {
+	value: () => unknown;
+}
+export declare function makeInitializer(fn: () => unknown): Initializer;
 /**
 * A WarpDriveSignal is a wrapper around a framework specific or TC39 signal
 * that enables us to store and manage the signal in a universal way.

package/declarations/store/-private/new-core-tmp/reactivity/signal.d.ts

@@ -25,12 +25,29 @@ export declare function defineSignal<T extends object>(obj: T, key: string, v?:
 * @internal
 */
 export declare function defineNonEnumerableSignal<T extends object>(obj: T, key: string, v?: unknown): void;
+interface DecoratorPropertyDescriptor extends PropertyDescriptor {
+	initializer?: () => unknown;
+}
+/**
+* Decorator version of creating a signal.
+*/
+export declare function signal<
+	T extends object,
+	K extends keyof T & string
+>(target: T, key: K, descriptor?: DecoratorPropertyDescriptor): void;
+/**
+* Decorator version of creating a memoized getter
+*/
 export declare function memoized<
 	T extends object,
 	K extends keyof T & string
 >(target: T, key: K, descriptor: PropertyDescriptor): PropertyDescriptor;
+/**
+* Decorator version of creating a gate.
+*/
 export declare function gate<
 	T extends object,
 	K extends keyof T & string
 >(_target: T, key: K, desc: PropertyDescriptor): PropertyDescriptor;
 export declare function defineGate<T extends object>(obj: T, key: string, desc: PropertyDescriptor): void;
+export {};

package/declarations/store/-private/new-core-tmp/request-state.d.ts

@@ -7,6 +7,7 @@ import type { PendingPromise, RejectedPromise, ResolvedPromise } from "./promise
 * reactive properties that can be used to build UIs that respond
 * to the progress of a request.
 *
+* @hideconstructor
 */
 export declare class RequestLoadingState {
 	private _sizeHint;
@@ -71,11 +72,52 @@ export interface PendingRequest extends PendingPromise {
 *
 */
 export interface ResolvedRequest<RT> extends ResolvedPromise<RT> {
+	/**
+	* Retries the request with high (blocking) priority. This is the
+	* same as having passed `cacheOptions.reload = true` on the original
+	* request.
+	*
+	* This will not change the existing request's state. To subscribe
+	* to the new request's state, use `getRequestState` on the returned
+	* {@link Future}.
+	*
+	* ```ts
+	* const future = state.reload();
+	* const state = getRequestState(future);
+	* ```
+	*
+	* It is safe to pass this around as an "action" or "event" handler
+	* as its context is bound.
+	*/
+	reload(): Future<RT>;
+	/**
+	* Retries the request with low (non-blocking) priority. This is the
+	* same as having passed `cacheOptions.backgroundReload = true` on the original
+	* request.
+	*
+	* This will not change the existing request's state. To subscribe
+	* to the new request's state, use `getRequestState` on the returned
+	* {@link Future}.
+	*
+	* ```ts
+	* const future = state.reload();
+	* const state = getRequestState(future);
+	* ```
+	*
+	* It is safe to pass this around as an "action" or "event" handler
+	* as its context is bound.
+	*/
+	refresh(usePolicy?: boolean): Future<RT>;
 	/**
 	* Whether the request is cancelled.
 	*
 	*/
 	isCancelled: false;
+	/**
+	* A lazily created {@link RequestLoadingState} instance
+	* which provides a number of reactive properties that can be used
+	* to build UIs that respond to the progress of a request.
+	*/
 	loadingState: RequestLoadingState;
 	request: ImmutableRequestInfo<RT> | null;
 	response: Response | ResponseInfo | null;
@@ -92,6 +134,42 @@ export interface RejectedRequest<
 	RT,
 	E extends StructuredErrorDocument = StructuredErrorDocument
 > extends RejectedPromise<E> {
+	/**
+	* Retries the request with high (blocking) priority. This is the
+	* same as having passed `cacheOptions.reload = true` on the original
+	* request.
+	*
+	* This will not change the existing request's state. To subscribe
+	* to the new request's state, use `getRequestState` on the returned
+	* {@link Future}.
+	*
+	* ```ts
+	* const future = state.reload();
+	* const state = getRequestState(future);
+	* ```
+	*
+	* It is safe to pass this around as an "action" or "event" handler
+	* as its context is bound.
+	*/
+	reload(): Future<RT>;
+	/**
+	* Retries the request with low (non-blocking) priority. This is the
+	* same as having passed `cacheOptions.backgroundReload = true` on the original
+	* request.
+	*
+	* This will not change the existing request's state. To subscribe
+	* to the new request's state, use `getRequestState` on the returned
+	* {@link Future}.
+	*
+	* ```ts
+	* const future = state.reload();
+	* const state = getRequestState(future);
+	* ```
+	*
+	* It is safe to pass this around as an "action" or "event" handler
+	* as its context is bound.
+	*/
+	refresh(usePolicy?: boolean): Future<RT>;
 	/**
 	* Whether the request is cancelled.
 	*
@@ -111,6 +189,42 @@ export interface CancelledRequest<
 	RT,
 	E extends StructuredErrorDocument = StructuredErrorDocument
 > {
+	/**
+	* Retries the request with high (blocking) priority. This is the
+	* same as having passed `cacheOptions.reload = true` on the original
+	* request.
+	*
+	* This will not change the existing request's state. To subscribe
+	* to the new request's state, use `getRequestState` on the returned
+	* {@link Future}.
+	*
+	* ```ts
+	* const future = state.reload();
+	* const state = getRequestState(future);
+	* ```
+	*
+	* It is safe to pass this around as an "action" or "event" handler
+	* as its context is bound.
+	*/
+	reload(): Future<RT>;
+	/**
+	* Retries the request with low (non-blocking) priority. This is the
+	* same as having passed `cacheOptions.backgroundReload = true` on the original
+	* request.
+	*
+	* This will not change the existing request's state. To subscribe
+	* to the new request's state, use `getRequestState` on the returned
+	* {@link Future}.
+	*
+	* ```ts
+	* const future = state.reload();
+	* const state = getRequestState(future);
+	* ```
+	*
+	* It is safe to pass this around as an "action" or "event" handler
+	* as its context is bound.
+	*/
+	refresh(usePolicy?: boolean): Future<RT>;
 	/**
 	* The status of the request.
 	*

package/declarations/store/-private/new-core-tmp/request-subscription.d.ts

@@ -3,14 +3,25 @@ import type { Future } from "../../../request.js";
 import type { StructuredErrorDocument } from "../../../types/request.js";
 import type { RequestState } from "../../-private.js";
 export declare const DISPOSE: "(symbol) dispose";
-interface ErrorFeatures {
+export interface ErrorFeatures {
 	isHidden: boolean;
 	isOnline: boolean;
 	retry: () => Promise<void>;
 }
-type AutorefreshBehaviorType = "online" | "interval" | "invalid";
-type AutorefreshBehaviorCombos = boolean | AutorefreshBehaviorType | `${AutorefreshBehaviorType},${AutorefreshBehaviorType}` | `${AutorefreshBehaviorType},${AutorefreshBehaviorType},${AutorefreshBehaviorType}`;
-type ContentFeatures<RT> = {
+export type AutorefreshBehaviorType = "online" | "interval" | "invalid";
+export type AutorefreshBehaviorCombos = boolean | AutorefreshBehaviorType | `${AutorefreshBehaviorType},${AutorefreshBehaviorType}` | `${AutorefreshBehaviorType},${AutorefreshBehaviorType},${AutorefreshBehaviorType}`;
+/**
+* Utilities to assist in recovering from the error.
+*/
+export interface RecoveryFeatures {
+	isOnline: boolean;
+	isHidden: boolean;
+	retry: () => Promise<void>;
+}
+/**
+* Utilities for keeping the request fresh
+*/
+export interface ContentFeatures<RT> {
 	isOnline: boolean;
 	isHidden: boolean;
 	isRefreshing: boolean;
@@ -18,7 +29,22 @@ type ContentFeatures<RT> = {
 	reload: () => Promise<void>;
 	abort?: () => void;
 	latestRequest?: Future<RT>;
-};
+}
+export interface RequestArgs<
+	RT,
+	E
+> extends SubscriptionArgs<RT, E> {
+	subscription?: RequestSubscription<RT, E>;
+	/**
+	* The store instance to use for making requests. If contexts are available,
+	* the component will default to using the `store` on the context.
+	*
+	* This is required if the store is not available via context or should be
+	* different from the store provided via context.
+	*
+	*/
+	store?: Store;
+}
 // eslint-disable-next-line @typescript-eslint/no-unused-vars
 export interface SubscriptionArgs<
 	RT,
@@ -29,14 +55,14 @@ export interface SubscriptionArgs<
 	* by either the `store.request` or `store.requestManager.request` methods.
 	*
 	*/
-	request?: Future<RT>;
+	request?: Future<RT> | undefined | null;
 	/**
 	* A query to use for the request. This should be an object that can be
 	* passed to `store.request`. Use this in place of `@request` if you would
 	* like the component to also initiate the request.
 	*
 	*/
-	query?: StoreRequestInput<RT>;
+	query?: StoreRequestInput<RT> | undefined | null;
 	/**
 	* The autorefresh behavior for the request. This can be a boolean, or any
 	* combination of the following values: `'online'`, `'interval'`, `'invalid'`.
@@ -76,6 +102,20 @@ export interface SubscriptionArgs<
 	*/
 	autorefreshBehavior?: "refresh" | "reload" | "policy";
 }
+export interface RequestComponentArgs<
+	RT,
+	E
+> extends SubscriptionArgs<RT, E> {
+	/**
+	* The store instance to use for making requests. If contexts are available,
+	* the component will default to using the `store` on the context.
+	*
+	* This is required if the store is not available via context or should be
+	* different from the store provided via context.
+	*
+	*/
+	store?: Store | RequestManager;
+}
 // eslint-disable-next-line @typescript-eslint/no-unused-vars
 export interface RequestSubscription<
 	RT,
@@ -227,6 +267,10 @@ export declare class RequestSubscription<
 	*/
 	private _maybeUpdate;
 	/**
+	* @internal
+	*/
+	private _getRequester;
+	/**
 	* Retry the request, reloading it from the server.
 	*/
 	retry: () => Promise<void>;
@@ -254,4 +298,3 @@ export declare function createRequestSubscription<
 	RT,
 	E
 >(store: Store | RequestManager, args: SubscriptionArgs<RT, E>): RequestSubscription<RT, E>;
-export {};

package/declarations/store/-private/store-service.d.ts

@@ -470,7 +470,7 @@ export declare class Store extends BaseClass {
 	* {@link CacheOptions.key | cache key} will have the request result
 	* and document cached.
 	*
-	* The cache key used is {@link RequestInfo.cacheOptions | RequestInfo.cacheOptions.key}
+	* The cache key used is {@link RequestInfo.cacheOptions.key | RequestInfo.cacheOptions.key}
 	* if present, falling back to {@link RequestInfo.url}.
 	*
 	* Params are not serialized as part of the cache-key, so

package/declarations/store/-private.d.ts

@@ -25,8 +25,8 @@ export type { StoreRequestInput } from "./-private/cache-handler/handler.js";
 export { type LegacyManyArray, type LegacyManyArray as RelatedCollection, createLegacyManyArray } from "./-private/record-arrays/legacy-many-array.js";
 export { log, logGroup } from "./-private/debug/utils.js";
 export { getPromiseState, type PromiseState } from "./-private/new-core-tmp/promise-state.js";
-export { DISPOSE, createRequestSubscription, type SubscriptionArgs, type RequestSubscription } from "./-private/new-core-tmp/request-subscription.js";
+export { DISPOSE, createRequestSubscription, type RequestArgs, type SubscriptionArgs, type RequestComponentArgs, type RequestSubscription, type ContentFeatures, type RecoveryFeatures, type AutorefreshBehaviorCombos, type AutorefreshBehaviorType } from "./-private/new-core-tmp/request-subscription.js";
 export { getRequestState, type RequestLoadingState, type RequestCacheRequestState as RequestState } from "./-private/new-core-tmp/request-state.js";
 export { createMemo, type SignalHooks, waitFor } from "./-private/new-core-tmp/reactivity/configure.js";
-export { memoized, gate, entangleSignal, defineSignal, defineGate, defineNonEnumerableSignal } from "./-private/new-core-tmp/reactivity/signal.js";
+export { signal, memoized, gate, entangleSignal, defineSignal, defineGate, defineNonEnumerableSignal } from "./-private/new-core-tmp/reactivity/signal.js";
 export { ARRAY_SIGNAL, OBJECT_SIGNAL, Signals, type WarpDriveSignal, peekInternalSignal, withSignalStore, notifyInternalSignal, consumeInternalSignal, getOrCreateInternalSignal } from "./-private/new-core-tmp/reactivity/internal.js";

package/declarations/types/request.d.ts

@@ -1,9 +1,9 @@
+import type { Store } from "../store/-private.js";
 import type { ResourceKey } from "./identifier.js";
 import type { QueryParamsSerializationOptions } from "./params.js";
 import type { TypeFromInstanceOrString } from "./record.js";
 import type { ResourceIdentifierObject } from "./spec/json-api-raw.js";
 import type { RequestSignature } from "./symbols.js";
-type Store = unknown;
 export declare const SkipCache: "___(unique) Symbol(SkipCache)";
 export declare const EnableHydration: "___(unique) Symbol(EnableHydration)";
 export declare const IS_FUTURE: "___(unique) Symbol(IS_FUTURE)";
@@ -199,12 +199,17 @@ export interface StructuredErrorDocument<T = unknown> extends Error {
 */
 export type StructuredDocument<T> = StructuredDataDocument<T> | StructuredErrorDocument<T>;
 /**
-* JavaScript's native Request class.
+* The {@link RequestInit} interface accepted by the native {@link fetch} API.
 *
 * WarpDrive provides our own typings due to incompleteness in the native typings.
 *
+* @privateRemarks
+* - [MDN Reference (fetch)](https://developer.mozilla.org/docs/Web/API/Window/fetch)
+* - [MDN Reference (RequestInit)](https://developer.mozilla.org/en-US/docs/Web/API/RequestInit)
+* - [MDN Reference (Request)](https://developer.mozilla.org/docs/Web/API/Request)
+*
 */
-interface Request {
+interface NativeRequestInit {
 	/** Returns the cache mode associated with request, which is a string indicating how the request will interact with the browser's cache when fetching.
 	*/
 	cache?: RequestCache;
@@ -264,11 +269,21 @@ export interface ImmutableHeaders extends Headers {
 	toJSON(): [string, string][];
 }
 /**
-* Extends JavaScript's native {@link Request} object with additional
-* properties specific to the RequestManager's capabilities.
+* Extends JavaScript's native {@link fetch} {@link NativeRequestInit | RequestInit} with additional
+* properties specific to the {@link RequestManager | RequestManager's} capabilities.
+*
+* This interface is used to define the shape of a request that can be made via
+* either the {@link RequestManager.request} or {@link Store.request} methods.
+*
+* @privateRemarks
+* - [MDN Reference (fetch)](https://developer.mozilla.org/docs/Web/API/Window/fetch)
+* - [MDN Reference (RequestInit)](https://developer.mozilla.org/en-US/docs/Web/API/RequestInit)
+* - [MDN Reference (Request)](https://developer.mozilla.org/docs/Web/API/Request)
 *
+* @public
+* @since 4.12
 */
-export interface RequestInfo<RT = unknown> extends Request {
+export interface RequestInfo<RT = unknown> extends NativeRequestInit {
 	/**
 	* If provided, used instead of the AbortController auto-configured for each request by the RequestManager
 	*
@@ -281,7 +296,7 @@ export interface RequestInfo<RT = unknown> extends Request {
 	store?: Store;
 	op?: string;
 	/**
-	* The identifiers of the primary resources involved in the request
+	* The {@link ResourceKey | ResourceKeys} of the primary resources involved in the request
 	* (if any). This may be used by handlers to perform transactional
 	* operations on the store.
 	*
@@ -298,7 +313,7 @@ export interface RequestInfo<RT = unknown> extends Request {
 	*/
 	data?: Record<string, unknown>;
 	/**
-	* options specifically intended for handlers
+	* options specifically intended for {@link Handler | Handlers}
 	* to utilize to process the request
 	*
 	*/

package/dist/{context-kQXhkeBj.js → context-BNZebmoO.js}

@@ -450,6 +450,7 @@ function upgradePromise(promise, future) {
   promise.onFinalize = future.onFinalize;
   promise.id = future.id;
   promise.lid = future.lid;
+  promise.requester = future.requester;
   return promise;
 }
 function createFuture(owner) {
@@ -477,6 +478,7 @@ function createFuture(owner) {
   };
   promise.id = owner.requestId;
   promise.lid = owner.god.identifier;
+  promise.requester = owner.god.requester;
   deferred.promise = promise;
   return deferred;
 }

package/dist/index.js

@@ -1,9 +1,10 @@
 import { setLogging, getRuntimeConfig } from './types/runtime.js';
-import { a as cloneResponseProperties, I as IS_CACHE_HANDLER, b as assertValidRequest, e as executeNextHandler, d as getRequestResult, u as upgradePromise, s as setPromiseResult, f as clearRequestResult } from "./context-kQXhkeBj.js";
+import { a as cloneResponseProperties, I as IS_CACHE_HANDLER, b as assertValidRequest, e as executeNextHandler, d as getRequestResult, u as upgradePromise, s as setPromiseResult, f as clearRequestResult } from "./context-BNZebmoO.js";
 import { macroCondition, getGlobalConfig } from '@embroider/macros';
 import { w as waitFor } from "./configure-B48bFHOl.js";
 import { peekUniversalTransient, setUniversalTransient } from './types/-private.js';
-export { C as CacheHandler, S as Store, r as recordIdentifierFor, M as setIdentifierForgetMethod, K as setIdentifierGenerationMethod, N as setIdentifierResetMethod, L as setIdentifierUpdateMethod, O as setKeyInfoForResource, s as storeFor } from "./request-state-55umD7hP.js";
+import { EnableHydration } from './types/request.js';
+export { C as CacheHandler, S as Store, r as recordIdentifierFor, N as setIdentifierForgetMethod, L as setIdentifierGenerationMethod, O as setIdentifierResetMethod, M as setIdentifierUpdateMethod, P as setKeyInfoForResource, s as storeFor } from "./request-state-XxA7ZVps.js";
 import '@ember/debug';
 import './utils/string.js';
 import "./symbols-sql1_mdx.js";
@@ -187,6 +188,7 @@ function isDict(v) {
   return v !== null && typeof v === 'object';
 }
 class RequestManager {
+  /** @internal */
   #handlers = [];
   /** @internal */
 
@@ -239,8 +241,6 @@ class RequestManager {
    * curry the request, or pass along a modified request.
    *
    * @public
-   * @param {Handler[]} newHandlers
-   * @return {ThisType}
    */
   use(newHandlers) {
     const handlers = this.#handlers;
@@ -267,8 +267,6 @@ class RequestManager {
    * Returns a Future that fulfills with a StructuredDocument
    *
    * @public
-   * @param {RequestInfo} request
-   * @return {Future}
    */
   request(request) {
     const handlers = this.#handlers;
@@ -290,7 +288,8 @@ class RequestManager {
       stream: null,
       hasRequestedStream: false,
       id: requestId,
-      identifier: null
+      identifier: null,
+      requester: request[EnableHydration] && request.store ? request.store : this
     };
     const promise = executeNextHandler(handlers, request, 0, context);
 

package/dist/reactive.js

@@ -1,5 +1,5 @@
-import { F as ReactiveResource, G as isNonIdentityCacheableField, H as getFieldCacheKeyStrict, r as recordIdentifierFor, z as withSignalStore } from "./request-state-55umD7hP.js";
-export { I as checkout, J as commit } from "./request-state-55umD7hP.js";
+import { G as ReactiveResource, H as isNonIdentityCacheableField, I as getFieldCacheKeyStrict, r as recordIdentifierFor, A as withSignalStore } from "./request-state-XxA7ZVps.js";
+export { J as checkout, K as commit } from "./request-state-XxA7ZVps.js";
 import { isResourceSchema } from './types/schema/fields.js';
 import { D as Destroy, C as Context } from "./symbols-sql1_mdx.js";
 export { a as Checkout } from "./symbols-sql1_mdx.js";
@@ -589,6 +589,13 @@ class SchemaService {
     })(kinds[kind]) : {};
     return kinds[kind];
   }
+
+  /**
+   * Registers a {@link HashFn} for use with a {@link HashField} for
+   * either {@link ObjectSchema} identity or polymorphic type calculation.
+   *
+   * @public
+   */
   registerHashFn(hashFn) {
     this._hashFns.set(hashFn[Type], hashFn);
   }

package/dist/{request-state-55umD7hP.js → request-state-XxA7ZVps.js}

@@ -7,8 +7,21 @@ import { CACHE_OWNER, DEBUG_STALE_CACHE_OWNER, DEBUG_KEY_TYPE, DEBUG_CLIENT_ORIG
 import { dasherize } from './utils/string.js';
 import { S as SOURCE, C as Context, D as Destroy, a as Checkout, b as Commit } from "./symbols-sql1_mdx.js";
 import { a as createSignal, b as consumeSignal, n as notifySignal, c as createMemo, A as ARRAY_SIGNAL, O as OBJECT_SIGNAL, d as willSyncFlushWatchers } from "./configure-B48bFHOl.js";
-import { g as getPromiseResult, s as setPromiseResult } from "./context-kQXhkeBj.js";
+import { g as getPromiseResult, s as setPromiseResult } from "./context-BNZebmoO.js";
 import { RecordStore } from './types/symbols.js';
+const INITIALIZER_PROTO = {
+  isInitializer: true
+};
+function makeInitializer(fn) {
+  // we use a prototype to ensure that the initializer is not enumerable
+  // and does not interfere with the signal's value.
+  return Object.assign(Object.create(INITIALIZER_PROTO), {
+    value: fn
+  });
+}
+function isInitializer(obj) {
+  return typeof obj === 'object' && obj !== null && Object.getPrototypeOf(obj) === INITIALIZER_PROTO;
+}
 
 /**
  * A WarpDriveSignal is a wrapper around a framework specific or TC39 signal
@@ -95,7 +108,7 @@ function createInternalSignal(signals, obj, key, initialValue) {
     key,
     context: obj,
     signal: createSignal(obj, key),
-    value: initialValue,
+    value: isInitializer(initialValue) ? initialValue.value.call(obj) : initialValue,
     isStale: false
   };
   signals.set(key, warpDriveSignal);
@@ -121,12 +134,12 @@ function notifyInternalSignal(signal) {
   }
 }
 function entangleSignal(signals, obj, key, initialValue) {
-  let signal = peekInternalSignal(signals, key);
-  if (!signal) {
-    signal = createInternalSignal(signals, obj, key, initialValue);
+  let internalSignal = peekInternalSignal(signals, key);
+  if (!internalSignal) {
+    internalSignal = createInternalSignal(signals, obj, key, initialValue);
   }
-  consumeInternalSignal(signal);
-  return signal;
+  consumeInternalSignal(internalSignal);
+  return internalSignal;
 }
 function createSignalDescriptor(key, intialValue) {
   return {
@@ -138,10 +151,10 @@ function createSignalDescriptor(key, intialValue) {
     },
     set(value) {
       const signals = withSignalStore(this);
-      const signal = getOrCreateInternalSignal(signals, this, key, intialValue);
-      if (signal.value !== value) {
-        signal.value = value;
-        notifyInternalSignal(signal);
+      const internalSignal = getOrCreateInternalSignal(signals, this, key, intialValue);
+      if (internalSignal.value !== value) {
+        internalSignal.value = value;
+        notifyInternalSignal(internalSignal);
       }
     }
   };
@@ -171,6 +184,27 @@ function defineNonEnumerableSignal(obj, key, v) {
   desc.enumerable = false;
   Object.defineProperty(obj, key, desc);
 }
+/**
+ * Decorator version of creating a signal.
+ */
+function signal(target, key, descriptor) {
+  // Error on `@signal()`, `@signal(...args)``
+  macroCondition(getGlobalConfig().WarpDrive.env.DEBUG) ? (test => {
+    if (!test) {
+      throw new Error('You attempted to use @signal(), which is not necessary nor supported. Remove the parentheses and you will be good to go!');
+    }
+  })(target !== undefined) : {};
+  macroCondition(getGlobalConfig().WarpDrive.env.DEBUG) ? (test => {
+    if (!test) {
+      throw new Error(`You attempted to use @signal on with ${arguments.length > 1 ? 'arguments' : 'an argument'} ( @signal(${Array.from(arguments).map(d => `'${d}'`).join(', ')}) ), which is not supported. Dependencies are automatically tracked, so you can just use ${'`@signal`'}`);
+    }
+  })(typeof target === 'object' && typeof key === 'string' && typeof descriptor === 'object' && arguments.length === 3) : {};
+  return createSignalDescriptor(key, descriptor.initializer ? makeInitializer(descriptor.initializer) : null);
+}
+
+/**
+ * Decorator version of creating a memoized getter
+ */
 function memoized(target, key, descriptor) {
   // Error on `@memoized()`, `@memoized(...args)`, and `@memoized propName = value;`
   macroCondition(getGlobalConfig().WarpDrive.env.DEBUG) ? (test => {
@@ -202,6 +236,10 @@ function memoized(target, key, descriptor) {
   };
   return descriptor;
 }
+
+/**
+ * Decorator version of creating a gate.
+ */
 function gate(_target, key, desc) {
   // eslint-disable-next-line @typescript-eslint/unbound-method
   const getter = desc.get;
@@ -210,34 +248,34 @@ function gate(_target, key, desc) {
   const isLocal = desc.isLocal;
   desc.get = function () {
     const signals = withSignalStore(this);
-    let signal = peekInternalSignal(signals, key);
-    if (!signal) {
-      signal = createInternalSignal(signals, this, key, getter.call(this));
-    } else if (signal.isStale) {
-      signal.isStale = false;
-      signal.value = getter.call(this);
-    }
-    consumeInternalSignal(signal);
-    return signal.value;
+    let internalSignal = peekInternalSignal(signals, key);
+    if (!internalSignal) {
+      internalSignal = createInternalSignal(signals, this, key, getter.call(this));
+    } else if (internalSignal.isStale) {
+      internalSignal.isStale = false;
+      internalSignal.value = getter.call(this);
+    }
+    consumeInternalSignal(internalSignal);
+    return internalSignal.value;
   };
   if (setter) {
     desc.set = function (v) {
       const signals = withSignalStore(this);
-      let signal = peekInternalSignal(signals, key);
-      if (!signal) {
+      let internalSignal = peekInternalSignal(signals, key);
+      if (!internalSignal) {
         // we can't use `v` as initialValue here because setters don't
         // return the value and the final value may be different
         // than what the setter was called with.
-        signal = createInternalSignal(signals, this, key, undefined);
-        signal.isStale = true;
+        internalSignal = createInternalSignal(signals, this, key, undefined);
+        internalSignal.isStale = true;
       }
       setter.call(this, v);
       // when a gate is set, we do not notify the signal
       // as its update is controlled externally.
       // unless it specifically sets itself to be locally managed
       if (isLocal) {
-        signal.isStale = true;
-        notifyInternalSignal(signal);
+        internalSignal.isStale = true;
+        notifyInternalSignal(internalSignal);
       }
     };
   }
@@ -6645,7 +6683,7 @@ class Store extends BaseClass {
    * {@link CacheOptions.key | cache key} will have the request result
    * and document cached.
    *
-   * The cache key used is {@link RequestInfo.cacheOptions | RequestInfo.cacheOptions.key}
+   * The cache key used is {@link RequestInfo.cacheOptions.key | RequestInfo.cacheOptions.key}
    * if present, falling back to {@link RequestInfo.url}.
    *
    * Params are not serialized as part of the cache-key, so
@@ -9048,6 +9086,14 @@ function isNeverString(val) {
   return val;
 }
 
+/**
+ * Utilities to assist in recovering from the error.
+ */
+
+/**
+ * Utilities for keeping the request fresh
+ */
+
 // eslint-disable-next-line @typescript-eslint/no-unused-vars
 
 // eslint-disable-next-line @typescript-eslint/no-unused-vars
@@ -9269,14 +9315,12 @@ class RequestSubscription {
     this._removeSubscriptions();
 
     // if we have a request, we need to subscribe to it
-    const {
-      store
-    } = this;
+    const store = this._getRequester();
     if (requestId && isStore(store)) {
       this._subscribedTo = requestId;
       this._subscription = store.notifications.subscribe(requestId, (_id, op) => {
         // ignore subscription events that occur while our own component's request
-        // is ocurring
+        // is occurring
         if (this._isUpdating) {
           return;
         }
@@ -9345,8 +9389,9 @@ class RequestSubscription {
    * @internal
    */
   _removeSubscriptions() {
-    if (this._subscription && isStore(this.store)) {
-      this.store.notifications.unsubscribe(this._subscription);
+    const store = this._getRequester();
+    if (this._subscription && isStore(store)) {
+      store.notifications.unsubscribe(this._subscription);
       this._subscribedTo = null;
       this._subscription = null;
     }
@@ -9411,6 +9456,12 @@ class RequestSubscription {
     if (this.isIdle) {
       return;
     }
+    const {
+      reqState
+    } = this;
+    if (reqState.isPending) {
+      return;
+    }
     const canAttempt = Boolean(this.isOnline && !this.isHidden && (mode || this.autorefreshTypes.size));
     if (!canAttempt) {
       if (!silent && mode && mode !== '_invalidated') {
@@ -9447,35 +9498,26 @@ class RequestSubscription {
     this._invalidated = false;
     if (shouldAttempt) {
       this._clearInterval();
-      const request = Object.assign({}, this.reqState.request);
+      this._isUpdating = true;
       const realMode = mode === '_invalidated' ? null : mode;
       const val = realMode ?? this._args.autorefreshBehavior ?? 'policy';
       switch (val) {
         case 'reload':
-          request.cacheOptions = Object.assign({}, request.cacheOptions, {
-            reload: true
-          });
+          this._latestRequest = reqState.reload();
           break;
         case 'refresh':
-          request.cacheOptions = Object.assign({}, request.cacheOptions, {
-            backgroundReload: true
-          });
+          this._latestRequest = reqState.refresh();
           break;
         case 'policy':
+          this._latestRequest = reqState.refresh(true);
           break;
         default:
-          throw new Error(`Invalid ${mode ? 'update mode' : '@autorefreshBehavior'} for <Request />: ${isNeverString(val)}`);
+          macroCondition(getGlobalConfig().WarpDrive.env.DEBUG) ? (test => {
+            {
+              throw new Error(`Invalid ${mode ? 'update mode' : '@autorefreshBehavior'} for <Request />: ${isNeverString(val)}`);
+            }
+          })() : {};
       }
-      const wasStoreRequest = request[EnableHydration] === true;
-      macroCondition(getGlobalConfig().WarpDrive.env.DEBUG) ? (test => {
-        if (!test) {
-          throw new Error(`Cannot supply a different store than was used to create the request`);
-        }
-      })(!request.store || request.store === this.store) : {};
-      const store = request.store || this.store;
-      const requester = !wasStoreRequest && 'requestManager' in store ? store.requestManager : store;
-      this._isUpdating = true;
-      this._latestRequest = requester.request(request);
       if (val !== 'refresh') {
         this._localRequest = this._latestRequest;
       }
@@ -9486,6 +9528,16 @@ class RequestSubscription {
     }
   }
 
+  /**
+   * @internal
+   */
+  _getRequester() {
+    if (this._args.request) {
+      return this._args.request.requester;
+    }
+    return this.store;
+  }
+
   /**
    * Retry the request, reloading it from the server.
    */
@@ -9573,7 +9625,6 @@ class RequestSubscription {
         throw new Error(`You must provide either @request or an @query arg with the <Request> component`);
       }
     })(query) : {};
-    // @ts-expect-error TODO investigate this
     return this.store.request(query);
   }
   static {
@@ -9710,6 +9761,7 @@ async function watchStream(stream, loadingState) {
  * reactive properties that can be used to build UIs that respond
  * to the progress of a request.
  *
+ * @hideconstructor
  */
 class RequestLoadingState {
   _stream = null;
@@ -9900,6 +9952,24 @@ defineNonEnumerableSignal(RequestLoadingState.prototype, '_lastPacketTime', 0);
  */
 
 const RequestStateProto = {};
+function performRefresh(requester, request, isReload) {
+  const req = Object.assign({}, request);
+  const cacheOptions = Object.assign({}, req.cacheOptions);
+  if (isReload) {
+    // force direct to network
+    cacheOptions.reload = true;
+  } else if (isReload === false) {
+    // delete reload to ensure we use backgroundReload / policy
+    delete cacheOptions.reload;
+    cacheOptions.backgroundReload = true;
+  } else {
+    // delete props to ensure we use the policy
+    delete cacheOptions.backgroundReload;
+    delete cacheOptions.reload;
+  }
+  req.cacheOptions = cacheOptions;
+  return requester.request(req);
+}
 
 // TODO introduce a new mechanism for defining multiple properties
 // that share a common signal
@@ -9931,6 +10001,25 @@ function createRequestState(future) {
   const state = getPromiseResult(future);
   const promiseState = Object.create(RequestStateProto);
   promiseState._request = future;
+  // @ts-expect-error - we still attach it for PendingState
+  promiseState.reload = () => {
+    macroCondition(getGlobalConfig().WarpDrive.env.DEBUG) ? (test => {
+      if (!test) {
+        throw new Error(`Cannot reload a request that is still pending. Await or abort the original request first.`);
+      }
+    })(!promiseState.isPending) : {};
+    return performRefresh(future.requester, promiseState.request, true);
+  };
+
+  // @ts-expect-error - we still attach it for PendingState
+  promiseState.refresh = (usePolicy = false) => {
+    macroCondition(getGlobalConfig().WarpDrive.env.DEBUG) ? (test => {
+      if (!test) {
+        throw new Error(`Cannot refresh a request that is still pending. Await or abort the original request first.`);
+      }
+    })(!promiseState.isPending) : {};
+    return performRefresh(future.requester, promiseState.request, usePolicy === true ? null : false);
+  };
   if (state) {
     if (state.isError) {
       promiseState.error = state.result;
@@ -10041,4 +10130,4 @@ function getRequestState(future) {
   }
   return state;
 }
-export { notifyInternalSignal as A, consumeInternalSignal as B, CacheHandler as C, DISPOSE as D, getOrCreateInternalSignal as E, ReactiveResource as F, isNonIdentityCacheableField as G, getFieldCacheKeyStrict as H, checkout as I, commit as J, setIdentifierGenerationMethod as K, setIdentifierUpdateMethod as L, setIdentifierForgetMethod as M, setIdentifierResetMethod as N, setKeyInfoForResource as O, RecordArrayManager as R, Store as S, _clearCaches as _, isRequestKey as a, coerceId as b, constructResource as c, setRecordIdentifier as d, ensureStringId as e, fastPush as f, StoreMap as g, createLegacyManyArray as h, isResourceKey as i, logGroup as j, getPromiseState as k, log as l, createRequestSubscription as m, normalizeModelName as n, getRequestState as o, memoized as p, gate as q, recordIdentifierFor as r, storeFor as s, entangleSignal as t, defineSignal as u, defineGate as v, defineNonEnumerableSignal as w, Signals as x, peekInternalSignal as y, withSignalStore as z };
+export { withSignalStore as A, notifyInternalSignal as B, CacheHandler as C, DISPOSE as D, consumeInternalSignal as E, getOrCreateInternalSignal as F, ReactiveResource as G, isNonIdentityCacheableField as H, getFieldCacheKeyStrict as I, checkout as J, commit as K, setIdentifierGenerationMethod as L, setIdentifierUpdateMethod as M, setIdentifierForgetMethod as N, setIdentifierResetMethod as O, setKeyInfoForResource as P, RecordArrayManager as R, Store as S, _clearCaches as _, isRequestKey as a, coerceId as b, constructResource as c, setRecordIdentifier as d, ensureStringId as e, fastPush as f, StoreMap as g, createLegacyManyArray as h, isResourceKey as i, logGroup as j, getPromiseState as k, log as l, createRequestSubscription as m, normalizeModelName as n, getRequestState as o, signal as p, memoized as q, recordIdentifierFor as r, storeFor as s, gate as t, entangleSignal as u, defineSignal as v, defineGate as w, defineNonEnumerableSignal as x, Signals as y, peekInternalSignal as z };

package/dist/request.js

@@ -1 +1 @@
-export { c as createDeferred, g as getPromiseResult, s as setPromiseResult } from "./context-kQXhkeBj.js";
+export { c as createDeferred, g as getPromiseResult, s as setPromiseResult } from "./context-BNZebmoO.js";

package/dist/store/-private.js

@@ -1,2 +1,2 @@
-export { C as CacheHandler, D as DISPOSE, R as RecordArrayManager, x as Signals, S as Store, g as StoreMap, _ as _clearCaches, n as _deprecatingNormalize, b as coerceId, c as constructResource, B as consumeInternalSignal, h as createLegacyManyArray, m as createRequestSubscription, v as defineGate, w as defineNonEnumerableSignal, u as defineSignal, e as ensureStringId, t as entangleSignal, f as fastPush, q as gate, E as getOrCreateInternalSignal, k as getPromiseState, o as getRequestState, a as isRequestKey, i as isResourceKey, l as log, j as logGroup, p as memoized, A as notifyInternalSignal, y as peekInternalSignal, r as recordIdentifierFor, d as setRecordIdentifier, s as storeFor, z as withSignalStore } from "../request-state-55umD7hP.js";
+export { C as CacheHandler, D as DISPOSE, R as RecordArrayManager, y as Signals, S as Store, g as StoreMap, _ as _clearCaches, n as _deprecatingNormalize, b as coerceId, c as constructResource, E as consumeInternalSignal, h as createLegacyManyArray, m as createRequestSubscription, w as defineGate, x as defineNonEnumerableSignal, v as defineSignal, e as ensureStringId, u as entangleSignal, f as fastPush, t as gate, F as getOrCreateInternalSignal, k as getPromiseState, o as getRequestState, a as isRequestKey, i as isResourceKey, l as log, j as logGroup, q as memoized, B as notifyInternalSignal, z as peekInternalSignal, r as recordIdentifierFor, d as setRecordIdentifier, p as signal, s as storeFor, A as withSignalStore } from "../request-state-XxA7ZVps.js";
 export { A as ARRAY_SIGNAL, O as OBJECT_SIGNAL, c as createMemo, w as waitFor } from "../configure-B48bFHOl.js";

package/dist/types/-private.js

@@ -1,6 +1,6 @@
 import { macroCondition, getGlobalConfig } from '@embroider/macros';
 const name = "@warp-drive/core";
-const version = "5.7.0-alpha.23";
+const version = "5.7.0-alpha.25";
 
 // in testing mode, we utilize globals to ensure only one copy exists of
 // these maps, due to bugs in ember-auto-import

package/dist/types/request.js

@@ -37,16 +37,31 @@ const STRUCTURED = getOrSetGlobal('DOC', Symbol('DOC'));
  */
 
 /**
- * JavaScript's native Request class.
+ * The {@link RequestInit} interface accepted by the native {@link fetch} API.
  *
  * WarpDrive provides our own typings due to incompleteness in the native typings.
  *
+ * @privateRemarks
+ * - [MDN Reference (fetch)](https://developer.mozilla.org/docs/Web/API/Window/fetch)
+ * - [MDN Reference (RequestInit)](https://developer.mozilla.org/en-US/docs/Web/API/RequestInit)
+ * - [MDN Reference (Request)](https://developer.mozilla.org/docs/Web/API/Request)
+ *
  */
 
 /**
- * Extends JavaScript's native {@link Request} object with additional
- * properties specific to the RequestManager's capabilities.
+ * Extends JavaScript's native {@link fetch} {@link NativeRequestInit | RequestInit} with additional
+ * properties specific to the {@link RequestManager | RequestManager's} capabilities.
+ *
+ * This interface is used to define the shape of a request that can be made via
+ * either the {@link RequestManager.request} or {@link Store.request} methods.
+ *
+ * @privateRemarks
+ * - [MDN Reference (fetch)](https://developer.mozilla.org/docs/Web/API/Window/fetch)
+ * - [MDN Reference (RequestInit)](https://developer.mozilla.org/en-US/docs/Web/API/RequestInit)
+ * - [MDN Reference (Request)](https://developer.mozilla.org/docs/Web/API/Request)
  *
+ * @public
+ * @since 4.12
  */
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@warp-drive/core",
-  "version": "5.7.0-alpha.23",
+  "version": "5.7.0-alpha.25",
   "description": "Core package for WarpDrive | All the Universal Basics",
   "keywords": [
     "ember-addon"
@@ -37,13 +37,13 @@
   },
   "dependencies": {
     "@embroider/macros": "^1.16.12",
-    "@warp-drive/build-config": "5.7.0-alpha.23"
+    "@warp-drive/build-config": "5.7.0-alpha.25"
   },
   "devDependencies": {
     "@babel/core": "^7.26.10",
     "@babel/plugin-transform-typescript": "^7.27.0",
     "@babel/preset-typescript": "^7.27.0",
-    "@warp-drive/internal-config": "5.7.0-alpha.23",
+    "@warp-drive/internal-config": "5.7.0-alpha.25",
     "decorator-transforms": "^2.3.0",
     "ember-source": "~6.3.0",
     "expect-type": "^1.2.1",