API
normalize(data, schema)
Normalizes input data per the schema definition provided.
根據提供的schema定義規範化輸入資料。
data
: required Input JSON (or plain JS object) data that needs normalization.schema
: required A schema definition
Usage
import { normalize, schema } from `normalizr`;
const myData = { users: [ { id: 1 }, { id: 2 } ] };
const user = new schema.Entity(`users`);
const mySchema = { users: [ user ] }
const normalizedData = normalize(myData, mySchema);複製程式碼
Output
{
result: { users: [ 1, 2 ] },
entities: {
users: {
`1`: { id: 1 },
`2`: { id: 2 }
}
}
}複製程式碼
denormalize(input, schema, entities)
Denormalizes an input based on schema and provided entities from a plain object or Immutable data. The reverse of normalize
.
基於schema和從普通物件或不可變資料提供的實體對輸入資料進行去規範化。 與規範化相反。
Be careful with denormalization. Prematurely reverting your data to large, nested objects could cause performance impacts in React (and other) applications.
小心非規範化。 過早將資料還原到大型巢狀物件可能會對React(和其他)應用程式造成效能影響。
If your schema and data have recursive references, only the first instance of an entity will be given. Subsequent references will be returned as the id
provided.
如果您的schema和資料具有遞迴引用,則只會給出實體的第一個例項。 隨後的引用將返回給ID。
input
: required The normalized result that should bede-normalized. Usually the same value that was given in the
result
key of the output ofnormalize
. 通常在規範化輸出的結果鍵中給出相同的值。schema
: required A schema definition that was used to get the value forinput
.entities
: required An object, keyed by entity schema names that may appear in the denormalized output. Also accepts an object with Immutable data.
Usage
import { denormalize, schema } from `normalizr`;
const user = new schema.Entity(`users`);
const mySchema = { users: [ user ] }
const entities = { users: { `1`: { id: 1 }, `2`: { id: 2 } } };
const denormalizedData = denormalize({ users: [ 1, 2 ] }, mySchema, entities);複製程式碼
Output
{
users: [
{ id: 1 },
{ id: 2 }
]
}複製程式碼
schema
Array(definition, schemaAttribute)
Creates a schema to normalize an array of entities. If the input value is an Object
instead of an Array
, the normalized result will be an Array
of the Object
`s values.
建立一個schema來規範化實體陣列。 如果輸入值是Object而不是Array,則歸一化結果將是Object的值的Array。
[ mySchema ]
相同的行為可以用速記語法來定義
definition
: required A singular schema that this array containsor a mapping of schema to attribute values.
需要此陣列包含的單一schema 或將schema 對映到屬性值。
schemaAttribute
:optional(required if
definition
is not a singular schema) The attribute on each entity found that defines what schema, per the definition mapping, to use when normalizing.
Can be a string or a function. If given a function, accepts the following arguments:value
: The input value of the entity.parent
: The parent object of the input array.key
: The key at which the input array appears on the parent object.
Instance Methods
define(definition)
: When used, thedefinition
passed in will be merged with the original definition passed to theArray
constructor. This method tends to be useful for creating circular references in schema.
使用時,傳入的definition
將與傳遞給Array建構函式的原始definition
合併。 該方法往往對於在schema
中建立迴圈引用很有用。
Usage
To describe a simple array of a singular entity type:
const data = [ { id: `123`, name: `Jim` }, { id: `456`, name: `Jane` } ];
const userSchema = new schema.Entity(`users`);
const userListSchema = new schema.Array(userSchema);
// or use shorthand syntax:
const userListSchema = [ userSchema ];
const normalizedData = normalize(data, userListSchema);複製程式碼
Output
{
entities: {
users: {
`123`: { id: `123`, name: `Jim` },
`456`: { id: `456`, name: `Jane` }
}
},
result: [ `123`, `456` ]
}複製程式碼
If your input data is an array of more than one type of entity, it is necessary to define a schema mapping.
如果您的輸入資料是多個型別的實體的陣列,則需要定義一個schema
對映。
如果您的資料返回一個未提供對映的物件,則將返回原始物件,並且不會建立一個實體。
For example:
const data = [ { id: 1, type: `admin` }, { id: 2, type: `user` } ];
const userSchema = new schema.Entity(`users`);
const adminSchema = new schema.Entity(`admins`);
const myArray = new schema.Array({
admins: adminSchema,
users: userSchema
}, (input, parent, key) => `${input.type}s`);
const normalizedData = normalize(data, myArray);複製程式碼
Output
{
entities: {
admins: { `1`: { id: 1, type: `admin` } },
users: { `2`: { id: 2, type: `user` } }
},
result: [
{ id: 1, schema: `admins` },
{ id: 2, schema: `users` }
]
}複製程式碼
Entity(key, definition = {}, options = {})
key
: required The key name under which all entities of this type will be listed in the normalized response. Must be a string name.definition
: A definition of the nested entities found within this entity. Defaults to empty object.
在該實體內發現的巢狀實體的definition
。 預設為空物件。
You do not need to define any keys in your entity other than those that hold nested entities. All other values will be copied to the normalized entity`s output.
您不需要在您的實體中定義任何鍵,除了巢狀實體的鍵。 所有其他值將被複制到標準化實體的輸出。definition不為空表示有巢狀。
options
:idAttribute
: The attribute where unique IDs for each of this entity type can be found.
Accepts either a stringkey
or a function that returns the IDsvalue
. Defaults to`id`
.
As a function, accepts the following arguments, in order:value
: The input value of the entity.parent
: The parent object of the input array.key
: The key at which the input array appears on the parent object. 輸入的陣列出現在父物件上的鍵。
mergeStrategy(entityA, entityB)
: Strategy to use when merging two entities with the sameid
value. Defaults to merge the more recently found entity onto the previous.
合併具有相同ID值的兩個實體時使用的策略。 預設將最近發現的實體合併到上一個實體。
-
processStrategy(value, parent, key)
: Strategy to use when pre-processing the entity. Use this method to add extra data, defaults, and/or completely change the entity before normalization is complete. Defaults to returning a shallow copy of the input entity.
預處理實體時使用的策略。 在規範化完成之前,使用此方法新增額外的資料,預設值和/或完全更改實體。 預設返回輸入實體的淺拷貝。
建議始終返回您的輸入的副本,而不是修改原件。
The function accepts the following arguments, in order:
value
: The input value of the entity.parent
: The parent object of the input array.key
: The key at which the input array appears on the parent object.
Instance Methods
define(definition)
: When used, thedefinition
passed in will be merged with the original definition passed to theEntity
constructor. This method tends to be useful for creating circular references in schema.
使用時,傳入的definition
將與傳遞給Entity建構函式的原始definition
合併。 該方法往往對於在模式中建立迴圈引用很有用。
Instance Attributes
key
: Returns the key provided to the constructor.idAttribute
: Returns the idAttribute provided to the constructor in options.
Usage
const data = { id_str: `123`, url: `https://twitter.com`, user: { id_str: `456`, name: `Jimmy` } };
const user = new schema.Entity(`users`, {}, { idAttribute: `id_str` });
const tweet = new schema.Entity(`tweets`, { user: user }, {
idAttribute: `id_str`,
// Apply everything from entityB over entityA, except for "favorites"
mergeStrategy: (entityA, entityB) => ({
...entityA,
...entityB,
favorites: entityA.favorites
}),
// Remove the URL field from the entity
processStrategy: (entity) => omit(entity, `url`)
});
const normalizedData = normalize(data, tweet);複製程式碼
Output
{
entities: {
tweets: { `123`: { id_str: `123`, user: `456` } },
users: { `456`: { id_str: `456`, name: `Jimmy` } }
},
result: `123`
}複製程式碼
idAttribute Usage
When passing the idAttribute
a function, it should return the IDs value.
idAttribute作為key
For Example:
const data = [
{ id: `1`, guest_id: null, name: `Esther` },
{ id: `1`, guest_id: `22`, name: `Tom` },
];
const patronsSchema = new schema.Entity(`patrons`, undefined, {
// idAttribute *functions* must return the ids **value** (not key)
idAttribute: value => value.guest_id ? `${value.id}-${value.guest_id}` : value.id,
});
normalize(data, [patronsSchema]);複製程式碼
Output
{
entities: {
patrons: {
`1`: { id: `1`, guest_id: null, name: `Esther` },
`1-22`: { id: `1`, guest_id: `22`, name: `Tom` },
}
},
result: [`1`, `1-22`]
}複製程式碼
Object(definition)
Define a plain object mapping that has values needing to be normalized into Entities.
定義一個普通物件對映,它需要將值歸一化為Entities。
{ ... }
definition
: required A definition of the nested entities found within this object. Defaults to empty object.
You do not need to define any keys in your object other than those that hold other entities. All other values will be copied to the normalized output.
Instance Methods
define(definition)
: When used, thedefinition
passed in will be merged with the original definition passed to theObject
constructor. This method tends to be useful for creating circular references in schema.
Usage
// Example data response
const data = { users: [ { id: `123`, name: `Beth` } ] };
const user = new schema.Entity(`users`);
const responseSchema = new schema.Object({ users: new schema.Array(user) });
// or shorthand
const responseSchema = { users: new schema.Array(user) };
const normalizedData = normalize(data, responseSchema);複製程式碼
Output
{
entities: {
users: { `123`: { id: `123`, name: `Beth` } }
},
result: { users: [ `123` ] }
}複製程式碼
Union(definition, schemaAttribute)
Describe a schema which is a union of multiple schemas. This is useful if you need the polymorphic behavior provided by schema.Array
or schema.Values
but for non-collection fields.
描述一個多個schema
的並集的schema
。 如果您需要由schema.Array
或schema.Values
提供的多型性行為,但對於非收集欄位,這是非常有用的。
definition
: required An object mapping the definition of the nested entities found within the input arrayschemaAttribute
: required The attribute on each entity found that defines what schema, per the definition mapping, to use when normalizing.
Can be a string or a function. If given a function, accepts the following arguments:value
: The input value of the entity.parent
: The parent object of the input array.key
: The key at which the input array appears on the parent object.
Instance Methods
define(definition)
: When used, thedefinition
passed in will be merged with the original definition passed to theUnion
constructor. This method tends to be useful for creating circular references in schema.
Usage
const data = { owner: { id: 1, type: `user`, name: `Anne` } };
const user = new schema.Entity(`users`);
const group = new schema.Entity(`groups`);
const unionSchema = new schema.Union({
user: user,
group: group
}, `type`);
const normalizedData = normalize(data, { owner: unionSchema });複製程式碼
Output
{
entities: {
users: { `1`: { id: 1, type: `user`, name: `Anne` } }
},
result: { owner: { id: 1, schema: `user` } }
}複製程式碼
Values(definition, schemaAttribute)
Describes a map whose values follow the given schema.
definition
: required A singular schema that this array containsor a mapping of schema to attribute values.schemaAttribute
:optional(required if
definition
is not a singular schema) The attribute on each entity found that defines what schema, per the definition mapping, to use when normalizing.
Can be a string or a function. If given a function, accepts the following arguments:value
: The input value of the entity.parent
: The parent object of the input array.key
: The key at which the input array appears on the parent object.
Instance Methods
define(definition)
: When used, thedefinition
passed in will be merged with the original definition passed to theValues
constructor. This method tends to be useful for creating circular references in schema.
Usage
const data = { firstThing: { id: 1 }, secondThing: { id: 2 } };
const item = new schema.Entity(`items`);
const valuesSchema = new schema.Values(item);
const normalizedData = normalize(data, valuesSchema);複製程式碼
Output
{
entities: {
items: { `1`: { id: 1 }, `2`: { id: 2 } }
},
result: { firstThing: 1, secondThing: 2 }
}複製程式碼
If your input data is an object that has values of more than one type of entity, but their schema is not easily defined by the key, you can use a mapping of schema, much like schema.Union
and schema.Array
.
For example:
const data = {
`1`: { id: 1, type: `admin` },
`2`: { id: 2, type: `user` }
};
const userSchema = new schema.Entity(`users`);
const adminSchema = new schema.Entity(`admins`);
const valuesSchema = new schema.Values({
admins: adminSchema,
users: userSchema
}, (input, parent, key) => `${input.type}s`);
const normalizedData = normalize(data, valuesSchema);複製程式碼
Output
{
entities: {
admins: { `1`: { id: 1, type: `admin` } },
users: { `2`: { id: 2, type: `user` } }
},
result: {
`1`: { id: 1, schema: `admins` },
`2`: { id: 2, schema: `users` }
}
}複製程式碼