introduce Serialized<O>

introduce ValueNode.serialized.

introduce eb.valSerialized.

introduce sql.valSerialized.

fix json-traversal test suite.

fix null handling @ compiler.

rename to `valJson`.

add instructions in errors.

typings test inserts.

call the new type `Json` instead, to not introduce a breaking change.

add missing json column @ Getting Started.

add `appendSerializedValue`.
Renames `valJson` to `jval` for JSON value wrapping

Renames the `valJson` method to `jval` for wrapping JSON values
when inserting or updating columns. This change promotes brevity
and consistency throughout the codebase.

The name change affects the expression builder, SQL raw builder,
and documentation.

fix jsdocs check.

Author: igalklebanov

deno.check.d.ts

@@ -3,6 +3,7 @@ import type {
   Generated,
   GeneratedAlways,
   Insertable,
+  Json,
   Kysely,
   Selectable,
   SqlBool,
@@ -13,6 +14,7 @@ export interface Database {
   audit: AuditTable
   person: PersonTable
   person_backup: PersonTable
+  person_metadata: PersonMetadataTable
   pet: PetTable
   toy: ToyTable
   wine: WineTable
@@ -47,6 +49,14 @@ interface PersonTable {
   marital_status: 'single' | 'married' | 'divorced' | 'widowed' | null
 }
 
+interface PersonMetadataTable {
+  id: Generated<number>
+  personId: number
+  experience: Json<{ title: string; company: string }[]>
+  preferences: Json<{ locale: string; timezone: string }> | null
+  profile: Json<{ email_verified: boolean }> | null
+}
+
 interface PetTable {
   id: Generated<number>
   created_at: GeneratedAlways<Date>

deno.check.json

@@ -4,6 +4,7 @@
     "types": ["./deno.check.d.ts"]
   },
   "imports": {
+    "@electric-sql/pglite": "npm:@electric-sql/pglite",
     "better-sqlite3": "npm:better-sqlite3",
     "kysely": "./dist/esm",
     "kysely/helpers/mssql": "./dist/esm/helpers/mssql.js",

site/docs/getting-started/Summary.tsx

@@ -12,6 +12,7 @@ const postgresqlCodeSnippet = `    await db.schema.createTable('person')
       .addColumn('created_at', 'timestamp', (cb) =>
         cb.notNull().defaultTo(sql\`now()\`)
       )
+      .addColumn('metadata', 'jsonb', (cb) => cb.notNull())
       .execute()`
 
 const dialectSpecificCodeSnippets: Record<Dialect, string> = {
@@ -24,6 +25,7 @@ const dialectSpecificCodeSnippets: Record<Dialect, string> = {
       .addColumn('created_at', 'timestamp', (cb) =>
         cb.notNull().defaultTo(sql\`now()\`)
       )
+      .addColumn('metadata', 'json', (cb) => cb.notNull())
       .execute()`,
   // TODO: Update line 42's IDENTITY once identity(1,1) is added to core.
   mssql: `    await db.schema.createTable('person')
@@ -34,6 +36,7 @@ const dialectSpecificCodeSnippets: Record<Dialect, string> = {
       .addColumn('created_at', 'datetime', (cb) =>
         cb.notNull().defaultTo(sql\`GETDATE()\`)
       )
+      .addColumn('metadata', sql\`nvarchar(max)\`, (cb) => cb.notNull())
       .execute()`,
   sqlite: `    await db.schema.createTable('person')
       .addColumn('id', 'integer', (cb) => cb.primaryKey().autoIncrement().notNull())
@@ -43,6 +46,7 @@ const dialectSpecificCodeSnippets: Record<Dialect, string> = {
       .addColumn('created_at', 'timestamp', (cb) =>
         cb.notNull().defaultTo(sql\`current_timestamp\`)
       )
+      .addColumn('metadata', 'text', (cb) => cb.notNull())
       .execute()`,
   pglite: postgresqlCodeSnippet,
 }
@@ -109,6 +113,12 @@ ${dialectSpecificCodeSnippet}
       first_name: 'Jennifer',
       last_name: 'Aniston',
       gender: 'woman',
+      metadata: sql.jval({
+        login_at: new Date().toISOString(),
+        ip: null,
+        agent: null,
+        plan: 'free',
+      }),
     })
   })
     

site/docs/getting-started/_types.mdx

@@ -10,7 +10,7 @@ import {
   ColumnType,
   Generated,
   Insertable,
-  JSONColumnType,
+  Json,
   Selectable,
   Updateable,
 } from 'kysely'
@@ -45,12 +45,10 @@ export interface PersonTable {
   // can never be updated:
   created_at: ColumnType<Date, string | undefined, never>
 
-  // You can specify JSON columns using the `JSONColumnType` wrapper.
-  // It is a shorthand for `ColumnType<T, string, string>`, where T
-  // is the type of the JSON object/array retrieved from the database,
-  // and the insert and update types are always `string` since you're
-  // always stringifying insert/update values.
-  metadata: JSONColumnType<{
+  // You can specify JSON columns using the `Json` wrapper.
+  // When inserting/updating values of such columns, you're required to wrap the
+  // values with `eb.jval` or `sql.jval`.
+  metadata: Json<{
     login_at: string
     ip: string | null
     agent: string | null

src/dialect/pglite/pglite-adapter.ts

@@ -5,13 +5,13 @@ export class PGliteAdapter extends PostgresAdapter {
     return false
   }
 
-  async acquireMigrationLock(): Promise<void> {
+  override async acquireMigrationLock(): Promise<void> {
     // PGlite only has one connection that's reserved by the migration system
     // for the whole time between acquireMigrationLock and releaseMigrationLock.
     // We don't need to do anything here.
   }
 
-  async releaseMigrationLock(): Promise<void> {
+  override async releaseMigrationLock(): Promise<void> {
     // PGlite only has one connection that's reserved by the migration system
     // for the whole time between acquireMigrationLock and releaseMigrationLock.
     // We don't need to do anything here.

src/dialect/pglite/pglite-dialect-config.ts

@@ -19,7 +19,7 @@ export interface PGliteDialectConfig {
    *
    * https://pglite.dev/docs/api#main-constructor
    */
-  pglite: PGlite | (() => Promise<PGlite>)
+  pglite: PGlite | (() => PGlite | Promise<PGlite>)
 }
 
 /**

src/expression/expression-builder.ts

@@ -69,7 +69,7 @@ import {
   ValTuple5,
 } from '../parser/tuple-parser.js'
 import { TupleNode } from '../operation-node/tuple-node.js'
-import { Selectable } from '../util/column-type.js'
+import { Selectable, Serialized } from '../util/column-type.js'
 import { JSONPathNode } from '../operation-node/json-path-node.js'
 import { KyselyTypeError } from '../util/type-error.js'
 import {
@@ -78,6 +78,7 @@ import {
 } from '../parser/data-type-parser.js'
 import { CastNode } from '../operation-node/cast-node.js'
 import { SelectFrom } from '../parser/select-from-parser.js'
+import { ValueNode } from '../operation-node/value-node.js'
 
 export interface ExpressionBuilder<DB, TB extends keyof DB> {
   /**
@@ -590,6 +591,42 @@ export interface ExpressionBuilder<DB, TB extends keyof DB> {
     value: VE,
   ): ExpressionWrapper<DB, TB, ExtractTypeFromValueExpression<VE>>
 
+  /**
+   * Returns a value expression that will be serialized before being passed to the database.
+   *
+   * This can be used to pass in an object/array value when inserting/updating a
+   * value to a column defined with `Json`.
+   *
+   * Default serializer function is `JSON.stringify`.
+   *
+   * ### Example
+   *
+   * ```ts
+   * import { Json } from 'kysely'
+   *
+   * interface Database {
+   *   person_metadata: {
+   *     experience: Json<{ title: string; company: string }[]>
+   *     preferences: Json<{ locale: string; timezone: string }>
+   *     profile: Json<{ email_verified: boolean }>
+   *   }
+   * }
+   *
+   * const result = await db
+   *   .insertInto('person_metadata')
+   *   .values(({ jval }) => ({
+   *     personId: 123,
+   *     experience: jval([{ title: 'Software Engineer', company: 'Google' }]), // ✔️
+   *     // preferences: jval({ locale: 'en' }), // ❌ missing `timezone`
+   *     // profile: JSON.stringify({ email_verified: true }), // ❌ doesn't match `Serialized<{ email_verified }>`
+   *   }))
+   *   .execute()
+   * ```
+   */
+  jval<O extends object | null>(
+    obj: O,
+  ): ExpressionWrapper<DB, TB, Serialized<O>>
+
   /**
    * Creates a tuple expression.
    *
@@ -1233,6 +1270,14 @@ export function createExpressionBuilder<DB, TB extends keyof DB>(
       return new ExpressionWrapper(parseValueExpression(value))
     },
 
+    jval<O extends object | null>(
+      value: O,
+    ): ExpressionWrapper<DB, TB, Serialized<O>> {
+      return new ExpressionWrapper(
+        ValueNode.create(value, { serialized: true }),
+      )
+    },
+
     refTuple(
       ...values: ReadonlyArray<ReferenceExpression<any, any>>
     ): ExpressionWrapper<DB, TB, any> {

src/operation-node/value-node.ts

@@ -5,6 +5,7 @@ export interface ValueNode extends OperationNode {
   readonly kind: 'ValueNode'
   readonly value: unknown
   readonly immediate?: boolean
+  readonly serialized?: boolean
 }
 
 /**
@@ -15,9 +16,10 @@ export const ValueNode = freeze({
     return node.kind === 'ValueNode'
   },
 
-  create(value: unknown): ValueNode {
+  create(value: unknown, props?: { serialized?: boolean }): ValueNode {
     return freeze({
       kind: 'ValueNode',
+      ...props,
       value,
     })
   },

src/query-compiler/default-query-compiler.ts

@@ -519,6 +519,8 @@ export class DefaultQueryCompiler
   protected override visitValue(node: ValueNode): void {
     if (node.immediate) {
       this.appendImmediateValue(node.value)
+    } else if (node.serialized) {
+      this.appendSerializedValue(node.value)
     } else {
       this.appendValue(node.value)
     }
@@ -1757,6 +1759,14 @@ export class DefaultQueryCompiler
     this.append(this.getCurrentParameterPlaceholder())
   }
 
+  protected appendSerializedValue(parameter: unknown): void {
+    if (parameter === null) {
+      this.appendValue(null)
+    } else {
+      this.appendValue(JSON.stringify(parameter))
+    }
+  }
+
   protected getLeftIdentifierWrapper(): string {
     return '"'
   }

src/raw-builder/sql.ts

@@ -6,6 +6,7 @@ import { ValueNode } from '../operation-node/value-node.js'
 import { parseStringReference } from '../parser/reference-parser.js'
 import { parseTable } from '../parser/table-parser.js'
 import { parseValueExpression } from '../parser/value-parser.js'
+import { Serialized } from '../util/column-type.js'
 import { createQueryId } from '../util/query-id.js'
 import { RawBuilder, createRawBuilder } from './raw-builder.js'
 
@@ -137,6 +138,22 @@ export interface Sql {
    */
   val<V>(value: V): RawBuilder<V>
 
+  /**
+   * `sql.jval(value)` is a shortcut for:
+   *
+   * ```ts
+   * import { Serialized, sql } from 'kysely'
+   *
+   * const serializerFn = JSON.stringify
+   * const obj = { hello: 'world!' }
+   *
+   * sql<Serialized<typeof obj>>`${serializerFn(obj)}`
+   * ```
+   *
+   * Default serializer function is `JSON.stringify`.
+   */
+  jval<O extends object | null>(value: O): RawBuilder<Serialized<O>>
+
   /**
    * @deprecated Use {@link Sql.val} instead.
    */
@@ -417,6 +434,15 @@ export const sql: Sql = Object.assign(
       })
     },
 
+    jval<O extends object | null>(value: O): RawBuilder<Serialized<O>> {
+      return createRawBuilder({
+        queryId: createQueryId(),
+        rawNode: RawNode.createWithChild(
+          ValueNode.create(value, { serialized: true }),
+        ),
+      })
+    },
+
     value<V>(value: V): RawBuilder<V> {
       return this.val(value)
     },