@forinda/kickjs-db 5.1.0 → 5.2.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.
- package/dist/devtools-events.d.mts +22 -0
- package/dist/devtools-events.d.mts.map +1 -0
- package/dist/devtools-events.mjs +11 -0
- package/dist/index.d.mts +49 -191
- package/dist/index.d.mts.map +1 -1
- package/dist/index.mjs +369 -75
- package/dist/index.mjs.map +1 -1
- package/dist/pg.d.mts +1 -1
- package/dist/pg.mjs +2 -2
- package/dist/{types-BcfY4esK.mjs → types-DBmUL5LM.mjs} +2 -2
- package/dist/{types-BcfY4esK.mjs.map → types-DBmUL5LM.mjs.map} +1 -1
- package/dist/{types-D2FzsPow.d.mts → types-Dc9RQGSf.d.mts} +1 -1
- package/dist/{types-D2FzsPow.d.mts.map → types-Dc9RQGSf.d.mts.map} +1 -1
- package/dist/types-snBo_IiR.d.mts +255 -0
- package/dist/types-snBo_IiR.d.mts.map +1 -0
- package/package.json +14 -3
package/dist/pg.d.mts
CHANGED
package/dist/pg.mjs
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
/**
|
|
2
|
-
* @forinda/kickjs-db v5.
|
|
2
|
+
* @forinda/kickjs-db v5.2.0
|
|
3
3
|
*
|
|
4
4
|
* Copyright (c) Felix Orinda
|
|
5
5
|
*
|
|
@@ -8,7 +8,7 @@
|
|
|
8
8
|
*
|
|
9
9
|
* @license MIT
|
|
10
10
|
*/
|
|
11
|
-
import { t as ColumnBuilder } from "./types-
|
|
11
|
+
import { t as ColumnBuilder } from "./types-DBmUL5LM.mjs";
|
|
12
12
|
//#region src/dsl/columns/pg.ts
|
|
13
13
|
var PgEnumColumnBuilder = class extends ColumnBuilder {
|
|
14
14
|
/** The enum's SQL identifier — preserved for emit + drift detection. */
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
/**
|
|
2
|
-
* @forinda/kickjs-db v5.
|
|
2
|
+
* @forinda/kickjs-db v5.2.0
|
|
3
3
|
*
|
|
4
4
|
* Copyright (c) Felix Orinda
|
|
5
5
|
*
|
|
@@ -103,4 +103,4 @@ var ColumnBuilder = class {
|
|
|
103
103
|
//#endregion
|
|
104
104
|
export { KICK_GENERATED as n, KICK_NOT_NULL as r, ColumnBuilder as t };
|
|
105
105
|
|
|
106
|
-
//# sourceMappingURL=types-
|
|
106
|
+
//# sourceMappingURL=types-DBmUL5LM.mjs.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"types-
|
|
1
|
+
{"version":3,"file":"types-DBmUL5LM.mjs","names":[],"sources":["../src/dsl/columns/types.ts"],"sourcesContent":["import type { ColumnSnapshot, FkAction } from '../../snapshot/types'\n\n/**\n * Runtime + type representation of a column reference (e.g. `users.id`).\n * Carries the parent table name, the column's own name, plus runtime\n * accessors used by FK thunks and constraint builders.\n *\n * Exported so adopters can annotate self-referencing thunks without\n * spelling the shape inline:\n *\n * parentId: uuid().references((): ColumnRef => categories.id)\n *\n * Without the annotation the initializer of a self-referencing const\n * trips TS7022 — TS needs to infer the const while the initializer\n * already references it.\n */\nexport interface ColumnRef {\n __tableName: string\n __name: string\n __builder: ColumnBuilder\n __state: () => ReturnType<ColumnBuilder['__state']>\n}\n\n/**\n * Resolved FK spec — `table` / `column` are pulled by invoking `thunk()`\n * lazily. The thunk pattern lets self-referencing tables work:\n *\n * const categories = table('categories', {\n * id: uuid().primaryKey().defaultRandom(),\n * parentId: uuid().references((): ColumnRef => categories.id),\n * })\n *\n * If we resolved at `.references()` call time, `categories` would TDZ-fail\n * inside its own initializer. Storing the thunk and resolving on read\n * (extract / render / emit) defers until after the const binding lands.\n */\nexport interface FkSpec {\n thunk: () => ColumnRef\n onDelete: FkAction\n onUpdate: FkAction\n}\n\nexport interface ColumnState {\n type: string\n nullable: boolean\n default: string | null\n primaryKey: boolean\n unique: boolean\n references: FkSpec | null\n}\n\n/**\n * Type-only brand attached to a column when it's auto-assigned by the\n * database (serial / bigserial / smallserial), has a runtime default\n * (`.default(...)`), or carries an expression default\n * (`uuid().defaultRandom()`, `timestamp().defaultNow()`). `SchemaToTypes<S>`\n * reads this marker and wraps the column type in Kysely's `Generated<T>` so\n * adopters can omit the column on insert.\n *\n * Runtime is a no-op — the symbol never reaches a value.\n */\nexport const KICK_GENERATED = Symbol.for('@forinda/kickjs-db/Generated')\nexport type GeneratedBrand = { readonly [KICK_GENERATED]?: true }\n\n/**\n * Type-only brand attached to a column when `.notNull()` or `.primaryKey()`\n * is called. `SchemaToTypes<S>` reads this brand to decide whether the\n * column type is `T` (NOT NULL) or `T | null` (default nullable).\n *\n * Why a brand instead of a class generic: chained methods (notNull,\n * primaryKey) can return `this & NotNullBrand` to narrow nullability while\n * preserving the subclass identity — so `uuid().primaryKey().defaultRandom()`\n * still resolves `defaultRandom()` on `UuidBuilder`. A class generic\n * `<TNullable>` would collapse the subclass back to the parent.\n */\nexport const KICK_NOT_NULL = Symbol.for('@forinda/kickjs-db/NotNull')\nexport type NotNullBrand = { readonly [KICK_NOT_NULL]?: true }\n\n/**\n * Phantom-typed column builder. The `T` generic carries the column's TS\n * value type (number / string / Date / etc.); nullability is tracked via\n * the `NotNullBrand` intersection rather than a class generic so chain\n * methods preserve subclass identity.\n *\n * Both `T` and the brand are erased at runtime; they exist purely so\n * `SchemaToTypes<S>` can pull them out per column.\n */\nexport class ColumnBuilder<T = unknown> {\n // Phantom param shows up in the public surface so the type system sees\n // it. Reading it at runtime is intentionally not supported.\n declare readonly __t?: T\n\n protected state: ColumnState\n\n constructor(type: string, defaults: Partial<ColumnState> = {}) {\n this.state = {\n type,\n nullable: defaults.nullable ?? true,\n default: defaults.default ?? null,\n primaryKey: defaults.primaryKey ?? false,\n unique: defaults.unique ?? false,\n references: defaults.references ?? null,\n }\n }\n\n notNull(): this & NotNullBrand {\n this.state.nullable = false\n return this as this & NotNullBrand\n }\n\n primaryKey(): this & NotNullBrand {\n this.state.primaryKey = true\n this.state.nullable = false\n return this as this & NotNullBrand\n }\n\n unique(): this {\n this.state.unique = true\n return this\n }\n\n array(): ColumnBuilder<T[]> {\n this.state.type = `${this.state.type}[]`\n return this as unknown as ColumnBuilder<T[]>\n }\n\n references(\n target: () => ColumnRef,\n opts: { onDelete?: FkAction; onUpdate?: FkAction } = {},\n ): this {\n // Store the thunk — do NOT invoke it here. Self-referencing tables\n // pass `() => self.id` whose binding does not exist yet.\n this.state.references = {\n thunk: target,\n onDelete: opts.onDelete ?? 'no_action',\n onUpdate: opts.onUpdate ?? 'no_action',\n }\n return this\n }\n\n /**\n * Mark the column as having a runtime / DB-assigned default. The\n * `GeneratedBrand` flows into `SchemaToTypes<S>` so the column wraps\n * in `Generated<T>` — adopters can `INSERT` without specifying it.\n */\n default(value: string): this & GeneratedBrand {\n this.state.default = value\n return this as this & GeneratedBrand\n }\n\n toJSON(name: string): ColumnSnapshot {\n return {\n name,\n type: this.state.type,\n nullable: this.state.nullable,\n default: this.state.default,\n primaryKey: this.state.primaryKey,\n }\n }\n\n // Internal accessor for table()/diff to read full state including unique/references.\n __state(): Readonly<ColumnState> {\n return this.state\n }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;AA6DA,MAAa,iBAAiB,OAAO,IAAI,+BAA+B;;;;;;;;;;;;AAcxE,MAAa,gBAAgB,OAAO,IAAI,6BAA6B;;;;;;;;;;AAYrE,IAAa,gBAAb,MAAwC;CAKtC;CAEA,YAAY,MAAc,WAAiC,EAAE,EAAE;AAC7D,OAAK,QAAQ;GACX;GACA,UAAU,SAAS,YAAY;GAC/B,SAAS,SAAS,WAAW;GAC7B,YAAY,SAAS,cAAc;GACnC,QAAQ,SAAS,UAAU;GAC3B,YAAY,SAAS,cAAc;GACpC;;CAGH,UAA+B;AAC7B,OAAK,MAAM,WAAW;AACtB,SAAO;;CAGT,aAAkC;AAChC,OAAK,MAAM,aAAa;AACxB,OAAK,MAAM,WAAW;AACtB,SAAO;;CAGT,SAAe;AACb,OAAK,MAAM,SAAS;AACpB,SAAO;;CAGT,QAA4B;AAC1B,OAAK,MAAM,OAAO,GAAG,KAAK,MAAM,KAAK;AACrC,SAAO;;CAGT,WACE,QACA,OAAqD,EAAE,EACjD;AAGN,OAAK,MAAM,aAAa;GACtB,OAAO;GACP,UAAU,KAAK,YAAY;GAC3B,UAAU,KAAK,YAAY;GAC5B;AACD,SAAO;;;;;;;CAQT,QAAQ,OAAsC;AAC5C,OAAK,MAAM,UAAU;AACrB,SAAO;;CAGT,OAAO,MAA8B;AACnC,SAAO;GACL;GACA,MAAM,KAAK,MAAM;GACjB,UAAU,KAAK,MAAM;GACrB,SAAS,KAAK,MAAM;GACpB,YAAY,KAAK,MAAM;GACxB;;CAIH,UAAiC;AAC/B,SAAO,KAAK"}
|
|
@@ -159,4 +159,4 @@ declare class ColumnBuilder<T = unknown> {
|
|
|
159
159
|
}
|
|
160
160
|
//#endregion
|
|
161
161
|
export { TableSnapshot as _, GeneratedBrand as a, NotNullBrand as c, Dialect as d, EnumSnapshot as f, SchemaSnapshot as g, IndexSnapshot as h, FkSpec as i, CheckSnapshot as l, ForeignKeySnapshot as m, ColumnRef as n, KICK_GENERATED as o, FkAction as p, ColumnState as r, KICK_NOT_NULL as s, ColumnBuilder as t, ColumnSnapshot as u };
|
|
162
|
-
//# sourceMappingURL=types-
|
|
162
|
+
//# sourceMappingURL=types-Dc9RQGSf.d.mts.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"types-
|
|
1
|
+
{"version":3,"file":"types-Dc9RQGSf.d.mts","names":[],"sources":["../src/snapshot/types.ts","../src/dsl/columns/types.ts"],"mappings":";;KAAY,OAAA;AAAA,KAEA,QAAA;AAAA,UAEK,cAAA;EACf,IAAA;EACA,IAAA;EACA,QAAA;EACA,OAAA;EACA,UAAA;AAAA;AAAA,UAGe,aAAA;EACf,IAAA;EACA,OAAA;EACA,MAAA;AAAA;AAAA,UAGe,kBAAA;EACf,IAAA;EACA,OAAA;EACA,QAAA;EACA,UAAA;EACA,QAAA,EAAU,QAAA;EACV,QAAA,EAAU,QAAA;AAAA;AAAA,UAGK,aAAA;EACf,IAAA;EACA,UAAA;AAAA;AAAA,UAGe,aAAA;EACf,IAAA;EACA,OAAA,EAAS,MAAA,SAAe,cAAA;EACxB,OAAA,EAAS,aAAA;EACT,WAAA,EAAa,kBAAA;EACb,MAAA,EAAQ,aAAA;AAAA;;;;;;UAQO,YAAA;EACf,IAAA;EAvBU;EAyBV,MAAA;AAAA;AAAA,UAGe,cAAA;EACf,OAAA;EACA,OAAA,EAAS,OAAA;EACT,MAAA,EAAQ,MAAA,SAAe,aAAA;;EAEvB,KAAA,GAAQ,MAAA,SAAe,YAAA;AAAA;;;AAxDzB;;;;;AAEA;;;;;AAEA;;;;AAJA,UCgBiB,SAAA;EACf,WAAA;EACA,MAAA;EACA,SAAA,EAAW,aAAA;EACX,OAAA,QAAe,UAAA,CAAW,aAAA;AAAA;;ADR5B;;;;;;;;;AAMA;;;UCkBiB,MAAA;EACf,KAAA,QAAa,SAAA;EACb,QAAA,EAAU,QAAA;EACV,QAAA,EAAU,QAAA;AAAA;AAAA,UAGK,WAAA;EACf,IAAA;EACA,QAAA;EACA,OAAA;EACA,UAAA;EACA,MAAA;EACA,UAAA,EAAY,MAAA;AAAA;;;;ADhBd;;;;;;;cC6Ba,cAAA;AAAA,KACD,cAAA;EAAA,UAA6B,cAAA;AAAA;;;;;;;;;;;;cAa5B,aAAA;AAAA,KACD,YAAA;EAAA,UAA2B,aAAA;AAAA;;ADzBvC;;;;;;;;cCoCa,aAAA;EAAA,SAGM,GAAA,GAAM,CAAA;EAAA,UAEb,KAAA,EAAO,WAAA;cAEL,IAAA,UAAc,QAAA,GAAU,OAAA,CAAQ,WAAA;EAW5C,OAAA,CAAA,UAAkB,YAAA;EAKlB,UAAA,CAAA,UAAqB,YAAA;EAMrB,MAAA,CAAA;EAKA,KAAA,CAAA,GAAS,aAAA,CAAc,CAAA;EAKvB,UAAA,CACE,MAAA,QAAc,SAAA,EACd,IAAA;IAAQ,QAAA,GAAW,QAAA;IAAU,QAAA,GAAW,QAAA;EAAA;EDxEP;;;;ACxCrC;EAiIE,OAAA,CAAQ,KAAA,kBAAuB,cAAA;EAK/B,MAAA,CAAO,IAAA,WAAe,cAAA;EAWtB,OAAA,CAAA,GAAW,QAAA,CAAS,WAAA;AAAA"}
|
|
@@ -0,0 +1,255 @@
|
|
|
1
|
+
|
|
2
|
+
import * as _$kysely from "kysely";
|
|
3
|
+
import { Dialect, Kysely } from "kysely";
|
|
4
|
+
import * as _$_forinda_kickjs_devtools_kit_bus0 from "@forinda/kickjs-devtools-kit/bus";
|
|
5
|
+
|
|
6
|
+
//#region src/extend/types.d.ts
|
|
7
|
+
/**
|
|
8
|
+
* Method bag keyed by table name. Methods receive `this` as the
|
|
9
|
+
* extended client (the runtime calls them with `Function.prototype.call`
|
|
10
|
+
* so the binding is correct). Adopter-side TS annotation:
|
|
11
|
+
* `this: typeof dbX` — fine for v1; full self-typed inference is a
|
|
12
|
+
* separate refactor.
|
|
13
|
+
*/
|
|
14
|
+
type ModelExtensions<DB> = { [Table in keyof DB & string]?: Record<string, (...args: never[]) => unknown> };
|
|
15
|
+
/**
|
|
16
|
+
* One result extension — declares which columns the compute reads
|
|
17
|
+
* (`needs`) and the function that produces the derived value
|
|
18
|
+
* (`compute`). Sync only in v1; async opens up "runtime queries
|
|
19
|
+
* inside compute" footguns.
|
|
20
|
+
*/
|
|
21
|
+
interface ResultExtension<Row> {
|
|
22
|
+
/** Map from column name → `true`. Auto-injected into SELECT list. */
|
|
23
|
+
needs: Partial<Record<keyof Row, true>>;
|
|
24
|
+
/** Receives the row's selected columns; return value lands on the row. */
|
|
25
|
+
compute: (row: Row) => unknown;
|
|
26
|
+
}
|
|
27
|
+
/**
|
|
28
|
+
* Result extensions keyed by table name. Each entry is a record of
|
|
29
|
+
* computed-field name → ResultExtension.
|
|
30
|
+
*/
|
|
31
|
+
type ResultExtensions<DB> = { [Table in keyof DB & string]?: Record<string, ResultExtension<DB[Table]>> };
|
|
32
|
+
/** Top-level shape passed to `db.$extends(...)`. */
|
|
33
|
+
interface ExtensionDefinition<DB> {
|
|
34
|
+
model?: ModelExtensions<DB>;
|
|
35
|
+
result?: ResultExtensions<DB>;
|
|
36
|
+
}
|
|
37
|
+
/**
|
|
38
|
+
* Fold result extensions into the DB row shape. For each table that
|
|
39
|
+
* has computeds, every row gains the computed properties typed by the
|
|
40
|
+
* compute function's return type.
|
|
41
|
+
*
|
|
42
|
+
* Implementation note: `compute(row: Row)` is contravariant in `Row`,
|
|
43
|
+
* so the obvious-looking `R[T] extends Record<string, ResultExtension<unknown>>`
|
|
44
|
+
* check fails — `ResultExtension<Row>` doesn't extend
|
|
45
|
+
* `ResultExtension<unknown>` under strictFunctionTypes. We use
|
|
46
|
+
* `(row: never)` as the variance-neutral position: every adopter
|
|
47
|
+
* compute extends `(row: never) => unknown`, so the check passes
|
|
48
|
+
* uniformly.
|
|
49
|
+
*/
|
|
50
|
+
type DBWithResults<DB, R> = { [T in keyof DB]: T extends keyof R ? DB[T] & ComputedFields<R[T]> : DB[T] };
|
|
51
|
+
/** Map a computed-bag to a record of computed-field name → return type. */
|
|
52
|
+
type ComputedFields<Bag> = Bag extends Record<string, {
|
|
53
|
+
compute: (row: never) => unknown;
|
|
54
|
+
}> ? { [K in keyof Bag]: Bag[K] extends {
|
|
55
|
+
compute: (row: never) => infer Out;
|
|
56
|
+
} ? Out : unknown } : {};
|
|
57
|
+
/**
|
|
58
|
+
* Result type of `db.$extends(...)` — the client typed against the
|
|
59
|
+
* (possibly result-augmented) DB, intersected with the per-table
|
|
60
|
+
* method bag from `model`.
|
|
61
|
+
*/
|
|
62
|
+
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]> };
|
|
63
|
+
//#endregion
|
|
64
|
+
//#region src/client/register.d.ts
|
|
65
|
+
/**
|
|
66
|
+
* Module-augmentable registry for the typed KickJS-DB surface. Adopters
|
|
67
|
+
* declare:
|
|
68
|
+
*
|
|
69
|
+
* declare module '@forinda/kickjs-db' {
|
|
70
|
+
* interface KickDbRegister {
|
|
71
|
+
* db: typeof appDbClient
|
|
72
|
+
* }
|
|
73
|
+
* }
|
|
74
|
+
*
|
|
75
|
+
* Once the augmentation is in scope, `KickDbClient` (with no explicit
|
|
76
|
+
* generic) widens to the registered DB shape everywhere —
|
|
77
|
+
* `@Inject(DB_PRIMARY) private db!: KickDbClient` produces the typed
|
|
78
|
+
* client with no manual cast at the call site.
|
|
79
|
+
*
|
|
80
|
+
* `kick db typegen` (M2.B-T9) emits this declaration into
|
|
81
|
+
* `.kickjs/types/kick__db.d.ts` for adopters who opt into codegen. Adopters
|
|
82
|
+
* who prefer to declare it by hand do so once in any module that's reached
|
|
83
|
+
* by their tsconfig.
|
|
84
|
+
*
|
|
85
|
+
* Named `KickDbRegister` rather than a generic `Register` to avoid
|
|
86
|
+
* collisions with other libraries that augment a same-named interface.
|
|
87
|
+
*/
|
|
88
|
+
interface KickDbRegister {}
|
|
89
|
+
/**
|
|
90
|
+
* Pull the registered DB shape out of the augmentable KickDbRegister.
|
|
91
|
+
* `unknown` when the adopter hasn't declared an augmentation — keeps the
|
|
92
|
+
* M1-permissive fallback intact.
|
|
93
|
+
*/
|
|
94
|
+
type RegisteredDB = KickDbRegister extends {
|
|
95
|
+
db: {
|
|
96
|
+
qb: {
|
|
97
|
+
__DB__?: never;
|
|
98
|
+
};
|
|
99
|
+
};
|
|
100
|
+
} ? unknown : KickDbRegister extends {
|
|
101
|
+
db: infer D;
|
|
102
|
+
} ? D extends {
|
|
103
|
+
qb: _$kysely.Kysely<infer X>;
|
|
104
|
+
} ? X : unknown : unknown;
|
|
105
|
+
//#endregion
|
|
106
|
+
//#region src/client/types.d.ts
|
|
107
|
+
interface QueryEvent {
|
|
108
|
+
sql: string;
|
|
109
|
+
parameters: readonly unknown[];
|
|
110
|
+
durationMs: number;
|
|
111
|
+
}
|
|
112
|
+
interface QueryErrorEvent {
|
|
113
|
+
sql: string;
|
|
114
|
+
parameters: readonly unknown[];
|
|
115
|
+
error: unknown;
|
|
116
|
+
}
|
|
117
|
+
interface BeforeQueryEvent {
|
|
118
|
+
/** Mutable — listeners may rewrite sql / parameters before execution. */
|
|
119
|
+
sql: string;
|
|
120
|
+
parameters: unknown[];
|
|
121
|
+
}
|
|
122
|
+
interface TransactionEvent {
|
|
123
|
+
isolation?: 'serializable' | 'repeatable read' | 'read committed' | 'read uncommitted';
|
|
124
|
+
}
|
|
125
|
+
interface TransactionRollbackEvent extends TransactionEvent {
|
|
126
|
+
error: unknown;
|
|
127
|
+
}
|
|
128
|
+
/**
|
|
129
|
+
* Fired when a query exceeds `createDbClient({ slowQueryThresholdMs })`.
|
|
130
|
+
* The `query` event ALSO fires for the same query — `slowQuery` is a
|
|
131
|
+
* separate channel so listeners can subscribe to slow ones only
|
|
132
|
+
* without filtering every query themselves.
|
|
133
|
+
*/
|
|
134
|
+
interface SlowQueryEvent extends QueryEvent {
|
|
135
|
+
/** The configured threshold the query exceeded. */
|
|
136
|
+
thresholdMs: number;
|
|
137
|
+
}
|
|
138
|
+
interface KickDbClientEvents {
|
|
139
|
+
beforeQuery: BeforeQueryEvent;
|
|
140
|
+
query: QueryEvent;
|
|
141
|
+
queryError: QueryErrorEvent;
|
|
142
|
+
slowQuery: SlowQueryEvent;
|
|
143
|
+
transactionStart: TransactionEvent;
|
|
144
|
+
transactionCommit: TransactionEvent;
|
|
145
|
+
transactionRollback: TransactionRollbackEvent;
|
|
146
|
+
}
|
|
147
|
+
/**
|
|
148
|
+
* KickDbClient wraps a Kysely instance with three additions:
|
|
149
|
+
*
|
|
150
|
+
* 1. Lifecycle events (`on('query', ...)` etc) for observability + RLS
|
|
151
|
+
* rewriting via `beforeQuery`.
|
|
152
|
+
* 2. transaction(fn) / transaction(opts, fn) — passes a fully-scoped child
|
|
153
|
+
* client whose mutations are isolated.
|
|
154
|
+
* 3. tx.savepoint(fn) — nested rollback boundary inside an outer transaction.
|
|
155
|
+
*
|
|
156
|
+
* The underlying query builder is exposed as `db.qb` for advanced cases
|
|
157
|
+
* that need APIs not surfaced through the wrapper. Adopters typically
|
|
158
|
+
* never reach for `qb` — `selectFrom` / `insertInto` / etc. cover the
|
|
159
|
+
* common query surface.
|
|
160
|
+
*
|
|
161
|
+
* NB: Rather than re-typing every query method on this surface, we
|
|
162
|
+
* directly expose `selectFrom`/`insertInto`/`updateTable`/`deleteFrom`
|
|
163
|
+
* as bound functions of the underlying builder — keeps us in sync with
|
|
164
|
+
* upstream type evolution without manual mirroring.
|
|
165
|
+
*/
|
|
166
|
+
interface KickDbClient<DB = RegisteredDB> {
|
|
167
|
+
/** Underlying query builder — escape hatch for advanced cases. */
|
|
168
|
+
readonly qb: Kysely<DB>;
|
|
169
|
+
readonly dialect: 'postgres' | 'sqlite' | 'mysql';
|
|
170
|
+
selectFrom: Kysely<DB>['selectFrom'];
|
|
171
|
+
insertInto: Kysely<DB>['insertInto'];
|
|
172
|
+
updateTable: Kysely<DB>['updateTable'];
|
|
173
|
+
deleteFrom: Kysely<DB>['deleteFrom'];
|
|
174
|
+
on<E extends keyof KickDbClientEvents>(event: E, listener: (e: KickDbClientEvents[E]) => void | Promise<void>): this;
|
|
175
|
+
off<E extends keyof KickDbClientEvents>(event: E, listener: (e: KickDbClientEvents[E]) => void | Promise<void>): this;
|
|
176
|
+
transaction<T>(fn: (tx: KickDbClient<DB>) => Promise<T>): Promise<T>;
|
|
177
|
+
transaction<T>(opts: TransactionEvent, fn: (tx: KickDbClient<DB>) => Promise<T>): Promise<T>;
|
|
178
|
+
savepoint<T>(fn: (sp: KickDbClient<DB>) => Promise<T>): Promise<T>;
|
|
179
|
+
/**
|
|
180
|
+
* Returns a wrapped client carrying adopter-defined per-table
|
|
181
|
+
* methods. Inside each method, `this` is the extended client so
|
|
182
|
+
* call-chains stay clean:
|
|
183
|
+
*
|
|
184
|
+
* const dbX = db.$extends({
|
|
185
|
+
* model: {
|
|
186
|
+
* users: {
|
|
187
|
+
* findByEmail(this: typeof dbX, email: string) {
|
|
188
|
+
* return this.selectFrom('users')
|
|
189
|
+
* .where('email', '=', email)
|
|
190
|
+
* .executeTakeFirst()
|
|
191
|
+
* },
|
|
192
|
+
* },
|
|
193
|
+
* },
|
|
194
|
+
* })
|
|
195
|
+
*
|
|
196
|
+
* await dbX.users.findByEmail('a@b.com')
|
|
197
|
+
*
|
|
198
|
+
* Result extensions (`compute()` over selected rows) and the
|
|
199
|
+
* insert-side toDriver pass land as follow-ups; v1 ships model
|
|
200
|
+
* methods only.
|
|
201
|
+
*/
|
|
202
|
+
$extends<E extends ExtensionDefinition<DB>>(ext: E): ExtendedClient<DB, E>;
|
|
203
|
+
destroy(): Promise<void>;
|
|
204
|
+
}
|
|
205
|
+
interface CreateDbClientOptions<TSchema, _DB = unknown> {
|
|
206
|
+
/** Schema record — only used for type inference (M2-S1 tightens). */
|
|
207
|
+
schema: TSchema;
|
|
208
|
+
/** A Kysely Dialect — typically PostgresDialect from db-pg. */
|
|
209
|
+
dialect: Dialect;
|
|
210
|
+
/**
|
|
211
|
+
* Enable lifecycle event emission for `query` / `queryError` /
|
|
212
|
+
* `slowQuery` / `transactionStart` / `transactionCommit` /
|
|
213
|
+
* `transactionRollback`. Default `false` — zero overhead path; the
|
|
214
|
+
* Kysely log callback isn't even installed.
|
|
215
|
+
*/
|
|
216
|
+
events?: boolean;
|
|
217
|
+
/**
|
|
218
|
+
* Fire the `slowQuery` event for any query whose duration exceeds
|
|
219
|
+
* this threshold (milliseconds). Default `null` — no slow-query
|
|
220
|
+
* detection. Setting a value implies `events: true` so the listener
|
|
221
|
+
* surface is attached.
|
|
222
|
+
*/
|
|
223
|
+
slowQueryThresholdMs?: number | null;
|
|
224
|
+
/**
|
|
225
|
+
* Optional KickEventBus instance the client republishes lifecycle
|
|
226
|
+
* events to. When set, the bus receives:
|
|
227
|
+
*
|
|
228
|
+
* - `db:slow-query` — fired alongside the local `slowQuery` event;
|
|
229
|
+
* payload `{ sql, parameters, durationMs, thresholdMs }`.
|
|
230
|
+
* - `db:query-error` — fired alongside the local `queryError`
|
|
231
|
+
* event; payload `{ sql, parameters, error }`.
|
|
232
|
+
*
|
|
233
|
+
* Setting a bus implies `events: true` (the publisher hangs off the
|
|
234
|
+
* existing emitter). Wire it from `DEVTOOLS_BUS` if you want the
|
|
235
|
+
* DevTools panel to pick the events up:
|
|
236
|
+
*
|
|
237
|
+
* import { DEVTOOLS_BUS } from '@forinda/kickjs-devtools-kit/bus'
|
|
238
|
+
* // Resolve only when devtools is actually wired — adopters who
|
|
239
|
+
* // skip @forinda/kickjs-devtools never register the token, and
|
|
240
|
+
* // resolve() throws on missing tokens.
|
|
241
|
+
* const db = createDbClient({
|
|
242
|
+
* ...,
|
|
243
|
+
* bus: container.has(DEVTOOLS_BUS) ? container.resolve(DEVTOOLS_BUS) : undefined,
|
|
244
|
+
* slowQueryThresholdMs: 100,
|
|
245
|
+
* })
|
|
246
|
+
*
|
|
247
|
+
* Type imported via `import type` so kickjs-db keeps devtools-kit
|
|
248
|
+
* as an optional peer; adopters who skip devtools never load the
|
|
249
|
+
* bus module.
|
|
250
|
+
*/
|
|
251
|
+
bus?: _$_forinda_kickjs_devtools_kit_bus0.KickEventBus;
|
|
252
|
+
}
|
|
253
|
+
//#endregion
|
|
254
|
+
export { QueryErrorEvent as a, TransactionEvent as c, RegisteredDB as d, ExtendedClient as f, KickDbClientEvents as i, TransactionRollbackEvent as l, ModelExtensions as m, CreateDbClientOptions as n, QueryEvent as o, ExtensionDefinition as p, KickDbClient as r, SlowQueryEvent as s, BeforeQueryEvent as t, KickDbRegister as u };
|
|
255
|
+
//# sourceMappingURL=types-snBo_IiR.d.mts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"types-snBo_IiR.d.mts","names":[],"sources":["../src/extend/types.ts","../src/client/register.ts","../src/client/types.ts"],"mappings":";;;;;;;;;;AA2CA;;;KAAY,eAAA,yBACM,EAAA,aAAe,MAAA,aAAmB,IAAA;;;;;;AASpD;UAAiB,eAAA;EAAe;EAE9B,KAAA,EAAO,OAAA,CAAQ,MAAA,OAAa,GAAA;EAAb;EAEf,OAAA,GAAU,GAAA,EAAK,GAAA;AAAA;;;;;KAOL,gBAAA,yBACM,EAAA,aAAe,MAAA,SAAe,eAAA,CAAgB,EAAA,CAAG,KAAA;;UAIlD,mBAAA;EACf,KAAA,GAAQ,eAAA,CAAgB,EAAA;EACxB,MAAA,GAAS,gBAAA,CAAiB,EAAA;AAAA;AAP5B;;;;;;;;;;;;;AAAA,KAuBY,aAAA,wBACE,EAAA,GAAK,CAAA,eAAgB,CAAA,GAAI,EAAA,CAAG,CAAA,IAAK,cAAA,CAAe,CAAA,CAAE,CAAA,KAAM,EAAA,CAAG,CAAA;;KAIpE,cAAA,QACH,GAAA,SAAY,MAAA;EAAiB,OAAA,GAAU,GAAA;AAAA,mBAErB,GAAA,GAAM,GAAA,CAAI,CAAA;EAAa,OAAA,GAAU,GAAA;AAAA,IAA6B,GAAA;;;;;;KAUtE,cAAA,eAA6B,mBAAA,CAAoB,EAAA,KAAO,YAAA,CAClE,CAAA,mBAAoB,gBAAA,CAAiB,EAAA,IAAM,aAAA,CAAc,EAAA,EAAI,WAAA,CAAY,CAAA,eAAgB,EAAA,kBAE7E,WAAA,CAAY,CAAA,mBAAoB,EAAA,YAAc,WAAA,CAAY,WAAA,CAAY,CAAA,WAAY,CAAA;;;;;;;;AAjEhG;;;;;;;;;;;AAUA;;;;;;;UC7BiB,cAAA;;;;;;KAOL,YAAA,GAAe,cAAA;EAAyB,EAAA;IAAM,EAAA;MAAM,MAAA;IAAA;EAAA;AAAA,cAE5D,cAAA;EAAyB,EAAA;AAAA,IACvB,CAAA;EAAY,EAAA,EADA,QAAA,CACqB,MAAA;AAAA,IAC/B,CAAA;;;UC/BS,UAAA;EACf,GAAA;EACA,UAAA;EACA,UAAA;AAAA;AAAA,UAGe,eAAA;EACf,GAAA;EACA,UAAA;EACA,KAAA;AAAA;AAAA,UAGe,gBAAA;EF4BmC;EE1BlD,GAAA;EACA,UAAA;AAAA;AAAA,UAGe,gBAAA;EACf,SAAA;AAAA;AAAA,UAGe,wBAAA,SAAiC,gBAAA;EAChD,KAAA;AAAA;;;;;;;UASe,cAAA,SAAuB,UAAA;EFqBtC;EEnBA,WAAA;AAAA;AAAA,UAGe,kBAAA;EACf,WAAA,EAAa,gBAAA;EACb,KAAA,EAAO,UAAA;EACP,UAAA,EAAY,eAAA;EACZ,SAAA,EAAW,cAAA;EACX,gBAAA,EAAkB,gBAAA;EAClB,iBAAA,EAAmB,gBAAA;EACnB,mBAAA,EAAqB,wBAAA;AAAA;;;;;;;;;;;;;AFqBvB;;;;;;;UECiB,YAAA,MAAkB,YAAA;EFCR;EAAA,SEChB,EAAA,EAAI,MAAA,CAAO,EAAA;EAAA,SACX,OAAA;EAET,UAAA,EAAY,MAAA,CAAO,EAAA;EACnB,UAAA,EAAY,MAAA,CAAO,EAAA;EACnB,WAAA,EAAa,MAAA,CAAO,EAAA;EACpB,UAAA,EAAY,MAAA,CAAO,EAAA;EAEnB,EAAA,iBAAmB,kBAAA,EACjB,KAAA,EAAO,CAAA,EACP,QAAA,GAAW,CAAA,EAAG,kBAAA,CAAmB,CAAA,aAAc,OAAA;EAGjD,GAAA,iBAAoB,kBAAA,EAClB,KAAA,EAAO,CAAA,EACP,QAAA,GAAW,CAAA,EAAG,kBAAA,CAAmB,CAAA,aAAc,OAAA;EAGjD,WAAA,IAAe,EAAA,GAAK,EAAA,EAAI,YAAA,CAAa,EAAA,MAAQ,OAAA,CAAQ,CAAA,IAAK,OAAA,CAAQ,CAAA;EAClE,WAAA,IAAe,IAAA,EAAM,gBAAA,EAAkB,EAAA,GAAK,EAAA,EAAI,YAAA,CAAa,EAAA,MAAQ,OAAA,CAAQ,CAAA,IAAK,OAAA,CAAQ,CAAA;EAE1F,SAAA,IAAa,EAAA,GAAK,EAAA,EAAI,YAAA,CAAa,EAAA,MAAQ,OAAA,CAAQ,CAAA,IAAK,OAAA,CAAQ,CAAA;EFNzC;;;;;;;;;;;;;;;;;;;;;;;EE+BvB,QAAA,WAAmE,mBAAA,CAAF,EAAA,GAC/D,GAAA,EAAK,CAAA,GAC0C,cAAA,CAAL,EAAA,EAAI,CAAA;EAEhD,OAAA,IAAW,OAAA;AAAA;AAAA,UAGI,qBAAA;EFrCyD;EEuCxE,MAAA,EAAQ,OAAA;EFnCS;EEqCjB,OAAA,EAAS,OAAA;EFpCT;;;;;;EE2CA,MAAA;EF5CkB;;;;;;EEmDlB,oBAAA;EFhDwB;;;;;;;;AAU1B;;;;;;;;;;;;;;;;;;;EEkEE,GAAA,GA1CsB,mCAAA,CA0C2B,YAAA;AAAA"}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@forinda/kickjs-db",
|
|
3
|
-
"version": "5.
|
|
3
|
+
"version": "5.2.0",
|
|
4
4
|
"description": "KickJS-native ORM — code-first schema, reversible migrations, multi-dialect SQL builder",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"kickjs",
|
|
@@ -24,6 +24,10 @@
|
|
|
24
24
|
"./pg": {
|
|
25
25
|
"import": "./dist/pg.mjs",
|
|
26
26
|
"types": "./dist/pg.d.mts"
|
|
27
|
+
},
|
|
28
|
+
"./devtools-events": {
|
|
29
|
+
"import": "./dist/devtools-events.mjs",
|
|
30
|
+
"types": "./dist/devtools-events.d.mts"
|
|
27
31
|
}
|
|
28
32
|
},
|
|
29
33
|
"files": [
|
|
@@ -48,7 +52,13 @@
|
|
|
48
52
|
"kysely": "0.28.16"
|
|
49
53
|
},
|
|
50
54
|
"peerDependencies": {
|
|
51
|
-
"@forinda/kickjs": ">=5.0.0"
|
|
55
|
+
"@forinda/kickjs": ">=5.0.0",
|
|
56
|
+
"@forinda/kickjs-devtools-kit": ">=5.1.0"
|
|
57
|
+
},
|
|
58
|
+
"peerDependenciesMeta": {
|
|
59
|
+
"@forinda/kickjs-devtools-kit": {
|
|
60
|
+
"optional": true
|
|
61
|
+
}
|
|
52
62
|
},
|
|
53
63
|
"devDependencies": {
|
|
54
64
|
"@testcontainers/postgresql": "^10.16.0",
|
|
@@ -57,7 +67,8 @@
|
|
|
57
67
|
"kysely": "^0.28.16",
|
|
58
68
|
"pg": "^8.13.1",
|
|
59
69
|
"typescript": "^5.9.2",
|
|
60
|
-
"@forinda/kickjs": "5.
|
|
70
|
+
"@forinda/kickjs-devtools-kit": "5.2.0",
|
|
71
|
+
"@forinda/kickjs": "5.2.0"
|
|
61
72
|
},
|
|
62
73
|
"publishConfig": {
|
|
63
74
|
"access": "public"
|