diff --git a/lib/formatting.js b/lib/formatting.js index 9db5acfd..09a5805a 100644 --- a/lib/formatting.js +++ b/lib/formatting.js @@ -376,14 +376,14 @@ const $as = { * Property name for the $[Custom Type Formatting] flag `rawType`. * * @example - * const ctf = pgp.as.ctf; // Custom Type Formatting symbols + * const {toPostgres, rawType} = pgp.as.ctf; // Custom Type Formatting symbols * * class MyType { * constructor() { - * this[ctf.rawType] = true; // set it only when toPostgres returns a pre-formatted result + * this[rawType] = true; // set it only when toPostgres returns a pre-formatted result * } * - * [ctf.toPostgres](self) { + * [toPostgres](self) { * // self = this * * // return the custom/actual value here diff --git a/lib/helpers/column-set.js b/lib/helpers/column-set.js index 258980ab..da1516b3 100644 --- a/lib/helpers/column-set.js +++ b/lib/helpers/column-set.js @@ -86,8 +86,9 @@ const npm = { * // 6. Property 'amount' needs to be set to 100, if it is 0 * // 7. Property 'total' must be skipped during updates, if 'amount' was 0, plus its * // column name is 'total-val' + * const {ColumnSet} = pgp.helpers; * - * const cs = new pgp.helpers.ColumnSet([ + * const cs = new ColumnSet([ * '?id', // ColumnConfig equivalent: {name: 'id', cnd: true} * 'list:csv', // ColumnConfig equivalent: {name: 'list', mod: ':csv'} * { diff --git a/lib/helpers/column.js b/lib/helpers/column.js index f966875b..b826ef87 100644 --- a/lib/helpers/column.js +++ b/lib/helpers/column.js @@ -91,7 +91,7 @@ const npm = { * capSQL: true // if you want all generated SQL capitalized * }); * - * const Column = pgp.helpers.Column; + * const {Column} = pgp.helpers; * * // creating a column from just a name: * const col1 = new Column('colName'); @@ -207,7 +207,7 @@ class Column extends InnerState { * * @example * - * const cs = new pgp.helpers.ColumnSet([ + * const cs = new ColumnSet([ * 'id', * 'coordinate:json', * { diff --git a/lib/helpers/methods/insert.js b/lib/helpers/methods/insert.js index 0a55e380..06f184cd 100644 --- a/lib/helpers/methods/insert.js +++ b/lib/helpers/methods/insert.js @@ -62,29 +62,32 @@ const npm = { * const pgp = require('pg-promise')({ * capSQL: true // if you want all generated SQL capitalized * }); + * const {insert} = pgp.helpers; * * const dataSingle = {val: 123, msg: 'hello'}; * const dataMulti = [{val: 123, msg: 'hello'}, {val: 456, msg: 'world!'}]; * * // Column details can be taken from the data object: * - * pgp.helpers.insert(dataSingle, null, 'my-table'); + * insert(dataSingle, null, 'my-table'); * //=> INSERT INTO "my-table"("val","msg") VALUES(123,'hello') * * @example * * // Column details are required for a multi-row `INSERT`: + * const {insert} = pgp.helpers; * - * pgp.helpers.insert(dataMulti, ['val', 'msg'], 'my-table'); + * insert(dataMulti, ['val', 'msg'], 'my-table'); * //=> INSERT INTO "my-table"("val","msg") VALUES(123,'hello'),(456,'world!') * * @example * * // Column details from a reusable ColumnSet (recommended for performance): + * const {ColumnSet, insert} = pgp.helpers; * - * const cs = new pgp.helpers.ColumnSet(['val', 'msg'], {table: 'my-table'}); + * const cs = new ColumnSet(['val', 'msg'], {table: 'my-table'}); * - * pgp.helpers.insert(dataMulti, cs); + * insert(dataMulti, cs); * //=> INSERT INTO "my-table"("val","msg") VALUES(123,'hello'),(456,'world!') * */ diff --git a/lib/helpers/methods/sets.js b/lib/helpers/methods/sets.js index da1039bf..0ddbdc41 100644 --- a/lib/helpers/methods/sets.js +++ b/lib/helpers/methods/sets.js @@ -57,10 +57,11 @@ const npm = { * * // Column details from a reusable ColumnSet (recommended for performance); * // NOTE: Conditional columns (start with '?') are skipped: + * const {ColumnSet, sets} = pgp.helpers; * - * const cs = new pgp.helpers.ColumnSet(['?id','val', 'msg']); + * const cs = new ColumnSet(['?id','val', 'msg']); * - * pgp.helpers.sets(data, cs); + * sets(data, cs); * //=> "val"=123,"msg"='hello' * */ diff --git a/lib/helpers/methods/update.js b/lib/helpers/methods/update.js index cc5e653f..2379bb1e 100644 --- a/lib/helpers/methods/update.js +++ b/lib/helpers/methods/update.js @@ -87,6 +87,7 @@ const npm = { * const pgp = require('pg-promise')({ * capSQL: true // if you want all generated SQL capitalized * }); + * const {update} = pgp.helpers; * * const dataSingle = {id: 1, val: 123, msg: 'hello'}; * const dataMulti = [{id: 1, val: 123, msg: 'hello'}, {id: 2, val: 456, msg: 'world!'}]; @@ -94,7 +95,7 @@ const npm = { * // Although column details can be taken from the data object, it is not * // a likely scenario for an update, unless updating the whole table: * - * pgp.helpers.update(dataSingle, null, 'my-table'); + * update(dataSingle, null, 'my-table'); * //=> UPDATE "my-table" SET "id"=1,"val"=123,"msg"='hello' * * @example @@ -104,7 +105,7 @@ const npm = { * // Dynamic conditions must be escaped/formatted properly: * const condition = pgp.as.format(' WHERE id = ${id}', dataSingle); * - * pgp.helpers.update(dataSingle, ['val', 'msg'], 'my-table') + condition; + * update(dataSingle, ['val', 'msg'], 'my-table') + condition; * //=> UPDATE "my-table" SET "val"=123,"msg"='hello' WHERE id = 1 * * @example @@ -112,17 +113,18 @@ const npm = { * // Column details are required for a multi-row `UPDATE`; * // Adding '?' in front of a column name means it is only for a WHERE condition: * - * pgp.helpers.update(dataMulti, ['?id', 'val', 'msg'], 'my-table') + ' WHERE v.id = t.id'; + * update(dataMulti, ['?id', 'val', 'msg'], 'my-table') + ' WHERE v.id = t.id'; * //=> UPDATE "my-table" AS t SET "val"=v."val","msg"=v."msg" FROM (VALUES(1,123,'hello'),(2,456,'world!')) * // AS v("id","val","msg") WHERE v.id = t.id * * @example * * // Column details from a reusable ColumnSet (recommended for performance): + * const {ColumnSet, update} = pgp.helpers; * - * const cs = new pgp.helpers.ColumnSet(['?id', 'val', 'msg'], {table: 'my-table'}); + * const cs = new ColumnSet(['?id', 'val', 'msg'], {table: 'my-table'}); * - * pgp.helpers.update(dataMulti, cs) + ' WHERE v.id = t.id'; + * update(dataMulti, cs) + ' WHERE v.id = t.id'; * //=> UPDATE "my-table" AS t SET "val"=v."val","msg"=v."msg" FROM (VALUES(1,123,'hello'),(2,456,'world!')) * // AS v("id","val","msg") WHERE v.id = t.id * @@ -130,16 +132,17 @@ const npm = { * * // Using parameter `options` to change the default alias names: * - * pgp.helpers.update(dataMulti, cs, null, {tableAlias: 'X', valueAlias: 'Y'}) + ' WHERE Y.id = X.id'; + * update(dataMulti, cs, null, {tableAlias: 'X', valueAlias: 'Y'}) + ' WHERE Y.id = X.id'; * //=> UPDATE "my-table" AS X SET "val"=Y."val","msg"=Y."msg" FROM (VALUES(1,123,'hello'),(2,456,'world!')) * // AS Y("id","val","msg") WHERE Y.id = X.id * * @example * * // Handling an empty update + * const {ColumnSet, update} = pgp.helpers; * - * const cs = new pgp.helpers.ColumnSet(['?id', '?name'], {table: 'tt'}); // no actual update-able columns - * const result = pgp.helpers.update(dataMulti, cs, null, {emptyUpdate: 123}); + * const cs = new ColumnSet(['?id', '?name'], {table: 'tt'}); // no actual update-able columns + * const result = update(dataMulti, cs, null, {emptyUpdate: 123}); * if(result === 123) { * // We know the update is empty, i.e. no columns that can be updated; * // And it didn't throw because we specified `emptyUpdate` option. diff --git a/lib/helpers/methods/values.js b/lib/helpers/methods/values.js index b5da990b..4f58ae48 100644 --- a/lib/helpers/methods/values.js +++ b/lib/helpers/methods/values.js @@ -72,10 +72,11 @@ const npm = { * @example * * // Column details from a reusable ColumnSet (recommended for performance): + * const {ColumnSet, values} = pgp.helpers; * - * const cs = new pgp.helpers.ColumnSet(['val', 'msg']); + * const cs = new ColumnSet(['val', 'msg']); * - * pgp.helpers.values(dataMulti, cs); + * values(dataMulti, cs); * //=> (123,'hello'),(456,'world!') * */ diff --git a/lib/helpers/table-name.js b/lib/helpers/table-name.js index 1586d10e..a5b310ec 100644 --- a/lib/helpers/table-name.js +++ b/lib/helpers/table-name.js @@ -89,8 +89,8 @@ class TableName { * $[Custom Type Formatting], based on $[Symbolic CTF], i.e. the actual method is available only via {@link external:Symbol Symbol}: * * ```js - * const ctf = pgp.as.ctf; // Custom Type Formatting symbols namespace - * const fullName = tn[ctf.toPostgres]; // tn = an object of type TableName + * const {toPostgres} = pgp.as.ctf; // Custom Type Formatting symbols namespace + * const fullName = tn[toPostgres]; // tn = an object of type TableName * ``` * * This is a raw formatting type (`rawType = true`), i.e. when used as a query-formatting parameter, type `TableName` diff --git a/lib/query-file.js b/lib/query-file.js index b55adda4..06fe7c4b 100644 --- a/lib/query-file.js +++ b/lib/query-file.js @@ -287,8 +287,8 @@ QueryFile.$query = file$query; * $[Custom Type Formatting], based on $[Symbolic CTF], i.e. the actual method is available only via {@link external:Symbol Symbol}: * * ```js - * const ctf = pgp.as.ctf; // Custom Type Formatting symbols namespace - * const query = qf[ctf.toPostgres](); // qf = an object of type QueryFile + * const {toPostgres} = pgp.as.ctf; // Custom Type Formatting symbols namespace + * const query = qf[toPostgres](); // qf = an object of type QueryFile * ``` * * This is a raw formatting type (`rawType = true`), i.e. when used as a query-formatting parameter, type `QueryFile` injects SQL as raw text. diff --git a/test/format.spec.js b/test/format.spec.js index 3b3290aa..4aa3da20 100644 --- a/test/format.spec.js +++ b/test/format.spec.js @@ -1350,32 +1350,32 @@ describe('Custom Type Formatting', () => { }); describe('for pre-defined ctf symbols', () => { - const ctf = pgp.as.ctf; + const {toPostgres, rawType} = pgp.as.ctf; it('must recognize symbolic ctf', () => { - expect(pgp.as.format('$1', {[ctf.toPostgres]: () => 'ok'})).toBe('\'ok\''); + expect(pgp.as.format('$1', {[toPostgres]: () => 'ok'})).toBe('\'ok\''); }); it('must recognize symbolic ctf for simple types', () => { const value = 0; - Number.prototype[ctf.toPostgres] = () => 'ok'; + Number.prototype[toPostgres] = () => 'ok'; expect(pgp.as.format('$1', value)).toBe('\'ok\''); - delete Number.prototype[ctf.toPostgres]; + delete Number.prototype[toPostgres]; }); it('must support symbolic rawType', () => { - expect(pgp.as.format('$1', {[ctf.toPostgres]: () => 'ok', [ctf.rawType]: true})).toBe('ok'); + expect(pgp.as.format('$1', {[toPostgres]: () => 'ok', [rawType]: true})).toBe('ok'); }); it('must ignore explicit rawType for symbolic ctf', () => { - expect(pgp.as.format('$1', {[ctf.toPostgres]: () => 'ok', rawType: true})).toBe('\'ok\''); + expect(pgp.as.format('$1', {[toPostgres]: () => 'ok', rawType: true})).toBe('\'ok\''); }); it('must ignore symbolic rawType for explicit ctf', () => { - expect(pgp.as.format('$1', {toPostgres: () => 'ok', [ctf.rawType]: true})).toBe('\'ok\''); + expect(pgp.as.format('$1', {toPostgres: () => 'ok', [rawType]: true})).toBe('\'ok\''); }); }); describe('for global ctf symbols', () => { - const ctf = pgp.as.ctf; + const {toPostgres, rawType} = pgp.as.ctf; it('must be equal the pre-defined symbols', () => { - expect(Symbol.for('ctf.toPostgres')).toBe(ctf.toPostgres); - expect(Symbol.for('ctf.rawType')).toBe(ctf.rawType); + expect(Symbol.for('ctf.toPostgres')).toBe(toPostgres); + expect(Symbol.for('ctf.rawType')).toBe(rawType); }); });