typion 0.1.0 → 0.1.1

package/docs/auth.md

@@ -2,14 +2,15 @@
 
 Typion does not sign people in. The config's context factory reads who is calling from the request, through an auth
 library, and looks up what the application knows of them: their role, their tenant. This page sets up Better Auth,
-email and password, on the database Typion uses.
+email and password, on the database Typion uses: on the connection of each Typion instance, so one recipe serves
+production and tests.
 
 ```ts
 // src/db.ts
 import { Pool } from 'pg'
 
-// One pool for Typion and Better Auth. pg connects on the first query, so importing the config — the CLI does, the
-// tests do — opens nothing. Whatever the config imports must not connect when it is imported.
+// Typion's pool, which Better Auth shares through the instance. pg connects on the first query, so importing the
+// config — the CLI does, the tests do — opens nothing. Whatever the config imports must not connect when it is imported.
 export const pool = new Pool({ connectionString: process.env.DATABASE_URL })
 ```
 
@@ -73,23 +74,43 @@ export const verification = pgTable('verification', {
 export const authTables = { user, session, account, verification }
 ```
 
+A property is named after Better Auth's field, and the column is named as the application likes
+(`emailVerified: boolean('email_verified')`). A plugin's tables follow the same rule, from the fields its
+documentation lists: the passkey plugin's table needs `credentialID`, whatever its column is called. Add them to
+`authTables`.
+
+Better Auth is built on the Drizzle connection of the Typion instance it serves, once per connection: the
+application's in production, a test's own database in a test.
+
 ```ts
 // src/auth.ts
 import { betterAuth } from 'better-auth'
 import { drizzleAdapter } from 'better-auth/adapters/drizzle'
-import { drizzle } from 'drizzle-orm/node-postgres'
 import { authTables } from './auth-schema.ts'
-import { pool } from './db.ts'
 
-export const auth = betterAuth({
-  database: drizzleAdapter(drizzle({ client: pool }), { provider: 'pg', schema: authTables }),
-  emailAndPassword: { enabled: true },
-})
+type AuthDb = Parameters<typeof drizzleAdapter>[0]
+
+function createAuth(db: AuthDb) {
+  return betterAuth({
+    database: drizzleAdapter(db, { provider: 'pg', schema: authTables }),
+    emailAndPassword: { enabled: true },
+  })
+}
+
+const auths = new WeakMap<AuthDb, ReturnType<typeof createAuth>>()
+
+export function authFor(db: AuthDb) {
+  let auth = auths.get(db)
+  if (auth === undefined) auths.set(db, (auth = createAuth(db)))
+  return auth
+}
 ```
 
-The config gives Typion the same pool, lists the tables, and turns a session into the context with
-`betterAuthContext(auth, map)` from `typion/auth/better-auth`, as [the guide's config](README.md#the-model) does:
-`map` gets the session (null for an anonymous caller) and the factory's input, with `system` to look the caller up.
+The config gives Typion the pool, lists the tables, and turns a session into the context with
+`betterAuthContext(authFor, map)` from `typion/auth/better-auth`, as [the guide's config](README.md#the-model) does.
+The context factory gets the instance's connection as `db`, and `betterAuthContext` hands it to `authFor`, so the
+config never reaches for the instance itself. `map` gets the session (null for an anonymous caller) and the factory's
+input, with `system` to look the caller up.
 Better Auth's user has no role: the application keeps it on a row of its own, here `users`, found by e-mail. In a
 multi-tenant application the same lookup finds the caller's membership, and with it their tenant.
 
@@ -98,7 +119,8 @@ import { drizzle } from 'drizzle-orm/node-postgres'
 import { dbAdapter } from 'typion'
 import { pool } from '@/db.ts'
 
-// What the config's `db` is when Better Auth shares the pool; `close` ends it when the CLI is done.
+// The config's `db`: Typion's connection on the pool, which Better Auth then uses too; `close` ends the pool when the
+// CLI is done.
 export const db = dbAdapter((relations) => drizzle({ client: pool, relations }), {
   url: process.env.DATABASE_URL,
   close: () => pool.end(),
@@ -107,14 +129,20 @@ export const db = dbAdapter((relations) => drizzle({ client: pool, relations }),
 
 ## Its routes
 
-Better Auth answers under `/api/auth/*`, next to Typion's transports under `/api/*`.
+Better Auth answers under `/api/auth/*`, next to Typion's transports under `/api/*`. A route reaches it through the
+instance, `authFor((await getTypion(config)).$db)`, which in a test is the test's instance ([testing.md](testing.md));
+so does server code that calls Better Auth's `api` itself.
 
 ```ts
 // src/app/api/auth/[...all]/route.ts
 import { toNextJsHandler } from 'better-auth/next-js'
-import { auth } from '@/auth.ts'
+import { getTypion } from 'typion'
+import { authFor } from '@/auth.ts'
+import { config } from '@/typion.config.ts'
 
-export const { GET, POST } = toNextJsHandler(auth)
+export const { GET, POST } = toNextJsHandler(async (request: Request) =>
+  authFor((await getTypion(config)).$db).handler(request),
+)
 ```
 
 A server action that signs in sets cookies: add Better Auth's `nextCookies()` to its `plugins`. On Hono, the route goes
@@ -124,12 +152,15 @@ before the transports' catch-all, which would otherwise answer it:
 import { rest } from '@typion/rest'
 import { rpc } from '@typion/rpc'
 import { Hono } from 'hono'
+import { getTypion } from 'typion'
 import { typionRoutes } from 'typion/hono'
-import { auth } from '@/auth.ts'
+import { authFor } from '@/auth.ts'
 import { config } from '@/typion.config.ts'
 
 export const server = new Hono()
-  .on(['GET', 'POST'], '/api/auth/*', (c) => auth.handler(c.req.raw))
+  .on(['GET', 'POST'], '/api/auth/*', async (c) =>
+    authFor((await getTypion(config)).$db).handler(c.req.raw),
+  )
   .all('/api/*', typionRoutes(config, { transports: [rest(), rpc()] }))
 ```
 
@@ -138,3 +169,27 @@ export const server = new Hono()
 A test binds its callers itself (`t.asUser(ctx)`), or replaces the context factory with
 `createTestTypion(config, { context })` ([testing.md](testing.md)), so it needs no session. Better Auth's tables are
 created with the collections either way.
+
+A test of signing in goes through Better Auth on the test's database: the instance's connection is `t.db`, so
+`authFor(t.db)` is the Better Auth that the context factory and the routes use while the test is open.
+
+```ts
+import { expect, it } from 'vitest'
+import { createTestTypion } from 'typion/testing'
+import { authFor } from '@/auth.ts'
+import { config } from '@/typion.config.ts'
+
+const t = await createTestTypion(config)
+
+it('knows who signed in', async () => {
+  await t.asSystem('seed').users.create({ name: 'Ada', email: 'ada@example.test', role: 'admin' })
+  const signedUp = await authFor(t.db).api.signUpEmail({
+    body: { name: 'Ada', email: 'ada@example.test', password: 'correct horse battery' },
+    asResponse: true,
+  })
+  const cookie = signedUp.headers.get('set-cookie')!.split(';')[0]!
+  const ada = await t.typion.$fromRequest(new Request('http://localhost/', { headers: { cookie } }))
+  expect(ada.$ctx.role).toBe('admin')
+  await t.close()
+})
+```

package/docs/collections.md

@@ -15,6 +15,10 @@ them, so it cannot be part of what they read.
 Every collection gets `id` (a uuid primary key) and `createdAt`/`updatedAt` unless it declares its own (`idColumn`,
 `timestamps: false`). Unknown keys are compile errors, so a misspelt option never passes in silence.
 
+`public: true` is the collection's `read` rule, `true`. It sits in the structure because the other collections read
+it there: a relation to a public collection is typed non-null. A collection that has it takes no `read` in
+`define()`, and one there is a compile error (`'read' does not exist in type 'Omit<AccessRules<…>, "read">'`).
+
 `fields` is part of the structure, which is typed before the config exists: field rules see the context type
 registered in `interface Register { context }` ([README.md](README.md)), and without it only the base context
 (`actorId`, `mode`, `now`) and what the features add (`locale`, `tenantId`).

package/docs/database.md

@@ -45,7 +45,9 @@ the shell set; an adapter given `url: process.env.DATABASE_URL` with the variabl
 2. `typion db generate --name <what-changed>`; read the SQL it wrote. A rename is a drop and an add unless you edit
    it: data is lost otherwise.
 3. Commit the SQL and the snapshot with the change.
-4. Deploys run `typion db migrate` before the new code serves requests.
+4. Deploys run `typion db migrate` before the new code serves requests. A deploy has no `.env.local` or `.env`:
+   `DATABASE_URL= pnpm build` tries the build without the URL even where they exist, since the CLI never writes
+   over what the shell set, an empty value included.
 
 `typion db push` is for a development database you can throw away; it never touches a shared one.
 

package/docs/features/multi-tenant.md

@@ -9,7 +9,7 @@ turned on per collection.
 import { type AnyPgColumn, uuid } from 'drizzle-orm/pg-core'
 import { defineConfig, defineSetup } from 'typion'
 import { pglite } from 'typion/db/pglite'
-import { auth } from './auth.ts'
+import { authFor } from './auth.ts'
 import { members } from './typion/collections/members.ts'
 import { projects } from './typion/collections/projects.ts'
 import { tenants } from './typion/collections/tenants.ts'
@@ -32,9 +32,10 @@ export const config = defineConfig({
   setup,
   collections: [tenants, members, projects],
   db: pglite({ dataDir: '.pglite' }),
-  // `system` here crosses tenants: it looks the caller up before their tenant is known.
-  context: async ({ headers, system }): Promise<AppContext> => {
-    const session = headers === undefined ? null : await auth.api.getSession({ headers })
+  // `system` here crosses tenants: it looks the caller up before their tenant is known. `db` is the instance's
+  // connection, which Better Auth is built on (auth.md).
+  context: async ({ headers, system, db }): Promise<AppContext> => {
+    const session = headers === undefined ? null : await authFor(db).api.getSession({ headers })
     const member =
       session === null
         ? null

package/docs/http.md

@@ -102,6 +102,10 @@ export default app
   has not signed in with `401`, as the transports do.
 - Node, Bun and Vercel run it as written. Cloudflare Workers do not yet: the instance keeps its database connection
   across requests, which Workers forbid.
+- On Vercel with TypeScript 7, whose `types` default to `[]`, put `/// <reference types="node" />` in a `.d.ts` under
+  `src/` rather than `"types": ["node"]` in `tsconfig.json`. Vercel's builder compiles through a tsconfig of its own,
+  in a temporary directory, that extends the project's and finds no `node_modules` from there (`TS2688`). A build
+  script of `typion db migrate` migrates before the function is deployed ([database.md](database.md#migrations)).
 
 ## Other frameworks
 

package/docs/queries.md

@@ -103,6 +103,9 @@ if (actorId !== null) {
 - `create(data, options)`, `update(id, data, options)`, `delete(id, options)`; `updateMany(where, data, { max })` and
   `deleteMany(where, { max })` lock every match first and run the whole pipeline per row, all or nothing, refusing
   more than `max` rows (1000 by default).
+- There is no `createMany`: many new rows are `create` in a loop inside `$transaction`, all or nothing, each through
+  its rules and hooks, a few queries a row. A list that is always read and written whole, such as a snapshot, is one
+  validated `jsonb` column rather than a row per item.
 - A write returns the row as the caller would read it straight after.
 - The columns the features manage are not in the input types; their operations write them (`delete`, `restore`,
   `publish`, `unpublish`, `discardDraft`).

package/docs/testing.md

@@ -49,7 +49,7 @@ describe('posts', () => {
   routes — a Hono app, a route handler — serve the test's database, and are tested with requests (below).
 - `t.reset()` empties every table, faster than a database per test. One instance per test file.
 - `createTestTypion(config, { now: () => date })` fixes the clock the engine writes timestamps with;
-  `{ context }` replaces the context factory, and gets what the config's gets, `system` included.
+  `{ context }` replaces the context factory, and gets what the config's gets, `system` and `db` included.
 - Every rule gets two tests: a caller it allows and one it refuses. A refused read is an empty result or
   `NOT_FOUND`; a refused write is `FORBIDDEN` or `NOT_FOUND`, with nothing written.
 - With `TYPION_TEST_DATABASE_URL=postgres://…` the same tests run on that Postgres server, each instance in a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "typion",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Headless, type-safe application engine on top of Drizzle ORM",
   "type": "module",
   "license": "MIT",