integreat 0.8.0-beta.32 → 0.8.0-beta.34
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/README.md +137 -227
- package/dist/create.d.ts +4 -2
- package/dist/create.js +8 -1
- package/dist/create.js.map +1 -1
- package/dist/dispatch.d.ts +3 -3
- package/dist/dispatch.js +10 -10
- package/dist/dispatch.js.map +1 -1
- package/dist/handlers/delete.d.ts +1 -1
- package/dist/handlers/delete.js +7 -10
- package/dist/handlers/delete.js.map +1 -1
- package/dist/handlers/expire.d.ts +1 -1
- package/dist/handlers/expire.js +9 -17
- package/dist/handlers/expire.js.map +1 -1
- package/dist/handlers/get.d.ts +1 -1
- package/dist/handlers/get.js +17 -25
- package/dist/handlers/get.js.map +1 -1
- package/dist/handlers/getAll.d.ts +2 -2
- package/dist/handlers/getAll.js +15 -16
- package/dist/handlers/getAll.js.map +1 -1
- package/dist/handlers/getIdent.d.ts +1 -1
- package/dist/handlers/getIdent.js +10 -10
- package/dist/handlers/getIdent.js.map +1 -1
- package/dist/handlers/getMeta.d.ts +1 -1
- package/dist/handlers/getMeta.js +11 -14
- package/dist/handlers/getMeta.js.map +1 -1
- package/dist/handlers/queue.d.ts +1 -1
- package/dist/handlers/queue.js +7 -9
- package/dist/handlers/queue.js.map +1 -1
- package/dist/handlers/run.js +24 -36
- package/dist/handlers/run.js.map +1 -1
- package/dist/handlers/service.d.ts +1 -1
- package/dist/handlers/service.js +4 -13
- package/dist/handlers/service.js.map +1 -1
- package/dist/handlers/set.d.ts +1 -1
- package/dist/handlers/set.js +4 -3
- package/dist/handlers/set.js.map +1 -1
- package/dist/handlers/setMeta.d.ts +1 -1
- package/dist/handlers/setMeta.js +5 -9
- package/dist/handlers/setMeta.js.map +1 -1
- package/dist/handlers/sync.js +6 -6
- package/dist/handlers/sync.js.map +1 -1
- package/dist/index.d.ts +2 -2
- package/dist/index.js +2 -2
- package/dist/index.js.map +1 -1
- package/dist/mutations/exchangeUri.js +1 -1
- package/dist/mutations/exchangeUri.js.map +1 -1
- package/dist/schema/createCastMapping.d.ts +2 -2
- package/dist/schema/createCastMapping.js +39 -25
- package/dist/schema/createCastMapping.js.map +1 -1
- package/dist/schema/index.d.ts +3 -3
- package/dist/schema/index.js +10 -15
- package/dist/schema/index.js.map +1 -1
- package/dist/schema/types.d.ts +2 -2
- package/dist/service/Auth.d.ts +1 -1
- package/dist/service/Auth.js +0 -3
- package/dist/service/Auth.js.map +1 -1
- package/dist/service/endpoints/create.d.ts +2 -2
- package/dist/service/endpoints/create.js +8 -16
- package/dist/service/endpoints/create.js.map +1 -1
- package/dist/service/endpoints/index.d.ts +2 -2
- package/dist/service/endpoints/index.js.map +1 -1
- package/dist/service/endpoints/types.d.ts +2 -4
- package/dist/service/index.d.ts +2 -2
- package/dist/service/index.js +12 -18
- package/dist/service/index.js.map +1 -1
- package/dist/service/types.d.ts +4 -11
- package/dist/transformers/builtIns/boolean.js +1 -1
- package/dist/transformers/builtIns/boolean.js.map +1 -1
- package/dist/transformers/builtIns/date.js +1 -1
- package/dist/transformers/builtIns/date.js.map +1 -1
- package/dist/transformers/builtIns/integer.js +1 -1
- package/dist/transformers/builtIns/integer.js.map +1 -1
- package/dist/transformers/builtIns/number.js +1 -1
- package/dist/transformers/builtIns/number.js.map +1 -1
- package/dist/transformers/builtIns/object.js +1 -1
- package/dist/transformers/builtIns/object.js.map +1 -1
- package/dist/transformers/builtIns/reference.js +1 -1
- package/dist/transformers/builtIns/reference.js.map +1 -1
- package/dist/transformers/builtIns/string.js +1 -1
- package/dist/transformers/builtIns/string.js.map +1 -1
- package/dist/transformers/builtIns/unarray.js +1 -1
- package/dist/transformers/builtIns/unarray.js.map +1 -1
- package/dist/transformers/form.js +1 -1
- package/dist/transformers/form.js.map +1 -1
- package/dist/transformers/generateUri.d.ts +7 -0
- package/dist/transformers/generateUri.js +69 -0
- package/dist/transformers/generateUri.js.map +1 -0
- package/dist/transformers/index.js +2 -2
- package/dist/transformers/index.js.map +1 -1
- package/dist/transformers/json.js +1 -1
- package/dist/transformers/json.js.map +1 -1
- package/dist/transformers/trim.js +1 -1
- package/dist/transformers/trim.js.map +1 -1
- package/dist/types.d.ts +5 -7
- package/dist/utils/action.d.ts +33 -0
- package/dist/utils/action.js +32 -0
- package/dist/utils/action.js.map +1 -0
- package/dist/utils/createMapOptions.d.ts +2 -2
- package/dist/utils/createMapOptions.js +1 -1
- package/dist/utils/createMapOptions.js.map +1 -1
- package/dist/utils/createUnknownServiceError.js +2 -2
- package/dist/utils/createUnknownServiceError.js.map +1 -1
- package/dist/utils/is.d.ts +3 -3
- package/dist/utils/is.js +2 -2
- package/dist/utils/is.js.map +1 -1
- package/dist/utils/validateFilters.js +24 -11
- package/dist/utils/validateFilters.js.map +1 -1
- package/dist/utils/xor.d.ts +1 -0
- package/dist/utils/xor.js +4 -0
- package/dist/utils/xor.js.map +1 -0
- package/package.json +4 -4
package/README.md
CHANGED
|
@@ -7,9 +7,10 @@ An integration layer for node.js.
|
|
|
7
7
|
[](https://coveralls.io/github/integreat-io/integreat?branch=master)
|
|
8
8
|
[](https://codeclimate.com/github/integreat-io/integreat/maintainability)
|
|
9
9
|
|
|
10
|
-
**Note:** We're
|
|
11
|
-
|
|
12
|
-
highly appreciate feedback, but know that anything might
|
|
10
|
+
**Note:** We're closing in on a more stable version, but there might still be
|
|
11
|
+
a few changes coming before v1.0. We encourage trying out and experimenting with
|
|
12
|
+
Integreat, and we highly appreciate feedback, but know that anything might still
|
|
13
|
+
change.
|
|
13
14
|
|
|
14
15
|
The basic idea of Integreat is to make it easy to define a set of data services
|
|
15
16
|
and expose them through a well defined interface, to abstract away the specifics
|
|
@@ -17,31 +18,40 @@ of each service, and map their data to defined schemas.
|
|
|
17
18
|
|
|
18
19
|
This is done through:
|
|
19
20
|
|
|
20
|
-
-
|
|
21
|
-
services
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
21
|
+
- Transporters: Does all the hard work of communicating with the different
|
|
22
|
+
services over different protocols, http, ftp, mongodb, redis, etc., while
|
|
23
|
+
hiding the specifics.
|
|
24
|
+
- Adapters: Adds another layer of normalization, e.g. by creating the same kind
|
|
25
|
+
of data structure from JSON, XML, CSV, etc.
|
|
26
|
+
- Mutations and schemas: You describe how data coming from and going to a
|
|
27
|
+
service, will be transformed to and from schemas you define for your setup.
|
|
28
|
+
Working with mutation for different services to the same schemas, takes away a
|
|
29
|
+
lot of complexity, and you may switch out one service without affecting the
|
|
30
|
+
others.
|
|
31
|
+
- A `dispatch()` function: Everything you do in Integreat is an "action" that
|
|
32
|
+
that describes what to do in a general form. When you dispatch the action,
|
|
33
|
+
Integreat takes care of all data mutation, authentication, caching, etc, and
|
|
34
|
+
sends the action to the right service(s).
|
|
35
|
+
|
|
36
|
+
Furthermore, a key idea in Integreat is that "everything is a service". Want to
|
|
37
|
+
set up a queue? That's a service. Want caching? That's a service. By simply
|
|
38
|
+
defining services and their specifics, you may set up a variety of
|
|
39
|
+
different types of configurations with the same building blocks.
|
|
33
40
|
|
|
34
41
|
```
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
42
|
+
_______________________________________
|
|
43
|
+
| |
|
|
44
|
+
| Integreat |
|
|
45
|
+
| |
|
|
46
|
+
| |-> Mutation <-> Adapter <-> Transporter <-> Service
|
|
47
|
+
Action -> Dispatch -| |
|
|
48
|
+
| |-> Mutation <-> Adapter <-> Transporter <-> Service
|
|
49
|
+
| |
|
|
50
|
+
|_______________________________________|
|
|
43
51
|
```
|
|
44
52
|
|
|
53
|
+
> Editor's note: Revise the following ...
|
|
54
|
+
|
|
45
55
|
Data from the services is retrieved, normalized, and mapped by the adapter, and
|
|
46
56
|
returned asynchronously back to the code that initiated the action. Actions for
|
|
47
57
|
fetching data will be executed right away.
|
|
@@ -55,16 +65,16 @@ only format that will be exposed to the code dispatching the actions. The
|
|
|
55
65
|
mapping, normalizing, and serializing will happing to and from this format,
|
|
56
66
|
according to the defined schemas and mapping rules.
|
|
57
67
|
|
|
58
|
-
To deal with security and permissions, Integreat has a
|
|
59
|
-
|
|
60
|
-
|
|
68
|
+
To deal with security and permissions, Integreat has a concept of an ident.
|
|
69
|
+
Other authentication schemes may be mapped to Integreat's ident scheme, to
|
|
70
|
+
provide data security from a service to another service or to the dispatched
|
|
61
71
|
action. A ground principle is that nothing that enters Integreat from an
|
|
62
72
|
authenticated service, will leave Integreat unauthenticated. What this means,
|
|
63
73
|
though, depends on how you define your services.
|
|
64
74
|
|
|
65
75
|
## Install
|
|
66
76
|
|
|
67
|
-
Requires node
|
|
77
|
+
Requires node v18.
|
|
68
78
|
|
|
69
79
|
Install from npm:
|
|
70
80
|
|
|
@@ -76,6 +86,8 @@ npm install integreat
|
|
|
76
86
|
|
|
77
87
|
The hello world example of Integreat, would look something like this:
|
|
78
88
|
|
|
89
|
+
> Editor's note: Provide an example that may be copy-pasted and run.
|
|
90
|
+
|
|
79
91
|
```javascript
|
|
80
92
|
import Integreat from 'integreat'
|
|
81
93
|
import httpTransporter from 'integreat-transporter-http'
|
|
@@ -127,27 +139,22 @@ returning the following json data:
|
|
|
127
139
|
## Schema definitions
|
|
128
140
|
|
|
129
141
|
To do anything with Integreat, you need to define one or more schemas. They
|
|
130
|
-
describe the data you expected to get out of Integreat. A
|
|
131
|
-
associated with a service, which is used to retrieve data for
|
|
132
|
-
another service is specified.
|
|
142
|
+
describe the data you expected to get out of, or send through, Integreat. A
|
|
143
|
+
schema will be associated with a service, which is used to retrieve data for
|
|
144
|
+
the schema, unless another service is specified in an action payload.
|
|
133
145
|
|
|
134
146
|
```
|
|
135
147
|
{
|
|
136
148
|
id: <string>,
|
|
137
149
|
plural: <string>,
|
|
138
150
|
service: <serviceId>,
|
|
139
|
-
|
|
140
|
-
<
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
<relId>: {
|
|
147
|
-
type: <string>,
|
|
148
|
-
default: <object>,
|
|
149
|
-
query: <query params>
|
|
150
|
-
}
|
|
151
|
+
shape: {
|
|
152
|
+
<fieldId>: <field type id>,
|
|
153
|
+
<fieldId>: {
|
|
154
|
+
$cast: <field type id>,
|
|
155
|
+
$default: <default value>
|
|
156
|
+
$const: <value that will override any other value>
|
|
157
|
+
},
|
|
151
158
|
},
|
|
152
159
|
auth: <auth def>
|
|
153
160
|
}
|
|
@@ -155,64 +162,33 @@ another service is specified.
|
|
|
155
162
|
|
|
156
163
|
The convention is to use singular mode for the `id`. The `plural` property is
|
|
157
164
|
optional, but it's good practice to set it to the plural mode of the `id`, as
|
|
158
|
-
some interfaces may use it.
|
|
159
|
-
[`integreat-api-json`](https://github.com/integreat-io/integreat-api-json) uses
|
|
160
|
-
it to build a RESTful endpoint structure, and will append an _s_ to `id` if
|
|
161
|
-
`plural` is not set – which may be weird in some cases.
|
|
162
|
-
|
|
163
|
-
### Attributes
|
|
164
|
-
|
|
165
|
-
Each attribute is defined with an id, which may contain only alphanumeric
|
|
166
|
-
characters, and may not start with a digit. This id is used to reference the
|
|
167
|
-
attribute.
|
|
168
|
-
|
|
169
|
-
The `type` defaults to `string`. Other options are `integer`, `float`,
|
|
170
|
-
`boolean`, and `date`. Data from Integreat will be cast to corresponding
|
|
171
|
-
JavaScript types.
|
|
172
|
-
|
|
173
|
-
The `default` value will be used when a data service does not provide this value.
|
|
174
|
-
Default is `null`.
|
|
175
|
-
|
|
176
|
-
### Relationships
|
|
165
|
+
some interfaces may use it.
|
|
177
166
|
|
|
178
|
-
|
|
179
|
-
difference: The `type` property refers to other Integreat schemas. E.g. a
|
|
180
|
-
schema for an article may have a relationship called `author`, with
|
|
181
|
-
`type: 'user'`, referring to the schema with id `user`. `type` is required on
|
|
182
|
-
relationships.
|
|
167
|
+
### Fields
|
|
183
168
|
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
of the type the relationship refers to.
|
|
169
|
+
Each field is defined with an id, which may contain only alphanumeric
|
|
170
|
+
characters, and may not start with a digit.
|
|
187
171
|
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
property.
|
|
172
|
+
The `$cast` prop sets the type of the field (what it will be "cast" to). The
|
|
173
|
+
available primitive types, are `string`, `integer`, `float` (or `number`),
|
|
174
|
+
`boolean`, and `date`.
|
|
192
175
|
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
176
|
+
A field may also have another schema as its type, in which case the id of the
|
|
177
|
+
schema is set in `$cast`. An example can be an `article` schema with an `author`
|
|
178
|
+
field of type `user`, referring to a schema with id `user`. When casting the
|
|
179
|
+
`article`, data on the `author` prop will be cast with the `user` schema.
|
|
196
180
|
|
|
197
|
-
|
|
181
|
+
It follows from this that a schema cannot have the same id as a primitive type.
|
|
198
182
|
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
id: 'user',
|
|
202
|
-
...
|
|
203
|
-
relationships: {
|
|
204
|
-
articles: {type: 'article', query: {author: 'id'}}
|
|
205
|
-
}
|
|
206
|
-
}
|
|
207
|
-
```
|
|
183
|
+
The `$default` value will be used when a data service does not provide this
|
|
184
|
+
value. Default is `undefined`.
|
|
208
185
|
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
`id` of the `user` item in question.
|
|
186
|
+
The `$const` value override any value you provide to the field. This is a bit
|
|
187
|
+
strange, and might be removed ...
|
|
212
188
|
|
|
213
189
|
### Authorization
|
|
214
190
|
|
|
215
|
-
Set the `access` property to enforce permission checking
|
|
191
|
+
Set the `access` property on a schema to enforce permission checking. This
|
|
216
192
|
applies to any service that provides this schema.
|
|
217
193
|
|
|
218
194
|
The simplest access type `auth`, which means that anyone can do anything with
|
|
@@ -223,8 +199,7 @@ Example of a schema with an access rule:
|
|
|
223
199
|
```javascript
|
|
224
200
|
{
|
|
225
201
|
id: 'entry',
|
|
226
|
-
|
|
227
|
-
relationships: {...},
|
|
202
|
+
shape: {...},
|
|
228
203
|
access: 'auth'
|
|
229
204
|
}
|
|
230
205
|
```
|
|
@@ -235,36 +210,35 @@ Integreat's principle of not letting authorized data out of Integreat without
|
|
|
235
210
|
an authorization rule. In a way, you can say that `all` is an authorization
|
|
236
211
|
rule, but it allows anybody to access the data, even the unauthenticated.
|
|
237
212
|
|
|
238
|
-
|
|
239
|
-
|
|
213
|
+
On the other end of the spectrum, `none` will allow no one to access data cast
|
|
214
|
+
to this schema, no matter who they are.
|
|
240
215
|
|
|
241
216
|
For a more fine-grained rules, set `access` to an access definition.
|
|
242
217
|
|
|
243
218
|
## Service definitions
|
|
244
219
|
|
|
245
220
|
Service definitions are at the core of Integreat, as they define the services to
|
|
246
|
-
fetch data from, how to
|
|
247
|
-
|
|
221
|
+
fetch data from, how to mutate this data to schemas, and how to send data back
|
|
222
|
+
to the service.
|
|
248
223
|
|
|
249
|
-
A service definition object
|
|
250
|
-
endpoints for fetching from and sending to the
|
|
251
|
-
|
|
224
|
+
A service definition object includes the transporter id, adapter ids, any
|
|
225
|
+
authentication method, the endpoints for fetching from and sending to the
|
|
226
|
+
service, mutations that data to all endpoints will pass through, and options
|
|
227
|
+
for transporters, adapters, etc.
|
|
252
228
|
|
|
253
229
|
```
|
|
254
230
|
{
|
|
255
231
|
id: <string>,
|
|
256
|
-
|
|
232
|
+
transporter: <string>,
|
|
233
|
+
adatpers: [<string>, <string>, ...],
|
|
257
234
|
auth: <auth id>,
|
|
258
235
|
meta: <type id>,
|
|
259
236
|
options: {...},
|
|
237
|
+
mutation: <mutation pipeline>,
|
|
260
238
|
endpoints: [
|
|
261
239
|
<endpoint definition>,
|
|
262
240
|
...
|
|
263
|
-
]
|
|
264
|
-
mappings: {
|
|
265
|
-
<schema id>: <mapping definition | mapping id>,
|
|
266
|
-
...
|
|
267
|
-
}
|
|
241
|
+
]
|
|
268
242
|
}
|
|
269
243
|
```
|
|
270
244
|
|
|
@@ -272,14 +246,14 @@ Service definitions are passed to Integreat on creation through the
|
|
|
272
246
|
`Integreat.create()` function. There is no way to change services after
|
|
273
247
|
creation.
|
|
274
248
|
|
|
275
|
-
See [
|
|
276
|
-
|
|
249
|
+
See [mutations](#mutations) for a description of how to define the mutation
|
|
250
|
+
pipeline for a service.
|
|
277
251
|
|
|
278
252
|
The `auth` property should normally be set to the id of an
|
|
279
|
-
[auth definition](#service-authentication) if the service requires
|
|
280
|
-
In cases where the service is authenticated by other means, e.g.
|
|
281
|
-
username and password in the uri, set the `auth` property to `true`
|
|
282
|
-
that this is an authenticated service.
|
|
253
|
+
[auth definition](#service-authentication), if the service requires
|
|
254
|
+
authentication. In cases where the service is authenticated by other means, e.g.
|
|
255
|
+
by including username and password in the uri, set the `auth` property to `true`
|
|
256
|
+
to signal that this is an authenticated service.
|
|
283
257
|
|
|
284
258
|
### Endpoint definition
|
|
285
259
|
|
|
@@ -293,13 +267,7 @@ that this is an authenticated service.
|
|
|
293
267
|
params: {...},
|
|
294
268
|
filters: []
|
|
295
269
|
},
|
|
296
|
-
validate: [],
|
|
297
270
|
mutation: <mutation pipeline>,
|
|
298
|
-
sendNoDefaults: <boolean>,
|
|
299
|
-
returnNoDefaults: <boolean>,
|
|
300
|
-
mappings: {
|
|
301
|
-
<schema id>: <mapping definition | mapping id>,
|
|
302
|
-
},
|
|
303
271
|
options: {...}
|
|
304
272
|
}
|
|
305
273
|
```
|
|
@@ -310,15 +278,21 @@ An endpoint may specify none or more of the following match properties:
|
|
|
310
278
|
|
|
311
279
|
- `id`: An action payload may include an `endpoint` property, that will be
|
|
312
280
|
matched against this `id`. For actions with an endpoint id, no other matching
|
|
313
|
-
properties will be considered
|
|
281
|
+
properties will be considered.
|
|
314
282
|
- `type`: When set, the endpoint will only be used for actions with the
|
|
315
|
-
specified schema type (
|
|
316
|
-
- `scope`: May be `member` or `collection`, to specify that the
|
|
317
|
-
be used to request one item (member)
|
|
318
|
-
Setting this to `member`
|
|
319
|
-
|
|
283
|
+
specified schema type (the schema's id).
|
|
284
|
+
- `scope`: May be `member`, `members`, or `collection`, to specify that the
|
|
285
|
+
endpoint should be used to request one item (member) by id, several items by
|
|
286
|
+
ids, or an entire collection of items. Setting this to `member` or `members`
|
|
287
|
+
will require an `id` property in the action payload, and this should be an
|
|
288
|
+
array of ids for `members`. Not setting this property signals an endpoint
|
|
289
|
+
that will work for all scopes.
|
|
290
|
+
- `params`: TODO
|
|
291
|
+
- `filters`: TODO
|
|
320
292
|
- `action`: May be set to the type string of an action. The endpoint will match
|
|
321
|
-
only actions of this type
|
|
293
|
+
only actions of this type.
|
|
294
|
+
|
|
295
|
+
> Editor's note: Double check that the order here is correct.
|
|
322
296
|
|
|
323
297
|
Endpoints are matched to an action by picking the matching endpoint with highest
|
|
324
298
|
level of specificity. E.g., for a GET action asking for resources of type
|
|
@@ -330,10 +304,10 @@ endpoints matches – e.g. one with a scope and the other with an action, the on
|
|
|
330
304
|
matching with scope is picked. When two endpoints are equally specified with the
|
|
331
305
|
same match properties specified, the first one is used.
|
|
332
306
|
|
|
333
|
-
All
|
|
334
|
-
|
|
335
|
-
|
|
336
|
-
|
|
307
|
+
All but `id` may be specified with an array of matching values, so that an
|
|
308
|
+
endpoint may match more cases. However, when two endpoints match on a property
|
|
309
|
+
specified as an array on one and as a single value on the other, the one with
|
|
310
|
+
the single value is picked.
|
|
337
311
|
|
|
338
312
|
When no match properties are set, the endpoint will match any actions, as long
|
|
339
313
|
as no other endpoints match.
|
|
@@ -352,7 +326,7 @@ Example service definition with endpoint parameters:
|
|
|
352
326
|
```
|
|
353
327
|
{
|
|
354
328
|
id: 'entries',
|
|
355
|
-
adapter: '
|
|
329
|
+
adapter: 'http',
|
|
356
330
|
endpoints: [
|
|
357
331
|
{
|
|
358
332
|
params: {
|
|
@@ -376,35 +350,30 @@ unless to define them as required:
|
|
|
376
350
|
included for `scope: 'collection'`, and optional when scope is not set.
|
|
377
351
|
- `type`: The item type from the action payload or from the data property (if it
|
|
378
352
|
is an object and not an array).
|
|
379
|
-
- `typePlural`: The plural form of the type, gotten from the corresponding
|
|
380
|
-
schema's `plural` prop – or by adding an 's' to the type is `plural` is not
|
|
381
|
-
set.
|
|
382
353
|
|
|
383
|
-
|
|
354
|
+
> Editor's note: Make sure what we say here about `id` is correct.
|
|
384
355
|
|
|
385
|
-
|
|
386
|
-
an object with properties to be passed to the adapter as part of a request. The
|
|
387
|
-
props are completely adapter specific, so that each adapter can dictate what
|
|
388
|
-
kind of information it will need, but there are a set of recommended props to
|
|
389
|
-
use when they are relevant:
|
|
390
|
-
|
|
391
|
-
- `uri`: A uri template, where e.g. `{id}` will be placed with the value of the
|
|
392
|
-
parameter `id` from the action payload. For a full specification of the template
|
|
393
|
-
format, see
|
|
394
|
-
[Integreat URI Template](https://github.com/integreat-io/great-uri-template).
|
|
356
|
+
#### Options property
|
|
395
357
|
|
|
396
|
-
|
|
397
|
-
|
|
398
|
-
|
|
399
|
-
|
|
358
|
+
Unlike the match properties, the `options` property is required (TODO: is it?).
|
|
359
|
+
This should be an object with properties to be passed to the transporter and
|
|
360
|
+
adapters as part of a request. The props are completely transporter/adapter
|
|
361
|
+
specific, so that each one can dictate what kind of information it will need,
|
|
362
|
+
but there are a set of recommended props to use when they are relevant:
|
|
400
363
|
|
|
364
|
+
- `uri`: A uri template, where e.g. `{payloadid}` will be replaced with the
|
|
365
|
+
value of the parameter `id` from the action payload.
|
|
366
|
+
- `queryParams`: TODO
|
|
401
367
|
- `method`: An adapter specific keyword, to tell the adapter which method of
|
|
402
368
|
transportation to use. For adapters based on http, the options will typically
|
|
403
369
|
be `PUT`, `POST`, etc. The method specified on the endpoint will override any
|
|
404
370
|
method provided elsewhere. As an example, the `SET` action will use the `PUT`
|
|
405
371
|
method as default, but only if no method is specified on the endpoint.
|
|
406
372
|
|
|
407
|
-
##
|
|
373
|
+
## Mutations
|
|
374
|
+
|
|
375
|
+
> Editor's note: Everything here is wrong. How much should we describe here
|
|
376
|
+
> before directing to map-transform?
|
|
408
377
|
|
|
409
378
|
```
|
|
410
379
|
{
|
|
@@ -477,6 +446,8 @@ types, by referring to the mapping id from several service definitions.
|
|
|
477
446
|
|
|
478
447
|
### Paths
|
|
479
448
|
|
|
449
|
+
> Editor's note: This should also be rewritten in light of map-transform.
|
|
450
|
+
|
|
480
451
|
Mappings, attributes, and relationships all have an optional `path` property,
|
|
481
452
|
for specifying what part of the data from the service to return in each case.
|
|
482
453
|
(Endpoints may also have a `path` property, but not all adapters support this.)
|
|
@@ -533,52 +504,16 @@ You may optionally supply alternative paths by providing an array of paths. If
|
|
|
533
504
|
the first one does not match any properties in the data, the next path is tried,
|
|
534
505
|
and so on.
|
|
535
506
|
|
|
536
|
-
### Qualifiers
|
|
537
|
-
|
|
538
|
-
When a service returns data for several schemas, Integreat needs a way to
|
|
539
|
-
recognize which schema to use for each item in the data. For some services,
|
|
540
|
-
the different schemas may be find on different paths in the data, so
|
|
541
|
-
specifying different paths on each mapping is sufficient. But when all items
|
|
542
|
-
are returned in one array, for instance, you need to specify qualifiers for
|
|
543
|
-
the mappings.
|
|
544
|
-
|
|
545
|
-
A qualifier is simply a path with an expression that will evaluate to true or
|
|
546
|
-
false. If a mapping has qualifiers, it will only be applied to data that
|
|
547
|
-
satisfies all its qualifiers. Qualifiers are applied to the data at the
|
|
548
|
-
mapping's path, before it is mapped and transformed.
|
|
549
|
-
|
|
550
|
-
An example of two mappings with qualifiers:
|
|
551
|
-
|
|
552
|
-
```
|
|
553
|
-
...
|
|
554
|
-
mappings: {
|
|
555
|
-
entry: {
|
|
556
|
-
attributes: {...},
|
|
557
|
-
qualifier: 'type="entry"'
|
|
558
|
-
},
|
|
559
|
-
admin: {
|
|
560
|
-
attributes: {...},
|
|
561
|
-
qualifier: [
|
|
562
|
-
'type="account"',
|
|
563
|
-
'permissions.roles[]="admin"'
|
|
564
|
-
]
|
|
565
|
-
}
|
|
566
|
-
}
|
|
567
|
-
```
|
|
568
|
-
|
|
569
|
-
When a qualifier points to an array, the qualifier returns true when at least
|
|
570
|
-
one of the items in the array satisfies the condition.
|
|
571
|
-
|
|
572
507
|
### Configuring metadata
|
|
573
508
|
|
|
574
509
|
If a service may send and receive metadata, set the `meta` property to the id of
|
|
575
|
-
a schema defining the metadata as
|
|
510
|
+
a schema defining the metadata as its shape.
|
|
576
511
|
|
|
577
512
|
```
|
|
578
513
|
{
|
|
579
514
|
id: 'meta',
|
|
580
515
|
service: <id of service handling the metadata>,
|
|
581
|
-
|
|
516
|
+
shape: {
|
|
582
517
|
<metadataKey>: {
|
|
583
518
|
type: <string>
|
|
584
519
|
}
|
|
@@ -587,37 +522,21 @@ a schema defining the metadata as attributes.
|
|
|
587
522
|
```
|
|
588
523
|
|
|
589
524
|
The `service` property on the type defines the service that holds metadata for
|
|
590
|
-
this type. In some cases the service you're defining metadata for and the
|
|
591
|
-
handling these metadata will be the same, but it is possible to let a
|
|
592
|
-
handle other services' metadata. If you're getting data from a read-only
|
|
593
|
-
but need to, for instance, set the `lastSyncedAt` metadata for this
|
|
594
|
-
you'll set up a service as a store for this (the store may also hold
|
|
595
|
-
of data). Then the read-only store will be defined with
|
|
596
|
-
`meta` schema will have `service='store'`.
|
|
525
|
+
this type. In some cases the service you're defining metadata for and the
|
|
526
|
+
service handling these metadata, will be the same, but it is possible to let a
|
|
527
|
+
service handle other services' metadata. If you're getting data from a read-only
|
|
528
|
+
service, but need to, for instance, set the `lastSyncedAt` metadata for this
|
|
529
|
+
store, you'll set up a service as a store for this (the store may also hold
|
|
530
|
+
other types of data). Then the read-only store will be defined with
|
|
531
|
+
`meta='meta'`, and the `meta` schema will have `service='store'`.
|
|
597
532
|
|
|
598
|
-
|
|
533
|
+
> Editor's note: This is not easy to understand, and the following is wrong. :S
|
|
599
534
|
|
|
600
535
|
As with other data received and sent to services, make sure to include endpoints
|
|
601
536
|
for the service that will hold the metadata, matching the `GET_META` and
|
|
602
537
|
`SET_META` actions, or the schema defining the metadata. The way you set up
|
|
603
538
|
these endpoints will depend on your service.
|
|
604
539
|
|
|
605
|
-
Also define a [mapping](#mapping-definition) between this schema and the
|
|
606
|
-
service. You may leave out `attributes` and `relationships` definitions and the
|
|
607
|
-
service will receive the metadata in Integreat's standard format:
|
|
608
|
-
|
|
609
|
-
```
|
|
610
|
-
{
|
|
611
|
-
id: <serviceId>,
|
|
612
|
-
type: <meta type>,
|
|
613
|
-
createdAt: <date>,
|
|
614
|
-
updatedAt: <date>,
|
|
615
|
-
attributes: {
|
|
616
|
-
<key>: <value>
|
|
617
|
-
}
|
|
618
|
-
}
|
|
619
|
-
```
|
|
620
|
-
|
|
621
540
|
Finally, if a service will not have metadata, simply set `meta` to null or skip
|
|
622
541
|
it all together.
|
|
623
542
|
|
|
@@ -640,7 +559,7 @@ Example ident:
|
|
|
640
559
|
|
|
641
560
|
The actual value of the `id` is irrelevant to Integreat, as long as it is a
|
|
642
561
|
string with A-Z, a-z, 0-9, \_, and -, and it's unique within one Integreat
|
|
643
|
-
configuration. This means that mapped
|
|
562
|
+
configuration. This means that mapped values from services may be used as ident
|
|
644
563
|
ids, but be careful to set this up right.
|
|
645
564
|
|
|
646
565
|
`tokens` are other values that may identify this ident. E.g., an api that uses
|
|
@@ -654,11 +573,12 @@ setting the auth rules for a service, roles may be used to require that
|
|
|
654
573
|
the request to get data of this schema, an ident with the role `admin` must
|
|
655
574
|
be provided.
|
|
656
575
|
|
|
657
|
-
|
|
658
|
-
the code dispatching an action to get hold of the properties of an ident
|
|
659
|
-
secure way. Once Integreat receives an ident, it will
|
|
660
|
-
information and uphold its part of the security
|
|
661
|
-
and execute actions that the ident have
|
|
576
|
+
Actions are authenticated by setting an ident on the `meta.ident` property. It's
|
|
577
|
+
up to the code dispatching an action to get hold of the properties of an ident
|
|
578
|
+
in a secure way. Once Integreat receives an ident through a dispatch, it will
|
|
579
|
+
assume this is accurate information and uphold its part of the security
|
|
580
|
+
agreement and only return data and execute actions that the ident have
|
|
581
|
+
permissions for.
|
|
662
582
|
|
|
663
583
|
### Access rules
|
|
664
584
|
|
|
@@ -948,10 +868,6 @@ is fetched, if it exists.
|
|
|
948
868
|
The endpoint will be picked according to the matching properties, unless an
|
|
949
869
|
endpoint id is supplied as an `endpoint` property of `payload`.
|
|
950
870
|
|
|
951
|
-
By default, the returned data will be cast with default values, but set
|
|
952
|
-
`returnNoDefaults: true` on the action payload to get only values mapped from
|
|
953
|
-
the service data.
|
|
954
|
-
|
|
955
871
|
#### `GET_UNMAPPED`
|
|
956
872
|
|
|
957
873
|
Get data from a service without applying the mapping rules. Returned in the
|
|
@@ -1053,12 +969,6 @@ may be removed in future versions of Integreat.
|
|
|
1053
969
|
The endpoint will be picked according to the matching properties, unless an
|
|
1054
970
|
endpoint id is supplied as an `endpoint` property of `payload`.
|
|
1055
971
|
|
|
1056
|
-
To send only fields mapped from the action data to the service, set
|
|
1057
|
-
`sendNoDefaults: true` on the endpoint config to cast the data going to the
|
|
1058
|
-
service without using default values. This will not affect the data coming back
|
|
1059
|
-
from the action, but set `returnNoDefaults: true` to leave defaults out of the
|
|
1060
|
-
response data.
|
|
1061
|
-
|
|
1062
972
|
#### `SET_META`
|
|
1063
973
|
|
|
1064
974
|
Set metadata on a service. Returned in the `data` property is whatever the
|
package/dist/create.d.ts
CHANGED
|
@@ -1,14 +1,15 @@
|
|
|
1
1
|
/// <reference types="node" resolution-mode="require"/>
|
|
2
2
|
import EventEmitter = require('node:events');
|
|
3
|
-
import type { Dictionaries, Transformer,
|
|
3
|
+
import type { Dictionaries, Transformer, TransformDefinition } from 'map-transform/types.js';
|
|
4
4
|
import type { Middleware, Transporter, Dispatch, JobDef, Action, Response, ActionHandler } from './types.js';
|
|
5
5
|
import type { ServiceDef, IdentConfig, AuthDef, Authenticator, Service } from './service/types.js';
|
|
6
6
|
import type { SchemaDef } from './schema/types.js';
|
|
7
|
+
import Auth from './service/Auth.js';
|
|
7
8
|
import { Schema } from './schema/index.js';
|
|
8
9
|
export interface Definitions {
|
|
9
10
|
schemas: SchemaDef[];
|
|
10
11
|
services: ServiceDef[];
|
|
11
|
-
mutations?: Record<string,
|
|
12
|
+
mutations?: Record<string, TransformDefinition>;
|
|
12
13
|
auths?: AuthDef[];
|
|
13
14
|
identConfig?: IdentConfig;
|
|
14
15
|
queueService?: string;
|
|
@@ -32,4 +33,5 @@ export interface Instance<ResponseData = unknown> {
|
|
|
32
33
|
close: () => Promise<Response>;
|
|
33
34
|
on: (eventName: string, listener: (...args: unknown[]) => void) => EventEmitter;
|
|
34
35
|
}
|
|
36
|
+
export declare const setUpAuth: (authenticators?: Record<string, Authenticator>) => (def: AuthDef) => Auth;
|
|
35
37
|
export default function create({ services: serviceDefs, schemas: schemaDefs, mutations, auths: authDefs, identConfig, queueService, dictionaries, jobs: jobsDefs, }: Definitions, { transporters, transformers, handlers, authenticators }: Resources, middlewareForDispatch?: Middleware[], middlewareForService?: Middleware[]): Instance;
|
package/dist/create.js
CHANGED
|
@@ -16,6 +16,13 @@ import close from './close.js';
|
|
|
16
16
|
import { indexById } from './utils/indexUtils.js';
|
|
17
17
|
import createSchedule from './utils/createSchedule.js';
|
|
18
18
|
import createDispatchScheduled from './dispatchScheduled.js';
|
|
19
|
+
export const setUpAuth = (authenticators) => function setUpAuth(def) {
|
|
20
|
+
const authenticator = lookupById(def.authenticator, authenticators);
|
|
21
|
+
if (!authenticator) {
|
|
22
|
+
throw new Error(`Auth config '${def.id}' references an unknown authenticator id '${def.authenticator}'`);
|
|
23
|
+
}
|
|
24
|
+
return new Auth(def.id, authenticator, def.options);
|
|
25
|
+
};
|
|
19
26
|
export default function create({ services: serviceDefs, schemas: schemaDefs, mutations, auths: authDefs, identConfig, queueService, dictionaries, jobs: jobsDefs = [], }, { transporters, transformers, handlers, authenticators }, middlewareForDispatch = [], middlewareForService = []) {
|
|
20
27
|
if (!Array.isArray(serviceDefs) || !Array.isArray(schemaDefs)) {
|
|
21
28
|
throw new TypeError('Please provide Integreat with at least services and schemas');
|
|
@@ -27,7 +34,7 @@ export default function create({ services: serviceDefs, schemas: schemaDefs, mut
|
|
|
27
34
|
const mapOptions = createMapOptions(schemas, mutations, { ...builtinTransformers, ...transformers }, dictionaries);
|
|
28
35
|
const auths = Array.isArray(authDefs)
|
|
29
36
|
? authDefs
|
|
30
|
-
.map((
|
|
37
|
+
.map(setUpAuth(authenticators))
|
|
31
38
|
.reduce(indexById, {})
|
|
32
39
|
: undefined;
|
|
33
40
|
const services = serviceDefs
|
package/dist/create.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"create.js","sourceRoot":"","sources":["../src/create.ts"],"names":[],"mappings":";;AAAA,8CAA4C;AAuB5C,OAAO,IAAI,MAAM,mBAAmB,CAAA;AACpC,OAAO,eAAe,MAAM,qBAAqB,CAAA;AACjD,OAAO,KAAK,MAAM,mBAAmB,CAAA;AACrC,OAAO,mBAAmB,MAAM,kCAAkC,CAAA;AAClE,OAAO,YAAwB,MAAM,mBAAmB,CAAA;AACxD,OAAO,aAAa,MAAM,oBAAoB,CAAA;AAC9C,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AACxC,OAAO,gBAAgB,MAAM,6BAA6B,CAAA;AAC1D,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAA;AAClD,OAAO,cAAc,MAAM,eAAe,CAAA;AAC1C,OAAO,MAAM,MAAM,aAAa,CAAA;AAChC,OAAO,KAAK,MAAM,YAAY,CAAA;AAC9B,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAA;AACjD,OAAO,cAAc,MAAM,2BAA2B,CAAA;AACtD,OAAO,uBAAuB,MAAM,wBAAwB,CAAA;
|
|
1
|
+
{"version":3,"file":"create.js","sourceRoot":"","sources":["../src/create.ts"],"names":[],"mappings":"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"}
|