@hitchy/plugin-odem-socket.io 0.1.0 → 0.2.0

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 (3) hide show
  1. package/api/services/odem/websocket-provider.js +8 -8
  2. package/package.json +1 -1
  3. package/readme.md +31 -16
package/api/services/odem/websocket-provider.js CHANGED
@@ -77,17 +77,17 @@ module.exports = function() {
77
77
 
78
78
  io.on( "connection", socket => {
79
79
  socket
80
- .on( `${prefix}:list`, async( sessionId, queryOptions, uuidsOnly, response ) => {
81
- logError( "request for listing %s instances w/ queryOptions %j and uuidsOnly %j", modelName, queryOptions, uuidsOnly );
80
+ .on( `${prefix}:list`, async( sessionId, queryOptions, loadRecords, response ) => {
81
+ logError( "request for listing %s instances w/ queryOptions %j and loadRecords %j", modelName, queryOptions, Boolean( loadRecords ) );
82
82
 
83
83
  try {
84
84
  const meta = {};
85
- const items = await model.list( queryOptions, { loadRecords: !uuidsOnly, metaCollector: meta } );
85
+ const items = await model.list( queryOptions, { loadRecords: Boolean( loadRecords ), metaCollector: meta } );
86
86
 
87
87
  response( {
88
88
  success: true,
89
89
  count: meta.count,
90
- items: items.map( item => ( uuidsOnly ? { uuid: item.uuid } : item.toObject( { serialized: true } ) ) ),
90
+ items: items.map( item => ( loadRecords ? item.toObject( { serialized: true } ) : { uuid: item.uuid } ) ),
91
91
  } );
92
92
  } catch ( error ) {
93
93
  logError( "listing %s instances failed: %s", modelName, error.stack );
@@ -97,17 +97,17 @@ module.exports = function() {
97
97
  } );
98
98
  }
99
99
  } )
100
- .on( `${prefix}:find`, async( sessionId, query, queryOptions, uuidsOnly, response ) => {
101
- logError( "request for finding %s instances matching %j w/ queryOptions %j and uuidsOnly %j", modelName, query, queryOptions, uuidsOnly );
100
+ .on( `${prefix}:find`, async( sessionId, query, queryOptions, loadRecords, response ) => {
101
+ logError( "request for finding %s instances matching %j w/ queryOptions %j and uuidsOnly %j", modelName, query, queryOptions, Boolean( loadRecords ) );
102
102
 
103
103
  try {
104
104
  const meta = {};
105
- const items = await model.find( query, queryOptions, { loadRecords: !uuidsOnly, metaCollector: meta } );
105
+ const items = await model.find( query, queryOptions, { loadRecords: Boolean( loadRecords ), metaCollector: meta } );
106
106
 
107
107
  response( {
108
108
  success: true,
109
109
  count: meta.count,
110
- items: items.map( item => ( uuidsOnly ? { uuid: item.uuid } : item.toObject( { serialized: true } ) ) ),
110
+ items: items.map( item => ( loadRecords ? item.toObject( { serialized: true } ) : { uuid: item.uuid } ) ),
111
111
  } );
112
112
  } catch ( error ) {
113
113
  logError( "finding %s instances matching %j failed: %s", modelName, error.stack );
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@hitchy/plugin-odem-socket.io",
3
- "version": "0.1.0",
3
+ "version": "0.2.0",
4
4
  "description": "exposing Hitchy's ODM via websocket",
5
5
  "main": "index.js",
6
6
  "scripts": {
package/readme.md CHANGED
@@ -19,6 +19,12 @@ npm i @hitchy/plugin-odem @hitchy/plugin-socket.io
19
19
  ```
20
20
 
21
21
 
22
+ ## Breaking changes
23
+
24
+ ### v0.2
25
+
26
+ * The parameter `uuidsOnly` of actions `<modelName>:list` and `<modelName>:find` has been replaced by `loadRecords` to match the semantics of server-side Odem API. You have to negate its value to adapt.
27
+
22
28
  ## Usage
23
29
 
24
30
  ### Basics
@@ -55,9 +61,13 @@ In all these examples, a _sessionId_ is given. This is the current user's sessio
55
61
 
56
62
  #### &lt;modelName>:list
57
63
 
58
- This request is the websocket variant of [Model.list()](https://odem.hitchy.org/api/model.html#model-list).
64
+ This request is the websocket variant of [Model.list()](https://odem.hitchy.org/api/model.html#model-list). Supported arguments are
59
65
 
60
- First argument following the session ID is forwarded as first argument to [Model.list()](https://odem.hitchy.org/api/model.html#model-list). The following argument is a boolean controlling if resulting list should provide UUID per listed match, only.
66
+ * the session ID,
67
+ * [query-related options](https://odem.hitchy.org/api/model.html#query-related-options) as supported by `Model.list()` and
68
+ * a boolean controlling `loadRecords` of [result-related options](https://odem.hitchy.org/api/model.html#result-related-options) supported by `Model.list()`.
69
+
70
+ > This boolean must be `true` to actually get all properties of retrieved items. Otherwise, listed items are represented by their UUIDs, only.
61
71
 
62
72
  ```javascript
63
73
  socket.emit( "<modelName>:list", sessionId, { limit: 10 }, false, response => {
@@ -67,11 +77,18 @@ socket.emit( "<modelName>:list", sessionId, { limit: 10 }, false, response => {
67
77
  } );
68
78
  ```
69
79
 
70
- The `response` is an object consisting of truthy property `success` on success or `error` message in case of a failure. On success, property `count` is providing total count of matches and `items` is the list of matching items' properties.
80
+ Last argument is a callback to be invoked with the resulting response from server-side. `response` is an object consisting of truthy property `success` on success or `error` message in case of a failure. On success, property `count` is providing total count of matches and `items` is the list of matching items' properties.
71
81
 
72
82
  #### &lt;modelName>:find
73
83
 
74
- This request is searching for instances of selected model matching some query. It is invoking [Model.find()](https://odem.hitchy.org/api/model.html#model-find) internally passing the first two arguments following the session ID as-is. The third argument is limited to a boolean controlling whether only UUIDs should be listed or not.
84
+ This request is searching for instances of selected model matching some query. It is invoking [Model.find()](https://odem.hitchy.org/api/model.html#model-find). Arguments are
85
+
86
+ * the session ID,
87
+ * the [query](https://odem.hitchy.org/api/model.html#model-find) describing items to find,
88
+ * [query-related options](https://odem.hitchy.org/api/model.html#query-related-options) as supported by `Model.find()` and
89
+ * a boolean controlling `loadRecords` of [result-related options](https://odem.hitchy.org/api/model.html#result-related-options) supported by `Model.find()`.
90
+
91
+ > This boolean must be `true` to actually get all properties of retrieved items. Otherwise, listed items are represented by their UUIDs, only.
75
92
 
76
93
  ```javascript
77
94
  socket.emit( "<modelName>:find", sessionId, {}, { limit: 10 }, true, response => {
@@ -81,11 +98,11 @@ socket.emit( "<modelName>:find", sessionId, {}, { limit: 10 }, true, response =>
81
98
  } );
82
99
  ```
83
100
 
84
- The `response` is an object consisting of truthy property `success` on success or `error` message in case of a failure. On success, property `count` is providing total count of matches and `items` is the selected excerpt from that list of matching items' each given by its properties including its UUID.
101
+ Last argument is a callback to be invoked with the resulting response from server-side. `response` is an object consisting of truthy property `success` on success or `error` message in case of a failure. On success, property `count` is providing total count of matches and `items` is the selected excerpt from that list of matching items' each given by its properties including its UUID.
85
102
 
86
103
  #### &lt;modelName>:create
87
104
 
88
- This request is creating another instance of selected model assigning provided properties as initial values. Properties of instance to create are provided in event argument following the session ID.
105
+ This request is creating another instance of selected model assigning provided properties as initial values. Properties of instance to create are provided as serializable object in argument following the session ID.
89
106
 
90
107
  ```javascript
91
108
  socket.emit( "<modelName>:create", sessionId, { title: "important things" }, response => {
@@ -95,34 +112,33 @@ socket.emit( "<modelName>:create", sessionId, { title: "important things" }, res
95
112
  } );
96
113
  ```
97
114
 
98
- The `response` is an object consisting of truthy property `success` on success or `error` message in case of a failure. On success, `properties` of created instance are returned. These may be different from provided ones due to server-side constraints.
115
+ Last argument is a callback to be invoked with the resulting response from server-side. `response` is an object consisting of truthy property `success` on success or `error` message in case of a failure. On success, `properties` of created instance are returned. These may be different from provided ones due to server-side constraints. The created item's UUID is added to that set of properties as `uuid`.
99
116
 
100
117
  #### &lt;modelName>:read
101
118
 
102
119
  This request is fetching a single instance's properties.
103
120
 
104
121
  ```javascript
105
- socket.emit( "<modelName>:create", sessionId, "12345678-1234-1234-1234-123456789012", response => {
122
+ socket.emit( "<modelName>:read", sessionId, "12345678-1234-1234-1234-123456789012", response => {
106
123
  // - check for `response.success` or `response.error`
107
124
  // - process properties of fetched instance in `response.properties`
108
125
  } );
109
126
  ```
110
127
 
111
- The `response` is an object consisting of truthy property `success` on success or `error` message in case of a failure. On success, `properties` of selected instance are returned.
128
+ Last argument is a callback to be invoked with the resulting response from server-side. `response` is an object consisting of truthy property `success` on success or `error` message in case of a failure. On success, `properties` of selected instance are returned.
112
129
 
113
130
  #### &lt;modelName>:update
114
131
 
115
- This request is updating an existing instance of model. Following the session ID, the selected item's UUID and the values per property to be assigned are provided in follow-up arguments.
132
+ This request is updating an existing instance of model. Following the session ID, the UUID of item to update and the values per property to assign are provided in additional arguments.
116
133
 
117
134
  ```javascript
118
135
  socket.emit( "<modelName>:update", sessionId, "12345678-1234-1234-1234-123456789012", { prio: 1 }, response => {
119
136
  // - check for `response.success` or `response.error`
120
- // - process properties of eventually created instance in `response.properties`
121
- // - created instance's UUID is available as `response.properties.uuid`
137
+ // - properties of updated instance are provided in `response.properties`
122
138
  } );
123
139
  ```
124
140
 
125
- The `response` is an object consisting of truthy property `success` on success or `error` message in case of a failure. On success, `properties` of updated instance are returned. These may be different from provided ones due to server-side constraints.
141
+ Last argument is a callback to be invoked with the resulting response from server-side. `response` is an object consisting of truthy property `success` on success or `error` message in case of a failure. On success, `properties` of updated instance are returned. These may be different from provided ones due to server-side constraints.
126
142
 
127
143
  #### &lt;modelName>:delete
128
144
 
@@ -131,12 +147,11 @@ This request is eventually completing the CRUD-support of this API by deleting a
131
147
  ```javascript
132
148
  socket.emit( "<modelName>:delete", sessionId, "12345678-1234-1234-1234-123456789012", response => {
133
149
  // - check for `response.success` or `response.error`
134
- // - process properties of eventually created instance in `response.properties`
135
- // - created instance's UUID is available as `response.properties.uuid`
150
+ // - deleted instance's UUID is available as `response.properties.uuid`
136
151
  } );
137
152
  ```
138
153
 
139
- The `response` is an object consisting of truthy property `success` on success or `error` message in case of a failure. On success, `properties` of updated instance are returned.
154
+ Last argument is a callback to be invoked with the resulting response from server-side. `response` is an object consisting of truthy property `success` on success or `error` message in case of a failure. On success, `properties` of updated instance are returned.
140
155
 
141
156
 
142
157
  ### Notifications