chore: readme

README.md

@@ -6,37 +6,111 @@
 
 ```bash
 npm i --save-dev kysely-migrate
+pnpm add -D kysely-migrate
+yarn add -D kysely-migrate
+bun add -D kysely-migrate
 ```
 
 ## Usage
 
+Create a `kysely-migrate.config.ts` file and fill it out:
+
+```ts
+// kysely-migrate.config.ts
+import { Kysely, MysqlDialect } from 'kysely'
+import { defineConfig } from 'kysely-migrate'
+import { createPool } from 'mysql2'
+
+export default defineConfig({
+  db: new Kysely({
+    dialect: new MysqlDialect({ pool: createPool('mysql://') }),
+  }),
+  migrationFolder: 'src/db/migrations',
+  codegen: { dialect: 'mysql', out: 'src/db/types.ts' },
+})
+```
+
+Run [commands](#commands) to manage migrations and generate types.
+
 ```bash
 kysely-migrate <command> [options]
 ```
 
-## Docs
+## API
 
-Run `kysely-migrate --help` (output below) or `kysely-migrate <command> --help` to see the list of available commands and options.
+### Commands
 
-```bash
-Usage:
-  $ kysely-migrate <command> [options]
-
-Commands:
-  codegen  generate types from database metadata
-  create   create new migration
-  down     migrate one step down
-  init     create configuration file
-  list     list migrations
-  to       migrate to selected migration
-  up       migrate one step up
-
-For more info, run any command with the `--help` flag:
-  $ kysely-migrate create --help
-
-Options:
-  -h, --help     Display this message 
-  -v, --version  Display version number 
+Run `kysely-migrate --help` or `kysely-migrate <command> --help` to see the list of available commands, options, and examples.
+
+- `codegen` generate types from database metadata
+- `create` create new migration
+- `down` migrate one step down
+- `init` create configuration file
+- `list` list migrations
+- `to` migrate to selected migration
+- `up` migrate one step up
+
+### defineConfig
+
+Creates [`Config`](#config) object.
+
+| Name    | Type                                       | Description                                                           |
+| ------- | ------------------------------------------ | --------------------------------------------------------------------- |
+| `config` | `Config \| (() => Config \| Promise<Config>)` | Configuration object or a function that returns a configuration object. |
+| returns | [`Config`](#config)                          | Configuration object.                                                  |
+
+### loadEnv
+
+Loads environment variables from `.env` or `.env.*` files.
+
+| Name           | Type                      | Description                                 |
+| -------------- | ------------------------- | ------------------------------------------- |
+| `config.mode`   | `string \| undefined`      | `.env` file type (e.g. `` `.env.${mode}` ``) |
+| `config.envDir` | `string \| undefined`      | Directory to load `.env` file from           |
+| returns        | `Record<string, string>`  | Parsed environment variables.               |
+
+### Config
+
+`Config` object.
+
+```ts
+{
+  /** Kysely instance used to manipulate migrations and introspect database */
+  db: Kysely<any>
+  /** Path to migrations directory */
+  migrationFolder: string
+
+  /** `kysely-migrate codegen` options */
+  codegen?:
+    | {
+        /** Custom definition mappings for database types to TypeScript types */
+        definitions?: Definitions | undefined
+        /** Dialect definitions to inherit */
+        dialect?: 'mysql' | 'postgres' | 'sqlite' | undefined
+        /** Output file path */
+        out: string
+      }
+    | undefined
+
+  /** Used for internal `FileMigrationProvider` instance. Defaults to `node:fs/promises`. */
+  fs?: FileMigrationProviderFS | undefined
+  /** Used for internal `FileMigrationProvider` instance. Defaults to `node:path`. */
+  path?: FileMigrationProviderPath | undefined
+  /** Defaults to internal `migrator` created with `db` and `migrationFolder`. */
+  migrator?: Migrator | undefined
+}
+```
+
+### Dialect Definitions
+
+Dialect definition files map database types to TypeScript types. They are used by the codegen command to generate types from database metadata. The following dialect definitions are available:
+
+```ts
+import {
+  mysqlDefinitions,
+  postgresDefinitions,
+  sqliteDefinitions,
+} from 'kysely-migrate'
 ```
 
 ## Sponsors

src/cli.ts

@@ -33,6 +33,7 @@ cli
   .option('-R, --reset', '[boolean] reset all migrations')
   .option('-r, --root <path>', '[string] root path to resolve config from')
   .example((name) => `${name} down`)
+  .example((name) => `${name} down --reset`)
   .action(async (options: DownOptions) => await down(options))
 
 cli
@@ -55,6 +56,7 @@ cli
   .option('-n, --name <name>', '[string] migration name')
   .option('-r, --root <path>', '[string] root path to resolve config from')
   .example((name) => `${name} to`)
+  .example((name) => `${name} to --name 0001_every_mangos_carry`)
   .action(async (options: ToOptions) => await to(options))
 
 cli
@@ -63,6 +65,7 @@ cli
   .option('-l, --latest', '[boolean] apply all pending migrations')
   .option('-r, --root <path>', '[string] root path to resolve config from')
   .example((name) => `${name} up`)
+  .example((name) => `${name} up --latest`)
   .action(async (options: UpOptions) => await up(options))
 
 cli.help()

src/config.ts

@@ -8,20 +8,14 @@ import {
 import { type CliOptions } from 'kysely-codegen'
 import { type Definitions } from './utils/codegen/types.js'
 
-export type Config =
-  | {
-      codegen?: Evaluate<Codegen> | undefined
-      db: Kysely<any>
-      fs?: FileMigrationProviderFS | undefined
-      path?: FileMigrationProviderPath | undefined
-      migrationFolder: string
-    }
-  | {
-      codegen?: Evaluate<Codegen> | undefined
-      db?: Kysely<any> | undefined
-      migrationFolder: string
-      migrator: Migrator
-    }
+export type Config = {
+  codegen?: Evaluate<Codegen> | undefined
+  db: Kysely<any>
+  fs?: FileMigrationProviderFS | undefined
+  path?: FileMigrationProviderPath | undefined
+  migrationFolder: string
+  migrator?: Migrator | undefined
+}
 
 type Codegen =
   | {

src/utils/getMigrator.ts

@@ -5,7 +5,7 @@ import { FileMigrationProvider, Migrator } from 'kysely'
 import { type Config } from '../config.js'
 
 export function getMigrator(config: Config) {
-  if ('migrator' in config) return config.migrator
+  if ('migrator' in config && config.migrator) return config.migrator
 
   const { db, fs = nodeFs, path = nodePath } = config
   const migrationFolder = nodePath.resolve(config.migrationFolder)

src/utils/loadEnv.ts

@@ -6,8 +6,8 @@ import { expand } from 'dotenv-expand'
 // https://github.com/vitejs/vite/blob/main/packages/vite/src/node/env.ts#L7
 export function loadEnv(
   config: {
-    mode?: string
-    envDir?: string
+    mode?: string | undefined
+    envDir?: string | undefined
   } = {},
 ): Record<string, string> {
   const mode = config.mode