@fraqjs/plugin-kysely

import KyselyPlugin from '@fraqjs/plugin-kysely';

ctx.install(KyselyPlugin, {
  // 在这里传入 KyselyPlugin 的配置选项
});

import { definePlugin } from '@fraqjs/fraq';
import { DatabaseService } from '@fraqjs/plugin-kysely';

definePlugin({
  name: 'my-plugin',
  inject: {
    db: DatabaseService,
  },
  apply(ctx) {
    // 使用 ctx.db 来访问 DatabaseService
  },
});

import type {
  ColumnType,
  Generated,
  Insertable,
  JSONColumnType,
  Selectable,
  Updateable,
} from 'kysely';

// 这个接口描述了 `person` 表的结构。
// Table 接口应该只在上面的 `FraqDatabase` 类型中使用，永远不要作为查询的结果类型！
// 请参见下面的 `Person`、`NewPerson` 和 `PersonUpdate` 类型。
export interface PersonTable {
  // Generated<T> 是一个工具类型，用于标记由数据库自动生成的列，例如自增 ID 或时间戳。
  // 被标记为 Generated 的列在插入（insert）和更新（update）操作中会被自动设为可选，
  // 它们的值会由数据库生成，而不是由用户提供。
  id: Generated<number>;

  first_name: string;
  gender: 'man' | 'woman' | 'other';

  // 如果数据库中的列是可空（nullable）的，那么在这里也应该将其类型设为可空。
  // 不要使用可选属性（last_name?: string），
  // Kysely 会自动根据数据库的定义来确定属性是否可选。
  last_name: string | null;

  // 可以使用 `ColumnType<SelectType, InsertType, UpdateType>`
  // 来为每种操作（查询、插入和更新）指定不同的类型。
  // 在这里，我们定义了一个 `created_at` 列：
  // - 在查询时被选为 `string` 类型；
  // - 在插入时可以可选地提供为 `string` 类型；
  // - 在更新时永远不能提供（即 `never`）。
  created_at: ColumnType<string, string | undefined, never>;

  // 可以使用 `JSONColumnType` 来声明 JSON 列。
  // 这是 `ColumnType<T, string, string>` 的简写：
  // - T 是从数据库中检索到的 JSON 对象/数组的类型；
  // - 插入和更新类型始终为 `string`，因为在插入和更新时总会序列化成字符串。
  // 这里我们定义了一个 `metadata` 列，它在查询时被 `select` 成一个对象，
  // 在插入和更新时被选为 `string` 类型（即 JSON 字符串）。
  metadata: JSONColumnType<{
    login_at: string;
    ip: string | null;
    agent: string | null;
    plan: 'free' | 'premium';
  }>;
}

// 永远不要直接使用 `PersonTable` 作为查询结果的类型；应该使用：
// - `Selectable<PersonTable>` 作为查询结果的类型；
// - `Insertable<PersonTable>` 作为插入操作的参数类型；
// - `Updateable<PersonTable>` 作为更新操作的参数类型。
// 这些工具类型会根据 `PersonTable` 中定义的列类型来正确地推断出每种操作的类型。
//
// 大多数时候你应该完全信任类型推断，而不需要使用显式的类型。
// 这些类型在为函数参数添加类型注解时可能会很有用。
export type Person = Selectable<PersonTable>;
export type NewPerson = Insertable<PersonTable>;
export type PersonUpdate = Updateable<PersonTable>;

// 使用声明合并（Declaration Merging）来扩展 `FraqDatabase` 类型，
// 以包含我们定义的 `my_plugin_person` 表。
// 一般情况下，用插件名称作为表名前缀是个不错的选择，以免与其他插件定义的表发生冲突。
declare module '@fraqjs/plugin-kysely' {
  interface FraqDatabase {
    my_plugin_person: PersonTable;
  }
}

import { sql } from 'kysely';

ctx.db.schemas.register({
  name: 'my_plugin_schema',
  migrations: {
    '001_create_person_table': {
      async up(kysely) {
        await kysely.schema
          .createTable('my_plugin_person')
          .addColumn('id', 'integer', (col) => col.primaryKey())
          .addColumn('first_name', 'text', (col) => col.notNull())
          .addColumn('last_name', 'text')
          .addColumn('gender', 'text', (col) => col.notNull())
          .addColumn('created_at', 'text', (col) =>
            col.defaultTo(sql`CURRENT_TIMESTAMP`).notNull(),
          )
          .addColumn('metadata', 'text', (col) => col.notNull())
          .execute();
      },
    },
  },
});

export interface PersonTable {
  id: Generated<number>;
  first_name: string;
  // 新增的字段应当尽量定义为可空
  nickname: string | null;
  gender: 'man' | 'woman' | 'other';
  last_name: string | null;
  created_at: ColumnType<string, string | undefined, never>;
  metadata: JSONColumnType<{
    login_at: string;
    ip: string | null;
    agent: string | null;
    plan: 'free' | 'premium';
  }>;
}

ctx.db.schemas.register({
  name: 'my_plugin_schema',
  migrations: {
    // 上面已经发布过的 001_create_person_table 迁移脚本
    '002_add_person_nickname': {
      async up(kysely) {
        await kysely.schema
          .alterTable('my_plugin_person')
          .addColumn('nickname', 'text')
          .execute();
      },
    },
  },
});

await ctx.db.kysely
  .insertInto('my_plugin_person')
  .values({
    first_name: 'Alice',
    nickname: null,
    last_name: null,
    gender: 'woman',
    metadata: JSON.stringify({
      login_at: new Date().toISOString(),
      ip: null,
      agent: null,
      plan: 'free',
    }),
  })
  .executeTakeFirst();

const person = await ctx.db.kysely
  .selectFrom('my_plugin_person')
  .select(['id', 'first_name', 'nickname', 'last_name', 'gender', 'created_at'])
  .where('first_name', '=', 'Alice')
  .executeTakeFirst();

if (person) {
  console.log(person.id, person.first_name);
}

const person = await ctx.db.kysely
  .selectFrom('my_plugin_person')
  .select(['id', 'first_name'])
  .where('id', '=', 1)
  .executeTakeFirstOrThrow();

await ctx.db.kysely
  .updateTable('my_plugin_person')
  .set({
    nickname: 'Ali',
    last_name: 'Liddell',
  })
  .where('id', '=', 1)
  .executeTakeFirst();

await ctx.db.kysely
  .deleteFrom('my_plugin_person')
  .where('id', '=', 1)
  .executeTakeFirst();

await ctx.db.kysely.transaction().execute(async (trx) => {
  const result = await trx
    .insertInto('my_plugin_person')
    .values({
      first_name: 'Bob',
      nickname: null,
      last_name: null,
      gender: 'man',
      metadata: JSON.stringify({
        login_at: new Date().toISOString(),
        ip: null,
        agent: null,
        plan: 'free',
      }),
    })
    .executeTakeFirst();

  console.log(result.insertId);
});