@taserjs/router 0.0.0

package/src/taser-router.ts

@@ -0,0 +1,160 @@
+import {
+  createTaserRuntime,
+  type NotFoundHandler,
+  type OnErrorHandler,
+  type RouteManifestShape,
+} from '@taserjs/router-core'
+import { normalizeOnError } from '@taserjs/router-utils'
+
+import {
+  createAllRoute,
+  createAnyRoute,
+  createDeleteRoute,
+  createGetRoute,
+  createHeadRoute,
+  createOptionsRoute,
+  createPatchRoute,
+  createPostRoute,
+  createPutRoute,
+} from './factories.js'
+import { defineHandler } from './define/handler.js'
+import { defineMiddleware } from './define/middleware.js'
+import { createMiddleware } from './middleware.js'
+import { TaserApp } from './taser-app.js'
+import type {
+  ContextDefinition,
+  CreateTaserAppOptions,
+  OnErrorOptions,
+} from './types/app.js'
+import type { AppContext } from './types/units.js'
+import type { HandlerBuilder, LayoutId, MiddlewareBuilder } from './types/index.js'
+import type { Schema } from './types/schema.js'
+import type {
+  CreateAllRoute,
+  CreateAnyRoute,
+  CreateWithBodyRoute,
+  CreateWithoutBodyRoute,
+} from './factories.js'
+
+function toOnErrorHandler(
+  onErrorOptions: OnErrorOptions | OnErrorOptions['handle'],
+): OnErrorHandler {
+  return normalizeOnError(onErrorOptions)
+}
+
+type RouterState = {
+  options: CreateTaserAppOptions
+  contextDef: ContextDefinition<Record<string, unknown>, Record<string, unknown>>
+  onError?: OnErrorHandler
+  notFound?: NotFoundHandler
+}
+
+const emptyContext: ContextDefinition<Record<string, unknown>, Record<string, unknown>> = {}
+
+export class TaserRouter<TAppContext extends Record<string, unknown> = AppContext> {
+  private readonly state: RouterState
+
+  constructor(options: CreateTaserAppOptions = {}, state?: Partial<Omit<RouterState, 'options'>>) {
+    this.state = {
+      options,
+      contextDef: state?.contextDef ?? emptyContext,
+      ...(state?.onError !== undefined ? { onError: state.onError } : {}),
+      ...(state?.notFound !== undefined ? { notFound: state.notFound } : {}),
+    }
+  }
+
+  context<
+    TBoot extends Record<string, unknown>,
+    TReq extends Record<string, unknown>,
+  >(definition: ContextDefinition<TBoot, TReq>): TaserRouter<TBoot & TReq> {
+    this.state.contextDef = definition
+    return this as unknown as TaserRouter<TBoot & TReq>
+  }
+
+  onError<TResponses extends import('./types/returns.js').ReturnsMap = import('./types/returns.js').ReturnsMap>(
+    options: OnErrorOptions<TResponses> | OnErrorOptions<TResponses>['handle'],
+  ): this {
+    this.state.onError = toOnErrorHandler(options)
+    return this
+  }
+
+  notFound(
+    handler: (ctx: unknown) => Response | Promise<Response> | unknown,
+  ): this {
+    this.state.notFound = ctx => handler(ctx)
+    return this
+  }
+
+  get: CreateWithoutBodyRoute<'GET', TAppContext> = createGetRoute as CreateWithoutBodyRoute<'GET', TAppContext>
+  post: CreateWithBodyRoute<'POST', TAppContext> = createPostRoute as CreateWithBodyRoute<'POST', TAppContext>
+  put: CreateWithBodyRoute<'PUT', TAppContext> = createPutRoute as CreateWithBodyRoute<'PUT', TAppContext>
+  patch: CreateWithBodyRoute<'PATCH', TAppContext> = createPatchRoute as CreateWithBodyRoute<'PATCH', TAppContext>
+  delete: CreateWithoutBodyRoute<'DELETE', TAppContext> = createDeleteRoute as CreateWithoutBodyRoute<'DELETE', TAppContext>
+  options: CreateWithoutBodyRoute<'OPTIONS', TAppContext> = createOptionsRoute as CreateWithoutBodyRoute<'OPTIONS', TAppContext>
+  head: CreateWithoutBodyRoute<'HEAD', TAppContext> = createHeadRoute as CreateWithoutBodyRoute<'HEAD', TAppContext>
+  any: CreateAnyRoute<TAppContext> = createAnyRoute as CreateAnyRoute<TAppContext>
+  all: CreateAllRoute<TAppContext> = createAllRoute as CreateAllRoute<TAppContext>
+
+  middleware<const Layout extends LayoutId>(layout: Layout): MiddlewareBuilder<Layout, readonly [], TAppContext> {
+    return createMiddleware(layout) as MiddlewareBuilder<Layout, readonly [], TAppContext>
+  }
+
+  defineHandler<
+    TQuery = unknown,
+    TParams = unknown,
+    TBody = unknown,
+  >(
+    options?: {
+      query?: Schema<TQuery>
+      params?: Schema<TParams>
+      body?: Schema<TBody>
+    },
+  ): HandlerBuilder<
+    readonly [],
+    { query: TQuery, params: TParams, body: TBody },
+    {},
+    TAppContext
+  > {
+    return options === undefined
+      ? defineHandler<TAppContext>()
+      : defineHandler<TAppContext>(options)
+  }
+
+  defineMiddleware(): ReturnType<typeof defineMiddleware<TAppContext>> {
+    return defineMiddleware<TAppContext>()
+  }
+
+  create<const TManifest extends RouteManifestShape>(manifest: TManifest): TaserApp<TManifest> {
+    const definition = this.state.contextDef
+    const validateResponse = this.state.options.response?.validate ?? true
+    const onValidationFailure = this.state.options.response?.onValidationFailure
+    const bootPromise = Promise.resolve(
+      // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-assertion
+      definition.boot?.() ?? ({} as Record<string, unknown>),
+    )
+
+    const runtime = createTaserRuntime(
+      manifest,
+      async ({ native }) => {
+        const bootContext = await bootPromise
+        const requestContext = await definition.request?.({ native }) ?? {}
+        return { ...bootContext, ...requestContext }
+      },
+      {
+        response: {
+          validate: validateResponse,
+          ...(onValidationFailure !== undefined ? { onValidationFailure } : {}),
+        },
+        ...(this.state.onError !== undefined ? { onError: this.state.onError } : {}),
+        ...(this.state.notFound !== undefined ? { notFound: this.state.notFound } : {}),
+        ...(this.state.options.cookies !== undefined ? { cookies: this.state.options.cookies } : {}),
+      },
+    )
+
+    return new TaserApp(runtime, manifest)
+  }
+}
+
+export function createTaserApp(options: CreateTaserAppOptions = {}): TaserRouter {
+  return new TaserRouter(options)
+}

package/src/types/app.ts

@@ -0,0 +1,65 @@
+import type { ResponseValidationFailureHandler } from '@taserjs/router-utils'
+
+import type { TaserApp } from '../taser-app.js'
+import type { ReturnsMap } from './returns.js'
+import type { Schema } from './schema.js'
+
+export type CreateTaserAppOptions = {
+  response?: {
+    /** Validate handler replies against returns maps. Default true. */
+    validate?: boolean
+    onValidationFailure?: ResponseValidationFailureHandler
+  }
+  /** Global cookie defaults and signing secret. Per-call `ctx.cookies.set` options override defaults. */
+  cookies?: {
+    secret?: string | BufferSource
+    path?: string
+    httpOnly?: boolean
+    sameSite?: 'Strict' | 'Lax' | 'None' | 'strict' | 'lax' | 'none'
+    secure?: boolean
+    domain?: string
+    maxAge?: number
+    expires?: Date
+  }
+}
+
+export type CreateContextArgs = {
+  native?: import('./units.js').NativeContext
+}
+
+export type ContextDefinition<
+  TBoot extends Record<string, unknown> = Record<string, never>,
+  TReq extends Record<string, unknown> = Record<string, never>,
+> = {
+  boot?: () => TBoot | Promise<TBoot>
+  request?: (args: CreateContextArgs) => TReq | Promise<TReq>
+}
+
+export type InferAppContext<
+  T extends ContextDefinition<Record<string, unknown>, Record<string, unknown>>,
+> = T extends ContextDefinition<infer TBoot, infer TReq> ? TBoot & TReq : Record<string, never>
+
+export type OnErrorOptions<TResponses extends ReturnsMap = ReturnsMap> = {
+  responses?: TResponses
+  handle: (
+    error: unknown,
+    ctx?: unknown,
+  ) => Response | Promise<Response>
+}
+
+export type InferAppManifest<TApp> = TApp extends TaserApp<infer TManifest> ? TManifest : never
+
+export type TaserHandler<TFrameworkApp> = {
+  /**
+   * Mount the Taser handler on a framework app.
+   * Use universal wildcard patterns (`/*`, `/prefix/*`) for Hono/Fastify.
+   * Use framework-native splat patterns for Express (e.g. `/{*splat}`, `/*splat`).
+   */
+  mount(pattern: string, frameworkApp: TFrameworkApp): void
+}
+
+export type { RouteManifestShape } from '@taserjs/router-core'
+
+export type { Schema }
+
+export type { TaserApp, TaserMountedApp, TaserNativeBound } from '../taser-app.js'