diff --git a/package.json b/package.json index db375b1..d1ae72e 100644 --- a/package.json +++ b/package.json @@ -27,7 +27,6 @@ "@types/multiparty": "^0.0.32", "@types/node": "^11.11.3", "@types/pg": "^7.4.14", - "@types/sql-bricks": "^2.0.1", "jest": "^24.5.0", "jest-haste-map": "^24.5.0", "jest-resolve": "^24.5.0", diff --git a/types/sql-bricks/index.d.ts b/types/sql-bricks/index.d.ts new file mode 100644 index 0000000..fba74c8 --- /dev/null +++ b/types/sql-bricks/index.d.ts @@ -0,0 +1,534 @@ +// Type definitions for sql-bricks 2.0 +// Project: http://csnw.github.io/sql-bricks +// Definitions by: Narcisse Assogba +// Paleo +// Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped + +declare namespace SqlBricks { + /** + * Statement is an abstract base class for all statements (SELECT, INSERT, UPDATE, DELETE) + * and should never be instantiated directly. It is exposed because it can be used with the + * instanceof operator to easily determine whether something is a SQL Bricks statement: my_var instanceof Statement. + */ + interface Statement { + /** + * Clones a statement so that subsequent modifications do not affect the original statement. + */ + clone(): this; + + /** + * Returns the non-parameterized SQL for the statement. This is called implicitly by Javascript when using a Statement anywhere that a string is expected (string concatenation, Array.join(), etc). + * While toString() is easy to use, it is not recommended in most cases because: + * It doesn't provide robust protection against SQL injection attacks (it just does basic escaping) + * It doesn't provide as much support for complex data types (objects, arrays, etc, are "stringified" before being passed to your database driver, which then has to interpret them correctly) + * It does not provide the same level of detail in error messages (see this issue) + * For the above reasons, it is usually better to use toParams(). + */ + toString(): string; + + /** + * Returns an object with two properties: a parameterized text string and a values array. The values are populated with anything on the right-hand side + * of a WHERE criteria,as well as any values passed into an insert() or update() (they can be passed explicitly with val() or opted out of with sql()) + * @param options A placeholder option of '?%d' can be passed to generate placeholders compatible with node-sqlite3 (%d is replaced with the parameter #): + * @example + * update('person', {'first_name': 'Fred'}).where({'last_name': 'Flintstone'}).toParams({placeholder: '?%d'}); + * // {"text": "UPDATE person SET first_name = ?1 WHERE last_name = ?2", "values": ["Fred", "Flintstone"]} + */ + toParams(options?: { placeholder: string }): SqlBricksParam; + } + + interface SqlBricksParam { + text: string; + values: any[]; + } + + type TableName = string | SelectStatement; + + interface OnCriteria { + [column: string]: string; + } + + interface WhereObject { + [column: string]: any; + } + + interface WhereGroup { + op?: string; + expressions: WhereExpression[]; + } + + interface WhereBinary { + op: string; + col: string | SelectStatement; + val: any; + quantifier: string; + } + + /** + * When a non-expression object is passed somewhere a whereExpression is expected, + * each key/value pair will be ANDed together: + */ + type WhereExpression = WhereGroup | WhereBinary | WhereObject | string; + + /** + * A SELECT statement + */ + interface SelectStatement extends Statement { + /** + * Appends additional columns to an existing query. + * @param columns can be passed as multiple arguments, a comma-delimited string or an array. + */ + select(...columns: Array): SelectStatement; + /** + * Appends additional columns to an existing query. + * @param columns can be passed as multiple arguments, a comma-delimited string or an array. + */ + select(columns: string[] | SelectStatement[]): SelectStatement; + + as(alias: string): SelectStatement; + + distinct(...columns: Array): SelectStatement; + distinct(columns: string[] | SelectStatement[]): SelectStatement; + + /** + * Makes the query a SELECT ... INTO query (which creates a new table with the results of the query). + * @alias intoTable + * @param tbl new table to create + */ + into(tbl: TableName): SelectStatement; + /** + * Makes the query a SELECT ... INTO query (which creates a new table with the results of the query). + * @alias into + * @param tbl new table to create + */ + intoTable(tbl: TableName): SelectStatement; + + intoTemp(tbl: TableName): SelectStatement; + intoTempTable(tbl: TableName): SelectStatement; + + /** + * Table names can be passed in as multiple string arguments, a comma-delimited string or an array. + * @param tbls table names + */ + from(...tbls: TableName[]): SelectStatement; + /** + * Table names can be passed in as multiple string arguments, a comma-delimited string or an array. + * @param tbls array of table names + */ + from(tbls: TableName[]): SelectStatement; + + /** + * Adds the specified join to the query. + * @alias innerJoin + * @param tbl can include an alias after a space or after the 'AS' keyword ('my_table my_alias'). + * @param onCriteria is optional if a joinCriteria function has been supplied. + */ + join( + tbl: string, + criteria?: OnCriteria | string[] | WhereExpression + ): SelectStatement; + join(tbl: string, onCol1: string, onCol2: string): SelectStatement; + join(firstTbl: string, ...otherTbls: string[]): SelectStatement; + + leftJoin( + tbl: string, + criteria?: OnCriteria | string[] | WhereExpression + ): SelectStatement; + leftJoin(tbl: string, onCol1: string, onCol2: string): SelectStatement; + leftJoin(firstTbl: string, ...otherTbls: string[]): SelectStatement; + rightJoin( + tbl: string, + criteria?: OnCriteria | string[] | WhereExpression + ): SelectStatement; + rightJoin(tbl: string, onCol1: string, onCol2: string): SelectStatement; + rightJoin(firstTbl: string, ...otherTbls: string[]): SelectStatement; + fullJoin( + tbl: string, + criteria?: OnCriteria | string[] | WhereExpression + ): SelectStatement; + fullJoin(tbl: string, onCol1: string, onCol2: string): SelectStatement; + fullJoin(firstTbl: string, ...otherTbls: string[]): SelectStatement; + crossJoin( + tbl: string, + criteria?: OnCriteria | string[] | WhereExpression + ): SelectStatement; + crossJoin(tbl: string, onCol1: string, onCol2: string): SelectStatement; + crossJoin(firstTbl: string, ...otherTbls: string[]): SelectStatement; + innerJoin( + tbl: string, + criteria?: OnCriteria | string[] | WhereExpression + ): SelectStatement; + innerJoin(tbl: string, onCol1: string, onCol2: string): SelectStatement; + innerJoin(firstTbl: string, ...otherTbls: string[]): SelectStatement; + leftOuterJoin( + tbl: string, + criteria?: OnCriteria | string[] | WhereExpression + ): SelectStatement; + leftOuterJoin( + tbl: string, + onCol1: string, + onCol2: string + ): SelectStatement; + leftOuterJoin(firstTbl: string, ...otherTbls: string[]): SelectStatement; + rightOuterJoin( + tbl: string, + criteria?: OnCriteria | string[] | WhereExpression + ): SelectStatement; + rightOuterJoin( + tbl: string, + onCol1: string, + onCol2: string + ): SelectStatement; + rightOuterJoin(firstTbl: string, ...otherTbls: string[]): SelectStatement; + fullOuterJoin( + tbl: string, + criteria?: OnCriteria | string[] | WhereExpression + ): SelectStatement; + fullOuterJoin( + tbl: string, + onCol1: string, + onCol2: string + ): SelectStatement; + fullOuterJoin(firstTbl: string, ...otherTbls: string[]): SelectStatement; + + on(onCriteria: OnCriteria | WhereExpression): SelectStatement; + on(onCol1: string, onCol2: string): SelectStatement; + + /** + * Joins using USING instead of ON. + * @param columnList columnList can be passed in as one or more string arguments, a comma-delimited string, or an array. + * @example + * select('*').from('person').join('address').using('address_id', 'country_id'); + * // SELECT * FROM person INNER JOIN address USING (address_id, country_id) + */ + using(...columnList: string[]): SelectStatement; + using(columnList: string[]): SelectStatement; + + /** + * Adds the specified natural join to the query. + * @param tbl can include an alias after a space or after the 'AS' keyword ('my_table my_alias'). + */ + naturalJoin(tbl: string): SelectStatement; + naturalLeftJoin(tbl: string): SelectStatement; + naturalRightJoin(tbl: string): SelectStatement; + naturalFullJoin(tbl: string): SelectStatement; + + naturalInnerJoin(tbl: string): SelectStatement; + naturalLeftOuterJoin(tbl: string): SelectStatement; + naturalRightOuterJoin(tbl: string): SelectStatement; + naturalFullOuterJoin(tbl: string): SelectStatement; + + where(column?: string | null, value?: any): SelectStatement; + where(...whereExpr: WhereExpression[]): SelectStatement; + + and(...options: any[]): SelectStatement; + + /** + * Sets or extends the GROUP BY columns. + * @param columns can take multiple arguments, a single comma-delimited string or an array. + */ + groupBy(...columns: string[]): SelectStatement; + groupBy(columns: string[]): SelectStatement; + + having(column: string, value: string): SelectStatement; + having(whereExpr: WhereExpression): SelectStatement; + + /** + * Sets or extends the list of columns in the ORDER BY clause. + * @param columns can be passed as multiple arguments, a single comma-delimited string or an array. + */ + orderBy(...columns: string[]): SelectStatement; + orderBy(columns: string[]): SelectStatement; + order(...columns: string[]): SelectStatement; + order(columns: string[]): SelectStatement; + + forUpdate(...tbls: string[]): SelectStatement; + of(tlb: string): SelectStatement; + noWait(): SelectStatement; + + union(...stmt: Statement[]): SelectStatement; + intersect(...stmt: Statement[]): SelectStatement; + minus(...stmt: Statement[]): SelectStatement; + except(...stmt: Statement[]): SelectStatement; + } + + /** + * An INSERT statement + */ + interface InsertStatement extends Statement { + into(tbl: TableName, ...columns: any[]): InsertStatement; + intoTable(tbl: TableName, ...columns: any[]): InsertStatement; + select(...columns: Array): SelectStatement; + select(columns: string[] | SelectStatement[]): SelectStatement; + values(...values: any[]): InsertStatement; + } + + /** + * An UPDATE statement + */ + interface UpdateStatement extends Statement { + values(...values: any[]): UpdateStatement; + set(...values: any[]): UpdateStatement; + where(column?: string | null, value?: any): UpdateStatement; + where(...whereExpr: WhereExpression[]): UpdateStatement; + and(column?: string | null, value?: any): UpdateStatement; + and(...whereExpr: WhereExpression[]): UpdateStatement; + } + + /** + * A DELETE statement + */ + interface DeleteStatement extends Statement { + from(...tbls: string[]): DeleteStatement; + using(...columnList: string[]): SelectStatement; + using(columnList: string[]): SelectStatement; + where(column?: string | null, value?: any): SelectStatement; + where(...whereExpr: WhereExpression[]): SelectStatement; + and(column?: string | null, value?: any): SelectStatement; + and(...whereExpr: WhereExpression[]): SelectStatement; + } +} + +interface SqlBricksFn { + (...params: any[]): any; + /** + * Wraps a value (user-supplied string, number, boolean, etc) so that it can be passed into SQL Bricks + * anywhere that a column is expected (the left-hand side of WHERE criteria and many other SQL Bricks APIs) + * @param value value to be wraped + */ + val(value: any): any; + + /** + * Returns a new INSERT statement. It can be used with or without the new operator. + * @alias insertInto + * @param tbl table name + * @param values a values object or a columns list. Passing a set of columns (as multiple arguments, a comma-delimited string or an array) + * will put the statement into split keys/values mode, where a matching array of values is expected in values() + * @example + * insert('person', {'first_name': 'Fred', 'last_name': 'Flintstone'}); + * // INSERT INTO person (first_name, last_name) VALUES ('Fred', 'Flintstone') + */ + insert(tbl?: string, ...values: any[]): SqlBricks.InsertStatement; + + /** + * Returns a new INSERT statement. It can be used with or without the new operator. + * @alias insert + * @param tbl table name + * @param values a values object or a columns list. Passing a set of columns (as multiple arguments, a comma-delimited string or an array) + * will put the statement into split keys/values mode, where a matching array of values is expected in values() + * @example + * insert('person', {'first_name': 'Fred', 'last_name': 'Flintstone'}); + * // INSERT INTO person (first_name, last_name) VALUES ('Fred', 'Flintstone') + */ + insertInto(tbl?: string, ...values: any[]): SqlBricks.InsertStatement; + + /** + * Returns a new select statement, seeded with a set of columns. It can be used with or without the new keyword. + * @param columns it can be passed in here (or appended later via sel.select() or sel.distinct()) via multiple arguments + * or a comma-delimited string or an array. If no columns are specified, toString() will default to SELECT *. + */ + select( + ...columns: Array + ): SqlBricks.SelectStatement; + select( + columns: string[] | SqlBricks.SelectStatement[] + ): SqlBricks.SelectStatement; + + /** + * Returns a new UPDATE statement. It can be used with or without the new operator. + * @param tbl table name + * @param values + */ + update(tbl: string, ...values: any[]): SqlBricks.UpdateStatement; + + /** + * Returns a new DELETE statement. It can be used with or without the new operator. + * @alias deleteFrom + * @param tbl table name + */ + delete(tbl?: string): SqlBricks.DeleteStatement; + /** + * Returns a new DELETE statement. It can be used with or without the new operator. + * @alias delete + * @param tbl table name + */ + deleteFrom(tbl?: string): SqlBricks.DeleteStatement; + + /** + * Registers a set of frequently-used table aliases with SQL Bricks. + * These table aliases can then be used by themselves in from(), join(), etc + * and SQL Bricks will automatically expand them to include the table name as well as the alias. + * @param expansions + * @example + * sql.aliasExpansions({'psn': 'person', 'addr': 'address', 'zip': 'zipcode', 'usr': 'user'}); + * select().from('psn').join('addr', {'psn.addr_id': 'addr.id'}); + * // SELECT * FROM person psn INNER JOIN address addr ON psn.addr_id = addr.id + */ + aliasExpansions(expansions: { [tbl: string]: string }): void; + + /** + * Sets a user-supplied function to automatically generate the .on() criteria for joins whenever it is not supplied explicitly. + * @param func + */ + joinCriteria(func?: (...args: any[]) => SqlBricks.OnCriteria): any; + + _extension(): any; + prop: number; + conversions: any; + + ////////////////////////////////////////// + ////// Where Expression functions ////// + ////////////////////////////////////////// + + /** + * Joins the passed expressions with AND + * @param whereExprs + */ + and(...whereExprs: SqlBricks.WhereExpression[]): SqlBricks.WhereGroup; + + /** + * Joins the passed expressions with OR: + * @param whereExprs + */ + or(...whereExprs: SqlBricks.WhereExpression[]): SqlBricks.WhereGroup; + + /** + * Negates the expression by wrapping it in NOT (...) + * (if it is at the top level, the parentheses are unnecessary and will be omitted) + * @param whereExpr + */ + not(whereExpr: SqlBricks.WhereExpression): SqlBricks.WhereGroup; + + /** + * Generates a BETWEEN + * @param column + * @param value1 + * @param value2 + */ + between(column: string, value1: any, value2: any): SqlBricks.WhereExpression; + isNull(column: string): SqlBricks.WhereExpression; + isNotNull(column: string): SqlBricks.WhereExpression; + like( + column: string, + value: any, + escapeStr?: string + ): SqlBricks.WhereExpression; + exists(stmt: any): SqlBricks.WhereExpression; + in( + column: string, + stmt: SqlBricks.SelectStatement + ): SqlBricks.WhereExpression; + in(column: string, ...values: any[]): SqlBricks.WhereExpression; + + /** + * Generates the appropriate relational operator (=, <>, <, <=, > or >=). + * @param column column name or query result + * @param value column value + */ + eq( + column: string | SqlBricks.SelectStatement, + value?: any + ): SqlBricks.WhereBinary; + equal( + column: string | SqlBricks.SelectStatement, + value?: any + ): SqlBricks.WhereBinary; + notEq( + column: string | SqlBricks.SelectStatement, + value?: any + ): SqlBricks.WhereBinary; + lt( + column: string | SqlBricks.SelectStatement, + value?: any + ): SqlBricks.WhereBinary; + lte( + column: string | SqlBricks.SelectStatement, + value?: any + ): SqlBricks.WhereBinary; + gt( + column: string | SqlBricks.SelectStatement, + value?: any + ): SqlBricks.WhereBinary; + gte( + column: string | SqlBricks.SelectStatement, + value?: any + ): SqlBricks.WhereBinary; + + eqAll( + column: string | SqlBricks.SelectStatement, + value?: any + ): SqlBricks.WhereBinary; + notEqAll( + column: string | SqlBricks.SelectStatement, + value?: any + ): SqlBricks.WhereBinary; + ltAll( + column: string | SqlBricks.SelectStatement, + value?: any + ): SqlBricks.WhereBinary; + lteAll( + column: string | SqlBricks.SelectStatement, + value?: any + ): SqlBricks.WhereBinary; + gtAll( + column: string | SqlBricks.SelectStatement, + value?: any + ): SqlBricks.WhereBinary; + gteAll( + column: string | SqlBricks.SelectStatement, + value?: any + ): SqlBricks.WhereBinary; + + eqAny( + column: string | SqlBricks.SelectStatement, + value?: any + ): SqlBricks.WhereBinary; + notEqAny( + column: string | SqlBricks.SelectStatement, + value?: any + ): SqlBricks.WhereBinary; + ltAny( + column: string | SqlBricks.SelectStatement, + value?: any + ): SqlBricks.WhereBinary; + lteAny( + column: string | SqlBricks.SelectStatement, + value?: any + ): SqlBricks.WhereBinary; + gtAny( + column: string | SqlBricks.SelectStatement, + value?: any + ): SqlBricks.WhereBinary; + gteAny( + column: string | SqlBricks.SelectStatement, + value?: any + ): SqlBricks.WhereBinary; + + eqSome( + column: string | SqlBricks.SelectStatement, + value?: any + ): SqlBricks.WhereBinary; + notEqSome( + column: string | SqlBricks.SelectStatement, + value?: any + ): SqlBricks.WhereBinary; + ltSome( + column: string | SqlBricks.SelectStatement, + value?: any + ): SqlBricks.WhereBinary; + lteSome( + column: string | SqlBricks.SelectStatement, + value?: any + ): SqlBricks.WhereBinary; + gtSome( + column: string | SqlBricks.SelectStatement, + value?: any + ): SqlBricks.WhereBinary; + gteSome( + column: string | SqlBricks.SelectStatement, + value?: any + ): SqlBricks.WhereBinary; +} + +declare const SqlBricks: SqlBricksFn; +export = SqlBricks; diff --git a/yarn.lock b/yarn.lock index 2ed98f9..4037e85 100644 --- a/yarn.lock +++ b/yarn.lock @@ -422,11 +422,6 @@ "@types/express-serve-static-core" "*" "@types/mime" "*" -"@types/sql-bricks@^2.0.1": - version "2.0.1" - resolved "https://registry.yarnpkg.com/@types/sql-bricks/-/sql-bricks-2.0.1.tgz#8d3241a59808e084bbcf2c2cddb1ea5429d251b7" - integrity sha512-57WN7R1oCqA6sQRDsRwpKi2x2SKfcc10w9KYsmaFxrcnjJ2N3M9rE9DIvqSylHRV16pwuPzF4fRbtIx5TzBzIA== - "@types/stack-utils@^1.0.1": version "1.0.1" resolved "https://registry.yarnpkg.com/@types/stack-utils/-/stack-utils-1.0.1.tgz#0a851d3bd96498fa25c33ab7278ed3bd65f06c3e"