@asla/yoursql 0.8.7 → 0.8.9

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/client/DbPoolConnection.d.ts

@@ -1,7 +1,7 @@
 import type { SqlStatementDataset } from "../sql_gen/mod.ts";
 import { DbQuery } from "./DbQuery.ts";
-import type { MultipleQueryResult, QueryRowsResult } from "./DbQuery.ts";
-import type { DbConnection, TransactionMode } from "./interfaces.ts";
+import type { MultipleQueryResult, QueryRowsResult, DbQueryBase } from "./DbQueryBase.ts";
+import type { StringLike, TransactionMode } from "./interfaces.ts";
 /**
 
 /**
@@ -10,15 +10,11 @@ import type { DbConnection, TransactionMode } from "./interfaces.ts";
  */
 export declare class DbPoolConnection extends DbQuery {
     #private;
-    constructor(conn: DbConnection, onRelease: () => void);
+    constructor(conn: DbQueryBase, onRelease: (conn: DbQueryBase) => void);
     begin(mode?: TransactionMode): Promise<void>;
     query<T = any>(sql: SqlStatementDataset<T>): Promise<QueryRowsResult<T>>;
-    query<T = any>(sql: {
-        toString(): string;
-    }): Promise<QueryRowsResult<T>>;
-    multipleQuery<T extends MultipleQueryResult = MultipleQueryResult>(sql: {
-        toString(): string;
-    }): Promise<T>;
+    query<T = any>(sql: StringLike): Promise<QueryRowsResult<T>>;
+    multipleQuery<T extends MultipleQueryResult = MultipleQueryResult>(sql: StringLike): Promise<T>;
     rollback(): Promise<void>;
     commit(): Promise<void>;
     get released(): boolean;

package/dist/client/DbPoolConnection.js

@@ -42,9 +42,10 @@ class DbPoolConnection extends DbQuery {
     }
     /** 调用 release() 时，如果事务未提交，则抛出异常 */
     release() {
-        if (this.#conn) {
+        const conn = this.#conn;
+        if (conn) {
             this.#conn = undefined;
-            this.#onRelease();
+            this.#onRelease(conn);
         }
     }
     //implement

package/dist/client/DbPoolTransaction.d.ts

@@ -1,8 +1,8 @@
 import type { SqlStatementDataset } from "../sql_gen/mod.ts";
 import { DbQuery } from "./DbQuery.ts";
-import type { MultipleQueryResult, QueryRowsResult } from "./DbQuery.ts";
+import type { MultipleQueryResult, QueryRowsResult } from "./DbQueryBase.ts";
 import type { DbPoolConnection } from "./DbPoolConnection.ts";
-import type { DbTransaction, TransactionMode } from "./interfaces.ts";
+import type { DbTransaction, StringLike, TransactionMode } from "./interfaces.ts";
 /** @public */
 export type DbPoolTransactionOption = {
     errorRollback?: boolean;
@@ -21,13 +21,9 @@ export declare class DbPoolTransaction extends DbQuery implements DbTransaction
     savePoint(savePoint: string): Promise<void>;
     rollbackTo(savePoint: string): Promise<void>;
     query<T extends object = any>(sql: SqlStatementDataset<T>): Promise<QueryRowsResult<T>>;
-    query<T extends object = any>(sql: {
-        toString(): string;
-    }): Promise<QueryRowsResult<T>>;
+    query<T extends object = any>(sql: StringLike): Promise<QueryRowsResult<T>>;
     multipleQuery<T extends MultipleQueryResult = MultipleQueryResult>(sql: SqlStatementDataset<T>): Promise<T>;
-    multipleQuery<T extends MultipleQueryResult = MultipleQueryResult>(sql: {
-        toString(): string;
-    }): Promise<T>;
+    multipleQuery<T extends MultipleQueryResult = MultipleQueryResult>(sql: StringLike): Promise<T>;
     get released(): boolean;
     [Symbol.asyncDispose](): Promise<void>;
 }

package/dist/client/DbQuery.d.ts

@@ -1,45 +1,22 @@
 import type { SqlStatementDataset } from "../sql_gen/mod.ts";
-/** @public */
-export interface SingleQueryResult {
-    rowCount: number;
-    rows?: any[];
-}
-/** @public */
-export interface QueryRowsResult<T = any> extends SingleQueryResult {
-    rowCount: number;
-    rows: T[];
-}
-/** @public */
-export type MultipleQueryResult = SingleQueryResult[];
-/** @public */
-export type QueryResult = MultipleQueryResult | SingleQueryResult;
+import { StringLike } from "./interfaces.ts";
+import { MultipleQueryResult, DbQueryBase, QueryRowsResult } from "./DbQueryBase.ts";
 /**
  * SQL 查询相关操作
  * @public
  */
-export declare abstract class DbQuery {
-    /** 单语句查询，不应查询条语句，否则返回错误值  */
-    abstract query<T = any>(sql: SqlStatementDataset<T>): Promise<QueryRowsResult<T>>;
-    /** 单语句查询，不应查询条语句，否则返回错误值  */
-    abstract query<T = any>(sql: {
-        toString(): string;
-    }): Promise<QueryRowsResult<T>>;
-    /** 多语句查询  */
-    abstract multipleQuery<T extends MultipleQueryResult = MultipleQueryResult>(sql: SqlStatementDataset<T>): Promise<T>;
-    /** 多语句查询 */
-    abstract multipleQuery<T extends MultipleQueryResult = MultipleQueryResult>(sql: {
-        toString(): string;
-    }): Promise<T>;
+export declare abstract class DbQuery implements DbQueryBase {
+    abstract query<T = any>(sql: StringLike): Promise<QueryRowsResult<T>>;
+    abstract multipleQuery<T extends MultipleQueryResult = MultipleQueryResult>(sql: StringLike): Promise<T>;
     /** 单语句查询受影响的行 */
-    queryCount(sql: string | {
-        toString(): string;
-    }): Promise<number>;
-    /** 单语句查询，不应查询条语句，否则返回错误值  */
+    queryCount(sql: string | StringLike): Promise<number>;
+    /** 单语句查询，不应查询多语句，否则返回错误值  */
     queryRows<T = any>(sql: SqlStatementDataset<T>): Promise<T[]>;
-    /** 单语句查询，不应查询条语句，否则返回错误值  */
-    queryRows<T = any>(sql: {
-        toString(): string;
-    }): Promise<T[]>;
+    /** 单语句查询，不应查询多语句，否则返回错误值  */
+    queryRows<T = any>(sql: StringLike): Promise<T[]>;
+    /** 单语句查询，只返回第一行。如果查询没有返回行，则抛出异常。 */
+    queryFirstRow<T = any>(sql: SqlStatementDataset<T>): Promise<T>;
+    queryFirstRow<T = any>(sql: StringLike): Promise<T>;
     /**
      * 查询行
      * 不应查询单条语句，否则返回错误值
@@ -47,22 +24,18 @@ export declare abstract class DbQuery {
     multipleQueryRows<T extends any[] = any[]>(sql: SqlStatementDataset<T>): Promise<T[]>;
     /**
      * 查询行
-     * 不应查询条语句，否则返回错误值
+     * 不应查询单语句，否则返回错误值
      */
-    multipleQueryRows<T extends any[] = any[]>(sql: {
-        toString(): string;
-    }): Promise<T[]>;
+    multipleQueryRows<T extends any[] = any[]>(sql: StringLike): Promise<T[]>;
     /**
      * 指定某一列为key，返回 key 到 row 的映射
-     * 单语句查询，不应查询条语句，否则返回错误值
+     * 单语句查询，不应查询多语句，否则返回错误值
      */
     queryMap<T extends Record<string, any> = Record<string, any>, K extends keyof T = string>(sql: SqlStatementDataset<T>, key: K): Promise<Map<T[K], T>>;
     /**
      * 指定某一列为key，返回 key 到 row 的映射
-     * 单语句查询，不应查询条语句，否则返回错误值
+     * 单语句查询，不应查询多语句，否则返回错误值
      */
-    queryMap<T extends Record<string, any> = Record<string, any>, K extends keyof T = string>(sql: {
-        toString(): string;
-    }, key: K): Promise<Map<T[K], T>>;
+    queryMap<T extends Record<string, any> = Record<string, any>, K extends keyof T = string>(sql: StringLike, key: K): Promise<Map<T[K], T>>;
 }
 //# sourceMappingURL=DbQuery.d.ts.map

package/dist/client/DbQuery.js

@@ -14,6 +14,13 @@ class DbQuery {
     queryRows(sql) {
         return this.query(sql.toString()).then((res) => res.rows);
     }
+    queryFirstRow(sql) {
+        return this.query(sql.toString()).then(({ rows, rowCount }) => {
+            if (rows.length === 0)
+                throw new Error("Query did not return any rows");
+            return rows[0];
+        });
+    }
     multipleQueryRows(sql) {
         return this.multipleQuery(sql.toString()).then((res) => res.map((item) => item.rows ?? []));
     }

package/dist/client/DbQueryBase.d.ts

@@ -0,0 +1,26 @@
+import type { SqlStatementDataset } from "../sql_gen/mod.ts";
+import { StringLike } from "./interfaces.ts";
+/** @public */
+export interface SingleQueryResult {
+    rowCount: number;
+    rows?: any[];
+}
+/** @public */
+export interface QueryRowsResult<T = any> extends SingleQueryResult {
+    rowCount: number;
+    rows: T[];
+}
+/** @public */
+export type MultipleQueryResult = SingleQueryResult[];
+/** @public */
+export type QueryResult = MultipleQueryResult | SingleQueryResult;
+/** @public */
+export interface DbQueryBase {
+    /** 单语句查询，不应查询多语句，否则返回错误值  */
+    query<T = any>(sql: SqlStatementDataset<T>): Promise<QueryRowsResult<T>>;
+    /** 单语句查询，不应查询多语句，否则返回错误值  */
+    query<T = any>(sql: StringLike): Promise<QueryRowsResult<T>>;
+    /** 多语句查询 */
+    multipleQuery<T extends MultipleQueryResult = MultipleQueryResult>(sql: StringLike): Promise<T>;
+}
+//# sourceMappingURL=DbQueryBase.d.ts.map

package/dist/client/interfaces.d.ts

@@ -59,8 +59,10 @@ export interface DbQueryPool extends DbQuery {
     totalCount: number;
     begin(mode?: TransactionMode): DbTransaction;
     cursor<T extends {}>(sql: SqlStatementDataset<T>): Promise<DbCursor<T>>;
-    cursor<T>(sql: {
-        toString(): string;
-    }, option?: DbCursorOption): Promise<DbCursor<T>>;
+    cursor<T>(sql: StringLike, option?: DbCursorOption): Promise<DbCursor<T>>;
 }
+/** @public */
+export type StringLike = {
+    toString(): string;
+} | string;
 //# sourceMappingURL=interfaces.d.ts.map

package/dist/client/mod.d.ts

@@ -1,5 +1,6 @@
 export * from "./errors.ts";
 export * from "./interfaces.ts";
+export * from "./DbQueryBase.ts";
 export * from "./DbQuery.ts";
 export * from "./DbCursor.ts";
 export * from "./DbPoolConnection.ts";

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/DbTable.d.ts

@@ -20,6 +20,8 @@ export declare class DbTable<T extends TableType> {
         [key: string]: string | boolean;
     }>, as?: string): ChainSelect<Record<string, any>>;
     /** 选择单表  */
+    select<R extends {} = Record<string, any>>(columns: Constructable<string | string[]>, as?: string): ChainSelect<R>;
+    /** 选择单表  */
     select<R extends {}>(columns: Constructable<{
         [key in keyof R]: boolean | string;
     } | string | string[]>, as?: string): ChainSelect<R>;

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

@@ -1,4 +1,3 @@
-import { SqlRaw } from "../sql_value/sql_value.ts";
 /**
  * @public
  * @param T - 表格查询类型
@@ -16,7 +15,7 @@ export type PickColumn<T extends {
 };
 /** @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.7",
+  "version": "0.8.9",
   "description": "",
   "type": "module",
   "types": "./dist/mod.d.ts",