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.

Author: igalklebanov

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/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,44 @@ 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 { GeneratedAlways, Json } from 'kysely'
+   *
+   * interface Database {
+   *   person: {
+   *     id: GeneratedAlways<number>
+   *     name: string
+   *     experience: Json<{ title: string; company: string }[]>
+   *     preferences: Json<{ locale: string; timezone: string }>
+   *     profile: Json<{ email_verified: boolean }>
+   *   }
+   * }
+   *
+   * const result = await db
+   *   .insertInto('person')
+   *   .values(({ jval }) => ({
+   *     name: 'Jennifer Aniston',
+   *     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 +1272,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,17 @@ export interface Sql {
    */
   val<V>(value: V): RawBuilder<V>
 
+  /**
+   * `sql.jval(value)` is a shortcut for:
+   *
+   * ```ts
+   * sql<Serialized<ValueType>>`${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 +429,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)
     },

src/util/column-type.ts

@@ -63,9 +63,37 @@ export type Generated<S> = ColumnType<S, S | undefined, S>
  */
 export type GeneratedAlways<S> = ColumnType<S, never, never>
 
+/**
+ * A shortcut for defining type-safe JSON columns. Inserts/updates require passing
+ * values that are wrapped with `eb.jval` or `sql.jval` instead of `JSON.stringify`.
+ */
+export type Json<
+  SelectType extends object | null,
+  InsertType extends Serialized<SelectType> | Extract<null, SelectType> =
+    | Serialized<SelectType>
+    | Extract<null, SelectType>,
+  UpdateType extends Serialized<SelectType> | Extract<null, SelectType> =
+    | Serialized<SelectType>
+    | Extract<null, SelectType>,
+> = ColumnType<SelectType, InsertType, UpdateType>
+
+/**
+ * A symbol that is used to brand serialized objects/arrays.
+ * @internal
+ */
+declare const SerializedBrand: unique symbol
+
+/**
+ * A type that is used to brand serialized objects/arrays.
+ */
+export type Serialized<O extends object | null> = O & {
+  readonly [SerializedBrand]: '⚠️ When you insert into or update columns of type `Json` (or similar), you should wrap your JSON value with `eb.jval` or `sql.jval`, instead of `JSON.stringify`. ⚠️'
+}
+
 /**
  * A shortcut for defining JSON columns, which are by default inserted/updated
  * as stringified JSON strings.
+ * @deprecated Use {@link Json} instead.
  */
 export type JSONColumnType<
   SelectType extends object | null,

test/node/src/json-traversal.test.ts

@@ -1,6 +1,6 @@
 import {
   ColumnDefinitionBuilder,
-  JSONColumnType,
+  Json,
   ParseJSONResultsPlugin,
   SqlBool,
   sql,
@@ -756,9 +756,9 @@ async function initJSONTest<D extends DialectDescriptor>(
   let db = testContext.db.withTables<{
     person_metadata: {
       person_id: number
-      website: JSONColumnType<{ url: string }>
-      nicknames: JSONColumnType<string[]>
-      profile: JSONColumnType<{
+      website: Json<{ url: string }>
+      nicknames: Json<string[]>
+      profile: Json<{
         auth: {
           roles: string[]
           last_login?: { device: string }
@@ -768,12 +768,12 @@ async function initJSONTest<D extends DialectDescriptor>(
         avatar: string | null
         tags: string[]
       }>
-      experience: JSONColumnType<
+      experience: Json<
         {
           establishment: string
         }[]
       >
-      schedule: JSONColumnType<{ name: string; time: string }[][][]>
+      schedule: Json<{ name: string; time: string }[][][]>
     }
   }>()
 
@@ -822,20 +822,20 @@ async function insertDefaultJSONDataSet(ctx: TestContext) {
 
   await ctx.db
     .insertInto('person_metadata')
-    .values(
+    .values((eb) =>
       people
         .filter((person) => person.first_name && person.last_name)
         .map((person, index) => ({
           person_id: person.id,
-          website: JSON.stringify({
+          website: eb.jval({
             url: `https://www.${person.first_name!.toLowerCase()}${person.last_name!.toLowerCase()}.com`,
           }),
-          nicknames: JSON.stringify([
+          nicknames: eb.jval([
             `${person.first_name![0]}.${person.last_name![0]}.`,
             `${person.first_name} the Great`,
             `${person.last_name} the Magnificent`,
           ]),
-          profile: JSON.stringify({
+          profile: eb.jval({
             tags: ['awesome'],
             auth: {
               roles: ['contributor', 'moderator'],
@@ -847,12 +847,12 @@ async function insertDefaultJSONDataSet(ctx: TestContext) {
             },
             avatar: null,
           }),
-          experience: JSON.stringify([
+          experience: eb.jval([
             {
               establishment: 'The University of Life',
             },
           ]),
-          schedule: JSON.stringify([[[{ name: 'Gym', time: '12:15' }]]]),
+          schedule: sql.jval([[[{ name: 'Gym', time: '12:15' }]]]),
         })),
     )
     .execute()

test/typings/shared.d.ts

@@ -1,9 +1,4 @@
-import {
-  ColumnType,
-  Generated,
-  GeneratedAlways,
-  JSONColumnType,
-} from '../../dist/cjs'
+import { ColumnType, Generated, GeneratedAlways, Json } from '../../dist/cjs'
 
 export interface Pet {
   id: Generated<string>
@@ -71,21 +66,21 @@ export interface Person {
 export interface PersonMetadata {
   id: Generated<number>
   person_id: number
-  website: JSONColumnType<{ url: string }>
-  nicknames: JSONColumnType<string[]>
-  profile: JSONColumnType<{
+  website: Json<{ url: string }>
+  nicknames: Json<string[]>
+  profile: Json<{
     auth: {
       roles: string[]
       last_login?: { device: string }
     }
     tags: string[]
   }>
-  experience: JSONColumnType<
+  experience: Json<
     {
       establishment: string
     }[]
   >
-  schedule: JSONColumnType<{ name: string; time: string }[][][]>
-  record: JSONColumnType<Record<string, string>>
-  array: JSONColumnType<Array<string>>
+  schedule: Json<{ name: string; time: string }[][][]>
+  record: Json<Record<string, string>>
+  array: Json<Array<string> | null>
 }