@warp-drive/core 5.8.0-alpha.6 → 5.8.0-alpha.8

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

@@ -3,25 +3,13 @@ import type { RequestKey } from "../../types/identifier.js";
 import type { ImmutableRequestInfo, RequestInfo } from "../../types/request.js";
 import type { ResourceDocument } from "../../types/spec/document.js";
 import type { Meta, PaginationLinks } from "../../types/spec/json-api-raw.js";
-/**
-* A Document is a class that wraps the response content from a request to the API
-* returned by `Cache.put` or `Cache.peek`, converting ResourceKeys into
-* ReactiveResource instances.
-*
-* It is not directly instantiated by the user, and its properties should not
-* be directly modified. Whether individual properties are mutable or not is
-* determined by the record instance itself.
-*
-* @public
-* @hideconstructor
-*/
-export declare class ReactiveDocument<T> {
+export interface ReactiveDocumentBase<T> {
 	/**
 	* The links object for this document, if any
 	*
 	* e.g.
 	*
-	* ```
+	* ```ts
 	* {
 	*   self: '/articles?page[number]=3',
 	* }
@@ -31,24 +19,6 @@ export declare class ReactiveDocument<T> {
 	*/
 	readonly links?: PaginationLinks;
 	/**
-	* The primary data for this document, if any.
-	*
-	* If this document has no primary data (e.g. because it is an error document)
-	* this property will be `undefined`.
-	*
-	* For collections this will be an array of record instances,
-	* for single resource requests it will be a single record instance or null.
-	*
-	* @public
-	*/
-	readonly data?: T;
-	/**
-	* The errors returned by the API for this request, if any
-	*
-	* @public
-	*/
-	readonly errors?: object[];
-	/**
 	* The meta object for this document, if any
 	*
 	* @public
@@ -60,18 +30,12 @@ export declare class ReactiveDocument<T> {
 	* @public
 	*/
 	readonly identifier: RequestKey | null;
-	constructor(store: Store, cacheKey: RequestKey | null, localCache: {
-		document: ResourceDocument;
-		request: ImmutableRequestInfo;
-	} | null);
 	/**
 	* Fetches the related link for this document, returning a promise that resolves
 	* with the document when the request completes. If no related link is present,
 	* will fallback to the self link if present
 	*
 	* @public
-	* @param {Object} options
-	* @return {Promise<Document>}
 	*/
 	fetch(options?: RequestInfo<ReactiveDocument<T>>): Promise<ReactiveDocument<T>>;
 	/**
@@ -80,8 +44,6 @@ export declare class ReactiveDocument<T> {
 	* next link.
 	*
 	* @public
-	* @param {Object} options
-	* @return {Promise<Document | null>}
 	*/
 	next(options?: RequestInfo<ReactiveDocument<T>>): Promise<ReactiveDocument<T> | null>;
 	/**
@@ -90,8 +52,6 @@ export declare class ReactiveDocument<T> {
 	* prev link.
 	*
 	* @public
-	* @param {Object} options
-	* @return {Promise<Document | null>}
 	*/
 	prev(options: RequestInfo<ReactiveDocument<T>>): Promise<ReactiveDocument<T> | null>;
 	/**
@@ -100,8 +60,6 @@ export declare class ReactiveDocument<T> {
 	* first link.
 	*
 	* @public
-	* @param {Object} options
-	* @return {Promise<Document | null>}
 	*/
 	first(options: RequestInfo<ReactiveDocument<T>>): Promise<ReactiveDocument<T> | null>;
 	/**
@@ -110,8 +68,6 @@ export declare class ReactiveDocument<T> {
 	* last link.
 	*
 	* @public
-	* @param {Object} options
-	* @return {Promise<Document | null>}
 	*/
 	last(options: RequestInfo<ReactiveDocument<T>>): Promise<ReactiveDocument<T> | null>;
 	/**
@@ -128,3 +84,59 @@ export declare class ReactiveDocument<T> {
 	*/
 	toJSON(): object;
 }
+export interface ReactiveErrorDocument<T> extends ReactiveDocumentBase<T> {
+	/**
+	* The primary data for this document, if any.
+	*
+	* If this document has no primary data (e.g. because it is an error document)
+	* this property will be `undefined`.
+	*
+	* For collections this will be an array of record instances,
+	* for single resource requests it will be a single record instance or null.
+	*
+	* @public
+	*/
+	readonly data?: undefined;
+	/**
+	* The errors returned by the API for this request, if any
+	*
+	* @public
+	*/
+	readonly errors: object[];
+}
+export interface ReactiveDataDocument<T> extends ReactiveDocumentBase<T> {
+	/**
+	* The primary data for this document, if any.
+	*
+	* If this document has no primary data (e.g. because it is an error document)
+	* this property will be `undefined`.
+	*
+	* For collections this will be an array of record instances,
+	* for single resource requests it will be a single record instance or null.
+	*
+	* @public
+	*/
+	readonly data: T;
+	/**
+	* The errors returned by the API for this request, if any
+	*
+	* @public
+	*/
+	readonly errors?: undefined;
+}
+/**
+* A Document is a class that wraps the response content from a request to the API
+* returned by `Cache.put` or `Cache.peek`, converting ResourceKeys into
+* ReactiveResource instances.
+*
+* It is not directly instantiated by the user, and its properties should not
+* be directly modified. Whether individual properties are mutable or not is
+* determined by the record instance itself.
+*
+* @public
+*/
+export type ReactiveDocument<T> = ReactiveDataDocument<T> | ReactiveErrorDocument<T>;
+export declare function createReactiveDocument<T>(store: Store, cacheKey: RequestKey | null, localCache: {
+	document: ResourceDocument;
+	request: ImmutableRequestInfo;
+} | null): ReactiveDocument<T>;

package/declarations/reactive.d.ts

@@ -55,7 +55,7 @@
 * The shape of the object and the transformation of raw cache data into its
 * reactive form is controlled by a resource schema.
 *
-* For instance, lets say your API is a [{JSON:API}](https://jsonapi.org) and your store is using
+* For instance, lets say your API is a [{json:api}](https://jsonapi.org) and your store is using
 * the Cache provided by [@warp-drive/json-api](/api/@warp-drive/json-api), and a request
 * returns the following raw data:
 *
@@ -277,5 +277,6 @@ export { type CAUTION_MEGA_DANGER_ZONE_Extension, type ProcessedExtension, type
 export { commit, type ReactiveResource } from "./reactive/-private/record.js";
 export { checkout };
 export { Checkout } from "./reactive/-private/symbols.js";
-export { type ReactiveDocument } from "./reactive/-private/document.js";
+export { type ReactiveDocument, type ReactiveDataDocument, type ReactiveErrorDocument } from "./reactive/-private/document.js";
 export { getExpensiveRequestSubscription } from "./store/-private/new-core-tmp/expensive-subscription.js";
+export { createRequestSubscription, getRequestState, getPromiseState, type PromiseState, type RequestState } from "./store/-private.js";

package/declarations/request.d.ts

@@ -1,5 +1,30 @@
+import type { RequestInfo } from "./types/request.js";
+import type { RequestSignature } from "./types/symbols.js";
 export { createDeferred } from "./request/-private/future.js";
 export type { Future, Handler, CacheHandler, NextFn, Deferred, ManagedRequestPriority } from "./request/-private/types.js";
 export { setPromiseResult, getPromiseResult } from "./request/-private/promise-cache.js";
 export type { Awaitable } from "./request/-private/promise-cache.js";
 export type { Context } from "./request/-private/context.js";
+/**
+* Brands the supplied object with the supplied response type.
+*
+* ```ts
+* import type { ReactiveDataDocument } from '@warp-drive/core/reactive';
+* import { withResponseType } from '@warp-drive/core/request';
+* import type { User } from '#/data/user.ts'
+*
+* const result = await store.request(
+*  withResponseType<ReactiveDataDocument<User>>({ url: '/users/1' })
+* );
+*
+* result.content.data; // will have type User
+* ```
+*
+*/
+export declare function withResponseType<T>(obj: RequestInfo): RequestInfo<T> & {
+	[RequestSignature]: T;
+};
+/**
+* @deprecated use {@link withResponseType} instead
+*/
+export { withResponseType as withBrand };

package/declarations/store/-private/caches/instance-cache.d.ts

@@ -1,4 +1,4 @@
-import { ReactiveDocument } from "../../../reactive/-private/document.js";
+import { type ReactiveDocument } from "../../../reactive/-private/document.js";
 import type { Cache } from "../../../types/cache.js";
 import type { RequestKey, ResourceKey } from "../../../types/identifier.js";
 import type { TypedRecordInstance, TypeFromInstance } from "../../../types/record.js";
@@ -6,7 +6,7 @@ import type { OpaqueRecordInstance } from "../../-types/q/record-instance.js";
 import { CacheCapabilitiesManager } from "../managers/cache-capabilities-manager.js";
 import type { CacheManager } from "../managers/cache-manager.js";
 import type { CreateRecordProperties, Store } from "../store-service.js";
-export declare function peekRecordIdentifier(record: OpaqueRecordInstance): ResourceKey | undefined;
+export declare function peekResourceKey(record: OpaqueRecordInstance): ResourceKey | undefined;
 /**
 Retrieves the unique referentially-stable {@link ResourceKey}
 assigned to the given record instance.

package/declarations/store/-private/managers/cache-key-manager.d.ts

@@ -1,5 +1,5 @@
 import { type PersistedResourceKey, type RequestKey, type ResourceKey } from "../../../types/identifier.js";
-import type { ImmutableRequestInfo } from "../../../types/request.js";
+import type { RequestInfo } from "../../../types/request.js";
 import type { ExistingResourceIdentifierObject, ResourceIdentifierObject } from "../../../types/spec/json-api-raw.js";
 import type { ForgetMethod, GenerationMethod, KeyInfo, KeyInfoMethod, ResetMethod, UpdateMethod } from "../../-types/q/identifier.js";
 type TypeFromIdentifier<T> = T extends {
@@ -197,16 +197,34 @@ export declare class CacheKeyManager {
 	*
 	* @private
 	*/
-	peekRecordIdentifier(resource: ResourceIdentifierObject): ResourceKey | undefined;
+	peekResourceKey(resource: ResourceIdentifierObject): ResourceKey | undefined;
 	/**
-	Returns the DocumentIdentifier for the given Request, creates one if it does not yet exist.
-	Returns `null` if the request does not have a `cacheKey` or `url`.
-	
-	@public
+	* Peeks the {@link RequestKey} for the given {@link RequestInfo}, but will not
+	* create one if none has been previously generated.
+	*
+	* @public
+	*/
+	peekRequestKey(request: RequestInfo): RequestKey | null;
+	/**
+	* Returns the {@link RequestKey} for the given {@link RequestInfo} if the request is
+	* considered cacheable. For cacheable requests, this method will create
+	* a RequestKey if none is found.
+	*
+	* A `null` response indicates the request cannot/will not be cached,
+	* generally this means either
+	*
+	* - {@link RequestInfo.cacheOptions.key} is not present on the `RequestInfo`
+	* - the request's method is `GET` but it has no `url`
+	*
+	* Generally you should not seek to cache requests that are not idempotent
+	* or have side effects, such as mutations that create, update or delete
+	* a resource.
+	*
+	* @public
 	*/
-	getOrCreateDocumentIdentifier(request: ImmutableRequestInfo): RequestKey | null;
+	getOrCreateDocumentIdentifier(request: RequestInfo): RequestKey | null;
 	/**
-	Returns the Identifier for the given Resource, creates one if it does not yet exist.
+	Returns the {@link ResourceKey} for the given Resource, creates one if it does not yet exist.
 	
 	Specifically this means that we:
 	

package/declarations/store/-private/managers/cache-manager.d.ts

@@ -6,7 +6,7 @@ import type { LocalRelationshipOperation } from "../../../types/graph.js";
 import type { RequestKey, ResourceKey } from "../../../types/identifier.js";
 import type { Value } from "../../../types/json/raw.js";
 import type { StructuredDataDocument, StructuredDocument } from "../../../types/request.js";
-import type { ResourceDocument, SingleResourceDataDocument } from "../../../types/spec/document.js";
+import type { CollectionResourceDataDocument, ResourceDocument, SingleResourceDataDocument } from "../../../types/spec/document.js";
 import type { ApiError } from "../../../types/spec/error.js";
 import type { StoreRequestContext } from "../cache-handler/handler.js";
 /**
@@ -220,21 +220,23 @@ export declare class CacheManager implements Cache {
 	* @public
 	* @param key
 	*/
-	willCommit(key: ResourceKey, context: StoreRequestContext): void;
+	willCommit(key: ResourceKey | ResourceKey[], context: StoreRequestContext): void;
 	/**
 	* [LIFECYCLE] Signals to the cache that a resource
 	* was successfully updated as part of a save transaction.
 	*
 	* @public
 	*/
-	didCommit(key: ResourceKey, result: StructuredDataDocument<unknown>): SingleResourceDataDocument;
+	didCommit(key: ResourceKey, result: StructuredDataDocument<SingleResourceDataDocument> | null): SingleResourceDataDocument;
+	didCommit(key: ResourceKey[], result: StructuredDataDocument<SingleResourceDataDocument> | null): SingleResourceDataDocument;
+	didCommit(key: ResourceKey[], result: StructuredDataDocument<CollectionResourceDataDocument> | null): CollectionResourceDataDocument;
 	/**
 	* [LIFECYCLE] Signals to the cache that a resource
 	* was update via a save transaction failed.
 	*
 	* @public
 	*/
-	commitWasRejected(key: ResourceKey, errors?: ApiError[]): void;
+	commitWasRejected(key: ResourceKey | ResourceKey[], errors?: ApiError[]): void;
 	/**
 	* [LIFECYCLE] Signals to the cache that all data for a resource
 	* should be cleared.

package/declarations/store/deprecated/store.d.ts

@@ -254,7 +254,7 @@ declare module "../-private/store-service" {
 		
 		If you use an adapter such as the
 		[JSONAPIAdapter](/api/@warp-drive/legacy/adapter/json-api/classes/JSONAPIAdapter)
-		which supports the [{JSON:API} specification](http://jsonapi.org/) and if your server
+		which supports the [{json:api} specification](http://jsonapi.org/) and if your server
 		endpoint supports the use of an
 		['include' query parameter](http://jsonapi.org/format/#fetching-includes),
 		you can use `findRecord()` or `findAll()` to automatically retrieve additional records related to

package/declarations/types/cache.d.ts

@@ -7,7 +7,7 @@ import type { RequestKey, ResourceKey } from "./identifier.js";
 import type { Value } from "./json/raw.js";
 import type { TypeFromInstanceOrString } from "./record.js";
 import type { RequestContext, StructuredDataDocument, StructuredDocument } from "./request.js";
-import type { ResourceDocument, SingleResourceDataDocument } from "./spec/document.js";
+import type { CollectionResourceDataDocument, ResourceDocument, SingleResourceDataDocument } from "./spec/document.js";
 import type { ApiError } from "./spec/error.js";
 /**
 * A hash of changed attributes with the key being the attribute name and the value being an
@@ -253,7 +253,7 @@ export interface Cache {
 	*
 	* @public
 	*/
-	willCommit(cacheKey: ResourceKey, context: RequestContext | null): void;
+	willCommit(cacheKey: ResourceKey | ResourceKey[], context: RequestContext | null): void;
 	/**
 	* [LIFECYCLE] Signals to the cache that a resource
 	* was successfully updated as part of a save transaction.
@@ -262,14 +262,16 @@ export interface Cache {
 	* @param the primary ResourceKey that was operated on
 	* @param data - a document in the cache format containing any updated data
 	*/
-	didCommit(cacheKey: ResourceKey, result: StructuredDataDocument<unknown> | null): SingleResourceDataDocument;
+	didCommit(cacheKey: ResourceKey, result: StructuredDataDocument<SingleResourceDataDocument> | null): SingleResourceDataDocument;
+	didCommit(cacheKey: ResourceKey[], result: StructuredDataDocument<SingleResourceDataDocument> | null): SingleResourceDataDocument;
+	didCommit(cacheKey: ResourceKey[], result: StructuredDataDocument<CollectionResourceDataDocument> | null): CollectionResourceDataDocument;
 	/**
 	* [LIFECYCLE] Signals to the cache that a resource
 	* was update via a save transaction failed.
 	*
 	* @public
 	*/
-	commitWasRejected(cacheKey: ResourceKey, errors?: ApiError[]): void;
+	commitWasRejected(cacheKey: ResourceKey | ResourceKey[], errors?: ApiError[]): void;
 	/**
 	* [LIFECYCLE] Signals to the cache that all data for a resource
 	* should be cleared.

package/declarations/types/request.d.ts

@@ -350,7 +350,4 @@ export interface RequestContext {
 	setStream(stream: ReadableStream | Promise<ReadableStream | null>): void;
 	setResponse(response: Response | ResponseInfo | null): void;
 }
-export declare function withBrand<T>(obj: RequestInfo): RequestInfo<T> & {
-	[RequestSignature]: T;
-};
 export {};

package/declarations/types/symbols.d.ts

@@ -9,7 +9,7 @@ export declare const RecordStore: "___(unique) Symbol(Store)";
 * record implementations to provide a typescript
 * hint for the type of the resource.
 *
-* When used, EmberData/WarpDrive APIs can
+* When used, WarpDrive APIs can
 * take advantage of this to provide better type
 * safety and intellisense.
 *
@@ -45,7 +45,7 @@ export declare const Type: "___(unique) Symbol($type)";
 * record implementations to provide a typescript
 * hint for the type of the resource.
 *
-* When used, EmberData/WarpDrive APIs can
+* When used, WarpDrive APIs can
 * take advantage of this to provide better type
 * safety and intellisense.
 *

package/dist/graph/-private.js

@@ -3331,7 +3331,7 @@ function isReordered(relationship) {
 /**
 Provides a performance tuned normalized graph for intelligently managing relationships between resources based on identity
 
-While this Graph is abstract, it currently is a private implementation required as a peer-dependency by the {JSON:API} Cache Implementation.
+While this Graph is abstract, it currently is a private implementation required as a peer-dependency by the {json:api} Cache Implementation.
 
 We intend to make this Graph public API after some additional iteration during the 5.x timeframe, until then all APIs should be considered experimental and unstable, not fit for direct application or 3rd party library usage.
 

package/dist/{index-Cg2akouS.js → index-CKXq9_RZ.js}

@@ -1,14 +1,14 @@
 import { deprecate, warn } from '@ember/debug';
-import { withBrand, EnableHydration, SkipCache, STRUCTURED } from './types/request.js';
+import { EnableHydration, SkipCache, STRUCTURED } from './types/request.js';
 import { macroCondition, getGlobalConfig, dependencySatisfies, importSync } from '@embroider/macros';
-import { C as Context, S as SOURCE, D as Destroy, a as Checkout, b as Commit } from "./symbols-sql1_mdx.js";
+import { D as Destroy, C as Context, S as SOURCE, a as Checkout, b as Commit } from "./symbols-sql1_mdx.js";
 import { isResourceSchema } from './types/schema/fields.js';
-import { g as getPromiseResult, s as setPromiseResult, a as cloneResponseProperties, I as IS_CACHE_HANDLER, b as assertValidRequest, e as executeNextHandler, d as getRequestResult, u as upgradePromise, f as clearRequestResult } from "./future-BKkJJkj7.js";
-import { c as createSignal, a as consumeSignal, n as notifySignal, b as createMemo, d as willSyncFlushWatchers, A as ARRAY_SIGNAL, O as OBJECT_SIGNAL, w as waitFor } from "./configure-C3x8YXzL.js";
+import { w as withResponseType, g as getPromiseResult, s as setPromiseResult, c as cloneResponseProperties, I as IS_CACHE_HANDLER, a as assertValidRequest, e as executeNextHandler, b as getRequestResult, u as upgradePromise, d as clearRequestResult } from "./request-CN-dNlEY.js";
 import { getOrSetGlobal, peekTransient, setTransient, peekUniversalTransient, setUniversalTransient } from './types/-private.js';
-import { D as DefaultCachePolicy } from "./default-cache-policy-D7_u4YRH.js";
+import { c as createSignal, a as consumeSignal, n as notifySignal, b as createMemo, d as willSyncFlushWatchers, A as ARRAY_SIGNAL, O as OBJECT_SIGNAL, w as waitFor } from "./configure-C3x8YXzL.js";
 import { CACHE_OWNER, DEBUG_STALE_CACHE_OWNER, DEBUG_KEY_TYPE, DEBUG_CLIENT_ORIGINATED } from './types/identifier.js';
 import { dasherize } from './utils/string.js';
+import { D as DefaultCachePolicy } from "./default-cache-policy-D7_u4YRH.js";
 import { setLogging, getRuntimeConfig } from './types/runtime.js';
 import { RecordStore, Type } from './types/symbols.js';
 const INITIALIZER_PROTO = {
@@ -490,83 +490,10 @@ function urlFromLink(link) {
  * determined by the record instance itself.
  *
  * @public
- * @hideconstructor
  */
-class ReactiveDocument {
-  /**
-   * The links object for this document, if any
-   *
-   * e.g.
-   *
-   * ```
-   * {
-   *   self: '/articles?page[number]=3',
-   * }
-   * ```
-   *
-   * @public
-   */
-
-  /**
-   * The primary data for this document, if any.
-   *
-   * If this document has no primary data (e.g. because it is an error document)
-   * this property will be `undefined`.
-   *
-   * For collections this will be an array of record instances,
-   * for single resource requests it will be a single record instance or null.
-   *
-   * @public
-   */
-
-  /**
-   * The errors returned by the API for this request, if any
-   *
-   * @public
-   */
-
-  /**
-   * The meta object for this document, if any
-   *
-   * @public
-   */
-
-  /**
-   * The RequestKey associated with this document, if any
-   *
-   * @public
-   */
-
-  /** @internal */
-
-  /** @internal */
-
-  constructor(store, cacheKey, localCache) {
-    this._store = store;
-    this._localCache = localCache;
-    this.identifier = cacheKey;
-    const signals = withSignalStore(this);
-
-    // TODO if we ever enable auto-cleanup of the cache, we will need to tear this down
-    // in a destroy method
-    if (cacheKey) {
-      store.notifications.subscribe(cacheKey, (_key, type) => {
-        switch (type) {
-          case 'updated':
-            // FIXME in the case of a collection we need to notify it's length
-            // and have it recalc
-            notifyInternalSignal(peekInternalSignal(signals, 'data'));
-            notifyInternalSignal(peekInternalSignal(signals, 'links'));
-            notifyInternalSignal(peekInternalSignal(signals, 'meta'));
-            notifyInternalSignal(peekInternalSignal(signals, 'errors'));
-            break;
-        }
-      });
-    }
-  }
 
-  /** @internal */
-  async #request(link, options = withBrand({
+const ReactiveDocumentProto = {
+  async _request(link, options = withResponseType({
     url: '',
     method: 'GET'
   })) {
@@ -580,18 +507,8 @@ class ReactiveDocument {
     });
     const response = await this._store.request(options);
     return response.content;
-  }
-
-  /**
-   * Fetches the related link for this document, returning a promise that resolves
-   * with the document when the request completes. If no related link is present,
-   * will fallback to the self link if present
-   *
-   * @public
-   * @param {Object} options
-   * @return {Promise<Document>}
-   */
-  fetch(options = withBrand({
+  },
+  fetch(options = withResponseType({
     url: '',
     method: 'GET'
   })) {
@@ -602,73 +519,20 @@ class ReactiveDocument {
     })(this.links?.related || this.links?.self) : {};
     options.cacheOptions = options.cacheOptions || {};
     options.cacheOptions.key = this.identifier?.lid;
-    return this.#request(this.links.related ? 'related' : 'self', options);
-  }
-
-  /**
-   * Fetches the next link for this document, returning a promise that resolves
-   * with the new document when the request completes, or null  if there is no
-   * next link.
-   *
-   * @public
-   * @param {Object} options
-   * @return {Promise<Document | null>}
-   */
+    return this._request(this.links.related ? 'related' : 'self', options);
+  },
   next(options) {
-    return this.#request('next', options);
-  }
-
-  /**
-   * Fetches the prev link for this document, returning a promise that resolves
-   * with the new document when the request completes, or null if there is no
-   * prev link.
-   *
-   * @public
-   * @param {Object} options
-   * @return {Promise<Document | null>}
-   */
+    return this._request('next', options);
+  },
   prev(options) {
-    return this.#request('prev', options);
-  }
-
-  /**
-   * Fetches the first link for this document, returning a promise that resolves
-   * with the new document when the request completes, or null if there is no
-   * first link.
-   *
-   * @public
-   * @param {Object} options
-   * @return {Promise<Document | null>}
-   */
+    return this._request('prev', options);
+  },
   first(options) {
-    return this.#request('first', options);
-  }
-
-  /**
-   * Fetches the last link for this document, returning a promise that resolves
-   * with the new document when the request completes, or null if there is no
-   * last link.
-   *
-   * @public
-   * @param {Object} options
-   * @return {Promise<Document | null>}
-   */
+    return this._request('first', options);
+  },
   last(options) {
-    return this.#request('last', options);
-  }
-
-  /**
-   * Implemented for `JSON.stringify` support.
-   *
-   * Returns the JSON representation of the document wrapper.
-   *
-   * This is a shallow serialization, it does not deeply serialize
-   * the document's contents, leaving that to the individual record
-   * instances to determine how to do, if at all.
-   *
-   * @public
-   * @return
-   */
+    return this._request('last', options);
+  },
   toJSON() {
     const data = {};
     data.identifier = this.identifier;
@@ -685,9 +549,23 @@ class ReactiveDocument {
       data.meta = this.meta;
     }
     return data;
+  },
+  [Destroy]() {
+    macroCondition(getGlobalConfig().WarpDrive.env.DEBUG) ? (test => {
+      if (!test) {
+        throw new Error(`Cannot destroy a ReactiveDocument which has already been destroyed`);
+      }
+    })(this._store) : {};
+    if (this._subscription) {
+      this._store.notifications.unsubscribe(this._subscription);
+      // @ts-expect-error
+      this._store = null;
+      // @ts-expect-error
+      this._subscription = null;
+    }
   }
-}
-defineGate(ReactiveDocument.prototype, 'errors', {
+};
+defineGate(ReactiveDocumentProto, 'errors', {
   get() {
     const {
       identifier
@@ -710,7 +588,7 @@ defineGate(ReactiveDocument.prototype, 'errors', {
     return 'errors' in doc ? doc.errors : undefined;
   }
 });
-defineGate(ReactiveDocument.prototype, 'data', {
+defineGate(ReactiveDocumentProto, 'data', {
   get() {
     const {
       identifier,
@@ -737,7 +615,7 @@ defineGate(ReactiveDocument.prototype, 'data', {
     }
   }
 });
-defineGate(ReactiveDocument.prototype, 'links', {
+defineGate(ReactiveDocumentProto, 'links', {
   get() {
     const {
       identifier
@@ -754,7 +632,7 @@ defineGate(ReactiveDocument.prototype, 'links', {
     return data.links;
   }
 });
-defineGate(ReactiveDocument.prototype, 'meta', {
+defineGate(ReactiveDocumentProto, 'meta', {
   get() {
     const {
       identifier
@@ -771,6 +649,32 @@ defineGate(ReactiveDocument.prototype, 'meta', {
     return data.meta;
   }
 });
+function createReactiveDocument(store, cacheKey, localCache) {
+  const doc = Object.create(ReactiveDocumentProto);
+  doc._store = store;
+  doc._localCache = localCache;
+  // @ts-expect-error we are initializing it here
+  doc.identifier = cacheKey;
+  const signals = withSignalStore(doc);
+
+  // TODO if we ever enable auto-cleanup of the cache, we will need to tear this down
+  // in a destroy method
+  if (cacheKey) {
+    doc._subscription = store.notifications.subscribe(cacheKey, (_key, type) => {
+      switch (type) {
+        case 'updated':
+          // FIXME in the case of a collection we need to notify it's length
+          // and have it recalc
+          notifyInternalSignal(peekInternalSignal(signals, 'data'));
+          notifyInternalSignal(peekInternalSignal(signals, 'links'));
+          notifyInternalSignal(peekInternalSignal(signals, 'meta'));
+          notifyInternalSignal(peekInternalSignal(signals, 'errors'));
+          break;
+      }
+    });
+  }
+  return doc;
+}
 const TEXT_COLORS = {
   TEXT: 'inherit',
   notify: ['white', 'white', 'inherit', 'magenta', 'inherit'],
@@ -1403,15 +1307,45 @@ class CacheKeyManager {
    *
    * @private
    */
-  peekRecordIdentifier(resource) {
+  peekResourceKey(resource) {
     return this._getRecordIdentifier(resource, 0);
   }
 
   /**
-    Returns the DocumentIdentifier for the given Request, creates one if it does not yet exist.
-    Returns `null` if the request does not have a `cacheKey` or `url`.
-     @public
-  */
+   * Peeks the {@link RequestKey} for the given {@link RequestInfo}, but will not
+   * create one if none has been previously generated.
+   *
+   * @public
+   */
+  peekRequestKey(request) {
+    let cacheKey = request.cacheOptions?.key;
+    if (!cacheKey) {
+      cacheKey = this._generate(request, 'document');
+    }
+    if (!cacheKey) {
+      return null;
+    }
+    const identifier = this._cache.documents.get(cacheKey);
+    return identifier ?? null;
+  }
+
+  /**
+   * Returns the {@link RequestKey} for the given {@link RequestInfo} if the request is
+   * considered cacheable. For cacheable requests, this method will create
+   * a RequestKey if none is found.
+   *
+   * A `null` response indicates the request cannot/will not be cached,
+   * generally this means either
+   *
+   * - {@link RequestInfo.cacheOptions.key} is not present on the `RequestInfo`
+   * - the request's method is `GET` but it has no `url`
+   *
+   * Generally you should not seek to cache requests that are not idempotent
+   * or have side effects, such as mutations that create, update or delete
+   * a resource.
+   *
+   * @public
+   */
   getOrCreateDocumentIdentifier(request) {
     let cacheKey = request.cacheOptions?.key;
     if (!cacheKey) {
@@ -1436,7 +1370,7 @@ class CacheKeyManager {
   }
 
   /**
-    Returns the Identifier for the given Resource, creates one if it does not yet exist.
+    Returns the {@link ResourceKey} for the given Resource, creates one if it does not yet exist.
      Specifically this means that we:
      - validate the `id` `type` and `lid` combo against known identifiers
     - return an object with an `lid` that is stable (repeated calls with the same
@@ -1941,7 +1875,7 @@ function isDestroyable(record) {
   return Boolean(record && typeof record === 'object' && typeof record.destroy === 'function');
 }
 const RecordCache = getOrSetGlobal('RecordCache', new Map());
-function peekRecordIdentifier(record) {
+function peekResourceKey(record) {
   return RecordCache.get(record);
 }
 
@@ -2075,7 +2009,7 @@ class InstanceCache {
   getDocument(identifier) {
     let doc = this.__instances.document.get(identifier);
     if (!doc) {
-      doc = new ReactiveDocument(this.store, identifier, null);
+      doc = createReactiveDocument(this.store, identifier, null);
       this.__instances.document.set(identifier, doc);
     }
     return doc;
@@ -2207,7 +2141,7 @@ class InstanceCache {
         console.log(`InstanceCache: updating id to '${id}' for record ${String(identifier)}`);
       }
     }
-    const existingIdentifier = this.store.cacheKeyManager.peekRecordIdentifier({
+    const existingIdentifier = this.store.cacheKeyManager.peekResourceKey({
       type,
       id
     });
@@ -2584,7 +2518,9 @@ class CacheManager {
    *
    * @public
    */
+
   didCommit(key, result) {
+    // @ts-expect-error TS doesn't enable proxying overload calls
     return this.___cache.didCommit(key, result);
   }
 
@@ -5196,7 +5132,7 @@ class Store extends BaseClass {
         id
       };
       if (resource.id) {
-        const identifier = this.cacheKeyManager.peekRecordIdentifier(resource);
+        const identifier = this.cacheKeyManager.peekResourceKey(resource);
         macroCondition(getGlobalConfig().WarpDrive.env.DEBUG) ? (test => {
           if (!test) {
             throw new Error(`The id ${String(properties.id)} has already been used with another '${normalizedModelName}' record.`);
@@ -5204,7 +5140,7 @@ class Store extends BaseClass {
         })(!identifier) : {};
       }
       if (context?.lid) {
-        const identifier = this.cacheKeyManager.peekRecordIdentifier({
+        const identifier = this.cacheKeyManager.peekResourceKey({
           lid: context?.lid
         });
         resource.lid = context.lid;
@@ -5239,7 +5175,7 @@ class Store extends BaseClass {
     if (macroCondition(getGlobalConfig().WarpDrive.env.DEBUG)) {
       assertDestroyingStore(this, 'deleteRecord');
     }
-    const identifier = peekRecordIdentifier(record);
+    const identifier = peekResourceKey(record);
     const cache = this.cache;
     macroCondition(getGlobalConfig().WarpDrive.env.DEBUG) ? (test => {
       if (!test) {
@@ -5269,7 +5205,7 @@ class Store extends BaseClass {
     if (macroCondition(getGlobalConfig().WarpDrive.env.DEBUG)) {
       assertDestroyingStore(this, 'unloadRecord');
     }
-    const identifier = peekRecordIdentifier(record);
+    const identifier = peekResourceKey(record);
     if (identifier) {
       this._instanceCache.unloadRecord(identifier);
     }
@@ -5308,7 +5244,7 @@ class Store extends BaseClass {
 
   peekRecord(identifier, id) {
     if (arguments.length === 1 && isMaybeIdentifier(identifier)) {
-      const stableIdentifier = this.cacheKeyManager.peekRecordIdentifier(identifier);
+      const stableIdentifier = this.cacheKeyManager.peekResourceKey(identifier);
       const isLoaded = stableIdentifier && this._instanceCache.recordIsLoaded(stableIdentifier);
       // TODO come up with a better mechanism for determining if we have data and could peek.
       // this is basically an "are we not empty" query.
@@ -5333,7 +5269,7 @@ class Store extends BaseClass {
       type,
       id: normalizedId
     };
-    const stableIdentifier = this.cacheKeyManager.peekRecordIdentifier(resource);
+    const stableIdentifier = this.cacheKeyManager.peekResourceKey(resource);
     const isLoaded = stableIdentifier && this._instanceCache.recordIsLoaded(stableIdentifier);
     return isLoaded ? this._instanceCache.getRecord(stableIdentifier) : null;
   }
@@ -6703,7 +6639,7 @@ function maybeUpdateUiObjects(store, request, options, document) {
 
   // if we don't have an identifier, we give the document
   // its own local cache
-  return new ReactiveDocument(store, null, {
+  return createReactiveDocument(store, null, {
     request,
     document
   });
@@ -6711,9 +6647,11 @@ function maybeUpdateUiObjects(store, request, options, document) {
 function updateCacheForSuccess(store, request, options, document) {
   let response = null;
   if (isMutation(request)) {
-    const record = request.data?.record || request.records?.[0];
-    if (record) {
-      response = store.cache.didCommit(record, document);
+    if (Array.isArray(request.records)) {
+      response = store.cache.didCommit(request.records, document);
+    } else if (request.data?.record) {
+      // legacy fallback, the data option should no longer be used for this
+      response = store.cache.didCommit(request.data.record, document);
 
       // a mutation combined with a 204 has no cache impact when no known records were involved
       // a createRecord with a 201 with an empty response and no known records should similarly
@@ -6753,8 +6691,14 @@ function updateCacheForError(store, context, options, error) {
     // TODO similar to didCommit we should spec this to be similar to cache.put for handling full response
     // currently we let the response remain undefiend.
     const errors = error && error.content && typeof error.content === 'object' && 'errors' in error.content && Array.isArray(error.content.errors) ? error.content.errors : undefined;
-    const record = context.request.data?.record || context.request.records?.[0];
-    store.cache.commitWasRejected(record, errors);
+    if (Array.isArray(context.request.records)) {
+      store.cache.commitWasRejected(context.request.records, errors);
+    } else if (context.request.data?.record) {
+      // legacy fallback, the data option should no longer be used for this
+      store.cache.commitWasRejected(context.request.data.record, errors);
+    } else {
+      store.cache.put(error);
+    }
   } else {
     response = store.cache.put(error);
     return maybeUpdateUiObjects(store, context.request, options, response);
@@ -6799,15 +6743,13 @@ function fetchContentAndHydrate(next, context, identifier, priority) {
   let isMut = false;
   if (isMutation(context.request)) {
     isMut = true;
-    // TODO should we handle multiple records in request.records by iteratively calling willCommit for each
-    const record = context.request.data?.record || context.request.records?.[0];
-    macroCondition(getGlobalConfig().WarpDrive.env.DEBUG) ? (test => {
-      if (!test) {
-        throw new Error(`Expected to receive a list of records included in the ${context.request.op} request`);
-      }
-    })(record || !shouldHydrate) : {};
-    if (record) {
-      store.cache.willCommit(record, context);
+    if (Array.isArray(context.request.records)) {
+      context.request.records.forEach(record => {
+        store.cache.willCommit(record, context);
+      });
+    } else if (context.request.data?.record) {
+      // legacy fallback, the data option should no longer be used for this
+      store.cache.willCommit(context.request.data.record, context);
     }
   }
   if (store.lifetimes?.willRequest) {

package/dist/index.js

@@ -1,8 +1,8 @@
-export { C as CacheHandler, V as Fetch, W as RequestManager, S as Store, r as recordIdentifierFor, $ as setIdentifierForgetMethod, Y as setIdentifierGenerationMethod, a0 as setIdentifierResetMethod, Z as setIdentifierUpdateMethod, a1 as setKeyInfoForResource, s as storeFor, X as useRecommendedStore } from "./index-Cg2akouS.js";
+export { C as CacheHandler, V as Fetch, W as RequestManager, S as Store, r as recordIdentifierFor, $ as setIdentifierForgetMethod, Y as setIdentifierGenerationMethod, a0 as setIdentifierResetMethod, Z as setIdentifierUpdateMethod, a1 as setKeyInfoForResource, s as storeFor, X as useRecommendedStore } from "./index-CKXq9_RZ.js";
 import "./symbols-sql1_mdx.js";
-import "./default-cache-policy-D7_u4YRH.js";
 import '@ember/debug';
 import '@embroider/macros';
 import './utils/string.js';
 import "./configure-C3x8YXzL.js";
+import "./default-cache-policy-D7_u4YRH.js";
 import './types/runtime.js';

package/dist/reactive.js

@@ -1,5 +1,10 @@
-export { O as SchemaService, L as checkout, U as commit, Q as fromIdentity, M as instantiateRecord, T as registerDerivations, N as teardownRecord, P as withDefaults } from "./index-Cg2akouS.js";
+export { O as SchemaService, L as checkout, U as commit, q as createRequestSubscription, Q as fromIdentity, p as getPromiseState, t as getRequestState, M as instantiateRecord, T as registerDerivations, N as teardownRecord, P as withDefaults } from "./index-CKXq9_RZ.js";
 export { a as Checkout } from "./symbols-sql1_mdx.js";
+import './types/request.js';
+import '@embroider/macros';
+import '@ember/debug';
+import './utils/string.js';
+import "./configure-C3x8YXzL.js";
 const Subscriptions = new WeakMap();
 
 /**

package/dist/{future-BKkJJkj7.js → request-CN-dNlEY.js}

@@ -675,4 +675,24 @@ function createFuture(owner) {
   deferred.promise = promise;
   return deferred;
 }
-export { IS_CACHE_HANDLER as I, cloneResponseProperties as a, assertValidRequest as b, createDeferred as c, getRequestResult as d, executeNextHandler as e, clearRequestResult as f, getPromiseResult as g, setPromiseResult as s, upgradePromise as u };
+
+/**
+ * Brands the supplied object with the supplied response type.
+ *
+ * ```ts
+ * import type { ReactiveDataDocument } from '@warp-drive/core/reactive';
+ * import { withResponseType } from '@warp-drive/core/request';
+ * import type { User } from '#/data/user.ts'
+ *
+ * const result = await store.request(
+ *  withResponseType<ReactiveDataDocument<User>>({ url: '/users/1' })
+ * );
+ *
+ * result.content.data; // will have type User
+ * ```
+ *
+ */
+function withResponseType(obj) {
+  return obj;
+}
+export { IS_CACHE_HANDLER as I, assertValidRequest as a, getRequestResult as b, cloneResponseProperties as c, clearRequestResult as d, executeNextHandler as e, createDeferred as f, getPromiseResult as g, setPromiseResult as s, upgradePromise as u, withResponseType as w };

package/dist/request.js

@@ -1 +1 @@
-export { c as createDeferred, g as getPromiseResult, s as setPromiseResult } from "./future-BKkJJkj7.js";
+export { f as createDeferred, g as getPromiseResult, s as setPromiseResult, w as withBrand, w as withResponseType } from "./request-CN-dNlEY.js";

package/dist/store/-private.js

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

package/dist/types/-private.js

@@ -1,6 +1,6 @@
 import { macroCondition, getGlobalConfig } from '@embroider/macros';
 const name = "@warp-drive/core";
-const version = "5.8.0-alpha.6";
+const version = "5.8.0-alpha.8";
 
 // 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

@@ -70,7 +70,4 @@ const STRUCTURED = getOrSetGlobal('DOC', Symbol('DOC'));
  *
  */
 
-function withBrand(obj) {
-  return obj;
-}
-export { EnableHydration, IS_FUTURE, STRUCTURED, SkipCache, withBrand };
+export { EnableHydration, IS_FUTURE, STRUCTURED, SkipCache };

package/dist/types/symbols.js

@@ -11,7 +11,7 @@ const RecordStore = getOrSetGlobal('Store', Symbol('Store'));
  * record implementations to provide a typescript
  * hint for the type of the resource.
  *
- * When used, EmberData/WarpDrive APIs can
+ * When used, WarpDrive APIs can
  * take advantage of this to provide better type
  * safety and intellisense.
  *
@@ -48,7 +48,7 @@ const Type = getOrSetGlobal('$type', Symbol('$type'));
  * record implementations to provide a typescript
  * hint for the type of the resource.
  *
- * When used, EmberData/WarpDrive APIs can
+ * When used, WarpDrive APIs can
  * take advantage of this to provide better type
  * safety and intellisense.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@warp-drive/core",
-  "version": "5.8.0-alpha.6",
+  "version": "5.8.0-alpha.8",
   "description": "Core package for WarpDrive | All the Universal Basics",
   "keywords": [
     "ember-addon"
@@ -37,13 +37,13 @@
   },
   "dependencies": {
     "@embroider/macros": "^1.18.1",
-    "@warp-drive/build-config": "5.8.0-alpha.6"
+    "@warp-drive/build-config": "5.8.0-alpha.8"
   },
   "devDependencies": {
     "@babel/core": "^7.28.3",
     "@babel/plugin-transform-typescript": "^7.28.0",
     "@babel/preset-typescript": "^7.27.1",
-    "@warp-drive/internal-config": "5.8.0-alpha.6",
+    "@warp-drive/internal-config": "5.8.0-alpha.8",
     "decorator-transforms": "^2.3.0",
     "ember-source": "~6.6.0",
     "expect-type": "^1.2.2",