@hitchy/plugin-odem-rest 0.5.1 → 0.5.2

package/index.js

@@ -156,6 +156,7 @@ module.exports = function() {
 
 		// here comes the REST-compliant part
 		routes.set( "GET " + resolve( modelUrl ), reqBadModel || reqFetchItems );
+		routes.set( "QUERY " + resolve( modelUrl ), reqBadModel || reqFetchItems );
 		routes.set( "GET " + resolve( modelUrl, ":uuid" ), reqBadModel || reqFetchItem );
 
 		routes.set( "HEAD " + resolve( modelUrl, ":uuid" ), reqBadModel || reqCheckItem );
@@ -314,7 +315,13 @@ module.exports = function() {
 				return undefined;
 			}
 
-			return ( req.query.q ? reqListMatches : reqListAll ).call( this, req, res );
+			let handler = reqListAll;
+
+			if ( req.query.q || req.query.query || req.method === "QUERY" ) {
+				handler = reqListMatches;
+			}
+
+			return handler.call( this, req, res );
 		}
 
 		/**
@@ -356,30 +363,66 @@ module.exports = function() {
 		 * @param {Hitchy.Core.ServerResponse} res API for creating response
 		 * @returns {Promise|undefined} promises request processed successfully
 		 */
-		function reqListMatches( req, res ) {
+		async function reqListMatches( req, res ) {
 			logDebug( "got request listing matching items" );
 
 			if ( !Schema.mayBeExposed( req, Model ) ) {
 				res.status( 403 ).json( { error: "access forbidden by model" } );
-				return undefined;
+				return;
 			}
 
-			const { q: query = "", offset = 0, limit = Infinity, sortBy = null, descending = false, loadRecords = true, count = false } = req.query;
-
-			if ( !query ) {
+			const {
+				q: simpleQuery = "",
+				offset = 0,
+				limit = Infinity,
+				sortBy = null,
+				descending = false,
+				loadRecords = true,
+				count = false
+			} = req.query;
+			let parsedQuery;
+
+			if ( simpleQuery ) {
+				// support old-style simple queries with ?q=<query>
+				parsedQuery = parseQuery( simpleQuery );
+
+				if ( !parsedQuery ) {
+					res.status( 400 ).json( { error: "invalid query, e.g. use ?q=name:operation:value" } );
+					return;
+				}
+			} else if ( req.query.query ) {
+				// support JSON-encoded queries in URL with ?query=<json-query>
+				try {
+					parsedQuery = JSON.parse( req.query.query );
+				} catch ( cause ) {
+					res.status( 400 ).json( { error: 'invalid extended query, e.g. use ?query={"operation":{"name":value}}' } );
+					return;
+				}
+			} else if ( req.method === "QUERY" ) {
+				// support HTTP QUERY method (which is in draft state, currently)
+				const query = await req.fetchBody();
+
+				if ( typeof query === "string" ) {
+					try {
+						parsedQuery = JSON.parse( query );
+					} catch ( cause ) {
+						res.status( 400 ).json( { error: "invalid query in QUERY request payload" } );
+						return;
+					}
+				} else if ( query && typeof query === "object" && !Array.isArray( query ) ) {
+					parsedQuery = query;
+				} else {
+					res.status( 400 ).json( { error: "invalid query in QUERY request payload" } );
+					return;
+				}
+			} else {
 				res.status( 400 ).json( { error: "missing query" } );
-				return undefined;
-			}
-
-			const parsedQuery = parseQuery( query );
-			if ( !parsedQuery ) {
-				res.status( 400 ).json( { error: "invalid query, e.g. use ?q=name:operation:value" } );
-				return undefined;
+				return;
 			}
 
 			const meta = count || req.headers["x-count"] ? {} : null;
 
-			return Model.find( parsedQuery, { offset, limit, sortBy, sortAscendingly: !descending }, {
+			await Model.find( parsedQuery, { offset, limit, sortBy, sortAscendingly: !descending }, {
 				metaCollector: meta,
 				loadRecords
 			} )

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@hitchy/plugin-odem-rest",
-	"version": "0.5.1",
+	"version": "0.5.2",
 	"description": "HTTP REST API for Hitchy's ODM",
 	"main": "index.js",
 	"scripts": {
@@ -19,14 +19,14 @@
 	"homepage": "https://gitlab.com/hitchy/plugin-odem-rest#plugin-odem-rest",
 	"peerDependencies": {
 		"@hitchy/core": "^0.7.2",
-		"@hitchy/plugin-odem": "^0.7.1"
+		"@hitchy/plugin-odem": "^0.7.4"
 	},
 	"devDependencies": {
 		"@hitchy/server-dev-tools": "^0.4.3",
-		"c8": "^7.11.3",
-		"eslint": "^8.15.0",
+		"c8": "^7.12.0",
+		"eslint": "^8.24.0",
 		"eslint-config-cepharum": "^1.0.12",
-		"eslint-plugin-promise": "^6.0.0",
+		"eslint-plugin-promise": "^6.0.1",
 		"mocha": "^10.0.0",
 		"should": "^13.2.3",
 		"should-http": "^0.1.1"

package/{README.md → readme.md}

@@ -6,6 +6,9 @@ HTTP REST API for [Hitchy's](https://core.hitchy.org/) [ODM](https://odem.hitchy
  
 This plugin is defining blueprint routes for accessing data managed in ODM using REST API.
 
+## License
+
+[MIT](LICENSE)
 
 ## Installation
 
@@ -59,7 +62,7 @@ module.exports = {
 
 When starting your Hitchy-based application it will discover a model named **LocalEmployee** and expose it via REST API using URLs like `/api/local-employee` just because of this package and its dependencies mentioned before.
 
-#### Models of Hitchy Plugins
+#### Models of Hitchy plugins
 
 Due to the way Hitchy is discovering plugins and compiling [components](https://core.hitchy.org/internals/components.html) defined there, this plugin is always covering models defined in installed plugins as well. Thus, any plugin is capable of defining additional models to be supported. In addition, some plugin may extend models defined by another plugin.
 
@@ -90,18 +93,19 @@ In Hitchy's ODM all model instances or items are uniquely addressable via UUIDs.
 
 The provided routes implement these actions:
 
-| Method | URL | Action |
-|---|---|---|
-| GET | `/api/model` | Lists items of selected model. |
-| GET | `/api/model/<uuid>` | Fetches properties of selected item. |
-| PUT | `/api/model/<uuid>` | Replaces all properties of selected item with those given in request body. Selected item is created when missing. |
-| PATCH | `/api/model/<uuid>` | Adjusts selected item by replacing values of properties given in request body (leaving those missing in request body untouched). |
-| POST | `/api/model` | Creates new item initialized with properties provided in request body. |
-| DELETE | `/api/model/<uuid>`  | Removes selected item from model's collection. |
-| HEAD | `/api/model` | Tests if selected model exists. |
-| HEAD | `/api/model/<uuid>` | Tests if selected item exists. |
+| Method | URL | Action                                                                                                                                   |
+|---|---|------------------------------------------------------------------------------------------------------------------------------------------|
+| GET | `/api/model` | Lists items of selected model.                                                                                                           |
+| GET | `/api/model/<uuid>` | Fetches properties of selected item.                                                                                                     |
+| PUT | `/api/model/<uuid>` | Replaces all properties of selected item with those given in request body. Selected item is created when missing.                        |
+| PATCH | `/api/model/<uuid>` | Adjusts selected item by replacing values of properties given in request body (leaving those missing in request body untouched).         |
+| POST | `/api/model` | Creates new item initialized with properties provided in request body.                                                                   |
+| DELETE | `/api/model/<uuid>`  | Removes selected item from model's collection.                                                                                           |
+| HEAD | `/api/model` | Tests if selected model exists.                                                                                                          |
+| HEAD | `/api/model/<uuid>` | Tests if selected item exists.                                                                                                           |
+| QUERY | `/api/model` | Fetches items of model matching JSON-encoded query in request body.<br><br>_Not working unless Node.js is supporting [HTTP QUERY method](https://datatracker.ietf.org/doc/draft-ietf-httpbis-safe-method-w-body/?include_text=1)._ |
 
-In addition following URLs are available for accessing schema information:
+In addition, following URLs are available for accessing schema information:
 
 | Method | URL | Action |
 |---|---|---|
@@ -121,7 +125,7 @@ Response status code indicates basic result of either requests.
 | 405 | A given method isn't allowed on selected model or item. This is basically a more specific information related to performing some invalid request like trying to PATCH or DELETE a whole model instead of a single item. |
 
 
-### Convenience Routes
+### Convenience routes
 
 By default, the module is exposing another set of routes for every model that enables requesting either supported action using GET-requests. This is assumed to be very useful in development e.g. to conveniently add or remove items using regular browser.
 
@@ -139,7 +143,7 @@ There are no extra routes following this pattern for actions that are exposed vi
 
 All request data is provided in query parameters instead of request body for GET requests don't have a body.
 
-#### Disabling Feature
+#### Disabling feature
 
 Disable this feature in the configuration file **config/model.js**:
 
@@ -150,16 +154,16 @@ exports.model = {
 ``` 
 
 
-### Extended Fetching of Items
+### Extended fetching of items
 
 Whenever fetching a list of items using GET request on a model's URL there are additional options for controlling the retrieved list.
 
 
 #### Filtering
 
-Using query parameter `q` the list of fetched items can be limited to those items matching criteria given in that query parameter. The abbreviated name `q` just refers to a _search query_.
+Using query parameter `q` the list of fetched items can be limited to those items matching criteria given in that simple query. The abbreviated name `q` just refers to a _search query_.
 
-##### Simple Comparisons
+##### Simple comparisons
 
 The search query may comply with the pattern `name:operation:value` to compare every item's property with a given value using one of these operations:
   
@@ -174,7 +178,7 @@ The search query may comply with the pattern `name:operation:value` to compare e
 
 For example, a GET-request for `/api/localEmployee?q=lastName:eq:Doe` will deliver all items of model **LocalEmployee** with property **lastName** equal given value **Doe**. The value may contain further colons.
 
-##### Simple Unary Tests
+##### Unary tests
 
 Alternatively the search query may comply with the pattern `name:operation` for testing the named property using one of these supported operations:
   
@@ -185,7 +189,7 @@ Alternatively the search query may comply with the pattern `name:operation` for
 
 For example, a GET-request for `/api/localEmployee?q=lastName:null` will deliver all items of model **LocalEmployee** with unset property **lastName**.
 
-##### Simple Ternary Tests
+##### Ternary tests
 
 A third type of test operations are ternary tests. This refers to operations consisting of three parameters: the property's name and two values instead of one to compare that property's values with. Related queries comply with the pattern `name:operation:value:value`, hence using colon in first given value is not supported.
   
@@ -195,9 +199,26 @@ A third type of test operations are ternary tests. This refers to operations con
 
 For example, a GET-request for `/api/localEmployee?q=salary:between:2000:4000` will deliver all items of model **LocalEmployee** with value of property **salary** in range from 2000 to 4000.
 
-##### Complex Tests
+##### Complex tests <Bade type=info text=v0.5.2+></Badge>
 
-There will be more complex tests supported in future versions using different formats in query parameter `q`.
+Hitchy ODM supports more complex queries that can't be encoded as such simple queries as described above. Thus, a different way of querying has been added. 
+
+When using parameter `query` instead of `q`, its value is assumed to be a JSON-encoded query complying with query syntax supported by [Model.find() method of Hitchy ODM](https://odem.hitchy.org/api/model.html#model-find).
+
+```http request
+GET /api/user?query={"in":{"name":["john","jane","jason"]}}
+```
+
+_This example omits proper URL encoding of value to `query` parameter for illustration purposes. You should always encode queries._
+
+In addition, support for upcoming [HTTP QUERY method](https://datatracker.ietf.org/doc/draft-ietf-httpbis-safe-method-w-body/?include_text=1) has been prepared. However, this one does not work unless Node.js is accepting HTTP requests with method `QUERY`. 
+
+```http request
+QUERY /api/user
+Content-Type: application/json
+
+{"in":{"name":["john","jane","jason"]}}
+```
 
 
 #### Sorting