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

package/declarations/serializer/-private/transforms/transform.d.ts

@@ -1,118 +0,0 @@
-import EmberObject from "@ember/object";
-import type { LegacyAttributeField } from "@warp-drive/core/types/schema/fields";
-export interface Transform {
-	/**
-	When given a deserialized value from a record attribute this
-	method must return the serialized value.
-	
-	Example
-	
-	```javascript
-	serialize(deserialized, options) {
-	return deserialized ? null : Number(deserialized);
-	}
-	```
-	
-	@public
-	@param deserialized The deserialized value
-	@param options hash of options passed to `attr`
-	@return The serialized value
-	*/
-	serialize(value: unknown, options: LegacyAttributeField["options"]): unknown;
-	/**
-	When given a serialized value from a JSON object this method must
-	return the deserialized value for the record attribute.
-	
-	Example
-	
-	```javascript
-	deserialize(serialized, options) {
-	return empty(serialized) ? null : Number(serialized);
-	}
-	```
-	
-	@public
-	@param serialized The serialized value
-	@param options hash of options passed to `attr`
-	@return The deserialized value
-	*/
-	deserialize(value: unknown, options: LegacyAttributeField["options"]): unknown;
-}
-/**
-The `Transform` class is used to serialize and deserialize model
-attributes when they are saved or loaded from an
-adapter. Subclassing `Transform` is useful for creating custom
-attributes. All subclasses of `Transform` must implement a
-`serialize` and a `deserialize` method.
-
-Example
-
-```js [app/transforms/temperature.js]
-
-// Converts centigrade in the JSON to fahrenheit in the app
-export default class TemperatureTransform {
-deserialize(serialized, options) {
-return (serialized *  1.8) + 32;
-}
-
-serialize(deserialized, options) {
-return (deserialized - 32) / 1.8;
-}
-
-static create() {
-return new this();
-}
-}
-```
-
-Usage
-
-```js [app/models/requirement.js]
-import { Model, attr } from '@warp-drive/legacy/model';
-
-export default class RequirementModel extends Model {
-@attr('string') name;
-@attr('temperature') temperature;
-}
-```
-
-The options passed into the `attr` function when the attribute is
-declared on the model is also available in the transform.
-
-```js [app/models/post.js]
-import { Model, attr } from '@warp-drive/legacy/model';
-
-export default class PostModel extends Model {
-@attr('string') title;
-@attr('markdown', {
-markdown: {
-gfm: false,
-sanitize: true
-}
-})
-markdown;
-}
-```
-
-```js [app/transforms/markdown.js]
-export default class MarkdownTransform {
-serialize(deserialized, options) {
-return deserialized.raw;
-}
-
-deserialize(serialized, options) {
-let markdownOptions = options.markdown || {};
-
-return marked(serialized, markdownOptions);
-}
-
-static create() {
-return new this();
-}
-}
-```
-
-@class Transform
-@public
-*/
-export declare const Transform: typeof EmberObject;

package/declarations/serializer/-private/utils.d.ts

@@ -1,3 +0,0 @@
-type Coercable = string | number | boolean | null | undefined | symbol;
-export declare function coerceId(id: Coercable): string | null;
-export {};

package/declarations/serializer/rest.d.ts

@@ -1,51 +0,0 @@
-/**
-* :::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}
-:::
-
-Normally, applications will use the `RESTSerializer` by implementing
-the `normalize` method.
-
-This allows you to do whatever kind of munging you need and is
-especially useful if your server is inconsistent and you need to
-do munging differently for many different kinds of responses.
-
-See the `normalize` documentation for more information.
-
-## Across the Board Normalization
-
-There are also a number of hooks that you might find useful to define
-across-the-board rules for your payload. These rules will be useful
-if your server is consistent, or if you're building an adapter for
-an infrastructure service, like Firebase, and want to encode service
-conventions.
-
-For example, if all of your keys are underscored and all-caps, but
-otherwise consistent with the names you use in your models, you
-can implement across-the-board rules for how to convert an attribute
-name in your model to a key in your JSON.
-
-```js [app/serializers/application.js]
-import { RESTSerializer } from '@warp-drive/legacy/serializer/rest';
-import { underscore } from '<app-name>/utils/string-utils';
-
-export default class ApplicationSerializer extends RESTSerializer {
-keyForAttribute(attr, method) {
-return underscore(attr).toUpperCase();
-}
-}
-```
-
-You can also implement `keyForRelationship`, which takes the name
-of the relationship as the first parameter, the kind of
-relationship (`hasMany` or `belongsTo`) as the second parameter, and
-the method (`serialize` or `deserialize`) as the third parameter.
-
-@class RESTSerializer
-@public
-*/
-declare const RESTSerializer: any;
-export { EmbeddedRecordsMixin } from "./-private/embedded-records-mixin.js";
-export { RESTSerializer };

package/declarations/serializer/transform.d.ts

@@ -1,5 +0,0 @@
-export { Transform } from "./-private/transforms/transform.js";
-export { BooleanTransform } from "./-private/transforms/boolean.js";
-export { DateTransform } from "./-private/transforms/date.js";
-export { NumberTransform } from "./-private/transforms/number.js";
-export { StringTransform } from "./-private/transforms/string.js";

package/declarations/serializer.d.ts

@@ -1,254 +0,0 @@
-/**
-## 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 serializer, consider writing a
-{@link Handler} instead to be used with the {@link RequestManager}
-:::
-
-In order to properly manage and present your data, WarpDrive
-needs to understand the structure of data it receives.
-
-`Serializers` convert data between the server's API format and
-the format WarpDrive understands.
-
-Data received from an API response is **normalized** into
-[{json:api}](https://jsonapi.org/) (the format used internally
-by WarpDrive), while data sent to an API is **serialized**
-into the format the API expects.
-
-### Implementing a Serializer
-
-There are only two required serializer methods, one for
-normalizing data from the server API format into {json:api}, and
-another for serializing records via `Snapshots` into the expected
-server API format.
-
-To implement a serializer, export a class that conforms to the structure
-described by {@link MinimumSerializerInterface}
-from the `app/serializers/` directory. An example is below.
-
-```ts
-import EmberObject from '@ember/object';
-
-export default class ApplicationSerializer extends EmberObject {
-normalizeResponse(store, schema, rawPayload) {
-return rawPayload;
-}
-
-serialize(snapshot, options) {
-const serializedResource = {
-id: snapshot.id,
-type: snapshot.modelName,
-attributes: snapshot.attributes()
-};
-
-return serializedResource;
-}
-}
-```
-
-
-### Serializer Resolution
-
-`store.serializerFor(name)` will lookup serializers defined in
-`app/serializers/` and return an instance. If no serializer is found, an
-error will be thrown.
-
-`serializerFor` first attempts to find a serializer with an exact match on `name`,
-then falls back to checking for the presence of a serializer named `application`.
-
-```ts
-store.serializerFor('author');
-
-// lookup paths (in order) =>
-//   app/serializers/author.js
-//   app/serializers/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`.
-
-Typically `serializerFor` will be used to find a serializer with a name matching that of the primary
-resource `type` for the request, falling back to the `application` serializer for those types that
-do not have a defined serializer. This is often described as a `per-model` or `per-type` strategy
-for defining serializers. However, because APIs rarely format payloads per-type but rather
-per-API-version, this may not be a desired strategy.
-
-It is recommended that applications define only a single `application` adapter and serializer
-where possible.
-
-If you have multiple API formats and the per-type strategy is not viable, one strategy is to
-write an `application` adapter and serializer that make use of `options` to specify the desired
-format when making a request.
-
-### Using a Serializer
-
-Any serializer in `app/serializers/` can be looked up by `name` using `store.serializerFor(name)`.
-
-### Default Serializers
-
-For applications whose APIs are *very close to* or *exactly* the **REST** format or **JSON:API**
-format the `@warp-drive/legacy/serializer` package contains implementations these applications can
-extend. It also contains a simple `JSONSerializer` for serializing to/from very basic JSON objects.
-
-Many applications will find writing their own serializer to be more performant and less
-complex than extending these classes even when their API format is very close to that expected
-by these serializers.
-
-It is recommended that apps write their own serializer to best suit the needs of their API and
-application.
-
-@module
-*/
-import EmberObject from "@ember/object";
-import type { Store } from "@warp-drive/core";
-import type { ModelSchema } from "@warp-drive/core/types";
-import type { EmptyResourceDocument, SingleResourceDocument } from "@warp-drive/core/types/spec/json-api-raw";
-/**
-> ⚠️ CAUTION you likely want the docs for {@link MinimumSerializerInterface}
-> as extending this abstract class is unnecessary.
-
-`Serializer` is an abstract base class that you may override in your
-application to customize it for your backend. The minimum set of methods
-that you should implement is:
-
-* `normalizeResponse()`
-* `serialize()`
-
-And you can optionally override the following methods:
-
-* `normalize()`
-
-For an example implementation, see the included {@link JSONSerializer}.
-
-@class Serializer
-@public
-*/
-export declare class Serializer extends EmberObject {
-	store: Store;
-	/**
-	The `store` property is the application's `store` that contains
-	all records. It can be used to look up serializers for other model
-	types that may be nested inside the payload response.
-	
-	Example:
-	
-	```js
-	Serializer.extend({
-	extractRelationship(relationshipModelName, relationshipHash) {
-	let modelClass = this.store.modelFor(relationshipModelName);
-	let relationshipSerializer = this.store.serializerFor(relationshipModelName);
-	return relationshipSerializer.normalize(modelClass, relationshipHash);
-	}
-	});
-	```
-	
-	@property store
-	@type {Store}
-	@public
-	*/
-	/**
-	The `normalizeResponse` method is used to normalize a payload from the
-	server to a JSON-API Document.
-	
-	http://jsonapi.org/format/#document-structure
-	
-	Example:
-	
-	```js
-	Serializer.extend({
-	normalizeResponse(store, primaryModelClass, payload, id, requestType) {
-	if (requestType === 'findRecord') {
-	return this.normalize(primaryModelClass, payload);
-	} else {
-	return payload.reduce(function(documentHash, item) {
-	let { data, included } = this.normalize(primaryModelClass, item);
-	documentHash.included.push(...included);
-	documentHash.data.push(data);
-	return documentHash;
-	}, { data: [], included: [] })
-	}
-	}
-	});
-	```
-	
-	@since 1.13.0
-	@public
-	@param {Store} store
-	@param {Model} primaryModelClass
-	@param {Object} payload
-	@param {String|Number} id
-	@param {String} requestType
-	@return {Object} JSON-API Document
-	*/
-	/**
-	The `serialize` method is used when a record is saved in order to convert
-	the record into the form that your external data source expects.
-	
-	`serialize` takes an optional `options` hash with a single option:
-	
-	- `includeId`: If this is `true`, `serialize` should include the ID
-	in the serialized object it builds.
-	
-	Example:
-	
-	```js
-	Serializer.extend({
-	serialize(snapshot, options) {
-	let json = {
-	id: snapshot.id
-	};
-	
-	snapshot.eachAttribute((key, attribute) => {
-	json[key] = snapshot.attr(key);
-	});
-	
-	snapshot.eachRelationship((key, relationship) => {
-	if (relationship.kind === 'belongsTo') {
-	json[key] = snapshot.belongsTo(key, { id: true });
-	} else if (relationship.kind === 'hasMany') {
-	json[key] = snapshot.hasMany(key, { ids: true });
-	}
-	});
-	
-	return json;
-	},
-	});
-	```
-	
-	@public
-	@param {Snapshot} snapshot
-	@param {Object} [options]
-	@return {Object}
-	*/
-	/**
-	The `normalize` method is used to convert a payload received from your
-	external data source into the normalized form `store.push()` expects. You
-	should override this method, munge the hash and return the normalized
-	payload.
-	
-	Example:
-	
-	```js
-	Serializer.extend({
-	normalize(modelClass, resourceHash) {
-	let data = {
-	id:            resourceHash.id,
-	type:          modelClass.modelName,
-	attributes:    resourceHash
-	};
-	return { data: data };
-	}
-	})
-	```
-	
-	@public
-	@param {Model} typeClass
-	@param {Object} hash
-	@return {Object}
-	*/
-	normalize(_typeClass: ModelSchema, hash: Record<string, unknown>): SingleResourceDocument | EmptyResourceDocument;
-}

package/declarations/store/-private.d.ts

@@ -1,223 +0,0 @@
-import { type InstanceCache } from "@warp-drive/core/store/-private";
-import type { NewResourceKey, ResourceKey } from "@warp-drive/core/types/identifier";
-import type { Value } from "@warp-drive/core/types/json/raw";
-import type { OpaqueRecordInstance, TypedRecordInstance, TypeFromInstance } from "@warp-drive/core/types/record";
-import type { LegacyAttributeField, LegacyRelationshipField } from "@warp-drive/core/types/schema/fields";
-import type { SingleResourceDocument } from "@warp-drive/core/types/spec/json-api-raw";
-import type { Store } from "../store.js";
-export declare function preloadData(store: Store, identifier: NewResourceKey, preload: Record<string, Value>): void;
-export interface BaseFinderOptions {
-	reload?: boolean;
-	backgroundReload?: boolean;
-	include?: string | string[];
-	adapterOptions?: Record<string, unknown>;
-}
-export interface FindRecordOptions extends BaseFinderOptions {
-	/**
-	* Data to preload into the store before the request is made.
-	* This feature is *highly* discouraged and has no corresponding
-	* feature when using builders and handlers.
-	*
-	* Excepting relationships: the data should be in the form of a
-	* JSON object where the keys are fields on the record and the value
-	* is the raw value to be added to the cache.
-	*
-	* Relationships can either be provided as string IDs from which
-	* an identifier will be built base upon the relationship's expected
-	* resource type, or be record instances from which the identifier
-	* will be extracted.
-	*
-	*/
-	preload?: Record<string, Value>;
-}
-export type QueryOptions = { [K in string | "adapterOptions"]? : K extends "adapterOptions" ? Record<string, unknown> : unknown };
-export type FindAllOptions = BaseFinderOptions;
-export type LegacyResourceQuery = {
-	include?: string | string[];
-	[key: string]: Value | undefined;
-};
-export type KeyOrString<T> = keyof T & string extends never ? string : keyof T & string;
-/**
-* Minimum subset of static schema methods and properties on the
-* "model" class.
-*
-* Only used when using the legacy schema-service implementation
-* for @ember-data/model or when wrapping schema for legacy
-* Adapters/Serializers.
-*
-*/
-export interface ModelSchema<T = unknown> {
-	modelName: T extends TypedRecordInstance ? TypeFromInstance<T> : string;
-	fields: Map<KeyOrString<T>, "attribute" | "belongsTo" | "hasMany">;
-	attributes: Map<KeyOrString<T>, LegacyAttributeField>;
-	relationshipsByName: Map<KeyOrString<T>, LegacyRelationshipField>;
-	eachAttribute<K extends KeyOrString<T>>(callback: (this: ModelSchema<T>, key: K, attribute: LegacyAttributeField) => void, binding?: T): void;
-	eachRelationship<K extends KeyOrString<T>>(callback: (this: ModelSchema<T>, key: K, relationship: LegacyRelationshipField) => void, binding?: T): void;
-	eachTransformedAttribute<K extends KeyOrString<T>>(callback: (this: ModelSchema<T>, key: K, type: string | null) => void, binding?: T): void;
-}
-export declare function resourceIsFullyDeleted(instanceCache: InstanceCache, identifier: ResourceKey): boolean;
-/**
-A `RecordReference` is a low-level API that allows users and
-addon authors to perform meta-operations on a record.
-
-@hideconstructor
-@public
-*/
-export declare class RecordReference {
-	constructor(store: Store, identifier: ResourceKey);
-	get type(): string;
-	/**
-	The `id` of the record that this reference refers to.
-	
-	Together, the `type` and `id` properties form a composite key for
-	the identity map.
-	
-	Example
-	
-	```javascript
-	let userRef = store.getReference('user', 1);
-	
-	userRef.id(); // '1'
-	```
-	
-	@public
-	@return The id of the record.
-	*/
-	id(): string | null;
-	/**
-	The `identifier` of the record that this reference refers to.
-	
-	Together, the `type` and `id` properties form a composite key for
-	the identity map.
-	
-	Example
-	
-	```javascript
-	let userRef = store.getReference('user', 1);
-	
-	userRef.identifier(); // '1'
-	```
-	
-	@public
-	@return The identifier of the record.
-	*/
-	identifier(): ResourceKey;
-	/**
-	How the reference will be looked up when it is loaded. Currently
-	this always returns `identity` to signify that a record will be
-	loaded by its `type` and `id`.
-	
-	Example
-	
-	```javascript
-	const userRef = store.getReference('user', 1);
-	
-	userRef.remoteType(); // 'identity'
-	```
-	
-	@public
-	*/
-	remoteType(): "identity";
-	/**
-	This API allows you to provide a reference with new data. The
-	simplest usage of this API is similar to `store.push`: you provide a
-	normalized hash of data and the object represented by the reference
-	will update.
-	
-	If you pass a promise to `push`, Ember Data will not ask the adapter
-	for the data if another attempt to fetch it is made in the
-	interim. When the promise resolves, the underlying object is updated
-	with the new data, and the promise returned by *this function* is resolved
-	with that object.
-	
-	For example, `recordReference.push(promise)` will be resolved with a
-	record.
-	
-	Example
-	
-	```javascript
-	let userRef = store.getReference('user', 1);
-	
-	// provide data for reference
-	userRef.push({
-	data: {
-	id: "1",
-	type: "user",
-	attributes: {
-	username: "@user"
-	}
-	}
-	}).then(function(user) {
-	userRef.value() === user;
-	});
-	```
-	
-	@public
-	@param objectOrPromise a JSON:API ResourceDocument or a promise resolving to one
-	@return a promise for the value (record or relationship)
-	*/
-	push(objectOrPromise: SingleResourceDocument | Promise<SingleResourceDocument>): Promise<OpaqueRecordInstance>;
-	/**
-	If the entity referred to by the reference is already loaded, it is
-	present as `reference.value`. Otherwise the value returned by this function
-	is `null`.
-	
-	Example
-	
-	```javascript
-	let userRef = store.getReference('user', 1);
-	
-	userRef.value(); // user
-	```
-	
-	@public
-	@return {Model} the record for this RecordReference
-	*/
-	value(): OpaqueRecordInstance | null;
-	/**
-	Triggers a fetch for the backing entity based on its `remoteType`
-	(see `remoteType` definitions per reference type).
-	
-	Example
-	
-	```javascript
-	let userRef = store.getReference('user', 1);
-	
-	// load user (via store.find)
-	userRef.load().then(...)
-	```
-	
-	@public
-	@return the record for this RecordReference
-	*/
-	load(): Promise<unknown>;
-	/**
-	Reloads the record if it is already loaded. If the record is not
-	loaded it will load the record via `store.findRecord`
-	
-	Example
-	
-	```javascript
-	let userRef = store.getReference('user', 1);
-	
-	// or trigger a reload
-	userRef.reload().then(...)
-	```
-	
-	@public
-	@return the record for this RecordReference
-	*/
-	reload(): Promise<unknown>;
-}
-export declare function getShimClass<T>(store: Store, modelName: T extends TypedRecordInstance ? TypeFromInstance<T> : string): ShimModelClass<T>;
-export declare class ShimModelClass<T = unknown> implements ModelSchema<T> {
-	__store: Store;
-	modelName: T extends TypedRecordInstance ? TypeFromInstance<T> : string;
-	constructor(store: Store, modelName: T extends TypedRecordInstance ? TypeFromInstance<T> : string);
-	get fields(): Map<KeyOrString<T>, "attribute" | "belongsTo" | "hasMany">;
-	get attributes(): Map<KeyOrString<T>, LegacyAttributeField>;
-	get relationshipsByName(): Map<KeyOrString<T>, LegacyRelationshipField>;
-	eachAttribute<K extends KeyOrString<T>>(callback: (key: K, attribute: LegacyAttributeField) => void, binding?: T): void;
-	eachRelationship<K extends KeyOrString<T>>(callback: (key: K, relationship: LegacyRelationshipField) => void, binding?: T): void;
-	eachTransformedAttribute<K extends KeyOrString<T>>(callback: (key: K, type: string | null) => void, binding?: T): void;
-}

package/declarations/store.d.ts

@@ -1,3 +0,0 @@
-import type { Store } from "@warp-drive/core";
-export declare function restoreDeprecatedStoreBehaviors(StoreKlass: typeof Store): void;
-export { Store };