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

package/dist/unpkg/prod-deprecated/declarations/serializer/-private/transforms/string.d.ts

@@ -0,0 +1,29 @@
+import type { TransformName } from "@warp-drive/core/types/symbols";
+export interface StringTransform {
+	[TransformName]: "string";
+}
+/**
+The `StringTransform` class is used to serialize and deserialize
+string attributes on Ember Data record objects. This transform is
+used when `string` is passed as the type parameter to the
+{@link attr} function.
+
+Usage
+
+```js [app/models/user.js]
+import Model, { attr, belongsTo } from '@ember-data/model';
+
+export default class UserModel extends Model {
+@attr('boolean') isAdmin;
+@attr('string') name;
+@attr('string') email;
+}
+```
+
+@public
+*/
+export declare class StringTransform {
+	deserialize(serialized: unknown, _options?: Record<string, unknown>): string | null;
+	serialize(deserialized: unknown, _options?: Record<string, unknown>): string | null;
+	static create(): StringTransform;
+}

package/dist/unpkg/prod-deprecated/declarations/serializer/-private/transforms/transform.d.ts

@@ -0,0 +1,118 @@
+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/dist/unpkg/prod-deprecated/declarations/serializer/-private/utils.d.ts

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

package/dist/unpkg/prod-deprecated/declarations/serializer/json-api.d.ts

@@ -0,0 +1,123 @@
+/**
+* :::danger
+⚠️ <strong>This is LEGACY documentation</strong> 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}
+:::
+
+In WarpDrive a Serializer is used to serialize and deserialize
+records when they are transferred in and out of an external source.
+This process involves normalizing property names, transforming
+attribute values and serializing relationships.
+
+`JSONAPISerializer` supports the http://jsonapi.org/ spec and is the
+serializer recommended by Ember Data.
+
+This serializer normalizes a JSON API payload that looks like:
+
+```js [app/models/player.js]
+import Model, { attr, belongsTo } from '@warp-drive/legacy/model';
+
+export default class Player extends Model {
+@attr('string') name;
+@attr('string') skill;
+@attr('number') gamesPlayed;
+@belongsTo('club') club;
+}
+```
+
+```js [app/models/club.js]
+import Model, { attr, hasMany } from '@warp-drive/legacy/model';
+
+export default class Club extends Model {
+@attr('string') name;
+@attr('string') location;
+@hasMany('player') players;
+}
+```
+
+```js
+{
+"data": [
+{
+"attributes": {
+"name": "Benfica",
+"location": "Portugal"
+},
+"id": "1",
+"relationships": {
+"players": {
+"data": [
+{
+"id": "3",
+"type": "players"
+}
+]
+}
+},
+"type": "clubs"
+}
+],
+"included": [
+{
+"attributes": {
+"name": "Eusebio Silva Ferreira",
+"skill": "Rocket shot",
+"games-played": 431
+},
+"id": "3",
+"relationships": {
+"club": {
+"data": {
+"id": "1",
+"type": "clubs"
+}
+}
+},
+"type": "players"
+}
+]
+}
+```
+
+to the format that the Ember Data store expects.
+
+### Customizing meta
+
+Since a JSON API Document can have meta defined in multiple locations you can
+use the specific serializer hooks if you need to customize the meta.
+
+One scenario would be to camelCase the meta keys of your payload. The example
+below shows how this could be done using `normalizeArrayResponse` and
+`extractRelationship`.
+
+```js [app/serializers/application.js]
+import JSONAPISerializer from '@warp-drive/legacy/serializer/json-api';
+
+export default class ApplicationSerializer extends JSONAPISerializer {
+normalizeArrayResponse(store, primaryModelClass, payload, id, requestType) {
+let normalizedDocument = super.normalizeArrayResponse(...arguments);
+
+// Customize document meta
+normalizedDocument.meta = camelCaseKeys(normalizedDocument.meta);
+
+return normalizedDocument;
+}
+
+extractRelationship(relationshipHash) {
+let normalizedRelationship = super.extractRelationship(...arguments);
+
+// Customize relationship meta
+normalizedRelationship.meta = camelCaseKeys(normalizedRelationship.meta);
+
+return normalizedRelationship;
+}
+}
+```
+
+@since 1.13.0
+@class JSONAPISerializer
+@public
+*/
+declare const JSONAPISerializer: any;
+export { JSONAPISerializer };

package/dist/unpkg/prod-deprecated/declarations/serializer/json.d.ts

@@ -0,0 +1,75 @@
+/**
+* :::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}
+:::
+
+In WarpDrive a Serializer is used to serialize and deserialize
+records when they are transferred in and out of an external source.
+This process involves normalizing property names, transforming
+attribute values and serializing relationships.
+
+By default, WarpDrive uses and recommends the `JSONAPISerializer`.
+
+`JSONSerializer` is useful for simpler or legacy backends that may
+not support the http://jsonapi.org/ spec.
+
+For example, given the following `User` model and JSON payload:
+
+```js [app/models/user.js]
+import Model, { attr, belongsTo, hasMany } from '@warp-drive/legacy/model';
+
+export default class UserModel extends Model {
+@hasMany('user') friends;
+@belongsTo('location') house;
+
+@attr('string') name;
+}
+```
+
+```js
+{
+id: 1,
+name: 'Sebastian',
+friends: [3, 4],
+links: {
+house: '/houses/lefkada'
+}
+}
+```
+
+`JSONSerializer` will normalize the JSON payload to the JSON API format that the
+Ember Data store expects.
+
+You can customize how JSONSerializer processes its payload by passing options in
+the `attrs` hash or by subclassing the `JSONSerializer` and overriding hooks:
+
+- To customize how a single record is normalized, use the `normalize` hook.
+- To customize how `JSONSerializer` normalizes the whole server response, use the
+`normalizeResponse` hook.
+- To customize how `JSONSerializer` normalizes a specific response from the server,
+use one of the many specific `normalizeResponse` hooks.
+- To customize how `JSONSerializer` normalizes your id, attributes or relationships,
+use the `extractId`, `extractAttributes` and `extractRelationships` hooks.
+
+The `JSONSerializer` normalization process follows these steps:
+
+1. `normalizeResponse`
+- entry method to the serializer.
+2. `normalizeCreateRecordResponse`
+- a `normalizeResponse` for a specific operation is called.
+3. `normalizeSingleResponse`|`normalizeArrayResponse`
+- for methods like `createRecord` we expect a single record back, while for methods like `findAll` we expect multiple records back.
+4. `normalize`
+- `normalizeArrayResponse` iterates and calls `normalize` for each of its records while `normalizeSingle`
+calls it once. This is the method you most likely want to subclass.
+5. `extractId` | `extractAttributes` | `extractRelationships`
+- `normalize` delegates to these methods to
+turn the record payload into the JSON API format.
+
+@class JSONSerializer
+@public
+*/
+declare const JSONSerializer: any;
+export { JSONSerializer };

package/dist/unpkg/prod-deprecated/declarations/serializer/rest.d.ts

@@ -0,0 +1,51 @@
+/**
+* :::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/dist/unpkg/prod-deprecated/declarations/serializer/transform.d.ts

@@ -0,0 +1,5 @@
+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/dist/unpkg/prod-deprecated/declarations/serializer.d.ts

@@ -0,0 +1,254 @@
+/**
+## 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;
+}