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

package/dist/unpkg/dev/index.js

@@ -7,12 +7,12 @@ import '@ember/object';
 import '@warp-drive/core/types/symbols';
 import '@warp-drive/utilities/string';
 import '@warp-drive/core/store/-private';
-import "./errors-DmGGJr3T.js";
-import "./schema-provider-DDVYxmUV.js";
-import { i as instantiateRecord, t as teardownRecord, m as modelFor } from "./hooks-CkYiE6Ud.js";
+import "./errors-DngRU-If.js";
+import "./schema-provider-0D7f-QOn.js";
+import { i as instantiateRecord, t as teardownRecord, m as modelFor } from "./hooks-UuiLxWxS.js";
 import '@ember/application';
 import { registerDerivations as registerDerivations$1, DelegatingSchemaService } from './model/migration-support.js';
-import { F as FragmentExtension, a as FragmentArrayExtension, f as fragmentsModelFor } from "./model-for-CqXsIKws.js";
+import { F as FragmentExtension, a as FragmentArrayExtension, f as fragmentsModelFor } from "./model-for-CXkJw59V.js";
 import { restoreDeprecatedStoreBehaviors } from './store.js';
 
 /**
@@ -20,10 +20,153 @@ import { restoreDeprecatedStoreBehaviors } from './store.js';
  * @mergeModuleWith <project>
  */
 
+/**
+ * Setup options for a legacy store configured to use `Model` with `linksMode`
+ * enabled, meaning no legacy adapter/serializer request infrastructure is required.
+ *
+ * @public
+ */
+
+/**
+ * Setup options for a legacy store configured to use `Model` along with the
+ * legacy adapter/serializer network layer, but without the deprecated
+ * `store.findRecord`/`findAll`/`query`/etc. request methods.
+ *
+ * @public
+ */
+
+/**
+ * Setup options for a legacy store configured to use `Model` along with the
+ * legacy adapter/serializer network layer and the deprecated
+ * `store.findRecord`/`findAll`/`query`/etc. request methods.
+ *
+ * @public
+ */
+
 //export type ConfiguredStore<T = unknown> = typeof Store;
 
+/**
+ * The available options when setting up the legacy store,
+ * one of:
+ *
+ * - {@link LegacyModelStoreSetupOptions}
+ * - {@link LegacyModelAndNetworkStoreSetupOptions}
+ * - {@link LegacyModelAndNetworkAndRequestStoreSetupOptions}
+ */
+
 /**
  * Use the legacy store with the given options.
+ *
+ * See {@link LegacyStoreSetupOptions} for details on the available options.
+ *
+ * ```ts
+ * import { useLegacyStore } from '@warp-drive/legacy';
+ * import { JSONAPICache } from '@warp-drive/json-api';
+ *
+ * export default useLegacyStore({
+ *   linksMode: false,
+ *   legacyRequests: true,
+ *   cache: JSONAPICache,
+ *   schemas: [],
+ * });
+ * ```
+ *
+ * ### Adding Stateful Handlers
+ *
+ * A request {@link Handler} is sometimes more than a plain object or class
+ * with a `request` method — it may need access to a stateful dependency such
+ * as an Ember service (an auth token, a feature-flags service, an i18n
+ * helper, etc.).
+ *
+ * A plain class handler that only relies on Ember's `@service` decorator will
+ * not work here on its own: the handler is never instantiated *through*
+ * Ember's container (it's just `new`'d up), so it has no owner and its
+ * `@service` injections would fail to resolve.
+ *
+ * Instead, give `handlers` a function. It receives the {@link Store} instance
+ * being configured, which by the time the function runs already has an owner
+ * assigned. Use `getOwner`/`setOwner` from `@ember/owner` to transfer that
+ * owner onto your handler instance before returning it, exactly as you would
+ * when constructing any other DI-aware object outside of the container:
+ *
+ * ```ts
+ * import { getOwner, setOwner } from '@ember/owner';
+ * import { service } from '@ember/service';
+ * import { useLegacyStore } from '@warp-drive/legacy';
+ * import type { NextFn } from '@warp-drive/core/request';
+ * import type { RequestContext } from '@warp-drive/core/types/request';
+ * import { JSONAPICache } from '@warp-drive/json-api';
+ *
+ * class AuthHandler {
+ *   @service session;
+ *
+ *   request<T>(context: RequestContext, next: NextFn<T>) {
+ *     const headers = new Headers(context.request.headers);
+ *     headers.append('Authorization', `Bearer ${this.session.accessToken}`);
+ *     return next(Object.assign({}, context.request, { headers }));
+ *   }
+ * }
+ *
+ * export default useLegacyStore({
+ *   linksMode: false,
+ *   legacyRequests: true,
+ *   cache: JSONAPICache,
+ *   handlers: (store) => {
+ *     const authHandler = new AuthHandler();
+ *     setOwner(authHandler, getOwner(store)!);
+ *     return [authHandler];
+ *   },
+ * });
+ * ```
+ *
+ * The `handlers` function is invoked lazily and only once per store instance,
+ * the first time `store.requestManager` is accessed, so it is safe to do
+ * owner-dependent setup like this inside of it.
+ *
+ * ### Accessing the Store from a Handler's Context
+ *
+ * If a handler only needs to read something *off of the store itself*
+ * (its cache, or a property/service you've attached to a custom store
+ * subclass) rather than an unrelated Ember service, there is a second,
+ * simpler option that requires no DI/`setOwner` wiring at all.
+ *
+ * Every request issued via {@link Store.request | store.request(...)}
+ * automatically carries the originating store along as
+ * {@link RequestInfo.store | context.request.store}. Any handler — a plain
+ * object, a function-built handler, or a class — can read it directly,
+ * without needing the `handlers` callback form shown above:
+ *
+ * ```ts
+ * import { useLegacyStore } from '@warp-drive/legacy';
+ * import type { NextFn } from '@warp-drive/core/request';
+ * import type { RequestContext } from '@warp-drive/core/types/request';
+ * import { JSONAPICache } from '@warp-drive/json-api';
+ *
+ * const LoggingHandler = {
+ *   request<T>(context: RequestContext, next: NextFn<T>) {
+ *     // only present when the request was made via `store.request(...)`
+ *     const store = context.request.store;
+ *     if (store) {
+ *       console.log(`[${store.constructor.name}] ${context.request.url ?? ''}`);
+ *     }
+ *     return next(context.request);
+ *   },
+ * };
+ *
+ * export default useLegacyStore({
+ *   linksMode: false,
+ *   legacyRequests: true,
+ *   cache: JSONAPICache,
+ *   handlers: [LoggingHandler],
+ * });
+ * ```
+ *
+ * The trade-off versus the `getOwner`/`setOwner` pattern above is that
+ * `context.request.store` is only populated for requests issued via
+ * `store.request(...)`; a request made directly against a
+ * {@link RequestManager} won't have it set unless the caller supplies it
+ * explicitly, so a handler relying on it should treat it as optional (as
+ * `LoggingHandler` does above).
  */
 
 function useLegacyStore(options, StoreKlass = Store) {
@@ -35,7 +178,30 @@ function useLegacyStore(options, StoreKlass = Store) {
   // we extend the store to ensure we don't leak our prototype overrides to other stores below.
   class BaseKlass extends StoreKlass {}
   class LegacyConfiguredStore extends BaseKlass {
-    requestManager = new RequestManager().use([options.linksMode ? null : LegacyNetworkHandler, ...(options.handlers ?? []), Fetch].filter(Boolean)).useCache(CacheHandler);
+    constructor(createArgs) {
+      super(createArgs);
+      // installed via defineProperty (rather than a class field/accessor) so that
+      // this lazy override of the inherited `requestManager` field does not
+      // conflict with the documented pattern of assigning it directly on
+      // consumer-authored Store subclasses. The setter preserves the ability
+      // to replace `requestManager` outright after construction.
+      let requestManager;
+      Object.defineProperty(this, 'requestManager', {
+        configurable: true,
+        enumerable: true,
+        get: () => {
+          if (!requestManager) {
+            const handlersOption = options.handlers;
+            const handlers = typeof handlersOption === 'function' ? handlersOption(this) : handlersOption ?? [];
+            requestManager = new RequestManager().use([options.linksMode ? null : LegacyNetworkHandler, ...handlers, Fetch].filter(Boolean)).useCache(CacheHandler);
+          }
+          return requestManager;
+        },
+        set: value => {
+          requestManager = value;
+        }
+      });
+    }
     lifetimes = options.policy ?? new DefaultCachePolicy({
       apiCacheHardExpires: 15 * 60 * 1000,
       // 15 minutes
@@ -115,14 +281,6 @@ function useLegacyStore(options, StoreKlass = Store) {
     }
     modelFor(type) {
       assertType(this.schema, type);
-      // TODO I'm not sure this is right
-      (test => {
-        if (!test) {
-          throw new Error(`modelFor should only be used to lookup legacy models when in linksMode: false`);
-        }
-      })(!options.linksMode || !this.schema.isDelegated({
-        type
-      }));
       const klass =
       // prefer real models if present
       modelFor.call(this, type) || (