nextpay-querystring

Thư viện QueryString của NextPay - Chuyển đổi QueryString thành điều kiện select cho MongoDB và MySQL với kiểm soát bảo mật và tránh SQL injection.

🚀 Tính năng

- ✅ Chuyển đổi QueryString thành MongoDB criteria
- ✅ Chuyển đổi QueryString thành MySQL WHERE clause
- ✅ Hỗ trợ nhiều loại operator: ==, !=, >, >=, <, <=, IN, NIN, BETWEEN, LIKE
- ✅ Validation field và data type
- ✅ Bảo mật chống SQL injection
- ✅ Hỗ trợ TypeScript
- ✅ Lightweight và performant

📦 Cài đặt

``bash
npm install nextpay-querystring
`

🎯 Cách sử dụng

$3

`typescript
// ✅ sử dụng cho mongodb
import { toMongoCriteria, FieldDescription, DataType } from 'nextpay-querystring';

// ✅ sử dụng cho Mysql
import { toMySqlCriteria, FieldDescription, DataType } from 'nextpay-querystring';
`

$3

`typescript
const fieldDescriptions: FieldDescription[] = [
{
field: '_id',
required: true,
dataType: DataType.STRING,
maxOccurrence: 5,
mapTo: '_id',
},
{
field: 'title',
required: true,
dataType: DataType.STRING,
maxOccurrence: 5,
mapTo: 'title',
},
{
field: 'status',
required: true,
dataType: DataType.STRING,
maxOccurrence: 5,
mapTo: 'status',
},
{
field: 'createdAt',
required: true,
dataType: DataType.DATE,
maxOccurrence: 5,
mapTo: 'createdAt',
},
{
field: 'isActive',
required: true,
dataType: DataType.BOOLEAN,
maxOccurrence: 5,
mapTo: 'isActive',
},
];
`

$3

`typescript
const queryString = "{title} == '''MACQ''' AND {status} IN ['''OPEN''', '''ON-HOLD'''] AND {isActive} == true";

const mongoCriteria = toMongoCriteria(queryString, fieldDescriptions);
const whereCondition = JSON.parse(mongoCriteria);

// Kết quả: {title: "MACQ", status: {$in: ["OPEN", "ON-HOLD"]}, isActive: true}

const result = await collection.find(whereCondition);
`

$3

`typescript
const queryString = "{title} == '''MACQ''' AND {status} IN ['''OPEN''', '''ON-HOLD'''] AND {isActive} == true";

const mysqlCriteria = toMySqlCriteria(queryString, fieldDescriptions);

// Kết quả: title = 'MACQ' AND status IN ('OPEN', 'ON-HOLD') AND isActive = true

const result = await connection.query(SELECT * FROM table WHERE ${mysqlCriteria});
`

$3

`typescript
import { toMongoCriteria, toMySqlCriteria, FieldDescription, DataType } from 'nextpay-querystring';

const fieldDescriptions: FieldDescription[] = [
{
field: 'status',
required: true,
dataType: DataType.STRING,
maxOccurrence: 5,
mapTo: 'status',
},
{
field: 'id',
required: true,
dataType: DataType.INTEGER,
maxOccurrence: 5,
mapTo: 'id',
},
{
field: 'title',
required: true,
dataType: DataType.STRING,
maxOccurrence: 5,
mapTo: 'title',
},
{
field: 'category',
required: false,
dataType: DataType.STRING,
maxOccurrence: 5,
mapTo: 'category',
},
];

// Query với grouping
const queryString = "{status} == '''ACTIVE''' AND ({id} == 1 OR {title} LIKE '''admin''') AND ({priority} >= 3 OR {category} == '''VIP''')";

// MongoDB
const mongoResult = toMongoCriteria(queryString, fieldDescriptions);
const mongoCriteria = JSON.parse(mongoResult);
console.log('MongoDB:', mongoCriteria);
// Output: {
// $and: [
// { status: 'ACTIVE' },
// { $or: [{ id: 1 }, { title: { $regex: 'admin', $options: 'i' } }] },
// { $or: [{ priority: { $gte: 3 } }, { category: 'VIP' }] }
// ]
// }

// MySQL
const mysqlResult = toMySqlCriteria(queryString, fieldDescriptions);
console.log('MySQL:', mysqlResult);
// Output: (status = "ACTIVE") AND ((id = 1) OR (title LIKE %"admin"%)) AND ((priority >= 3) OR (category = "VIP"))
`

📝 Quy tắc viết QueryString

$3


`
{}
`

$3

| Kiểu dữ liệu | Cú pháp | Ví dụ |
|-------------|---------|-------|
| String | '''value''' | {title} == '''MACQ''' |
| Number | value | {id} == 1 |
| Boolean | true/false | {isActive} == true |
| Date | #value# | {createdAt} == #2025-01-15# |

$3

#### Comparison Operators
- == - Equals
- != - Not equals
- === - Triple equals
- > - Greater than
- >= - Greater than or equal
- < - Less than
- <= - Less than or equal

#### Array Operators
- IN - In array
- NIN - Not in array
- BETWEEN - Between range
- NBETWEEN - Not between range

#### String Operators
- like% - Starts with
- like - Contains
- %like - Ends with
- nlike - Not contains
- nlike% - Not starts with
- %nlike - Not ends with

#### NULL Operators
- is_null - Is null
- is_not_null - Is not null

#### Logical Operators
- AND - Logical AND
- OR - Logical OR
- NOT - Logical NOT

$3

`typescript
const complexQuery =
{title} == '''MACQ''' AND
{id} == 1 AND
{status} IN ['''OPEN''', '''ON-HOLD'''] AND
{isPrivate} == true AND
{dueDate} == #2025-08-25# AND
{description} like '''important'''
;
`

$3

`typescript
// String negative operators
const negativeStringQuery =
{title} nlike '''admin''' AND
{description} nlike% '''draft''' AND
{filename} %nlike '''.tmp'''
;

// Range negative operator
const negativeRangeQuery =
{priority} nbetween [1, 5] AND
{createdAt} nbetween [#2024-01-01#, #2024-12-31#]
;

// Complex negative query
const complexNegativeQuery =
{title} nlike '''admin''' AND
{status} nbetween ['''DELETED''', '''ARCHIVED'''] AND
({priority} >= 3 OR {category} == '''VIP''')
;

// NULL operators
const nullQuery =
{title} is_not_null AND
{description} is_null AND
{priority} >= 3
;

// Complex query with NULL operators
const complexNullQuery =
({title} is_null OR {description} is_not_null) AND
{status} == '''ACTIVE''' AND
{priority} is_not_null
;

// BETWEEN operator examples
const betweenQuery =
{priority} between [1, 5] AND
{createdAt} between [#2024-01-01#, #2024-12-31#] AND
{status} between ['''ACTIVE''', '''PENDING''']
;
`

$3

`typescript
// ✅ Simple OR group
const orGroup = "({id} == 1 OR {id} == 2)";

// ✅ AND với OR group
const andWithOr = "{status} == '''ACTIVE''' AND ({id} == 1 OR {title} LIKE '''tan''')";

// ✅ Nested groups
const nestedGroups = "({status} == '''ACTIVE''' AND ({id} == 1 OR {id} == 2)) OR ({category} == '''VIP''')";

// ✅ Multiple groups
const multipleGroups = "({id} == 1 OR {id} == 2) AND ({status} == '''ACTIVE''' OR {status} == '''PENDING''')";

// ✅ Group với IN operator
const groupWithIn = "({id} == 1 OR {id} == 2) AND {status} IN ['''ACTIVE''', '''PENDING''']";

// ✅ Complex nested groups
const complexNested = "({status} == '''ACTIVE''' AND ({id} == 1 OR {id} == 2)) AND ({priority} >= 3 OR ({category} == '''VIP''' AND {isActive} == true))";
`

🔧 Data Types

`typescript
enum DataType {
STRING, // String values
INTEGER, // Integer numbers
DOUBLE, // Decimal numbers
BOOLEAN, // true/false
DATE, // Date values
}
`

🛡️ Bảo mật

- Field Validation: Chỉ cho phép sử dụng các field đã được khai báo
- Data Type Validation: Kiểm tra kiểu dữ liệu phù hợp
- SQL Injection Prevention: Escape và validate tất cả input
- Occurrence Limit: Giới hạn số lần xuất hiện của mỗi field

🧪 Testing

`bash


Chạy tests

npm test

Chạy tests với watch mode

npm run test:watch

Chạy tests với coverage

npm test -- --coverage
`

📦 Exports

$3

- toMongoCriteria(queryString: string, fieldDescriptions: FieldDescription[]): string - Chuyển đổi QueryString thành MongoDB criteria
- toMySqlCriteria(queryString: string, fieldDescriptions: FieldDescription[]): string - Chuyển đổi QueryString thành MySQL WHERE clause

$3

- FieldDescription - Interface cho field description
- FieldDescriptionContainer - Class container cho field descriptions
- DataType - Enum cho các kiểu dữ liệu (STRING, INTEGER, DOUBLE, BOOLEAN, DATE)

$3

- FieldDescriptionType - Alias cho FieldDescription

📚 API Reference

$3

Chuyển đổi QueryString thành MongoDB criteria dạng JSON string.

$3

Chuyển đổi QueryString thành MySQL WHERE clause.

$3

`typescript
interface FieldDescription {
readonly field: string; // Tên field trong QueryString
readonly required: boolean; // Field có bắt buộc không
readonly dataType: DataType; // Kiểu dữ liệu
readonly maxOccurrence: number; // Số lần xuất hiện tối đa
readonly mapTo: string; // Tên field trong database
}
`

👨‍💻 Tác giả

- Username: Mvtcode - Tanmv - MacTan
- Email: tanmv@mpos.vn

🤝 Contributing

1. Fork project
2. Tạo feature branch (git checkout -b feature/AmazingFeature)
3. Commit changes (git commit -m 'Add some AmazingFeature')
4. Push to branch (git push origin feature/AmazingFeature`)
5. Tạo Pull Request

📄 License

MIT License - xem file LICENSE để biết thêm chi tiết.

🆘 Support

Nếu gặp vấn đề, vui lòng tạo issue tại GitHub Issues.