@warp-drive/legacy 5.8.0-alpha.30 → 5.8.0-alpha.34

package/dist/unpkg/prod/declarations/compat/utils.d.ts

@@ -0,0 +1,137 @@
+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;
+export declare function expectId(id: string | number): string;
+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/dist/unpkg/prod/declarations/compat.d.ts

@@ -0,0 +1,157 @@
+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;
+	adapterFor(this: Store, modelName: string): MinimumAdapterInterface;
+	adapterFor(this: Store, modelName: string, _allowMissing: true): MinimumAdapterInterface | undefined;
+	serializerFor<K extends string>(modelName: K, _allowMissing?: boolean): MinimumSerializerInterface | null;
+	normalize(modelName: string, payload: ObjectValue): ObjectValue;
+	pushPayload(modelName: string, payload: ObjectValue): void;
+	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;
+export declare function serializeRecord(this: Store, record: unknown, options?: SerializerOptions): unknown;
+export declare function cleanup(this: Store): void;

package/dist/unpkg/prod/declarations/index.d.ts

@@ -0,0 +1,70 @@
+/**
+* @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"> {
+	schemas?: Array<ResourceSchema | ObjectSchema>;
+	/**
+	* Whether to include support for ModelFragments migrations.
+	*/
+	modelFragments?: boolean;
+}
+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.
+	*/
+	linksMode: true;
+	/**
+	* if true, all legacy request methods and supporting infrastructure will
+	* be available on the store.
+	*/
+	legacyRequests?: false;
+}
+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.
+	*/
+	linksMode: false;
+	/**
+	* if true, all legacy request methods and supporting infrastructure will
+	* be available on the store.
+	*/
+	legacyRequests?: false;
+}
+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.
+	*/
+	linksMode: false;
+	/**
+	* if true, all legacy request methods and supporting infrastructure will
+	* be available on the store.
+	*/
+	legacyRequests: true;
+}
+export type LegacyStoreSetupOptions<T extends Cache = Cache> = LegacyModelStoreSetupOptions<T> | LegacyModelAndNetworkStoreSetupOptions<T> | LegacyModelAndNetworkAndRequestStoreSetupOptions<T>;
+export declare class ConfiguredStore<T extends {
+	cache: Cache;
+}> extends Store {
+	createCache(capabilities: CacheCapabilitiesManager): T["cache"];
+}
+/**
+* Use the legacy store with the given options.
+*/
+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 {};

package/dist/unpkg/prod/declarations/model/-private/attr.d.ts

@@ -0,0 +1,170 @@
+import type { ArrayValue, ObjectValue, PrimitiveValue } from "@warp-drive/core/types/json/raw";
+import { type TransformName } from "@warp-drive/core/types/symbols";
+import type { DecoratorPropertyDescriptor } from "./util.js";
+/**
+* Options provided to the attr decorator are
+* supplied to the associated transform. Any
+* key-value pair is valid; however, it is highly
+* recommended to only use statically defined values
+* that could be serialized to JSON.
+*
+* If no transform is provided, the only valid
+* option is `defaultValue`.
+*
+* Examples:
+*
+* ```ts
+* class User extends Model {
+*  @attr('string', { defaultValue: 'Anonymous' }) name;
+*  @attr('date', { defaultValue: () => new Date() }) createdAt;
+*  @attr({ defaultValue: () => ({}) }) preferences;
+*  @attr('boolean') hasVerifiedEmail;
+*  @attr address;
+* }
+*
+* @class NOTATHING
+*/
+export type AttrOptions<DV = PrimitiveValue | object | unknown[]> = {
+	/**
+	* The default value for this attribute.
+	*
+	* Default values can be provided as a value or a function that will be
+	* executed to generate the default value.
+	*
+	* Default values *should not* be stateful (object, arrays, etc.) as
+	* they will be shared across all instances of the record.
+	*
+	*/
+	defaultValue?: DV extends PrimitiveValue ? DV : () => DV;
+};
+type LooseTransformInstance<
+	V,
+	Raw,
+	Name extends string
+> = {
+	/**
+	* value type must match the return type of the deserialize method
+	*
+	*/
+	serialize: (value: V, options: any) => Raw;
+	/**
+	* defaultValue type must match the return type of the deserialize method
+	*
+	*/
+	deserialize: (value: Raw, options: any) => V;
+	[TransformName]: Name;
+};
+export type TransformHasType = {
+	[TransformName]: string;
+};
+export type TypedTransformInstance<
+	V,
+	T extends string
+> = LooseTransformInstance<V, string, T> | LooseTransformInstance<V, number, T> | LooseTransformInstance<V, boolean, T> | LooseTransformInstance<V, null, T> | LooseTransformInstance<V, ObjectValue, T> | LooseTransformInstance<V, ArrayValue, T> | LooseTransformInstance<V, string | null, T> | LooseTransformInstance<V, number | null, T> | LooseTransformInstance<V, boolean | null, T> | LooseTransformInstance<V, ObjectValue | null, T> | LooseTransformInstance<V, ArrayValue | null, T>;
+export type GetMaybeDeserializeValue<T> = T extends {
+	deserialize: (...args: any[]) => unknown;
+} ? ReturnType<T["deserialize"]> : never;
+export type TypeFromInstance<T> = T extends TransformHasType ? T[typeof TransformName] : never;
+export type ExtractOptions<T extends TypedTransformInstance<GetMaybeDeserializeValue<T>, TypeFromInstance<T>>> = Parameters<T["deserialize"]>[1] & Parameters<T["serialize"]>[1] & AttrOptions<ReturnType<T["deserialize"]>>;
+export type OptionsFromInstance<T> = TypeFromInstance<T> extends never ? never : GetMaybeDeserializeValue<T> extends never ? never : T extends TypedTransformInstance<GetMaybeDeserializeValue<T>, TypeFromInstance<T>> ? Parameters<T["deserialize"]>[1] & Parameters<T["serialize"]>[1] & AttrOptions<ReturnType<T["deserialize"]>> : never;
+/**
+* The return type of `void` is a lie to appease TypeScript. The actual return type
+* is a descriptor, but typescript incorrectly insists that decorator functions return
+* `void` or `any`.
+*
+*/
+export type DataDecorator = (target: object, key: string, desc?: DecoratorPropertyDescriptor) => void;
+/**
+`attr` defines an attribute on a {@link Model}.
+By default, attributes are passed through as-is, however you can specify an
+optional type to have the value automatically transformed.
+WarpDrive ships with four basic transform types: `string`, `number`,
+`boolean` and `date`. You can define your own transforms by subclassing
+{@link Transform}.
+
+Note that you cannot use `attr` to define an attribute of `id`.
+
+`attr` takes an optional hash as a second parameter, currently
+supported options are:
+
+- `defaultValue`: Pass a string or a function to be called to set the attribute
+to a default value if and only if the key is absent from the payload response.
+
+Example
+
+```js [app/models/user.js]
+import { Model, attr } from '@warp-drive/legacy/model';
+
+export default class UserModel extends Model {
+@attr('string') username;
+@attr('string') email;
+@attr('boolean', { defaultValue: false }) verified;
+}
+```
+
+Default value can also be a function. This is useful it you want to return
+a new object for each attribute.
+
+```js [app/models/user.js]
+import { Model, attr } from '@warp-drive/legacy/model';
+
+export default class UserModel extends Model {
+@attr('string') username;
+@attr('string') email;
+
+@attr({
+defaultValue() {
+return {};
+}
+})
+settings;
+}
+```
+
+The `options` hash is passed as second argument to a transforms'
+`serialize` and `deserialize` method. This allows to configure a
+transformation and adapt the corresponding value, based on the config:
+
+```js [app/models/post.js]
+import { Model, attr } from '@warp-drive/legacy/model';
+
+export default class PostModel extends Model {
+@attr('text', {
+uppercase: true
+})
+text;
+}
+```
+
+```js [app/transforms/text.js]
+export default class TextTransform {
+serialize(value, options) {
+if (options.uppercase) {
+return value.toUpperCase();
+}
+
+return value;
+}
+
+deserialize(value) {
+return value;
+}
+
+static create() {
+return new this();
+}
+}
+```
+
+@public
+@param type the attribute type
+@param options a hash of options
+*/
+export declare function attr(): DataDecorator;
+export declare function attr<T>(type: TypeFromInstance<T>): DataDecorator;
+export declare function attr(type: string): DataDecorator;
+export declare function attr(options: AttrOptions): DataDecorator;
+export declare function attr<T>(type: TypeFromInstance<T>, options?: OptionsFromInstance<T>): DataDecorator;
+export declare function attr(type: string, options?: AttrOptions & object): DataDecorator;
+export declare function attr(target: object, key: string | symbol, desc?: PropertyDescriptor): void;
+export {};