@asla/yoursql 0.6.0 → 0.6.2

package/README.md

@@ -5,15 +5,75 @@
 
 [package]: https://img.shields.io/badge/package-ESM-ffe536.svg
 [package-url]: https://nodejs.org/api/esm.html
-[npm]: https://img.shields.io/npm/v/yoursql.svg
-[npm-url]: https://npmjs.com/package/yoursql
+[npm]: https://img.shields.io/npm/v/@asla/yoursql.svg
+[npm-url]: https://npmjs.com/package/@asla/yoursql
 [jsr]: https://jsr.io/badges/@asla/yoursql
 [jsr-url]: https://jsr.io/@asla/yoursql
-[node]: https://img.shields.io/node/v/yoursql.svg
+[node]: https://img.shields.io/node/v/@asla/yoursql.svg
 [node-url]: https://nodejs.org
-[size]: https://packagephobia.com/badge?p=yoursql
-[size-url]: https://packagephobia.com/result?p=yoursql
+[size]: https://packagephobia.com/badge?p=@asla%2Fyoursql
+[size-url]: https://packagephobia.com/result?p=@asla%2Fyoursql
 
 SQL 生成器
 
 [API 文档](https://jsr.io/@asla/yoursql/doc)
+
+### 安全转将 JS 值转换为 SQL 值，避免 SQL 注入
+
+导入
+
+```ts
+import { v } from "@asla/yoursql";
+```
+
+默认情况下，支持 PostgresSQL, 因为不同数据库的值转换有些差异，如果使用其他数据库，可能需要配置对象转换器
+
+```ts
+v(1); // "1"
+v(1n); // "1"
+v("te'xt"); // "'te''xt'"
+v(new Date()); // "'2024-11-30T05:08:33.112Z'"
+v([1, 2, 3]); // "ARRAY[1,2,3]"
+v({ id: "abc", size: 1 }); // "'{\"id\":\"abc\",\"size\":1}'"
+v(null); // "NULL"
+v(undefined); // "DEFAULT"
+```
+
+如果传入 String 对象，将保留其字符串值，不会进行任何转换
+
+```ts
+v(new String("1+1")); // "1+1"
+```
+
+你可以自定义对象到字符串的转换, 例如，你想将 Set 转换为 PostgresSql 的 ARRAY[] 输入格式
+
+```ts
+v.setTransformer(Set, function (value: Set) {
+  return this.v(Array.from(value));
+});
+```
+
+转换对象数组
+
+```ts
+const values = [{ a: 1, b: 2 }, { c: 3 }];
+
+// 这将自动选择数组中所有键的并集
+v.objectListToValuesList(values); // "(1,2,null),(null,null,3)"
+
+// 或者你可以指定选择键并指定顺序
+v.objectListToValuesList(values, ["c", "b"]); // "(null,2),(3,3)"
+```
+
+### 生成 SQL 语句
+
+```ts
+import { Selection, v } from "@asla/yoursql";
+
+const searchName = "Bob";
+const s = Selection.from("user", "u")
+  .innerJoin("role", "r", "u.id=r.user_id")
+  .select({ uid: "u.id", rid: "r.id", example: "u.id||r.id" }) // SELECT u.id AS uid, r.id AS rid u.id||u.id AS example
+  .where(`u.name LIKE %${v(searchName)}%`)
+  .toString();
+```

package/dist/mod.d.ts

@@ -6,4 +6,10 @@ export * from "./select/selectable.ts";
 export * from "./select/TableQuery.ts";
 export * from "./util.ts";
 export * from "./your_table/mod.ts";
+import { SqlValueFn } from "./sql_value/sql_value.ts";
+/**
+ * 默认的 SqlValuesCreator 实列
+ * @public
+ */
+export declare const v: SqlValueFn;
 //# sourceMappingURL=mod.d.ts.map

package/dist/mod.js

@@ -284,21 +284,13 @@ class SqlQueryStatement extends SqlSelectable {
 }
 _SqlQueryStatement_sql = new WeakMap();
 
-var _SqlRaw_value, _YourValuesAs_asName, _YourValuesAs_valuesStr, _YourValuesAs_sql;
+var _YourValuesAs_asName, _YourValuesAs_valuesStr, _YourValuesAs_sql;
 /**
- * SQL 原始字符对象
+ * SQL 原始字符类。可以使用 String 类代替，这只是为了推断类型
  * @public
  */
-class SqlRaw {
-    constructor(value) {
-        _SqlRaw_value.set(this, void 0);
-        __classPrivateFieldSet(this, _SqlRaw_value, value, "f");
-    }
-    toString() {
-        return __classPrivateFieldGet(this, _SqlRaw_value, "f");
-    }
+class SqlRaw extends String {
 }
-_SqlRaw_value = new WeakMap();
 /**
  * SQL value 生成器
  * @public
@@ -320,28 +312,42 @@ class SqlValuesCreator {
     /**
      * @param map - 自定义对象转换
      */
-    constructor(map = new Map()) {
-        this.map = map;
+    constructor(map) {
+        this._map = new Map(map);
     }
-    /** 设置转换器 */
-    setTransformer(type, transformer) {
-        if (!transformer)
-            this.map.delete(type);
-        else
-            this.map.set(type, transformer);
+    setTransformer(type_map, encoder) {
+        if (typeof type_map === "function") {
+            if (encoder)
+                this._map.set(type_map, encoder);
+            else
+                this._map.delete(type_map);
+        }
+        else {
+            for (const [type, encoder] of type_map) {
+                if (typeof type === "function" && typeof encoder === "function") {
+                    this._map.set(type, encoder);
+                }
+            }
+        }
     }
-    /** 将 JS 对象转为 SQL 的字符值的形式 。 undefined 将被转换为 DEFAULT */
-    toSqlStr(value, expectType) {
+    /**
+     * 将 JS 对象转为 SQL 的字符值的形式 。 undefined 将被转换为 DEFAULT
+     * ```ts
+     *  const v=SqlValuesCreator.create()
+     *  v() 和 v.toSqlStr() 是等价的
+     * ```
+     */
+    toSqlStr(value, assertType) {
         let basicType;
-        if (expectType) {
-            if (typeof expectType === "function") {
-                let type = this.map.get(expectType);
+        if (assertType) {
+            if (typeof assertType === "function") {
+                let type = this._map.get(assertType);
                 if (!type)
                     throw new Error("类型不存在");
                 return type.call(this, value);
             }
             else {
-                basicType = expectType;
+                basicType = assertType;
             }
         }
         else
@@ -358,7 +364,7 @@ class SqlValuesCreator {
             case "object": {
                 if (value === null)
                     return "NULL";
-                if (value instanceof SqlRaw)
+                if (value instanceof String)
                     return value.toString();
                 return this.getObjectType(value).call(this, value);
             }
@@ -372,9 +378,9 @@ class SqlValuesCreator {
     }
     /** 获取值对应的 SqlValueEncoder */
     getObjectType(value) {
-        for (const Class of this.map.keys()) {
+        for (const Class of this._map.keys()) {
             if (value instanceof Class)
-                return this.map.get(Class);
+                return this._map.get(Class);
         }
         return this.defaultObject;
     }
@@ -947,4 +953,10 @@ class YourTable extends DbTableQuery {
     }
 }
 
-export { ColumnMeta, CustomDbType, DbTable, DbTableQuery, Selection, SqlQueryStatement, SqlRaw, SqlSelectable, SqlValuesCreator, TypeChecker, YourTable, YourTypeMap, getObjectListKeys, having, orderBy, pgSqlTransformer, selectColumns, where };
+/**
+ * 默认的 SqlValuesCreator 实列
+ * @public
+ */
+const v = SqlValuesCreator.create(pgSqlTransformer);
+
+export { ColumnMeta, CustomDbType, DbTable, DbTableQuery, Selection, SqlQueryStatement, SqlRaw, SqlSelectable, SqlValuesCreator, TypeChecker, YourTable, YourTypeMap, getObjectListKeys, having, orderBy, pgSqlTransformer, selectColumns, v, where };

package/dist/sql_value/sql_value.d.ts

@@ -1,33 +1,33 @@
 import { SqlSelectable } from "../select/selectable.ts";
 declare const SQL_RAW: unique symbol;
 /**
- * SQL 原始字符对象
+ * SQL 原始字符类。可以使用 String 类代替，这只是为了推断类型
  * @public
  */
-export declare class SqlRaw<T = any> {
-    #private;
-    constructor(value: string);
-    toString(): string;
+export declare class SqlRaw<T = any> extends String {
     /** 保留以推断类型 */
     protected [SQL_RAW]: T;
 }
-/** @public */
+/** @public js 对象到编码函数的映射*/
 export type JsObjectMapSql = Map<new (...args: any[]) => any, SqlValueEncoder>;
-/** @public */
+/** @public 将 js 值转为 SQl 字符串的函数*/
 export type SqlValueEncoder<T = any> = (this: SqlValuesCreator, value: T) => string;
-/** @public */
+/** @public 断言类型 */
 export type ManualType = "bigint" | "number" | "string" | "boolean" | "object" | (new (...args: any[]) => any);
 /** @public */
-export interface SqlValueFn {
-    /** 将 JS 对象转为 SQL 的字符值的形式 。 undefined 将被转换为 DEFAULT */
-    (value: any, expectType?: ManualType): string;
-}
+export type SqlValueFn = SqlValuesCreator & {
+    /**
+     * 安全将 JS 对象转为 SQL 的字符值的形式，可避免 SQL 注入。
+     * undefined 将被转换为 DEFAULT
+     */
+    (value: any, assertType?: ManualType): string;
+};
 /**
  * SQL value 生成器
  * @public
  */
 export declare class SqlValuesCreator {
-    static create(map?: JsObjectMapSql): SqlValuesCreator & SqlValueFn;
+    static create(map?: JsObjectMapSql): SqlValueFn;
     /**
      * 将字符串转为 SQL 的字符串值的形式(单引号会被转义)。
      * @example 输入 a'b'c , 返回 a''b''c.
@@ -38,15 +38,22 @@ export declare class SqlValuesCreator {
      */
     constructor(map?: JsObjectMapSql);
     /** 设置转换器 */
-    setTransformer<T>(type: new (...args: any[]) => T, transformer?: SqlValueEncoder): void;
-    private readonly map;
-    /** 将 JS 对象转为 SQL 的字符值的形式 。 undefined 将被转换为 DEFAULT */
-    toSqlStr(value: any, expectType?: ManualType): string;
+    setTransformer(type: new (...args: any[]) => any, encoder?: SqlValueEncoder): void;
+    setTransformer(map: JsObjectMapSql): void;
+    private readonly _map;
+    /**
+     * 将 JS 对象转为 SQL 的字符值的形式 。 undefined 将被转换为 DEFAULT
+     * ```ts
+     *  const v=SqlValuesCreator.create()
+     *  v() 和 v.toSqlStr() 是等价的
+     * ```
+     */
+    toSqlStr(value: any, assertType?: ManualType): string;
     /** 获取值对应的 SqlValueEncoder */
     getObjectType(value: object): SqlValueEncoder;
     protected defaultObject(value: object): string;
     /**
-     * 将对象列表转为 SQL 的 VALUES
+     * 将对象列表转为 SQL 的 VALUES。
      * @example 返回示例： " (...),(...) "
      * @param keys - 选择的键。如果指定了 keys, 值为 undefined 的属性将自动填充为 null; 如果未指定 keys，将选择 objectList 所有不是 undefined 项的键的并集
      */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@asla/yoursql",
-  "version": "0.6.0",
+  "version": "0.6.2",
   "description": "",
   "type": "module",
   "types": "./dist/mod.d.ts",