Writing docs

This page is the authoring guide for these docs and a showcase of every
component the viewer renders. Each example has two tabs: Result is what a
reader sees, and Markdown is what you write to get it. The two tab groups
are synced, so picking Markdown once shows the source of every example on
the page.

Every component degrades on GitHub. Block components are written as HTML
comments, which GitHub hides, so a reader there sees the same content in order,
without the chrome.

Code blocks

The first word of a fence's info string is the language. Meta may follow it:
title="…" adds a filename bar, {3,5-7} highlights those lines, and
showLineNumbers adds a gutter. Every block gets a Copy button.

import { Prorm, DataTypes } from 'ts-prorm-orm';

const db = new Prorm({ dialect: 'sqlite', storage: ':memory:' });

const User = db.define('User', {
  id:    { type: DataTypes.INTEGER(), primaryKey: true, autoIncrement: true },
  email: { type: DataTypes.STRING(255), allowNull: false, unique: true },
});

export { db, User };

```ts title="src/models/user.ts" {3,5-7} showLineNumbers
import { Prorm, DataTypes } from 'ts-prorm-orm';

const db = new Prorm({ dialect: 'sqlite', storage: ':memory:' });

const User = db.define('User', {
  id:    { type: DataTypes.INTEGER(), primaryKey: true, autoIncrement: true },
  email: { type: DataTypes.STRING(255), allowNull: false, unique: true },
});

export { db, User };
```

Line ranges count from 1 and may be listed in any order: {1}, {2-4},
{1,3,6-8}. The checker reports a range past the end of its block.

Terminal sessions

console, shell-session and sh blocks render as a terminal. A line that
starts with $ is a command and the rest is output. The prompt is drawn by
the viewer, so it can't be selected, and Copy copies only the commands.
A command ending in \ continues on the next line. An sh block with no
$ lines is treated as all commands.

$ npm install ts-prorm-orm better-sqlite3
added 3 packages in 2s
$ npx orm-cli migrate \
    --config prorm.config.json
Applied 2 migrations.

```console title="Create the schema"
$ npm install ts-prorm-orm better-sqlite3
added 3 packages in 2s
$ npx orm-cli migrate \
    --config prorm.config.json
Applied 2 migrations.
```

Use bash for a script that a reader saves to a file, not for a session they
type into a shell.

Diffs

A diff block colours + and - lines. diff-<lang> also highlights the
code as that language. There, Copy copies the new version: the context
and added lines, without the removed ones.

 const db = new Prorm({
-  dialect: 'sqlite',
-  storage: ':memory:',
+  dialect: 'postgres',
+  host: 'localhost',
+  database: 'app',
 });

```diff-ts title="src/db.ts"
 const db = new Prorm({
-  dialect: 'sqlite',
-  storage: ':memory:',
+  dialect: 'postgres',
+  host: 'localhost',
+  database: 'app',
 });
```

Start each line with +, - or a space. A plain diff block is shown as
written, so a real git diff with its @@ hunks works too.

File trees

A tree block renders a project layout. Indent two spaces per level, end a
directory with /, and put a comment after #, with a space before it.

src/
  models/
    user.ts      # the User model
    post.ts
  migrations/
    001-init.ts  # run by `orm-cli migrate`
  index.ts
prorm.config.json

```tree
src/
  models/
    user.ts      # the User model
    post.ts
  migrations/
    001-init.ts  # run by `orm-cli migrate`
  index.ts
prorm.config.json
```

Examples are type-checked

Every ts and typescript block is compiled against src/ by
scripts/check-docs-snippets.mjs. That includes blocks inside tabs, steps and
<details>, and ones with meta after the language. Use the real exported APIs
and read the source when in doubt. A block that is deliberately a fragment
takes  on the line before its fence. Use it rarely:
the test fails if more than one block in twenty is skipped.

Callouts

GitHub's alerts render natively on GitHub and as callouts here. An optional
title may follow the marker. The older style, a blockquote that starts with
Note:, Tip:, Warning:, Danger: or Deprecated:, still works.

[!NOTE]
Useful information a reader should know, even when skimming.

[!TIP] Faster startups
Keep one Prorm instance per process; its pool is the expensive part.

[!IMPORTANT]
Key information a reader needs to succeed.

[!WARNING]
sync({ force: true }) drops the table first.

[!CAUTION]
This deletes production data and can't be undone.

Deprecated: the query option of createMaterializedView(). Pass definition instead.

> [!NOTE]
> Useful information a reader should know, even when skimming.

> [!TIP] Faster startups
> Keep one `Prorm` instance per process; its pool is the expensive part.

> [!IMPORTANT]
> Key information a reader needs to succeed.

> [!WARNING]
> `sync({ force: true })` drops the table first.

> [!CAUTION]
> This deletes production data and can't be undone.

> **Deprecated:** the `query` option of `createMaterializedView()`. Pass `definition` instead.

Tabs

Tabs hold alternatives: one example per dialect or per package manager, or
code in one tab and an explanation in another. A tab can hold any Markdown.

import { Prorm } from 'ts-prorm-orm';

const db = new Prorm({ dialect: 'postgres', host: 'localhost', database: 'app', username: 'app' });

import { Prorm } from 'ts-prorm-orm';

const db = new Prorm({ dialect: 'mysql', host: 'localhost', database: 'app', username: 'app' });

SQLite needs no server; a file path is the whole configuration.

import { Prorm } from 'ts-prorm-orm';

const db = new Prorm({ dialect: 'sqlite', storage: 'app.db' });

<!-- tabs -->
<!-- tab: PostgreSQL -->
```ts
import { Prorm } from 'ts-prorm-orm';

const db = new Prorm({ dialect: 'postgres', host: 'localhost', database: 'app', username: 'app' });
```
<!-- tab: MySQL -->
```ts
import { Prorm } from 'ts-prorm-orm';

const db = new Prorm({ dialect: 'mysql', host: 'localhost', database: 'app', username: 'app' });
```
<!-- tab: SQLite -->
SQLite needs no server; a file path is the whole configuration.

```ts
import { Prorm } from 'ts-prorm-orm';

const db = new Prorm({ dialect: 'sqlite', storage: 'app.db' });
```
<!-- /tabs -->

Synced tabs

Tab groups switch together across the page, and the reader's choice is
remembered on their next visit. Groups sync when they share a label: choose
SQLite in the group above and this one follows, and so does every other
page that uses the same labels.

PostgreSQL listens on port 5432 unless you set port.

MySQL listens on port 3306 unless you set port.

SQLite has no port: storage is a file path, or ':memory:'.

To sync only a particular set of groups, give them a name with
. Named groups sync only with groups of the same
name, so a package-manager choice doesn't switch anything else.

$ npm install ts-prorm-orm

$ pnpm add ts-prorm-orm

$ yarn add ts-prorm-orm

$ bun add ts-prorm-orm

Tabs are keyboard accessible. Tab moves to the selected tab,
← and → move between tabs, and Home and
End jump to the first and last. On GitHub, the panels show one after
another, so start each panel with something that says which one it is when
the tab label alone wouldn't.

Steps

Use steps for a procedure. Each ### heading inside becomes a numbered step on
a vertical line, and the headings still appear in the page's table of
contents. Steps can hold anything, including tabs and code.

Install the package

$ npm install ts-prorm-orm better-sqlite3

Connect

import { Prorm } from 'ts-prorm-orm';

const db = new Prorm({ dialect: 'sqlite', storage: ':memory:' });
await db.connect();

Define a model and create its table

import { Prorm, DataTypes } from 'ts-prorm-orm';

const db = new Prorm({ dialect: 'sqlite', storage: ':memory:' });
const User = db.define('User', {
  id:   { type: DataTypes.INTEGER(), primaryKey: true, autoIncrement: true },
  name: { type: DataTypes.STRING(100), allowNull: false },
});
await db.sync();

<!-- steps -->
### Install the package

```console
$ npm install ts-prorm-orm better-sqlite3
```

### Connect

```ts
import { Prorm } from 'ts-prorm-orm';

const db = new Prorm({ dialect: 'sqlite', storage: ':memory:' });
await db.connect();
```

### Define a model and create its table

```ts
…
```
<!-- /steps -->

Cards

Cards are a grid of links, for an overview or a "where next" section. Each list
item is a Markdown link, then an em dash and a one-line description. A leading {icon:name} adds an icon.
The available icons are database, code, book, rocket, shield,
lock, key, terminal, gear, bolt, search, layers, cloud,
chart, plug, users, file, diagram, check and globe. An unknown
icon name is ignored.

{icon:database} Models — Define tables as classes.

{icon:search} Querying — Filter, sort and paginate.

{icon:layers} Migrations — Change the schema safely.

<!-- cards -->
- {icon:database} [Models](models.md) — Define tables as classes.
- {icon:search} [Querying](querying.md) — Filter, sort and paginate.
- {icon:layers} [Migrations](migrations.md) — Change the schema safely.
<!-- /cards -->

Collapsible sections

Use the native <details> element for material most readers can skip. Leave a
blank line after <summary> so the content inside is read as Markdown, and a
blank line after </details> before whatever follows it: until a blank line,
Markdown treats the lines after an HTML tag as more HTML.

Why is the pool per process?

Each Prorm instance owns its connection pool. Two instances against the same
database hold two pools, which doubles the connections the server has to
keep open.

<details>
<summary>Why is the pool per process?</summary>

Each `Prorm` instance owns its connection pool. Two instances against the same
database hold two pools, which doubles the connections the server has to
keep open.

</details>

Badges and keys

A  line directly after a heading puts a small badge on that
heading. A version such as v4.9 is blue, and deprecated and experimental
get their own colours. Write keys with <kbd>.

Streaming reads

The `query` option

Press Ctrl + K to search.

#### Streaming reads
<!-- badge: v4.9 -->
<!-- badge: experimental -->

#### The `query` option
<!-- badge: deprecated -->

Press <kbd>Ctrl</kbd> + <kbd>K</kbd> to search.

Diagrams

Use a fenced mermaid block. Prefer flowchart, sequenceDiagram,
stateDiagram-v2, erDiagram, classDiagram, gantt and pie. Quote a
label that contains punctuation, such as A["text (x)"]. Labels can't contain
HTML.

```mermaid
flowchart LR
  A["Model.findAll()"] --> B["Query builder"]
  B --> C{"Dialect"}
  C -->|postgres| D["SQL + RETURNING"]
  C -->|sqlite| E["SQL"]
```

API reference tables

Use ordinary GFM tables. The viewer styles them, and a wide table scrolls
inside its own box. Put option and parameter names in code spans.

Option	Type	Default	Meaning
`dialect`	`string`	(required)	Which database to talk to.
`storage`	`string`	—	SQLite only: a file path, or `':memory:'`.
`pool.max`	`number`	`10`	The most connections the pool opens.

Checking your page

Run the checks before you open a merge request. The link checker also lints
the components on this page: it reports an unclosed , a
 without its colon, a badge that doesn't follow a heading, a
card that isn't a link, an unknown alert type, and a highlighted line past the
end of its block.

$ node scripts/check-docs-links.mjs
$ node scripts/check-docs-snippets.mjs docs/guides/writing-docs.md

Rules

Every ts example must compile against src/. Use the real exported
APIs, and read the source when in doubt.

Don't edit generated content: docs/guides/klock-errors.md, and any
table marked .

Teach with every addition. Use runnable, realistic examples, dialect tabs
where behaviour differs, and diagrams where there's a flow, state or
relationship to show. Use steps for procedures, cards for overviews, and tree
blocks for project layouts.

Code blocks#

Terminal sessions#

Diffs#

File trees#

Examples are type-checked#

Callouts#

Tabs#

Synced tabs#

Steps#

Install the package#

Connect#

Define a model and create its table#

Cards#

Collapsible sections#

Badges and keys#

Streaming reads#

The query option#

Diagrams#

API reference tables#

Checking your page#

Rules#