@digitalwalletcorp/sql-builder 1.0.2 → 1.1.0

package/README.md

@@ -38,7 +38,7 @@ You provide the `SQLBuilder` with a template string containing special, S2Dao-st
 
 This is the most common use case. The `WHERE` clause is built dynamically based on which properties exist in the `bindEntity`.
 
-##### Template:
+**Template:**
 
 ```sql
 SELECT
@@ -55,7 +55,7 @@ ORDER BY started_at DESC
 LIMIT /*limit*/100
 ```
 
-##### Code:
+**Code:**
 
 ```typescript
 import { SQLBuilder } from '@digitalwalletcorp/sql-builder';
@@ -81,7 +81,7 @@ const sql2 = builder.generateSQL(template, bindEntity2);
 console.log(sql2);
 ```
 
-##### Resulting SQL:
+**Resulting SQL:**
 
 * SQL 1 (Scenario A): The `project_name` condition is excluded, but the `status` condition is included.
 
@@ -114,7 +114,7 @@ LIMIT 100
 
 Use a `/*FOR...*/` block to iterate over an array and generate SQL for each item. This is useful for building multiple `LIKE` conditions.
 
-##### Template:
+**Template:**
 
 ```sql
 SELECT * FROM activity
@@ -122,7 +122,7 @@ WHERE 1 = 1
 /*FOR name:projectNames*/AND project_name LIKE '%' || /*name*/'default' || '%'/*END*/
 ```
 
-##### Code:
+**Code:**
 
 ```typescript
 import { SQLBuilder } from '@digitalwalletcorp/sql-builder';
@@ -138,7 +138,7 @@ const sql = builder.generateSQL(template, bindEntity);
 console.log(sql);
 ```
 
-##### Resulting SQL:
+**Resulting SQL:**
 
 ```sql
 SELECT * FROM activity
@@ -162,6 +162,68 @@ Generates a final SQL string by processing the template with the provided data e
 * `entity`: A data object whose properties are used for evaluating conditions (`/*IF...*/`) and binding values (`/*variable*/`).
 * Returns: The generated SQL string.
 
+##### `generateParameterizedSQL(template: string, entity: Record<string, any>, bindType: 'postgres' | 'mysql' | 'oracle'): [string, Array<any> | Record<string, any>]`
+
+Generates a SQL string with placeholders for prepared statements and returns an array of bind parameters. This method is crucial for preventing SQL injection.
+
+* `template`: The SQL template string containing S2Dao-style comments.
+* `entity`: A data object whose properties are used for evaluating conditions (`/*IF...*/`) and binding values.
+* `bindType`: Specifies the database type ('postgres', 'mysql', or 'oracle') to determine the correct placeholder syntax (`$1`, `?`, or `:name`).
+
+    **Note on `bindType` Mapping:**
+    While `bindType` explicitly names PostgreSQL, MySQL, and Oracle, the generated placeholder syntax is compatible with other SQL databases as follows:
+
+    | `bindType` | Placeholder Syntax | Compatible Databases | Bind Parameter Type |
+    | :------------- | :----------------- | :------------------- | :------------------ |
+    | `postgres`     | `$1`, `$2`, ...    | **PostgreSQL** | `Array<any>`        |
+    | `mysql`        | `?`, `?`, ...      | **MySQL**, **SQLite**, **SQL Server** (for unnamed parameters) | `Array<any>`        |
+    | `oracle`       | `:name`, `:age`, ... | **Oracle**, **SQLite** (for named parameters) | `Record<string, any>` |
+
+* Returns: A tuple `[sql, bindParams]`.
+    * `sql`: The generated SQL query with appropriate placeholders.
+    * `bindParams`: An array of values (for PostgreSQL/MySQL) or an object of named values (for Oracle) to bind to the placeholders.
+
+##### Example 3: Parameterized SQL with PostgreSQL
+
+**Template:**
+
+```sql
+SELECT
+  id,
+  user_name
+FROM users
+/*BEGIN*/WHERE
+  1 = 1
+  /*IF userId != null*/AND user_id = /*userId*/0/*END*/
+  /*IF projectNames.length*/AND project_name IN /*projectNames*/('default_project')/*END*/
+/*END*/
+```
+
+**Code:**
+
+```typescript
+import { SQLBuilder } from '@digitalwalletcorp/sql-builder';
+
+const builder = new SQLBuilder();
+const template = `...`; // The SQL template from above
+
+const bindEntity = {
+  userId: 123,
+  projectNames: ['project_a', 'project_b']
+};
+
+const [sql, params] = builder.generateParameterizedSQL(template, bindEntity, 'postgres');
+console.log('SQL:', sql);
+console.log('Parameters:', params);
+```
+
+**Resulting SQL & Parameters:**
+
+```
+SQL: SELECT id, user_name FROM users WHERE 1 = 1 AND user_id = $1 AND project_name IN ($2, $3)
+Parameters: [ 123, 'project_a', 'project_b' ]
+```
+
 ## 🪄 Special Comment Syntax
 
 | Tag | Syntax | Description |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@digitalwalletcorp/sql-builder",
-  "version": "1.0.2",
+  "version": "1.1.0",
   "description": "This is a library for building SQL",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",

package/src/sql-builder.ts

@@ -6,6 +6,27 @@ type ExtractValueType<T extends 'string' | 'array' | 'object'>
       ? any[] | undefined
       : Record<string, any> | undefined;
 
+/**
+ * PostgreSQL: $1, $2... 配列
+ * MySQL: ? 配列
+ * SQLite: ?, $name, :name 配列またはオブジェクト
+ * SQL Server: ?, `@name` 配列またはオブジェクト
+ * Oracle: :name オブジェクト
+ *
+ * 以下をサポートする
+ * ・$1, $2 (postgres)
+ * ・? (mysql) SQLite, SQL Serverもこれで代替可能
+ * ・:name (oracle) SQLiteもこれで代替可能
+ */
+type BindType = 'postgres' | 'mysql' | 'oracle';
+
+type BindParameterType<T extends 'postgres' | 'mysql' | 'oracle'>
+  = T extends 'postgres'
+    ? any[]
+    : T extends 'mysql'
+      ? any[]
+      : Record<string, any>;
+
 interface TagContext {
   type: TagType;
   match: string;
@@ -90,6 +111,48 @@ export class SQLBuilder {
     return result;
   }
 
+  /**
+   * 指定したテンプレートにエンティティの値をバインド可能なプレースホルダー付きSQLを生成し、
+   * バインドパラメータと共にタプル型で返却する
+   *
+   * @param {string} template
+   * @param {Record<string, any>} entity
+   * @param {BindType} bindType
+   * @returns {[string, BindParameterType<T>]}
+   */
+  public generateParameterizedSQL<T extends BindType>(template: string, entity: Record<string, any>, bindType: T): [string, BindParameterType<T>] {
+
+    let bindParams: BindParameterType<T>;
+    switch (bindType) {
+      case 'postgres':
+      case 'mysql':
+        bindParams = [] as unknown as BindParameterType<T>;
+        break;
+      case 'oracle':
+        bindParams = {} as BindParameterType<T>;
+        break;
+      default:
+        throw new Error(`Unsupported bind type: ${bindType}`);
+    }
+
+    /**
+     * 「\/* *\/」で囲まれたすべての箇所を抽出
+     */
+    const allMatchers = template.match(this.REGEX_TAG_PATTERN);
+    if (!allMatchers) {
+      return [template, bindParams];
+    }
+
+    const tagContexts = this.createTagContexts(template);
+    const pos: SharedIndex = { index: 0 };
+    const result = this.parse(pos, template, entity, tagContexts, {
+      bindType: bindType,
+      bindIndex: 1,
+      bindParams: bindParams
+    });
+    return [result, bindParams];
+  }
+
   /**
    * テンプレートに含まれるタグ構成を解析してコンテキストを返す
    *
@@ -218,9 +281,17 @@ export class SQLBuilder {
    * @param {string} template
    * @param {Record<string, any>} entity
    * @param {TagContext[]} tagContexts
+   * @param {*} [options]
+   *   ├ bindType BindType
+   *   ├ bindIndex number
+   *   ├ bindParams BindParameterType<T>
    * @returns {string}
    */
-  private parse(pos: SharedIndex, template: string, entity: Record<string, any>, tagContexts: TagContext[]): string {
+  private parse<T extends BindType>(pos: SharedIndex, template: string, entity: Record<string, any>, tagContexts: TagContext[], options?: {
+    bindType: T,
+    bindIndex: number,
+    bindParams: BindParameterType<T>
+  }): string {
     let result = '';
     for (const tagContext of tagContexts) {
       switch (tagContext.type) {
@@ -228,7 +299,7 @@ export class SQLBuilder {
           result += template.substring(pos.index, tagContext.startIndex);
           pos.index = tagContext.endIndex;
           // BEGINのときは無条件にsubに対して再帰呼び出し
-          result += this.parse(pos, template, entity, tagContext.sub);
+          result += this.parse(pos, template, entity, tagContext.sub, options);
           break;
         }
         case 'IF': {
@@ -237,7 +308,7 @@ export class SQLBuilder {
           if (this.evaluateCondition(tagContext.contents, entity)) {
             // IF条件が成立する場合はsubに対して再帰呼び出し
             tagContext.status = 10;
-            result += this.parse(pos, template, entity, tagContext.sub);
+            result += this.parse(pos, template, entity, tagContext.sub, options);
           } else {
             // IF条件が成立しない場合は再帰呼び出しせず、subのENDタグのendIndexをposに設定
             const endTagContext = tagContext.sub[tagContext.sub.length - 1];
@@ -255,7 +326,7 @@ export class SQLBuilder {
             for (const value of array) {
               // 再帰呼び出しによりposが進むので、ループのたびにposを戻す必要がある
               pos.index = tagContext.endIndex;
-              result += this.parse(pos, template, { [bindName]: value }, tagContext.sub);
+              result += this.parse(pos, template, { [bindName]: value }, tagContext.sub, options);
               // FORループするときは各行で改行する
               result += '\n';
             }
@@ -282,8 +353,61 @@ export class SQLBuilder {
         case 'BIND': {
           result += template.substring(pos.index, tagContext.startIndex);
           pos.index = tagContext.endIndex;
-          const value = this.extractValue(tagContext.contents, entity);
-          result += value == null ? '' : String(value);
+          const value = this.getProperty(entity, tagContext.contents);
+          switch (options?.bindType) {
+            case 'postgres': {
+              // PostgreSQL形式の場合、$Nでバインドパラメータを展開
+              if (Array.isArray(value)) {
+                const placeholders: string[] = [];
+                for (const item of value) {
+                  placeholders.push(`$${options.bindIndex++}`);
+                  (options.bindParams as any[]).push(item);
+                }
+                result += `(${placeholders.join(',')})`; // IN ($1,$2,$3)
+              } else {
+                result += `$${options.bindIndex++}`;
+                (options.bindParams as any[]).push(value);
+              }
+              break;
+            }
+            case 'mysql': {
+              // MySQL形式の場合、?でバインドパラメータを展開
+              if (Array.isArray(value)) {
+                const placeholders: string[] = [];
+                for (const item of value) {
+                  placeholders.push('?');
+                  (options.bindParams as any[]).push(item);
+                }
+                result += `(${placeholders.join(',')})`; // IN (?,?,?)
+              } else {
+                result += '?';
+                (options.bindParams as any[]).push(value);
+              }
+              break;
+            }
+            case 'oracle': {
+              // Oracle形式の場合、名前付きバインドでバインドパラメータを展開
+              if (Array.isArray(value)) {
+                const placeholders: string[] = [];
+                for (let i = 0; i < value.length; i++) {
+                  // 名前付きバインドで配列の場合は名前が重複する可能性があるので枝番を付与
+                  const paramName = `${tagContext.contents}_${i}`; // :projectNames_0, :projectNames_1
+                  placeholders.push(`:${paramName}`);
+                  (options.bindParams as Record<string, any>)[paramName] = value[i];
+                }
+                result += `(${placeholders.join(',')})`; // IN (:p_0,:p_1,:p3)
+              } else {
+                result += `:${tagContext.contents}`;
+                (options.bindParams as Record<string, any>)[tagContext.contents] = value;
+              }
+              break;
+            }
+            default: {
+              // generateSQLの場合
+              const escapedValue = this.extractValue(tagContext.contents, entity);
+              result += value == null ? '' : escapedValue;
+            }
+          }
           break;
         }
         default:
@@ -391,8 +515,29 @@ export class SQLBuilder {
     }
   }
 
+  /**
+   * entityで指定したオブジェクトからドットで連結されたプロパティキーに該当する値を取得する
+   *
+   * @param {Record<string, any>} entity
+   * @param {string} property
+   * @returns {any}
+   */
+  private getProperty(entity: Record<string, any>, property: string): any {
+    const propertyPath = property.split('.');
+    let value = entity;
+    for (const prop of propertyPath) {
+      if (value && value.hasOwnProperty(prop)) {
+        value = value[prop];
+      } else {
+        return undefined;
+      }
+    }
+    return value;
+  }
+
   /**
    * entityからparamで指定した値を文字列で取得する
+   * entityの値がstringの場合、SQLインジェクションの危険のある文字はエスケープする
    *
    * * 返却する値が配列の場合は丸括弧で括り、各項目をカンマで区切る
    *   ('a', 'b', 'c')
@@ -412,15 +557,7 @@ export class SQLBuilder {
     responseType?: T
   }): ExtractValueType<T> {
     try {
-      const propertyPath = property.split('.');
-      let value: any = entity;
-      for (const prop of propertyPath) {
-        if (value && value.hasOwnProperty(prop)) {
-          value = value[prop];
-        } else {
-          return undefined as ExtractValueType<T>;
-        }
-      }
+      const value = this.getProperty(entity, property);
       let result = '';
       switch (options?.responseType) {
         case 'array':