@warp-drive/legacy 5.9.0-beta.0 → 5.9.0-beta.2

package/dist/index.d.ts

@@ -0,0 +1,243 @@
+import { Store, StoreSetupOptions } from "@warp-drive/core";
+import { CacheCapabilitiesManager } from "@warp-drive/core/types";
+import { Cache } from "@warp-drive/core/types/cache";
+import { ObjectSchema, ResourceSchema } from "@warp-drive/core/types/schema/fields";
+//#region src/index.d.ts
+interface _LegacyStoreSetupOptions<T extends Cache> extends Omit<StoreSetupOptions<T>, "schemas"> {
+  /**
+   * The {@link ResourceSchema | ResourceSchemas} or {@link ObjectSchema | ObjectSchemas} of entities
+   * migrated to no longer use {@link Model}.
+   *
+   * :::caution
+   * {@link Model} is still able to be used directly as a source of schema when using {@link useLegacyStore},
+   * however, its reliance on EmberObject, classic computeds and resolver behaviors mean that Model
+   * will stop working when these things are deprecated in Ember.
+   * :::
+   */
+  schemas?: Array<ResourceSchema | ObjectSchema>;
+  /**
+   * Whether to include support for ModelFragments migrations.
+   *
+   * @default false
+   */
+  modelFragments?: boolean;
+}
+/**
+ * Setup options for a legacy store configured to use `Model` with `linksMode`
+ * enabled, meaning no legacy adapter/serializer request infrastructure is required.
+ *
+ * @public
+ */
+interface LegacyModelStoreSetupOptions<T extends Cache> extends _LegacyStoreSetupOptions<T> {
+  /**
+   * If true, it is presumed that no requests require use of the LegacyNetworkHandler
+   * and associated adapters/serializer methods.
+   *
+   * If legacyRequests is true, {@link linksMode} must be false
+   *
+   * @default false
+   */
+  linksMode: true;
+  /**
+   * if true, all legacy request methods and supporting infrastructure will
+   * be available on the store.
+   *
+   * If legacyRequests is true, {@link linksMode} must be false
+   *
+   * @default false
+   */
+  legacyRequests?: false;
+}
+/**
+ * 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
+ */
+interface LegacyModelAndNetworkStoreSetupOptions<T extends Cache> extends _LegacyStoreSetupOptions<T> {
+  /**
+   * If true, it is presumed that no requests require use of the LegacyNetworkHandler
+   * and associated adapters/serializer methods.
+   *
+   * @default false
+   */
+  linksMode: false;
+  /**
+   * if true, all legacy request methods and supporting infrastructure will
+   * be available on the store.
+   *
+   * If legacyRequests is true, {@link linksMode} must be false
+   *
+   * @default false
+   */
+  legacyRequests?: false;
+}
+/**
+ * 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
+ */
+interface LegacyModelAndNetworkAndRequestStoreSetupOptions<T extends Cache> extends _LegacyStoreSetupOptions<T> {
+  /**
+   * If true, it is presumed that no requests require use of the LegacyNetworkHandler
+   * and associated adapters/serializer methods.
+   *
+   * @default false
+   */
+  linksMode: false;
+  /**
+   * if true, all legacy request methods and supporting infrastructure will
+   * be available on the store.
+   *
+   * If legacyRequests is true, {@link linksMode} must be false
+   *
+   * @default false
+   */
+  legacyRequests: true;
+}
+/**
+ * The available options when setting up the legacy store,
+ * one of:
+ *
+ * - {@link LegacyModelStoreSetupOptions}
+ * - {@link LegacyModelAndNetworkStoreSetupOptions}
+ * - {@link LegacyModelAndNetworkAndRequestStoreSetupOptions}
+ */
+type LegacyStoreSetupOptions<T extends Cache = Cache> = LegacyModelStoreSetupOptions<T> | LegacyModelAndNetworkStoreSetupOptions<T> | LegacyModelAndNetworkAndRequestStoreSetupOptions<T>;
+declare class ConfiguredStore<T extends {
+  /**
+   * The {@link Cache} implementation this store was configured with.
+   */
+  cache: Cache;
+}> extends Store {
+  createCache(capabilities: CacheCapabilitiesManager): T["cache"];
+}
+/**
+ * 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).
+ */
+declare function useLegacyStore<T extends Cache>(options: LegacyModelStoreSetupOptions<T>, StoreKlass?: typeof Store): typeof ConfiguredStore<{
+  cache: T;
+}>;
+declare function useLegacyStore<T extends Cache>(options: LegacyModelAndNetworkStoreSetupOptions<T>, StoreKlass?: typeof Store): typeof ConfiguredStore<{
+  cache: T;
+}>;
+declare function useLegacyStore<T extends Cache>(options: LegacyModelAndNetworkAndRequestStoreSetupOptions<T>, StoreKlass?: typeof Store): typeof ConfiguredStore<{
+  cache: T;
+}>;
+//#endregion
+export { ConfiguredStore, LegacyModelAndNetworkAndRequestStoreSetupOptions, LegacyModelAndNetworkStoreSetupOptions, LegacyModelStoreSetupOptions, LegacyStoreSetupOptions, useLegacyStore };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/index.ts"],"mappings":";;;;;UA0CU,yBAAyB,UAAU,eAAe,KAAK,kBAAkB;;;;;;;;;;;EAWjF,UAAU,MAAM,iBAAiB;;;;;;EAOjC;;;;;;;;UASe,6BAA6B,UAAU,eAAe,yBAAyB;;;;;;;;;EAS9F;;;;;;;;;EASA;;;;;;;;;UAUe,uCAAuC,UAAU,eAAe,yBAAyB;;;;;;;EAOxG;;;;;;;;;EASA;;;;;;;;;UAUe,iDAAiD,UAAU,eAAe,yBAAyB;;;;;;;EAOlH;;;;;;;;;EASA;;;;;;;;;;KAaU,wBAAwB,UAAU,QAAQ,SAClD,6BAA6B,KAC7B,uCAAuC,KACvC,iDAAiD;cAEhC,gBACnB;;;;EAIE,OAAO;WAED;EAER,YAAY,cAAc,2BAA2B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAqHvC,eAAe,UAAU,OACvC,SAAS,6BAA6B,IACtC,oBAAoB,eACZ;EAAkB,OAAO;;iBACnB,eAAe,UAAU,OACvC,SAAS,uCAAuC,IAChD,oBAAoB,eACZ;EAAkB,OAAO;;iBACnB,eAAe,UAAU,OACvC,SAAS,iDAAiD,IAC1D,oBAAoB,eACZ;EAAkB,OAAO"}