Node-Qsbuilder

Universal SQL Query String Builder for Node.js (sqlite3, mariadb, ...)

개요

Node-Qsbuilder는 다양한 데이터베이스(SQLITE, MariaDB 등)에서 공통적으로 사용할 수 있는 쿼리 문자열 생성기입니다. TypeScript 기반으로, DDL/DML/JOIN 등 다양한 쿼리 유형을 안전하고 일관되게 생성할 수 있습니다.

주요 기능

• DB별 쿼리 빌더: Sqlite, MariaDB 등
• SELECT, INSERT, UPDATE, DELETE, CREATE TABLE, DROP TABLE 등 지원
• WHERE, ORDER BY, LIMIT, OFFSET, JOIN 등 옵션 지원
• 타입 안전성(TypeScript)
• 테스트 및 예제 코드 제공

설치

npm install node-qsbuilder
# 또는 로컬 개발 시
npm install ../Node-Qsbuilder

사용 예시 (TypeScript/ESM)

import { SqliteQueryBuilder, MariadbQueryBuilder } from "node-qsbuilder";

const sqliteBuilder = new SqliteQueryBuilder();
const mariadbBuilder = new MariadbQueryBuilder();

// SELECT
console.log(
    sqliteBuilder.select("users", ["id", "name"], {
        where: [{ field: "id", operator: ">", value: 10 }],
        orderBy: [{ field: "name", direction: "ASC" }],
        limit: 5,
    })
);

// INSERT
console.log(sqliteBuilder.insert("users", { id: 1, name: "kim" }));

// UPDATE
console.log(
    sqliteBuilder.update(
        "users",
        { name: "lee" },
        { where: [{ field: "id", operator: "=", value: 1 }] }
    )
);

// DELETE
console.log(
    sqliteBuilder.delete("users", {
        where: [{ field: "id", operator: "=", value: 1 }],
    })
);

// CREATE TABLE
console.log(
    sqliteBuilder.createTable({
        name: "users",
        columns: [
            {
                name: "id",
                type: "INTEGER",
                primaryKey: true,
                autoIncrement: true,
            },
            { name: "name", type: "TEXT", notNull: true },
        ],
    })
);

// JOIN
console.log(
    sqliteBuilder.select("users", ["users.id", "orders.amount"], {
        joins: [
            { type: "INNER", table: "orders", on: "users.id = orders.user_id" },
        ],
        where: [{ field: "users.id", operator: "=", value: 1 }],
    })
);

CommonJS 사용 예시

const { SqliteQueryBuilder, MariadbQueryBuilder } = require("node-qsbuilder");

const builder = new SqliteQueryBuilder();
const sql = builder.select("users", ["id", "name"], { limit: 10 });
console.log(sql);

더 많은 예제는 examples/queryBuilderExamples.ts 참고

API Reference

QueryBuilder 공통 메서드 (추상)

| 메서드 | 설명 | 파라미터 | 반환값 | | --------------------------------- | ---------------------- | ---------------------------------------------------------------- | ------------ | | select(table, columns?, options?) | SELECT 쿼리 생성 | table: string, columns?: string[], options?: QueryOptions | string (SQL) | | insert(table, data) | INSERT 쿼리 생성 | table: string, data: Record<string, any> | string (SQL) | | update(table, data, options?) | UPDATE 쿼리 생성 | table: string, data: Record<string, any>, options?: QueryOptions | string (SQL) | | delete(table, options?) | DELETE 쿼리 생성 | table: string, options?: QueryOptions | string (SQL) | | createTable(schema) | CREATE TABLE 쿼리 생성 | schema: TableSchema | string (SQL) | | dropTable(table) | DROP TABLE 쿼리 생성 | table: string | string (SQL) | | alterTable(table, changes) | ALTER TABLE 쿼리 생성 | table: string, changes: any | string (SQL) |

QueryOptions 타입

interface QueryOptions {
    where?: QueryCondition[];
    orderBy?: QueryOrder[];
    limit?: number;
    offset?: number;
    joins?: QueryJoin[];
}

TableSchema 타입

interface TableSchema {
    name: string;
    columns: TableColumn[];
}

TableColumn 타입

interface TableColumn {
    name: string;
    type: string;
    primaryKey?: boolean;
    notNull?: boolean;
    autoIncrement?: boolean;
    default?: string | number | boolean | null;
}

SqliteQueryBuilder / MariadbQueryBuilder 메서드별 상세 예시

select

builder.select("users", ["id", "name"], {
    where: [{ field: "id", operator: ">", value: 10 }],
    orderBy: [{ field: "name", direction: "ASC" }],
    limit: 5,
    offset: 0,
    joins: [
        { type: "INNER", table: "orders", on: "users.id = orders.user_id" },
    ],
});
// => SELECT id, name FROM users INNER JOIN orders ON users.id = orders.user_id WHERE id > 10 ORDER BY name ASC LIMIT 5 OFFSET 0

insert

builder.insert("users", { id: 1, name: "kim" });
// => INSERT INTO users (id, name) VALUES (:id, :name)

update

builder.update(
    "users",
    { name: "lee" },
    { where: [{ field: "id", operator: "=", value: 1 }] }
);
// => UPDATE users SET name = :name WHERE id = 1

delete

builder.delete("users", { where: [{ field: "id", operator: "=", value: 1 }] });
// => DELETE FROM users WHERE id = 1

createTable

builder.createTable({
    name: "users",
    columns: [
        { name: "id", type: "INTEGER", primaryKey: true, autoIncrement: true },
        { name: "name", type: "TEXT", notNull: true },
    ],
});
// => CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT NOT NULL)

dropTable

builder.dropTable("users");
// => DROP TABLE IF EXISTS users

alterTable (컬럼 추가 예시)

builder.alterTable("users", { addColumn: { name: "age", type: "INTEGER" } });
// => ALTER TABLE users ADD COLUMN age INTEGER

각 메서드의 파라미터 타입, 옵션, 반환값, 예시는 [src/types/index.ts]와 [examples/queryBuilderExamples.ts]를 참고하세요.

테스트

npm install
npx jest

폴더 구조

• src/ : 쿼리 빌더 소스
• tests/ : 단위 테스트
• examples/ : 사용 예제

라이선스

MIT