usql 1.0.2 → 1.0.5

package/dist/index.js

@@ -1 +1 @@
-!function(t,n){"object"==typeof exports&&"object"==typeof module?module.exports=n():"function"==typeof define&&define.amd?define([],n):"object"==typeof exports?exports.usql=n():t.usql=n()}(window,(function(){return function(t){var n={};function e(r){if(n[r])return n[r].exports;var o=n[r]={i:r,l:!1,exports:{}};return t[r].call(o.exports,o,o.exports,e),o.l=!0,o.exports}return e.m=t,e.c=n,e.d=function(t,n,r){e.o(t,n)||Object.defineProperty(t,n,{enumerable:!0,get:r})},e.r=function(t){"undefined"!=typeof Symbol&&Symbol.toStringTag&&Object.defineProperty(t,Symbol.toStringTag,{value:"Module"}),Object.defineProperty(t,"__esModule",{value:!0})},e.t=function(t,n){if(1&n&&(t=e(t)),8&n)return t;if(4&n&&"object"==typeof t&&t&&t.__esModule)return t;var r=Object.create(null);if(e.r(r),Object.defineProperty(r,"default",{enumerable:!0,value:t}),2&n&&"string"!=typeof t)for(var o in t)e.d(r,o,function(n){return t[n]}.bind(null,o));return r},e.n=function(t){var n=t&&t.__esModule?function(){return t.default}:function(){return t};return e.d(n,"a",n),n},e.o=function(t,n){return Object.prototype.hasOwnProperty.call(t,n)},e.p="",e(e.s=6)}([function(t,n){t.exports=function(t,n,e){return n in t?Object.defineProperty(t,n,{value:e,enumerable:!0,configurable:!0,writable:!0}):t[n]=e,t}},function(t,n){t.exports=function(t,n){if(!(t instanceof n))throw new TypeError("Cannot call a class as a function")}},function(t,n){function e(t,n){for(var e=0;e<n.length;e++){var r=n[e];r.enumerable=r.enumerable||!1,r.configurable=!0,"value"in r&&(r.writable=!0),Object.defineProperty(t,r.key,r)}}t.exports=function(t,n,r){return n&&e(t.prototype,n),r&&e(t,r),t}},function(t,n,e){var r=e(7),o=e(8),i=e(9);t.exports=function(t,n){return r(t)||o(t,n)||i()}},function(t,n){function e(n){return"function"==typeof Symbol&&"symbol"==typeof Symbol.iterator?t.exports=e=function(t){return typeof t}:t.exports=e=function(t){return t&&"function"==typeof Symbol&&t.constructor===Symbol&&t!==Symbol.prototype?"symbol":typeof t},e(n)}t.exports=e},function(t,n,e){var r=e(10),o=e(11),i=e(12);t.exports=function(t){return r(t)||o(t)||i()}},function(t,n,e){"use strict";t.exports=e(13).default},function(t,n){t.exports=function(t){if(Array.isArray(t))return t}},function(t,n){t.exports=function(t,n){if(Symbol.iterator in Object(t)||"[object Arguments]"===Object.prototype.toString.call(t)){var e=[],r=!0,o=!1,i=void 0;try{for(var u,a=t[Symbol.iterator]();!(r=(u=a.next()).done)&&(e.push(u.value),!n||e.length!==n);r=!0);}catch(t){o=!0,i=t}finally{try{r||null==a.return||a.return()}finally{if(o)throw i}}return e}}},function(t,n){t.exports=function(){throw new TypeError("Invalid attempt to destructure non-iterable instance")}},function(t,n){t.exports=function(t){if(Array.isArray(t)){for(var n=0,e=new Array(t.length);n<t.length;n++)e[n]=t[n];return e}}},function(t,n){t.exports=function(t){if(Symbol.iterator in Object(t)||"[object Arguments]"===Object.prototype.toString.call(t))return Array.from(t)}},function(t,n){t.exports=function(){throw new TypeError("Invalid attempt to spread non-iterable instance")}},function(t,n,e){"use strict";e.r(n);var r=e(3),o=e.n(r),i=e(4),u=e.n(i),a=e(5),s=e.n(a),c=e(1),l=e.n(c),f=e(2),h=e.n(f),p=e(0),d=e.n(p),y=function(){function t(n){l()(this,t),d()(this,"data",void 0),this.data=n}return h()(t,[{key:"toString",value:function(){return this.data}}]),t}(),v=function(){function t(n){l()(this,t),d()(this,"table",null),d()(this,"alias",null),d()(this,"selects",[]),d()(this,"joins",[]),d()(this,"wheres",[]),d()(this,"orders",[]),d()(this,"dataOffset",null),d()(this,"dataLimit",null),this.table=n}return h()(t,[{key:"as",value:function(t){return this.alias=t,this}},{key:"escape",value:function(n){return null===n?null:n instanceof t||n instanceof y?n.toString():"string"==typeof n?JSON.stringify(n).slice(1,-1):JSON.stringify(n)}},{key:"renderColumn",value:function(n){if(n instanceof t||n instanceof y)return n.toString();if("null"===String(n).toLowerCase())return"null";var e=function(t){var n=s()(t.matchAll(/`?(\w+|\*)`?/g));return(n=n.map((function(t){return"*"===t[0]||"*"===t[1]?"*":"`".concat(t[1]?escape(t[1]):escape(t[0]),"`")}))).join(".")};return n.includes(" as ")?n.split(" as ").map((function(t){return e(t)})).join(" as "):e(n)}},{key:"renderStr",value:function(t){return t instanceof y?t.toString():"null"===String(t).toLowerCase()?"NULL":Number(t)===t?'"'.concat(t,'"'):'"'.concat(escape(t),'"')}},{key:"_where",value:function(){var t=this,n=arguments.length>0&&void 0!==arguments[0]?arguments[0]:"AND",e=arguments.length>1?arguments[1]:void 0,r=e.column,o=e.operator,i=void 0===o?"=":o,a=e.value;"object"===u()(r)&&Object.keys(r).forEach((function(e){t.wheres.push({joiner:n,column:e,operator:i,value:r[e]})})),"string"==typeof r&&(void 0!==i&&void 0===a&&(a=i,i="="),this.wheres.push({joiner:n,column:r,operator:i,value:a}))}},{key:"where",value:function(t){var n=arguments.length>1&&void 0!==arguments[1]?arguments[1]:"=",e=arguments.length>2?arguments[2]:void 0;return this._where("AND",{column:t,operator:n,value:e}),this}},{key:"whereNot",value:function(t,n){return this._where("AND",{column:t,operator:"!=",value:n}),this}},{key:"orWhere",value:function(t,n,e){return this._where("OR",{column:t,operator:n,value:e}),this}},{key:"join",value:function(t,n,e,r){return void 0!==e&&void 0===r&&(r=e,e="="),this.joins.push([t,n,e,r]),this}},{key:"select",value:function(){var t;return(t=this.selects).push.apply(t,arguments),this}},{key:"count",value:function(n){return this.selects.push(t.raw("COUNT(".concat(this.renderColumn(n),")"))),this}},{key:"orderBy",value:function(t,n){return this.orders.push([t,n]),this}},{key:"offset",value:function(t){return this.dataOffset=t,this}},{key:"limit",value:function(t){return this.dataLimit=t,this}},{key:"toString",value:function(){var t=this,n=[];if(n.push("SELECT"),n.push(this.selects.length>0?this.selects.map((function(n){return t.renderColumn(n)})).join(", "):"*"),n.push("FROM ".concat(this.renderColumn(this.table))),this.joins.length>0&&n.push(this.joins.map((function(n){var e=o()(n,4),r=e[0],i=e[1],u=e[2],a=e[3];return"JOIN ".concat(t.renderColumn(r)," ON ").concat(t.renderColumn(i)," ").concat(u," ").concat(t.renderColumn(a))})).join(" ")),this.wheres.length>0){var e=this.wheres.map((function(n,e){var r=n.joiner,o=n.column,i=n.operator,u=n.value;if("null"===String(u).toLowerCase()){var a={"!=":"IS NOT","=":"IS"};i=a[i]?a[i]:i}return r=e>0?"".concat(r," "):"","".concat(r).concat(t.renderColumn(o)," ").concat(i," ").concat(t.renderStr(u,"value"))}));n.push("WHERE"),n.push(e.join(" "))}this.orders.length>0&&(n.push("ORDER BY"),n.push(this.orders.map((function(n){var e=o()(n,2),r=e[0],i=e[1];return"".concat(t.renderColumn(r)," ").concat(i)})).join(", "))),this.dataLimit&&this.dataOffset?n.push("LIMIT ".concat(this.dataOffset,", ").concat(this.dataLimit)):this.dataLimit&&!this.dataOffset&&n.push("LIMIT ".concat(this.dataLimit));var r=n.join(" ");return null!==this.alias&&(r="(".concat(r,") as ").concat(this.renderColumn(this.alias))),r}}],[{key:"raw",value:function(t){return new y(t)}}]),t}();n.default=v}])}));
+!function(t,e){"object"==typeof exports&&"object"==typeof module?module.exports=e():"function"==typeof define&&define.amd?define([],e):"object"==typeof exports?exports.usql=e():t.usql=e()}(window,(function(){return function(t){var e={};function n(r){if(e[r])return e[r].exports;var o=e[r]={i:r,l:!1,exports:{}};return t[r].call(o.exports,o,o.exports,n),o.l=!0,o.exports}return n.m=t,n.c=e,n.d=function(t,e,r){n.o(t,e)||Object.defineProperty(t,e,{enumerable:!0,get:r})},n.r=function(t){"undefined"!=typeof Symbol&&Symbol.toStringTag&&Object.defineProperty(t,Symbol.toStringTag,{value:"Module"}),Object.defineProperty(t,"__esModule",{value:!0})},n.t=function(t,e){if(1&e&&(t=n(t)),8&e)return t;if(4&e&&"object"==typeof t&&t&&t.__esModule)return t;var r=Object.create(null);if(n.r(r),Object.defineProperty(r,"default",{enumerable:!0,value:t}),2&e&&"string"!=typeof t)for(var o in t)n.d(r,o,function(e){return t[e]}.bind(null,o));return r},n.n=function(t){var e=t&&t.__esModule?function(){return t.default}:function(){return t};return n.d(e,"a",e),e},n.o=function(t,e){return Object.prototype.hasOwnProperty.call(t,e)},n.p="",n(n.s=6)}([function(t,e){t.exports=function(t,e,n){return e in t?Object.defineProperty(t,e,{value:n,enumerable:!0,configurable:!0,writable:!0}):t[e]=n,t}},function(t,e,n){var r=n(10),o=n(11),i=n(12);t.exports=function(t){return r(t)||o(t)||i()}},function(t,e){t.exports=function(t,e){if(!(t instanceof e))throw new TypeError("Cannot call a class as a function")}},function(t,e){function n(t,e){for(var n=0;n<e.length;n++){var r=e[n];r.enumerable=r.enumerable||!1,r.configurable=!0,"value"in r&&(r.writable=!0),Object.defineProperty(t,r.key,r)}}t.exports=function(t,e,r){return e&&n(t.prototype,e),r&&n(t,r),t}},function(t,e,n){var r=n(7),o=n(8),i=n(9);t.exports=function(t,e){return r(t)||o(t,e)||i()}},function(t,e){function n(e){return"function"==typeof Symbol&&"symbol"==typeof Symbol.iterator?t.exports=n=function(t){return typeof t}:t.exports=n=function(t){return t&&"function"==typeof Symbol&&t.constructor===Symbol&&t!==Symbol.prototype?"symbol":typeof t},n(e)}t.exports=n},function(t,e,n){"use strict";t.exports=n(13).default},function(t,e){t.exports=function(t){if(Array.isArray(t))return t}},function(t,e){t.exports=function(t,e){if(Symbol.iterator in Object(t)||"[object Arguments]"===Object.prototype.toString.call(t)){var n=[],r=!0,o=!1,i=void 0;try{for(var u,a=t[Symbol.iterator]();!(r=(u=a.next()).done)&&(n.push(u.value),!e||n.length!==e);r=!0);}catch(t){o=!0,i=t}finally{try{r||null==a.return||a.return()}finally{if(o)throw i}}return n}}},function(t,e){t.exports=function(){throw new TypeError("Invalid attempt to destructure non-iterable instance")}},function(t,e){t.exports=function(t){if(Array.isArray(t)){for(var e=0,n=new Array(t.length);e<t.length;e++)n[e]=t[e];return n}}},function(t,e){t.exports=function(t){if(Symbol.iterator in Object(t)||"[object Arguments]"===Object.prototype.toString.call(t))return Array.from(t)}},function(t,e){t.exports=function(){throw new TypeError("Invalid attempt to spread non-iterable instance")}},function(t,e,n){"use strict";n.r(e);var r=n(4),o=n.n(r),i=n(5),u=n.n(i),a=n(2),s=n.n(a),c=n(3),l=n.n(c),f=n(0),h=n.n(f),p=n(1),d=n.n(p),y=function(){return l()((function t(e){s()(this,t),h()(this,"data",void 0),this.data=e}),[{key:"toString",value:function(){return this.data}}])}();function v(t,e){var n=Object.keys(t);if(Object.getOwnPropertySymbols){var r=Object.getOwnPropertySymbols(t);e&&(r=r.filter((function(e){return Object.getOwnPropertyDescriptor(t,e).enumerable}))),n.push.apply(n,r)}return n}var m=new Set(["=","!=","<>","<",">","<=",">=","LIKE","NOT LIKE","IN","NOT IN","IS","IS NOT"]),b=new Set(["ASC","DESC"]);function g(t){return'"'+t.replace(/\\/g,"\\\\").replace(/\0/g,"\\0").replace(/\n/g,"\\n").replace(/\r/g,"\\r").replace(/\x1a/g,"\\Z").replace(/"/g,'\\"')+'"'}function w(t){if(!m.has(String(t).toUpperCase())&&!m.has(String(t)))throw new RangeError('usql: disallowed SQL operator "'.concat(t,'". Allowed: ').concat(d()(m).join(", ")))}var S=function(){function t(e){s()(this,t),h()(this,"table",null),h()(this,"alias",null),h()(this,"selects",[]),h()(this,"joins",[]),h()(this,"wheres",[]),h()(this,"orders",[]),h()(this,"dataOffset",null),h()(this,"dataLimit",null),this.table=e}return l()(t,[{key:"as",value:function(t){return this.alias=t,this}},{key:"clone",value:function(){var e=new t(this.table);return e.alias=this.alias,e.selects=d()(this.selects),e.joins=this.joins.map((function(t){return d()(t)})),e.wheres=this.wheres.map((function(t){return function(t){for(var e=1;e<arguments.length;e++){var n=null!=arguments[e]?arguments[e]:{};e%2?v(Object(n),!0).forEach((function(e){h()(t,e,n[e])})):Object.getOwnPropertyDescriptors?Object.defineProperties(t,Object.getOwnPropertyDescriptors(n)):v(Object(n)).forEach((function(e){Object.defineProperty(t,e,Object.getOwnPropertyDescriptor(n,e))}))}return t}({},t)})),e.orders=this.orders.map((function(t){return d()(t)})),e.dataOffset=this.dataOffset,e.dataLimit=this.dataLimit,e}},{key:"escape",value:function(e){return null===e?null:e instanceof t||e instanceof y?e.toString():g(String(e)).slice(1,-1)}},{key:"renderColumn",value:function(e){if(e instanceof t||e instanceof y)return e.toString();if(null==e)return"null";if("null"===String(e).toLowerCase())return"null";var n=function(t){var e=d()(t.matchAll(/`?(\w+|\*)`?/g));return(e=e.map((function(t){return"*"===t[0]||"*"===t[1]?"*":"`".concat(t[1]?t[1]:t[0],"`")}))).join(".")},r=String(e);return r.includes(" as ")?r.split(" as ").map((function(t){return n(t)})).join(" as "):n(r)}},{key:"renderStr",value:function(t){return t instanceof y?t.toString():null===t?"NULL":g(String(t))}},{key:"_where",value:function(){var t=this,e=arguments.length>0&&void 0!==arguments[0]?arguments[0]:"AND",n=arguments.length>1?arguments[1]:void 0,r=n.column,o=n.operator,i=void 0===o?"=":o,a=n.value,s=n.group,c=void 0!==s&&s;if(c)this.wheres.push({joiner:e,group:!0,conditions:r});else{if(null==r)throw new TypeError("usql: where() column argument must not be null or undefined");if("object"===u()(r))return w(i),void Object.keys(r).forEach((function(n){t.wheres.push({joiner:e,column:n,operator:i,value:r[n]})}));"string"==typeof r&&(void 0!==i&&void 0===a&&(a=i,i="="),w(i),this.wheres.push({joiner:e,column:r,operator:i,value:a}))}}},{key:"where",value:function(t){var e=arguments.length>1&&void 0!==arguments[1]?arguments[1]:"=",n=arguments.length>2?arguments[2]:void 0;return this._where("AND",{column:t,operator:e,value:n}),this}},{key:"whereNot",value:function(t,e){return this._where("AND",{column:t,operator:"!=",value:e}),this}},{key:"orWhere",value:function(t,e,n){return this._where("OR",{column:t,operator:e,value:n}),this}},{key:"whereGroup",value:function(e){var n=new t(this.table);return e(n),this._where("AND",{column:n.wheres,group:!0}),this}},{key:"orWhereGroup",value:function(e){var n=new t(this.table);return e(n),this._where("OR",{column:n.wheres,group:!0}),this}},{key:"join",value:function(t,e,n,r){return void 0!==n&&void 0===r&&(r=n,n="="),w(n),this.joins.push([t,e,n,r]),this}},{key:"select",value:function(){var t;return(t=this.selects).push.apply(t,arguments),this}},{key:"count",value:function(e){return this.selects.push(t.raw("COUNT(".concat(this.renderColumn(e),")"))),this}},{key:"orderBy",value:function(t){var e=arguments.length>1&&void 0!==arguments[1]?arguments[1]:"ASC",n=String(e).toUpperCase();if(!b.has(n))throw new RangeError('usql: invalid ORDER BY direction "'.concat(e,"\". Must be 'ASC' or 'DESC'."));return this.orders.push([t,n]),this}},{key:"offset",value:function(t){var e=parseInt(t,10);if(!Number.isFinite(e)||String(e)!==String(t).trim())throw new TypeError("usql: offset() requires an integer, got: ".concat(JSON.stringify(t)));return this.dataOffset=e,this}},{key:"limit",value:function(t){var e=parseInt(t,10);if(!Number.isFinite(e)||String(e)!==String(t).trim())throw new TypeError("usql: limit() requires an integer, got: ".concat(JSON.stringify(t)));return this.dataLimit=e,this}},{key:"_buildSQL",value:function(){var e=this,n=arguments.length>0&&void 0!==arguments[0]?arguments[0]:null,r=Array.isArray(n),i=function(o){return null===o?"NULL":r?o instanceof y||o instanceof t?o.toString():(n.push(o),"?"):e.renderStr(o)},u=function(t){return t.map((function(t,n){var r=t.joiner,o=t.column,a=t.operator,s=t.value,c=t.group,l=t.conditions,f=n>0?"".concat(r," "):"";if(c)return"".concat(f,"(").concat(u(l),")");var h=a;if(null===s){var p={"!=":"IS NOT","<>":"IS NOT","=":"IS"};h=void 0!==p[h]?p[h]:h}return"".concat(f).concat(e.renderColumn(o)," ").concat(h," ").concat(i(s))})).join(" ")},a=[];a.push("SELECT"),a.push(this.selects.length>0?this.selects.map((function(t){return e.renderColumn(t)})).join(", "):"*"),a.push("FROM ".concat(this.renderColumn(this.table))),this.joins.length>0&&a.push(this.joins.map((function(t){var n=o()(t,4),r=n[0],i=n[1],u=n[2],a=n[3];return"JOIN ".concat(e.renderColumn(r)," ON ").concat(e.renderColumn(i)," ").concat(u," ").concat(e.renderColumn(a))})).join(" ")),this.wheres.length>0&&(a.push("WHERE"),a.push(u(this.wheres))),this.orders.length>0&&(a.push("ORDER BY"),a.push(this.orders.map((function(t){var n=o()(t,2),r=n[0],i=n[1];return"".concat(e.renderColumn(r)," ").concat(i)})).join(", "))),null!==this.dataLimit&&null!==this.dataOffset?a.push("LIMIT ".concat(this.dataOffset,", ").concat(this.dataLimit)):null!==this.dataLimit&&null===this.dataOffset&&a.push("LIMIT ".concat(this.dataLimit));var s=a.join(" ");return null!==this.alias&&(s="(".concat(s,") as ").concat(this.renderColumn(this.alias))),s}},{key:"toString",value:function(){return this._buildSQL(null)}},{key:"toSQL",value:function(){var t=[];return{sql:this._buildSQL(t),bindings:t}}}],[{key:"raw",value:function(t){return new y(t)}}])}();e.default=S}])}));

package/index.d.ts

@@ -0,0 +1,286 @@
+/*
+  MIT License http://www.opensource.org/licenses/mit-license.php
+  Author Andrew Guk
+
+  TypeScript definitions for usql
+*/
+
+// ---------------------------------------------------------------------------
+// Primitive union types
+// ---------------------------------------------------------------------------
+
+/** Allowed SQL comparison operators. */
+export type SqlOperator =
+  | '='
+  | '!='
+  | '<>'
+  | '<'
+  | '>'
+  | '<='
+  | '>='
+  | 'LIKE'
+  | 'NOT LIKE'
+  | 'IN'
+  | 'NOT IN'
+  | 'IS'
+  | 'IS NOT'
+
+/** Allowed ORDER BY directions (case-insensitive — normalised to uppercase internally). */
+export type OrderDirection = 'ASC' | 'DESC' | 'asc' | 'desc'
+
+// ---------------------------------------------------------------------------
+// Return-value shapes
+// ---------------------------------------------------------------------------
+
+/**
+ * The object returned by {@link DB.toSQL}.
+ *
+ * Pass `sql` to your database driver together with `bindings` so the driver
+ * handles value escaping safely rather than relying on inline string escaping.
+ */
+export interface SqlResult {
+  /** SQL string with `?` placeholders substituted for every bound value. */
+  sql: string
+  /** Ordered array of values to bind to the `?` placeholders. */
+  bindings: unknown[]
+}
+
+// ---------------------------------------------------------------------------
+// RAW wrapper
+// ---------------------------------------------------------------------------
+
+/**
+ * Wraps a raw SQL fragment that is inserted verbatim into a query with **no**
+ * escaping whatsoever.
+ *
+ * ⚠️  **Security warning** — only pass string literals or values you have
+ * already validated / escaped yourself. Never pass attacker-controlled input
+ * to `DB.raw()`.
+ */
+export declare class RAW {
+  constructor(data: string)
+  toString(): string
+}
+
+// ---------------------------------------------------------------------------
+// DB query builder
+// ---------------------------------------------------------------------------
+
+/** A column or table reference: a plain name string, a sub-query, or a raw fragment. */
+export type ColumnRef = string | DB | RAW
+
+/** An object mapping column names to values for object-style where clauses. */
+export type WhereObject = Record<string, unknown>
+
+export declare class DB {
+  // -------------------------------------------------------------------------
+  // Construction
+  // -------------------------------------------------------------------------
+
+  constructor(table: ColumnRef)
+
+  /**
+   * Create a raw SQL fragment. The content is inserted **verbatim** — see the
+   * {@link RAW} security warning before use.
+   */
+  static raw(data: string): RAW
+
+  // -------------------------------------------------------------------------
+  // Instance cloning
+  // -------------------------------------------------------------------------
+
+  /**
+   * Return a deep copy of this builder instance.
+   *
+   * Use `clone()` when you want to share a base query object across multiple
+   * call sites without risk of cross-request state mutation.
+   *
+   * @example
+   * const base = new DB('users').where('active', 1)
+   * const admins = base.clone().where('role', 'admin')
+   * const mods   = base.clone().where('role', 'moderator')
+   */
+  clone(): DB
+
+  // -------------------------------------------------------------------------
+  // Aliasing
+  // -------------------------------------------------------------------------
+
+  /**
+   * Alias the current query for use as a sub-query.
+   * Has no effect when the query is used at the top level.
+   */
+  as(alias: string): this
+
+  // -------------------------------------------------------------------------
+  // Column selection
+  // -------------------------------------------------------------------------
+
+  /** Add one or more columns (or sub-queries) to the SELECT list. */
+  select(...columns: ColumnRef[]): this
+
+  /**
+   * Add a `COUNT(column)` aggregate to the SELECT list.
+   *
+   * @example
+   * new DB('orders').count('id')
+   * // → SELECT COUNT(`id`) FROM `orders`
+   */
+  count(column: ColumnRef): this
+
+  // -------------------------------------------------------------------------
+  // WHERE clauses
+  // -------------------------------------------------------------------------
+
+  /**
+   * Add an AND WHERE condition.
+   *
+   * Three-argument form (explicit operator):
+   * ```ts
+   * .where('age', '>=', 18)
+   * ```
+   *
+   * Two-argument form (defaults to `=`):
+   * ```ts
+   * .where('status', 'active')
+   * ```
+   *
+   * Object form (multiple equality conditions joined with AND):
+   * ```ts
+   * .where({ first_name: 'Alice', last_name: 'Smith' })
+   * ```
+   *
+   * @throws {TypeError}   if `column` is `null` or `undefined`.
+   * @throws {RangeError}  if `operator` is not in the allowed set.
+   */
+  where(column: WhereObject): this
+  where(column: string, value: unknown): this
+  where(column: string, operator: SqlOperator, value: unknown): this
+
+  /**
+   * Add an AND WHERE `column != value` condition.
+   *
+   * @throws {TypeError}  if `column` is `null` or `undefined`.
+   */
+  whereNot(column: WhereObject): this
+  whereNot(column: string, value: unknown): this
+
+  /**
+   * Add an OR WHERE condition (same argument forms as {@link where}).
+   *
+   * @throws {TypeError}   if `column` is `null` or `undefined`.
+   * @throws {RangeError}  if `operator` is not in the allowed set.
+   */
+  orWhere(column: WhereObject): this
+  orWhere(column: string, value: unknown): this
+  orWhere(column: string, operator: SqlOperator, value: unknown): this
+
+  /**
+   * Add a grouped AND WHERE clause.
+   *
+   * The callback receives a fresh `DB` instance; call `.where()` / `.orWhere()`
+   * on it to populate the group.  The resulting conditions are wrapped in
+   * parentheses and joined to the outer query with AND.
+   *
+   * @example
+   * new DB('users')
+   *   .where('active', 1)
+   *   .whereGroup(q => q.where('role', 'admin').orWhere('role', 'moderator'))
+   * // → SELECT * FROM `users` WHERE `active` = "1" AND (`role` = "admin" OR `role` = "moderator")
+   */
+  whereGroup(callback: (sub: DB) => void): this
+
+  /**
+   * Add a grouped OR WHERE clause (same semantics as {@link whereGroup} but
+   * joined with OR).
+   *
+   * @example
+   * new DB('users')
+   *   .where('is_deleted', 0)
+   *   .orWhereGroup(q => q.where('role', 'superadmin').where('active', 1))
+   * // → … WHERE `is_deleted` = "0" OR (`role` = "superadmin" AND `active` = "1")
+   */
+  orWhereGroup(callback: (sub: DB) => void): this
+
+  // -------------------------------------------------------------------------
+  // JOIN
+  // -------------------------------------------------------------------------
+
+  /**
+   * Add a JOIN clause.
+   *
+   * Two-column form (operator defaults to `=`):
+   * ```ts
+   * .join('contacts', 'users.id', 'contacts.user_id')
+   * ```
+   *
+   * Explicit operator form:
+   * ```ts
+   * .join('logs', 'logs.user_id', '=', 'users.id')
+   * ```
+   *
+   * @throws {RangeError}  if `operator` is not in the allowed set.
+   */
+  join(table: ColumnRef, tableColumn: string, joinedColumn: string): this
+  join(table: ColumnRef, tableColumn: string, operator: SqlOperator, joinedColumn: string): this
+
+  // -------------------------------------------------------------------------
+  // Ordering
+  // -------------------------------------------------------------------------
+
+  /**
+   * Add an ORDER BY clause.
+   *
+   * Direction is case-insensitive and normalised to uppercase internally.
+   *
+   * @param column    Column to order by.
+   * @param direction `'ASC'` (default) or `'DESC'`.
+   *
+   * @throws {RangeError}  if `direction` is not `'ASC'` or `'DESC'` (case-insensitive).
+   */
+  orderBy(column: ColumnRef, direction?: OrderDirection): this
+
+  // -------------------------------------------------------------------------
+  // Pagination
+  // -------------------------------------------------------------------------
+
+  /**
+   * Set the LIMIT value.
+   *
+   * @throws {TypeError}  if `data` cannot be parsed as a finite integer.
+   */
+  limit(data: number): this
+
+  /**
+   * Set the OFFSET value.  Has no effect unless `limit()` is also called.
+   *
+   * @throws {TypeError}  if `data` cannot be parsed as a finite integer.
+   */
+  offset(data: number): this
+
+  // -------------------------------------------------------------------------
+  // Output
+  // -------------------------------------------------------------------------
+
+  /**
+   * Render the query as a plain SQL string with values **escaped inline**.
+   *
+   * ⚠️  Prefer {@link toSQL} + parameterised execution with your database
+   * driver.  Inline escaping is provided for logging and debugging purposes.
+   */
+  toString(): string
+
+  /**
+   * Render the query in **parameterised form**.
+   *
+   * Values are replaced with `?` placeholders and collected into the returned
+   * `bindings` array.  Pass both to your database driver:
+   *
+   * @example
+   * const { sql, bindings } = new DB('users').where('id', userId).toSQL()
+   * await db.execute(sql, bindings)
+   */
+  toSQL(): SqlResult
+}
+
+export default DB

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "usql",
-  "version": "1.0.2",
+  "version": "1.0.5",
   "description": "Tiny, zero-dependency SQL query generator",
   "main": "index.js",
   "repository": "https://github.com/gukandrew/usql",
@@ -17,15 +17,6 @@
     "mysql",
     "orm"
   ],
-  "scripts": {
-    "dev": "NODE_ENV='development' yarn run build --watch",
-    "build": "NODE_ENV='production' webpack",
-    "build:babel": "babel src/index.js --out-file ./dist/index.js",
-    "test": "jest ./tests/*",
-    "test:inspect": "NODE_ENV='development' node --inspect-brk ./node_modules/.bin/jest  --watch --runInBand ./tests/*",
-    "test:watch": "yarn dev & yarn run test --watch",
-    "test:watch:inspect": "yarn dev & yarn run test:inspect"
-  },
   "devDependencies": {
     "@babel/cli": "~7.12.0",
     "@babel/core": "~7.7.7",
@@ -40,5 +31,14 @@
     "jest": "~24.9.0",
     "webpack": "~4.41.6",
     "webpack-cli": "~3.3.12"
+  },
+  "scripts": {
+    "dev": "NODE_ENV='development' pnpm run build --watch",
+    "build": "NODE_ENV='production' webpack",
+    "build:babel": "babel src/index.js --out-file ./dist/index.js",
+    "test": "jest ./tests/*",
+    "test:inspect": "NODE_ENV='development' node --inspect-brk ./node_modules/.bin/jest  --watch --runInBand ./tests/*",
+    "test:watch": "pnpm dev & pnpm run test --watch",
+    "test:watch:inspect": "pnpm dev & pnpm run test:inspect"
   }
-}
+}