refactor(imports): use explicit type-only imports across codebase

- Replace standard imports with type-only imports to improve clarity
  and align with TypeScript best practices.
- Ensure consistency across modules by modifying all relevant files.

.gitattributes

@@ -0,0 +1 @@
+CHANGELOG.md merge=ours

.gitea/HOWTO_RELEASE.md

@@ -122,3 +122,77 @@ git commit -m "chore(version): bump to 1.2.3"
 ```
 
 > Nur die ersten beiden erscheinen im Changelog – der dritte wird **automatisch übersprungen**.
+
+---
+
+## 🧾 Umgang mit `CHANGELOG.md` beim Mergen und Releasen
+
+Wenn du automatisiert einen Changelog mit `git-cliff` erzeugst, ist `CHANGELOG.md` ein **generiertes Artefakt** – und kein handgepflegter Quelltext.
+
+Beim Mergen von Feature-Branches in `main` kann es deshalb zu **unnötigen Konflikten** in dieser Datei kommen, obwohl der Inhalt später sowieso neu erzeugt wird.
+
+---
+
+## 🧼 Umgang mit `CHANGELOG.md` in Feature-Branches
+
+Wenn du mit **Feature-Branches** arbeitest, wird `CHANGELOG.md` dort oft automatisch erzeugt.
+Das kann beim späteren Merge in `main` zu **unnötigen Merge-Konflikten** führen.
+
+### ✅ Empfohlene Vorgehensweise
+
+**Bevor du den Branch mit `main` zusammenführst** (Merge oder Cherry-Pick):
+
+```bash
+git rm CHANGELOG.md
+git commit -m "chore(changelog): remove generated CHANGELOG.md before merge"
+git push
+```
+
+Dadurch:
+
+* verhinderst du Merge-Konflikte mit `CHANGELOG.md`
+* wird die Datei bei Feature-Branches nicht mehr automatisch erzeugt
+* bleibt deine Historie sauber und konfliktfrei
+
+> 💡 Der Workflow erzeugt `CHANGELOG.md` automatisch **nur**, wenn:
+>
+> * die Datei schon vorhanden ist **oder**
+> * der Branch `main` heißt
+
+---
+
+## 🧩 Merge-Konflikte verhindern mit `.gitattributes`
+
+Damit Git bei Konflikten in `CHANGELOG.md` **automatisch deine Version bevorzugt**, kannst du folgende Zeile in die Datei `.gitattributes` aufnehmen:
+
+```gitattributes
+CHANGELOG.md merge=ours
+```
+
+Das bedeutet:
+
+* Beim Merge wird die Version aus dem aktuellen Branch (`ours`) behalten
+* Änderungen aus dem Ziel-Branch (`theirs`) werden verworfen
+
+### ✅ So verwendest du es richtig:
+
+1. **Füge die Regel in `main` hinzu**:
+
+```bash
+echo "CHANGELOG.md merge=ours" >> .gitattributes
+git add .gitattributes
+git commit -m "chore(git): prevent merge conflicts in CHANGELOG.md"
+git push origin main
+```
+
+2. **Hole sie in deinen Feature-Branch**:
+
+```bash
+git checkout feature/xyz
+git rebase origin/main
+```
+
+3. **Ab sofort werden Konflikte in `CHANGELOG.md` automatisch aufgelöst** – lokal.
+
+> ⚠️ Hinweis: Plattformen wie **Gitea, GitHub oder GitLab ignorieren `.gitattributes` beim Merge über die Web-Oberfläche**.
+> Führe Merges daher **lokal** durch, wenn du Konflikte verhindern willst.

.gitea/workflows/release.yml

@@ -4,38 +4,44 @@ on:
   push:
     branches:
       - main
+      - '**'
 
 jobs:
   detect-version-change:
     runs-on: ubuntu-latest
     outputs:
-      version_changed: ${{ steps.check.outputs.version_changed }}
+      version_changed: ${{ steps.set.outputs.version_changed }}
     steps:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 0
 
       - name: Check if VERSION file changed
-        id: check
+        if: github.ref == 'refs/heads/main'
         run: |
           echo "🔍 Vergleich mit github.event.before:"
           echo "Before: ${{ github.event.before }}"
           echo "After:  ${{ github.sha }}"
-          
+
           echo "📄 Changed files between before and after:"
           git diff --name-only ${{ github.event.before }} ${{ github.sha }} || echo "(diff failed)"
 
           if git diff --name-only ${{ github.event.before }} ${{ github.sha }} | grep -q '^VERSION$'; then
-            echo "✅ VERSION file was changed between before and after"
+            echo "✅ VERSION file was changed"
-            echo "version_changed=true" >> $GITHUB_OUTPUT
+            echo "VERSION_CHANGED=true" >> $GITHUB_ENV
           else
-            echo "ℹ️ VERSION file not changed between before and after"
+            echo "ℹ️ VERSION file not changed"
-            echo "version_changed=false" >> $GITHUB_OUTPUT
+            echo "VERSION_CHANGED=false" >> $GITHUB_ENV
           fi
 
+      - name: Set output (always)
+        id: set
+        run: |
+          echo "version_changed=${VERSION_CHANGED:-false}" >> $GITHUB_OUTPUT
+
   changelog-only:
     needs: detect-version-change
-    if: needs.detect-version-change.outputs.version_changed == 'false'
+    if: github.ref != 'refs/heads/main' || needs.detect-version-change.outputs.version_changed == 'false'
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
@@ -65,8 +71,14 @@ jobs:
         run: |
           cargo install git-cliff --version "${{ steps.cliff_version.outputs.version }}" --features gitea
 
-      - name: Generate unreleased changelog
+      - name: Generate unreleased changelog (if file exists or on main)
-        run: git-cliff -c cliff.toml -o CHANGELOG.md
+        run: |
+          if [[ -f CHANGELOG.md || "${GITHUB_REF##refs/heads/}" == "main" ]]; then
+            echo "Generating CHANGELOG.md..."
+            git-cliff -c cliff.toml -o CHANGELOG.md
+          else
+            echo "CHANGELOG.md does not exist and this is not 'main'. Skipping generation."
+          fi
 
       - name: Commit updated CHANGELOG
         run: |
@@ -75,12 +87,12 @@ jobs:
             echo "No changes to commit"
           else
             git commit -m "chore(changelog): update unreleased changelog"
-            git push origin main
+            git push origin "${GITHUB_REF##refs/heads/}"
           fi
 
   release:
     needs: detect-version-change
-    if: needs.detect-version-change.outputs.version_changed == 'true'
+    if: needs.detect-version-change.outputs.version_changed == 'true' && github.ref == 'refs/heads/main'
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4

CHANGELOG.md

@@ -6,19 +6,27 @@ All notable changes to this project will be documented in this file.
 
 ### 🚀 Features
 
+- *(workflows)* Conditionally generate changelog - ([b44bb2d](https://git.0xmax42.io/maxp/http-kernel/commit/b44bb2ddafe99c85b25229d2c4a0dfeacf750052))
 - *(workflows)* Add CI for Deno project tests - ([9d5db4f](https://git.0xmax42.io/maxp/http-kernel/commit/9d5db4f414cf961248f2b879f2b132b81a32cb92))
 
+### 🐛 Bug Fixes
+
+- *(workflows)* Ensure version detection output is always set - ([3707242](https://git.0xmax42.io/maxp/http-kernel/commit/3707242d278e15c55a41056bb64810f6824d24b3))
+
 ### 🚜 Refactor
 
 - *(workflows)* Rename changelog file for consistency - ([b9d25f2](https://git.0xmax42.io/maxp/http-kernel/commit/b9d25f23fc6ad7696deee319024aa5b1af4d98c0))
 
 ### 📚 Documentation
 
+- *(release)* Update guidelines for handling changelog - ([6a0f1c7](https://git.0xmax42.io/maxp/http-kernel/commit/6a0f1c774bc01ab976090612bbc361576feb3942))
 - Add README for HttpKernel project - ([a1ce306](https://git.0xmax42.io/maxp/http-kernel/commit/a1ce30627c68a3f869eb6a104308322af8596dc1))
 - Add MIT license file - ([5118a19](https://git.0xmax42.io/maxp/http-kernel/commit/5118a19aeaa1102591aa7fe093fdec1aa19dc7f5))
 
 ### ⚙️ Miscellaneous Tasks
 
+- *(git)* Ignore merge conflicts for CHANGELOG.md - ([6399113](https://git.0xmax42.io/maxp/http-kernel/commit/6399113e122e1207ebf4113aebd250358e31f461))
+- *(workflows)* Refine branch handling in release process - ([71ea424](https://git.0xmax42.io/maxp/http-kernel/commit/71ea4247b35dc4afe5090d3c6502bfa936b5a947))
 - *(workflows)* Update changelog file extension to .md and revert b9d25f23fc - ([a88b4d1](https://git.0xmax42.io/maxp/http-kernel/commit/a88b4d112f5c07664d41f6e9d03246307551f25d))
 - Rename changelog and readme files to use .md extension - ([4f2b650](https://git.0xmax42.io/maxp/http-kernel/commit/4f2b65049f461ef377e7231905fd066cbc3c7fe0))
 - *(workflows)* Update test workflow for http-kernel project - ([0311546](https://git.0xmax42.io/maxp/http-kernel/commit/03115464e0fb01b8ca00a2fdabde013d004ae8a2))

deno.jsonc

@@ -1,6 +1,9 @@
 {
     "name": "@0xmax42/http-kernel",
     "description": "A simple HTTP kernel for Deno",
+    "exports": {
+        "./mod.ts": "./src/mod.ts"
+    },
     "tasks": {
         "test": "deno test --allow-net --allow-env --unstable-kv --allow-read --allow-write --coverage **/__tests__/*.test.ts",
         "test:watch": "deno test --watch --allow-net --allow-env --unstable-kv --allow-read --allow-write **/__tests__/*.test.ts"

src/HttpKernel.ts

@@ -1,4 +1,4 @@
-import {
+import type {
     IContext,
     IHttpKernel,
     IHttpKernelConfig,
@@ -7,14 +7,14 @@ import {
     IRouteDefinition,
 } from './Interfaces/mod.ts';
 import {
-    DeepPartial,
+    type DeepPartial,
-    Handler,
+    type Handler,
     HTTP_404_NOT_FOUND,
     HTTP_500_INTERNAL_SERVER_ERROR,
     HttpStatusTextMap,
     isHandler,
     isMiddleware,
-    Middleware,
+    type Middleware,
 } from './Types/mod.ts';
 import { RouteBuilder } from './RouteBuilder.ts';
 import { createEmptyContext, normalizeError } from './Utils/mod.ts';

src/Interfaces/IContext.ts

@@ -1,4 +1,4 @@
-import { Params, Query, State } from '../Types/mod.ts';
+import type { Params, Query, State } from '../Types/mod.ts';
 
 /**
  * Represents the complete context for a single HTTP request,

src/Interfaces/IHttpErrorHandlers.ts

@@ -1,5 +1,5 @@
-import { IContext } from '../Interfaces/mod.ts';
+import type { IContext } from '../Interfaces/mod.ts';
-import { HttpErrorHandler, validHttpErrorCodes } from '../Types/mod.ts';
+import type { HttpErrorHandler, validHttpErrorCodes } from '../Types/mod.ts';
 
 /**
  * A mapping of HTTP status codes to their corresponding error handlers.

src/Interfaces/IHttpKernel.ts

@@ -1,6 +1,6 @@
-import { IContext } from './IContext.ts';
+import type { IContext } from './IContext.ts';
-import { IRouteBuilder } from './IRouteBuilder.ts';
+import type { IRouteBuilder } from './IRouteBuilder.ts';
-import { IRouteDefinition } from './IRouteDefinition.ts';
+import type { IRouteDefinition } from './IRouteDefinition.ts';
 
 /**
  * The `IHttpKernel` interface defines the public API for a type-safe, middleware-driven HTTP dispatching system.

src/Interfaces/IHttpKernelConfig.ts

@@ -1,7 +1,7 @@
-import { ResponseDecorator } from '../Types/mod.ts';
+import type { ResponseDecorator } from '../Types/mod.ts';
-import { IContext } from './IContext.ts';
+import type { IContext } from './IContext.ts';
-import { IHttpErrorHandlers } from './IHttpErrorHandlers.ts';
+import type { IHttpErrorHandlers } from './IHttpErrorHandlers.ts';
-import { IRouteBuilderFactory } from './IRouteBuilder.ts';
+import type { IRouteBuilderFactory } from './IRouteBuilder.ts';
 
 export interface IHttpKernelConfig<TContext extends IContext = IContext> {
     decorateResponse: ResponseDecorator<TContext>;

src/Interfaces/IInternalRoute.ts

@@ -1,5 +1,5 @@
-import { Handler, HttpMethod, Middleware } from '../Types/mod.ts';
+import type { Handler, HttpMethod, Middleware } from '../Types/mod.ts';
-import { IContext, IRouteMatcher } from './mod.ts';
+import type { IContext, IRouteMatcher } from './mod.ts';
 
 /**
  * Represents an internally registered route within the HttpKernel.

src/Interfaces/IRouteBuilder.ts

@@ -1,7 +1,7 @@
-import { Handler, Middleware } from '../Types/mod.ts';
+import type { Handler, Middleware } from '../Types/mod.ts';
-import { IInternalRoute } from './IInternalRoute.ts';
+import type { IInternalRoute } from './IInternalRoute.ts';
-import { IRouteDefinition } from './IRouteDefinition.ts';
+import type { IRouteDefinition } from './IRouteDefinition.ts';
-import { IContext } from './mod.ts';
+import type { IContext } from './mod.ts';
 
 export interface IRouteBuilderFactory<TContext extends IContext = IContext> {
     new (

src/Interfaces/IRouteDefinition.ts

@@ -1,5 +1,5 @@
-import { HttpMethod, isHttpMethod } from '../Types/mod.ts';
+import { type HttpMethod, isHttpMethod } from '../Types/mod.ts';
-import { IRouteMatcher } from './IRouteMatcher.ts';
+import type { IRouteMatcher } from './IRouteMatcher.ts';
 
 /**
  * Defines a static route using a path pattern with optional parameters.

src/Interfaces/IRouteMatch.ts

@@ -1,4 +1,4 @@
-import { Params, Query } from '../Types/mod.ts';
+import type { Params, Query } from '../Types/mod.ts';
 
 export interface IRouteMatch {
     params?: Params;

src/Interfaces/IRouteMatcher.ts

@@ -1,6 +1,5 @@
-import { Params } from '../Types/mod.ts';
+import type { IRouteDefinition } from './IRouteDefinition.ts';
-import { IRouteDefinition } from './IRouteDefinition.ts';
+import type { IRouteMatch } from './IRouteMatch.ts';
-import { IRouteMatch } from './IRouteMatch.ts';
 
 /**
  * Defines a route matcher function that evaluates whether a route applies to a given request.

src/Interfaces/__tests__/routeDefinitionGuards.test.ts

@@ -1,6 +1,6 @@
 import { assertEquals } from 'https://deno.land/std@0.204.0/assert/mod.ts';
 import {
-    IRouteDefinition,
+    type IRouteDefinition,
     isDynamicRouteDefinition,
     isStaticRouteDefinition,
 } from '../IRouteDefinition.ts';

src/RouteBuilder.ts

@@ -1,6 +1,10 @@
-import { IRouteMatcherFactory } from './Interfaces/IRouteMatcher.ts';
+import type { IRouteMatcherFactory } from './Interfaces/IRouteMatcher.ts';
-import { IContext, IRouteBuilder, IRouteDefinition } from './Interfaces/mod.ts';
+import type {
-import { Handler, Middleware, RegisterRoute } from './Types/mod.ts';
+    IContext,
+    IRouteBuilder,
+    IRouteDefinition,
+} from './Interfaces/mod.ts';
+import type { Handler, Middleware, RegisterRoute } from './Types/mod.ts';
 import { createRouteMatcher } from './Utils/createRouteMatcher.ts';
 
 /**

src/Types/Handler.ts

@@ -1,4 +1,4 @@
-import { IContext } from '../Interfaces/mod.ts';
+import type { IContext } from '../Interfaces/mod.ts';
 
 /**
  * Represents a final request handler responsible for producing an HTTP response.

src/Types/HttpErrorHandler.ts

@@ -1,4 +1,4 @@
-import { IContext } from '../Interfaces/mod.ts';
+import type { IContext } from '../Interfaces/mod.ts';
 
 /**
  * Defines a handler function for errors that occur during the execution

src/Types/Middleware.ts

@@ -1,4 +1,4 @@
-import { IContext } from '../Interfaces/IContext.ts';
+import type { IContext } from '../Interfaces/IContext.ts';
 
 /**
  * Represents a middleware function in the HTTP request pipeline.

src/Types/RegisterRoute.ts

@@ -1,5 +1,5 @@
-import { IContext } from '../Interfaces/IContext.ts';
+import type { IContext } from '../Interfaces/IContext.ts';
-import { IInternalRoute } from '../Interfaces/mod.ts';
+import type { IInternalRoute } from '../Interfaces/mod.ts';
 
 /**
  * A type alias for the internal route registration function used by the `HttpKernel`.

src/Types/ResponseDecorator.ts

@@ -1,4 +1,4 @@
-import { IContext } from '../Interfaces/mod.ts';
+import type { IContext } from '../Interfaces/mod.ts';
 
 /**
  * A function that modifies or enriches an outgoing HTTP response before it is returned to the client.

src/Utils/__tests__/createEmptyContext.test.ts

@@ -1,6 +1,6 @@
 import { assertEquals } from 'https://deno.land/std/assert/mod.ts';
 import { createEmptyContext } from '../createEmptyContext.ts';
-import { IContext } from '../../Interfaces/mod.ts';
+import type { IContext } from '../../Interfaces/mod.ts';
 
 Deno.test('createEmptyContext: returns default-initialized context', () => {
     const request = new Request('http://localhost');

src/Utils/__tests__/createRouteMatcher.test.ts

@@ -3,7 +3,7 @@ import {
     assertEquals,
     assertStrictEquals,
 } from 'https://deno.land/std/assert/mod.ts';
-import { IRouteDefinition } from '../../Interfaces/mod.ts';
+import type { IRouteDefinition } from '../../Interfaces/mod.ts';
 import { createRouteMatcher } from '../../mod.ts';
 
 // Dummy request

src/Utils/createEmptyContext.ts

@@ -1,5 +1,5 @@
-import { IContext } from '../Interfaces/mod.ts';
+import type { IContext } from '../Interfaces/mod.ts';
-import { Params, Query, State } from '../Types/mod.ts';
+import type { Params, Query, State } from '../Types/mod.ts';
 
 /**
  * Creates an empty request context suitable for fallback handlers (e.g., 404 or 500 errors).

src/Utils/createRouteMatcher.ts

@@ -1,12 +1,12 @@
 // createRouteMatcher.ts
 
 import {
-    IRouteDefinition,
+    type IRouteDefinition,
-    IRouteMatch,
+    type IRouteMatch,
-    IRouteMatcher,
+    type IRouteMatcher,
     isDynamicRouteDefinition,
 } from '../Interfaces/mod.ts';
-import { Params, Query } from '../Types/mod.ts';
+import type { Params, Query } from '../Types/mod.ts';
 
 /**
  * Transforms a route definition into a matcher using Deno's URLPattern API.

src/Utils/normalizeError.ts

@@ -22,11 +22,9 @@
  * ```
  */
 export function normalizeError(unknownError: unknown): Error {
-    return unknownError instanceof Error
+    return unknownError instanceof Error ? unknownError : new Error(
-        ? unknownError
+        typeof unknownError === 'string'
-        : new Error(
+            ? unknownError
-            typeof unknownError === 'string'
+            : JSON.stringify(unknownError),
-                ? unknownError
+    );
-                : JSON.stringify(unknownError),
-        );
 }

src/__tests__/HttpKernel.test.ts

@@ -1,6 +1,6 @@
 import { assertEquals } from 'https://deno.land/std@0.204.0/assert/mod.ts';
 import { HttpKernel } from '../HttpKernel.ts';
-import { IRouteDefinition } from '../Interfaces/mod.ts';
+import type { IRouteDefinition } from '../Interfaces/mod.ts';
 
 Deno.test('HttpKernel: matches static route and executes handler', async () => {
     const kernel = new HttpKernel();

src/__tests__/RouteBuilder.test.ts

@@ -4,9 +4,9 @@ import {
     assertNotEquals,
     assertThrows,
 } from 'https://deno.land/std@0.204.0/assert/mod.ts';
-import { IInternalRoute, IRouteDefinition } from '../Interfaces/mod.ts';
+import type { IInternalRoute, IRouteDefinition } from '../Interfaces/mod.ts';
 import { RouteBuilder } from '../mod.ts';
-import { Handler, Middleware } from '../Types/mod.ts';
+import type { Handler, Middleware } from '../Types/mod.ts';
 
 // Dummy objects
 // deno-lint-ignore require-await
@@ -91,7 +91,7 @@ Deno.test('handle: works with no middleware', async () => {
 Deno.test('handle: uses custom matcher factory', () => {
     let called = false;
 
-    const factory = (def: IRouteDefinition) => {
+    const factory = (_def: IRouteDefinition) => {
         called = true;
         return dummyMatcher;
     };