@warp-drive/legacy 5.9.0-alpha.2 → 5.9.0-alpha.21

package/declarations/adapter/rest.d.ts

@@ -10,22 +10,66 @@ import type { MixtBuildURLMixin } from "./-private/build-url-mixin.js";
 import type { FastBoot } from "./-private/fastboot-interface.js";
 import { AdapterError } from "./error.js";
 type Payload = Error | Record<string, unknown> | unknown[] | string | undefined;
+/**
+* The query params built by {@link RESTAdapter.buildQuery | buildQuery} for a
+* `findAll`/`findRecord` request.
+*/
 export type QueryState = {
+	/**
+	* the relationship paths to sideload
+	*/
 	include?: unknown;
+	/**
+	* a value used to request only records updated since the given value
+	*/
 	since?: unknown;
 };
+/**
+* The options passed to the native `fetch` API by {@link RESTAdapter._fetchRequest | _fetchRequest}.
+*/
 export interface FetchRequestInit extends RequestInit {
+	/**
+	* the url to request
+	*/
 	url: string;
+	/**
+	* the HTTP method to use
+	*/
 	method: HTTPMethod;
+	/**
+	* the HTTP method to use, duplicated for jQuery/fetch option compatibility
+	*/
 	type: HTTPMethod;
 }
+/**
+* The options passed to jQuery's `$.ajax` by {@link RESTAdapter._ajaxRequest | _ajaxRequest}.
+*/
 export interface JQueryRequestInit extends JQueryAjaxSettings {
+	/**
+	* the url to request
+	*/
 	url: string;
+	/**
+	* the HTTP method to use
+	*/
 	method: HTTPMethod;
+	/**
+	* the HTTP method to use, duplicated for jQuery/fetch option compatibility
+	*/
 	type: HTTPMethod;
 }
+/**
+* A minimal description of an in-flight request, used for building
+* error messages when a request fails.
+*/
 export type RequestData = {
+	/**
+	* the url that was requested
+	*/
 	url: string;
+	/**
+	* the HTTP method that was used
+	*/
 	method: HTTPMethod;
 	[key: string]: unknown;
 };
@@ -253,9 +297,21 @@ return {
 @public
 */
 declare class RESTAdapter extends AdapterWithBuildURLMixin {
+	/**
+	* @private
+	*/
 	_fastboot: FastBoot;
+	/**
+	* @private
+	*/
 	_coalesceFindRequests: boolean;
+	/**
+	* See "Host customization" above.
+	*/
 	host: string | null;
+	/**
+	* See "Namespace customization" above.
+	*/
 	namespace: string | null;
 	/**
 	This property allows ajax to still be used instead when `false`.
@@ -264,8 +320,19 @@ declare class RESTAdapter extends AdapterWithBuildURLMixin {
 	@public
 	*/
 	useFetch: boolean;
+	/**
+	* The `Content-Type` header used when serializing request bodies
+	* that don't otherwise specify one.
+	*/
 	_defaultContentType: string;
+	/**
+	* The FastBoot service instance, if running in a FastBoot environment.
+	* Lazily looked up on first access.
+	*/
 	get fastboot(): FastBoot;
+	/**
+	* Sets the FastBoot service instance to use.
+	*/
 	set fastboot(value: FastBoot);
 	/**
 	By default, the RESTAdapter will send the query params sorted alphabetically to the
@@ -592,6 +659,13 @@ declare class RESTAdapter extends AdapterWithBuildURLMixin {
 	@private
 	*/
 	_stripIDFromURL(store: Store, snapshot: Snapshot): string;
+	/**
+	* The maximum URL length to allow when coalescing `findRecord` requests
+	* into a single `findMany` request via {@link RESTAdapter.groupRecordsForFindMany | groupRecordsForFindMany}.
+	* Requests that would exceed this length are split into multiple groups.
+	*
+	* See http://stackoverflow.com/questions/417142/what-is-the-maximum-length-of-a-url-in-different-browsers
+	*/
 	maxURLLength: number;
 	/**
 	Organize records into groups, each of which is to be passed to separate

package/declarations/adapter.d.ts

@@ -244,7 +244,13 @@ included REST adapter.
 @public
 */
 export declare class Adapter extends EmberObject implements MinimumAdapterInterface {
+	/**
+	* The Store service instance that owns this Adapter.
+	*/
 	store: Store;
+	/**
+	* @private
+	*/
 	_coalesceFindRequests: boolean;
 	/**
 	The `findRecord()` method is invoked when the store is asked for a record that

package/declarations/compat/builders/find-all.d.ts

@@ -26,7 +26,6 @@ To that end, these builders are deprecated and will be removed in a future versi
 @deprecated
 @public
 @param type the name of the resource
-@param query a query to be used by the adapter
 @param options optional, may include `adapterOptions` hash which will be passed to adapter.findAll
 @return request config
 */

package/declarations/compat/extensions.d.ts

@@ -1,7 +1,19 @@
 import { type default as EmberObject } from "@ember/object";
 import type { CAUTION_MEGA_DANGER_ZONE_Extension } from "@warp-drive/core/reactive";
 declare const EmberObjectMethods: readonly ["addObserver", "cacheFor", "decrementProperty", "get", "getProperties", "incrementProperty", "notifyPropertyChange", "removeObserver", "set", "setProperties", "toggleProperty"];
+/**
+* A schema extension that adds the classic `EmberObject` API (`get`, `set`,
+* `getProperties`, `setProperties`, `incrementProperty`, `decrementProperty`,
+* `toggleProperty`, `notifyPropertyChange`, `addObserver`, `removeObserver`)
+* to reactive array resources.
+*/
 export declare const EmberObjectArrayExtension: CAUTION_MEGA_DANGER_ZONE_Extension;
+/**
+* A schema extension that adds the classic `EmberObject` API (`get`, `set`,
+* `getProperties`, `setProperties`, `incrementProperty`, `decrementProperty`,
+* `toggleProperty`, `notifyPropertyChange`, `addObserver`, `removeObserver`)
+* to reactive object resources.
+*/
 export declare const EmberObjectExtension: CAUTION_MEGA_DANGER_ZONE_Extension;
 declare const EmberArrayLikeFeatures: {
 	addObject<T>(this: T[], obj: T): T[];
@@ -46,14 +58,42 @@ declare const EmberArrayLikeFeatures: {
 	firstObject: unknown;
 	lastObject: unknown;
 };
+/**
+* A schema extension that adds Ember's classic `MutableArray`/`Enumerable`
+* style methods (`pushObject`, `removeObject`, `mapBy`, `filterBy`,
+* `sortBy`, `firstObject`, `lastObject`, etc.) to reactive array resources.
+*/
 export declare const EmberArrayLikeExtension: CAUTION_MEGA_DANGER_ZONE_Extension;
+/**
+* Extracts the element type of an array type, or `never` if `T` is not an array.
+*/
 export type ArrayType<T> = T extends ReadonlyArray<infer U> ? U : never;
+/**
+* Adds the classic `EmberObject` API (as registered by {@link EmberObjectExtension}/
+* {@link EmberObjectArrayExtension}) to the type of a reactive resource.
+*/
 export type WithEmberObject<T> = T & Pick<T & EmberObject, ArrayType<typeof EmberObjectMethods>>;
+/**
+* Adds Ember's classic array-like API (as registered by {@link EmberArrayLikeExtension})
+* to the type of a reactive array resource.
+*/
 export type WithArrayLike<T> = T extends Array<infer U> ? U & Omit<typeof EmberArrayLikeFeatures, "firstObject" | "lastObject"> & {
+	/**
+	* the first member of the array, or `undefined` if the array is empty
+	*/
 	firstObject: T | undefined;
+	/**
+	* the last member of the array, or `undefined` if the array is empty
+	*/
 	lastObject: T | undefined;
 } : T[] & Omit<typeof EmberArrayLikeFeatures, "firstObject" | "lastObject"> & {
+	/**
+	* the first member of the array, or `undefined` if the array is empty
+	*/
 	firstObject: T | undefined;
+	/**
+	* the last member of the array, or `undefined` if the array is empty
+	*/
 	lastObject: T | undefined;
 };
 export {};

package/declarations/compat/legacy-network-handler/legacy-network-handler.d.ts

@@ -1,2 +1,9 @@
 import type { Handler } from "@warp-drive/core/request";
+/**
+* A {@link Handler} that fulfills legacy `findRecord`/`findAll`/`query`/
+* `queryRecord`/`findBelongsTo`/`findHasMany`/`createRecord`/`updateRecord`/
+* `deleteRecord` requests using the store's configured {@link MinimumAdapterInterface | adapter}
+* and {@link MinimumSerializerInterface | serializer}, passing any other
+* request through to the next handler unchanged.
+*/
 export declare const LegacyNetworkHandler: Handler;

package/declarations/compat/legacy-network-handler/minimum-adapter-interface.d.ts

@@ -5,6 +5,10 @@ import type { LegacyRelationshipField as RelationshipSchema } from "@warp-drive/
 import type { Snapshot } from "./snapshot.js";
 import type { SnapshotRecordArray } from "./snapshot-record-array.js";
 type Group = Snapshot[];
+/**
+* The raw payload shape returned by a legacy adapter's request methods,
+* prior to being normalized by a {@link MinimumSerializerInterface}.
+*/
 export type AdapterPayload = Record<string, unknown> | unknown[];
 /**
 * :::danger

package/declarations/compat/legacy-network-handler/minimum-serializer-interface.d.ts

@@ -4,7 +4,14 @@ import type { ObjectValue } from "@warp-drive/core/types/json/raw";
 import type { JsonApiDocument, SingleResourceDocument } from "@warp-drive/core/types/spec/json-api-raw";
 import type { AdapterPayload } from "./minimum-adapter-interface.js";
 import type { Snapshot } from "./snapshot.js";
+/**
+* Options accepted by {@link MinimumSerializerInterface.serialize | serialize}
+* and related legacy serializer methods.
+*/
 export type SerializerOptions = {
+	/**
+	* whether the resource's id should be included in the serialized output
+	*/
 	includeId?: boolean;
 };
 export type RequestType = "findRecord" | "queryRecord" | "findAll" | "findBelongsTo" | "findHasMany" | "findMany" | "query" | "createRecord" | "deleteRecord" | "updateRecord";

package/declarations/compat/utils.d.ts

@@ -84,7 +84,18 @@ export declare function formattedType<T extends string>(type: T | string): T;
 export declare function formattedId(id: string | number): string;
 export declare function formattedId(id: null): null;
 export declare function formattedId(id: string | number | null): string | null;
+/**
+* Like {@link formattedId}, but asserts that `id` is not `null` rather
+* than allowing and passing through `null`.
+*
+* @public
+*/
 export declare function expectId(id: string | number): string;
+/**
+* Throws, since `id` is `null`.
+*
+* @public
+*/
 export declare function expectId(id: null): never;
 /**
 * Compares two types for strict equality, converting them to

package/declarations/compat.d.ts

@@ -19,11 +19,35 @@ export interface LegacyStoreCompat extends Store {
 	* @private
 	*/
 	_fetchManager: FetchManager;
+	/**
+	* Returns the adapter instance for the given model type, instantiating
+	* it (and caching the instance) if necessary. See {@link adapterFor}.
+	*/
 	adapterFor(this: Store, modelName: string): MinimumAdapterInterface;
+	/**
+	* Same as the single-argument overload, but returns `undefined` instead
+	* of throwing/asserting when `_allowMissing` is `true` and no adapter
+	* is found.
+	*/
 	adapterFor(this: Store, modelName: string, _allowMissing: true): MinimumAdapterInterface | undefined;
+	/**
+	* Returns the serializer instance for the given model type, instantiating
+	* it (and caching the instance) if necessary. See {@link serializerFor}.
+	*/
 	serializerFor<K extends string>(modelName: K, _allowMissing?: boolean): MinimumSerializerInterface | null;
+	/**
+	* Normalizes a payload for the given model type using its serializer.
+	* See {@link normalize}.
+	*/
 	normalize(modelName: string, payload: ObjectValue): ObjectValue;
+	/**
+	* Pushes a payload into the store using the appropriate serializer to
+	* normalize it first. See {@link pushPayload}.
+	*/
 	pushPayload(modelName: string, payload: ObjectValue): void;
+	/**
+	* Serializes a record using its serializer. See {@link serializeRecord}.
+	*/
 	serializeRecord(record: unknown, options?: SerializerOptions): unknown;
 	/**
 	* @private
@@ -153,5 +177,13 @@ store.pushPayload('post', pushData); // Will use the post serializer
 @param inputPayload
 */
 export declare function pushPayload(this: Store, modelName: string, inputPayload: ObjectValue): void;
+/**
+* Serializes a record using the store's legacy network layer, as with
+* {@link LegacyStoreCompat.serializeRecord | store.serializeRecord}.
+*/
 export declare function serializeRecord(this: Store, record: unknown, options?: SerializerOptions): unknown;
+/**
+* Destroys any adapters/serializers the legacy network layer has created
+* for this store, invoked when the store itself is destroyed.
+*/
 export declare function cleanup(this: Store): void;

package/declarations/index.d.ts

@@ -25,6 +25,12 @@ interface _LegacyStoreSetupOptions<T extends Cache> extends Omit<StoreSetupOptio
 	*/
 	modelFragments?: boolean;
 }
+/**
+* Setup options for a legacy store configured to use `Model` with `linksMode`
+* enabled, meaning no legacy adapter/serializer request infrastructure is required.
+*
+* @public
+*/
 export interface LegacyModelStoreSetupOptions<T extends Cache> extends _LegacyStoreSetupOptions<T> {
 	/**
 	* If true, it is presumed that no requests require use of the LegacyNetworkHandler
@@ -45,6 +51,13 @@ export interface LegacyModelStoreSetupOptions<T extends Cache> extends _LegacySt
 	*/
 	legacyRequests?: false;
 }
+/**
+* Setup options for a legacy store configured to use `Model` along with the
+* legacy adapter/serializer network layer, but without the deprecated
+* `store.findRecord`/`findAll`/`query`/etc. request methods.
+*
+* @public
+*/
 export interface LegacyModelAndNetworkStoreSetupOptions<T extends Cache> extends _LegacyStoreSetupOptions<T> {
 	/**
 	* If true, it is presumed that no requests require use of the LegacyNetworkHandler
@@ -63,6 +76,13 @@ export interface LegacyModelAndNetworkStoreSetupOptions<T extends Cache> extends
 	*/
 	legacyRequests?: false;
 }
+/**
+* Setup options for a legacy store configured to use `Model` along with the
+* legacy adapter/serializer network layer and the deprecated
+* `store.findRecord`/`findAll`/`query`/etc. request methods.
+*
+* @public
+*/
 export interface LegacyModelAndNetworkAndRequestStoreSetupOptions<T extends Cache> extends _LegacyStoreSetupOptions<T> {
 	/**
 	* If true, it is presumed that no requests require use of the LegacyNetworkHandler
@@ -81,14 +101,136 @@ export interface LegacyModelAndNetworkAndRequestStoreSetupOptions<T extends Cach
 	*/
 	legacyRequests: true;
 }
+/**
+* The available options when setting up the legacy store,
+* one of:
+*
+* - {@link LegacyModelStoreSetupOptions}
+* - {@link LegacyModelAndNetworkStoreSetupOptions}
+* - {@link LegacyModelAndNetworkAndRequestStoreSetupOptions}
+*/
 export type LegacyStoreSetupOptions<T extends Cache = Cache> = LegacyModelStoreSetupOptions<T> | LegacyModelAndNetworkStoreSetupOptions<T> | LegacyModelAndNetworkAndRequestStoreSetupOptions<T>;
 export declare class ConfiguredStore<T extends {
+	/**
+	* The {@link Cache} implementation this store was configured with.
+	*/
 	cache: Cache;
 }> extends Store {
 	createCache(capabilities: CacheCapabilitiesManager): T["cache"];
 }
 /**
 * Use the legacy store with the given options.
+*
+* See {@link LegacyStoreSetupOptions} for details on the available options.
+*
+* ```ts
+* import { useLegacyStore } from '@warp-drive/legacy';
+* import { JSONAPICache } from '@warp-drive/json-api';
+*
+* export default useLegacyStore({
+*   linksMode: false,
+*   legacyRequests: true,
+*   cache: JSONAPICache,
+*   schemas: [],
+* });
+* ```
+*
+* ### Adding Stateful Handlers
+*
+* A request {@link Handler} is sometimes more than a plain object or class
+* with a `request` method — it may need access to a stateful dependency such
+* as an Ember service (an auth token, a feature-flags service, an i18n
+* helper, etc.).
+*
+* A plain class handler that only relies on Ember's `@service` decorator will
+* not work here on its own: the handler is never instantiated *through*
+* Ember's container (it's just `new`'d up), so it has no owner and its
+* `@service` injections would fail to resolve.
+*
+* Instead, give `handlers` a function. It receives the {@link Store} instance
+* being configured, which by the time the function runs already has an owner
+* assigned. Use `getOwner`/`setOwner` from `@ember/owner` to transfer that
+* owner onto your handler instance before returning it, exactly as you would
+* when constructing any other DI-aware object outside of the container:
+*
+* ```ts
+* import { getOwner, setOwner } from '@ember/owner';
+* import { service } from '@ember/service';
+* import { useLegacyStore } from '@warp-drive/legacy';
+* import type { NextFn } from '@warp-drive/core/request';
+* import type { RequestContext } from '@warp-drive/core/types/request';
+* import { JSONAPICache } from '@warp-drive/json-api';
+*
+* class AuthHandler {
+*   @service session;
+*
+*   request<T>(context: RequestContext, next: NextFn<T>) {
+*     const headers = new Headers(context.request.headers);
+*     headers.append('Authorization', `Bearer ${this.session.accessToken}`);
+*     return next(Object.assign({}, context.request, { headers }));
+*   }
+* }
+*
+* export default useLegacyStore({
+*   linksMode: false,
+*   legacyRequests: true,
+*   cache: JSONAPICache,
+*   handlers: (store) => {
+*     const authHandler = new AuthHandler();
+*     setOwner(authHandler, getOwner(store)!);
+*     return [authHandler];
+*   },
+* });
+* ```
+*
+* The `handlers` function is invoked lazily and only once per store instance,
+* the first time `store.requestManager` is accessed, so it is safe to do
+* owner-dependent setup like this inside of it.
+*
+* ### Accessing the Store from a Handler's Context
+*
+* If a handler only needs to read something *off of the store itself*
+* (its cache, or a property/service you've attached to a custom store
+* subclass) rather than an unrelated Ember service, there is a second,
+* simpler option that requires no DI/`setOwner` wiring at all.
+*
+* Every request issued via {@link Store.request | store.request(...)}
+* automatically carries the originating store along as
+* {@link RequestInfo.store | context.request.store}. Any handler — a plain
+* object, a function-built handler, or a class — can read it directly,
+* without needing the `handlers` callback form shown above:
+*
+* ```ts
+* import { useLegacyStore } from '@warp-drive/legacy';
+* import type { NextFn } from '@warp-drive/core/request';
+* import type { RequestContext } from '@warp-drive/core/types/request';
+* import { JSONAPICache } from '@warp-drive/json-api';
+*
+* const LoggingHandler = {
+*   request<T>(context: RequestContext, next: NextFn<T>) {
+*     // only present when the request was made via `store.request(...)`
+*     const store = context.request.store;
+*     if (store) {
+*       console.log(`[${store.constructor.name}] ${context.request.url ?? ''}`);
+*     }
+*     return next(context.request);
+*   },
+* };
+*
+* export default useLegacyStore({
+*   linksMode: false,
+*   legacyRequests: true,
+*   cache: JSONAPICache,
+*   handlers: [LoggingHandler],
+* });
+* ```
+*
+* The trade-off versus the `getOwner`/`setOwner` pattern above is that
+* `context.request.store` is only populated for requests issued via
+* `store.request(...)`; a request made directly against a
+* {@link RequestManager} won't have it set unless the caller supplies it
+* explicitly, so a handler relying on it should treat it as optional (as
+* `LoggingHandler` does above).
 */
 export declare function useLegacyStore<T extends Cache>(options: LegacyModelStoreSetupOptions<T>, StoreKlass?: typeof Store): typeof ConfiguredStore<{
 	cache: T;

package/declarations/model/-private/attr.d.ts

@@ -36,6 +36,27 @@ export type AttrOptions<DV = PrimitiveValue | object | unknown[]> = {
 	*
 	*/
 	defaultValue?: DV extends PrimitiveValue ? DV : () => DV;
+	/**
+	* The name of the field as returned by the API and inserted into the
+	* cache if it differs from the name of the decorated property.
+	*
+	* For instance, if the API returns:
+	*
+	* ```ts
+	* {
+	*   attributes: {
+	*     'first-name': 'Chris'
+	*   }
+	* }
+	* ```
+	*
+	* But the app desires to use `record.firstName; // 'Chris'`, then the
+	* property should be named `firstName` and `sourceKey` should be set
+	* to `'first-name'`.
+	*
+	* This option is only needed when the value differs from the property name.
+	*/
+	sourceKey?: string;
 };
 type LooseTransformInstance<
 	V,

package/declarations/model/-private/belongs-to.d.ts

@@ -10,6 +10,27 @@ export type RelationshipOptions<
 	as?: string;
 	linksMode?: true;
 	resetOnRemoteUpdate?: boolean;
+	/**
+	* The name of the field as returned by the API and inserted into the
+	* cache if it differs from the name of the decorated property.
+	*
+	* For instance, if the API returns:
+	*
+	* ```ts
+	* {
+	*   relationships: {
+	*     'best-friend': { data: { type: 'user', id: '1' } }
+	*   }
+	* }
+	* ```
+	*
+	* But the app desires to use `record.bestFriend`, then the property
+	* should be named `bestFriend` and `sourceKey` should be set to
+	* `'best-friend'`.
+	*
+	* This option is only needed when the value differs from the property name.
+	*/
+	sourceKey?: string;
 };
 export type NoNull<T> = Exclude<T, null>;
 export type RelationshipDecorator<T> = <This>(target: This, key: string, desc?: PropertyDescriptor) => void;

package/declarations/model/-private/hooks.d.ts

@@ -2,9 +2,35 @@ import { type Store } from "@warp-drive/core/store/-private";
 import type { ResourceKey } from "@warp-drive/core/types/identifier";
 import type { TypeFromInstance } from "@warp-drive/core/types/record";
 import type { Model } from "./model.js";
+/**
+* The `instantiateRecord` hook implementation for use with `Model`. Pass
+* this to your store's `instantiateRecord` method when configuring the
+* store to use `Model` for schema/record instantiation.
+*
+* @public
+*/
 export declare function instantiateRecord(this: Store, identifier: ResourceKey, createRecordArgs?: {
 	[key: string]: unknown;
 }): Model;
+/**
+* The `teardownRecord` hook implementation for use with `Model`. Pass this
+* to your store's `teardownRecord` method when configuring the store to
+* use `Model` for schema/record instantiation.
+*
+* @public
+*/
 export declare function teardownRecord(record: Model): void;
+/**
+* The `modelFor` implementation for use with `Model`, exposed on the store
+* as `store.modelFor(type)` when the store is configured to use `Model`.
+* Returns the `Model` subclass registered for the given type, if any.
+*
+* @public
+*/
 export declare function modelFor<T>(type: TypeFromInstance<T>): typeof Model | void;
+/**
+* Overload accepting a raw type string instead of a typed record instance.
+*
+* @public
+*/
 export declare function modelFor(type: string): typeof Model | void;