@typesql/kysely 0.2.0 → 0.2.1

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # @typesql/kysely
 
+## 0.2.1
+
+### Patch Changes
+
+- The README is shorter: install, one example and links to the docs site, which now has the details it used to repeat.
+
+- Updated dependencies:
+  - @typesql/core@0.6.0
+
 ## 0.2.0
 
 ### Minor Changes

package/README.md

@@ -1,209 +1,52 @@
 # @typesql/kysely
 
-Use the `DB` interface you already have for [Kysely](https://kysely.dev) as a TypeSQL schema:
-the one generated by [kysely-codegen](https://github.com/RobinBlomberg/kysely-codegen), by
-[prisma-kysely](https://github.com/valtyr/prisma-kysely), or written by hand. The conversion is
-type-level only; nothing is generated and no database is contacted.
+Write [TypeSQL](https://www.npmjs.com/package/@typesql/core) queries against the `DB` interface you already have for [Kysely](https://kysely.dev), and run them on your Kysely instance. The interface can come from [kysely-codegen](https://github.com/RobinBlomberg/kysely-codegen), [prisma-kysely](https://github.com/valtyr/prisma-kysely), or be written by hand.
+
+## Install
 
 ```sh
-pnpm add @typesql/core @typesql/kysely kysely
+npm install @typesql/core @typesql/kysely kysely
 ```
 
-[Open an example in the TypeScript Playground](https://www.typescriptlang.org/play/#code/PTAEBUE8AcFMGUCKAZUB3AlgFwBagNKQDOsANpKABQACWMsRAjqcANbFmQCUAdKAJoB7AK4AnAh3KgAIgCFQGAHZZYogGYBDAMawq7EuQC0WwQBNYAc1iLQIrNGFZbogFAhQODYtOG0o7CqKXApEoLi6RFo4sAC2GgA0oF6moKIaaKBIqKLCiqGCNpAi4oQGFEpEWF46fAASggBuqmHRqQzCpFhEPC4uGDHQgqJOAN6gWqKwGirwzKAAvqBqooIxoABEtPRMLPqc6wDcfQNDoy4AkHRwoADCgqTCMYpQcPEXV7oA4taq07Cmb3OpU4gIACoJKhZJkRpBgNKRYFosG9FstVhs9uRDsdBsNQGNwfcFksVmt1tALNi3GBMZBjGZLNZbI4HMiwv4YjF-i4PqAAJLKAAcoAAvLd7o9nvQADwXSr+RQWQEAIwwFiUTgAPqBFI9lc1tfKlEqLqr1cpQNrdTF9eJDVgFRYXAA+I688D9BhVAai8UPJ4vWDS6R-RIhlSW0BGxVhv6R6MWV08+igACygjMvvWnmg0Eg60j6yIGlMVI1qk0Ohk8hGF2EJFERAAXPiLucMKYW99FL8VKZpdbbUnzudYhoMKQWwmjiOYhnO2n55HdaRSDPzhMpn2APrTLs-NJ96UermVDQDYfzGeDSrN1sjjv7nuH-7SgVYQXD84aRw4Ibbx8dT1VR1ywbAESnB1jXXBxlVIDAiGiBdu17V9lQzBEvEvI55l6Ew8icUxlV9HsMmBchg1kZ1KFrc5TDhBEkRbUjQHBSFoVheFESwGjQEGe5mNgDJCVIShgnmLgUS4I58MqKM5jFTc-lmUhKOoojpN6dxwFaRhhFUChlWECdzHENQhnQTwnGwUBTEEBh0DIUhEiyJYLPCNpKkSKJEVYf4kgsccCJaCJz10Ko4IYHpZMItI1C6X10nHQjlQuHgDG4gAxUlKHJCEunWLg0oypFKAAbXWDt1kSdYwKwBF1gAXSK84eDQaJJly2D4MQ-5qo2EV+s0UgSBanhYAAD0RRxYDEo4XBi0BMNM9CNFEFIxR2SgLgAA3gABRZB9pucBQGEca4gnRJzrnMxvJEZRKGgHgO2CABBeA+Pyog3lAP7-oBwGgeB-60kUVgxNAAB5AA1faACUqCh+HpAR0BZH4cYHp457Xpkfb4Bud7PugUhtFgFwQap4HMvhqHUzOhtQmEUAjsy06ACkob5AA5L7bz46G+een9cH-DtfXOiW3p56Q+J4bqEKQynqdVv6AHVagR-azp4W6NtAAASABGFW1epz46YAVVBdHMal0wdsBbMNFzfM3k0xawb8g2kps5bVFW9bxqmrQZrm6kAYAPQAfi0sABSIDtdA0CQynZLxiyRDACkSVVvCSeTSDCQQFCcLBS5iDAJtAIyTOaZJMhQUA9NUDAopcP2Up4B1M+0MCCjEkPppUSgNCISBFC0KgHQm4IRWde8u-ZCa2x4YRoFMP5wA0SKuu+wq15IHixkV3qFwdfSFha1r2tUWb1lFv9RAA0sasGxJjZv4ew9HzTvzQMlcYkxlLMDUpQWeXBtojh2qjI64Ada03pvzBKmttZJF-OLA2JtQAyzljzKGp0z5ISdm2Y2gJeCTRHrNTSEl5pbT2odY6p0JZIIZvWVQoQ0Hwx1vrX0JsnYbC8FCfM0lQDuFUCsUQzFBBOFTg0eEV9BBqBCqAPh1hHguCAA) <!-- playground:kysely --> to hover the types and edit the SQL, with nothing to install.
+## Usage
 
 ```ts
 import { createSql } from "@typesql/kysely";
-import type { DB } from "./db"; // kysely-codegen output
+import type { DB } from "./db"; // the interface you pass to new Kysely<DB>()
 
-const sql = createSql<DB>(db); // db: your Kysely<DB> instance, or a Transaction<DB>
+const sql = createSql<DB>(db); // db: your Kysely<DB> instance, or a transaction
 
-const q = sql(
-  `SELECT u.id, u.email, p.title, p.views
-     FROM users u JOIN posts p ON p.author_id = u.id
-    WHERE u.id = $1 AND p.published = $2`,
-  1, true,
-);
-//    ^? Query<{ id: number; email: string; title: string; views: string }, [number | null, boolean | null]>
-
-const rows = await q.execute();
+const posts = await sql(
+  `SELECT u.email, p.title
+   FROM users u JOIN posts p ON p.author_id = u.id
+   WHERE u.id = $1`,
+  1,
+).execute();
+// { email: string; title: string }[]
 
 await sql.transaction(async (tx) => {
   await tx("UPDATE posts SET published = true WHERE author_id = $1", 1).execute();
 });
 ```
 
-## API
-
-| Export | What it is |
-|---|---|
-| `createSql<DB, TM = DefaultTypeMap, Overrides = {}, Options = {}>(db, options?)` | core's `createSql<FromKysely<DB, Overrides, Options>, TM>()` with the queries running on `db`; `{ rowKeys: "camelCase" }` gives `CamelCasePlugin`-style row keys |
-| `q.execute()`, `q.executeTakeFirst()`, `q.executeTakeFirstOrThrow()`, `q.executeCount()` | `Promise<Row[]>`, `Promise<Row \| undefined>`, `Promise<Row>` (`NoResultError` on 0 rows), `Promise<number>` (`numAffectedRows`; for other statements the number of rows returned, 0 for DDL) |
-| `sql.transaction(fn)` | `db.transaction().execute(...)` with `tx` bound to the transaction; on a `Transaction`, and for `tx.transaction(fn)`, a savepoint |
-| `FromKysely<DB, Overrides = {}, Options = {}>` | the converted schema type, for use with core's `createSql<Schema, TM>()` or the adapters' `createSql<Schema>(client)` |
-| `KyselySql<DB, TM, Overrides, Options, Keys>` | the type `createSql` returns |
-| `executor(db)` | an `Executor` for `q.execute(executor)` and core's `createSql(executor)`, also bypassing plugins |
-| `InferColumn<T>` | the descriptor inferred for one Kysely column type (handy to check a mapping) |
-| `SnakeCase<S>` | `CamelCasePlugin`'s default camelCase → snake_case mapping, at the type level |
-| `KyselyOverrides`, `TableOverride`, `ColumnOverride`, `KyselyOptions`, `KyselyExecutor` | parameter types |
-
-`TM` is the type map for the driver Kysely runs on. Kysely's `PostgresDialect` uses `pg`, so
-`PgTypeMap` from `@typesql/pg` is the exact choice (`Buffer` for `bytea`, interval methods); core's
-`DefaultTypeMap` already matches `pg` otherwise:
-
-```ts
-import type { PgTypeMap } from "@typesql/pg";
-import { createSql, type FromKysely } from "@typesql/kysely";
-import { createSql as createCoreSql } from "@typesql/core";
-
-const sql = createSql<DB, PgTypeMap>(db);
-const same = createCoreSql<FromKysely<DB>, PgTypeMap>(); // types only, no client
-```
-
-Queries are sent as `CompiledQuery.raw(q.text, q.values)` through
-`db.withoutPlugins().executeQuery(...)`. Plugins are bypassed on purpose: TypeSQL's row types
-describe what Postgres returns (`created_at`), and a result transformer such as
-`CamelCasePlugin` would rename the keys (use `{ rowKeys: "camelCase" }` for camelCase rows).
-Logging, the dialect and the connection pool are unaffected. Inside a Kysely transaction,
-`createSql<DB>(trx)` binds a `sql` to it, so builder and SQL queries share the transaction.
-
-## How columns are converted
-
-Kysely describes a column by its TS type; TypeSQL needs a Postgres type name. The TS shape
-is read back as follows (for `ColumnType<S, I, U>` the select type `S` decides, the insert type
-`I` breaks ties):
-
-| Kysely column type | Postgres type | Notes |
-|---|---|---|
-| `number` | `int4` | also what codegen emits for `int2`, `float4`, `float8`, `oid`: override those |
-| `string` | `text` | also `varchar`, `uuid`, `time`, `money`, `inet`, …: override if it matters |
-| `boolean` | `bool` | |
-| `bigint` | `int8` | |
-| `Date` | `timestamptz` | |
-| `Buffer` / `Uint8Array` | `bytea` | |
-| `Int8` = `ColumnType<string, bigint \| number \| string, …>` | `int8` | `bigint` in the insert type |
-| `Numeric` = `ColumnType<string, number \| string, …>` | `numeric` | `number` in the insert type |
-| `Timestamp` = `ColumnType<Date, Date \| string, …>` | `timestamptz` | codegen uses `Timestamp` for `date`, `timestamp` and `timestamptz` alike |
-| `Interval` (an object with `days`) | `interval` | |
-| `Point` (`{ x, y }`) / `Circle` (`{ x, y, radius }`) | `point` / `circle` | |
-| `Json` / `JsonValue`, `unknown`, `JSONColumnType<T>`, any other object | `jsonb` | always nullable (see below) |
-| `T[]`, `ArrayType<T>` | element type + `[]` | `number[][]` is `int4[]` too |
-| `"a" \| "b"` (string-literal union, codegen enums, prisma-kysely enums, TS string enums) | an enum | registered in `$types`, see [Enums](#enums) |
-| `T \| null` | nullable | |
-| `Generated<T>` (kysely's or codegen's), `GeneratedAlways<T>` | has a default | optional in `INSERT`; `GeneratedAlways<Int8>` stays `int8` |
-| `"auth.users"` key | `Schema["auth"]["users"]` | query it as `auth.users` |
-| `"public.users"` key | `Schema["users"]` | |
-
-Rows then come out through the type map, so `int8` and `numeric` columns are `string`, as
-kysely-codegen declares them and as `pg` returns them.
-
-## Overrides
-
-The mapping is a best guess. The third type argument (`Overrides`) pins the exact Postgres type of any
-column, keyed by the table key and the column key as they appear in your `DB` interface:
-
-```ts
-const sql = createSql<DB, DefaultTypeMap, {
-  users: {
-    id: "int8";                                    // just a type name: nullability and default are kept
-    score: "float8";
-    birthday: "date";
-    created_at: { type: "timestamp"; hasDefault: true }; // or a partial descriptor
-  };
-  "auth.users": { id: "uuid" };
-  active_users: { $view: true };                   // a view: INSERT/UPDATE/DELETE are rejected
-  $types: { mood: Mood; "auth.role": AuthRole };   // enum names, see below
-}>(db);
-```
-
-A descriptor may set any of `type`, `nullable` and `hasDefault`; the others stay inferred.
-Declare the overrides with a `type` alias or inline, not an `interface` (an interface has no
-index signature, so it does not satisfy the `KyselyOverrides` constraint).
-
-Worth overriding:
-
-- `float4`/`float8` columns (inferred `int4`): `score / 2` is integer division for `int4`, and
-  `sum`/`avg` result types differ.
-- `date` and `timestamp` columns (inferred `timestamptz`): `date - date` is an `int4` number of
-  days, `timestamptz - date` an `interval`.
-- `uuid`, `varchar`, `time`, `inet`… (inferred `text`): row and parameter types are `string`
-  either way; override when you use functions or operators that exist for that type only.
-- `json` columns (inferred `jsonb`).
-
-## Enums
+[Open an example in the TypeScript Playground](https://www.typescriptlang.org/play/#code/PTAEBUE8AcFMGUCKAZUB3AlgFwBagNKQDOsANpKABQACWMsRAjqcANbFmQCUAdKAJoB7AK4AnAh3KgAIgCFQGAHZZYogGYBDAMawq7EuQC0WwQBNYAc1iLQIrNGFZbogFAhQODYtOG0o7CqKXApEoLi6RFo4sAC2GgA0oF6moKIaaKBIqKLCiqGCNpAi4oQGFEpEWF46fAASggBuqmHRqQzCpFhEPC4uGDHQgqJOAN6gWqKwGirwzKAAvqBqooIxoABEtPRMLPqc6wDcfQNDoy4AkHRwoADCgqTCMYpQcPEXV7oA4taq07Cmb3OpU4gIACoJKhZJkRpBgNKRYFosG9FstVhs9uRDsdBsNQGNwfcFksVmt1tALNi3GBMZBjGZLNZbI4HMiwv4YjF-i4PqAAJLKAAcoAAvLd7o9nvQADwXSr+RQWQEAIwwFiUTgAPqBFI9lc1tfKlEqLqr1cpQNrdTF9eJDVgFRYXAA+I688D9BhVAai8UPJ4vWDS6R-RIhlSW0BGxVhv6R6MWV08+igACygjMvvWnmg0Eg60j6yIGlMVI1qk0Ohk8hGF2EJFERAAXPiLucMKYW99FL8VKZpdbbUnzudYhoMKQWwmjiOYhnO2n55HdaRSDPzhMpn2APrTLs-NJ96UermVDQDYfzGeDSrN1sjjv7nuH-7SgVYQXD84aRw4Ibbx8dT1VR1ywbAESnB1jXXBxlVIDAiGiBdu17V9lQzBEvEvI55l6Ew8icUxlV9HsMmBchg1kZ1KFrc5TDhBEkRbUjQHBSFoVheFESwGjQEGe5mNgDJCVIShgnmLgUS4I58MqKM5jFTc-lmUhKOoojpN6dxwFaRhhFUChlWECdzHENQhnQTwnGwUBTEEBh0DIUhEiyJYLPCNpKkSKJEVYf4kgsccCJaCJz10Ko4IYHpZMItI1C6X10nHQjlQuHgDG4gAxUlKHJCEunWLg0oypFKAAbXWDt1kSdYwKwBF1gAXSK84eDQaJJly2D4MQ-5qo2EV+s0UgSBanhYAAD0RRxYDEo4XBi0BMNM9CNFEFIxR2SgLgAA3gABRZB9pucBQGEca4gnRJzrnMxvJEZRKGgHgO2CABBeA+Pyog3lAP7-oBwGgeB-60kUVgxNAAB5AA1faACUqCh+HpAR0BZH4cYHp457Xpkfb4Bud7PugUhtFgFwQap4HMvhqHUzOhtQmEUAjsy06ACkob5AA5L7bz46G+een9cH-DtfXOiW3p56Q+J4bqEKQynqdVv6AHVagR-azp4W6NtAAASABGFW1epz46YAVVBdHMal0wdsBbMNFzfM3k0xawb8g2kps5bVFW9bxqmrQZrm6kAYAPQAfi0sABSIDtdA0CQynZLxiyRDACkSVVvCSeTSDCQQFCcLBS5iDAJtAIyTOaZJMhQUA9NUDAopcP2Up4B1M+0MCCjEkPppUSgNCISBFC0KgHQm4IRWde8u-ZCa2x4YRoFMP5wA0SKuu+wq15IHixkV3qFwdfSFha1r2tUWb1lFv9RAA0sasGxJjZv4ew9HzTvzQMlcYkxlLMDUpQWeXBtojh2qjI64Ada03pvzBKmttZJF-OLA2JtQAyzljzKGp0z5ISdm2Y2gJeCTRHrNTSEl5pbT2odY6p0JZIIZvWVQoQ0Hwx1vrX0JsnYbC8FCfM0lQDuFUCsUQzFBBOFTg0eEV9BBqBCqAPh1hHguCAA) <!-- playground:kysely --> to hover the types and edit the SQL, with nothing to install.
 
-A column whose type is a union of string literals becomes an enum column. Its values go into the
-schema's `$types`, so rows and parameters have the literal union (`"happy" | "sad"`), and a
-string literal in SQL is accepted where Postgres accepts it.
+## Pin column types
 
-Kysely types do not carry the enum's Postgres name, so by default each column gets its own name,
-`table.column` (`users.mood`, `auth.users.role`). That is enough for reading and filtering, but
-two columns of the same enum are then different types: `SELECT mood FROM users UNION SELECT mood
-FROM posts` is rejected, like it would be for two distinct Postgres enums. Name your enums once
-under `$types` and every column whose values are **exactly** that union gets the name:
+Kysely describes columns with TypeScript types, so TypeSQL guesses the Postgres type: `number` is `int4`, `string` is `text`, `Date` is `timestamptz`. Rows come out right either way, but division, aggregates and date arithmetic can differ. Pin the columns where it matters:
 
 ```ts
-import type { Mood, AuthRole } from "./db"; // kysely-codegen exports one alias per enum
+import type { DefaultTypeMap } from "@typesql/core";
 
-createSql<DB, DefaultTypeMap, { $types: { mood: Mood; "auth.role": AuthRole } }>(db);
+const sql = createSql<DB, DefaultTypeMap, { posts: { score: "float8" } }>(db);
 ```
 
-If two `$types` entries have the same values the column keeps its derived name; set the column's
-type explicitly (`{ users: { mood: "mood" } }`). A column override with a non-builtin name also
-registers the column's union under that name; an override with a built-in name (`"text"`) drops
-the union.
-
-## camelCase
+For an interface generated with `kysely-codegen --camel-case`, pass `{ camelCase: true }` as the fourth type argument.
 
-If the interface was generated with `kysely-codegen --camel-case` (and the app uses
-`CamelCasePlugin`), pass `{ camelCase: true }` as the options. Table and column keys are mapped
-back to the database's snake_case names the way `CamelCasePlugin` does by default (`createdAt` →
-`created_at`, `userID` → `user_id`), so the SQL you write and the rows you get use the real names:
+## Documentation
 
-```ts
-const sql = createSql<DB, DefaultTypeMap, {}, { camelCase: true }>(db);
-const q = sql("SELECT author_id, created_at FROM blog_posts WHERE id = $1", 1);
-//    ^? Query<{ author_id: number; created_at: Date }, [number | null]>
-```
-
-Overrides still use the interface's (camelCase) keys. The plugin's non-default options
-(`upperCase`, `underscoreBeforeDigits`, `underscoreBetweenUppercaseLetters`) are not modelled.
+See [From Kysely, Drizzle or Prisma](https://typesql.karsli.net/guide/orms#kysely) for how columns are converted, overrides, enums and camelCase, and [Limits](https://typesql.karsli.net/guide/limits#orm-schemas) for what the conversion can't tell.
 
-For camelCase **rows**, add `{ rowKeys: "camelCase" }`. The top-level keys are renamed with
-`CamelCasePlugin`'s default snake_case → camelCase mapping, in the row types and at runtime.
-The plugin itself stays bypassed, so keys inside JSON values are left alone:
-
-```ts
-const sql = createSql<DB, DefaultTypeMap, {}, { camelCase: true }>(db, { rowKeys: "camelCase" });
-const post = await sql("SELECT author_id, created_at FROM blog_posts WHERE id = $1", 1).executeTakeFirstOrThrow();
-//    ^? { authorId: number; createdAt: Date }
-```
+## License
 
-## Limitations
-
-- **The TS → Postgres mapping is lossy.** `number`, `string` and `Date` each stand for several
-  Postgres types; see [Overrides](#overrides). Row types are still right for the inferred type
-  (a `float8` inferred as `int4` is `number` either way); the difference shows in expression
-  typing (division, aggregates, operators that exist for one type only).
-- **JSON columns are always nullable.** kysely-codegen's `JsonValue` (and prisma-kysely's
-  `unknown`) include `null`, so `Json` and `Json | null` cannot be told apart. The row type is
-  `unknown` either way; only `INSERT` stops requiring the column. Override with
-  `{ nullable: false }` to get the not-null check back.
-- **JSON shapes are not kept.** `JSONColumnType<{ a: number }>` becomes `jsonb`, read as
-  `unknown` (the type map decides; TypeSQL has no per-column TS types).
-- **Views look like tables.** Kysely interfaces do not mark views; mark them with `$view: true`
-  to have writes rejected.
-- **Defaults come from `Generated`/`GeneratedAlways` only.** A column with a default that the
-  interface declares as a plain type is required in `INSERT`; override `{ hasDefault: true }`.
-- kysely-codegen options that change the select types (`--date-parser string`,
-  `--numeric-parser number`, …) change the inference accordingly (e.g. dates as `string` become
-  `text`): override the affected columns.
-- Domains, ranges, `tsvector`, network and geometric types other than `point`/`circle` are
-  emitted by codegen as `string` and become `text`.
-
-The conversion is a flat mapped type per table with a fixed number of conditional types per
-column; converting a 50-table, 600-column schema costs about 20k type instantiations (~10 ms),
-next to the 100k+ that core spends on its first query.
-
-## Examples
-
-[`examples/basic.ts`](examples/basic.ts) walks through the features above; it is type-checked with the package (`pnpm typecheck`).
+[MIT](LICENSE)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@typesql/kysely",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Use Kysely database interfaces (kysely-codegen, prisma-kysely) as a TypeSQL schema.",
   "license": "MIT",
   "repository": {
@@ -28,7 +28,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@typesql/core": "0.5.0"
+    "@typesql/core": "0.6.0"
   },
   "peerDependencies": {
     "kysely": ">=0.27"