@warp-drive-mirror/utilities 5.8.0-alpha.30 → 5.8.0-alpha.32

package/dist/unpkg/dev/declarations/-private/handlers/auto-compress.d.ts

@@ -0,0 +1,158 @@
+import type { Future, Handler, NextFn } from "@warp-drive-mirror/core/request";
+import type { RequestContext } from "@warp-drive-mirror/core/types/request";
+/**
+* Whether the browser supports `ReadableStream` as a request body
+* in a `POST` request.
+*
+* @group Constants
+*/
+export declare const SupportsRequestStreams: boolean;
+interface Constraints {
+	/**
+	* The minimum size at which to compress blobs
+	*
+	* @default 1000
+	*/
+	Blob?: number;
+	/**
+	* The minimum size at which to compress array buffers
+	*
+	* @default 1000
+	*/
+	ArrayBuffer?: number;
+	/**
+	* The minimum size at which to compress typed arrays
+	*
+	* @default 1000
+	*/
+	TypedArray?: number;
+	/**
+	* The minimum size at which to compress data views
+	*
+	* @default 1000
+	*/
+	DataView?: number;
+	/**
+	* The minimum size at which to compress strings
+	*
+	* @default 1000
+	*/
+	String?: number;
+}
+/**
+* Options for configuring the AutoCompress handler.
+*
+*/
+interface CompressionOptions {
+	/**
+	* The compression format to use. Must be a valid
+	* compression format supported by [CompressionStream](https://developer.mozilla.org/en-US/docs/Web/API/CompressionStream)
+	*
+	* The default is `gzip`.
+	*
+	*/
+	format?: CompressionFormat;
+	/**
+	* Some browsers support `ReadableStream` as a request body. This option
+	* enables passing the compression stream as the request body instead of
+	* the final compressed body when the browser supports doing so.
+	*
+	* This comes with several caveats:
+	*
+	* - the request will be put into `duplex: 'half'` mode. This should be
+	*   transparent to you, but it is worth noting.
+	* - the request mode cannot be `no-cors` as requests with a `ReadableStream`
+	*   have no content length and thus are a new form of request that triggers
+	*   cors requirements and a preflight request.
+	* - http/1.x is not supported.
+	*
+	* For additional reading about the restrictions of using `ReadableStream`
+	* as a request body, see the [Chromium Documentation](https://developer.chrome.com/docs/capabilities/web-apis/fetch-streaming-requests#restrictions)
+	*
+	* Streaming can be enabled per-request in browsers which support it by
+	* setting `request.options.allowStreaming` to `true`.
+	*
+	* Streaming can be forced even when the browser does not support it by setting
+	* `request.options.forceStreaming` to `true`. This is useful if later handlers
+	* in the chain can handle the request body as a stream.
+	*
+	* @default false
+	*/
+	allowStreaming?: boolean;
+	/**
+	* If `true`, the request will be forced into streaming mode even
+	* if the browser does not support it. This is useful if later handlers
+	* in the chain can handle the request body as a stream.
+	*
+	* @default false
+	*/
+	forceStreaming?: boolean;
+	/**
+	* The constraints for the request body. This is used to determine
+	* whether to compress the request body or not.
+	*
+	* The defaults are:
+	*
+	* ```ts
+	* {
+	*   Blob: 1000, // blob.size
+	*   ArrayBuffer: 1000, // buffer.byteLength
+	*   TypedArray: 1000, // array.byteLength
+	*   DataView: 1000, // view.byteLength
+	*   String: 1000, // string.length
+	* }
+	* ```
+	*
+	* The following body types are never compressed unless explicitly
+	* configured by the request:
+	* - `FormData`
+	* - `URLSearchParams`
+	* - `ReadableStream`
+	*
+	* A request.options.compress value of `false` will disable
+	* compression for a request body of any type. While a value of
+	* `true` will enable compression for the request.
+	*
+	* An undefined value will use the default, a value of `0` will
+	* enable compression for all values, and a value of `-1` will
+	* disable compression.
+	*
+	*/
+	constraints?: Constraints;
+}
+/**
+* A request handler that automatically compresses the request body
+* if the request body is a string, array buffer, blob, or form data.
+*
+* This uses the [CompressionStream API](https://developer.mozilla.org/en-US/docs/Web/API/CompressionStream)
+*
+* The compression format as well as the kinds of data to compress can be
+* configured using the `format` and `constraints` options.
+*
+* ```diff
+* +import { AutoCompress } from '@ember-data-mirror/request-utils/handlers';
+* import Fetch from '@ember-data-mirror/request/fetch';
+* import RequestManager from '@ember-data-mirror/request';
+* import Store from '@ember-data-mirror/store';
+*
+* class AppStore extends Store {
+*   requestManager = new RequestManager()
+*     .use([
+* +       new AutoCompress(),
+*        Fetch
+*     ]);
+* }
+* ```
+*
+* @group Handlers
+* @public
+* @since 5.5.0
+*/
+export declare class AutoCompress implements Handler {
+	options: Required<CompressionOptions> & {
+		constraints: Required<Constraints>;
+	};
+	constructor(options?: CompressionOptions);
+	request<T>({ request }: RequestContext, next: NextFn<T>): Promise<T> | Future<T>;
+}
+export {};

package/dist/unpkg/dev/declarations/-private/handlers/gated.d.ts

@@ -0,0 +1,19 @@
+import type { Future, Handler, NextFn } from "@warp-drive-mirror/core/request";
+import type { RequestContext, StructuredDataDocument } from "@warp-drive-mirror/core/types/request";
+/**
+* If CheckFn returns true, the wrapped handler will be used.
+* If CheckFn returns false, the wrapped handler will be skipped.
+*/
+type CheckFn = (context: RequestContext) => boolean;
+/**
+*
+* @group Handlers
+* @public
+*/
+export declare class Gate implements Handler {
+	handler: Handler;
+	checkFn: CheckFn;
+	constructor(handler: Handler, checkFn: CheckFn);
+	request<T = unknown>(context: RequestContext, next: NextFn<T>): Promise<T | StructuredDataDocument<T>> | Future<T>;
+}
+export {};

package/dist/unpkg/dev/declarations/-private/handlers/meta-doc.d.ts

@@ -0,0 +1,47 @@
+import type { Handler } from "@warp-drive-mirror/core/request";
+/**
+* MetaDocHandler processes requests that are marked as meta requests.
+*
+* It treats the response body as "entirely meta" transforming
+*
+* ```ts
+* {
+*   some: "key",
+*   another: "thing"
+* }
+* ```
+*
+* into
+*
+* ```ts
+* {
+* 	 meta: {
+*     some: "key",
+*     another: "thing"
+*   }
+* }
+* ```
+*
+* To activate this handler, a request should specify
+*
+* ```ts
+* options.isMetaRequest = true
+* ```
+*
+* For instance
+*
+* ```ts
+* store.request({
+*   url: '/example',
+*   options: {
+*     isMetaRequest: true
+*   }
+* });
+* ```
+*
+* Errors are not processed by this handler, so if the request fails and the error response
+* is not in {json:api} format additional processing may be needed.
+*
+* @group Handlers
+*/
+export declare const MetaDocHandler: Handler;

package/dist/unpkg/dev/declarations/-private/handlers/utils.d.ts

@@ -0,0 +1,41 @@
+/**
+* A unique identifier for the current browser tab
+* useful for observability/tracing and deduping
+* across multiple tabs.
+*
+* @group Constants
+*/
+export declare const TAB_ID: string;
+/**
+* The epoch seconds at which the tab id was generated
+*
+* @group Constants
+*/
+export declare const TAB_ASSIGNED: number;
+/**
+* Adds the `X-Amzn-Trace-Id` header to support observability
+* tooling around request routing.
+*
+* This makes use of the {@link TAB_ID} and {@link TAB_ASSIGNED}
+* to enable tracking the browser tab of origin across multiple requests.
+*
+* Follows the template: `Root=1-${now}-${uuidv4};TabId=1-${epochSeconds}-${tab-uuid}`
+*
+* @group Utility Functions
+*/
+export declare function addTraceHeader(headers: Headers): Headers;
+/**
+* Source: https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/cloudfront-limits.html
+* As of 2024-12-05 the maximum URL length is 8192 bytes.
+*
+* @group Constants
+*/
+export declare const MAX_URL_LENGTH = 8192;
+/**
+* This assertion takes a URL and throws an error if the URL is longer than the maximum URL length.
+*
+* See also {@link MAX_URL_LENGTH}
+*
+* @group Utility Functions
+*/
+export declare function assertInvalidUrlLength(url: string | undefined): void;

package/dist/unpkg/dev/declarations/-private/json-api/-utils.d.ts

@@ -0,0 +1,109 @@
+import type { QueryParamsSource } from "@warp-drive-mirror/core/types/params";
+import type { BuildURLConfig } from "../../index.js";
+export interface JSONAPIConfig extends BuildURLConfig {
+	profiles?: {
+		pagination?: string;
+		[key: string]: string | undefined;
+	};
+	extensions?: {
+		atomic?: string;
+		[key: string]: string | undefined;
+	};
+}
+export declare let CONFIG: JSONAPIConfig;
+export declare let ACCEPT_HEADER_VALUE: string;
+/**
+* Allows setting extensions and profiles to be used in the `Accept` header.
+*
+* Extensions and profiles are keyed by their namespace with the value being
+* their URI.
+*
+* Example:
+*
+* ```ts
+* setBuildURLConfig({
+*   extensions: {
+*     atomic: 'https://jsonapi.org/ext/atomic'
+*   },
+*   profiles: {
+*     pagination: 'https://jsonapi.org/profiles/ethanresnick/cursor-pagination'
+*   }
+* });
+* ```
+*
+* This also sets the global configuration for `buildBaseURL`
+* for host and namespace values for the global coniguration
+* done via `import { setBuildURLConfig } from '@warp-drive-mirror/utilities';`
+*
+* These values may still be overridden by passing
+* them to buildBaseURL directly.
+*
+* This method may be called as many times as needed
+*
+* ```ts
+* type BuildURLConfig = {
+*   host: string;
+*   namespace: string'
+* }
+* ```
+*
+* @public
+* @param {BuildURLConfig} config
+* @return {void}
+*/
+export declare function setBuildURLConfig(config: JSONAPIConfig): void;
+interface RelatedObject {
+	[key: string]: string | string[] | RelatedObject;
+}
+export type JsonApiQuery = {
+	include?: string | string[] | RelatedObject;
+	fields?: Record<string, string | string[]>;
+	page?: {
+		size?: number;
+		after?: string;
+		before?: string;
+	};
+};
+/**
+* Sorts query params by both key and value, returning a query params string
+*
+* Treats `included` specially, splicing it into an array if it is a string and sorting the array.
+*   - If `included` is an object we build paths dynamically for you
+* Treats `fields` specially, building JSON:API partial fields params from an object
+* Treats `page` specially, building cursor-pagination profile page params from an object
+*
+* ```ts
+* const params = buildQueryParams({
+*  include: {
+*    company: {
+*      locations: 'address'
+*    }
+*  },
+*   fields: {
+*     company: ['name', 'ticker'],
+*     person: 'name'
+*   },
+*   page: {
+*     size: 10,
+*     after: 'abc',
+*   }
+* });
+*
+* // => 'fields[company]=name,ticker&fields[person]=name&include=company.locations,company.locations.address&page[after]=abc&page[size]=10'
+* ```
+*
+* Options:
+* - arrayFormat: 'bracket' | 'indices' | 'repeat' | 'comma'
+*
+* 'bracket': appends [] to the key for every value e.g. `ids[]=1&ids[]=2`
+* 'indices': appends [i] to the key for every value e.g. `ids[0]=1&ids[1]=2`
+* 'repeat': appends the key for every value e.g. `ids=1&ids=2`
+* 'comma' (default): appends the key once with a comma separated list of values e.g. `ids=1,2`
+*
+* @public
+* @param {URLSearchParams | Object} params
+* @param {Object} [options]
+* @return {String} A sorted query params string without the leading `?`
+*/
+export declare function buildQueryParams(query: JsonApiQuery | QueryParamsSource): string;
+export {};

package/dist/unpkg/dev/declarations/-private/json-api/find-record.d.ts

@@ -0,0 +1,84 @@
+import type { ReactiveDataDocument } from "@warp-drive-mirror/core/reactive";
+import type { TypeFromInstance } from "@warp-drive-mirror/core/types/record";
+import type { FindRecordOptions, FindRecordRequestOptions, RemotelyAccessibleIdentifier } from "@warp-drive-mirror/core/types/request";
+/**
+* Builds request options to fetch a single resource by a known id or identifier
+* configured for the url and header expectations of most JSON:API APIs.
+*
+* :::tabs
+*
+* == Basic Usage
+*
+* ```ts
+* import { findRecord } from '@warp-drive-mirror/utilities/json-api';
+* import type { Person } from '#/data/types';
+*
+* const result = await store.request(
+*   findRecord<Person>('person', '1')
+* );
+* ```
+*
+* == With Options
+*
+* ```ts
+* import { findRecord } from '@warp-drive-mirror/utilities/json-api';
+* import type { Person } from '#/data/types';
+*
+* const data = await store.request(
+*   findRecord<Person>(
+*     'person', '1',
+*     { include: ['pets', 'friends'] }
+*   )
+* );
+* ```
+*
+* == With an Identifier
+*
+* ```ts
+* import { findRecord } from '@warp-drive-mirror/utilities/json-api';
+* import type { Person } from '#/data/types';
+*
+* const data = await store.request(
+*   findRecord<Person>(
+*     { type: 'person', id: '1' },
+*     { include: ['pets', 'friends'] }
+*   )
+* );
+* ```
+*
+* :::
+*
+* **Supplying Options to Modify the Request Behavior**
+*
+* The following options are supported:
+*
+* - `host` - The host to use for the request, defaults to the `host` configured with `setBuildURLConfig`.
+* - `namespace` - The namespace to use for the request, defaults to the `namespace` configured with `setBuildURLConfig`.
+* - `resourcePath` - The resource path to use for the request, defaults to pluralizing the supplied type
+* - `reload` - Whether to forcibly reload the request if it is already in the store, not supplying this
+*      option will delegate to the store's CachePolicy, defaulting to `false` if none is configured.
+* - `backgroundReload` - Whether to reload the request if it is already in the store, but to also resolve the
+*      promise with the cached value, not supplying this option will delegate to the store's CachePolicy,
+*      defaulting to `false` if none is configured.
+* - `urlParamsSetting` - an object containing options for how to serialize the query params (see `buildQueryParams`)
+*
+* ```ts
+* import { findRecord } from '@warp-drive-mirror/utilities/json-api';
+*
+* const data = await store.request(
+*   findRecord(
+*     'person', '1',
+*     { include: ['pets', 'friends'] },
+*     { namespace: 'api/v2' }
+*   )
+* );
+* ```
+*
+* @public
+*/
+export declare function findRecord<T>(identifier: RemotelyAccessibleIdentifier<TypeFromInstance<T>>, options?: FindRecordOptions): FindRecordRequestOptions<ReactiveDataDocument<T>, T>;
+export declare function findRecord(identifier: RemotelyAccessibleIdentifier, options?: FindRecordOptions): FindRecordRequestOptions;
+export declare function findRecord<T>(type: TypeFromInstance<T>, id: string, options?: FindRecordOptions): FindRecordRequestOptions<ReactiveDataDocument<T>, T>;
+export declare function findRecord(type: string, id: string, options?: FindRecordOptions): FindRecordRequestOptions;
+/** @deprecated use {@link ReactiveDataDocument} */
+export type FindRecordResultDocument<T> = ReactiveDataDocument<T>;

package/dist/unpkg/dev/declarations/-private/json-api/query.d.ts

@@ -0,0 +1,100 @@
+import type { ReactiveDataDocument } from "@warp-drive-mirror/core/reactive";
+import type { QueryParamsSource } from "@warp-drive-mirror/core/types/params";
+import type { TypedRecordInstance, TypeFromInstance } from "@warp-drive-mirror/core/types/record";
+import type { ConstrainedRequestOptions, PostQueryRequestOptions, QueryRequestOptions } from "@warp-drive-mirror/core/types/request";
+/**
+* Builds request options to query for resources, usually by a primary
+* type, configured for the url and header expectations of most JSON:API APIs.
+*
+* The key difference between this and `postQuery` is that this method will send the query
+* as query params in the url of a "GET" request instead of as the JSON body of a "POST"
+* request.
+*
+* **Basic Usage**
+*
+* ```ts
+* import { query } from '@warp-drive-mirror/utilities/json-api';
+*
+* const data = await store.request(query('person'));
+* ```
+*
+* **With Query Params**
+*
+* ```ts
+* import { query } from '@warp-drive-mirror/utilities/json-api';
+*
+* const options = query('person', { include: ['pets', 'friends'] });
+* const data = await store.request(options);
+* ```
+*
+* **Supplying Options to Modify the Request Behavior**
+*
+* The following options are supported:
+*
+* - `host` - The host to use for the request, defaults to the `host` configured with `setBuildURLConfig`.
+* - `namespace` - The namespace to use for the request, defaults to the `namespace` configured with `setBuildURLConfig`.
+* - `resourcePath` - The resource path to use for the request, defaults to pluralizing the supplied type
+* - `reload` - Whether to forcibly reload the request if it is already in the store, not supplying this
+*      option will delegate to the store's CachePolicy, defaulting to `false` if none is configured.
+* - `backgroundReload` - Whether to reload the request if it is already in the store, but to also resolve the
+*      promise with the cached value, not supplying this option will delegate to the store's CachePolicy,
+*      defaulting to `false` if none is configured.
+* - `urlParamsSetting` - an object containing options for how to serialize the query params (see `buildQueryParams`)
+*
+* ```ts
+* import { query } from '@warp-drive-mirror/utilities/json-api';
+*
+* const options = query('person', { include: ['pets', 'friends'] }, { reload: true });
+* const data = await store.request(options);
+* ```
+*
+* @public
+*/
+export declare function query<T extends TypedRecordInstance>(type: TypeFromInstance<T>, query?: QueryParamsSource, options?: ConstrainedRequestOptions): QueryRequestOptions<ReactiveDataDocument<T[]>>;
+export declare function query(type: string, query?: QueryParamsSource, options?: ConstrainedRequestOptions): QueryRequestOptions;
+/**
+* Builds request options to query for resources, usually by a primary
+* type, configured for the url and header expectations of most JSON:API APIs.
+*
+* The key difference between this and `query` is that this method will send the query
+* as the JSON body of a "POST" request instead of as query params in the url of a "GET"
+* request.
+*
+* A CacheKey is generated from the url and query params, and used to cache the response
+* in the store.
+*
+* ```ts
+* import { postQuery } from '@warp-drive-mirror/utilities/json-api';
+*
+* const options = postQuery('person', { include: ['pets', 'friends'] });
+* const data = await store.request(options);
+* ```
+*
+* **Supplying Options to Modify the Request Behavior**
+*
+* The following options are supported:
+*
+* - `host` - The host to use for the request, defaults to the `host` configured with `setBuildURLConfig`.
+* - `namespace` - The namespace to use for the request, defaults to the `namespace` configured with `setBuildURLConfig`.
+* - `resourcePath` - The resource path to use for the request, defaults to pluralizing the supplied type
+* - `reload` - Whether to forcibly reload the request if it is already in the store, not supplying this
+*      option will delegate to the store's CachePolicy, defaulting to `false` if none is configured.
+* - `backgroundReload` - Whether to reload the request if it is already in the store, but to also resolve the
+*      promise with the cached value, not supplying this option will delegate to the store's CachePolicy,
+*      defaulting to `false` if none is configured.
+* - `urlParamsSetting` - an object containing options for how to serialize the query params (see `buildQueryParams`)
+*
+* ```ts
+* import { postQuery } from '@warp-drive-mirror/utilities/json-api';
+*
+* const options = postQuery('person', { include: ['pets', 'friends'] }, { reload: true });
+* const data = await store.request(options);
+* ```
+*
+* @public
+* @param identifier
+* @param query
+* @param options
+*/
+export declare function postQuery<T>(type: TypeFromInstance<T>, query?: QueryParamsSource, options?: ConstrainedRequestOptions): PostQueryRequestOptions<ReactiveDataDocument<T[]>>;
+export declare function postQuery(type: string, query?: QueryParamsSource, options?: ConstrainedRequestOptions): PostQueryRequestOptions;