All globalOptions plus option to change table name
define columns according to following object structure
Validation function for user input validation
string | The name of the modal and table |
| options | [modalOptions](#modalOptions) | Modal customization options |
**Example**
```js
const PgormModel = require('pg-models');
const Users = new PgormModel('users');
```
### pgormModel.tableName
gets or sets the table name (with prefix)
**Kind**: instance property of [PgormModel](#PgormModel)
### pgormModel.define(columns, options)
Creates new table for the model with given configurations. Alters the table if already exists according to the given configurations.
**Kind**: instance method of [PgormModel](#PgormModel)
| Param | Type | Description |
| --- | --- | --- |
| columns | [columnsObj](#columnsObj) | Table columns with configurations |
| options | object | Options to modify the behaviour of PgormModel |
**Example**
```js
Users.define({
fullname: {
schema: 'fullname TEXT NOT NULL',
validations: [
function (input, colName) {
if (typeof input !== "string") throw new Error(colName + ' must be a string')
},
function (input, colName) {
if (input.length < 5) throw new Error(colName + ' can not be less than 5 char')
},
]
},
age: {
schema: 'age INT',
validations: [
function (input) {
if (typeof input !== "number") throw new Error('age must be a number')
}
]
},
about: {
schema: 'about TEXT'
},
});
```
### pgormModel.findAll(options) ⇒
Gets all the results in the model
**Kind**: instance method of [PgormModel](#PgormModel)
**Returns**: Array of results or an empty array
| Param | Type | Description |
| --- | --- | --- |
| options | Object | Options to configure the query |
**Example**
```js
const users = await Users.findAll();
```
### pgormModel.findAllWhere(whereClause, paramsArray) ⇒
Gets all the results in the model, matching whereClause
**Kind**: instance method of [PgormModel](#PgormModel)
**Returns**: Array of results or an emtpy array
| Param | Type | Description |
| --- | --- | --- |
| whereClause | String | SQL query starting with 'WHERE' |
| paramsArray | Array | Array of values for the query placeholders |
**Example**
```js
const users = await Users.findAllWhere('WHERE age>=$1', [20]);
```
### pgormModel.findOne(column, value) ⇒
Gets the one matching result
**Kind**: instance method of [PgormModel](#PgormModel)
**Returns**: Object or null
| Param | Type | Description |
| --- | --- | --- |
| column | String | Name of the column to search |
| value | String | Value for the column to match |
**Example**
```js
const user = await Users.findOne('fullname', 'Ali Hassan');
```
### pgormModel.findById(id) ⇒
Gets the result from the model against the given id.
Return null if no result found.
**Kind**: instance method of [PgormModel](#PgormModel)
**Returns**: Object or null
| Param | Type | Description |
| --- | --- | --- |
| id | Number | Id of the result |
**Example**
```js
const user = await Users.findById(12);
```
### pgormModel.updateById(id, values) ⇒
Updates the record by given id
**Kind**: instance method of [PgormModel](#PgormModel)
**Returns**: Updated record or null
| Param | Type | Description |
| --- | --- | --- |
| id | Number | Id of the record to be updated |
| values | Object | New values for the record |
**Example**
```js
const updatedUser = await Users.updateById(12,{fullname: 'Ali Hussain', age: 23});
if(updatedUsers){
// user updated do something with updatedUser...
} else {
// user not found with that id...
}
```
### pgormModel.create(values) ⇒
Creates new record
**Kind**: instance method of [PgormModel](#PgormModel)
**Returns**: Created record or null
| Param | Type | Description |
| --- | --- | --- |
| values | Object | Values for the new record |
**Example**
```js
const user = await Users.create({fullname: 'Huzaifa Tayyab', age: 23});
```
### pgormModel.deleteById(id) ⇒
Deletes the record by given id
**Kind**: instance method of [PgormModel](#PgormModel)
**Returns**: boolean
| Param | Type | Description |
| --- | --- | --- |
| id | Number | Id of the record to be deleted |
**Example**
```js
const isUserDeleted = await Users.deleteById(12);
if(isUserDeleted){
// deleted
} else {
// user not found with that id
}
```
### pgormModel.beforeCreate(fn)
Registers a validator hook, which is called before every 'create' operation on this model.
Validator function must throw error on validation failure.
**Kind**: instance method of [PgormModel](#PgormModel)
| Param | Type | Description |
| --- | --- | --- |
| fn | function | A function to run before PgormModel.create(..) operation |
**Example**
```js
Users.beforeCreate(async (client, values)=>{
// await client.query(..)
// throws error on validation failure
})
```
### pgormModel.beforeUpdate(fn)
Registers a validator hook, which is called before every 'update' operation on this model.
Validator function must throw error on validation failure.
**Kind**: instance method of [PgormModel](#PgormModel)
| Param | Type | Description |
| --- | --- | --- |
| fn | function | A function to run before PgormModel.update(..) operation |
**Example**
```js
Users.beforeUpdate(async (client, recordId)=>{
// await client.query(..)
// throws error on validation failure
})
```
### pgormModel.beforeDestroy(fn)
Registers a validator hook, which is called before every 'delete' operation on this model.
Validator function must throw error on validation failure.
**Kind**: instance method of [PgormModel](#PgormModel)
| Param | Type | Description |
| --- | --- | --- |
| fn | function | A function to run before PgormModel.destory(..) operation |
**Example**
```js
Users.beforeDestroy(async (client, recordId)=>{
// await client.query(..)
// throws error on validation failure
})
```
### pgormModel.addQueryMethod(methodName, fn)
Creates new function on the model, that can be accessed by the model instance.
i.e `MyModel.customQueries.myCustomQueryMethod(..)`
**Kind**: instance method of [PgormModel](#PgormModel)
| Param | Type | Description |
| --- | --- | --- |
| methodName | String | The name for the function |
| fn | function | A callback which returns a query function to attach to the model, |
**Example**
```js
Users.addQueryMethod('getByQualification', (client)=>{
// here you define and return your query function
return async (qual_id) => {
// const { rows: usersByQual } = await client.query(..)
// return usersByQual
}
});
// in users controller
await Users.customQueries.getByQualification(1)
```
### pgormModel.addForeignKey(fkName, parentTableName)
Creates a foreign key. fkName must be present in the model
Throws error if the foreign key already exists or column is not defined in the model.
**Kind**: instance method of [PgormModel](#PgormModel)
| Param | Type | Description |
| --- | --- | --- |
| fkName | String | Name of the foreign key |
| parentTableName | String | The name of the parent table to which key is being linked |
**Example**
```js
const Books = new PgormModel('books', {
title: {
schema: 'title VARCHAR(255)',
},
user_id: {
schema: 'user_id INT',
},
});
// create a foreign key on user_id column
Books.addForeignKey('user_id', Users.tableName);
```
### PgormModel.useConnection(dbConnection)
**Kind**: static method of [PgormModel](#PgormModel)
| Param | Type | Description |
| --- | --- | --- |
| dbConnection | PG\_Client | The pg client object returned by `pg.connect()` |
**Example**
```js
PgormModel.useConnection(pgClient);
```
### PgormModel.setOptions(options)
Sets options for `PgormModel` class that will apply to all instances of this class.
Use this method if you want to customize all models once.
**Kind**: static method of [PgormModel](#PgormModel)
| Param | Type | Description |
| --- | --- | --- |
| options | [globalOptions](#globalOptions) | Configuration options. |
## globalOptions
**Kind**: global constant
**Properties**
| Name | Type | Description |
| --- | --- | --- |
| tablePrefix | string | Prefix for table name |
| tableSchema | string | Schema for table |
| pkName | string | Name of primary key of table |
| timestamps | boolean \| object | Whether to add timestamps or not, provide object to override default values |
| paranoid | boolean | Whether to soft delete or not |
| alter | boolean | Whether to alter table (on config change) or not |
| errorLogs | boolean | Whether to log errors or not |
**Example**
```js
// timestamps property can be boolean or object
timestamps: true
// or
timestamps: {
createdAt: 'created_at',
updatedAt: 'updated_at',
deletedAt: 'deleted_at',
}
```
## modalOptions
All globalOptions plus option to change table name
**Kind**: global constant
**Properties**
| Name | Type | Description |
| --- | --- | --- |
| string | tableName | Name of table for current model |
## columnsObj
define columns according to following object structure
**Kind**: global constant
**Properties**
| Name | Type | Description |
| --- | --- | --- |
| columnName | object | Name of the column |
| schema | string | Schema of the column |
| validations | Array | Array of validation functions |
**Example**
```js
const columnsObj = {
columnName: {
schema: 'columnName TEXT NOT NULL',
validations: [validatorFn],
},
// ...other columns
};
```
## validatorFn(val, col, values)
Validation function for user input validation
**Kind**: global function
| Param | Type | Description |
| --- | --- | --- |
| val | any | Value entered for current column |
| col | string | Name of current column |
| values | object | All user entered values |
---
_Source: https://npm.io/package/pg-models · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._