@avelonjs/assay 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ryan Yannelli
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,146 @@
+# @avelonjs/assay
+
+`@avelonjs/assay` is the test harness. It sits on `bun test` and gives you HTTP helpers that dispatch through the core kernel, model factories, and seeds. Reach for it when a feature test should speak in requests, factories, and assertions rather than constructing `HttpRequest` by hand.
+
+Assay tests a material for what it really is: the same kernel, routes, and models the adapter will serve.
+
+## Installation
+
+```sh
+bun add -d @avelonjs/assay
+```
+
+Assay expects `@avelonjs/core` and `@avelonjs/orm`. You pass a kernel and route table in; vendor drivers stay in test setup, never in `app/`.
+
+## Basic Usage
+
+```ts
+import { FakeDatabase } from '@avelonjs/conformance'
+import { createKernel, defineConfig, view } from '@avelonjs/core'
+import { assay } from '@avelonjs/assay'
+
+defineConfig({ name: 'tests', drivers: { database: new FakeDatabase() } })
+
+const kernel = createKernel()
+const client = assay({ kernel, routes })
+
+const index = await client.get('/users')
+index.assertOk().assertView('users.index')
+const stored = await client.actingAs({ id: 'u1' }).post('/users', { name: 'Ada' })
+stored.assertRedirect('/users/u1')
+```
+
+## HTTP Helpers
+
+`assay()` matches method plus path against a `RouteDefinition` table, preferring static segments so `/users/create` does not lose to `/users/{user}`. Each helper builds an `HttpRequest`, dispatches through the kernel, and flushes `after` listeners.
+
+```ts
+const shown = await client.get('/users/u1')
+shown.assertStatus(200)
+shown.view().props
+```
+
+`call(name, httpRequest())` dispatches a named route when you already have params. Unauthenticated S4-style kernels still read `cookies.user`; `actingAs('ada')` writes that cookie.
+
+## Factories
+
+Factories fill Scrivener models. Sequence numbers start at 1. There is no bundled faker; you return plain attributes so tests stay deterministic.
+
+```ts
+import { defineFactory } from '@avelonjs/assay'
+import { User } from '@/app/Models/User'
+
+const UserFactory = defineFactory(User, (sequence) => ({
+  id: `user-${sequence}`,
+  email: `user-${sequence}@example.test`,
+  name: `User ${sequence}`,
+}))
+
+UserFactory.state('ada', () => ({ name: 'Ada Lovelace', email: 'ada@example.test' }))
+
+await UserFactory.make()
+await UserFactory.create({ name: 'Ada' })
+await UserFactory.as('ada').create()
+await UserFactory.createMany(3)
+```
+
+## Seeds
+
+Seeds are ordinary modules with a default export. `reeve db:seed` and `runSeeds(dir)` load `database/seeds` in filename order.
+
+```ts
+import { defineSeed } from '@avelonjs/assay'
+
+export default defineSeed(async () => {
+  await UserFactory.createMany(5)
+}, 'users')
+```
+
+```ts
+import { runSeed, runSeeds } from '@avelonjs/assay'
+
+await runSeed(seed)
+await runSeeds('database/seeds')
+```
+
+## Method Reference
+
+| Method / export                | Signature                                           | Description                                               |
+| ------------------------------ | --------------------------------------------------- | --------------------------------------------------------- |
+| `assay`                        | `(options: AssayOptions) => AssayClient`            | Creates an HTTP client bound to a kernel and route table. |
+| `AssayClient.get`              | `(path, headers?) => Promise<AssayResponse>`        | Dispatches GET.                                           |
+| `AssayClient.post`             | `(path, body?, headers?) => Promise<AssayResponse>` | Dispatches POST.                                          |
+| `AssayClient.put`              | `(path, body?, headers?) => Promise<AssayResponse>` | Dispatches PUT.                                           |
+| `AssayClient.patch`            | `(path, body?, headers?) => Promise<AssayResponse>` | Dispatches PATCH.                                         |
+| `AssayClient.delete`           | `(path, headers?) => Promise<AssayResponse>`        | Dispatches DELETE.                                        |
+| `AssayClient.call`             | `(name, request) => Promise<AssayResponse>`         | Dispatches a named route with an existing `HttpRequest`.  |
+| `AssayClient.actingAs`         | `(actor: { id: string } \| string) => this`         | Sets the actor cookie for subsequent requests.            |
+| `AssayClient.asGuest`          | `() => this`                                        | Clears actor cookies.                                     |
+| `AssayResponse.assertOk`       | `() => this`                                        | Fails unless the outcome is 2xx and not a failed action.  |
+| `AssayResponse.assertStatus`   | `(expected: number) => this`                        | Fails unless the status hint equals `expected`.           |
+| `AssayResponse.assertRedirect` | `(location: string) => this`                        | Fails unless the kernel redirected to `location`.         |
+| `AssayResponse.assertView`     | `(view: unknown) => this`                           | Fails unless the kernel rendered `view`.                  |
+| `AssayResponse.status`         | `() => number`                                      | Returns the transport-neutral status hint.                |
+| `AssayResponse.view`           | `() => ViewResult`                                  | Returns the view result or throws.                        |
+| `AssayResponse.data`           | `() => unknown`                                     | Returns action data or view props.                        |
+| `AssayResponse.result`         | `KernelResult`                                      | Underlying kernel result.                                 |
+| `AssayAssertion`               | `class AssayAssertion extends Error`                | Thrown when an assertion does not hold.                   |
+| `matchRoute`                   | `(routes, method, path) => { route, params }`       | Resolves a path, preferring static segments.              |
+| `httpRequest`                  | `(overrides?) => HttpRequest`                       | Builds a kernel request with test defaults.               |
+| `parsePath`                    | `(path: string) => { pathname, query }`             | Splits path and query, preserving repeated keys.          |
+| `requestFromCall`              | `(options) => HttpRequest`                          | Builds a request for an HTTP helper call.                 |
+| `encodeBody`                   | `(body: unknown) => Uint8Array`                     | Encodes a body for `rawBody()`.                           |
+| `defineFactory`                | `(model, definition) => Factory`                    | Creates a model factory.                                  |
+| `Factory.make`                 | `(overrides?) => Promise<TModel>`                   | Builds a model without persisting.                        |
+| `Factory.create`               | `(overrides?) => Promise<TModel>`                   | Persists one model.                                       |
+| `Factory.createMany`           | `(count, overrides?) => Promise<readonly TModel[]>` | Persists `count` models.                                  |
+| `Factory.state`                | `(name, attributes) => this`                        | Registers a named attribute overlay.                      |
+| `Factory.as`                   | `(name: string) => this`                            | Applies a named state to the next make/create.            |
+| `Factory.reset`                | `() => void`                                        | Clears sequence and pending states.                       |
+| `Factory.sequence`             | `number`                                            | Current sequence number.                                  |
+| `defineSeed`                   | `(run, name?) => Seed`                              | Wraps a seed callback.                                    |
+| `runSeed`                      | `(seed, context?) => Promise<void>`                 | Runs one seed.                                            |
+| `runSeeds`                     | `(dir: string) => Promise<readonly string[]>`       | Imports and runs default exports in filename order.       |
+| `AssayOptions`                 | `interface`                                         | Kernel, routes, and optional actor cookie name.           |
+| `Seed`                         | `interface`                                         | Named seed with a `run` callback.                         |
+| `FactoryDefinition`            | `type`                                              | `(sequence) => attributes` factory callback.              |
+| `FactoryState`                 | `type`                                              | `() => attributes` overlay registered with `Factory.state`. |
+| `SeedCallback`                 | `type`                                              | `(context: SeedContext) => Promise<void> \| void` seed body. |
+| `SeedContext`                  | `interface`                                         | Optional `path` of a seed file loaded from disk.          |
+
+## Testing
+
+Assay is itself tested with `FakeDatabase` and `createKernel`. Point `assay()` at the same kernel your adapter mounts.
+
+```ts
+import { assay } from '@avelonjs/assay'
+import { FakeDatabase } from '@avelonjs/conformance'
+
+const client = assay({ kernel, routes })
+await client.get('/users').assertOk()
+```
+
+```sh
+bun test
+bun run typecheck
+```

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@avelonjs/assay",
+  "version": "0.1.0",
+  "private": false,
+  "description": "Test harness with HTTP helpers, factories, and seeds for Avelon applications.",
+  "license": "MIT",
+  "author": "Ryan Yannelli <ryanyannelli@gmail.com>",
+  "homepage": "https://github.com/yannelli/avelon",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yannelli/avelon.git",
+    "directory": "packages/assay"
+  },
+  "bugs": {
+    "url": "https://github.com/yannelli/avelon/issues"
+  },
+  "keywords": [
+    "avelon",
+    "typescript",
+    "testing",
+    "harness"
+  ],
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "test": "bun test",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@avelonjs/core": "workspace:*",
+    "@avelonjs/orm": "workspace:*"
+  },
+  "devDependencies": {
+    "@avelonjs/conformance": "workspace:*",
+    "@types/bun": "1.3.14",
+    "typescript": "5.9.3"
+  },
+  "engines": {
+    "bun": ">=1.3.14"
+  }
+}

package/src/factory.ts

@@ -0,0 +1,87 @@
+import { Model } from '@avelonjs/orm'
+
+type Row = Record<string, unknown>
+type ModelCtor = typeof Model & (new () => Model)
+
+/** Definition that produces attributes for one factory sequence number. */
+export type FactoryDefinition<TModel extends Model> = (sequence: number) => Row | Promise<Row>
+
+/** Named attribute overlay registered with {@link Factory.state}. */
+export type FactoryState = () => Row | Promise<Row>
+
+/** Model factory used by tests and seeds. Sequence numbers start at 1. */
+export class Factory<TCtor extends ModelCtor> {
+  #sequence = 0
+  readonly #states = new Map<string, FactoryState>()
+  readonly #active: FactoryState[] = []
+
+  constructor(
+    readonly model: TCtor,
+    readonly definition: FactoryDefinition<InstanceType<TCtor>>,
+  ) {}
+
+  /** Registers a named state that overlays extra attributes. */
+  state(name: string, attributes: FactoryState): this {
+    this.#states.set(name, attributes)
+    return this
+  }
+
+  /** Applies `name` to the next make/create call. */
+  as(name: string): this {
+    const state = this.#states.get(name)
+    if (state === undefined) {
+      throw new Error(`Unknown factory state '${name}'.`)
+    }
+    this.#active.push(state)
+    return this
+  }
+
+  /** Builds attributes without persisting. */
+  async make(overrides: Row = {}): Promise<InstanceType<TCtor>> {
+    const attributes = await this.#attributes(overrides)
+    const model = new this.model() as InstanceType<TCtor>
+    model.fill(attributes)
+    return model
+  }
+
+  /** Persists one model. */
+  async create(overrides: Row = {}): Promise<InstanceType<TCtor>> {
+    const attributes = await this.#attributes(overrides)
+    return this.model.create(attributes) as Promise<InstanceType<TCtor>>
+  }
+
+  /** Persists `count` models. */
+  async createMany(count: number, overrides: Row = {}): Promise<readonly InstanceType<TCtor>[]> {
+    const models: InstanceType<TCtor>[] = []
+    for (let i = 0; i < count; i += 1) models.push(await this.create(overrides))
+    return models
+  }
+
+  /** Current sequence number, including the last make/create. */
+  get sequence(): number {
+    return this.#sequence
+  }
+
+  /** Resets the sequence. Intended for tests. */
+  reset(): void {
+    this.#sequence = 0
+    this.#active.length = 0
+  }
+
+  async #attributes(overrides: Row): Promise<Row> {
+    this.#sequence += 1
+    const layered: Row = { ...(await this.definition(this.#sequence)) }
+    for (const state of this.#active) Object.assign(layered, await state())
+    this.#active.length = 0
+    Object.assign(layered, overrides)
+    return layered
+  }
+}
+
+/** Creates a factory for `model`. Sequence values are unique per factory instance. */
+export function defineFactory<TCtor extends ModelCtor>(
+  model: TCtor,
+  definition: FactoryDefinition<InstanceType<TCtor>>,
+): Factory<TCtor> {
+  return new Factory(model, definition)
+}

package/src/http.ts

@@ -0,0 +1,258 @@
+import {
+  finishResponse,
+  Invalid,
+  type HttpMethod,
+  type HttpRequest,
+  type Kernel,
+  type KernelResult,
+  type RouteDefinition,
+  type ViewResult,
+} from '@avelonjs/core'
+
+import { requestFromCall } from './request'
+
+/** Failure raised when an Assay assertion does not hold. */
+export class AssayAssertion extends Error {
+  /** Creates an assertion failure with a stable name. */
+  constructor(message: string) {
+    super(message)
+    this.name = 'AssayAssertion'
+  }
+}
+
+/** Options for {@link assay}. */
+export interface AssayOptions<TController = unknown> {
+  /** Kernel every helper dispatches through. */
+  kernel: Kernel<TController>
+  /** Route table used to resolve method plus path. */
+  routes: readonly RouteDefinition<TController>[]
+  /** Cookie name written by {@link AssayClient.actingAs}. Defaults to `user`. */
+  actorCookie?: string
+}
+
+function scorePath(pattern: string, pathname: string): number | undefined {
+  const patternParts = pattern.split('/').filter(Boolean)
+  const pathParts = pathname.split('/').filter(Boolean)
+  if (patternParts.length !== pathParts.length) return undefined
+  let score = 0
+  for (let i = 0; i < patternParts.length; i += 1) {
+    const expected = patternParts[i]
+    const actual = pathParts[i]
+    if (expected === undefined || actual === undefined) return undefined
+    if (expected.startsWith('{') && expected.endsWith('}')) continue
+    if (expected !== actual) return undefined
+    score += 1
+  }
+  return score
+}
+
+function extractParams(pattern: string, pathname: string): Record<string, string> {
+  const params: Record<string, string> = {}
+  const patternParts = pattern.split('/').filter(Boolean)
+  const pathParts = pathname.split('/').filter(Boolean)
+  for (let i = 0; i < patternParts.length; i += 1) {
+    const expected = patternParts[i]
+    const actual = pathParts[i]
+    if (expected === undefined || actual === undefined) continue
+    if (expected.startsWith('{') && expected.endsWith('}')) {
+      params[expected.slice(1, -1)] = actual
+    }
+  }
+  return params
+}
+
+function pathnameOf(path: string): string {
+  return new URL(path, 'http://localhost').pathname
+}
+
+/** Resolves a method and path against a route table, preferring static segments. */
+export function matchRoute<TController>(
+  routes: readonly RouteDefinition<TController>[],
+  method: HttpMethod,
+  path: string,
+): { route: RouteDefinition<TController>; params: Record<string, string> } {
+  const pathname = pathnameOf(path)
+  let best: { route: RouteDefinition<TController>; score: number } | undefined
+  for (const route of routes) {
+    if (route.method !== method) continue
+    const score = scorePath(route.path, pathname)
+    if (score === undefined) continue
+    if (best === undefined || score > best.score) best = { route, score }
+  }
+  if (best === undefined) {
+    throw new Invalid(`No ${method} route matches ${pathname}.`, {
+      metadata: { fields: { route: [`${method} ${pathname} is not registered.`] } },
+    })
+  }
+  return { route: best.route, params: extractParams(best.route.path, pathname) }
+}
+
+function statusOf(result: KernelResult): number {
+  if (result.type === 'redirect') return result.status
+  return result.status ?? (result.type === 'action' && !result.ok ? 422 : 200)
+}
+
+/** Kernel result plus assertion helpers used in feature tests. */
+export class AssayResponse {
+  constructor(readonly result: KernelResult) {}
+
+  /** Transport-neutral status hint. */
+  status(): number {
+    return statusOf(this.result)
+  }
+
+  /** Fails unless the status is `expected`. */
+  assertStatus(expected: number): this {
+    const actual = this.status()
+    if (actual !== expected) {
+      throw new AssayAssertion(`Expected status ${expected}, received ${actual}.`)
+    }
+    return this
+  }
+
+  /** Fails unless the response is a successful 2xx outcome. */
+  assertOk(): this {
+    const status = this.status()
+    if (status < 200 || status >= 300) {
+      throw new AssayAssertion(`Expected 2xx, received ${status}.`)
+    }
+    if (this.result.type === 'action' && !this.result.ok) {
+      throw new AssayAssertion('Expected a successful action result.')
+    }
+    return this
+  }
+
+  /** Fails unless the kernel redirected to `location`. */
+  assertRedirect(location: string): this {
+    if (this.result.type !== 'redirect') {
+      throw new AssayAssertion(`Expected a redirect, received ${this.result.type}.`)
+    }
+    if (this.result.location !== location) {
+      throw new AssayAssertion(`Expected redirect ${location}, received ${this.result.location}.`)
+    }
+    return this
+  }
+
+  /** Fails unless the kernel rendered `view`. */
+  assertView(view: unknown): this {
+    if (this.result.type !== 'view') {
+      throw new AssayAssertion(`Expected a view, received ${this.result.type}.`)
+    }
+    if (this.result.view !== view) {
+      throw new AssayAssertion(
+        `Expected view ${String(view)}, received ${String(this.result.view)}.`,
+      )
+    }
+    return this
+  }
+
+  /** View result when the kernel rendered one. */
+  view(): ViewResult<unknown, object> {
+    if (this.result.type !== 'view') {
+      throw new AssayAssertion(`Expected a view, received ${this.result.type}.`)
+    }
+    return this.result
+  }
+
+  /** Serializable action/view payload. */
+  data(): unknown {
+    if (this.result.type === 'action') return this.result.data
+    if (this.result.type === 'view') return this.result.props
+    return undefined
+  }
+}
+
+/** HTTP test client that dispatches through the core kernel. */
+export class AssayClient<TController = unknown> {
+  #cookies: Record<string, string> = {}
+
+  constructor(private readonly options: AssayOptions<TController>) {}
+
+  /** Sets the actor cookie used by subsequent requests. */
+  actingAs(actor: { readonly id: string } | string): this {
+    const id = typeof actor === 'string' ? actor : actor.id
+    this.#cookies = { ...this.#cookies, [this.options.actorCookie ?? 'user']: id }
+    return this
+  }
+
+  /** Clears actor cookies. */
+  asGuest(): this {
+    this.#cookies = {}
+    return this
+  }
+
+  /** Dispatches GET. */
+  get(path: string, headers?: Readonly<Record<string, string>>): Promise<AssayResponse> {
+    return this.#dispatch('GET', path, undefined, headers)
+  }
+
+  /** Dispatches POST. */
+  post(
+    path: string,
+    body?: unknown,
+    headers?: Readonly<Record<string, string>>,
+  ): Promise<AssayResponse> {
+    return this.#dispatch('POST', path, body, headers)
+  }
+
+  /** Dispatches PUT. */
+  put(
+    path: string,
+    body?: unknown,
+    headers?: Readonly<Record<string, string>>,
+  ): Promise<AssayResponse> {
+    return this.#dispatch('PUT', path, body, headers)
+  }
+
+  /** Dispatches PATCH. */
+  patch(
+    path: string,
+    body?: unknown,
+    headers?: Readonly<Record<string, string>>,
+  ): Promise<AssayResponse> {
+    return this.#dispatch('PATCH', path, body, headers)
+  }
+
+  /** Dispatches DELETE. */
+  delete(path: string, headers?: Readonly<Record<string, string>>): Promise<AssayResponse> {
+    return this.#dispatch('DELETE', path, undefined, headers)
+  }
+
+  /** Dispatches an already-built kernel request against a named route. */
+  async call(routeName: string, request: HttpRequest): Promise<AssayResponse> {
+    const route = this.options.routes.find((entry) => entry.name === routeName)
+    if (route === undefined) {
+      throw new Invalid(`Route ${routeName} was not found.`, {
+        metadata: { fields: { route: [`${routeName} is not registered.`] } },
+      })
+    }
+    const result = await this.options.kernel.dispatch(route, request)
+    await finishResponse()
+    return new AssayResponse(result)
+  }
+
+  async #dispatch(
+    method: HttpMethod,
+    path: string,
+    body: unknown,
+    headers?: Readonly<Record<string, string>>,
+  ): Promise<AssayResponse> {
+    const matched = matchRoute(this.options.routes, method, path)
+    const request = requestFromCall({
+      method,
+      path,
+      body,
+      headers,
+      cookies: this.#cookies,
+      params: matched.params,
+    })
+    const result = await this.options.kernel.dispatch(matched.route, request)
+    await finishResponse()
+    return new AssayResponse(result)
+  }
+}
+
+/** Creates an HTTP test client bound to a kernel and route table. */
+export function assay<TController>(options: AssayOptions<TController>): AssayClient<TController> {
+  return new AssayClient(options)
+}

package/src/index.ts

@@ -0,0 +1,7 @@
+export { assay, AssayAssertion, AssayClient, AssayResponse, matchRoute } from './http'
+export type { AssayOptions } from './http'
+export { defineFactory, Factory } from './factory'
+export type { FactoryDefinition, FactoryState } from './factory'
+export { defineSeed, runSeed, runSeeds } from './seed'
+export type { Seed, SeedCallback, SeedContext } from './seed'
+export { encodeBody, httpRequest, parsePath, requestFromCall } from './request'

package/src/request.ts

@@ -0,0 +1,64 @@
+import type { HttpMethod, HttpRequest } from '@avelonjs/core'
+
+/** Builds a kernel `HttpRequest` with test-sensible defaults. */
+export function httpRequest(overrides: Partial<HttpRequest> = {}): HttpRequest {
+  return {
+    method: 'GET',
+    url: 'http://localhost/',
+    params: {},
+    query: {},
+    headers: {},
+    cookies: {},
+    body: null,
+    rawBody: async () => new Uint8Array(),
+    aborted: false,
+    ...overrides,
+  }
+}
+
+/** Parses `path?a=1&b=2` into pathname plus query map, preserving repeated keys. */
+export function parsePath(path: string): {
+  pathname: string
+  query: Record<string, string | readonly string[]>
+} {
+  const url = new URL(path, 'http://localhost')
+  const query: Record<string, string | string[]> = {}
+  for (const [key, value] of url.searchParams.entries()) {
+    const existing = query[key]
+    if (existing === undefined) query[key] = value
+    else if (typeof existing === 'string') query[key] = [existing, value]
+    else existing.push(value)
+  }
+  return { pathname: url.pathname, query }
+}
+
+/** Encodes a request body as UTF-8 bytes for `rawBody()`. */
+export function encodeBody(body: unknown): Uint8Array {
+  if (body === null || body === undefined) return new Uint8Array()
+  if (body instanceof Uint8Array) return body
+  if (typeof body === 'string') return new TextEncoder().encode(body)
+  return new TextEncoder().encode(JSON.stringify(body))
+}
+
+/** Builds a request for an HTTP helper call. */
+export function requestFromCall(options: {
+  method: HttpMethod
+  path: string
+  body?: unknown
+  headers?: Readonly<Record<string, string>>
+  cookies?: Readonly<Record<string, string>>
+  params?: Readonly<Record<string, string>>
+}): HttpRequest {
+  const parsed = parsePath(options.path)
+  const raw = encodeBody(options.body)
+  return httpRequest({
+    method: options.method,
+    url: new URL(options.path, 'http://localhost').toString(),
+    params: options.params ?? {},
+    query: parsed.query,
+    headers: options.headers ?? {},
+    cookies: options.cookies ?? {},
+    body: options.body ?? null,
+    rawBody: async () => raw,
+  })
+}

package/src/seed.ts

@@ -0,0 +1,52 @@
+import { readdir } from 'node:fs/promises'
+import { join } from 'node:path'
+
+/** Context passed to a seed callback. */
+export interface SeedContext {
+  /** Absolute path of the seed file when loaded from disk. */
+  path?: string
+}
+
+/** Seed callback that inserts fixture data. */
+export type SeedCallback = (context: SeedContext) => Promise<void> | void
+
+/** Named seed used by `reeve db:seed` and {@link runSeed}. */
+export interface Seed {
+  /** Optional name printed in logs. */
+  name?: string
+  /** Inserts rows. */
+  run: SeedCallback
+}
+
+/** Wraps a seed callback so default exports stay typed. */
+export function defineSeed(run: SeedCallback, name?: string): Seed {
+  return { name, run }
+}
+
+/** Runs one seed. */
+export async function runSeed(seed: Seed | SeedCallback, context: SeedContext = {}): Promise<void> {
+  if (typeof seed === 'function') {
+    await seed(context)
+    return
+  }
+  await seed.run(context)
+}
+
+function isSeedModule(value: unknown): value is { default?: Seed | SeedCallback } {
+  return typeof value === 'object' && value !== null
+}
+
+/** Loads `database/seeds` (or `dir`) and runs each default export in filename order. */
+export async function runSeeds(dir: string): Promise<readonly string[]> {
+  const entries = await readdir(dir)
+  const files = entries.filter((name) => name.endsWith('.ts') || name.endsWith('.js')).sort()
+  const ran: string[] = []
+  for (const file of files) {
+    const path = join(dir, file)
+    const loaded: unknown = await import(path)
+    if (!isSeedModule(loaded) || loaded.default === undefined) continue
+    await runSeed(loaded.default, { path })
+    ran.push(path)
+  }
+  return ran
+}