mythix-orm-postgresql 1.10.1 → 1.11.1

package/.biblorc.js

@@ -0,0 +1,30 @@
+'use strict';
+
+/* global __dirname */
+
+const Path = require('path');
+
+module.exports = {
+  rootDir:    __dirname,
+  inputDir:   Path.resolve(__dirname),
+  outputDir:  Path.resolve(__dirname, '..', 'mythix-orm-postgresql.wiki'),
+  files: [
+    {
+      include:  /\/lib\/.*\.js$/,
+      parser:   'typescript',
+      compiler: 'typescript',
+    },
+    {
+      include:  /\/docs\/.*\.md$/,
+      parser:   'markdown',
+      compiler: 'markdown',
+    },
+  ],
+  exclude: [
+    /node_modules|\/spec\//
+  ],
+  generatorOptions: {
+    repositoryURL:  'https://github.com/th317erd/mythix-orm-postgresql',
+    baseURL:        './',
+  },
+};

package/README.md

@@ -1,5 +1,58 @@
 # mythix-orm-postgresql
 
-PostgreSQL driver for Mythix ORM
+SQLite database driver for [Mythix ORM](https://www.npmjs.com/package/mythix-orm).
 
-Mythix ORM aims to replace Sequelize and the few other terrible solutions that the poor destitute Node community has to work with. Mythix ORM is not yet quite ready for prime time however, so please check back soon!
+## Install
+
+```bash
+npm i --save mythix-orm-postgresql
+```
+
+## Documentation
+
+Documentation can be found at the [WIKI](https://github.com/th317erd/mythix-orm-postgresql/wiki).
+
+Documentation for Mythix ORM can be found at the [Mythix ORM WIKI](https://github.com/th317erd/mythix-orm/wiki).
+
+## Usage
+
+```javascript
+const { PostgreSQLConnection } = require('mythix-orm-postgresql');
+
+(async function() {
+  let connection = new PostgreSQLConnection({
+    bindModels: true,
+    models:     [ /* application models */ ],
+    logger:     console,
+    user:       'database-username',
+    password:   'database-password',
+    database:   'test-database',
+    host:       '127.0.0.1',
+    port:       5432,
+  });
+
+  await connection.start();
+
+  // run application code
+
+  await connection.stop();
+})();
+```
+
+## Connection Options
+
+| Option | Type | Default Value | Description |
+| ------ | ---- | ------------- | ----------- |
+| `bindModels` | `boolean` | `true` | Bind the models provided to this connection (see the Mythix ORM [Connection Binding](https://github.com/th317erd/mythix-orm/wiki/ConnectionBinding) article for more information). |
+| `connectionTimeout` | `number` | `60000` | Number of milliseconds to wait for connection. |
+| `host` | `string` | `undefined` | The domain/host used to connect to the database. |
+| `idleTransactionTimeout` | `number` | `undefined` | Number of milliseconds before terminating any session with an open idle transaction. |
+| `logger` | Logger Interface | `undefined` | Assign a logger to the connection. If a logger is assigned, then every query (and every error) will be logged using this logger. |
+| `maxPoolConnections` | `number` | `10` | Maximum number of clients the connection pool should contain. |
+| `models` | `Array<Model>` | `undefined` | Models to register with the connection (these models will be bound to the connection if the `boundModels` option is `true`).
+| `password` | `string` | `undefined` | The password used to connect to the database. |
+| `port` | `string` | `5432` | The port used to connect to the database. |
+| `queryGenerator` | [QueryGenerator](https://github.com/th317erd/mythix-orm/wiki/QueryGeneratorBase) | <see>PostgreSQLQueryGenerator</see> | Provide an alternate `QueryGenerator` interface for generating SQL statements for SQLite. This is not usually needed, as the `SQLiteConnection` itself will provide its own generator interface. However, if you want to customize the default query generator, or want to provide your own, you can do so using this option. |
+| `queryTimeout` | `number` | `15000` | Number of milliseconds before a query call will timeout. |
+| `statementTimeout` | `number` | `15000` | Number of milliseconds before a statement in query will time out. |
+| `user` | `string` | `undefined` | The username used to connect to the database. |

package/docs/Home.md

@@ -0,0 +1,54 @@
+SQLite database driver for [Mythix ORM](https://www.npmjs.com/package/mythix-orm).
+
+## Install
+
+```bash
+npm i --save mythix-orm-postgresql
+```
+
+## Documentation
+
+Documentation for Mythix ORM can be found at the [Mythix ORM WIKI](https://github.com/th317erd/mythix-orm/wiki).
+
+## Usage
+
+```javascript
+const { PostgreSQLConnection } = require('mythix-orm-postgresql');
+
+(async function() {
+  let connection = new PostgreSQLConnection({
+    bindModels: true,
+    models:     [ /* application models */ ],
+    logger:     console,
+    user:       'database-username',
+    password:   'database-password',
+    database:   'test-database',
+    host:       '127.0.0.1',
+    port:       5432,
+  });
+
+  await connection.start();
+
+  // run application code
+
+  await connection.stop();
+})();
+```
+
+## Connection Options
+
+| Option | Type | Default Value | Description |
+| ------ | ---- | ------------- | ----------- |
+| `bindModels` | `boolean` | `true` | Bind the models provided to this connection (see the Mythix ORM [Connection Binding](https://github.com/th317erd/mythix-orm/wiki/ConnectionBinding) article for more information). |
+| `connectionTimeout` | `number` | `60000` | Number of milliseconds to wait for connection. |
+| `host` | `string` | `undefined` | The domain/host used to connect to the database. |
+| `idleTransactionTimeout` | `number` | `undefined` | Number of milliseconds before terminating any session with an open idle transaction. |
+| `logger` | Logger Interface | `undefined` | Assign a logger to the connection. If a logger is assigned, then every query (and every error) will be logged using this logger. |
+| `maxPoolConnections` | `number` | `10` | Maximum number of clients the connection pool should contain. |
+| `models` | `Array<Model>` | `undefined` | Models to register with the connection (these models will be bound to the connection if the `boundModels` option is `true`).
+| `password` | `string` | `undefined` | The password used to connect to the database. |
+| `port` | `string` | `5432` | The port used to connect to the database. |
+| `queryGenerator` | [QueryGenerator](https://github.com/th317erd/mythix-orm/wiki/QueryGeneratorBase) | <see>PostgreSQLQueryGenerator</see> | Provide an alternate `QueryGenerator` interface for generating SQL statements for SQLite. This is not usually needed, as the `SQLiteConnection` itself will provide its own generator interface. However, if you want to customize the default query generator, or want to provide your own, you can do so using this option. |
+| `queryTimeout` | `number` | `15000` | Number of milliseconds before a query call will timeout. |
+| `statementTimeout` | `number` | `15000` | Number of milliseconds before a statement in query will time out. |
+| `user` | `string` | `undefined` | The username used to connect to the database. |

package/lib/postgresql-connection.js

@@ -19,11 +19,40 @@ function sleep(ms) {
   });
 }
 
+/// Mythix ORM connection driver for PostgreSQL.
+///
+/// This inherits from [SQLConnectionBase](https://github.com/th317erd/mythix-orm-sql-base/wiki)
+/// and so gets most of its SQL functionality from its parent class.
+///
+/// Extends: [SQLConnectionBase](https://github.com/th317erd/mythix-orm-sql-base/wiki)
 class PostgreSQLConnection extends SQLConnectionBase {
   static dialect = 'postgresql';
 
   static DefaultQueryGenerator = PostgreSQLQueryGenerator;
 
+  /// Create a new `PostgreSQLConnection` instance.
+  ///
+  /// Arguments:
+  ///   options?: object
+  ///     Options to provide to the connection. All options are optional, though `models`
+  ///     is required before the connection is used. If not provided here to the constructor,
+  ///     the application models can always be provided at a later time using the
+  ///     [Connection.registerModels](https://github.com/th317erd/mythix-orm/wiki/ConnectionBase#method-registerModels) method.
+  ///     | Option | Type | Default Value | Description |
+  ///     | ------ | ---- | ------------- | ----------- |
+  ///     | `bindModels` | `boolean` | `true` | Bind the models provided to this connection (see the Mythix ORM [Connection Binding](https://github.com/th317erd/mythix-orm/wiki/ConnectionBinding) article for more information). |
+  ///     | `connectionTimeout` | `number` | `60000` | Number of milliseconds to wait for connection. |
+  ///     | `host` | `string` | `undefined` | The domain/host used to connect to the database. |
+  ///     | `idleTransactionTimeout` | `number` | `undefined` | Number of milliseconds before terminating any session with an open idle transaction. |
+  ///     | `logger` | Logger Interface | `undefined` | Assign a logger to the connection. If a logger is assigned, then every query (and every error) will be logged using this logger. |
+  ///     | `maxPoolConnections` | `number` | `10` | Maximum number of clients the connection pool should contain. |
+  ///     | `models` | `Array<Model>` | `undefined` | Models to register with the connection (these models will be bound to the connection if the `boundModels` option is `true`).
+  ///     | `password` | `string` | `undefined` | The password used to connect to the database. |
+  ///     | `port` | `string` | `5432` | The port used to connect to the database. |
+  ///     | `queryGenerator` | [QueryGenerator](https://github.com/th317erd/mythix-orm/wiki/QueryGeneratorBase) | <see>PostgreSQLQueryGenerator</see> | Provide an alternate `QueryGenerator` interface for generating SQL statements for PostgreSQL. This is not usually needed, as the `PostgreSQLConnection` itself will provide its own generator interface. However, if you want to customize the default query generator, or want to provide your own, you can do so using this option. |
+  ///     | `queryTimeout` | `number` | `15000` | Number of milliseconds before a query call will timeout. |
+  ///     | `statementTimeout` | `number` | `15000` | Number of milliseconds before a statement in query will time out. |
+  ///     | `user` | `string` | `undefined` | The username used to connect to the database. |
   constructor(_options) {
     super(_options);
 
@@ -152,14 +181,35 @@ class PostgreSQLConnection extends SQLConnectionBase {
 
   // eslint-disable-next-line no-unused-vars
   async enableForeignKeyConstraints(enable) {
-    // Not supported in PostgreSQL
-    return;
+    throw new Error(`${this.constructor.name}::enableForeignKeyConstraints: This operation is not supported for this connection type.`);
   }
 
   async exec(...args) {
     return await this.query(...args);
   }
 
+  /// A raw query interface for the PostgreSQL database.
+  ///
+  /// This method is used internally to execute all
+  /// SQL statements generated against PostgreSQL. For
+  /// `SELECT` or `RETURNING` SQL statements, this will
+  /// return the results in a formatted object: `{ rows: [ ... ], columns: [ ... ] }`.
+  ///
+  /// Arguments:
+  ///   sql: string
+  ///     The fully formed SQL statement to execute.
+  ///   options?: object
+  ///     Options for the operation.
+  ///     | Option | Type | Default Value | Description |
+  ///     | ------ | ---- | ------------- | ----------- |
+  ///     | `logger` | Logger Interface | `undefined` | If provided, then the query and any errors encountered will be logged |
+  ///     | `logResponse` | `boolean` | `false` | If `true`, then the response from PostgreSQL will be logged |
+  ///     | `parameters` | `Array` or `Object` | `undefined` | Parameters to bind for [pg](https://node-postgres.com/features/queries) |
+  ///
+  /// Return: any
+  ///   A `{ rows: [ ... ], columns: [ ... ] }` object if the statement is a
+  ///   `SELECT` statement, or a statement with a `RETURNING` clause. Otherwise
+  ///   the raw result from PostgreSQL will be returned for the statement executed.
   async query(_sql, _options, _client) {
     let sql = _sql;
     if (!sql)
@@ -218,7 +268,20 @@ class PostgreSQLConnection extends SQLConnectionBase {
     }
   }
 
-  formatResultsResponse(sqlStatement, result) {
+  /// Format the response from PostgreSQL for a `SELECT`
+  /// or `RETURNING` statement.
+  ///
+  /// Arguments:
+  ///   sql: string
+  ///     The SQL statement that was executed.
+  ///   result: any
+  ///     The response from PostgreSQL.
+  ///
+  /// Return: { rows: Array<any>, columns: Array<string> }
+  ///   The formatted response, containing all the rows returned by the query, and all
+  ///   projected columns. The columns are converted to names only, so as to keep the
+  ///   query interface consistent across all database drivers Mythix ORM supports.
+  formatResultsResponse(sql, result) {
     if (!result.rows || !result.fields)
       return result;
 
@@ -228,6 +291,34 @@ class PostgreSQLConnection extends SQLConnectionBase {
     };
   }
 
+  /// This method will start a transaction, or, if a transaction
+  /// is already active, will instead start a `SAVEPOINT`.
+  ///
+  /// If an error is thrown in the provided `callback`, then the
+  /// transaction or `SAVEPOINT` will be automatically rolled back.
+  /// If the `callback` provided returns successfully, then the
+  /// transaction will be committed automatically for you.
+  ///
+  /// Arguments:
+  ///   callback: (connection: PostgreSQLConnection) => any
+  ///     The transaction connection is passed to this callback as soon as
+  ///     the transaction or `SAVEPOINT` is started. This often isn't needed
+  ///     if the global [AsyncLocalStorage](https://github.com/th317erd/mythix-orm/wiki/AsyncStore) context is supported and in-use
+  ///     (the default). If the [AsyncLocalStorage](https://github.com/th317erd/mythix-orm/wiki/AsyncStore) context is not in-use,
+  ///     then this `connection` **must** be passed all the way through all
+  ///     database calls made inside this callback.
+  ///   options?: object
+  ///     Options for the transaction operation. This includes the options listed below, as well as any
+  ///     options that can be passed to <see>PostgreSQLConnection.query</see>. The `lock` options object has
+  ///     one PostgreSQL specific sub-option named `mode`, that can be one of `ACCESS EXCLUSIVE` (the default),
+  ///     `EXCLUSIVE`, or `ACCESS SHARE`. To understand what these do, refer to the [PostgreSQL documentation](https://www.postgresql.org/docs/15/sql-begin.html).
+  ///     | Option | Type | Default Value | Description |
+  ///     | ------ | ---- | ------------- | ----------- |
+  ///     | `connection` | `PostgreSQLConnection` | `undefined` | The connection to use for the operation. This is generally only needed if you are already inside a transaction, and need to supply the transaction connection to start a sub-transaction (a `SAVEPOINT`). |
+  ///     | `lock | [Lock Mode](https://github.com/th317erd/mythix-orm/wiki/ConnectionBase#method-getLockMode) | `undefined` | Specify the lock mode for the transaction. See [ConnectionBase.getLockMode](https://github.com/th317erd/mythix-orm/wiki/ConnectionBase#method-getLockMode) for more information. |
+  ///
+  /// Return: any
+  ///   Return the result of the provided `callback`.
   async transaction(callback, _options, _retryCount) {
     let options       = _options || {};
     let inheritedThis = Object.create(options.connection || this.getContextValue('connection', this));

package/lib/postgresql-query-generator.js

@@ -6,13 +6,25 @@ const { SQLQueryGeneratorBase } = require('mythix-orm-sql-base');
 
 const LiteralBase = Literals.LiteralBase;
 
+/// The query generator interface for PostgreSQL.
+///
+/// See [SQLQueryGeneratorBase](https://github.com/th317erd/mythix-orm-sql-base/wiki/SQLQueryGeneratorBase)
+/// for a better understanding of this class. This modifies some of
+/// the methods provided by [SQLQueryGeneratorBase](https://github.com/th317erd/mythix-orm-sql-base/wiki/SQLQueryGeneratorBase)
+/// for PostgreSQL specific syntax.
+///
+/// Extends: [SQLQueryGeneratorBase](https://github.com/th317erd/mythix-orm-sql-base/wiki/SQLQueryGeneratorBase)
 class PostgreSQLQueryGenerator extends SQLQueryGeneratorBase {
   // eslint-disable-next-line no-unused-vars
   generateSQLJoinTypeFromQueryEngineJoinType(joinType, outer, options) {
     if (!joinType || joinType === 'inner')
       return 'INNER JOIN';
     else if (joinType === 'left')
-      return 'LEFT JOIN';
+      return (outer) ? 'LEFT OUTER JOIN' : 'LEFT JOIN';
+    else if (joinType === 'right')
+      return (outer) ? 'RIGHT OUTER JOIN' : 'RIGHT JOIN';
+    else if (joinType === 'full')
+      return (outer) ? 'FULL OUTER JOIN' : 'FULL JOIN';
     else if (joinType === 'cross')
       return 'CROSS JOIN';
 
@@ -89,6 +101,18 @@ class PostgreSQLQueryGenerator extends SQLQueryGeneratorBase {
     return super.generateColumnDeclarationStatement(Model, field, { ...options, noAutoIncrementDefault: true });
   }
 
+  /// Generate a `TRUNCATE TABLE` statement.
+  ///
+  /// Arguments:
+  ///   Model: class [Model](https://github.com/th317erd/mythix-orm/wiki/Model)
+  ///     The model that defines the table to truncate.
+  ///   options?: object
+  ///     Operation specific options.
+  ///     | Option | Type | Default Value | Description |
+  ///     | ------ | ---- | ------------- | ----------- |
+  ///     | `cascade` | `boolean` | `true` | If `true`, then automatically truncate all tables that have foreign-key references to any of the named tables, or to any tables added to the group due to `CASCADE`. |
+  ///     | `continueIdentity` | `boolean` | `false` | If `true`, then auto-incrementing ids will not be reset. |
+  ///     | `onlySpecifiedTable` | `boolean` | `false` | If `true`, then only truncate this table. If `false` (the default), then all descendant tables (if any) are truncated as well. |
   generateTruncateTableStatement(Model, _options) {
     let options           = _options || {};
     let escapedTableName  = this.escapeID(Model.getTableName(this.connection));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mythix-orm-postgresql",
-  "version": "1.10.1",
+  "version": "1.11.1",
   "description": "PostgreSQL driver for Mythix ORM",
   "main": "lib/index.js",
   "type": "commonjs",
@@ -33,8 +33,8 @@
   },
   "homepage": "https://github.com/th317erd/mythix-orm-postgresql#readme",
   "peerDependencies": {
-    "mythix-orm": "^1.12.0",
-    "mythix-orm-sql-base": "^1.10.1"
+    "mythix-orm": "^1.13.1",
+    "mythix-orm-sql-base": "^1.11.0"
   },
   "dependencies": {
     "luxon": "^3.1.0",