monstrous - npm Package Compare versions

Comparing version 0.2.0 to 0.3.0

CHANGELOG.md

@@ -5,2 +5,10 @@ # Changelog
 
+## [0.3.0](https://gitlab.com/monstrous/monstrous/compare/v0.2.0...v0.3.0) (2023-07-16)
+
+
+### Features
+
+* db.query() raw sql ([0a8a991](https://gitlab.com/monstrous/monstrous/commit/0a8a991ca1dd9ede653c0a2ed90329f1cc46236a))
+* inline ordinal arguments for exprs, fluent method for options ([3075db4](https://gitlab.com/monstrous/monstrous/commit/3075db4e205f4fde25e6a26b137d4d15b225ac78))
+
 ## [0.2.0](https://gitlab.com/monstrous/monstrous/compare/v0.1.6...v0.2.0) (2023-07-15)
@@ -7,0 +15,0 @@

lib/database/connection.js

@@ -30,3 +30,18 @@ import pgp from 'pg-promise';
     this.instance = instance;
-    this.query = this.instance.query;
+    this.query = function () {
+      const args = [...arguments];
+
+      const sql = args.shift();
+      let target = this.instance.query;
+
+      if (typeof args[args.length - 1] === 'function') {
+        target = args.pop();
+      }
+
+      if (args.length === 1 && Object.prototype.toString.call(args[0]) === '[object Object]') {
+        return target(sql, args[0]);
+      }
+
+      return target(sql, args);
+    }
   }
@@ -149,3 +164,3 @@
     } else {
-      target = this.query;
+      target = this.instance.query;
     }
@@ -152,0 +167,0 @@

lib/database/index.js

@@ -41,2 +41,3 @@ import * as url from 'url';
     // forward the query-running methods from Connection
+    this.query = this.#connection.query.bind(this.#connection);
     this.task = this.#connection.task.bind(this.#connection);
@@ -43,0 +44,0 @@ this.transaction = this.#connection.transaction.bind(this.#connection);

lib/statement/expr.js

@@ -6,6 +6,10 @@ import pgp from 'pg-promise';
 
-  constructor (sql, params, options = {}) {
+  constructor (sql, ...params) {
     this.sql = sql;
-    this.params = params || [];
-    this.options = options;
+
+    if (params.length === 1 && Object.prototype.toString.call(params[0]) === '[object Object]') {
+      this.params = params[0];
+    } else {
+      this.params = params;
+    }
   }
@@ -23,4 +27,10 @@
 
+  options(format_options) {
+    this.format_options = format_options;
+
+    return this;
+  }
+
   compile() {
-    return pgp.as.format(this.sql, this.params, this.options);
+    return pgp.as.format(this.sql, this.params, this.format_options || {});
   }
@@ -41,2 +51,4 @@ }
   compile(raw) {
+    // tuples only use ordinal parameters since the SQL is constructed entirely
+    // behind monstrous' api surface
     const placeholders = this.params.map((p, idx) => {
@@ -59,3 +71,3 @@ if (p instanceof Expr) return `$${idx + 1}:raw`;
         }),
-        this.options
+        this.format_options || {}
       )
@@ -62,0 +74,0 @@ };

package.json

 {
   "name": "monstrous",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "a lightweight SQL composer for Node.js and PostgreSQL",
@@ -5,0 +5,0 @@ "main": "index.js",

README.md

@@ -5,2 +5,3 @@ # monstrous
 
+[![npm](https://img.shields.io/npm/v/monstrous)](https://npmjs.com/package/monstrous)
 [![Coverage Status](https://coveralls.io/repos/gitlab/monstrous/monstrous/badge.svg?branch=main)](https://coveralls.io/gitlab/monstrous/monstrous?branch=main)
@@ -125,8 +126,28 @@
 
-Exprs interpolate SQL text into the final query. They're a thin layer over [pg-promise's custom type formatting](https://vitaly-t.github.io/pg-promise/formatting.html#.format) and accept the SQL, an array of indexed or an object of named parameters, and options. Both latter arguments are optional.
+`db.query` runs raw SQL statements. Ordinal arguments may be passed inline, or a map of [named parameters](https://github.com/vitaly-t/pg-promise#named-parameters). A [query target](#query-targets) may be passed as the final argument to specify results handling.
 
 ```javascript
+await db.query(
+  `select * from books where author_id = $1`,
+  3
+);
+
+await db.query(
+  `select * from books where author_id = $(author_id) and title ilike $(title)`,
+  {
+    author_id: 3,
+    title: 'the placeholder'
+  },
+  db.$target.one
+);
+```
+
+### exprs and tuples
+
+Exprs interpolate SQL text into a constructed query. They're a thin layer over [pg-promise's custom type formatting](https://vitaly-t.github.io/pg-promise/formatting.html#.format) and accept the SQL with an optional array of indexed or map of named parameters.
+
+```javascript
 db.expr(
   `extract(years from justify_interval($1 - ${db.employees.$hired_on}))`,
-  [new Date()]
+  new Date() // argument $1
 ).as('tenure') // alias only required in projection!
@@ -141,2 +162,4 @@ ```
 
+Exprs can be assigned [pg-promise formatting options](http://vitaly-t.github.io/pg-promise/formatting.html#.format) via `db.expr(...).options({capSQL: true})`
+
 Tuples are a subclass of Expr which represent composite types or records. These do not include an SQL snippet, instead transforming their arguments -- which can include other exprs in order to reference columns in the query -- into record values.
@@ -185,3 +208,3 @@
 
-### projection
+## projection
 
@@ -260,3 +283,3 @@ `statement.project()` defines the shape of your query output, articulating nested collections and objects. It unifies Massive's resultset decomposition (aka join definitions) and the `fields` and `exprs` options.
 
-### ordering
+## ordering
 
@@ -276,6 +299,8 @@ ```javascript
 
-### json
+## json
 
-Postgres supports JSON traversal either through subscripting(`json_field['alpha']['beta']`) or custom operators (`json_field ->> 'alpha'` or `json_field #>> '{alpha,beta}'`). monstrous supports both methods in filter criteria keys. Returning elements of JSON fields can be done with exprs.
+Postgres supports JSON traversal either through subscripting(`json_field['alpha']['beta']`) or custom operators (`json_field ->> 'alpha'` or `json_field #>> '{alpha,beta}'`). monstrous supports both methods in filter criteria keys.
 
+Projecting elements of JSON fields can be accomplished with exprs.
+
 ## persistence
@@ -366,5 +391,6 @@
 ```javascript
-// QueryFile with ordinal ($1 style) parameters
+// QueryFile (sql/collections/purge.sql) or database function with ordinal ($1
+// style) parameters
 await db.execute(
-  db.collections.purge, // sql/collections/purge.sql
+  db.collections.purge,
   1,
@@ -376,5 +402,5 @@ 123,
 
-// QueryFile with named parameter object
+// QueryFile (sql/collections/purge.sql) with named parameter object
 await db.execute(
-  db.collections.purge, // sql/collections/purge.sql
+  db.collections.purge,
   {
@@ -387,11 +413,2 @@ library_id: 1,
 );
-
-// database functions only take ordinal parameters
-await db.execute(
-  db.collections.purge,
-  1,
-  123,
-  'have 5 copies in better condition',
-  db.$target.one
-)
 ```
@@ -398,0 +415,0 @@

No alert changes

Improved metrics

Total package byte prevSize

90513

increased by2.05%

Lines of code

1820

increased by1.17%

Number of lines in readme file

501

increased by3.51%

No dependency changes