# kysely-plugin-serialize

> Auto serialize / deserialize plugin for kysely

Latest version **0.8.2** (published 2025-02-12) · MIT license · 0 weekly downloads

## Install

```sh
npm install kysely-plugin-serialize
pnpm add kysely-plugin-serialize
yarn add kysely-plugin-serialize
bun add kysely-plugin-serialize
```

## Health

**Score 40/100 (D)** — status: maintenance-mode.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads; pre 1.0.

Negative: stale; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.8.2 |
| Published | 2025-02-12 |
| First published | 2023-04-24 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 0 |
| Unpacked size | 24.2 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 13 |
| Author | subframe7536 |
| Maintainers | subframe7536 |
| Keywords | kysely, sql, plugin |

## Links

- npm: https://www.npmjs.com/package/kysely-plugin-serialize
- Repository: https://github.com/subframe7536/kysely-plugin-serialize.git#master
- Homepage: https://github.com/subframe7536/kysely-plugin-serialize
- Issues: https://github.com/subframe7536/kysely-plugin-serialize/issues
- npm.io page: https://npm.io/package/kysely-plugin-serialize

## Recent versions

- 0.8.2 (latest) — 2025-02-12
- 0.8.1 — 2025-01-31
- 0.8.0 — 2025-01-29
- 0.7.0 — 2024-10-29
- 0.6.3 — 2024-08-18
- 0.6.2 — 2024-07-07
- 0.6.1 — 2024-05-11
- 0.6.0 — 2024-03-27
- 0.5.7 — 2024-02-15
- 0.5.6 — 2024-01-09
- 0.5.4 — 2023-12-12
- 0.5.3 — 2023-11-14
- 0.5.2 — 2023-11-14
- 0.5.1 — 2023-11-12
- 0.5.0 — 2023-11-08
- … 26 more at https://npm.io/package/kysely-plugin-serialize/versions

## README

# kysely-plugin-serialize

Auto serialize / deserialize plugin for [kysely](https://github.com/kysely-org/kysely)

Breaking change expected between minors in version `0.x`

## Purpose

Kysely does not process the values passed in, so in some cases you may need to manually handle the values to ensure they can be processed correctly by the dialect. Therefore, the main goal of this plugin is DX, so the values serialized by the default serializer may not conform to the usual standards. If you need to ensure the actual values in the database, you can write your own serializer.

## Install

```shell
pnpm add kysely kysely-plugin-serialize
```

## Usage

The following example will return an error when using sqlite dialects, unless using this plugin:

```ts
import { Kysely, SqliteDialect } from 'kysely'
import { SerializePlugin } from 'kysely-plugin-serialize'

interface TestTable {
  id: Generated<number>
  person: { name: string, age: number, time: Date } | null
  gender: boolean
  blob: Uint8Array | null
  date: Date
}

interface Database {
  test: TestTable
}

const db = new Kysely<Database>({
  dialect: new SqliteDialect({
    database: new Database(':memory:'),
  }),
  plugins: [
    new SerializePlugin(),
  ],
})

await db.insertInto('test').values({
  gender: true,
  person: { name: 'test', age: 2, time: new Date() },
  blob: Uint8Array.from([1, 2, 3]),
  date: new Date(),
}).execute()
```

You can also provide a custom serializer function:

```ts
import { Kysely, SqliteDialect } from 'kysely'
import { SerializePlugin } from 'kysely-plugin-serialize'

const db = new Kysely<Database>({
  dialect: new SqliteDialect({
    database: new Database(':memory:'),
  }),
  plugins: [
    new SerializePlugin({
      serializer: (value) => {
        if (value instanceof Date) {
          return formatDatetime(value)
        }

        if (value !== null && typeof value === 'object') {
          return JSON.stringify(value)
        }

        return value
      }
    }),
  ],
})
```

### Base plugin

If you want to reduce your production size, you can use basic plugin

```ts
import {
  BaseSerializePlugin,
  dateRegex,
  type Deserializer,
  maybeJson,
  type Serializer,
  skipTransform as skip,
} from 'kysely-plugin-serialize'

const skipTransform = (parameter: unknown): boolean => skip(parameter) || typeof parameter === 'boolean'

const serializer: Serializer = (parameter) => {
  if (skipTransform(parameter) || typeof parameter === 'string') {
    return parameter
  }
  try {
    return JSON.stringify(parameter)
  } catch {
    return parameter
  }
}

const deserializer: Deserializer = (parameter) => {
  if (skipTransform(parameter)) {
    return parameter
  }
  if (typeof parameter === 'string') {
    if (dateRegex.test(parameter)) {
      return new Date(parameter)
    } else if (maybeJson(parameter)) {
      try {
        return JSON.parse(parameter)
      } catch { }
    }
  }
  return parameter
}

const plugin = new BaseSerializePlugin(serializer, deserializer, [])
```

## Notice

THIS PLUGIN SHOULD BE PLACED AT THE END OF PLUGINS ARRAY

default serializer / deserializer is built for SQLite

rules:

1. `number` / `bigint` / `ArrayBuffer` / `Buffer` will skip serialization
2. `boolean` will be serialized to `'true'` / `'false'`
3. `Date` will be serialized to ISO string
4. others will be serialized by `JSON.stringify` / `JSON.parse`

## Credit

[kysely #138](https://github.com/koskimas/kysely/pull/138)

---
_Source: https://npm.io/package/kysely-plugin-serialize · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._