API Reference

@fossyl/core

Runtime Functions

createRouter<BasePath>(path: BasePath): Router<BasePath>

Creates a new router scoped to a base path. The BasePath type parameter locks the URL prefix at the type level.

executeRoute(route, req, extract, db?)

Executes a single route against an incoming request. Low-level entry point for custom server adapters.

defineConfig(options)

Defines type-safe fossyl configuration. Accepts a FossylConfig object.

authWrapper<T>(auth: T): T & Authentication

Wraps an authentication function so it satisfies the Authentication interface at the type level.

Types

type Router<BasePath extends string> = {
  createEndpoint<Path extends `${BasePath}${string}`>(path: Path) => Endpoint<Path>: <Path extends `${BasePath}${string}`>(pathPath: Path) => Endpoint<Path>
  createSubrouter<Path extends `${BasePath}${string}`>(path: Path) => Router<Path>: <Path extends `${BasePath}${string}`>(pathPath: Path) => Router<Path>
}

type Endpoint<Path, HasTransactions>  // entry point to the builder chain

type Route = {
  pathPath: string
  method: RestMethod
  steps: unknown[]
  handler: Handler<any, any, any, any>
  authenticator?: AuthenticationFunction<any>
  validator?: ValidatorFunction<any>
  queryValidator?: ValidatorFunction<any>
  urlParamValidator?: ValidatorFunction<any>
  paginationConfig?: PaginationConfig
  hasTransaction: boolean
}

type RestMethod = "GET" | "POST" | "PUT" | "DELETE"

type BodySupportedMethods = "POST" | "PUT"

type Handler<P, Response, RequestBody, Auth>

type Authentication  // interface for auth functions
type ResponseData<TypeName>
type Params<Path>    // extracts URL params from a path string

type PaginationParams
type PaginationConfig
type PaginatedResponse<T>

type ValidatorFunction<T>
type AuthenticationFunction<T>

type RequestExtractor<T>

type FrameworkAdapter
type DatabaseAdapter
type DatabaseContext
type ValidationAdapter
type LoggerAdapter
type Logger
type HttpMethod

type FossylConfig
type AdaptersConfig

Builder State Types

These mark the current state of an endpoint builder chain:

• OpenRouter — base state, no auth or body validation. Exposes .authenticator(), .validator(), and all HTTP methods.
• AuthenticatedRouter — auth middleware applied. Can add body validation or produce a route via any HTTP method.
• ValidatedRouter — body validator applied. Only .post() and .put() available.
• FullRouter — both auth and body validation applied. Only .post() and .put() available.
• QueryableRouter — query validator applied. Adds .paginate() to the OpenRouter interface.
• PaginatedRouter — pagination config applied. Type alias for OpenRouter with pagination bound.

Not Exported from @fossyl/core

• RequestBody — used internally for typed request bodies
• bodyWrapper — internal utility for body parsing (defined in source, not re-exported)

---

@fossyl/express

Functions

expressAdapter(options?: ExpressAdapterOptions): FrameworkAdapter

Creates a framework adapter for Express. Wires middleware, error handling, and context extraction.

getContext(): RequestContext | undefinedundefined
getLogger() => {
  info: (msg: string, meta?: any) => void
  warn: (msg: string, meta?: any) => void
  error: (msg: string, meta?: any) => void
}(): LoggerContext | undefinedundefined
getRequestId(): string | undefinedundefined
getDb(): DatabaseContext | undefinedundefined

Async-local helpers to access request-scoped values anywhere in the call stack.

Classes

AuthenticationError  // extends Error
ValidationError      // extends Error

Utilities

wrapResponse<T>(dataT: T): ApiResponse<T>

Wraps a non-paginated response body in the standard ApiResponse envelope.

Exports

createErrorResponse(status: number, code: ErrorCode, messagestring | undefined: string): ErrorResponse

ERROR_CODES        // enum-like object of known error codes
type ErrorCode     // union type of error code strings
type ErrorResponse // shape of error response body
type RequestContext
type LoggerContext

---

@fossyl/zod

zodValidator<T>(schema: T): (dataT: unknown) => z.infer<T>

Creates a body validator from a Zod schema. The returned function validates data and returns the inferred output type.

zodQueryValidator<T>(schema: T): (dataT: unknown) => z.infer<T>

Same as zodValidator but for query parameter validation.

---

@fossyl/kysely

Functions

kyselyAdapter(options?: KyselyAdapterOptions): DatabaseAdapter

Creates a database adapter backed by Kysely. Handles connection lifecycle and transaction boundaries.

getDb(): DatabaseConnection | undefinedundefined
getTransaction(): Transaction | undefinedundefined

Retrieve the current Kysely instance or active transaction from async context.

transactionContext<T>(fn: () => Promise<T>): Promise<T>

Runs fn inside a database transaction, accessible via getTransaction().

setBaseClient(db: Kysely<any>): void
createDbProxy(): Kysely<any>

createMigrationProvider(migrations: KyselyMigration[]): MigrationProvider
defineMigration(migration: KyselyMigration): KyselyMigration
runMigrations(db: Kysely<any>, provider: MigrationProvider): Promise<MigrationResult[]>
rollbackMigration(db: Kysely<any>, provider: MigrationProvider): Promise<MigrationResult>
getMigrationStatus(db: Kysely<any>, provider: MigrationProvider): Promise<MigrationRecord[]>

Migration utilities wrapping Kysely’s built-in Migrator.

Types

type KyselyAdapterOptions  // adapter configuration

type KyselyMigration = {
  namestring: string
  up(db: Kysely<any>) => {
  new (
    executor: (
      resolve: (value: void | PromiseLike<void>) => void,
      reject: (reason?: any) => void,
    ) => void,
  ): Promise<void>
  all<T>(values: Iterable<T | PromiseLike<T>>): Promise<Awaited<T>[]>
  all<T extends readonly unknown[] | []>(
    values: T,
  ): Promise<{ -readonly [P in keyof T]: Awaited<T[P]> }>
  race<T>(values: Iterable<T | PromiseLike<T>>): Promise<Awaited<T>>
  race<T extends readonly unknown[] | []>(
    values: T,
  ): Promise<Awaited<T[number]>>
  readonly prototype: Promise<any>
  reject<T = never>(reason?: any): Promise<T>
  resolve(): Promise<void>
  resolve<T>(value: T): Promise<Awaited<T>>
  resolve<T>(value: T | PromiseLike<T>): Promise<Awaited<T>>
  allSettled<T extends readonly unknown[] | []>(
    values: T,
  ): Promise<{ -readonly [P in keyof T]: PromiseSettledResult<Awaited<T[P]>> }>
  allSettled<T>(
    values: Iterable<T | PromiseLike<T>>,
  ): Promise<PromiseSettledResult<Awaited<T>>[]>
  any<T extends readonly unknown[] | []>(values: T): Promise<Awaited<T[number]>>
  any<T>(values: Iterable<T | PromiseLike<T>>): Promise<Awaited<T>>
  withResolvers<T>(): PromiseWithResolvers<T>
  try<T, U extends unknown[]>(
    callbackFn: (...args: U) => T | PromiseLike<T>,
    ...args: U
  ): Promise<Awaited<T>>
  readonly [Symbol.species]: PromiseConstructor
}: (dbKysely<any>: Kysely<any>) => Promise<void>
  down(db: Kysely<any>) => {
  new (
    executor: (
      resolve: (value: void | PromiseLike<void>) => void,
      reject: (reason?: any) => void,
    ) => void,
  ): Promise<void>
  all<T>(values: Iterable<T | PromiseLike<T>>): Promise<Awaited<T>[]>
  all<T extends readonly unknown[] | []>(
    values: T,
  ): Promise<{ -readonly [P in keyof T]: Awaited<T[P]> }>
  race<T>(values: Iterable<T | PromiseLike<T>>): Promise<Awaited<T>>
  race<T extends readonly unknown[] | []>(
    values: T,
  ): Promise<Awaited<T[number]>>
  readonly prototype: Promise<any>
  reject<T = never>(reason?: any): Promise<T>
  resolve(): Promise<void>
  resolve<T>(value: T): Promise<Awaited<T>>
  resolve<T>(value: T | PromiseLike<T>): Promise<Awaited<T>>
  allSettled<T extends readonly unknown[] | []>(
    values: T,
  ): Promise<{ -readonly [P in keyof T]: PromiseSettledResult<Awaited<T[P]>> }>
  allSettled<T>(
    values: Iterable<T | PromiseLike<T>>,
  ): Promise<PromiseSettledResult<Awaited<T>>[]>
  any<T extends readonly unknown[] | []>(values: T): Promise<Awaited<T[number]>>
  any<T>(values: Iterable<T | PromiseLike<T>>): Promise<Awaited<T>>
  withResolvers<T>(): PromiseWithResolvers<T>
  try<T, U extends unknown[]>(
    callbackFn: (...args: U) => T | PromiseLike<T>,
    ...args: U
  ): Promise<Awaited<T>>
  readonly [Symbol.species]: PromiseConstructor
}?: (dbKysely<any>: Kysely<any>) => Promise<void>
}

type MigrationRecord = {
  namestring: string
  executedAtDate: DateDateConstructor
}

type MigrationResult = {
  namestring: string
  direction"Up" | "Down": "Up" | "Down"
  status"Executed" | "Error" | "NotExecuted": "Executed" | "Error" | "NotExecuted"
}

type TransactionContext  // exposed via getTransaction()