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.
Files changed (111) hide show
  1. package/README.md +137 -227
  2. package/dist/create.d.ts +4 -2
  3. package/dist/create.js +8 -1
  4. package/dist/create.js.map +1 -1
  5. package/dist/dispatch.d.ts +3 -3
  6. package/dist/dispatch.js +10 -10
  7. package/dist/dispatch.js.map +1 -1
  8. package/dist/handlers/delete.d.ts +1 -1
  9. package/dist/handlers/delete.js +7 -10
  10. package/dist/handlers/delete.js.map +1 -1
  11. package/dist/handlers/expire.d.ts +1 -1
  12. package/dist/handlers/expire.js +9 -17
  13. package/dist/handlers/expire.js.map +1 -1
  14. package/dist/handlers/get.d.ts +1 -1
  15. package/dist/handlers/get.js +17 -25
  16. package/dist/handlers/get.js.map +1 -1
  17. package/dist/handlers/getAll.d.ts +2 -2
  18. package/dist/handlers/getAll.js +15 -16
  19. package/dist/handlers/getAll.js.map +1 -1
  20. package/dist/handlers/getIdent.d.ts +1 -1
  21. package/dist/handlers/getIdent.js +10 -10
  22. package/dist/handlers/getIdent.js.map +1 -1
  23. package/dist/handlers/getMeta.d.ts +1 -1
  24. package/dist/handlers/getMeta.js +11 -14
  25. package/dist/handlers/getMeta.js.map +1 -1
  26. package/dist/handlers/queue.d.ts +1 -1
  27. package/dist/handlers/queue.js +7 -9
  28. package/dist/handlers/queue.js.map +1 -1
  29. package/dist/handlers/run.js +24 -36
  30. package/dist/handlers/run.js.map +1 -1
  31. package/dist/handlers/service.d.ts +1 -1
  32. package/dist/handlers/service.js +4 -13
  33. package/dist/handlers/service.js.map +1 -1
  34. package/dist/handlers/set.d.ts +1 -1
  35. package/dist/handlers/set.js +4 -3
  36. package/dist/handlers/set.js.map +1 -1
  37. package/dist/handlers/setMeta.d.ts +1 -1
  38. package/dist/handlers/setMeta.js +5 -9
  39. package/dist/handlers/setMeta.js.map +1 -1
  40. package/dist/handlers/sync.js +6 -6
  41. package/dist/handlers/sync.js.map +1 -1
  42. package/dist/index.d.ts +2 -2
  43. package/dist/index.js +2 -2
  44. package/dist/index.js.map +1 -1
  45. package/dist/mutations/exchangeUri.js +1 -1
  46. package/dist/mutations/exchangeUri.js.map +1 -1
  47. package/dist/schema/createCastMapping.d.ts +2 -2
  48. package/dist/schema/createCastMapping.js +39 -25
  49. package/dist/schema/createCastMapping.js.map +1 -1
  50. package/dist/schema/index.d.ts +3 -3
  51. package/dist/schema/index.js +10 -15
  52. package/dist/schema/index.js.map +1 -1
  53. package/dist/schema/types.d.ts +2 -2
  54. package/dist/service/Auth.d.ts +1 -1
  55. package/dist/service/Auth.js +0 -3
  56. package/dist/service/Auth.js.map +1 -1
  57. package/dist/service/endpoints/create.d.ts +2 -2
  58. package/dist/service/endpoints/create.js +8 -16
  59. package/dist/service/endpoints/create.js.map +1 -1
  60. package/dist/service/endpoints/index.d.ts +2 -2
  61. package/dist/service/endpoints/index.js.map +1 -1
  62. package/dist/service/endpoints/types.d.ts +2 -4
  63. package/dist/service/index.d.ts +2 -2
  64. package/dist/service/index.js +12 -18
  65. package/dist/service/index.js.map +1 -1
  66. package/dist/service/types.d.ts +4 -11
  67. package/dist/transformers/builtIns/boolean.js +1 -1
  68. package/dist/transformers/builtIns/boolean.js.map +1 -1
  69. package/dist/transformers/builtIns/date.js +1 -1
  70. package/dist/transformers/builtIns/date.js.map +1 -1
  71. package/dist/transformers/builtIns/integer.js +1 -1
  72. package/dist/transformers/builtIns/integer.js.map +1 -1
  73. package/dist/transformers/builtIns/number.js +1 -1
  74. package/dist/transformers/builtIns/number.js.map +1 -1
  75. package/dist/transformers/builtIns/object.js +1 -1
  76. package/dist/transformers/builtIns/object.js.map +1 -1
  77. package/dist/transformers/builtIns/reference.js +1 -1
  78. package/dist/transformers/builtIns/reference.js.map +1 -1
  79. package/dist/transformers/builtIns/string.js +1 -1
  80. package/dist/transformers/builtIns/string.js.map +1 -1
  81. package/dist/transformers/builtIns/unarray.js +1 -1
  82. package/dist/transformers/builtIns/unarray.js.map +1 -1
  83. package/dist/transformers/form.js +1 -1
  84. package/dist/transformers/form.js.map +1 -1
  85. package/dist/transformers/generateUri.d.ts +7 -0
  86. package/dist/transformers/generateUri.js +69 -0
  87. package/dist/transformers/generateUri.js.map +1 -0
  88. package/dist/transformers/index.js +2 -2
  89. package/dist/transformers/index.js.map +1 -1
  90. package/dist/transformers/json.js +1 -1
  91. package/dist/transformers/json.js.map +1 -1
  92. package/dist/transformers/trim.js +1 -1
  93. package/dist/transformers/trim.js.map +1 -1
  94. package/dist/types.d.ts +5 -7
  95. package/dist/utils/action.d.ts +33 -0
  96. package/dist/utils/action.js +32 -0
  97. package/dist/utils/action.js.map +1 -0
  98. package/dist/utils/createMapOptions.d.ts +2 -2
  99. package/dist/utils/createMapOptions.js +1 -1
  100. package/dist/utils/createMapOptions.js.map +1 -1
  101. package/dist/utils/createUnknownServiceError.js +2 -2
  102. package/dist/utils/createUnknownServiceError.js.map +1 -1
  103. package/dist/utils/is.d.ts +3 -3
  104. package/dist/utils/is.js +2 -2
  105. package/dist/utils/is.js.map +1 -1
  106. package/dist/utils/validateFilters.js +24 -11
  107. package/dist/utils/validateFilters.js.map +1 -1
  108. package/dist/utils/xor.d.ts +1 -0
  109. package/dist/utils/xor.js +4 -0
  110. package/dist/utils/xor.js.map +1 -0
  111. package/package.json +4 -4
package/README.md CHANGED
@@ -7,9 +7,10 @@ An integration layer for node.js.
7
7
  [![Coverage Status](https://coveralls.io/repos/github/integreat-io/integreat/badge.svg?branch=master)](https://coveralls.io/github/integreat-io/integreat?branch=master)
8
8
  [![Maintainability](https://api.codeclimate.com/v1/badges/a5bd9841a47ff9f74577/maintainability)](https://codeclimate.com/github/integreat-io/integreat/maintainability)
9
9
 
10
- **Note:** We're still changing the api rather drastically from release to
11
- release. We encourage trying it out and experimenting with Integreat, and we
12
- highly appreciate feedback, but know that anything might change.
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
- - adapters, that does all the hard work of communicating with the different
21
- services
22
- - a definition format, for setting up each service with the right adapter and
23
- parameters
24
- - a `dispatch()` function that sends actions to the right adapters via internal
25
- action handlers
26
-
27
- It is possible to set up Integreat to treat one service as a store/buffer for
28
- other services, and schedule syncs between the store and the other services.
29
-
30
- Finally, there will be different interface modules available, that will plug
31
- into the `dispatch()` function and offer other ways of reaching data from the
32
- services such as out of the box REST or GraphQL APSs.
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
- | Integreat |
37
- | |
38
- | |-> Adapter <-> Service
39
- Action -> Dispatch -| |
40
- | |-> Adapter <-> Service
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 built-in concept of an
59
- ident. Other authentication schemes may be mapped to Integreat's ident scheme,
60
- to provide data security from a service to another service or to the dispatched
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 v8.6.
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 type will be
131
- associated with a service, which is used to retrieve data for the type, unless
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
- attributes: {
140
- <attrId>: {
141
- type: <string>,
142
- default: <object>
143
- }
144
- },
145
- relationships: {
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. For instance,
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
- Relationship is defined in the same way as attributes, but with one important
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
- The `default` property sets a default value for the relationship, in the same
185
- way as for attributes, but note that this value should be a valid id for an item
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
- Finally, relationships have a `query` property, which is used to retrieve items
189
- for this relationship. In many cases, a service may not have data that maps to
190
- id(s) for a relationship directly, and this is the typical use case for this
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
- The `query` property is an object with key/value pairs, where the key is the id
194
- of a field (an attribute, a relationship, or `id`) on the schema the relationship
195
- refers to, and the value is the id of field on this schema.
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
- Example schema with a query definition:
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
- In this case, the `articles` relationship on the `user` schema may be fetched by
210
- querying for all items of type `article`, where the `author` field equals the
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 on the schema. This
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
- attributes: {...},
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
- The last of the simpler access types, is `none`, which will simly give no one
239
- access, no matter who they are.
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 map this data to a set of items to make available
247
- through Integreat's data api, and how to send data back to the service.
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 defines the adapter, any authentication method, the
250
- endpoints for fetching from and sending to the service, and mappings to the
251
- supported schemas (attributes and relationships):
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
- adapter: <string>,
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 [mapping definition](#mapping-definition) for a description of the
276
- relationship between services and mappings, and the `mappings` property.
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 authentication.
280
- In cases where the service is authenticated by other means, e.g. by including
281
- username and password in the uri, set the `auth` property to `true` to signal
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 (not to be confused with the action type)
316
- - `scope`: May be `member` or `collection`, to specify that the endpoint should
317
- be used to request one item (member) or an entire collection of items.
318
- Setting this to `member` will require an `id` property in the action payload.
319
- Not setting this property signals an endpoint that will work for both
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 match properties except `id` may be specified with an array of matching
334
- values, so that an endpoint may match more cases. However, when two endpoints
335
- match on a property specified as an array on one and as a single value on the
336
- other, the one with the single value is picked.
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: 'json',
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
- #### Options property
354
+ > Editor's note: Make sure what we say here about `id` is correct.
384
355
 
385
- Unlike the match properties, the `options` property is required. This should be
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
- - `path`: A [path](#paths) into the data, specific for this endpoint. It will
397
- usually point to an array, in which the items can be found, but as mappings may
398
- have their own `path`, the endpoint path may point to an object from where the
399
- different mapping paths point to different arrays.
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
- ## Mapping definition
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 attributes.
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
- attributes: {
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 service
591
- handling these metadata will be the same, but it is possible to let a service
592
- handle other services' metadata. If you're getting data from a read-only service,
593
- but need to, for instance, set the `lastSyncedAt` metadata for this store,
594
- you'll set up a service as a store for this (the store may also hold other types
595
- of data). Then the read-only store will be defined with `meta='meta'`, and the
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
- It will usually make no sense to specify default values for metadata.
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 value from services may be used as ident
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
- Idents may be supplied with an action on the `meta.ident` property. It's up to
658
- the code dispatching an action to get hold of the properties of an ident in a
659
- secure way. Once Integreat receives an ident, it will assume this is accurate
660
- information and uphold its part of the security agreement and only return data
661
- and execute actions that the ident have permissions for.
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, MapDefinition } from 'map-transform/types.js';
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, MapDefinition>;
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((def) => new Auth(def.id, lookupById(def.authenticator, authenticators), def.options))
37
+ .map(setUpAuth(authenticators))
31
38
  .reduce(indexById, {})
32
39
  : undefined;
33
40
  const services = serviceDefs
@@ -1 +1 @@
1
- {"version":3,"file":"create.js","sourceRoot":"","sources":["../src/create.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"create.js","sourceRoot":"","sources":["../src/create.ts"],"names":[],"mappings":"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"}