@warp-drive/legacy 5.10.0-alpha.13 → 5.10.0-alpha.14

package/dist/adapter/json-api.d.ts

@@ -1,3 +1,8 @@
+/**
+ * @module
+ * @summary Legacy `JSONAPIAdapter`, which turns store requests into HTTP requests following JSON:API URL, verb and
+ * header conventions.
+ */
 import { _ as AdapterPayload, m as Snapshot, p as SnapshotRecordArray } from "../compat-BZlQ-5eI.js";
 import { i as RESTAdapter, n as JQueryRequestInit, r as QueryState, t as FetchRequestInit } from "../rest-ddU-K5eS.js";
 import { Store } from "@warp-drive/core";

package/dist/adapter/json-api.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"json-api.d.ts","names":[],"sources":["../../src/adapter/json-api.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAmKM,uBAAuB;;;;;EAK3B;;;;;;;;EASA,YACE,aACA,MAAM,YACN,UAAS,qBAAqB,cAC7B,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;MAgEnB;MAQA,qBAAqB;EAIzB,SAAS,OAAO,OAAO,MAAM,aAAa,eAAe,WAAW,aAAa,QAAQ;;;;;;;;EAYzF,YAAY;EAKZ,aAAa,OAAO,OAAO,QAAQ,aAAa,UAAU,WAAW,QAAQ;;;;;;;;;;EAoB7E,WAAW,UAAU,WAAW,sBAAsB"}
+{"version":3,"file":"json-api.d.ts","names":[],"sources":["../../src/adapter/json-api.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAmKM,uBAAuB;;;;;EAK3B;;;;;;;;EASA,YACE,aACA,MAAM,YACN,UAAS,qBAAqB,cAC7B,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;MAgEnB;MAQA,qBAAqB;EAIzB,SAAS,OAAO,OAAO,MAAM,aAAa,eAAe,WAAW,aAAa,QAAQ;;;;;;;;EAYzF,YAAY;EAKZ,aAAa,OAAO,OAAO,QAAQ,aAAa,UAAU,WAAW,QAAQ;;;;;;;;;;EAoB7E,WAAW,UAAU,WAAW,sBAAsB"}

package/dist/adapter.d.ts

@@ -1,2 +1,220 @@
+/**
+* ## Overview
+*
+* :::danger
+*   ⚠️ **This is LEGACY documentation** for a feature that is no longer encouraged to be used.
+*   If starting a new app or thinking of implementing a new adapter, consider writing a
+*   {@link Handler} instead to be used with the {@link RequestManager}
+* ::::
+*
+* In order to properly fetch and update data, @warp-drive/legacy
+* needs to understand how to connect to your API.
+*
+* `Adapters` accept various kinds of requests from the store
+* and manage fulfillment of the request from your API.
+*
+* ### Why It's Legacy
+*
+* The Adapter pattern was designed for class-based architectures in which each resource type
+* could have its own data-fetching logic:
+*
+* - `store.adapterFor` resolves an adapter by resource type at runtime, looking up
+*   `adapter:<type>` and then `adapter:application` through Ember's owner.
+* - Each request is fulfilled by a single adapter, so sharing behavior across resource types
+*   means extending a common base class rather than composing request logic.
+* - The provided adapter classes extend `EmberObject`, which, together with the owner lookup,
+*   ties the pattern to Ember.
+* - Adapter methods resolve with an untyped `AdapterPayload`, so nothing ties the response's
+*   type to the request that produced it.
+*
+* ### Modern Alternative
+*
+* Use [Handlers](/api/@warp-drive/core/request/types/Handler) with the {@link RequestManager}.
+* Each request passes through a chain of handlers, any of which can fulfill it, modify it or
+* pass it along. Handlers support:
+*
+* - request builders, which return a request typed with its expected response, so
+*   `store.request` resolves with that type
+* - composition: `RequestManager.use` takes a list of handlers, such as the built-in `Fetch`
+*   handler, and wrappers such as `Gate` from `@warp-drive/utilities/handlers` run another
+*   handler only for the requests it accepts
+* - explicit imports rather than lookup by name at runtime
+* - any framework ***Warp*Drive** supports, since `@warp-drive/core` has no runtime
+*   dependency on Ember (see [Installation](/guides/installation/))
+*
+* For an alternative modern pattern to Adapters, see the
+* [Request Handlers Guide](/guides/the-manual/requests/handlers).
+*
+* ### Request Flow
+*
+* When the store decides it needs to issue a request it uses the following flow to manage the request and process the data.
+*
+* - find the appropriate adapter
+* - issue the request to the adapter
+* - await the adapter's response
+*   - if an error occurs reject with the error
+*   - if no error
+*      - if there is response data
+*      - pass the response data to the appropriate serializer
+*      - update the cache using the JSON:API formatted data from the serializer's response
+*    - return the primary record(s) associated with the request
+*
+* ### Request Errors
+*
+* When a request errors and your adapter does not have the ability to recover from the error,
+* you may either reject the promise returned by your adapter method with the error or simply
+* throw the error.
+*
+* If the request was for a `createRecord` `updateRecord` or `deleteRecord` special rules
+* apply to how this error will affect the state of the store and additional properties on
+* the `Error` class may be used. See the documentation for these methods in
+* {@link MinimumAdapterInterface} for more information.
+*
+* ### Implementing an Adapter
+*
+* There are seven required adapter methods, one for each of
+* the primary request types that @warp-drive/legacy issues.
+*
+* They are:
+*
+*  - findRecord
+*  - findAll
+*  - queryRecord
+*  - query
+*  - createRecord
+*  - updateRecord
+*  - deleteRecord
+*
+* Each of these request types has a matching store method that triggers it
+* and matching `requestType` that is passed to the serializer's
+* `normalizeResponse` method.
+*
+* If your app only reads data but never writes data, it is not necessary
+* to implement the methods for create, update, and delete. This extends to
+* all of the store's find methods with the exception of `findRecord` (`findAll`,
+* `query`, `queryRecord`): if you do not use the store method in your app then
+* your Adapter does not need the method.
+*
+* ```ts
+* async function fetchData(url, options = {}) {
+*   let response = await fetch(url, options);
+*   return response.toJSON();
+* }
+*
+* export default class ApplicationAdapter {
+*   findRecord(_, { modelName }, id) {
+*     return fetchData(`./${modelName}s/${id}`);
+*   }
+*
+*   static create() {
+*     return new this();
+*   }
+* }
+* ```
+*
+* ### Adapter Resolution
+*
+* `store.adapterFor(name)` will lookup adapters defined in `app/adapters/` and
+* return an instance.
+*
+* `adapterFor` first attempts to find an adapter with an exact match on `name`,
+then falls back to checking for the presence of an adapter named `application`.
+
+If no adapter is found, an error will be thrown.
+
+```ts
+store.adapterFor('author');
+
+// lookup paths (in order) =>
+//   app/adapters/author.js
+//   app/adapters/application.js
+```
+
+Most requests in @warp-drive/legacy are made with respect to a particular `type` (or `modelName`)
+(e.g., "get me the full collection of **books**" or "get me the **employee** whose id is 37"). We
+refer to this as the **primary** resource `type`.
+
+`adapterFor` is used by the store to find an adapter with a name matching that of the primary
+resource `type` for the request, which then falls back to the `application` adapter.
+
+It is recommended that applications define only a single `application` adapter and serializer
+where possible, only implementing an adapter specific to the `type` when absolutely necessary.
+
+If you need to support multiple API versions for the same type, the per-type strategy for
+defining adapters might not be adequate.
+
+If you have multiple APIs or multiple API versions and the single application adapter and per-type
+strategy does not suite your needs, one strategy is to write an `application` adapter and serializer
+that make use of `options` to specify the desired format when making a request, then forwards to the
+request to the desired adapter or serializer as needed.
+
+```js [app/adapters/application.js]
+export default class Adapter extends EmberObject {
+findRecord(store, schema, id, snapshot) {
+let { apiVersion } = snapshot.adapterOptions;
+return this.adapterFor(`-api-${apiVersion}`).findRecord(store, schema, id, snapshot);
+}
+}
+```
+
+### Overriding `Store.adapterFor`
+
+```js
+import Store from '@ember-data/store';
+import Adapter from '@ember-data/adapter/json-api';
+
+class extends Store {
+#adapter = new Adapter();
+
+adapterFor() {
+return this.#adapter;
+}
+}
+```
+
+
+Note: If you are using Ember and would like to make use of `service` injections in your adapter, you will want to additionally `setOwner` for the Adapter.
+
+```js
+import Store from '@ember-data/store';
+import Adapter from '@ember-data/adapter/json-api';
+import { getOwner, setOwner } from '@ember/owner';
+
+class extends Store {
+#adapter = null;
+
+adapterFor() {
+let adapter = this.#adapter;
+if (!adapter) {
+const owner = getOwner(this);
+adapter = new Adapter();
+setOwner(adapter, owner);
+this.#adapter = adapter;
+}
+
+return adapter;
+}
+}
+```
+
+By default when using with Ember you only need to implement this hook if you want your adapter usage to be statically analyzeable. *Ember***Data** will attempt to resolve adapters using Ember's resolver. To provide a single Adapter for your application like the above you would provide it as the default export of the file `app/adapters/application.{js/ts}`
+
+### Using an Adapter
+
+Any adapter in `app/adapters/` can be looked up by `name` using `store.adapterFor(name)`.
+
+### Default Adapters
+
+Applications whose API's structure endpoint URLs *very close to* or *exactly* the **REST**
+or **JSON:API** convention, the `@ember-data/adapter` package contains implementations
+these applications can extend.
+
+Many applications will find writing their own adapter to be allow greater flexibility,
+customization, and maintenance than attempting to override methods in these adapters.
+
+@summary Legacy adapter layer through which the store fetches and saves data from an API, superseded by
+`RequestManager` handlers.
+@module
+*/
 import { n as BuildURLMixin, t as Adapter } from "./adapter-D3A8ixjz.js";
 export { Adapter, BuildURLMixin };

package/dist/compat/builders.d.ts

@@ -1,3 +1,15 @@
+/**
+Builders for migrating from `store` methods to `store.request`.
+
+These builders enable you to migrate your codebase to using the correct syntax for `store.request` while temporarily preserving legacy behaviors.
+This is useful for quickly upgrading an entire app to a unified syntax while a longer incremental migration is made to shift off of adapters and serializers.
+To that end, these builders are deprecated and will be removed in a future version of Ember Data.
+
+@summary Deprecated request builders that move `findRecord`, `query`, and `saveRecord` calls to `store.request`
+while still using adapters and serializers.
+@module
+@deprecated
+*/
 import { StoreRequestInput } from "@warp-drive/core";
 import { RequestSignature } from "@warp-drive/core/types/symbols";
 import { FindAllOptions, FindRecordOptions, LegacyResourceQuery, QueryOptions, ResourceKey } from "@warp-drive/core/types";

package/dist/compat/builders.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"builders.d.ts","names":[],"sources":["../../src/compat/builders/find-all.ts","../../src/compat/builders/find-record.ts","../../src/compat/builders/query.ts","../../src/compat/builders/save-record.ts"],"mappings":";;;;;;KASK,oBAAoB,2BAA2B,kBAAkB;EACpE;EACA;IACE,MAAM;IACN,SAAS;;GAEV,oBAAoB;;KAGlB,wBAAwB;;;;;;;;;;;;;;;;;;iBAmBb,eAAe,UAAU,qBACvC,MAAM,iBAAiB,IACvB,UAAU,wBACT,oBAAoB,iBAAiB,IAAI;iBAC5B,eAAe,cAAc,UAAU,wBAAwB;;;KC9B1E,uBAAuB,2BAA2B,gBAAgB;EACrE;EACA;IACE,QAAQ,yBAAyB;IACjC,SAAS;;GAEV,oBAAoB;;KAGlB,2BAA2B,KAAK;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAsCrB,kBAAkB,UAAU,qBAC1C,MAAM,iBAAiB,IACvB,YACA,UAAU,2BACT,uBAAuB,iBAAiB,IAAI;iBAC/B,kBAAkB,cAAc,YAAY,UAAU,2BAA2B;iBACjF,kBAAkB,UAAU,qBAC1C,UAAU,yBAAyB,iBAAiB,KACpD,UAAU,2BACT,uBAAuB,iBAAiB,IAAI;iBAC/B,kBACd,UAAU,0BACV,UAAU,2BACT;;;KC9DE,kBAAkB,2BAA2B,kBAAkB;EAClE;EACA;IACE,MAAM;IACN,OAAO;IACP,SAAS;;GAEV,oBAAoB;;KAGlB,sBAAsB;;;;;;;;;;;;;;;;;;;iBAoBX,aAAa,UAAU,qBACrC,MAAM,iBAAiB,IACvB,OAAO,qBACP,UAAU,sBACT,kBAAkB,iBAAiB,IAAI;iBAC1B,aACd,cACA,OAAO,qBACP,UAAU,sBACT;KAwBE,wBAAwB,2BAA2B,gBAAgB;EACtE;EACA;IACE,MAAM;IACN,OAAO;IACP,SAAS;;GAEV,oBAAoB;;;;;;;;;;;;;;;;;;;;iBAqBP,mBAAmB,UAAU,qBAC3C,MAAM,iBAAiB,IACvB,OAAO,qBACP,UAAU,sBACT,wBAAwB,iBAAiB,IAAI;iBAChC,mBACd,cACA,OAAO,qBACP,UAAU,sBACT;;;KCpGE,uBAAuB,2BAA2B,gBAAgB;EACrE;EACA;IACE,QAAQ,YAAY;IACpB,SAAS;;EAEX,UAAU,YAAY;GACrB,oBAAoB;;KAGlB,2BAA2B;;;;;;;;;;;;;;;;;;iBA4BhB,kBAAkB,UAAU,qBAC1C,QAAQ,GACR,UAAS,0BACR,uBAAuB,iBAAiB,IAAI"}
+{"version":3,"file":"builders.d.ts","names":[],"sources":["../../src/compat/builders/find-all.ts","../../src/compat/builders/find-record.ts","../../src/compat/builders/query.ts","../../src/compat/builders/save-record.ts"],"mappings":";;;;;;;;;;;;;;;;;;KASK,oBAAoB,2BAA2B,kBAAkB;EACpE;EACA;IACE,MAAM;IACN,SAAS;;GAEV,oBAAoB;;KAGlB,wBAAwB;;;;;;;;;;;;;;;;;;iBAmBb,eAAe,UAAU,qBACvC,MAAM,iBAAiB,IACvB,UAAU,wBACT,oBAAoB,iBAAiB,IAAI;iBAC5B,eAAe,cAAc,UAAU,wBAAwB;;;KC9B1E,uBAAuB,2BAA2B,gBAAgB;EACrE;EACA;IACE,QAAQ,yBAAyB;IACjC,SAAS;;GAEV,oBAAoB;;KAGlB,2BAA2B,KAAK;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAsCrB,kBAAkB,UAAU,qBAC1C,MAAM,iBAAiB,IACvB,YACA,UAAU,2BACT,uBAAuB,iBAAiB,IAAI;iBAC/B,kBAAkB,cAAc,YAAY,UAAU,2BAA2B;iBACjF,kBAAkB,UAAU,qBAC1C,UAAU,yBAAyB,iBAAiB,KACpD,UAAU,2BACT,uBAAuB,iBAAiB,IAAI;iBAC/B,kBACd,UAAU,0BACV,UAAU,2BACT;;;KC9DE,kBAAkB,2BAA2B,kBAAkB;EAClE;EACA;IACE,MAAM;IACN,OAAO;IACP,SAAS;;GAEV,oBAAoB;;KAGlB,sBAAsB;;;;;;;;;;;;;;;;;;;iBAoBX,aAAa,UAAU,qBACrC,MAAM,iBAAiB,IACvB,OAAO,qBACP,UAAU,sBACT,kBAAkB,iBAAiB,IAAI;iBAC1B,aACd,cACA,OAAO,qBACP,UAAU,sBACT;KAwBE,wBAAwB,2BAA2B,gBAAgB;EACtE;EACA;IACE,MAAM;IACN,OAAO;IACP,SAAS;;GAEV,oBAAoB;;;;;;;;;;;;;;;;;;;;iBAqBP,mBAAmB,UAAU,qBAC3C,MAAM,iBAAiB,IACvB,OAAO,qBACP,UAAU,sBACT,wBAAwB,iBAAiB,IAAI;iBAChC,mBACd,cACA,OAAO,qBACP,UAAU,sBACT;;;KCpGE,uBAAuB,2BAA2B,gBAAgB;EACrE;EACA;IACE,QAAQ,YAAY;IACpB,SAAS;;EAEX,UAAU,YAAY;GACrB,oBAAoB;;KAGlB,2BAA2B;;;;;;;;;;;;;;;;;;iBA4BhB,kBAAkB,UAAU,qBAC1C,QAAQ,GACR,UAAS,0BACR,uBAAuB,iBAAiB,IAAI"}

package/dist/compat/extensions.d.ts

@@ -1,2 +1,7 @@
+/**
+ * @module
+ * @summary Legacy schema extensions that give reactive objects and arrays the classic `EmberObject` and Ember array
+ * APIs, such as `get`, `set` and `mapBy`, plus matching types.
+ */
 import { a as WithArrayLike, i as EmberObjectExtension, n as EmberArrayLikeExtension, o as WithEmberObject, r as EmberObjectArrayExtension, t as ArrayType } from "../extensions-fwdnX9n4.js";
 export { ArrayType, EmberArrayLikeExtension, EmberObjectArrayExtension, EmberObjectExtension, WithArrayLike, WithEmberObject };

package/dist/compat/utils.d.ts

@@ -163,4 +163,5 @@ export declare function isEquivType(expected: string, actual: string): boolean;
  */
 export declare function isEquivId(expected: string | number, actual: string | number | null): boolean;
 //#endregion
+export {};
 //# sourceMappingURL=utils.d.ts.map

package/dist/{errors-BI0Xugyo.js → errors-DdSAsjym.js}

@@ -1589,16 +1589,17 @@ var LegacySupport = class {
 		if (this.graph) {
 			if (!resource) return;
 			const { definition, state } = relationship;
-			/* @__PURE__ */ upgradeStore(this.store);
-			const adapter = this.store.adapterFor?.(definition.type);
-			const { isStale, hasDematerializedInverse, hasReceivedData, isEmpty, shouldForceReload } = state;
-			const allInverseRecordsAreLoaded = areAllInverseRecordsLoaded(this.store, resource);
-			const identifiers = resource.data;
-			const shouldFindViaLink = resource.links && resource.links.related && (typeof adapter?.findHasMany === "function" || typeof identifiers === "undefined") && (shouldForceReload || hasDematerializedInverse || isStale || !allInverseRecordsAreLoaded && !isEmpty);
 			const field = this.store.schema.fields({ type: definition.inverseType }).get(definition.key);
 			macroCondition(getGlobalConfig().WarpDrive.env.DEBUG) && ((test) => {
 				if (!test) throw new Error(`Expected a hasMany field definition for ${definition.inverseType}.${definition.key}`);
 			})(field && field.kind === "hasMany");
+			/* @__PURE__ */ upgradeStore(this.store);
+			const isLinksMode = Boolean(field.options.linksMode);
+			const adapter = isLinksMode ? void 0 : this.store.adapterFor?.(definition.type);
+			const { isStale, hasDematerializedInverse, hasReceivedData, isEmpty, shouldForceReload } = state;
+			const allInverseRecordsAreLoaded = areAllInverseRecordsLoaded(this.store, resource);
+			const identifiers = resource.data;
+			const shouldFindViaLink = resource.links && resource.links.related && (isLinksMode || typeof adapter?.findHasMany === "function" || typeof identifiers === "undefined") && (shouldForceReload || hasDematerializedInverse || isStale || !allInverseRecordsAreLoaded && !isEmpty);
 			const request = {
 				useLink: shouldFindViaLink,
 				field,
@@ -1620,6 +1621,12 @@ var LegacySupport = class {
 					method: "GET",
 					records: identifiers || [],
 					data: request,
+					options: {
+						field,
+						identifier: parentIdentifier,
+						links: resource.links,
+						meta: resource.meta
+					},
 					[EnableHydration]: false
 				} : {
 					op: "findHasMany",
@@ -1685,6 +1692,12 @@ var LegacySupport = class {
 				method: "GET",
 				records: identifier ? [identifier] : [],
 				data: request,
+				options: {
+					field,
+					identifier: parentIdentifier,
+					links: resource.links,
+					meta: resource.meta
+				},
 				[EnableHydration]: false
 			} : {
 				op: "findBelongsTo",
@@ -2140,4 +2153,4 @@ var Errors = class extends ArrayProxyWithCustomOverrides {
 
 //#endregion
 export { PromiseManyArray as a, releaseLegacySupport as i, LEGACY_SUPPORT as n, PromiseBelongsTo as o, lookupLegacySupport as r, Errors as t };
-//# sourceMappingURL=errors-BI0Xugyo.js.map
+//# sourceMappingURL=errors-DdSAsjym.js.map