feat(builder): destroy(), setParam() parameter change, type & jsdoc improve

subframe7536 · subframe7536 · commit 37e4ee1a74d4 · 2023-08-28T17:25:09.000+08:00
diff --git a/packages/sqlite-builder/package.json b/packages/sqlite-builder/package.json
@@ -41,6 +41,6 @@
     "kysely-plugin-serialize": "workspace:*"
   },
   "peerDependencies": {
-    "kysely": "^0.26.1"
+    "kysely": "^0.26.3"
   }
 }
diff --git a/packages/sqlite-builder/src/builder.ts b/packages/sqlite-builder/src/builder.ts
@@ -1,15 +1,16 @@
 import type { Compilable, CompiledQuery, KyselyPlugin, LogEvent, QueryResult, RawBuilder, Sql, Transaction } from 'kysely'
 import { Kysely, sql } from 'kysely'
 import { SqliteSerializePlugin } from 'kysely-plugin-serialize'
-import type { SimplifySingleResult } from 'kysely/dist/cjs/util/type-utils'
-import { parseTableMap, preCompile, runCreateTable } from './utils'
-import type { AvailableBuilder, BuilderResult, Logger, QueryBuilderOutput, SqliteBuilderOption, Table } from './types'
+import type { Simplify } from 'kysely/dist/cjs/util/type-utils'
+import { parseTableMap, precompileQuery, runCreateTable } from './utils'
+import type { AvailableBuilder, Logger, QueryBuilderOutput, QueryBuilderResult, SqliteBuilderOption, Table } from './types'
 import { Stack } from './stack'
 
 type DBStatus =
- | 'needDrop'
- | 'noNeedDrop'
- | 'ready'
+  | 'needDrop'
+  | 'noNeedDrop'
+  | 'ready'
+  | 'destroy'
 
 export class SqliteBuilder<DB extends Record<string, any>> {
   public kysely: Kysely<DB>
@@ -45,20 +46,27 @@ export class SqliteBuilder<DB extends Record<string, any>> {
     return this
   }
 
-  private async isEmptyTable(): Promise<boolean> {
+  private async isFailToInitDB(): Promise<boolean> {
+    if (this.status === 'destroy') {
+      this.logger?.error('DB have been destroyed')
+      return true
+    }
     this.status !== 'ready' && await this.init()
     if (this.status === 'ready') {
       return false
     }
-    this.logger?.error('fail to init table')
+    this.logger?.error('fail to init DB')
     return true
   }
 
+  /**
+   * execute sql in transaction, support nest transactions
+   */
   public async transaction<T>(
     cb: (trx: Transaction<DB>) => Promise<T>,
     errorMsg?: string,
   ): Promise<T | undefined> {
-    if (await this.isEmptyTable()) {
+    if (await this.isFailToInitDB()) {
       return undefined
     }
     return await this.kysely.transaction()
@@ -79,11 +87,14 @@ export class SqliteBuilder<DB extends Record<string, any>> {
     return this.trxs.isEmpty() ? this.kysely : this.trxs.peek()
   }
 
+  /**
+   * execute query manually, auto detect transaction
+   */
   public async exec<O>(
     cb: (db: Kysely<DB> | Transaction<DB>) => Promise<O>,
     errorMsg?: string,
   ): Promise<O | undefined> {
-    if (await this.isEmptyTable()) {
+    if (await this.isFailToInitDB()) {
       return undefined
     }
     return cb(this.getDB())
@@ -93,48 +104,63 @@ export class SqliteBuilder<DB extends Record<string, any>> {
       })
   }
 
+  /**
+   * execute query and auto return first result, auto detect transaction
+   */
   public async execOne<O>(
     cb: (db: Kysely<DB> | Transaction<DB>) => AvailableBuilder<DB, O>,
     errorMsg?: string,
-  ): Promise<SimplifySingleResult<O> | undefined> {
+  ): Promise<Simplify<O> | undefined> {
     const resultList = await this.execList(cb, errorMsg)
     return resultList?.length ? resultList[0] : undefined
   }
 
+  /**
+   * execute query and auto return results, auto detect transaction
+   */
   public async execList<O>(
     cb: (db: Kysely<DB> | Transaction<DB>) => AvailableBuilder<DB, O>,
     errorMsg?: string,
-  ): Promise<Exclude<SimplifySingleResult<O>, undefined>[] | undefined> {
-    if (await this.isEmptyTable()) {
+  ): Promise<Simplify<O>[] | undefined> {
+    if (await this.isFailToInitDB()) {
       return undefined
     }
     return cb(this.getDB())
       .execute()
       .catch((err) => {
         errorMsg && this.logger?.error(errorMsg, err)
         return undefined
-      }) as any
+      })
   }
 
-  public preCompile<O>(
+  /**
+   * see {@link precompileQuery}
+   */
+  public precompile<O>(
     queryBuilder: (db: Kysely<DB> | Transaction<DB>) => QueryBuilderOutput<Compilable<O>>,
-  ): ReturnType<typeof preCompile<O>> {
-    return preCompile(queryBuilder(this.kysely))
+  ): ReturnType<typeof precompileQuery<O>> {
+    return precompileQuery(queryBuilder(this.kysely))
   }
 
+  /**
+   * exec compiled query, and return rows in result, auto detect transaction, useful for select
+   */
   public async execCompiledRows<O>(
     query: CompiledQuery<O>,
     errorMsg?: string,
-  ): Promise<BuilderResult<O>['rows'] | undefined> {
+  ): Promise<QueryBuilderResult<O>['rows'] | undefined> {
     const result = await this.execCompiled(query, errorMsg)
-    return result?.rows ?? undefined
+    return result?.rows?.length ? result.rows : undefined
   }
 
+  /**
+   * exec compiled query, return result, auto detect transaction
+   */
   public async execCompiled<O>(
     query: CompiledQuery<O>,
     errorMsg?: string,
-  ): Promise<BuilderResult<O> | undefined> {
-    if (await this.isEmptyTable()) {
+  ): Promise<QueryBuilderResult<O> | undefined> {
+    if (await this.isFailToInitDB()) {
       return undefined
     }
     return this.getDB().executeQuery(query)
@@ -144,14 +170,31 @@ export class SqliteBuilder<DB extends Record<string, any>> {
       }) as any
   }
 
+  /**
+   * compile query builder
+   */
   public async toSQL<T extends Compilable>(cb: (db: Kysely<DB>) => T): Promise<CompiledQuery<unknown>> {
-    return cb(this.getDB()).compile()
+    return cb(this.kysely).compile()
   }
 
-  public async raw<T = any>(rawSql: (s: Sql) => RawBuilder<T>): Promise<QueryResult<T> | undefined> {
-    if (await this.isEmptyTable()) {
+  /**
+   * execute raw sql, auto detect transaction
+   * @see {@link Sql}
+   */
+  public async raw<O = any>(rawSql: (s: Sql) => RawBuilder<O>): Promise<QueryResult<O> | undefined> {
+    if (await this.isFailToInitDB()) {
       return undefined
     }
     return rawSql(sql).execute(this.getDB())
   }
+
+  /**
+   * destroy db connection
+   */
+  public async destroy() {
+    await this.kysely.destroy()
+    this.status = 'destroy'
+    this.tableMap.clear()
+    this.trxs.clear()
+  }
 }
diff --git a/packages/sqlite-builder/src/index.ts b/packages/sqlite-builder/src/index.ts
@@ -1,3 +1,3 @@
 export * from './builder'
 export * from './types'
-export { createTimeTrigger, parseTableMap, runCreateTable, preCompile } from './utils'
+export { createTimeTrigger, parseTableMap, runCreateTable, precompileQuery } from './utils'
diff --git a/packages/sqlite-builder/src/stack.ts b/packages/sqlite-builder/src/stack.ts
@@ -24,4 +24,10 @@ export class Stack<T> {
   size() {
     return this.items.length
   }
+
+  clear() {
+    while (this.size()) {
+      this.pop()
+    }
+  }
 }
diff --git a/packages/sqlite-builder/src/types.ts b/packages/sqlite-builder/src/types.ts
@@ -61,4 +61,7 @@ export type AvailableBuilder<DB, O> =
 
 export type QueryBuilderOutput<QB> = QB extends Compilable<infer O> ? O : never
 
-export type BuilderResult<T> = T extends SelectQueryBuilder<any, any, infer P> ? QueryResult<P> : Omit<QueryResult<any>, 'rows'> & { rows: [] }
+export type QueryBuilderResult<T> =
+  T extends SelectQueryBuilder<any, any, infer P>
+    ? QueryResult<P>
+    : Omit<QueryResult<any>, 'rows'> & { rows: [] }
diff --git a/packages/sqlite-builder/src/utils.ts b/packages/sqlite-builder/src/utils.ts
@@ -145,38 +145,77 @@ export async function runCreateTable<T>(
   }
 }
 
-export function preCompile<O>(
+/**
+ * create precompiled query, inspired by {@link https://github.com/jtlapp/kysely-params kysely-params}
+ * @example
+ * ```ts
+ * const query = precompileQuery(
+ *   db.selectFrom('test').selectAll(),
+ * ).setParam<{ name: string }>((qb, param) =>
+ *   qb.where('name', '=', param('name')),
+ * )
+ * const compiledQuery = query({ name: 'test' })
+ * // {
+ * //   sql: 'select * from "test" where "name" = ?',
+ * //   parameters: ['test'],
+ * //   query: { kind: 'SelectQueryNode' }
+ * // }
+ * ```
+ */
+export function precompileQuery<O>(
   queryBuilder: QueryBuilderOutput<Compilable<O>>,
 ) {
-  function getParam<P extends Record<string, any>>(name: keyof P): P[keyof P] {
-    return `__precomile_${name as string}` as unknown as P[keyof P]
-  }
-  return {
-    setParam<P extends Record<string, any>>(
-      paramBuilder: (
-        queryBuilder: QueryBuilderOutput<Compilable<O>>,
-        param: typeof getParam<P>
-      ) => Compilable<O>,
-    ) {
-      let compiled: CompiledQuery<Compilable<O>>
-      return (param: P, processRootOperatorNode?: (node: RootOperationNode) => RootOperationNode): CompiledQuery<O> => {
-        if (!compiled) {
-          const { parameters, sql, query } = paramBuilder(queryBuilder, getParam).compile()
-          compiled = {
-            sql,
-            query: processRootOperatorNode?.(query) || { kind: query.kind } as any,
-            parameters,
-          }
-        }
-        return {
-          ...compiled,
-          parameters: compiled.parameters.map(p =>
-            (typeof p === 'string' && p.startsWith('__precomile_'))
-              ? defaultSerializer(param[p.slice(12)])
-              : p,
-          ),
-        }
+  const getParam = <T extends Record<string, any>>(
+    name: keyof T,
+  ): T[keyof T] => `__precomile_${name as string}` as unknown as T[keyof T]
+      type SetParam<T extends Record<string, any>> = {
+        /**
+         * query builder for setup params
+         */
+        qb: QueryBuilderOutput<Compilable<O>>
+        /**
+         * param builder
+         */
+        param: typeof getParam<T>
       }
-    },
-  }
+    /**
+     * @param param custom params
+     * @param processRootOperatorNode process `query` in {@link CompiledQuery}
+     * @default (node) => ({ kind: node.kind })
+     */
+    type CompileFn<T extends Record<string, any>> = (
+      param: T,
+      processRootOperatorNode?: ((node: RootOperationNode) => RootOperationNode)
+    ) => CompiledQuery<O>
+
+    return {
+      /**
+       * setup params
+       * @param paramBuilder param builder
+       * @returns function to {@link CompileFn compile}
+       */
+      setParam: <T extends Record<string, any>>(
+        paramBuilder: ({ param, qb }: SetParam<T>) => Compilable<O>,
+      ): CompileFn<T> => {
+        let compiled: CompiledQuery<Compilable<O>>
+        return ((param, processRootOperatorNode) => {
+          if (!compiled) {
+            const { parameters, sql, query } = paramBuilder({ qb: queryBuilder, param: getParam }).compile()
+            compiled = {
+              sql,
+              query: processRootOperatorNode?.(query) || { kind: query.kind } as any,
+              parameters,
+            }
+          }
+          return {
+            ...compiled,
+            parameters: compiled.parameters.map(p =>
+              (typeof p === 'string' && p.startsWith('__precomile_'))
+                ? defaultSerializer(param[p.slice(12)])
+                : p,
+            ),
+          }
+        }) satisfies CompileFn<T>
+      },
+    }
 }
diff --git a/test/builder.test.ts b/test/builder.test.ts
@@ -75,7 +75,7 @@ describe('test builder', async () => {
     expect(result![0].createAt).toBeInstanceOf(Date)
     expect(result![0].updateAt).toBeInstanceOf(Date)
     const result2 = await db.execOne(d => d.selectFrom('test').selectAll())
-    expect(result).toBeInstanceOf(Object)
+    expect(result2).toBeInstanceOf(Object)
     expect(result2!.person).toStrictEqual({ name: 'test' })
     expect(result2!.gender).toStrictEqual(false)
     expect(result2!.createAt).toBeInstanceOf(Date)
@@ -90,13 +90,22 @@ describe('test builder', async () => {
     expect(query.sql).toBe('select * from "test" where "person" = ?')
     expect(query.parameters).toStrictEqual(['{"name":"1"}'])
   })
-  test('preCompile', async () => {
-    const select = db.preCompile(db => db.selectFrom('test').selectAll())
-      .setParam<{ person: { name: string } }>((qb, param) => qb.where('person', '=', param('person')))
-    const insert = db.preCompile(db => db.insertInto('test'))
-      .setParam<{ gender: boolean }>((qb, param) => qb.values({ gender: param('gender') }))
-    const update = db.preCompile(db => db.updateTable('test'))
-      .setParam<{ gender: boolean }>((qb, param) => qb.set({ gender: param('gender') }).where('id', '=', 1))
+  test('precompile', async () => {
+    const select = db.precompile(
+      db => db.selectFrom('test').selectAll(),
+    ).setParam<{ person: { name: string } }>(({ qb, param }) =>
+      qb.where('person', '=', param('person')),
+    )
+    const insert = db.precompile(
+      db => db.insertInto('test'),
+    ).setParam<{ gender: boolean }>(({ qb, param }) =>
+      qb.values({ gender: param('gender') }),
+    )
+    const update = db.precompile(
+      db => db.updateTable('test'),
+    ).setParam<{ gender: boolean }>(({ qb, param }) =>
+      qb.set({ gender: param('gender') }).where('id', '=', 1),
+    )
 
     const start = performance.now()
 

Original file line number	Diff line number	Diff line change
`@@ -41,6 +41,6 @@`
`41`	`41`	`"kysely-plugin-serialize": "workspace:*"`
`42`	`42`	`},`
`43`	`43`	`"peerDependencies": {`
`44`		`- "kysely": "^0.26.1"`
	`44`	`+ "kysely": "^0.26.3"`
`45`	`45`	`}`
`46`	`46`	`}`
Original file line number	Diff line number	Diff line change
`@@ -24,4 +24,10 @@ export class Stack<T> {`
`24`	`24`	`size() {`
`25`	`25`	`return this.items.length`
`26`	`26`	`}`
	`27`	`+`
	`28`	`+ clear() {`
	`29`	`+ while (this.size()) {`
	`30`	`+ this.pop()`
	`31`	`+ }`
	`32`	`+ }`
`27`	`33`	`}`