From 6617e85df77f86319ad4a36b127e6e3558148343 Mon Sep 17 00:00:00 2001 From: Chris Manson Date: Tue, 25 Jun 2024 12:50:53 +0100 Subject: [PATCH] remove no-highlight language --- .../4.10.0/modules/ember-data-4.10.0-@ember-data/request.json | 2 +- .../4.10.0/modules/ember-data-4.10.0-ember-data-overview.json | 2 +- .../4.11.3/modules/ember-data-4.11.3-@ember-data/request.json | 2 +- .../4.11.3/modules/ember-data-4.11.3-ember-data-overview.json | 2 +- .../4.12.3/modules/ember-data-4.12.3-@ember-data/graph.json | 2 +- .../4.12.3/modules/ember-data-4.12.3-@ember-data/json-api.json | 2 +- .../4.12.3/modules/ember-data-4.12.3-@ember-data/request.json | 2 +- .../4.12.3/modules/ember-data-4.12.3-ember-data-overview.json | 2 +- .../4.9.1/modules/ember-data-4.9.1-@ember-data/request.json | 2 +- .../4.9.1/modules/ember-data-4.9.1-ember-data-overview.json | 2 +- .../5.0.1/modules/ember-data-5.0.1-@ember-data/graph.json | 2 +- .../5.0.1/modules/ember-data-5.0.1-@ember-data/json-api.json | 2 +- .../5.0.1/modules/ember-data-5.0.1-@ember-data/request.json | 2 +- .../5.0.1/modules/ember-data-5.0.1-ember-data-overview.json | 2 +- .../5.1.2/modules/ember-data-5.1.2-@ember-data/graph.json | 2 +- .../5.1.2/modules/ember-data-5.1.2-@ember-data/json-api.json | 2 +- .../5.1.2/modules/ember-data-5.1.2-@ember-data/request.json | 2 +- .../5.1.2/modules/ember-data-5.1.2-ember-data-overview.json | 2 +- .../5.2.0/modules/ember-data-5.2.0-@ember-data/graph.json | 2 +- .../5.2.0/modules/ember-data-5.2.0-@ember-data/json-api.json | 2 +- .../5.2.0/modules/ember-data-5.2.0-@ember-data/request.json | 2 +- .../5.2.0/modules/ember-data-5.2.0-ember-data-overview.json | 2 +- .../ember-data-5.3.0-@ember-data/active-record/request.json | 2 +- .../5.3.0/modules/ember-data-5.3.0-@ember-data/graph.json | 2 +- .../5.3.0/modules/ember-data-5.3.0-@ember-data/json-api.json | 2 +- .../modules/ember-data-5.3.0-@ember-data/json-api/request.json | 2 +- .../5.3.0/modules/ember-data-5.3.0-@ember-data/request.json | 2 +- .../modules/ember-data-5.3.0-@ember-data/rest/request.json | 2 +- .../5.3.0/modules/ember-data-5.3.0-ember-data-overview.json | 2 +- 29 files changed, 29 insertions(+), 29 deletions(-) diff --git a/json-docs/ember-data/4.10.0/modules/ember-data-4.10.0-@ember-data/request.json b/json-docs/ember-data/4.10.0/modules/ember-data-4.10.0-@ember-data/request.json index e24803648..79035f613 100644 --- a/json-docs/ember-data/4.10.0/modules/ember-data-4.10.0-@ember-data/request.json +++ b/json-docs/ember-data/4.10.0/modules/ember-data-4.10.0-@ember-data/request.json @@ -11,7 +11,7 @@ "tag": "main", "file": "../packages/request/src/-private/types.ts", "line": 57, - "description": "

\n \n

\n\n

⚑️ a simple abstraction over fetch to enable easy management of request/response flows

\n\nThis package provides [*Ember*‍**Data**](https://github.com/emberjs/data/)'s `RequestManager`, a framework agnostic library that can be integrated with any Javascript application to make [fetch](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) happen.\n\n## Installation\n\nInstall using your javascript package manager of choice. For instance with [pnpm](https://pnpm.io/)\n\n```no-highlight\npnpm add @ember-data/request\n```\n\n## πŸš€ Basic Usage\n\nA `RequestManager` provides a request/response flow in which configured handlers are successively given the opportunity to handle, modify, or pass-along a request.\n\nThe RequestManager on its own does not know how to fulfill requests. For this we must register at least one handler. A basic `Fetch` handler is provided that will take the request options provided and execute `fetch`.\n\n```ts\nimport { RequestManager } from '@ember-data/request';\nimport { Fetch } from '@ember-data/request/fetch';\nimport { apiUrl } from './config';\n\n// ... create manager and add our Fetch handler\nconst manager = new RequestManager();\nmanager.use([Fetch]);\n\n// ... execute a request\nconst response = await manager.request({\n url: `${apiUrl}/users`\n});\n```\n\n\n## πŸͺœ Architecture\n\nA `RequestManager` receives a request and manages fulfillment via configured handlers. It may be used standalone from the rest of *Ember*‍**Data** and is not specific to any library or framework.\n\nEach handler may choose to fulfill the request using some source of data or to pass the request along to other handlers.\n\nThe same or a separate instance of a `RequestManager` may also be used to fulfill requests issued by [*Ember*‍**Data**{Store}](https://github.com/emberjs/data/tree/master/packages/store)\n\nWhen the same instance is used by both this allows for simple coordination throughout the application. Requests issued by the Store will use the in-memory cache\nand return hydrated responses, requests issued directly to the RequestManager\nwill skip the in-memory cache and return raw responses.\n\n## Usage\n\n
\n Making Requests\n\n`RequestManager` has a single asyncronous method as it's API: `request`\n\n```ts\nclass RequestManager {\n async request(req: RequestInfo): Future;\n}\n```\n\n`manager.request` accepts a `RequestInfo`, an object containing the information\nnecessary for the request to be handled successfully.\n\n`RequestInfo` extends the [options](https://developer.mozilla.org/en-US/docs/Web/API/fetch#parameters) provided to `fetch`, and can accept a [`Request`](https://developer.mozilla.org/en-US/docs/Web/API/Request/Request). All properties accepted by Request options and fetch options are valid on `RequestInfo`.\n\n```ts\ninterface RequestInfo extends FetchOptions {\n url: string;\n // data that a handler should convert into\n // the query (GET) or body (POST)\n data?: Record;\n// options specifically intended for handlers\n // to utilize to process the request\n options?: Record;\n}\n```\n\n> **note:** providing a `signal` is unnecessary as an `AbortController` is automatically provided if none is present.\n\n
\n
\n Using the Response
\n\n`manager.request` returns a `Future`, which allows access to limited information about the request while it is still pending and fulfills with the final state when the request completes and the response has been read.\n\nA `Future` is cancellable via `abort`.\n\nHandlers may *optionally* expose a ReadableStream to the `Future` for streaming data; however, when doing so the handler should not resolve until it has fully read the response stream itself.\n\n```ts\ninterface Future extends Promise> {\n abort(): void;\nasync getStream(): ReadableStream | null;\n}\n```\n\nA Future resolves or rejects with a `StructuredDocument`.\n\n```ts\ninterface StructuredDocument {\n request: RequestInfo;\n response: ResponseInfo | null;\n data?: T;\n error?: Error;\n}\n```\n\nThe `RequestInfo` specified by `document.request` is the same as originally provided to `manager.request`. If any handler fulfilled this request using different request info it is not represented here. This contract helps to ensure that `retry` and `caching` are possible since the original arguments are correctly preserved. This also allows handlers to \"fork\" the request or fulfill from multiple sources without the details of fulfillment muddying the original request.\n\nThe `ResponseInfo` is a serializable fulfilled subset of a [Response](https://developer.mozilla.org/en-US/docs/Web/API/Response) if set via `setResponse`. If no response was ever set this will be `null`.\n\n```ts\ninterface ResponseInfo {\n headers?: Record;\n ok?: boolean;\n redirected?: boolean;\n status?: HTTPStatusCode;\n statusText?: string;\n type?: 'basic' | 'cors';\n url?: string;\n}\n```\n\n
\n\n

Handling Requests

\n
\n { request(context, next): Promise | Future; }
\n\nRequests are fulfilled by handlers. A handler receives the request context\nas well as a `next` function with which to pass along a request to the next\nhandler if it so chooses.\n\nA handler may be any object with a `request` method. This allows both stateful and non-stateful\nhandlers to be utilized.\n\nIf a handler calls `next`, it receives a `Future` which resolves to a `StructuredDocument`\nthat it can then compose how it sees fit with its own response.\n\n```ts\n\ntype NextFn

= (req: RequestInfo) => Future

;\n\ninterface Handler {\n async request(context: RequestContext, next: NextFn

): T;\n}\n```\n\n`RequestContext` contains a readonly version of the RequestInfo as well as a few methods for building up the `StructuredDocument` and `Future` that will be part of the response.\n\n```ts\ninterface RequestContext {\n readonly request: RequestInfo;\nsetStream(stream: ReadableStream | Promise): void;\n setResponse(response: Response | ResponseInfo): void;\n}\n```\n\nA basic `fetch` handler with support for streaming content updates while\nthe download is still underway might look like the following, where we use\n[`response.clone()`](https://developer.mozilla.org/en-US/docs/Web/API/Response/clone) to `tee` the `ReadableStream` into two streams.\n\nA more efficient handler might read from the response stream, building up the\nresponse data before passing along the chunk downstream.\n\n```ts\nconst FetchHandler = {\n async request(context) {\n const response = await fetch(context.request);\n context.setResponse(reponse);\n context.setStream(response.clone().body);\n return response.json();\n }\n}\n```\n\nRequest handlers are registered by configuring the manager via `use`\n\n```ts\nmanager.use([Handler1, Handler2])\n```\n\nHandlers will be invoked in the order they are registered (\"fifo\", first-in first-out), and may only be registered up until the first request is made. It is recommended but not required to register all handlers at one time in order to ensure explicitly visible handler ordering.\n\n

\n\n
\n Stream Currying
\n\n`RequestManager.request` and `next` differ from `fetch` in one **crucial detail** in that the outer Promise resolves only once the response stream has been processed.\n\nFor context, it helps to understand a few of the use-cases that RequestManager\nis intended to allow.\n\n- to manage and return streaming content (such as video files)\n- to fulfill a request from multiple sources or by splitting one request into multiple requests\n - for instance one API call for a user and another for the user's friends\n - or e.g. fulfilling part of the request from one source (one API, in-memory, localStorage, IndexedDB\n etc.) and the rest from another source (a different API, a WebWorker, etc.)\n- to coalesce multiple requests\n- to decorate a request with additional info\n - e.g. an Auth handler that ensures the correct tokens or headers or cookies are attached.\n\n`await fetch()` resolves at the moment headers are received. This allows for the body of the request to be processed as a stream by application\ncode *while chunks are still being received by the browser*.\n\nWhen an app chooses to `await response.json()` what occurs is the browser reads the stream to completion and then returns the result. Additionally, this stream may only be read **once**.\n\nThe `RequestManager` preserves this ability to subscribe to and utilize the stream by either the application or the handler – thereby delivering the full power and flexibility of native APIs – without restricting developers in ways that lead to complicated workarounds.\n\nEach handler may call `setStream` only once, but may do so *at any time* until the promise that the handler returns has resolved. The associated promise returned by calling `future.getStream` will resolve with the stream set by `setStream` if that method is called, or `null` if that method\nhas not been called by the time that the handler's request method has resolved.\n\nHandlers that do not create a stream of their own, but which call `next`, should defensively pipe the stream forward. While this is not required (see automatic currying below) it is better to do so in most cases as otherwise the stream may not become available to downstream handlers or the application until the upstream handler has fully read it.\n\n```ts\ncontext.setStream(future.getStream());\n```\n\nHandlers that either call `next` multiple times or otherwise have reason to create multiple fetch requests should either choose to return no stream, meaningfully combine the streams, or select a single prioritized stream.\n\nOf course, any handler may choose to read and handle the stream, and return either no stream or a different stream in the process.\n\n
\n\n
\n Automatic Currying of Stream and Response
\n\nIn order to simplify the common case for handlers which decorate a request, if `next` is called only a single time and `setResponse` was never called by the handler, the response set by the next handler in the chain will be applied to that handler's outcome. For instance, this makes the following pattern possible `return (await next()).data;`.\n\nSimilarly, if `next` is called only a single time and neither `setStream` nor `getStream` was called, we automatically curry the stream from the future returned by `next` onto the future returned by the handler.\n\nFinally, if the return value of a handler is a `Future`, we curry `data` and `errors` as well, thus enabling the simplest form `return next()`.\n\nIn the case of the `Future` being returned, `Stream` proxying is automatic and immediate and does not wait for the `Future` to resolve.\n\n
\n\n### Using as a Service\n\nMost applications will desire to have a single `RequestManager` instance, which can be achieved using module-state patterns for singletons, or for [Ember](https://emberjs.com) applications by exporting the manager as a [service](https://guides.emberjs.com/release/services/).\n\nservices/request.ts*\n```ts\nimport { RequestManager } from '@ember-data/request';\nimport { Fetch } from '@ember-data/request/fetch';\nimport Auth from 'ember-simple-auth/ember-data-handler';\n\nexport default class extends RequestManager {\n constructor(createArgs) {\n super(createArgs);\n this.use([Auth, Fetch]);\n }\n}\n```\n\n### Using with `@ember-data/store`\n\nTo have a request service unique to a Store:\n\n```ts\nimport Store from '@ember-data/store';\nimport { RequestManager } from '@ember-data/request';\nimport { Fetch } from '@ember-data/request/fetch';\n\nclass extends Store {\n requestManager = new RequestManager();\nconstructor(args) {\n super(args);\n this.requestManager.use([Fetch]);\n }\n}\n```\n\n### Using with `ember-data`\n\nIf using the package [ember-data](https://github.com/emberjs/data/tree/master/packages/-ember-data), the following configuration will automatically be done in order to preserve the legacy [Adapter](https://github.com/emberjs/data/tree/master/packages/adapter) and [Serializer](https://github.com/emberjs/data/tree/master/packages/serializer) behavior. Additional handlers or a service injection like the above would need to be done by the consuming application in order to make broader use of `RequestManager`.\n\n```ts\nimport Store from '@ember-data/store';\nimport { RequestManager } from '@ember-data/request';\nimport { LegacyHandler } from '@ember-data/legacy-network-handler';\n\nexport default class extends Store {\n requestManager = new RequestManager();\nconstructor(args) {\n super(args);\n this.requestManager.use([LegacyHandler]);\n }\n}\n```\n\nBecause the application's store service (if present) will override the store supplied by `ember-data`, all that is required to define your own ordering and handlers is to supply a store service extending from `@ember-data/store` and configure as shown above.\n\nFor usage of the store's `requestManager` via `store.request()` see the [Store](https://api.emberjs.com/ember-data/release/modules/@ember-data%2Fstore) documentation.", + "description": "

\n \n

\n\n

⚑️ a simple abstraction over fetch to enable easy management of request/response flows

\n\nThis package provides [*Ember*‍**Data**](https://github.com/emberjs/data/)'s `RequestManager`, a framework agnostic library that can be integrated with any Javascript application to make [fetch](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) happen.\n\n## Installation\n\nInstall using your javascript package manager of choice. For instance with [pnpm](https://pnpm.io/)\n\n```\npnpm add @ember-data/request\n```\n\n## πŸš€ Basic Usage\n\nA `RequestManager` provides a request/response flow in which configured handlers are successively given the opportunity to handle, modify, or pass-along a request.\n\nThe RequestManager on its own does not know how to fulfill requests. For this we must register at least one handler. A basic `Fetch` handler is provided that will take the request options provided and execute `fetch`.\n\n```ts\nimport { RequestManager } from '@ember-data/request';\nimport { Fetch } from '@ember-data/request/fetch';\nimport { apiUrl } from './config';\n\n// ... create manager and add our Fetch handler\nconst manager = new RequestManager();\nmanager.use([Fetch]);\n\n// ... execute a request\nconst response = await manager.request({\n url: `${apiUrl}/users`\n});\n```\n\n\n## πŸͺœ Architecture\n\nA `RequestManager` receives a request and manages fulfillment via configured handlers. It may be used standalone from the rest of *Ember*‍**Data** and is not specific to any library or framework.\n\nEach handler may choose to fulfill the request using some source of data or to pass the request along to other handlers.\n\nThe same or a separate instance of a `RequestManager` may also be used to fulfill requests issued by [*Ember*‍**Data**{Store}](https://github.com/emberjs/data/tree/master/packages/store)\n\nWhen the same instance is used by both this allows for simple coordination throughout the application. Requests issued by the Store will use the in-memory cache\nand return hydrated responses, requests issued directly to the RequestManager\nwill skip the in-memory cache and return raw responses.\n\n## Usage\n\n
\n Making Requests\n\n`RequestManager` has a single asyncronous method as it's API: `request`\n\n```ts\nclass RequestManager {\n async request(req: RequestInfo): Future;\n}\n```\n\n`manager.request` accepts a `RequestInfo`, an object containing the information\nnecessary for the request to be handled successfully.\n\n`RequestInfo` extends the [options](https://developer.mozilla.org/en-US/docs/Web/API/fetch#parameters) provided to `fetch`, and can accept a [`Request`](https://developer.mozilla.org/en-US/docs/Web/API/Request/Request). All properties accepted by Request options and fetch options are valid on `RequestInfo`.\n\n```ts\ninterface RequestInfo extends FetchOptions {\n url: string;\n // data that a handler should convert into\n // the query (GET) or body (POST)\n data?: Record;\n// options specifically intended for handlers\n // to utilize to process the request\n options?: Record;\n}\n```\n\n> **note:** providing a `signal` is unnecessary as an `AbortController` is automatically provided if none is present.\n\n
\n
\n Using the Response
\n\n`manager.request` returns a `Future`, which allows access to limited information about the request while it is still pending and fulfills with the final state when the request completes and the response has been read.\n\nA `Future` is cancellable via `abort`.\n\nHandlers may *optionally* expose a ReadableStream to the `Future` for streaming data; however, when doing so the handler should not resolve until it has fully read the response stream itself.\n\n```ts\ninterface Future extends Promise> {\n abort(): void;\nasync getStream(): ReadableStream | null;\n}\n```\n\nA Future resolves or rejects with a `StructuredDocument`.\n\n```ts\ninterface StructuredDocument {\n request: RequestInfo;\n response: ResponseInfo | null;\n data?: T;\n error?: Error;\n}\n```\n\nThe `RequestInfo` specified by `document.request` is the same as originally provided to `manager.request`. If any handler fulfilled this request using different request info it is not represented here. This contract helps to ensure that `retry` and `caching` are possible since the original arguments are correctly preserved. This also allows handlers to \"fork\" the request or fulfill from multiple sources without the details of fulfillment muddying the original request.\n\nThe `ResponseInfo` is a serializable fulfilled subset of a [Response](https://developer.mozilla.org/en-US/docs/Web/API/Response) if set via `setResponse`. If no response was ever set this will be `null`.\n\n```ts\ninterface ResponseInfo {\n headers?: Record;\n ok?: boolean;\n redirected?: boolean;\n status?: HTTPStatusCode;\n statusText?: string;\n type?: 'basic' | 'cors';\n url?: string;\n}\n```\n\n
\n\n

Handling Requests

\n
\n { request(context, next): Promise | Future; }
\n\nRequests are fulfilled by handlers. A handler receives the request context\nas well as a `next` function with which to pass along a request to the next\nhandler if it so chooses.\n\nA handler may be any object with a `request` method. This allows both stateful and non-stateful\nhandlers to be utilized.\n\nIf a handler calls `next`, it receives a `Future` which resolves to a `StructuredDocument`\nthat it can then compose how it sees fit with its own response.\n\n```ts\n\ntype NextFn

= (req: RequestInfo) => Future

;\n\ninterface Handler {\n async request(context: RequestContext, next: NextFn

): T;\n}\n```\n\n`RequestContext` contains a readonly version of the RequestInfo as well as a few methods for building up the `StructuredDocument` and `Future` that will be part of the response.\n\n```ts\ninterface RequestContext {\n readonly request: RequestInfo;\nsetStream(stream: ReadableStream | Promise): void;\n setResponse(response: Response | ResponseInfo): void;\n}\n```\n\nA basic `fetch` handler with support for streaming content updates while\nthe download is still underway might look like the following, where we use\n[`response.clone()`](https://developer.mozilla.org/en-US/docs/Web/API/Response/clone) to `tee` the `ReadableStream` into two streams.\n\nA more efficient handler might read from the response stream, building up the\nresponse data before passing along the chunk downstream.\n\n```ts\nconst FetchHandler = {\n async request(context) {\n const response = await fetch(context.request);\n context.setResponse(reponse);\n context.setStream(response.clone().body);\n return response.json();\n }\n}\n```\n\nRequest handlers are registered by configuring the manager via `use`\n\n```ts\nmanager.use([Handler1, Handler2])\n```\n\nHandlers will be invoked in the order they are registered (\"fifo\", first-in first-out), and may only be registered up until the first request is made. It is recommended but not required to register all handlers at one time in order to ensure explicitly visible handler ordering.\n\n

\n\n
\n Stream Currying
\n\n`RequestManager.request` and `next` differ from `fetch` in one **crucial detail** in that the outer Promise resolves only once the response stream has been processed.\n\nFor context, it helps to understand a few of the use-cases that RequestManager\nis intended to allow.\n\n- to manage and return streaming content (such as video files)\n- to fulfill a request from multiple sources or by splitting one request into multiple requests\n - for instance one API call for a user and another for the user's friends\n - or e.g. fulfilling part of the request from one source (one API, in-memory, localStorage, IndexedDB\n etc.) and the rest from another source (a different API, a WebWorker, etc.)\n- to coalesce multiple requests\n- to decorate a request with additional info\n - e.g. an Auth handler that ensures the correct tokens or headers or cookies are attached.\n\n`await fetch()` resolves at the moment headers are received. This allows for the body of the request to be processed as a stream by application\ncode *while chunks are still being received by the browser*.\n\nWhen an app chooses to `await response.json()` what occurs is the browser reads the stream to completion and then returns the result. Additionally, this stream may only be read **once**.\n\nThe `RequestManager` preserves this ability to subscribe to and utilize the stream by either the application or the handler – thereby delivering the full power and flexibility of native APIs – without restricting developers in ways that lead to complicated workarounds.\n\nEach handler may call `setStream` only once, but may do so *at any time* until the promise that the handler returns has resolved. The associated promise returned by calling `future.getStream` will resolve with the stream set by `setStream` if that method is called, or `null` if that method\nhas not been called by the time that the handler's request method has resolved.\n\nHandlers that do not create a stream of their own, but which call `next`, should defensively pipe the stream forward. While this is not required (see automatic currying below) it is better to do so in most cases as otherwise the stream may not become available to downstream handlers or the application until the upstream handler has fully read it.\n\n```ts\ncontext.setStream(future.getStream());\n```\n\nHandlers that either call `next` multiple times or otherwise have reason to create multiple fetch requests should either choose to return no stream, meaningfully combine the streams, or select a single prioritized stream.\n\nOf course, any handler may choose to read and handle the stream, and return either no stream or a different stream in the process.\n\n
\n\n
\n Automatic Currying of Stream and Response
\n\nIn order to simplify the common case for handlers which decorate a request, if `next` is called only a single time and `setResponse` was never called by the handler, the response set by the next handler in the chain will be applied to that handler's outcome. For instance, this makes the following pattern possible `return (await next()).data;`.\n\nSimilarly, if `next` is called only a single time and neither `setStream` nor `getStream` was called, we automatically curry the stream from the future returned by `next` onto the future returned by the handler.\n\nFinally, if the return value of a handler is a `Future`, we curry `data` and `errors` as well, thus enabling the simplest form `return next()`.\n\nIn the case of the `Future` being returned, `Stream` proxying is automatic and immediate and does not wait for the `Future` to resolve.\n\n
\n\n### Using as a Service\n\nMost applications will desire to have a single `RequestManager` instance, which can be achieved using module-state patterns for singletons, or for [Ember](https://emberjs.com) applications by exporting the manager as a [service](https://guides.emberjs.com/release/services/).\n\nservices/request.ts*\n```ts\nimport { RequestManager } from '@ember-data/request';\nimport { Fetch } from '@ember-data/request/fetch';\nimport Auth from 'ember-simple-auth/ember-data-handler';\n\nexport default class extends RequestManager {\n constructor(createArgs) {\n super(createArgs);\n this.use([Auth, Fetch]);\n }\n}\n```\n\n### Using with `@ember-data/store`\n\nTo have a request service unique to a Store:\n\n```ts\nimport Store from '@ember-data/store';\nimport { RequestManager } from '@ember-data/request';\nimport { Fetch } from '@ember-data/request/fetch';\n\nclass extends Store {\n requestManager = new RequestManager();\nconstructor(args) {\n super(args);\n this.requestManager.use([Fetch]);\n }\n}\n```\n\n### Using with `ember-data`\n\nIf using the package [ember-data](https://github.com/emberjs/data/tree/master/packages/-ember-data), the following configuration will automatically be done in order to preserve the legacy [Adapter](https://github.com/emberjs/data/tree/master/packages/adapter) and [Serializer](https://github.com/emberjs/data/tree/master/packages/serializer) behavior. Additional handlers or a service injection like the above would need to be done by the consuming application in order to make broader use of `RequestManager`.\n\n```ts\nimport Store from '@ember-data/store';\nimport { RequestManager } from '@ember-data/request';\nimport { LegacyHandler } from '@ember-data/legacy-network-handler';\n\nexport default class extends Store {\n requestManager = new RequestManager();\nconstructor(args) {\n super(args);\n this.requestManager.use([LegacyHandler]);\n }\n}\n```\n\nBecause the application's store service (if present) will override the store supplied by `ember-data`, all that is required to define your own ordering and handlers is to supply a store service extending from `@ember-data/store` and configure as shown above.\n\nFor usage of the store's `requestManager` via `store.request()` see the [Store](https://api.emberjs.com/ember-data/release/modules/@ember-data%2Fstore) documentation.", "itemtype": "main", "parent": null, "publicclasses": [ diff --git a/json-docs/ember-data/4.10.0/modules/ember-data-4.10.0-ember-data-overview.json b/json-docs/ember-data/4.10.0/modules/ember-data-4.10.0-ember-data-overview.json index 55af91c1c..1f5e37809 100644 --- a/json-docs/ember-data/4.10.0/modules/ember-data-4.10.0-ember-data-overview.json +++ b/json-docs/ember-data/4.10.0/modules/ember-data-4.10.0-ember-data-overview.json @@ -11,7 +11,7 @@ "tag": "main", "file": "../packages/-ember-data/addon/index.js", "line": 1, - "description": "

\n \n

\n\n

The lightweight reactive data library for JavaScript applications

\n\n---\n\nWrangle your application's data management with scalable patterns for developer productivity.\n\n- ⚑️ Committed to Best-In-Class Performance\n- 🌲 Focused on being as svelte as possible\n- πŸš€ SSR Ready\n- πŸ”œ Typescript Support\n- 🐹 Built with β™₯️ by [Ember](https://emberjs.com)\n- βš›οΈ Supports any API: `GraphQL` `JSON:API` `REST` `tRPC` ...bespoke or a mix\n\n### πŸ“– On This Page\n\n- [Overview](./#overview)\n - [Architecture](#πŸͺœ-architecture)\n - [Basic Installation](#basic-installation)\n - [Advanced Installation](#advanced-installation)\n- [Configuration](#configuration)\n - [Deprecation Stripping](#deprecation-stripping)\n - [randomUUID polyfill](#randomuuid-polyfill)\n - [Removing inspector support in production](#removing-inspector-support-in-production)\n - [Debugging](#debugging)\n\n\n# Overview\n\n*Ember*‍**Data** is a lightweight reactive data library for JavaScript applications that provides composable primitives for ordering query/mutation/peek flows, managing network and cache, and reducing data for presentation.\n\n## πŸͺœ Architecture\n\nThe core of *Ember*‍**Data** is the `Store`, which coordinates interaction between your application, the `Cache`, and sources of data (such as your `API` or a local persistence layer).\nOptionally, the Store can be configured to hydrate the response data into rich presentation classes.\n\n*Ember*‍**Data** is both resource centric and document centric in it's approach to caching, requesting and presenting data. Your application's configuration and usage drives which is important and when.\n\nThe `Store` is a **coordinator**. When using a `Store` you configure what cache to use, how cache data should be presented to the UI, and where it should look for requested data when it is not available in the cache.\n\nThis coordination is handled opaquely to the nature of the requests issued and the format of the data being handled. This approach gives applications broad flexibility to configure *Ember*‍**Data** to best suite their needs. This makes *Ember*‍**Data** a powerful solution for applications regardless of their size and complexity.\n\n*Ember*‍**Data** is designed to scale, with a religious focus on performance and asset-size to keep its footprint small but speedy while still being able to handle large complex APIs in huge data-driven applications with no additional code and no added application complexity. It's goal is to prevent applications from writing code to manage data that is difficult to maintain or reason about.\n\n*Ember*‍**Data**'s power comes not from specific features, data formats, or adherence to specific API specs such as `JSON:API` `trpc` or `GraphQL`, but from solid conventions around requesting and mutating data developed over decades of experience scaling developer productivity.\n\n## Basic Installation\n\nInstall using your javascript package manager of choice. For instance with [pnpm](https://pnpm.io/)\n\n```no-highlight\npnpm add ember-data\n```\n\n`ember-data` is installed by default for new applications generated with `ember-cli`. You can check what version is installed by looking in the `devDependencies` hash of your project's [package.json](https://docs.npmjs.com/cli/v8/configuring-npm/package-json) file.\n\nIf you have generated a new `Ember` application using `ember-cli` but do\nnot wish to use `ember-data`, remove `ember-data` from your project's `package.json` file and run your package manager's install command to update your lockfile.\n\n## Advanced Installation\n\n*Ember*‍**Data** is organized into primitives that compose together via public APIs.\n\n- [@ember-data/store](/ember-data/release/modules/@ember-data%2Fstore) is the core and handles coordination\n- [@ember-data/record-data](/ember-data/release/modules/@ember-data%2Frecord-data) is a resource cache for JSON:API structured data. It integrates with the store via the hook `createRecordDataFor`\n- [@ember-data/model](/ember-data/release/modules/@ember-data%2Fmodel) is a presentation layer, it integrates with the store via the hooks `instantiateRecord` and `teardownRecord`.\n- [@ember-data/adapter](/ember-data/release/modules/@ember-data%2Fadapter) provides various network API integrations for APIS built over specific REST or JSON:API conventions.\n- [@ember-data/serializer](/ember-data/release/modules/@ember-data%2Fserializer) pairs with `@ember-data/adapter` to normalize and serialize data to and from an API format into the `JSON:API` format understood by `@ember-data/record-data`.\n- [@ember-data/debug](/ember-data/release/modules/@ember-data%2Fdebug) provides debugging support for the `ember-inspector`.\n- **ember-data** is a \"meta\" package which bundles all of these together for convenience\n\nThe packages interop with each other through well defined public API boundaries. The core\nof the library is the store provided by `@ember-data/store`, while each of the other libraries plugs into the store when installed. Because these packages interop via fully\npublic APIs, other libraries or applications may provide their own implementations. For instance, [ember-m3](https://github.com/hjdivad/ember-m3) is a commonly used presentation and cache implementation suitable for complex resource objects and graphs.\n\n## Configuration\n\n### Deprecation Stripping\n\n*Ember*‍**Data** allows users to opt-in and remove code that exists to support deprecated behaviors.\n\nIf your app has resolved all deprecations present in a given version, you may specify that version as your \"compatibility\" version to remove the code that supported the deprecated behavior from your app.\n\n```ts\nlet app = new EmberApp(defaults, {\n emberData: {\n compatWith: '4.8',\n },\n});\n```\n\n- [Full Documentation](https://api.emberjs.com/ember-data/release/modules/@ember-data%2Fdeprecations)\n\n### randomUUID polyfill\n\n*Ember*‍**Data** uses `UUID V4` by default to generate identifiers for new data created on the client. Identifier generation is configurable, but we also for convenience will polyfill\nthe necessary feature if your browser support or deployment environment demands it. To\nactivate this polyfill:\n\n```ts\nlet app = new EmberApp(defaults, {\n '@embroider/macros': {\n setConfig: {\n '@ember-data/store': {\n polyfillUUID: true\n },\n },\n },\n});\n```\n\n### removing inspector support in production\n\nIf you do not with to ship inspector support in your production application, you can specify\nthat all support for it should be stripped from the build.\n\n```ts\nlet app = new EmberApp(defaults, {\n emberData: {\n includeDataAdapterInProduction: false\n }\n});\n```\n\n- [Full Documentation](https://api.emberjs.com/ember-data/release/modules/@ember-data%2Fdebug)\n\n### Debugging\n\nMany portions of the internals are helpfully instrumented with logging that can be activated\nat build time. This instrumentation is always removed from production builds or any builds\nthat has not explicitly activated it. To activate it set the appropriate flag to `true`.\n\n```ts\n let app = new EmberApp(defaults, {\n emberData: {\n debug: {\n LOG_PAYLOADS: false, // data store received to update cache with\n LOG_OPERATIONS: false, // updates to cache remote state\n LOG_MUTATIONS: false, // updates to cache local state\n LOG_NOTIFICATIONS: false,\n LOG_REQUEST_STATUS: false,\n LOG_IDENTIFIERS: false,\n LOG_GRAPH: false,\n LOG_INSTANCE_CACHE: false,\n }\n }\n });\n ```", + "description": "

\n \n

\n\n

The lightweight reactive data library for JavaScript applications

\n\n---\n\nWrangle your application's data management with scalable patterns for developer productivity.\n\n- ⚑️ Committed to Best-In-Class Performance\n- 🌲 Focused on being as svelte as possible\n- πŸš€ SSR Ready\n- πŸ”œ Typescript Support\n- 🐹 Built with β™₯️ by [Ember](https://emberjs.com)\n- βš›οΈ Supports any API: `GraphQL` `JSON:API` `REST` `tRPC` ...bespoke or a mix\n\n### πŸ“– On This Page\n\n- [Overview](./#overview)\n - [Architecture](#πŸͺœ-architecture)\n - [Basic Installation](#basic-installation)\n - [Advanced Installation](#advanced-installation)\n- [Configuration](#configuration)\n - [Deprecation Stripping](#deprecation-stripping)\n - [randomUUID polyfill](#randomuuid-polyfill)\n - [Removing inspector support in production](#removing-inspector-support-in-production)\n - [Debugging](#debugging)\n\n\n# Overview\n\n*Ember*‍**Data** is a lightweight reactive data library for JavaScript applications that provides composable primitives for ordering query/mutation/peek flows, managing network and cache, and reducing data for presentation.\n\n## πŸͺœ Architecture\n\nThe core of *Ember*‍**Data** is the `Store`, which coordinates interaction between your application, the `Cache`, and sources of data (such as your `API` or a local persistence layer).\nOptionally, the Store can be configured to hydrate the response data into rich presentation classes.\n\n*Ember*‍**Data** is both resource centric and document centric in it's approach to caching, requesting and presenting data. Your application's configuration and usage drives which is important and when.\n\nThe `Store` is a **coordinator**. When using a `Store` you configure what cache to use, how cache data should be presented to the UI, and where it should look for requested data when it is not available in the cache.\n\nThis coordination is handled opaquely to the nature of the requests issued and the format of the data being handled. This approach gives applications broad flexibility to configure *Ember*‍**Data** to best suite their needs. This makes *Ember*‍**Data** a powerful solution for applications regardless of their size and complexity.\n\n*Ember*‍**Data** is designed to scale, with a religious focus on performance and asset-size to keep its footprint small but speedy while still being able to handle large complex APIs in huge data-driven applications with no additional code and no added application complexity. It's goal is to prevent applications from writing code to manage data that is difficult to maintain or reason about.\n\n*Ember*‍**Data**'s power comes not from specific features, data formats, or adherence to specific API specs such as `JSON:API` `trpc` or `GraphQL`, but from solid conventions around requesting and mutating data developed over decades of experience scaling developer productivity.\n\n## Basic Installation\n\nInstall using your javascript package manager of choice. For instance with [pnpm](https://pnpm.io/)\n\n```\npnpm add ember-data\n```\n\n`ember-data` is installed by default for new applications generated with `ember-cli`. You can check what version is installed by looking in the `devDependencies` hash of your project's [package.json](https://docs.npmjs.com/cli/v8/configuring-npm/package-json) file.\n\nIf you have generated a new `Ember` application using `ember-cli` but do\nnot wish to use `ember-data`, remove `ember-data` from your project's `package.json` file and run your package manager's install command to update your lockfile.\n\n## Advanced Installation\n\n*Ember*‍**Data** is organized into primitives that compose together via public APIs.\n\n- [@ember-data/store](/ember-data/release/modules/@ember-data%2Fstore) is the core and handles coordination\n- [@ember-data/record-data](/ember-data/release/modules/@ember-data%2Frecord-data) is a resource cache for JSON:API structured data. It integrates with the store via the hook `createRecordDataFor`\n- [@ember-data/model](/ember-data/release/modules/@ember-data%2Fmodel) is a presentation layer, it integrates with the store via the hooks `instantiateRecord` and `teardownRecord`.\n- [@ember-data/adapter](/ember-data/release/modules/@ember-data%2Fadapter) provides various network API integrations for APIS built over specific REST or JSON:API conventions.\n- [@ember-data/serializer](/ember-data/release/modules/@ember-data%2Fserializer) pairs with `@ember-data/adapter` to normalize and serialize data to and from an API format into the `JSON:API` format understood by `@ember-data/record-data`.\n- [@ember-data/debug](/ember-data/release/modules/@ember-data%2Fdebug) provides debugging support for the `ember-inspector`.\n- **ember-data** is a \"meta\" package which bundles all of these together for convenience\n\nThe packages interop with each other through well defined public API boundaries. The core\nof the library is the store provided by `@ember-data/store`, while each of the other libraries plugs into the store when installed. Because these packages interop via fully\npublic APIs, other libraries or applications may provide their own implementations. For instance, [ember-m3](https://github.com/hjdivad/ember-m3) is a commonly used presentation and cache implementation suitable for complex resource objects and graphs.\n\n## Configuration\n\n### Deprecation Stripping\n\n*Ember*‍**Data** allows users to opt-in and remove code that exists to support deprecated behaviors.\n\nIf your app has resolved all deprecations present in a given version, you may specify that version as your \"compatibility\" version to remove the code that supported the deprecated behavior from your app.\n\n```ts\nlet app = new EmberApp(defaults, {\n emberData: {\n compatWith: '4.8',\n },\n});\n```\n\n- [Full Documentation](https://api.emberjs.com/ember-data/release/modules/@ember-data%2Fdeprecations)\n\n### randomUUID polyfill\n\n*Ember*‍**Data** uses `UUID V4` by default to generate identifiers for new data created on the client. Identifier generation is configurable, but we also for convenience will polyfill\nthe necessary feature if your browser support or deployment environment demands it. To\nactivate this polyfill:\n\n```ts\nlet app = new EmberApp(defaults, {\n '@embroider/macros': {\n setConfig: {\n '@ember-data/store': {\n polyfillUUID: true\n },\n },\n },\n});\n```\n\n### removing inspector support in production\n\nIf you do not with to ship inspector support in your production application, you can specify\nthat all support for it should be stripped from the build.\n\n```ts\nlet app = new EmberApp(defaults, {\n emberData: {\n includeDataAdapterInProduction: false\n }\n});\n```\n\n- [Full Documentation](https://api.emberjs.com/ember-data/release/modules/@ember-data%2Fdebug)\n\n### Debugging\n\nMany portions of the internals are helpfully instrumented with logging that can be activated\nat build time. This instrumentation is always removed from production builds or any builds\nthat has not explicitly activated it. To activate it set the appropriate flag to `true`.\n\n```ts\n let app = new EmberApp(defaults, {\n emberData: {\n debug: {\n LOG_PAYLOADS: false, // data store received to update cache with\n LOG_OPERATIONS: false, // updates to cache remote state\n LOG_MUTATIONS: false, // updates to cache local state\n LOG_NOTIFICATIONS: false,\n LOG_REQUEST_STATUS: false,\n LOG_IDENTIFIERS: false,\n LOG_GRAPH: false,\n LOG_INSTANCE_CACHE: false,\n }\n }\n });\n ```", "itemtype": "main", "parent": null, "publicclasses": [], diff --git a/json-docs/ember-data/4.11.3/modules/ember-data-4.11.3-@ember-data/request.json b/json-docs/ember-data/4.11.3/modules/ember-data-4.11.3-@ember-data/request.json index 2edcd490b..9ec442b50 100644 --- a/json-docs/ember-data/4.11.3/modules/ember-data-4.11.3-@ember-data/request.json +++ b/json-docs/ember-data/4.11.3/modules/ember-data-4.11.3-@ember-data/request.json @@ -11,7 +11,7 @@ "tag": "main", "file": "../packages/request/src/-private/types.ts", "line": 57, - "description": "

\n \n

\n\n

⚑️ a simple abstraction over fetch to enable easy management of request/response flows

\n\nThis package provides [*Ember*‍**Data**](https://github.com/emberjs/data/)'s `RequestManager`, a framework agnostic library that can be integrated with any Javascript application to make [fetch](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) happen.\n\n## Installation\n\nInstall using your javascript package manager of choice. For instance with [pnpm](https://pnpm.io/)\n\n```no-highlight\npnpm add @ember-data/request\n```\n\n## πŸš€ Basic Usage\n\nA `RequestManager` provides a request/response flow in which configured handlers are successively given the opportunity to handle, modify, or pass-along a request.\n\nThe RequestManager on its own does not know how to fulfill requests. For this we must register at least one handler. A basic `Fetch` handler is provided that will take the request options provided and execute `fetch`.\n\n```ts\nimport { RequestManager } from '@ember-data/request';\nimport { Fetch } from '@ember-data/request/fetch';\nimport { apiUrl } from './config';\n\n// ... create manager and add our Fetch handler\nconst manager = new RequestManager();\nmanager.use([Fetch]);\n\n// ... execute a request\nconst response = await manager.request({\n url: `${apiUrl}/users`\n});\n```\n\n\n## πŸͺœ Architecture\n\nA `RequestManager` receives a request and manages fulfillment via configured handlers. It may be used standalone from the rest of *Ember*‍**Data** and is not specific to any library or framework.\n\nEach handler may choose to fulfill the request using some source of data or to pass the request along to other handlers.\n\nThe same or a separate instance of a `RequestManager` may also be used to fulfill requests issued by [*Ember*‍**Data**{Store}](https://github.com/emberjs/data/tree/master/packages/store)\n\nWhen the same instance is used by both this allows for simple coordination throughout the application. Requests issued by the Store will use the in-memory cache\nand return hydrated responses, requests issued directly to the RequestManager\nwill skip the in-memory cache and return raw responses.\n\n## Usage\n\n
\n Making Requests\n\n`RequestManager` has a single asyncronous method as it's API: `request`\n\n```ts\nclass RequestManager {\n async request(req: RequestInfo): Future;\n}\n```\n\n`manager.request` accepts a `RequestInfo`, an object containing the information\nnecessary for the request to be handled successfully.\n\n`RequestInfo` extends the [options](https://developer.mozilla.org/en-US/docs/Web/API/fetch#parameters) provided to `fetch`, and can accept a [`Request`](https://developer.mozilla.org/en-US/docs/Web/API/Request/Request). All properties accepted by Request options and fetch options are valid on `RequestInfo`.\n\n```ts\ninterface RequestInfo extends FetchOptions {\n url: string;\n // data that a handler should convert into\n // the query (GET) or body (POST)\n data?: Record;\n// options specifically intended for handlers\n // to utilize to process the request\n options?: Record;\n}\n```\n\n> **note:** providing a `signal` is unnecessary as an `AbortController` is automatically provided if none is present.\n\n
\n
\n Using the Response
\n\n`manager.request` returns a `Future`, which allows access to limited information about the request while it is still pending and fulfills with the final state when the request completes and the response has been read.\n\nA `Future` is cancellable via `abort`.\n\nHandlers may *optionally* expose a ReadableStream to the `Future` for streaming data; however, when doing so the handler should not resolve until it has fully read the response stream itself.\n\n```ts\ninterface Future extends Promise> {\n abort(): void;\nasync getStream(): ReadableStream | null;\n}\n```\n\nA Future resolves or rejects with a `StructuredDocument`.\n\n```ts\ninterface StructuredDocument {\n request: RequestInfo;\n response: ResponseInfo | null;\n data?: T;\n error?: Error;\n}\n```\n\nThe `RequestInfo` specified by `document.request` is the same as originally provided to `manager.request`. If any handler fulfilled this request using different request info it is not represented here. This contract helps to ensure that `retry` and `caching` are possible since the original arguments are correctly preserved. This also allows handlers to \"fork\" the request or fulfill from multiple sources without the details of fulfillment muddying the original request.\n\nThe `ResponseInfo` is a serializable fulfilled subset of a [Response](https://developer.mozilla.org/en-US/docs/Web/API/Response) if set via `setResponse`. If no response was ever set this will be `null`.\n\n```ts\ninterface ResponseInfo {\n headers?: Record;\n ok?: boolean;\n redirected?: boolean;\n status?: HTTPStatusCode;\n statusText?: string;\n type?: 'basic' | 'cors';\n url?: string;\n}\n```\n\n
\n\n

Handling Requests

\n
\n { request(context, next): Promise | Future; }
\n\nRequests are fulfilled by handlers. A handler receives the request context\nas well as a `next` function with which to pass along a request to the next\nhandler if it so chooses.\n\nA handler may be any object with a `request` method. This allows both stateful and non-stateful\nhandlers to be utilized.\n\nIf a handler calls `next`, it receives a `Future` which resolves to a `StructuredDocument`\nthat it can then compose how it sees fit with its own response.\n\n```ts\n\ntype NextFn

= (req: RequestInfo) => Future

;\n\ninterface Handler {\n async request(context: RequestContext, next: NextFn

): T;\n}\n```\n\n`RequestContext` contains a readonly version of the RequestInfo as well as a few methods for building up the `StructuredDocument` and `Future` that will be part of the response.\n\n```ts\ninterface RequestContext {\n readonly request: RequestInfo;\nsetStream(stream: ReadableStream | Promise): void;\n setResponse(response: Response | ResponseInfo): void;\n}\n```\n\nA basic `fetch` handler with support for streaming content updates while\nthe download is still underway might look like the following, where we use\n[`response.clone()`](https://developer.mozilla.org/en-US/docs/Web/API/Response/clone) to `tee` the `ReadableStream` into two streams.\n\nA more efficient handler might read from the response stream, building up the\nresponse data before passing along the chunk downstream.\n\n```ts\nconst FetchHandler = {\n async request(context) {\n const response = await fetch(context.request);\n context.setResponse(reponse);\n context.setStream(response.clone().body);\n return response.json();\n }\n}\n```\n\nRequest handlers are registered by configuring the manager via `use`\n\n```ts\nmanager.use([Handler1, Handler2])\n```\n\nHandlers will be invoked in the order they are registered (\"fifo\", first-in first-out), and may only be registered up until the first request is made. It is recommended but not required to register all handlers at one time in order to ensure explicitly visible handler ordering.\n\n

\n\n
\n Stream Currying
\n\n`RequestManager.request` and `next` differ from `fetch` in one **crucial detail** in that the outer Promise resolves only once the response stream has been processed.\n\nFor context, it helps to understand a few of the use-cases that RequestManager\nis intended to allow.\n\n- to manage and return streaming content (such as video files)\n- to fulfill a request from multiple sources or by splitting one request into multiple requests\n - for instance one API call for a user and another for the user's friends\n - or e.g. fulfilling part of the request from one source (one API, in-memory, localStorage, IndexedDB\n etc.) and the rest from another source (a different API, a WebWorker, etc.)\n- to coalesce multiple requests\n- to decorate a request with additional info\n - e.g. an Auth handler that ensures the correct tokens or headers or cookies are attached.\n\n`await fetch()` resolves at the moment headers are received. This allows for the body of the request to be processed as a stream by application\ncode *while chunks are still being received by the browser*.\n\nWhen an app chooses to `await response.json()` what occurs is the browser reads the stream to completion and then returns the result. Additionally, this stream may only be read **once**.\n\nThe `RequestManager` preserves this ability to subscribe to and utilize the stream by either the application or the handler – thereby delivering the full power and flexibility of native APIs – without restricting developers in ways that lead to complicated workarounds.\n\nEach handler may call `setStream` only once, but may do so *at any time* until the promise that the handler returns has resolved. The associated promise returned by calling `future.getStream` will resolve with the stream set by `setStream` if that method is called, or `null` if that method\nhas not been called by the time that the handler's request method has resolved.\n\nHandlers that do not create a stream of their own, but which call `next`, should defensively pipe the stream forward. While this is not required (see automatic currying below) it is better to do so in most cases as otherwise the stream may not become available to downstream handlers or the application until the upstream handler has fully read it.\n\n```ts\ncontext.setStream(future.getStream());\n```\n\nHandlers that either call `next` multiple times or otherwise have reason to create multiple fetch requests should either choose to return no stream, meaningfully combine the streams, or select a single prioritized stream.\n\nOf course, any handler may choose to read and handle the stream, and return either no stream or a different stream in the process.\n\n
\n\n
\n Automatic Currying of Stream and Response
\n\nIn order to simplify the common case for handlers which decorate a request, if `next` is called only a single time and `setResponse` was never called by the handler, the response set by the next handler in the chain will be applied to that handler's outcome. For instance, this makes the following pattern possible `return (await next()).data;`.\n\nSimilarly, if `next` is called only a single time and neither `setStream` nor `getStream` was called, we automatically curry the stream from the future returned by `next` onto the future returned by the handler.\n\nFinally, if the return value of a handler is a `Future`, we curry `data` and `errors` as well, thus enabling the simplest form `return next()`.\n\nIn the case of the `Future` being returned, `Stream` proxying is automatic and immediate and does not wait for the `Future` to resolve.\n\n
\n\n### Using as a Service\n\nMost applications will desire to have a single `RequestManager` instance, which can be achieved using module-state patterns for singletons, or for [Ember](https://emberjs.com) applications by exporting the manager as a [service](https://guides.emberjs.com/release/services/).\n\nservices/request.ts*\n```ts\nimport { RequestManager } from '@ember-data/request';\nimport { Fetch } from '@ember-data/request/fetch';\nimport Auth from 'ember-simple-auth/ember-data-handler';\n\nexport default class extends RequestManager {\n constructor(createArgs) {\n super(createArgs);\n this.use([Auth, Fetch]);\n }\n}\n```\n\n### Using with `@ember-data/store`\n\nTo have a request service unique to a Store:\n\n```ts\nimport Store from '@ember-data/store';\nimport { RequestManager } from '@ember-data/request';\nimport { Fetch } from '@ember-data/request/fetch';\n\nclass extends Store {\n requestManager = new RequestManager();\nconstructor(args) {\n super(args);\n this.requestManager.use([Fetch]);\n }\n}\n```\n\n### Using with `ember-data`\n\nIf using the package [ember-data](https://github.com/emberjs/data/tree/master/packages/-ember-data), the following configuration will automatically be done in order to preserve the legacy [Adapter](https://github.com/emberjs/data/tree/master/packages/adapter) and [Serializer](https://github.com/emberjs/data/tree/master/packages/serializer) behavior. Additional handlers or a service injection like the above would need to be done by the consuming application in order to make broader use of `RequestManager`.\n\n```ts\nimport Store from '@ember-data/store';\nimport { RequestManager } from '@ember-data/request';\nimport { LegacyHandler } from '@ember-data/legacy-network-handler';\n\nexport default class extends Store {\n requestManager = new RequestManager();\nconstructor(args) {\n super(args);\n this.requestManager.use([LegacyHandler]);\n }\n}\n```\n\nBecause the application's store service (if present) will override the store supplied by `ember-data`, all that is required to define your own ordering and handlers is to supply a store service extending from `@ember-data/store` and configure as shown above.\n\nFor usage of the store's `requestManager` via `store.request()` see the [Store](https://api.emberjs.com/ember-data/release/modules/@ember-data%2Fstore) documentation.", + "description": "

\n \n

\n\n

⚑️ a simple abstraction over fetch to enable easy management of request/response flows

\n\nThis package provides [*Ember*‍**Data**](https://github.com/emberjs/data/)'s `RequestManager`, a framework agnostic library that can be integrated with any Javascript application to make [fetch](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) happen.\n\n## Installation\n\nInstall using your javascript package manager of choice. For instance with [pnpm](https://pnpm.io/)\n\n```\npnpm add @ember-data/request\n```\n\n## πŸš€ Basic Usage\n\nA `RequestManager` provides a request/response flow in which configured handlers are successively given the opportunity to handle, modify, or pass-along a request.\n\nThe RequestManager on its own does not know how to fulfill requests. For this we must register at least one handler. A basic `Fetch` handler is provided that will take the request options provided and execute `fetch`.\n\n```ts\nimport { RequestManager } from '@ember-data/request';\nimport { Fetch } from '@ember-data/request/fetch';\nimport { apiUrl } from './config';\n\n// ... create manager and add our Fetch handler\nconst manager = new RequestManager();\nmanager.use([Fetch]);\n\n// ... execute a request\nconst response = await manager.request({\n url: `${apiUrl}/users`\n});\n```\n\n\n## πŸͺœ Architecture\n\nA `RequestManager` receives a request and manages fulfillment via configured handlers. It may be used standalone from the rest of *Ember*‍**Data** and is not specific to any library or framework.\n\nEach handler may choose to fulfill the request using some source of data or to pass the request along to other handlers.\n\nThe same or a separate instance of a `RequestManager` may also be used to fulfill requests issued by [*Ember*‍**Data**{Store}](https://github.com/emberjs/data/tree/master/packages/store)\n\nWhen the same instance is used by both this allows for simple coordination throughout the application. Requests issued by the Store will use the in-memory cache\nand return hydrated responses, requests issued directly to the RequestManager\nwill skip the in-memory cache and return raw responses.\n\n## Usage\n\n
\n Making Requests\n\n`RequestManager` has a single asyncronous method as it's API: `request`\n\n```ts\nclass RequestManager {\n async request(req: RequestInfo): Future;\n}\n```\n\n`manager.request` accepts a `RequestInfo`, an object containing the information\nnecessary for the request to be handled successfully.\n\n`RequestInfo` extends the [options](https://developer.mozilla.org/en-US/docs/Web/API/fetch#parameters) provided to `fetch`, and can accept a [`Request`](https://developer.mozilla.org/en-US/docs/Web/API/Request/Request). All properties accepted by Request options and fetch options are valid on `RequestInfo`.\n\n```ts\ninterface RequestInfo extends FetchOptions {\n url: string;\n // data that a handler should convert into\n // the query (GET) or body (POST)\n data?: Record;\n// options specifically intended for handlers\n // to utilize to process the request\n options?: Record;\n}\n```\n\n> **note:** providing a `signal` is unnecessary as an `AbortController` is automatically provided if none is present.\n\n
\n
\n Using the Response
\n\n`manager.request` returns a `Future`, which allows access to limited information about the request while it is still pending and fulfills with the final state when the request completes and the response has been read.\n\nA `Future` is cancellable via `abort`.\n\nHandlers may *optionally* expose a ReadableStream to the `Future` for streaming data; however, when doing so the handler should not resolve until it has fully read the response stream itself.\n\n```ts\ninterface Future extends Promise> {\n abort(): void;\nasync getStream(): ReadableStream | null;\n}\n```\n\nA Future resolves or rejects with a `StructuredDocument`.\n\n```ts\ninterface StructuredDocument {\n request: RequestInfo;\n response: ResponseInfo | null;\n data?: T;\n error?: Error;\n}\n```\n\nThe `RequestInfo` specified by `document.request` is the same as originally provided to `manager.request`. If any handler fulfilled this request using different request info it is not represented here. This contract helps to ensure that `retry` and `caching` are possible since the original arguments are correctly preserved. This also allows handlers to \"fork\" the request or fulfill from multiple sources without the details of fulfillment muddying the original request.\n\nThe `ResponseInfo` is a serializable fulfilled subset of a [Response](https://developer.mozilla.org/en-US/docs/Web/API/Response) if set via `setResponse`. If no response was ever set this will be `null`.\n\n```ts\ninterface ResponseInfo {\n headers?: Record;\n ok?: boolean;\n redirected?: boolean;\n status?: HTTPStatusCode;\n statusText?: string;\n type?: 'basic' | 'cors';\n url?: string;\n}\n```\n\n
\n\n

Handling Requests

\n
\n { request(context, next): Promise | Future; }
\n\nRequests are fulfilled by handlers. A handler receives the request context\nas well as a `next` function with which to pass along a request to the next\nhandler if it so chooses.\n\nA handler may be any object with a `request` method. This allows both stateful and non-stateful\nhandlers to be utilized.\n\nIf a handler calls `next`, it receives a `Future` which resolves to a `StructuredDocument`\nthat it can then compose how it sees fit with its own response.\n\n```ts\n\ntype NextFn

= (req: RequestInfo) => Future

;\n\ninterface Handler {\n async request(context: RequestContext, next: NextFn

): T;\n}\n```\n\n`RequestContext` contains a readonly version of the RequestInfo as well as a few methods for building up the `StructuredDocument` and `Future` that will be part of the response.\n\n```ts\ninterface RequestContext {\n readonly request: RequestInfo;\nsetStream(stream: ReadableStream | Promise): void;\n setResponse(response: Response | ResponseInfo): void;\n}\n```\n\nA basic `fetch` handler with support for streaming content updates while\nthe download is still underway might look like the following, where we use\n[`response.clone()`](https://developer.mozilla.org/en-US/docs/Web/API/Response/clone) to `tee` the `ReadableStream` into two streams.\n\nA more efficient handler might read from the response stream, building up the\nresponse data before passing along the chunk downstream.\n\n```ts\nconst FetchHandler = {\n async request(context) {\n const response = await fetch(context.request);\n context.setResponse(reponse);\n context.setStream(response.clone().body);\n return response.json();\n }\n}\n```\n\nRequest handlers are registered by configuring the manager via `use`\n\n```ts\nmanager.use([Handler1, Handler2])\n```\n\nHandlers will be invoked in the order they are registered (\"fifo\", first-in first-out), and may only be registered up until the first request is made. It is recommended but not required to register all handlers at one time in order to ensure explicitly visible handler ordering.\n\n

\n\n
\n Stream Currying
\n\n`RequestManager.request` and `next` differ from `fetch` in one **crucial detail** in that the outer Promise resolves only once the response stream has been processed.\n\nFor context, it helps to understand a few of the use-cases that RequestManager\nis intended to allow.\n\n- to manage and return streaming content (such as video files)\n- to fulfill a request from multiple sources or by splitting one request into multiple requests\n - for instance one API call for a user and another for the user's friends\n - or e.g. fulfilling part of the request from one source (one API, in-memory, localStorage, IndexedDB\n etc.) and the rest from another source (a different API, a WebWorker, etc.)\n- to coalesce multiple requests\n- to decorate a request with additional info\n - e.g. an Auth handler that ensures the correct tokens or headers or cookies are attached.\n\n`await fetch()` resolves at the moment headers are received. This allows for the body of the request to be processed as a stream by application\ncode *while chunks are still being received by the browser*.\n\nWhen an app chooses to `await response.json()` what occurs is the browser reads the stream to completion and then returns the result. Additionally, this stream may only be read **once**.\n\nThe `RequestManager` preserves this ability to subscribe to and utilize the stream by either the application or the handler – thereby delivering the full power and flexibility of native APIs – without restricting developers in ways that lead to complicated workarounds.\n\nEach handler may call `setStream` only once, but may do so *at any time* until the promise that the handler returns has resolved. The associated promise returned by calling `future.getStream` will resolve with the stream set by `setStream` if that method is called, or `null` if that method\nhas not been called by the time that the handler's request method has resolved.\n\nHandlers that do not create a stream of their own, but which call `next`, should defensively pipe the stream forward. While this is not required (see automatic currying below) it is better to do so in most cases as otherwise the stream may not become available to downstream handlers or the application until the upstream handler has fully read it.\n\n```ts\ncontext.setStream(future.getStream());\n```\n\nHandlers that either call `next` multiple times or otherwise have reason to create multiple fetch requests should either choose to return no stream, meaningfully combine the streams, or select a single prioritized stream.\n\nOf course, any handler may choose to read and handle the stream, and return either no stream or a different stream in the process.\n\n
\n\n
\n Automatic Currying of Stream and Response
\n\nIn order to simplify the common case for handlers which decorate a request, if `next` is called only a single time and `setResponse` was never called by the handler, the response set by the next handler in the chain will be applied to that handler's outcome. For instance, this makes the following pattern possible `return (await next()).data;`.\n\nSimilarly, if `next` is called only a single time and neither `setStream` nor `getStream` was called, we automatically curry the stream from the future returned by `next` onto the future returned by the handler.\n\nFinally, if the return value of a handler is a `Future`, we curry `data` and `errors` as well, thus enabling the simplest form `return next()`.\n\nIn the case of the `Future` being returned, `Stream` proxying is automatic and immediate and does not wait for the `Future` to resolve.\n\n
\n\n### Using as a Service\n\nMost applications will desire to have a single `RequestManager` instance, which can be achieved using module-state patterns for singletons, or for [Ember](https://emberjs.com) applications by exporting the manager as a [service](https://guides.emberjs.com/release/services/).\n\nservices/request.ts*\n```ts\nimport { RequestManager } from '@ember-data/request';\nimport { Fetch } from '@ember-data/request/fetch';\nimport Auth from 'ember-simple-auth/ember-data-handler';\n\nexport default class extends RequestManager {\n constructor(createArgs) {\n super(createArgs);\n this.use([Auth, Fetch]);\n }\n}\n```\n\n### Using with `@ember-data/store`\n\nTo have a request service unique to a Store:\n\n```ts\nimport Store from '@ember-data/store';\nimport { RequestManager } from '@ember-data/request';\nimport { Fetch } from '@ember-data/request/fetch';\n\nclass extends Store {\n requestManager = new RequestManager();\nconstructor(args) {\n super(args);\n this.requestManager.use([Fetch]);\n }\n}\n```\n\n### Using with `ember-data`\n\nIf using the package [ember-data](https://github.com/emberjs/data/tree/master/packages/-ember-data), the following configuration will automatically be done in order to preserve the legacy [Adapter](https://github.com/emberjs/data/tree/master/packages/adapter) and [Serializer](https://github.com/emberjs/data/tree/master/packages/serializer) behavior. Additional handlers or a service injection like the above would need to be done by the consuming application in order to make broader use of `RequestManager`.\n\n```ts\nimport Store from '@ember-data/store';\nimport { RequestManager } from '@ember-data/request';\nimport { LegacyHandler } from '@ember-data/legacy-network-handler';\n\nexport default class extends Store {\n requestManager = new RequestManager();\nconstructor(args) {\n super(args);\n this.requestManager.use([LegacyHandler]);\n }\n}\n```\n\nBecause the application's store service (if present) will override the store supplied by `ember-data`, all that is required to define your own ordering and handlers is to supply a store service extending from `@ember-data/store` and configure as shown above.\n\nFor usage of the store's `requestManager` via `store.request()` see the [Store](https://api.emberjs.com/ember-data/release/modules/@ember-data%2Fstore) documentation.", "itemtype": "main", "parent": null, "publicclasses": [ diff --git a/json-docs/ember-data/4.11.3/modules/ember-data-4.11.3-ember-data-overview.json b/json-docs/ember-data/4.11.3/modules/ember-data-4.11.3-ember-data-overview.json index 4b082ece6..981fcc7dd 100644 --- a/json-docs/ember-data/4.11.3/modules/ember-data-4.11.3-ember-data-overview.json +++ b/json-docs/ember-data/4.11.3/modules/ember-data-4.11.3-ember-data-overview.json @@ -11,7 +11,7 @@ "tag": "main", "file": "../packages/-ember-data/addon/index.js", "line": 1, - "description": "

\n \n

\n\n

The lightweight reactive data library for JavaScript applications

\n\n---\n\nWrangle your application's data management with scalable patterns for developer productivity.\n\n- ⚑️ Committed to Best-In-Class Performance\n- 🌲 Focused on being as svelte as possible\n- πŸš€ SSR Ready\n- πŸ”œ Typescript Support\n- 🐹 Built with β™₯️ by [Ember](https://emberjs.com)\n- βš›οΈ Supports any API: `GraphQL` `JSON:API` `REST` `tRPC` ...bespoke or a mix\n\n### πŸ“– On This Page\n\n- [Overview](./#overview)\n - [Architecture](#πŸͺœ-architecture)\n - [Basic Installation](#basic-installation)\n - [Advanced Installation](#advanced-installation)\n- [Configuration](#configuration)\n - [Deprecation Stripping](#deprecation-stripping)\n - [randomUUID polyfill](#randomuuid-polyfill)\n - [Removing inspector support in production](#removing-inspector-support-in-production)\n - [Debugging](#debugging)\n\n\n# Overview\n\n*Ember*‍**Data** is a lightweight reactive data library for JavaScript applications that provides composable primitives for ordering query/mutation/peek flows, managing network and cache, and reducing data for presentation.\n\n## πŸͺœ Architecture\n\nThe core of *Ember*‍**Data** is the `Store`, which coordinates interaction between your application, the `Cache`, and sources of data (such as your `API` or a local persistence layer).\nOptionally, the Store can be configured to hydrate the response data into rich presentation classes.\n\n*Ember*‍**Data** is both resource centric and document centric in it's approach to caching, requesting and presenting data. Your application's configuration and usage drives which is important and when.\n\nThe `Store` is a **coordinator**. When using a `Store` you configure what cache to use, how cache data should be presented to the UI, and where it should look for requested data when it is not available in the cache.\n\nThis coordination is handled opaquely to the nature of the requests issued and the format of the data being handled. This approach gives applications broad flexibility to configure *Ember*‍**Data** to best suite their needs. This makes *Ember*‍**Data** a powerful solution for applications regardless of their size and complexity.\n\n*Ember*‍**Data** is designed to scale, with a religious focus on performance and asset-size to keep its footprint small but speedy while still being able to handle large complex APIs in huge data-driven applications with no additional code and no added application complexity. It's goal is to prevent applications from writing code to manage data that is difficult to maintain or reason about.\n\n*Ember*‍**Data**'s power comes not from specific features, data formats, or adherence to specific API specs such as `JSON:API` `trpc` or `GraphQL`, but from solid conventions around requesting and mutating data developed over decades of experience scaling developer productivity.\n\n## Basic Installation\n\nInstall using your javascript package manager of choice. For instance with [pnpm](https://pnpm.io/)\n\n```no-highlight\npnpm add ember-data\n```\n\n`ember-data` is installed by default for new applications generated with `ember-cli`. You can check what version is installed by looking in the `devDependencies` hash of your project's [package.json](https://docs.npmjs.com/cli/v8/configuring-npm/package-json) file.\n\nIf you have generated a new `Ember` application using `ember-cli` but do\nnot wish to use `ember-data`, remove `ember-data` from your project's `package.json` file and run your package manager's install command to update your lockfile.\n\n## Advanced Installation\n\n*Ember*‍**Data** is organized into primitives that compose together via public APIs.\n\n- [@ember-data/store](/ember-data/release/modules/@ember-data%2Fstore) is the core and handles coordination\n- [@ember-data/record-data](/ember-data/release/modules/@ember-data%2Frecord-data) is a resource cache for JSON:API structured data. It integrates with the store via the hook `createRecordDataFor`\n- [@ember-data/model](/ember-data/release/modules/@ember-data%2Fmodel) is a presentation layer, it integrates with the store via the hooks `instantiateRecord` and `teardownRecord`.\n- [@ember-data/adapter](/ember-data/release/modules/@ember-data%2Fadapter) provides various network API integrations for APIS built over specific REST or JSON:API conventions.\n- [@ember-data/serializer](/ember-data/release/modules/@ember-data%2Fserializer) pairs with `@ember-data/adapter` to normalize and serialize data to and from an API format into the `JSON:API` format understood by `@ember-data/record-data`.\n- [@ember-data/debug](/ember-data/release/modules/@ember-data%2Fdebug) provides debugging support for the `ember-inspector`.\n- **ember-data** is a \"meta\" package which bundles all of these together for convenience\n\nThe packages interop with each other through well defined public API boundaries. The core\nof the library is the store provided by `@ember-data/store`, while each of the other libraries plugs into the store when installed. Because these packages interop via fully\npublic APIs, other libraries or applications may provide their own implementations. For instance, [ember-m3](https://github.com/hjdivad/ember-m3) is a commonly used presentation and cache implementation suitable for complex resource objects and graphs.\n\n## Configuration\n\n### Deprecation Stripping\n\n*Ember*‍**Data** allows users to opt-in and remove code that exists to support deprecated behaviors.\n\nIf your app has resolved all deprecations present in a given version, you may specify that version as your \"compatibility\" version to remove the code that supported the deprecated behavior from your app.\n\n```ts\nlet app = new EmberApp(defaults, {\n emberData: {\n compatWith: '4.8',\n },\n});\n```\n\n- [Full Documentation](https://api.emberjs.com/ember-data/release/modules/@ember-data%2Fdeprecations)\n\n### randomUUID polyfill\n\n*Ember*‍**Data** uses `UUID V4` by default to generate identifiers for new data created on the client. Identifier generation is configurable, but we also for convenience will polyfill\nthe necessary feature if your browser support or deployment environment demands it. To\nactivate this polyfill:\n\n```ts\nlet app = new EmberApp(defaults, {\n '@embroider/macros': {\n setConfig: {\n '@ember-data/store': {\n polyfillUUID: true\n },\n },\n },\n});\n```\n\n### removing inspector support in production\n\nIf you do not with to ship inspector support in your production application, you can specify\nthat all support for it should be stripped from the build.\n\n```ts\nlet app = new EmberApp(defaults, {\n emberData: {\n includeDataAdapterInProduction: false\n }\n});\n```\n\n- [Full Documentation](https://api.emberjs.com/ember-data/release/modules/@ember-data%2Fdebug)\n\n### Debugging\n\nMany portions of the internals are helpfully instrumented with logging that can be activated\nat build time. This instrumentation is always removed from production builds or any builds\nthat has not explicitly activated it. To activate it set the appropriate flag to `true`.\n\n```ts\n let app = new EmberApp(defaults, {\n emberData: {\n debug: {\n LOG_PAYLOADS: false, // data store received to update cache with\n LOG_OPERATIONS: false, // updates to cache remote state\n LOG_MUTATIONS: false, // updates to cache local state\n LOG_NOTIFICATIONS: false,\n LOG_REQUEST_STATUS: false,\n LOG_IDENTIFIERS: false,\n LOG_GRAPH: false,\n LOG_INSTANCE_CACHE: false,\n }\n }\n });\n ```", + "description": "

\n \n

\n\n

The lightweight reactive data library for JavaScript applications

\n\n---\n\nWrangle your application's data management with scalable patterns for developer productivity.\n\n- ⚑️ Committed to Best-In-Class Performance\n- 🌲 Focused on being as svelte as possible\n- πŸš€ SSR Ready\n- πŸ”œ Typescript Support\n- 🐹 Built with β™₯️ by [Ember](https://emberjs.com)\n- βš›οΈ Supports any API: `GraphQL` `JSON:API` `REST` `tRPC` ...bespoke or a mix\n\n### πŸ“– On This Page\n\n- [Overview](./#overview)\n - [Architecture](#πŸͺœ-architecture)\n - [Basic Installation](#basic-installation)\n - [Advanced Installation](#advanced-installation)\n- [Configuration](#configuration)\n - [Deprecation Stripping](#deprecation-stripping)\n - [randomUUID polyfill](#randomuuid-polyfill)\n - [Removing inspector support in production](#removing-inspector-support-in-production)\n - [Debugging](#debugging)\n\n\n# Overview\n\n*Ember*‍**Data** is a lightweight reactive data library for JavaScript applications that provides composable primitives for ordering query/mutation/peek flows, managing network and cache, and reducing data for presentation.\n\n## πŸͺœ Architecture\n\nThe core of *Ember*‍**Data** is the `Store`, which coordinates interaction between your application, the `Cache`, and sources of data (such as your `API` or a local persistence layer).\nOptionally, the Store can be configured to hydrate the response data into rich presentation classes.\n\n*Ember*‍**Data** is both resource centric and document centric in it's approach to caching, requesting and presenting data. Your application's configuration and usage drives which is important and when.\n\nThe `Store` is a **coordinator**. When using a `Store` you configure what cache to use, how cache data should be presented to the UI, and where it should look for requested data when it is not available in the cache.\n\nThis coordination is handled opaquely to the nature of the requests issued and the format of the data being handled. This approach gives applications broad flexibility to configure *Ember*‍**Data** to best suite their needs. This makes *Ember*‍**Data** a powerful solution for applications regardless of their size and complexity.\n\n*Ember*‍**Data** is designed to scale, with a religious focus on performance and asset-size to keep its footprint small but speedy while still being able to handle large complex APIs in huge data-driven applications with no additional code and no added application complexity. It's goal is to prevent applications from writing code to manage data that is difficult to maintain or reason about.\n\n*Ember*‍**Data**'s power comes not from specific features, data formats, or adherence to specific API specs such as `JSON:API` `trpc` or `GraphQL`, but from solid conventions around requesting and mutating data developed over decades of experience scaling developer productivity.\n\n## Basic Installation\n\nInstall using your javascript package manager of choice. For instance with [pnpm](https://pnpm.io/)\n\n```\npnpm add ember-data\n```\n\n`ember-data` is installed by default for new applications generated with `ember-cli`. You can check what version is installed by looking in the `devDependencies` hash of your project's [package.json](https://docs.npmjs.com/cli/v8/configuring-npm/package-json) file.\n\nIf you have generated a new `Ember` application using `ember-cli` but do\nnot wish to use `ember-data`, remove `ember-data` from your project's `package.json` file and run your package manager's install command to update your lockfile.\n\n## Advanced Installation\n\n*Ember*‍**Data** is organized into primitives that compose together via public APIs.\n\n- [@ember-data/store](/ember-data/release/modules/@ember-data%2Fstore) is the core and handles coordination\n- [@ember-data/record-data](/ember-data/release/modules/@ember-data%2Frecord-data) is a resource cache for JSON:API structured data. It integrates with the store via the hook `createRecordDataFor`\n- [@ember-data/model](/ember-data/release/modules/@ember-data%2Fmodel) is a presentation layer, it integrates with the store via the hooks `instantiateRecord` and `teardownRecord`.\n- [@ember-data/adapter](/ember-data/release/modules/@ember-data%2Fadapter) provides various network API integrations for APIS built over specific REST or JSON:API conventions.\n- [@ember-data/serializer](/ember-data/release/modules/@ember-data%2Fserializer) pairs with `@ember-data/adapter` to normalize and serialize data to and from an API format into the `JSON:API` format understood by `@ember-data/record-data`.\n- [@ember-data/debug](/ember-data/release/modules/@ember-data%2Fdebug) provides debugging support for the `ember-inspector`.\n- **ember-data** is a \"meta\" package which bundles all of these together for convenience\n\nThe packages interop with each other through well defined public API boundaries. The core\nof the library is the store provided by `@ember-data/store`, while each of the other libraries plugs into the store when installed. Because these packages interop via fully\npublic APIs, other libraries or applications may provide their own implementations. For instance, [ember-m3](https://github.com/hjdivad/ember-m3) is a commonly used presentation and cache implementation suitable for complex resource objects and graphs.\n\n## Configuration\n\n### Deprecation Stripping\n\n*Ember*‍**Data** allows users to opt-in and remove code that exists to support deprecated behaviors.\n\nIf your app has resolved all deprecations present in a given version, you may specify that version as your \"compatibility\" version to remove the code that supported the deprecated behavior from your app.\n\n```ts\nlet app = new EmberApp(defaults, {\n emberData: {\n compatWith: '4.8',\n },\n});\n```\n\n- [Full Documentation](https://api.emberjs.com/ember-data/release/modules/@ember-data%2Fdeprecations)\n\n### randomUUID polyfill\n\n*Ember*‍**Data** uses `UUID V4` by default to generate identifiers for new data created on the client. Identifier generation is configurable, but we also for convenience will polyfill\nthe necessary feature if your browser support or deployment environment demands it. To\nactivate this polyfill:\n\n```ts\nlet app = new EmberApp(defaults, {\n '@embroider/macros': {\n setConfig: {\n '@ember-data/store': {\n polyfillUUID: true\n },\n },\n },\n});\n```\n\n### removing inspector support in production\n\nIf you do not with to ship inspector support in your production application, you can specify\nthat all support for it should be stripped from the build.\n\n```ts\nlet app = new EmberApp(defaults, {\n emberData: {\n includeDataAdapterInProduction: false\n }\n});\n```\n\n- [Full Documentation](https://api.emberjs.com/ember-data/release/modules/@ember-data%2Fdebug)\n\n### Debugging\n\nMany portions of the internals are helpfully instrumented with logging that can be activated\nat build time. This instrumentation is always removed from production builds or any builds\nthat has not explicitly activated it. To activate it set the appropriate flag to `true`.\n\n```ts\n let app = new EmberApp(defaults, {\n emberData: {\n debug: {\n LOG_PAYLOADS: false, // data store received to update cache with\n LOG_OPERATIONS: false, // updates to cache remote state\n LOG_MUTATIONS: false, // updates to cache local state\n LOG_NOTIFICATIONS: false,\n LOG_REQUEST_STATUS: false,\n LOG_IDENTIFIERS: false,\n LOG_GRAPH: false,\n LOG_INSTANCE_CACHE: false,\n }\n }\n });\n ```", "itemtype": "main", "parent": null, "publicclasses": [], diff --git a/json-docs/ember-data/4.12.3/modules/ember-data-4.12.3-@ember-data/graph.json b/json-docs/ember-data/4.12.3/modules/ember-data-4.12.3-@ember-data/graph.json index 9a1faab81..d1b1fd92a 100644 --- a/json-docs/ember-data/4.12.3/modules/ember-data-4.12.3-@ember-data/graph.json +++ b/json-docs/ember-data/4.12.3/modules/ember-data-4.12.3-@ember-data/graph.json @@ -11,7 +11,7 @@ "tag": "main", "file": "../graph/src/-private.ts", "line": 3, - "description": "

\n \n

\n\n

Provides a performance tuned normalized graph for intelligently managing relationships between resources based on identity

\n\nWhile this Graph is abstract, it currently is a private implementation required as a peer-dependency by the [JSON:API Cache Implementation](https://github.com/emberjs/data/tree/main/packages/json-api).\n\nWe intend to make this Graph public API after some additional iteration during the 5.x timeframe, until then all APIs should be considered experimental and unstable, not fit for direct application or 3rd party library usage.\n\n## Installation\n\nInstall using your javascript package manager of choice. For instance with [pnpm](https://pnpm.io/)\n\n```no-highlight\npnpm add @ember-data/graph\n```", + "description": "

\n \n

\n\n

Provides a performance tuned normalized graph for intelligently managing relationships between resources based on identity

\n\nWhile this Graph is abstract, it currently is a private implementation required as a peer-dependency by the [JSON:API Cache Implementation](https://github.com/emberjs/data/tree/main/packages/json-api).\n\nWe intend to make this Graph public API after some additional iteration during the 5.x timeframe, until then all APIs should be considered experimental and unstable, not fit for direct application or 3rd party library usage.\n\n## Installation\n\nInstall using your javascript package manager of choice. For instance with [pnpm](https://pnpm.io/)\n\n```\npnpm add @ember-data/graph\n```", "itemtype": "main", "parent": null, "publicclasses": [], diff --git a/json-docs/ember-data/4.12.3/modules/ember-data-4.12.3-@ember-data/json-api.json b/json-docs/ember-data/4.12.3/modules/ember-data-4.12.3-@ember-data/json-api.json index 2311cec8b..8aeab58fb 100644 --- a/json-docs/ember-data/4.12.3/modules/ember-data-4.12.3-@ember-data/json-api.json +++ b/json-docs/ember-data/4.12.3/modules/ember-data-4.12.3-@ember-data/json-api.json @@ -11,7 +11,7 @@ "tag": "main", "file": "../json-api/src/-private/cache.ts", "line": 85, - "description": "

\n \n

\n\nThis package provides an in-memory [JSON:API](https://jsonapi.org/) document and resource [*Ember***Data** Cache](https://github.com/emberjs/data/blob/main/ember-data-types/cache/cache.ts) implementation.\n\n## Installation\n\nInstall using your javascript package manager of choice. For instance with [pnpm](https://pnpm.io/)\n\n```no-highlight\npnpm add @ember-data/json-api\n```\n\n## πŸš€ Setup\n\n> **Note** When using [ember-data](https://github.com/emberjs/data/blob/main/packages/-ember-data) the below\n> configuration is handled for you automatically.\n\n```ts\nimport Store from '@ember-data/store';\nimport Cache from '@ember-data/json-api';\n\nexport default class extends Store {\n createCache(wrapper) {\n return new Cache(wrapper);\n }\n}\n```\n\n\n## Usage\n\nUsually you will directly interact with the cache only if implementing a presentation class. Below we\ngive an example of a read-only record (mutations never written back to the cache). More typically cache\ninteractions are something that the `Store` coordinates as part of the `request/response` lifecycle.\n\n```ts\nimport Store, { recordIdentifierFor } from '@ember-data/store';\nimport Cache from '@ember-data/json-api';\nimport { TrackedObject } from 'tracked-built-ins';\n\nclass extends Store {\n createCache(wrapper) {\n return new Cache(wrapper);\n }\n\n instantiateRecord(identifier) {\n const { cache, notifications } = this;\n const { type, id } = identifier;\n\n // create a TrackedObject with our attributes, id and type\n const attrs = cache.peek(identifier).attributes;\n const data = Object.assign({}, attrs, { type, id });\n const record = new TrackedObject(data);\n\n // update the TrackedObject whenever attributes change\n const token = notifications.subscribe(identifier, (_, change) => {\n if (change === 'attributes') {\n Object.assign(record, cache.peek(identifier).attributes);\n }\n });\n\n // setup the ability to teardown the subscription when the\n // record is no longer needed\n record.destroy = () => {\n this.notifications.unsubscribe(token);\n };\n\n return record;\n }\n\n teardownRecord(record: FakeRecord) {\n record.destroy();\n }\n}\n```\n\nFor the full list of APIs available read the code documentation for [*Ember***Data** Cache](https://github.com/emberjs/data/blob/main/ember-data-types/cache/cache.ts)", + "description": "

\n \n

\n\nThis package provides an in-memory [JSON:API](https://jsonapi.org/) document and resource [*Ember***Data** Cache](https://github.com/emberjs/data/blob/main/ember-data-types/cache/cache.ts) implementation.\n\n## Installation\n\nInstall using your javascript package manager of choice. For instance with [pnpm](https://pnpm.io/)\n\n```\npnpm add @ember-data/json-api\n```\n\n## πŸš€ Setup\n\n> **Note** When using [ember-data](https://github.com/emberjs/data/blob/main/packages/-ember-data) the below\n> configuration is handled for you automatically.\n\n```ts\nimport Store from '@ember-data/store';\nimport Cache from '@ember-data/json-api';\n\nexport default class extends Store {\n createCache(wrapper) {\n return new Cache(wrapper);\n }\n}\n```\n\n\n## Usage\n\nUsually you will directly interact with the cache only if implementing a presentation class. Below we\ngive an example of a read-only record (mutations never written back to the cache). More typically cache\ninteractions are something that the `Store` coordinates as part of the `request/response` lifecycle.\n\n```ts\nimport Store, { recordIdentifierFor } from '@ember-data/store';\nimport Cache from '@ember-data/json-api';\nimport { TrackedObject } from 'tracked-built-ins';\n\nclass extends Store {\n createCache(wrapper) {\n return new Cache(wrapper);\n }\n\n instantiateRecord(identifier) {\n const { cache, notifications } = this;\n const { type, id } = identifier;\n\n // create a TrackedObject with our attributes, id and type\n const attrs = cache.peek(identifier).attributes;\n const data = Object.assign({}, attrs, { type, id });\n const record = new TrackedObject(data);\n\n // update the TrackedObject whenever attributes change\n const token = notifications.subscribe(identifier, (_, change) => {\n if (change === 'attributes') {\n Object.assign(record, cache.peek(identifier).attributes);\n }\n });\n\n // setup the ability to teardown the subscription when the\n // record is no longer needed\n record.destroy = () => {\n this.notifications.unsubscribe(token);\n };\n\n return record;\n }\n\n teardownRecord(record: FakeRecord) {\n record.destroy();\n }\n}\n```\n\nFor the full list of APIs available read the code documentation for [*Ember***Data** Cache](https://github.com/emberjs/data/blob/main/ember-data-types/cache/cache.ts)", "itemtype": "main", "parent": null, "publicclasses": [ diff --git a/json-docs/ember-data/4.12.3/modules/ember-data-4.12.3-@ember-data/request.json b/json-docs/ember-data/4.12.3/modules/ember-data-4.12.3-@ember-data/request.json index cf56f948c..7859f5b97 100644 --- a/json-docs/ember-data/4.12.3/modules/ember-data-4.12.3-@ember-data/request.json +++ b/json-docs/ember-data/4.12.3/modules/ember-data-4.12.3-@ember-data/request.json @@ -11,7 +11,7 @@ "tag": "main", "file": "../request/src/-private/types.ts", "line": 202, - "description": "

\n \n

\n\n

⚑️ a simple abstraction over fetch to enable easy management of request/response flows

\n\nThis package provides [*Ember*‍**Data**](https://github.com/emberjs/data/)'s `RequestManager`, a framework agnostic library that can be integrated with any Javascript application to make [fetch](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) happen.\n\n## Installation\n\nInstall using your javascript package manager of choice. For instance with [pnpm](https://pnpm.io/)\n\n```no-highlight\npnpm add @ember-data/request\n```\n\n## πŸš€ Basic Usage\n\nA `RequestManager` provides a request/response flow in which configured handlers are successively given the opportunity to handle, modify, or pass-along a request.\n\nThe RequestManager on its own does not know how to fulfill requests. For this we must register at least one handler. A basic `Fetch` handler is provided that will take the request options provided and execute `fetch`.\n\n```ts\nimport RequestManager from '@ember-data/request';\nimport Fetch from '@ember-data/request/fetch';\nimport { apiUrl } from './config';\n\n// ... create manager and add our Fetch handler\nconst manager = new RequestManager();\nmanager.use([Fetch]);\n\n// ... execute a request\nconst response = await manager.request({\n url: `${apiUrl}/users`\n});\n```\n\n\n## πŸͺœ Architecture\n\nA `RequestManager` receives a request and manages fulfillment via configured handlers. It may be used standalone from the rest of *Ember*‍**Data** and is not specific to any library or framework.\n\nEach handler may choose to fulfill the request using some source of data or to pass the request along to other handlers.\n\nThe same or a separate instance of a `RequestManager` may also be used to fulfill requests issued by [*Ember*‍**Data**{Store}](https://github.com/emberjs/data/tree/main/packages/store)\n\nWhen the same instance is used by both this allows for simple coordination throughout the application. Requests issued by the Store will use the in-memory cache\nand return hydrated responses, requests issued directly to the RequestManager\nwill skip the in-memory cache and return raw responses.\n\n## Usage\n\n```ts\nconst userList = await manager.request({\n url: `/api/v1/users.list`\n});\n\nconst users = userList.content;\n```\n\n
\n Making Requests\n\n`RequestManager` has a single asyncronous method as it's API: `request`\n\n```ts\nclass RequestManager {\n request(req: RequestInfo): Future;\n}\n```\n\n`manager.request()` accepts an object containing the information\nnecessary for the request to be handled successfully.\n\nThese options extend the [options](https://developer.mozilla.org/en-US/docs/Web/API/fetch#parameters) provided to `fetch`, and can accept a [`Request`](https://developer.mozilla.org/en-US/docs/Web/API/Request/Request). All properties accepted by Request options and fetch options are valid.\n\n```ts\ninterface RequestInfo extends FetchOptions {\n op?: string;\n store?: Store;\nurl: string;\n // data that a handler should convert into\n // the query (GET) or body (POST)\n data?: Record;\n// options specifically intended for handlers\n // to utilize to process the request\n options?: Record;\n}\n```\n\n> **note:** providing a `signal` is unnecessary as an `AbortController` is automatically provided if none is present.\n\n
\n
\n Using the Response
\n\n`manager.request` returns a `Future`, which allows access to limited information about the request while it is still pending and fulfills with the final state when the request completes and the response has been read.\n\n```ts\nconst usersFuture = manager.request({\n url: `/api/v1/users.list`\n});\n```\n\nA `Future` is cancellable via `abort`.\n\n```ts\nusersFuture.abort();\n```\n\nHandlers may *optionally* expose a ReadableStream to the `Future` for streaming data; however, when doing so the handler should not resolve until it has fully read the response stream itself.\n\n```ts\ninterface Future extends Promise> {\n abort(): void;\nasync getStream(): ReadableStream | null;\n}\n```\n\nA Future resolves or rejects with a `StructuredDocument`.\n\n```ts\ninterface StructuredDocument {\n request: RequestInfo;\n response: ResponseInfo | null;\n content?: T;\n error?: Error;\n}\n```\n\nThe `RequestInfo` specified by `document.request` is the same as originally provided to `manager.request`. If any handler fulfilled this request using different request info it is not represented here. This contract helps to ensure that `retry` and `caching` are possible since the original arguments are correctly preserved. This also allows handlers to \"fork\" the request or fulfill from multiple sources without the details of fulfillment muddying the original request.\n\nThe `ResponseInfo` is a serializable fulfilled subset of a [Response](https://developer.mozilla.org/en-US/docs/Web/API/Response) if set via `setResponse`. If no response was ever set this will be `null`.\n\n```ts\ninterface ResponseInfo {\n headers?: Record;\n ok?: boolean;\n redirected?: boolean;\n status?: HTTPStatusCode;\n statusText?: string;\n type?: 'basic' | 'cors';\n url?: string;\n}\n```\n\n
\n\n

Handling Requests

\n
\n { request(context, next): Promise | Future; }
\n\nRequests are fulfilled by handlers. A handler receives the request context\nas well as a `next` function with which to pass along a request to the next\nhandler if it so chooses.\n\nA handler may be any object with a `request` method. This allows both stateful and non-stateful\nhandlers to be utilized.\n\nIf a handler calls `next`, it receives a `Future` which resolves to a `StructuredDocument`\nthat it can then compose how it sees fit with its own response.\n\n```ts\n\ntype NextFn

= (req: RequestInfo) => Future

;\n\ninterface Handler {\n async request(context: RequestContext, next: NextFn

): T;\n}\n```\n\n`RequestContext` contains a readonly version of the RequestInfo as well as a few methods for building up the `StructuredDocument` and `Future` that will be part of the response.\n\n```ts\ninterface RequestContext {\n readonly request: RequestInfo;\nsetStream(stream: ReadableStream | Promise): void;\n setResponse(response: Response | ResponseInfo): void;\n}\n```\n\nA basic `fetch` handler with support for streaming content updates while\nthe download is still underway might look like the following, where we use\n[`response.clone()`](https://developer.mozilla.org/en-US/docs/Web/API/Response/clone) to `tee` the `ReadableStream` into two streams.\n\nA more efficient handler might read from the response stream, building up the\nresponse content before passing along the chunk downstream.\n\n```ts\nconst FetchHandler = {\n async request(context) {\n const response = await fetch(context.request);\n context.setResponse(reponse);\n context.setStream(response.clone().body);\n return response.json();\n }\n}\n```\n\nRequest handlers are registered by configuring the manager via `use`\n\n```ts\nmanager.use([Handler1, Handler2])\n```\n\nHandlers will be invoked in the order they are registered (\"fifo\", first-in first-out), and may only be registered up until the first request is made. It is recommended but not required to register all handlers at one time in order to ensure explicitly visible handler ordering.\n\n

\n\n\n
\n Error Handling
\nEach handler in the chain can catch errors from upstream and choose to\n either handle the error, re-throw the error, or throw a new error.\n```ts\n const MAX_RETRIES = 5;\nconst Handler = {\n async request(context, next) {\n let attempts = 0;\n while (attempts < MAX_RETRIES) {\n attempts++;\n try {\n const response = await next(context.request);\n return response;\n } catch (e) {\n if (isTimeoutError(e) && attempts < MAX_RETRIES) {\n // retry request\n continue;\n }\n // rethrow if it is not a timeout error\n throw e;\n }\n }\n }\n }\n ```\n
\n\n
\n Handling Abort
\nAborting a request will reject the current handler in the chain. However,\n every handler can potentially catch this error. If your handler needs to\n separate AbortError from other Error types, it is recommended to check\n `context.request.signal.aborted` (or if a custom controller was supplied `controller.signal.aborted`).\nIn this manner it is possible for a request to recover from an abort and\n still proceed; however, as a best practice this should be used for necessary\n cleanup only and the original AbortError rethrown if the abort signal comes\n from the root controller.\n\n*AbortControllers are Always Present and Always Entangled**\nIf the initial request does not supply an [AbortController](https://developer.mozilla.org/en-US/docs/Web/API/AbortController), one will be generated.\nThe [signal](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) for this controller is automatically added to the request passed into the first handler.\nEach handler has the option to supply a new controller to the request when calling `next`. If a new controller is provided it will be automatically\n entangled with the root controller. If the root controller aborts, so will\n any entangled controllers.\nIf an entangled controller aborts, the root controller will not abort. This\n allows for advanced request-flow scenarios to abort subsections of the request tree without aborting the entire request.\n\n
\n\n\n
\n Stream Currying
\n\n`RequestManager.request` and `next` differ from `fetch` in one **crucial detail** in that the outer Promise resolves only once the response stream has been processed.\n\nFor context, it helps to understand a few of the use-cases that RequestManager\nis intended to allow.\n\n- to manage and return streaming content (such as video files)\n- to fulfill a request from multiple sources or by splitting one request into multiple requests\n - for instance one API call for a user and another for the user's friends\n - or e.g. fulfilling part of the request from one source (one API, in-memory, localStorage, IndexedDB\n etc.) and the rest from another source (a different API, a WebWorker, etc.)\n- to coalesce multiple requests\n- to decorate a request with additional info\n - e.g. an Auth handler that ensures the correct tokens or headers or cookies are attached.\n\n\n`await fetch()` resolves at the moment headers are received. This allows for the body of the request to be processed as a stream by application\ncode *while chunks are still being received by the browser*.\n\nWhen an app chooses to `await response.json()` what occurs is the browser reads the stream to completion and then returns the result. Additionally, this stream may only be read **once**.\n\nThe `RequestManager` preserves this ability to subscribe to and utilize the stream by either the application or the handler – thereby delivering the full power and flexibility of native APIs – without restricting developers in ways that lead to complicated workarounds.\n\nEach handler may call `setStream` only once, but may do so *at any time* until the promise that the handler returns has resolved. The associated promise returned by calling `future.getStream` will resolve with the stream set by `setStream` if that method is called, or `null` if that method\nhas not been called by the time that the handler's request method has resolved.\n\nHandlers that do not create a stream of their own, but which call `next`, should defensively pipe the stream forward. While this is not required (see automatic currying below) it is better to do so in most cases as otherwise the stream may not become available to downstream handlers or the application until the upstream handler has fully read it.\n\n```ts\ncontext.setStream(future.getStream());\n```\n\nHandlers that either call `next` multiple times or otherwise have reason to create multiple fetch requests should either choose to return no stream, meaningfully combine the streams, or select a single prioritized stream.\n\nOf course, any handler may choose to read and handle the stream, and return either no stream or a different stream in the process.\n\n
\n\n
\n Automatic Currying of Stream and Response
\n\nIn order to simplify the common case for handlers which decorate a request, if `next` is called only a single time and `setResponse` was never called by the handler, the response set by the next handler in the chain will be applied to that handler's outcome. For instance, this makes the following pattern possible `return (await next()).content;`.\n\nSimilarly, if `next` is called only a single time and neither `setStream` nor `getStream` was called, we automatically curry the stream from the future returned by `next` onto the future returned by the handler.\n\nFinally, if the return value of a handler is a `Future`, we curry `content` and `errors` as well, thus enabling the simplest form `return next()`.\n\nIn the case of the `Future` being returned, `Stream` proxying is automatic and immediate and does not wait for the `Future` to resolve.\n\n
\n\n### Using as a Service\n\nMost applications will desire to have a single `RequestManager` instance, which can be achieved using module-state patterns for singletons, or for [Ember](https://emberjs.com) applications by exporting the manager as a [service](https://guides.emberjs.com/release/services/).\n\nservices/request.ts*\n```ts\nimport RequestManager from '@ember-data/request';\nimport Fetch from '@ember-data/request/fetch';\nimport Auth from 'ember-simple-auth/ember-data-handler';\n\nexport default class extends RequestManager {\n constructor(createArgs) {\n super(createArgs);\n this.use([Auth, Fetch]);\n }\n}\n```\n\n### Using with `@ember-data/store`\n\nTo have a request service unique to a Store:\n\n```ts\nimport Store, { CacheHandler } from '@ember-data/store';\nimport RequestManager from '@ember-data/request';\nimport Fetch from '@ember-data/request/fetch';\n\nclass extends Store {\n requestManager = new RequestManager();\nconstructor(args) {\n super(args);\n this.requestManager.use([Fetch]);\n this.requestManager.useCache(CacheHandler);\n }\n}\n```\n\n### Using with `ember-data`\n\nIf using the package [ember-data](https://github.com/emberjs/data/tree/main/packages/-ember-data), the following configuration will automatically be done in order to preserve the legacy [Adapter](https://github.com/emberjs/data/tree/main/packages/adapter) and [Serializer](https://github.com/emberjs/data/tree/main/packages/serializer) behavior. Additional handlers or a service injection like the above would need to be done by the consuming application in order to make broader use of `RequestManager`.\n\n```ts\nimport Store, { CacheHandler } from '@ember-data/store';\nimport RequestManager from '@ember-data/request';\nimport { LegacyNetworkHandler } from '@ember-data/legacy-compat';\n\nexport default class extends Store {\n requestManager = new RequestManager();\nconstructor(args) {\n super(args);\n this.requestManager.use([LegacyNetworkHandler]);\n this.requestManager.useCache(CacheHandler);\n }\n}\n```\n\nBecause the application's store service (if present) will override the store supplied by `ember-data`, all that is required to define your own ordering and handlers is to supply a store service extending from `@ember-data/store` and configure as shown above.\n\nFor usage of the store's `requestManager` via `store.request()` see the [Store](https://api.emberjs.com/ember-data/release/modules/@ember-data%2Fstore) documentation.", + "description": "

\n \n

\n\n

⚑️ a simple abstraction over fetch to enable easy management of request/response flows

\n\nThis package provides [*Ember*‍**Data**](https://github.com/emberjs/data/)'s `RequestManager`, a framework agnostic library that can be integrated with any Javascript application to make [fetch](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) happen.\n\n## Installation\n\nInstall using your javascript package manager of choice. For instance with [pnpm](https://pnpm.io/)\n\n```\npnpm add @ember-data/request\n```\n\n## πŸš€ Basic Usage\n\nA `RequestManager` provides a request/response flow in which configured handlers are successively given the opportunity to handle, modify, or pass-along a request.\n\nThe RequestManager on its own does not know how to fulfill requests. For this we must register at least one handler. A basic `Fetch` handler is provided that will take the request options provided and execute `fetch`.\n\n```ts\nimport RequestManager from '@ember-data/request';\nimport Fetch from '@ember-data/request/fetch';\nimport { apiUrl } from './config';\n\n// ... create manager and add our Fetch handler\nconst manager = new RequestManager();\nmanager.use([Fetch]);\n\n// ... execute a request\nconst response = await manager.request({\n url: `${apiUrl}/users`\n});\n```\n\n\n## πŸͺœ Architecture\n\nA `RequestManager` receives a request and manages fulfillment via configured handlers. It may be used standalone from the rest of *Ember*‍**Data** and is not specific to any library or framework.\n\nEach handler may choose to fulfill the request using some source of data or to pass the request along to other handlers.\n\nThe same or a separate instance of a `RequestManager` may also be used to fulfill requests issued by [*Ember*‍**Data**{Store}](https://github.com/emberjs/data/tree/main/packages/store)\n\nWhen the same instance is used by both this allows for simple coordination throughout the application. Requests issued by the Store will use the in-memory cache\nand return hydrated responses, requests issued directly to the RequestManager\nwill skip the in-memory cache and return raw responses.\n\n## Usage\n\n```ts\nconst userList = await manager.request({\n url: `/api/v1/users.list`\n});\n\nconst users = userList.content;\n```\n\n
\n Making Requests\n\n`RequestManager` has a single asyncronous method as it's API: `request`\n\n```ts\nclass RequestManager {\n request(req: RequestInfo): Future;\n}\n```\n\n`manager.request()` accepts an object containing the information\nnecessary for the request to be handled successfully.\n\nThese options extend the [options](https://developer.mozilla.org/en-US/docs/Web/API/fetch#parameters) provided to `fetch`, and can accept a [`Request`](https://developer.mozilla.org/en-US/docs/Web/API/Request/Request). All properties accepted by Request options and fetch options are valid.\n\n```ts\ninterface RequestInfo extends FetchOptions {\n op?: string;\n store?: Store;\nurl: string;\n // data that a handler should convert into\n // the query (GET) or body (POST)\n data?: Record;\n// options specifically intended for handlers\n // to utilize to process the request\n options?: Record;\n}\n```\n\n> **note:** providing a `signal` is unnecessary as an `AbortController` is automatically provided if none is present.\n\n
\n
\n Using the Response
\n\n`manager.request` returns a `Future`, which allows access to limited information about the request while it is still pending and fulfills with the final state when the request completes and the response has been read.\n\n```ts\nconst usersFuture = manager.request({\n url: `/api/v1/users.list`\n});\n```\n\nA `Future` is cancellable via `abort`.\n\n```ts\nusersFuture.abort();\n```\n\nHandlers may *optionally* expose a ReadableStream to the `Future` for streaming data; however, when doing so the handler should not resolve until it has fully read the response stream itself.\n\n```ts\ninterface Future extends Promise> {\n abort(): void;\nasync getStream(): ReadableStream | null;\n}\n```\n\nA Future resolves or rejects with a `StructuredDocument`.\n\n```ts\ninterface StructuredDocument {\n request: RequestInfo;\n response: ResponseInfo | null;\n content?: T;\n error?: Error;\n}\n```\n\nThe `RequestInfo` specified by `document.request` is the same as originally provided to `manager.request`. If any handler fulfilled this request using different request info it is not represented here. This contract helps to ensure that `retry` and `caching` are possible since the original arguments are correctly preserved. This also allows handlers to \"fork\" the request or fulfill from multiple sources without the details of fulfillment muddying the original request.\n\nThe `ResponseInfo` is a serializable fulfilled subset of a [Response](https://developer.mozilla.org/en-US/docs/Web/API/Response) if set via `setResponse`. If no response was ever set this will be `null`.\n\n```ts\ninterface ResponseInfo {\n headers?: Record;\n ok?: boolean;\n redirected?: boolean;\n status?: HTTPStatusCode;\n statusText?: string;\n type?: 'basic' | 'cors';\n url?: string;\n}\n```\n\n
\n\n

Handling Requests

\n
\n { request(context, next): Promise | Future; }
\n\nRequests are fulfilled by handlers. A handler receives the request context\nas well as a `next` function with which to pass along a request to the next\nhandler if it so chooses.\n\nA handler may be any object with a `request` method. This allows both stateful and non-stateful\nhandlers to be utilized.\n\nIf a handler calls `next`, it receives a `Future` which resolves to a `StructuredDocument`\nthat it can then compose how it sees fit with its own response.\n\n```ts\n\ntype NextFn

= (req: RequestInfo) => Future

;\n\ninterface Handler {\n async request(context: RequestContext, next: NextFn

): T;\n}\n```\n\n`RequestContext` contains a readonly version of the RequestInfo as well as a few methods for building up the `StructuredDocument` and `Future` that will be part of the response.\n\n```ts\ninterface RequestContext {\n readonly request: RequestInfo;\nsetStream(stream: ReadableStream | Promise): void;\n setResponse(response: Response | ResponseInfo): void;\n}\n```\n\nA basic `fetch` handler with support for streaming content updates while\nthe download is still underway might look like the following, where we use\n[`response.clone()`](https://developer.mozilla.org/en-US/docs/Web/API/Response/clone) to `tee` the `ReadableStream` into two streams.\n\nA more efficient handler might read from the response stream, building up the\nresponse content before passing along the chunk downstream.\n\n```ts\nconst FetchHandler = {\n async request(context) {\n const response = await fetch(context.request);\n context.setResponse(reponse);\n context.setStream(response.clone().body);\n return response.json();\n }\n}\n```\n\nRequest handlers are registered by configuring the manager via `use`\n\n```ts\nmanager.use([Handler1, Handler2])\n```\n\nHandlers will be invoked in the order they are registered (\"fifo\", first-in first-out), and may only be registered up until the first request is made. It is recommended but not required to register all handlers at one time in order to ensure explicitly visible handler ordering.\n\n

\n\n\n
\n Error Handling
\nEach handler in the chain can catch errors from upstream and choose to\n either handle the error, re-throw the error, or throw a new error.\n```ts\n const MAX_RETRIES = 5;\nconst Handler = {\n async request(context, next) {\n let attempts = 0;\n while (attempts < MAX_RETRIES) {\n attempts++;\n try {\n const response = await next(context.request);\n return response;\n } catch (e) {\n if (isTimeoutError(e) && attempts < MAX_RETRIES) {\n // retry request\n continue;\n }\n // rethrow if it is not a timeout error\n throw e;\n }\n }\n }\n }\n ```\n
\n\n
\n Handling Abort
\nAborting a request will reject the current handler in the chain. However,\n every handler can potentially catch this error. If your handler needs to\n separate AbortError from other Error types, it is recommended to check\n `context.request.signal.aborted` (or if a custom controller was supplied `controller.signal.aborted`).\nIn this manner it is possible for a request to recover from an abort and\n still proceed; however, as a best practice this should be used for necessary\n cleanup only and the original AbortError rethrown if the abort signal comes\n from the root controller.\n\n*AbortControllers are Always Present and Always Entangled**\nIf the initial request does not supply an [AbortController](https://developer.mozilla.org/en-US/docs/Web/API/AbortController), one will be generated.\nThe [signal](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) for this controller is automatically added to the request passed into the first handler.\nEach handler has the option to supply a new controller to the request when calling `next`. If a new controller is provided it will be automatically\n entangled with the root controller. If the root controller aborts, so will\n any entangled controllers.\nIf an entangled controller aborts, the root controller will not abort. This\n allows for advanced request-flow scenarios to abort subsections of the request tree without aborting the entire request.\n\n
\n\n\n
\n Stream Currying
\n\n`RequestManager.request` and `next` differ from `fetch` in one **crucial detail** in that the outer Promise resolves only once the response stream has been processed.\n\nFor context, it helps to understand a few of the use-cases that RequestManager\nis intended to allow.\n\n- to manage and return streaming content (such as video files)\n- to fulfill a request from multiple sources or by splitting one request into multiple requests\n - for instance one API call for a user and another for the user's friends\n - or e.g. fulfilling part of the request from one source (one API, in-memory, localStorage, IndexedDB\n etc.) and the rest from another source (a different API, a WebWorker, etc.)\n- to coalesce multiple requests\n- to decorate a request with additional info\n - e.g. an Auth handler that ensures the correct tokens or headers or cookies are attached.\n\n\n`await fetch()` resolves at the moment headers are received. This allows for the body of the request to be processed as a stream by application\ncode *while chunks are still being received by the browser*.\n\nWhen an app chooses to `await response.json()` what occurs is the browser reads the stream to completion and then returns the result. Additionally, this stream may only be read **once**.\n\nThe `RequestManager` preserves this ability to subscribe to and utilize the stream by either the application or the handler – thereby delivering the full power and flexibility of native APIs – without restricting developers in ways that lead to complicated workarounds.\n\nEach handler may call `setStream` only once, but may do so *at any time* until the promise that the handler returns has resolved. The associated promise returned by calling `future.getStream` will resolve with the stream set by `setStream` if that method is called, or `null` if that method\nhas not been called by the time that the handler's request method has resolved.\n\nHandlers that do not create a stream of their own, but which call `next`, should defensively pipe the stream forward. While this is not required (see automatic currying below) it is better to do so in most cases as otherwise the stream may not become available to downstream handlers or the application until the upstream handler has fully read it.\n\n```ts\ncontext.setStream(future.getStream());\n```\n\nHandlers that either call `next` multiple times or otherwise have reason to create multiple fetch requests should either choose to return no stream, meaningfully combine the streams, or select a single prioritized stream.\n\nOf course, any handler may choose to read and handle the stream, and return either no stream or a different stream in the process.\n\n
\n\n
\n Automatic Currying of Stream and Response
\n\nIn order to simplify the common case for handlers which decorate a request, if `next` is called only a single time and `setResponse` was never called by the handler, the response set by the next handler in the chain will be applied to that handler's outcome. For instance, this makes the following pattern possible `return (await next()).content;`.\n\nSimilarly, if `next` is called only a single time and neither `setStream` nor `getStream` was called, we automatically curry the stream from the future returned by `next` onto the future returned by the handler.\n\nFinally, if the return value of a handler is a `Future`, we curry `content` and `errors` as well, thus enabling the simplest form `return next()`.\n\nIn the case of the `Future` being returned, `Stream` proxying is automatic and immediate and does not wait for the `Future` to resolve.\n\n
\n\n### Using as a Service\n\nMost applications will desire to have a single `RequestManager` instance, which can be achieved using module-state patterns for singletons, or for [Ember](https://emberjs.com) applications by exporting the manager as a [service](https://guides.emberjs.com/release/services/).\n\nservices/request.ts*\n```ts\nimport RequestManager from '@ember-data/request';\nimport Fetch from '@ember-data/request/fetch';\nimport Auth from 'ember-simple-auth/ember-data-handler';\n\nexport default class extends RequestManager {\n constructor(createArgs) {\n super(createArgs);\n this.use([Auth, Fetch]);\n }\n}\n```\n\n### Using with `@ember-data/store`\n\nTo have a request service unique to a Store:\n\n```ts\nimport Store, { CacheHandler } from '@ember-data/store';\nimport RequestManager from '@ember-data/request';\nimport Fetch from '@ember-data/request/fetch';\n\nclass extends Store {\n requestManager = new RequestManager();\nconstructor(args) {\n super(args);\n this.requestManager.use([Fetch]);\n this.requestManager.useCache(CacheHandler);\n }\n}\n```\n\n### Using with `ember-data`\n\nIf using the package [ember-data](https://github.com/emberjs/data/tree/main/packages/-ember-data), the following configuration will automatically be done in order to preserve the legacy [Adapter](https://github.com/emberjs/data/tree/main/packages/adapter) and [Serializer](https://github.com/emberjs/data/tree/main/packages/serializer) behavior. Additional handlers or a service injection like the above would need to be done by the consuming application in order to make broader use of `RequestManager`.\n\n```ts\nimport Store, { CacheHandler } from '@ember-data/store';\nimport RequestManager from '@ember-data/request';\nimport { LegacyNetworkHandler } from '@ember-data/legacy-compat';\n\nexport default class extends Store {\n requestManager = new RequestManager();\nconstructor(args) {\n super(args);\n this.requestManager.use([LegacyNetworkHandler]);\n this.requestManager.useCache(CacheHandler);\n }\n}\n```\n\nBecause the application's store service (if present) will override the store supplied by `ember-data`, all that is required to define your own ordering and handlers is to supply a store service extending from `@ember-data/store` and configure as shown above.\n\nFor usage of the store's `requestManager` via `store.request()` see the [Store](https://api.emberjs.com/ember-data/release/modules/@ember-data%2Fstore) documentation.", "itemtype": "main", "parent": null, "publicclasses": [ diff --git a/json-docs/ember-data/4.12.3/modules/ember-data-4.12.3-ember-data-overview.json b/json-docs/ember-data/4.12.3/modules/ember-data-4.12.3-ember-data-overview.json index 463edd48c..78779ef35 100644 --- a/json-docs/ember-data/4.12.3/modules/ember-data-4.12.3-ember-data-overview.json +++ b/json-docs/ember-data/4.12.3/modules/ember-data-4.12.3-ember-data-overview.json @@ -11,7 +11,7 @@ "tag": "main", "file": "../-ember-data/addon/index.js", "line": 1, - "description": "

\n \n

\n\n

The lightweight reactive data library for JavaScript applications

\n\n---\n\nWrangle your application's data management with scalable patterns for developer productivity.\n\n- ⚑️ Committed to Best-In-Class Performance\n- 🌲 Focused on being as svelte as possible\n- πŸš€ SSR Ready\n- πŸ”œ Typescript Support\n- 🐹 Built with β™₯️ by [Ember](https://emberjs.com)\n- βš›οΈ Supports any API: `GraphQL` `JSON:API` `REST` `tRPC` ...bespoke or a mix\n\n### πŸ“– On This Page\n\n- [Overview](./#overview)\n - [Architecture](#πŸͺœ-architecture)\n - [Basic Installation](#basic-installation)\n - [Advanced Installation](#advanced-installation)\n- [Configuration](#configuration)\n - [Deprecation Stripping](#deprecation-stripping)\n - [randomUUID polyfill](#randomuuid-polyfill)\n - [Removing inspector support in production](#removing-inspector-support-in-production)\n - [Debugging](#debugging)\n\n\n# Overview\n\n*Ember*‍**Data** is a lightweight reactive data library for JavaScript applications that provides composable primitives for ordering query/mutation/peek flows, managing network and cache, and reducing data for presentation.\n\n## πŸͺœ Architecture\n\nThe core of *Ember*‍**Data** is the `Store`, which coordinates interaction between your application, the `Cache`, and sources of data (such as your `API` or a local persistence layer).\nOptionally, the Store can be configured to hydrate the response data into rich presentation classes.\n\n*Ember*‍**Data** is both resource centric and document centric in it's approach to caching, requesting and presenting data. Your application's configuration and usage drives which is important and when.\n\nThe `Store` is a **coordinator**. When using a `Store` you configure what cache to use, how cache data should be presented to the UI, and where it should look for requested data when it is not available in the cache.\n\nThis coordination is handled opaquely to the nature of the requests issued and the format of the data being handled. This approach gives applications broad flexibility to configure *Ember*‍**Data** to best suite their needs. This makes *Ember*‍**Data** a powerful solution for applications regardless of their size and complexity.\n\n*Ember*‍**Data** is designed to scale, with a religious focus on performance and asset-size to keep its footprint small but speedy while still being able to handle large complex APIs in huge data-driven applications with no additional code and no added application complexity. It's goal is to prevent applications from writing code to manage data that is difficult to maintain or reason about.\n\n*Ember*‍**Data**'s power comes not from specific features, data formats, or adherence to specific API specs such as `JSON:API` `trpc` or `GraphQL`, but from solid conventions around requesting and mutating data developed over decades of experience scaling developer productivity.\n\n## Basic Installation\n\nInstall using your javascript package manager of choice. For instance with [pnpm](https://pnpm.io/)\n\n```no-highlight\npnpm add ember-data\n```\n\n`ember-data` is installed by default for new applications generated with `ember-cli`. You can check what version is installed by looking in the `devDependencies` hash of your project's [package.json](https://docs.npmjs.com/cli/v8/configuring-npm/package-json) file.\n\nIf you have generated a new `Ember` application using `ember-cli` but do\nnot wish to use `ember-data`, remove `ember-data` from your project's `package.json` file and run your package manager's install command to update your lockfile.\n\n## Advanced Installation\n\n*Ember*‍**Data** is organized into primitives that compose together via public APIs.\n\n- [@ember-data/store](/ember-data/release/modules/@ember-data%2Fstore) is the core and handles coordination\n- [@ember-data/json-api](/ember-data/release/modules/@ember-data%2Fjson-api) provides a resource cache for JSON:API structured data. It integrates with the store via the hook `createCache`\n- [@ember-data/model](/ember-data/release/modules/@ember-data%2Fmodel) is a presentation layer, it integrates with the store via the hooks `instantiateRecord` and `teardownRecord`.\n- [@ember-data/adapter](/ember-data/release/modules/@ember-data%2Fadapter) provides various network API integrations for APIS built over specific REST or JSON:API conventions.\n- [@ember-data/serializer](/ember-data/release/modules/@ember-data%2Fserializer) pairs with `@ember-data/adapter` to normalize and serialize data to and from an API format into the `JSON:API` format understood by `@ember-data/json-api`.\n- [@ember-data/debug](/ember-data/release/modules/@ember-data%2Fdebug) provides debugging support for the `ember-inspector`.\n- **ember-data** is a \"meta\" package which bundles all of these together for convenience\n\nThe packages interop with each other through well defined public API boundaries. The core\nof the library is the store provided by `@ember-data/store`, while each of the other libraries plugs into the store when installed. Because these packages interop via fully\npublic APIs, other libraries or applications may provide their own implementations. For instance, [ember-m3](https://github.com/hjdivad/ember-m3) is a commonly used presentation and cache implementation suitable for complex resource objects and graphs.\n\n## Configuration\n\n### Deprecation Stripping\n\n*Ember*‍**Data** allows users to opt-in and remove code that exists to support deprecated behaviors.\n\nIf your app has resolved all deprecations present in a given version, you may specify that version as your \"compatibility\" version to remove the code that supported the deprecated behavior from your app.\n\n```ts\nlet app = new EmberApp(defaults, {\n emberData: {\n compatWith: '4.8',\n },\n});\n```\n\n- [Full Documentation](https://api.emberjs.com/ember-data/release/modules/@ember-data%2Fdeprecations)\n\n### randomUUID polyfill\n\n*Ember*‍**Data** uses `UUID V4` by default to generate identifiers for new data created on the client. Identifier generation is configurable, but we also for convenience will polyfill\nthe necessary feature if your browser support or deployment environment demands it. To\nactivate this polyfill:\n\n```ts\nlet app = new EmberApp(defaults, {\n '@embroider/macros': {\n setConfig: {\n '@ember-data/store': {\n polyfillUUID: true\n },\n },\n },\n});\n```\n\n### removing inspector support in production\n\nIf you do not with to ship inspector support in your production application, you can specify\nthat all support for it should be stripped from the build.\n\n```ts\nlet app = new EmberApp(defaults, {\n emberData: {\n includeDataAdapterInProduction: false\n }\n});\n```\n\n- [Full Documentation](https://api.emberjs.com/ember-data/release/modules/@ember-data%2Fdebug)\n\n### Debugging\n\nMany portions of the internals are helpfully instrumented with logging that can be activated\nat build time. This instrumentation is always removed from production builds or any builds\nthat has not explicitly activated it. To activate it set the appropriate flag to `true`.\n\n```ts\n let app = new EmberApp(defaults, {\n emberData: {\n debug: {\n LOG_PAYLOADS: false, // data store received to update cache with\n LOG_OPERATIONS: false, // updates to cache remote state\n LOG_MUTATIONS: false, // updates to cache local state\n LOG_NOTIFICATIONS: false,\n LOG_REQUESTS: false, // log Requests issued via the request manager\n LOG_REQUEST_STATUS: false,\n LOG_IDENTIFIERS: false,\n LOG_GRAPH: false,\n LOG_INSTANCE_CACHE: false,\n }\n }\n });\n ```", + "description": "

\n \n

\n\n

The lightweight reactive data library for JavaScript applications

\n\n---\n\nWrangle your application's data management with scalable patterns for developer productivity.\n\n- ⚑️ Committed to Best-In-Class Performance\n- 🌲 Focused on being as svelte as possible\n- πŸš€ SSR Ready\n- πŸ”œ Typescript Support\n- 🐹 Built with β™₯️ by [Ember](https://emberjs.com)\n- βš›οΈ Supports any API: `GraphQL` `JSON:API` `REST` `tRPC` ...bespoke or a mix\n\n### πŸ“– On This Page\n\n- [Overview](./#overview)\n - [Architecture](#πŸͺœ-architecture)\n - [Basic Installation](#basic-installation)\n - [Advanced Installation](#advanced-installation)\n- [Configuration](#configuration)\n - [Deprecation Stripping](#deprecation-stripping)\n - [randomUUID polyfill](#randomuuid-polyfill)\n - [Removing inspector support in production](#removing-inspector-support-in-production)\n - [Debugging](#debugging)\n\n\n# Overview\n\n*Ember*‍**Data** is a lightweight reactive data library for JavaScript applications that provides composable primitives for ordering query/mutation/peek flows, managing network and cache, and reducing data for presentation.\n\n## πŸͺœ Architecture\n\nThe core of *Ember*‍**Data** is the `Store`, which coordinates interaction between your application, the `Cache`, and sources of data (such as your `API` or a local persistence layer).\nOptionally, the Store can be configured to hydrate the response data into rich presentation classes.\n\n*Ember*‍**Data** is both resource centric and document centric in it's approach to caching, requesting and presenting data. Your application's configuration and usage drives which is important and when.\n\nThe `Store` is a **coordinator**. When using a `Store` you configure what cache to use, how cache data should be presented to the UI, and where it should look for requested data when it is not available in the cache.\n\nThis coordination is handled opaquely to the nature of the requests issued and the format of the data being handled. This approach gives applications broad flexibility to configure *Ember*‍**Data** to best suite their needs. This makes *Ember*‍**Data** a powerful solution for applications regardless of their size and complexity.\n\n*Ember*‍**Data** is designed to scale, with a religious focus on performance and asset-size to keep its footprint small but speedy while still being able to handle large complex APIs in huge data-driven applications with no additional code and no added application complexity. It's goal is to prevent applications from writing code to manage data that is difficult to maintain or reason about.\n\n*Ember*‍**Data**'s power comes not from specific features, data formats, or adherence to specific API specs such as `JSON:API` `trpc` or `GraphQL`, but from solid conventions around requesting and mutating data developed over decades of experience scaling developer productivity.\n\n## Basic Installation\n\nInstall using your javascript package manager of choice. For instance with [pnpm](https://pnpm.io/)\n\n```\npnpm add ember-data\n```\n\n`ember-data` is installed by default for new applications generated with `ember-cli`. You can check what version is installed by looking in the `devDependencies` hash of your project's [package.json](https://docs.npmjs.com/cli/v8/configuring-npm/package-json) file.\n\nIf you have generated a new `Ember` application using `ember-cli` but do\nnot wish to use `ember-data`, remove `ember-data` from your project's `package.json` file and run your package manager's install command to update your lockfile.\n\n## Advanced Installation\n\n*Ember*‍**Data** is organized into primitives that compose together via public APIs.\n\n- [@ember-data/store](/ember-data/release/modules/@ember-data%2Fstore) is the core and handles coordination\n- [@ember-data/json-api](/ember-data/release/modules/@ember-data%2Fjson-api) provides a resource cache for JSON:API structured data. It integrates with the store via the hook `createCache`\n- [@ember-data/model](/ember-data/release/modules/@ember-data%2Fmodel) is a presentation layer, it integrates with the store via the hooks `instantiateRecord` and `teardownRecord`.\n- [@ember-data/adapter](/ember-data/release/modules/@ember-data%2Fadapter) provides various network API integrations for APIS built over specific REST or JSON:API conventions.\n- [@ember-data/serializer](/ember-data/release/modules/@ember-data%2Fserializer) pairs with `@ember-data/adapter` to normalize and serialize data to and from an API format into the `JSON:API` format understood by `@ember-data/json-api`.\n- [@ember-data/debug](/ember-data/release/modules/@ember-data%2Fdebug) provides debugging support for the `ember-inspector`.\n- **ember-data** is a \"meta\" package which bundles all of these together for convenience\n\nThe packages interop with each other through well defined public API boundaries. The core\nof the library is the store provided by `@ember-data/store`, while each of the other libraries plugs into the store when installed. Because these packages interop via fully\npublic APIs, other libraries or applications may provide their own implementations. For instance, [ember-m3](https://github.com/hjdivad/ember-m3) is a commonly used presentation and cache implementation suitable for complex resource objects and graphs.\n\n## Configuration\n\n### Deprecation Stripping\n\n*Ember*‍**Data** allows users to opt-in and remove code that exists to support deprecated behaviors.\n\nIf your app has resolved all deprecations present in a given version, you may specify that version as your \"compatibility\" version to remove the code that supported the deprecated behavior from your app.\n\n```ts\nlet app = new EmberApp(defaults, {\n emberData: {\n compatWith: '4.8',\n },\n});\n```\n\n- [Full Documentation](https://api.emberjs.com/ember-data/release/modules/@ember-data%2Fdeprecations)\n\n### randomUUID polyfill\n\n*Ember*‍**Data** uses `UUID V4` by default to generate identifiers for new data created on the client. Identifier generation is configurable, but we also for convenience will polyfill\nthe necessary feature if your browser support or deployment environment demands it. To\nactivate this polyfill:\n\n```ts\nlet app = new EmberApp(defaults, {\n '@embroider/macros': {\n setConfig: {\n '@ember-data/store': {\n polyfillUUID: true\n },\n },\n },\n});\n```\n\n### removing inspector support in production\n\nIf you do not with to ship inspector support in your production application, you can specify\nthat all support for it should be stripped from the build.\n\n```ts\nlet app = new EmberApp(defaults, {\n emberData: {\n includeDataAdapterInProduction: false\n }\n});\n```\n\n- [Full Documentation](https://api.emberjs.com/ember-data/release/modules/@ember-data%2Fdebug)\n\n### Debugging\n\nMany portions of the internals are helpfully instrumented with logging that can be activated\nat build time. This instrumentation is always removed from production builds or any builds\nthat has not explicitly activated it. To activate it set the appropriate flag to `true`.\n\n```ts\n let app = new EmberApp(defaults, {\n emberData: {\n debug: {\n LOG_PAYLOADS: false, // data store received to update cache with\n LOG_OPERATIONS: false, // updates to cache remote state\n LOG_MUTATIONS: false, // updates to cache local state\n LOG_NOTIFICATIONS: false,\n LOG_REQUESTS: false, // log Requests issued via the request manager\n LOG_REQUEST_STATUS: false,\n LOG_IDENTIFIERS: false,\n LOG_GRAPH: false,\n LOG_INSTANCE_CACHE: false,\n }\n }\n });\n ```", "itemtype": "main", "parent": null, "publicclasses": [], diff --git a/json-docs/ember-data/4.9.1/modules/ember-data-4.9.1-@ember-data/request.json b/json-docs/ember-data/4.9.1/modules/ember-data-4.9.1-@ember-data/request.json index c2b9f43fb..8eb461364 100644 --- a/json-docs/ember-data/4.9.1/modules/ember-data-4.9.1-@ember-data/request.json +++ b/json-docs/ember-data/4.9.1/modules/ember-data-4.9.1-@ember-data/request.json @@ -11,7 +11,7 @@ "tag": "main", "file": "../packages/request/src/-private/types.ts", "line": 57, - "description": "

\n \n

\n\n

⚑️ a simple abstraction over fetch to enable easy management of request/response flows

\n\nThis package provides [*Ember*‍**Data**](https://github.com/emberjs/data/)'s `RequestManager`, a framework agnostic library that can be integrated with any Javascript application to make [fetch](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) happen.\n\n## Installation\n\nInstall using your javascript package manager of choice. For instance with [pnpm](https://pnpm.io/)\n\n```no-highlight\npnpm add @ember-data/request\n```\n\n## πŸš€ Basic Usage\n\nA `RequestManager` provides a request/response flow in which configured handlers are successively given the opportunity to handle, modify, or pass-along a request.\n\nThe RequestManager on its own does not know how to fulfill requests. For this we must register at least one handler. A basic `Fetch` handler is provided that will take the request options provided and execute `fetch`.\n\n```ts\nimport { RequestManager } from '@ember-data/request';\nimport { Fetch } from '@ember-data/request/fetch';\nimport { apiUrl } from './config';\n\n// ... create manager and add our Fetch handler\nconst manager = new RequestManager();\nmanager.use([Fetch]);\n\n// ... execute a request\nconst response = await manager.request({\n url: `${apiUrl}/users`\n});\n```\n\n\n## πŸͺœ Architecture\n\nA `RequestManager` receives a request and manages fulfillment via configured handlers. It may be used standalone from the rest of *Ember*‍**Data** and is not specific to any library or framework.\n\nEach handler may choose to fulfill the request using some source of data or to pass the request along to other handlers.\n\nThe same or a separate instance of a `RequestManager` may also be used to fulfill requests issued by [*Ember*‍**Data**{Store}](https://github.com/emberjs/data/tree/master/packages/store)\n\nWhen the same instance is used by both this allows for simple coordination throughout the application. Requests issued by the Store will use the in-memory cache\nand return hydrated responses, requests issued directly to the RequestManager\nwill skip the in-memory cache and return raw responses.\n\n## Usage\n\n
\n Making Requests\n\n`RequestManager` has a single asyncronous method as it's API: `request`\n\n```ts\nclass RequestManager {\n async request(req: RequestInfo): Future;\n}\n```\n\n`manager.request` accepts a `RequestInfo`, an object containing the information\nnecessary for the request to be handled successfully.\n\n`RequestInfo` extends the [options](https://developer.mozilla.org/en-US/docs/Web/API/fetch#parameters) provided to `fetch`, and can accept a [`Request`](https://developer.mozilla.org/en-US/docs/Web/API/Request/Request). All properties accepted by Request options and fetch options are valid on `RequestInfo`.\n\n```ts\ninterface RequestInfo extends FetchOptions {\n url: string;\n // data that a handler should convert into\n // the query (GET) or body (POST)\n data?: Record;\n// options specifically intended for handlers\n // to utilize to process the request\n options?: Record;\n}\n```\n\n> **note:** providing a `signal` is unnecessary as an `AbortController` is automatically provided if none is present.\n\n
\n
\n Using the Response
\n\n`manager.request` returns a `Future`, which allows access to limited information about the request while it is still pending and fulfills with the final state when the request completes and the response has been read.\n\nA `Future` is cancellable via `abort`.\n\nHandlers may *optionally* expose a ReadableStream to the `Future` for streaming data; however, when doing so the handler should not resolve until it has fully read the response stream itself.\n\n```ts\ninterface Future extends Promise> {\n abort(): void;\nasync getStream(): ReadableStream | null;\n}\n```\n\nA Future resolves or rejects with a `StructuredDocument`.\n\n```ts\ninterface StructuredDocument {\n request: RequestInfo;\n response: ResponseInfo | null;\n data?: T;\n error?: Error;\n}\n```\n\nThe `RequestInfo` specified by `document.request` is the same as originally provided to `manager.request`. If any handler fulfilled this request using different request info it is not represented here. This contract helps to ensure that `retry` and `caching` are possible since the original arguments are correctly preserved. This also allows handlers to \"fork\" the request or fulfill from multiple sources without the details of fulfillment muddying the original request.\n\nThe `ResponseInfo` is a serializable fulfilled subset of a [Response](https://developer.mozilla.org/en-US/docs/Web/API/Response) if set via `setResponse`. If no response was ever set this will be `null`.\n\n```ts\ninterface ResponseInfo {\n headers?: Record;\n ok?: boolean;\n redirected?: boolean;\n status?: HTTPStatusCode;\n statusText?: string;\n type?: 'basic' | 'cors';\n url?: string;\n}\n```\n\n
\n\n

Handling Requests

\n
\n { request(context, next): Promise | Future; }
\n\nRequests are fulfilled by handlers. A handler receives the request context\nas well as a `next` function with which to pass along a request to the next\nhandler if it so chooses.\n\nA handler may be any object with a `request` method. This allows both stateful and non-stateful\nhandlers to be utilized.\n\nIf a handler calls `next`, it receives a `Future` which resolves to a `StructuredDocument`\nthat it can then compose how it sees fit with its own response.\n\n```ts\n\ntype NextFn

= (req: RequestInfo) => Future

;\n\ninterface Handler {\n async request(context: RequestContext, next: NextFn

): T;\n}\n```\n\n`RequestContext` contains a readonly version of the RequestInfo as well as a few methods for building up the `StructuredDocument` and `Future` that will be part of the response.\n\n```ts\ninterface RequestContext {\n readonly request: RequestInfo;\nsetStream(stream: ReadableStream | Promise): void;\n setResponse(response: Response | ResponseInfo): void;\n}\n```\n\nA basic `fetch` handler with support for streaming content updates while\nthe download is still underway might look like the following, where we use\n[`response.clone()`](https://developer.mozilla.org/en-US/docs/Web/API/Response/clone) to `tee` the `ReadableStream` into two streams.\n\nA more efficient handler might read from the response stream, building up the\nresponse data before passing along the chunk downstream.\n\n```ts\nconst FetchHandler = {\n async request(context) {\n const response = await fetch(context.request);\n context.setResponse(reponse);\n context.setStream(response.clone().body);\n return response.json();\n }\n}\n```\n\nRequest handlers are registered by configuring the manager via `use`\n\n```ts\nmanager.use([Handler1, Handler2])\n```\n\nHandlers will be invoked in the order they are registered (\"fifo\", first-in first-out), and may only be registered up until the first request is made. It is recommended but not required to register all handlers at one time in order to ensure explicitly visible handler ordering.\n\n

\n\n
\n Stream Currying
\n\n`RequestManager.request` and `next` differ from `fetch` in one **crucial detail** in that the outer Promise resolves only once the response stream has been processed.\n\nFor context, it helps to understand a few of the use-cases that RequestManager\nis intended to allow.\n\n- to manage and return streaming content (such as video files)\n- to fulfill a request from multiple sources or by splitting one request into multiple requests\n - for instance one API call for a user and another for the user's friends\n - or e.g. fulfilling part of the request from one source (one API, in-memory, localStorage, IndexedDB\n etc.) and the rest from another source (a different API, a WebWorker, etc.)\n- to coalesce multiple requests\n- to decorate a request with additional info\n - e.g. an Auth handler that ensures the correct tokens or headers or cookies are attached.\n\n`await fetch()` resolves at the moment headers are received. This allows for the body of the request to be processed as a stream by application\ncode *while chunks are still being received by the browser*.\n\nWhen an app chooses to `await response.json()` what occurs is the browser reads the stream to completion and then returns the result. Additionally, this stream may only be read **once**.\n\nThe `RequestManager` preserves this ability to subscribe to and utilize the stream by either the application or the handler – thereby delivering the full power and flexibility of native APIs – without restricting developers in ways that lead to complicated workarounds.\n\nEach handler may call `setStream` only once, but may do so *at any time* until the promise that the handler returns has resolved. The associated promise returned by calling `future.getStream` will resolve with the stream set by `setStream` if that method is called, or `null` if that method\nhas not been called by the time that the handler's request method has resolved.\n\nHandlers that do not create a stream of their own, but which call `next`, should defensively pipe the stream forward. While this is not required (see automatic currying below) it is better to do so in most cases as otherwise the stream may not become available to downstream handlers or the application until the upstream handler has fully read it.\n\n```ts\ncontext.setStream(future.getStream());\n```\n\nHandlers that either call `next` multiple times or otherwise have reason to create multiple fetch requests should either choose to return no stream, meaningfully combine the streams, or select a single prioritized stream.\n\nOf course, any handler may choose to read and handle the stream, and return either no stream or a different stream in the process.\n\n
\n\n
\n Automatic Currying of Stream and Response
\n\nIn order to simplify the common case for handlers which decorate a request, if `next` is called only a single time and `setResponse` was never called by the handler, the response set by the next handler in the chain will be applied to that handler's outcome. For instance, this makes the following pattern possible `return (await next()).data;`.\n\nSimilarly, if `next` is called only a single time and neither `setStream` nor `getStream` was called, we automatically curry the stream from the future returned by `next` onto the future returned by the handler.\n\nFinally, if the return value of a handler is a `Future`, we curry `data` and `errors` as well, thus enabling the simplest form `return next()`.\n\nIn the case of the `Future` being returned, `Stream` proxying is automatic and immediate and does not wait for the `Future` to resolve.\n\n
\n\n### Using as a Service\n\nMost applications will desire to have a single `RequestManager` instance, which can be achieved using module-state patterns for singletons, or for [Ember](https://emberjs.com) applications by exporting the manager as a [service](https://guides.emberjs.com/release/services/).\n\nservices/request.ts*\n```ts\nimport { RequestManager } from '@ember-data/request';\nimport { Fetch } from '@ember-data/request/fetch';\nimport Auth from 'ember-simple-auth/ember-data-handler';\n\nexport default class extends RequestManager {\n constructor(createArgs) {\n super(createArgs);\n this.use([Auth, Fetch]);\n }\n}\n```\n\n### Using with `@ember-data/store`\n\nTo have a request service unique to a Store:\n\n```ts\nimport Store from '@ember-data/store';\nimport { RequestManager } from '@ember-data/request';\nimport { Fetch } from '@ember-data/request/fetch';\n\nclass extends Store {\n requestManager = new RequestManager();\nconstructor(args) {\n super(args);\n this.requestManager.use([Fetch]);\n }\n}\n```\n\n### Using with `ember-data`\n\nIf using the package [ember-data](https://github.com/emberjs/data/tree/master/packages/-ember-data), the following configuration will automatically be done in order to preserve the legacy [Adapter](https://github.com/emberjs/data/tree/master/packages/adapter) and [Serializer](https://github.com/emberjs/data/tree/master/packages/serializer) behavior. Additional handlers or a service injection like the above would need to be done by the consuming application in order to make broader use of `RequestManager`.\n\n```ts\nimport Store from '@ember-data/store';\nimport { RequestManager } from '@ember-data/request';\nimport { LegacyHandler } from '@ember-data/legacy-network-handler';\n\nexport default class extends Store {\n requestManager = new RequestManager();\nconstructor(args) {\n super(args);\n this.requestManager.use([LegacyHandler]);\n }\n}\n```\n\nBecause the application's store service (if present) will override the store supplied by `ember-data`, all that is required to define your own ordering and handlers is to supply a store service extending from `@ember-data/store` and configure as shown above.\n\nFor usage of the store's `requestManager` via `store.request()` see the [Store](https://api.emberjs.com/ember-data/release/modules/@ember-data%2Fstore) documentation.", + "description": "

\n \n

\n\n

⚑️ a simple abstraction over fetch to enable easy management of request/response flows

\n\nThis package provides [*Ember*‍**Data**](https://github.com/emberjs/data/)'s `RequestManager`, a framework agnostic library that can be integrated with any Javascript application to make [fetch](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) happen.\n\n## Installation\n\nInstall using your javascript package manager of choice. For instance with [pnpm](https://pnpm.io/)\n\n```\npnpm add @ember-data/request\n```\n\n## πŸš€ Basic Usage\n\nA `RequestManager` provides a request/response flow in which configured handlers are successively given the opportunity to handle, modify, or pass-along a request.\n\nThe RequestManager on its own does not know how to fulfill requests. For this we must register at least one handler. A basic `Fetch` handler is provided that will take the request options provided and execute `fetch`.\n\n```ts\nimport { RequestManager } from '@ember-data/request';\nimport { Fetch } from '@ember-data/request/fetch';\nimport { apiUrl } from './config';\n\n// ... create manager and add our Fetch handler\nconst manager = new RequestManager();\nmanager.use([Fetch]);\n\n// ... execute a request\nconst response = await manager.request({\n url: `${apiUrl}/users`\n});\n```\n\n\n## πŸͺœ Architecture\n\nA `RequestManager` receives a request and manages fulfillment via configured handlers. It may be used standalone from the rest of *Ember*‍**Data** and is not specific to any library or framework.\n\nEach handler may choose to fulfill the request using some source of data or to pass the request along to other handlers.\n\nThe same or a separate instance of a `RequestManager` may also be used to fulfill requests issued by [*Ember*‍**Data**{Store}](https://github.com/emberjs/data/tree/master/packages/store)\n\nWhen the same instance is used by both this allows for simple coordination throughout the application. Requests issued by the Store will use the in-memory cache\nand return hydrated responses, requests issued directly to the RequestManager\nwill skip the in-memory cache and return raw responses.\n\n## Usage\n\n
\n Making Requests\n\n`RequestManager` has a single asyncronous method as it's API: `request`\n\n```ts\nclass RequestManager {\n async request(req: RequestInfo): Future;\n}\n```\n\n`manager.request` accepts a `RequestInfo`, an object containing the information\nnecessary for the request to be handled successfully.\n\n`RequestInfo` extends the [options](https://developer.mozilla.org/en-US/docs/Web/API/fetch#parameters) provided to `fetch`, and can accept a [`Request`](https://developer.mozilla.org/en-US/docs/Web/API/Request/Request). All properties accepted by Request options and fetch options are valid on `RequestInfo`.\n\n```ts\ninterface RequestInfo extends FetchOptions {\n url: string;\n // data that a handler should convert into\n // the query (GET) or body (POST)\n data?: Record;\n// options specifically intended for handlers\n // to utilize to process the request\n options?: Record;\n}\n```\n\n> **note:** providing a `signal` is unnecessary as an `AbortController` is automatically provided if none is present.\n\n
\n
\n Using the Response
\n\n`manager.request` returns a `Future`, which allows access to limited information about the request while it is still pending and fulfills with the final state when the request completes and the response has been read.\n\nA `Future` is cancellable via `abort`.\n\nHandlers may *optionally* expose a ReadableStream to the `Future` for streaming data; however, when doing so the handler should not resolve until it has fully read the response stream itself.\n\n```ts\ninterface Future extends Promise> {\n abort(): void;\nasync getStream(): ReadableStream | null;\n}\n```\n\nA Future resolves or rejects with a `StructuredDocument`.\n\n```ts\ninterface StructuredDocument {\n request: RequestInfo;\n response: ResponseInfo | null;\n data?: T;\n error?: Error;\n}\n```\n\nThe `RequestInfo` specified by `document.request` is the same as originally provided to `manager.request`. If any handler fulfilled this request using different request info it is not represented here. This contract helps to ensure that `retry` and `caching` are possible since the original arguments are correctly preserved. This also allows handlers to \"fork\" the request or fulfill from multiple sources without the details of fulfillment muddying the original request.\n\nThe `ResponseInfo` is a serializable fulfilled subset of a [Response](https://developer.mozilla.org/en-US/docs/Web/API/Response) if set via `setResponse`. If no response was ever set this will be `null`.\n\n```ts\ninterface ResponseInfo {\n headers?: Record;\n ok?: boolean;\n redirected?: boolean;\n status?: HTTPStatusCode;\n statusText?: string;\n type?: 'basic' | 'cors';\n url?: string;\n}\n```\n\n
\n\n

Handling Requests

\n
\n { request(context, next): Promise | Future; }
\n\nRequests are fulfilled by handlers. A handler receives the request context\nas well as a `next` function with which to pass along a request to the next\nhandler if it so chooses.\n\nA handler may be any object with a `request` method. This allows both stateful and non-stateful\nhandlers to be utilized.\n\nIf a handler calls `next`, it receives a `Future` which resolves to a `StructuredDocument`\nthat it can then compose how it sees fit with its own response.\n\n```ts\n\ntype NextFn

= (req: RequestInfo) => Future

;\n\ninterface Handler {\n async request(context: RequestContext, next: NextFn

): T;\n}\n```\n\n`RequestContext` contains a readonly version of the RequestInfo as well as a few methods for building up the `StructuredDocument` and `Future` that will be part of the response.\n\n```ts\ninterface RequestContext {\n readonly request: RequestInfo;\nsetStream(stream: ReadableStream | Promise): void;\n setResponse(response: Response | ResponseInfo): void;\n}\n```\n\nA basic `fetch` handler with support for streaming content updates while\nthe download is still underway might look like the following, where we use\n[`response.clone()`](https://developer.mozilla.org/en-US/docs/Web/API/Response/clone) to `tee` the `ReadableStream` into two streams.\n\nA more efficient handler might read from the response stream, building up the\nresponse data before passing along the chunk downstream.\n\n```ts\nconst FetchHandler = {\n async request(context) {\n const response = await fetch(context.request);\n context.setResponse(reponse);\n context.setStream(response.clone().body);\n return response.json();\n }\n}\n```\n\nRequest handlers are registered by configuring the manager via `use`\n\n```ts\nmanager.use([Handler1, Handler2])\n```\n\nHandlers will be invoked in the order they are registered (\"fifo\", first-in first-out), and may only be registered up until the first request is made. It is recommended but not required to register all handlers at one time in order to ensure explicitly visible handler ordering.\n\n

\n\n
\n Stream Currying
\n\n`RequestManager.request` and `next` differ from `fetch` in one **crucial detail** in that the outer Promise resolves only once the response stream has been processed.\n\nFor context, it helps to understand a few of the use-cases that RequestManager\nis intended to allow.\n\n- to manage and return streaming content (such as video files)\n- to fulfill a request from multiple sources or by splitting one request into multiple requests\n - for instance one API call for a user and another for the user's friends\n - or e.g. fulfilling part of the request from one source (one API, in-memory, localStorage, IndexedDB\n etc.) and the rest from another source (a different API, a WebWorker, etc.)\n- to coalesce multiple requests\n- to decorate a request with additional info\n - e.g. an Auth handler that ensures the correct tokens or headers or cookies are attached.\n\n`await fetch()` resolves at the moment headers are received. This allows for the body of the request to be processed as a stream by application\ncode *while chunks are still being received by the browser*.\n\nWhen an app chooses to `await response.json()` what occurs is the browser reads the stream to completion and then returns the result. Additionally, this stream may only be read **once**.\n\nThe `RequestManager` preserves this ability to subscribe to and utilize the stream by either the application or the handler – thereby delivering the full power and flexibility of native APIs – without restricting developers in ways that lead to complicated workarounds.\n\nEach handler may call `setStream` only once, but may do so *at any time* until the promise that the handler returns has resolved. The associated promise returned by calling `future.getStream` will resolve with the stream set by `setStream` if that method is called, or `null` if that method\nhas not been called by the time that the handler's request method has resolved.\n\nHandlers that do not create a stream of their own, but which call `next`, should defensively pipe the stream forward. While this is not required (see automatic currying below) it is better to do so in most cases as otherwise the stream may not become available to downstream handlers or the application until the upstream handler has fully read it.\n\n```ts\ncontext.setStream(future.getStream());\n```\n\nHandlers that either call `next` multiple times or otherwise have reason to create multiple fetch requests should either choose to return no stream, meaningfully combine the streams, or select a single prioritized stream.\n\nOf course, any handler may choose to read and handle the stream, and return either no stream or a different stream in the process.\n\n
\n\n
\n Automatic Currying of Stream and Response
\n\nIn order to simplify the common case for handlers which decorate a request, if `next` is called only a single time and `setResponse` was never called by the handler, the response set by the next handler in the chain will be applied to that handler's outcome. For instance, this makes the following pattern possible `return (await next()).data;`.\n\nSimilarly, if `next` is called only a single time and neither `setStream` nor `getStream` was called, we automatically curry the stream from the future returned by `next` onto the future returned by the handler.\n\nFinally, if the return value of a handler is a `Future`, we curry `data` and `errors` as well, thus enabling the simplest form `return next()`.\n\nIn the case of the `Future` being returned, `Stream` proxying is automatic and immediate and does not wait for the `Future` to resolve.\n\n
\n\n### Using as a Service\n\nMost applications will desire to have a single `RequestManager` instance, which can be achieved using module-state patterns for singletons, or for [Ember](https://emberjs.com) applications by exporting the manager as a [service](https://guides.emberjs.com/release/services/).\n\nservices/request.ts*\n```ts\nimport { RequestManager } from '@ember-data/request';\nimport { Fetch } from '@ember-data/request/fetch';\nimport Auth from 'ember-simple-auth/ember-data-handler';\n\nexport default class extends RequestManager {\n constructor(createArgs) {\n super(createArgs);\n this.use([Auth, Fetch]);\n }\n}\n```\n\n### Using with `@ember-data/store`\n\nTo have a request service unique to a Store:\n\n```ts\nimport Store from '@ember-data/store';\nimport { RequestManager } from '@ember-data/request';\nimport { Fetch } from '@ember-data/request/fetch';\n\nclass extends Store {\n requestManager = new RequestManager();\nconstructor(args) {\n super(args);\n this.requestManager.use([Fetch]);\n }\n}\n```\n\n### Using with `ember-data`\n\nIf using the package [ember-data](https://github.com/emberjs/data/tree/master/packages/-ember-data), the following configuration will automatically be done in order to preserve the legacy [Adapter](https://github.com/emberjs/data/tree/master/packages/adapter) and [Serializer](https://github.com/emberjs/data/tree/master/packages/serializer) behavior. Additional handlers or a service injection like the above would need to be done by the consuming application in order to make broader use of `RequestManager`.\n\n```ts\nimport Store from '@ember-data/store';\nimport { RequestManager } from '@ember-data/request';\nimport { LegacyHandler } from '@ember-data/legacy-network-handler';\n\nexport default class extends Store {\n requestManager = new RequestManager();\nconstructor(args) {\n super(args);\n this.requestManager.use([LegacyHandler]);\n }\n}\n```\n\nBecause the application's store service (if present) will override the store supplied by `ember-data`, all that is required to define your own ordering and handlers is to supply a store service extending from `@ember-data/store` and configure as shown above.\n\nFor usage of the store's `requestManager` via `store.request()` see the [Store](https://api.emberjs.com/ember-data/release/modules/@ember-data%2Fstore) documentation.", "itemtype": "main", "parent": null, "publicclasses": [ diff --git a/json-docs/ember-data/4.9.1/modules/ember-data-4.9.1-ember-data-overview.json b/json-docs/ember-data/4.9.1/modules/ember-data-4.9.1-ember-data-overview.json index 20df0c740..ea43d0b1d 100644 --- a/json-docs/ember-data/4.9.1/modules/ember-data-4.9.1-ember-data-overview.json +++ b/json-docs/ember-data/4.9.1/modules/ember-data-4.9.1-ember-data-overview.json @@ -11,7 +11,7 @@ "tag": "main", "file": "../packages/-ember-data/addon/index.js", "line": 1, - "description": "

\n \n

\n\n

The lightweight reactive data library for JavaScript applications

\n\n---\n\nWrangle your application's data management with scalable patterns for developer productivity.\n\n- ⚑️ Committed to Best-In-Class Performance\n- 🌲 Focused on being as svelte as possible\n- πŸš€ SSR Ready\n- πŸ”œ Typescript Support\n- 🐹 Built with β™₯️ by [Ember](https://emberjs.com)\n- βš›οΈ Supports any API: `GraphQL` `JSON:API` `REST` `tRPC` ...bespoke or a mix\n\n### πŸ“– On This Page\n\n- [Overview](./#overview)\n - [Architecture](#πŸͺœ-architecture)\n - [Basic Installation](#basic-installation)\n - [Advanced Installation](#advanced-installation)\n- [Configuration](#configuration)\n - [Deprecation Stripping](#deprecation-stripping)\n - [randomUUID polyfill](#randomuuid-polyfill)\n - [Removing inspector support in production](#removing-inspector-support-in-production)\n - [Debugging](#debugging)\n\n\n# Overview\n\n*Ember*‍**Data** is a lightweight reactive data library for JavaScript applications that provides composable primitives for ordering query/mutation/peek flows, managing network and cache, and reducing data for presentation.\n\n## πŸͺœ Architecture\n\nThe core of *Ember*‍**Data** is the `Store`, which coordinates interaction between your application, the `Cache`, and sources of data (such as your `API` or a local persistence layer).\nOptionally, the Store can be configured to hydrate the response data into rich presentation classes.\n\n*Ember*‍**Data** is both resource centric and document centric in it's approach to caching, requesting and presenting data. Your application's configuration and usage drives which is important and when.\n\nThe `Store` is a **coordinator**. When using a `Store` you configure what cache to use, how cache data should be presented to the UI, and where it should look for requested data when it is not available in the cache.\n\nThis coordination is handled opaquely to the nature of the requests issued and the format of the data being handled. This approach gives applications broad flexibility to configure *Ember*‍**Data** to best suite their needs. This makes *Ember*‍**Data** a powerful solution for applications regardless of their size and complexity.\n\n*Ember*‍**Data** is designed to scale, with a religious focus on performance and asset-size to keep its footprint small but speedy while still being able to handle large complex APIs in huge data-driven applications with no additional code and no added application complexity. It's goal is to prevent applications from writing code to manage data that is difficult to maintain or reason about.\n\n*Ember*‍**Data**'s power comes not from specific features, data formats, or adherence to specific API specs such as `JSON:API` `trpc` or `GraphQL`, but from solid conventions around requesting and mutating data developed over decades of experience scaling developer productivity.\n\n## Basic Installation\n\nInstall using your javascript package manager of choice. For instance with [pnpm](https://pnpm.io/)\n\n```no-highlight\npnpm add ember-data\n```\n\n`ember-data` is installed by default for new applications generated with `ember-cli`. You can check what version is installed by looking in the `devDependencies` hash of your project's [package.json](https://docs.npmjs.com/cli/v8/configuring-npm/package-json) file.\n\nIf you have generated a new `Ember` application using `ember-cli` but do\nnot wish to use `ember-data`, remove `ember-data` from your project's `package.json` file and run your package manager's install command to update your lockfile.\n\n## Advanced Installation\n\n*Ember*‍**Data** is organized into primitives that compose together via public APIs.\n\n- [@ember-data/store](/ember-data/release/modules/@ember-data%2Fstore) is the core and handles coordination\n- [@ember-data/record-data](/ember-data/release/modules/@ember-data%2Frecord-data) is a resource cache for JSON:API structured data. It integrates with the store via the hook `createRecordDataFor`\n- [@ember-data/model](/ember-data/release/modules/@ember-data%2Fmodel) is a presentation layer, it integrates with the store via the hooks `instantiateRecord` and `teardownRecord`.\n- [@ember-data/adapter](/ember-data/release/modules/@ember-data%2Fadapter) provides various network API integrations for APIS built over specific REST or JSON:API conventions.\n- [@ember-data/serializer](/ember-data/release/modules/@ember-data%2Fserializer) pairs with `@ember-data/adapter` to normalize and serialize data to and from an API format into the `JSON:API` format understood by `@ember-data/record-data`.\n- [@ember-data/debug](/ember-data/release/modules/@ember-data%2Fdebug) provides debugging support for the `ember-inspector`.\n- **ember-data** is a \"meta\" package which bundles all of these together for convenience\n\nThe packages interop with each other through well defined public API boundaries. The core\nof the library is the store provided by `@ember-data/store`, while each of the other libraries plugs into the store when installed. Because these packages interop via fully\npublic APIs, other libraries or applications may provide their own implementations. For instance, [ember-m3](https://github.com/hjdivad/ember-m3) is a commonly used presentation and cache implementation suitable for complex resource objects and graphs.\n\n## Configuration\n\n### Deprecation Stripping\n\n*Ember*‍**Data** allows users to opt-in and remove code that exists to support deprecated behaviors.\n\nIf your app has resolved all deprecations present in a given version, you may specify that version as your \"compatibility\" version to remove the code that supported the deprecated behavior from your app.\n\n```ts\nlet app = new EmberApp(defaults, {\n emberData: {\n compatWith: '4.8',\n },\n});\n```\n\n- [Full Documentation](https://api.emberjs.com/ember-data/release/modules/@ember-data%2Fdeprecations)\n\n### randomUUID polyfill\n\n*Ember*‍**Data** uses `UUID V4` by default to generate identifiers for new data created on the client. Identifier generation is configurable, but we also for convenience will polyfill\nthe necessary feature if your browser support or deployment environment demands it. To\nactivate this polyfill:\n\n```ts\nlet app = new EmberApp(defaults, {\n '@embroider/macros': {\n setConfig: {\n '@ember-data/store': {\n polyfillUUID: true\n },\n },\n },\n});\n```\n\n### removing inspector support in production\n\nIf you do not with to ship inspector support in your production application, you can specify\nthat all support for it should be stripped from the build.\n\n```ts\nlet app = new EmberApp(defaults, {\n emberData: {\n includeDataAdapterInProduction: false\n }\n});\n```\n\n- [Full Documentation](https://api.emberjs.com/ember-data/release/modules/@ember-data%2Fdebug)\n\n### Debugging\n\nMany portions of the internals are helpfully instrumented with logging that can be activated\nat build time. This instrumentation is always removed from production builds or any builds\nthat has not explicitly activated it. To activate it set the appropriate flag to `true`.\n\n```ts\n let app = new EmberApp(defaults, {\n emberData: {\n debug: {\n LOG_PAYLOADS: false, // data store received to update cache with\n LOG_OPERATIONS: false, // updates to cache remote state\n LOG_MUTATIONS: false, // updates to cache local state\n LOG_NOTIFICATIONS: false,\n LOG_REQUEST_STATUS: false,\n LOG_IDENTIFIERS: false,\n LOG_GRAPH: false,\n LOG_INSTANCE_CACHE: false,\n }\n }\n });\n ```", + "description": "

\n \n

\n\n

The lightweight reactive data library for JavaScript applications

\n\n---\n\nWrangle your application's data management with scalable patterns for developer productivity.\n\n- ⚑️ Committed to Best-In-Class Performance\n- 🌲 Focused on being as svelte as possible\n- πŸš€ SSR Ready\n- πŸ”œ Typescript Support\n- 🐹 Built with β™₯️ by [Ember](https://emberjs.com)\n- βš›οΈ Supports any API: `GraphQL` `JSON:API` `REST` `tRPC` ...bespoke or a mix\n\n### πŸ“– On This Page\n\n- [Overview](./#overview)\n - [Architecture](#πŸͺœ-architecture)\n - [Basic Installation](#basic-installation)\n - [Advanced Installation](#advanced-installation)\n- [Configuration](#configuration)\n - [Deprecation Stripping](#deprecation-stripping)\n - [randomUUID polyfill](#randomuuid-polyfill)\n - [Removing inspector support in production](#removing-inspector-support-in-production)\n - [Debugging](#debugging)\n\n\n# Overview\n\n*Ember*‍**Data** is a lightweight reactive data library for JavaScript applications that provides composable primitives for ordering query/mutation/peek flows, managing network and cache, and reducing data for presentation.\n\n## πŸͺœ Architecture\n\nThe core of *Ember*‍**Data** is the `Store`, which coordinates interaction between your application, the `Cache`, and sources of data (such as your `API` or a local persistence layer).\nOptionally, the Store can be configured to hydrate the response data into rich presentation classes.\n\n*Ember*‍**Data** is both resource centric and document centric in it's approach to caching, requesting and presenting data. Your application's configuration and usage drives which is important and when.\n\nThe `Store` is a **coordinator**. When using a `Store` you configure what cache to use, how cache data should be presented to the UI, and where it should look for requested data when it is not available in the cache.\n\nThis coordination is handled opaquely to the nature of the requests issued and the format of the data being handled. This approach gives applications broad flexibility to configure *Ember*‍**Data** to best suite their needs. This makes *Ember*‍**Data** a powerful solution for applications regardless of their size and complexity.\n\n*Ember*‍**Data** is designed to scale, with a religious focus on performance and asset-size to keep its footprint small but speedy while still being able to handle large complex APIs in huge data-driven applications with no additional code and no added application complexity. It's goal is to prevent applications from writing code to manage data that is difficult to maintain or reason about.\n\n*Ember*‍**Data**'s power comes not from specific features, data formats, or adherence to specific API specs such as `JSON:API` `trpc` or `GraphQL`, but from solid conventions around requesting and mutating data developed over decades of experience scaling developer productivity.\n\n## Basic Installation\n\nInstall using your javascript package manager of choice. For instance with [pnpm](https://pnpm.io/)\n\n```\npnpm add ember-data\n```\n\n`ember-data` is installed by default for new applications generated with `ember-cli`. You can check what version is installed by looking in the `devDependencies` hash of your project's [package.json](https://docs.npmjs.com/cli/v8/configuring-npm/package-json) file.\n\nIf you have generated a new `Ember` application using `ember-cli` but do\nnot wish to use `ember-data`, remove `ember-data` from your project's `package.json` file and run your package manager's install command to update your lockfile.\n\n## Advanced Installation\n\n*Ember*‍**Data** is organized into primitives that compose together via public APIs.\n\n- [@ember-data/store](/ember-data/release/modules/@ember-data%2Fstore) is the core and handles coordination\n- [@ember-data/record-data](/ember-data/release/modules/@ember-data%2Frecord-data) is a resource cache for JSON:API structured data. It integrates with the store via the hook `createRecordDataFor`\n- [@ember-data/model](/ember-data/release/modules/@ember-data%2Fmodel) is a presentation layer, it integrates with the store via the hooks `instantiateRecord` and `teardownRecord`.\n- [@ember-data/adapter](/ember-data/release/modules/@ember-data%2Fadapter) provides various network API integrations for APIS built over specific REST or JSON:API conventions.\n- [@ember-data/serializer](/ember-data/release/modules/@ember-data%2Fserializer) pairs with `@ember-data/adapter` to normalize and serialize data to and from an API format into the `JSON:API` format understood by `@ember-data/record-data`.\n- [@ember-data/debug](/ember-data/release/modules/@ember-data%2Fdebug) provides debugging support for the `ember-inspector`.\n- **ember-data** is a \"meta\" package which bundles all of these together for convenience\n\nThe packages interop with each other through well defined public API boundaries. The core\nof the library is the store provided by `@ember-data/store`, while each of the other libraries plugs into the store when installed. Because these packages interop via fully\npublic APIs, other libraries or applications may provide their own implementations. For instance, [ember-m3](https://github.com/hjdivad/ember-m3) is a commonly used presentation and cache implementation suitable for complex resource objects and graphs.\n\n## Configuration\n\n### Deprecation Stripping\n\n*Ember*‍**Data** allows users to opt-in and remove code that exists to support deprecated behaviors.\n\nIf your app has resolved all deprecations present in a given version, you may specify that version as your \"compatibility\" version to remove the code that supported the deprecated behavior from your app.\n\n```ts\nlet app = new EmberApp(defaults, {\n emberData: {\n compatWith: '4.8',\n },\n});\n```\n\n- [Full Documentation](https://api.emberjs.com/ember-data/release/modules/@ember-data%2Fdeprecations)\n\n### randomUUID polyfill\n\n*Ember*‍**Data** uses `UUID V4` by default to generate identifiers for new data created on the client. Identifier generation is configurable, but we also for convenience will polyfill\nthe necessary feature if your browser support or deployment environment demands it. To\nactivate this polyfill:\n\n```ts\nlet app = new EmberApp(defaults, {\n '@embroider/macros': {\n setConfig: {\n '@ember-data/store': {\n polyfillUUID: true\n },\n },\n },\n});\n```\n\n### removing inspector support in production\n\nIf you do not with to ship inspector support in your production application, you can specify\nthat all support for it should be stripped from the build.\n\n```ts\nlet app = new EmberApp(defaults, {\n emberData: {\n includeDataAdapterInProduction: false\n }\n});\n```\n\n- [Full Documentation](https://api.emberjs.com/ember-data/release/modules/@ember-data%2Fdebug)\n\n### Debugging\n\nMany portions of the internals are helpfully instrumented with logging that can be activated\nat build time. This instrumentation is always removed from production builds or any builds\nthat has not explicitly activated it. To activate it set the appropriate flag to `true`.\n\n```ts\n let app = new EmberApp(defaults, {\n emberData: {\n debug: {\n LOG_PAYLOADS: false, // data store received to update cache with\n LOG_OPERATIONS: false, // updates to cache remote state\n LOG_MUTATIONS: false, // updates to cache local state\n LOG_NOTIFICATIONS: false,\n LOG_REQUEST_STATUS: false,\n LOG_IDENTIFIERS: false,\n LOG_GRAPH: false,\n LOG_INSTANCE_CACHE: false,\n }\n }\n });\n ```", "itemtype": "main", "parent": null, "publicclasses": [], diff --git a/json-docs/ember-data/5.0.1/modules/ember-data-5.0.1-@ember-data/graph.json b/json-docs/ember-data/5.0.1/modules/ember-data-5.0.1-@ember-data/graph.json index 3a0d0db7c..5ad3ae171 100644 --- a/json-docs/ember-data/5.0.1/modules/ember-data-5.0.1-@ember-data/graph.json +++ b/json-docs/ember-data/5.0.1/modules/ember-data-5.0.1-@ember-data/graph.json @@ -11,7 +11,7 @@ "tag": "main", "file": "../graph/src/-private.ts", "line": 3, - "description": "

\n \n

\n\n

Provides a performance tuned normalized graph for intelligently managing relationships between resources based on identity

\n\nWhile this Graph is abstract, it currently is a private implementation required as a peer-dependency by the [JSON:API Cache Implementation](https://github.com/emberjs/data/tree/main/packages/json-api).\n\nWe intend to make this Graph public API after some additional iteration during the 5.x timeframe, until then all APIs should be considered experimental and unstable, not fit for direct application or 3rd party library usage.\n\n## Installation\n\nInstall using your javascript package manager of choice. For instance with [pnpm](https://pnpm.io/)\n\n```no-highlight\npnpm add @ember-data/graph\n```", + "description": "

\n \n

\n\n

Provides a performance tuned normalized graph for intelligently managing relationships between resources based on identity

\n\nWhile this Graph is abstract, it currently is a private implementation required as a peer-dependency by the [JSON:API Cache Implementation](https://github.com/emberjs/data/tree/main/packages/json-api).\n\nWe intend to make this Graph public API after some additional iteration during the 5.x timeframe, until then all APIs should be considered experimental and unstable, not fit for direct application or 3rd party library usage.\n\n## Installation\n\nInstall using your javascript package manager of choice. For instance with [pnpm](https://pnpm.io/)\n\n```\npnpm add @ember-data/graph\n```", "itemtype": "main", "parent": null, "publicclasses": [], diff --git a/json-docs/ember-data/5.0.1/modules/ember-data-5.0.1-@ember-data/json-api.json b/json-docs/ember-data/5.0.1/modules/ember-data-5.0.1-@ember-data/json-api.json index 5ec02d25e..b8d321b83 100644 --- a/json-docs/ember-data/5.0.1/modules/ember-data-5.0.1-@ember-data/json-api.json +++ b/json-docs/ember-data/5.0.1/modules/ember-data-5.0.1-@ember-data/json-api.json @@ -11,7 +11,7 @@ "tag": "main", "file": "../json-api/src/-private/cache.ts", "line": 84, - "description": "

\n \n

\n\nThis package provides an in-memory [JSON:API](https://jsonapi.org/) document and resource [*Ember***Data** Cache](https://github.com/emberjs/data/blob/main/ember-data-types/cache/cache.ts) implementation.\n\n## Installation\n\nInstall using your javascript package manager of choice. For instance with [pnpm](https://pnpm.io/)\n\n```no-highlight\npnpm add @ember-data/json-api\n```\n\n## πŸš€ Setup\n\n> **Note** When using [ember-data](https://github.com/emberjs/data/blob/main/packages/-ember-data) the below\n> configuration is handled for you automatically.\n\n```ts\nimport Store from '@ember-data/store';\nimport Cache from '@ember-data/json-api';\n\nexport default class extends Store {\n createCache(wrapper) {\n return new Cache(wrapper);\n }\n}\n```\n\n\n## Usage\n\nUsually you will directly interact with the cache only if implementing a presentation class. Below we\ngive an example of a read-only record (mutations never written back to the cache). More typically cache\ninteractions are something that the `Store` coordinates as part of the `request/response` lifecycle.\n\n```ts\nimport Store, { recordIdentifierFor } from '@ember-data/store';\nimport Cache from '@ember-data/json-api';\nimport { TrackedObject } from 'tracked-built-ins';\n\nclass extends Store {\n createCache(wrapper) {\n return new Cache(wrapper);\n }\n\n instantiateRecord(identifier) {\n const { cache, notifications } = this;\n const { type, id } = identifier;\n\n // create a TrackedObject with our attributes, id and type\n const attrs = cache.peek(identifier).attributes;\n const data = Object.assign({}, attrs, { type, id });\n const record = new TrackedObject(data);\n\n // update the TrackedObject whenever attributes change\n const token = notifications.subscribe(identifier, (_, change) => {\n if (change === 'attributes') {\n Object.assign(record, cache.peek(identifier).attributes);\n }\n });\n\n // setup the ability to teardown the subscription when the\n // record is no longer needed\n record.destroy = () => {\n this.notifications.unsubscribe(token);\n };\n\n return record;\n }\n\n teardownRecord(record: FakeRecord) {\n record.destroy();\n }\n}\n```\n\nFor the full list of APIs available read the code documentation for [*Ember***Data** Cache](https://github.com/emberjs/data/blob/main/ember-data-types/cache/cache.ts)", + "description": "

\n \n

\n\nThis package provides an in-memory [JSON:API](https://jsonapi.org/) document and resource [*Ember***Data** Cache](https://github.com/emberjs/data/blob/main/ember-data-types/cache/cache.ts) implementation.\n\n## Installation\n\nInstall using your javascript package manager of choice. For instance with [pnpm](https://pnpm.io/)\n\n```\npnpm add @ember-data/json-api\n```\n\n## πŸš€ Setup\n\n> **Note** When using [ember-data](https://github.com/emberjs/data/blob/main/packages/-ember-data) the below\n> configuration is handled for you automatically.\n\n```ts\nimport Store from '@ember-data/store';\nimport Cache from '@ember-data/json-api';\n\nexport default class extends Store {\n createCache(wrapper) {\n return new Cache(wrapper);\n }\n}\n```\n\n\n## Usage\n\nUsually you will directly interact with the cache only if implementing a presentation class. Below we\ngive an example of a read-only record (mutations never written back to the cache). More typically cache\ninteractions are something that the `Store` coordinates as part of the `request/response` lifecycle.\n\n```ts\nimport Store, { recordIdentifierFor } from '@ember-data/store';\nimport Cache from '@ember-data/json-api';\nimport { TrackedObject } from 'tracked-built-ins';\n\nclass extends Store {\n createCache(wrapper) {\n return new Cache(wrapper);\n }\n\n instantiateRecord(identifier) {\n const { cache, notifications } = this;\n const { type, id } = identifier;\n\n // create a TrackedObject with our attributes, id and type\n const attrs = cache.peek(identifier).attributes;\n const data = Object.assign({}, attrs, { type, id });\n const record = new TrackedObject(data);\n\n // update the TrackedObject whenever attributes change\n const token = notifications.subscribe(identifier, (_, change) => {\n if (change === 'attributes') {\n Object.assign(record, cache.peek(identifier).attributes);\n }\n });\n\n // setup the ability to teardown the subscription when the\n // record is no longer needed\n record.destroy = () => {\n this.notifications.unsubscribe(token);\n };\n\n return record;\n }\n\n teardownRecord(record: FakeRecord) {\n record.destroy();\n }\n}\n```\n\nFor the full list of APIs available read the code documentation for [*Ember***Data** Cache](https://github.com/emberjs/data/blob/main/ember-data-types/cache/cache.ts)", "itemtype": "main", "parent": null, "publicclasses": [ diff --git a/json-docs/ember-data/5.0.1/modules/ember-data-5.0.1-@ember-data/request.json b/json-docs/ember-data/5.0.1/modules/ember-data-5.0.1-@ember-data/request.json index 85fe592ae..fd37def3f 100644 --- a/json-docs/ember-data/5.0.1/modules/ember-data-5.0.1-@ember-data/request.json +++ b/json-docs/ember-data/5.0.1/modules/ember-data-5.0.1-@ember-data/request.json @@ -11,7 +11,7 @@ "tag": "main", "file": "../request/src/-private/types.ts", "line": 202, - "description": "

\n \n

\n\n

⚑️ a simple abstraction over fetch to enable easy management of request/response flows

\n\nThis package provides [*Ember*‍**Data**](https://github.com/emberjs/data/)'s `RequestManager`, a framework agnostic library that can be integrated with any Javascript application to make [fetch](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) happen.\n\n## Installation\n\nInstall using your javascript package manager of choice. For instance with [pnpm](https://pnpm.io/)\n\n```no-highlight\npnpm add @ember-data/request\n```\n\n## πŸš€ Basic Usage\n\nA `RequestManager` provides a request/response flow in which configured handlers are successively given the opportunity to handle, modify, or pass-along a request.\n\nThe RequestManager on its own does not know how to fulfill requests. For this we must register at least one handler. A basic `Fetch` handler is provided that will take the request options provided and execute `fetch`.\n\n```ts\nimport RequestManager from '@ember-data/request';\nimport Fetch from '@ember-data/request/fetch';\nimport { apiUrl } from './config';\n\n// ... create manager and add our Fetch handler\nconst manager = new RequestManager();\nmanager.use([Fetch]);\n\n// ... execute a request\nconst response = await manager.request({\n url: `${apiUrl}/users`\n});\n```\n\n\n## πŸͺœ Architecture\n\nA `RequestManager` receives a request and manages fulfillment via configured handlers. It may be used standalone from the rest of *Ember*‍**Data** and is not specific to any library or framework.\n\nEach handler may choose to fulfill the request using some source of data or to pass the request along to other handlers.\n\nThe same or a separate instance of a `RequestManager` may also be used to fulfill requests issued by [*Ember*‍**Data**{Store}](https://github.com/emberjs/data/tree/main/packages/store)\n\nWhen the same instance is used by both this allows for simple coordination throughout the application. Requests issued by the Store will use the in-memory cache\nand return hydrated responses, requests issued directly to the RequestManager\nwill skip the in-memory cache and return raw responses.\n\n## Usage\n\n```ts\nconst userList = await manager.request({\n url: `/api/v1/users.list`\n});\n\nconst users = userList.content;\n```\n\n
\n Making Requests\n\n`RequestManager` has a single asyncronous method as it's API: `request`\n\n```ts\nclass RequestManager {\n request(req: RequestInfo): Future;\n}\n```\n\n`manager.request()` accepts an object containing the information\nnecessary for the request to be handled successfully.\n\nThese options extend the [options](https://developer.mozilla.org/en-US/docs/Web/API/fetch#parameters) provided to `fetch`, and can accept a [`Request`](https://developer.mozilla.org/en-US/docs/Web/API/Request/Request). All properties accepted by Request options and fetch options are valid.\n\n```ts\ninterface RequestInfo extends FetchOptions {\n op?: string;\n store?: Store;\nurl: string;\n // data that a handler should convert into\n // the query (GET) or body (POST)\n data?: Record;\n// options specifically intended for handlers\n // to utilize to process the request\n options?: Record;\n}\n```\n\n> **note:** providing a `signal` is unnecessary as an `AbortController` is automatically provided if none is present.\n\n
\n
\n Using the Response
\n\n`manager.request` returns a `Future`, which allows access to limited information about the request while it is still pending and fulfills with the final state when the request completes and the response has been read.\n\n```ts\nconst usersFuture = manager.request({\n url: `/api/v1/users.list`\n});\n```\n\nA `Future` is cancellable via `abort`.\n\n```ts\nusersFuture.abort();\n```\n\nHandlers may *optionally* expose a ReadableStream to the `Future` for streaming data; however, when doing so the handler should not resolve until it has fully read the response stream itself.\n\n```ts\ninterface Future extends Promise> {\n abort(): void;\nasync getStream(): ReadableStream | null;\n}\n```\n\nA Future resolves or rejects with a `StructuredDocument`.\n\n```ts\ninterface StructuredDocument {\n request: RequestInfo;\n response: ResponseInfo | null;\n content?: T;\n error?: Error;\n}\n```\n\nThe `RequestInfo` specified by `document.request` is the same as originally provided to `manager.request`. If any handler fulfilled this request using different request info it is not represented here. This contract helps to ensure that `retry` and `caching` are possible since the original arguments are correctly preserved. This also allows handlers to \"fork\" the request or fulfill from multiple sources without the details of fulfillment muddying the original request.\n\nThe `ResponseInfo` is a serializable fulfilled subset of a [Response](https://developer.mozilla.org/en-US/docs/Web/API/Response) if set via `setResponse`. If no response was ever set this will be `null`.\n\n```ts\ninterface ResponseInfo {\n headers?: Record;\n ok?: boolean;\n redirected?: boolean;\n status?: HTTPStatusCode;\n statusText?: string;\n type?: 'basic' | 'cors';\n url?: string;\n}\n```\n\n
\n\n

Handling Requests

\n
\n { request(context, next): Promise | Future; }
\n\nRequests are fulfilled by handlers. A handler receives the request context\nas well as a `next` function with which to pass along a request to the next\nhandler if it so chooses.\n\nA handler may be any object with a `request` method. This allows both stateful and non-stateful\nhandlers to be utilized.\n\nIf a handler calls `next`, it receives a `Future` which resolves to a `StructuredDocument`\nthat it can then compose how it sees fit with its own response.\n\n```ts\n\ntype NextFn

= (req: RequestInfo) => Future

;\n\ninterface Handler {\n async request(context: RequestContext, next: NextFn

): T;\n}\n```\n\n`RequestContext` contains a readonly version of the RequestInfo as well as a few methods for building up the `StructuredDocument` and `Future` that will be part of the response.\n\n```ts\ninterface RequestContext {\n readonly request: RequestInfo;\nsetStream(stream: ReadableStream | Promise): void;\n setResponse(response: Response | ResponseInfo): void;\n}\n```\n\nA basic `fetch` handler with support for streaming content updates while\nthe download is still underway might look like the following, where we use\n[`response.clone()`](https://developer.mozilla.org/en-US/docs/Web/API/Response/clone) to `tee` the `ReadableStream` into two streams.\n\nA more efficient handler might read from the response stream, building up the\nresponse content before passing along the chunk downstream.\n\n```ts\nconst FetchHandler = {\n async request(context) {\n const response = await fetch(context.request);\n context.setResponse(reponse);\n context.setStream(response.clone().body);\n return response.json();\n }\n}\n```\n\nRequest handlers are registered by configuring the manager via `use`\n\n```ts\nmanager.use([Handler1, Handler2])\n```\n\nHandlers will be invoked in the order they are registered (\"fifo\", first-in first-out), and may only be registered up until the first request is made. It is recommended but not required to register all handlers at one time in order to ensure explicitly visible handler ordering.\n\n

\n\n\n
\n Error Handling
\nEach handler in the chain can catch errors from upstream and choose to\n either handle the error, re-throw the error, or throw a new error.\n```ts\n const MAX_RETRIES = 5;\nconst Handler = {\n async request(context, next) {\n let attempts = 0;\n while (attempts < MAX_RETRIES) {\n attempts++;\n try {\n const response = await next(context.request);\n return response;\n } catch (e) {\n if (isTimeoutError(e) && attempts < MAX_RETRIES) {\n // retry request\n continue;\n }\n // rethrow if it is not a timeout error\n throw e;\n }\n }\n }\n }\n ```\n
\n\n
\n Handling Abort
\nAborting a request will reject the current handler in the chain. However,\n every handler can potentially catch this error. If your handler needs to\n separate AbortError from other Error types, it is recommended to check\n `context.request.signal.aborted` (or if a custom controller was supplied `controller.signal.aborted`).\nIn this manner it is possible for a request to recover from an abort and\n still proceed; however, as a best practice this should be used for necessary\n cleanup only and the original AbortError rethrown if the abort signal comes\n from the root controller.\n\n*AbortControllers are Always Present and Always Entangled**\nIf the initial request does not supply an [AbortController](https://developer.mozilla.org/en-US/docs/Web/API/AbortController), one will be generated.\nThe [signal](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) for this controller is automatically added to the request passed into the first handler.\nEach handler has the option to supply a new controller to the request when calling `next`. If a new controller is provided it will be automatically\n entangled with the root controller. If the root controller aborts, so will\n any entangled controllers.\nIf an entangled controller aborts, the root controller will not abort. This\n allows for advanced request-flow scenarios to abort subsections of the request tree without aborting the entire request.\n\n
\n\n\n
\n Stream Currying
\n\n`RequestManager.request` and `next` differ from `fetch` in one **crucial detail** in that the outer Promise resolves only once the response stream has been processed.\n\nFor context, it helps to understand a few of the use-cases that RequestManager\nis intended to allow.\n\n- to manage and return streaming content (such as video files)\n- to fulfill a request from multiple sources or by splitting one request into multiple requests\n - for instance one API call for a user and another for the user's friends\n - or e.g. fulfilling part of the request from one source (one API, in-memory, localStorage, IndexedDB\n etc.) and the rest from another source (a different API, a WebWorker, etc.)\n- to coalesce multiple requests\n- to decorate a request with additional info\n - e.g. an Auth handler that ensures the correct tokens or headers or cookies are attached.\n\n\n`await fetch()` resolves at the moment headers are received. This allows for the body of the request to be processed as a stream by application\ncode *while chunks are still being received by the browser*.\n\nWhen an app chooses to `await response.json()` what occurs is the browser reads the stream to completion and then returns the result. Additionally, this stream may only be read **once**.\n\nThe `RequestManager` preserves this ability to subscribe to and utilize the stream by either the application or the handler – thereby delivering the full power and flexibility of native APIs – without restricting developers in ways that lead to complicated workarounds.\n\nEach handler may call `setStream` only once, but may do so *at any time* until the promise that the handler returns has resolved. The associated promise returned by calling `future.getStream` will resolve with the stream set by `setStream` if that method is called, or `null` if that method\nhas not been called by the time that the handler's request method has resolved.\n\nHandlers that do not create a stream of their own, but which call `next`, should defensively pipe the stream forward. While this is not required (see automatic currying below) it is better to do so in most cases as otherwise the stream may not become available to downstream handlers or the application until the upstream handler has fully read it.\n\n```ts\ncontext.setStream(future.getStream());\n```\n\nHandlers that either call `next` multiple times or otherwise have reason to create multiple fetch requests should either choose to return no stream, meaningfully combine the streams, or select a single prioritized stream.\n\nOf course, any handler may choose to read and handle the stream, and return either no stream or a different stream in the process.\n\n
\n\n
\n Automatic Currying of Stream and Response
\n\nIn order to simplify the common case for handlers which decorate a request, if `next` is called only a single time and `setResponse` was never called by the handler, the response set by the next handler in the chain will be applied to that handler's outcome. For instance, this makes the following pattern possible `return (await next()).content;`.\n\nSimilarly, if `next` is called only a single time and neither `setStream` nor `getStream` was called, we automatically curry the stream from the future returned by `next` onto the future returned by the handler.\n\nFinally, if the return value of a handler is a `Future`, we curry `content` and `errors` as well, thus enabling the simplest form `return next()`.\n\nIn the case of the `Future` being returned, `Stream` proxying is automatic and immediate and does not wait for the `Future` to resolve.\n\n
\n\n### Using as a Service\n\nMost applications will desire to have a single `RequestManager` instance, which can be achieved using module-state patterns for singletons, or for [Ember](https://emberjs.com) applications by exporting the manager as a [service](https://guides.emberjs.com/release/services/).\n\nservices/request.ts*\n```ts\nimport RequestManager from '@ember-data/request';\nimport Fetch from '@ember-data/request/fetch';\nimport Auth from 'ember-simple-auth/ember-data-handler';\n\nexport default class extends RequestManager {\n constructor(createArgs) {\n super(createArgs);\n this.use([Auth, Fetch]);\n }\n}\n```\n\n### Using with `@ember-data/store`\n\nTo have a request service unique to a Store:\n\n```ts\nimport Store, { CacheHandler } from '@ember-data/store';\nimport RequestManager from '@ember-data/request';\nimport Fetch from '@ember-data/request/fetch';\n\nclass extends Store {\n requestManager = new RequestManager();\nconstructor(args) {\n super(args);\n this.requestManager.use([Fetch]);\n this.requestManager.useCache(CacheHandler);\n }\n}\n```\n\n### Using with `ember-data`\n\nIf using the package [ember-data](https://github.com/emberjs/data/tree/main/packages/-ember-data), the following configuration will automatically be done in order to preserve the legacy [Adapter](https://github.com/emberjs/data/tree/main/packages/adapter) and [Serializer](https://github.com/emberjs/data/tree/main/packages/serializer) behavior. Additional handlers or a service injection like the above would need to be done by the consuming application in order to make broader use of `RequestManager`.\n\n```ts\nimport Store, { CacheHandler } from '@ember-data/store';\nimport RequestManager from '@ember-data/request';\nimport { LegacyNetworkHandler } from '@ember-data/legacy-compat';\n\nexport default class extends Store {\n requestManager = new RequestManager();\nconstructor(args) {\n super(args);\n this.requestManager.use([LegacyNetworkHandler]);\n this.requestManager.useCache(CacheHandler);\n }\n}\n```\n\nBecause the application's store service (if present) will override the store supplied by `ember-data`, all that is required to define your own ordering and handlers is to supply a store service extending from `@ember-data/store` and configure as shown above.\n\nFor usage of the store's `requestManager` via `store.request()` see the [Store](https://api.emberjs.com/ember-data/release/modules/@ember-data%2Fstore) documentation.", + "description": "

\n \n

\n\n

⚑️ a simple abstraction over fetch to enable easy management of request/response flows

\n\nThis package provides [*Ember*‍**Data**](https://github.com/emberjs/data/)'s `RequestManager`, a framework agnostic library that can be integrated with any Javascript application to make [fetch](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) happen.\n\n## Installation\n\nInstall using your javascript package manager of choice. For instance with [pnpm](https://pnpm.io/)\n\n```\npnpm add @ember-data/request\n```\n\n## πŸš€ Basic Usage\n\nA `RequestManager` provides a request/response flow in which configured handlers are successively given the opportunity to handle, modify, or pass-along a request.\n\nThe RequestManager on its own does not know how to fulfill requests. For this we must register at least one handler. A basic `Fetch` handler is provided that will take the request options provided and execute `fetch`.\n\n```ts\nimport RequestManager from '@ember-data/request';\nimport Fetch from '@ember-data/request/fetch';\nimport { apiUrl } from './config';\n\n// ... create manager and add our Fetch handler\nconst manager = new RequestManager();\nmanager.use([Fetch]);\n\n// ... execute a request\nconst response = await manager.request({\n url: `${apiUrl}/users`\n});\n```\n\n\n## πŸͺœ Architecture\n\nA `RequestManager` receives a request and manages fulfillment via configured handlers. It may be used standalone from the rest of *Ember*‍**Data** and is not specific to any library or framework.\n\nEach handler may choose to fulfill the request using some source of data or to pass the request along to other handlers.\n\nThe same or a separate instance of a `RequestManager` may also be used to fulfill requests issued by [*Ember*‍**Data**{Store}](https://github.com/emberjs/data/tree/main/packages/store)\n\nWhen the same instance is used by both this allows for simple coordination throughout the application. Requests issued by the Store will use the in-memory cache\nand return hydrated responses, requests issued directly to the RequestManager\nwill skip the in-memory cache and return raw responses.\n\n## Usage\n\n```ts\nconst userList = await manager.request({\n url: `/api/v1/users.list`\n});\n\nconst users = userList.content;\n```\n\n
\n Making Requests\n\n`RequestManager` has a single asyncronous method as it's API: `request`\n\n```ts\nclass RequestManager {\n request(req: RequestInfo): Future;\n}\n```\n\n`manager.request()` accepts an object containing the information\nnecessary for the request to be handled successfully.\n\nThese options extend the [options](https://developer.mozilla.org/en-US/docs/Web/API/fetch#parameters) provided to `fetch`, and can accept a [`Request`](https://developer.mozilla.org/en-US/docs/Web/API/Request/Request). All properties accepted by Request options and fetch options are valid.\n\n```ts\ninterface RequestInfo extends FetchOptions {\n op?: string;\n store?: Store;\nurl: string;\n // data that a handler should convert into\n // the query (GET) or body (POST)\n data?: Record;\n// options specifically intended for handlers\n // to utilize to process the request\n options?: Record;\n}\n```\n\n> **note:** providing a `signal` is unnecessary as an `AbortController` is automatically provided if none is present.\n\n
\n
\n Using the Response
\n\n`manager.request` returns a `Future`, which allows access to limited information about the request while it is still pending and fulfills with the final state when the request completes and the response has been read.\n\n```ts\nconst usersFuture = manager.request({\n url: `/api/v1/users.list`\n});\n```\n\nA `Future` is cancellable via `abort`.\n\n```ts\nusersFuture.abort();\n```\n\nHandlers may *optionally* expose a ReadableStream to the `Future` for streaming data; however, when doing so the handler should not resolve until it has fully read the response stream itself.\n\n```ts\ninterface Future extends Promise> {\n abort(): void;\nasync getStream(): ReadableStream | null;\n}\n```\n\nA Future resolves or rejects with a `StructuredDocument`.\n\n```ts\ninterface StructuredDocument {\n request: RequestInfo;\n response: ResponseInfo | null;\n content?: T;\n error?: Error;\n}\n```\n\nThe `RequestInfo` specified by `document.request` is the same as originally provided to `manager.request`. If any handler fulfilled this request using different request info it is not represented here. This contract helps to ensure that `retry` and `caching` are possible since the original arguments are correctly preserved. This also allows handlers to \"fork\" the request or fulfill from multiple sources without the details of fulfillment muddying the original request.\n\nThe `ResponseInfo` is a serializable fulfilled subset of a [Response](https://developer.mozilla.org/en-US/docs/Web/API/Response) if set via `setResponse`. If no response was ever set this will be `null`.\n\n```ts\ninterface ResponseInfo {\n headers?: Record;\n ok?: boolean;\n redirected?: boolean;\n status?: HTTPStatusCode;\n statusText?: string;\n type?: 'basic' | 'cors';\n url?: string;\n}\n```\n\n
\n\n

Handling Requests

\n
\n { request(context, next): Promise | Future; }
\n\nRequests are fulfilled by handlers. A handler receives the request context\nas well as a `next` function with which to pass along a request to the next\nhandler if it so chooses.\n\nA handler may be any object with a `request` method. This allows both stateful and non-stateful\nhandlers to be utilized.\n\nIf a handler calls `next`, it receives a `Future` which resolves to a `StructuredDocument`\nthat it can then compose how it sees fit with its own response.\n\n```ts\n\ntype NextFn

= (req: RequestInfo) => Future

;\n\ninterface Handler {\n async request(context: RequestContext, next: NextFn

): T;\n}\n```\n\n`RequestContext` contains a readonly version of the RequestInfo as well as a few methods for building up the `StructuredDocument` and `Future` that will be part of the response.\n\n```ts\ninterface RequestContext {\n readonly request: RequestInfo;\nsetStream(stream: ReadableStream | Promise): void;\n setResponse(response: Response | ResponseInfo): void;\n}\n```\n\nA basic `fetch` handler with support for streaming content updates while\nthe download is still underway might look like the following, where we use\n[`response.clone()`](https://developer.mozilla.org/en-US/docs/Web/API/Response/clone) to `tee` the `ReadableStream` into two streams.\n\nA more efficient handler might read from the response stream, building up the\nresponse content before passing along the chunk downstream.\n\n```ts\nconst FetchHandler = {\n async request(context) {\n const response = await fetch(context.request);\n context.setResponse(reponse);\n context.setStream(response.clone().body);\n return response.json();\n }\n}\n```\n\nRequest handlers are registered by configuring the manager via `use`\n\n```ts\nmanager.use([Handler1, Handler2])\n```\n\nHandlers will be invoked in the order they are registered (\"fifo\", first-in first-out), and may only be registered up until the first request is made. It is recommended but not required to register all handlers at one time in order to ensure explicitly visible handler ordering.\n\n

\n\n\n
\n Error Handling
\nEach handler in the chain can catch errors from upstream and choose to\n either handle the error, re-throw the error, or throw a new error.\n```ts\n const MAX_RETRIES = 5;\nconst Handler = {\n async request(context, next) {\n let attempts = 0;\n while (attempts < MAX_RETRIES) {\n attempts++;\n try {\n const response = await next(context.request);\n return response;\n } catch (e) {\n if (isTimeoutError(e) && attempts < MAX_RETRIES) {\n // retry request\n continue;\n }\n // rethrow if it is not a timeout error\n throw e;\n }\n }\n }\n }\n ```\n
\n\n
\n Handling Abort
\nAborting a request will reject the current handler in the chain. However,\n every handler can potentially catch this error. If your handler needs to\n separate AbortError from other Error types, it is recommended to check\n `context.request.signal.aborted` (or if a custom controller was supplied `controller.signal.aborted`).\nIn this manner it is possible for a request to recover from an abort and\n still proceed; however, as a best practice this should be used for necessary\n cleanup only and the original AbortError rethrown if the abort signal comes\n from the root controller.\n\n*AbortControllers are Always Present and Always Entangled**\nIf the initial request does not supply an [AbortController](https://developer.mozilla.org/en-US/docs/Web/API/AbortController), one will be generated.\nThe [signal](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) for this controller is automatically added to the request passed into the first handler.\nEach handler has the option to supply a new controller to the request when calling `next`. If a new controller is provided it will be automatically\n entangled with the root controller. If the root controller aborts, so will\n any entangled controllers.\nIf an entangled controller aborts, the root controller will not abort. This\n allows for advanced request-flow scenarios to abort subsections of the request tree without aborting the entire request.\n\n
\n\n\n
\n Stream Currying
\n\n`RequestManager.request` and `next` differ from `fetch` in one **crucial detail** in that the outer Promise resolves only once the response stream has been processed.\n\nFor context, it helps to understand a few of the use-cases that RequestManager\nis intended to allow.\n\n- to manage and return streaming content (such as video files)\n- to fulfill a request from multiple sources or by splitting one request into multiple requests\n - for instance one API call for a user and another for the user's friends\n - or e.g. fulfilling part of the request from one source (one API, in-memory, localStorage, IndexedDB\n etc.) and the rest from another source (a different API, a WebWorker, etc.)\n- to coalesce multiple requests\n- to decorate a request with additional info\n - e.g. an Auth handler that ensures the correct tokens or headers or cookies are attached.\n\n\n`await fetch()` resolves at the moment headers are received. This allows for the body of the request to be processed as a stream by application\ncode *while chunks are still being received by the browser*.\n\nWhen an app chooses to `await response.json()` what occurs is the browser reads the stream to completion and then returns the result. Additionally, this stream may only be read **once**.\n\nThe `RequestManager` preserves this ability to subscribe to and utilize the stream by either the application or the handler – thereby delivering the full power and flexibility of native APIs – without restricting developers in ways that lead to complicated workarounds.\n\nEach handler may call `setStream` only once, but may do so *at any time* until the promise that the handler returns has resolved. The associated promise returned by calling `future.getStream` will resolve with the stream set by `setStream` if that method is called, or `null` if that method\nhas not been called by the time that the handler's request method has resolved.\n\nHandlers that do not create a stream of their own, but which call `next`, should defensively pipe the stream forward. While this is not required (see automatic currying below) it is better to do so in most cases as otherwise the stream may not become available to downstream handlers or the application until the upstream handler has fully read it.\n\n```ts\ncontext.setStream(future.getStream());\n```\n\nHandlers that either call `next` multiple times or otherwise have reason to create multiple fetch requests should either choose to return no stream, meaningfully combine the streams, or select a single prioritized stream.\n\nOf course, any handler may choose to read and handle the stream, and return either no stream or a different stream in the process.\n\n
\n\n
\n Automatic Currying of Stream and Response
\n\nIn order to simplify the common case for handlers which decorate a request, if `next` is called only a single time and `setResponse` was never called by the handler, the response set by the next handler in the chain will be applied to that handler's outcome. For instance, this makes the following pattern possible `return (await next()).content;`.\n\nSimilarly, if `next` is called only a single time and neither `setStream` nor `getStream` was called, we automatically curry the stream from the future returned by `next` onto the future returned by the handler.\n\nFinally, if the return value of a handler is a `Future`, we curry `content` and `errors` as well, thus enabling the simplest form `return next()`.\n\nIn the case of the `Future` being returned, `Stream` proxying is automatic and immediate and does not wait for the `Future` to resolve.\n\n
\n\n### Using as a Service\n\nMost applications will desire to have a single `RequestManager` instance, which can be achieved using module-state patterns for singletons, or for [Ember](https://emberjs.com) applications by exporting the manager as a [service](https://guides.emberjs.com/release/services/).\n\nservices/request.ts*\n```ts\nimport RequestManager from '@ember-data/request';\nimport Fetch from '@ember-data/request/fetch';\nimport Auth from 'ember-simple-auth/ember-data-handler';\n\nexport default class extends RequestManager {\n constructor(createArgs) {\n super(createArgs);\n this.use([Auth, Fetch]);\n }\n}\n```\n\n### Using with `@ember-data/store`\n\nTo have a request service unique to a Store:\n\n```ts\nimport Store, { CacheHandler } from '@ember-data/store';\nimport RequestManager from '@ember-data/request';\nimport Fetch from '@ember-data/request/fetch';\n\nclass extends Store {\n requestManager = new RequestManager();\nconstructor(args) {\n super(args);\n this.requestManager.use([Fetch]);\n this.requestManager.useCache(CacheHandler);\n }\n}\n```\n\n### Using with `ember-data`\n\nIf using the package [ember-data](https://github.com/emberjs/data/tree/main/packages/-ember-data), the following configuration will automatically be done in order to preserve the legacy [Adapter](https://github.com/emberjs/data/tree/main/packages/adapter) and [Serializer](https://github.com/emberjs/data/tree/main/packages/serializer) behavior. Additional handlers or a service injection like the above would need to be done by the consuming application in order to make broader use of `RequestManager`.\n\n```ts\nimport Store, { CacheHandler } from '@ember-data/store';\nimport RequestManager from '@ember-data/request';\nimport { LegacyNetworkHandler } from '@ember-data/legacy-compat';\n\nexport default class extends Store {\n requestManager = new RequestManager();\nconstructor(args) {\n super(args);\n this.requestManager.use([LegacyNetworkHandler]);\n this.requestManager.useCache(CacheHandler);\n }\n}\n```\n\nBecause the application's store service (if present) will override the store supplied by `ember-data`, all that is required to define your own ordering and handlers is to supply a store service extending from `@ember-data/store` and configure as shown above.\n\nFor usage of the store's `requestManager` via `store.request()` see the [Store](https://api.emberjs.com/ember-data/release/modules/@ember-data%2Fstore) documentation.", "itemtype": "main", "parent": null, "publicclasses": [ diff --git a/json-docs/ember-data/5.0.1/modules/ember-data-5.0.1-ember-data-overview.json b/json-docs/ember-data/5.0.1/modules/ember-data-5.0.1-ember-data-overview.json index 89b2556b0..e0d41599d 100644 --- a/json-docs/ember-data/5.0.1/modules/ember-data-5.0.1-ember-data-overview.json +++ b/json-docs/ember-data/5.0.1/modules/ember-data-5.0.1-ember-data-overview.json @@ -11,7 +11,7 @@ "tag": "main", "file": "../-ember-data/addon/index.js", "line": 1, - "description": "

\n \n

\n\n

The lightweight reactive data library for JavaScript applications

\n\n---\n\nWrangle your application's data management with scalable patterns for developer productivity.\n\n- ⚑️ Committed to Best-In-Class Performance\n- 🌲 Focused on being as svelte as possible\n- πŸš€ SSR Ready\n- πŸ”œ Typescript Support\n- 🐹 Built with β™₯️ by [Ember](https://emberjs.com)\n- βš›οΈ Supports any API: `GraphQL` `JSON:API` `REST` `tRPC` ...bespoke or a mix\n\n### πŸ“– On This Page\n\n- [Overview](./#overview)\n - [Architecture](#πŸͺœ-architecture)\n - [Basic Installation](#basic-installation)\n - [Advanced Installation](#advanced-installation)\n- [Configuration](#configuration)\n - [Deprecation Stripping](#deprecation-stripping)\n - [randomUUID polyfill](#randomuuid-polyfill)\n - [Removing inspector support in production](#removing-inspector-support-in-production)\n - [Debugging](#debugging)\n\n\n# Overview\n\n*Ember*‍**Data** is a lightweight reactive data library for JavaScript applications that provides composable primitives for ordering query/mutation/peek flows, managing network and cache, and reducing data for presentation.\n\n## πŸͺœ Architecture\n\nThe core of *Ember*‍**Data** is the `Store`, which coordinates interaction between your application, the `Cache`, and sources of data (such as your `API` or a local persistence layer).\nOptionally, the Store can be configured to hydrate the response data into rich presentation classes.\n\n*Ember*‍**Data** is both resource centric and document centric in it's approach to caching, requesting and presenting data. Your application's configuration and usage drives which is important and when.\n\nThe `Store` is a **coordinator**. When using a `Store` you configure what cache to use, how cache data should be presented to the UI, and where it should look for requested data when it is not available in the cache.\n\nThis coordination is handled opaquely to the nature of the requests issued and the format of the data being handled. This approach gives applications broad flexibility to configure *Ember*‍**Data** to best suite their needs. This makes *Ember*‍**Data** a powerful solution for applications regardless of their size and complexity.\n\n*Ember*‍**Data** is designed to scale, with a religious focus on performance and asset-size to keep its footprint small but speedy while still being able to handle large complex APIs in huge data-driven applications with no additional code and no added application complexity. It's goal is to prevent applications from writing code to manage data that is difficult to maintain or reason about.\n\n*Ember*‍**Data**'s power comes not from specific features, data formats, or adherence to specific API specs such as `JSON:API` `trpc` or `GraphQL`, but from solid conventions around requesting and mutating data developed over decades of experience scaling developer productivity.\n\n## Basic Installation\n\nInstall using your javascript package manager of choice. For instance with [pnpm](https://pnpm.io/)\n\n```no-highlight\npnpm add ember-data\n```\n\n`ember-data` is installed by default for new applications generated with `ember-cli`. You can check what version is installed by looking in the `devDependencies` hash of your project's [package.json](https://docs.npmjs.com/cli/v8/configuring-npm/package-json) file.\n\nIf you have generated a new `Ember` application using `ember-cli` but do\nnot wish to use `ember-data`, remove `ember-data` from your project's `package.json` file and run your package manager's install command to update your lockfile.\n\n## Advanced Installation\n\n*Ember*‍**Data** is organized into primitives that compose together via public APIs.\n\n- [@ember-data/store](/ember-data/release/modules/@ember-data%2Fstore) is the core and handles coordination\n- [@ember-data/json-api](/ember-data/release/modules/@ember-data%2Fjson-api) provides a resource cache for JSON:API structured data. It integrates with the store via the hook `createCache`\n- [@ember-data/model](/ember-data/release/modules/@ember-data%2Fmodel) is a presentation layer, it integrates with the store via the hooks `instantiateRecord` and `teardownRecord`.\n- [@ember-data/adapter](/ember-data/release/modules/@ember-data%2Fadapter) provides various network API integrations for APIS built over specific REST or JSON:API conventions.\n- [@ember-data/serializer](/ember-data/release/modules/@ember-data%2Fserializer) pairs with `@ember-data/adapter` to normalize and serialize data to and from an API format into the `JSON:API` format understood by `@ember-data/json-api`.\n- [@ember-data/debug](/ember-data/release/modules/@ember-data%2Fdebug) provides debugging support for the `ember-inspector`.\n- **ember-data** is a \"meta\" package which bundles all of these together for convenience\n\nThe packages interop with each other through well defined public API boundaries. The core\nof the library is the store provided by `@ember-data/store`, while each of the other libraries plugs into the store when installed. Because these packages interop via fully\npublic APIs, other libraries or applications may provide their own implementations. For instance, [ember-m3](https://github.com/hjdivad/ember-m3) is a commonly used presentation and cache implementation suitable for complex resource objects and graphs.\n\n## Configuration\n\n### Deprecation Stripping\n\n*Ember*‍**Data** allows users to opt-in and remove code that exists to support deprecated behaviors.\n\nIf your app has resolved all deprecations present in a given version, you may specify that version as your \"compatibility\" version to remove the code that supported the deprecated behavior from your app.\n\n```ts\nlet app = new EmberApp(defaults, {\n emberData: {\n compatWith: '4.8',\n },\n});\n```\n\n- [Full Documentation](https://api.emberjs.com/ember-data/release/modules/@ember-data%2Fdeprecations)\n\n### randomUUID polyfill\n\n*Ember*‍**Data** uses `UUID V4` by default to generate identifiers for new data created on the client. Identifier generation is configurable, but we also for convenience will polyfill\nthe necessary feature if your browser support or deployment environment demands it. To\nactivate this polyfill:\n\n```ts\nlet app = new EmberApp(defaults, {\n '@embroider/macros': {\n setConfig: {\n '@ember-data/store': {\n polyfillUUID: true\n },\n },\n },\n});\n```\n\n### removing inspector support in production\n\nIf you do not with to ship inspector support in your production application, you can specify\nthat all support for it should be stripped from the build.\n\n```ts\nlet app = new EmberApp(defaults, {\n emberData: {\n includeDataAdapterInProduction: false\n }\n});\n```\n\n- [Full Documentation](https://api.emberjs.com/ember-data/release/modules/@ember-data%2Fdebug)\n\n### Debugging\n\nMany portions of the internals are helpfully instrumented with logging that can be activated\nat build time. This instrumentation is always removed from production builds or any builds\nthat has not explicitly activated it. To activate it set the appropriate flag to `true`.\n\n```ts\n let app = new EmberApp(defaults, {\n emberData: {\n debug: {\n LOG_PAYLOADS: false, // data store received to update cache with\n LOG_OPERATIONS: false, // updates to cache remote state\n LOG_MUTATIONS: false, // updates to cache local state\n LOG_NOTIFICATIONS: false,\n LOG_REQUESTS: false, // log Requests issued via the request manager\n LOG_REQUEST_STATUS: false,\n LOG_IDENTIFIERS: false,\n LOG_GRAPH: false,\n LOG_INSTANCE_CACHE: false,\n }\n }\n });\n ```", + "description": "

\n \n

\n\n

The lightweight reactive data library for JavaScript applications

\n\n---\n\nWrangle your application's data management with scalable patterns for developer productivity.\n\n- ⚑️ Committed to Best-In-Class Performance\n- 🌲 Focused on being as svelte as possible\n- πŸš€ SSR Ready\n- πŸ”œ Typescript Support\n- 🐹 Built with β™₯️ by [Ember](https://emberjs.com)\n- βš›οΈ Supports any API: `GraphQL` `JSON:API` `REST` `tRPC` ...bespoke or a mix\n\n### πŸ“– On This Page\n\n- [Overview](./#overview)\n - [Architecture](#πŸͺœ-architecture)\n - [Basic Installation](#basic-installation)\n - [Advanced Installation](#advanced-installation)\n- [Configuration](#configuration)\n - [Deprecation Stripping](#deprecation-stripping)\n - [randomUUID polyfill](#randomuuid-polyfill)\n - [Removing inspector support in production](#removing-inspector-support-in-production)\n - [Debugging](#debugging)\n\n\n# Overview\n\n*Ember*‍**Data** is a lightweight reactive data library for JavaScript applications that provides composable primitives for ordering query/mutation/peek flows, managing network and cache, and reducing data for presentation.\n\n## πŸͺœ Architecture\n\nThe core of *Ember*‍**Data** is the `Store`, which coordinates interaction between your application, the `Cache`, and sources of data (such as your `API` or a local persistence layer).\nOptionally, the Store can be configured to hydrate the response data into rich presentation classes.\n\n*Ember*‍**Data** is both resource centric and document centric in it's approach to caching, requesting and presenting data. Your application's configuration and usage drives which is important and when.\n\nThe `Store` is a **coordinator**. When using a `Store` you configure what cache to use, how cache data should be presented to the UI, and where it should look for requested data when it is not available in the cache.\n\nThis coordination is handled opaquely to the nature of the requests issued and the format of the data being handled. This approach gives applications broad flexibility to configure *Ember*‍**Data** to best suite their needs. This makes *Ember*‍**Data** a powerful solution for applications regardless of their size and complexity.\n\n*Ember*‍**Data** is designed to scale, with a religious focus on performance and asset-size to keep its footprint small but speedy while still being able to handle large complex APIs in huge data-driven applications with no additional code and no added application complexity. It's goal is to prevent applications from writing code to manage data that is difficult to maintain or reason about.\n\n*Ember*‍**Data**'s power comes not from specific features, data formats, or adherence to specific API specs such as `JSON:API` `trpc` or `GraphQL`, but from solid conventions around requesting and mutating data developed over decades of experience scaling developer productivity.\n\n## Basic Installation\n\nInstall using your javascript package manager of choice. For instance with [pnpm](https://pnpm.io/)\n\n```\npnpm add ember-data\n```\n\n`ember-data` is installed by default for new applications generated with `ember-cli`. You can check what version is installed by looking in the `devDependencies` hash of your project's [package.json](https://docs.npmjs.com/cli/v8/configuring-npm/package-json) file.\n\nIf you have generated a new `Ember` application using `ember-cli` but do\nnot wish to use `ember-data`, remove `ember-data` from your project's `package.json` file and run your package manager's install command to update your lockfile.\n\n## Advanced Installation\n\n*Ember*‍**Data** is organized into primitives that compose together via public APIs.\n\n- [@ember-data/store](/ember-data/release/modules/@ember-data%2Fstore) is the core and handles coordination\n- [@ember-data/json-api](/ember-data/release/modules/@ember-data%2Fjson-api) provides a resource cache for JSON:API structured data. It integrates with the store via the hook `createCache`\n- [@ember-data/model](/ember-data/release/modules/@ember-data%2Fmodel) is a presentation layer, it integrates with the store via the hooks `instantiateRecord` and `teardownRecord`.\n- [@ember-data/adapter](/ember-data/release/modules/@ember-data%2Fadapter) provides various network API integrations for APIS built over specific REST or JSON:API conventions.\n- [@ember-data/serializer](/ember-data/release/modules/@ember-data%2Fserializer) pairs with `@ember-data/adapter` to normalize and serialize data to and from an API format into the `JSON:API` format understood by `@ember-data/json-api`.\n- [@ember-data/debug](/ember-data/release/modules/@ember-data%2Fdebug) provides debugging support for the `ember-inspector`.\n- **ember-data** is a \"meta\" package which bundles all of these together for convenience\n\nThe packages interop with each other through well defined public API boundaries. The core\nof the library is the store provided by `@ember-data/store`, while each of the other libraries plugs into the store when installed. Because these packages interop via fully\npublic APIs, other libraries or applications may provide their own implementations. For instance, [ember-m3](https://github.com/hjdivad/ember-m3) is a commonly used presentation and cache implementation suitable for complex resource objects and graphs.\n\n## Configuration\n\n### Deprecation Stripping\n\n*Ember*‍**Data** allows users to opt-in and remove code that exists to support deprecated behaviors.\n\nIf your app has resolved all deprecations present in a given version, you may specify that version as your \"compatibility\" version to remove the code that supported the deprecated behavior from your app.\n\n```ts\nlet app = new EmberApp(defaults, {\n emberData: {\n compatWith: '4.8',\n },\n});\n```\n\n- [Full Documentation](https://api.emberjs.com/ember-data/release/modules/@ember-data%2Fdeprecations)\n\n### randomUUID polyfill\n\n*Ember*‍**Data** uses `UUID V4` by default to generate identifiers for new data created on the client. Identifier generation is configurable, but we also for convenience will polyfill\nthe necessary feature if your browser support or deployment environment demands it. To\nactivate this polyfill:\n\n```ts\nlet app = new EmberApp(defaults, {\n '@embroider/macros': {\n setConfig: {\n '@ember-data/store': {\n polyfillUUID: true\n },\n },\n },\n});\n```\n\n### removing inspector support in production\n\nIf you do not with to ship inspector support in your production application, you can specify\nthat all support for it should be stripped from the build.\n\n```ts\nlet app = new EmberApp(defaults, {\n emberData: {\n includeDataAdapterInProduction: false\n }\n});\n```\n\n- [Full Documentation](https://api.emberjs.com/ember-data/release/modules/@ember-data%2Fdebug)\n\n### Debugging\n\nMany portions of the internals are helpfully instrumented with logging that can be activated\nat build time. This instrumentation is always removed from production builds or any builds\nthat has not explicitly activated it. To activate it set the appropriate flag to `true`.\n\n```ts\n let app = new EmberApp(defaults, {\n emberData: {\n debug: {\n LOG_PAYLOADS: false, // data store received to update cache with\n LOG_OPERATIONS: false, // updates to cache remote state\n LOG_MUTATIONS: false, // updates to cache local state\n LOG_NOTIFICATIONS: false,\n LOG_REQUESTS: false, // log Requests issued via the request manager\n LOG_REQUEST_STATUS: false,\n LOG_IDENTIFIERS: false,\n LOG_GRAPH: false,\n LOG_INSTANCE_CACHE: false,\n }\n }\n });\n ```", "itemtype": "main", "parent": null, "publicclasses": [], diff --git a/json-docs/ember-data/5.1.2/modules/ember-data-5.1.2-@ember-data/graph.json b/json-docs/ember-data/5.1.2/modules/ember-data-5.1.2-@ember-data/graph.json index 93babbd58..3440858d5 100644 --- a/json-docs/ember-data/5.1.2/modules/ember-data-5.1.2-@ember-data/graph.json +++ b/json-docs/ember-data/5.1.2/modules/ember-data-5.1.2-@ember-data/graph.json @@ -11,7 +11,7 @@ "tag": "main", "file": "../graph/src/-private.ts", "line": 3, - "description": "

\n \n

\n\n

Provides a performance tuned normalized graph for intelligently managing relationships between resources based on identity

\n\nWhile this Graph is abstract, it currently is a private implementation required as a peer-dependency by the [JSON:API Cache Implementation](https://github.com/emberjs/data/tree/main/packages/json-api).\n\nWe intend to make this Graph public API after some additional iteration during the 5.x timeframe, until then all APIs should be considered experimental and unstable, not fit for direct application or 3rd party library usage.\n\n## Installation\n\nInstall using your javascript package manager of choice. For instance with [pnpm](https://pnpm.io/)\n\n```no-highlight\npnpm add @ember-data/graph\n```", + "description": "

\n \n

\n\n

Provides a performance tuned normalized graph for intelligently managing relationships between resources based on identity

\n\nWhile this Graph is abstract, it currently is a private implementation required as a peer-dependency by the [JSON:API Cache Implementation](https://github.com/emberjs/data/tree/main/packages/json-api).\n\nWe intend to make this Graph public API after some additional iteration during the 5.x timeframe, until then all APIs should be considered experimental and unstable, not fit for direct application or 3rd party library usage.\n\n## Installation\n\nInstall using your javascript package manager of choice. For instance with [pnpm](https://pnpm.io/)\n\n```\npnpm add @ember-data/graph\n```", "itemtype": "main", "parent": null, "publicclasses": [], diff --git a/json-docs/ember-data/5.1.2/modules/ember-data-5.1.2-@ember-data/json-api.json b/json-docs/ember-data/5.1.2/modules/ember-data-5.1.2-@ember-data/json-api.json index c4cbb120a..fa4ca2472 100644 --- a/json-docs/ember-data/5.1.2/modules/ember-data-5.1.2-@ember-data/json-api.json +++ b/json-docs/ember-data/5.1.2/modules/ember-data-5.1.2-@ember-data/json-api.json @@ -11,7 +11,7 @@ "tag": "main", "file": "../json-api/src/-private/cache.ts", "line": 84, - "description": "

\n \n

\n\nThis package provides an in-memory [JSON:API](https://jsonapi.org/) document and resource [*Ember***Data** Cache](https://github.com/emberjs/data/blob/main/ember-data-types/cache/cache.ts) implementation.\n\n## Installation\n\nInstall using your javascript package manager of choice. For instance with [pnpm](https://pnpm.io/)\n\n```no-highlight\npnpm add @ember-data/json-api\n```\n\n## πŸš€ Setup\n\n> **Note** When using [ember-data](https://github.com/emberjs/data/blob/main/packages/-ember-data) the below\n> configuration is handled for you automatically.\n\n```ts\nimport Store from '@ember-data/store';\nimport Cache from '@ember-data/json-api';\n\nexport default class extends Store {\n createCache(wrapper) {\n return new Cache(wrapper);\n }\n}\n```\n\n\n## Usage\n\nUsually you will directly interact with the cache only if implementing a presentation class. Below we\ngive an example of a read-only record (mutations never written back to the cache). More typically cache\ninteractions are something that the `Store` coordinates as part of the `request/response` lifecycle.\n\n```ts\nimport Store, { recordIdentifierFor } from '@ember-data/store';\nimport Cache from '@ember-data/json-api';\nimport { TrackedObject } from 'tracked-built-ins';\n\nclass extends Store {\n createCache(wrapper) {\n return new Cache(wrapper);\n }\n\n instantiateRecord(identifier) {\n const { cache, notifications } = this;\n const { type, id } = identifier;\n\n // create a TrackedObject with our attributes, id and type\n const attrs = cache.peek(identifier).attributes;\n const data = Object.assign({}, attrs, { type, id });\n const record = new TrackedObject(data);\n\n // update the TrackedObject whenever attributes change\n const token = notifications.subscribe(identifier, (_, change) => {\n if (change === 'attributes') {\n Object.assign(record, cache.peek(identifier).attributes);\n }\n });\n\n // setup the ability to teardown the subscription when the\n // record is no longer needed\n record.destroy = () => {\n this.notifications.unsubscribe(token);\n };\n\n return record;\n }\n\n teardownRecord(record: FakeRecord) {\n record.destroy();\n }\n}\n```\n\nFor the full list of APIs available read the code documentation for [*Ember***Data** Cache](https://github.com/emberjs/data/blob/main/ember-data-types/cache/cache.ts)", + "description": "

\n \n

\n\nThis package provides an in-memory [JSON:API](https://jsonapi.org/) document and resource [*Ember***Data** Cache](https://github.com/emberjs/data/blob/main/ember-data-types/cache/cache.ts) implementation.\n\n## Installation\n\nInstall using your javascript package manager of choice. For instance with [pnpm](https://pnpm.io/)\n\n```\npnpm add @ember-data/json-api\n```\n\n## πŸš€ Setup\n\n> **Note** When using [ember-data](https://github.com/emberjs/data/blob/main/packages/-ember-data) the below\n> configuration is handled for you automatically.\n\n```ts\nimport Store from '@ember-data/store';\nimport Cache from '@ember-data/json-api';\n\nexport default class extends Store {\n createCache(wrapper) {\n return new Cache(wrapper);\n }\n}\n```\n\n\n## Usage\n\nUsually you will directly interact with the cache only if implementing a presentation class. Below we\ngive an example of a read-only record (mutations never written back to the cache). More typically cache\ninteractions are something that the `Store` coordinates as part of the `request/response` lifecycle.\n\n```ts\nimport Store, { recordIdentifierFor } from '@ember-data/store';\nimport Cache from '@ember-data/json-api';\nimport { TrackedObject } from 'tracked-built-ins';\n\nclass extends Store {\n createCache(wrapper) {\n return new Cache(wrapper);\n }\n\n instantiateRecord(identifier) {\n const { cache, notifications } = this;\n const { type, id } = identifier;\n\n // create a TrackedObject with our attributes, id and type\n const attrs = cache.peek(identifier).attributes;\n const data = Object.assign({}, attrs, { type, id });\n const record = new TrackedObject(data);\n\n // update the TrackedObject whenever attributes change\n const token = notifications.subscribe(identifier, (_, change) => {\n if (change === 'attributes') {\n Object.assign(record, cache.peek(identifier).attributes);\n }\n });\n\n // setup the ability to teardown the subscription when the\n // record is no longer needed\n record.destroy = () => {\n this.notifications.unsubscribe(token);\n };\n\n return record;\n }\n\n teardownRecord(record: FakeRecord) {\n record.destroy();\n }\n}\n```\n\nFor the full list of APIs available read the code documentation for [*Ember***Data** Cache](https://github.com/emberjs/data/blob/main/ember-data-types/cache/cache.ts)", "itemtype": "main", "parent": null, "publicclasses": [ diff --git a/json-docs/ember-data/5.1.2/modules/ember-data-5.1.2-@ember-data/request.json b/json-docs/ember-data/5.1.2/modules/ember-data-5.1.2-@ember-data/request.json index ca39e319b..afeed58e6 100644 --- a/json-docs/ember-data/5.1.2/modules/ember-data-5.1.2-@ember-data/request.json +++ b/json-docs/ember-data/5.1.2/modules/ember-data-5.1.2-@ember-data/request.json @@ -11,7 +11,7 @@ "tag": "main", "file": "../request/src/-private/types.ts", "line": 202, - "description": "

\n \n

\n\n

⚑️ a simple abstraction over fetch to enable easy management of request/response flows

\n\nThis package provides [*Ember*‍**Data**](https://github.com/emberjs/data/)'s `RequestManager`, a framework agnostic library that can be integrated with any Javascript application to make [fetch](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) happen.\n\n## Installation\n\nInstall using your javascript package manager of choice. For instance with [pnpm](https://pnpm.io/)\n\n```no-highlight\npnpm add @ember-data/request\n```\n\n## πŸš€ Basic Usage\n\nA `RequestManager` provides a request/response flow in which configured handlers are successively given the opportunity to handle, modify, or pass-along a request.\n\nThe RequestManager on its own does not know how to fulfill requests. For this we must register at least one handler. A basic `Fetch` handler is provided that will take the request options provided and execute `fetch`.\n\n```ts\nimport RequestManager from '@ember-data/request';\nimport Fetch from '@ember-data/request/fetch';\nimport { apiUrl } from './config';\n\n// ... create manager and add our Fetch handler\nconst manager = new RequestManager();\nmanager.use([Fetch]);\n\n// ... execute a request\nconst response = await manager.request({\n url: `${apiUrl}/users`\n});\n```\n\n\n## πŸͺœ Architecture\n\nA `RequestManager` receives a request and manages fulfillment via configured handlers. It may be used standalone from the rest of *Ember*‍**Data** and is not specific to any library or framework.\n\nEach handler may choose to fulfill the request using some source of data or to pass the request along to other handlers.\n\nThe same or a separate instance of a `RequestManager` may also be used to fulfill requests issued by [*Ember*‍**Data**{Store}](https://github.com/emberjs/data/tree/main/packages/store)\n\nWhen the same instance is used by both this allows for simple coordination throughout the application. Requests issued by the Store will use the in-memory cache\nand return hydrated responses, requests issued directly to the RequestManager\nwill skip the in-memory cache and return raw responses.\n\n## Usage\n\n```ts\nconst userList = await manager.request({\n url: `/api/v1/users.list`\n});\n\nconst users = userList.content;\n```\n\n
\n Making Requests\n\n`RequestManager` has a single asyncronous method as it's API: `request`\n\n```ts\nclass RequestManager {\n request(req: RequestInfo): Future;\n}\n```\n\n`manager.request()` accepts an object containing the information\nnecessary for the request to be handled successfully.\n\nThese options extend the [options](https://developer.mozilla.org/en-US/docs/Web/API/fetch#parameters) provided to `fetch`, and can accept a [`Request`](https://developer.mozilla.org/en-US/docs/Web/API/Request/Request). All properties accepted by Request options and fetch options are valid.\n\n```ts\ninterface RequestInfo extends FetchOptions {\n op?: string;\n store?: Store;\nurl: string;\n // data that a handler should convert into\n // the query (GET) or body (POST)\n data?: Record;\n// options specifically intended for handlers\n // to utilize to process the request\n options?: Record;\n}\n```\n\n> **note:** providing a `signal` is unnecessary as an `AbortController` is automatically provided if none is present.\n\n
\n
\n Using the Response
\n\n`manager.request` returns a `Future`, which allows access to limited information about the request while it is still pending and fulfills with the final state when the request completes and the response has been read.\n\n```ts\nconst usersFuture = manager.request({\n url: `/api/v1/users.list`\n});\n```\n\nA `Future` is cancellable via `abort`.\n\n```ts\nusersFuture.abort();\n```\n\nHandlers may *optionally* expose a ReadableStream to the `Future` for streaming data; however, when doing so the handler should not resolve until it has fully read the response stream itself.\n\n```ts\ninterface Future extends Promise> {\n abort(): void;\nasync getStream(): ReadableStream | null;\n}\n```\n\nA Future resolves or rejects with a `StructuredDocument`.\n\n```ts\ninterface StructuredDocument {\n request: RequestInfo;\n response: ResponseInfo | null;\n content?: T;\n error?: Error;\n}\n```\n\nThe `RequestInfo` specified by `document.request` is the same as originally provided to `manager.request`. If any handler fulfilled this request using different request info it is not represented here. This contract helps to ensure that `retry` and `caching` are possible since the original arguments are correctly preserved. This also allows handlers to \"fork\" the request or fulfill from multiple sources without the details of fulfillment muddying the original request.\n\nThe `ResponseInfo` is a serializable fulfilled subset of a [Response](https://developer.mozilla.org/en-US/docs/Web/API/Response) if set via `setResponse`. If no response was ever set this will be `null`.\n\n```ts\ninterface ResponseInfo {\n headers?: Record;\n ok?: boolean;\n redirected?: boolean;\n status?: HTTPStatusCode;\n statusText?: string;\n type?: 'basic' | 'cors';\n url?: string;\n}\n```\n\n
\n\n

Handling Requests

\n
\n { request(context, next): Promise | Future; }
\n\nRequests are fulfilled by handlers. A handler receives the request context\nas well as a `next` function with which to pass along a request to the next\nhandler if it so chooses.\n\nA handler may be any object with a `request` method. This allows both stateful and non-stateful\nhandlers to be utilized.\n\nIf a handler calls `next`, it receives a `Future` which resolves to a `StructuredDocument`\nthat it can then compose how it sees fit with its own response.\n\n```ts\n\ntype NextFn

= (req: RequestInfo) => Future

;\n\ninterface Handler {\n async request(context: RequestContext, next: NextFn

): T;\n}\n```\n\n`RequestContext` contains a readonly version of the RequestInfo as well as a few methods for building up the `StructuredDocument` and `Future` that will be part of the response.\n\n```ts\ninterface RequestContext {\n readonly request: RequestInfo;\nsetStream(stream: ReadableStream | Promise): void;\n setResponse(response: Response | ResponseInfo): void;\n}\n```\n\nA basic `fetch` handler with support for streaming content updates while\nthe download is still underway might look like the following, where we use\n[`response.clone()`](https://developer.mozilla.org/en-US/docs/Web/API/Response/clone) to `tee` the `ReadableStream` into two streams.\n\nA more efficient handler might read from the response stream, building up the\nresponse content before passing along the chunk downstream.\n\n```ts\nconst FetchHandler = {\n async request(context) {\n const response = await fetch(context.request);\n context.setResponse(reponse);\n context.setStream(response.clone().body);\n return response.json();\n }\n}\n```\n\nRequest handlers are registered by configuring the manager via `use`\n\n```ts\nmanager.use([Handler1, Handler2])\n```\n\nHandlers will be invoked in the order they are registered (\"fifo\", first-in first-out), and may only be registered up until the first request is made. It is recommended but not required to register all handlers at one time in order to ensure explicitly visible handler ordering.\n\n

\n\n\n
\n Error Handling
\nEach handler in the chain can catch errors from upstream and choose to\n either handle the error, re-throw the error, or throw a new error.\n```ts\n const MAX_RETRIES = 5;\nconst Handler = {\n async request(context, next) {\n let attempts = 0;\n while (attempts < MAX_RETRIES) {\n attempts++;\n try {\n const response = await next(context.request);\n return response;\n } catch (e) {\n if (isTimeoutError(e) && attempts < MAX_RETRIES) {\n // retry request\n continue;\n }\n // rethrow if it is not a timeout error\n throw e;\n }\n }\n }\n }\n ```\n
\n\n
\n Handling Abort
\nAborting a request will reject the current handler in the chain. However,\n every handler can potentially catch this error. If your handler needs to\n separate AbortError from other Error types, it is recommended to check\n `context.request.signal.aborted` (or if a custom controller was supplied `controller.signal.aborted`).\nIn this manner it is possible for a request to recover from an abort and\n still proceed; however, as a best practice this should be used for necessary\n cleanup only and the original AbortError rethrown if the abort signal comes\n from the root controller.\n\n*AbortControllers are Always Present and Always Entangled**\nIf the initial request does not supply an [AbortController](https://developer.mozilla.org/en-US/docs/Web/API/AbortController), one will be generated.\nThe [signal](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) for this controller is automatically added to the request passed into the first handler.\nEach handler has the option to supply a new controller to the request when calling `next`. If a new controller is provided it will be automatically\n entangled with the root controller. If the root controller aborts, so will\n any entangled controllers.\nIf an entangled controller aborts, the root controller will not abort. This\n allows for advanced request-flow scenarios to abort subsections of the request tree without aborting the entire request.\n\n
\n\n\n
\n Stream Currying
\n\n`RequestManager.request` and `next` differ from `fetch` in one **crucial detail** in that the outer Promise resolves only once the response stream has been processed.\n\nFor context, it helps to understand a few of the use-cases that RequestManager\nis intended to allow.\n\n- to manage and return streaming content (such as video files)\n- to fulfill a request from multiple sources or by splitting one request into multiple requests\n - for instance one API call for a user and another for the user's friends\n - or e.g. fulfilling part of the request from one source (one API, in-memory, localStorage, IndexedDB\n etc.) and the rest from another source (a different API, a WebWorker, etc.)\n- to coalesce multiple requests\n- to decorate a request with additional info\n - e.g. an Auth handler that ensures the correct tokens or headers or cookies are attached.\n\n\n`await fetch()` resolves at the moment headers are received. This allows for the body of the request to be processed as a stream by application\ncode *while chunks are still being received by the browser*.\n\nWhen an app chooses to `await response.json()` what occurs is the browser reads the stream to completion and then returns the result. Additionally, this stream may only be read **once**.\n\nThe `RequestManager` preserves this ability to subscribe to and utilize the stream by either the application or the handler – thereby delivering the full power and flexibility of native APIs – without restricting developers in ways that lead to complicated workarounds.\n\nEach handler may call `setStream` only once, but may do so *at any time* until the promise that the handler returns has resolved. The associated promise returned by calling `future.getStream` will resolve with the stream set by `setStream` if that method is called, or `null` if that method\nhas not been called by the time that the handler's request method has resolved.\n\nHandlers that do not create a stream of their own, but which call `next`, should defensively pipe the stream forward. While this is not required (see automatic currying below) it is better to do so in most cases as otherwise the stream may not become available to downstream handlers or the application until the upstream handler has fully read it.\n\n```ts\ncontext.setStream(future.getStream());\n```\n\nHandlers that either call `next` multiple times or otherwise have reason to create multiple fetch requests should either choose to return no stream, meaningfully combine the streams, or select a single prioritized stream.\n\nOf course, any handler may choose to read and handle the stream, and return either no stream or a different stream in the process.\n\n
\n\n
\n Automatic Currying of Stream and Response
\n\nIn order to simplify the common case for handlers which decorate a request, if `next` is called only a single time and `setResponse` was never called by the handler, the response set by the next handler in the chain will be applied to that handler's outcome. For instance, this makes the following pattern possible `return (await next()).content;`.\n\nSimilarly, if `next` is called only a single time and neither `setStream` nor `getStream` was called, we automatically curry the stream from the future returned by `next` onto the future returned by the handler.\n\nFinally, if the return value of a handler is a `Future`, we curry `content` and `errors` as well, thus enabling the simplest form `return next()`.\n\nIn the case of the `Future` being returned, `Stream` proxying is automatic and immediate and does not wait for the `Future` to resolve.\n\n
\n\n### Using as a Service\n\nMost applications will desire to have a single `RequestManager` instance, which can be achieved using module-state patterns for singletons, or for [Ember](https://emberjs.com) applications by exporting the manager as a [service](https://guides.emberjs.com/release/services/).\n\nservices/request.ts*\n```ts\nimport RequestManager from '@ember-data/request';\nimport Fetch from '@ember-data/request/fetch';\nimport Auth from 'ember-simple-auth/ember-data-handler';\n\nexport default class extends RequestManager {\n constructor(createArgs) {\n super(createArgs);\n this.use([Auth, Fetch]);\n }\n}\n```\n\n### Using with `@ember-data/store`\n\nTo have a request service unique to a Store:\n\n```ts\nimport Store, { CacheHandler } from '@ember-data/store';\nimport RequestManager from '@ember-data/request';\nimport Fetch from '@ember-data/request/fetch';\n\nclass extends Store {\n requestManager = new RequestManager();\nconstructor(args) {\n super(args);\n this.requestManager.use([Fetch]);\n this.requestManager.useCache(CacheHandler);\n }\n}\n```\n\n### Using with `ember-data`\n\nIf using the package [ember-data](https://github.com/emberjs/data/tree/main/packages/-ember-data), the following configuration will automatically be done in order to preserve the legacy [Adapter](https://github.com/emberjs/data/tree/main/packages/adapter) and [Serializer](https://github.com/emberjs/data/tree/main/packages/serializer) behavior. Additional handlers or a service injection like the above would need to be done by the consuming application in order to make broader use of `RequestManager`.\n\n```ts\nimport Store, { CacheHandler } from '@ember-data/store';\nimport RequestManager from '@ember-data/request';\nimport { LegacyNetworkHandler } from '@ember-data/legacy-compat';\n\nexport default class extends Store {\n requestManager = new RequestManager();\nconstructor(args) {\n super(args);\n this.requestManager.use([LegacyNetworkHandler]);\n this.requestManager.useCache(CacheHandler);\n }\n}\n```\n\nBecause the application's store service (if present) will override the store supplied by `ember-data`, all that is required to define your own ordering and handlers is to supply a store service extending from `@ember-data/store` and configure as shown above.\n\nFor usage of the store's `requestManager` via `store.request()` see the [Store](https://api.emberjs.com/ember-data/release/modules/@ember-data%2Fstore) documentation.", + "description": "

\n \n

\n\n

⚑️ a simple abstraction over fetch to enable easy management of request/response flows

\n\nThis package provides [*Ember*‍**Data**](https://github.com/emberjs/data/)'s `RequestManager`, a framework agnostic library that can be integrated with any Javascript application to make [fetch](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) happen.\n\n## Installation\n\nInstall using your javascript package manager of choice. For instance with [pnpm](https://pnpm.io/)\n\n```\npnpm add @ember-data/request\n```\n\n## πŸš€ Basic Usage\n\nA `RequestManager` provides a request/response flow in which configured handlers are successively given the opportunity to handle, modify, or pass-along a request.\n\nThe RequestManager on its own does not know how to fulfill requests. For this we must register at least one handler. A basic `Fetch` handler is provided that will take the request options provided and execute `fetch`.\n\n```ts\nimport RequestManager from '@ember-data/request';\nimport Fetch from '@ember-data/request/fetch';\nimport { apiUrl } from './config';\n\n// ... create manager and add our Fetch handler\nconst manager = new RequestManager();\nmanager.use([Fetch]);\n\n// ... execute a request\nconst response = await manager.request({\n url: `${apiUrl}/users`\n});\n```\n\n\n## πŸͺœ Architecture\n\nA `RequestManager` receives a request and manages fulfillment via configured handlers. It may be used standalone from the rest of *Ember*‍**Data** and is not specific to any library or framework.\n\nEach handler may choose to fulfill the request using some source of data or to pass the request along to other handlers.\n\nThe same or a separate instance of a `RequestManager` may also be used to fulfill requests issued by [*Ember*‍**Data**{Store}](https://github.com/emberjs/data/tree/main/packages/store)\n\nWhen the same instance is used by both this allows for simple coordination throughout the application. Requests issued by the Store will use the in-memory cache\nand return hydrated responses, requests issued directly to the RequestManager\nwill skip the in-memory cache and return raw responses.\n\n## Usage\n\n```ts\nconst userList = await manager.request({\n url: `/api/v1/users.list`\n});\n\nconst users = userList.content;\n```\n\n
\n Making Requests\n\n`RequestManager` has a single asyncronous method as it's API: `request`\n\n```ts\nclass RequestManager {\n request(req: RequestInfo): Future;\n}\n```\n\n`manager.request()` accepts an object containing the information\nnecessary for the request to be handled successfully.\n\nThese options extend the [options](https://developer.mozilla.org/en-US/docs/Web/API/fetch#parameters) provided to `fetch`, and can accept a [`Request`](https://developer.mozilla.org/en-US/docs/Web/API/Request/Request). All properties accepted by Request options and fetch options are valid.\n\n```ts\ninterface RequestInfo extends FetchOptions {\n op?: string;\n store?: Store;\nurl: string;\n // data that a handler should convert into\n // the query (GET) or body (POST)\n data?: Record;\n// options specifically intended for handlers\n // to utilize to process the request\n options?: Record;\n}\n```\n\n> **note:** providing a `signal` is unnecessary as an `AbortController` is automatically provided if none is present.\n\n
\n
\n Using the Response
\n\n`manager.request` returns a `Future`, which allows access to limited information about the request while it is still pending and fulfills with the final state when the request completes and the response has been read.\n\n```ts\nconst usersFuture = manager.request({\n url: `/api/v1/users.list`\n});\n```\n\nA `Future` is cancellable via `abort`.\n\n```ts\nusersFuture.abort();\n```\n\nHandlers may *optionally* expose a ReadableStream to the `Future` for streaming data; however, when doing so the handler should not resolve until it has fully read the response stream itself.\n\n```ts\ninterface Future extends Promise> {\n abort(): void;\nasync getStream(): ReadableStream | null;\n}\n```\n\nA Future resolves or rejects with a `StructuredDocument`.\n\n```ts\ninterface StructuredDocument {\n request: RequestInfo;\n response: ResponseInfo | null;\n content?: T;\n error?: Error;\n}\n```\n\nThe `RequestInfo` specified by `document.request` is the same as originally provided to `manager.request`. If any handler fulfilled this request using different request info it is not represented here. This contract helps to ensure that `retry` and `caching` are possible since the original arguments are correctly preserved. This also allows handlers to \"fork\" the request or fulfill from multiple sources without the details of fulfillment muddying the original request.\n\nThe `ResponseInfo` is a serializable fulfilled subset of a [Response](https://developer.mozilla.org/en-US/docs/Web/API/Response) if set via `setResponse`. If no response was ever set this will be `null`.\n\n```ts\ninterface ResponseInfo {\n headers?: Record;\n ok?: boolean;\n redirected?: boolean;\n status?: HTTPStatusCode;\n statusText?: string;\n type?: 'basic' | 'cors';\n url?: string;\n}\n```\n\n
\n\n

Handling Requests

\n
\n { request(context, next): Promise | Future; }
\n\nRequests are fulfilled by handlers. A handler receives the request context\nas well as a `next` function with which to pass along a request to the next\nhandler if it so chooses.\n\nA handler may be any object with a `request` method. This allows both stateful and non-stateful\nhandlers to be utilized.\n\nIf a handler calls `next`, it receives a `Future` which resolves to a `StructuredDocument`\nthat it can then compose how it sees fit with its own response.\n\n```ts\n\ntype NextFn

= (req: RequestInfo) => Future

;\n\ninterface Handler {\n async request(context: RequestContext, next: NextFn

): T;\n}\n```\n\n`RequestContext` contains a readonly version of the RequestInfo as well as a few methods for building up the `StructuredDocument` and `Future` that will be part of the response.\n\n```ts\ninterface RequestContext {\n readonly request: RequestInfo;\nsetStream(stream: ReadableStream | Promise): void;\n setResponse(response: Response | ResponseInfo): void;\n}\n```\n\nA basic `fetch` handler with support for streaming content updates while\nthe download is still underway might look like the following, where we use\n[`response.clone()`](https://developer.mozilla.org/en-US/docs/Web/API/Response/clone) to `tee` the `ReadableStream` into two streams.\n\nA more efficient handler might read from the response stream, building up the\nresponse content before passing along the chunk downstream.\n\n```ts\nconst FetchHandler = {\n async request(context) {\n const response = await fetch(context.request);\n context.setResponse(reponse);\n context.setStream(response.clone().body);\n return response.json();\n }\n}\n```\n\nRequest handlers are registered by configuring the manager via `use`\n\n```ts\nmanager.use([Handler1, Handler2])\n```\n\nHandlers will be invoked in the order they are registered (\"fifo\", first-in first-out), and may only be registered up until the first request is made. It is recommended but not required to register all handlers at one time in order to ensure explicitly visible handler ordering.\n\n

\n\n\n
\n Error Handling
\nEach handler in the chain can catch errors from upstream and choose to\n either handle the error, re-throw the error, or throw a new error.\n```ts\n const MAX_RETRIES = 5;\nconst Handler = {\n async request(context, next) {\n let attempts = 0;\n while (attempts < MAX_RETRIES) {\n attempts++;\n try {\n const response = await next(context.request);\n return response;\n } catch (e) {\n if (isTimeoutError(e) && attempts < MAX_RETRIES) {\n // retry request\n continue;\n }\n // rethrow if it is not a timeout error\n throw e;\n }\n }\n }\n }\n ```\n
\n\n
\n Handling Abort
\nAborting a request will reject the current handler in the chain. However,\n every handler can potentially catch this error. If your handler needs to\n separate AbortError from other Error types, it is recommended to check\n `context.request.signal.aborted` (or if a custom controller was supplied `controller.signal.aborted`).\nIn this manner it is possible for a request to recover from an abort and\n still proceed; however, as a best practice this should be used for necessary\n cleanup only and the original AbortError rethrown if the abort signal comes\n from the root controller.\n\n*AbortControllers are Always Present and Always Entangled**\nIf the initial request does not supply an [AbortController](https://developer.mozilla.org/en-US/docs/Web/API/AbortController), one will be generated.\nThe [signal](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) for this controller is automatically added to the request passed into the first handler.\nEach handler has the option to supply a new controller to the request when calling `next`. If a new controller is provided it will be automatically\n entangled with the root controller. If the root controller aborts, so will\n any entangled controllers.\nIf an entangled controller aborts, the root controller will not abort. This\n allows for advanced request-flow scenarios to abort subsections of the request tree without aborting the entire request.\n\n
\n\n\n
\n Stream Currying
\n\n`RequestManager.request` and `next` differ from `fetch` in one **crucial detail** in that the outer Promise resolves only once the response stream has been processed.\n\nFor context, it helps to understand a few of the use-cases that RequestManager\nis intended to allow.\n\n- to manage and return streaming content (such as video files)\n- to fulfill a request from multiple sources or by splitting one request into multiple requests\n - for instance one API call for a user and another for the user's friends\n - or e.g. fulfilling part of the request from one source (one API, in-memory, localStorage, IndexedDB\n etc.) and the rest from another source (a different API, a WebWorker, etc.)\n- to coalesce multiple requests\n- to decorate a request with additional info\n - e.g. an Auth handler that ensures the correct tokens or headers or cookies are attached.\n\n\n`await fetch()` resolves at the moment headers are received. This allows for the body of the request to be processed as a stream by application\ncode *while chunks are still being received by the browser*.\n\nWhen an app chooses to `await response.json()` what occurs is the browser reads the stream to completion and then returns the result. Additionally, this stream may only be read **once**.\n\nThe `RequestManager` preserves this ability to subscribe to and utilize the stream by either the application or the handler – thereby delivering the full power and flexibility of native APIs – without restricting developers in ways that lead to complicated workarounds.\n\nEach handler may call `setStream` only once, but may do so *at any time* until the promise that the handler returns has resolved. The associated promise returned by calling `future.getStream` will resolve with the stream set by `setStream` if that method is called, or `null` if that method\nhas not been called by the time that the handler's request method has resolved.\n\nHandlers that do not create a stream of their own, but which call `next`, should defensively pipe the stream forward. While this is not required (see automatic currying below) it is better to do so in most cases as otherwise the stream may not become available to downstream handlers or the application until the upstream handler has fully read it.\n\n```ts\ncontext.setStream(future.getStream());\n```\n\nHandlers that either call `next` multiple times or otherwise have reason to create multiple fetch requests should either choose to return no stream, meaningfully combine the streams, or select a single prioritized stream.\n\nOf course, any handler may choose to read and handle the stream, and return either no stream or a different stream in the process.\n\n
\n\n
\n Automatic Currying of Stream and Response
\n\nIn order to simplify the common case for handlers which decorate a request, if `next` is called only a single time and `setResponse` was never called by the handler, the response set by the next handler in the chain will be applied to that handler's outcome. For instance, this makes the following pattern possible `return (await next()).content;`.\n\nSimilarly, if `next` is called only a single time and neither `setStream` nor `getStream` was called, we automatically curry the stream from the future returned by `next` onto the future returned by the handler.\n\nFinally, if the return value of a handler is a `Future`, we curry `content` and `errors` as well, thus enabling the simplest form `return next()`.\n\nIn the case of the `Future` being returned, `Stream` proxying is automatic and immediate and does not wait for the `Future` to resolve.\n\n
\n\n### Using as a Service\n\nMost applications will desire to have a single `RequestManager` instance, which can be achieved using module-state patterns for singletons, or for [Ember](https://emberjs.com) applications by exporting the manager as a [service](https://guides.emberjs.com/release/services/).\n\nservices/request.ts*\n```ts\nimport RequestManager from '@ember-data/request';\nimport Fetch from '@ember-data/request/fetch';\nimport Auth from 'ember-simple-auth/ember-data-handler';\n\nexport default class extends RequestManager {\n constructor(createArgs) {\n super(createArgs);\n this.use([Auth, Fetch]);\n }\n}\n```\n\n### Using with `@ember-data/store`\n\nTo have a request service unique to a Store:\n\n```ts\nimport Store, { CacheHandler } from '@ember-data/store';\nimport RequestManager from '@ember-data/request';\nimport Fetch from '@ember-data/request/fetch';\n\nclass extends Store {\n requestManager = new RequestManager();\nconstructor(args) {\n super(args);\n this.requestManager.use([Fetch]);\n this.requestManager.useCache(CacheHandler);\n }\n}\n```\n\n### Using with `ember-data`\n\nIf using the package [ember-data](https://github.com/emberjs/data/tree/main/packages/-ember-data), the following configuration will automatically be done in order to preserve the legacy [Adapter](https://github.com/emberjs/data/tree/main/packages/adapter) and [Serializer](https://github.com/emberjs/data/tree/main/packages/serializer) behavior. Additional handlers or a service injection like the above would need to be done by the consuming application in order to make broader use of `RequestManager`.\n\n```ts\nimport Store, { CacheHandler } from '@ember-data/store';\nimport RequestManager from '@ember-data/request';\nimport { LegacyNetworkHandler } from '@ember-data/legacy-compat';\n\nexport default class extends Store {\n requestManager = new RequestManager();\nconstructor(args) {\n super(args);\n this.requestManager.use([LegacyNetworkHandler]);\n this.requestManager.useCache(CacheHandler);\n }\n}\n```\n\nBecause the application's store service (if present) will override the store supplied by `ember-data`, all that is required to define your own ordering and handlers is to supply a store service extending from `@ember-data/store` and configure as shown above.\n\nFor usage of the store's `requestManager` via `store.request()` see the [Store](https://api.emberjs.com/ember-data/release/modules/@ember-data%2Fstore) documentation.", "itemtype": "main", "parent": null, "publicclasses": [ diff --git a/json-docs/ember-data/5.1.2/modules/ember-data-5.1.2-ember-data-overview.json b/json-docs/ember-data/5.1.2/modules/ember-data-5.1.2-ember-data-overview.json index dff87d958..3a4fb6c4c 100644 --- a/json-docs/ember-data/5.1.2/modules/ember-data-5.1.2-ember-data-overview.json +++ b/json-docs/ember-data/5.1.2/modules/ember-data-5.1.2-ember-data-overview.json @@ -11,7 +11,7 @@ "tag": "main", "file": "../-ember-data/addon/index.js", "line": 1, - "description": "

\n \n

\n\n

The lightweight reactive data library for JavaScript applications

\n\n---\n\nWrangle your application's data management with scalable patterns for developer productivity.\n\n- ⚑️ Committed to Best-In-Class Performance\n- 🌲 Focused on being as svelte as possible\n- πŸš€ SSR Ready\n- πŸ”œ Typescript Support\n- 🐹 Built with β™₯️ by [Ember](https://emberjs.com)\n- βš›οΈ Supports any API: `GraphQL` `JSON:API` `REST` `tRPC` ...bespoke or a mix\n\n### πŸ“– On This Page\n\n- [Overview](./#overview)\n - [Architecture](#πŸͺœ-architecture)\n - [Basic Installation](#basic-installation)\n - [Advanced Installation](#advanced-installation)\n- [Configuration](#configuration)\n - [Deprecation Stripping](#deprecation-stripping)\n - [randomUUID polyfill](#randomuuid-polyfill)\n - [Removing inspector support in production](#removing-inspector-support-in-production)\n - [Debugging](#debugging)\n\n\n# Overview\n\n*Ember*‍**Data** is a lightweight reactive data library for JavaScript applications that provides composable primitives for ordering query/mutation/peek flows, managing network and cache, and reducing data for presentation.\n\n## πŸͺœ Architecture\n\nThe core of *Ember*‍**Data** is the `Store`, which coordinates interaction between your application, the `Cache`, and sources of data (such as your `API` or a local persistence layer).\nOptionally, the Store can be configured to hydrate the response data into rich presentation classes.\n\n*Ember*‍**Data** is both resource centric and document centric in it's approach to caching, requesting and presenting data. Your application's configuration and usage drives which is important and when.\n\nThe `Store` is a **coordinator**. When using a `Store` you configure what cache to use, how cache data should be presented to the UI, and where it should look for requested data when it is not available in the cache.\n\nThis coordination is handled opaquely to the nature of the requests issued and the format of the data being handled. This approach gives applications broad flexibility to configure *Ember*‍**Data** to best suite their needs. This makes *Ember*‍**Data** a powerful solution for applications regardless of their size and complexity.\n\n*Ember*‍**Data** is designed to scale, with a religious focus on performance and asset-size to keep its footprint small but speedy while still being able to handle large complex APIs in huge data-driven applications with no additional code and no added application complexity. It's goal is to prevent applications from writing code to manage data that is difficult to maintain or reason about.\n\n*Ember*‍**Data**'s power comes not from specific features, data formats, or adherence to specific API specs such as `JSON:API` `trpc` or `GraphQL`, but from solid conventions around requesting and mutating data developed over decades of experience scaling developer productivity.\n\n## Basic Installation\n\nInstall using your javascript package manager of choice. For instance with [pnpm](https://pnpm.io/)\n\n```no-highlight\npnpm add ember-data\n```\n\n`ember-data` is installed by default for new applications generated with `ember-cli`. You can check what version is installed by looking in the `devDependencies` hash of your project's [package.json](https://docs.npmjs.com/cli/v8/configuring-npm/package-json) file.\n\nIf you have generated a new `Ember` application using `ember-cli` but do\nnot wish to use `ember-data`, remove `ember-data` from your project's `package.json` file and run your package manager's install command to update your lockfile.\n\n## Advanced Installation\n\n*Ember*‍**Data** is organized into primitives that compose together via public APIs.\n\n- [@ember-data/store](/ember-data/release/modules/@ember-data%2Fstore) is the core and handles coordination\n- [@ember-data/json-api](/ember-data/release/modules/@ember-data%2Fjson-api) provides a resource cache for JSON:API structured data. It integrates with the store via the hook `createCache`\n- [@ember-data/model](/ember-data/release/modules/@ember-data%2Fmodel) is a presentation layer, it integrates with the store via the hooks `instantiateRecord` and `teardownRecord`.\n- [@ember-data/adapter](/ember-data/release/modules/@ember-data%2Fadapter) provides various network API integrations for APIS built over specific REST or JSON:API conventions.\n- [@ember-data/serializer](/ember-data/release/modules/@ember-data%2Fserializer) pairs with `@ember-data/adapter` to normalize and serialize data to and from an API format into the `JSON:API` format understood by `@ember-data/json-api`.\n- [@ember-data/debug](/ember-data/release/modules/@ember-data%2Fdebug) provides debugging support for the `ember-inspector`.\n- **ember-data** is a \"meta\" package which bundles all of these together for convenience\n\nThe packages interop with each other through well defined public API boundaries. The core\nof the library is the store provided by `@ember-data/store`, while each of the other libraries plugs into the store when installed. Because these packages interop via fully\npublic APIs, other libraries or applications may provide their own implementations. For instance, [ember-m3](https://github.com/hjdivad/ember-m3) is a commonly used presentation and cache implementation suitable for complex resource objects and graphs.\n\n## Configuration\n\n### Deprecation Stripping\n\n*Ember*‍**Data** allows users to opt-in and remove code that exists to support deprecated behaviors.\n\nIf your app has resolved all deprecations present in a given version, you may specify that version as your \"compatibility\" version to remove the code that supported the deprecated behavior from your app.\n\n```ts\nlet app = new EmberApp(defaults, {\n emberData: {\n compatWith: '4.8',\n },\n});\n```\n\n- [Full Documentation](https://api.emberjs.com/ember-data/release/modules/@ember-data%2Fdeprecations)\n\n### randomUUID polyfill\n\n*Ember*‍**Data** uses `UUID V4` by default to generate identifiers for new data created on the client. Identifier generation is configurable, but we also for convenience will polyfill\nthe necessary feature if your browser support or deployment environment demands it. To\nactivate this polyfill:\n\n```ts\nlet app = new EmberApp(defaults, {\n '@embroider/macros': {\n setConfig: {\n '@ember-data/store': {\n polyfillUUID: true\n },\n },\n },\n});\n```\n\n### removing inspector support in production\n\nIf you do not with to ship inspector support in your production application, you can specify\nthat all support for it should be stripped from the build.\n\n```ts\nlet app = new EmberApp(defaults, {\n emberData: {\n includeDataAdapterInProduction: false\n }\n});\n```\n\n- [Full Documentation](https://api.emberjs.com/ember-data/release/modules/@ember-data%2Fdebug)\n\n### Debugging\n\nMany portions of the internals are helpfully instrumented with logging that can be activated\nat build time. This instrumentation is always removed from production builds or any builds\nthat has not explicitly activated it. To activate it set the appropriate flag to `true`.\n\n```ts\n let app = new EmberApp(defaults, {\n emberData: {\n debug: {\n LOG_PAYLOADS: false, // data store received to update cache with\n LOG_OPERATIONS: false, // updates to cache remote state\n LOG_MUTATIONS: false, // updates to cache local state\n LOG_NOTIFICATIONS: false,\n LOG_REQUESTS: false, // log Requests issued via the request manager\n LOG_REQUEST_STATUS: false,\n LOG_IDENTIFIERS: false,\n LOG_GRAPH: false,\n LOG_INSTANCE_CACHE: false,\n }\n }\n });\n ```", + "description": "

\n \n

\n\n

The lightweight reactive data library for JavaScript applications

\n\n---\n\nWrangle your application's data management with scalable patterns for developer productivity.\n\n- ⚑️ Committed to Best-In-Class Performance\n- 🌲 Focused on being as svelte as possible\n- πŸš€ SSR Ready\n- πŸ”œ Typescript Support\n- 🐹 Built with β™₯️ by [Ember](https://emberjs.com)\n- βš›οΈ Supports any API: `GraphQL` `JSON:API` `REST` `tRPC` ...bespoke or a mix\n\n### πŸ“– On This Page\n\n- [Overview](./#overview)\n - [Architecture](#πŸͺœ-architecture)\n - [Basic Installation](#basic-installation)\n - [Advanced Installation](#advanced-installation)\n- [Configuration](#configuration)\n - [Deprecation Stripping](#deprecation-stripping)\n - [randomUUID polyfill](#randomuuid-polyfill)\n - [Removing inspector support in production](#removing-inspector-support-in-production)\n - [Debugging](#debugging)\n\n\n# Overview\n\n*Ember*‍**Data** is a lightweight reactive data library for JavaScript applications that provides composable primitives for ordering query/mutation/peek flows, managing network and cache, and reducing data for presentation.\n\n## πŸͺœ Architecture\n\nThe core of *Ember*‍**Data** is the `Store`, which coordinates interaction between your application, the `Cache`, and sources of data (such as your `API` or a local persistence layer).\nOptionally, the Store can be configured to hydrate the response data into rich presentation classes.\n\n*Ember*‍**Data** is both resource centric and document centric in it's approach to caching, requesting and presenting data. Your application's configuration and usage drives which is important and when.\n\nThe `Store` is a **coordinator**. When using a `Store` you configure what cache to use, how cache data should be presented to the UI, and where it should look for requested data when it is not available in the cache.\n\nThis coordination is handled opaquely to the nature of the requests issued and the format of the data being handled. This approach gives applications broad flexibility to configure *Ember*‍**Data** to best suite their needs. This makes *Ember*‍**Data** a powerful solution for applications regardless of their size and complexity.\n\n*Ember*‍**Data** is designed to scale, with a religious focus on performance and asset-size to keep its footprint small but speedy while still being able to handle large complex APIs in huge data-driven applications with no additional code and no added application complexity. It's goal is to prevent applications from writing code to manage data that is difficult to maintain or reason about.\n\n*Ember*‍**Data**'s power comes not from specific features, data formats, or adherence to specific API specs such as `JSON:API` `trpc` or `GraphQL`, but from solid conventions around requesting and mutating data developed over decades of experience scaling developer productivity.\n\n## Basic Installation\n\nInstall using your javascript package manager of choice. For instance with [pnpm](https://pnpm.io/)\n\n```\npnpm add ember-data\n```\n\n`ember-data` is installed by default for new applications generated with `ember-cli`. You can check what version is installed by looking in the `devDependencies` hash of your project's [package.json](https://docs.npmjs.com/cli/v8/configuring-npm/package-json) file.\n\nIf you have generated a new `Ember` application using `ember-cli` but do\nnot wish to use `ember-data`, remove `ember-data` from your project's `package.json` file and run your package manager's install command to update your lockfile.\n\n## Advanced Installation\n\n*Ember*‍**Data** is organized into primitives that compose together via public APIs.\n\n- [@ember-data/store](/ember-data/release/modules/@ember-data%2Fstore) is the core and handles coordination\n- [@ember-data/json-api](/ember-data/release/modules/@ember-data%2Fjson-api) provides a resource cache for JSON:API structured data. It integrates with the store via the hook `createCache`\n- [@ember-data/model](/ember-data/release/modules/@ember-data%2Fmodel) is a presentation layer, it integrates with the store via the hooks `instantiateRecord` and `teardownRecord`.\n- [@ember-data/adapter](/ember-data/release/modules/@ember-data%2Fadapter) provides various network API integrations for APIS built over specific REST or JSON:API conventions.\n- [@ember-data/serializer](/ember-data/release/modules/@ember-data%2Fserializer) pairs with `@ember-data/adapter` to normalize and serialize data to and from an API format into the `JSON:API` format understood by `@ember-data/json-api`.\n- [@ember-data/debug](/ember-data/release/modules/@ember-data%2Fdebug) provides debugging support for the `ember-inspector`.\n- **ember-data** is a \"meta\" package which bundles all of these together for convenience\n\nThe packages interop with each other through well defined public API boundaries. The core\nof the library is the store provided by `@ember-data/store`, while each of the other libraries plugs into the store when installed. Because these packages interop via fully\npublic APIs, other libraries or applications may provide their own implementations. For instance, [ember-m3](https://github.com/hjdivad/ember-m3) is a commonly used presentation and cache implementation suitable for complex resource objects and graphs.\n\n## Configuration\n\n### Deprecation Stripping\n\n*Ember*‍**Data** allows users to opt-in and remove code that exists to support deprecated behaviors.\n\nIf your app has resolved all deprecations present in a given version, you may specify that version as your \"compatibility\" version to remove the code that supported the deprecated behavior from your app.\n\n```ts\nlet app = new EmberApp(defaults, {\n emberData: {\n compatWith: '4.8',\n },\n});\n```\n\n- [Full Documentation](https://api.emberjs.com/ember-data/release/modules/@ember-data%2Fdeprecations)\n\n### randomUUID polyfill\n\n*Ember*‍**Data** uses `UUID V4` by default to generate identifiers for new data created on the client. Identifier generation is configurable, but we also for convenience will polyfill\nthe necessary feature if your browser support or deployment environment demands it. To\nactivate this polyfill:\n\n```ts\nlet app = new EmberApp(defaults, {\n '@embroider/macros': {\n setConfig: {\n '@ember-data/store': {\n polyfillUUID: true\n },\n },\n },\n});\n```\n\n### removing inspector support in production\n\nIf you do not with to ship inspector support in your production application, you can specify\nthat all support for it should be stripped from the build.\n\n```ts\nlet app = new EmberApp(defaults, {\n emberData: {\n includeDataAdapterInProduction: false\n }\n});\n```\n\n- [Full Documentation](https://api.emberjs.com/ember-data/release/modules/@ember-data%2Fdebug)\n\n### Debugging\n\nMany portions of the internals are helpfully instrumented with logging that can be activated\nat build time. This instrumentation is always removed from production builds or any builds\nthat has not explicitly activated it. To activate it set the appropriate flag to `true`.\n\n```ts\n let app = new EmberApp(defaults, {\n emberData: {\n debug: {\n LOG_PAYLOADS: false, // data store received to update cache with\n LOG_OPERATIONS: false, // updates to cache remote state\n LOG_MUTATIONS: false, // updates to cache local state\n LOG_NOTIFICATIONS: false,\n LOG_REQUESTS: false, // log Requests issued via the request manager\n LOG_REQUEST_STATUS: false,\n LOG_IDENTIFIERS: false,\n LOG_GRAPH: false,\n LOG_INSTANCE_CACHE: false,\n }\n }\n });\n ```", "itemtype": "main", "parent": null, "publicclasses": [], diff --git a/json-docs/ember-data/5.2.0/modules/ember-data-5.2.0-@ember-data/graph.json b/json-docs/ember-data/5.2.0/modules/ember-data-5.2.0-@ember-data/graph.json index cd6995c26..39977cae4 100644 --- a/json-docs/ember-data/5.2.0/modules/ember-data-5.2.0-@ember-data/graph.json +++ b/json-docs/ember-data/5.2.0/modules/ember-data-5.2.0-@ember-data/graph.json @@ -11,7 +11,7 @@ "tag": "main", "file": "../graph/src/-private.ts", "line": 3, - "description": "

\n \n

\n\n

Provides a performance tuned normalized graph for intelligently managing relationships between resources based on identity

\n\nWhile this Graph is abstract, it currently is a private implementation required as a peer-dependency by the [JSON:API Cache Implementation](https://github.com/emberjs/data/tree/main/packages/json-api).\n\nWe intend to make this Graph public API after some additional iteration during the 5.x timeframe, until then all APIs should be considered experimental and unstable, not fit for direct application or 3rd party library usage.\n\n## Installation\n\nInstall using your javascript package manager of choice. For instance with [pnpm](https://pnpm.io/)\n\n```no-highlight\npnpm add @ember-data/graph\n```", + "description": "

\n \n

\n\n

Provides a performance tuned normalized graph for intelligently managing relationships between resources based on identity

\n\nWhile this Graph is abstract, it currently is a private implementation required as a peer-dependency by the [JSON:API Cache Implementation](https://github.com/emberjs/data/tree/main/packages/json-api).\n\nWe intend to make this Graph public API after some additional iteration during the 5.x timeframe, until then all APIs should be considered experimental and unstable, not fit for direct application or 3rd party library usage.\n\n## Installation\n\nInstall using your javascript package manager of choice. For instance with [pnpm](https://pnpm.io/)\n\n```\npnpm add @ember-data/graph\n```", "itemtype": "main", "parent": null, "publicclasses": [], diff --git a/json-docs/ember-data/5.2.0/modules/ember-data-5.2.0-@ember-data/json-api.json b/json-docs/ember-data/5.2.0/modules/ember-data-5.2.0-@ember-data/json-api.json index 818fcfd1a..cb2754ce4 100644 --- a/json-docs/ember-data/5.2.0/modules/ember-data-5.2.0-@ember-data/json-api.json +++ b/json-docs/ember-data/5.2.0/modules/ember-data-5.2.0-@ember-data/json-api.json @@ -11,7 +11,7 @@ "tag": "main", "file": "../json-api/src/-private/cache.ts", "line": 84, - "description": "

\n \n

\n\nThis package provides an in-memory [JSON:API](https://jsonapi.org/) document and resource [*Ember***Data** Cache](https://github.com/emberjs/data/blob/main/ember-data-types/cache/cache.ts) implementation.\n\n## Installation\n\nInstall using your javascript package manager of choice. For instance with [pnpm](https://pnpm.io/)\n\n```no-highlight\npnpm add @ember-data/json-api\n```\n\n## πŸš€ Setup\n\n> **Note** When using [ember-data](https://github.com/emberjs/data/blob/main/packages/-ember-data) the below\n> configuration is handled for you automatically.\n\n```ts\nimport Store from '@ember-data/store';\nimport Cache from '@ember-data/json-api';\n\nexport default class extends Store {\n createCache(wrapper) {\n return new Cache(wrapper);\n }\n}\n```\n\n\n## Usage\n\nUsually you will directly interact with the cache only if implementing a presentation class. Below we\ngive an example of a read-only record (mutations never written back to the cache). More typically cache\ninteractions are something that the `Store` coordinates as part of the `request/response` lifecycle.\n\n```ts\nimport Store, { recordIdentifierFor } from '@ember-data/store';\nimport Cache from '@ember-data/json-api';\nimport { TrackedObject } from 'tracked-built-ins';\n\nclass extends Store {\n createCache(wrapper) {\n return new Cache(wrapper);\n }\n\n instantiateRecord(identifier) {\n const { cache, notifications } = this;\n const { type, id } = identifier;\n\n // create a TrackedObject with our attributes, id and type\n const attrs = cache.peek(identifier).attributes;\n const data = Object.assign({}, attrs, { type, id });\n const record = new TrackedObject(data);\n\n // update the TrackedObject whenever attributes change\n const token = notifications.subscribe(identifier, (_, change) => {\n if (change === 'attributes') {\n Object.assign(record, cache.peek(identifier).attributes);\n }\n });\n\n // setup the ability to teardown the subscription when the\n // record is no longer needed\n record.destroy = () => {\n this.notifications.unsubscribe(token);\n };\n\n return record;\n }\n\n teardownRecord(record: FakeRecord) {\n record.destroy();\n }\n}\n```\n\nFor the full list of APIs available read the code documentation for [*Ember***Data** Cache](https://github.com/emberjs/data/blob/main/ember-data-types/cache/cache.ts)", + "description": "

\n \n

\n\nThis package provides an in-memory [JSON:API](https://jsonapi.org/) document and resource [*Ember***Data** Cache](https://github.com/emberjs/data/blob/main/ember-data-types/cache/cache.ts) implementation.\n\n## Installation\n\nInstall using your javascript package manager of choice. For instance with [pnpm](https://pnpm.io/)\n\n```\npnpm add @ember-data/json-api\n```\n\n## πŸš€ Setup\n\n> **Note** When using [ember-data](https://github.com/emberjs/data/blob/main/packages/-ember-data) the below\n> configuration is handled for you automatically.\n\n```ts\nimport Store from '@ember-data/store';\nimport Cache from '@ember-data/json-api';\n\nexport default class extends Store {\n createCache(wrapper) {\n return new Cache(wrapper);\n }\n}\n```\n\n\n## Usage\n\nUsually you will directly interact with the cache only if implementing a presentation class. Below we\ngive an example of a read-only record (mutations never written back to the cache). More typically cache\ninteractions are something that the `Store` coordinates as part of the `request/response` lifecycle.\n\n```ts\nimport Store, { recordIdentifierFor } from '@ember-data/store';\nimport Cache from '@ember-data/json-api';\nimport { TrackedObject } from 'tracked-built-ins';\n\nclass extends Store {\n createCache(wrapper) {\n return new Cache(wrapper);\n }\n\n instantiateRecord(identifier) {\n const { cache, notifications } = this;\n const { type, id } = identifier;\n\n // create a TrackedObject with our attributes, id and type\n const attrs = cache.peek(identifier).attributes;\n const data = Object.assign({}, attrs, { type, id });\n const record = new TrackedObject(data);\n\n // update the TrackedObject whenever attributes change\n const token = notifications.subscribe(identifier, (_, change) => {\n if (change === 'attributes') {\n Object.assign(record, cache.peek(identifier).attributes);\n }\n });\n\n // setup the ability to teardown the subscription when the\n // record is no longer needed\n record.destroy = () => {\n this.notifications.unsubscribe(token);\n };\n\n return record;\n }\n\n teardownRecord(record: FakeRecord) {\n record.destroy();\n }\n}\n```\n\nFor the full list of APIs available read the code documentation for [*Ember***Data** Cache](https://github.com/emberjs/data/blob/main/ember-data-types/cache/cache.ts)", "itemtype": "main", "parent": null, "publicclasses": [ diff --git a/json-docs/ember-data/5.2.0/modules/ember-data-5.2.0-@ember-data/request.json b/json-docs/ember-data/5.2.0/modules/ember-data-5.2.0-@ember-data/request.json index 046c2adb0..8415929f1 100644 --- a/json-docs/ember-data/5.2.0/modules/ember-data-5.2.0-@ember-data/request.json +++ b/json-docs/ember-data/5.2.0/modules/ember-data-5.2.0-@ember-data/request.json @@ -11,7 +11,7 @@ "tag": "main", "file": "../request/src/-private/types.ts", "line": 202, - "description": "

\n \n

\n\n

⚑️ a simple abstraction over fetch to enable easy management of request/response flows

\n\nThis package provides [*Ember*‍**Data**](https://github.com/emberjs/data/)'s `RequestManager`, a framework agnostic library that can be integrated with any Javascript application to make [fetch](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) happen.\n\n## Installation\n\nInstall using your javascript package manager of choice. For instance with [pnpm](https://pnpm.io/)\n\n```no-highlight\npnpm add @ember-data/request\n```\n\n## πŸš€ Basic Usage\n\nA `RequestManager` provides a request/response flow in which configured handlers are successively given the opportunity to handle, modify, or pass-along a request.\n\nThe RequestManager on its own does not know how to fulfill requests. For this we must register at least one handler. A basic `Fetch` handler is provided that will take the request options provided and execute `fetch`.\n\n```ts\nimport RequestManager from '@ember-data/request';\nimport Fetch from '@ember-data/request/fetch';\nimport { apiUrl } from './config';\n\n// ... create manager and add our Fetch handler\nconst manager = new RequestManager();\nmanager.use([Fetch]);\n\n// ... execute a request\nconst response = await manager.request({\n url: `${apiUrl}/users`\n});\n```\n\n\n## πŸͺœ Architecture\n\nA `RequestManager` receives a request and manages fulfillment via configured handlers. It may be used standalone from the rest of *Ember*‍**Data** and is not specific to any library or framework.\n\nEach handler may choose to fulfill the request using some source of data or to pass the request along to other handlers.\n\nThe same or a separate instance of a `RequestManager` may also be used to fulfill requests issued by [*Ember*‍**Data**{Store}](https://github.com/emberjs/data/tree/main/packages/store)\n\nWhen the same instance is used by both this allows for simple coordination throughout the application. Requests issued by the Store will use the in-memory cache\nand return hydrated responses, requests issued directly to the RequestManager\nwill skip the in-memory cache and return raw responses.\n\n## Usage\n\n```ts\nconst userList = await manager.request({\n url: `/api/v1/users.list`\n});\n\nconst users = userList.content;\n```\n\n
\n Making Requests\n\n`RequestManager` has a single asyncronous method as it's API: `request`\n\n```ts\nclass RequestManager {\n request(req: RequestInfo): Future;\n}\n```\n\n`manager.request()` accepts an object containing the information\nnecessary for the request to be handled successfully.\n\nThese options extend the [options](https://developer.mozilla.org/en-US/docs/Web/API/fetch#parameters) provided to `fetch`, and can accept a [`Request`](https://developer.mozilla.org/en-US/docs/Web/API/Request/Request). All properties accepted by Request options and fetch options are valid.\n\n```ts\ninterface RequestInfo extends FetchOptions {\n op?: string;\n store?: Store;\nurl: string;\n // data that a handler should convert into\n // the query (GET) or body (POST)\n data?: Record;\n// options specifically intended for handlers\n // to utilize to process the request\n options?: Record;\n}\n```\n\n> **note:** providing a `signal` is unnecessary as an `AbortController` is automatically provided if none is present.\n\n
\n
\n Using the Response
\n\n`manager.request` returns a `Future`, which allows access to limited information about the request while it is still pending and fulfills with the final state when the request completes and the response has been read.\n\n```ts\nconst usersFuture = manager.request({\n url: `/api/v1/users.list`\n});\n```\n\nA `Future` is cancellable via `abort`.\n\n```ts\nusersFuture.abort();\n```\n\nHandlers may *optionally* expose a ReadableStream to the `Future` for streaming data; however, when doing so the handler should not resolve until it has fully read the response stream itself.\n\n```ts\ninterface Future extends Promise> {\n abort(): void;\nasync getStream(): ReadableStream | null;\n}\n```\n\nA Future resolves or rejects with a `StructuredDocument`.\n\n```ts\ninterface StructuredDocument {\n request: RequestInfo;\n response: ResponseInfo | null;\n content?: T;\n error?: Error;\n}\n```\n\nThe `RequestInfo` specified by `document.request` is the same as originally provided to `manager.request`. If any handler fulfilled this request using different request info it is not represented here. This contract helps to ensure that `retry` and `caching` are possible since the original arguments are correctly preserved. This also allows handlers to \"fork\" the request or fulfill from multiple sources without the details of fulfillment muddying the original request.\n\nThe `ResponseInfo` is a serializable fulfilled subset of a [Response](https://developer.mozilla.org/en-US/docs/Web/API/Response) if set via `setResponse`. If no response was ever set this will be `null`.\n\n```ts\ninterface ResponseInfo {\n headers?: Record;\n ok?: boolean;\n redirected?: boolean;\n status?: HTTPStatusCode;\n statusText?: string;\n type?: 'basic' | 'cors';\n url?: string;\n}\n```\n\n
\n\n

Handling Requests

\n
\n { request(context, next): Promise | Future; }
\n\nRequests are fulfilled by handlers. A handler receives the request context\nas well as a `next` function with which to pass along a request to the next\nhandler if it so chooses.\n\nA handler may be any object with a `request` method. This allows both stateful and non-stateful\nhandlers to be utilized.\n\nIf a handler calls `next`, it receives a `Future` which resolves to a `StructuredDocument`\nthat it can then compose how it sees fit with its own response.\n\n```ts\n\ntype NextFn

= (req: RequestInfo) => Future

;\n\ninterface Handler {\n async request(context: RequestContext, next: NextFn

): T;\n}\n```\n\n`RequestContext` contains a readonly version of the RequestInfo as well as a few methods for building up the `StructuredDocument` and `Future` that will be part of the response.\n\n```ts\ninterface RequestContext {\n readonly request: RequestInfo;\nsetStream(stream: ReadableStream | Promise): void;\n setResponse(response: Response | ResponseInfo): void;\n}\n```\n\nA basic `fetch` handler with support for streaming content updates while\nthe download is still underway might look like the following, where we use\n[`response.clone()`](https://developer.mozilla.org/en-US/docs/Web/API/Response/clone) to `tee` the `ReadableStream` into two streams.\n\nA more efficient handler might read from the response stream, building up the\nresponse content before passing along the chunk downstream.\n\n```ts\nconst FetchHandler = {\n async request(context) {\n const response = await fetch(context.request);\n context.setResponse(reponse);\n context.setStream(response.clone().body);\n return response.json();\n }\n}\n```\n\nRequest handlers are registered by configuring the manager via `use`\n\n```ts\nmanager.use([Handler1, Handler2])\n```\n\nHandlers will be invoked in the order they are registered (\"fifo\", first-in first-out), and may only be registered up until the first request is made. It is recommended but not required to register all handlers at one time in order to ensure explicitly visible handler ordering.\n\n

\n\n\n
\n Error Handling
\nEach handler in the chain can catch errors from upstream and choose to\n either handle the error, re-throw the error, or throw a new error.\n```ts\n const MAX_RETRIES = 5;\nconst Handler = {\n async request(context, next) {\n let attempts = 0;\n while (attempts < MAX_RETRIES) {\n attempts++;\n try {\n const response = await next(context.request);\n return response;\n } catch (e) {\n if (isTimeoutError(e) && attempts < MAX_RETRIES) {\n // retry request\n continue;\n }\n // rethrow if it is not a timeout error\n throw e;\n }\n }\n }\n }\n ```\n
\n\n
\n Handling Abort
\nAborting a request will reject the current handler in the chain. However,\n every handler can potentially catch this error. If your handler needs to\n separate AbortError from other Error types, it is recommended to check\n `context.request.signal.aborted` (or if a custom controller was supplied `controller.signal.aborted`).\nIn this manner it is possible for a request to recover from an abort and\n still proceed; however, as a best practice this should be used for necessary\n cleanup only and the original AbortError rethrown if the abort signal comes\n from the root controller.\n\n*AbortControllers are Always Present and Always Entangled**\nIf the initial request does not supply an [AbortController](https://developer.mozilla.org/en-US/docs/Web/API/AbortController), one will be generated.\nThe [signal](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) for this controller is automatically added to the request passed into the first handler.\nEach handler has the option to supply a new controller to the request when calling `next`. If a new controller is provided it will be automatically\n entangled with the root controller. If the root controller aborts, so will\n any entangled controllers.\nIf an entangled controller aborts, the root controller will not abort. This\n allows for advanced request-flow scenarios to abort subsections of the request tree without aborting the entire request.\n\n
\n\n\n
\n Stream Currying
\n\n`RequestManager.request` and `next` differ from `fetch` in one **crucial detail** in that the outer Promise resolves only once the response stream has been processed.\n\nFor context, it helps to understand a few of the use-cases that RequestManager\nis intended to allow.\n\n- to manage and return streaming content (such as video files)\n- to fulfill a request from multiple sources or by splitting one request into multiple requests\n - for instance one API call for a user and another for the user's friends\n - or e.g. fulfilling part of the request from one source (one API, in-memory, localStorage, IndexedDB\n etc.) and the rest from another source (a different API, a WebWorker, etc.)\n- to coalesce multiple requests\n- to decorate a request with additional info\n - e.g. an Auth handler that ensures the correct tokens or headers or cookies are attached.\n\n\n`await fetch()` resolves at the moment headers are received. This allows for the body of the request to be processed as a stream by application\ncode *while chunks are still being received by the browser*.\n\nWhen an app chooses to `await response.json()` what occurs is the browser reads the stream to completion and then returns the result. Additionally, this stream may only be read **once**.\n\nThe `RequestManager` preserves this ability to subscribe to and utilize the stream by either the application or the handler – thereby delivering the full power and flexibility of native APIs – without restricting developers in ways that lead to complicated workarounds.\n\nEach handler may call `setStream` only once, but may do so *at any time* until the promise that the handler returns has resolved. The associated promise returned by calling `future.getStream` will resolve with the stream set by `setStream` if that method is called, or `null` if that method\nhas not been called by the time that the handler's request method has resolved.\n\nHandlers that do not create a stream of their own, but which call `next`, should defensively pipe the stream forward. While this is not required (see automatic currying below) it is better to do so in most cases as otherwise the stream may not become available to downstream handlers or the application until the upstream handler has fully read it.\n\n```ts\ncontext.setStream(future.getStream());\n```\n\nHandlers that either call `next` multiple times or otherwise have reason to create multiple fetch requests should either choose to return no stream, meaningfully combine the streams, or select a single prioritized stream.\n\nOf course, any handler may choose to read and handle the stream, and return either no stream or a different stream in the process.\n\n
\n\n
\n Automatic Currying of Stream and Response
\n\nIn order to simplify the common case for handlers which decorate a request, if `next` is called only a single time and `setResponse` was never called by the handler, the response set by the next handler in the chain will be applied to that handler's outcome. For instance, this makes the following pattern possible `return (await next()).content;`.\n\nSimilarly, if `next` is called only a single time and neither `setStream` nor `getStream` was called, we automatically curry the stream from the future returned by `next` onto the future returned by the handler.\n\nFinally, if the return value of a handler is a `Future`, we curry `content` and `errors` as well, thus enabling the simplest form `return next()`.\n\nIn the case of the `Future` being returned, `Stream` proxying is automatic and immediate and does not wait for the `Future` to resolve.\n\n
\n\n### Using as a Service\n\nMost applications will desire to have a single `RequestManager` instance, which can be achieved using module-state patterns for singletons, or for [Ember](https://emberjs.com) applications by exporting the manager as a [service](https://guides.emberjs.com/release/services/).\n\nservices/request.ts*\n```ts\nimport RequestManager from '@ember-data/request';\nimport Fetch from '@ember-data/request/fetch';\nimport Auth from 'ember-simple-auth/ember-data-handler';\n\nexport default class extends RequestManager {\n constructor(createArgs) {\n super(createArgs);\n this.use([Auth, Fetch]);\n }\n}\n```\n\n### Using with `@ember-data/store`\n\nTo have a request service unique to a Store:\n\n```ts\nimport Store, { CacheHandler } from '@ember-data/store';\nimport RequestManager from '@ember-data/request';\nimport Fetch from '@ember-data/request/fetch';\n\nclass extends Store {\n requestManager = new RequestManager();\nconstructor(args) {\n super(args);\n this.requestManager.use([Fetch]);\n this.requestManager.useCache(CacheHandler);\n }\n}\n```\n\n### Using with `ember-data`\n\nIf using the package [ember-data](https://github.com/emberjs/data/tree/main/packages/-ember-data), the following configuration will automatically be done in order to preserve the legacy [Adapter](https://github.com/emberjs/data/tree/main/packages/adapter) and [Serializer](https://github.com/emberjs/data/tree/main/packages/serializer) behavior. Additional handlers or a service injection like the above would need to be done by the consuming application in order to make broader use of `RequestManager`.\n\n```ts\nimport Store, { CacheHandler } from '@ember-data/store';\nimport RequestManager from '@ember-data/request';\nimport { LegacyNetworkHandler } from '@ember-data/legacy-compat';\n\nexport default class extends Store {\n requestManager = new RequestManager();\nconstructor(args) {\n super(args);\n this.requestManager.use([LegacyNetworkHandler]);\n this.requestManager.useCache(CacheHandler);\n }\n}\n```\n\nBecause the application's store service (if present) will override the store supplied by `ember-data`, all that is required to define your own ordering and handlers is to supply a store service extending from `@ember-data/store` and configure as shown above.\n\nFor usage of the store's `requestManager` via `store.request()` see the [Store](https://api.emberjs.com/ember-data/release/modules/@ember-data%2Fstore) documentation.", + "description": "

\n \n

\n\n

⚑️ a simple abstraction over fetch to enable easy management of request/response flows

\n\nThis package provides [*Ember*‍**Data**](https://github.com/emberjs/data/)'s `RequestManager`, a framework agnostic library that can be integrated with any Javascript application to make [fetch](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) happen.\n\n## Installation\n\nInstall using your javascript package manager of choice. For instance with [pnpm](https://pnpm.io/)\n\n```\npnpm add @ember-data/request\n```\n\n## πŸš€ Basic Usage\n\nA `RequestManager` provides a request/response flow in which configured handlers are successively given the opportunity to handle, modify, or pass-along a request.\n\nThe RequestManager on its own does not know how to fulfill requests. For this we must register at least one handler. A basic `Fetch` handler is provided that will take the request options provided and execute `fetch`.\n\n```ts\nimport RequestManager from '@ember-data/request';\nimport Fetch from '@ember-data/request/fetch';\nimport { apiUrl } from './config';\n\n// ... create manager and add our Fetch handler\nconst manager = new RequestManager();\nmanager.use([Fetch]);\n\n// ... execute a request\nconst response = await manager.request({\n url: `${apiUrl}/users`\n});\n```\n\n\n## πŸͺœ Architecture\n\nA `RequestManager` receives a request and manages fulfillment via configured handlers. It may be used standalone from the rest of *Ember*‍**Data** and is not specific to any library or framework.\n\nEach handler may choose to fulfill the request using some source of data or to pass the request along to other handlers.\n\nThe same or a separate instance of a `RequestManager` may also be used to fulfill requests issued by [*Ember*‍**Data**{Store}](https://github.com/emberjs/data/tree/main/packages/store)\n\nWhen the same instance is used by both this allows for simple coordination throughout the application. Requests issued by the Store will use the in-memory cache\nand return hydrated responses, requests issued directly to the RequestManager\nwill skip the in-memory cache and return raw responses.\n\n## Usage\n\n```ts\nconst userList = await manager.request({\n url: `/api/v1/users.list`\n});\n\nconst users = userList.content;\n```\n\n
\n Making Requests\n\n`RequestManager` has a single asyncronous method as it's API: `request`\n\n```ts\nclass RequestManager {\n request(req: RequestInfo): Future;\n}\n```\n\n`manager.request()` accepts an object containing the information\nnecessary for the request to be handled successfully.\n\nThese options extend the [options](https://developer.mozilla.org/en-US/docs/Web/API/fetch#parameters) provided to `fetch`, and can accept a [`Request`](https://developer.mozilla.org/en-US/docs/Web/API/Request/Request). All properties accepted by Request options and fetch options are valid.\n\n```ts\ninterface RequestInfo extends FetchOptions {\n op?: string;\n store?: Store;\nurl: string;\n // data that a handler should convert into\n // the query (GET) or body (POST)\n data?: Record;\n// options specifically intended for handlers\n // to utilize to process the request\n options?: Record;\n}\n```\n\n> **note:** providing a `signal` is unnecessary as an `AbortController` is automatically provided if none is present.\n\n
\n
\n Using the Response
\n\n`manager.request` returns a `Future`, which allows access to limited information about the request while it is still pending and fulfills with the final state when the request completes and the response has been read.\n\n```ts\nconst usersFuture = manager.request({\n url: `/api/v1/users.list`\n});\n```\n\nA `Future` is cancellable via `abort`.\n\n```ts\nusersFuture.abort();\n```\n\nHandlers may *optionally* expose a ReadableStream to the `Future` for streaming data; however, when doing so the handler should not resolve until it has fully read the response stream itself.\n\n```ts\ninterface Future extends Promise> {\n abort(): void;\nasync getStream(): ReadableStream | null;\n}\n```\n\nA Future resolves or rejects with a `StructuredDocument`.\n\n```ts\ninterface StructuredDocument {\n request: RequestInfo;\n response: ResponseInfo | null;\n content?: T;\n error?: Error;\n}\n```\n\nThe `RequestInfo` specified by `document.request` is the same as originally provided to `manager.request`. If any handler fulfilled this request using different request info it is not represented here. This contract helps to ensure that `retry` and `caching` are possible since the original arguments are correctly preserved. This also allows handlers to \"fork\" the request or fulfill from multiple sources without the details of fulfillment muddying the original request.\n\nThe `ResponseInfo` is a serializable fulfilled subset of a [Response](https://developer.mozilla.org/en-US/docs/Web/API/Response) if set via `setResponse`. If no response was ever set this will be `null`.\n\n```ts\ninterface ResponseInfo {\n headers?: Record;\n ok?: boolean;\n redirected?: boolean;\n status?: HTTPStatusCode;\n statusText?: string;\n type?: 'basic' | 'cors';\n url?: string;\n}\n```\n\n
\n\n

Handling Requests

\n
\n { request(context, next): Promise | Future; }
\n\nRequests are fulfilled by handlers. A handler receives the request context\nas well as a `next` function with which to pass along a request to the next\nhandler if it so chooses.\n\nA handler may be any object with a `request` method. This allows both stateful and non-stateful\nhandlers to be utilized.\n\nIf a handler calls `next`, it receives a `Future` which resolves to a `StructuredDocument`\nthat it can then compose how it sees fit with its own response.\n\n```ts\n\ntype NextFn

= (req: RequestInfo) => Future

;\n\ninterface Handler {\n async request(context: RequestContext, next: NextFn

): T;\n}\n```\n\n`RequestContext` contains a readonly version of the RequestInfo as well as a few methods for building up the `StructuredDocument` and `Future` that will be part of the response.\n\n```ts\ninterface RequestContext {\n readonly request: RequestInfo;\nsetStream(stream: ReadableStream | Promise): void;\n setResponse(response: Response | ResponseInfo): void;\n}\n```\n\nA basic `fetch` handler with support for streaming content updates while\nthe download is still underway might look like the following, where we use\n[`response.clone()`](https://developer.mozilla.org/en-US/docs/Web/API/Response/clone) to `tee` the `ReadableStream` into two streams.\n\nA more efficient handler might read from the response stream, building up the\nresponse content before passing along the chunk downstream.\n\n```ts\nconst FetchHandler = {\n async request(context) {\n const response = await fetch(context.request);\n context.setResponse(reponse);\n context.setStream(response.clone().body);\n return response.json();\n }\n}\n```\n\nRequest handlers are registered by configuring the manager via `use`\n\n```ts\nmanager.use([Handler1, Handler2])\n```\n\nHandlers will be invoked in the order they are registered (\"fifo\", first-in first-out), and may only be registered up until the first request is made. It is recommended but not required to register all handlers at one time in order to ensure explicitly visible handler ordering.\n\n

\n\n\n
\n Error Handling
\nEach handler in the chain can catch errors from upstream and choose to\n either handle the error, re-throw the error, or throw a new error.\n```ts\n const MAX_RETRIES = 5;\nconst Handler = {\n async request(context, next) {\n let attempts = 0;\n while (attempts < MAX_RETRIES) {\n attempts++;\n try {\n const response = await next(context.request);\n return response;\n } catch (e) {\n if (isTimeoutError(e) && attempts < MAX_RETRIES) {\n // retry request\n continue;\n }\n // rethrow if it is not a timeout error\n throw e;\n }\n }\n }\n }\n ```\n
\n\n
\n Handling Abort
\nAborting a request will reject the current handler in the chain. However,\n every handler can potentially catch this error. If your handler needs to\n separate AbortError from other Error types, it is recommended to check\n `context.request.signal.aborted` (or if a custom controller was supplied `controller.signal.aborted`).\nIn this manner it is possible for a request to recover from an abort and\n still proceed; however, as a best practice this should be used for necessary\n cleanup only and the original AbortError rethrown if the abort signal comes\n from the root controller.\n\n*AbortControllers are Always Present and Always Entangled**\nIf the initial request does not supply an [AbortController](https://developer.mozilla.org/en-US/docs/Web/API/AbortController), one will be generated.\nThe [signal](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) for this controller is automatically added to the request passed into the first handler.\nEach handler has the option to supply a new controller to the request when calling `next`. If a new controller is provided it will be automatically\n entangled with the root controller. If the root controller aborts, so will\n any entangled controllers.\nIf an entangled controller aborts, the root controller will not abort. This\n allows for advanced request-flow scenarios to abort subsections of the request tree without aborting the entire request.\n\n
\n\n\n
\n Stream Currying
\n\n`RequestManager.request` and `next` differ from `fetch` in one **crucial detail** in that the outer Promise resolves only once the response stream has been processed.\n\nFor context, it helps to understand a few of the use-cases that RequestManager\nis intended to allow.\n\n- to manage and return streaming content (such as video files)\n- to fulfill a request from multiple sources or by splitting one request into multiple requests\n - for instance one API call for a user and another for the user's friends\n - or e.g. fulfilling part of the request from one source (one API, in-memory, localStorage, IndexedDB\n etc.) and the rest from another source (a different API, a WebWorker, etc.)\n- to coalesce multiple requests\n- to decorate a request with additional info\n - e.g. an Auth handler that ensures the correct tokens or headers or cookies are attached.\n\n\n`await fetch()` resolves at the moment headers are received. This allows for the body of the request to be processed as a stream by application\ncode *while chunks are still being received by the browser*.\n\nWhen an app chooses to `await response.json()` what occurs is the browser reads the stream to completion and then returns the result. Additionally, this stream may only be read **once**.\n\nThe `RequestManager` preserves this ability to subscribe to and utilize the stream by either the application or the handler – thereby delivering the full power and flexibility of native APIs – without restricting developers in ways that lead to complicated workarounds.\n\nEach handler may call `setStream` only once, but may do so *at any time* until the promise that the handler returns has resolved. The associated promise returned by calling `future.getStream` will resolve with the stream set by `setStream` if that method is called, or `null` if that method\nhas not been called by the time that the handler's request method has resolved.\n\nHandlers that do not create a stream of their own, but which call `next`, should defensively pipe the stream forward. While this is not required (see automatic currying below) it is better to do so in most cases as otherwise the stream may not become available to downstream handlers or the application until the upstream handler has fully read it.\n\n```ts\ncontext.setStream(future.getStream());\n```\n\nHandlers that either call `next` multiple times or otherwise have reason to create multiple fetch requests should either choose to return no stream, meaningfully combine the streams, or select a single prioritized stream.\n\nOf course, any handler may choose to read and handle the stream, and return either no stream or a different stream in the process.\n\n
\n\n
\n Automatic Currying of Stream and Response
\n\nIn order to simplify the common case for handlers which decorate a request, if `next` is called only a single time and `setResponse` was never called by the handler, the response set by the next handler in the chain will be applied to that handler's outcome. For instance, this makes the following pattern possible `return (await next()).content;`.\n\nSimilarly, if `next` is called only a single time and neither `setStream` nor `getStream` was called, we automatically curry the stream from the future returned by `next` onto the future returned by the handler.\n\nFinally, if the return value of a handler is a `Future`, we curry `content` and `errors` as well, thus enabling the simplest form `return next()`.\n\nIn the case of the `Future` being returned, `Stream` proxying is automatic and immediate and does not wait for the `Future` to resolve.\n\n
\n\n### Using as a Service\n\nMost applications will desire to have a single `RequestManager` instance, which can be achieved using module-state patterns for singletons, or for [Ember](https://emberjs.com) applications by exporting the manager as a [service](https://guides.emberjs.com/release/services/).\n\nservices/request.ts*\n```ts\nimport RequestManager from '@ember-data/request';\nimport Fetch from '@ember-data/request/fetch';\nimport Auth from 'ember-simple-auth/ember-data-handler';\n\nexport default class extends RequestManager {\n constructor(createArgs) {\n super(createArgs);\n this.use([Auth, Fetch]);\n }\n}\n```\n\n### Using with `@ember-data/store`\n\nTo have a request service unique to a Store:\n\n```ts\nimport Store, { CacheHandler } from '@ember-data/store';\nimport RequestManager from '@ember-data/request';\nimport Fetch from '@ember-data/request/fetch';\n\nclass extends Store {\n requestManager = new RequestManager();\nconstructor(args) {\n super(args);\n this.requestManager.use([Fetch]);\n this.requestManager.useCache(CacheHandler);\n }\n}\n```\n\n### Using with `ember-data`\n\nIf using the package [ember-data](https://github.com/emberjs/data/tree/main/packages/-ember-data), the following configuration will automatically be done in order to preserve the legacy [Adapter](https://github.com/emberjs/data/tree/main/packages/adapter) and [Serializer](https://github.com/emberjs/data/tree/main/packages/serializer) behavior. Additional handlers or a service injection like the above would need to be done by the consuming application in order to make broader use of `RequestManager`.\n\n```ts\nimport Store, { CacheHandler } from '@ember-data/store';\nimport RequestManager from '@ember-data/request';\nimport { LegacyNetworkHandler } from '@ember-data/legacy-compat';\n\nexport default class extends Store {\n requestManager = new RequestManager();\nconstructor(args) {\n super(args);\n this.requestManager.use([LegacyNetworkHandler]);\n this.requestManager.useCache(CacheHandler);\n }\n}\n```\n\nBecause the application's store service (if present) will override the store supplied by `ember-data`, all that is required to define your own ordering and handlers is to supply a store service extending from `@ember-data/store` and configure as shown above.\n\nFor usage of the store's `requestManager` via `store.request()` see the [Store](https://api.emberjs.com/ember-data/release/modules/@ember-data%2Fstore) documentation.", "itemtype": "main", "parent": null, "publicclasses": [ diff --git a/json-docs/ember-data/5.2.0/modules/ember-data-5.2.0-ember-data-overview.json b/json-docs/ember-data/5.2.0/modules/ember-data-5.2.0-ember-data-overview.json index b72aaa4f7..fdf570b6c 100644 --- a/json-docs/ember-data/5.2.0/modules/ember-data-5.2.0-ember-data-overview.json +++ b/json-docs/ember-data/5.2.0/modules/ember-data-5.2.0-ember-data-overview.json @@ -11,7 +11,7 @@ "tag": "main", "file": "../-ember-data/addon/index.js", "line": 1, - "description": "

\n \n

\n\n

The lightweight reactive data library for JavaScript applications

\n\n---\n\nWrangle your application's data management with scalable patterns for developer productivity.\n\n- ⚑️ Committed to Best-In-Class Performance\n- 🌲 Focused on being as svelte as possible\n- πŸš€ SSR Ready\n- πŸ”œ Typescript Support\n- 🐹 Built with β™₯️ by [Ember](https://emberjs.com)\n- βš›οΈ Supports any API: `GraphQL` `JSON:API` `REST` `tRPC` ...bespoke or a mix\n\n### πŸ“– On This Page\n\n- [Overview](./#overview)\n - [Architecture](#πŸͺœ-architecture)\n - [Basic Installation](#basic-installation)\n - [Advanced Installation](#advanced-installation)\n- [Configuration](#configuration)\n - [Deprecation Stripping](#deprecation-stripping)\n - [randomUUID polyfill](#randomuuid-polyfill)\n - [Removing inspector support in production](#removing-inspector-support-in-production)\n - [Debugging](#debugging)\n\n\n# Overview\n\n*Ember*‍**Data** is a lightweight reactive data library for JavaScript applications that provides composable primitives for ordering query/mutation/peek flows, managing network and cache, and reducing data for presentation.\n\n## πŸͺœ Architecture\n\nThe core of *Ember*‍**Data** is the `Store`, which coordinates interaction between your application, the `Cache`, and sources of data (such as your `API` or a local persistence layer).\nOptionally, the Store can be configured to hydrate the response data into rich presentation classes.\n\n*Ember*‍**Data** is both resource centric and document centric in it's approach to caching, requesting and presenting data. Your application's configuration and usage drives which is important and when.\n\nThe `Store` is a **coordinator**. When using a `Store` you configure what cache to use, how cache data should be presented to the UI, and where it should look for requested data when it is not available in the cache.\n\nThis coordination is handled opaquely to the nature of the requests issued and the format of the data being handled. This approach gives applications broad flexibility to configure *Ember*‍**Data** to best suite their needs. This makes *Ember*‍**Data** a powerful solution for applications regardless of their size and complexity.\n\n*Ember*‍**Data** is designed to scale, with a religious focus on performance and asset-size to keep its footprint small but speedy while still being able to handle large complex APIs in huge data-driven applications with no additional code and no added application complexity. It's goal is to prevent applications from writing code to manage data that is difficult to maintain or reason about.\n\n*Ember*‍**Data**'s power comes not from specific features, data formats, or adherence to specific API specs such as `JSON:API` `trpc` or `GraphQL`, but from solid conventions around requesting and mutating data developed over decades of experience scaling developer productivity.\n\n## Basic Installation\n\nInstall using your javascript package manager of choice. For instance with [pnpm](https://pnpm.io/)\n\n```no-highlight\npnpm add ember-data\n```\n\n`ember-data` is installed by default for new applications generated with `ember-cli`. You can check what version is installed by looking in the `devDependencies` hash of your project's [package.json](https://docs.npmjs.com/cli/v8/configuring-npm/package-json) file.\n\nIf you have generated a new `Ember` application using `ember-cli` but do\nnot wish to use `ember-data`, remove `ember-data` from your project's `package.json` file and run your package manager's install command to update your lockfile.\n\n## Advanced Installation\n\n*Ember*‍**Data** is organized into primitives that compose together via public APIs.\n\n- [@ember-data/store](/ember-data/release/modules/@ember-data%2Fstore) is the core and handles coordination\n- [@ember-data/json-api](/ember-data/release/modules/@ember-data%2Fjson-api) provides a resource cache for JSON:API structured data. It integrates with the store via the hook `createCache`\n- [@ember-data/model](/ember-data/release/modules/@ember-data%2Fmodel) is a presentation layer, it integrates with the store via the hooks `instantiateRecord` and `teardownRecord`.\n- [@ember-data/adapter](/ember-data/release/modules/@ember-data%2Fadapter) provides various network API integrations for APIS built over specific REST or JSON:API conventions.\n- [@ember-data/serializer](/ember-data/release/modules/@ember-data%2Fserializer) pairs with `@ember-data/adapter` to normalize and serialize data to and from an API format into the `JSON:API` format understood by `@ember-data/json-api`.\n- [@ember-data/debug](/ember-data/release/modules/@ember-data%2Fdebug) provides debugging support for the `ember-inspector`.\n- **ember-data** is a \"meta\" package which bundles all of these together for convenience\n\nThe packages interop with each other through well defined public API boundaries. The core\nof the library is the store provided by `@ember-data/store`, while each of the other libraries plugs into the store when installed. Because these packages interop via fully\npublic APIs, other libraries or applications may provide their own implementations. For instance, [ember-m3](https://github.com/hjdivad/ember-m3) is a commonly used presentation and cache implementation suitable for complex resource objects and graphs.\n\n## Configuration\n\n### Deprecation Stripping\n\n*Ember*‍**Data** allows users to opt-in and remove code that exists to support deprecated behaviors.\n\nIf your app has resolved all deprecations present in a given version, you may specify that version as your \"compatibility\" version to remove the code that supported the deprecated behavior from your app.\n\n```ts\nlet app = new EmberApp(defaults, {\n emberData: {\n compatWith: '4.8',\n },\n});\n```\n\n- [Full Documentation](https://api.emberjs.com/ember-data/release/modules/@ember-data%2Fdeprecations)\n\n### randomUUID polyfill\n\n*Ember*‍**Data** uses `UUID V4` by default to generate identifiers for new data created on the client. Identifier generation is configurable, but we also for convenience will polyfill\nthe necessary feature if your browser support or deployment environment demands it. To\nactivate this polyfill:\n\n```ts\nlet app = new EmberApp(defaults, {\n '@embroider/macros': {\n setConfig: {\n '@ember-data/store': {\n polyfillUUID: true\n },\n },\n },\n});\n```\n\n### removing inspector support in production\n\nIf you do not with to ship inspector support in your production application, you can specify\nthat all support for it should be stripped from the build.\n\n```ts\nlet app = new EmberApp(defaults, {\n emberData: {\n includeDataAdapterInProduction: false\n }\n});\n```\n\n- [Full Documentation](https://api.emberjs.com/ember-data/release/modules/@ember-data%2Fdebug)\n\n### Debugging\n\nMany portions of the internals are helpfully instrumented with logging that can be activated\nat build time. This instrumentation is always removed from production builds or any builds\nthat has not explicitly activated it. To activate it set the appropriate flag to `true`.\n\n```ts\n let app = new EmberApp(defaults, {\n emberData: {\n debug: {\n LOG_PAYLOADS: false, // data store received to update cache with\n LOG_OPERATIONS: false, // updates to cache remote state\n LOG_MUTATIONS: false, // updates to cache local state\n LOG_NOTIFICATIONS: false,\n LOG_REQUESTS: false, // log Requests issued via the request manager\n LOG_REQUEST_STATUS: false,\n LOG_IDENTIFIERS: false,\n LOG_GRAPH: false,\n LOG_INSTANCE_CACHE: false,\n }\n }\n });\n ```", + "description": "

\n \n

\n\n

The lightweight reactive data library for JavaScript applications

\n\n---\n\nWrangle your application's data management with scalable patterns for developer productivity.\n\n- ⚑️ Committed to Best-In-Class Performance\n- 🌲 Focused on being as svelte as possible\n- πŸš€ SSR Ready\n- πŸ”œ Typescript Support\n- 🐹 Built with β™₯️ by [Ember](https://emberjs.com)\n- βš›οΈ Supports any API: `GraphQL` `JSON:API` `REST` `tRPC` ...bespoke or a mix\n\n### πŸ“– On This Page\n\n- [Overview](./#overview)\n - [Architecture](#πŸͺœ-architecture)\n - [Basic Installation](#basic-installation)\n - [Advanced Installation](#advanced-installation)\n- [Configuration](#configuration)\n - [Deprecation Stripping](#deprecation-stripping)\n - [randomUUID polyfill](#randomuuid-polyfill)\n - [Removing inspector support in production](#removing-inspector-support-in-production)\n - [Debugging](#debugging)\n\n\n# Overview\n\n*Ember*‍**Data** is a lightweight reactive data library for JavaScript applications that provides composable primitives for ordering query/mutation/peek flows, managing network and cache, and reducing data for presentation.\n\n## πŸͺœ Architecture\n\nThe core of *Ember*‍**Data** is the `Store`, which coordinates interaction between your application, the `Cache`, and sources of data (such as your `API` or a local persistence layer).\nOptionally, the Store can be configured to hydrate the response data into rich presentation classes.\n\n*Ember*‍**Data** is both resource centric and document centric in it's approach to caching, requesting and presenting data. Your application's configuration and usage drives which is important and when.\n\nThe `Store` is a **coordinator**. When using a `Store` you configure what cache to use, how cache data should be presented to the UI, and where it should look for requested data when it is not available in the cache.\n\nThis coordination is handled opaquely to the nature of the requests issued and the format of the data being handled. This approach gives applications broad flexibility to configure *Ember*‍**Data** to best suite their needs. This makes *Ember*‍**Data** a powerful solution for applications regardless of their size and complexity.\n\n*Ember*‍**Data** is designed to scale, with a religious focus on performance and asset-size to keep its footprint small but speedy while still being able to handle large complex APIs in huge data-driven applications with no additional code and no added application complexity. It's goal is to prevent applications from writing code to manage data that is difficult to maintain or reason about.\n\n*Ember*‍**Data**'s power comes not from specific features, data formats, or adherence to specific API specs such as `JSON:API` `trpc` or `GraphQL`, but from solid conventions around requesting and mutating data developed over decades of experience scaling developer productivity.\n\n## Basic Installation\n\nInstall using your javascript package manager of choice. For instance with [pnpm](https://pnpm.io/)\n\n```\npnpm add ember-data\n```\n\n`ember-data` is installed by default for new applications generated with `ember-cli`. You can check what version is installed by looking in the `devDependencies` hash of your project's [package.json](https://docs.npmjs.com/cli/v8/configuring-npm/package-json) file.\n\nIf you have generated a new `Ember` application using `ember-cli` but do\nnot wish to use `ember-data`, remove `ember-data` from your project's `package.json` file and run your package manager's install command to update your lockfile.\n\n## Advanced Installation\n\n*Ember*‍**Data** is organized into primitives that compose together via public APIs.\n\n- [@ember-data/store](/ember-data/release/modules/@ember-data%2Fstore) is the core and handles coordination\n- [@ember-data/json-api](/ember-data/release/modules/@ember-data%2Fjson-api) provides a resource cache for JSON:API structured data. It integrates with the store via the hook `createCache`\n- [@ember-data/model](/ember-data/release/modules/@ember-data%2Fmodel) is a presentation layer, it integrates with the store via the hooks `instantiateRecord` and `teardownRecord`.\n- [@ember-data/adapter](/ember-data/release/modules/@ember-data%2Fadapter) provides various network API integrations for APIS built over specific REST or JSON:API conventions.\n- [@ember-data/serializer](/ember-data/release/modules/@ember-data%2Fserializer) pairs with `@ember-data/adapter` to normalize and serialize data to and from an API format into the `JSON:API` format understood by `@ember-data/json-api`.\n- [@ember-data/debug](/ember-data/release/modules/@ember-data%2Fdebug) provides debugging support for the `ember-inspector`.\n- **ember-data** is a \"meta\" package which bundles all of these together for convenience\n\nThe packages interop with each other through well defined public API boundaries. The core\nof the library is the store provided by `@ember-data/store`, while each of the other libraries plugs into the store when installed. Because these packages interop via fully\npublic APIs, other libraries or applications may provide their own implementations. For instance, [ember-m3](https://github.com/hjdivad/ember-m3) is a commonly used presentation and cache implementation suitable for complex resource objects and graphs.\n\n## Configuration\n\n### Deprecation Stripping\n\n*Ember*‍**Data** allows users to opt-in and remove code that exists to support deprecated behaviors.\n\nIf your app has resolved all deprecations present in a given version, you may specify that version as your \"compatibility\" version to remove the code that supported the deprecated behavior from your app.\n\n```ts\nlet app = new EmberApp(defaults, {\n emberData: {\n compatWith: '4.8',\n },\n});\n```\n\n- [Full Documentation](https://api.emberjs.com/ember-data/release/modules/@ember-data%2Fdeprecations)\n\n### randomUUID polyfill\n\n*Ember*‍**Data** uses `UUID V4` by default to generate identifiers for new data created on the client. Identifier generation is configurable, but we also for convenience will polyfill\nthe necessary feature if your browser support or deployment environment demands it. To\nactivate this polyfill:\n\n```ts\nlet app = new EmberApp(defaults, {\n '@embroider/macros': {\n setConfig: {\n '@ember-data/store': {\n polyfillUUID: true\n },\n },\n },\n});\n```\n\n### removing inspector support in production\n\nIf you do not with to ship inspector support in your production application, you can specify\nthat all support for it should be stripped from the build.\n\n```ts\nlet app = new EmberApp(defaults, {\n emberData: {\n includeDataAdapterInProduction: false\n }\n});\n```\n\n- [Full Documentation](https://api.emberjs.com/ember-data/release/modules/@ember-data%2Fdebug)\n\n### Debugging\n\nMany portions of the internals are helpfully instrumented with logging that can be activated\nat build time. This instrumentation is always removed from production builds or any builds\nthat has not explicitly activated it. To activate it set the appropriate flag to `true`.\n\n```ts\n let app = new EmberApp(defaults, {\n emberData: {\n debug: {\n LOG_PAYLOADS: false, // data store received to update cache with\n LOG_OPERATIONS: false, // updates to cache remote state\n LOG_MUTATIONS: false, // updates to cache local state\n LOG_NOTIFICATIONS: false,\n LOG_REQUESTS: false, // log Requests issued via the request manager\n LOG_REQUEST_STATUS: false,\n LOG_IDENTIFIERS: false,\n LOG_GRAPH: false,\n LOG_INSTANCE_CACHE: false,\n }\n }\n });\n ```", "itemtype": "main", "parent": null, "publicclasses": [], diff --git a/json-docs/ember-data/5.3.0/modules/ember-data-5.3.0-@ember-data/active-record/request.json b/json-docs/ember-data/5.3.0/modules/ember-data-5.3.0-@ember-data/active-record/request.json index 05d481373..d2d1a7540 100644 --- a/json-docs/ember-data/5.3.0/modules/ember-data-5.3.0-@ember-data/active-record/request.json +++ b/json-docs/ember-data/5.3.0/modules/ember-data-5.3.0-@ember-data/active-record/request.json @@ -13,7 +13,7 @@ "tag": "main", "file": "../active-record/src/request.ts", "line": 1, - "description": "

\n \n

\n\nThis package provides utilities for working with [ActiveRecord](https://guides.rubyonrails.org/active_record_basics.html#convention-over-configuration-in-active-record) APIs with [*Ember***Data**](https://github.com/emberjs/data/).\n\n## Installation\n\nInstall using your javascript package manager of choice. For instance with [pnpm](https://pnpm.io/)\n\n```no-highlight\npnpm add @ember-data/active-record\n```\n\n## Usage\n\nRequest builders are functions that produce [Fetch Options](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API).\nThey take a few contextual inputs about the request you want to make, abstracting away the gnarlier details.\n\nFor instance, to fetch a resource from your API\n\n```ts\nimport { findRecord } from '@ember-data/active-record/request';\n\nconst options = findRecord('ember-developer', '1', { include: ['pets', 'friends'] });\n\n/\\*\n => {\n url: 'https://api.example.com/v1/ember_developers/1?include=friends,pets',\n method: 'GET',\n headers: , // 'Content-Type': 'application/json; charset=utf-8'\n op: 'findRecord';\n records: [{ type: 'ember-developer', id: '1' }]\n }\n\\/\n```\n\nRequest builder output may be used with either `requestManager.request` or `store.request`.\n\nURLs are stable. The same query will produce the same URL every time, even if the order of keys in\nthe query or values in an array changes.\n\nURLs follow the most common ActiveRecord format (underscored pluralized resource types).\n\n### Available Builders\n\n- [createRecord](https://api.emberjs.com/ember-data/release/functions/@ember-data%2Factive-record/createRecord)\n- [deleteRecord](https://api.emberjs.com/ember-data/release/functions/@ember-data%2Factive-record/deleteRecord)\n- [findRecord](https://api.emberjs.com/ember-data/release/functions/@ember-data%2Factive-record/findRecord)\n- [query](https://api.emberjs.com/ember-data/release/functions/@ember-data%2Factive-record/query)\n- [updateRecord](https://api.emberjs.com/ember-data/release/functions/@ember-data%2Factive-record/updateRecord)", + "description": "

\n \n

\n\nThis package provides utilities for working with [ActiveRecord](https://guides.rubyonrails.org/active_record_basics.html#convention-over-configuration-in-active-record) APIs with [*Ember***Data**](https://github.com/emberjs/data/).\n\n## Installation\n\nInstall using your javascript package manager of choice. For instance with [pnpm](https://pnpm.io/)\n\n```\npnpm add @ember-data/active-record\n```\n\n## Usage\n\nRequest builders are functions that produce [Fetch Options](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API).\nThey take a few contextual inputs about the request you want to make, abstracting away the gnarlier details.\n\nFor instance, to fetch a resource from your API\n\n```ts\nimport { findRecord } from '@ember-data/active-record/request';\n\nconst options = findRecord('ember-developer', '1', { include: ['pets', 'friends'] });\n\n/\\*\n => {\n url: 'https://api.example.com/v1/ember_developers/1?include=friends,pets',\n method: 'GET',\n headers: , // 'Content-Type': 'application/json; charset=utf-8'\n op: 'findRecord';\n records: [{ type: 'ember-developer', id: '1' }]\n }\n\\/\n```\n\nRequest builder output may be used with either `requestManager.request` or `store.request`.\n\nURLs are stable. The same query will produce the same URL every time, even if the order of keys in\nthe query or values in an array changes.\n\nURLs follow the most common ActiveRecord format (underscored pluralized resource types).\n\n### Available Builders\n\n- [createRecord](https://api.emberjs.com/ember-data/release/functions/@ember-data%2Factive-record/createRecord)\n- [deleteRecord](https://api.emberjs.com/ember-data/release/functions/@ember-data%2Factive-record/deleteRecord)\n- [findRecord](https://api.emberjs.com/ember-data/release/functions/@ember-data%2Factive-record/findRecord)\n- [query](https://api.emberjs.com/ember-data/release/functions/@ember-data%2Factive-record/query)\n- [updateRecord](https://api.emberjs.com/ember-data/release/functions/@ember-data%2Factive-record/updateRecord)", "itemtype": "main", "parent": null, "publicclasses": [], diff --git a/json-docs/ember-data/5.3.0/modules/ember-data-5.3.0-@ember-data/graph.json b/json-docs/ember-data/5.3.0/modules/ember-data-5.3.0-@ember-data/graph.json index 3db8d1607..b990f246c 100644 --- a/json-docs/ember-data/5.3.0/modules/ember-data-5.3.0-@ember-data/graph.json +++ b/json-docs/ember-data/5.3.0/modules/ember-data-5.3.0-@ember-data/graph.json @@ -11,7 +11,7 @@ "tag": "main", "file": "../graph/src/-private.ts", "line": 3, - "description": "

\n \n

\n\n

Provides a performance tuned normalized graph for intelligently managing relationships between resources based on identity

\n\nWhile this Graph is abstract, it currently is a private implementation required as a peer-dependency by the [JSON:API Cache Implementation](https://github.com/emberjs/data/tree/main/packages/json-api).\n\nWe intend to make this Graph public API after some additional iteration during the 5.x timeframe, until then all APIs should be considered experimental and unstable, not fit for direct application or 3rd party library usage.\n\n## Installation\n\nInstall using your javascript package manager of choice. For instance with [pnpm](https://pnpm.io/)\n\n```no-highlight\npnpm add @ember-data/graph\n```", + "description": "

\n \n

\n\n

Provides a performance tuned normalized graph for intelligently managing relationships between resources based on identity

\n\nWhile this Graph is abstract, it currently is a private implementation required as a peer-dependency by the [JSON:API Cache Implementation](https://github.com/emberjs/data/tree/main/packages/json-api).\n\nWe intend to make this Graph public API after some additional iteration during the 5.x timeframe, until then all APIs should be considered experimental and unstable, not fit for direct application or 3rd party library usage.\n\n## Installation\n\nInstall using your javascript package manager of choice. For instance with [pnpm](https://pnpm.io/)\n\n```\npnpm add @ember-data/graph\n```", "itemtype": "main", "parent": null, "publicclasses": [], diff --git a/json-docs/ember-data/5.3.0/modules/ember-data-5.3.0-@ember-data/json-api.json b/json-docs/ember-data/5.3.0/modules/ember-data-5.3.0-@ember-data/json-api.json index ec31f55fc..1590c5458 100644 --- a/json-docs/ember-data/5.3.0/modules/ember-data-5.3.0-@ember-data/json-api.json +++ b/json-docs/ember-data/5.3.0/modules/ember-data-5.3.0-@ember-data/json-api.json @@ -11,7 +11,7 @@ "tag": "main", "file": "../json-api/src/-private/cache.ts", "line": 84, - "description": "

\n \n

\n\nThis package provides an in-memory [JSON:API](https://jsonapi.org/) document and resource [*Ember***Data** Cache](https://github.com/emberjs/data/blob/main/ember-data-types/cache/cache.ts) implementation.\n\n## Installation\n\nInstall using your javascript package manager of choice. For instance with [pnpm](https://pnpm.io/)\n\n```no-highlight\npnpm add @ember-data/json-api\n```\n\n## πŸš€ Setup\n\n> **Note** When using [ember-data](https://github.com/emberjs/data/blob/main/packages/-ember-data) the below\n> configuration is handled for you automatically.\n\n```ts\nimport Store from '@ember-data/store';\nimport Cache from '@ember-data/json-api';\n\nexport default class extends Store {\n createCache(wrapper) {\n return new Cache(wrapper);\n }\n}\n```\n\n\n## Usage\n\nUsually you will directly interact with the cache only if implementing a presentation class. Below we\ngive an example of a read-only record (mutations never written back to the cache). More typically cache\ninteractions are something that the `Store` coordinates as part of the `request/response` lifecycle.\n\n```ts\nimport Store, { recordIdentifierFor } from '@ember-data/store';\nimport Cache from '@ember-data/json-api';\nimport { TrackedObject } from 'tracked-built-ins';\n\nclass extends Store {\n createCache(wrapper) {\n return new Cache(wrapper);\n }\n\n instantiateRecord(identifier) {\n const { cache, notifications } = this;\n const { type, id } = identifier;\n\n // create a TrackedObject with our attributes, id and type\n const attrs = cache.peek(identifier).attributes;\n const data = Object.assign({}, attrs, { type, id });\n const record = new TrackedObject(data);\n\n // update the TrackedObject whenever attributes change\n const token = notifications.subscribe(identifier, (_, change) => {\n if (change === 'attributes') {\n Object.assign(record, cache.peek(identifier).attributes);\n }\n });\n\n // setup the ability to teardown the subscription when the\n // record is no longer needed\n record.destroy = () => {\n this.notifications.unsubscribe(token);\n };\n\n return record;\n }\n\n teardownRecord(record: FakeRecord) {\n record.destroy();\n }\n}\n```\n\nFor the full list of APIs available read the code documentation for [*Ember***Data** Cache](https://github.com/emberjs/data/blob/main/ember-data-types/cache/cache.ts)", + "description": "

\n \n

\n\nThis package provides an in-memory [JSON:API](https://jsonapi.org/) document and resource [*Ember***Data** Cache](https://github.com/emberjs/data/blob/main/ember-data-types/cache/cache.ts) implementation.\n\n## Installation\n\nInstall using your javascript package manager of choice. For instance with [pnpm](https://pnpm.io/)\n\n```\npnpm add @ember-data/json-api\n```\n\n## πŸš€ Setup\n\n> **Note** When using [ember-data](https://github.com/emberjs/data/blob/main/packages/-ember-data) the below\n> configuration is handled for you automatically.\n\n```ts\nimport Store from '@ember-data/store';\nimport Cache from '@ember-data/json-api';\n\nexport default class extends Store {\n createCache(wrapper) {\n return new Cache(wrapper);\n }\n}\n```\n\n\n## Usage\n\nUsually you will directly interact with the cache only if implementing a presentation class. Below we\ngive an example of a read-only record (mutations never written back to the cache). More typically cache\ninteractions are something that the `Store` coordinates as part of the `request/response` lifecycle.\n\n```ts\nimport Store, { recordIdentifierFor } from '@ember-data/store';\nimport Cache from '@ember-data/json-api';\nimport { TrackedObject } from 'tracked-built-ins';\n\nclass extends Store {\n createCache(wrapper) {\n return new Cache(wrapper);\n }\n\n instantiateRecord(identifier) {\n const { cache, notifications } = this;\n const { type, id } = identifier;\n\n // create a TrackedObject with our attributes, id and type\n const attrs = cache.peek(identifier).attributes;\n const data = Object.assign({}, attrs, { type, id });\n const record = new TrackedObject(data);\n\n // update the TrackedObject whenever attributes change\n const token = notifications.subscribe(identifier, (_, change) => {\n if (change === 'attributes') {\n Object.assign(record, cache.peek(identifier).attributes);\n }\n });\n\n // setup the ability to teardown the subscription when the\n // record is no longer needed\n record.destroy = () => {\n this.notifications.unsubscribe(token);\n };\n\n return record;\n }\n\n teardownRecord(record: FakeRecord) {\n record.destroy();\n }\n}\n```\n\nFor the full list of APIs available read the code documentation for [*Ember***Data** Cache](https://github.com/emberjs/data/blob/main/ember-data-types/cache/cache.ts)", "itemtype": "main", "parent": null, "publicclasses": [ diff --git a/json-docs/ember-data/5.3.0/modules/ember-data-5.3.0-@ember-data/json-api/request.json b/json-docs/ember-data/5.3.0/modules/ember-data-5.3.0-@ember-data/json-api/request.json index 7d7c18ae8..37c33316b 100644 --- a/json-docs/ember-data/5.3.0/modules/ember-data-5.3.0-@ember-data/json-api/request.json +++ b/json-docs/ember-data/5.3.0/modules/ember-data-5.3.0-@ember-data/json-api/request.json @@ -13,7 +13,7 @@ "tag": "main", "file": "../json-api/src/request.ts", "line": 1, - "description": "

\n \n

\n\nThis package provides utilities for working with [JSON:API](https://json-api.org) APIs with [*Ember***Data**](https://github.com/emberjs/data/).\n\n## Installation\n\nInstall using your javascript package manager of choice. For instance with [pnpm](https://pnpm.io/)\n\n```no-highlight\npnpm add @ember-data/json-api\n```\n\n## Usage\n\nRequest builders are functions that produce [Fetch Options](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API).\nThey take a few contextual inputs about the request you want to make, abstracting away the gnarlier details.\n\nFor instance, to fetch a resource from your API\n\n```ts\nimport { findRecord } from '@ember-data/json-api/request';\n\nconst options = findRecord('ember-developer', '1', { include: ['pets', 'friends'] });\n\n/\\*\n => {\n url: 'https://api.example.com/v1/ember-developers/1?include=friends,pets',\n method: 'GET',\n headers: ,\n // => 'Accept': 'application/vnd.api+json'\n // => 'Content-Type': 'application/vnd.api+json'\n op: 'findRecord';\n records: [{ type: 'ember-developer', id: '1' }]\n }\n\\/\n```\n\nRequest builder output may be used with either `requestManager.request` or `store.request`.\n\nURLs are stable. The same query will produce the same URL every time, even if the order of keys in\nthe query or values in an array changes.\n\nURLs follow the most common JSON:API format (dasherized pluralized resource types).\n\n### Available Builders\n\n- [createRecord](https://api.emberjs.com/ember-data/release/functions/@ember-data%2Fjson-api/createRecord)\n- [deleteRecord](https://api.emberjs.com/ember-data/release/functions/@ember-data%2Fjson-api/deleteRecord)\n- [findRecord](https://api.emberjs.com/ember-data/release/functions/@ember-data%2Fjson-api/findRecord)\n- [query](https://api.emberjs.com/ember-data/release/functions/@ember-data%2Fjson-api/query)\n- [updateRecord](https://api.emberjs.com/ember-data/release/functions/@ember-data%2Fjson-api/updateRecord)", + "description": "

\n \n

\n\nThis package provides utilities for working with [JSON:API](https://json-api.org) APIs with [*Ember***Data**](https://github.com/emberjs/data/).\n\n## Installation\n\nInstall using your javascript package manager of choice. For instance with [pnpm](https://pnpm.io/)\n\n```\npnpm add @ember-data/json-api\n```\n\n## Usage\n\nRequest builders are functions that produce [Fetch Options](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API).\nThey take a few contextual inputs about the request you want to make, abstracting away the gnarlier details.\n\nFor instance, to fetch a resource from your API\n\n```ts\nimport { findRecord } from '@ember-data/json-api/request';\n\nconst options = findRecord('ember-developer', '1', { include: ['pets', 'friends'] });\n\n/\\*\n => {\n url: 'https://api.example.com/v1/ember-developers/1?include=friends,pets',\n method: 'GET',\n headers: ,\n // => 'Accept': 'application/vnd.api+json'\n // => 'Content-Type': 'application/vnd.api+json'\n op: 'findRecord';\n records: [{ type: 'ember-developer', id: '1' }]\n }\n\\/\n```\n\nRequest builder output may be used with either `requestManager.request` or `store.request`.\n\nURLs are stable. The same query will produce the same URL every time, even if the order of keys in\nthe query or values in an array changes.\n\nURLs follow the most common JSON:API format (dasherized pluralized resource types).\n\n### Available Builders\n\n- [createRecord](https://api.emberjs.com/ember-data/release/functions/@ember-data%2Fjson-api/createRecord)\n- [deleteRecord](https://api.emberjs.com/ember-data/release/functions/@ember-data%2Fjson-api/deleteRecord)\n- [findRecord](https://api.emberjs.com/ember-data/release/functions/@ember-data%2Fjson-api/findRecord)\n- [query](https://api.emberjs.com/ember-data/release/functions/@ember-data%2Fjson-api/query)\n- [updateRecord](https://api.emberjs.com/ember-data/release/functions/@ember-data%2Fjson-api/updateRecord)", "itemtype": "main", "parent": null, "publicclasses": [], diff --git a/json-docs/ember-data/5.3.0/modules/ember-data-5.3.0-@ember-data/request.json b/json-docs/ember-data/5.3.0/modules/ember-data-5.3.0-@ember-data/request.json index 9f63d4f00..19624d773 100644 --- a/json-docs/ember-data/5.3.0/modules/ember-data-5.3.0-@ember-data/request.json +++ b/json-docs/ember-data/5.3.0/modules/ember-data-5.3.0-@ember-data/request.json @@ -11,7 +11,7 @@ "tag": "main", "file": "../request/src/-private/types.ts", "line": 205, - "description": "

\n \n

\n\n

⚑️ a simple abstraction over fetch to enable easy management of request/response flows

\n\nThis package provides [*Ember*‍**Data**](https://github.com/emberjs/data/)'s `RequestManager`, a framework agnostic library that can be integrated with any Javascript application to make [fetch](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) happen.\n\n## Installation\n\nInstall using your javascript package manager of choice. For instance with [pnpm](https://pnpm.io/)\n\n```no-highlight\npnpm add @ember-data/request\n```\n\n## πŸš€ Basic Usage\n\nA `RequestManager` provides a request/response flow in which configured handlers are successively given the opportunity to handle, modify, or pass-along a request.\n\nThe RequestManager on its own does not know how to fulfill requests. For this we must register at least one handler. A basic `Fetch` handler is provided that will take the request options provided and execute `fetch`.\n\n```ts\nimport RequestManager from '@ember-data/request';\nimport Fetch from '@ember-data/request/fetch';\nimport { apiUrl } from './config';\n\n// ... create manager and add our Fetch handler\nconst manager = new RequestManager();\nmanager.use([Fetch]);\n\n// ... execute a request\nconst response = await manager.request({\n url: `${apiUrl}/users`\n});\n```\n\n\n## πŸͺœ Architecture\n\nA `RequestManager` receives a request and manages fulfillment via configured handlers. It may be used standalone from the rest of *Ember*‍**Data** and is not specific to any library or framework.\n\nEach handler may choose to fulfill the request using some source of data or to pass the request along to other handlers.\n\nThe same or a separate instance of a `RequestManager` may also be used to fulfill requests issued by [*Ember*‍**Data**{Store}](https://github.com/emberjs/data/tree/main/packages/store)\n\nWhen the same instance is used by both this allows for simple coordination throughout the application. Requests issued by the Store will use the in-memory cache\nand return hydrated responses, requests issued directly to the RequestManager\nwill skip the in-memory cache and return raw responses.\n\n## Usage\n\n```ts\nconst userList = await manager.request({\n url: `/api/v1/users.list`\n});\n\nconst users = userList.content;\n```\n\n
\n Making Requests\n\n`RequestManager` has a single asyncronous method as it's API: `request`\n\n```ts\nclass RequestManager {\n request(req: RequestInfo): Future;\n}\n```\n\n`manager.request()` accepts an object containing the information\nnecessary for the request to be handled successfully.\n\nThese options extend the [options](https://developer.mozilla.org/en-US/docs/Web/API/fetch#parameters) provided to `fetch`, and can accept a [`Request`](https://developer.mozilla.org/en-US/docs/Web/API/Request/Request). All properties accepted by Request options and fetch options are valid.\n\n```ts\ninterface RequestInfo extends FetchOptions {\n op?: string;\n store?: Store;\nurl: string;\n // data that a handler should convert into\n // the query (GET) or body (POST)\n data?: Record;\n// options specifically intended for handlers\n // to utilize to process the request\n options?: Record;\n}\n```\n\n> **note:** providing a `signal` is unnecessary as an `AbortController` is automatically provided if none is present.\n\n
\n
\n Using the Response
\n\n`manager.request` returns a `Future`, which allows access to limited information about the request while it is still pending and fulfills with the final state when the request completes and the response has been read.\n\n```ts\nconst usersFuture = manager.request({\n url: `/api/v1/users.list`\n});\n```\n\nA `Future` is cancellable via `abort`.\n\n```ts\nusersFuture.abort();\n```\n\nHandlers may *optionally* expose a ReadableStream to the `Future` for streaming data; however, when doing so the handler should not resolve until it has fully read the response stream itself.\n\n```ts\ninterface Future extends Promise> {\n abort(): void;\nasync getStream(): ReadableStream | null;\n}\n```\n\nA Future resolves or rejects with a `StructuredDocument`.\n\n```ts\ninterface StructuredDocument {\n request: RequestInfo;\n response: ResponseInfo | null;\n content?: T;\n error?: Error;\n}\n```\n\nThe `RequestInfo` specified by `document.request` is the same as originally provided to `manager.request`. If any handler fulfilled this request using different request info it is not represented here. This contract helps to ensure that `retry` and `caching` are possible since the original arguments are correctly preserved. This also allows handlers to \"fork\" the request or fulfill from multiple sources without the details of fulfillment muddying the original request.\n\nThe `ResponseInfo` is a serializable fulfilled subset of a [Response](https://developer.mozilla.org/en-US/docs/Web/API/Response) if set via `setResponse`. If no response was ever set this will be `null`.\n\n```ts\ninterface ResponseInfo {\n headers?: Record;\n ok?: boolean;\n redirected?: boolean;\n status?: HTTPStatusCode;\n statusText?: string;\n type?: 'basic' | 'cors';\n url?: string;\n}\n```\n\n
\n\n

Handling Requests

\n
\n { request(context, next): Promise | Future; }
\n\nRequests are fulfilled by handlers. A handler receives the request context\nas well as a `next` function with which to pass along a request to the next\nhandler if it so chooses.\n\nA handler may be any object with a `request` method. This allows both stateful and non-stateful\nhandlers to be utilized.\n\nIf a handler calls `next`, it receives a `Future` which resolves to a `StructuredDocument`\nthat it can then compose how it sees fit with its own response.\n\n```ts\n\ntype NextFn

= (req: RequestInfo) => Future

;\n\ninterface Handler {\n async request(context: RequestContext, next: NextFn

): T;\n}\n```\n\n`RequestContext` contains a readonly version of the RequestInfo as well as a few methods for building up the `StructuredDocument` and `Future` that will be part of the response.\n\n```ts\ninterface RequestContext {\n readonly request: RequestInfo;\nsetStream(stream: ReadableStream | Promise): void;\n setResponse(response: Response | ResponseInfo): void;\n}\n```\n\nA basic `fetch` handler with support for streaming content updates while\nthe download is still underway might look like the following, where we use\n[`response.clone()`](https://developer.mozilla.org/en-US/docs/Web/API/Response/clone) to `tee` the `ReadableStream` into two streams.\n\nA more efficient handler might read from the response stream, building up the\nresponse content before passing along the chunk downstream.\n\n```ts\nconst FetchHandler = {\n async request(context) {\n const response = await fetch(context.request);\n context.setResponse(reponse);\n context.setStream(response.clone().body);\n return response.json();\n }\n}\n```\n\nRequest handlers are registered by configuring the manager via `use`\n\n```ts\nmanager.use([Handler1, Handler2])\n```\n\nHandlers will be invoked in the order they are registered (\"fifo\", first-in first-out), and may only be registered up until the first request is made. It is recommended but not required to register all handlers at one time in order to ensure explicitly visible handler ordering.\n\n

\n\n\n
\n Error Handling
\nEach handler in the chain can catch errors from upstream and choose to\n either handle the error, re-throw the error, or throw a new error.\n```ts\n const MAX_RETRIES = 5;\nconst Handler = {\n async request(context, next) {\n let attempts = 0;\n while (attempts < MAX_RETRIES) {\n attempts++;\n try {\n const response = await next(context.request);\n return response;\n } catch (e) {\n if (isTimeoutError(e) && attempts < MAX_RETRIES) {\n // retry request\n continue;\n }\n // rethrow if it is not a timeout error\n throw e;\n }\n }\n }\n }\n ```\n
\n\n
\n Handling Abort
\nAborting a request will reject the current handler in the chain. However,\n every handler can potentially catch this error. If your handler needs to\n separate AbortError from other Error types, it is recommended to check\n `context.request.signal.aborted` (or if a custom controller was supplied `controller.signal.aborted`).\nIn this manner it is possible for a request to recover from an abort and\n still proceed; however, as a best practice this should be used for necessary\n cleanup only and the original AbortError rethrown if the abort signal comes\n from the root controller.\n\n*AbortControllers are Always Present and Always Entangled**\nIf the initial request does not supply an [AbortController](https://developer.mozilla.org/en-US/docs/Web/API/AbortController), one will be generated.\nThe [signal](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) for this controller is automatically added to the request passed into the first handler.\nEach handler has the option to supply a new controller to the request when calling `next`. If a new controller is provided it will be automatically\n entangled with the root controller. If the root controller aborts, so will\n any entangled controllers.\nIf an entangled controller aborts, the root controller will not abort. This\n allows for advanced request-flow scenarios to abort subsections of the request tree without aborting the entire request.\n\n
\n\n\n
\n Stream Currying
\n\n`RequestManager.request` and `next` differ from `fetch` in one **crucial detail** in that the outer Promise resolves only once the response stream has been processed.\n\nFor context, it helps to understand a few of the use-cases that RequestManager\nis intended to allow.\n\n- to manage and return streaming content (such as video files)\n- to fulfill a request from multiple sources or by splitting one request into multiple requests\n - for instance one API call for a user and another for the user's friends\n - or e.g. fulfilling part of the request from one source (one API, in-memory, localStorage, IndexedDB\n etc.) and the rest from another source (a different API, a WebWorker, etc.)\n- to coalesce multiple requests\n- to decorate a request with additional info\n - e.g. an Auth handler that ensures the correct tokens or headers or cookies are attached.\n\n\n`await fetch()` resolves at the moment headers are received. This allows for the body of the request to be processed as a stream by application\ncode *while chunks are still being received by the browser*.\n\nWhen an app chooses to `await response.json()` what occurs is the browser reads the stream to completion and then returns the result. Additionally, this stream may only be read **once**.\n\nThe `RequestManager` preserves this ability to subscribe to and utilize the stream by either the application or the handler – thereby delivering the full power and flexibility of native APIs – without restricting developers in ways that lead to complicated workarounds.\n\nEach handler may call `setStream` only once, but may do so *at any time* until the promise that the handler returns has resolved. The associated promise returned by calling `future.getStream` will resolve with the stream set by `setStream` if that method is called, or `null` if that method\nhas not been called by the time that the handler's request method has resolved.\n\nHandlers that do not create a stream of their own, but which call `next`, should defensively pipe the stream forward. While this is not required (see automatic currying below) it is better to do so in most cases as otherwise the stream may not become available to downstream handlers or the application until the upstream handler has fully read it.\n\n```ts\ncontext.setStream(future.getStream());\n```\n\nHandlers that either call `next` multiple times or otherwise have reason to create multiple fetch requests should either choose to return no stream, meaningfully combine the streams, or select a single prioritized stream.\n\nOf course, any handler may choose to read and handle the stream, and return either no stream or a different stream in the process.\n\n
\n\n
\n Automatic Currying of Stream and Response
\n\nIn order to simplify the common case for handlers which decorate a request, if `next` is called only a single time and `setResponse` was never called by the handler, the response set by the next handler in the chain will be applied to that handler's outcome. For instance, this makes the following pattern possible `return (await next()).content;`.\n\nSimilarly, if `next` is called only a single time and neither `setStream` nor `getStream` was called, we automatically curry the stream from the future returned by `next` onto the future returned by the handler.\n\nFinally, if the return value of a handler is a `Future`, we curry `content` and `errors` as well, thus enabling the simplest form `return next()`.\n\nIn the case of the `Future` being returned, `Stream` proxying is automatic and immediate and does not wait for the `Future` to resolve.\n\n
\n\n### Using as a Service\n\nMost applications will desire to have a single `RequestManager` instance, which can be achieved using module-state patterns for singletons, or for [Ember](https://emberjs.com) applications by exporting the manager as a [service](https://guides.emberjs.com/release/services/).\n\nservices/request.ts*\n```ts\nimport RequestManager from '@ember-data/request';\nimport Fetch from '@ember-data/request/fetch';\nimport Auth from 'ember-simple-auth/ember-data-handler';\n\nexport default class extends RequestManager {\n constructor(createArgs) {\n super(createArgs);\n this.use([Auth, Fetch]);\n }\n}\n```\n\n### Using with `@ember-data/store`\n\nTo have a request service unique to a Store:\n\n```ts\nimport Store, { CacheHandler } from '@ember-data/store';\nimport RequestManager from '@ember-data/request';\nimport Fetch from '@ember-data/request/fetch';\n\nclass extends Store {\n requestManager = new RequestManager();\nconstructor(args) {\n super(args);\n this.requestManager.use([Fetch]);\n this.requestManager.useCache(CacheHandler);\n }\n}\n```\n\n### Using with `ember-data`\n\nIf using the package [ember-data](https://github.com/emberjs/data/tree/main/packages/-ember-data), the following configuration will automatically be done in order to preserve the legacy [Adapter](https://github.com/emberjs/data/tree/main/packages/adapter) and [Serializer](https://github.com/emberjs/data/tree/main/packages/serializer) behavior. Additional handlers or a service injection like the above would need to be done by the consuming application in order to make broader use of `RequestManager`.\n\n```ts\nimport Store, { CacheHandler } from '@ember-data/store';\nimport RequestManager from '@ember-data/request';\nimport { LegacyNetworkHandler } from '@ember-data/legacy-compat';\n\nexport default class extends Store {\n requestManager = new RequestManager();\nconstructor(args) {\n super(args);\n this.requestManager.use([LegacyNetworkHandler]);\n this.requestManager.useCache(CacheHandler);\n }\n}\n```\n\nBecause the application's store service (if present) will override the store supplied by `ember-data`, all that is required to define your own ordering and handlers is to supply a store service extending from `@ember-data/store` and configure as shown above.\n\nFor usage of the store's `requestManager` via `store.request()` see the [Store](https://api.emberjs.com/ember-data/release/modules/@ember-data%2Fstore) documentation.", + "description": "

\n \n

\n\n

⚑️ a simple abstraction over fetch to enable easy management of request/response flows

\n\nThis package provides [*Ember*‍**Data**](https://github.com/emberjs/data/)'s `RequestManager`, a framework agnostic library that can be integrated with any Javascript application to make [fetch](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) happen.\n\n## Installation\n\nInstall using your javascript package manager of choice. For instance with [pnpm](https://pnpm.io/)\n\n```\npnpm add @ember-data/request\n```\n\n## πŸš€ Basic Usage\n\nA `RequestManager` provides a request/response flow in which configured handlers are successively given the opportunity to handle, modify, or pass-along a request.\n\nThe RequestManager on its own does not know how to fulfill requests. For this we must register at least one handler. A basic `Fetch` handler is provided that will take the request options provided and execute `fetch`.\n\n```ts\nimport RequestManager from '@ember-data/request';\nimport Fetch from '@ember-data/request/fetch';\nimport { apiUrl } from './config';\n\n// ... create manager and add our Fetch handler\nconst manager = new RequestManager();\nmanager.use([Fetch]);\n\n// ... execute a request\nconst response = await manager.request({\n url: `${apiUrl}/users`\n});\n```\n\n\n## πŸͺœ Architecture\n\nA `RequestManager` receives a request and manages fulfillment via configured handlers. It may be used standalone from the rest of *Ember*‍**Data** and is not specific to any library or framework.\n\nEach handler may choose to fulfill the request using some source of data or to pass the request along to other handlers.\n\nThe same or a separate instance of a `RequestManager` may also be used to fulfill requests issued by [*Ember*‍**Data**{Store}](https://github.com/emberjs/data/tree/main/packages/store)\n\nWhen the same instance is used by both this allows for simple coordination throughout the application. Requests issued by the Store will use the in-memory cache\nand return hydrated responses, requests issued directly to the RequestManager\nwill skip the in-memory cache and return raw responses.\n\n## Usage\n\n```ts\nconst userList = await manager.request({\n url: `/api/v1/users.list`\n});\n\nconst users = userList.content;\n```\n\n
\n Making Requests\n\n`RequestManager` has a single asyncronous method as it's API: `request`\n\n```ts\nclass RequestManager {\n request(req: RequestInfo): Future;\n}\n```\n\n`manager.request()` accepts an object containing the information\nnecessary for the request to be handled successfully.\n\nThese options extend the [options](https://developer.mozilla.org/en-US/docs/Web/API/fetch#parameters) provided to `fetch`, and can accept a [`Request`](https://developer.mozilla.org/en-US/docs/Web/API/Request/Request). All properties accepted by Request options and fetch options are valid.\n\n```ts\ninterface RequestInfo extends FetchOptions {\n op?: string;\n store?: Store;\nurl: string;\n // data that a handler should convert into\n // the query (GET) or body (POST)\n data?: Record;\n// options specifically intended for handlers\n // to utilize to process the request\n options?: Record;\n}\n```\n\n> **note:** providing a `signal` is unnecessary as an `AbortController` is automatically provided if none is present.\n\n
\n
\n Using the Response
\n\n`manager.request` returns a `Future`, which allows access to limited information about the request while it is still pending and fulfills with the final state when the request completes and the response has been read.\n\n```ts\nconst usersFuture = manager.request({\n url: `/api/v1/users.list`\n});\n```\n\nA `Future` is cancellable via `abort`.\n\n```ts\nusersFuture.abort();\n```\n\nHandlers may *optionally* expose a ReadableStream to the `Future` for streaming data; however, when doing so the handler should not resolve until it has fully read the response stream itself.\n\n```ts\ninterface Future extends Promise> {\n abort(): void;\nasync getStream(): ReadableStream | null;\n}\n```\n\nA Future resolves or rejects with a `StructuredDocument`.\n\n```ts\ninterface StructuredDocument {\n request: RequestInfo;\n response: ResponseInfo | null;\n content?: T;\n error?: Error;\n}\n```\n\nThe `RequestInfo` specified by `document.request` is the same as originally provided to `manager.request`. If any handler fulfilled this request using different request info it is not represented here. This contract helps to ensure that `retry` and `caching` are possible since the original arguments are correctly preserved. This also allows handlers to \"fork\" the request or fulfill from multiple sources without the details of fulfillment muddying the original request.\n\nThe `ResponseInfo` is a serializable fulfilled subset of a [Response](https://developer.mozilla.org/en-US/docs/Web/API/Response) if set via `setResponse`. If no response was ever set this will be `null`.\n\n```ts\ninterface ResponseInfo {\n headers?: Record;\n ok?: boolean;\n redirected?: boolean;\n status?: HTTPStatusCode;\n statusText?: string;\n type?: 'basic' | 'cors';\n url?: string;\n}\n```\n\n
\n\n

Handling Requests

\n
\n { request(context, next): Promise | Future; }
\n\nRequests are fulfilled by handlers. A handler receives the request context\nas well as a `next` function with which to pass along a request to the next\nhandler if it so chooses.\n\nA handler may be any object with a `request` method. This allows both stateful and non-stateful\nhandlers to be utilized.\n\nIf a handler calls `next`, it receives a `Future` which resolves to a `StructuredDocument`\nthat it can then compose how it sees fit with its own response.\n\n```ts\n\ntype NextFn

= (req: RequestInfo) => Future

;\n\ninterface Handler {\n async request(context: RequestContext, next: NextFn

): T;\n}\n```\n\n`RequestContext` contains a readonly version of the RequestInfo as well as a few methods for building up the `StructuredDocument` and `Future` that will be part of the response.\n\n```ts\ninterface RequestContext {\n readonly request: RequestInfo;\nsetStream(stream: ReadableStream | Promise): void;\n setResponse(response: Response | ResponseInfo): void;\n}\n```\n\nA basic `fetch` handler with support for streaming content updates while\nthe download is still underway might look like the following, where we use\n[`response.clone()`](https://developer.mozilla.org/en-US/docs/Web/API/Response/clone) to `tee` the `ReadableStream` into two streams.\n\nA more efficient handler might read from the response stream, building up the\nresponse content before passing along the chunk downstream.\n\n```ts\nconst FetchHandler = {\n async request(context) {\n const response = await fetch(context.request);\n context.setResponse(reponse);\n context.setStream(response.clone().body);\n return response.json();\n }\n}\n```\n\nRequest handlers are registered by configuring the manager via `use`\n\n```ts\nmanager.use([Handler1, Handler2])\n```\n\nHandlers will be invoked in the order they are registered (\"fifo\", first-in first-out), and may only be registered up until the first request is made. It is recommended but not required to register all handlers at one time in order to ensure explicitly visible handler ordering.\n\n

\n\n\n
\n Error Handling
\nEach handler in the chain can catch errors from upstream and choose to\n either handle the error, re-throw the error, or throw a new error.\n```ts\n const MAX_RETRIES = 5;\nconst Handler = {\n async request(context, next) {\n let attempts = 0;\n while (attempts < MAX_RETRIES) {\n attempts++;\n try {\n const response = await next(context.request);\n return response;\n } catch (e) {\n if (isTimeoutError(e) && attempts < MAX_RETRIES) {\n // retry request\n continue;\n }\n // rethrow if it is not a timeout error\n throw e;\n }\n }\n }\n }\n ```\n
\n\n
\n Handling Abort
\nAborting a request will reject the current handler in the chain. However,\n every handler can potentially catch this error. If your handler needs to\n separate AbortError from other Error types, it is recommended to check\n `context.request.signal.aborted` (or if a custom controller was supplied `controller.signal.aborted`).\nIn this manner it is possible for a request to recover from an abort and\n still proceed; however, as a best practice this should be used for necessary\n cleanup only and the original AbortError rethrown if the abort signal comes\n from the root controller.\n\n*AbortControllers are Always Present and Always Entangled**\nIf the initial request does not supply an [AbortController](https://developer.mozilla.org/en-US/docs/Web/API/AbortController), one will be generated.\nThe [signal](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) for this controller is automatically added to the request passed into the first handler.\nEach handler has the option to supply a new controller to the request when calling `next`. If a new controller is provided it will be automatically\n entangled with the root controller. If the root controller aborts, so will\n any entangled controllers.\nIf an entangled controller aborts, the root controller will not abort. This\n allows for advanced request-flow scenarios to abort subsections of the request tree without aborting the entire request.\n\n
\n\n\n
\n Stream Currying
\n\n`RequestManager.request` and `next` differ from `fetch` in one **crucial detail** in that the outer Promise resolves only once the response stream has been processed.\n\nFor context, it helps to understand a few of the use-cases that RequestManager\nis intended to allow.\n\n- to manage and return streaming content (such as video files)\n- to fulfill a request from multiple sources or by splitting one request into multiple requests\n - for instance one API call for a user and another for the user's friends\n - or e.g. fulfilling part of the request from one source (one API, in-memory, localStorage, IndexedDB\n etc.) and the rest from another source (a different API, a WebWorker, etc.)\n- to coalesce multiple requests\n- to decorate a request with additional info\n - e.g. an Auth handler that ensures the correct tokens or headers or cookies are attached.\n\n\n`await fetch()` resolves at the moment headers are received. This allows for the body of the request to be processed as a stream by application\ncode *while chunks are still being received by the browser*.\n\nWhen an app chooses to `await response.json()` what occurs is the browser reads the stream to completion and then returns the result. Additionally, this stream may only be read **once**.\n\nThe `RequestManager` preserves this ability to subscribe to and utilize the stream by either the application or the handler – thereby delivering the full power and flexibility of native APIs – without restricting developers in ways that lead to complicated workarounds.\n\nEach handler may call `setStream` only once, but may do so *at any time* until the promise that the handler returns has resolved. The associated promise returned by calling `future.getStream` will resolve with the stream set by `setStream` if that method is called, or `null` if that method\nhas not been called by the time that the handler's request method has resolved.\n\nHandlers that do not create a stream of their own, but which call `next`, should defensively pipe the stream forward. While this is not required (see automatic currying below) it is better to do so in most cases as otherwise the stream may not become available to downstream handlers or the application until the upstream handler has fully read it.\n\n```ts\ncontext.setStream(future.getStream());\n```\n\nHandlers that either call `next` multiple times or otherwise have reason to create multiple fetch requests should either choose to return no stream, meaningfully combine the streams, or select a single prioritized stream.\n\nOf course, any handler may choose to read and handle the stream, and return either no stream or a different stream in the process.\n\n
\n\n
\n Automatic Currying of Stream and Response
\n\nIn order to simplify the common case for handlers which decorate a request, if `next` is called only a single time and `setResponse` was never called by the handler, the response set by the next handler in the chain will be applied to that handler's outcome. For instance, this makes the following pattern possible `return (await next()).content;`.\n\nSimilarly, if `next` is called only a single time and neither `setStream` nor `getStream` was called, we automatically curry the stream from the future returned by `next` onto the future returned by the handler.\n\nFinally, if the return value of a handler is a `Future`, we curry `content` and `errors` as well, thus enabling the simplest form `return next()`.\n\nIn the case of the `Future` being returned, `Stream` proxying is automatic and immediate and does not wait for the `Future` to resolve.\n\n
\n\n### Using as a Service\n\nMost applications will desire to have a single `RequestManager` instance, which can be achieved using module-state patterns for singletons, or for [Ember](https://emberjs.com) applications by exporting the manager as a [service](https://guides.emberjs.com/release/services/).\n\nservices/request.ts*\n```ts\nimport RequestManager from '@ember-data/request';\nimport Fetch from '@ember-data/request/fetch';\nimport Auth from 'ember-simple-auth/ember-data-handler';\n\nexport default class extends RequestManager {\n constructor(createArgs) {\n super(createArgs);\n this.use([Auth, Fetch]);\n }\n}\n```\n\n### Using with `@ember-data/store`\n\nTo have a request service unique to a Store:\n\n```ts\nimport Store, { CacheHandler } from '@ember-data/store';\nimport RequestManager from '@ember-data/request';\nimport Fetch from '@ember-data/request/fetch';\n\nclass extends Store {\n requestManager = new RequestManager();\nconstructor(args) {\n super(args);\n this.requestManager.use([Fetch]);\n this.requestManager.useCache(CacheHandler);\n }\n}\n```\n\n### Using with `ember-data`\n\nIf using the package [ember-data](https://github.com/emberjs/data/tree/main/packages/-ember-data), the following configuration will automatically be done in order to preserve the legacy [Adapter](https://github.com/emberjs/data/tree/main/packages/adapter) and [Serializer](https://github.com/emberjs/data/tree/main/packages/serializer) behavior. Additional handlers or a service injection like the above would need to be done by the consuming application in order to make broader use of `RequestManager`.\n\n```ts\nimport Store, { CacheHandler } from '@ember-data/store';\nimport RequestManager from '@ember-data/request';\nimport { LegacyNetworkHandler } from '@ember-data/legacy-compat';\n\nexport default class extends Store {\n requestManager = new RequestManager();\nconstructor(args) {\n super(args);\n this.requestManager.use([LegacyNetworkHandler]);\n this.requestManager.useCache(CacheHandler);\n }\n}\n```\n\nBecause the application's store service (if present) will override the store supplied by `ember-data`, all that is required to define your own ordering and handlers is to supply a store service extending from `@ember-data/store` and configure as shown above.\n\nFor usage of the store's `requestManager` via `store.request()` see the [Store](https://api.emberjs.com/ember-data/release/modules/@ember-data%2Fstore) documentation.", "itemtype": "main", "parent": null, "publicclasses": [ diff --git a/json-docs/ember-data/5.3.0/modules/ember-data-5.3.0-@ember-data/rest/request.json b/json-docs/ember-data/5.3.0/modules/ember-data-5.3.0-@ember-data/rest/request.json index 38f5c1515..a37387429 100644 --- a/json-docs/ember-data/5.3.0/modules/ember-data-5.3.0-@ember-data/rest/request.json +++ b/json-docs/ember-data/5.3.0/modules/ember-data-5.3.0-@ember-data/rest/request.json @@ -13,7 +13,7 @@ "tag": "main", "file": "../rest/src/request.ts", "line": 1, - "description": "

\n \n

\n\nThis package provides utilities for working with **REST**ful APIs with [*Ember***Data**](https://github.com/emberjs/data/).\n\n## Installation\n\nInstall using your javascript package manager of choice. For instance with [pnpm](https://pnpm.io/)\n\n```no-highlight\npnpm add @ember-data/json-api\n```\n\n## Usage\n\nRequest builders are functions that produce [Fetch Options](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API).\nThey take a few contextual inputs about the request you want to make, abstracting away the gnarlier details.\n\nFor instance, to fetch a resource from your API\n\n```ts\nimport { findRecord } from '@ember-data/rest/request';\n\nconst options = findRecord('ember-developer', '1', { include: ['pets', 'friends'] });\n\n/*\n => {\n url: 'https://api.example.com/v1/emberDevelopers/1?include=friends,pets',\n method: 'GET',\n headers: , // 'Content-Type': 'application/json; charset=utf-8'\n op: 'findRecord';\n records: [{ type: 'ember-developer', id: '1' }]\n }\n/\n```\n\nRequest builder output is ready to go for use with [store.request](https://api.emberjs.com/ember-data/release/classes/Store/methods/request?anchor=request),\n[manager.request](https://api.emberjs.com/ember-data/release/classes/RequestManager/methods/request?anchor=request) and most conventional REST APIs.\n\nResource types are pluralized and camelized for the url.\n\nURLs are stable. The same query will produce the same URL every time, even if the order of keys in\nthe query or values in an array changes.\n\nURLs follow the most common REST format (camelCase pluralized resource types).\n\n### Available Builders\n\n- [createRecord](https://api.emberjs.com/ember-data/release/functions/@ember-data%2Frest/createRecord)\n- [deleteRecord](https://api.emberjs.com/ember-data/release/functions/@ember-data%2Frest/deleteRecord)\n- [findRecord](https://api.emberjs.com/ember-data/release/functions/@ember-data%2Frest/findRecord)\n- [query](https://api.emberjs.com/ember-data/release/functions/@ember-data%2Frest/query)\n- [updateRecord](https://api.emberjs.com/ember-data/release/functions/@ember-data%2Frest/updateRecord)", + "description": "

\n \n

\n\nThis package provides utilities for working with **REST**ful APIs with [*Ember***Data**](https://github.com/emberjs/data/).\n\n## Installation\n\nInstall using your javascript package manager of choice. For instance with [pnpm](https://pnpm.io/)\n\n```\npnpm add @ember-data/json-api\n```\n\n## Usage\n\nRequest builders are functions that produce [Fetch Options](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API).\nThey take a few contextual inputs about the request you want to make, abstracting away the gnarlier details.\n\nFor instance, to fetch a resource from your API\n\n```ts\nimport { findRecord } from '@ember-data/rest/request';\n\nconst options = findRecord('ember-developer', '1', { include: ['pets', 'friends'] });\n\n/*\n => {\n url: 'https://api.example.com/v1/emberDevelopers/1?include=friends,pets',\n method: 'GET',\n headers: , // 'Content-Type': 'application/json; charset=utf-8'\n op: 'findRecord';\n records: [{ type: 'ember-developer', id: '1' }]\n }\n/\n```\n\nRequest builder output is ready to go for use with [store.request](https://api.emberjs.com/ember-data/release/classes/Store/methods/request?anchor=request),\n[manager.request](https://api.emberjs.com/ember-data/release/classes/RequestManager/methods/request?anchor=request) and most conventional REST APIs.\n\nResource types are pluralized and camelized for the url.\n\nURLs are stable. The same query will produce the same URL every time, even if the order of keys in\nthe query or values in an array changes.\n\nURLs follow the most common REST format (camelCase pluralized resource types).\n\n### Available Builders\n\n- [createRecord](https://api.emberjs.com/ember-data/release/functions/@ember-data%2Frest/createRecord)\n- [deleteRecord](https://api.emberjs.com/ember-data/release/functions/@ember-data%2Frest/deleteRecord)\n- [findRecord](https://api.emberjs.com/ember-data/release/functions/@ember-data%2Frest/findRecord)\n- [query](https://api.emberjs.com/ember-data/release/functions/@ember-data%2Frest/query)\n- [updateRecord](https://api.emberjs.com/ember-data/release/functions/@ember-data%2Frest/updateRecord)", "itemtype": "main", "parent": null, "publicclasses": [], diff --git a/json-docs/ember-data/5.3.0/modules/ember-data-5.3.0-ember-data-overview.json b/json-docs/ember-data/5.3.0/modules/ember-data-5.3.0-ember-data-overview.json index 3de5f2fb0..36968519d 100644 --- a/json-docs/ember-data/5.3.0/modules/ember-data-5.3.0-ember-data-overview.json +++ b/json-docs/ember-data/5.3.0/modules/ember-data-5.3.0-ember-data-overview.json @@ -11,7 +11,7 @@ "tag": "main", "file": "../-ember-data/addon/index.js", "line": 1, - "description": "

\n \n

\n\n

The lightweight reactive data library for JavaScript applications

\n\n---\n\nWrangle your application's data management with scalable patterns for developer productivity.\n\n- ⚑️ Committed to Best-In-Class Performance\n- 🌲 Focused on being as svelte as possible\n- πŸš€ SSR Ready\n- πŸ”œ Typescript Support\n- 🐹 Built with β™₯️ by [Ember](https://emberjs.com)\n- βš›οΈ Supports any API: `GraphQL` `JSON:API` `REST` `tRPC` ...bespoke or a mix\n\n### πŸ“– On This Page\n\n- [Overview](./#overview)\n - [Architecture](#πŸͺœ-architecture)\n - [Basic Installation](#basic-installation)\n - [Advanced Installation](#advanced-installation)\n- [Configuration](#configuration)\n - [Deprecation Stripping](#deprecation-stripping)\n - [randomUUID polyfill](#randomuuid-polyfill)\n - [Removing inspector support in production](#removing-inspector-support-in-production)\n - [Debugging](#debugging)\n\n\n# Overview\n\n*Ember*‍**Data** is a lightweight reactive data library for JavaScript applications that provides composable primitives for ordering query/mutation/peek flows, managing network and cache, and reducing data for presentation.\n\n## πŸͺœ Architecture\n\nThe core of *Ember*‍**Data** is the `Store`, which coordinates interaction between your application, the `Cache`, and sources of data (such as your `API` or a local persistence layer).\nOptionally, the Store can be configured to hydrate the response data into rich presentation classes.\n\n*Ember*‍**Data** is both resource centric and document centric in it's approach to caching, requesting and presenting data. Your application's configuration and usage drives which is important and when.\n\nThe `Store` is a **coordinator**. When using a `Store` you configure what cache to use, how cache data should be presented to the UI, and where it should look for requested data when it is not available in the cache.\n\nThis coordination is handled opaquely to the nature of the requests issued and the format of the data being handled. This approach gives applications broad flexibility to configure *Ember*‍**Data** to best suite their needs. This makes *Ember*‍**Data** a powerful solution for applications regardless of their size and complexity.\n\n*Ember*‍**Data** is designed to scale, with a religious focus on performance and asset-size to keep its footprint small but speedy while still being able to handle large complex APIs in huge data-driven applications with no additional code and no added application complexity. It's goal is to prevent applications from writing code to manage data that is difficult to maintain or reason about.\n\n*Ember*‍**Data**'s power comes not from specific features, data formats, or adherence to specific API specs such as `JSON:API` `trpc` or `GraphQL`, but from solid conventions around requesting and mutating data developed over decades of experience scaling developer productivity.\n\n## Basic Installation\n\nInstall using your javascript package manager of choice. For instance with [pnpm](https://pnpm.io/)\n\n```no-highlight\npnpm add ember-data\n```\n\n`ember-data` is installed by default for new applications generated with `ember-cli`. You can check what version is installed by looking in the `devDependencies` hash of your project's [package.json](https://docs.npmjs.com/cli/v8/configuring-npm/package-json) file.\n\nIf you have generated a new `Ember` application using `ember-cli` but do\nnot wish to use `ember-data`, remove `ember-data` from your project's `package.json` file and run your package manager's install command to update your lockfile.\n\n## Advanced Installation\n\n*Ember*‍**Data** is organized into primitives that compose together via public APIs.\n\n- [@ember-data/store](/ember-data/release/modules/@ember-data%2Fstore) is the core and handles coordination\n- [@ember-data/json-api](/ember-data/release/modules/@ember-data%2Fjson-api) provides a resource cache for JSON:API structured data. It integrates with the store via the hook `createCache`\n- [@ember-data/model](/ember-data/release/modules/@ember-data%2Fmodel) is a presentation layer, it integrates with the store via the hooks `instantiateRecord` and `teardownRecord`.\n- [@ember-data/adapter](/ember-data/release/modules/@ember-data%2Fadapter) provides various network API integrations for APIS built over specific REST or JSON:API conventions.\n- [@ember-data/serializer](/ember-data/release/modules/@ember-data%2Fserializer) pairs with `@ember-data/adapter` to normalize and serialize data to and from an API format into the `JSON:API` format understood by `@ember-data/json-api`.\n- [@ember-data/debug](/ember-data/release/modules/@ember-data%2Fdebug) provides debugging support for the `ember-inspector`.\n- **ember-data** is a \"meta\" package which bundles all of these together for convenience\n\nThe packages interop with each other through well defined public API boundaries. The core\nof the library is the store provided by `@ember-data/store`, while each of the other libraries plugs into the store when installed. Because these packages interop via fully\npublic APIs, other libraries or applications may provide their own implementations. For instance, [ember-m3](https://github.com/hjdivad/ember-m3) is a commonly used presentation and cache implementation suitable for complex resource objects and graphs.\n\n## Configuration\n\n### Deprecation Stripping\n\n*Ember*‍**Data** allows users to opt-in and remove code that exists to support deprecated behaviors.\n\nIf your app has resolved all deprecations present in a given version, you may specify that version as your \"compatibility\" version to remove the code that supported the deprecated behavior from your app.\n\n```ts\nlet app = new EmberApp(defaults, {\n emberData: {\n compatWith: '4.8',\n },\n});\n```\n\n- [Full Documentation](https://api.emberjs.com/ember-data/release/modules/@ember-data%2Fdeprecations)\n\n### randomUUID polyfill\n\n*Ember*‍**Data** uses `UUID V4` by default to generate identifiers for new data created on the client. Identifier generation is configurable, but we also for convenience will polyfill\nthe necessary feature if your browser support or deployment environment demands it. To\nactivate this polyfill:\n\n```ts\nlet app = new EmberApp(defaults, {\n '@embroider/macros': {\n setConfig: {\n '@ember-data/store': {\n polyfillUUID: true\n },\n },\n },\n});\n```\n\n### removing inspector support in production\n\nIf you do not with to ship inspector support in your production application, you can specify\nthat all support for it should be stripped from the build.\n\n```ts\nlet app = new EmberApp(defaults, {\n emberData: {\n includeDataAdapterInProduction: false\n }\n});\n```\n\n- [Full Documentation](https://api.emberjs.com/ember-data/release/modules/@ember-data%2Fdebug)\n\n### Debugging\n\nMany portions of the internals are helpfully instrumented with logging that can be activated\nat build time. This instrumentation is always removed from production builds or any builds\nthat has not explicitly activated it. To activate it set the appropriate flag to `true`.\n\n```ts\n let app = new EmberApp(defaults, {\n emberData: {\n debug: {\n LOG_PAYLOADS: false, // data store received to update cache with\n LOG_OPERATIONS: false, // updates to cache remote state\n LOG_MUTATIONS: false, // updates to cache local state\n LOG_NOTIFICATIONS: false,\n LOG_REQUESTS: false, // log Requests issued via the request manager\n LOG_REQUEST_STATUS: false,\n LOG_IDENTIFIERS: false,\n LOG_GRAPH: false,\n LOG_INSTANCE_CACHE: false,\n }\n }\n });\n ```", + "description": "

\n \n

\n\n

The lightweight reactive data library for JavaScript applications

\n\n---\n\nWrangle your application's data management with scalable patterns for developer productivity.\n\n- ⚑️ Committed to Best-In-Class Performance\n- 🌲 Focused on being as svelte as possible\n- πŸš€ SSR Ready\n- πŸ”œ Typescript Support\n- 🐹 Built with β™₯️ by [Ember](https://emberjs.com)\n- βš›οΈ Supports any API: `GraphQL` `JSON:API` `REST` `tRPC` ...bespoke or a mix\n\n### πŸ“– On This Page\n\n- [Overview](./#overview)\n - [Architecture](#πŸͺœ-architecture)\n - [Basic Installation](#basic-installation)\n - [Advanced Installation](#advanced-installation)\n- [Configuration](#configuration)\n - [Deprecation Stripping](#deprecation-stripping)\n - [randomUUID polyfill](#randomuuid-polyfill)\n - [Removing inspector support in production](#removing-inspector-support-in-production)\n - [Debugging](#debugging)\n\n\n# Overview\n\n*Ember*‍**Data** is a lightweight reactive data library for JavaScript applications that provides composable primitives for ordering query/mutation/peek flows, managing network and cache, and reducing data for presentation.\n\n## πŸͺœ Architecture\n\nThe core of *Ember*‍**Data** is the `Store`, which coordinates interaction between your application, the `Cache`, and sources of data (such as your `API` or a local persistence layer).\nOptionally, the Store can be configured to hydrate the response data into rich presentation classes.\n\n*Ember*‍**Data** is both resource centric and document centric in it's approach to caching, requesting and presenting data. Your application's configuration and usage drives which is important and when.\n\nThe `Store` is a **coordinator**. When using a `Store` you configure what cache to use, how cache data should be presented to the UI, and where it should look for requested data when it is not available in the cache.\n\nThis coordination is handled opaquely to the nature of the requests issued and the format of the data being handled. This approach gives applications broad flexibility to configure *Ember*‍**Data** to best suite their needs. This makes *Ember*‍**Data** a powerful solution for applications regardless of their size and complexity.\n\n*Ember*‍**Data** is designed to scale, with a religious focus on performance and asset-size to keep its footprint small but speedy while still being able to handle large complex APIs in huge data-driven applications with no additional code and no added application complexity. It's goal is to prevent applications from writing code to manage data that is difficult to maintain or reason about.\n\n*Ember*‍**Data**'s power comes not from specific features, data formats, or adherence to specific API specs such as `JSON:API` `trpc` or `GraphQL`, but from solid conventions around requesting and mutating data developed over decades of experience scaling developer productivity.\n\n## Basic Installation\n\nInstall using your javascript package manager of choice. For instance with [pnpm](https://pnpm.io/)\n\n```\npnpm add ember-data\n```\n\n`ember-data` is installed by default for new applications generated with `ember-cli`. You can check what version is installed by looking in the `devDependencies` hash of your project's [package.json](https://docs.npmjs.com/cli/v8/configuring-npm/package-json) file.\n\nIf you have generated a new `Ember` application using `ember-cli` but do\nnot wish to use `ember-data`, remove `ember-data` from your project's `package.json` file and run your package manager's install command to update your lockfile.\n\n## Advanced Installation\n\n*Ember*‍**Data** is organized into primitives that compose together via public APIs.\n\n- [@ember-data/store](/ember-data/release/modules/@ember-data%2Fstore) is the core and handles coordination\n- [@ember-data/json-api](/ember-data/release/modules/@ember-data%2Fjson-api) provides a resource cache for JSON:API structured data. It integrates with the store via the hook `createCache`\n- [@ember-data/model](/ember-data/release/modules/@ember-data%2Fmodel) is a presentation layer, it integrates with the store via the hooks `instantiateRecord` and `teardownRecord`.\n- [@ember-data/adapter](/ember-data/release/modules/@ember-data%2Fadapter) provides various network API integrations for APIS built over specific REST or JSON:API conventions.\n- [@ember-data/serializer](/ember-data/release/modules/@ember-data%2Fserializer) pairs with `@ember-data/adapter` to normalize and serialize data to and from an API format into the `JSON:API` format understood by `@ember-data/json-api`.\n- [@ember-data/debug](/ember-data/release/modules/@ember-data%2Fdebug) provides debugging support for the `ember-inspector`.\n- **ember-data** is a \"meta\" package which bundles all of these together for convenience\n\nThe packages interop with each other through well defined public API boundaries. The core\nof the library is the store provided by `@ember-data/store`, while each of the other libraries plugs into the store when installed. Because these packages interop via fully\npublic APIs, other libraries or applications may provide their own implementations. For instance, [ember-m3](https://github.com/hjdivad/ember-m3) is a commonly used presentation and cache implementation suitable for complex resource objects and graphs.\n\n## Configuration\n\n### Deprecation Stripping\n\n*Ember*‍**Data** allows users to opt-in and remove code that exists to support deprecated behaviors.\n\nIf your app has resolved all deprecations present in a given version, you may specify that version as your \"compatibility\" version to remove the code that supported the deprecated behavior from your app.\n\n```ts\nlet app = new EmberApp(defaults, {\n emberData: {\n compatWith: '4.8',\n },\n});\n```\n\n- [Full Documentation](https://api.emberjs.com/ember-data/release/modules/@ember-data%2Fdeprecations)\n\n### randomUUID polyfill\n\n*Ember*‍**Data** uses `UUID V4` by default to generate identifiers for new data created on the client. Identifier generation is configurable, but we also for convenience will polyfill\nthe necessary feature if your browser support or deployment environment demands it. To\nactivate this polyfill:\n\n```ts\nlet app = new EmberApp(defaults, {\n '@embroider/macros': {\n setConfig: {\n '@ember-data/store': {\n polyfillUUID: true\n },\n },\n },\n});\n```\n\n### removing inspector support in production\n\nIf you do not with to ship inspector support in your production application, you can specify\nthat all support for it should be stripped from the build.\n\n```ts\nlet app = new EmberApp(defaults, {\n emberData: {\n includeDataAdapterInProduction: false\n }\n});\n```\n\n- [Full Documentation](https://api.emberjs.com/ember-data/release/modules/@ember-data%2Fdebug)\n\n### Debugging\n\nMany portions of the internals are helpfully instrumented with logging that can be activated\nat build time. This instrumentation is always removed from production builds or any builds\nthat has not explicitly activated it. To activate it set the appropriate flag to `true`.\n\n```ts\n let app = new EmberApp(defaults, {\n emberData: {\n debug: {\n LOG_PAYLOADS: false, // data store received to update cache with\n LOG_OPERATIONS: false, // updates to cache remote state\n LOG_MUTATIONS: false, // updates to cache local state\n LOG_NOTIFICATIONS: false,\n LOG_REQUESTS: false, // log Requests issued via the request manager\n LOG_REQUEST_STATUS: false,\n LOG_IDENTIFIERS: false,\n LOG_GRAPH: false,\n LOG_INSTANCE_CACHE: false,\n }\n }\n });\n ```", "itemtype": "main", "parent": null, "publicclasses": [],