soul-cli 0.10.0 → 0.12.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 (43) hide show
  1. package/.env.sample +1 -0
  2. package/.github/workflows/ci.yml +2 -0
  3. package/.prettierrc +4 -0
  4. package/.release-please-manifest.json +1 -1
  5. package/CHANGELOG.md +25 -0
  6. package/README.md +3 -0
  7. package/ROADMAP.md +83 -25
  8. package/docs/api/batch-examples.md +55 -0
  9. package/docs/api/rows-examples.md +10 -2
  10. package/docs/api-examples.md +1 -0
  11. package/docs/auth.md +10 -0
  12. package/package.json +1 -1
  13. package/src/cli.js +6 -0
  14. package/src/config/index.js +7 -0
  15. package/src/config/index.test.js +10 -0
  16. package/src/constants/messages.js +1 -1
  17. package/src/controllers/batch.js +128 -0
  18. package/src/controllers/batch.test.js +180 -0
  19. package/src/controllers/rows.js +223 -213
  20. package/src/controllers/rows.query.test.js +369 -0
  21. package/src/index.js +2 -0
  22. package/src/middlewares/api.js +6 -2
  23. package/src/middlewares/api.test.js +27 -13
  24. package/src/middlewares/auth.js +52 -33
  25. package/src/middlewares/auth.test.js +137 -3
  26. package/src/middlewares/broadcast.js +7 -11
  27. package/src/routes/batch.js +12 -0
  28. package/src/routes/rows.js +1 -0
  29. package/src/schemas/batch.js +27 -0
  30. package/src/schemas/rows.js +4 -1
  31. package/src/services/authService.js +31 -4
  32. package/src/services/authService.test.js +76 -0
  33. package/src/services/rowService.js +12 -6
  34. package/src/services/rowService.test.js +37 -0
  35. package/src/swagger/index.js +14 -16
  36. package/src/swagger/swagger.json +68 -59
  37. package/src/utils/query.js +285 -0
  38. package/src/utils/query.test.js +147 -0
  39. package/src/utils/sql.js +24 -0
  40. package/src/utils/sql.test.js +14 -0
  41. package/src/websocket.js +10 -8
  42. package/src/websocket.test.js +52 -0
  43. package/src/schemas/index.js +0 -30
@@ -3,8 +3,100 @@ const { rowService } = require('../services');
3
3
  const {
4
4
  assertValidTableName,
5
5
  assertValidColumnName,
6
- assertValidOperator,
6
+ invalidRequestError,
7
+ quoteIdentifier,
7
8
  } = require('../utils/sql');
9
+ const {
10
+ buildFilterClause,
11
+ buildDistinct,
12
+ buildGroupedSelect,
13
+ } = require('../utils/query');
14
+
15
+ const failure = (status, body) =>
16
+ Object.assign(new Error(body.message || body.error), { status, body });
17
+
18
+ const sendError = (res, error) =>
19
+ res
20
+ .status(error.status || 400)
21
+ .json(error.body || { message: error.message, error });
22
+
23
+ const resolveLookupField = (tableName, lookupField) => {
24
+ if (lookupField) {
25
+ assertValidColumnName(db, tableName, lookupField);
26
+ return lookupField;
27
+ }
28
+ return db
29
+ .prepare('SELECT * FROM pragma_table_info(?)')
30
+ .all(tableName)
31
+ .find((field) => field.pk === 1).name;
32
+ };
33
+
34
+ // Core row writes: sync, throw on failure, shared with the batch endpoint.
35
+ const insertRow = ({ tableName, fields: queryFields }) => {
36
+ assertValidTableName(db, tableName);
37
+
38
+ // Remove null values from fields for accurate query construction.
39
+ const fields = Object.fromEntries(
40
+ Object.entries(queryFields).filter(([, value]) => value !== null),
41
+ );
42
+ const data = rowService.save({ tableName, fields });
43
+
44
+ return {
45
+ status: 201,
46
+ body: { message: 'Row inserted', data },
47
+ broadcast: {
48
+ type: 'INSERT',
49
+ data: { pk: data.lastInsertRowid, ...fields },
50
+ },
51
+ };
52
+ };
53
+
54
+ const updateRows = ({ tableName, pks, fields, lookupField: lookup }) => {
55
+ assertValidTableName(db, tableName);
56
+ const lookupField = resolveLookupField(tableName, lookup);
57
+ Object.keys(fields).forEach((field) =>
58
+ assertValidColumnName(db, tableName, field),
59
+ );
60
+
61
+ if (Object.keys(fields).length === 0) {
62
+ throw failure(400, {
63
+ message: 'No fields provided',
64
+ error: 'no_fields_provided',
65
+ });
66
+ }
67
+
68
+ const data = rowService.update({ tableName, fields, lookupField, pks });
69
+
70
+ return {
71
+ status: 200,
72
+ body: { message: 'Row updated', data },
73
+ broadcast: {
74
+ type: 'UPDATE',
75
+ _lookup_field: lookupField,
76
+ data: { pks: pks.split(','), ...fields },
77
+ },
78
+ };
79
+ };
80
+
81
+ const deleteRows = ({ tableName, pks, lookupField: lookup }) => {
82
+ assertValidTableName(db, tableName);
83
+ const lookupField = resolveLookupField(tableName, lookup);
84
+ const data = rowService.delete({ tableName, lookupField, pks });
85
+
86
+ if (data.changes === 0) {
87
+ throw failure(404, { error: 'not_found' });
88
+ }
89
+
90
+ return {
91
+ status: 200,
92
+ body: { message: 'Row deleted', data },
93
+ broadcast: {
94
+ type: 'DELETE',
95
+ _lookup_field: lookupField,
96
+ data: { pks: pks.split(',') },
97
+ },
98
+ };
99
+ };
8
100
 
9
101
  // Return paginated rows of a table
10
102
  const listTableRows = async (req, res, next) => {
@@ -41,7 +133,19 @@ const listTableRows = async (req, res, next) => {
41
133
  in: 'query',
42
134
  }
43
135
  #swagger.parameters['_filters'] = {
44
- description: 'Filter rows. e.g. ?_filters=name:John,age:20 will return rows where name is John and age is 20.',
136
+ description: 'Filter rows. e.g. ?_filters=name:John,age:20 will return rows where name is John and age is 20. Operators: __eq, __neq, __lt, __gt, __lte, __gte, __null, __notnull, __like, __contains, __startswith, __between, __in, __notin. Lists use brackets, e.g. id:[1,2]. Wrap a value in double quote characters to use , : | in it. (a:1|b:2) is an OR group and ! negates a filter or group.',
137
+ in: 'query',
138
+ }
139
+ #swagger.parameters['_distinct'] = {
140
+ description: 'Return unique combinations of these columns. e.g. ?_distinct=category,price',
141
+ in: 'query',
142
+ }
143
+ #swagger.parameters['_group_by'] = {
144
+ description: 'Group rows by these columns. e.g. ?_group_by=category',
145
+ in: 'query',
146
+ }
147
+ #swagger.parameters['_aggregate'] = {
148
+ description: 'Aggregates: count, sum:col, avg:col, min:col, max:col. e.g. ?_group_by=category&_aggregate=count,sum:price. Results are named count, sum_price, ...',
45
149
  in: 'query',
46
150
  }
47
151
  */
@@ -55,6 +159,9 @@ const listTableRows = async (req, res, next) => {
55
159
  _schema,
56
160
  _extend,
57
161
  _filters = '',
162
+ _distinct,
163
+ _group_by,
164
+ _aggregate,
58
165
  } = req.query;
59
166
 
60
167
  const page = parseInt(_page);
@@ -70,76 +177,22 @@ const listTableRows = async (req, res, next) => {
70
177
  }
71
178
 
72
179
  // if _filters are provided, filter rows by them
73
- // _filters consists of fields to filter by
74
- // filtering is case insensitive
75
- // e.g. ?_filters=name:John,age:20
76
- // will filter by name like '%John%' and age like '%20%'
77
- let filters;
78
-
79
- // split the filters by comma(,) except when in an array
80
- const re = /,(?![^[]*?\])/;
81
- try {
82
- filters =
83
- _filters === ''
84
- ? []
85
- : _filters.split(re).map((filter) => {
86
- //NOTE: When using the _filter parameter, the values are split using the ":" sign, like this (_filters=Total__eq:1). However, if the user sends a date value, such as (_filters=InvoiceDate__eq:2010-01-08 00:00:00), there will be additional colon (":") signs present.
87
- let [key, ...value] = filter.split(':');
88
- if (value.length === 1) {
89
- value = value[0];
90
- } else {
91
- value = value.map((element) => element).join(':');
92
- }
93
-
94
- let field = key.split('__')[0];
95
- let fieldOperator = key.split('__')[1] || 'eq';
96
-
97
- assertValidColumnName(db, tableName, field);
98
- let operator;
99
- try {
100
- operator = assertValidOperator(fieldOperator);
101
- } catch {
102
- throw new Error(
103
- `Invalid field operator '${fieldOperator}' for field '${field}'. You can only use the following operators after the '${field}' field: __lt, __gt, __lte, __gte, __eq, __neq.`,
104
- );
105
- }
106
-
107
- if (['null', 'notnull'].includes(fieldOperator)) {
108
- value = null;
109
- }
110
-
111
- return { field, operator, value };
112
- });
113
- } catch (error) {
114
- return res.status(error.status || 400).json({
115
- message: error.message,
116
- error: error,
117
- });
118
- }
119
-
180
+ // e.g. ?_filters=name:John,age__gte:20 (filters are ANDed)
181
+ // e.g. ?_filters=id:[1,2],(name:John|age__null),!city:Paris,note:"a, b"
120
182
  let whereString = '';
121
183
  const whereStringValues = [];
122
184
 
123
185
  if (_filters !== '') {
124
- whereString += ' WHERE ';
125
- whereString += filters
126
- .map((filter) => {
127
- if (filter.value) {
128
- if (filter.value.startsWith('[') && filter.value.endsWith(']')) {
129
- const arrayValues = filter.value.slice(1, -1).split(',');
130
- whereStringValues.push(...arrayValues);
131
- return `${tableName}.${filter.field} IN (${arrayValues
132
- .map(() => '?')
133
- .join(', ')})`;
134
- } else {
135
- whereStringValues.push(filter.value);
136
- return `${tableName}.${filter.field} ${filter.operator} ?`;
137
- }
138
- } else {
139
- return `${tableName}.${filter.field} ${filter.operator}`;
140
- }
141
- })
142
- .join(' AND ');
186
+ try {
187
+ const { clause, values } = buildFilterClause(db, tableName, _filters);
188
+ whereString = ` WHERE ${clause}`;
189
+ whereStringValues.push(...values);
190
+ } catch (error) {
191
+ return res.status(error.status || 400).json({
192
+ message: error.message,
193
+ error: error,
194
+ });
195
+ }
143
196
  params = `_filters=${_filters}&`;
144
197
  }
145
198
 
@@ -174,38 +227,88 @@ const listTableRows = async (req, res, next) => {
174
227
  }
175
228
  }
176
229
 
230
+ // _distinct=col1,col2 returns unique combinations of those columns
231
+ // _group_by=col&_aggregate=count,sum:price groups rows and aggregates them
232
+ const isGrouped = Boolean(_group_by || _aggregate);
233
+ let schemaString = '';
234
+ let groupString = '';
235
+ let distinctString = '';
236
+ let grouped = { groupColumns: [], aliases: [] };
237
+
238
+ try {
239
+ if (
240
+ (_distinct || isGrouped) &&
241
+ (_schema || _extend || (_distinct && isGrouped))
242
+ ) {
243
+ throw invalidRequestError(
244
+ "_distinct and _group_by/_aggregate can't be combined with each other or with _schema/_extend",
245
+ );
246
+ }
247
+
248
+ if (_distinct) {
249
+ distinctString = buildDistinct(db, tableName, _distinct);
250
+ schemaString = distinctString;
251
+ params += `_distinct=${_distinct}&`;
252
+ } else if (isGrouped) {
253
+ grouped = buildGroupedSelect(db, tableName, _group_by, _aggregate);
254
+ ({ schemaString, groupString } = grouped);
255
+ params += _group_by ? `_group_by=${_group_by}&` : '';
256
+ params += _aggregate ? `_aggregate=${_aggregate}&` : '';
257
+ }
258
+ } catch (error) {
259
+ return res.status(error.status || 400).json({
260
+ message: error.message,
261
+ error: error,
262
+ });
263
+ }
264
+
177
265
  // if _ordering is provided, order rows by it
178
266
  // e.g. ?_ordering=name will order by name
179
267
  // e.g. ?_ordering=-name will order by name descending
268
+ // e.g. ?_ordering=category,-price orders by several columns
180
269
  // e.g. ?_ordering=publisher.name will order by publisher name, considering that publisher is a foreign key to publishers table
181
270
  let orderString = '';
182
271
  let extendString = '';
183
272
  let joins = {};
184
273
 
185
274
  if (_ordering) {
186
- const isDesc = _ordering.startsWith('-');
187
- const cleanOrder = _ordering.replace('-', '');
188
-
189
275
  try {
190
- if (cleanOrder.includes('.')) {
191
- // Handle foreign key sort, e.g. publisher.name
192
- const [relation, field] = cleanOrder.split('.');
276
+ const orderTerms = _ordering.split(',').map((term) => {
277
+ const isDesc = term.startsWith('-');
278
+ const cleanOrder = isDesc ? term.slice(1) : term;
279
+ const direction = isDesc ? 'DESC' : 'ASC';
280
+
281
+ if (isGrouped) {
282
+ if (grouped.aliases.includes(cleanOrder)) {
283
+ return `${quoteIdentifier(cleanOrder)} ${direction}`;
284
+ }
285
+ if (!grouped.groupColumns.includes(cleanOrder)) {
286
+ throw invalidRequestError(
287
+ `Can only order by a _group_by column or an aggregate: '${cleanOrder}'`,
288
+ );
289
+ }
290
+ return `${tableName}.${cleanOrder} ${direction}`;
291
+ }
193
292
 
194
- const { foreignKey, joinedTableName, joinedTableFields } =
195
- rowService.getForeignKeyInfo(tableName, relation);
293
+ if (cleanOrder.includes('.')) {
294
+ // Handle foreign key sort, e.g. publisher.name
295
+ const [relation, field] = cleanOrder.split('.');
196
296
 
197
- assertValidColumnName(db, joinedTableName, field);
297
+ if (!joins[relation]) {
298
+ joins[relation] = rowService.getForeignKeyInfo(tableName, relation);
299
+ extendString += ` LEFT JOIN ${joins[relation].joinedTableName} ON ${joins[relation].joinedTableName}.${joins[relation].foreignKey.to} = ${tableName}.${relation}`;
300
+ }
301
+
302
+ assertValidColumnName(db, joins[relation].joinedTableName, field);
303
+ return `${joins[relation].joinedTableName}.${field} ${direction}`;
304
+ }
198
305
 
199
- extendString += ` LEFT JOIN ${joinedTableName} ON ${joinedTableName}.${foreignKey.to} = ${tableName}.${relation}`;
200
- joins[relation] = { foreignKey, joinedTableName, joinedTableFields };
201
- orderString += ` ORDER BY ${joinedTableName}.${field} ${
202
- isDesc ? 'DESC' : 'ASC'
203
- }`;
204
- } else {
205
306
  // regular field sort
206
307
  assertValidColumnName(db, tableName, cleanOrder);
207
- orderString += ` ORDER BY ${cleanOrder} ${isDesc ? 'DESC' : 'ASC'}`;
208
- }
308
+ return `${cleanOrder} ${direction}`;
309
+ });
310
+
311
+ orderString = ` ORDER BY ${orderTerms.join(', ')}`;
209
312
  } catch (error) {
210
313
  return res.status(error.status || 400).json({
211
314
  message: error.message,
@@ -219,7 +322,6 @@ const listTableRows = async (req, res, next) => {
219
322
  // if _schema is provided, return only those fields
220
323
  // e.g. ?_schema=name,age will return only name and age fields
221
324
  // if _schema is not provided, return all fields
222
- let schemaString = '';
223
325
  if (_schema) {
224
326
  const schemaFields = _schema.split(',');
225
327
  try {
@@ -234,7 +336,7 @@ const listTableRows = async (req, res, next) => {
234
336
  });
235
337
  }
236
338
  params += `_schema=${_schema}&`;
237
- } else {
339
+ } else if (!_distinct && !isGrouped) {
238
340
  schemaString = `${tableName}.*`;
239
341
  }
240
342
 
@@ -330,7 +432,9 @@ const listTableRows = async (req, res, next) => {
330
432
  tableName,
331
433
  extendString,
332
434
  whereString,
435
+ groupString,
333
436
  orderString,
437
+ distinct: Boolean(_distinct),
334
438
  limit,
335
439
  page: limit * (page - 1),
336
440
  whereStringValues,
@@ -350,11 +454,16 @@ const listTableRows = async (req, res, next) => {
350
454
  }
351
455
 
352
456
  // get total number of rows
353
- const total = rowService.getCount({
354
- tableName,
355
- whereString,
356
- whereStringValues,
357
- });
457
+ const total =
458
+ isGrouped && !groupString
459
+ ? 1
460
+ : rowService.getCount({
461
+ tableName,
462
+ whereString,
463
+ whereStringValues,
464
+ groupString,
465
+ distinctString,
466
+ });
358
467
 
359
468
  const nextPage =
360
469
  data.length === limit
@@ -404,17 +513,10 @@ const insertRowInTable = async (req, res, next) => {
404
513
  */
405
514
 
406
515
  const { name: tableName } = req.params;
407
- const { fields: queryFields } = req.body;
408
-
409
- // Remove null values from fields for accurate query construction.
410
- const fields = Object.fromEntries(
411
- Object.entries(queryFields).filter(([, value]) => value !== null),
412
- );
516
+ const { fields } = req.body;
413
517
 
414
518
  try {
415
- assertValidTableName(db, tableName);
416
-
417
- const data = rowService.save({ tableName, fields });
519
+ const { status, body, broadcast } = insertRow({ tableName, fields });
418
520
 
419
521
  /*
420
522
  #swagger.responses[201] = {
@@ -424,18 +526,8 @@ const insertRowInTable = async (req, res, next) => {
424
526
  }
425
527
  }
426
528
  */
427
- res.status(201).json({
428
- message: 'Row inserted',
429
- data,
430
- });
431
-
432
- req.broadcast = {
433
- type: 'INSERT',
434
- data: {
435
- pk: data.lastInsertRowid,
436
- ...fields,
437
- },
438
- };
529
+ res.status(status).json(body);
530
+ req.broadcast = broadcast;
439
531
  next();
440
532
  } catch (error) {
441
533
  /*
@@ -446,10 +538,7 @@ const insertRowInTable = async (req, res, next) => {
446
538
  }
447
539
  }
448
540
  */
449
- res.status(error.status || 400).json({
450
- message: error.message,
451
- error: error,
452
- });
541
+ sendError(res, error);
453
542
  }
454
543
  };
455
544
 
@@ -695,64 +784,18 @@ const updateRowInTableByPK = async (req, res, next) => {
695
784
  const { fields } = req.body;
696
785
  const { _lookup_field } = req.query;
697
786
 
698
- let lookupField = _lookup_field;
699
-
700
- try {
701
- assertValidTableName(db, tableName);
702
-
703
- if (!_lookup_field) {
704
- // find the primary key of the table
705
- lookupField = db
706
- .prepare('SELECT * FROM pragma_table_info(?)')
707
- .all(tableName)
708
- .find((field) => field.pk === 1).name;
709
- } else {
710
- assertValidColumnName(db, tableName, _lookup_field);
711
- }
712
-
713
- Object.keys(fields).forEach((field) =>
714
- assertValidColumnName(db, tableName, field),
715
- );
716
- } catch (error) {
717
- return res.status(error.status || 400).json({
718
- message: error.message,
719
- error: error,
720
- });
721
- }
722
-
723
- if (Object.keys(fields).length === 0) {
724
- return res.status(400).json({
725
- message: 'No fields provided',
726
- error: 'no_fields_provided',
727
- });
728
- }
729
-
730
787
  try {
731
- const data = rowService.update({
788
+ const { status, body, broadcast } = updateRows({
732
789
  tableName,
733
- fields,
734
- lookupField,
735
790
  pks,
791
+ fields,
792
+ lookupField: _lookup_field,
736
793
  });
737
-
738
- res.json({
739
- message: 'Row updated',
740
- data,
741
- });
742
- req.broadcast = {
743
- type: 'UPDATE',
744
- _lookup_field: lookupField,
745
- data: {
746
- pks: pks.split(','),
747
- ...fields,
748
- },
749
- };
794
+ res.status(status).json(body);
795
+ req.broadcast = broadcast;
750
796
  next();
751
797
  } catch (error) {
752
- res.status(400).json({
753
- message: error.message,
754
- error: error,
755
- });
798
+ sendError(res, error);
756
799
  }
757
800
  };
758
801
 
@@ -784,57 +827,24 @@ const deleteRowInTableByPK = async (req, res, next) => {
784
827
  const { name: tableName, pks } = req.params;
785
828
  const { _lookup_field } = req.query;
786
829
 
787
- let lookupField = _lookup_field;
788
-
789
830
  try {
790
- assertValidTableName(db, tableName);
791
-
792
- if (!_lookup_field) {
793
- // find the primary key of the table
794
- lookupField = db
795
- .prepare('SELECT * FROM pragma_table_info(?)')
796
- .all(tableName)
797
- .find((field) => field.pk === 1).name;
798
- } else {
799
- assertValidColumnName(db, tableName, _lookup_field);
800
- }
801
- } catch (error) {
802
- return res.status(error.status || 400).json({
803
- message: error.message,
804
- error: error,
831
+ const { status, body, broadcast } = deleteRows({
832
+ tableName,
833
+ pks,
834
+ lookupField: _lookup_field,
805
835
  });
806
- }
807
-
808
- try {
809
- const data = rowService.delete({ tableName, lookupField, pks });
810
-
811
- if (data.changes === 0) {
812
- res.status(404).json({
813
- error: 'not_found',
814
- });
815
- } else {
816
- res.json({
817
- message: 'Row deleted',
818
- data,
819
- });
820
- req.broadcast = {
821
- type: 'DELETE',
822
- _lookup_field: lookupField,
823
- data: {
824
- pks: pks.split(','),
825
- },
826
- };
827
- next();
828
- }
836
+ res.status(status).json(body);
837
+ req.broadcast = broadcast;
838
+ next();
829
839
  } catch (error) {
830
- res.status(error.status || 400).json({
831
- message: error.message,
832
- error: error,
833
- });
840
+ sendError(res, error);
834
841
  }
835
842
  };
836
843
 
837
844
  module.exports = {
845
+ insertRow,
846
+ updateRows,
847
+ deleteRows,
838
848
  listTableRows,
839
849
  insertRowInTable,
840
850
  getRowInTableByPK,