@sigitex/route 1.0.0

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright © 2026 Sigitex
+
+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,7 @@
+# @sigitex/route
+
+`bun add @sigitex/route`
+
+A server-side web framework.
+
+> **Note:** This package currently exports TypeScript sources directly. A TypeScript-compatible runtime or bundler (Bun, etc.) is required.

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@sigitex/route",
+  "type": "module",
+  "license": "MIT",
+  "author": {
+    "name": "Sigitex",
+    "url": "http://github.com/sigitex"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/sigitex/route.git"
+  },
+  "exports": {
+    ".": "./src/index.ts",
+    "./cloudflare": "./src/cloudflare/index.ts",
+    "./bun": "./src/bun/index.ts"
+  },
+  "devDependencies": {
+    "@cloudflare/workers-types": "^4.20250425.0",
+    "@commitlint/cli": "^20.5.3",
+    "@commitlint/config-conventional": "^20.5.3",
+    "@markwylde/semantic-release-gitea": "^2.2.0",
+    "@semantic-release/exec": "^7.0.3",
+    "@sigitex/bind": "*",
+    "@sigitex/ssjs": "*",
+    "@types/bun": "1.3.11",
+    "@typescript/native-preview": "beta",
+    "husky": "^9.1.7",
+    "multi-semantic-release": "^3.1.0",
+    "oxfmt": "^0.47.0",
+    "oxlint": "^1.62.0",
+    "semantic-release": "^25.0.3"
+  },
+  "dependencies": {
+    "regexparam": "3.0.0"
+  },
+  "scripts": {
+    "check": "tsgo --noEmit && find . -mindepth 2 -name tsconfig.json -not -path '*/node_modules/*' -exec tsgo --noEmit -p {} \\;",
+    "test": "bun test --pass-with-no-tests",
+    "prepare": "husky",
+    "lint": "oxlint"
+  },
+  "files": [
+    "src"
+  ],
+  "version": "1.0.0"
+}

package/src/Assets.ts

@@ -0,0 +1,4 @@
+export type Assets = {
+  static(path: string): Promise<Response>
+  file(request: Request): Promise<Response | undefined>
+}

package/src/CSP.ts

@@ -0,0 +1,18 @@
+const nonce = Symbol("csp-nonce")
+
+export const CSP = {
+  self: "'self'",
+  none: "'none'",
+  unsafeInline: "'unsafe-inline'",
+  unsafeEval: "'unsafe-eval'",
+  unsafeHashes: "'unsafe-hashes'",
+  strictDynamic: "'strict-dynamic'",
+  nonce,
+  wildcard: "*",
+  data: "data:",
+  blob: "blob:",
+  https: "https:",
+  wss: "wss:",
+} as const
+
+export type CspSource = string | typeof nonce

package/src/HTTP.ts

@@ -0,0 +1,83 @@
+export const HTTP = {
+  method: {
+    GET: "GET",
+    POST: "POST",
+    PUT: "PUT",
+    PATCH: "PATCH",
+    DELETE: "DELETE",
+    HEAD: "HEAD",
+    OPTIONS: "OPTIONS",
+  },
+  status: {
+    NoContent: 204,
+    MovedPermanently: 301,
+    Forbidden: 403,
+    PayloadTooLarge: 413,
+    UnsupportedMediaType: 415,
+    TooManyRequests: 429,
+  },
+  statusText: {
+    Forbidden: "Forbidden",
+    PayloadTooLarge: "Payload Too Large",
+    UnsupportedMediaType: "Unsupported Media Type",
+    TooManyRequests: "Too Many Requests",
+  },
+  header: {
+    Accept: "Accept",
+    Authorization: "Authorization",
+    CacheControl: "Cache-Control",
+    ContentLength: "Content-Length",
+    ContentType: "Content-Type",
+    Cookie: "Cookie",
+    Origin: "Origin",
+    Referrer: "Referer",
+    SetCookie: "Set-Cookie",
+    Vary: "Vary",
+    XContentTypeOptions: "X-Content-Type-Options",
+    XForwardedFor: "X-Forwarded-For",
+    XFrameOptions: "X-Frame-Options",
+    XRequestId: "X-Request-Id",
+    XCsrfToken: "X-CSRF-Token",
+    StrictTransportSecurity: "Strict-Transport-Security",
+    ReferrerPolicy: "Referrer-Policy",
+    AccessControlAllowOrigin: "Access-Control-Allow-Origin",
+    AccessControlAllowMethods: "Access-Control-Allow-Methods",
+    AccessControlAllowHeaders: "Access-Control-Allow-Headers",
+    AccessControlExposeHeaders: "Access-Control-Expose-Headers",
+    AccessControlAllowCredentials: "Access-Control-Allow-Credentials",
+    AccessControlMaxAge: "Access-Control-Max-Age",
+    AccessControlRequestMethod: "Access-Control-Request-Method",
+    AccessControlRequestHeaders: "Access-Control-Request-Headers",
+    ContentSecurityPolicy: "Content-Security-Policy",
+    ContentSecurityPolicyReportOnly: "Content-Security-Policy-Report-Only",
+    CFConnectingIP: "CF-Connecting-IP",
+    XRateLimitLimit: "X-RateLimit-Limit",
+    XRateLimitRemaining: "X-RateLimit-Remaining",
+    XRateLimitReset: "X-RateLimit-Reset",
+  },
+  contentType: {
+    json: "application/json",
+    urlencoded: "application/x-www-form-urlencoded",
+    formData: "multipart/form-data",
+    text: "text/plain",
+    html: "text/html",
+    octetStream: "application/octet-stream",
+  },
+  referrerPolicy: {
+    noReferrer: "no-referrer",
+    noReferrerWhenDowngrade: "no-referrer-when-downgrade",
+    origin: "origin",
+    originWhenCrossOrigin: "origin-when-cross-origin",
+    sameOrigin: "same-origin",
+    strictOrigin: "strict-origin",
+    strictOriginWhenCrossOrigin: "strict-origin-when-cross-origin",
+    unsafeUrl: "unsafe-url",
+  },
+  frameOption: {
+    deny: "DENY",
+    sameOrigin: "SAMEORIGIN",
+  },
+  contentTypeOptions: {
+    nosniff: "nosniff",
+  },
+} as const

package/src/Router.ts

@@ -0,0 +1,100 @@
+import type { Container } from "@sigitex/bind"
+import type {
+  RequestHandler,
+  RouterOptions,
+  RouteMiddleware,
+  RequestContext
+} from "./router.types"
+
+export class Router {
+  private readonly handlers: RequestHandler[]
+  private readonly container: Container | undefined
+  private readonly middlewares: RouteMiddleware[]
+
+  constructor(handlers: RequestHandler[], options: RouterOptions = {}) {
+    this.handlers = handlers
+    this.container = options.container
+    this.middlewares = options.middlewares ?? []
+  }
+
+  async route(
+    request: Request,
+    env: Env,
+  ): Promise<Response> {
+    const url = new URL(request.url)
+    const context: RequestContext = {
+      request,
+      env,
+      url,
+      bind,
+      dispatch,
+    }
+    const container = this.container?.clone()
+    try {
+      if (container) {
+        container.bind(context)
+      }
+      for (const handler of this.handlers) {
+        const result = await dispatch(handler, this.middlewares)
+        if (result === undefined) continue
+        return result
+      }
+      return fail(404, "Not found.")
+    } catch (error) {
+      console.error(error)
+      return fail(500, "Internal server error.")
+    }
+
+    // oxlint-disable-next-line typescript/no-explicit-any
+    async function bind(bindings: { [key: string]: any }) {
+      if (container) {
+        container.bind(bindings)
+      } else {
+        Object.assign(context, bindings)
+      }
+    }
+
+    async function dispatch(
+      handler: RequestHandler,
+      middlewares: RouteMiddleware[],
+    ): Promise<Response | undefined> {
+      for (const { before } of middlewares) {
+        if (!before) continue
+        const interrupt = await Promise.resolve(invoke(before))
+        if (interrupt !== undefined) return respond(interrupt)
+      }
+      const result = await Promise.resolve(invoke(handler))
+      if (result === undefined) {
+        return
+      }
+      const response = respond(result)
+      bind({ response })
+      for (const { after } of middlewares) {
+        if (!after) continue
+        const interrupt = await Promise.resolve(invoke(after))
+        if (interrupt !== undefined) return respond(interrupt)
+      }
+      return respond(result)
+    }
+
+    async function invoke(handler: RequestHandler) {
+      if (container) {
+        return container.call(handler)
+      }
+      return handler(context)
+    }
+  }
+}
+
+function fail(status: number, error: string) {
+  return new Response(JSON.stringify({ error }), {
+    status,
+    statusText: error,
+  })
+}
+
+function respond(result: unknown) {
+  return result instanceof Response
+    ? result
+    : new Response(JSON.stringify(result))
+}

package/src/RouterError.ts

@@ -0,0 +1,31 @@
+export class RouterError extends Error {
+  readonly code: number
+  constructor(code: number, message: string) {
+    super(message)
+    this.code = code
+  }
+}
+
+export class NotFound extends RouterError {
+  constructor(message?: string) {
+    super(404, message ?? "Not found.")
+  }
+}
+
+export class ServerError extends Error {
+  constructor(message?: string) {
+    super(message ?? "Internal error.")
+  }
+}
+
+export class MethodNotAllowed extends RouterError {
+  constructor(message?: string) {
+    super(405, message ?? "Method not allowed.")
+  }
+}
+
+export class InvalidRequest extends RouterError {
+  constructor(message?: string) {
+    super(400, message ?? "Invalid request.")
+  }
+}

package/src/bun/bun.ts

@@ -0,0 +1,37 @@
+import { join } from "node:path"
+import type { Assets } from "../Assets"
+import type { RequestHandler } from "../router.types"
+
+type BunOptions = {
+  readonly assets?: string
+}
+
+export function bun(options: BunOptions = {}): RequestHandler {
+  const assets = bunAssets(options.assets ?? "./assets")
+  return ({ bind }: { bind: (bindings: { assets: Assets }) => void }) => {
+    bind({ assets })
+  }
+}
+
+function bunAssets(dir: string): Assets {
+  const cache = new Map<string, Response>()
+
+  return {
+    async static(path) {
+      const cached = cache.get(path)
+      if (cached) return cached.clone() as Response
+      const file = Bun.file(join(dir, path))
+      const response = new Response(await file.bytes(), {
+        headers: { "Content-Type": file.type },
+      })
+      cache.set(path, response.clone() as Response)
+      return response as Response
+    },
+    async file(request) {
+      const path = new URL(request.url).pathname
+      const file = Bun.file(join(dir, path))
+      if (!await file.exists()) return undefined
+      return new Response(file) as Response
+    },
+  }
+}

package/src/bun/index.ts

@@ -0,0 +1 @@
+export * from "./bun"

package/src/bun/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "types": ["bun"]
+  },
+  "include": [".", "../env.d.ts"],
+  "exclude": []
+}

package/src/cloudflare/cloudflare.ts

@@ -0,0 +1,43 @@
+import type { Assets } from "../Assets"
+import type { RequestHandler } from "../router.types"
+
+type CloudflareAssets = {
+  readonly fetch: (request: Request | URL | string) => Promise<Response>
+}
+
+type CloudflareOptions = {
+  readonly assets?: string
+}
+
+export function cloudflare(options: CloudflareOptions = {}): RequestHandler {
+  const assetsKey = options.assets ?? "ASSETS"
+  return ({
+    env,
+    request,
+    bind,
+  }: {
+    env: Env
+    request: Request
+    bind: (bindings: { assets: Assets }) => void
+  }) => {
+    // oxlint-disable-next-line typescript/no-explicit-any
+    const binding = (env as any)[assetsKey] as CloudflareAssets
+    const { origin } = new URL(request.url)
+    bind({ assets: cloudflareAssets(binding, origin) })
+  }
+}
+
+function cloudflareAssets(binding: CloudflareAssets, origin: string): Assets {
+  return {
+    async static(path) {
+      return binding.fetch(new Request(`${origin}${path}`))
+    },
+    async file(request) {
+      const response = await binding.fetch(request)
+      if (response.status === 404) {
+        return undefined
+      }
+      return response
+    },
+  }
+}

package/src/cloudflare/index.ts

@@ -0,0 +1 @@
+export * from "./cloudflare"

package/src/cloudflare/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "types": ["@cloudflare/workers-types"]
+  },
+  "include": [".", "../env.d.ts"],
+  "exclude": []
+}

package/src/env.d.ts

@@ -0,0 +1 @@
+interface Env {}

package/src/global.d.ts

@@ -0,0 +1 @@
+import "@sigitex/ssjs"

package/src/handler/app.ts

@@ -0,0 +1,27 @@
+import * as RegexParam from "regexparam"
+import type { Assets } from "../Assets"
+import type { RequestHandler, RouteTree } from "../router.types"
+
+export function app(routes: RouteTree): RequestHandler {
+  const patterns: RegExp[] = getAppPatterns(routes)
+  return async ({ assets, url }: { assets: Assets, url: URL }) => {
+    for (const pattern of patterns) {
+      if (pattern.test(url.pathname)) {
+        return await assets.static("/index.html")
+      }
+    }
+    return
+  }
+}
+
+function getAppPatterns(tree: RouteTree) {
+  const patterns: RegExp[] = []
+  for (const [_key, value] of Object.entries(tree)) {
+    if (typeof value === "string") {
+      patterns.push(RegexParam.parse(value).pattern)
+    } else {
+      patterns.push(...getAppPatterns(value))
+    }
+  }
+  return patterns
+}

package/src/handler/assets.ts

@@ -0,0 +1,10 @@
+import type { Assets } from "../Assets"
+import type { RequestHandler } from "../router.types"
+
+export function assets(): RequestHandler {
+  return async ({ assets, request }: { assets: Assets, request: Request }) => {
+    const response = await assets.file(request)
+    if (!response || response.status === 404) return
+    return response
+  }
+}

package/src/handler/index.ts

@@ -0,0 +1,7 @@
+export * from "./app"
+export * from "./assets"
+export * from "./mount"
+export * from "./noop"
+export * from "./pattern"
+export * from "./prefix"
+export * from "./use"

package/src/handler/mount.ts

@@ -0,0 +1,13 @@
+// oxlint-disable typescript/no-explicit-any
+import type { RequestHandler } from "../router.types"
+
+/** Wraps a standard fetch function as a router handler. */
+export function mount(handler: (request: Request) => Promise<Response>): RequestHandler {
+  return ({ request, url, container }: any) => {
+    const mapped = new Request(url.href, request)
+    if ("__mount" in handler && container) {
+      return (handler as any).__mount(mapped, container)
+    }
+    return handler(mapped)
+  }
+}

package/src/handler/noop.ts

@@ -0,0 +1,3 @@
+import type { RequestHandler } from "../router.types"
+
+export const noop: RequestHandler = () => {}

package/src/handler/pattern.ts

@@ -0,0 +1,71 @@
+import * as RegexParam from "regexparam"
+import { MethodNotAllowed } from "../RouterError"
+import type { RequestContext, RequestHandler, RouteMiddleware } from "../router.types"
+
+export function pattern(
+  method: string | null,
+  path: string,
+  handler: RequestHandler,
+  ...middlewares: RouteMiddleware[]
+): RequestHandler {
+  const { pattern, keys } = RegexParam.parse(path)
+  return ({ url, request, bind, dispatch }: RequestContext) => {
+    const match = pattern.exec(url.pathname)
+    if (!match) return
+    if (method !== null && request.method !== method) {
+      return new MethodNotAllowed(`Please use "${method}".`)
+    }
+    const params: { [key: string]: string } = {}
+    if (keys.length > 0) {
+      for (let k = 0; k < keys.length; k++) {
+        let key = keys[k]
+        if (key === "*") {
+          key = "path"
+        }
+        params[key] = match[k + 1]
+      }
+    }
+    bind({ params })
+    return dispatch(handler, middlewares)
+  }
+}
+
+export function get(
+  path: string,
+  handler: RequestHandler,
+  ...middlewares: RouteMiddleware[]
+): RequestHandler {
+  return pattern("GET", path, handler, ...middlewares)
+}
+
+export function post(
+  path: string,
+  handler: RequestHandler,
+  ...middlewares: RouteMiddleware[]
+): RequestHandler {
+  return pattern("POST", path, handler, ...middlewares)
+}
+
+export function put(
+  path: string,
+  handler: RequestHandler,
+  ...middlewares: RouteMiddleware[]
+): RequestHandler {
+  return pattern("PUT", path, handler, ...middlewares)
+}
+
+export function del(
+  path: string,
+  handler: RequestHandler,
+  ...middlewares: RouteMiddleware[]
+): RequestHandler {
+  return pattern("DELETE", path, handler, ...middlewares)
+}
+
+export function patch(
+  path: string,
+  handler: RequestHandler,
+  ...middlewares: RouteMiddleware[]
+): RequestHandler {
+  return pattern("PATCH", path, handler, ...middlewares)
+}

package/src/handler/prefix.ts

@@ -0,0 +1,32 @@
+import type { RequestContext, RequestHandler, RouteMiddleware } from "../router.types"
+import { use } from "./use"
+
+export function prefix(
+  prefix: string,
+  ...handlers: RequestHandler[]
+): RequestHandler
+export function prefix(
+  prefix: string,
+  middlewares: RouteMiddleware[],
+  ...handlers: RequestHandler[]
+): RequestHandler
+export function prefix(
+  prefix: string,
+  head: RouteMiddleware[] | RequestHandler,
+  ...tail: RequestHandler[]
+): RequestHandler {
+  const [middlewares, handlers] = Array.isArray(head)
+    ? [head, tail]
+    : [[], [head, ...tail]]
+  const root = prefix.endsWith("/") ? prefix : prefix + "/"
+  const handle = use(middlewares, ...handlers)
+  return (context: RequestContext) => {
+    if (!context.url.pathname.startsWith(root)) {
+      return
+    }
+    const url = new URL(context.url.href)
+    url.pathname = url.pathname.slice(root.length - 1) || "/"
+    context.bind({ url })
+    return handle(context)
+  }
+}

package/src/handler/use.ts

@@ -0,0 +1,36 @@
+import type { RequestContext, RequestHandler, RouteMiddleware } from "../router.types"
+import { noop } from "./noop"
+
+export function use(
+  middlewares: RouteMiddleware[],
+  ...handlers: RequestHandler[]
+): RequestHandler {
+  const befores = middlewares.filter(({ before }) => before)
+  const afters = middlewares
+    .filter(({ after }) => after)
+    .map(({ after }) => ({ before: after }) as RouteMiddleware)
+  return async ({ dispatch, bind }: RequestContext) => {
+    if (befores.length) {
+      const interruptBefore = await dispatch(noop, befores)
+      if (interruptBefore !== undefined) {
+        return interruptBefore
+      }
+    }
+    let response: Response | undefined
+    for (const handler of handlers) {
+      response = await dispatch(handler, [])
+      if (response !== undefined) break
+    }
+    if (response === undefined) {
+      return
+    }
+    bind({ response })
+    if (afters.length) {
+      const interruptAfter = await dispatch(noop, afters)
+      if (interruptAfter !== undefined) {
+        return interruptAfter
+      }
+    }
+    return response
+  }
+}

package/src/index.ts

@@ -0,0 +1,9 @@
+export * from "./Assets"
+export * from "./HTTP"
+export * from "./CSP"
+export * from "./router.types"
+export * from "./Router"
+export * from "./RouterError"
+export * from "./route"
+export * from "./handler"
+export * from "./middleware"