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

package/declarations/compat/utils.d.ts

@@ -1,148 +0,0 @@
-type Reporter = (type: "formatted-id" | "formatted-type", actual: unknown, expected: unknown) => void;
-/**
-* Configure a function to be called when an id or type
-* changes during normalization. This is useful for instrumenting
-* to discover places where usage in the app is not consistent.
-*
-* @param fn - a function which takes a mismatch-type ('formatted-id' | 'formatted-type'), actual, and expected value
-* @public
-*/
-export declare function configureMismatchReporter(fn: Reporter): void;
-/**
-* Configure a function to be called when an id or type
-* fails validation. This is useful for instrumenting
-* to discover places where usage in the app is not consistent.
-*
-* @param fn - a function which takes a message and a condition
-* @public
-*/
-export declare function configureAssertFn(fn: (message: string, condition: unknown) => void): void;
-/**
-* Configure a function to be called to normalize
-* a resource type string. Used by both formattedType
-* and isEquivType to ensure consistent normalization
-* during comparison.
-*
-* If validation fails or the type turns out be unnormalized
-* the configured mismatch reporter and assert functions will
-* be called.
-*
-* @param fn - a function which takes a string and returns a string
-* @public
-*/
-export declare function configureTypeNormalization(fn: (type: string) => string): void;
-/**
-* Converts a potentially unnormalized type into the format expected
-* by our WarpDrive Cache. Currently this is singular-dasherized.
-*
-* you should not rely on this function to give you an exact format
-* for display purposes. Formatting for display should be handled
-* differently if the exact format matters.
-*
-* Asserts invalid types (undefined, null, '') in dev.
-*
-* **Usage**
-*
-* ```js
-* import formattedType from 'soxhub-client/helpers/formatted-type';
-*
-* formattedType('post'); // => 'post'
-* formattedType('posts'); // => 'post'
-* formattedType('Posts'); // => 'post'
-* formattedType('post-comment'); // => 'post-comment'
-* formattedType('post-comments'); // => 'post-comment'
-* formattedType('post_comment'); // => 'post-comment'
-* formattedType('postComment'); // => 'post-comment'
-* formattedType('PostComment'); // => 'post-comment'
-* ```
-*
-* @param type the potentially un-normalized type
-* @return the normalized type
-* @public
-*/
-export declare function formattedType<T extends string>(type: T | string): T;
-/**
-* Format an id to the format expected by the WarpDrive Cache.
-* Currently this means that id should be `string | null`.
-*
-* Asserts invalid IDs (undefined, '', 0, '0') in dev.
-*
-* **Usage**
-*
-* ```js
-* import formattedId from 'client/utils/formatted-id';
-*
-* formattedId('1'); // => '1'
-* formattedId(1); // => '1'
-* formattedId(null); // => null
-*	```
-*
-* @param id the potentially un-normalized id
-* @return the normalized id
-* @public
-*/
-export declare function formattedId(id: string | number): string;
-export declare function formattedId(id: null): null;
-export declare function formattedId(id: string | number | null): string | null;
-/**
-* Like {@link formattedId}, but asserts that `id` is not `null` rather
-* than allowing and passing through `null`.
-*
-* @public
-*/
-export declare function expectId(id: string | number): string;
-/**
-* Throws, since `id` is `null`.
-*
-* @public
-*/
-export declare function expectId(id: null): never;
-/**
-* Compares two types for strict equality, converting them to
-* the format expected by the WarpDrive Cache to ensure
-* differences in format are accounted for in the comparison.
-*
-* Asserts when expected or actual are invalid types in dev.
-* Expected may never be null.
-*
-* ```js
-* isEquivType('posts', 'post'); // true
-* isEquivType('post', 'post'); // true
-* isEquivType('posts', 'posts'); // true
-* isEquivType('post-comment', 'postComment'); // true
-* isEquivType('post-comment', 'PostComment'); // true
-* isEquivType('post-comment', 'post_comment'); // true
-* isEquivType('post-comment', 'post-comment'); // true
-* isEquivType('post-comment', 'post'); // false
-* isEquivType('posts', null); // false
-* ```
-*
-* @param expected a potentially unnormalized type to match against
-* @param actual a potentially unnormalized type to match against
-* @return true if the types are equivalent
-* @public
-*/
-export declare function isEquivType(expected: string, actual: string): boolean;
-/**
-* Compares two IDs for strict equality, converting them to
-* the format expected by the WarpDrive Cache to ensure
-* differences in format are accounted for in the comparison.
-*
-* Asserts when expected or actual are invalid IDs in dev.
-* Expected may never be null.
-*
-* ```js
-* isEquivId('1', 1); // true
-* isEquivId('2', '2'); // true
-* isEquivId(3, '3'); // true
-* isEquivId(4, '3'); // false
-* isEquivId(1, null); // false
-* ```
-*
-* @param expected a potentially un-normalized id to match against
-* @param actual a potentially un-normalized id to match against
-* @return true if the ids are equivalent
-* @public
-*/
-export declare function isEquivId(expected: string | number, actual: string | number | null): boolean;
-export {};

package/declarations/compat.d.ts

@@ -1,189 +0,0 @@
-import { type Store } from "@warp-drive/core";
-import type { ObjectValue } from "@warp-drive/core/types/json/raw";
-import type { SingleResourceDocument } from "@warp-drive/core/types/spec/json-api-raw";
-import { FetchManager } from "./compat/-private.js";
-import type { AdapterPayload, MinimumAdapterInterface } from "./compat/legacy-network-handler/minimum-adapter-interface.js";
-import type { MinimumSerializerInterface, SerializerOptions } from "./compat/legacy-network-handler/minimum-serializer-interface.js";
-export { LegacyNetworkHandler } from "./compat/legacy-network-handler/legacy-network-handler.js";
-export type { MinimumAdapterInterface, MinimumSerializerInterface, SerializerOptions, AdapterPayload };
-/**
-* Extends the signature of {@link Store} with additional
-* methods available when using the legacy network layer.
-*
-* @public
-* @noInheritDoc
-* @legacy
-*/
-export interface LegacyStoreCompat extends Store {
-	/**
-	* @private
-	*/
-	_fetchManager: FetchManager;
-	/**
-	* Returns the adapter instance for the given model type, instantiating
-	* it (and caching the instance) if necessary. See {@link adapterFor}.
-	*/
-	adapterFor(this: Store, modelName: string): MinimumAdapterInterface;
-	/**
-	* Same as the single-argument overload, but returns `undefined` instead
-	* of throwing/asserting when `_allowMissing` is `true` and no adapter
-	* is found.
-	*/
-	adapterFor(this: Store, modelName: string, _allowMissing: true): MinimumAdapterInterface | undefined;
-	/**
-	* Returns the serializer instance for the given model type, instantiating
-	* it (and caching the instance) if necessary. See {@link serializerFor}.
-	*/
-	serializerFor<K extends string>(modelName: K, _allowMissing?: boolean): MinimumSerializerInterface | null;
-	/**
-	* Normalizes a payload for the given model type using its serializer.
-	* See {@link normalize}.
-	*/
-	normalize(modelName: string, payload: ObjectValue): ObjectValue;
-	/**
-	* Pushes a payload into the store using the appropriate serializer to
-	* normalize it first. See {@link pushPayload}.
-	*/
-	pushPayload(modelName: string, payload: ObjectValue): void;
-	/**
-	* Serializes a record using its serializer. See {@link serializeRecord}.
-	*/
-	serializeRecord(record: unknown, options?: SerializerOptions): unknown;
-	/**
-	* @private
-	*/
-	_adapterCache: Record<string, MinimumAdapterInterface & {
-		store: Store;
-	}>;
-	/**
-	* @private
-	*/
-	_serializerCache: Record<string, MinimumSerializerInterface & {
-		store: Store;
-	}>;
-}
-/**
-* @deprecated - use {@link LegacyStoreCompat} instead
-*/
-export type CompatStore = LegacyStoreCompat;
-/**
-Returns an instance of the adapter for a given type. For
-example, `adapterFor('person')` will return an instance of
-the adapter located at `app/adapters/person.js`
-
-If no `person` adapter is found, this method will look
-for an `application` adapter (the default adapter for
-your entire application).
-
-@public
-@param modelName
-*/
-export declare function adapterFor(this: Store, modelName: string): MinimumAdapterInterface;
-export declare function adapterFor(this: Store, modelName: string, _allowMissing: true): MinimumAdapterInterface | undefined;
-/**
-Returns an instance of the serializer for a given type. For
-example, `serializerFor('person')` will return an instance of
-`App.PersonSerializer`.
-
-If no `App.PersonSerializer` is found, this method will look
-for an `App.ApplicationSerializer` (the default serializer for
-your entire application).
-
-If a serializer cannot be found on the adapter, it will fall back
-to an instance of `JSONSerializer`.
-
-@public
-@param modelName the record to serialize
-*/
-export declare function serializerFor(this: Store, modelName: string): MinimumSerializerInterface | null;
-/**
-`normalize` converts a json payload into the normalized form expected by
-{@link Store.push | push} using the serializer specified by `modelName`
-
-:::warning
-Generally it would be better to invoke the serializer yourself directly,
-or write a more specialized normalization utility.
-:::
-
-Example
-
-```js
-socket.on('message', function(message) {
-let modelName = message.model;
-let data = message.data;
-store.push(store.normalize(modelName, data));
-});
-```
-
-@legacy
-@public
-@param modelName The name of the model type for this payload
-@return The normalized payload
-*/
-export declare function normalize(this: Store, modelName: string, payload: ObjectValue): SingleResourceDocument;
-/**
-Push some raw data into the store.
-
-This method can be used both to push in brand new
-records, as well as to update existing records. You
-can push in more than one type of object at once.
-All objects should be in the format expected by the
-serializer.
-
-```js [app/serializers/application.js]
-import RESTSerializer from '@warp-drive/legacy/serializer/rest';
-
-export default class ApplicationSerializer extends RESTSerializer;
-```
-
-```js
-let pushData = {
-posts: [
-{ id: 1, postTitle: "Great post", commentIds: [2] }
-],
-comments: [
-{ id: 2, commentBody: "Insightful comment" }
-]
-}
-
-store.pushPayload(pushData);
-```
-
-By default, the data will be deserialized using a default
-serializer (the application serializer if it exists).
-
-Alternatively, `pushPayload` will accept a model type which
-will determine which serializer will process the payload.
-
-```js [app/serializers/application.js]
-import RESTSerializer from '@warp-drive/legacy/serializer/rest';
-
-export default class ApplicationSerializer extends RESTSerializer;
-```
-
-```js [app/serializers/post.js]
-import JSONSerializer from '@warp-drive/legacy/serializer/json';
-
-export default JSONSerializer;
-```
-
-```js
-store.pushPayload(pushData); // Will use the application serializer
-store.pushPayload('post', pushData); // Will use the post serializer
-```
-
-@public
-@param modelName Optionally, a model type used to determine which serializer will be used
-@param inputPayload
-*/
-export declare function pushPayload(this: Store, modelName: string, inputPayload: ObjectValue): void;
-/**
-* Serializes a record using the store's legacy network layer, as with
-* {@link LegacyStoreCompat.serializeRecord | store.serializeRecord}.
-*/
-export declare function serializeRecord(this: Store, record: unknown, options?: SerializerOptions): unknown;
-/**
-* Destroys any adapters/serializers the legacy network layer has created
-* for this store, invoked when the store itself is destroyed.
-*/
-export declare function cleanup(this: Store): void;

package/declarations/index.d.ts

@@ -1,244 +0,0 @@
-/**
-* @module
-* @mergeModuleWith <project>
-*/
-import { Store, type StoreSetupOptions } from "@warp-drive/core";
-import type { CacheCapabilitiesManager } from "@warp-drive/core/types";
-import type { Cache } from "@warp-drive/core/types/cache";
-import type { ObjectSchema, ResourceSchema } from "@warp-drive/core/types/schema/fields";
-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
-*/
-export 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
-*/
-export 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
-*/
-export 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}
-*/
-export type LegacyStoreSetupOptions<T extends Cache = Cache> = LegacyModelStoreSetupOptions<T> | LegacyModelAndNetworkStoreSetupOptions<T> | LegacyModelAndNetworkAndRequestStoreSetupOptions<T>;
-export 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).
-*/
-export declare function useLegacyStore<T extends Cache>(options: LegacyModelStoreSetupOptions<T>, StoreKlass?: typeof Store): typeof ConfiguredStore<{
-	cache: T;
-}>;
-export declare function useLegacyStore<T extends Cache>(options: LegacyModelAndNetworkStoreSetupOptions<T>, StoreKlass?: typeof Store): typeof ConfiguredStore<{
-	cache: T;
-}>;
-export declare function useLegacyStore<T extends Cache>(options: LegacyModelAndNetworkAndRequestStoreSetupOptions<T>, StoreKlass?: typeof Store): typeof ConfiguredStore<{
-	cache: T;
-}>;
-export {};