Fetch Handler

Leichtgewichtiger HTTP-Client auf Basis der nativen Fetch API. Um typische Netzwerkoperationen im Frontend zu vereinheitlichen und zu vereinfachen. Im Mittelpunkt steht eine klare, konsistente Schnittstelle für alle HTTP-Methoden wie GET, POST, PUT, PATCH und DELETE. Dabei werden wiederkehrende Aufgaben wie JSON-Verarbeitung, QueryString-Erstellung, File-Uploads über FormData sowie Timeout- und Abort-Handling abstrahiert und automatisch übernommen.

Der FetchHandler ist so aufgebaut, dass er sowohl in kleinen Projekten als auch in größeren Anwendungen oder Framework-Strukturen problemlos eingesetzt werden kann. Jede Anfrage liefert ein standardisiertes Result-Objekt zurück, unabhängig davon, ob die Anfrage erfolgreich war, fehlschlug oder durch ein Timeout abgebrochen wurde. Fehler werden dabei nicht geworfen, sondern strukturiert im Ergebnis abgebildet. Der FetchHandler verwendet standardmäßig einen eigenen AbortController pro Request. Dadurch ist jede Anfrage isoliert und kann unabhängig von anderen Requests abgebrochen werden. Das verhindert unnötig laufende oder veraltete Requests, z.B. bei mehrfachen API-Aufrufen oder Live-Suche.

Initialisierung

document.addEventListener('kryzo:ready', async ({ detail: { FETCH } }) => {
    /* Ab hier stellen alle FETCH Funktionen zur Verfügung */
});

GET Request (Daten abrufen)


/* 
   Führt einen GET Request aus.
   Holt Daten vom Server und gibt JSON zurück.
*/

FETCH.get({
    url: '/api/users' /* API Endpoint für Benutzerliste */
}).then(result => {

    /* result.data enthält die vom Server zurückgegebenen Daten */
    console.log(result.data);

});

GET mit Parametern (QueryString)


/* 
   data wird automatisch in URL Query Parameter umgewandelt.
   Ideal für Filter, Pagination oder Suche.
*/

FETCH.get({
    url: '/api/users', /* Ziel-API - Ausgehend vom Root Pfad! */
    data: {
        page: 1,       /* Seite der Pagination */
        limit: 10,     /* Anzahl der Ergebnisse */
        search: 'max'  /* Suchbegriff */
    }
}).then(result => {

    console.log(result.data);

});

POST JSON (Login / Daten senden)


/* 
   Sendet JSON-Daten an den Server.
   Automatisch gesetzter Content-Type: application/json
*/

FETCH.post({
    url: '/api/login', /* Login Endpoint */
    data: {
        username: 'admin',    /* Benutzername */
        password: '123456'    /* Passwort */
    }
}).then(result => {

    /* Ergebnis vom Server (z.B. Token) */
    console.log(result.data);

});

POST FormData (Datei Upload)


/* 
   FormData wird automatisch erkannt.
   Perfekt für Datei-Uploads oder HTML Formulare.
*/

const form = new FormData();              /* Neues FormData Objekt */
form.append('name', 'Max');               /* Textfeld */
form.append('file', fileInput.files[0]);  /* Datei aus Input */

FETCH.post({
    url: '/api/upload', /* Upload Endpoint */
    data: form          /* FormData wird direkt gesendet */
}).then(result => {

    console.log(result.data);

});

Mehrere Dateien Upload


/* 
   Mehrere Dateien werden als Array übertragen.
   Backend verarbeitet meist files[] Struktur.
*/

const form = new FormData(); /* Container für Daten */

for (const file of fileInput.files) {
    form.append('files[]', file); /* Jede Datei einzeln hinzufügen */
}

FETCH.post({
    url: '/api/upload',
    data: form
}).then(result => {

    console.log(result.data);

});

PUT Request (kompletter Update)


/* 
   Ersetzt einen kompletten Datensatz.
   Alle Felder sollten vollständig übergeben werden.
*/

FETCH.put({
    url: '/api/users/1', /* Zielressource */
    data: {
        name: 'Max Mustermann', /* kompletter neuer Name */
        email: 'max@mail.de'    /* komplette neue E-Mail */
    }
}).then(result => {

    console.log(result.data);

});

PATCH Request (Teil-Update)


/* 
   Aktualisiert nur einzelne Felder.
   Restliche Daten bleiben unverändert.
*/

FETCH.patch({
    url: '/api/users/1',
    data: {
        active: true /* nur dieses Feld wird geändert */
    }
}).then(result => {

    console.log(result.data);

});

DELETE Request


/* 
   Löscht eine Ressource auf dem Server.
*/

FETCH.delete({
    url: '/api/users/1' /* zu löschender User */
}).then(result => {

    console.log(result.status); /* HTTP Status Code */

});

Custom Header (Auth Token)


/* 
   Fügt zusätzliche Header hinzu.
   Häufig für JWT oder API Keys verwendet.
*/

FETCH.get({
    url: '/api/private',
    headers: {
        Authorization: 'Bearer TOKEN' /* Authentifizierung */
    }
}).then(result => {

    console.log(result.data);

});

Timeout Request (Auto Abort)


/* 
   Request wird automatisch abgebrochen,
   wenn die Zeit überschritten wird.
*/

FETCH.get({
    url: '/api/slow',
    timeout: 5000 /* 5 Sekunden Timeout */
}).then(result => {

    if (result.aborted) {

        console.log('Request wurde abgebrochen (Timeout)');

    }

});

Text Response


/* 
   Antwort wird als reiner Text zurückgegeben.
*/

FETCH.get({
    url: '/robots.txt',
    responseType: 'text' /* keine JSON Verarbeitung */
}).then(result => {

    console.log(result.data); /* Textinhalt */

});

Blob Download (Datei / Bild)


/* 
   Lädt Binärdaten (z.B. Bilder) als Blob.
   Blob kann in eine URL umgewandelt werden.
*/

FETCH.get({
    url: '/image.jpg',
    responseType: 'blob' /* wichtig für Dateien */
}).then(result => {

    const url = URL.createObjectURL(result.data); /* temporäre Datei-URL */

    console.log(url); /* kann z.B. in  genutzt werden */

});

AbortController deaktivieren


/* 
   Deaktiviert automatisches Abbrechen des Requests.
*/

FETCH.get({
    url: '/api/data',
    useAbortController: false
}).then(result => {

    console.log(result.data);

});

Cookies / Session Requests


/* 
   Sendet Cookies mit (Login Sessions).
*/

FETCH.get({
    url: '/api/session',
    credentials: 'include' /* wichtig für Auth Sessions */
}).then(result => {

    console.log(result.data);

});