@forinda/kickjs-db 8.12.4 → 8.14.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (72) hide show
  1. package/bin/kickjs-db.mjs +11 -27
  2. package/dist/{adapter-cVrkWrul.d.mts → adapter-HRQJb4xQ.d.mts} +2 -4
  3. package/dist/adapter-HRQJb4xQ.d.mts.map +1 -0
  4. package/dist/cli.d.mts +39 -9
  5. package/dist/cli.d.mts.map +1 -1
  6. package/dist/cli.mjs +4 -4
  7. package/dist/cli.mjs.map +1 -1
  8. package/dist/{create-NrvNUwZr.mjs → create-CncI2KmH.mjs} +5 -5
  9. package/dist/create-CncI2KmH.mjs.map +1 -0
  10. package/dist/{custom-type-CNmg8h4k.mjs → custom-type-CUtJElSp.mjs} +2 -2
  11. package/dist/custom-type-CUtJElSp.mjs.map +1 -0
  12. package/dist/devtools-events.d.mts +1 -3
  13. package/dist/devtools-events.d.mts.map +1 -1
  14. package/dist/devtools-events.mjs +1 -1
  15. package/dist/{index-Nf43jLx4.d.mts → index-AaU739CK.d.mts} +329 -135
  16. package/dist/index-AaU739CK.d.mts.map +1 -0
  17. package/dist/index.d.mts +5 -5
  18. package/dist/index.mjs +2 -2
  19. package/dist/mysql.d.mts +2 -8
  20. package/dist/mysql.d.mts.map +1 -1
  21. package/dist/mysql.mjs +2 -2
  22. package/dist/mysql.mjs.map +1 -1
  23. package/dist/{pg-lghOiA3k.mjs → pg-RMJhs3tX.mjs} +3 -3
  24. package/dist/{pg-lghOiA3k.mjs.map → pg-RMJhs3tX.mjs.map} +1 -1
  25. package/dist/pg.d.mts +4 -12
  26. package/dist/pg.d.mts.map +1 -1
  27. package/dist/pg.mjs +2 -2
  28. package/dist/pg.mjs.map +1 -1
  29. package/dist/pglite.d.mts +1 -3
  30. package/dist/pglite.d.mts.map +1 -1
  31. package/dist/pglite.mjs +1 -1
  32. package/dist/pglite.mjs.map +1 -1
  33. package/dist/{schema-types-CdU4u-Ow.d.mts → schema-types-CsgTPOPi.d.mts} +9 -5
  34. package/dist/schema-types-CsgTPOPi.d.mts.map +1 -0
  35. package/dist/{schema-jLdsVhUe.d.mts → schema-v6Jgocab.d.mts} +3 -5
  36. package/dist/schema-v6Jgocab.d.mts.map +1 -0
  37. package/dist/schema.d.mts +1 -1
  38. package/dist/schema.mjs +2 -2
  39. package/dist/schema.mjs.map +1 -1
  40. package/dist/{split-statements-cNBnqF81.mjs → split-statements-CoWc_gGU.mjs} +2 -2
  41. package/dist/{split-statements-cNBnqF81.mjs.map → split-statements-CoWc_gGU.mjs.map} +1 -1
  42. package/dist/sqlite.d.mts +1 -7
  43. package/dist/sqlite.d.mts.map +1 -1
  44. package/dist/sqlite.mjs +2 -2
  45. package/dist/sqlite.mjs.map +1 -1
  46. package/dist/{src-BkewQb59.mjs → src-B8GJNbzI.mjs} +4 -4
  47. package/dist/src-B8GJNbzI.mjs.map +1 -0
  48. package/dist/{table-BGk08X3C.d.mts → table-B8eYtdq_.d.mts} +7 -8
  49. package/dist/table-B8eYtdq_.d.mts.map +1 -0
  50. package/dist/testing-vitest.d.mts +24 -0
  51. package/dist/testing-vitest.d.mts.map +1 -0
  52. package/dist/testing-vitest.mjs +12 -0
  53. package/dist/testing-vitest.mjs.map +1 -0
  54. package/dist/testing.d.mts +46 -13
  55. package/dist/testing.d.mts.map +1 -1
  56. package/dist/testing.mjs +16 -3
  57. package/dist/testing.mjs.map +1 -1
  58. package/dist/{types-8xZUYm43.d.mts → types-Bmbj69hY.d.mts} +79 -17
  59. package/dist/types-Bmbj69hY.d.mts.map +1 -0
  60. package/dist/{types-DB_xyeQT.d.mts → types-D4x2u-EZ.d.mts} +22 -5
  61. package/dist/types-D4x2u-EZ.d.mts.map +1 -0
  62. package/package.json +21 -12
  63. package/dist/adapter-cVrkWrul.d.mts.map +0 -1
  64. package/dist/create-NrvNUwZr.mjs.map +0 -1
  65. package/dist/custom-type-CNmg8h4k.mjs.map +0 -1
  66. package/dist/index-Nf43jLx4.d.mts.map +0 -1
  67. package/dist/schema-jLdsVhUe.d.mts.map +0 -1
  68. package/dist/schema-types-CdU4u-Ow.d.mts.map +0 -1
  69. package/dist/src-BkewQb59.mjs.map +0 -1
  70. package/dist/table-BGk08X3C.d.mts.map +0 -1
  71. package/dist/types-8xZUYm43.d.mts.map +0 -1
  72. package/dist/types-DB_xyeQT.d.mts.map +0 -1
@@ -1,6 +1,5 @@
1
1
 
2
- import { S as PolicySnapshot, m as TypedColumnRefs, n as ColumnBuilder, t as CheckSelfRefs, w as RoleSnapshot, x as IndexSnapshot } from "./types-DB_xyeQT.mjs";
3
- //#region src/dsl/rls.d.ts
2
+ import { S as PolicySnapshot, m as TypedColumnRefs, n as ColumnBuilder, t as CheckSelfRefs, w as RoleSnapshot, x as IndexSnapshot } from "./types-D4x2u-EZ.mjs";
4
3
  /** A database role, for `policy().to(...)` — created by migrations unless `.existing()`. */
5
4
  declare class RoleDecl {
6
5
  readonly __isRole = true;
@@ -58,8 +57,6 @@ declare class PolicyDecl {
58
57
  * A table with a policy has row-level security turned on.
59
58
  */
60
59
  declare function policy(name: string): PolicyDecl;
61
- //#endregion
62
- //#region src/dsl/constraints.d.ts
63
60
  interface ColRef {
64
61
  __name: string;
65
62
  }
@@ -148,8 +145,11 @@ declare function primaryKey(name?: string): {
148
145
  * expression is SQL, passed through as written.
149
146
  */
150
147
  declare function check(name: string, expression: string): CheckDecl;
151
- //#endregion
152
- //#region src/dsl/table.d.ts
148
+ /**
149
+ * A table declared with `table()`: its name, columns, indexes and constraints.
150
+ *
151
+ * @see https://kickjs.app/guide/database/schema
152
+ */
153
153
  interface TableDecl<TName extends string = string, C extends Record<string, ColumnBuilder> = Record<string, ColumnBuilder>, TSchema extends string | undefined = string | undefined> {
154
154
  __isTable: true;
155
155
  __name: TName;
@@ -232,6 +232,5 @@ declare function buildTable<TName extends string, C extends Record<string, Colum
232
232
  * the class is enough — no separate `export const users = User.table`.
233
233
  */
234
234
  declare function unwrapTable(value: unknown): TableDecl | undefined;
235
- //#endregion
236
235
  export { PolicyDecl as _, qualifiedTableName as a, pgRole as b, CheckDecl as c, PrimaryKeyDecl as d, TableConstraint as f, unique as g, primaryKey as h, buildTable as i, IndexDecl as l, index as m, TableDecl as n, table as o, check as p, TableOptions as r, unwrapTable as s, QualifiedName as t, IndexKey as u, RoleDecl as v, policy as x, isRole as y };
237
- //# sourceMappingURL=table-BGk08X3C.d.mts.map
236
+ //# sourceMappingURL=table-B8eYtdq_.d.mts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"table-B8eYtdq_.d.mts","names":[],"sources":["../src/dsl/rls.ts","../src/dsl/constraints.ts","../src/dsl/table.ts"],"mappings":";;;cAGa;WACF;WACA,QAAQ;;EAEjB;EAEA,YAAY,cAAc,UAAS,KAAK;;EAKxC;;;;;;;;;;;iBAec,OAAO,cAAc,UAAS,KAAK,wBAA6B;iBAIhE,OAAO,iBAAiB,SAAS;KAI5C,UAAU;;cAGF;WACF;WACA,UAAU;EAEnB,YAAY;;EAKZ,IAAI,SAAS;;EAMb,MAAM,OAAO,eAAe;;;;;EAS5B,GAAG;;EAMH,MAAM;;EAMN,UAAU;;;;;;;;;;;;;;;;;iBAqBI,OAAO,eAAe;UC9F5B;EACR;;;KAIU,WAAW;;;;;;;;;;cAeV;;WAEF,SAAS;EAElB,YAAY,cAAc,MAAM,YAAY;;EAK5C,MAAM;;EAMN,MAAM;;EAMN,WAAW,MAAM;;EAMjB,GAAG,KAAK,UAAU;;;;;;EAclB;;;;;;;;;;;iBAec,MAAM;EAElB,MAAE,MAAU,aAAa;;;;;;;;;iBAab,OAAO;EAEnB,MAAE,MAAU,aAAa;;;UAOZ;EACf;;EAEA;EACA;;;UAIe;EACf;EACA;;EAEA;;;KAIU,kBAAkB,YAAY,iBAAiB,YAAY;;;;;;;;;;iBAWvD,WAAW;EAEvB,MAAE,MAAU,WAAW;;;;;;iBAYX,MAAM,cAAc,qBAAqB;;;;;;UClIxC,UACf,+BACA,UAAU,eAAe,iBAAiB,eAAe,gBACzD;EAEA;EACA,QAAQ;EACR,WAAW;EACX,WAAW;;EAEX,eAAe;EACf,WAAW;;EAEX;;EAEA;IAAU;;EACV,aAAa;;;;;;;;;EASb,WAAW;;;;;WAKF,UAAU,SAAS;;;;;;;;;;KAWlB,cACV,sBACA,sCACE,4BAA4B,WAAW,UAAU;;iBAGrC,mBAAmB;EACjC;EACA;;KAKG,UACH,sBACA,UAAU,eAAe,gBACzB,kDACE,UAAU,OAAO,GAAG,WAAW,gBAAgB;KAE9C,kBAAkB,UAAU,eAAe,mBAC9C,MAAM,gBAAgB,OACnB,eAAe;;;;;KAMR,aAAa,UAAU,eAAe,kBAC9C,kBAAkB;EAEhB,cAAc,kBAAkB;EAChC;;;;;;;EAOA;IAAkB;;;;;;;;;iBASR,MAAM,sBAAsB,UAAU,eAAe,gBACnE,MAAM,OACN,SAAS,IAAI,cAAc,IAC3B,UAAU,aAAa,KACtB,UAAU,OAAO;;;;;iBAQJ,WACd,sBACA,UAAU,eAAe,gBACzB,oCAEA,MAAM,OACN,UAAU,GACV,SAAS,aAAa,gBACtB,QAAQ,UACP,UAAU,OAAO,GAAG;;;;;;;iBA6EP,YAAY,iBAAiB"}
@@ -0,0 +1,24 @@
1
+
2
+ import { r as KickDbClient } from "./types-Bmbj69hY.mjs";
3
+ import { t as SchemaToTypes } from "./schema-types-CsgTPOPi.mjs";
4
+ import { ServerTestDbOptions } from "./testing.mjs";
5
+ export interface UseTestDbOptions<S> extends ServerTestDbOptions<S> {
6
+ /**
7
+ * Default: `'postgres'` when a Postgres server is known (`connectionString`,
8
+ * `inject('postgres')` or `KICK_TEST_POSTGRES_URL`), else `'mysql'` when a
9
+ * MySQL one is (`inject('mysql')` / `KICK_TEST_MYSQL_URL`), else `'sqlite'`.
10
+ */
11
+ dialect?: 'postgres' | 'mysql' | 'sqlite';
12
+ }
13
+ export interface TestDbHandle<S> {
14
+ /** The client — inside tests (it's made in `beforeAll`). */
15
+ readonly db: KickDbClient<SchemaToTypes<S>>;
16
+ /** The database's connection string; `undefined` for SQLite. */
17
+ readonly connectionString?: string;
18
+ }
19
+ /**
20
+ * A database for this test file: created in `beforeAll`, dropped in
21
+ * `afterAll`, reached through the returned handle's `db`.
22
+ */
23
+ export declare function useTestDb<S>(opts: UseTestDbOptions<S>): TestDbHandle<S>;
24
+ //# sourceMappingURL=testing-vitest.d.mts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"testing-vitest.d.mts","names":[],"sources":["../src/testing-vitest.ts"],"mappings":";;;;iBAsBiB,iBAAiB,WAAW,oBAAoB;;;;;;EAM/D;;iBAGe,aAAa;;WAEnB,IAAI,aAAa,cAAc;;WAE/B;;;;;;wBAgBK,UAAU,GAAG,MAAM,iBAAiB,KAAK,aAAa"}
@@ -0,0 +1,12 @@
1
+ /**
2
+ * @forinda/kickjs-db v8.14.0
3
+ *
4
+ * Copyright (c) Felix Orinda
5
+ *
6
+ * This source code is licensed under the MIT license found in the
7
+ * LICENSE file in the root directory of this source tree.
8
+ *
9
+ * @license MIT
10
+ */
11
+ import{createMysqlTestDb,createPgTestDb,createTestDb}from"./testing.mjs";import{afterAll,beforeAll,inject}from"vitest";const provided=key=>{try{return inject(key)}catch{return}};function useTestDb(opts){let db,connectionString,drop;return beforeAll(async()=>{let pgUrl=provided(`postgres`)??process.env.KICK_TEST_POSTGRES_URL,mysqlUrl=provided(`mysql`)??process.env.KICK_TEST_MYSQL_URL,dialect=opts.dialect??(opts.connectionString||pgUrl?`postgres`:mysqlUrl?`mysql`:`sqlite`);if(dialect===`sqlite`){db=await createTestDb({...opts,schema:opts.schema??{}}),drop=()=>db.destroy();return}let made=dialect===`postgres`?await createPgTestDb({...opts,connectionString:opts.connectionString??pgUrl}):await createMysqlTestDb({...opts,connectionString:opts.connectionString??mysqlUrl});({db,connectionString}=made),drop=made.drop}),afterAll(async()=>{await drop?.()}),{get db(){if(!db)throw Error("useTestDb: the database exists inside tests (beforeAll has not run) — read `.db` in a test or a hook");return db},get connectionString(){return connectionString}}}export{useTestDb};
12
+ //# sourceMappingURL=testing-vitest.mjs.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"testing-vitest.mjs","names":[],"sources":["../src/testing-vitest.ts"],"sourcesContent":["/**\n * `@forinda/kickjs-db/testing/vitest` — a test database in one line per file:\n * made before the file's tests, dropped after.\n *\n * const t = useTestDb({ migrationsDir: 'db/migrations' })\n * it('lists users', async () => { await t.db.selectFrom('users')… })\n *\n * On a shared server (`kickTestServices` from `@forinda/kickjs-testing/vitest`)\n * each file gets its own database; with no server, an in-memory SQLite one.\n *\n * @module @forinda/kickjs-db/testing/vitest\n */\nimport { afterAll, beforeAll, inject } from 'vitest'\nimport type { KickDbClient } from './client/types'\nimport type { SchemaToTypes } from './client/schema-types'\nimport {\n createMysqlTestDb,\n createPgTestDb,\n createTestDb,\n type ServerTestDbOptions,\n} from './testing'\n\nexport interface UseTestDbOptions<S> extends ServerTestDbOptions<S> {\n /**\n * Default: `'postgres'` when a Postgres server is known (`connectionString`,\n * `inject('postgres')` or `KICK_TEST_POSTGRES_URL`), else `'mysql'` when a\n * MySQL one is (`inject('mysql')` / `KICK_TEST_MYSQL_URL`), else `'sqlite'`.\n */\n dialect?: 'postgres' | 'mysql' | 'sqlite'\n}\n\nexport interface TestDbHandle<S> {\n /** The client — inside tests (it's made in `beforeAll`). */\n readonly db: KickDbClient<SchemaToTypes<S>>\n /** The database's connection string; `undefined` for SQLite. */\n readonly connectionString?: string\n}\n\n/** A value `kickTestServices` provided, if it ran. */\nconst provided = (key: string): string | undefined => {\n try {\n return (inject as unknown as (k: string) => string | undefined)(key)\n } catch {\n return undefined\n }\n}\n\n/**\n * A database for this test file: created in `beforeAll`, dropped in\n * `afterAll`, reached through the returned handle's `db`.\n */\nexport function useTestDb<S>(opts: UseTestDbOptions<S>): TestDbHandle<S> {\n let db: KickDbClient<SchemaToTypes<S>> | undefined\n let connectionString: string | undefined\n let drop: (() => Promise<void>) | undefined\n\n beforeAll(async () => {\n const pgUrl = provided('postgres') ?? process.env.KICK_TEST_POSTGRES_URL\n const mysqlUrl = provided('mysql') ?? process.env.KICK_TEST_MYSQL_URL\n const dialect =\n opts.dialect ?? (opts.connectionString || pgUrl ? 'postgres' : mysqlUrl ? 'mysql' : 'sqlite')\n if (dialect === 'sqlite') {\n db = await createTestDb({ ...opts, schema: opts.schema ?? ({} as S) })\n drop = () => db!.destroy()\n return\n }\n const made =\n dialect === 'postgres'\n ? await createPgTestDb({ ...opts, connectionString: opts.connectionString ?? pgUrl })\n : await createMysqlTestDb({ ...opts, connectionString: opts.connectionString ?? mysqlUrl })\n ;({ db, connectionString } = made)\n drop = made.drop\n })\n afterAll(async () => {\n await drop?.()\n })\n\n return {\n get db() {\n if (!db) {\n throw new Error(\n 'useTestDb: the database exists inside tests (beforeAll has not run) — read `.db` in a test or a hook',\n )\n }\n return db\n },\n get connectionString() {\n return connectionString\n },\n }\n}\n"],"mappings":";;;;;;;;;;A,uHAuCA,MAAM,SAAY,KAAoC,CACpD,GAAI,CACF,OAAQ,OAAwD,GAAG,CACrE,MAAQ,CACN,MACF,CACF,EAMA,SAAgB,UAAa,KAA4C,CACvE,IAAI,GACA,iBACA,KAuBJ,OArBA,UAAU,SAAY,CACpB,IAAM,MAAQ,SAAS,UAAU,GAAK,QAAQ,IAAI,uBAC5C,SAAW,SAAS,OAAO,GAAK,QAAQ,IAAI,oBAC5C,QACJ,KAAK,UAAY,KAAK,kBAAoB,MAAQ,WAAa,SAAW,QAAU,UACtF,GAAI,UAAY,SAAU,CACxB,GAAK,MAAM,aAAa,CAAE,GAAG,KAAM,OAAQ,KAAK,QAAW,CAAC,CAAQ,CAAC,EACrE,SAAa,GAAI,QAAQ,EACzB,MACF,CACA,IAAM,KACJ,UAAY,WACR,MAAM,eAAe,CAAE,GAAG,KAAM,iBAAkB,KAAK,kBAAoB,KAAM,CAAC,EAClF,MAAM,kBAAkB,CAAE,GAAG,KAAM,iBAAkB,KAAK,kBAAoB,QAAS,CAAC,GAC5F,CAAE,GAAI,kBAAqB,MAC7B,KAAO,KAAK,IACd,CAAC,EACD,SAAS,SAAY,CACnB,MAAM,OAAO,CACf,CAAC,EAEM,CACL,IAAI,IAAK,CACP,GAAI,CAAC,GACH,MAAU,MACR,sGACF,EAEF,OAAO,EACT,EACA,IAAI,kBAAmB,CACrB,OAAO,gBACT,CACF,CACF,C"}
@@ -1,7 +1,6 @@
1
1
 
2
- import { r as KickDbClient, s as QueryEvent } from "./types-8xZUYm43.mjs";
3
- import { t as SchemaToTypes } from "./schema-types-CdU4u-Ow.mjs";
4
- //#region src/testing.d.ts
2
+ import { r as KickDbClient, s as QueryEvent } from "./types-Bmbj69hY.mjs";
3
+ import { t as SchemaToTypes } from "./schema-types-CsgTPOPi.mjs";
5
4
  export interface TestDbOptions<S> {
6
5
  schema: S;
7
6
  /**
@@ -26,19 +25,54 @@ export interface PgTestDb<S> {
26
25
  /** Close the client and drop the database. Call it in `afterAll`. */
27
26
  drop(): Promise<void>;
28
27
  }
28
+ /** Options for a throwaway database on a shared server (Postgres or MySQL). */
29
+ export interface ServerTestDbOptions<S> extends Partial<TestDbOptions<S>> {
30
+ /**
31
+ * A database on the server to connect to first, with permission to CREATE
32
+ * DATABASE. Default: `KICK_TEST_POSTGRES_URL` / `KICK_TEST_MYSQL_URL`, which
33
+ * `kickTestServices` sets.
34
+ */
35
+ connectionString?: string;
36
+ /** Allow a server URL whose database name doesn't contain `test`. */
37
+ allowNonTestDatabase?: boolean;
38
+ /**
39
+ * How long a file waits for another file building the same template
40
+ * (default 120 s). Keep your test runner's hook timeout above it.
41
+ */
42
+ lockWaitSeconds?: number;
43
+ }
29
44
  /**
30
- * A throwaway database on an existing Postgres server — a CI service
31
- * container, a local Docker Postgres — with your schema or migrations
32
- * applied. Creating one takes well under a second, so each test file can
33
- * have its own without starting a container. Needs `pg`.
45
+ * A short key for what a template holds: the migrations' files, or the
46
+ * schema's snapshot when there are none — so a change makes a new template.
47
+ */
48
+ export declare function templateKey(input: {
49
+ migrationsDir?: string;
50
+ schema?: unknown;
51
+ casing?: string;
52
+ dialect?: 'postgres' | 'mysql';
53
+ }): Promise<string>;
54
+ /**
55
+ * A throwaway database on an existing Postgres server — a shared test
56
+ * container (`kickTestServices`), a CI service container, a local Docker
57
+ * Postgres. With `migrationsDir` (or `schema`) it's a copy of a template
58
+ * database migrated once, so creating one stays well under a second however
59
+ * many migrations there are; with neither, it's empty. Needs `pg`.
34
60
  *
35
- * const pg = await createPgTestDb({ schema, connectionString: process.env.TEST_DATABASE_URL! })
61
+ * const pg = await createPgTestDb({ migrationsDir: 'db/migrations' })
36
62
  * afterAll(() => pg.drop())
37
63
  */
38
- export declare function createPgTestDb<S>(opts: TestDbOptions<S> & {
39
- /** A database on the server to connect to first, with permission to CREATE DATABASE. */
40
- connectionString: string;
41
- }): Promise<PgTestDb<S>>;
64
+ export declare function createPgTestDb<S>(opts: ServerTestDbOptions<S>): Promise<PgTestDb<S>>;
65
+ /** A throwaway MySQL database: the same shape as {@link PgTestDb}. */
66
+ export type MysqlTestDb<S> = PgTestDb<S>;
67
+ /**
68
+ * A throwaway database on an existing MySQL server — a shared test container
69
+ * (`kickTestServices`), a CI service, a local Docker MySQL — with the same
70
+ * options as {@link createPgTestDb}. MySQL has no template databases, so the
71
+ * migrations run once into one and each file's database copies its tables,
72
+ * rows and foreign keys; a template with views, triggers or routines is
73
+ * migrated per file instead. Needs `mysql2`.
74
+ */
75
+ export declare function createMysqlTestDb<S>(opts: ServerTestDbOptions<S>): Promise<MysqlTestDb<S>>;
42
76
  /**
43
77
  * Run `fn` in a transaction that's always rolled back — every test starts
44
78
  * from the same data. Code that only holds the client (a service, a
@@ -68,6 +102,5 @@ export declare function captureQueries<T>(db: Observable, fn: () => Promise<T>):
68
102
  * await expectQueries(db, 2, () => postsWithAuthors()) // 1 + 1, not 1 + N
69
103
  */
70
104
  export declare function expectQueries<T>(db: Observable, count: number, fn: () => Promise<T>): Promise<T>;
71
- //#endregion
72
105
  export {};
73
106
  //# sourceMappingURL=testing.d.mts.map
@@ -1 +1 @@
1
- {"version":3,"file":"testing.d.mts","names":[],"sources":["../src/testing.ts"],"mappings":";;;;iBAeiB,cAAc;EAC7B,QAAQ;;;;;EAKR;;EAEA;;;;;;;;wBASoB,aAAa,GACjC,MAAM,cAAc,KACnB,QAAQ,aAAa,cAAc;iBA6BrB,SAAS;EACxB,IAAI,aAAa,cAAc;;EAE/B;;EAEA,QAAQ;;;;;;;;;;;wBAYY,eAAe,GACnC,MAAM,cAAc;;EAElB;IAED,QAAQ,SAAS;;;;;;;;;;wBA8EE,WAAW,GAE/B,IAAI,KAAK,mCACT,UAAU,QAAQ,KACjB,QAAQ;KAcN,aAAa,KAAK;;;;;;;;wBASD,eAAe,GACnC,IAAI,YACJ,UAAU,QAAQ,KACjB;EAAU,QAAQ;EAAG,SAAS;;;;;;;;wBAuBX,cAAc,GAClC,IAAI,YACJ,eACA,UAAU,QAAQ,KACjB,QAAQ"}
1
+ {"version":3,"file":"testing.d.mts","names":[],"sources":["../src/testing.ts"],"mappings":";;;iBAeiB,cAAc;EAC7B,QAAQ;;;;;EAKR;;EAEA;;;;;;;;wBASoB,aAAa,GACjC,MAAM,cAAc,KACnB,QAAQ,aAAa,cAAc;iBA6BrB,SAAS;EACxB,IAAI,aAAa,cAAc;;EAE/B;;EAEA,QAAQ;;;iBAIO,oBAAoB,WAAW,QAAQ,cAAc;;;;;;EAMpE;;EAEA;;;;;EAKA;;;;;;wBAcoB,YAAY;EAChC;EACA;EACA;EACA;IACE;;;;;;;;;;;wBA8DkB,eAAe,GAAG,MAAM,oBAAoB,KAAK,QAAQ,SAAS;;YAqL5E,YAAY,KAAK,SAAS;;;;;;;;;wBAgBhB,kBAAkB,GAAG,MAAM,oBAAoB,KAAK,QAAQ,YAAY;;;;;;;;;;wBAiSxE,WAAW,GAE/B,IAAI,KAAK,mCACT,UAAU,QAAQ,KACjB,QAAQ;KAcN,aAAa,KAAK;;;;;;;;wBASD,eAAe,GACnC,IAAI,YACJ,UAAU,QAAQ,KACjB;EAAU,QAAQ;EAAG,SAAS;;;;;;;;wBAuBX,cAAc,GAClC,IAAI,YACJ,eACA,UAAU,QAAQ,KACjB,QAAQ"}
package/dist/testing.mjs CHANGED
@@ -1,5 +1,5 @@
1
1
  /**
2
- * @forinda/kickjs-db v8.12.4
2
+ * @forinda/kickjs-db v8.14.0
3
3
  *
4
4
  * Copyright (c) Felix Orinda
5
5
  *
@@ -8,6 +8,19 @@
8
8
  *
9
9
  * @license MIT
10
10
  */
11
- import{O as emitPg,Q as extractSnapshot,Y as diff,d as migrateLatest,t as createDbClient,y as emitSqlite,z as EVENTS_ENABLED}from"./create-NrvNUwZr.mjs";import{randomBytes}from"node:crypto";async function createTestDb(opts){let{default:Database}=await import(`better-sqlite3`),{sqliteAdapter,sqliteDialect}=await import(`./sqlite.mjs`),database=new Database(`:memory:`);if(database.pragma(`foreign_keys = ON`),opts.migrationsDir)await migrateLatest({adapter:sqliteAdapter({database}),migrationsDir:opts.migrationsDir,requireReviewed:!1,driftCheck:`ignore`});else{let empty={version:1,dialect:`sqlite`,tables:{}},target=extractSnapshot(opts.schema,`sqlite`,{casing:opts.casing});database.exec(emitSqlite(diff(empty,target),{from:empty,to:target}))}return createDbClient({schema:opts.schema,dialect:sqliteDialect({database}),casing:opts.casing,events:!0})}async function createPgTestDb(opts){let{default:pg}=await import(`pg`),{pgAdapter,pgDialect}=await import(`./pg.mjs`),name=`kick_test_${randomBytes(6).toString(`hex`)}`,admin=new pg.Client({connectionString:opts.connectionString});await admin.connect();try{await admin.query(`CREATE DATABASE "${name}"`)}finally{await admin.end()}let url=new URL(opts.connectionString);url.pathname=`/${name}`;let connectionString=url.toString(),pool=new pg.Pool({connectionString});pool.on(`error`,()=>{}),pool.on(`connect`,client=>client.on(`error`,()=>{})),opts.migrationsDir?await migrateLatest({adapter:pgAdapter({pool}),migrationsDir:opts.migrationsDir,requireReviewed:!1,driftCheck:`ignore`}):await pool.query(emitPg(diff({version:1,dialect:`postgres`,tables:{}},extractSnapshot(opts.schema,`postgres`,{casing:opts.casing}))));let db=createDbClient({schema:opts.schema,dialect:pgDialect({pool}),casing:opts.casing,events:!0});return{db,connectionString,async drop(){await db.destroy();let admin=new pg.Client({connectionString:opts.connectionString});await admin.connect();try{await admin.query(`DROP DATABASE IF EXISTS "${name}" WITH (FORCE)`)}finally{await admin.end()}}}}const ROLLBACK=Symbol(`kickjs-db rolled back`);async function rolledBack(db,fn){let result;return await db.transaction(async()=>{throw result=await fn(),ROLLBACK}).catch(err=>{if(err!==ROLLBACK)throw err}),result}async function captureQueries(db,fn){if(db[EVENTS_ENABLED]===!1)throw Error("captureQueries: this client was created without events, so no query is reported and every count would be 0. Create it with `events: true`.");let queries=[],listener=event=>void queries.push(event);db.on(`query`,listener);try{return{result:await fn(),queries}}finally{db.off(`query`,listener)}}async function expectQueries(db,count,fn){let{result,queries}=await captureQueries(db,fn);if(queries.length!==count){let list=queries.map((q,i)=>` ${i+1}. ${q.sql}`).join(`
12
- `);throw Error(`Expected ${count} quer${count===1?`y`:`ies`}, ran ${queries.length}:\n${list||` (none)`}`)}return result}export{captureQueries,createPgTestDb,createTestDb,expectQueries,rolledBack};
11
+ import{$ as extractSnapshot,B as EVENTS_ENABLED,X as diff,b as emitSqlite,d as migrateLatest,k as emitPg,t as createDbClient}from"./create-CncI2KmH.mjs";import{randomBytes}from"node:crypto";async function createTestDb(opts){let{default:Database}=await import(`better-sqlite3`),{sqliteAdapter,sqliteDialect}=await import(`./sqlite.mjs`),database=new Database(`:memory:`);if(database.pragma(`foreign_keys = ON`),opts.migrationsDir)await migrateLatest({adapter:sqliteAdapter({database}),migrationsDir:opts.migrationsDir,requireReviewed:!1,driftCheck:`ignore`});else{let empty={version:1,dialect:`sqlite`,tables:{}},target=extractSnapshot(opts.schema,`sqlite`,{casing:opts.casing});database.exec(emitSqlite(diff(empty,target),{from:empty,to:target}))}return createDbClient({schema:opts.schema,dialect:sqliteDialect({database}),casing:opts.casing,events:!0})}const lockTimedOut=(template,seconds)=>/* @__PURE__ */ Error(`@forinda/kickjs-db/testing: waited ${seconds}s for the lock on ${template} — another test file is building that template. Raise lockWaitSeconds (and your hook timeout) if your migrations take longer.`);async function templateKey(input){let{createHash}=await import(`node:crypto`),h=createHash(`sha256`).update(`${input.dialect??`postgres`}\0${input.casing??``}\0`);if(input.migrationsDir){let{readdir,readFile}=await import(`node:fs/promises`),path=await import(`node:path`),files=[],walk=async rel=>{for(let e of await readdir(path.join(input.migrationsDir,rel),{withFileTypes:!0})){let child=rel?`${rel}/${e.name}`:e.name;e.isDirectory()?await walk(child):e.isFile()&&files.push(child)}};await walk(``);for(let f of files.toSorted())h.update(f).update(`\0`).update(await readFile(path.join(input.migrationsDir,f)))}else h.update(JSON.stringify(extractSnapshot(input.schema,input.dialect??`postgres`,{casing:input.casing})));return h.digest(`hex`).slice(0,12)}function guardTestServer(url,allow){let name=decodeURIComponent(new URL(url).pathname.slice(1));if(!(allow||/test/i.test(name)))throw Error(`@forinda/kickjs-db/testing: refusing to create test databases from "${name}": its name must contain "test" (pass allowNonTestDatabase: true to override)`)}const createdNote=kind=>`${kind} created ${(/* @__PURE__ */ new Date()).toISOString()}`,SWEEP_AFTER={kick_test:216e5,kick_tpl:864e5};let pgSwept=!1;async function createPgTestDb(opts){let server=opts.connectionString??process.env.KICK_TEST_POSTGRES_URL;if(!server)throw Error(`@forinda/kickjs-db/testing: createPgTestDb needs a connectionString (or KICK_TEST_POSTGRES_URL, set by kickTestServices)`);guardTestServer(server,opts.allowNonTestDatabase);let{default:pg}=await import(`pg`),name=`kick_test_${randomBytes(6).toString(`hex`)}`,urlOf=db=>{let url=new URL(server);return url.pathname=`/${db}`,url.toString()},admin=new pg.Client({connectionString:server});await admin.connect();try{if(pgSwept||(pgSwept=!0,await sweepPg(admin)),opts.migrationsDir||opts.schema){let template=`kick_tpl_${await templateKey({migrationsDir:opts.migrationsDir,schema:opts.schema,casing:opts.casing})}`,wait=opts.lockWaitSeconds??120;await admin.query(`SET lock_timeout = '${Math.max(1,Math.floor(wait))}s'`),await admin.query(`select pg_advisory_lock(hashtext($1))`,[template]).catch(err=>{throw err.code===`55P03`?lockTimedOut(template,wait):err}),await admin.query(`RESET lock_timeout`);try{let{rows}=await admin.query(`select shobj_description(oid, 'pg_database') as note from pg_database where datname = $1`,[template]);(rows[0]?.note?.startsWith(`kick_tpl created `)??!1)||(rows.length&&await admin.query(`DROP DATABASE IF EXISTS "${template}" WITH (FORCE)`),await buildPgTemplate(pg,admin,template,urlOf(template),opts)),await admin.query(`CREATE DATABASE "${name}" TEMPLATE "${template}"`)}finally{await admin.query(`select pg_advisory_unlock(hashtext($1))`,[template])}}else await admin.query(`CREATE DATABASE "${name}"`);await admin.query(`COMMENT ON DATABASE "${name}" IS '${createdNote(`kick_test`)}'`)}finally{await admin.end()}let connectionString=urlOf(name),{pgDialect}=await import(`./pg.mjs`),pool=new pg.Pool({connectionString});pool.on(`error`,()=>{}),pool.on(`connect`,client=>client.on(`error`,()=>{}));let db=createDbClient({schema:opts.schema??{},dialect:pgDialect({pool}),casing:opts.casing,events:!0});return{db,connectionString,async drop(){await db.destroy();let admin=new pg.Client({connectionString:server});await admin.connect();try{await admin.query(`DROP DATABASE IF EXISTS "${name}" WITH (FORCE)`)}finally{await admin.end()}}}}async function buildPgTemplate(pg,admin,template,url,opts){await admin.query(`CREATE DATABASE "${template}"`);try{let pool=new pg.Pool({connectionString:url});pool.on(`error`,()=>{});try{if(opts.migrationsDir){let{pgAdapter}=await import(`./pg.mjs`);await migrateLatest({adapter:pgAdapter({pool}),migrationsDir:opts.migrationsDir,requireReviewed:!1,driftCheck:`ignore`})}else await pool.query(emitPg(diff({version:1,dialect:`postgres`,tables:{}},extractSnapshot(opts.schema,`postgres`,{casing:opts.casing}))))}finally{await pool.end()}await admin.query(`COMMENT ON DATABASE "${template}" IS '${createdNote(`kick_tpl`)}'`)}catch(err){throw await admin.query(`DROP DATABASE IF EXISTS "${template}" WITH (FORCE)`).catch(()=>{}),err}}async function sweepPg(admin){let{rows}=await admin.query(`select d.datname, shobj_description(d.oid, 'pg_database') as note
12
+ from pg_database d where d.datname like 'kick\\_test\\_%' or d.datname like 'kick\\_tpl\\_%'`),now=Date.now();for(let{datname,note}of rows){let m=/^(kick_test|kick_tpl) created (.+)$/.exec(note??``);if(!m)continue;let at=Date.parse(m[2]);if(!(Number.isNaN(at)||now-at<SWEEP_AFTER[m[1]])){if(m[1]===`kick_tpl`){let{rows:got}=await admin.query(`select pg_try_advisory_lock(hashtext($1)) as ok`,[datname]);if(!got[0]?.ok)continue;try{let{rows:now2}=await admin.query(`select shobj_description(oid, 'pg_database') as note from pg_database where datname = $1`,[datname]),again=/^kick_tpl created (.+)$/.exec(now2[0]?.note??``);again&&Date.now()-Date.parse(again[1])>=SWEEP_AFTER.kick_tpl&&await admin.query(`DROP DATABASE IF EXISTS "${datname}"`).catch(()=>{})}finally{await admin.query(`select pg_advisory_unlock(hashtext($1))`,[datname])}}else await admin.query(`DROP DATABASE IF EXISTS "${datname}"`).catch(()=>{})}}}const MYSQL_META=`kicktest_meta`;let mysqlSwept=!1;async function createMysqlTestDb(opts){let server=opts.connectionString??process.env.KICK_TEST_MYSQL_URL;if(!server)throw Error(`@forinda/kickjs-db/testing: createMysqlTestDb needs a connectionString (or KICK_TEST_MYSQL_URL, set by kickTestServices)`);guardTestServer(server,opts.allowNonTestDatabase);let mysql=await import(`mysql2/promise`),name=`kick_test_${randomBytes(6).toString(`hex`)}`,urlOf=db=>{let url=new URL(server);return url.pathname=`/${db}`,url.toString()},admin=await mysql.createConnection({uri:server,multipleStatements:!0});try{if(await admin.query(`CREATE DATABASE IF NOT EXISTS \`${MYSQL_META}\``),await admin.query(`CREATE TABLE IF NOT EXISTS \`${MYSQL_META}\`.dbs (name varchar(64) PRIMARY KEY, created_at bigint NOT NULL)`),mysqlSwept||(mysqlSwept=!0,await sweepMysql(admin)),opts.migrationsDir||opts.schema){let template=`kick_tpl_${await templateKey({migrationsDir:opts.migrationsDir,schema:opts.schema,casing:opts.casing,dialect:`mysql`})}`,wait=opts.lockWaitSeconds??120,[locked]=await admin.query(`SELECT GET_LOCK(?, ?) AS got`,[template,wait]);if(Number(locked[0]?.got)!==1)throw lockTimedOut(template,wait);try{let[done]=await admin.query(`SELECT 1 FROM \`${MYSQL_META}\`.dbs WHERE name = ?`,[template]);done.length||(await admin.query(`DROP DATABASE IF EXISTS \`${template}\``),await buildMysql(mysql,admin,template,urlOf(template),opts,!0)),await mysqlHasProgrammables(admin,template)?await buildMysql(mysql,admin,name,urlOf(name),opts,!1):await copyMysql(admin,template,name)}finally{await admin.query(`SELECT RELEASE_LOCK(?)`,[template])}}else await admin.query(`CREATE DATABASE \`${name}\``);await admin.query(`INSERT INTO \`${MYSQL_META}\`.dbs VALUES (?, ?)`,[name,Date.now()])}finally{await admin.end()}let connectionString=urlOf(name),{mysqlDialect}=await import(`./mysql.mjs`),pool=mysql.createPool({uri:connectionString}),db=createDbClient({schema:opts.schema??{},dialect:mysqlDialect({pool}),casing:opts.casing,events:!0});return{db,connectionString,async drop(){await db.destroy();let admin=await mysql.createConnection({uri:server});try{await admin.query(`DROP DATABASE IF EXISTS \`${name}\``),await admin.query(`DELETE FROM \`${MYSQL_META}\`.dbs WHERE name = ?`,[name])}finally{await admin.end()}}}}async function buildMysql(mysql,admin,db,url,opts,template){await admin.query(`CREATE DATABASE \`${db}\``);try{let pool=mysql.createPool({uri:url,multipleStatements:!0});try{if(opts.migrationsDir){let{mysqlAdapter}=await import(`./mysql.mjs`);await migrateLatest({adapter:mysqlAdapter({pool}),migrationsDir:opts.migrationsDir,requireReviewed:!1,driftCheck:`ignore`})}else{let{emitMysql}=await import(`./create-CncI2KmH.mjs`).then(n=>n.v);await pool.query(emitMysql(diff({version:1,dialect:`mysql`,tables:{}},extractSnapshot(opts.schema,`mysql`,{casing:opts.casing}))))}}finally{await pool.end()}template&&await admin.query(`INSERT INTO \`${MYSQL_META}\`.dbs VALUES (?, ?)`,[db,Date.now()])}catch(err){throw await admin.query(`DROP DATABASE IF EXISTS \`${db}\``).catch(()=>{}),err}}async function mysqlHasProgrammables(admin,db){let[rows]=await admin.query(`SELECT (SELECT COUNT(*) FROM information_schema.VIEWS WHERE TABLE_SCHEMA = ?)
13
+ + (SELECT COUNT(*) FROM information_schema.TRIGGERS WHERE TRIGGER_SCHEMA = ?)
14
+ + (SELECT COUNT(*) FROM information_schema.ROUTINES WHERE ROUTINE_SCHEMA = ?) AS n`,[db,db,db]);return Number(rows[0].n)>0}async function copyMysql(admin,from,to){await admin.query(`CREATE DATABASE \`${to}\``);try{await copyMysqlInto(admin,from,to)}catch(err){throw await admin.query(`DROP DATABASE IF EXISTS \`${to}\``).catch(()=>{}),err}}async function copyMysqlInto(admin,from,to){let[tables]=await admin.query(`SELECT TABLE_NAME AS t FROM information_schema.TABLES WHERE TABLE_SCHEMA = ? AND TABLE_TYPE = 'BASE TABLE'`,[from]),names=tables.map(r=>r.t);await admin.query(`SET FOREIGN_KEY_CHECKS = 0`);try{for(let t of names){await admin.query(`CREATE TABLE \`${to}\`.\`${t}\` LIKE \`${from}\`.\`${t}\``);let[cols]=await admin.query(`SELECT COLUMN_NAME AS c FROM information_schema.COLUMNS
15
+ WHERE TABLE_SCHEMA = ? AND TABLE_NAME = ? AND EXTRA NOT LIKE '%GENERATED%'
16
+ ORDER BY ORDINAL_POSITION`,[from,t]),list=cols.map(r=>`\`${r.c}\``).join(`, `);list&&await admin.query(`INSERT INTO \`${to}\`.\`${t}\` (${list}) SELECT ${list} FROM \`${from}\`.\`${t}\``)}let[fks]=await admin.query(`SELECT k.TABLE_NAME AS t, k.CONSTRAINT_NAME AS c, k.COLUMN_NAME AS col,
17
+ k.REFERENCED_TABLE_NAME AS rt, k.REFERENCED_COLUMN_NAME AS rcol,
18
+ r.DELETE_RULE AS del, r.UPDATE_RULE AS upd
19
+ FROM information_schema.KEY_COLUMN_USAGE k
20
+ JOIN information_schema.REFERENTIAL_CONSTRAINTS r
21
+ ON r.CONSTRAINT_SCHEMA = k.CONSTRAINT_SCHEMA AND r.CONSTRAINT_NAME = k.CONSTRAINT_NAME
22
+ WHERE k.TABLE_SCHEMA = ? AND k.REFERENCED_TABLE_NAME IS NOT NULL
23
+ ORDER BY k.TABLE_NAME, k.CONSTRAINT_NAME, k.ORDINAL_POSITION`,[from]),byKey=/* @__PURE__ */ new Map;for(let f of fks){let k=`${f.t}\0${f.c}`,e=byKey.get(k)??{t:f.t,c:f.c,cols:[],rt:f.rt,rcols:[],del:f.del,upd:f.upd};e.cols.push(f.col),e.rcols.push(f.rcol),byKey.set(k,e)}let q=c=>c.map(x=>`\`${x}\``).join(`, `);for(let f of byKey.values())await admin.query(`ALTER TABLE \`${to}\`.\`${f.t}\` ADD CONSTRAINT \`${f.c}\` FOREIGN KEY (${q(f.cols)})
24
+ REFERENCES \`${to}\`.\`${f.rt}\` (${q(f.rcols)}) ON DELETE ${f.del} ON UPDATE ${f.upd}`)}finally{await admin.query(`SET FOREIGN_KEY_CHECKS = 1`)}}async function sweepMysql(admin){let[rows]=await admin.query(`SELECT name, created_at FROM \`${MYSQL_META}\`.dbs`),[busy]=await admin.query(`SELECT DISTINCT DB AS db FROM information_schema.PROCESSLIST WHERE DB IS NOT NULL`),inUse=new Set(busy.map(r=>r.db)),now=Date.now();for(let{name,created_at}of rows){let kind=name.startsWith(`kick_tpl_`)?`kick_tpl`:`kick_test`;if(!(now-Number(created_at)<SWEEP_AFTER[kind]||inUse.has(name))){if(kind===`kick_tpl`){let[got]=await admin.query(`SELECT GET_LOCK(?, 0) AS got`,[name]);if(Number(got[0]?.got)!==1)continue}try{if(kind===`kick_tpl`){let[again]=await admin.query(`SELECT created_at FROM \`${MYSQL_META}\`.dbs WHERE name = ?`,[name]),at=again[0]?.created_at;if(at===void 0||Date.now()-Number(at)<SWEEP_AFTER.kick_tpl)continue}await admin.query(`DROP DATABASE IF EXISTS \`${name}\``).catch(()=>{}),await admin.query(`DELETE FROM \`${MYSQL_META}\`.dbs WHERE name = ?`,[name])}finally{kind===`kick_tpl`&&await admin.query(`SELECT RELEASE_LOCK(?)`,[name])}}}}const ROLLBACK=Symbol(`kickjs-db rolled back`);async function rolledBack(db,fn){let result;return await db.transaction(async()=>{throw result=await fn(),ROLLBACK}).catch(err=>{if(err!==ROLLBACK)throw err}),result}async function captureQueries(db,fn){if(db[EVENTS_ENABLED]===!1)throw Error("captureQueries: this client was created without events, so no query is reported and every count would be 0. Create it with `events: true`.");let queries=[],listener=event=>void queries.push(event);db.on(`query`,listener);try{return{result:await fn(),queries}}finally{db.off(`query`,listener)}}async function expectQueries(db,count,fn){let{result,queries}=await captureQueries(db,fn);if(queries.length!==count){let list=queries.map((q,i)=>` ${i+1}. ${q.sql}`).join(`
25
+ `);throw Error(`Expected ${count} quer${count===1?`y`:`ies`}, ran ${queries.length}:\n${list||` (none)`}`)}return result}export{captureQueries,createMysqlTestDb,createPgTestDb,createTestDb,expectQueries,rolledBack,templateKey};
13
26
  //# sourceMappingURL=testing.mjs.map
@@ -1 +1 @@
1
- {"version":3,"file":"testing.mjs","names":[],"sources":["../src/testing.ts"],"sourcesContent":["// `@forinda/kickjs-db/testing` — test helpers (D.15): a throwaway database\n// per test file, and a transaction per test that never commits.\nimport { randomBytes } from 'node:crypto'\nimport { createDbClient } from './client/create'\nimport { EVENTS_ENABLED } from './client/events'\nimport type { QueryEvent } from './client/types'\nimport type { KickDbClient } from './client/types'\nimport type { SchemaToTypes } from './client/schema-types'\nimport { diff } from './diff/engine'\nimport { emitPg } from './emit/pg'\nimport { emitSqlite } from './emit/sqlite'\nimport { migrateLatest } from './migrate/runner'\nimport { extractSnapshot } from './snapshot/extract'\nimport type { SchemaSnapshot } from './snapshot/types'\n\nexport interface TestDbOptions<S> {\n schema: S\n /**\n * Apply these migrations instead of creating tables straight from the\n * schema — the SQL production runs. Unreviewed ones apply too.\n */\n migrationsDir?: string\n /** The `casing` your client and `kick.config.ts` use. */\n casing?: 'snake_case'\n}\n\n/**\n * A fresh in-memory SQLite database with your schema, foreign keys on —\n * milliseconds to create, one per test file. Needs `better-sqlite3`.\n *\n * const db = await createTestDb({ schema })\n */\nexport async function createTestDb<S>(\n opts: TestDbOptions<S>,\n): Promise<KickDbClient<SchemaToTypes<S>>> {\n const { default: Database } = await import('better-sqlite3')\n const { sqliteAdapter, sqliteDialect } = await import('./sqlite')\n const database = new Database(':memory:')\n database.pragma('foreign_keys = ON')\n\n if (opts.migrationsDir) {\n await migrateLatest({\n adapter: sqliteAdapter({ database }),\n migrationsDir: opts.migrationsDir,\n requireReviewed: false,\n driftCheck: 'ignore',\n })\n } else {\n const empty: SchemaSnapshot = { version: 1, dialect: 'sqlite', tables: {} }\n const target = extractSnapshot(opts.schema as Record<string, unknown>, 'sqlite', {\n casing: opts.casing,\n })\n database.exec(emitSqlite(diff(empty, target), { from: empty, to: target }))\n }\n return createDbClient({\n schema: opts.schema,\n dialect: sqliteDialect({ database }),\n casing: opts.casing,\n // On, so captureQueries / expectQueries can count.\n events: true,\n }) as never\n}\n\nexport interface PgTestDb<S> {\n db: KickDbClient<SchemaToTypes<S>>\n /** The throwaway database's connection string — for code that opens its own pool. */\n connectionString: string\n /** Close the client and drop the database. Call it in `afterAll`. */\n drop(): Promise<void>\n}\n\n/**\n * A throwaway database on an existing Postgres server — a CI service\n * container, a local Docker Postgres — with your schema or migrations\n * applied. Creating one takes well under a second, so each test file can\n * have its own without starting a container. Needs `pg`.\n *\n * const pg = await createPgTestDb({ schema, connectionString: process.env.TEST_DATABASE_URL! })\n * afterAll(() => pg.drop())\n */\nexport async function createPgTestDb<S>(\n opts: TestDbOptions<S> & {\n /** A database on the server to connect to first, with permission to CREATE DATABASE. */\n connectionString: string\n },\n): Promise<PgTestDb<S>> {\n const { default: pg } = await import('pg')\n const { pgAdapter, pgDialect } = await import('./pg')\n const name = `kick_test_${randomBytes(6).toString('hex')}`\n\n const admin = new pg.Client({ connectionString: opts.connectionString })\n await admin.connect()\n try {\n await admin.query(`CREATE DATABASE \"${name}\"`)\n } finally {\n await admin.end()\n }\n\n const url = new URL(opts.connectionString)\n url.pathname = `/${name}`\n const connectionString = url.toString()\n const pool = new pg.Pool({ connectionString })\n // Dropped connections at teardown aren't test failures. The client-level\n // listener matters: `pool.end()` resolves before a client's socket closes,\n // and the pool detaches its own listener first, so the FORCE drop's\n // termination would otherwise surface as an uncaught error.\n pool.on('error', () => {})\n pool.on('connect', (client) => client.on('error', () => {}))\n\n if (opts.migrationsDir) {\n await migrateLatest({\n adapter: pgAdapter({ pool }),\n migrationsDir: opts.migrationsDir,\n requireReviewed: false,\n driftCheck: 'ignore',\n })\n } else {\n const empty: SchemaSnapshot = { version: 1, dialect: 'postgres', tables: {} }\n await pool.query(\n emitPg(\n diff(\n empty,\n extractSnapshot(opts.schema as Record<string, unknown>, 'postgres', {\n casing: opts.casing,\n }),\n ),\n ),\n )\n }\n\n const db = createDbClient({\n schema: opts.schema,\n dialect: pgDialect({ pool }),\n casing: opts.casing,\n events: true,\n }) as never as KickDbClient<SchemaToTypes<S>>\n return {\n db,\n connectionString,\n async drop() {\n await db.destroy() // ends the pool\n const admin = new pg.Client({ connectionString: opts.connectionString })\n await admin.connect()\n try {\n await admin.query(`DROP DATABASE IF EXISTS \"${name}\" WITH (FORCE)`)\n } finally {\n await admin.end()\n }\n },\n }\n}\n\nconst ROLLBACK = Symbol('kickjs-db rolled back')\n\n/**\n * Run `fn` in a transaction that's always rolled back — every test starts\n * from the same data. Code that only holds the client (a service, a\n * repository) joins the transaction through the call chain, so nothing it\n * writes survives. `afterCommit` hooks don't run. A real failure in `fn`\n * still throws.\n *\n * it('creates a user', () => rolledBack(db, async () => { … }))\n */\nexport async function rolledBack<T>(\n // oxlint-disable-next-line no-explicit-any -- any schema's client\n db: Pick<KickDbClient<any>, 'transaction'>,\n fn: () => Promise<T>,\n): Promise<T> {\n let result!: T\n await db\n .transaction(async () => {\n result = await fn()\n throw ROLLBACK\n })\n .catch((err: unknown) => {\n if (err !== ROLLBACK) throw err\n })\n return result\n}\n\n// oxlint-disable-next-line no-explicit-any -- any schema's client\ntype Observable = Pick<KickDbClient<any>, 'on' | 'off'>\n\n/**\n * Run `fn` and return the queries it sent, in order. The client must have\n * events on — `createTestDb` / `createPgTestDb` clients do; your own needs\n * `createDbClient({ events: true })`.\n *\n * const { result, queries } = await captureQueries(db, () => repo.list())\n */\nexport async function captureQueries<T>(\n db: Observable,\n fn: () => Promise<T>,\n): Promise<{ result: T; queries: QueryEvent[] }> {\n if ((db as unknown as Record<symbol, unknown>)[EVENTS_ENABLED] === false) {\n throw new Error(\n 'captureQueries: this client was created without events, so no query is reported ' +\n 'and every count would be 0. Create it with `events: true`.',\n )\n }\n const queries: QueryEvent[] = []\n const listener = (event: QueryEvent) => void queries.push(event)\n db.on('query', listener)\n try {\n return { result: await fn(), queries }\n } finally {\n db.off('query', listener)\n }\n}\n\n/**\n * Assert `fn` sends exactly `count` queries — a guard against N+1 queries\n * that grows with the data. On a mismatch the error lists every query sent.\n *\n * await expectQueries(db, 2, () => postsWithAuthors()) // 1 + 1, not 1 + N\n */\nexport async function expectQueries<T>(\n db: Observable,\n count: number,\n fn: () => Promise<T>,\n): Promise<T> {\n const { result, queries } = await captureQueries(db, fn)\n if (queries.length !== count) {\n const list = queries.map((q, i) => ` ${i + 1}. ${q.sql}`).join('\\n')\n throw new Error(\n `Expected ${count} quer${count === 1 ? 'y' : 'ies'}, ran ${queries.length}:\\n${list || ' (none)'}`,\n )\n }\n return result\n}\n"],"mappings":"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"}
1
+ {"version":3,"file":"testing.mjs","names":[],"sources":["../src/testing.ts"],"sourcesContent":["// `@forinda/kickjs-db/testing` — test helpers (D.15): a throwaway database\n// per test file, and a transaction per test that never commits.\nimport { randomBytes } from 'node:crypto'\nimport { createDbClient } from './client/create'\nimport { EVENTS_ENABLED } from './client/events'\nimport type { QueryEvent } from './client/types'\nimport type { KickDbClient } from './client/types'\nimport type { SchemaToTypes } from './client/schema-types'\nimport { diff } from './diff/engine'\nimport { emitPg } from './emit/pg'\nimport { emitSqlite } from './emit/sqlite'\nimport { migrateLatest } from './migrate/runner'\nimport { extractSnapshot } from './snapshot/extract'\nimport type { SchemaSnapshot } from './snapshot/types'\n\nexport interface TestDbOptions<S> {\n schema: S\n /**\n * Apply these migrations instead of creating tables straight from the\n * schema — the SQL production runs. Unreviewed ones apply too.\n */\n migrationsDir?: string\n /** The `casing` your client and `kick.config.ts` use. */\n casing?: 'snake_case'\n}\n\n/**\n * A fresh in-memory SQLite database with your schema, foreign keys on —\n * milliseconds to create, one per test file. Needs `better-sqlite3`.\n *\n * const db = await createTestDb({ schema })\n */\nexport async function createTestDb<S>(\n opts: TestDbOptions<S>,\n): Promise<KickDbClient<SchemaToTypes<S>>> {\n const { default: Database } = await import('better-sqlite3')\n const { sqliteAdapter, sqliteDialect } = await import('./sqlite')\n const database = new Database(':memory:')\n database.pragma('foreign_keys = ON')\n\n if (opts.migrationsDir) {\n await migrateLatest({\n adapter: sqliteAdapter({ database }),\n migrationsDir: opts.migrationsDir,\n requireReviewed: false,\n driftCheck: 'ignore',\n })\n } else {\n const empty: SchemaSnapshot = { version: 1, dialect: 'sqlite', tables: {} }\n const target = extractSnapshot(opts.schema as Record<string, unknown>, 'sqlite', {\n casing: opts.casing,\n })\n database.exec(emitSqlite(diff(empty, target), { from: empty, to: target }))\n }\n return createDbClient({\n schema: opts.schema,\n dialect: sqliteDialect({ database }),\n casing: opts.casing,\n // On, so captureQueries / expectQueries can count.\n events: true,\n }) as never\n}\n\nexport interface PgTestDb<S> {\n db: KickDbClient<SchemaToTypes<S>>\n /** The throwaway database's connection string — for code that opens its own pool. */\n connectionString: string\n /** Close the client and drop the database. Call it in `afterAll`. */\n drop(): Promise<void>\n}\n\n/** Options for a throwaway database on a shared server (Postgres or MySQL). */\nexport interface ServerTestDbOptions<S> extends Partial<TestDbOptions<S>> {\n /**\n * A database on the server to connect to first, with permission to CREATE\n * DATABASE. Default: `KICK_TEST_POSTGRES_URL` / `KICK_TEST_MYSQL_URL`, which\n * `kickTestServices` sets.\n */\n connectionString?: string\n /** Allow a server URL whose database name doesn't contain `test`. */\n allowNonTestDatabase?: boolean\n /**\n * How long a file waits for another file building the same template\n * (default 120 s). Keep your test runner's hook timeout above it.\n */\n lockWaitSeconds?: number\n}\n\n/** Waiting for the template lock took too long: say what it was waiting for. */\nconst lockTimedOut = (template: string, seconds: number) =>\n new Error(\n `@forinda/kickjs-db/testing: waited ${seconds}s for the lock on ${template} — another test file is ` +\n 'building that template. Raise lockWaitSeconds (and your hook timeout) if your migrations take longer.',\n )\n\n/**\n * A short key for what a template holds: the migrations' files, or the\n * schema's snapshot when there are none — so a change makes a new template.\n */\nexport async function templateKey(input: {\n migrationsDir?: string\n schema?: unknown\n casing?: string\n dialect?: 'postgres' | 'mysql'\n}): Promise<string> {\n const { createHash } = await import('node:crypto')\n const h = createHash('sha256').update(`${input.dialect ?? 'postgres'}\\0${input.casing ?? ''}\\0`)\n if (input.migrationsDir) {\n const { readdir, readFile } = await import('node:fs/promises')\n const path = await import('node:path')\n // Walked by hand: recursive readdir and Dirent.parentPath need Node 20.12+.\n const files: string[] = []\n const walk = async (rel: string): Promise<void> => {\n for (const e of await readdir(path.join(input.migrationsDir!, rel), {\n withFileTypes: true,\n })) {\n const child = rel ? `${rel}/${e.name}` : e.name\n if (e.isDirectory()) await walk(child)\n else if (e.isFile()) files.push(child)\n }\n }\n await walk('')\n for (const f of files.toSorted()) {\n h.update(f)\n .update('\\0')\n .update(await readFile(path.join(input.migrationsDir, f)))\n }\n } else {\n h.update(\n JSON.stringify(\n extractSnapshot(input.schema as Record<string, unknown>, input.dialect ?? 'postgres', {\n casing: input.casing as 'snake_case' | undefined,\n }),\n ),\n )\n }\n return h.digest('hex').slice(0, 12)\n}\n\n/** Refuse a server whose database name doesn't say it's for tests. */\nfunction guardTestServer(url: string, allow: boolean | undefined): void {\n const name = decodeURIComponent(new URL(url).pathname.slice(1))\n if (allow || /test/i.test(name)) return\n throw new Error(\n `@forinda/kickjs-db/testing: refusing to create test databases from \"${name}\": its name must contain \"test\" ` +\n '(pass allowNonTestDatabase: true to override)',\n )\n}\n\n/** When a test database was made, written on it so a later run can sweep leftovers. */\nconst createdNote = (kind: 'kick_test' | 'kick_tpl') =>\n `${kind} created ${new Date().toISOString()}`\nconst SWEEP_AFTER = { kick_test: 6 * 3_600_000, kick_tpl: 24 * 3_600_000 }\n\nlet pgSwept = false\n\n/**\n * A throwaway database on an existing Postgres server — a shared test\n * container (`kickTestServices`), a CI service container, a local Docker\n * Postgres. With `migrationsDir` (or `schema`) it's a copy of a template\n * database migrated once, so creating one stays well under a second however\n * many migrations there are; with neither, it's empty. Needs `pg`.\n *\n * const pg = await createPgTestDb({ migrationsDir: 'db/migrations' })\n * afterAll(() => pg.drop())\n */\nexport async function createPgTestDb<S>(opts: ServerTestDbOptions<S>): Promise<PgTestDb<S>> {\n const server = opts.connectionString ?? process.env.KICK_TEST_POSTGRES_URL\n if (!server) {\n throw new Error(\n '@forinda/kickjs-db/testing: createPgTestDb needs a connectionString (or KICK_TEST_POSTGRES_URL, set by kickTestServices)',\n )\n }\n guardTestServer(server, opts.allowNonTestDatabase)\n const { default: pg } = await import('pg')\n const name = `kick_test_${randomBytes(6).toString('hex')}`\n const urlOf = (db: string) => {\n const url = new URL(server)\n url.pathname = `/${db}`\n return url.toString()\n }\n\n const admin = new pg.Client({ connectionString: server })\n await admin.connect()\n try {\n if (!pgSwept) {\n pgSwept = true\n await sweepPg(admin)\n }\n if (opts.migrationsDir || opts.schema) {\n const key = await templateKey({\n migrationsDir: opts.migrationsDir,\n schema: opts.schema,\n casing: opts.casing,\n })\n const template = `kick_tpl_${key}`\n // One process builds a template; the rest wait for it, then copy.\n // Copies wait too: Postgres won't copy a database someone is in.\n const wait = opts.lockWaitSeconds ?? 120\n await admin.query(`SET lock_timeout = '${Math.max(1, Math.floor(wait))}s'`)\n await admin.query('select pg_advisory_lock(hashtext($1))', [template]).catch((err) => {\n if ((err as { code?: string }).code === '55P03') throw lockTimedOut(template, wait)\n throw err\n })\n await admin.query('RESET lock_timeout')\n try {\n const { rows } = await admin.query<{ note: string | null }>(\n `select shobj_description(oid, 'pg_database') as note from pg_database where datname = $1`,\n [template],\n )\n // A template is finished once its note is written — last, after the\n // migrations. One without it is what a killed build left: rebuild.\n const finished = rows[0]?.note?.startsWith('kick_tpl created ') ?? false\n if (!finished) {\n if (rows.length) await admin.query(`DROP DATABASE IF EXISTS \"${template}\" WITH (FORCE)`)\n await buildPgTemplate(pg, admin, template, urlOf(template), opts)\n }\n await admin.query(`CREATE DATABASE \"${name}\" TEMPLATE \"${template}\"`)\n } finally {\n await admin.query('select pg_advisory_unlock(hashtext($1))', [template])\n }\n } else {\n await admin.query(`CREATE DATABASE \"${name}\"`)\n }\n await admin.query(`COMMENT ON DATABASE \"${name}\" IS '${createdNote('kick_test')}'`)\n } finally {\n await admin.end()\n }\n\n const connectionString = urlOf(name)\n const { pgDialect } = await import('./pg')\n const pool = new pg.Pool({ connectionString })\n // Dropped connections at teardown aren't test failures. The client-level\n // listener matters: `pool.end()` resolves before a client's socket closes,\n // and the pool detaches its own listener first, so the FORCE drop's\n // termination would otherwise surface as an uncaught error.\n pool.on('error', () => {})\n pool.on('connect', (client) => client.on('error', () => {}))\n\n const db = createDbClient({\n schema: opts.schema ?? {},\n dialect: pgDialect({ pool }),\n casing: opts.casing,\n events: true,\n }) as never as KickDbClient<SchemaToTypes<S>>\n return {\n db,\n connectionString,\n async drop() {\n await db.destroy() // ends the pool\n const admin = new pg.Client({ connectionString: server })\n await admin.connect()\n try {\n await admin.query(`DROP DATABASE IF EXISTS \"${name}\" WITH (FORCE)`)\n } finally {\n await admin.end()\n }\n },\n }\n}\n\ntype PgModule = typeof import('pg').default\n\n/** Create `template` and apply the migrations (or the schema) to it. */\nasync function buildPgTemplate<S>(\n pg: PgModule,\n admin: import('pg').Client,\n template: string,\n url: string,\n opts: ServerTestDbOptions<S>,\n): Promise<void> {\n await admin.query(`CREATE DATABASE \"${template}\"`)\n try {\n const pool = new pg.Pool({ connectionString: url })\n pool.on('error', () => {})\n try {\n if (opts.migrationsDir) {\n const { pgAdapter } = await import('./pg')\n await migrateLatest({\n adapter: pgAdapter({ pool }),\n migrationsDir: opts.migrationsDir,\n requireReviewed: false,\n driftCheck: 'ignore',\n })\n } else {\n const empty: SchemaSnapshot = { version: 1, dialect: 'postgres', tables: {} }\n await pool.query(\n emitPg(\n diff(\n empty,\n extractSnapshot(opts.schema as Record<string, unknown>, 'postgres', {\n casing: opts.casing,\n }),\n ),\n ),\n )\n }\n } finally {\n await pool.end()\n }\n await admin.query(`COMMENT ON DATABASE \"${template}\" IS '${createdNote('kick_tpl')}'`)\n } catch (err) {\n // A half-built template must not be copied by the next file.\n await admin.query(`DROP DATABASE IF EXISTS \"${template}\" WITH (FORCE)`).catch(() => {})\n throw err\n }\n}\n\n/** Drop test databases and templates a crashed run left, once per process; ones in use are skipped. */\nasync function sweepPg(admin: import('pg').Client): Promise<void> {\n const { rows } = await admin.query<{ datname: string; note: string | null }>(\n `select d.datname, shobj_description(d.oid, 'pg_database') as note\n from pg_database d where d.datname like 'kick\\\\_test\\\\_%' or d.datname like 'kick\\\\_tpl\\\\_%'`,\n )\n const now = Date.now()\n for (const { datname, note } of rows) {\n const m = /^(kick_test|kick_tpl) created (.+)$/.exec(note ?? '')\n if (!m) continue\n const at = Date.parse(m[2]!)\n if (Number.isNaN(at) || now - at < SWEEP_AFTER[m[1] as 'kick_test' | 'kick_tpl']) continue\n if (m[1] === 'kick_tpl') {\n // A template only under its lock: another file may be about to copy it.\n const { rows: got } = await admin.query<{ ok: boolean }>(\n 'select pg_try_advisory_lock(hashtext($1)) as ok',\n [datname],\n )\n if (!got[0]?.ok) continue\n try {\n // Read again under the lock: another file may have rebuilt it since.\n const { rows: now2 } = await admin.query<{ note: string | null }>(\n `select shobj_description(oid, 'pg_database') as note from pg_database where datname = $1`,\n [datname],\n )\n const again = /^kick_tpl created (.+)$/.exec(now2[0]?.note ?? '')\n const stillOld = again && Date.now() - Date.parse(again[1]!) >= SWEEP_AFTER.kick_tpl\n if (stillOld) await admin.query(`DROP DATABASE IF EXISTS \"${datname}\"`).catch(() => {})\n } finally {\n await admin.query('select pg_advisory_unlock(hashtext($1))', [datname])\n }\n continue\n }\n // No FORCE: one still in use (another run's) fails, and is left alone.\n await admin.query(`DROP DATABASE IF EXISTS \"${datname}\"`).catch(() => {})\n }\n}\n\n/** A throwaway MySQL database: the same shape as {@link PgTestDb}. */\nexport type MysqlTestDb<S> = PgTestDb<S>\n\n/** Where creation times live for the MySQL sweep (MySQL keeps no comment on a database). */\nconst MYSQL_META = 'kicktest_meta'\nlet mysqlSwept = false\n\ntype MysqlConnection = import('mysql2/promise').Connection\n\n/**\n * A throwaway database on an existing MySQL server — a shared test container\n * (`kickTestServices`), a CI service, a local Docker MySQL — with the same\n * options as {@link createPgTestDb}. MySQL has no template databases, so the\n * migrations run once into one and each file's database copies its tables,\n * rows and foreign keys; a template with views, triggers or routines is\n * migrated per file instead. Needs `mysql2`.\n */\nexport async function createMysqlTestDb<S>(opts: ServerTestDbOptions<S>): Promise<MysqlTestDb<S>> {\n const server = opts.connectionString ?? process.env.KICK_TEST_MYSQL_URL\n if (!server) {\n throw new Error(\n '@forinda/kickjs-db/testing: createMysqlTestDb needs a connectionString (or KICK_TEST_MYSQL_URL, set by kickTestServices)',\n )\n }\n guardTestServer(server, opts.allowNonTestDatabase)\n const mysql = await import('mysql2/promise')\n const name = `kick_test_${randomBytes(6).toString('hex')}`\n const urlOf = (db: string) => {\n const url = new URL(server)\n url.pathname = `/${db}`\n return url.toString()\n }\n\n const admin = await mysql.createConnection({ uri: server, multipleStatements: true })\n try {\n await admin.query(`CREATE DATABASE IF NOT EXISTS \\`${MYSQL_META}\\``)\n await admin.query(\n `CREATE TABLE IF NOT EXISTS \\`${MYSQL_META}\\`.dbs (name varchar(64) PRIMARY KEY, created_at bigint NOT NULL)`,\n )\n if (!mysqlSwept) {\n mysqlSwept = true\n await sweepMysql(admin)\n }\n if (opts.migrationsDir || opts.schema) {\n const key = await templateKey({\n migrationsDir: opts.migrationsDir,\n schema: opts.schema,\n casing: opts.casing,\n dialect: 'mysql',\n })\n const template = `kick_tpl_${key}`\n const wait = opts.lockWaitSeconds ?? 120\n const [locked] = await admin.query('SELECT GET_LOCK(?, ?) AS got', [template, wait])\n // 1: ours. 0: timed out. NULL: an error. Only 1 may go on.\n if (Number((locked as Array<{ got: number | null }>)[0]?.got) !== 1) {\n throw lockTimedOut(template, wait)\n }\n try {\n // Finished once its registry row is written — last, after the\n // migrations. A schema without one is what a killed build left.\n const [done] = await admin.query(`SELECT 1 FROM \\`${MYSQL_META}\\`.dbs WHERE name = ?`, [\n template,\n ])\n if (!(done as unknown[]).length) {\n await admin.query(`DROP DATABASE IF EXISTS \\`${template}\\``)\n await buildMysql(mysql, admin, template, urlOf(template), opts, true)\n }\n if (await mysqlHasProgrammables(admin, template)) {\n // Views, triggers and routines don't copy with CREATE TABLE … LIKE.\n await buildMysql(mysql, admin, name, urlOf(name), opts, false)\n } else {\n await copyMysql(admin, template, name)\n }\n } finally {\n await admin.query('SELECT RELEASE_LOCK(?)', [template])\n }\n } else {\n await admin.query(`CREATE DATABASE \\`${name}\\``)\n }\n await admin.query(`INSERT INTO \\`${MYSQL_META}\\`.dbs VALUES (?, ?)`, [name, Date.now()])\n } finally {\n await admin.end()\n }\n\n const connectionString = urlOf(name)\n const { mysqlDialect } = await import('./mysql')\n const pool = mysql.createPool({ uri: connectionString })\n const db = createDbClient({\n schema: opts.schema ?? {},\n dialect: mysqlDialect({ pool }),\n casing: opts.casing,\n events: true,\n }) as never as KickDbClient<SchemaToTypes<S>>\n return {\n db,\n connectionString,\n async drop() {\n await db.destroy()\n const admin = await mysql.createConnection({ uri: server })\n try {\n await admin.query(`DROP DATABASE IF EXISTS \\`${name}\\``)\n await admin.query(`DELETE FROM \\`${MYSQL_META}\\`.dbs WHERE name = ?`, [name])\n } finally {\n await admin.end()\n }\n },\n }\n}\n\n/** Create `db` and apply the migrations (or the schema); a failed template is dropped. */\nasync function buildMysql<S>(\n mysql: typeof import('mysql2/promise'),\n admin: MysqlConnection,\n db: string,\n url: string,\n opts: ServerTestDbOptions<S>,\n template: boolean,\n): Promise<void> {\n await admin.query(`CREATE DATABASE \\`${db}\\``)\n try {\n const pool = mysql.createPool({ uri: url, multipleStatements: true })\n try {\n if (opts.migrationsDir) {\n const { mysqlAdapter } = await import('./mysql')\n await migrateLatest({\n adapter: mysqlAdapter({ pool }),\n migrationsDir: opts.migrationsDir,\n requireReviewed: false,\n driftCheck: 'ignore',\n })\n } else {\n const { emitMysql } = await import('./emit/mysql')\n const empty: SchemaSnapshot = { version: 1, dialect: 'mysql', tables: {} }\n await pool.query(\n emitMysql(\n diff(\n empty,\n extractSnapshot(opts.schema as Record<string, unknown>, 'mysql', {\n casing: opts.casing,\n }),\n ),\n ),\n )\n }\n } finally {\n await pool.end()\n }\n if (template)\n await admin.query(`INSERT INTO \\`${MYSQL_META}\\`.dbs VALUES (?, ?)`, [db, Date.now()])\n } catch (err) {\n await admin.query(`DROP DATABASE IF EXISTS \\`${db}\\``).catch(() => {})\n throw err\n }\n}\n\nasync function mysqlHasProgrammables(admin: MysqlConnection, db: string): Promise<boolean> {\n const [rows] = await admin.query(\n `SELECT (SELECT COUNT(*) FROM information_schema.VIEWS WHERE TABLE_SCHEMA = ?)\n + (SELECT COUNT(*) FROM information_schema.TRIGGERS WHERE TRIGGER_SCHEMA = ?)\n + (SELECT COUNT(*) FROM information_schema.ROUTINES WHERE ROUTINE_SCHEMA = ?) AS n`,\n [db, db, db],\n )\n return Number((rows as Array<{ n: number }>)[0]!.n) > 0\n}\n\n/** `to` as a copy of `from`: each table's structure and rows, then the foreign keys LIKE leaves out. */\nasync function copyMysql(admin: MysqlConnection, from: string, to: string): Promise<void> {\n await admin.query(`CREATE DATABASE \\`${to}\\``)\n try {\n await copyMysqlInto(admin, from, to)\n } catch (err) {\n // Not registered yet, so no sweep would ever find it: drop it here.\n await admin.query(`DROP DATABASE IF EXISTS \\`${to}\\``).catch(() => {})\n throw err\n }\n}\n\nasync function copyMysqlInto(admin: MysqlConnection, from: string, to: string): Promise<void> {\n const [tables] = await admin.query(\n \"SELECT TABLE_NAME AS t FROM information_schema.TABLES WHERE TABLE_SCHEMA = ? AND TABLE_TYPE = 'BASE TABLE'\",\n [from],\n )\n const names = (tables as Array<{ t: string }>).map((r) => r.t)\n await admin.query('SET FOREIGN_KEY_CHECKS = 0')\n try {\n for (const t of names) {\n await admin.query(`CREATE TABLE \\`${to}\\`.\\`${t}\\` LIKE \\`${from}\\`.\\`${t}\\``)\n // Named columns: a generated one can't be written, and `SELECT *` skips\n // invisible ones (they're listed here).\n const [cols] = await admin.query(\n `SELECT COLUMN_NAME AS c FROM information_schema.COLUMNS\n WHERE TABLE_SCHEMA = ? AND TABLE_NAME = ? AND EXTRA NOT LIKE '%GENERATED%'\n ORDER BY ORDINAL_POSITION`,\n [from, t],\n )\n const list = (cols as Array<{ c: string }>).map((r) => `\\`${r.c}\\``).join(', ')\n if (list) {\n await admin.query(\n `INSERT INTO \\`${to}\\`.\\`${t}\\` (${list}) SELECT ${list} FROM \\`${from}\\`.\\`${t}\\``,\n )\n }\n }\n const [fks] = await admin.query(\n `SELECT k.TABLE_NAME AS t, k.CONSTRAINT_NAME AS c, k.COLUMN_NAME AS col,\n k.REFERENCED_TABLE_NAME AS rt, k.REFERENCED_COLUMN_NAME AS rcol,\n r.DELETE_RULE AS del, r.UPDATE_RULE AS upd\n FROM information_schema.KEY_COLUMN_USAGE k\n JOIN information_schema.REFERENTIAL_CONSTRAINTS r\n ON r.CONSTRAINT_SCHEMA = k.CONSTRAINT_SCHEMA AND r.CONSTRAINT_NAME = k.CONSTRAINT_NAME\n WHERE k.TABLE_SCHEMA = ? AND k.REFERENCED_TABLE_NAME IS NOT NULL\n ORDER BY k.TABLE_NAME, k.CONSTRAINT_NAME, k.ORDINAL_POSITION`,\n [from],\n )\n const byKey = new Map<\n string,\n {\n t: string\n c: string\n cols: string[]\n rt: string\n rcols: string[]\n del: string\n upd: string\n }\n >()\n for (const f of fks as Array<{\n t: string\n c: string\n col: string\n rt: string\n rcol: string\n del: string\n upd: string\n }>) {\n const k = `${f.t}\\0${f.c}`\n const e = byKey.get(k) ?? {\n t: f.t,\n c: f.c,\n cols: [],\n rt: f.rt,\n rcols: [],\n del: f.del,\n upd: f.upd,\n }\n e.cols.push(f.col)\n e.rcols.push(f.rcol)\n byKey.set(k, e)\n }\n const q = (c: string[]) => c.map((x) => `\\`${x}\\``).join(', ')\n for (const f of byKey.values()) {\n await admin.query(\n `ALTER TABLE \\`${to}\\`.\\`${f.t}\\` ADD CONSTRAINT \\`${f.c}\\` FOREIGN KEY (${q(f.cols)})\n REFERENCES \\`${to}\\`.\\`${f.rt}\\` (${q(f.rcols)}) ON DELETE ${f.del} ON UPDATE ${f.upd}`,\n )\n }\n } finally {\n await admin.query('SET FOREIGN_KEY_CHECKS = 1')\n }\n}\n\n/** Drop old test databases and templates, once per process; skip any with a connection. */\nasync function sweepMysql(admin: MysqlConnection): Promise<void> {\n const [rows] = await admin.query(`SELECT name, created_at FROM \\`${MYSQL_META}\\`.dbs`)\n const [busy] = await admin.query(\n 'SELECT DISTINCT DB AS db FROM information_schema.PROCESSLIST WHERE DB IS NOT NULL',\n )\n const inUse = new Set((busy as Array<{ db: string }>).map((r) => r.db))\n const now = Date.now()\n for (const { name, created_at } of rows as Array<{ name: string; created_at: number }>) {\n const kind = name.startsWith('kick_tpl_') ? 'kick_tpl' : 'kick_test'\n if (now - Number(created_at) < SWEEP_AFTER[kind] || inUse.has(name)) continue\n // A template only under its lock: a copy reads it over another\n // connection, which PROCESSLIST doesn't show as using it.\n if (kind === 'kick_tpl') {\n const [got] = await admin.query('SELECT GET_LOCK(?, 0) AS got', [name])\n if (Number((got as Array<{ got: number | null }>)[0]?.got) !== 1) continue\n }\n try {\n if (kind === 'kick_tpl') {\n // Read again under the lock: another file may have rebuilt it since.\n const [again] = await admin.query(\n `SELECT created_at FROM \\`${MYSQL_META}\\`.dbs WHERE name = ?`,\n [name],\n )\n const at = (again as Array<{ created_at: number }>)[0]?.created_at\n if (at === undefined || Date.now() - Number(at) < SWEEP_AFTER.kick_tpl) continue\n }\n await admin.query(`DROP DATABASE IF EXISTS \\`${name}\\``).catch(() => {})\n await admin.query(`DELETE FROM \\`${MYSQL_META}\\`.dbs WHERE name = ?`, [name])\n } finally {\n if (kind === 'kick_tpl') await admin.query('SELECT RELEASE_LOCK(?)', [name])\n }\n }\n}\n\nconst ROLLBACK = Symbol('kickjs-db rolled back')\n\n/**\n * Run `fn` in a transaction that's always rolled back — every test starts\n * from the same data. Code that only holds the client (a service, a\n * repository) joins the transaction through the call chain, so nothing it\n * writes survives. `afterCommit` hooks don't run. A real failure in `fn`\n * still throws.\n *\n * it('creates a user', () => rolledBack(db, async () => { … }))\n */\nexport async function rolledBack<T>(\n // oxlint-disable-next-line no-explicit-any -- any schema's client\n db: Pick<KickDbClient<any>, 'transaction'>,\n fn: () => Promise<T>,\n): Promise<T> {\n let result!: T\n await db\n .transaction(async () => {\n result = await fn()\n throw ROLLBACK\n })\n .catch((err: unknown) => {\n if (err !== ROLLBACK) throw err\n })\n return result\n}\n\n// oxlint-disable-next-line no-explicit-any -- any schema's client\ntype Observable = Pick<KickDbClient<any>, 'on' | 'off'>\n\n/**\n * Run `fn` and return the queries it sent, in order. The client must have\n * events on — `createTestDb` / `createPgTestDb` clients do; your own needs\n * `createDbClient({ events: true })`.\n *\n * const { result, queries } = await captureQueries(db, () => repo.list())\n */\nexport async function captureQueries<T>(\n db: Observable,\n fn: () => Promise<T>,\n): Promise<{ result: T; queries: QueryEvent[] }> {\n if ((db as unknown as Record<symbol, unknown>)[EVENTS_ENABLED] === false) {\n throw new Error(\n 'captureQueries: this client was created without events, so no query is reported ' +\n 'and every count would be 0. Create it with `events: true`.',\n )\n }\n const queries: QueryEvent[] = []\n const listener = (event: QueryEvent) => void queries.push(event)\n db.on('query', listener)\n try {\n return { result: await fn(), queries }\n } finally {\n db.off('query', listener)\n }\n}\n\n/**\n * Assert `fn` sends exactly `count` queries — a guard against N+1 queries\n * that grows with the data. On a mismatch the error lists every query sent.\n *\n * await expectQueries(db, 2, () => postsWithAuthors()) // 1 + 1, not 1 + N\n */\nexport async function expectQueries<T>(\n db: Observable,\n count: number,\n fn: () => Promise<T>,\n): Promise<T> {\n const { result, queries } = await captureQueries(db, fn)\n if (queries.length !== count) {\n const list = queries.map((q, i) => ` ${i + 1}. ${q.sql}`).join('\\n')\n throw new Error(\n `Expected ${count} quer${count === 1 ? 'y' : 'ies'}, ran ${queries.length}:\\n${list || ' (none)'}`,\n )\n }\n return result\n}\n"],"mappings":"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"}
@@ -1,7 +1,7 @@
1
1
 
2
- import { n as ColumnBuilder, s as GeneratedBrand, u as NotNullBrand } from "./types-DB_xyeQT.mjs";
2
+ import { n as ColumnBuilder, s as GeneratedBrand, u as NotNullBrand } from "./types-D4x2u-EZ.mjs";
3
3
  import { CommonTableExpression, Dialect, Expression, ExpressionBuilder, Insertable, Kysely, KyselyPlugin, SelectQueryBuilder, SelectType, Selectable, SqlBool, UpdateObject } from "kysely";
4
- //#region src/client/insert-many.d.ts
4
+ /** Options for `db.insertMany()`: the parameter limit per statement, and atomicity. */
5
5
  interface InsertManyOptions {
6
6
  /**
7
7
  * Bind parameters one statement may use. Default the dialect's limit; set it
@@ -15,8 +15,11 @@ interface InsertManyOptions {
15
15
  */
16
16
  atomic?: boolean;
17
17
  }
18
- //#endregion
19
- //#region src/client/upsert.d.ts
18
+ /**
19
+ * Options for `db.upsert()`.
20
+ *
21
+ * @see https://kickjs.app/guide/database/queries#upsert-and-find-or-create
22
+ */
20
23
  interface UpsertOptions<DB, T extends keyof DB & string> extends InsertManyOptions {
21
24
  /**
22
25
  * The row — or rows — to insert. Many rows are split into statements that
@@ -48,6 +51,11 @@ interface UpsertOptions<DB, T extends keyof DB & string> extends InsertManyOptio
48
51
  type PresentKeys<W> = { [K in keyof W]-?: {} extends Pick<W, K> ? never : K; }[keyof W];
49
52
  /** What `create` adds to `where`: every required column `where` may leave out. */
50
53
  type CreateRest<DB, T extends keyof DB, W> = Omit<Insertable<DB[T]>, PresentKeys<W>> & Partial<Insertable<DB[T]>>;
54
+ /**
55
+ * Options for `db.findOrCreate()`: the unique key to look up, and the rest of the row to create.
56
+ *
57
+ * @see https://kickjs.app/guide/database/queries#upsert-and-find-or-create
58
+ */
51
59
  type FindOrCreateOptions<DB, T extends keyof DB & string, W extends Partial<Selectable<DB[T]>> = Partial<Selectable<DB[T]>>> = {
52
60
  /** Identifies the row — columns of a unique key. Also part of what's created. */
53
61
  where: W & Record<Exclude<keyof W, keyof Selectable<DB[T]>>, never>;
@@ -56,8 +64,6 @@ type FindOrCreateOptions<DB, T extends keyof DB & string, W extends Partial<Sele
56
64
  } : {
57
65
  create: CreateRest<DB, T, W>;
58
66
  });
59
- //#endregion
60
- //#region src/extend/types.d.ts
61
67
  /**
62
68
  * Method bag keyed by table name. Methods receive `this` as the
63
69
  * extended client (the runtime calls them with `Function.prototype.call`
@@ -114,8 +120,6 @@ type ComputedFields<Bag> = Bag extends Record<string, {
114
120
  * method bag from `model`.
115
121
  */
116
122
  type ExtendedClient<DB, E extends ExtensionDefinition<DB>> = KickDbClient<E['result'] extends ResultExtensions<DB> ? DBWithResults<DB, NonNullable<E['result']>> : DB> & { [T in keyof NonNullable<E['model']> & keyof DB & string]: NonNullable<NonNullable<E['model']>[T]>; };
117
- //#endregion
118
- //#region src/tenancy.d.ts
119
123
  /**
120
124
  * How tenants' rows are kept apart:
121
125
  *
@@ -132,6 +136,11 @@ type ExtendedClient<DB, E extends ExtensionDefinition<DB>> = KickDbClient<E['res
132
136
  * central database.
133
137
  */
134
138
  type TenancyStrategy = 'column' | 'rls' | 'schema' | 'database';
139
+ /**
140
+ * Options for `defineTenancy()`.
141
+ *
142
+ * @see https://kickjs.app/guide/database/tenancy
143
+ */
135
144
  interface TenancyOptions {
136
145
  strategy: TenancyStrategy;
137
146
  /**
@@ -195,18 +204,33 @@ interface TenancyOptions {
195
204
  */
196
205
  roleCheck?: 'error' | 'warn' | 'off';
197
206
  }
207
+ /**
208
+ * What `onBypass` receives for each `bypass()`: the reason, the strategy, and where it was called.
209
+ *
210
+ * @see https://kickjs.app/guide/database/tenancy#cross-tenant-work-bypass
211
+ */
198
212
  interface BypassInfo {
199
213
  reason: string;
200
214
  strategy: TenancyStrategy;
201
215
  /** Where `bypass()` was called. */
202
216
  stack: string | undefined;
203
217
  }
218
+ /**
219
+ * Options for `tenancy.bypass()`.
220
+ *
221
+ * @see https://kickjs.app/guide/database/tenancy#cross-tenant-work-bypass
222
+ */
204
223
  interface BypassOptions {
205
224
  /** Why — passed to `onBypass`, for the audit log. */
206
225
  reason: string;
207
226
  /** Allow it inside an HTTP request (refused there by default). */
208
227
  allowInRequest?: boolean;
209
228
  }
229
+ /**
230
+ * A tenancy made by `defineTenancy()`: pass it to `createDbClient({ tenancy })` and to `tenantKey()` columns.
231
+ *
232
+ * @see https://kickjs.app/guide/database/tenancy
233
+ */
210
234
  interface Tenancy extends Readonly<Required<Pick<TenancyOptions, 'strategy' | 'setting' | 'schemaFor' | 'binding' | 'roleCheck'>>> {
211
235
  readonly bypassDialect?: Dialect;
212
236
  readonly dialectFor?: (tenantId: string) => Dialect;
@@ -229,6 +253,17 @@ interface Tenancy extends Readonly<Required<Pick<TenancyOptions, 'strategy' | 's
229
253
  declare class TenantRequiredError extends Error {
230
254
  constructor(table: string);
231
255
  }
256
+ /**
257
+ * One description of how tenants are separated, shared by the schema
258
+ * (`tenantKey(tenancy)`) and the client (`createDbClient({ tenancy })`).
259
+ *
260
+ * ```ts
261
+ * export const tenancy = defineTenancy({
262
+ * strategy: 'rls',
263
+ * current: () => getRequestValue('tenant')?.id,
264
+ * })
265
+ * ```
266
+ */
232
267
  declare function defineTenancy(options: TenancyOptions): Tenancy;
233
268
  /**
234
269
  * The tenant column of a tenanted table — what marks it tenanted. Filled
@@ -247,8 +282,6 @@ declare function defineTenancy(options: TenancyOptions): Tenancy;
247
282
  * setting. Pass another column to change its type: `tenantKey(tenancy, uuid())`.
248
283
  */
249
284
  declare function tenantKey<T = string>(tenancy: Tenancy, column?: ColumnBuilder<T>): ColumnBuilder<T> & NotNullBrand & GeneratedBrand;
250
- //#endregion
251
- //#region src/client/register.d.ts
252
285
  /**
253
286
  * Module-augmentable registry for the typed KickJS-DB surface. Adopters
254
287
  * declare:
@@ -289,8 +322,6 @@ type RegisteredDB = KickDbRegister extends {
289
322
  } ? D extends {
290
323
  qb: import('kysely').Kysely<infer X>;
291
324
  } ? X : unknown : unknown;
292
- //#endregion
293
- //#region src/query/types.d.ts
294
325
  /**
295
326
  * Adopter-augmented at typegen time, mirroring `KickDbRegister`. The
296
327
  * augmentation slots a record keyed by table name; each value is a
@@ -517,8 +548,11 @@ interface TableQueryNamespace<DB, Table extends keyof DB & string> {
517
548
  * without an explicit generic.
518
549
  */
519
550
  type QueryNamespace<DB = RegisteredDB> = { [Table in keyof DB & string]: TableQueryNamespace<DB, Table>; };
520
- //#endregion
521
- //#region src/client/types.d.ts
551
+ /**
552
+ * Payload of the `query` event: a query that ran, with its duration.
553
+ *
554
+ * @see https://kickjs.app/guide/database/events-plugins#lifecycle-events
555
+ */
522
556
  interface QueryEvent {
523
557
  sql: string;
524
558
  parameters: readonly unknown[];
@@ -528,6 +562,11 @@ interface QueryEvent {
528
562
  /** The transaction it ran in, when it ran in one (a savepoint shares its transaction's). */
529
563
  txId?: string;
530
564
  }
565
+ /**
566
+ * Payload of the `queryError` event: a query that failed.
567
+ *
568
+ * @see https://kickjs.app/guide/database/events-plugins#lifecycle-events
569
+ */
531
570
  interface QueryErrorEvent {
532
571
  sql: string;
533
572
  parameters: readonly unknown[];
@@ -537,6 +576,12 @@ interface QueryErrorEvent {
537
576
  /** The transaction it ran in, when it ran in one (a savepoint shares its transaction's). */
538
577
  txId?: string;
539
578
  }
579
+ /**
580
+ * Payload of the `beforeQuery` event, fired before a query runs; listeners may
581
+ * rewrite `sql` and `parameters`.
582
+ *
583
+ * @see https://kickjs.app/guide/database/events-plugins#lifecycle-events
584
+ */
540
585
  interface BeforeQueryEvent {
541
586
  /** Mutable — listeners may rewrite sql / parameters before execution. */
542
587
  sql: string;
@@ -544,9 +589,11 @@ interface BeforeQueryEvent {
544
589
  /** Kysely's id for this query, as `query` / `queryError` report it. Absent for statements kick/db sends itself. */
545
590
  readonly queryId?: string;
546
591
  }
592
+ /** Payload of the `transactionStart` and `transactionCommit` events. */
547
593
  interface TransactionEvent {
548
594
  isolation?: 'serializable' | 'repeatable read' | 'read committed' | 'read uncommitted';
549
595
  }
596
+ /** Payload of the `transactionRollback` event: the error that rolled it back. */
550
597
  interface TransactionRollbackEvent extends TransactionEvent {
551
598
  error: unknown;
552
599
  }
@@ -558,13 +605,13 @@ interface TransactionRetryEvent extends TransactionEvent {
558
605
  error: unknown;
559
606
  delayMs: number;
560
607
  }
561
- /** Options for `transaction(opts, fn)`. */
562
608
  /** A transaction from `startTransaction()`: a client, and the way to finish it. */
563
609
  type ManualTransaction<DB> = KickDbClient<DB> & {
564
610
  /** Commit, then run its `afterCommit` hooks. */
565
611
  commit(): Promise<void>;
566
612
  rollback(): Promise<void>;
567
613
  };
614
+ /** Options for `transaction(opts, fn)`. */
568
615
  interface TransactionOptions extends TransactionEvent {
569
616
  /**
570
617
  * What to do when a transaction is already open on this call chain:
@@ -634,7 +681,18 @@ interface ReadRoute {
634
681
  /** How many replicas there are: valid indexes are `0` to `replicas - 1`. */
635
682
  replicas: number;
636
683
  }
684
+ /**
685
+ * Picks where a read outside a transaction goes: `'primary'`, a replica's
686
+ * index, or `undefined` for the default (replicas in turn).
687
+ *
688
+ * @see https://kickjs.app/guide/database/pooling#read-replicas
689
+ */
637
690
  type ReadRouter = (read: ReadRoute) => 'primary' | number | undefined;
691
+ /**
692
+ * The client's lifecycle events by name, with their payloads: what `db.on(name, fn)` takes.
693
+ *
694
+ * @see https://kickjs.app/guide/database/events-plugins#lifecycle-events
695
+ */
638
696
  interface KickDbClientEvents {
639
697
  beforeQuery: BeforeQueryEvent;
640
698
  query: QueryEvent;
@@ -826,6 +884,11 @@ interface KickDbClient<DB = RegisteredDB> {
826
884
  $extends<E extends ExtensionDefinition<DB>>(ext: E): ExtendedClient<DB, E>;
827
885
  destroy(): Promise<void>;
828
886
  }
887
+ /**
888
+ * Options for `createDbClient()`.
889
+ *
890
+ * @see https://kickjs.app/guide/database/
891
+ */
829
892
  interface CreateDbClientOptions<TSchema, _DB = unknown> {
830
893
  /** Schema record — only used for type inference (M2-S1 tightens). */
831
894
  schema: TSchema;
@@ -953,6 +1016,5 @@ interface CreateDbClientOptions<TSchema, _DB = unknown> {
953
1016
  */
954
1017
  casing?: 'snake_case';
955
1018
  }
956
- //#endregion
957
1019
  export { TenancyStrategy as A, WithClause as C, BypassOptions as D, BypassInfo as E, ExtensionDefinition as F, ModelExtensions as I, FindOrCreateOptions as L, defineTenancy as M, tenantKey as N, Tenancy as O, ExtendedClient as P, UpsertOptions as R, TableRelations as S, RegisteredDB as T, KickDbRelationsRegister as _, ManualTransaction as a, RelationMapEntry as b, ReadRoute as c, TransactionEvent as d, TransactionOptions as f, FindManyRow as g, FindManyOptions as h, KickDbClientEvents as i, TenantRequiredError as j, TenancyOptions as k, ReadRouter as l, TransactionRollbackEvent as m, CreateDbClientOptions as n, QueryErrorEvent as o, TransactionRetryEvent as p, KickDbClient as r, QueryEvent as s, BeforeQueryEvent as t, SlowQueryEvent as u, QueryNamespace as v, KickDbRegister as w, TableQueryNamespace as x, RegisteredRelations as y, InsertManyOptions as z };
958
- //# sourceMappingURL=types-8xZUYm43.d.mts.map
1020
+ //# sourceMappingURL=types-Bmbj69hY.d.mts.map