@taserjs/router 0.0.0

package/package.json

@@ -0,0 +1,149 @@
+{
+  "name": "@taserjs/router",
+  "version": "0.0.0",
+  "description": "Type-safe Node.js router with runtime validation and middleware",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/cjs/index.cjs",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/esm/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/esm/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/index.d.cts",
+        "default": "./dist/cjs/index.cjs"
+      }
+    },
+    "./body-limit": {
+      "import": {
+        "types": "./dist/esm/middleware/body-limit.d.ts",
+        "default": "./dist/esm/middleware/body-limit.js"
+      },
+      "require": {
+        "types": "./dist/cjs/middleware/body-limit.d.cts",
+        "default": "./dist/cjs/middleware/body-limit.cjs"
+      }
+    },
+    "./compress": {
+      "import": {
+        "types": "./dist/esm/middleware/compress.d.ts",
+        "default": "./dist/esm/middleware/compress.js"
+      },
+      "require": {
+        "types": "./dist/cjs/middleware/compress.d.cts",
+        "default": "./dist/cjs/middleware/compress.cjs"
+      }
+    },
+    "./cors": {
+      "import": {
+        "types": "./dist/esm/middleware/cors.d.ts",
+        "default": "./dist/esm/middleware/cors.js"
+      },
+      "require": {
+        "types": "./dist/cjs/middleware/cors.d.cts",
+        "default": "./dist/cjs/middleware/cors.cjs"
+      }
+    },
+    "./csrf": {
+      "import": {
+        "types": "./dist/esm/middleware/csrf.d.ts",
+        "default": "./dist/esm/middleware/csrf.js"
+      },
+      "require": {
+        "types": "./dist/cjs/middleware/csrf.d.cts",
+        "default": "./dist/cjs/middleware/csrf.cjs"
+      }
+    },
+    "./etag": {
+      "import": {
+        "types": "./dist/esm/middleware/etag.d.ts",
+        "default": "./dist/esm/middleware/etag.js"
+      },
+      "require": {
+        "types": "./dist/cjs/middleware/etag.d.cts",
+        "default": "./dist/cjs/middleware/etag.cjs"
+      }
+    },
+    "./jwk": {
+      "import": {
+        "types": "./dist/esm/middleware/jwk.d.ts",
+        "default": "./dist/esm/middleware/jwk.js"
+      },
+      "require": {
+        "types": "./dist/cjs/middleware/jwk.d.cts",
+        "default": "./dist/cjs/middleware/jwk.cjs"
+      }
+    },
+    "./jwt": {
+      "import": {
+        "types": "./dist/esm/middleware/jwt.d.ts",
+        "default": "./dist/esm/middleware/jwt.js"
+      },
+      "require": {
+        "types": "./dist/cjs/middleware/jwt.d.cts",
+        "default": "./dist/cjs/middleware/jwt.cjs"
+      }
+    },
+    "./secure-headers": {
+      "import": {
+        "types": "./dist/esm/middleware/secure-headers.d.ts",
+        "default": "./dist/esm/middleware/secure-headers.js"
+      },
+      "require": {
+        "types": "./dist/cjs/middleware/secure-headers.d.cts",
+        "default": "./dist/cjs/middleware/secure-headers.cjs"
+      }
+    },
+    "./timing": {
+      "import": {
+        "types": "./dist/esm/middleware/timing.d.ts",
+        "default": "./dist/esm/middleware/timing.js"
+      },
+      "require": {
+        "types": "./dist/cjs/middleware/timing.d.cts",
+        "default": "./dist/cjs/middleware/timing.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "dependencies": {
+    "@standard-schema/spec": "^1.1.0",
+    "hono": "^4.10.3",
+    "@taserjs/router-core": "0.0.0",
+    "@taserjs/router-utils": "0.0.0"
+  },
+  "devDependencies": {
+    "@tanstack/vite-config": "^0.6.0",
+    "publint": "^0.3.22",
+    "vite": "^8.1.5",
+    "vitest": "^4.1.10",
+    "zod": "^4.4.3"
+  },
+  "engines": {
+    "node": ">=20.19"
+  },
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/taserjs/taserjs.git",
+    "directory": "packages/router"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "scripts": {
+    "clean": "rimraf dist",
+    "build": "vite build && publint --strict",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "vitest run"
+  }
+}

package/src/constants.ts

@@ -0,0 +1,10 @@
+/** Input schema keys validated by middleware and route handlers. Headers/cookies are parsed only. */
+export const SCHEMA_KEYS = ['query', 'params', 'body'] as const
+
+export type SchemaKey = (typeof SCHEMA_KEYS)[number]
+
+export const HANDLER_SCHEMA_KEY_MAP = {
+  query: 'handlerQuery',
+  params: 'handlerParams',
+  body: 'handlerBody',
+} as const satisfies Record<SchemaKey, string>

package/src/create-context.ts

@@ -0,0 +1,19 @@
+import type { ReservedContextKey } from '@taserjs/router-core'
+
+import type { ContextDefinition } from './types/app.js'
+
+type NoReservedKeysConstraint<TBoot extends Record<string, unknown>, TReq extends Record<string, unknown>>
+  = Extract<keyof TBoot | keyof TReq, ReservedContextKey> extends never
+    ? unknown
+    : never
+
+export function createContext<
+  TBoot extends Record<string, unknown> = Record<string, never>,
+  TReq extends Record<string, unknown> = Record<string, never>,
+>(
+  definition: ContextDefinition<TBoot, TReq> & NoReservedKeysConstraint<TBoot, TReq>,
+): ContextDefinition<TBoot, TReq> {
+  return definition
+}
+
+export type { ContextDefinition, InferAppContext } from './types/app.js'

package/src/define/handler.ts

@@ -0,0 +1,72 @@
+import type { HandlerBuilder } from '../types/index.js'
+import type {
+  AppContext,
+  HandlerUnit,
+  MiddlewareDefinition,
+  ReturnsMap,
+  ValidatorParts,
+} from '../types/units.js'
+import type { Schema } from '../types/schema.js'
+import { pickDefinedSchemas, type SchemaValidators } from './validators.js'
+import { collectReturnsFromDefinitions } from '@taserjs/router-utils'
+
+function createHandlerBuilder<TAppContext extends Record<string, unknown> = AppContext>(
+  validators: SchemaValidators,
+  middlewares: MiddlewareDefinition[],
+  returnsMap: ReturnsMap,
+): HandlerBuilder<readonly [], ValidatorParts, {}, TAppContext> {
+  const builder = {
+    returns(map: ReturnsMap) {
+      return createHandlerBuilder<TAppContext>(validators, middlewares, { ...returnsMap, ...map })
+    },
+    use(unitOrOptions: MiddlewareDefinition) {
+      middlewares.push(unitOrOptions)
+      return builder
+    },
+    handler(fn: (ctx: unknown) => unknown) {
+      const mwReturns = collectReturnsFromDefinitions(middlewares)
+      const mergedReturns = { ...mwReturns, ...returnsMap }
+      const unit = {
+        $Infer: { Output: undefined as unknown as Response },
+        middlewares: [...middlewares],
+        handler: fn as HandlerUnit<readonly [], ValidatorParts>['handler'],
+        ...pickDefinedSchemas(validators),
+        ...(Object.keys(mergedReturns).length > 0 ? { returns: mergedReturns } : {}),
+      } as HandlerUnit<readonly [], ValidatorParts>
+      return unit
+    },
+  }
+
+  return builder as unknown as HandlerBuilder<readonly [], ValidatorParts, {}, TAppContext>
+}
+
+export function defineHandler<TAppContext extends Record<string, unknown> = AppContext>(): HandlerBuilder<
+  readonly [],
+  {},
+  {},
+  TAppContext
+>
+
+export function defineHandler<
+  TAppContext extends Record<string, unknown> = AppContext,
+  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
+>
+
+export function defineHandler<TAppContext extends Record<string, unknown> = AppContext>(
+  options?: SchemaValidators,
+): HandlerBuilder<readonly [], ValidatorParts, {}, TAppContext> {
+  return createHandlerBuilder<TAppContext>(options ?? {}, [], {})
+}

package/src/define/middleware.ts

@@ -0,0 +1,289 @@
+import type { ReplyResult } from '@taserjs/router-utils'
+import { createTaserCompatHandler } from '@taserjs/router-core'
+
+import type { Awaitable, ReturnsMap } from '../types/index.js'
+import type {
+  AppContext,
+  MiddlewareReturnFromParts,
+  MiddlewareUnit,
+  StandaloneMiddlewareContext,
+} from '../types/units.js'
+import type { Schema } from '../types/schema.js'
+
+type HonoMiddlewareHandler = Parameters<typeof createTaserCompatHandler>[0]
+
+type HonoMiddlewareUnit = MiddlewareUnit<
+  MiddlewareReturnFromParts<unknown, unknown, unknown, {}>
+>
+
+type MiddlewareBuilderState<
+  TQuery = unknown,
+  TParams = unknown,
+  TBody = unknown,
+  TState = unknown,
+  TCtx = unknown,
+  TReturns extends ReturnsMap = {},
+> = {
+  state?: Schema<TState>
+  ctx?: Schema<TCtx>
+  query?: Schema<TQuery>
+  params?: Schema<TParams>
+  body?: Schema<TBody>
+  returns?: TReturns
+}
+
+type FluentNext<TState, TCtx>
+  = [TState] extends [undefined]
+    ? [TCtx] extends [undefined]
+        ? () => Promise<ReplyResult>
+        : (args: { ctx: TCtx }) => Promise<ReplyResult>
+    : [TCtx] extends [undefined]
+        ? (args: { state: TState }) => Promise<ReplyResult>
+        : (args: { state: TState, ctx: TCtx }) => Promise<ReplyResult>
+
+type FluentMiddlewareBuilder<
+  TQuery = unknown,
+  TParams = unknown,
+  TBody = unknown,
+  TState = undefined,
+  TCtx = undefined,
+  TReturns extends ReturnsMap = {},
+  TAppContext extends Record<string, unknown> = AppContext,
+> = {
+  returns<const M extends ReturnsMap>(
+    map: M,
+  ): FluentMiddlewareBuilder<
+    TQuery,
+    TParams,
+    TBody,
+    TState,
+    TCtx,
+    Omit<TReturns, keyof M> & M,
+    TAppContext
+  >
+  handler(
+    fn: (
+      ctx: StandaloneMiddlewareContext<TQuery, TParams, TBody, TAppContext>,
+      next: FluentNext<TState, TCtx>,
+    ) => Awaitable<ReplyResult | Response | unknown>,
+  ): MiddlewareUnit<
+    MiddlewareReturnFromParts<
+      TQuery,
+      TParams,
+      TBody,
+      TState extends undefined ? {} : TState,
+      TCtx extends undefined ? {} : TCtx
+    >,
+    TReturns
+  >
+}
+
+function createFluentBuilder<TAppContext extends Record<string, unknown> = AppContext>(
+  state: MiddlewareBuilderState,
+): FluentMiddlewareBuilder<unknown, unknown, unknown, undefined, undefined, {}, TAppContext> {
+  return {
+    returns(map: ReturnsMap) {
+      return createFluentBuilder<TAppContext>({
+        ...state,
+        returns: { ...(state.returns ?? {}), ...map },
+      })
+    },
+    handler(fn: (...args: never[]) => unknown) {
+      const unit = {
+        ...state,
+        handler: fn,
+        __middlewareAcc: undefined as unknown,
+        ...(state.returns ? { __returns: state.returns } : {}),
+      }
+      return unit as unknown as MiddlewareUnit<
+        MiddlewareReturnFromParts<unknown, unknown, unknown, unknown, unknown>,
+        ReturnsMap
+      >
+    },
+  } as unknown as FluentMiddlewareBuilder<unknown, unknown, unknown, undefined, undefined, {}, TAppContext>
+}
+
+export function defineMiddleware(middleware: HonoMiddlewareHandler): HonoMiddlewareUnit
+
+export function defineMiddleware<
+  TAppContext extends Record<string, unknown> = AppContext,
+  TState = unknown,
+  TCtx = unknown,
+  TQuery = unknown,
+  TParams = unknown,
+  TBody = unknown,
+  TReturns extends ReturnsMap = {},
+>(
+  options: {
+    state: Schema<TState>
+    ctx: Schema<TCtx>
+    query?: Schema<TQuery>
+    params?: Schema<TParams>
+    body?: Schema<TBody>
+    returns?: TReturns
+    handler: (
+      ctx: StandaloneMiddlewareContext<TQuery, TParams, TBody, TAppContext>,
+      next: (args: { state: TState, ctx: TCtx }) => Promise<ReplyResult>,
+    ) => Awaitable<ReplyResult | Response | unknown>
+  },
+): MiddlewareUnit<
+  MiddlewareReturnFromParts<TQuery, TParams, TBody, TState, TCtx>,
+  TReturns
+>
+
+export function defineMiddleware<
+  TAppContext extends Record<string, unknown> = AppContext,
+  TState = unknown,
+  TQuery = unknown,
+  TParams = unknown,
+  TBody = unknown,
+  TReturns extends ReturnsMap = {},
+>(
+  options: {
+    state: Schema<TState>
+    query?: Schema<TQuery>
+    params?: Schema<TParams>
+    body?: Schema<TBody>
+    returns?: TReturns
+    handler: (
+      ctx: StandaloneMiddlewareContext<TQuery, TParams, TBody, TAppContext>,
+      next: (args: { state: TState }) => Promise<ReplyResult>,
+    ) => Awaitable<ReplyResult | Response | unknown>
+  },
+): MiddlewareUnit<
+  MiddlewareReturnFromParts<TQuery, TParams, TBody, TState>,
+  TReturns
+>
+
+export function defineMiddleware<
+  TAppContext extends Record<string, unknown> = AppContext,
+  TCtx = unknown,
+  TQuery = unknown,
+  TParams = unknown,
+  TBody = unknown,
+  TReturns extends ReturnsMap = {},
+>(
+  options: {
+    ctx: Schema<TCtx>
+    query?: Schema<TQuery>
+    params?: Schema<TParams>
+    body?: Schema<TBody>
+    returns?: TReturns
+    handler: (
+      ctx: StandaloneMiddlewareContext<TQuery, TParams, TBody, TAppContext>,
+      next: (args: { ctx: TCtx }) => Promise<ReplyResult>,
+    ) => Awaitable<ReplyResult | Response | unknown>
+  },
+): MiddlewareUnit<
+  MiddlewareReturnFromParts<TQuery, TParams, TBody, {}, TCtx>,
+  TReturns
+>
+
+export function defineMiddleware<
+  TAppContext extends Record<string, unknown> = AppContext,
+  TQuery = unknown,
+  TParams = unknown,
+  TBody = unknown,
+  TReturns extends ReturnsMap = {},
+>(
+  options: {
+    query?: Schema<TQuery>
+    params?: Schema<TParams>
+    body?: Schema<TBody>
+    returns?: TReturns
+    handler: (
+      ctx: StandaloneMiddlewareContext<TQuery, TParams, TBody, TAppContext>,
+      next: () => Promise<ReplyResult>,
+    ) => Awaitable<ReplyResult | Response | unknown>
+  },
+): MiddlewareUnit<
+  MiddlewareReturnFromParts<TQuery, TParams, TBody, {}>,
+  TReturns
+>
+
+export function defineMiddleware<
+  TAppContext extends Record<string, unknown> = AppContext,
+>(): FluentMiddlewareBuilder<unknown, unknown, unknown, undefined, undefined, {}, TAppContext>
+
+export function defineMiddleware<
+  TAppContext extends Record<string, unknown> = AppContext,
+  TQuery = unknown,
+  TParams = unknown,
+  TBody = unknown,
+>(
+  options: {
+    query?: Schema<TQuery>
+    params?: Schema<TParams>
+    body?: Schema<TBody>
+  },
+): FluentMiddlewareBuilder<TQuery, TParams, TBody, undefined, undefined, {}, TAppContext>
+
+export function defineMiddleware<
+  TAppContext extends Record<string, unknown> = AppContext,
+  TState = unknown,
+  TQuery = unknown,
+  TParams = unknown,
+  TBody = unknown,
+>(
+  options: {
+    state: Schema<TState>
+    query?: Schema<TQuery>
+    params?: Schema<TParams>
+    body?: Schema<TBody>
+  },
+): FluentMiddlewareBuilder<TQuery, TParams, TBody, TState, undefined, {}, TAppContext>
+
+export function defineMiddleware<
+  TAppContext extends Record<string, unknown> = AppContext,
+  TCtx = unknown,
+  TQuery = unknown,
+  TParams = unknown,
+  TBody = unknown,
+>(
+  options: {
+    ctx: Schema<TCtx>
+    query?: Schema<TQuery>
+    params?: Schema<TParams>
+    body?: Schema<TBody>
+  },
+): FluentMiddlewareBuilder<TQuery, TParams, TBody, undefined, TCtx, {}, TAppContext>
+
+export function defineMiddleware<
+  TAppContext extends Record<string, unknown> = AppContext,
+  TState = unknown,
+  TCtx = unknown,
+  TQuery = unknown,
+  TParams = unknown,
+  TBody = unknown,
+>(
+  options: {
+    state: Schema<TState>
+    ctx: Schema<TCtx>
+    query?: Schema<TQuery>
+    params?: Schema<TParams>
+    body?: Schema<TBody>
+  },
+): FluentMiddlewareBuilder<TQuery, TParams, TBody, TState, TCtx, {}, TAppContext>
+
+export function defineMiddleware(options?: unknown): unknown {
+  if (typeof options === 'function') {
+    const honoMiddleware = options as HonoMiddlewareHandler
+    return defineMiddleware({
+      handler: (ctx, next) => createTaserCompatHandler(honoMiddleware)(ctx, next),
+    })
+  }
+
+  if (options === undefined) {
+    return createFluentBuilder({})
+  }
+
+  if (
+    typeof options === 'object'
+    && options !== null
+    && !('handler' in options)
+  ) {
+    return createFluentBuilder(options)
+  }
+
+  return options
+}

package/src/define/validators.ts

@@ -0,0 +1,22 @@
+import type { Schema } from '../types/schema.js'
+import { SCHEMA_KEYS, type SchemaKey } from '../constants.js'
+
+export type SchemaValidators = {
+  query?: Schema<unknown>
+  params?: Schema<unknown>
+  body?: Schema<unknown>
+}
+
+export function pickDefinedSchemas(
+  source: SchemaValidators,
+  keyMap?: Partial<Record<SchemaKey, string>>,
+): Record<string, Schema<unknown>> {
+  const result: Record<string, Schema<unknown>> = {}
+  for (const key of SCHEMA_KEYS) {
+    const value = source[key]
+    if (value !== undefined) {
+      result[keyMap?.[key] ?? key] = value
+    }
+  }
+  return result
+}