@warp-drive/core 5.8.0-alpha.3 → 5.8.0-alpha.30

package/README.md

@@ -1,52 +1,44 @@
-<h1 align="center">
-  <img
-    class="project-logo light-only"
-    src="./logos/github-header.svg#gh-light-mode-only"
-    alt="WarpDrive | Boldly go where no app has gone before"
-    title="WarpDrive | Boldly go where no app has gone before"
-    />
+<p align="center">
   <img
-    class="project-logo dark-only"
-    src="./logos/github-header.svg#gh-dark-mode-only"
-    alt="WarpDrive | Boldly go where no app has gone before"
-    title="WarpDrive | Boldly go where no app has gone before"
+    class="project-logo"
+    src="./logos/logo-yellow-slab.svg"
+    alt="WarpDrive"
+    width="180px"
+    title="WarpDrive"
     />
-</h1>
+</p>
 
-![NPM Stable Version](https://img.shields.io/npm/v/ember-data/latest?label=version&style=flat&color=FFC474)
-![NPM Downloads](https://img.shields.io/npm/dm/ember-data.svg?style=flat&color=FFC474)
-![License](https://img.shields.io/github/license/emberjs/data.svg?style=flat&color=FFC474)
-[![Docs](./logos/docs-badge.svg)](https://api.emberjs.com/ember-data/release)
-[![EmberJS Discord Community Server](https://img.shields.io/badge/EmberJS-grey?logo=discord&logoColor=FFC474)](https://discord.gg/zT3asNS
+![NPM Stable Version](https://img.shields.io/npm/v/ember-data/latest?label=version&style=flat&color=fdb155)
+![NPM Downloads](https://img.shields.io/npm/dm/ember-data.svg?style=flat&color=fdb155)
+![License](https://img.shields.io/github/license/warp-drive-data/warp-drive.svg?style=flat&color=fdb155)
+[![EmberJS Discord Community Server](https://img.shields.io/badge/EmberJS-grey?logo=discord&logoColor=fdb155)](https://discord.gg/zT3asNS
 )
-[![WarpDrive Discord Server](https://img.shields.io/badge/WarpDrive-grey?logo=discord&logoColor=FFC474)](https://discord.gg/n8BptgFzNt
+[![WarpDrive Discord Server](https://img.shields.io/badge/WarpDrive-grey?logo=discord&logoColor=fdb155)](https://discord.gg/PHBbnWJx5S
 )
 
-
 <p align="center">
   <br>
-  <a href="https://warp-drive.io">WarpDrive</a> is a lightweight data library for web apps &mdash;
+  <a href="https://warp-drive.io">WarpDrive</a> is the lightweight data library for web apps &mdash;
   <br>
   universal, typed, reactive, and ready to scale.
-  <br>
-  <br>
+  <br/><br/>
 </p>
 
-WarpDrive provides features that make it easy to build scalable, fast, feature
-rich application &mdash; letting you ship better experiences more quickly without re-architecting your app or API. WarpDrive is:
+***Warp*Drive** makes it easy to build scalable, fast, feature
+rich applications &mdash; letting you ship better experiences more quickly without re-architecting your app or API. ***Warp*Drive** is:
 
+- 🌌 Seamless Reactivity in any Framework
 - ⚡️ Committed to Best-In-Class Performance
-- 🌲 Focused on being as svelte as possible
-- 🚀 SSR Ready
 - 💚 Typed
-- 🔜 works with any framework
-- ⚛️ Supports any API: `GraphQL` `JSON:API` `REST` `tRPC` ...bespoke or a mix
+- ⚛️ Works with any API
+- 🌲 Focused on being as tiny as possible
+- 🚀 SSR Ready
 - 🐹 Built with ♥️ by [Ember](https://emberjs.com)
 
 <br>
 <br>
 
-*Get Started* → [Guides](./guides/index.md)
+*Get Started* → [Guides](https://warp-drive.io/guides/)
 
 <br>
 
@@ -54,17 +46,9 @@ rich application &mdash; letting you ship better experiences more quickly withou
 
 <br>
 
-## Installation
-
-```sh
-pnpm add -E @warp-drive/core@latest
-```
-
-<br>
-
 ## Code of Conduct
 
-Refer to the [Code of Conduct](https://github.com/emberjs/data/blob/main/CODE_OF_CONDUCT.md) for community guidelines and inclusivity.
+Refer to the [Code of Conduct](https://github.com/warp-drive-data/warp-drive/blob/main/CODE_OF_CONDUCT.md) for community guidelines and inclusivity.
 
 <br>
 

package/declarations/build-config.d.ts

@@ -1 +1,18 @@
-export { setConfig } from "@warp-drive/build-config";
+/**
+* This module provides a build-plugin that enables configuration of deprecations,
+* optional features, development/testing support and debug logging.
+*
+* Available settings include:
+*
+* - {@link LOGGING | debugging}
+* - {@link DEPRECATIONS | deprecations}
+* - {@link FEATURES | features}
+* - {@link WarpDriveConfig.polyfillUUID | polyfillUUID}
+* - {@link WarpDriveConfig.includeDataAdapterInProduction | includeDataAdapterInProduction}
+* - {@link WarpDriveConfig.compatWith | compatWith}
+*
+* @module
+*/
+import type { WarpDriveConfig } from "@warp-drive/build-config";
+export { setConfig, babelPlugin } from "@warp-drive/build-config";
+export type { WarpDriveConfig };

package/declarations/graph/-private/-edge-definition.d.ts

@@ -75,10 +75,15 @@ export declare function temporaryConvertToLegacy(field: ResourceField | Collecti
 export interface UpgradedMeta {
 	kind: "implicit" | RelationshipFieldKind;
 	/**
-	* The field name on `this` record
+	* The field sourceKey on `this` record,
+	* name if sourceKey is not set.
 	*/
 	key: string;
 	/**
+	* The field name on `this` record
+	*/
+	name: string;
+	/**
 	* The `type` of the related record
 	*
 	*/
@@ -91,10 +96,15 @@ export interface UpgradedMeta {
 	isLinksMode: boolean;
 	inverseKind: "implicit" | RelationshipFieldKind;
 	/**
-	* The field name on the opposing record
+	* The field sourceKey on the opposing record,
+	* name if sourceKey is not set.
 	*/
 	inverseKey: string;
 	/**
+	* The field name on the opposing record,
+	*/
+	inverseName: string;
+	/**
 	* The `type` of `this` record
 	*/
 	inverseType: string;

package/declarations/index.d.ts

@@ -2,13 +2,92 @@
 * @module
 * @mergeModuleWith <project>
 */
+import type { CAUTION_MEGA_DANGER_ZONE_Extension } from "./reactive.js";
 import type { ReactiveDocument } from "./reactive/-private/document.js";
-export { Fetch } from "./request/-private/fetch.js";
-export { RequestManager } from "./request/-private/manager.js";
-export { Store, type StoreRequestContext, CacheHandler, type CachePolicy, type StoreRequestInput, recordIdentifierFor, storeFor } from "./store/-private.js";
+import type { Handler } from "./request.js";
+import { Fetch } from "./request/-private/fetch.js";
+import { RequestManager } from "./request/-private/manager.js";
+import { CacheHandler, type CachePolicy, Store } from "./store/-private.js";
+import { recordIdentifierFor } from "./store/-private.js";
+import type { CacheCapabilitiesManager } from "./types.js";
+import type { Cache } from "./types/cache.js";
+import type { Derivation, HashFn, Transformation } from "./types/schema/concepts.js";
+import type { ObjectSchema, PolarisResourceSchema, Trait } from "./types/schema/fields.js";
+export { recordIdentifierFor, recordIdentifierFor as cacheKeyFor };
+export { Fetch, RequestManager };
+export { Store, CacheHandler, type CachePolicy };
+export { type StoreRequestContext, type StoreRequestInput, storeFor } from "./store/-private.js";
 /**
 * @deprecated use `ReactiveDocument` instead
 */
 export type Document<T> = ReactiveDocument<T>;
 export type { DocumentCacheOperation, CacheOperation, NotificationType } from "./store/-private/managers/notification-manager.js";
 export { setIdentifierGenerationMethod, setIdentifierUpdateMethod, setIdentifierForgetMethod, setIdentifierResetMethod, setKeyInfoForResource } from "./store/-private/managers/cache-key-manager.js";
+/**
+* Options for setting up a Store instance with `useRecommendedStore`.
+*/
+export interface StoreSetupOptions<T extends Cache = Cache> {
+	/**
+	* The Cache implementation to use
+	*/
+	cache: new (capabilities: CacheCapabilitiesManager) => T;
+	/**
+	* The Cache policy to use.
+	*
+	* Defaults to {@link DefaultCachePolicy} configured to
+	* respect `Expires`, `X-WarpDrive-Expires`, and `Cache-Control` headers
+	* with a fallback to 30s soft expiration and 15m hard expiration.
+	*/
+	policy?: CachePolicy;
+	/**
+	* The request handlers to use. {@link Fetch} will automatically
+	* be added to the end of the handler chain and {@link CacheHandler}
+	* will automatically be added as the cache handler.
+	*/
+	handlers?: Handler[];
+	/**
+	* Schemas describing the structure of your resource data.
+	*
+	* See {@link PolarisResourceSchema,} and {@link ObjectSchema} for more information.
+	*/
+	schemas?: Array<PolarisResourceSchema | ObjectSchema>;
+	/**
+	* {@link Trait | Traits} to use with {@link PolarisResourceSchema, | Resource Schemas}
+	*/
+	traits?: Trait[];
+	/**
+	* {@link Derivation | Derivations} to use for derived fields.
+	*/
+	derivations?: Derivation[];
+	/**
+	* {@link Transformation | Transformations} to use for transforming fields.
+	*/
+	transformations?: Transformation[];
+	/**
+	* {@link HashFn | Hash Functions} to use for embedded object identity and polymorphic type calculations
+	*/
+	hashFns?: HashFn[];
+	/**
+	* {@link CAUTION_MEGA_DANGER_ZONE_Extension | Extensions} to use with resources, objects and arrays
+	* to provide custom behaviors and capabilities that are not described by Schema.
+	*
+	* This feature should only be used during a transition period to support migrating towards
+	* schemas from existing Model and ModelFragments implementations.
+	*/
+	CAUTION_MEGA_DANGER_ZONE_extensions?: CAUTION_MEGA_DANGER_ZONE_Extension[];
+}
+/**
+* Creates a configured Store class with recommended defaults
+* for schema handling, reactivity, caching, and request management.
+*
+* ```ts
+* import { useRecommendedStore } from '@warp-drive/core';
+* import { JSONAPICache } from '@warp-drive/json-api';
+*
+* export const Store = useRecommendedStore({
+*   cache: JSONAPICache,
+*   schemas: [],
+* });
+* ```
+*/
+export declare function useRecommendedStore(options: StoreSetupOptions, StoreKlass?: typeof Store): typeof Store;

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/-private/record.d.ts

@@ -1,5 +1,5 @@
 import type { ObjectContext, ResourceContext } from "./default-mode.js";
-import { Checkout } from "./symbols.js";
+import { Checkout, Context } from "./symbols.js";
 export interface ReactiveResource {
 	/**
 	* Create an editable copy of the record
@@ -21,6 +21,15 @@ export interface ReactiveResource {
 	[Checkout]<T>(): Promise<T>;
 }
 /**
+* @private
+*/
+export interface PrivateReactiveResource extends ReactiveResource {
+	/**
+	* @private
+	*/
+	[Context]: ObjectContext | ResourceContext;
+}
+/**
 * A class that uses a the ResourceSchema for a ResourceType
 * and a ResourceKey to transform data from the cache into a rich, reactive
 * object.

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

@@ -8,17 +8,22 @@ import type { WithPartial } from "../../types/utils.js";
 import type { ReactiveResource } from "./record.js";
 /**
 * Extensions allow providing non-schema driven behaviors to
-* reactive resources and arrays.
+* ReactiveResources, ReactiveArrays, and ReactiveObjects.
+*
+* This should only be used for temporary migration purposes
+* to the new schema system when migrating from either Model
+* or ModelFragments.
 */
 export interface CAUTION_MEGA_DANGER_ZONE_Extension {
 	/**
 	* Whether this extension extends the behaviors of objects
-	* or of arrays.
+	* (both ReactiveObjects and ReactiveResources) or of arrays.
 	*/
 	kind: "object" | "array";
 	/**
 	* The name of the extension, to be used when specifying
-	* either `objectExtensions` or `arrayExtensions`
+	* either `objectExtensions` or `arrayExtensions` on the
+	* field, ResourceSchema or ObjectSchema
 	*/
 	name: string;
 	/**
@@ -29,6 +34,74 @@ export interface CAUTION_MEGA_DANGER_ZONE_Extension {
 	*
 	* A constructable such as a Function or Class whose prototype
 	* will be iterated with getOwnPropertyNames.
+	*
+	* Examples:
+	*
+	* **An Object with methods**
+	*
+	* ```ts
+	* store.schema.CAUTION_MEGA_DANGER_ZONE_registerExtension({
+	*    kind: 'object',
+	*    name: 'do-thing-1',
+	*    features: {
+	*      doThingOne(this: { street: string }) {
+	*        return `do-thing-1:${this.street}`;
+	*      },
+	*      doThingTwo(this: { street: string }) {
+	*        return `do-thing-1:${this.street}`;
+	*      },
+	*    },
+	*  });
+	* ```
+	*
+	* **A class with getters, methods and decorated fields**
+	*
+	* ```ts
+	* class Features {
+	*   sayHello() {
+	*     return 'hello!';
+	*   }
+	*
+	*   @tracked trackedField = 'initial tracked value';
+	*
+	*   get realName() {
+	*     const self = this as unknown as { name: string };
+	*     return self.name;
+	*   }
+	*   set realName(v: string) {
+	*     const self = this as unknown as { name: string };
+	*     self.name = v;
+	*   }
+	*
+	*   get greeting() {
+	*     const self = this as unknown as { name: string };
+	*     return `hello ${self.name}!`;
+	*   }
+	*
+	*   @computed('name')
+	*   get salutation() {
+	*     const self = this as unknown as { name: string };
+	*     return `salutations ${self.name}!`;
+	*   }
+	*
+	*   @cached
+	*   get helloThere() {
+	*     const self = this as unknown as { name: string };
+	*     return `Well Hello There ${self.name}!`;
+	*   }
+	* }
+	*
+	* // non-decorated fields dont appear on class prototypes as they are instance only
+	* // @ts-expect-error
+	* Features.prototype.untrackedField = 'initial untracked value';
+	*
+	* store.schema.CAUTION_MEGA_DANGER_ZONE_registerExtension({
+	*   kind: 'object',
+	*   name: 'my-ext',
+	*   features: Features,
+	* });
+	* ```
+	*
 	*/
 	features: Record<string | symbol, unknown> | Function;
 }
@@ -80,7 +153,7 @@ export interface ExtensibleField {
 * @param schema
 * @return {PolarisResourceSchema}
 */
-export declare function withDefaults(schema: WithPartial<PolarisResourceSchema, "identity">): ResourceSchema;
+export declare function withDefaults(schema: WithPartial<PolarisResourceSchema, "identity">): PolarisResourceSchema;
 interface FromIdentityDerivation {
 	(record: ReactiveResource, options: {
 		key: "lid";

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

@@ -1 +1,2 @@
 export { Context } from "./-private/symbols.js";
+export type { PrivateReactiveResource } from "./-private/record.js";

package/declarations/reactive.d.ts

@@ -5,8 +5,8 @@
 * reactive representations of the raw data for requests, resources and their relationships
 * stored in the cache.
 *
-* - For configuring the store to use these reactive objects, see [The Setup Guide](/guides/1-configuration/2-setup/1-universal.md)
-* - For defining resource schemas, see [The Schema Guide](/guides)
+* - For configuring the store to use these reactive objects, see [The Setup Guide](/guides/configuration/)
+* - For defining resource schemas, see [The Schema Guide](/guides/the-manual/schemas/)
 *
 * Any method that returns a record instance will use the `instantiateRecord`
 * hook configured above to instantiate a ReactiveResource once this is in place.
@@ -26,7 +26,7 @@
 * - local changes immediately reflect app wide
 * - records have all the APIs of Model (references, state props, currentState, methods etc)
 * - the continued use of `@warp-drive/legacy` is required (though most imports from it can be removed)
-* - `async: true` relationships are supported (but not recommended outside of [LinksMode](https://github.com/warp-drive-data/warp-drive/blob/main/guides/relationships/features/links-mode.md))
+* - `async: true` relationships are supported (but not recommended outside of [LinksMode](/guides/the-manual/misc/links-mode.md))
 *
 * ---
 *
@@ -38,7 +38,7 @@
 * - local changes are isolated until committed, displaying only via the editable version of the record
 * - records have a more limited API, focused on only what is in their schema.
 * - some common operations may have more friction to perform because intended utilities are not yet available
-* - `async: true` relationships are not supported (see [LinksMode](https://github.com/warp-drive-data/warp-drive/blob/main/guides/relationships/features/links-mode.md))
+* - `async: true` relationships are not supported (see [LinksMode](/guides/the-manual/misc/links-mode.md))
 * - The `@warp-drive/legacy` package is not required
 *
 * These modes are interopable. The reactive object (record) for a resource in PolarisMode can relate to
@@ -55,8 +55,8 @@
 * 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
-* the Cache provided by [@warp-drive/json-api](/api/@warp-drive/json-api), and a request
+* For instance, lets say your API is a [{json:api}](https://jsonapi.org) and your store is using
+* the Cache provided by {@link @warp-drive/json-api! | @warp-drive/json-api}, and a request
 * returns the following raw data:
 *
 * ```ts
@@ -277,5 +277,11 @@ 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, type RequestState } from "./store/-private.js";
+export { getPromiseState, type PromiseState, type ResolvedPromise, type RejectedPromise, type PendingPromise } from "./store/-private/new-core-tmp/promise-state.js";
+export type { LegacyLiveArray } from "./store/-private/record-arrays/legacy-live-array.js";
+export type { LegacyManyArray } from "./store/-private/record-arrays/legacy-many-array.js";
+export type { LegacyQueryArray } from "./store/-private/record-arrays/legacy-query.js";
+export type { ReactiveResourceArray } from "./store/-private/record-arrays/resource-array.js";

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

@@ -27,7 +27,7 @@ export type DeferredStream = {
 	};
 };
 /**
-* A Future is a {@link Promise} which resolves to a {@link StructuredDataDocument | StructuredDocument}
+* A Future is a {@link Promise} which resolves or rejects with a {@link StructuredDocument}
 * while providing the ability to {@link Future.abort | abort} the underlying request, and
 * {@link Future.getStream | access the response stream} before the outer promise resolves;
 *

package/declarations/request.d.ts

@@ -1,5 +1,52 @@
+import type { ReactiveDataDocument } from "./reactive.js";
+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;
+};
+/**
+* Brands the supplied object with the supplied response type
+* wrapped in {@link ReactiveDataDocument}. This is a convenience for
+* the common case of using {@link withResponseType} with `ReactiveDataDocument`.
+*
+* ```ts
+* import { withReactiveResponse } from '@warp-drive/core/request';
+* import type { User } from '#/data/user.ts'
+*
+* const result = await store.request(
+*   withReactiveResponse<User>({ url: '/users/1' })
+* );
+*
+* result.content.data; // will have type User
+* ```
+*
+* @public
+*/
+export declare function withReactiveResponse<T>(obj: RequestInfo): RequestInfo<ReactiveDataDocument<T>> & {
+	[RequestSignature]: ReactiveDataDocument<T>;
+};
+/**
+* @deprecated use {@link withResponseType} instead
+*/
+export declare const withBrand: typeof withResponseType;