soul-cli 0.8.1 → 0.8.2

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.
@@ -62,6 +62,15 @@
62
62
  "contributions": [
63
63
  "code"
64
64
  ]
65
+ },
66
+ {
67
+ "login": "thoughtsunificator",
68
+ "name": "Romain Lebesle",
69
+ "avatar_url": "https://avatars.githubusercontent.com/u/85041649?v=4",
70
+ "profile": "http://thoughtsunificator.me",
71
+ "contributions": [
72
+ "code"
73
+ ]
65
74
  }
66
75
  ],
67
76
  "contributorsPerLine": 7,
@@ -0,0 +1,8 @@
1
+ meta {
2
+ name: auth
3
+ seq: 2
4
+ }
5
+
6
+ auth {
7
+ mode: inherit
8
+ }
@@ -0,0 +1,25 @@
1
+ meta {
2
+ name: obtain-access-token
3
+ type: http
4
+ seq: 1
5
+ }
6
+
7
+ post {
8
+ url: {{base_url}}/api/auth/token/obtain
9
+ body: json
10
+ auth: inherit
11
+ }
12
+
13
+ body:json {
14
+ {
15
+ "fields": {
16
+ "username": "john",
17
+ "password": "johns_passowrd"
18
+ }
19
+ }
20
+ }
21
+
22
+ settings {
23
+ encodeUrl: true
24
+ timeout: 0
25
+ }
@@ -0,0 +1,6 @@
1
+ {
2
+ "version": "1",
3
+ "name": "soul",
4
+ "type": "collection",
5
+ "ignore": ["node_modules", ".git"]
6
+ }
@@ -0,0 +1,3 @@
1
+ vars {
2
+ base_url: http://localhost:8000
3
+ }
@@ -0,0 +1,8 @@
1
+ meta {
2
+ name: rows
3
+ seq: 1
4
+ }
5
+
6
+ auth {
7
+ mode: inherit
8
+ }
@@ -0,0 +1,25 @@
1
+ meta {
2
+ name: list-rows-with-ordering
3
+ type: http
4
+ seq: 1
5
+ }
6
+
7
+ get {
8
+ url: {{base_url}}/api/tables/:tableName/rows/?_ordering=-CustomerId.LastName&_extend=CustomerId
9
+ body: none
10
+ auth: inherit
11
+ }
12
+
13
+ params:query {
14
+ _ordering: -CustomerId.LastName
15
+ _extend: CustomerId
16
+ }
17
+
18
+ params:path {
19
+ tableName: Invoice
20
+ }
21
+
22
+ settings {
23
+ encodeUrl: true
24
+ timeout: 0
25
+ }
@@ -0,0 +1,8 @@
1
+ meta {
2
+ name: tables
3
+ seq: 3
4
+ }
5
+
6
+ auth {
7
+ mode: inherit
8
+ }
@@ -0,0 +1,16 @@
1
+ meta {
2
+ name: list-tables
3
+ type: http
4
+ seq: 1
5
+ }
6
+
7
+ get {
8
+ url: {{base_url}}/api/tables
9
+ body: none
10
+ auth: inherit
11
+ }
12
+
13
+ settings {
14
+ encodeUrl: true
15
+ timeout: 0
16
+ }
package/README.md CHANGED
@@ -8,16 +8,43 @@
8
8
  [![justforfunnoreally.dev badge](https://img.shields.io/badge/justforfunnoreally-dev-9ff)](https://justforfunnoreally.dev)
9
9
  [![All Contributors](https://img.shields.io/github/all-contributors/thevahidal/soul?color=ee8449&style=flat-square)](#contributors)
10
10
 
11
- ## Installation
11
+ ## Usage
12
+
13
+ ### Docker
14
+
15
+ > This is the preferred method as the dependency [better-sqlite3](https://github.com/WiseLibs/better-sqlite3) is making of lot of assumptions about the system it will be installed and running on which in most cases will lead to errors when installing soul.
16
+
17
+ Using the following Dockerfile:
18
+
19
+ <details>
20
+ <summary>Dockerfile</summary>
21
+
22
+ ```nginx
23
+ # node:19-alpine amd64
24
+ FROM node@sha256:d0ba7111bc031323ce2706f8e424afc868db289ba40ff55b05561cf59c123be1 AS node
25
+
26
+ WORKDIR /app
27
+
28
+ ENV NODE_ENV="production"
29
+
30
+ COPY package-lock.json package.json ./
12
31
 
13
- Install Soul CLI with npm
32
+ RUN apk update && apk add python3=3.11.10-r1 build-base=0.5-r3 && npm ci
33
+
34
+ COPY . .
35
+
36
+ CMD [ "npm", "start" ]
37
+ ```
38
+ </details>
39
+
40
+ You can proceed [to building the application](https://docs.docker.com/get-started/workshop/02_our_app/#build-the-apps-image).
41
+
42
+ ### npm
14
43
 
15
44
  ```bash
16
45
  npm install -g soul-cli
17
46
  ```
18
47
 
19
- ## Usage
20
-
21
48
  ### 1. Running Soul
22
49
 
23
50
  Soul is command line tool, after installing it,
@@ -148,7 +175,7 @@ A collection of projects that revolve around the Soul ecosystem.
148
175
  git clone https://github.com/thevahidal/soul # Clone project
149
176
 
150
177
  cp .env.sample .env # Duplicate sample environment variables
151
- nano .env # Update the environment variables
178
+ vim .env # Update the environment variables
152
179
 
153
180
  npm install # Install dependencies
154
181
  npm run dev # Start the dev server
@@ -168,6 +195,10 @@ npm run dev # Start the dev server
168
195
 
169
196
  Make sure to replace the placeholders with the appropriate values for your environment.
170
197
 
198
+ ## Hosting Static Content Using Soul
199
+
200
+ You can host static content using Soul by utilizing its extensions feature. This allows you to expose your static application through Soul, enabling users to access your content without hosting multiple applications. please check [this](./docs/self-hosting.md) document
201
+
171
202
  ## Community
172
203
 
173
204
  [Join](https://bit.ly/soul-discord) the discussion in our Discord server and help making Soul together.
@@ -198,6 +229,7 @@ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/d
198
229
  <td align="center" valign="top" width="14.28%"><a href="https://godot.id"><img src="https://avatars.githubusercontent.com/u/40712686?v=4?s=100" width="100px;" alt="Hanz"/><br /><sub><b>Hanz</b></sub></a><br /><a href="https://github.com/thevahidal/soul/commits?author=HanzCEO" title="Code">💻</a></td>
199
230
  <td align="center" valign="top" width="14.28%"><a href="https://github.com/KoenDG"><img src="https://avatars.githubusercontent.com/u/1440619?v=4?s=100" width="100px;" alt="Koen De Groote"/><br /><sub><b>Koen De Groote</b></sub></a><br /><a href="https://github.com/thevahidal/soul/commits?author=KoenDG" title="Code">💻</a></td>
200
231
  <td align="center" valign="top" width="14.28%"><a href="https://github.com/TahaKhanAbdalli"><img src="https://avatars.githubusercontent.com/u/50602678?v=4?s=100" width="100px;" alt="Muhammad Taha Khan"/><br /><sub><b>Muhammad Taha Khan</b></sub></a><br /><a href="https://github.com/thevahidal/soul/commits?author=TahaKhanAbdalli" title="Code">💻</a></td>
232
+ <td align="center" valign="top" width="14.28%"><a href="http://thoughtsunificator.me"><img src="https://avatars.githubusercontent.com/u/85041649?v=4?s=100" width="100px;" alt="Romain Lebesle"/><br /><sub><b>Romain Lebesle</b></sub></a><br /><a href="https://github.com/thevahidal/soul/commits?author=thoughtsunificator" title="Code">💻</a></td>
201
233
  </tr>
202
234
  </tbody>
203
235
  </table>
Binary file
@@ -0,0 +1,54 @@
1
+ # Hosting Static Content Using Soul
2
+
3
+ You can host static content using Soul by utilizing its extensions feature. This allows you to expose your static application through Soul, enabling users to access your content without hosting multiple applications.
4
+
5
+ Here are diagrams showing how to access Soul APIs when running standalone and how to expose a static client via extensions.
6
+
7
+ **Accessing Soul APIs**
8
+ ![soul standalone](../assets/images/soul-standalone.png)
9
+
10
+ **Accessing a React Admin Application via Soul**
11
+ ![soul RA app](../assets/images/soul-RA-app.png)
12
+
13
+ ## Steps
14
+
15
+ In this guide, we will demonstrate how to host a static `React Admin` application.
16
+
17
+ 1. Create an `_extensions` folder and add an `api.js` file to it.:
18
+ ```sh
19
+ mkdir _extensions && touch _extensions/api.js
20
+ ```
21
+ 2. Add the following code to the `api.js` file:
22
+
23
+ ```js
24
+ const reactAdminApp = {
25
+ method: "GET",
26
+ path: "/api/client",
27
+ handler: (req, res, db) => {
28
+ const clientPath = path.join(__dirname, "../dist", "index.html");
29
+ res.app.use(express.static(path.join(__dirname, "../dist")));
30
+ res.sendFile(clientPath);
31
+ },
32
+ };
33
+ ```
34
+
35
+ 3. Build your React Admin client:
36
+
37
+ ```sh
38
+ npm run build
39
+ ```
40
+
41
+ 4. Copy the `dist` folder from your `React Admin` project to the `_extensions` folder:
42
+
43
+ ```sh
44
+ cp -r dist <path/to/_extensions>
45
+ ```
46
+
47
+ 5. Run your Soul application:
48
+ ```sh
49
+ soul -d foobar.db --extensions /path/to/_extensions/
50
+ ```
51
+ 6. To verify that the app is working, open the following URL in your browser:
52
+ ```
53
+ http://localhost:<port>/api/client
54
+ ```
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "soul-cli",
3
- "version": "0.8.1",
3
+ "version": "0.8.2",
4
4
  "description": "A SQLite REST and Realtime server",
5
5
  "main": "src/server.js",
6
6
  "bin": {
@@ -163,18 +163,38 @@ const listTableRows = async (req, res, next) => {
163
163
  // if _ordering is provided, order rows by it
164
164
  // e.g. ?_ordering=name will order by name
165
165
  // e.g. ?_ordering=-name will order by name descending
166
+ // e.g. ?_ordering=publisher.name will order by publisher name, considering that publisher is a foreign key to publishers table
166
167
  let orderString = '';
168
+ let extendString = '';
169
+ let joins = {};
170
+
167
171
  if (_ordering) {
168
- orderString += ` ORDER BY ${_ordering.replace('-', '')} ${
169
- _ordering.startsWith('-') ? 'DESC' : 'ASC'
170
- }`;
172
+ const isDesc = _ordering.startsWith('-');
173
+ const cleanOrder = _ordering.replace('-', '');
174
+
175
+ if (cleanOrder.includes('.')) {
176
+ // Handle foreign key sort, e.g. publisher.name
177
+ const [relation, field] = cleanOrder.split('.');
178
+
179
+ const { foreignKey, joinedTableName, joinedTableFields } =
180
+ rowService.getForeignKeyInfo(tableName, relation);
181
+
182
+ extendString += ` LEFT JOIN ${joinedTableName} ON ${joinedTableName}.${foreignKey.to} = ${tableName}.${relation}`;
183
+ joins[relation] = { foreignKey, joinedTableName, joinedTableFields };
184
+ orderString += ` ORDER BY ${joinedTableName}.${field} ${
185
+ isDesc ? 'DESC' : 'ASC'
186
+ }`;
187
+ } else {
188
+ // regular field sort
189
+ orderString += ` ORDER BY ${cleanOrder} ${isDesc ? 'DESC' : 'ASC'}`;
190
+ }
191
+
171
192
  params += `_ordering=${_ordering}&`;
172
193
  }
173
194
 
174
195
  // if _schema is provided, return only those fields
175
196
  // e.g. ?_schema=name,age will return only name and age fields
176
197
  // if _schema is not provided, return all fields
177
-
178
198
  let schemaString = '';
179
199
  if (_schema) {
180
200
  const schemaFields = _schema.split(',');
@@ -217,31 +237,27 @@ const listTableRows = async (req, res, next) => {
217
237
  // }
218
238
 
219
239
  let foreignKeyError = { error: '', message: '' };
220
- let extendString = '';
221
240
 
222
241
  if (_extend) {
223
242
  const extendFields = _extend.split(',');
224
243
  extendFields.forEach((extendedField) => {
225
244
  try {
226
- const foreignKey = db
227
- .prepare(`PRAGMA foreign_key_list(${tableName})`)
228
- .all()
229
- .find((fk) => fk.from === extendedField);
230
-
231
- if (!foreignKey) {
232
- throw new Error(
233
- `Foreign key not found for extended field '${extendedField}'`,
245
+ let foreignKey, joinedTableName, joinedTableFields;
246
+ if (joins[extendedField]) {
247
+ foreignKey = joins[extendedField].foreignKey;
248
+ joinedTableName = joins[extendedField].joinedTableName;
249
+ joinedTableFields = joins[extendedField].joinedTableFields;
250
+ } else {
251
+ const foreignKeyInfo = rowService.getForeignKeyInfo(
252
+ tableName,
253
+ extendedField,
234
254
  );
255
+ foreignKey = foreignKeyInfo.foreignKey;
256
+ joinedTableName = foreignKeyInfo.joinedTableName;
257
+ joinedTableFields = foreignKeyInfo.joinedTableFields;
258
+ extendString += ` LEFT JOIN ${joinedTableName} ON ${joinedTableName}.${foreignKey.to} = ${tableName}.${extendedField}`;
235
259
  }
236
260
 
237
- const { table: joinedTableName } = foreignKey;
238
-
239
- const joinedTableFields = db
240
- .prepare(`PRAGMA table_info(${joinedTableName})`)
241
- .all();
242
-
243
- extendString += ` LEFT JOIN ${joinedTableName} ON ${joinedTableName}.${foreignKey.to} = ${tableName}.${extendedField}`;
244
-
245
261
  // joined fields will be returned in a new object called {field}_data e.g. author_id_data
246
262
  const extendFieldsString =
247
263
  'json_object( ' +
@@ -77,6 +77,35 @@ describe('Rows Endpoints', () => {
77
77
  );
78
78
  });
79
79
 
80
+ it('GET /tables/:name/rows?_ordering:userId.firstName&_extend=userId: should return the rows ordered by the related table field', async () => {
81
+ const accessToken = await generateToken(
82
+ { username: 'John', isSuperuser: true },
83
+ config.tokenSecret,
84
+ '1H',
85
+ );
86
+
87
+ const params = {
88
+ _ordering: 'userId.firstName',
89
+ _extend: 'userId',
90
+ };
91
+ const query = queryString(params);
92
+ const res = await requestWithSupertest
93
+ .get(`/api/tables/posts/rows?${query}`)
94
+ .set('Cookie', [`accessToken=${accessToken}`]);
95
+
96
+ expect(res.status).toEqual(200);
97
+ expect(res.type).toEqual(expect.stringContaining('json'));
98
+ expect(res.body).toHaveProperty('data');
99
+ expect(res.body.data).toEqual(expect.any(Array));
100
+
101
+ const firstUserFirstName = res.body.data[1].userId_data.firstName;
102
+ const secondUserFirstName = res.body.data[2].userId_data.firstName;
103
+ const thirdUserFirstName = res.body.data[3].userId_data.firstName;
104
+
105
+ expect(firstUserFirstName <= secondUserFirstName).toBe(true);
106
+ expect(secondUserFirstName <= thirdUserFirstName).toBe(true);
107
+ });
108
+
80
109
  it('GET /tables/:name/rows: should return a null field', async () => {
81
110
  const accessToken = await generateToken(
82
111
  { username: 'John', isSuperuser: true },
@@ -268,8 +297,9 @@ describe('Rows Endpoints', () => {
268
297
  );
269
298
 
270
299
  const res = await requestWithSupertest
271
- .delete('/api/tables/users/rows/1')
300
+ .delete('/api/tables/posts/rows/1')
272
301
  .set('Cookie', [`accessToken=${accessToken}`]);
302
+
273
303
  expect(res.status).toEqual(200);
274
304
  expect(res.type).toEqual(expect.stringContaining('json'));
275
305
  });
@@ -5,7 +5,7 @@ const listTableRows = Joi.object({
5
5
  _page: Joi.number().integer().min(1).default(1),
6
6
  _limit: Joi.number().integer().min(1).default(10),
7
7
  _search: Joi.string(),
8
- _ordering: Joi.string().regex(/^[\w-]+$/),
8
+ _ordering: Joi.string().regex(/^[\w.-]+$/),
9
9
  _schema: Joi.string(),
10
10
  _extend: Joi.string(),
11
11
  _filters: Joi.string(),
@@ -94,5 +94,23 @@ module.exports = (db) => {
94
94
  const result = statement.run(...pks);
95
95
  return result;
96
96
  },
97
+
98
+ getForeignKeyInfo(tableName, field) {
99
+ const foreignKey = db
100
+ .prepare(`PRAGMA foreign_key_list(${tableName})`)
101
+ .all()
102
+ .find((fk) => fk.from === field);
103
+
104
+ if (!foreignKey) {
105
+ throw new Error(`Foreign key not found for field '${field}'`);
106
+ }
107
+
108
+ const joinedTableName = foreignKey.table;
109
+ const joinedTableFields = db
110
+ .prepare(`PRAGMA table_info(${joinedTableName})`)
111
+ .all();
112
+
113
+ return { foreignKey, joinedTableName, joinedTableFields };
114
+ },
97
115
  };
98
116
  };
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "swagger": "2.0",
3
3
  "info": {
4
- "version": "0.8.0",
4
+ "version": "0.8.1",
5
5
  "title": "Soul API",
6
6
  "description": "API Documentation for <b>Soul</b>, a SQLite REST and realtime server. "
7
7
  },
@@ -1,11 +1,18 @@
1
- const { createTestTable, insertIntoTestTable } = require('.');
1
+ const {
2
+ createTestTable,
3
+ insertIntoTestTable,
4
+ createTestRelatedTable,
5
+ insertIntoTestRelatedTable,
6
+ } = require('.');
2
7
 
3
8
  const setup = () => {
4
9
  console.log('Test suite started');
5
10
  console.log('Creating test table...');
6
11
  createTestTable();
12
+ createTestRelatedTable();
7
13
  console.log('Inserting a row into test table...');
8
14
  insertIntoTestTable();
15
+ insertIntoTestRelatedTable();
9
16
  };
10
17
 
11
18
  module.exports = setup;
@@ -30,6 +30,12 @@ const createTestTable = (table = 'users') => {
30
30
  ).run();
31
31
  };
32
32
 
33
+ const createTestRelatedTable = (table = 'posts') => {
34
+ db.prepare(
35
+ `CREATE TABLE ${table} (id INTEGER PRIMARY KEY, userId INTEGER, title TEXT, content TEXT, createdAt TEXT, FOREIGN KEY(userId) REFERENCES users(id))`,
36
+ ).run();
37
+ };
38
+
33
39
  const insertIntoTestTable = (table = 'users') => {
34
40
  const statement = db.prepare(
35
41
  `INSERT INTO ${table} (firstName, lastName, createdAt) VALUES (?, ?, ?)`,
@@ -40,9 +46,26 @@ const insertIntoTestTable = (table = 'users') => {
40
46
  }
41
47
  };
42
48
 
49
+ const insertIntoTestRelatedTable = (table = 'posts') => {
50
+ const statement = db.prepare(
51
+ `INSERT INTO ${table} (userId, title, content, createdAt) VALUES (?, ?, ?, ?)`,
52
+ );
53
+
54
+ for (let i = 1; i <= testNames.length; i++) {
55
+ statement.run(
56
+ '' + i,
57
+ `Post Title ${i}`,
58
+ `This is the content of post ${i}.`,
59
+ new Date().toISOString(),
60
+ );
61
+ }
62
+ };
63
+
43
64
  module.exports = {
44
65
  dropTestTable,
45
66
  dropTestDatabase,
46
67
  createTestTable,
68
+ createTestRelatedTable,
47
69
  insertIntoTestTable,
70
+ insertIntoTestRelatedTable,
48
71
  };