@warp-drive-mirror/core 5.10.0-alpha.12 → 5.10.0-alpha.13

package/dist/unpkg/prod-deprecated/types/request.js.map

@@ -1 +1 @@
-{"version":3,"file":"request.js","names":["getOrSetGlobal","getOrSetUniversal","SkipCache","Symbol","for","EnableHydration","IS_FUTURE","STRUCTURED"],"sources":["../../../../src/types/request.ts"],"sourcesContent":["// oxlint-disable-next-line no-unused-vars\nimport type { Future, Handler } from '../request.ts';\n// oxlint-disable-next-line no-unused-vars\nimport type { Fetch } from '../request/-private/fetch.ts';\n// oxlint-disable-next-line no-unused-vars\nimport type { RequestManager } from '../request/-private/manager.ts';\nimport type { FetchError } from '../request/-private/utils.ts';\n// oxlint-disable-next-line no-unused-vars\nimport type { RequestLoadingState } from '../signals/request-state.ts';\nimport type { Store } from '../store/-private.ts';\nimport { getOrSetGlobal, getOrSetUniversal } from './-private.ts';\nimport type { ResourceKey } from './identifier.ts';\nimport type { QueryParamsSerializationOptions } from './params.ts';\nimport type {\n  // oxlint-disable-next-line no-unused-vars\n  Includes,\n  TypeFromInstanceOrString,\n} from './record.ts';\nimport type { ResourceIdentifierObject } from './spec/json-api-raw.ts';\nimport type { RequestSignature } from './symbols.ts';\n\n/**\n * A {@link RequestInfo.cacheOptions | cacheOptions} flag which, when set,\n * signals that a request should never be handled by the cache-manager and\n * thus will never resolve from cache nor update the cache.\n */\nexport const SkipCache: '___(unique) Symbol(SkipCache)' = getOrSetUniversal('SkipCache', Symbol.for('wd:skip-cache'));\n/**\n * A {@link RequestInfo} flag which, when set, signals to the store's\n * `instantiateRecord` hook that the resolved content should be hydrated\n * into reactive records rather than returned as raw data.\n */\nexport const EnableHydration: '___(unique) Symbol(EnableHydration)' = getOrSetUniversal(\n  'EnableHydration',\n  Symbol.for('wd:enable-hydration')\n);\n/**\n * @private\n */\nexport const IS_FUTURE: '___(unique) Symbol(IS_FUTURE)' = getOrSetGlobal('IS_FUTURE', Symbol('IS_FUTURE'));\n/**\n * @private\n */\nexport const STRUCTURED: '___(unique) Symbol(DOC)' = getOrSetGlobal('DOC', Symbol('DOC'));\n\nexport type { FetchError };\n\n/**\n * The HTTP methods WarpDrive's request layer supports.\n */\nexport type HTTPMethod =\n  | 'QUERY'\n  | 'GET'\n  | 'OPTIONS'\n  | 'POST'\n  | 'PUT'\n  | 'PATCH'\n  | 'DELETE'\n  | 'HEAD'\n  | 'CONNECT'\n  | 'TRACE';\n\n/**\n * Use these options to adjust {@link CacheHandler} behavior for a request\n * via {@link RequestInfo.cacheOptions}.\n *\n */\nexport interface CacheOptions {\n  /**\n   * A key that uniquely identifies this request. If not present, the url wil be used\n   * as the key for any GET request, while all other requests will not be cached.\n   *\n   */\n  key?: string;\n  /**\n   * If true, the request will be made even if a cached response is present\n   * and not expired.\n   *\n   */\n  reload?: boolean;\n  /**\n   * If true, and a cached response is present and not expired, the request\n   * will be made in the background and the cached response will be returned.\n   *\n   */\n  backgroundReload?: boolean;\n  /**\n   * Useful for metadata around when to invalidate the cache. Typically used\n   * by strategies that invalidate requests by resource type when a new resource\n   * of that type has been created. See the CachePolicy implementation\n   * provided by `@ember-data-mirror/request-utils` for an example.\n   *\n   * It is recommended to only use this for query/queryRecord requests where\n   * new records created later would affect the results, though using it for\n   * findRecord requests is also supported if desired where it may be useful\n   * when a create may affect the result of a sideloaded relationship.\n   *\n   * Generally it is better to patch the cache directly for relationship updates\n   * than to invalidate findRecord requests for one.\n   *\n   */\n  // TODO: Ideally this would be T extends TypedRecordInstance ? ExtractSuggestedCacheTypes<T>[] : string[];\n  // but that leads to `Type instantiation is excessively deep and possibly infinite.`\n  // issues when `T` has many properties.\n  types?: string[];\n\n  /**\n   * If true, the request will never be handled by the cache-manager and thus\n   * will never resolve from cache nor update the cache.\n   *\n   * Generally this is only used for legacy request that manage resource cache\n   * updates in a non-standard way via the LegacyNetworkHandler.\n   *\n   */\n  [SkipCache]?: boolean;\n}\n/**\n * The request shape produced by the `findRecord` request builders, for\n * use with {@link Store.request}.\n */\nexport type FindRecordRequestOptions<RT = unknown, T = unknown> = {\n  /**\n   * the url to request\n   */\n  url: string;\n  /**\n   * the HTTP method to use\n   */\n  method: 'GET';\n  /**\n   * the headers to send with the request\n   */\n  headers: Headers;\n  /**\n   * see {@link CacheOptions}\n   */\n  cacheOptions?: CacheOptions;\n  /**\n   * the name of the request operation\n   */\n  op: 'findRecord';\n  /**\n   * the resource being requested\n   */\n  records: [ResourceIdentifierObject<TypeFromInstanceOrString<T>>];\n  /**\n   * @private used only to carry the response type for type inference purposes\n   */\n  [RequestSignature]?: RT;\n};\n\n/**\n * The request shape produced by the `query` request builders, for\n * use with {@link Store.request}.\n */\nexport type QueryRequestOptions<RT = unknown> = {\n  /**\n   * the url to request\n   */\n  url: string;\n  /**\n   * the HTTP method to use\n   */\n  method: 'GET';\n  /**\n   * the headers to send with the request\n   */\n  headers: Headers;\n  /**\n   * see {@link CacheOptions}\n   */\n  cacheOptions?: CacheOptions;\n  /**\n   * the name of the request operation\n   */\n  op: 'query';\n  /**\n   * @private used only to carry the response type for type inference purposes\n   */\n  [RequestSignature]?: RT;\n};\n\n/**\n * The request shape produced by the `postQuery` request builders, for\n * use with {@link Store.request}.\n */\nexport type PostQueryRequestOptions<RT = unknown> = {\n  /**\n   * the url to request\n   */\n  url: string;\n  /**\n   * the HTTP method to use\n   */\n  method: 'POST' | 'QUERY';\n  /**\n   * the headers to send with the request\n   */\n  headers: Headers;\n  /**\n   * the body to send with the request\n   */\n  body?: string | BodyInit | FormData;\n  /**\n   * see {@link CacheOptions}. A `key` is required since `POST`/`QUERY`\n   * requests otherwise have no cache-safe way to derive one from the url.\n   */\n  cacheOptions: CacheOptions & {\n    /**\n     * a key that uniquely identifies this request\n     */\n    key: string;\n  };\n  /**\n   * the name of the request operation\n   */\n  op: 'query';\n  /**\n   * @private used only to carry the response type for type inference purposes\n   */\n  [RequestSignature]?: RT;\n};\n\n/**\n * The request shape produced by the `deleteRecord` request builders, for\n * use with {@link Store.request}.\n */\nexport type DeleteRequestOptions<RT = unknown, T = unknown> = {\n  /**\n   * the url to request\n   */\n  url: string;\n  /**\n   * the HTTP method to use\n   */\n  method: 'DELETE';\n  /**\n   * the headers to send with the request\n   */\n  headers: Headers;\n  /**\n   * the name of the request operation\n   */\n  op: 'deleteRecord';\n  /**\n   * the body to send with the request\n   */\n  body?: string | BodyInit | FormData;\n  /**\n   * data for handlers to convert into the request body\n   */\n  data: {\n    /**\n     * the resource being deleted\n     */\n    record: ResourceKey<TypeFromInstanceOrString<T>>;\n  };\n  /**\n   * the resource being deleted\n   */\n  records: [ResourceIdentifierObject<TypeFromInstanceOrString<T>>];\n  /**\n   * @private used only to carry the response type for type inference purposes\n   */\n  [RequestSignature]?: RT;\n};\n\ntype ImmutableRequest<T> = Readonly<T> & {\n  readonly headers: ImmutableHeaders;\n  readonly records: [ResourceKey];\n};\n\n/**\n * The request shape produced by the `updateRecord` request builders, for\n * use with {@link Store.request}.\n */\nexport type UpdateRequestOptions<RT = unknown, T = unknown> = {\n  /**\n   * the url to request\n   */\n  url: string;\n  /**\n   * the HTTP method to use\n   */\n  method: 'PATCH' | 'PUT';\n  /**\n   * the headers to send with the request\n   */\n  headers: Headers;\n  /**\n   * the name of the request operation\n   */\n  op: 'updateRecord';\n  /**\n   * the body to send with the request\n   */\n  body?: string | BodyInit | FormData;\n  /**\n   * data for handlers to convert into the request body\n   */\n  data: {\n    /**\n     * the resource being updated\n     */\n    record: ResourceKey<TypeFromInstanceOrString<T>>;\n  };\n  /**\n   * the resource being updated\n   */\n  records: [ResourceIdentifierObject<TypeFromInstanceOrString<T>>];\n  /**\n   * @private used only to carry the response type for type inference purposes\n   */\n  [RequestSignature]?: RT;\n};\n\n/**\n * The request shape produced by the `createRecord` request builders, for\n * use with {@link Store.request}.\n */\nexport type CreateRequestOptions<RT = unknown, T = unknown> = {\n  /**\n   * the url to request\n   */\n  url: string;\n  /**\n   * the HTTP method to use\n   */\n  method: 'POST';\n  /**\n   * the headers to send with the request\n   */\n  headers: Headers;\n  /**\n   * the name of the request operation\n   */\n  op: 'createRecord';\n  /**\n   * the body to send with the request\n   */\n  body?: string | BodyInit | FormData;\n  /**\n   * data for handlers to convert into the request body\n   */\n  data: {\n    /**\n     * the resource being created\n     */\n    record: ResourceKey<TypeFromInstanceOrString<T>>;\n  };\n  /**\n   * the resource being created\n   */\n  records: [ResourceIdentifierObject<TypeFromInstanceOrString<T>>];\n  /**\n   * @private used only to carry the response type for type inference purposes\n   */\n  [RequestSignature]?: RT;\n};\n\n/**\n * The immutable, handler-facing form of {@link DeleteRequestOptions}.\n */\nexport type ImmutableDeleteRequestOptions = ImmutableRequest<DeleteRequestOptions>;\n/**\n * The immutable, handler-facing form of {@link UpdateRequestOptions}.\n */\nexport type ImmutableUpdateRequestOptions = ImmutableRequest<UpdateRequestOptions>;\n/**\n * The immutable, handler-facing form of {@link CreateRequestOptions}.\n */\nexport type ImmutableCreateRequestOptions = ImmutableRequest<CreateRequestOptions>;\n\n/**\n * A minimal reference to a resource sufficient to build a URL for it,\n * as accepted by the request builders.\n */\nexport type RemotelyAccessibleIdentifier<T extends string = string> = {\n  /**\n   * the resource's persisted id\n   */\n  id: string;\n  /**\n   * the resource's type\n   */\n  type: T;\n  /**\n   * the local identifier WarpDrive has assigned to the resource, if known\n   */\n  lid?: string;\n};\n\n/**\n * Options accepted by the request builders for constraining how a\n * request's url is constructed and how the request interacts with the cache.\n */\nexport interface ConstrainedRequestOptions {\n  /**\n   * If true, the request will be made even if a cached response is present\n   * and not expired.\n   */\n  reload?: boolean;\n  /**\n   * If true, and a cached response is present and not expired, the request\n   * will be made in the background and the cached response will be returned.\n   */\n  backgroundReload?: boolean;\n  /**\n   * The host to use when constructing the request's url, overriding any\n   * host configured via `setBuildURLConfig`.\n   */\n  host?: string;\n  /**\n   * The namespace to use when constructing the request's url, overriding\n   * any namespace configured via `setBuildURLConfig`.\n   */\n  namespace?: string;\n  /**\n   * The resource path to use when constructing the request's url,\n   * overriding the default of pluralizing the resource's type.\n   */\n  resourcePath?: string;\n  /**\n   * Options for how to serialize the request's query params, see {@link QueryParamsSerializationOptions}.\n   */\n  urlParamsSettings?: QueryParamsSerializationOptions;\n}\n\n/**\n * Options accepted by the `findRecord` request builders.\n */\nexport interface FindRecordOptions extends ConstrainedRequestOptions {\n  /**\n   * the relationship paths to sideload, see {@link Includes}\n   */\n  include?: string | string[];\n}\n\n/**\n * When a {@link Future} resolves, it returns an object\n * containing the original {@link RequestInfo | request},\n * the {@link Response | response} set by the handler chain (if any), and\n * the processed content.\n */\nexport interface StructuredDataDocument<T> {\n  /**\n   * @private\n   */\n  [STRUCTURED]?: true;\n  /**\n   * @see {@link ImmutableRequestInfo}\n   */\n  request: ImmutableRequestInfo;\n  /**\n   * the response set by the handler chain, if any\n   */\n  response: Response | ResponseInfo | null;\n  /**\n   * the processed content of the response\n   */\n  content: T;\n}\n\n/**\n * When a {@link Future} rejects, it throws either an {@link Error}\n * an {@link AggregateError} or a {@link DOMException} that maintains\n * the `{ request, response, content }` shape but is also an Error instance\n * itself.\n *\n * If using the error originates from the {@link Fetch | Fetch Handler}\n * the error will be a {@link FetchError}\n */\nexport interface StructuredErrorDocument<T = unknown> extends Error {\n  /**\n   * @private\n   */\n  [STRUCTURED]?: true;\n  /**\n   * @see {@link ImmutableRequestInfo}\n   */\n  request: ImmutableRequestInfo;\n  /**\n   * the response set by the handler chain, if any\n   */\n  response: Response | ResponseInfo | null;\n  /**\n   * the error that caused the request to fail\n   */\n  error: string | object;\n  /**\n   * the processed content of the response, if any was received before the failure\n   */\n  content?: T;\n}\n\n/**\n * A union of the resolve/reject data types for the {@link Future}\n * returned by {@link Store.request | request}\n *\n * See also the docs for:\n *\n * - {@link Future}\n * - {@link StructuredDataDocument} (resolved/successful requests)\n * - {@link StructuredErrorDocument} (rejected/failed requests)\n */\nexport type StructuredDocument<T> = StructuredDataDocument<T> | StructuredErrorDocument<T>;\n\n/**\n * The {@link RequestInit} interface accepted by the native {@link fetch} API.\n *\n * WarpDrive provides our own typings due to incompleteness in the native typings.\n *\n * @privateRemarks\n * - [MDN Reference (fetch)](https://developer.mozilla.org/docs/Web/API/Window/fetch)\n * - [MDN Reference (RequestInit)](https://developer.mozilla.org/en-US/docs/Web/API/RequestInit)\n * - [MDN Reference (Request)](https://developer.mozilla.org/docs/Web/API/Request)\n *\n */\ninterface NativeRequestInit {\n  /** Returns the cache mode associated with request, which is a string indicating how the request will interact with the browser's cache when fetching.\n   */\n  cache?: RequestCache;\n  /** Returns the credentials mode associated with request, which is a string indicating whether credentials will be sent with the request always, never, or only when sent to a same-origin URL.\n   */\n  credentials?: RequestCredentials;\n  /** Returns the kind of resource requested by request, e.g., \"document\" or \"script\".\n   */\n  destination?: RequestDestination;\n  /** Returns a Headers object consisting of the headers associated with request. Note that headers added in the network layer by the user agent will not be accounted for in this object, e.g., the \"Host\" header.\n   */\n  headers?: Headers;\n  /** Returns request's subresource integrity metadata, which is a cryptographic hash of the resource being fetched. Its value consists of multiple hashes separated by whitespace. [SRI]\n   */\n  integrity?: string;\n  /** Returns a boolean indicating whether or not request can outlive the global in which it was created.\n   */\n  keepalive?: boolean;\n  /** Returns request's HTTP method, which is \"GET\" by default.\n   */\n  method?: HTTPMethod;\n  /** Returns the mode associated with request, which is a string indicating whether the request will use CORS, or will be restricted to same-origin URLs.\n   *\n   * `no-cors` is not allowed for streaming request bodies.\n   *\n   */\n  mode?: RequestMode;\n  /**\n   * provides an explicit priority hint for the request.\n   */\n  priority?: RequestPriority;\n  /** Returns the redirect mode associated with request, which is a string indicating how redirects for the request will be handled during fetching. A request will follow redirects by default.\n   */\n  redirect?: RequestRedirect;\n  /** Returns the referrer of request. Its value can be a same-origin URL if explicitly set in init, the empty string to indicate no referrer, and \"about:client\" when defaulting to the global's default. This is used during fetching to determine the value of the `Referer` header of the request being made.\n   */\n  referrer?: string;\n  /** Returns the referrer policy associated with request. This is used during fetching to compute the value of the request's referrer.\n   */\n  referrerPolicy?: ReferrerPolicy;\n  /** Returns the signal associated with request, which is an AbortSignal object indicating whether or not request has been aborted, and its abort event handler.\n   */\n  signal?: AbortSignal;\n  /** Returns the URL of request as a string.\n   */\n  url?: string;\n  /** Any body that you want to add to your request. Note that a GET or HEAD request may not have a body.\n   */\n  body?: BodyInit | null;\n\n  /**\n   * When sending a ReadableStream as the body of a request, 'half' must be\n   * specified.\n   *\n   * [Half Duplex Further Reading](https://developer.chrome.com/docs/capabilities/web-apis/fetch-streaming-requests#half_duplex)\n   *\n   */\n  duplex?: 'half';\n}\n\n/**\n * A read-only {@link Headers} instance, as passed to {@link Handler | Handlers}\n * via {@link ImmutableRequestInfo.headers}.\n */\nexport interface ImmutableHeaders extends Headers {\n  /**\n   * Returns a mutable clone of these headers, if supported by the implementation.\n   */\n  clone?(): Headers;\n  /**\n   * Returns the headers as an array of `[key, value]` pairs.\n   */\n  toJSON(): [string, string][];\n}\n\n/**\n * Extends JavaScript's native {@link fetch} {@link NativeRequestInit | RequestInit} with additional\n * properties specific to the {@link RequestManager | RequestManager's} capabilities.\n *\n * This interface is used to define the shape of a request that can be made via\n * either the {@link RequestManager.request} or {@link Store.request} methods.\n *\n * @privateRemarks\n * - [MDN Reference (fetch)](https://developer.mozilla.org/docs/Web/API/Window/fetch)\n * - [MDN Reference (RequestInit)](https://developer.mozilla.org/en-US/docs/Web/API/RequestInit)\n * - [MDN Reference (Request)](https://developer.mozilla.org/docs/Web/API/Request)\n *\n * @public\n * @since 4.12\n */\nexport interface RequestInfo<RT = unknown> extends NativeRequestInit {\n  /**\n   * If provided, used instead of the AbortController auto-configured for each request by the RequestManager\n   *\n   */\n  controller?: AbortController;\n\n  /**\n   * @see {@link CacheOptions}\n   */\n  cacheOptions?: CacheOptions;\n  /**\n   * The {@link Store} the request was made against, if made via\n   * {@link Store.request} rather than directly against a {@link RequestManager}.\n   *\n   * A {@link Handler} can read this off of {@link RequestContext.request | context.request}\n   * to reach store state (the cache, other services attached to a custom\n   * store subclass, etc.) without needing any Ember DI/`setOwner` wiring at\n   * handler-construction time. This works for a handler of any shape (a\n   * function, plain object, or class) because the store is attached to each\n   * request individually rather than to the handler itself.\n   *\n   * The trade-off is that this is only populated for requests issued via\n   * {@link Store.request | store.request(...)}; a request issued directly\n   * against a {@link RequestManager} will not have it set unless the caller\n   * supplies it explicitly. Handlers that rely on it should treat it as\n   * optional.\n   *\n   * @example\n   * ```ts\n   * const LoggingHandler = {\n   *   request<T>(context: RequestContext, next: NextFn<T>) {\n   *     const store = context.request.store;\n   *     if (store) {\n   *       console.log(`[${store.constructor.name}] ${context.request.url ?? ''}`);\n   *     }\n   *     return next(context.request);\n   *   },\n   * };\n   * ```\n   */\n  store?: Store;\n\n  /**\n   * The name of the request operation, if any (e.g. `'findRecord'`, `'query'`).\n   */\n  op?: string;\n\n  /**\n   * The {@link ResourceKey | ResourceKeys} of the primary resources involved in the request\n   * (if any). This may be used by handlers to perform transactional\n   * operations on the store.\n   *\n   */\n  records?: ResourceKey[];\n\n  /**\n   * If true, this request will not be tracked by test waiters.\n   */\n  disableTestWaiter?: boolean;\n  /**\n   * data that a handler should convert into\n   * the query (GET) or body (POST).\n   *\n   * Note: It is recommended that builders set query params\n   * and body directly in most scenarios.\n   *\n   */\n  data?: Record<string, unknown>;\n  /**\n   * options specifically intended for {@link Handler | Handlers}\n   * to utilize to process the request\n   *\n   */\n  options?: Record<string, unknown>;\n\n  /**\n   * @private used only to carry the response type for type inference purposes\n   */\n  [RequestSignature]?: RT;\n\n  /**\n   * see {@link EnableHydration}\n   */\n  [EnableHydration]?: boolean;\n}\n\n/**\n * Immutable version of {@link RequestInfo}. This is what is passed to handlers.\n *\n */\nexport type ImmutableRequestInfo<RT = unknown> = Readonly<Omit<RequestInfo<RT>, 'controller'>> & {\n  /**\n   * see {@link CacheOptions}\n   */\n  readonly cacheOptions?: Readonly<CacheOptions>;\n  /**\n   * see {@link ImmutableHeaders}\n   */\n  readonly headers?: ImmutableHeaders;\n  /**\n   * see {@link RequestInfo.data}\n   */\n  readonly data?: Readonly<Record<string, unknown>>;\n  /**\n   * see {@link RequestInfo.options}\n   */\n  readonly options?: Readonly<Record<string, unknown>>;\n\n  /** Whether the request body has been read.\n   */\n  readonly bodyUsed?: boolean;\n};\n\n/**\n * An immutable, JSON-serializable subset of the native {@link Response}\n * interface.\n */\nexport interface ResponseInfo {\n  /**\n   * see {@link ImmutableHeaders}\n   */\n  readonly headers: ImmutableHeaders; // to do, maybe not this?\n  /**\n   * whether the response's status code was in the 200-299 range\n   */\n  readonly ok: boolean;\n  /**\n   * whether the response is the result of a redirect\n   */\n  readonly redirected: boolean;\n  /**\n   * the response's HTTP status code\n   */\n  readonly status: number;\n  /**\n   * the status message associated with the response's status code\n   */\n  readonly statusText: string;\n  /**\n   * the type of the response, see [MDN Reference](https://developer.mozilla.org/docs/Web/API/Response/type)\n   */\n  readonly type: ResponseType;\n  /**\n   * the url of the response\n   */\n  readonly url: string;\n}\n\n/**\n * The object a {@link Handler} uses to fulfill a request: it provides a\n * readonly view of the {@link RequestContext.request | request} and methods\n * for supplying the {@link Future}'s stream and final response.\n */\nexport interface RequestContext {\n  /**\n   * @see {@link ImmutableRequestInfo}\n   */\n  request: ImmutableRequestInfo;\n  /**\n   * a unique id for this request\n   */\n  id: number;\n\n  /**\n   * Supplies the stream of the response's content, if available, enabling\n   * consumers to monitor download progress via {@link RequestLoadingState}.\n   */\n  setStream(stream: ReadableStream | Promise<ReadableStream | null>): void;\n  /**\n   * Supplies the response for the request.\n   */\n  setResponse(response: Response | ResponseInfo | null): void;\n}\n"],"mappings":";;;;;;;;AA0BA,MAAaE,YAA6CD,kBAAkB,aAAaE,OAAOC,IAAI,eAAe,CAAC;;;;;;AAMpH,MAAaC,kBAAyDJ,kBACpE,mBACAE,OAAOC,IAAI,qBAAqB,CAClC;;;;AAIA,MAAaE,YAA6CN,eAAe,aAAaG,OAAO,WAAW,CAAC;;;;AAIzG,MAAaI,aAAwCP,eAAe,OAAOG,OAAO,KAAK,CAAC"}
+{"version":3,"file":"request.js","names":["getOrSetGlobal","getOrSetUniversal","SkipCache","Symbol","for","EnableHydration","IS_FUTURE","STRUCTURED"],"sources":["../../../../src/types/request.ts"],"sourcesContent":["/**\n * @module\n * @summary Types for requests and responses: `RequestInfo`, the request shapes builders return, cache options, the\n * handler context and the documents a request's `Future` settles with.\n */\n\n// oxlint-disable-next-line no-unused-vars\nimport type { Future, Handler } from '../request.ts';\n// oxlint-disable-next-line no-unused-vars\nimport type { Fetch } from '../request/-private/fetch.ts';\n// oxlint-disable-next-line no-unused-vars\nimport type { RequestManager } from '../request/-private/manager.ts';\nimport type { FetchError } from '../request/-private/utils.ts';\n// oxlint-disable-next-line no-unused-vars\nimport type { RequestLoadingState } from '../signals/request-state.ts';\nimport type { Store } from '../store/-private.ts';\nimport { getOrSetGlobal, getOrSetUniversal } from './-private.ts';\nimport type { ResourceKey } from './identifier.ts';\nimport type { QueryParamsSerializationOptions } from './params.ts';\nimport type {\n  // oxlint-disable-next-line no-unused-vars\n  Includes,\n  TypeFromInstanceOrString,\n} from './record.ts';\nimport type { ResourceIdentifierObject } from './spec/json-api-raw.ts';\nimport type { RequestSignature } from './symbols.ts';\n\n/**\n * A {@link RequestInfo.cacheOptions | cacheOptions} flag which, when set,\n * signals that a request should never be handled by the cache-manager and\n * thus will never resolve from cache nor update the cache.\n *\n * @summary Symbol key for a request's `cacheOptions` that, when true, makes the request bypass the CacheHandler so it\n * neither resolves from nor updates the cache.\n */\nexport const SkipCache: '___(unique) Symbol(SkipCache)' = getOrSetUniversal('SkipCache', Symbol.for('wd:skip-cache'));\n/**\n * A {@link RequestInfo} flag which, when set, signals to the store's\n * `instantiateRecord` hook that the resolved content should be hydrated\n * into reactive records rather than returned as raw data.\n *\n * @summary Symbol flag on a request that makes the CacheHandler return reactive records instead of raw cache\n * documents; `store.request` sets it automatically.\n */\nexport const EnableHydration: '___(unique) Symbol(EnableHydration)' = getOrSetUniversal(\n  'EnableHydration',\n  Symbol.for('wd:enable-hydration')\n);\n/**\n * @private\n */\nexport const IS_FUTURE: '___(unique) Symbol(IS_FUTURE)' = getOrSetGlobal('IS_FUTURE', Symbol('IS_FUTURE'));\n/**\n * @private\n */\nexport const STRUCTURED: '___(unique) Symbol(DOC)' = getOrSetGlobal('DOC', Symbol('DOC'));\n\nexport type { FetchError };\n\n/**\n * The HTTP methods WarpDrive's request layer supports.\n *\n * @summary Union of the HTTP method strings, including `QUERY`, that a WarpDrive request's `method` may be set to.\n */\nexport type HTTPMethod =\n  | 'QUERY'\n  | 'GET'\n  | 'OPTIONS'\n  | 'POST'\n  | 'PUT'\n  | 'PATCH'\n  | 'DELETE'\n  | 'HEAD'\n  | 'CONNECT'\n  | 'TRACE';\n\n/**\n * Use these options to adjust {@link CacheHandler} behavior for a request\n * via {@link RequestInfo.cacheOptions}.\n *\n * @summary Per-request settings on `cacheOptions` that control the cache key, forced or background reloads,\n * invalidation by resource type, and cache bypass.\n */\nexport interface CacheOptions {\n  /**\n   * A key that uniquely identifies this request. If not present, the url wil be used\n   * as the key for any GET request, while all other requests will not be cached.\n   *\n   */\n  key?: string;\n  /**\n   * If true, the request will be made even if a cached response is present\n   * and not expired.\n   *\n   */\n  reload?: boolean;\n  /**\n   * If true, and a cached response is present and not expired, the request\n   * will be made in the background and the cached response will be returned.\n   *\n   */\n  backgroundReload?: boolean;\n  /**\n   * Useful for metadata around when to invalidate the cache. Typically used\n   * by strategies that invalidate requests by resource type when a new resource\n   * of that type has been created. See the CachePolicy implementation\n   * provided by `@ember-data-mirror/request-utils` for an example.\n   *\n   * It is recommended to only use this for query/queryRecord requests where\n   * new records created later would affect the results, though using it for\n   * findRecord requests is also supported if desired where it may be useful\n   * when a create may affect the result of a sideloaded relationship.\n   *\n   * Generally it is better to patch the cache directly for relationship updates\n   * than to invalidate findRecord requests for one.\n   *\n   */\n  // TODO: Ideally this would be T extends TypedRecordInstance ? ExtractSuggestedCacheTypes<T>[] : string[];\n  // but that leads to `Type instantiation is excessively deep and possibly infinite.`\n  // issues when `T` has many properties.\n  types?: string[];\n\n  /**\n   * If true, the request will never be handled by the cache-manager and thus\n   * will never resolve from cache nor update the cache.\n   *\n   * Generally this is only used for legacy request that manage resource cache\n   * updates in a non-standard way via the LegacyNetworkHandler.\n   *\n   */\n  [SkipCache]?: boolean;\n}\n/**\n * The request shape produced by the `findRecord` request builders, for\n * use with {@link Store.request}.\n *\n * @summary Shape of the `GET` request object that `findRecord` builders return for `store.request`, carrying the url,\n * headers, and requested resource identifier.\n */\nexport type FindRecordRequestOptions<RT = unknown, T = unknown> = {\n  /**\n   * the url to request\n   */\n  url: string;\n  /**\n   * the HTTP method to use\n   */\n  method: 'GET';\n  /**\n   * the headers to send with the request\n   */\n  headers: Headers;\n  /**\n   * see {@link CacheOptions}\n   */\n  cacheOptions?: CacheOptions;\n  /**\n   * the name of the request operation\n   */\n  op: 'findRecord';\n  /**\n   * the resource being requested\n   */\n  records: [ResourceIdentifierObject<TypeFromInstanceOrString<T>>];\n  /**\n   * @private used only to carry the response type for type inference purposes\n   */\n  [RequestSignature]?: RT;\n};\n\n/**\n * The request shape produced by the `query` request builders, for\n * use with {@link Store.request}.\n *\n * @summary Shape of the `GET` request object that `query` builders return for `store.request`, carrying the url,\n * headers, and cache options.\n */\nexport type QueryRequestOptions<RT = unknown> = {\n  /**\n   * the url to request\n   */\n  url: string;\n  /**\n   * the HTTP method to use\n   */\n  method: 'GET';\n  /**\n   * the headers to send with the request\n   */\n  headers: Headers;\n  /**\n   * see {@link CacheOptions}\n   */\n  cacheOptions?: CacheOptions;\n  /**\n   * the name of the request operation\n   */\n  op: 'query';\n  /**\n   * @private used only to carry the response type for type inference purposes\n   */\n  [RequestSignature]?: RT;\n};\n\n/**\n * The request shape produced by the `postQuery` request builders, for\n * use with {@link Store.request}.\n *\n * @summary Shape of the `POST` or `QUERY` request object that `postQuery` builders return, with a body and a required\n * cache key since the url cannot serve as one.\n */\nexport type PostQueryRequestOptions<RT = unknown> = {\n  /**\n   * the url to request\n   */\n  url: string;\n  /**\n   * the HTTP method to use\n   */\n  method: 'POST' | 'QUERY';\n  /**\n   * the headers to send with the request\n   */\n  headers: Headers;\n  /**\n   * the body to send with the request\n   */\n  body?: string | BodyInit | FormData;\n  /**\n   * see {@link CacheOptions}. A `key` is required since `POST`/`QUERY`\n   * requests otherwise have no cache-safe way to derive one from the url.\n   */\n  cacheOptions: CacheOptions & {\n    /**\n     * a key that uniquely identifies this request\n     */\n    key: string;\n  };\n  /**\n   * the name of the request operation\n   */\n  op: 'query';\n  /**\n   * @private used only to carry the response type for type inference purposes\n   */\n  [RequestSignature]?: RT;\n};\n\n/**\n * The request shape produced by the `deleteRecord` request builders, for\n * use with {@link Store.request}.\n *\n * @summary Shape of the `DELETE` request object that `deleteRecord` builders return for `store.request`, identifying\n * the resource being deleted.\n */\nexport type DeleteRequestOptions<RT = unknown, T = unknown> = {\n  /**\n   * the url to request\n   */\n  url: string;\n  /**\n   * the HTTP method to use\n   */\n  method: 'DELETE';\n  /**\n   * the headers to send with the request\n   */\n  headers: Headers;\n  /**\n   * the name of the request operation\n   */\n  op: 'deleteRecord';\n  /**\n   * the body to send with the request\n   */\n  body?: string | BodyInit | FormData;\n  /**\n   * data for handlers to convert into the request body\n   */\n  data: {\n    /**\n     * the resource being deleted\n     */\n    record: ResourceKey<TypeFromInstanceOrString<T>>;\n  };\n  /**\n   * the resource being deleted\n   */\n  records: [ResourceIdentifierObject<TypeFromInstanceOrString<T>>];\n  /**\n   * @private used only to carry the response type for type inference purposes\n   */\n  [RequestSignature]?: RT;\n};\n\ntype ImmutableRequest<T> = Readonly<T> & {\n  readonly headers: ImmutableHeaders;\n  readonly records: [ResourceKey];\n};\n\n/**\n * The request shape produced by the `updateRecord` request builders, for\n * use with {@link Store.request}.\n *\n * @summary Shape of the `PATCH` or `PUT` request object that `updateRecord` builders return for `store.request`,\n * identifying the resource being saved.\n */\nexport type UpdateRequestOptions<RT = unknown, T = unknown> = {\n  /**\n   * the url to request\n   */\n  url: string;\n  /**\n   * the HTTP method to use\n   */\n  method: 'PATCH' | 'PUT';\n  /**\n   * the headers to send with the request\n   */\n  headers: Headers;\n  /**\n   * the name of the request operation\n   */\n  op: 'updateRecord';\n  /**\n   * the body to send with the request\n   */\n  body?: string | BodyInit | FormData;\n  /**\n   * data for handlers to convert into the request body\n   */\n  data: {\n    /**\n     * the resource being updated\n     */\n    record: ResourceKey<TypeFromInstanceOrString<T>>;\n  };\n  /**\n   * the resource being updated\n   */\n  records: [ResourceIdentifierObject<TypeFromInstanceOrString<T>>];\n  /**\n   * @private used only to carry the response type for type inference purposes\n   */\n  [RequestSignature]?: RT;\n};\n\n/**\n * The request shape produced by the `createRecord` request builders, for\n * use with {@link Store.request}.\n *\n * @summary Shape of the `POST` request object that `createRecord` builders return for `store.request`, identifying the\n * new resource being saved.\n */\nexport type CreateRequestOptions<RT = unknown, T = unknown> = {\n  /**\n   * the url to request\n   */\n  url: string;\n  /**\n   * the HTTP method to use\n   */\n  method: 'POST';\n  /**\n   * the headers to send with the request\n   */\n  headers: Headers;\n  /**\n   * the name of the request operation\n   */\n  op: 'createRecord';\n  /**\n   * the body to send with the request\n   */\n  body?: string | BodyInit | FormData;\n  /**\n   * data for handlers to convert into the request body\n   */\n  data: {\n    /**\n     * the resource being created\n     */\n    record: ResourceKey<TypeFromInstanceOrString<T>>;\n  };\n  /**\n   * the resource being created\n   */\n  records: [ResourceIdentifierObject<TypeFromInstanceOrString<T>>];\n  /**\n   * @private used only to carry the response type for type inference purposes\n   */\n  [RequestSignature]?: RT;\n};\n\n/**\n * The immutable, handler-facing form of {@link DeleteRequestOptions}.\n *\n * @summary Read-only view of a `deleteRecord` request as a handler receives it, with immutable headers and `records`\n * as resource keys.\n */\nexport type ImmutableDeleteRequestOptions = ImmutableRequest<DeleteRequestOptions>;\n/**\n * The immutable, handler-facing form of {@link UpdateRequestOptions}.\n *\n * @summary Read-only view of an `updateRecord` request as a handler receives it, with immutable headers and `records`\n * as resource keys.\n */\nexport type ImmutableUpdateRequestOptions = ImmutableRequest<UpdateRequestOptions>;\n/**\n * The immutable, handler-facing form of {@link CreateRequestOptions}.\n *\n * @summary Read-only view of a `createRecord` request as a handler receives it, with immutable headers and `records`\n * as resource keys.\n */\nexport type ImmutableCreateRequestOptions = ImmutableRequest<CreateRequestOptions>;\n\n/**\n * A minimal reference to a resource sufficient to build a URL for it,\n * as accepted by the request builders.\n *\n * @summary A resource reference with a persisted `id` and `type` and an optional `lid`, which is enough for request\n * builders to construct its url.\n */\nexport type RemotelyAccessibleIdentifier<T extends string = string> = {\n  /**\n   * the resource's persisted id\n   */\n  id: string;\n  /**\n   * the resource's type\n   */\n  type: T;\n  /**\n   * the local identifier WarpDrive has assigned to the resource, if known\n   */\n  lid?: string;\n};\n\n/**\n * Options accepted by the request builders for constraining how a\n * request's url is constructed and how the request interacts with the cache.\n *\n * @summary Options the request builders accept to set reload behavior and override the url's host, namespace, resource\n * path, and query param serialization.\n */\nexport interface ConstrainedRequestOptions {\n  /**\n   * If true, the request will be made even if a cached response is present\n   * and not expired.\n   */\n  reload?: boolean;\n  /**\n   * If true, and a cached response is present and not expired, the request\n   * will be made in the background and the cached response will be returned.\n   */\n  backgroundReload?: boolean;\n  /**\n   * The host to use when constructing the request's url, overriding any\n   * host configured via `setBuildURLConfig`.\n   */\n  host?: string;\n  /**\n   * The namespace to use when constructing the request's url, overriding\n   * any namespace configured via `setBuildURLConfig`.\n   */\n  namespace?: string;\n  /**\n   * The resource path to use when constructing the request's url,\n   * overriding the default of pluralizing the resource's type.\n   */\n  resourcePath?: string;\n  /**\n   * Options for how to serialize the request's query params, see {@link QueryParamsSerializationOptions}.\n   */\n  urlParamsSettings?: QueryParamsSerializationOptions;\n}\n\n/**\n * Options accepted by the `findRecord` request builders.\n *\n * @summary Options the `findRecord` request builders accept: the shared url and reload options plus the relationship\n * paths to `include`.\n */\nexport interface FindRecordOptions extends ConstrainedRequestOptions {\n  /**\n   * the relationship paths to sideload, see {@link Includes}\n   */\n  include?: string | string[];\n}\n\n/**\n * When a {@link Future} resolves, it returns an object\n * containing the original {@link RequestInfo | request},\n * the {@link Response | response} set by the handler chain (if any), and\n * the processed content.\n *\n * @summary The `{ request, response, content }` object that a request's `Future` resolves with when the request\n * succeeds.\n */\nexport interface StructuredDataDocument<T> {\n  /**\n   * @private\n   */\n  [STRUCTURED]?: true;\n  /**\n   * @see {@link ImmutableRequestInfo}\n   */\n  request: ImmutableRequestInfo;\n  /**\n   * the response set by the handler chain, if any\n   */\n  response: Response | ResponseInfo | null;\n  /**\n   * the processed content of the response\n   */\n  content: T;\n}\n\n/**\n * When a {@link Future} rejects, it throws either an {@link Error}\n * an {@link AggregateError} or a {@link DOMException} that maintains\n * the `{ request, response, content }` shape but is also an Error instance\n * itself.\n *\n * If using the error originates from the {@link Fetch | Fetch Handler}\n * the error will be a {@link FetchError}\n *\n * @summary The Error a request's `Future` rejects with when the request fails, carrying the `request`, `response`,\n * `error`, and any `content` received.\n */\nexport interface StructuredErrorDocument<T = unknown> extends Error {\n  /**\n   * @private\n   */\n  [STRUCTURED]?: true;\n  /**\n   * @see {@link ImmutableRequestInfo}\n   */\n  request: ImmutableRequestInfo;\n  /**\n   * the response set by the handler chain, if any\n   */\n  response: Response | ResponseInfo | null;\n  /**\n   * the error that caused the request to fail\n   */\n  error: string | object;\n  /**\n   * the processed content of the response, if any was received before the failure\n   */\n  content?: T;\n}\n\n/**\n * A union of the resolve/reject data types for the {@link Future}\n * returned by {@link Store.request | request}\n *\n * The [Using The Response](/guides/the-manual/requests/using-the-response) guide shows\n * how to read one.\n *\n * See also the docs for:\n *\n * - {@link Future}\n * - {@link StructuredDataDocument} (resolved/successful requests)\n * - {@link StructuredErrorDocument} (rejected/failed requests)\n *\n * @summary Union of the success and error documents that a request's `Future` resolves or rejects with.\n */\nexport type StructuredDocument<T> = StructuredDataDocument<T> | StructuredErrorDocument<T>;\n\n/**\n * The {@link RequestInit} interface accepted by the native {@link fetch} API.\n *\n * WarpDrive provides our own typings due to incompleteness in the native typings.\n *\n * @privateRemarks\n * - [MDN Reference (fetch)](https://developer.mozilla.org/docs/Web/API/Window/fetch)\n * - [MDN Reference (RequestInit)](https://developer.mozilla.org/en-US/docs/Web/API/RequestInit)\n * - [MDN Reference (Request)](https://developer.mozilla.org/docs/Web/API/Request)\n *\n */\ninterface NativeRequestInit {\n  /** Returns the cache mode associated with request, which is a string indicating how the request will interact with the browser's cache when fetching.\n   */\n  cache?: RequestCache;\n  /** Returns the credentials mode associated with request, which is a string indicating whether credentials will be sent with the request always, never, or only when sent to a same-origin URL.\n   */\n  credentials?: RequestCredentials;\n  /** Returns the kind of resource requested by request, e.g., \"document\" or \"script\".\n   */\n  destination?: RequestDestination;\n  /** Returns a Headers object consisting of the headers associated with request. Note that headers added in the network layer by the user agent will not be accounted for in this object, e.g., the \"Host\" header.\n   */\n  headers?: Headers;\n  /** Returns request's subresource integrity metadata, which is a cryptographic hash of the resource being fetched. Its value consists of multiple hashes separated by whitespace. [SRI]\n   */\n  integrity?: string;\n  /** Returns a boolean indicating whether or not request can outlive the global in which it was created.\n   */\n  keepalive?: boolean;\n  /** Returns request's HTTP method, which is \"GET\" by default.\n   */\n  method?: HTTPMethod;\n  /** Returns the mode associated with request, which is a string indicating whether the request will use CORS, or will be restricted to same-origin URLs.\n   *\n   * `no-cors` is not allowed for streaming request bodies.\n   *\n   */\n  mode?: RequestMode;\n  /**\n   * provides an explicit priority hint for the request.\n   */\n  priority?: RequestPriority;\n  /** Returns the redirect mode associated with request, which is a string indicating how redirects for the request will be handled during fetching. A request will follow redirects by default.\n   */\n  redirect?: RequestRedirect;\n  /** Returns the referrer of request. Its value can be a same-origin URL if explicitly set in init, the empty string to indicate no referrer, and \"about:client\" when defaulting to the global's default. This is used during fetching to determine the value of the `Referer` header of the request being made.\n   */\n  referrer?: string;\n  /** Returns the referrer policy associated with request. This is used during fetching to compute the value of the request's referrer.\n   */\n  referrerPolicy?: ReferrerPolicy;\n  /** Returns the signal associated with request, which is an AbortSignal object indicating whether or not request has been aborted, and its abort event handler.\n   */\n  signal?: AbortSignal;\n  /** Returns the URL of request as a string.\n   */\n  url?: string;\n  /** Any body that you want to add to your request. Note that a GET or HEAD request may not have a body.\n   */\n  body?: BodyInit | null;\n\n  /**\n   * When sending a ReadableStream as the body of a request, 'half' must be\n   * specified.\n   *\n   * [Half Duplex Further Reading](https://developer.chrome.com/docs/capabilities/web-apis/fetch-streaming-requests#half_duplex)\n   *\n   */\n  duplex?: 'half';\n}\n\n/**\n * A read-only {@link Headers} instance, as passed to {@link Handler | Handlers}\n * via {@link ImmutableRequestInfo.headers}.\n *\n * @summary Read-only `Headers` that handlers see on a request, adding `toJSON` to serialize them as `[key, value]`\n * pairs and an optional mutable `clone`.\n */\nexport interface ImmutableHeaders extends Headers {\n  /**\n   * Returns a mutable clone of these headers, if supported by the implementation.\n   */\n  clone?(): Headers;\n  /**\n   * Returns the headers as an array of `[key, value]` pairs.\n   */\n  toJSON(): [string, string][];\n}\n\n/**\n * Extends JavaScript's native {@link fetch} {@link NativeRequestInit | RequestInit} with additional\n * properties specific to the {@link RequestManager | RequestManager's} capabilities.\n *\n * This interface is used to define the shape of a request that can be made via\n * either the {@link RequestManager.request} or {@link Store.request} methods.\n *\n * The [Making Requests](/guides/the-manual/requests/#request-options) guide explains\n * its options.\n *\n * @summary Describes a request for `store.request` or `RequestManager.request`: native fetch options plus cache\n * options, operation name, records, data, and the store.\n * @privateRemarks\n * - [MDN Reference (fetch)](https://developer.mozilla.org/docs/Web/API/Window/fetch)\n * - [MDN Reference (RequestInit)](https://developer.mozilla.org/en-US/docs/Web/API/RequestInit)\n * - [MDN Reference (Request)](https://developer.mozilla.org/docs/Web/API/Request)\n *\n * @public\n * @since 4.12\n */\nexport interface RequestInfo<RT = unknown> extends NativeRequestInit {\n  /**\n   * If provided, used instead of the AbortController auto-configured for each request by the RequestManager\n   *\n   */\n  controller?: AbortController;\n\n  /**\n   * @see {@link CacheOptions}\n   */\n  cacheOptions?: CacheOptions;\n  /**\n   * The {@link Store} the request was made against, if made via\n   * {@link Store.request} rather than directly against a {@link RequestManager}.\n   *\n   * A {@link Handler} can read this off of {@link RequestContext.request | context.request}\n   * to reach store state (the cache, other services attached to a custom\n   * store subclass, etc.) without needing any Ember DI/`setOwner` wiring at\n   * handler-construction time. This works for a handler of any shape (a\n   * function, plain object, or class) because the store is attached to each\n   * request individually rather than to the handler itself.\n   *\n   * The trade-off is that this is only populated for requests issued via\n   * {@link Store.request | store.request(...)}; a request issued directly\n   * against a {@link RequestManager} will not have it set unless the caller\n   * supplies it explicitly. Handlers that rely on it should treat it as\n   * optional.\n   *\n   * @example\n   * ```ts\n   * const LoggingHandler = {\n   *   request<T>(context: RequestContext, next: NextFn<T>) {\n   *     const store = context.request.store;\n   *     if (store) {\n   *       console.log(`[${store.constructor.name}] ${context.request.url ?? ''}`);\n   *     }\n   *     return next(context.request);\n   *   },\n   * };\n   * ```\n   */\n  store?: Store;\n\n  /**\n   * The name of the request operation, if any (e.g. `'findRecord'`, `'query'`).\n   */\n  op?: string;\n\n  /**\n   * The {@link ResourceKey | ResourceKeys} of the primary resources involved in the request\n   * (if any). This may be used by handlers to perform transactional\n   * operations on the store.\n   *\n   */\n  records?: ResourceKey[];\n\n  /**\n   * If true, this request will not be tracked by test waiters.\n   */\n  disableTestWaiter?: boolean;\n  /**\n   * data that a handler should convert into\n   * the query (GET) or body (POST).\n   *\n   * Note: It is recommended that builders set query params\n   * and body directly in most scenarios.\n   *\n   */\n  data?: Record<string, unknown>;\n  /**\n   * options specifically intended for {@link Handler | Handlers}\n   * to utilize to process the request\n   *\n   */\n  options?: Record<string, unknown>;\n\n  /**\n   * @private used only to carry the response type for type inference purposes\n   */\n  [RequestSignature]?: RT;\n\n  /**\n   * see {@link EnableHydration}\n   */\n  [EnableHydration]?: boolean;\n}\n\n/**\n * Immutable version of {@link RequestInfo}. This is what is passed to handlers.\n *\n * @summary Read-only form of a request as handlers receive it, with frozen headers, data, options, and cache options\n * and no `controller`.\n */\nexport type ImmutableRequestInfo<RT = unknown> = Readonly<Omit<RequestInfo<RT>, 'controller'>> & {\n  /**\n   * see {@link CacheOptions}\n   */\n  readonly cacheOptions?: Readonly<CacheOptions>;\n  /**\n   * see {@link ImmutableHeaders}\n   */\n  readonly headers?: ImmutableHeaders;\n  /**\n   * see {@link RequestInfo.data}\n   */\n  readonly data?: Readonly<Record<string, unknown>>;\n  /**\n   * see {@link RequestInfo.options}\n   */\n  readonly options?: Readonly<Record<string, unknown>>;\n\n  /** Whether the request body has been read.\n   */\n  readonly bodyUsed?: boolean;\n};\n\n/**\n * An immutable, JSON-serializable subset of the native {@link Response}\n * interface.\n *\n * @summary Immutable, JSON-serializable snapshot of a fetch `Response`'s headers, status, url, and type, usable in\n * place of a `Response` in request results.\n */\nexport interface ResponseInfo {\n  /**\n   * see {@link ImmutableHeaders}\n   */\n  readonly headers: ImmutableHeaders; // to do, maybe not this?\n  /**\n   * whether the response's status code was in the 200-299 range\n   */\n  readonly ok: boolean;\n  /**\n   * whether the response is the result of a redirect\n   */\n  readonly redirected: boolean;\n  /**\n   * the response's HTTP status code\n   */\n  readonly status: number;\n  /**\n   * the status message associated with the response's status code\n   */\n  readonly statusText: string;\n  /**\n   * the type of the response, see [MDN Reference](https://developer.mozilla.org/docs/Web/API/Response/type)\n   */\n  readonly type: ResponseType;\n  /**\n   * the url of the response\n   */\n  readonly url: string;\n}\n\n/**\n * The object a {@link Handler} uses to fulfill a request: it provides a\n * readonly view of the {@link RequestContext.request | request} and methods\n * for supplying the {@link Future}'s stream and final response.\n *\n * The [Handlers](/guides/the-manual/requests/handlers) guide shows a handler using it.\n *\n * @summary Object passed to each request handler with the immutable request, a request id, and methods for setting the\n * response stream and the response.\n */\nexport interface RequestContext {\n  /**\n   * @see {@link ImmutableRequestInfo}\n   */\n  request: ImmutableRequestInfo;\n  /**\n   * a unique id for this request\n   */\n  id: number;\n\n  /**\n   * Supplies the stream of the response's content, if available, enabling\n   * consumers to monitor download progress via {@link RequestLoadingState}.\n   */\n  setStream(stream: ReadableStream | Promise<ReadableStream | null>): void;\n  /**\n   * Supplies the response for the request.\n   */\n  setResponse(response: Response | ResponseInfo | null): void;\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAmCA,MAAaE,YAA6CD,kBAAkB,aAAaE,OAAOC,IAAI,eAAe,CAAC;;;;;;;;;AASpH,MAAaC,kBAAyDJ,kBACpE,mBACAE,OAAOC,IAAI,qBAAqB,CAClC;;;;AAIA,MAAaE,YAA6CN,eAAe,aAAaG,OAAO,WAAW,CAAC;;;;AAIzG,MAAaI,aAAwCP,eAAe,OAAOG,OAAO,KAAK,CAAC"}

package/dist/unpkg/prod-deprecated/types/schema/fields.js

@@ -1,11 +1,25 @@
 //#region src/types/schema/fields.ts
 /**
+* The [Schemas](/guides/the-manual/schemas/) guide teaches how these schemas and
+* fields fit together.
+*
+* @module
+* @summary Types for every field schema kind and for PolarisMode and LegacyMode resource, object and trait schemas,
+* plus the `resourceSchema` and `objectSchema` helpers and type guards.
+*/
+/**
 * Options signature for Legacy Attributes.
+*
+* @summary Options object on a legacy `attribute` field schema, holding a `defaultValue` (a primitive or a function
+* producing one) plus any transform-specific options.
 */
 /**
 * A generic "field" that can be used to define
 * primitive value fields.
 *
+* The [SimpleFields](/guides/the-manual/schemas/simple-fields) guide shows how to
+* define them.
+*
 * Replaces "attribute" for primitive value fields.
 * Can also be used to eject from deep-tracking of
 * objects or arrays.
@@ -16,6 +30,8 @@
 * "type" points to a new-style transform on "field"
 * that a record implmentation *must* use.
 *
+* @summary Field schema of kind `field` for a primitive value, optionally converted by a registered `Transformation`;
+* objects and arrays in it are not deep-tracked.
 * @public
 */
 /**
@@ -44,6 +60,8 @@
 * an AliasField could be used to expose both a string and a Date version of the
 * same field, with both being capable of being written to.
 *
+* @summary Field schema of kind `alias` for LegacyMode resources that exposes another field's cache value, including
+* legacy attributes and relationships, under a new name.
 * @public
 */
 /**
@@ -72,6 +90,8 @@
 * an AliasField could be used to expose both a string and a Date version of the
 * same field, with both being capable of being written to.
 *
+* @summary Field schema of kind `alias` for PolarisMode resources that exposes another field's cache value, including
+* LinksMode relationships, under a new name.
 * @public
 */
 /**
@@ -100,12 +120,17 @@
 * an AliasField could be used to expose both a string and a Date version of the
 * same field, with both being capable of being written to.
 *
+* @summary Field schema of kind `alias` for object schemas that exposes another non-relationship field's cache value
+* under a new name.
 * @public
 */
 /**
 * Represents a field whose value is the primary
 * key of the resource.
 *
+* The [ResourceSchemas](/guides/the-manual/schemas/resources/) guide shows where it
+* sits in a schema.
+*
 * This allows any field to serve as the primary
 * key while still being able to drive identity
 * needs within the system.
@@ -114,6 +139,8 @@
 * 'uuid', 'urn' or 'entityUrn' or 'primaryKey' as their
 * primary key field instead of 'id'.
 *
+* @summary Field schema of kind `@id` naming which field holds a resource's primary key, with an optional `sourceKey`
+* when the API uses another name like `uuid`.
 * @public
 */
 /**
@@ -137,6 +164,8 @@
 * it should be placed in the `ResourceSchema`'s `@id` field
 * in place of an `IdentityField`.
 *
+* @summary Field schema of kind `@hash` that computes a schema-object's identity from its cache data using a registered
+* hash function.
 * @public
 */
 /**
@@ -166,6 +195,8 @@
 *
 * Don't make us regret this decision.
 *
+* @summary Field schema of kind `@local` for memoized, writable per-record state that is never cached or sent to the
+* server; currently private to built-in fields.
 * @public
 */
 /**
@@ -177,6 +208,8 @@
 * if the key/value pairs have well-defined shape,
 * use 'schema-object' instead.
 *
+* @summary Field schema of kind `object` for a plain object of primitive values, optionally passed as a whole through a
+* registered transformation.
 * @public
 */
 /**
@@ -184,11 +217,16 @@
 * with a well-defined structure described by
 * a schema-object (a non-resource schema).
 *
+* The [Complex Fields](/guides/the-manual/schemas/complex-fields#schema-objects) guide
+* shows how to use it.
+*
 * If the object's structure is not well-defined,
 * use 'object' instead.
 *
 * By default, a SchemaObject within
 *
+* @summary Field schema of kind `schema-object` for a nested object whose shape is described by an `ObjectSchema`, with
+* optional polymorphism.
 * @public
 */
 /**
@@ -198,6 +236,8 @@
 * If the array's elements are not primitive
 * values, use 'schema-array' instead.
 *
+* @summary Field schema of kind `array` for an array of primitive values, each optionally passed through a registered
+* transformation.
 * @public
 */
 /**
@@ -205,15 +245,23 @@
 * of objects with a well-defined structure
 * described by a non-resource schema.
 *
+* The [Complex Fields](/guides/the-manual/schemas/complex-fields#schema-arrays) guide
+* shows how to use it.
+*
 * If the array's elements are not well-defined,
 * use 'array' instead.
 *
+* @summary Field schema of kind `schema-array` for an array of objects described by an `ObjectSchema`, with options for
+* member identity keys and polymorphism.
 * @public
 */
 /**
 * Represents a field whose value is derived
 * from other fields in the schema.
 *
+* The [Derivations](/guides/the-manual/schemas/derivations) guide explains when to
+* use one and how to register its derivation.
+*
 * The value is read-only, and is not stored
 * in the cache, nor is it sent to the server.
 *
@@ -224,15 +272,24 @@
 * or that require access to related resources
 * that may not be loaded should be avoided.
 *
+* @summary Field schema of kind `derived` for a read-only, memoized value computed by a registered derivation and never
+* cached or sent to the server.
 * @public
 */
 /**
 * Represents a field that is a reference to
 * another resource.
 *
-* SUPPORT FOR THIS FEATURE IS NOT YET IMPLEMENTED
-* BY ReactiveResource
+* SUPPORT FOR THIS FEATURE IS NOT YET COMPLETE
+* IN ReactiveResource. It is not yet part of
+* {@link PolarisModeFieldSchema} or {@link LegacyModeFieldSchema}.
+* Reading the field returns an object with the related
+* record as `data`, plus `links`, `meta` and a `fetch()`
+* method, but it does not yet update when the
+* relationship changes, and setting it is not supported.
 *
+* @summary Field schema of kind `resource` for a reference to another resource; not yet implemented by
+* `ReactiveResource`.
 * @public
 */
 /**
@@ -241,8 +298,13 @@
 * paginate.
 *
 * SUPPORT FOR THIS FEATURE IS NOT YET IMPLEMENTED
-* BY ReactiveResource
+* BY ReactiveResource. It is not yet part of
+* {@link PolarisModeFieldSchema} or {@link LegacyModeFieldSchema},
+* and reading or setting the field fails an assertion
+* in development builds.
 *
+* @summary Field schema of kind `collection` for a possibly paginated reference to other resources; not yet implemented
+* by `ReactiveResource`.
 * @public
 */
 /**
@@ -256,10 +318,15 @@
 * If the field points to an object or array,
 * it will not be deep-tracked.
 *
+* The [LegacyMode](/guides/the-manual/schemas/resources/legacy-mode#defining-legacy-schemas)
+* guide shows how to use it.
+*
 * Transforms when defined are legacy transforms
 * that a serializer *might* use, but their usage
 * is not guaranteed.
 *
+* @summary Legacy field schema of kind `attribute` for a primitive value whose `type` names a legacy transform a
+* serializer may apply; LegacyMode only.
 * @public
 */
 /**
@@ -271,6 +338,11 @@
 *
 * This is the legacy version of the `ResourceField`.
 *
+* The [LegacyMode](/guides/the-manual/schemas/resources/legacy-mode#defining-legacy-schemas)
+* guide shows how to use it.
+*
+* @summary Legacy field schema of kind `belongsTo` for a reference to one related resource, with required `async` and
+* `inverse` options and optional `linksMode`.
 * @public
 */
 /**
@@ -282,6 +354,8 @@
 *
 * This is the legacy version of the `ResourceField`.
 *
+* @summary Legacy field schema of kind `belongsTo` in LinksMode: a sync reference to one related resource, loaded via
+* links without adapters, usable in PolarisMode.
 * @public
 */
 /**
@@ -293,6 +367,11 @@
 *
 * This is the legacy version of the `CollectionField`.
 *
+* The [LegacyMode](/guides/the-manual/schemas/resources/legacy-mode#defining-legacy-schemas)
+* guide shows how to use it.
+*
+* @summary Legacy field schema of kind `hasMany` for a reference to many related resources, with required `async` and
+* `inverse` options and optional `linksMode`.
 * @public
 */
 /**
@@ -304,6 +383,8 @@
 *
 * This is the legacy version of the `CollectionField`.
 *
+* @summary Legacy field schema of kind `hasMany` in LinksMode: a sync reference to many related resources, loaded via
+* links without adapters, usable in PolarisMode.
 * @public
 */
 /**
@@ -325,6 +406,8 @@
 * - {@link LegacyBelongsToField}
 * - {@link LegacyHasManyField}
 *
+* @summary Union of every field schema allowed on a LegacyMode resource schema, including legacy attribute, belongsTo,
+* and hasMany fields.
 * @public
 */
 /**
@@ -345,6 +428,8 @@
 * - {@link LinksModeBelongsToField}
 * - {@link LinksModeHasManyField}
 *
+* @summary Union of every field schema allowed on a PolarisMode resource schema, with relationships limited to their
+* LinksMode forms.
 * @public
 */
 /**
@@ -356,6 +441,8 @@
 * as appropriate as they are more specific and will
 * provide better guidance around what is valid.
 *
+* @summary Union of every LegacyMode and PolarisMode field schema; prefer the mode-specific unions for more precise
+* type-checking.
 * @public
 */
 /**
@@ -366,12 +453,14 @@
 * In other words this will not include types like alias
 * fields, local fields, or derived fields.
 *
+* @summary Union of the field schemas whose values live in the cache, excluding alias, local, and derived fields.
 * @public
 */
 /**
 * A union of all possible field schemas that can be
 * used in an ObjectSchema.
 *
+* @summary Union of the field schemas allowed in an `ObjectSchema`, which excludes identity and relationship fields.
 * @public
 */
 /**
@@ -381,15 +470,22 @@
 * own which may allow them to appear in relationships, or in multiple
 * response documents.
 *
+* @summary Schema describing a PolarisMode resource type: its `@id` identity field, its fields, and the traits it
+* implements.
 * @public
 */
 /**
 * Represents a schema for a primary resource in LegacyMode
 *
+* The [LegacyMode](/guides/the-manual/schemas/resources/legacy-mode#defining-legacy-schemas)
+* guide shows how to define one.
+*
 * Primary resources are objects with a unique identity of their
 * own which may allow them to appear in relationships, or in multiple
 * response documents.
 *
+* @summary Schema describing a LegacyMode resource type, marked `legacy: true`, with its identity field, fields,
+* traits, and optional extensions.
 * @public
 */
 /**
@@ -397,24 +493,36 @@
 * definition for either a PolarisMode or a
 * LegacyMode resource.
 *
+* The [ResourceSchemas](/guides/the-manual/schemas/resources/) guide shows how to
+* create and register one.
+*
 * Note, this is separate from the type returned
 * by the SchemaService which provides fields as a Map
 * instead of as an Array.
 *
+* @summary Union of the PolarisMode and LegacyMode schema definitions for a primary resource type, as registered with
+* the schema service.
 * @public
 */
 /**
 * Represents a schema for an object that is not
 * a primary resource (has no unique identity of its own).
 *
+* The [ObjectSchemas](/guides/the-manual/schemas/object-schemas) guide shows how to
+* define and register one.
+*
 * ObjectSchemas may not currently contain relationships.
 *
+* @summary Schema describing an embedded object that has no identity of its own, used by `schema-object` and
+* `schema-array` fields.
 * @public
 */
 /**
 * A union of {@link ResourceSchema} and {@link ObjectSchema} representing
 * any schema that can be registered with or returned by the SchemaService.
 *
+* @summary Union of resource and object schemas, covering any schema that can be registered with or returned by the
+* schema service.
 * @public
 */
 /**
@@ -423,6 +531,9 @@
 * Traits are reusable collections of fields that can be composed onto a
 * resource schema, often to describe a polymorphic capability shared by
 * multiple resource types.
+*
+* @summary A named, reusable set of PolarisMode fields that resource schemas compose in via their `traits`, often to
+* model polymorphic capabilities.
 */
 /**
 * A trait for use on a LegacyMode record.
@@ -430,11 +541,19 @@
 * Traits are reusable collections of fields that can be composed onto a
 * resource schema, often to describe a polymorphic capability shared by
 * multiple resource types.
+*
+* @summary A named, reusable set of LegacyMode fields that resource schemas compose in via their `traits`, often to
+* model polymorphic capabilities.
 */
 /**
 * A union of
 * - {@link LegacyTrait}
 * - {@link PolarisTrait}
+*
+* The [Traits](/guides/the-manual/schemas/traits) guide shows how to create, register
+* and use one.
+*
+* @summary Union of the LegacyMode and PolarisMode trait definitions that can be registered with the schema service.
 */
 /**
 * A no-op type utility that enables type-checking resource schema
@@ -446,6 +565,8 @@
 * as doing so would require a full schema graph to be passed in
 * and no cycles in the graph to be present.
 *
+* @summary Returns the given resource schema unchanged, typed so its definition is type-checked; relationship inverses
+* and related types are not validated.
 * @public
 */
 function resourceSchema(schema) {
@@ -457,6 +578,7 @@ function resourceSchema(schema) {
 *
 * Will return the passed in schema.
 *
+* @summary Returns the given object schema unchanged, typed so its definition is type-checked.
 * @public
 */
 function objectSchema(schema) {
@@ -465,6 +587,8 @@ function objectSchema(schema) {
 /**
 * A type utility to narrow a schema to a ResourceSchema
 *
+* @summary Type guard that returns true when a schema is a resource schema, meaning its identity field is of kind
+* `@id`.
 * @public
 */
 function isResourceSchema(schema) {
@@ -473,6 +597,8 @@ function isResourceSchema(schema) {
 /**
 * A type utility to narrow a schema to LegacyResourceSchema
 *
+* @summary Type guard that returns true when a schema is a LegacyMode resource schema, meaning it is a resource schema
+* with `legacy: true`.
 * @public
 */
 function isLegacyResourceSchema(schema) {
@@ -491,6 +617,8 @@ function isLegacyResourceSchema(schema) {
 * - {@link LinksModeBelongsToField}
 * - {@link LinksModeHasManyField}
 *
+* @summary Union of the legacy attribute, belongsTo, and hasMany field schemas, including the LinksMode relationship
+* variants.
 * @public
 */
 /**
@@ -504,6 +632,7 @@ function isLegacyResourceSchema(schema) {
 * - {@link LinksModeBelongsToField}
 * - {@link LinksModeHasManyField}
 *
+* @summary Union of the legacy belongsTo and hasMany field schemas, including their LinksMode variants.
 * @public
 */
 //#endregion