chore: more docs

packages/migrator/readme.md

@@ -13,6 +13,15 @@ By default, the migration scripts it runs are plain `.sql` files. No learning th
 
 It can also run `.js` or `.ts` files - these are expected to be modules with a require `up` export, and an optional `down` export. Each of these functions will have an object passed to them with a `slonik` instance, and a `sql` tag function. However, where possible, it's often preferable to keep it simple and stick to SQL.
 
+<details>
+  <summary>running typescript migrations</summary>
+
+  Note: if writing migrations in typescript, you will likely want to use a tool like [ts-node](https://npmjs.com/package/ts-node) to enable loading typescript modules. You can either add `require('ts-node/register/transpile-only')` at the top of your `migrate.js` file, or run `node -r ts-node/register/transpile-only migrate ...` instead of `node migrate ...`.
+
+  (In general, using `ts-node/register/transpile-only` is preferable over `ts-node/register` - type-checking is best left to a separate process)
+
+</details>
+
 This isn't technically a cli - it's a cli _helper_. Most node migration libraries are command-line utilities, which require a separate `database.json` or `config.json` file where you have to hard-code in your connection credentials. This library uses a different approach - it exposes a javascript function which you pass a slonik instance into. The javascript file you make that call in then becomes a runnable migration CLI. The migrations can be invoked programmatically from the same config.
 
 ## Usage
@@ -47,7 +56,7 @@ This generates placeholder migration sql scripts in the directory specified by `
 
 You can now edit the generated sql files to `create table users(name text)` for the 'up' migration and `drop table users` for the 'down' migration.
 
-Note: `node migrate create xyz` will try to detect the type of pre-existing migrations. The extension of the file generated will be `.sql`, `.js` or `.ts` to match the last migration found in the target directory.
+Note: `node migrate create xyz` will try to detect the type of pre-existing migrations. The extension of the file generated will be `.sql`, `.js` or `.ts` to match the last migration found in the target directory, default to `.sql` if none is found. You can override this behaviour by explicitly providing an extension, e.g. `node migrate create xyz.js`.
 
 ```bash
 node migrate up