Skip to content
This repository was archived by the owner on Mar 20, 2022. It is now read-only.

Commit 4d94a0d

Browse files
ntuckerntucker
committed
update docs
1 parent 06d25bd commit 4d94a0d

File tree

1 file changed

+79
-74
lines changed

1 file changed

+79
-74
lines changed

‎docs/api.md

+79-74
Original file line numberDiff line numberDiff line change
@@ -3,11 +3,11 @@
33
* [normalize](#normalizedata-schema)
44
* [denormalize](#denormalizeinput-schema-entities)
55
* [schema](#schema)
6-
- [Array](#arraydefinition-schemaattribute)
7-
- [Entity](#entitykey-definition---options--)
8-
- [Object](#objectdefinition)
9-
- [Union](#uniondefinition-schemaattribute)
10-
- [Values](#valuesdefinition-schemaattribute)
6+
* [Array](#arraydefinition-schemaattribute)
7+
* [Entity](#entitykey-definition---options--)
8+
* [Object](#objectdefinition)
9+
* [Union](#uniondefinition-schemaattribute)
10+
* [Values](#valuesdefinition-schemaattribute)
1111

1212
## `normalize(data, schema)`
1313

@@ -21,9 +21,9 @@ Normalizes input data per the schema definition provided.
2121
```js
2222
import { normalize, schema } from 'normalizr';
2323

24-
const myData = { users: [ { id: 1 }, { id: 2 } ] };
24+
const myData = { users: [{ id: 1 }, { id: 2 }] };
2525
const user = new schema.Entity('users');
26-
const mySchema = { users: [ user ] }
26+
const mySchema = { users: [user] };
2727
const normalizedData = normalize(myData, mySchema);
2828
```
2929

@@ -45,11 +45,11 @@ const normalizedData = normalize(myData, mySchema);
4545

4646
Denormalizes an input based on schema and provided entities from a plain object or Immutable data. The reverse of `normalize`.
4747

48-
*Special Note:* Be careful with denormalization. Prematurely reverting your data to large, nested objects could cause performance impacts in React (and other) applications.
48+
_Special Note:_ Be careful with denormalization. Prematurely reverting your data to large, nested objects could cause performance impacts in React (and other) applications.
4949

5050
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.
5151

52-
* `input`: **required** The normalized result that should be *de-normalized*. Usually the same value that was given in the `result` key of the output of `normalize`.
52+
* `input`: **required** The normalized result that should be _de-normalized_. Usually the same value that was given in the `result` key of the output of `normalize`.
5353
* `schema`: **required** A schema definition that was used to get the value for `input`.
5454
* `entities`: **required** An object, keyed by entity schema names that may appear in the denormalized output. Also accepts an object with Immutable data.
5555

@@ -59,36 +59,32 @@ If your schema and data have recursive references, only the first instance of an
5959
import { denormalize, schema } from 'normalizr';
6060

6161
const user = new schema.Entity('users');
62-
const mySchema = { users: [ user ] }
62+
const mySchema = { users: [user] };
6363
const entities = { users: { '1': { id: 1 }, '2': { id: 2 } } };
64-
const denormalizedData = denormalize({ users: [ 1, 2 ] }, mySchema, entities);
64+
const denormalizedData = denormalize({ users: [1, 2] }, mySchema, entities);
6565
```
6666

6767
### Output
6868

6969
```js
70-
{
71-
users: [
72-
{ id: 1 },
73-
{ id: 2 }
74-
]
70+
{
71+
users: [{ id: 1 }, { id: 2 }];
7572
}
7673
```
7774

7875
## `schema`
7976

8077
### `Array(definition, schemaAttribute)`
8178

82-
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.
79+
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.
8380

84-
*Note: The same behavior can be defined with shorthand syntax: `[ mySchema ]`*
81+
_Note: The same behavior can be defined with shorthand syntax: `[ mySchema ]`_
8582

86-
* `definition`: **required** A singular schema that this array contains *or* a mapping of schema to attribute values.
87-
* `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.
88-
Can be a string or a function. If given a function, accepts the following arguments:
89-
* `value`: The input value of the entity.
90-
* `parent`: The parent object of the input array.
91-
* `key`: The key at which the input array appears on the parent object.
83+
* `definition`: **required** A singular schema that this array contains _or_ a mapping of schema to attribute values.
84+
* `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.
85+
Can be a string or a function. If given a function, accepts the following arguments:
86+
_ `value`: The input value of the entity.
87+
_ `parent`: The parent object of the input array. \* `key`: The key at which the input array appears on the parent object.
9288

9389
#### Instance Methods
9490

@@ -99,12 +95,12 @@ Can be a string or a function. If given a function, accepts the following argume
9995
To describe a simple array of a singular entity type:
10096

10197
```js
102-
const data = [ { id: '123', name: 'Jim' }, { id: '456', name: 'Jane' } ];
98+
const data = [{ id: '123', name: 'Jim' }, { id: '456', name: 'Jane' }];
10399
const userSchema = new schema.Entity('users');
104100

105101
const userListSchema = new schema.Array(userSchema);
106102
// or use shorthand syntax:
107-
const userListSchema = [ userSchema ];
103+
const userListSchema = [userSchema];
108104

109105
const normalizedData = normalize(data, userListSchema);
110106
```
@@ -123,21 +119,24 @@ const normalizedData = normalize(data, userListSchema);
123119
}
124120
```
125121

126-
If your input data is an array of more than one type of entity, it is necessary to define a schema mapping.
122+
If your input data is an array of more than one type of entity, it is necessary to define a schema mapping.
127123

128-
*Note: If your data returns an object that you did not provide a mapping for, the original object will be returned in the result and an entity will not be created.*
124+
_Note: If your data returns an object that you did not provide a mapping for, the original object will be returned in the result and an entity will not be created._
129125

130126
For example:
131127

132128
```js
133-
const data = [ { id: 1, type: 'admin' }, { id: 2, type: 'user' } ];
129+
const data = [{ id: 1, type: 'admin' }, { id: 2, type: 'user' }];
134130

135131
const userSchema = new schema.Entity('users');
136132
const adminSchema = new schema.Entity('admins');
137-
const myArray = new schema.Array({
138-
admins: adminSchema,
139-
users: userSchema
140-
}, (input, parent, key) => `${input.type}s`);
133+
const myArray = new schema.Array(
134+
{
135+
admins: adminSchema,
136+
users: userSchema
137+
},
138+
(input, parent, key) => `${input.type}s`
139+
);
141140

142141
const normalizedData = normalize(data, myArray);
143142
```
@@ -159,23 +158,23 @@ const normalizedData = normalize(data, myArray);
159158

160159
### `Entity(key, definition = {}, options = {})`
161160

162-
* `key`: **required** The key name under which all entities of this type will be listed in the normalized response. Must be a string name.
161+
* `key`: **required** The key name under which all entities of this type will be listed in the normalized response. Must be a string name or [Symbol](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol).
163162
* `definition`: A definition of the nested entities found within this entity. Defaults to empty object.
164-
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.
163+
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.
165164
* `options`:
166-
- `idAttribute`: The attribute where unique IDs for each of this entity type can be found.
165+
* `idAttribute`: The attribute where unique IDs for each of this entity type can be found.
167166
Accepts either a string `key` or a function that returns the IDs `value`. Defaults to `'id'`.
168-
As a function, accepts the following arguments, in order:
169-
* `value`: The input value of the entity.
170-
* `parent`: The parent object of the input array.
171-
* `key`: The key at which the input array appears on the parent object.
172-
- `mergeStrategy(entityA, entityB)`: Strategy to use when merging two entities with the same `id` value. Defaults to merge the more recently found entity onto the previous.
173-
- `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.
174-
*Note: It is recommended to always return a copy of your input and not modify the original.*
175-
The function accepts the following arguments, in order:
176-
* `value`: The input value of the entity.
177-
* `parent`: The parent object of the input array.
178-
* `key`: The key at which the input array appears on the parent object.
167+
As a function, accepts the following arguments, in order:
168+
* `value`: The input value of the entity.
169+
* `parent`: The parent object of the input array.
170+
* `key`: The key at which the input array appears on the parent object.
171+
* `mergeStrategy(entityA, entityB)`: Strategy to use when merging two entities with the same `id` value. Defaults to merge the more recently found entity onto the previous.
172+
* `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.
173+
_Note: It is recommended to always return a copy of your input and not modify the original._
174+
The function accepts the following arguments, in order:
175+
* `value`: The input value of the entity.
176+
* `parent`: The parent object of the input array.
177+
* `key`: The key at which the input array appears on the parent object.
179178

180179
#### Instance Methods
181180

@@ -192,7 +191,10 @@ You *do not* need to define any keys in your entity other than those that hold n
192191
const data = { id_str: '123', url: 'https://twitter.com', user: { id_str: '456', name: 'Jimmy' } };
193192

194193
const user = new schema.Entity('users', {}, { idAttribute: 'id_str' });
195-
const tweet = new schema.Entity('tweets', { user: user }, {
194+
const tweet = new schema.Entity(
195+
'tweets',
196+
{ user: user },
197+
{
196198
idAttribute: 'id_str',
197199
// Apply everything from entityB over entityA, except for "favorites"
198200
mergeStrategy: (entityA, entityB) => ({
@@ -202,7 +204,8 @@ const tweet = new schema.Entity('tweets', { user: user }, {
202204
}),
203205
// Remove the URL field from the entity
204206
processStrategy: (entity) => omit(entity, 'url')
205-
});
207+
}
208+
);
206209

207210
const normalizedData = normalize(data, tweet);
208211
```
@@ -221,19 +224,16 @@ const normalizedData = normalize(data, tweet);
221224

222225
#### `idAttribute` Usage
223226

224-
When passing the `idAttribute` a function, it should return the IDs value.
227+
When passing the `idAttribute` a function, it should return the IDs value.
225228

226229
For Example:
227230

228231
```js
229-
const data = [
230-
{ id: '1', guest_id: null, name: 'Esther' },
231-
{ id: '1', guest_id: '22', name: 'Tom' },
232-
];
232+
const data = [{ id: '1', guest_id: null, name: 'Esther' }, { id: '1', guest_id: '22', name: 'Tom' }];
233233

234234
const patronsSchema = new schema.Entity('patrons', undefined, {
235235
// idAttribute *functions* must return the ids **value** (not key)
236-
idAttribute: value => value.guest_id ? `${value.id}-${value.guest_id}` : value.id,
236+
idAttribute: (value) => (value.guest_id ? `${value.id}-${value.guest_id}` : value.id)
237237
});
238238

239239
normalize(data, [patronsSchema]);
@@ -253,13 +253,12 @@ normalize(data, [patronsSchema]);
253253
}
254254
```
255255

256-
257256
### `Object(definition)`
258257

259-
Define a plain object mapping that has values needing to be normalized into Entities. *Note: The same behavior can be defined with shorthand syntax: `{ ... }`*
258+
Define a plain object mapping that has values needing to be normalized into Entities. _Note: The same behavior can be defined with shorthand syntax: `{ ... }`_
260259

261260
* `definition`: **required** A definition of the nested entities found within this object. Defaults to empty object.
262-
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.
261+
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.
263262

264263
#### Instance Methods
265264

@@ -269,7 +268,7 @@ You *do not* need to define any keys in your object other than those that hold o
269268

270269
```js
271270
// Example data response
272-
const data = { users: [ { id: '123', name: 'Beth' } ] };
271+
const data = { users: [{ id: '123', name: 'Beth' }] };
273272

274273
const user = new schema.Entity('users');
275274
const responseSchema = new schema.Object({ users: new schema.Array(user) });
@@ -296,7 +295,7 @@ Describe a schema which is a union of multiple schemas. This is useful if you ne
296295

297296
* `definition`: **required** An object mapping the definition of the nested entities found within the input array
298297
* `schemaAttribute`: **required** The attribute on each entity found that defines what schema, per the definition mapping, to use when normalizing.
299-
Can be a string or a function. If given a function, accepts the following arguments:
298+
Can be a string or a function. If given a function, accepts the following arguments:
300299
* `value`: The input value of the entity.
301300
* `parent`: The parent object of the input array.
302301
* `key`: The key at which the input array appears on the parent object.
@@ -307,17 +306,20 @@ Can be a string or a function. If given a function, accepts the following argume
307306

308307
#### Usage
309308

310-
*Note: If your data returns an object that you did not provide a mapping for, the original object will be returned in the result and an entity will not be created.*
309+
_Note: If your data returns an object that you did not provide a mapping for, the original object will be returned in the result and an entity will not be created._
311310

312311
```js
313312
const data = { owner: { id: 1, type: 'user', name: 'Anne' } };
314313

315314
const user = new schema.Entity('users');
316315
const group = new schema.Entity('groups');
317-
const unionSchema = new schema.Union({
318-
user: user,
319-
group: group
320-
}, 'type');
316+
const unionSchema = new schema.Union(
317+
{
318+
user: user,
319+
group: group
320+
},
321+
'type'
322+
);
321323

322324
const normalizedData = normalize(data, { owner: unionSchema });
323325
```
@@ -337,9 +339,9 @@ const normalizedData = normalize(data, { owner: unionSchema });
337339

338340
Describes a map whose values follow the given schema.
339341

340-
* `definition`: **required** A singular schema that this array contains *or* a mapping of schema to attribute values.
341-
* `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.
342-
Can be a string or a function. If given a function, accepts the following arguments:
342+
* `definition`: **required** A singular schema that this array contains _or_ a mapping of schema to attribute values.
343+
* `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.
344+
Can be a string or a function. If given a function, accepts the following arguments:
343345
* `value`: The input value of the entity.
344346
* `parent`: The parent object of the input array.
345347
* `key`: The key at which the input array appears on the parent object.
@@ -372,22 +374,25 @@ const normalizedData = normalize(data, valuesSchema);
372374

373375
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`.
374376

375-
*Note: If your data returns an object that you did not provide a mapping for, the original object will be returned in the result and an entity will not be created.*
377+
_Note: If your data returns an object that you did not provide a mapping for, the original object will be returned in the result and an entity will not be created._
376378

377379
For example:
378380

379381
```js
380382
const data = {
381-
'1': { id: 1, type: 'admin' },
383+
'1': { id: 1, type: 'admin' },
382384
'2': { id: 2, type: 'user' }
383385
};
384386

385387
const userSchema = new schema.Entity('users');
386388
const adminSchema = new schema.Entity('admins');
387-
const valuesSchema = new schema.Values({
388-
admins: adminSchema,
389-
users: userSchema
390-
}, (input, parent, key) => `${input.type}s`);
389+
const valuesSchema = new schema.Values(
390+
{
391+
admins: adminSchema,
392+
users: userSchema
393+
},
394+
(input, parent, key) => `${input.type}s`
395+
);
391396

392397
const normalizedData = normalize(data, valuesSchema);
393398
```

0 commit comments

Comments
 (0)