@asla/yoursql 0.8.8 → 0.8.10

package/README.md

@@ -18,17 +18,16 @@ SQL 生成器
 
 [API 文档](https://jsr.io/@asla/yoursql/doc)
 
-### 安全转将 JS 值转换为 SQL 值，避免 SQL 注入
+### v()
 
-导入
+安全转将 JS 值转换为 SQL 值，避免 SQL 注入
+
+`v` 函数能够将 JS 值转换为 SQL 的文本形式。\
+默认情况下，支持 PostgresSQL, 因为不同数据库的值转换有些差异，如果使用其他数据库，可能需要配置对象到字符串的自定义转换器
 
 ```ts
 import { v } from "@asla/yoursql";
-```
 
-默认情况下，支持 PostgresSQL, 因为不同数据库的值转换有些差异，如果使用其他数据库，可能需要配置对象转换器
-
-```ts
 v(1); // "1"
 v(1n); // "1"
 v("te'xt"); // "'te''xt'"
@@ -37,32 +36,86 @@ v([1, 2, 3]); // "ARRAY[1,2,3]"
 v({ id: "abc", size: 1 }); // "'{\"id\":\"abc\",\"size\":1}'"
 v(null); // "NULL"
 v(undefined); // "DEFAULT"
+
+const params = { id: 3 };
+const sql = `SELECT * FROM user WHERE user_id=${v(params.id)}`;
 ```
 
-如果传入 String 对象，将保留其字符串值，不会进行任何转换
+如果传入 String 对象，将保留其字符串值，不会进行任何转换， 这在有些需要原生SQL操作的场景下非常有用
 
 ```ts
+import { v } from "@asla/yoursql";
+
 v(new String("1+1")); // "1+1"
 ```
 
 你可以自定义对象到字符串的转换, 例如，你想将 Set 转换为 PostgresSql 的 ARRAY[] 输入格式
 
 ```ts
+import { v } from "@asla/yoursql";
+
 v.setTransformer(Set, function (value: Set) {
   return this.v(Array.from(value));
 });
+
+v(new Set([1, 2, 3])); // "ARRAY[1,2,3]"
 ```
 
-转换对象数组
+#### v.toValues()
+
+转换数组为 values 的单个值
 
 ```ts
+import { v } from "@asla/yoursql";
+v.toValues([1, "abc", null, undefined, { key: "value" }]); // `1,'abc',NULL,DEFAULT,'{"key":"value"}'`
+```
+
+#### v.objectToValues()
+
+转换对象为 values 的单个值
+
+```ts
+import { v } from "@asla/yoursql";
+const obj = { a: "a1", b: "b1", c: undefined, d: "d1" };
+v.objectToValues(obj); // "'a1','b1',DEFAULT,'d1'"
+v.objectToValues(obj, ["b", "a"]); // "'b1','a1'"
+v.objectToValues(obj, [{ a: "TEXT", b: {} }]); // 'a1'::TEXT,'b1'"
+```
+
+#### v.objectListToValuesList()
+
+转换对象数组为 values
+
+```ts
+import { v } from "@asla/yoursql";
+
 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)"
+const valueStr = v.objectListToValuesList(values, ["c", "b"]); // "(null,2),(3,3)"
+
+const sql = `INSERT INTO user(name, role) VALUES ${valueStr}`;
+```
+
+#### v.createValues()
+
+```ts
+const objectList = [{ age: 1, name: "hhh" }, { age: 2, name: "row2" }, { age: 3, name: "row3" }, {}];
+
+v.createValues("customName", objectList, {
+  age: { sqlType: "INT", sqlDefault: "MAXIMUM(1,2)" },
+  name: "TEXT",
+});
+//这将返回
+`(VALUES
+  (1::INT,'hhh'::TEXT),
+  (2,'row2'),
+  (3,'row3'),
+  (MAXIMUM(1,2),NULL))
+  AS customName(age,name)`;
 ```
 
 ### 生成 SQL 语句
@@ -78,6 +131,17 @@ const s = Selection.from("user", "u")
   .toString();
 ```
 
+查看 [select](./docs/select.md) 用法
+查看 [insert/update/delete](./docs/table.md) 用法
+
+#### Constructable
+
+toto
+
+#### ConditionParam
+
+toto
+
 ### client 抽象类
 
 yoursql 还导出了一些抽象类，实现抽象类后可以方便的进行数据查询
@@ -98,7 +162,12 @@ import {
 
 ```ts
 class YourQuery extends DbQuery {
-  // implement
+  query<T = any>(sql: StringLike): Promise<QueryRowsResult<T>> {
+    // implement
+  }
+  multipleQuery<T extends MultipleQueryResult = MultipleQueryResult>(sql: StringLike): Promise<T> {
+    // implement
+  }
 }
 const db: DbQuery = new YourQuery();
 ```
@@ -190,3 +259,62 @@ for await (const element of cursor) {
   if (conditions) break; //提前关闭游标
 }
 ```
+
+### 扩展查询链
+
+```ts
+import { v, SqlStatement, SqlStatementDataset, SqlValuesCreator } from "@asla/yoursql";
+import type { DbCursor, QueryResult, QueryRowsResult } from "@asla/yoursql/client";
+
+declare const pool: DbQueryPool = new YourPool(); // 你需要实现一个 DbQueryPool
+
+export interface QueryableSql {
+  query(): Promise<QueryResult>;
+  queryCount(): Promise<number>;
+}
+export interface QueryableDataSql<T> extends QueryableSql {
+  queryRows(): Promise<T[]>;
+  queryMap<K>(key: string): Promise<Map<K, T>>;
+  cursor(): Promise<DbCursor<T>>;
+}
+declare module "@asla/yoursql" {
+  interface SqlStatement extends QueryableSql {}
+  interface SqlStatementDataset<T> extends QueryableDataSql<T> {}
+}
+const base: QueryableSql = {
+  queryCount(): Promise<number> {
+    return dbPool.queryCount(this.toString());
+  },
+  query(): Promise<QueryRowsResult<any>> {
+    return dbPool.query<any>(this);
+  },
+};
+const obj: QueryableDataSql<any> = {
+  ...base,
+  cursor(): Promise<DbCursor<any>> {
+    return dbPool.cursor(this.toString());
+  },
+  queryMap<K>(key: string): Promise<Map<K, any>> {
+    return dbPool.queryMap(this.toString(), key);
+  },
+  queryRows(): Promise<any[]> {
+    return dbPool.queryRows(this.toString());
+  },
+};
+
+Object.assign(SqlStatement.prototype, base);
+Object.assign(SqlStatementDataset.prototype, obj);
+```
+
+现在，以及扩展了 SqlStatement 和 SqlStatementDataset 类的原型链，你可以从 select 等语句直接调用查询方法了
+
+```ts
+import { Selection, v } from "@asla/yoursql";
+
+const searchName = "Bob";
+const rows = await Selection.from("user", "u")
+  .innerJoin("role", "r", "u.id=r.user_id")
+  .select({ uid: "u.id", rid: "r.id", example: "u.id||r.id" })
+  .where(`u.name LIKE %${v(searchName)}%`)
+  .queryRows();
+```

package/dist/sql_gen/mod.js

@@ -1,6 +1,5 @@
 import { pgSqlTransformer } from './sql_value/db_type.js';
 import { SqlValuesCreator } from './sql_value/sql_value.js';
-export { SqlRaw } from './sql_value/sql_value.js';
 export { DbTable } from './select/DbTable.js';
 export { Selection, SqlSelectChain } from './select/query_chain_select.js';
 export { SqlStatement, SqlStatementDataset, SqlTextStatementDataset } from './select/chain_base.js';

package/dist/sql_gen/select/type.d.ts

@@ -1,5 +1,5 @@
-import { SqlRaw } from "../sql_value/sql_value.ts";
 /**
+ * @deprecated 已废弃，改用 ToInsertType
  * @public
  * @param T - 表格查询类型
  * @param Rq - 默认选择
@@ -14,9 +14,22 @@ export type PickColumn<T extends {
 } & {
     [key in Pa]?: T[key];
 };
+/**
+ * 推断表插入类型
+ * @public
+ * @param T - 表格创建类型
+ * @param Pa - 可选列
+ */
+export type ToInsertType<T extends {
+    [key: string]: any;
+}, Pa extends keyof T = never> = {
+    [key in keyof T as key extends Pa ? never : null extends T[key] ? never : key]: T[key];
+} & {
+    [key in keyof T as null extends T[key] ? key : key extends Pa ? key : never]?: T[key];
+};
 /** @public */
 export type UpdateRowValue<T extends object> = {
-    [key in keyof T]?: T[key] | SqlRaw;
+    [key in keyof T]?: T[key] | String;
 };
 /** @public */
 export type OrderValue = "ASC" | "DESC";

package/dist/sql_gen/sql_value/sql_value.d.ts

@@ -1,13 +1,4 @@
 import { SqlStatementDataset } from "../select/chain_base.ts";
-declare const SQL_RAW: unique symbol;
-/**
- * SQL 原始字符类。可以使用 String 类代替，这只是为了推断类型
- * @public
- */
-export declare class SqlRaw<T = any> extends String {
-    /** 保留以推断类型 */
-    protected [SQL_RAW]: T;
-}
 /** @public js 对象到编码函数的映射*/
 export type JsObjectMapSql = Map<new (...args: any[]) => any, SqlValueEncoder>;
 /** @public 将 js 值转为 SQl 字符串的函数*/
@@ -62,6 +53,7 @@ export declare class SqlValuesCreator {
      * 将对象列表转为 SQL 的 VALUES。
      * @example 返回示例： " (...),(...) "
      * @param keys - 选择的键。如果指定了 keys, 值为 undefined 的属性将自动填充为 null; 如果未指定 keys，将选择 objectList 所有不是 undefined 项的键的并集
+     * @param keepUndefinedKey - 是否保留 undefined 的键。默认值为 false，如果为 true , 数组的某一个字段均为 undefined时，将忽略字段,
      */
     objectListToValuesList<T extends object>(objectList: T[], keys?: readonly (keyof T)[] | {
         [key in keyof T]?: string | undefined | ColumnToValueConfig;
@@ -77,7 +69,10 @@ export declare class SqlValuesCreator {
     private _internalObjectToValues;
     /**
      * 将数组列表转为 SQL 的一个 value
-     * @example 返回示例： " 'abc', '6', 'now()' "
+     * @example
+     * ```ts
+     *  v.toValues([1, "abc", null, undefined, { key: "value" }]) // `1,'abc',NULL,DEFAULT,'{"key":"value"}'`
+     * ```
      */
     toValues(values: readonly any[]): string;
     /**
@@ -103,5 +98,4 @@ export type ColumnToValueConfig = {
     sqlType?: string;
     assertJsType?: AssertJsType;
 };
-export {};
 //# sourceMappingURL=sql_value.d.ts.map

package/dist/sql_gen/sql_value/sql_value.js

@@ -1,12 +1,6 @@
 import { getObjectListKeys } from '../util.js';
 import { SqlStatementDataset } from '../select/chain_base.js';
 
-/**
- * SQL 原始字符类。可以使用 String 类代替，这只是为了推断类型
- * @public
- */
-class SqlRaw extends String {
-}
 /**
  * SQL value 生成器
  * @public
@@ -84,7 +78,7 @@ class SqlValuesCreator {
             case "string":
                 return SqlValuesCreator.string(value);
             case "boolean":
-                return value.toString();
+                return value ? "TRUE" : "FALSE";
             case "object": {
                 if (value instanceof String)
                     return value.toString();
@@ -203,13 +197,20 @@ class SqlValuesCreator {
             let message = error instanceof Error ? error.message : String(error);
             throw new Error("字段 '" + key + "' 异常，" + message);
         }
+        if (values.length === 0)
+            throw new Error("object 不能为空");
         return values.join(",");
     }
     /**
      * 将数组列表转为 SQL 的一个 value
-     * @example 返回示例： " 'abc', '6', 'now()' "
+     * @example
+     * ```ts
+     *  v.toValues([1, "abc", null, undefined, { key: "value" }]) // `1,'abc',NULL,DEFAULT,'{"key":"value"}'`
+     * ```
      */
     toValues(values) {
+        if (values.length === 0)
+            throw new Error("values 不能为空");
         return values.map((v) => this.toSqlStr(v)).join(",");
     }
     createValues(asName, values, valuesTypes) {
@@ -301,4 +302,4 @@ class AssertError extends TypeError {
     }
 }
 
-export { SqlRaw, SqlValuesCreator };
+export { SqlValuesCreator };

package/package.json

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