ts-japi 1.6.0 → 1.6.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +13 -1
- package/Makefile +1 -27
- package/README.md +145 -75
- package/api-extractor.json +14 -0
- package/lib/classes/cache.d.ts +2 -2
- package/lib/classes/cache.js +26 -48
- package/lib/classes/cache.js.map +1 -1
- package/lib/classes/error-serializer.d.ts +6 -6
- package/lib/classes/error-serializer.js +58 -125
- package/lib/classes/error-serializer.js.map +1 -1
- package/lib/classes/linker.d.ts +5 -5
- package/lib/classes/linker.d.ts.map +1 -1
- package/lib/classes/linker.js +15 -41
- package/lib/classes/linker.js.map +1 -1
- package/lib/classes/metaizer.d.ts +4 -4
- package/lib/classes/metaizer.d.ts.map +1 -1
- package/lib/classes/metaizer.js +12 -38
- package/lib/classes/metaizer.js.map +1 -1
- package/lib/classes/paginator.d.ts +3 -3
- package/lib/classes/paginator.js +17 -16
- package/lib/classes/paginator.js.map +1 -1
- package/lib/classes/relator.d.ts +6 -6
- package/lib/classes/relator.d.ts.map +1 -1
- package/lib/classes/relator.js +71 -135
- package/lib/classes/relator.js.map +1 -1
- package/lib/classes/serializer.d.ts +9 -9
- package/lib/classes/serializer.js +213 -316
- package/lib/classes/serializer.js.map +1 -1
- package/lib/index.js +17 -10
- package/lib/index.js.map +1 -1
- package/lib/interfaces/cache.interface.d.ts +2 -2
- package/lib/interfaces/cache.interface.js +1 -1
- package/lib/interfaces/error-serializer.interface.d.ts +11 -11
- package/lib/interfaces/error-serializer.interface.js +1 -1
- package/lib/interfaces/error.interface.js +1 -1
- package/lib/interfaces/json-api.interface.js +1 -1
- package/lib/interfaces/linker.interface.d.ts +1 -1
- package/lib/interfaces/linker.interface.js +1 -1
- package/lib/interfaces/paginator.interface.js +1 -1
- package/lib/interfaces/relator.interface.d.ts +5 -4
- package/lib/interfaces/relator.interface.d.ts.map +1 -1
- package/lib/interfaces/relator.interface.js +1 -1
- package/lib/interfaces/serializer.interface.d.ts +24 -24
- package/lib/interfaces/serializer.interface.js +1 -1
- package/lib/models/error.model.d.ts +1 -1
- package/lib/models/error.model.js +59 -22
- package/lib/models/error.model.js.map +1 -1
- package/lib/models/link.model.js +11 -10
- package/lib/models/link.model.js.map +1 -1
- package/lib/models/meta.model.js +5 -6
- package/lib/models/meta.model.js.map +1 -1
- package/lib/models/relationship.model.js +8 -6
- package/lib/models/relationship.model.js.map +1 -1
- package/lib/models/resource-identifier.model.js +11 -9
- package/lib/models/resource-identifier.model.js.map +1 -1
- package/lib/models/resource.model.js +13 -28
- package/lib/models/resource.model.js.map +1 -1
- package/lib/tsdoc-metadata.json +11 -0
- package/lib/types/global.types.js +1 -1
- package/lib/utils/is-error-document.d.ts +1 -1
- package/lib/utils/is-error-document.js +6 -8
- package/lib/utils/is-error-document.js.map +1 -1
- package/lib/utils/is-object.js +1 -1
- package/lib/utils/is-plain-object.js +4 -4
- package/lib/utils/is-plain-object.js.map +1 -1
- package/lib/utils/merge.d.ts +2 -2
- package/lib/utils/merge.js +16 -63
- package/lib/utils/merge.js.map +1 -1
- package/lib/utils/serializer.utils.js +56 -202
- package/lib/utils/serializer.utils.js.map +1 -1
- package/package.json +94 -88
- package/tools/generate_docs.ts +33 -0
- package/tools/internal/custom_markdown_action.ts +32 -0
- package/tools/internal/custom_markdown_documenter.ts +1337 -0
- package/tsconfig.json +60 -79
- package/CONTRIBUTING.md +0 -127
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,17 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 1.6.2
|
|
4
|
+
|
|
5
|
+
### Patch Changes
|
|
6
|
+
|
|
7
|
+
- c5a8201: Add customisable relationship names
|
|
8
|
+
|
|
9
|
+
## 1.6.1
|
|
10
|
+
|
|
11
|
+
### Patch Changes
|
|
12
|
+
|
|
13
|
+
- d5cd4d1: Updated dependencies
|
|
14
|
+
|
|
3
15
|
## 1.6.0
|
|
4
16
|
|
|
5
17
|
### Minor Changes
|
|
@@ -18,7 +30,7 @@
|
|
|
18
30
|
|
|
19
31
|
### Minor Changes
|
|
20
32
|
|
|
21
|
-
- Fixes https://github.com/
|
|
33
|
+
- Fixes https://github.com/mathematic-inc/ts-japi/issues/23
|
|
22
34
|
|
|
23
35
|
## 1.4.0
|
|
24
36
|
|
package/Makefile
CHANGED
|
@@ -1,33 +1,7 @@
|
|
|
1
1
|
PATH:=$(PATH):$(PWD)/node_modules/.bin
|
|
2
2
|
SHELL:=env PATH=$(PATH) /bin/bash
|
|
3
3
|
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
lib: $(shell find src -name '*.ts')
|
|
7
|
-
@echo 'Building library...'
|
|
8
|
-
@tsc
|
|
9
|
-
|
|
10
|
-
docs: $(shell find src -name '*.ts')
|
|
11
|
-
@echo 'Building documentation...'
|
|
12
|
-
@typedoc
|
|
13
|
-
@rsync -a ./src/docs/assets ./docs
|
|
14
|
-
|
|
15
|
-
README.md: src/docs/README.md
|
|
16
|
-
@echo 'Building README...'
|
|
17
|
-
@typedoc --plugin typedoc-plugin-markdown --out ./md-docs --theme markdown
|
|
18
|
-
@mv md-docs/README.md README.md
|
|
19
|
-
@rm -rf md-docs
|
|
20
|
-
@ts-node scripts/readme-postbuild.ts
|
|
21
|
-
|
|
22
|
-
clean: clean-docs clean-readme clean-build clean-coverage
|
|
23
|
-
|
|
24
|
-
clean-docs:
|
|
25
|
-
@echo 'Cleaning documentation...'
|
|
26
|
-
@rm -rf ./docs
|
|
27
|
-
|
|
28
|
-
clean-readme:
|
|
29
|
-
@echo 'Cleaning README...'
|
|
30
|
-
@rm -rf ./readme
|
|
4
|
+
clean: clean-build clean-coverage
|
|
31
5
|
|
|
32
6
|
clean-lib:
|
|
33
7
|
@echo 'Cleaning build artifacts...'
|
package/README.md
CHANGED
|
@@ -1,46 +1,51 @@
|
|
|
1
|
-
ts
|
|
1
|
+
# ts:japi
|
|
2
2
|
|
|
3
|
-
<br
|
|
4
|
-
<img src="https://raw.githubusercontent.com/
|
|
5
|
-
<br
|
|
3
|
+
<br/>
|
|
4
|
+
<img src="https://raw.githubusercontent.com/mathematic-inc/ts-japi/master/docs/assets/images/logo.svg" alt="{ts:japi}" width="350"/>
|
|
5
|
+
<br/>
|
|
6
6
|
|
|
7
7
|

|
|
8
8
|
[](https://opensource.org/licenses/Apache-2.0)
|
|
9
9
|
|
|
10
|
-
> A highly-modular (typescript-friendly)-framework agnostic library for serializing data to the
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
- [
|
|
14
|
-
- [
|
|
15
|
-
- [
|
|
16
|
-
- [
|
|
17
|
-
- [
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
- [
|
|
25
|
-
- [
|
|
26
|
-
- [
|
|
27
|
-
- [
|
|
28
|
-
- [
|
|
29
|
-
- [
|
|
10
|
+
> A highly-modular (typescript-friendly)-framework agnostic library for serializing data to the
|
|
11
|
+
> JSON:API specification
|
|
12
|
+
|
|
13
|
+
- [ts:japi](#tsjapi)
|
|
14
|
+
- [Features](#features)
|
|
15
|
+
- [Documentation](#documentation)
|
|
16
|
+
- [Installation](#installation)
|
|
17
|
+
- [Getting Started](#getting-started)
|
|
18
|
+
- [Examples](#examples)
|
|
19
|
+
- [Serialization](#serialization)
|
|
20
|
+
- [Links](#links)
|
|
21
|
+
- [Pagination](#pagination)
|
|
22
|
+
- [Relationships](#relationships)
|
|
23
|
+
- [Metadata](#metadata)
|
|
24
|
+
- [Serializing Errors](#serializing-errors)
|
|
25
|
+
- [Caching](#caching)
|
|
26
|
+
- [Deserialization](#deserialization)
|
|
27
|
+
- [Remarks](#remarks)
|
|
28
|
+
- [FAQ](#faq)
|
|
29
|
+
- [For Developers](#for-developers)
|
|
30
|
+
- [Contributing](#contributing)
|
|
31
|
+
- [License](#license)
|
|
30
32
|
|
|
31
33
|
## Features
|
|
32
34
|
|
|
33
|
-
- This is the **only** typescript-compatible library that fully types the JSON:API specification and
|
|
35
|
+
- This is the **only** typescript-compatible library that fully types the JSON:API specification and
|
|
36
|
+
performs _proper_ serialization.
|
|
34
37
|
- [**Zero dependencies**](#zdg).
|
|
35
38
|
- This is the **only** library with [resource recursion](#wirr).
|
|
36
|
-
- The modular framework laid out here
|
|
39
|
+
- The modular framework laid out here _highly promotes_ the specifications intentions:
|
|
37
40
|
- Using links is no longer obfuscated.
|
|
38
41
|
- Meta can truly be placed anywhere with possible dependencies laid out visibly.
|
|
39
|
-
- This library is designed to adhere to the specifications "never remove, only add" policy, so we
|
|
42
|
+
- This library is designed to adhere to the specifications "never remove, only add" policy, so we
|
|
43
|
+
will remain backwards-compatible.
|
|
40
44
|
|
|
41
45
|
## Documentation
|
|
42
46
|
|
|
43
|
-
The [documentation](https://
|
|
47
|
+
The [documentation](https://mathematic-inc.github.io/ts-japi/) has everything that is covered here
|
|
48
|
+
and more.
|
|
44
49
|
|
|
45
50
|
## Installation
|
|
46
51
|
|
|
@@ -54,25 +59,38 @@ npm install ts-japi
|
|
|
54
59
|
|
|
55
60
|
There are fives classes that are used to serialize data (only one of which is necessarily required).
|
|
56
61
|
|
|
57
|
-
- [`Serializer`](https://
|
|
58
|
-
|
|
59
|
-
- [`
|
|
60
|
-
|
|
61
|
-
- [`
|
|
62
|
-
|
|
63
|
-
-
|
|
64
|
-
|
|
65
|
-
|
|
62
|
+
- [`Serializer`](https://mathematic-inc.github.io/ts-japi/classes/serializer.html) with
|
|
63
|
+
[`SerializerOptions`](https://mathematic-inc.github.io/ts-japi/interfaces/serializeroptions.html)
|
|
64
|
+
- [`Relator`](https://mathematic-inc.github.io/ts-japi/classes/relator.html) with
|
|
65
|
+
[`RelatorOptions`](https://mathematic-inc.github.io/ts-japi/interfaces/relatoroptions.html)
|
|
66
|
+
- [`Linker`](https://mathematic-inc.github.io/ts-japi/classes/linker.html) with
|
|
67
|
+
[`LinkerOptions`](https://mathematic-inc.github.io/ts-japi/interfaces/linkeroptions.html)
|
|
68
|
+
- [`Metaizer`](https://mathematic-inc.github.io/ts-japi/classes/metaizer.html)
|
|
69
|
+
- [`Paginator`](https://mathematic-inc.github.io/ts-japi/classes/paginator.html)
|
|
70
|
+
- [`ErrorSerializer`](https://mathematic-inc.github.io/ts-japi/classes/errorserializer.html) with
|
|
71
|
+
[`ErrorSerializerOptions`](https://mathematic-inc.github.io/ts-japi/interfaces/errorserializeroptions.html)
|
|
72
|
+
- [`Cache`](https://mathematic-inc.github.io/ts-japi/classes/cache.html) with
|
|
73
|
+
[`CacheOptions`](https://mathematic-inc.github.io/ts-japi/interfaces/cacheoptions.html)
|
|
74
|
+
|
|
75
|
+
You can check the [documentation](https://mathematic-inc.github.io/ts-japi) for a deeper insight
|
|
76
|
+
into the usage.
|
|
66
77
|
|
|
67
78
|
### Examples
|
|
68
79
|
|
|
69
|
-
You can check the [examples](https://github.com/
|
|
80
|
+
You can check the [examples](https://github.com/mathematic-inc/ts-japi/tree/master/examples) and the
|
|
81
|
+
[test](https://github.com/mathematic-inc/ts-japi/tree/master/test) folders to see some examples
|
|
82
|
+
(such as the ones below). You can check
|
|
83
|
+
[this example](https://github.com/mathematic-inc/ts-japi/blob/master/examples/full.example.ts) to
|
|
84
|
+
see almost every option of
|
|
85
|
+
[`Serializer`](https://mathematic-inc.github.io/ts-japi/classes/serializer.html) exhausted.
|
|
70
86
|
|
|
71
87
|
## Serialization
|
|
72
88
|
|
|
73
|
-
The [`Serializer`](https://
|
|
89
|
+
The [`Serializer`](https://mathematic-inc.github.io/ts-japi/classes/serializer.html) class is the
|
|
90
|
+
only class required for basic serialization.
|
|
74
91
|
|
|
75
|
-
The following example constructs the most basic
|
|
92
|
+
The following example constructs the most basic
|
|
93
|
+
[`Serializer`](https://mathematic-inc.github.io/ts-japi/classes/serializer.html): (Note the `await`)
|
|
76
94
|
|
|
77
95
|
```typescript
|
|
78
96
|
import { Serializer } from '../src';
|
|
@@ -99,14 +117,16 @@ const UserSerializer = new Serializer('users');
|
|
|
99
117
|
// }
|
|
100
118
|
// }
|
|
101
119
|
})();
|
|
102
|
-
|
|
103
120
|
```
|
|
104
121
|
|
|
105
122
|
### Links
|
|
106
123
|
|
|
107
|
-
The [`Linker`](https://
|
|
124
|
+
The [`Linker`](https://mathematic-inc.github.io/ts-japi/classes/linker.html) class is used to
|
|
125
|
+
generate a normalized [document link](https://jsonapi.org/format/#document-links). Its methods are
|
|
126
|
+
not meant to be called. See the [FAQ](#faq) for reasons.
|
|
108
127
|
|
|
109
|
-
The following example constructs a
|
|
128
|
+
The following example constructs a
|
|
129
|
+
[`Linker`](https://mathematic-inc.github.io/ts-japi/classes/linker.html) for `User`s and `Article`s:
|
|
110
130
|
|
|
111
131
|
```typescript
|
|
112
132
|
import { Linker } from '../src';
|
|
@@ -130,14 +150,16 @@ const UserArticleLinker = new Linker((user: User, articles: Article | Article[])
|
|
|
130
150
|
|
|
131
151
|
// Output: https://www.example.com/users/sample_user_id/articles/same_article_id
|
|
132
152
|
})();
|
|
133
|
-
|
|
134
153
|
```
|
|
135
154
|
|
|
136
155
|
#### Pagination
|
|
137
156
|
|
|
138
|
-
The [`Paginator`](https://
|
|
157
|
+
The [`Paginator`](https://mathematic-inc.github.io/ts-japi/classes/paginator.html) class is used to
|
|
158
|
+
generate [pagination links](https://jsonapi.org/format/#fetching-pagination). Its methods are not
|
|
159
|
+
meant to be called.
|
|
139
160
|
|
|
140
|
-
The following example constructs a
|
|
161
|
+
The following example constructs a
|
|
162
|
+
[`Paginator`](https://mathematic-inc.github.io/ts-japi/classes/paginator.html):
|
|
141
163
|
|
|
142
164
|
```typescript
|
|
143
165
|
import { Paginator } from '../src';
|
|
@@ -172,16 +194,25 @@ const ArticlePaginator = new Paginator((articles: Article | Article[]) => {
|
|
|
172
194
|
// next: null
|
|
173
195
|
// }
|
|
174
196
|
})();
|
|
175
|
-
|
|
176
197
|
```
|
|
177
198
|
|
|
178
199
|
### Relationships
|
|
179
200
|
|
|
180
|
-
The [`Relator`](https://
|
|
201
|
+
The [`Relator`](https://mathematic-inc.github.io/ts-japi/classes/relator.html) class is used to
|
|
202
|
+
generate top-level [included data](https://jsonapi.org/format/#document-top-level) as well as
|
|
203
|
+
resource-level [relationships](https://jsonapi.org/format/#document-resource-object-relationships).
|
|
204
|
+
Its methods are not meant to be called.
|
|
181
205
|
|
|
182
|
-
[`Relator`](https://
|
|
206
|
+
[`Relator`](https://mathematic-inc.github.io/ts-japi/classes/relator.html)s may also take optional
|
|
207
|
+
[`Linker`](https://mathematic-inc.github.io/ts-japi/classes/linker.html)s (using the
|
|
208
|
+
[`linker`](https://mathematic-inc.github.io/ts-japi/interfaces/relatoroptions.html#linkers) option)
|
|
209
|
+
to define [relationship links](https://jsonapi.org/format/#document-resource-object-relationships)
|
|
210
|
+
and
|
|
211
|
+
[related resource links](https://jsonapi.org/format/#document-resource-object-related-resource-links).
|
|
183
212
|
|
|
184
|
-
The following example constructs a
|
|
213
|
+
The following example constructs a
|
|
214
|
+
[`Relator`](https://mathematic-inc.github.io/ts-japi/classes/relator.html) for `User`s and
|
|
215
|
+
`Article`s:
|
|
185
216
|
|
|
186
217
|
```typescript
|
|
187
218
|
import { Serializer, Relator } from '../src';
|
|
@@ -205,21 +236,24 @@ const UserArticleRelator = new Relator<User, Article>(
|
|
|
205
236
|
|
|
206
237
|
// Output: { data: [ { type: 'articles', id: 'same_article_id' } ] }
|
|
207
238
|
})();
|
|
208
|
-
|
|
209
239
|
```
|
|
210
240
|
|
|
211
241
|
### Metadata
|
|
212
242
|
|
|
213
|
-
The [`Metaizer`](https://
|
|
243
|
+
The [`Metaizer`](https://mathematic-inc.github.io/ts-japi/classes/metaizer.html) class is used to
|
|
244
|
+
construct generate metadata given some dependencies. There are several locations
|
|
245
|
+
[`Metaizer`](https://mathematic-inc.github.io/ts-japi/classes/metaizer.html) can be used:
|
|
214
246
|
|
|
215
|
-
- [`ErrorSerializerOptions.metaizers`](https://
|
|
216
|
-
- [`RelatorOptions.metaizer`](https://
|
|
217
|
-
- [`SerializerOptions.metaizers`](https://
|
|
218
|
-
- [`LinkerOptions.metaizer`](https://
|
|
247
|
+
- [`ErrorSerializerOptions.metaizers`](https://mathematic-inc.github.io/ts-japi/interfaces/errorserializeroptions.html#metaizers)
|
|
248
|
+
- [`RelatorOptions.metaizer`](https://mathematic-inc.github.io/ts-japi/interfaces/relatoroptions.html#metaizer)
|
|
249
|
+
- [`SerializerOptions.metaizers`](https://mathematic-inc.github.io/ts-japi/interfaces/serializeroptions.html#metaizers)
|
|
250
|
+
- [`LinkerOptions.metaizer`](https://mathematic-inc.github.io/ts-japi/interfaces/linkeroptions.html#metaizer)
|
|
219
251
|
|
|
220
|
-
Like [`Linker`](https://
|
|
252
|
+
Like [`Linker`](https://mathematic-inc.github.io/ts-japi/classes/linker.html), its methods are not
|
|
253
|
+
meant to be called.
|
|
221
254
|
|
|
222
|
-
The following example constructs a
|
|
255
|
+
The following example constructs a
|
|
256
|
+
[`Metaizer`](https://mathematic-inc.github.io/ts-japi/classes/metaizer.html):
|
|
223
257
|
|
|
224
258
|
```typescript
|
|
225
259
|
import { User, Article } from '../test/models';
|
|
@@ -246,16 +280,25 @@ const UserArticleMetaizer = new Metaizer((user: User, articles: Article | Articl
|
|
|
246
280
|
// article_created: '2020-05-20T15:39:43.277Z'
|
|
247
281
|
// }
|
|
248
282
|
})();
|
|
249
|
-
|
|
250
283
|
```
|
|
251
284
|
|
|
252
285
|
### Serializing Errors
|
|
253
286
|
|
|
254
|
-
The [`ErrorSerializer`](https://
|
|
287
|
+
The [`ErrorSerializer`](https://mathematic-inc.github.io/ts-japi/classes/errorserializer.html) class
|
|
288
|
+
is used to serialize any object considered an error (the
|
|
289
|
+
[`attributes`](https://mathematic-inc.github.io/ts-japi/interfaces/errorserializeroptions.html#attributes)
|
|
290
|
+
option allows you to choose what attributes to use during serialization). _Alternatively_
|
|
291
|
+
(**recommended**), you can construct custom errors by extending the
|
|
292
|
+
[`JapiError`](https://mathematic-inc.github.io/ts-japi/classes/japierror.html) class and use those
|
|
293
|
+
for all server-to-client errors.
|
|
255
294
|
|
|
256
|
-
The
|
|
295
|
+
The
|
|
296
|
+
[error serializer test](https://github.com/mathematic-inc/ts-japi/tree/master/test/error-serializer.test.ts)
|
|
297
|
+
includes an example of the alternative solution.
|
|
257
298
|
|
|
258
|
-
The following example constructs the most basic
|
|
299
|
+
The following example constructs the most basic
|
|
300
|
+
[`ErrorSerializer`](https://mathematic-inc.github.io/ts-japi/classes/errorserializer.html): (Note
|
|
301
|
+
the lack of `await`)
|
|
259
302
|
|
|
260
303
|
```typescript
|
|
261
304
|
import { ErrorSerializer } from '../src';
|
|
@@ -273,28 +316,45 @@ const PrimitiveErrorSerializer = new ErrorSerializer();
|
|
|
273
316
|
// jsonapi: { version: '1.0' }
|
|
274
317
|
// }
|
|
275
318
|
})();
|
|
276
|
-
|
|
277
319
|
```
|
|
278
320
|
|
|
279
321
|
### Caching
|
|
280
322
|
|
|
281
|
-
The [`Cache`](https://
|
|
323
|
+
The [`Cache`](https://mathematic-inc.github.io/ts-japi/classes/cache.html) class can be placed in a
|
|
324
|
+
[`Serializer`](https://mathematic-inc.github.io/ts-japi/classes/serializer.html)'s
|
|
325
|
+
[`cache`](https://mathematic-inc.github.io/ts-japi/interfaces/serializeroptions.html#cache) option.
|
|
326
|
+
Alternatively, setting that option to `true` will provide a default
|
|
327
|
+
[`Cache`](https://mathematic-inc.github.io/ts-japi/classes/cache.html).
|
|
282
328
|
|
|
283
|
-
The default [`Cache`](https://
|
|
329
|
+
The default [`Cache`](https://mathematic-inc.github.io/ts-japi/classes/cache.html) uses the basic
|
|
330
|
+
[`Object.is`](https://mathematic-inc.github.io/ts-japi/https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/is)
|
|
331
|
+
function to determine if input data are the same. If you want to adjust this, instantiate a new
|
|
332
|
+
[`Cache`](https://mathematic-inc.github.io/ts-japi/classes/cache.html) with a
|
|
333
|
+
[`resolver`](https://mathematic-inc.github.io/ts-japi/interfaces/cacheoptions.html#resolver).
|
|
284
334
|
|
|
285
335
|
## Deserialization
|
|
286
336
|
|
|
287
|
-
We stress the following: Given that there are many clients readily built to consume JSON:API
|
|
337
|
+
We stress the following: Given that there are many clients readily built to consume JSON:API
|
|
338
|
+
endpoints (see [here](https://jsonapi.org/implementations/)), we do not provide deserialization. In
|
|
339
|
+
particular, since unmarshalling data is strongly related to the code it will be used in (e.g.
|
|
340
|
+
React), tighter integration is recommended over an unnecessary abstraction.
|
|
288
341
|
|
|
289
342
|
## Remarks
|
|
290
343
|
|
|
291
|
-
There are several model classes used inside TS:JAPI such as `Resource` and `Relationships`. These
|
|
344
|
+
There are several model classes used inside TS:JAPI such as `Resource` and `Relationships`. These
|
|
345
|
+
models are used for normalization as well as traversing a JSON:API document. If you plan to fork
|
|
346
|
+
this repo, you can extend these models and reimplement them to create your own custom (non-standard,
|
|
347
|
+
extended) serializer.
|
|
292
348
|
|
|
293
349
|
## FAQ
|
|
294
350
|
|
|
295
|
-
> Why not just allow optional functions that return the internal `Link` Class (or just a URI
|
|
351
|
+
> Why not just allow optional functions that return the internal `Link` Class (or just a URI
|
|
352
|
+
> `string`)?
|
|
296
353
|
|
|
297
|
-
The `Link` class is defined to be as general as possible in case of changes in the specification. In
|
|
354
|
+
The `Link` class is defined to be as general as possible in case of changes in the specification. In
|
|
355
|
+
particular, the implementation of metadata and the types in our library rely on the generality of
|
|
356
|
+
the `Link` class. Relying on user arguments will generate a lot of overhead for both us and users
|
|
357
|
+
whenever the specs change.
|
|
298
358
|
|
|
299
359
|
> Why does the `Meta` class exist if it is essentially just a plain object?
|
|
300
360
|
|
|
@@ -302,22 +362,32 @@ In case the specification is updated to change the meta objects in some function
|
|
|
302
362
|
|
|
303
363
|
> What is "resource recursion"?<a id="wirr"></a>
|
|
304
364
|
|
|
305
|
-
Due to [compound documents](https://jsonapi.org/format/#document-compound-documents), it is possible
|
|
365
|
+
Due to [compound documents](https://jsonapi.org/format/#document-compound-documents), it is possible
|
|
366
|
+
to recurse through related resources via their
|
|
367
|
+
[resource linkages](https://jsonapi.org/format/#document-resource-object-linkage) and obtain
|
|
368
|
+
[included resources](https://jsonapi.org/format/#document-top-level) beyond primary data relations.
|
|
369
|
+
This is should be done with caution (see
|
|
370
|
+
[`SerializerOptions.depth`](https://mathematic-inc.github.io/ts-japi/interfaces/serializeroptions.html#depth)
|
|
371
|
+
and
|
|
372
|
+
[this example](https://github.com/mathematic-inc/ts-japi/blob/master/examples/resource-recursion.example.ts))
|
|
306
373
|
|
|
307
374
|
## For Developers
|
|
308
375
|
|
|
309
|
-
To get started in developing this library, run `yarn install`, `yarn build` and `yarn test` (in this
|
|
376
|
+
To get started in developing this library, run `yarn install`, `yarn build` and `yarn test` (in this
|
|
377
|
+
precise order) to assure everything is in working order.
|
|
310
378
|
|
|
311
379
|
## Contributing
|
|
312
380
|
|
|
313
|
-
This project is maintained by the author, however contributions are welcome and appreciated.
|
|
314
|
-
|
|
381
|
+
This project is maintained by the author, however contributions are welcome and appreciated. You can
|
|
382
|
+
find TS:JAPI on GitHub:
|
|
383
|
+
[https://github.com/mathematic-inc/ts-japi](https://github.com/mathematic-inc/ts-japi)
|
|
315
384
|
|
|
316
385
|
Feel free to submit an issue, but please do not submit pull requests unless it is to fix some issue.
|
|
317
|
-
For more information, read the
|
|
386
|
+
For more information, read the
|
|
387
|
+
[contribution guide](https://github.com/mathematic-inc/ts-japi/blob/master/CONTRIBUTING.html).
|
|
318
388
|
|
|
319
389
|
## License
|
|
320
390
|
|
|
321
|
-
Copyright © 2020 [
|
|
391
|
+
Copyright © 2020 [mathematic-inc](https://github.com/mathematic-inc).
|
|
322
392
|
|
|
323
393
|
Licensed under [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0).
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
{
|
|
2
|
+
"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
|
|
3
|
+
"mainEntryPointFilePath": "<projectFolder>/lib/index.d.ts",
|
|
4
|
+
"apiReport": {
|
|
5
|
+
"enabled": false
|
|
6
|
+
},
|
|
7
|
+
"docModel": {
|
|
8
|
+
"enabled": true,
|
|
9
|
+
"apiJsonFilePath": "<projectFolder>/docs/<unscopedPackageName>.api.json"
|
|
10
|
+
},
|
|
11
|
+
"dtsRollup": {
|
|
12
|
+
"enabled": false
|
|
13
|
+
}
|
|
14
|
+
}
|
package/lib/classes/cache.d.ts
CHANGED
|
@@ -18,9 +18,9 @@ export default class Cache<PrimaryType> {
|
|
|
18
18
|
*/
|
|
19
19
|
private resolver;
|
|
20
20
|
/**
|
|
21
|
-
* Creates a {@
|
|
21
|
+
* Creates a {@link Cache}
|
|
22
22
|
*
|
|
23
|
-
* @param limit The maximum amount of documents that can be stored before erasure.
|
|
23
|
+
* @param limit - The maximum amount of documents that can be stored before erasure.
|
|
24
24
|
*/
|
|
25
25
|
constructor(options?: Partial<CacheOptions<PrimaryType>>);
|
|
26
26
|
/** @internal Gets a document in the cache */
|
package/lib/classes/cache.js
CHANGED
|
@@ -1,69 +1,47 @@
|
|
|
1
1
|
"use strict";
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
finally { if (e) throw e.error; }
|
|
15
|
-
}
|
|
16
|
-
return ar;
|
|
17
|
-
};
|
|
18
|
-
exports.__esModule = true;
|
|
19
|
-
var Cache = /** @class */ (function () {
|
|
2
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
+
class Cache {
|
|
4
|
+
/**
|
|
5
|
+
* The default max for document storage
|
|
6
|
+
*/
|
|
7
|
+
static defaultLimit = 10;
|
|
8
|
+
/** @internal The storage for the cache */
|
|
9
|
+
storage = [];
|
|
10
|
+
/**
|
|
11
|
+
* The maximum amount of documents that can be storage before erasure.
|
|
12
|
+
*/
|
|
13
|
+
limit = Cache.defaultLimit;
|
|
20
14
|
/**
|
|
21
|
-
*
|
|
15
|
+
* The method to use in determining data equality
|
|
16
|
+
*/
|
|
17
|
+
resolver = Object.is;
|
|
18
|
+
/**
|
|
19
|
+
* Creates a {@link Cache}
|
|
22
20
|
*
|
|
23
|
-
* @param limit The maximum amount of documents that can be stored before erasure.
|
|
21
|
+
* @param limit - The maximum amount of documents that can be stored before erasure.
|
|
24
22
|
*/
|
|
25
|
-
|
|
26
|
-
if (options === void 0) { options = {}; }
|
|
27
|
-
/** @internal The storage for the cache */
|
|
28
|
-
this.storage = [];
|
|
29
|
-
/**
|
|
30
|
-
* The maximum amount of documents that can be storage before erasure.
|
|
31
|
-
*/
|
|
32
|
-
this.limit = Cache.defaultLimit;
|
|
33
|
-
/**
|
|
34
|
-
* The method to use in determining data equality
|
|
35
|
-
*/
|
|
36
|
-
this.resolver = Object.is;
|
|
23
|
+
constructor(options = {}) {
|
|
37
24
|
if (options.limit)
|
|
38
25
|
this.limit = options.limit;
|
|
39
26
|
if (options.resolver)
|
|
40
27
|
this.resolver = options.resolver;
|
|
41
28
|
}
|
|
42
29
|
/** @internal Gets a document in the cache */
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
var document = this.storage.find(function (_a) {
|
|
46
|
-
var _b = __read(_a, 2), storedData = _b[0], storedOptions = _b[1];
|
|
47
|
-
return _this.resolver(storedData, data) && Object.is(storedOptions, options);
|
|
48
|
-
});
|
|
30
|
+
get(data, options) {
|
|
31
|
+
const document = this.storage.find(([storedData, storedOptions]) => this.resolver(storedData, data) && Object.is(storedOptions, options));
|
|
49
32
|
if (document)
|
|
50
33
|
return document[2];
|
|
51
34
|
else
|
|
52
35
|
return false;
|
|
53
|
-
}
|
|
36
|
+
}
|
|
54
37
|
/** @internal Sets a document in the cache */
|
|
55
|
-
|
|
38
|
+
set(data, document, options) {
|
|
56
39
|
if (this.storage.length > this.limit) {
|
|
57
40
|
this.storage.shift();
|
|
58
41
|
}
|
|
59
42
|
this.storage.push([data, options, document]);
|
|
60
43
|
return document;
|
|
61
|
-
}
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
*/
|
|
65
|
-
Cache.defaultLimit = 10;
|
|
66
|
-
return Cache;
|
|
67
|
-
}());
|
|
68
|
-
exports["default"] = Cache;
|
|
44
|
+
}
|
|
45
|
+
}
|
|
46
|
+
exports.default = Cache;
|
|
69
47
|
//# sourceMappingURL=cache.js.map
|
package/lib/classes/cache.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"cache.js","sourceRoot":"","sources":["../../src/classes/cache.ts"],"names":[],"mappings":"
|
|
1
|
+
{"version":3,"file":"cache.js","sourceRoot":"","sources":["../../src/classes/cache.ts"],"names":[],"mappings":";;AAKA,MAAqB,KAAK;IACxB;;OAEG;IACI,MAAM,CAAC,YAAY,GAAG,EAAE,CAAC;IAEhC,0CAA0C;IAClC,OAAO,GAMX,EAAE,CAAC;IAEP;;OAEG;IACK,KAAK,GAAW,KAAK,CAAC,YAAY,CAAC;IAE3C;;OAEG;IACK,QAAQ,GAGD,MAAM,CAAC,EAAE,CAAC;IAEzB;;;;OAIG;IACH,YAAmB,UAA8C,EAAE;QACjE,IAAI,OAAO,CAAC,KAAK;YAAE,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC;QAC9C,IAAI,OAAO,CAAC,QAAQ;YAAE,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;IACzD,CAAC;IAED,6CAA6C;IACtC,GAAG,CACR,IAA0C,EAC1C,OAAiD;QAEjD,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAChC,CAAC,CAAC,UAAU,EAAE,aAAa,CAAC,EAAE,EAAE,CAC9B,IAAI,CAAC,QAAQ,CAAC,UAAU,EAAE,IAAI,CAAC,IAAI,MAAM,CAAC,EAAE,CAAC,aAAa,EAAE,OAAO,CAAC,CACvE,CAAC;QACF,IAAI,QAAQ;YAAE,OAAO,QAAQ,CAAC,CAAC,CAAC,CAAC;;YAC5B,OAAO,KAAK,CAAC;IACpB,CAAC;IAED,6CAA6C;IACtC,GAAG,CACR,IAA0C,EAC1C,QAA4C,EAC5C,OAAiD;QAEjD,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,KAAK,EAAE;YACpC,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;SACtB;QACD,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC,CAAC;QAC7C,OAAO,QAAQ,CAAC;IAClB,CAAC;;AA9DH,wBA+DC"}
|
|
@@ -2,7 +2,7 @@ import { ErrorSerializerOptions } from '../interfaces/error-serializer.interface
|
|
|
2
2
|
import { ErrorDocument } from '../interfaces/json-api.interface';
|
|
3
3
|
import { SingleOrArray } from '../types/global.types';
|
|
4
4
|
/**
|
|
5
|
-
* The {@
|
|
5
|
+
* The {@link ErrorSerializer} class is used to serialize errors.
|
|
6
6
|
*
|
|
7
7
|
* Example:
|
|
8
8
|
* ```typescript
|
|
@@ -34,17 +34,17 @@ export default class ErrorSerializer<ErrorType> {
|
|
|
34
34
|
*/
|
|
35
35
|
private options;
|
|
36
36
|
/**
|
|
37
|
-
* Creates a {@
|
|
37
|
+
* Creates a {@link Serializer}.
|
|
38
38
|
*
|
|
39
|
-
* @param collectionName The name of the collection of objects.
|
|
40
|
-
* @param options Options for the serializer.
|
|
39
|
+
* @param collectionName - The name of the collection of objects.
|
|
40
|
+
* @param options - Options for the serializer.
|
|
41
41
|
*/
|
|
42
42
|
constructor(options?: Partial<ErrorSerializerOptions<ErrorType>>);
|
|
43
43
|
/**
|
|
44
44
|
* The actual serialization function.
|
|
45
45
|
*
|
|
46
|
-
* @param errors Errors to serialize.
|
|
47
|
-
* @param options Options to use at runtime.
|
|
46
|
+
* @param errors - Errors to serialize.
|
|
47
|
+
* @param options - Options to use at runtime.
|
|
48
48
|
*/
|
|
49
49
|
serialize(errors: SingleOrArray<ErrorType>, options?: Partial<ErrorSerializerOptions<ErrorType>>): ErrorDocument;
|
|
50
50
|
}
|