You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
- Fix regression with attribute casting not handling dates correctly, and add more sophisticated handling of primitives, constructables, and callables.
Use the `sync` method to load your JSON:API response document into the store. Both the primary `data` and any `included` resources will be synced. The return value will be a model, or an array of models, corresponding to the primary data.
45
+
Use the `sync` method to load your JSON:API response document into the store. Both the primary `data` and any `included`
46
+
resources will be synced. The return value will be a model, or an array of models, corresponding to the primary data.
46
47
47
48
```ts
48
49
const model =models.sync(document);
49
50
```
50
51
51
-
If any of the synced resources already exist within the store, the new data will be **merged** into the old model. The model instance will not change so references to it throughout your application will remain intact.
52
+
If any of the synced resources already exist within the store, the new data will be **merged** into the old model. The
53
+
model instance will not change so references to it throughout your application will remain intact.
52
54
53
55
You can also sync an individual resource using the `syncResource` method:
54
56
@@ -62,12 +64,13 @@ const model = models.syncResource({
62
64
63
65
### Retrieving Models
64
66
65
-
Specific models can be retrieved from the store using the `find` method. Pass it a type and an ID, a resource identifier object, or an array of resource identifier objects:
67
+
Specific models can be retrieved from the store using the `find` method. Pass it a type and an ID, a resource identifier
68
+
object, or an array of resource identifier objects:
Retrieve all of the models of a given type using the `findAll` method:
77
80
78
81
```ts
79
-
constmodels=models.findAll('users');
82
+
constusers=models.findAll('users');
80
83
```
81
84
82
85
### Working with Models
83
86
84
-
Models are a _superset_ of JSON:API resource objects, meaning they contain all of the members you would expect (`type`, `id`, `attributes`, `relationships`, `meta`, `links`) plus some additional functionality.
87
+
Models are a _superset_ of JSON:API resource objects, meaning they contain all of the members you would
88
+
expect (`type`, `id`, `attributes`, `relationships`, `meta`, `links`) plus some additional functionality.
85
89
86
-
Getters are automatically defined for all fields, allowing you to easily access their contents. Relationship fields are automatically resolved to their related models (if present within the store):
90
+
Getters are automatically defined for all fields, allowing you to easily access their contents. Relationship fields are
91
+
automatically resolved to their related models (if present within the store):
To easily retrieve a resource identifier object for the model, the `identifier` method is available. This is useful when constructing relationships in JSON:API request documents.
98
+
To easily retrieve a resource identifier object for the model, the `identifier` method is available. This is useful when
99
+
constructing relationships in JSON:API request documents.
94
100
95
101
```ts
96
102
model.identifier(); // { type: 'users', id: '1' }
97
103
```
98
104
99
105
### Forgetting Models
100
106
101
-
Remove a model from the store using the `forget` method, which accepts a resource identifier object. This means you can pass a model directly into it:
107
+
Remove a model from the store using the `forget` method, which accepts a resource identifier object. This means you can
108
+
pass a model directly into it:
102
109
103
110
```ts
104
111
models.forget(user);
105
112
```
106
113
107
114
### Custom Models
108
115
109
-
You can define custom model classes to add your own functionality. Custom models must extend the `Model` base class. This is useful if you wish to add any custom getters or methods to models for a specific resource type, and also to define types for each resource field:
116
+
You can define custom model classes to add your own functionality. Custom models must extend the `Model` base class.
117
+
This is useful if you wish to add any custom getters or methods to models for a specific resource type:
110
118
111
119
```ts
112
120
import { Model } from'json-api-models';
113
121
114
-
classUserextendsModel<'users'> {
115
-
publicdeclare name:string;
116
-
publicdeclare age:number;
117
-
122
+
classUserextendsModel {
118
123
get firstName() {
119
124
returnthis.name.split('')[0];
120
125
}
@@ -129,24 +134,45 @@ const models = new Store({
129
134
});
130
135
```
131
136
132
-
#### Attribute Casts
137
+
###TypeScript
133
138
134
-
You can define typecasts for attributes on your custom models:
139
+
For TypeScript autocompletion of model attributes and relationships, provide the raw JSON:API resource schema when defining your models.
135
140
136
141
```ts
137
-
classUserextendsModel<'users'> {
138
-
publicdeclare name:string;
139
-
publicdeclare createdAt:Date;
140
-
141
-
protected casts = {
142
-
createdAt: Date,
142
+
typeUsersSchema= {
143
+
type:'users';
144
+
id:string;
145
+
attributes: {
146
+
name:string;
143
147
};
144
-
}
148
+
relationships: {
149
+
dog: { data?: { type:'dogs'; id:string } |null };
150
+
};
151
+
};
152
+
153
+
classUserextendsModel<UsersSchema> {}
154
+
```
155
+
156
+
To type related resources, you can provide a collection of all models as the second generic.
157
+
158
+
```ts
159
+
typeDogsSchema= {
160
+
// ...
161
+
};
162
+
163
+
typeSchemas= {
164
+
users:User;
165
+
dogs:Dog;
166
+
};
167
+
168
+
classUserextendsModel<UsersSchema, Schemas> {}
169
+
classDogextendsModel<DogsSchema, Schemas> {}
145
170
```
146
171
147
172
### API Consumption Tips
148
173
149
-
This library is completely unopinionated about how you interact with your JSON:API server. It merely gives you an easy way to work with the resulting JSON:API data. An example integration with `fetch` is demonstrated below:
174
+
This library is completely unopinionated about how you interact with your JSON:API server. It merely gives you an easy
175
+
way to work with the resulting JSON:API data. An example integration with `fetch` is demonstrated below:
150
176
151
177
```ts
152
178
const models =newStore();
@@ -169,7 +195,7 @@ function api(url, options = {}) {
169
195
const data =models.sync(document);
170
196
return { response, document, data };
171
197
}
172
-
}
198
+
},
173
199
);
174
200
}
175
201
@@ -178,7 +204,9 @@ api('users/1').then(({ data }) => {
178
204
});
179
205
```
180
206
181
-
When constructing API requests, remember that JSON:API resource objects contain `links` that can be used instead of rebuilding the URL. Also, models contain an `identifier` method that can be used to spread the `type` and `id` members into the document `data` (required by the specification). Here is an example of a request to update a resource:
207
+
When constructing API requests, remember that JSON:API resource objects contain `links` that can be used instead of
208
+
rebuilding the URL. Also, models contain an `identifier` method that can be used to spread the `type` and `id` members
209
+
into the document `data` (required by the specification). Here is an example of a request to update a resource:
182
210
183
211
```ts
184
212
const user =models.find('users', '1');
@@ -194,29 +222,6 @@ api(user.links.self, {
194
222
});
195
223
```
196
224
197
-
### Building Queries
198
-
199
-
Building query strings for your JSON:API requests can be tedious, and sometimes they may need to be constructed dynamically with merge logic for certain parameters. The `Query` class takes care of this:
0 commit comments