@nxgt/janus-drizzle 0.1.0

package/dist/tables.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tables.d.ts","sourceRoot":"","sources":["../src/tables.ts"],"names":[],"mappings":"AACA,OAAO,EAQN,KAAK,QAAQ,EAMb,MAAM,qBAAqB,CAAC;AAE7B;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,6BAA6B;AAC7B,MAAM,WAAW,kBAAkB;IAClC;;;;;;OAMG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,QAAQ,CAAC;CAC3B;AAiBD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,GAAE,kBAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAkJjE;AAED,mDAAmD;AACnD,MAAM,MAAM,WAAW,GAAG,UAAU,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAE/D;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,qBAAqB,CACrC,CAAC,SAAS,MAAM,WAAW,GAAG,MAAM,WAAW;IAE/C,QAAQ,CAAC,MAAM,CAAC,EAAE,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC;CACvC"}

package/dist/translate.d.ts

@@ -0,0 +1,31 @@
+import { StoreConflict } from '@nxgt/janus';
+/**
+ * **The database's errors, as the port's.** One file, and one default.
+ *
+ * | What happens | Becomes |
+ * | --- | --- |
+ * | A login another user of the type holds | `StoreConflict('login')`, carrying `login` and `userType` |
+ * | A row with this id already there | nothing: the insert is a retry, and answers what is stored |
+ * | A unique violation on **any other constraint** | **`StoreFailure`** |
+ * | A check or foreign key refusing a row | **`StoreFailure`** |
+ * | Anything else, absolutely | `StoreFailure`, with `@nxgt/drizzle`'s `DataError` as `cause` |
+ *
+ * The first two are never errors here: a login is written with `on conflict
+ * do nothing`, and a login the statement did not write is one somebody else
+ * holds — so no conflict is ever told apart by parsing a driver's message.
+ *
+ * The bold rows go against the obvious reading. A violation the adapter did
+ * not mean to cause is an adapter bug, and reporting it as `LOGIN_TAKEN`
+ * would tell somebody their login is taken when it is not. The core
+ * validated every record before it reached a store, so a constraint refusing
+ * one means the adapter and the port disagree — never the caller's fault.
+ *
+ * **The default is a failure, not an absence.** That branch is what keeps the
+ * port's first rule: nothing here answers `null` for an error.
+ */
+export type Slot = 'users' | 'sessions' | 'tokens' | 'relations';
+/** Runs one port method, and makes every rejection one the port allows. */
+export declare function run<T>(slot: Slot, operation: string, body: () => Promise<T>): Promise<T>;
+/** The refusal the port promises for a taken login. */
+export declare function loginTaken(operation: string, type: string, login: string): StoreConflict;
+//# sourceMappingURL=translate.d.ts.map

package/dist/translate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"translate.d.ts","sourceRoot":"","sources":["../src/translate.ts"],"names":[],"mappings":"AACA,OAAO,EAAc,aAAa,EAAgB,MAAM,aAAa,CAAC;AAEtE;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,MAAM,MAAM,IAAI,GAAG,OAAO,GAAG,UAAU,GAAG,QAAQ,GAAG,WAAW,CAAC;AAEjE,2EAA2E;AAC3E,wBAAsB,GAAG,CAAC,CAAC,EAC1B,IAAI,EAAE,IAAI,EACV,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACpB,OAAO,CAAC,CAAC,CAAC,CAYZ;AAED,uDAAuD;AACvD,wBAAgB,UAAU,CACzB,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,GACX,aAAa,CAMf"}

package/docs/README.md

@@ -0,0 +1,12 @@
+# @nxgt/janus-drizzle — documentation
+
+The [README](../README.md) shows the whole wiring in one example; these pages
+give the detail.
+
+| Page | Read it when |
+| --- | --- |
+| [Wiring the stores and the relations](guide/wiring.md) | You are passing your Drizzle instance to `janus()` and `permissions()`, choosing a driver, or handling what a failure throws |
+| [Where the tables live](guide/database.md) | You are choosing between a database of Janus's own and a PostgreSQL schema in yours, or backing up and restoring Janus's tables |
+| [The tables in your migrations](guide/migrations.md) | You are adding the tables to your schema, generating the migration, collecting lapsed sessions, or want to know what the database holds |
+| [Troubleshooting](troubleshooting.md) | You have an error message and want its cause and its fix |
+| [Roadmap](roadmap.md) | You want to know what is coming, what shipped, and what is deliberately not planned |

package/docs/guide/database.md

@@ -0,0 +1,172 @@
+# Where the tables live
+
+This page covers:
+- giving Janus **a database of its own**, the recommended setup;
+- or **a PostgreSQL schema of its own**, beside your tables in one database;
+- backing up and restoring Janus's tables, in either setup.
+
+The five tables are `users`, `logins`, `sessions`, `tokens` and `relations`,
+with no prefix. Where they live is the one choice you make:
+
+| | A database of its own | A schema of its own |
+| --- | --- | --- |
+| The tables | `users`, … in `public` | `janus.users`, … |
+| `defineJanusTables(…)` | `defineJanusTables()` | `defineJanusTables({ schema: janus })` |
+| The adapter | `createDrizzleAdapter(janusDb)` | `createDrizzleAdapter(db, { tables: janusTables })` |
+| Migrations | a drizzle-kit config of its own | your application's drizzle-kit config |
+| Back up and restore Janus alone | `pg_dump` / `pg_restore` of the database | `pg_dump -n janus` / `pg_restore -n janus` |
+| A foreign key from your tables to `users`, one transaction over both | no | yes |
+
+The core never needs a transaction over your tables and Janus's, and never
+reads your tables. Choose a schema of its own only if your own tables must
+reference Janus's users, or if you cannot run a second database.
+
+## A database of its own
+
+Janus's tables in `janus`, your application's in `app`: restoring one never
+rolls the other back, and each is dumped, restored, moved or sized alone.
+
+### The schema file and its drizzle-kit config
+
+```ts
+// src/janus/schema.ts
+import { defineJanusTables } from '@nxgt/janus-drizzle';
+
+export const { users, logins, sessions, tokens, relations } = defineJanusTables();
+```
+
+```ts
+// drizzle.janus.config.ts — beside your application's drizzle.config.ts
+import { defineConfig } from 'drizzle-kit';
+
+export default defineConfig({
+	dialect: 'postgresql',
+	schema: './src/janus/schema.ts',
+	out: './drizzle/janus',
+	dbCredentials: { url: process.env.JANUS_DATABASE_URL ?? 'postgres://localhost:5432/janus' },
+});
+```
+
+Create the database once, then generate and apply Janus's migrations with this
+config:
+
+```sh
+createdb janus
+bunx drizzle-kit generate --config drizzle.janus.config.ts
+bunx drizzle-kit migrate --config drizzle.janus.config.ts
+```
+
+`drizzle-kit generate` writes `CREATE TABLE "users"`, `"logins"`,
+`"sessions"`, `"tokens"` and `"relations"`, with their indexes and the
+foreign key from `logins` to `users`.
+
+### A Drizzle instance of its own
+
+```ts
+import { createDrizzleAdapter } from '@nxgt/janus-drizzle';
+import { drizzle } from 'drizzle-orm/node-postgres';
+
+// Your application's own tables stay on its own instance, over DATABASE_URL.
+const janusDb = drizzle(process.env.JANUS_DATABASE_URL ?? 'postgres://localhost:5432/janus');
+const postgres = createDrizzleAdapter(janusDb); // { store, relations }
+```
+
+Everything else is wired as in [Wiring the stores and the relations](wiring.md).
+
+## A schema of its own
+
+The tables in a PostgreSQL schema named `janus`, in your application's
+database, created by your application's migrations.
+
+```ts
+// src/db/schema.ts — the file your drizzle.config.ts names as `schema`
+import { defineJanusTables } from '@nxgt/janus-drizzle';
+import { pgSchema } from 'drizzle-orm/pg-core';
+
+export const janus = pgSchema('janus');
+export const { users, logins, sessions, tokens, relations } = defineJanusTables({ schema: janus });
+
+// your own tables below
+```
+
+**Export the schema, `janus`, too.** drizzle-kit writes `CREATE SCHEMA
+"janus"` only for a schema it finds exported. Without it, the migration
+creates `"janus"."users"` in a schema that does not exist, and fails with
+`schema "janus" does not exist`.
+
+**Pass the adapter the tables you exported**, so the stores query exactly
+what your migration created:
+
+```ts
+// src/db/schema.ts
+export const janus = pgSchema('janus');
+export const janusTables = defineJanusTables({ schema: janus });
+export const { users, logins, sessions, tokens, relations } = janusTables;
+```
+
+```ts
+import { janusTables } from './db/schema';
+
+const postgres = createDrizzleAdapter(db, { tables: janusTables });
+```
+
+drizzle-kit ignores `janusTables`, an object and not a table, and creates the
+five from the exports below it. `createDrizzleStores(db, { tables })` and
+`createDrizzleRelations(db, { tables })` take them the same way.
+
+**Without `{ tables }`, the stores query `users`, `sessions`, … in the
+connection's `search_path`: `public`.** If your application has a `users`
+table of its own there, deleting a user through the store would delete from
+it. Always pass the tables with a schema of its own.
+
+The names in your schema file are yours to choose. If `users` is taken by a
+table of your own, rename on export:
+
+```ts
+export const janusTables = defineJanusTables({ schema: janus });
+export const janusUsers = janusTables.users;
+// …and the four others
+```
+
+## Backing up and restoring
+
+`pg_dump`'s custom format, `-Fc`, is what `pg_restore` reads. Both setups were
+measured on PostgreSQL 17.
+
+### A database of its own
+
+```sh
+pg_dump -Fc -f janus.dump janus
+
+# Into the same database, replacing what is there:
+pg_restore --clean --if-exists -d janus janus.dump
+```
+
+The dump holds drizzle-kit's migration journal too, the `drizzle` schema, so a
+restored database knows which migrations it has.
+
+### A schema of its own
+
+```sh
+pg_dump -Fc -n janus -f janus.dump app
+
+# Into the same database, replacing Janus's tables and nothing else:
+pg_restore --clean -n janus -d app janus.dump
+```
+
+`-n janus` dumps the schema and its five tables only: your tables are neither
+dumped nor touched by the restore. The migration journal is not in the dump,
+since it is your application's.
+
+### What a restore means for your users
+
+A restore brings back the users, logins and relations as they were, and the
+sessions and one-time tokens too:
+- a session revoked since the dump stands again until it lapses. If that
+  matters, `delete from sessions` (or `delete from janus.sessions`) after the
+  restore signs everybody out;
+- a user created since the dump is gone, with their sign-in;
+- a reset link sent since the dump answers `TOKEN_UNKNOWN`.
+
+With sessions in Redis, through `@nxgt/janus-redis`, sessions and tokens are
+not in the dump at all, and a restore leaves them as they are.

package/docs/guide/migrations.md

@@ -0,0 +1,153 @@
+# The tables in your migrations
+
+This page covers:
+- adding the five tables to the schema drizzle-kit reads;
+- what the migration creates;
+- collecting lapsed sessions;
+- what the database holds.
+
+The core never manages a schema, and the stores create nothing per request.
+**Your migrations create the tables**, as they create your own.
+
+## In your schema
+
+`defineJanusTables()` returns the five tables. Export them from the file, or
+one of the files, that a drizzle-kit config names as `schema`:
+
+```ts
+// src/janus/schema.ts
+import { defineJanusTables } from '@nxgt/janus-drizzle';
+
+export const { users, logins, sessions, tokens, relations } = defineJanusTables();
+```
+
+Which config, and which database, is the choice
+[Where the tables live](database.md) walks through: a database of its own,
+with a drizzle-kit config of its own (recommended), or a PostgreSQL schema of
+its own, `defineJanusTables({ schema: janus })`, in your application's
+schema file.
+
+Then generate and apply the migration with that config:
+
+```sh
+bunx drizzle-kit generate --config drizzle.janus.config.ts
+bunx drizzle-kit migrate --config drizzle.janus.config.ts
+```
+
+With a schema of its own in your application's database, it is your
+application's config, so the plain `bunx drizzle-kit generate` and `migrate`.
+
+drizzle-kit only picks up top-level table exports, so export each table: the
+object `defineJanusTables()` returns is not itself a table, and drizzle-kit
+finds nothing in it. Measured on drizzle-kit 1.0.0-rc.4.
+
+**Keep all five.** drizzle-kit writes a `DROP TABLE` for a table the schema no
+longer names, and that drops every user. Read the migration before you apply
+it, as with any other.
+
+An application that only authenticates can leave out `relations`, as long as
+it never passes `createDrizzleRelations`. `createDrizzleAdapter` needs all
+five.
+
+## What the migration creates
+
+It needs **PostgreSQL 15 or later**: the tuple constraint is `unique nulls not
+distinct`.
+
+```sql
+CREATE TABLE "users" (
+	"id" text collate "C" PRIMARY KEY,
+	"type" text collate "C" NOT NULL,
+	"schema_version" text NOT NULL,
+	"active" boolean NOT NULL,
+	"fields" jsonb NOT NULL,
+	"logins" text[] NOT NULL,
+	"password_hash" text,
+	"password_updated_at" timestamp(3) with time zone,
+	"email_verified_at" timestamp(3) with time zone,
+	"version" integer NOT NULL,
+	"created_at" timestamp(3) with time zone NOT NULL,
+	"updated_at" timestamp(3) with time zone NOT NULL,
+	CONSTRAINT "users_id_type_unique" UNIQUE("id","type"),
+	CONSTRAINT "users_password_whole" CHECK (("password_hash" is null) = ("password_updated_at" is null))
+);
+CREATE TABLE "logins" (
+	"type" text collate "C",
+	"login" text collate "C",
+	"user_id" text collate "C" NOT NULL,
+	CONSTRAINT "logins_pkey" PRIMARY KEY("type","login")
+);
+-- sessions, tokens, relations, the indexes, and the foreign key from
+-- logins to users, on delete cascade.
+```
+
+With `defineJanusTables({ schema: janus })`, it starts with `CREATE SCHEMA "janus"`, and every
+name is qualified: `CREATE TABLE "janus"."users"`.
+
+The specs build their database from exactly this: drizzle-kit's own
+`generateMigration` over the exported tables, in both layouts. So what your
+migration creates is what the conformance suites ran on.
+
+### The choices in it
+
+- **No prefix.** In a database of its own, nothing can collide; beside your
+  tables, a PostgreSQL schema keeps them apart, and `pg_dump -n janus` backs
+  them up alone. A prefix would do neither.
+- **`snake_case` columns.** This follows PostgreSQL's catalog and
+  `@nxgt/drizzle`'s `timestamps()`, so a query written by hand needs no quotes.
+  The records the stores return are camelCase.
+- **`text collate "C"` for every key.** The port compares ids, logins and
+  types byte for byte. Under a database collation such as `en-US`, `B` sorts
+  after `a`, and a page in ascending id order repeats or skips rows.
+- **`text`, not `uuid`, for ids.** The core mints UUIDv7s, but a `uuid` column
+  would refuse any other id with an error rather than find nothing, and would
+  return a different spelling than the one written.
+- **`timestamp(3)`.** A JavaScript `Date` has milliseconds. At PostgreSQL's
+  default of microseconds, a date written and read back is not the one the
+  core wrote.
+- **`jsonb` for `fields`.** The core validated them against your schema. Keys
+  come back in `jsonb`'s own order; values are unchanged.
+- **Logins twice.** They are stored as the `logins` array on the user,
+  returned verbatim and in order, and as rows in `logins`, whose primary
+  key is the per-type uniqueness. PostgreSQL has no unique index over the
+  elements of an array.
+- **No foreign key from sessions and tokens to users.** Deleting a user
+  deletes the user; the core deletes the sessions and tokens next, as it does
+  when they live in another store.
+
+## Collecting lapsed sessions
+
+PostgreSQL has no TTL. A lapsed session is refused on every read, but it stays
+in `sessions` until something deletes it. `auth.collectExpired()`
+deletes every session whose `expiresAt` has passed, and returns how many:
+
+```ts
+// Hourly, from whatever runs your scheduled jobs.
+const collected = await auth.collectExpired();
+console.info(`janus: ${collected} lapsed sessions deleted`);
+```
+
+`expires_at` is indexed, so this is one indexed `delete`. Spent and lapsed
+one-time tokens stay until their user is deleted; there are few of them per
+user.
+
+## Reading the tables yourself
+
+The tables your schema file exports are ordinary Drizzle tables, for a query
+of your own: an admin listing, a report, a data export.
+
+```ts
+import { count, eq } from 'drizzle-orm';
+import { users } from './janus/schema';
+
+// janusDb: the Drizzle instance over Janus's tables
+const [row] = await janusDb
+	.select({ patients: count() })
+	.from(users)
+	.where(eq(users.type, 'patient'));
+const patients = row?.patients ?? 0;
+```
+
+**Read, never write.** A row written behind the store's back skips its
+invariants: the logins' uniqueness, `version`, the password check. Write
+through `auth` and `access`.

package/docs/guide/wiring.md

@@ -0,0 +1,170 @@
+# Wiring the stores and the relations
+
+This page covers connecting `@nxgt/janus` to PostgreSQL through Drizzle:
+- the three user stores for `janus()`;
+- the relation store for `permissions()`;
+- what each one throws when the database cannot answer.
+
+Creating the tables is covered in [the migrations page](migrations.md), and
+choosing their database in [Where the tables live](database.md).
+
+```ts
+import { janus, scryptHasher } from '@nxgt/janus';
+import { defineModel, permissions } from '@nxgt/janus/permissions';
+import { createDrizzleAdapter } from '@nxgt/janus-drizzle';
+import { drizzle } from 'drizzle-orm/node-postgres';
+import { z } from 'zod';
+
+// Janus's own database; your application's tables stay on their own instance.
+const db = drizzle(process.env.JANUS_DATABASE_URL ?? 'postgres://localhost:5432/janus');
+
+const postgres = createDrizzleAdapter(db); // { store, relations }
+
+export const auth = janus({
+	user: z.object({ email: z.email(), name: z.string() }),
+	password: { login: 'email' },
+	hasher: scryptHasher(),
+	...postgres, // deleting a user deletes every tuple naming them
+});
+
+export const model = defineModel({
+	subjects: auth.types,
+	types: {
+		document: {
+			related: { owners: ['user'], viewers: ['user'] },
+			permits: { view: ['owners', 'viewers'] },
+		},
+	},
+});
+
+export const access = permissions({ model, store: postgres.relations });
+```
+
+## `createDrizzleAdapter(db, options?)`
+
+```ts
+import type { PgDatabase } from '@nxgt/drizzle/pg'; // any Drizzle PostgreSQL instance
+
+function createDrizzleAdapter(
+	db: PgDatabase,
+	options?: { tables?: JanusTables }, // DrizzleAdapterOptions
+): DrizzleAdapter; // { store, relations }
+```
+
+It returns `createDrizzleStores(db, options)` as `store` and
+`createDrizzleRelations(db, options)` as `relations`: the two keys `janus()` takes them under, so a spread wires
+both. `permissions()` takes the same relation store as `postgres.relations`.
+It connects to nothing and creates nothing.
+
+`options.tables` is what your schema file's `defineJanusTables(…)` returned,
+so the stores query the tables your migration created. Leave it out for
+tables in the connection's `search_path`, `public` by default. **Pass it
+whenever the tables are in a PostgreSQL schema of their own**: without it, the
+stores query `public`, where your application may have a `users` of its own
+([Where the tables live](database.md#a-schema-of-its-own)).
+
+**Pass the relation store to both.** If only `permissions()` gets it, tuples
+are still written, but deleting a user leaves behind every tuple naming them.
+The spread makes that impossible to forget. An application that only
+authenticates takes `createDrizzleStores(db)` alone, below.
+
+`db` is any Drizzle PostgreSQL instance, whatever its driver:
+
+| Driver | Import |
+| --- | --- |
+| `pg` (node-postgres) | `drizzle-orm/node-postgres` |
+| `postgres` (postgres.js) | `drizzle-orm/postgres-js` |
+| Bun's own `SQL` | `drizzle-orm/bun-sql` |
+| PGlite, for tests | `drizzle-orm/pglite` |
+
+The adapter's specs run on all four: on PGlite, and on PostgreSQL 17 over each
+of the other three, on every CI run.
+
+## `createDrizzleStores(db, options?)`
+
+```ts
+function createDrizzleStores(db: PgDatabase, options?: { tables?: Pick<JanusTables, 'users' | 'logins' | 'sessions' | 'tokens'> }): JanusStores; // { users, sessions, tokens }
+```
+
+This is what `janus({ store })` takes. It uses `users`, `logins`, `sessions`
+and `tokens`.
+
+**Every read is one statement.** An absence comes back as an empty result,
+which becomes `null`. Anything that rejects is a failure, so an outage can
+never be confused with "no such user".
+
+**Writing a user is one transaction** that covers the user's row and its rows
+in `logins`. It runs through `@nxgt/drizzle`'s `withTransaction`, inside
+the method; the core never opens one. Every other write is a single
+statement. `consumeToken` is one statement, `with before as (select … for update) update … from before`: of
+twenty concurrent redemptions of one token, exactly one sees `spentAt: null`.
+This is measured on PostgreSQL 17 on every CI run.
+
+Every method of the port is implemented, **including the optional
+`deleteExpiredSessions`**. PostgreSQL has no TTL, so
+`auth.collectExpired()` is how lapsed sessions leave the table; schedule it.
+The [migrations page](migrations.md#collecting-lapsed-sessions) shows how.
+
+## `createDrizzleRelations(db, options?)`
+
+```ts
+function createDrizzleRelations(db: PgDatabase, options?: { tables?: Pick<JanusTables, 'relations'> }): RelationStore;
+```
+
+This is what `permissions({ store })` takes, and `janus({ relations })`. It
+uses `relations`.
+
+**A write of more than one tuple is a transaction**: removals first, then
+additions, all or nothing. `grant` and `revoke` write one tuple, in one
+statement. A transaction is not retried; a write is idempotent, so retry it
+yourself if you want to.
+
+`findObjects` orders ids byte by byte: the columns are `collate "C"`, so the
+order does not depend on your database's collation. Under `en-US`, `a` sorts
+before `B`. Here `B` comes first, as JavaScript's `<` puts it.
+
+## What a failure looks like
+
+The adapter defines **no error class**. Every rejection is `@nxgt/janus`'s own,
+so `instanceof` holds in your code: `@nxgt/janus` is a peer, and there is one
+copy of it.
+
+| What PostgreSQL reports | What you get |
+| --- | --- |
+| A login another user of the type holds | `StoreConflict`, code `LOGIN_TAKEN`, carrying `login` and `userType` |
+| A row with this id already there | Nothing: the insert was a retry, and returns what is stored — or `NOT_FOUND` if the user was deleted between the two |
+| A unique violation on **any other constraint** | `StoreFailure`: an adapter bug, never reported as a taken login |
+| A check or foreign key refusing a row | `StoreFailure`: the core validated the record already, so it is never the caller's fault |
+| Anything else: a refused connection, a timeout, a missing table | `StoreFailure`, with the driver's error as `cause` |
+
+A login is claimed with `on conflict do nothing`, so no conflict is ever told
+apart by parsing a driver message. The logins are claimed in sorted order, so
+two sign-ups racing for the same ones never deadlock: the second waits, then
+gets `LOGIN_TAKEN`.
+
+The `cause` is `@nxgt/drizzle`'s `toDataError(error)`. Over `node-postgres`,
+postgres.js and PGlite that is a `DataError`, whose `sqlState`, `table` and
+`constraint` say what PostgreSQL refused. Over Bun's `SQL` it is Drizzle's
+`DrizzleQueryError`, with PostgreSQL's code as `errno` on its own `cause`.
+
+Nothing returns `null` for an error, so a route answers 503, not 401 or 404:
+
+```ts
+import { StoreFailure } from '@nxgt/janus';
+
+export async function me(request: Request): Promise<Response> {
+	try {
+		const current = await auth.authenticate(request);
+		return current === null ? new Response(null, { status: 401 }) : Response.json({ id: current.user.id });
+	} catch (error) {
+		if (error instanceof StoreFailure) {
+			console.error('janus: the database could not answer', error.cause);
+			return new Response(null, { status: 503 });
+		}
+		throw error;
+	}
+}
+```
+
+With `@nxgt/janus-hono`, `app.onError(janusErrors())` does the same for every
+route.

package/docs/roadmap.md

@@ -0,0 +1,44 @@
+# Roadmap
+
+Where `@nxgt/janus-drizzle` is heading. It shows a direction, not a
+commitment: there are no dates here, and the only number is the version
+something shipped in.
+
+## Now
+
+Nothing yet.
+
+## Next
+
+Nothing yet.
+
+## Later
+
+Nothing yet.
+
+## Not planned
+
+- **MySQL and SQLite.** `@nxgt/drizzle` is PostgreSQL only, and so is this
+  adapter: the tuple constraint, `for update` and `collate "C"` are
+  PostgreSQL's.
+- **PostgreSQL before 15.** The tuple constraint needs `unique nulls not
+  distinct`.
+- **Creating the tables from the store.** Your migrations create them, from
+  the exported tables. The stores never create anything per request.
+- **Retrying a transaction for you.** A write is idempotent, so retry it
+  yourself, on your own terms.
+- **Error classes of its own.** The adapter throws `@nxgt/janus`'s classes,
+  which is why `@nxgt/janus` is a required peer and never a dependency:
+  `instanceof StoreFailure` has to hold in your code.
+- **`moduleResolution: "nodenext"`.** Like `@nxgt/janus`, the package imports
+  without extensions and resolves as Bun and every bundler do. Use
+  `"moduleResolution": "bundler"`.
+
+## Shipped
+
+- **The first release, v0.1.0.** Both sides of `@nxgt/janus` over one
+  PostgreSQL database, on Drizzle; the adapter passes both conformance suites
+  on PostgreSQL 17 and PGlite. `defineJanusTables({ schema? })` puts the tables
+  in a database or a schema of their own, with no prefix, and the factories
+  take the tables your schema file exports, so the stores query exactly what
+  your drizzle-kit migration created.