@taserjs/router 0.0.0

package/src/types/returns.ts

@@ -0,0 +1,135 @@
+import type { ReplyOf } from '@taserjs/router-utils'
+
+import type { Simplify } from './type-utils.js'
+import type { Schema } from './schema.js'
+import type { InferOutput } from './schema.js'
+
+/**
+ * Known HTTP status codes. `number & {}` allows custom codes while keeping
+ * literal autocomplete / inference for well-known values.
+ */
+export type StatusCode
+  = | 100
+    | 101
+    | 102
+    | 103
+    | 200
+    | 201
+    | 202
+    | 203
+    | 204
+    | 205
+    | 206
+    | 207
+    | 208
+    | 226
+    | 300
+    | 301
+    | 302
+    | 303
+    | 304
+    | 305
+    | 306
+    | 307
+    | 308
+    | 400
+    | 401
+    | 402
+    | 403
+    | 404
+    | 405
+    | 406
+    | 407
+    | 408
+    | 409
+    | 410
+    | 411
+    | 412
+    | 413
+    | 414
+    | 415
+    | 416
+    | 417
+    | 418
+    | 421
+    | 422
+    | 423
+    | 424
+    | 425
+    | 426
+    | 428
+    | 429
+    | 431
+    | 451
+    | 500
+    | 501
+    | 502
+    | 503
+    | 504
+    | 505
+    | 506
+    | 507
+    | 508
+    | 510
+    | 511
+    | (number & {})
+
+/** Status-code → Standard Schema map for route/middleware/handler outputs. */
+export type ReturnsMap = {
+  readonly [K in StatusCode]?: Schema<unknown>
+}
+
+/** Later map wins on overlapping status keys. */
+export type MergeReturns<
+  A extends ReturnsMap,
+  B extends ReturnsMap,
+> = Omit<A, keyof B> & B
+
+/** Typed reply union for statuses declared in a returns map. */
+export type ReplyResultFor<M extends ReturnsMap> = {
+  [S in keyof M]-?: S extends StatusCode
+    ? M[S] extends Schema<unknown>
+      ? ReplyOf<S, Simplify<InferOutput<M[S]>>>
+      : never
+    : never
+}[keyof M]
+
+export type EmptyReturns = {}
+
+/** True when no status schemas have been declared yet. */
+export type HasReturns<M extends ReturnsMap> = [keyof M] extends [never] ? false : true
+
+/**
+ * Validate a concrete reply `R` against returns map `M`.
+ * Declared statuses must match schema output; undeclared statuses stay open
+ * (same rule as runtime `validateReply`).
+ */
+export type ValidHandlerReply<R, M extends ReturnsMap> = R extends ReplyOf<infer S, infer B>
+  ? S extends keyof M
+    ? M[S] extends Schema<unknown>
+      ? B extends Simplify<InferOutput<M[S]>>
+        ? R
+        : never
+      : R
+    : R
+  : R extends Response
+    ? R
+    : never
+
+/**
+ * Narrow a handler return so declared statuses are schema-checked without
+ * breaking multi-status unions (avoids circular `R extends …<R>` constraints).
+ */
+export type EnforceHandlerReply<R, M extends ReturnsMap>
+  = [R] extends [ValidHandlerReply<R, M>]
+    ? R
+    : ValidHandlerReply<R, M>
+
+/**
+ * Expected `.handler` return type for a returns map.
+ * Prefer constraining handler generics with {@link EnforceHandlerReply}.
+ */
+export type HandlerReply<M extends ReturnsMap>
+  = HasReturns<M> extends true
+    ? ReplyResultFor<M> | Response
+    : Response

package/src/types/schema.ts

@@ -0,0 +1,22 @@
+import type { StandardSchemaV1 } from '@standard-schema/spec'
+
+import type { RequestShape } from './type-utils.js'
+
+export type { StandardSchemaV1 } from '@standard-schema/spec'
+
+/**
+ * A Standard Schema validator.
+ * `TOutput` is the validated/output type; `TInput` is the pre-parse input (request shape).
+ */
+export type Schema<TOutput = unknown, TInput = unknown> = StandardSchemaV1<TInput, TOutput>
+
+/** Infers the output type from a Standard Schema. */
+export type InferOutput<S> = S extends StandardSchemaV1<unknown, infer O> ? O : never
+
+/** Infers the input type from a Standard Schema. */
+export type InferInput<S> = S extends StandardSchemaV1<infer I, unknown> ? I : never
+
+/** Pre-parse request shape from a Standard Schema. */
+export type SchemaRequestShape<S> = S extends StandardSchemaV1<infer I, infer O>
+  ? RequestShape<I, O>
+  : S

package/src/types/type-utils.ts

@@ -0,0 +1,86 @@
+export type Method = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'OPTIONS' | 'HEAD'
+export type HttpMethod = Method
+
+export type MiddlewareFieldName
+  = | 'query'
+    | 'params'
+    | 'body'
+    | 'state'
+    | 'ctx'
+
+export type MiddlewareInputFieldName = 'query' | 'params' | 'body'
+
+export type UnwrapPart<T> = unknown extends T ? {} : T
+
+export type MergePart<T, Base> = unknown extends T ? Base : Base & T
+
+/** Collapse intersections so `Omit`/`keyof` treat the result as one object type. */
+export type Simplify<T> = { [K in keyof T]: T[K] } & {}
+
+/**
+ * Request prop: when schema input is `unknown` (e.g. zod coerce),
+ * fall back to the validated output type.
+ */
+type RequestPropType<TIn, TOut> = [unknown] extends [Exclude<TIn, undefined>]
+  ? TOut
+  : TIn
+
+/**
+ * Pre-parse request shape. Prefer input types (defaults → optional),
+ * but replace `unknown` input props with output types.
+ */
+export type RequestShape<TIn, TOut> = unknown extends TIn
+  ? UnwrapPart<TOut>
+  : Simplify<{
+    [K in keyof TIn]: K extends keyof TOut
+      ? RequestPropType<TIn[K], TOut[K]>
+      : TIn[K]
+  }>
+
+export type UnionToIntersection<U>
+  = (U extends unknown ? (value: U) => void : never) extends (value: infer Value) => void ? Value : never
+
+export type MiddlewareField<
+  Middleware,
+  Field extends MiddlewareFieldName,
+> = Field extends 'query'
+  ? Middleware extends { query: infer Query } ? Query : {}
+  : Field extends 'params'
+    ? Middleware extends { params: infer Params } ? Params : {}
+    : Field extends 'body'
+      ? Middleware extends { body: infer Body } ? Body : {}
+      : Field extends 'state'
+        ? Middleware extends { state: infer State } ? State : {}
+        : Field extends 'ctx'
+          ? Middleware extends { ctx: infer Ctx } ? Ctx : {}
+          : {}
+
+export type MiddlewareInputField<
+  Middleware,
+  Field extends MiddlewareInputFieldName,
+> = Middleware extends { input: { [K in Field]: infer V } } ? V : {}
+
+export type MergeMiddlewareField<
+  Middlewares extends readonly unknown[],
+  Field extends MiddlewareFieldName,
+> = [Middlewares] extends [readonly []]
+  ? {}
+  : UnionToIntersection<MiddlewareField<Middlewares[number], Field>>
+
+export type MergeMiddlewareInputField<
+  Middlewares extends readonly unknown[],
+  Field extends MiddlewareInputFieldName,
+> = [Middlewares] extends [readonly []]
+  ? {}
+  : UnionToIntersection<MiddlewareInputField<Middlewares[number], Field>>
+
+export type RuntimeContextFields<TNative = unknown> = {
+  request: Request
+  method: Method
+  url: URL
+  headers: import('@taserjs/router-core').TaserHeaders
+  cookies: import('@taserjs/router-core').TaserCookieJar
+  reply: typeof import('@taserjs/router-utils').reply
+  var: Record<string, unknown>
+  native?: TNative
+}

package/src/types/units.ts

@@ -0,0 +1,167 @@
+import type { Awaitable, TaserCookieJar, TaserHeaders } from '@taserjs/router-core'
+import type { ReplyResult } from '@taserjs/router-utils'
+
+import type { RouterRegister } from '../register.js'
+import type {
+  MergeMiddlewareField,
+  MergePart,
+  RequestShape,
+  RuntimeContextFields,
+  Simplify,
+  UnwrapPart,
+} from './type-utils.js'
+import type { ReturnsMap } from './returns.js'
+import type { Schema } from './schema.js'
+
+export type { HttpMethod, Method } from './type-utils.js'
+export type { EmptyReturns, MergeReturns, ReturnsMap, HandlerReply, HasReturns, StatusCode, ValidHandlerReply, EnforceHandlerReply } from './returns.js'
+
+/** Default empty app context for standalone units without a bound router instance. */
+export type AppContext = Record<never, never>
+
+export type NativeContext = RouterRegister extends { NativeContext: infer N } ? N : unknown
+
+export type ValidatorParts = {
+  query?: unknown
+  params?: unknown
+  body?: unknown
+  queryIn?: unknown
+  paramsIn?: unknown
+  bodyIn?: unknown
+}
+
+export type MiddlewareNext = {
+  (args?: { state?: unknown, ctx?: unknown }): Promise<ReplyResult>
+}
+
+export type MiddlewareDefinition = {
+  state?: unknown
+  ctx?: unknown
+  query?: unknown
+  params?: unknown
+  body?: unknown
+  returns?: ReturnsMap
+  handler: (
+    ctx: unknown,
+    next: MiddlewareNext,
+  ) => Awaitable<ReplyResult | Response | unknown>
+}
+
+export type MiddlewareReturnFromParts<
+  TQuery,
+  TParams,
+  TBody,
+  TState,
+  TCtx = unknown,
+  TQueryIn = TQuery,
+  TParamsIn = TParams,
+  TBodyIn = TBody,
+> = {
+  query: Simplify<UnwrapPart<TQuery>>
+  params: Simplify<UnwrapPart<TParams>>
+  body: Simplify<UnwrapPart<TBody>>
+  state: Simplify<UnwrapPart<TState>>
+  ctx: Simplify<UnwrapPart<TCtx>>
+  /** Pre-parse shapes merged into route `$Infer.Input`. */
+  input: {
+    query: RequestShape<TQueryIn, TQuery>
+    params: RequestShape<TParamsIn, TParams>
+    body: RequestShape<TBodyIn, TBody>
+  }
+}
+
+type UnitRuntimeContext = RuntimeContextFields<NativeContext>
+
+export type StandaloneMiddlewareContext<
+  TQuery = unknown,
+  TParams = unknown,
+  TBody = unknown,
+  TAppContext extends Record<string, unknown> = AppContext,
+> = Simplify<
+  TAppContext & UnitRuntimeContext & {
+    query: Simplify<UnwrapPart<TQuery>>
+    params: Simplify<UnwrapPart<TParams>>
+    body: Simplify<UnwrapPart<TBody>>
+    state: {}
+    headers: TaserHeaders
+    cookies: TaserCookieJar
+  }
+>
+
+export type HandlerContext<
+  Acc extends readonly unknown[],
+  Validators extends ValidatorParts,
+  TAppContext extends Record<string, unknown> = AppContext,
+> = Simplify<
+  TAppContext
+  & UnitRuntimeContext
+  & MergeMiddlewareField<Acc, 'ctx'>
+  & {
+    query: Simplify<MergePart<
+      Validators extends { query?: infer Q } ? Q : unknown,
+      MergeMiddlewareField<Acc, 'query'>
+    >>
+    params: Simplify<MergePart<
+      Validators extends { params?: infer P } ? P : unknown,
+      MergeMiddlewareField<Acc, 'params'>
+    >>
+    body: Simplify<MergePart<
+      Validators extends { body?: infer B } ? B : unknown,
+      MergeMiddlewareField<Acc, 'body'>
+    >>
+    state: Simplify<MergeMiddlewareField<Acc, 'state'>>
+    headers: TaserHeaders
+    cookies: TaserCookieJar
+  }
+>
+
+export type MiddlewareUnit<
+  TAcc = unknown,
+  TReturns extends ReturnsMap = {},
+> = MiddlewareDefinition & {
+  readonly __middlewareAcc: TAcc
+  readonly __returns?: TReturns
+}
+
+export type HandlerUnit<
+  _Acc extends readonly unknown[],
+  _Validators extends ValidatorParts,
+  TReturns extends ReturnsMap = {},
+  TOutput = Response,
+> = {
+  readonly __returns?: TReturns
+  readonly $Infer: {
+    Output: TOutput
+  }
+  middlewares: readonly MiddlewareDefinition[]
+  handler: (ctx: unknown) => Awaitable<ReplyResult | Response>
+  returns?: ReturnsMap
+  query?: Schema<unknown>
+  params?: Schema<unknown>
+  body?: Schema<unknown>
+}
+
+export type InlineMiddlewareOptions = {
+  state?: Schema<unknown>
+  ctx?: Schema<unknown>
+  query?: Schema<unknown>
+  params?: Schema<unknown>
+  body?: Schema<unknown>
+  returns?: ReturnsMap
+  handler: (
+    ctx: unknown,
+    next: MiddlewareNext,
+  ) => Awaitable<unknown>
+}
+
+export function isHandlerUnit(
+  value: unknown,
+): value is HandlerUnit<readonly unknown[], ValidatorParts> {
+  return (
+    typeof value === 'object'
+    && value !== null
+    && 'handler' in value
+    && 'middlewares' in value
+    && Array.isArray((value as HandlerUnit<readonly unknown[], ValidatorParts>).middlewares)
+  )
+}