@forinda/kickjs-db 5.1.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.
@@ -0,0 +1,162 @@
1
+
2
+ //#region src/snapshot/types.d.ts
3
+ type Dialect = 'postgres' | 'sqlite' | 'mysql';
4
+ type FkAction = 'cascade' | 'restrict' | 'set_null' | 'set_default' | 'no_action';
5
+ interface ColumnSnapshot {
6
+ name: string;
7
+ type: string;
8
+ nullable: boolean;
9
+ default: string | null;
10
+ primaryKey: boolean;
11
+ }
12
+ interface IndexSnapshot {
13
+ name: string;
14
+ columns: string[];
15
+ unique: boolean;
16
+ }
17
+ interface ForeignKeySnapshot {
18
+ name: string;
19
+ columns: string[];
20
+ refTable: string;
21
+ refColumns: string[];
22
+ onDelete: FkAction;
23
+ onUpdate: FkAction;
24
+ }
25
+ interface CheckSnapshot {
26
+ name: string;
27
+ expression: string;
28
+ }
29
+ interface TableSnapshot {
30
+ name: string;
31
+ columns: Record<string, ColumnSnapshot>;
32
+ indexes: IndexSnapshot[];
33
+ foreignKeys: ForeignKeySnapshot[];
34
+ checks: CheckSnapshot[];
35
+ }
36
+ /**
37
+ * PostgreSQL ENUM type declaration. Currently PG-only; the field is
38
+ * optional on `SchemaSnapshot` so other dialects don't have to carry
39
+ * a phantom `enums: {}`.
40
+ */
41
+ interface EnumSnapshot {
42
+ name: string;
43
+ /** Allowed values, in declaration order. PG preserves the order. */
44
+ values: readonly string[];
45
+ }
46
+ interface SchemaSnapshot {
47
+ version: 1;
48
+ dialect: Dialect;
49
+ tables: Record<string, TableSnapshot>;
50
+ /** ENUM types declared via `pgEnum()`. PG-only; absent on other dialects. */
51
+ enums?: Record<string, EnumSnapshot>;
52
+ }
53
+ //#endregion
54
+ //#region src/dsl/columns/types.d.ts
55
+ /**
56
+ * Runtime + type representation of a column reference (e.g. `users.id`).
57
+ * Carries the parent table name, the column's own name, plus runtime
58
+ * accessors used by FK thunks and constraint builders.
59
+ *
60
+ * Exported so adopters can annotate self-referencing thunks without
61
+ * spelling the shape inline:
62
+ *
63
+ * parentId: uuid().references((): ColumnRef => categories.id)
64
+ *
65
+ * Without the annotation the initializer of a self-referencing const
66
+ * trips TS7022 — TS needs to infer the const while the initializer
67
+ * already references it.
68
+ */
69
+ interface ColumnRef {
70
+ __tableName: string;
71
+ __name: string;
72
+ __builder: ColumnBuilder;
73
+ __state: () => ReturnType<ColumnBuilder['__state']>;
74
+ }
75
+ /**
76
+ * Resolved FK spec — `table` / `column` are pulled by invoking `thunk()`
77
+ * lazily. The thunk pattern lets self-referencing tables work:
78
+ *
79
+ * const categories = table('categories', {
80
+ * id: uuid().primaryKey().defaultRandom(),
81
+ * parentId: uuid().references((): ColumnRef => categories.id),
82
+ * })
83
+ *
84
+ * If we resolved at `.references()` call time, `categories` would TDZ-fail
85
+ * inside its own initializer. Storing the thunk and resolving on read
86
+ * (extract / render / emit) defers until after the const binding lands.
87
+ */
88
+ interface FkSpec {
89
+ thunk: () => ColumnRef;
90
+ onDelete: FkAction;
91
+ onUpdate: FkAction;
92
+ }
93
+ interface ColumnState {
94
+ type: string;
95
+ nullable: boolean;
96
+ default: string | null;
97
+ primaryKey: boolean;
98
+ unique: boolean;
99
+ references: FkSpec | null;
100
+ }
101
+ /**
102
+ * Type-only brand attached to a column when it's auto-assigned by the
103
+ * database (serial / bigserial / smallserial), has a runtime default
104
+ * (`.default(...)`), or carries an expression default
105
+ * (`uuid().defaultRandom()`, `timestamp().defaultNow()`). `SchemaToTypes<S>`
106
+ * reads this marker and wraps the column type in Kysely's `Generated<T>` so
107
+ * adopters can omit the column on insert.
108
+ *
109
+ * Runtime is a no-op — the symbol never reaches a value.
110
+ */
111
+ declare const KICK_GENERATED: unique symbol;
112
+ type GeneratedBrand = {
113
+ readonly [KICK_GENERATED]?: true;
114
+ };
115
+ /**
116
+ * Type-only brand attached to a column when `.notNull()` or `.primaryKey()`
117
+ * is called. `SchemaToTypes<S>` reads this brand to decide whether the
118
+ * column type is `T` (NOT NULL) or `T | null` (default nullable).
119
+ *
120
+ * Why a brand instead of a class generic: chained methods (notNull,
121
+ * primaryKey) can return `this & NotNullBrand` to narrow nullability while
122
+ * preserving the subclass identity — so `uuid().primaryKey().defaultRandom()`
123
+ * still resolves `defaultRandom()` on `UuidBuilder`. A class generic
124
+ * `<TNullable>` would collapse the subclass back to the parent.
125
+ */
126
+ declare const KICK_NOT_NULL: unique symbol;
127
+ type NotNullBrand = {
128
+ readonly [KICK_NOT_NULL]?: true;
129
+ };
130
+ /**
131
+ * Phantom-typed column builder. The `T` generic carries the column's TS
132
+ * value type (number / string / Date / etc.); nullability is tracked via
133
+ * the `NotNullBrand` intersection rather than a class generic so chain
134
+ * methods preserve subclass identity.
135
+ *
136
+ * Both `T` and the brand are erased at runtime; they exist purely so
137
+ * `SchemaToTypes<S>` can pull them out per column.
138
+ */
139
+ declare class ColumnBuilder<T = unknown> {
140
+ readonly __t?: T;
141
+ protected state: ColumnState;
142
+ constructor(type: string, defaults?: Partial<ColumnState>);
143
+ notNull(): this & NotNullBrand;
144
+ primaryKey(): this & NotNullBrand;
145
+ unique(): this;
146
+ array(): ColumnBuilder<T[]>;
147
+ references(target: () => ColumnRef, opts?: {
148
+ onDelete?: FkAction;
149
+ onUpdate?: FkAction;
150
+ }): this;
151
+ /**
152
+ * Mark the column as having a runtime / DB-assigned default. The
153
+ * `GeneratedBrand` flows into `SchemaToTypes<S>` so the column wraps
154
+ * in `Generated<T>` — adopters can `INSERT` without specifying it.
155
+ */
156
+ default(value: string): this & GeneratedBrand;
157
+ toJSON(name: string): ColumnSnapshot;
158
+ __state(): Readonly<ColumnState>;
159
+ }
160
+ //#endregion
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-D2FzsPow.d.mts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"types-D2FzsPow.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"}
package/package.json ADDED
@@ -0,0 +1,87 @@
1
+ {
2
+ "name": "@forinda/kickjs-db",
3
+ "version": "5.1.0",
4
+ "description": "KickJS-native ORM — code-first schema, reversible migrations, multi-dialect SQL builder",
5
+ "keywords": [
6
+ "kickjs",
7
+ "orm",
8
+ "typescript",
9
+ "postgres",
10
+ "sqlite",
11
+ "mysql",
12
+ "migrations",
13
+ "query-builder",
14
+ "@forinda/kickjs"
15
+ ],
16
+ "type": "module",
17
+ "main": "dist/index.mjs",
18
+ "types": "dist/index.d.mts",
19
+ "exports": {
20
+ ".": {
21
+ "import": "./dist/index.mjs",
22
+ "types": "./dist/index.d.mts"
23
+ },
24
+ "./pg": {
25
+ "import": "./dist/pg.mjs",
26
+ "types": "./dist/pg.d.mts"
27
+ }
28
+ },
29
+ "files": [
30
+ "dist"
31
+ ],
32
+ "wireit": {
33
+ "build": {
34
+ "command": "tsdown",
35
+ "files": [
36
+ "src/**/*.ts",
37
+ "tsdown.config.ts",
38
+ "tsconfig.json",
39
+ "package.json"
40
+ ],
41
+ "output": [
42
+ "dist/**"
43
+ ],
44
+ "dependencies": []
45
+ }
46
+ },
47
+ "dependencies": {
48
+ "kysely": "0.28.16"
49
+ },
50
+ "peerDependencies": {
51
+ "@forinda/kickjs": ">=5.0.0"
52
+ },
53
+ "devDependencies": {
54
+ "@testcontainers/postgresql": "^10.16.0",
55
+ "@types/node": "^25.6.0",
56
+ "@types/pg": "^8.11.10",
57
+ "kysely": "^0.28.16",
58
+ "pg": "^8.13.1",
59
+ "typescript": "^5.9.2",
60
+ "@forinda/kickjs": "5.1.0"
61
+ },
62
+ "publishConfig": {
63
+ "access": "public"
64
+ },
65
+ "license": "MIT",
66
+ "author": "Felix Orinda",
67
+ "engines": {
68
+ "node": ">=20.0"
69
+ },
70
+ "homepage": "https://forinda.github.io/kick-js/",
71
+ "repository": {
72
+ "type": "git",
73
+ "url": "https://github.com/forinda/kick-js.git",
74
+ "directory": "packages/db"
75
+ },
76
+ "bugs": {
77
+ "url": "https://github.com/forinda/kick-js/issues"
78
+ },
79
+ "scripts": {
80
+ "build": "wireit",
81
+ "dev": "tsdown --watch",
82
+ "test": "vitest run --passWithNoTests",
83
+ "typecheck": "tsc --noEmit",
84
+ "clean": "rm -rf dist .wireit",
85
+ "lint": "tsc --noEmit"
86
+ }
87
+ }