typion 0.0.0-stage → 0.1.0

package/docs/queries.md

@@ -0,0 +1,197 @@
+# Reading and writing
+
+Every call goes through an app bound to a caller:
+
+| Where                                     | The app                                         |
+| ----------------------------------------- | ----------------------------------------------- |
+| a Next.js server component or action      | `await getApp(config)` from `typion/next`       |
+| a route handler with a `Request`          | `await typion.$fromRequest(request)`            |
+| a known caller (a test, a job for a user) | `typion.$as({ actorId, role })`                 |
+| a seed, a job, a webhook                  | `typion.$system({ reason: 'nightly cleanup' })` |
+
+`typion` is `await getTypion(config)`, one instance per config and process. The bound app has one property per
+collection (`app.posts`), and `$ctx`, `$transaction`, `$run`.
+
+## Reads
+
+```ts
+const rows = await app.posts.find({
+  columns: { id: true, title: true, slug: true },
+  with: {
+    author: { columns: { name: true } },
+    tags: { columns: { label: true } },
+    comments: { columns: { body: true }, orderBy: { createdAt: 'asc' }, limit: 3 },
+  },
+  where: { title: { ilike: '%typion%' }, tags: { label: 'release' } },
+  orderBy: { createdAt: 'desc' },
+  limit: 20,
+})
+rows satisfies {
+  id: string
+  title: string
+  slug: string
+  author: { name: string }
+  tags: { label: string }[]
+  comments: { body: string }[]
+}[]
+```
+
+- `find`, `findOne` (no `limit`), `findById(id, config)` (`NOT_FOUND` when missing or hidden), `count({ where })`,
+  `page({ limit, offset, … })` → `{ items, total, limit, offset, hasMore }`.
+- The config is Drizzle's relational query config: `columns` (`{ x: true }` to pick, `{ x: false }` to leave out),
+  nested `with` with its own `columns`, `where`, `orderBy`, `limit` and `offset`, and `where` with `eq`, `ne`, `gt`,
+  `gte`, `lt`, `lte`, `in`, `notIn`, `like`, `ilike`, `isNull`, `isNotNull`, `AND`, `OR`, `NOT`, and relation filters
+  (`author: { role: 'admin' }`, `comments: true` for "has at least one").
+- The features add options: `withDeleted` (soft delete), `draft` (drafts), `locale` and `fallback` (localization).
+  A collection without the feature has no such option: the types refuse it.
+- **The result type is the query's.** A relation is `| null` when the caller may not see its target, `T[]` for
+  `many`; a column a field rule may hide is `T | null`. Do not cast these away: they are what the rules allow.
+- A list read without `limit` returns every row the caller may see. Lists are `page` or `find` with a `limit`; over
+  HTTP a missing limit is capped (`maxLimit`, 100 by default). A `limit` above `maxLimit` is `BAD_REQUEST` in
+  process too.
+
+### Descriptors
+
+A descriptor is a query as a value, carrying its result type: pages, components and the browser share it, and nobody
+writes the row type by hand.
+
+```ts
+// src/typion/queries.ts
+import type { InferItem, Typion } from 'typion'
+import { defineQueries } from 'typion/contract'
+import type { config } from '../typion.config.ts'
+
+// `import type`: the browser bundle gets the types, not the server.
+const q = defineQueries<Typion<typeof config>>()
+
+export const postCards = q.posts.find({
+  columns: { id: true, slug: true, title: true },
+  with: { author: { columns: { name: true } } },
+  orderBy: { createdAt: 'desc' },
+  limit: 20,
+})
+
+export type PostCard = InferItem<typeof postCards>
+```
+
+```ts
+import { type PostCard, postCards } from '@/typion/queries.ts'
+
+const cards = await app.$run(postCards)
+cards satisfies PostCard[]
+```
+
+`defineQueries` accepts what can travel as JSON (no `RAW`, `extras` or callbacks), so the same descriptor runs in
+process with `app.$run` and from the browser through the client ([http.md](http.md)). On the server,
+`typion.posts.query({…})` gives the same value without that restriction.
+
+## Writes
+
+```ts
+const actorId = app.$ctx.actorId
+if (actorId !== null) {
+  const post = await app.posts.create({ title: 'Hello', slug: 'hello', authorId: actorId })
+  await app.posts.update(post.id, { body: 'First draft' })
+  // Published posts are edited as drafts: the live row stays as it is until `publish`.
+  await app.posts.update(post.id, { title: 'Hello, world' }, { draft: true })
+  await app.posts.publish(post.id)
+  // Soft delete: the row stays, every read hides it, `restore` brings it back.
+  await app.posts.delete(post.id)
+}
+```
+
+- `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).
+- 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`).
+
+## Transactions
+
+`app.$transaction(fn)` runs `fn` with an app bound to the same caller and to one transaction: every call in it commits
+or rolls back together, and `afterCommit` hooks wait for the outermost commit. A business operation of several writes
+is one transaction.
+
+```ts
+await app.$transaction(async (tx) => {
+  const post = await tx.posts.findById('7f8e…', { columns: { id: true } })
+  await tx.comments.updateMany(
+    { postId: post.id, approved: false },
+    { approved: true },
+    { max: 100 },
+  )
+  await tx.posts.update(post.id, { body: 'Comments reviewed.' })
+})
+```
+
+A function that takes the caller's app — a business operation that a server action, a route and a test all call —
+types it as `TypionAppOf<typeof config>`:
+
+```ts
+import type { TypionAppOf } from 'typion'
+import type { config } from '@/typion.config.ts'
+
+export async function approveAll(app: TypionAppOf<typeof config>, postId: string) {
+  return app.$transaction((tx) =>
+    tx.comments.updateMany({ postId, approved: false }, { approved: true }, { max: 100 }),
+  )
+}
+```
+
+## Links
+
+The side that owns a many-to-many (`writable: true`, [collections.md](collections.md)) writes its links:
+
+```ts
+const post = await app.posts.findById('7f8e…', { columns: { id: true } })
+const tag = await app.tags.findOne({ where: { label: 'release' }, columns: { id: true } })
+if (tag !== null) {
+  await app.posts.link(post.id, 'tags', [tag.id]) // { count: 1 }; a link already there is kept
+  await app.posts.unlink(post.id, 'tags', [tag.id])
+}
+```
+
+- A link is an edit of the owning row: it locks the post under its `update` rule, tenant and features, so a post the
+  caller may not update is `NOT_FOUND`. Every tag must be one the caller may read, or nothing is written and the call
+  is `NOT_FOUND`.
+- `count` is how many links were added or removed. Links run no collection hooks and are not in the history;
+  `@typion/audit` records them on the owning row.
+- Over HTTP: `POST /api/posts/:id/link/tags` and `/unlink/tags` with `{ ids }`, or the descriptors
+  `q.posts.link({ id, relation: 'tags', ids })` and `q.posts.unlink(…)`.
+
+## Errors
+
+Operations throw a `TypionError` with a `code`; over HTTP the same error is the response's `{ error }` with its status.
+
+| `code`          | Status | When                                                                    |
+| --------------- | ------ | ----------------------------------------------------------------------- |
+| `NOT_FOUND`     | 404    | the row is missing, or the caller may not see it                        |
+| `FORBIDDEN`     | 403    | a rule refused, a field may not be written, a call has no tenant        |
+| `VALIDATION`    | 422    | the input does not fit the columns or the schemas (`issues`)            |
+| `CONFLICT`      | 409    | a unique, foreign key or check constraint; `retryable` on serialization |
+| `INVALID_STATE` | 409    | the workflow refuses it (unpublish a draft, restore a live row)         |
+| `BAD_REQUEST`   | 400    | an unknown option, column or key; a limit or depth over the caps        |
+| `UNSUPPORTED`   | 400    | a feature's option or operation on a collection without the feature     |
+
+```ts
+import { isTypionError } from 'typion'
+
+try {
+  await app.posts.update('7f8e…', { title: 'Renamed' })
+} catch (error) {
+  if (isTypionError(error, 'NOT_FOUND')) {
+    // show "not found": the caller cannot tell a hidden post from a missing one, by design
+  } else {
+    throw error
+  }
+}
+```
+
+`attempt(() => …)` returns `{ ok: true, data }` or `{ ok: false, error }` instead of throwing.
+
+## The escape hatch
+
+`typion.$db` is the Drizzle instance underneath. It skips everything Typion does — rules, tenants, soft delete,
+drafts, validation, hooks, the history, the audit trail — so it is only for set-based maintenance in code no user
+drives (a backfill, a cleanup job), and never with input from a request.

package/docs/testing.md

@@ -0,0 +1,85 @@
+# Testing
+
+`createTestTypion(config)` from `typion/testing` gives the config's instance on an in-memory PGlite, with the schema
+pushed: no server, no network. It keeps the config's rules, hooks and context factory, and replaces the database.
+
+```ts
+import { afterAll, beforeEach, describe, expect, it } from 'vitest'
+import { createTestTypion } from 'typion/testing'
+import { config } from '@/typion.config.ts'
+
+const t = await createTestTypion(config)
+afterAll(() => t.close())
+beforeEach(() => t.reset())
+
+describe('posts', () => {
+  it('lets authors edit their own posts, and nobody write in their name', async () => {
+    const system = t.asSystem('seed')
+    const ada = await system.users.create({
+      name: 'Ada',
+      email: 'ada@example.test',
+      role: 'editor',
+    })
+    const bob = await system.users.create({
+      name: 'Bob',
+      email: 'bob@example.test',
+      role: 'editor',
+    })
+    const asAda = t.asUser({ actorId: ada.id, role: 'editor' })
+    const asBob = t.asUser({ actorId: bob.id, role: 'editor' })
+
+    const post = await asAda.posts.create({ title: 'Mine', slug: 'mine', authorId: ada.id })
+    expect((await asAda.posts.update(post.id, { title: 'Still mine' })).title).toBe('Still mine')
+
+    // Another author's post does not exist for Bob: NOT_FOUND, not FORBIDDEN.
+    await expect(asBob.posts.update(post.id, { title: 'Taken' })).rejects.toMatchObject({
+      code: 'NOT_FOUND',
+    })
+    await expect(
+      asBob.posts.create({ title: 'Forged', slug: 'forged', authorId: ada.id }),
+    ).rejects.toMatchObject({ code: 'FORBIDDEN' })
+  })
+})
+```
+
+- `t.asUser(ctx)` and `t.asSystem(reason)` are `typion.$as` and `typion.$system`; `t.typion` is the instance, and
+  `createHandler(t.typion, { transports: [rest(), rpc()] })` from `typion/http` its HTTP handler, for a test that
+  sends a `Request`.
+- Until `t.close()`, the test's instance is the config's: `getTypion(config)` returns it, so the application's own
+  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.
+- 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
+  database of its own, created and dropped by the harness: what PGlite cannot show, such as concurrent transactions,
+  shows there. The server's role must be allowed to create databases.
+
+## An application's routes
+
+A Hono app is tested with `app.request()`, against the test's instance; Hono's client `hc` and the browser client
+take the same in-process `fetch`.
+
+```ts
+import { createClient } from '@typion/rpc/client'
+import { rest } from '@typion/rest'
+import { rpc } from '@typion/rpc'
+import { Hono } from 'hono'
+import { expect, it } from 'vitest'
+import { typionRoutes } from 'typion/hono'
+import { createTestTypion } from 'typion/testing'
+import { config } from '@/typion.config.ts'
+import { postCards } from '@/typion/queries.ts'
+
+const t = await createTestTypion(config)
+const server = new Hono().all('/api/*', typionRoutes(config, { transports: [rest(), rpc()] }))
+
+it('serves the published posts to anyone', async () => {
+  const response = await server.request('/api/posts?columns=slug')
+  expect(response.status).toBe(200)
+  const client = createClient({ url: '/api', fetch: (input, init) => server.request(input, init) })
+  expect(await client.run(postCards)).toEqual([])
+  await t.close()
+})
+```

package/package.json

@@ -1,6 +1,128 @@
 {
   "name": "typion",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Headless, type-safe application engine on top of Drizzle ORM",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/the-escape-studio/typion.git",
+    "directory": "packages/typion"
+  },
+  "homepage": "https://github.com/the-escape-studio/typion/tree/main/packages/typion#readme",
+  "bugs": {
+    "url": "https://github.com/the-escape-studio/typion/issues"
+  },
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "bin",
+    "docs",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./schema": {
+      "types": "./dist/schema/index.d.ts",
+      "default": "./dist/schema/index.js"
+    },
+    "./contract": {
+      "types": "./dist/contract/index.d.ts",
+      "default": "./dist/contract/index.js"
+    },
+    "./http": {
+      "types": "./dist/http/index.d.ts",
+      "default": "./dist/http/index.js"
+    },
+    "./db/pglite": {
+      "types": "./dist/db/pglite.d.ts",
+      "default": "./dist/db/pglite.js"
+    },
+    "./seed": {
+      "types": "./dist/seed/index.d.ts",
+      "default": "./dist/seed/index.js"
+    },
+    "./next": {
+      "types": "./dist/next/index.d.ts",
+      "default": "./dist/next/index.js"
+    },
+    "./hono": {
+      "types": "./dist/hono/index.d.ts",
+      "default": "./dist/hono/index.js"
+    },
+    "./validation/zod": {
+      "types": "./dist/validation/zod.d.ts",
+      "default": "./dist/validation/zod.js"
+    },
+    "./auth/better-auth": {
+      "types": "./dist/auth/better-auth.d.ts",
+      "default": "./dist/auth/better-auth.js"
+    },
+    "./testing": {
+      "types": "./dist/testing/index.d.ts",
+      "default": "./dist/testing/index.js"
+    },
+    "./cli": {
+      "types": "./dist/cli/index.d.ts",
+      "default": "./dist/cli/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "@standard-schema/spec": "^1.1.0"
+  },
+  "peerDependencies": {
+    "@electric-sql/pglite": ">=0.5.0",
+    "drizzle-kit": "1.0.0-rc.4",
+    "drizzle-orm": "1.0.0-rc.4",
+    "hono": "^4.13.13 || ^5",
+    "next": ">=15",
+    "pg": "^8.0.0",
+    "superjson": "^2.2.0",
+    "zod": "^4.0.0",
+    "drizzle-seed": "1.0.0-rc.5-ab785fc"
+  },
+  "peerDependenciesMeta": {
+    "@electric-sql/pglite": {
+      "optional": true
+    },
+    "drizzle-kit": {
+      "optional": true
+    },
+    "superjson": {
+      "optional": true
+    },
+    "zod": {
+      "optional": true
+    },
+    "hono": {
+      "optional": true
+    },
+    "next": {
+      "optional": true
+    },
+    "pg": {
+      "optional": true
+    },
+    "drizzle-seed": {
+      "optional": true
+    }
+  },
+  "keywords": [
+    "drizzle",
+    "orm",
+    "headless",
+    "cms",
+    "access-control",
+    "typescript"
+  ],
+  "bin": {
+    "typion": "./bin/typion.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
 }