Forestil dig en virksomhed, som modtager forespørgsler om fjernelse af træstubbe.
Én kunde har en enkelt stub midt i græsplænen. En anden har fem stubbe langs en gammel hæk. En tredje ønsker også at få undersøgt rødder, der ligger i vejen for en ny sti.
Hvordan kan vi beskrive disse opgaver i et program uden at miste vigtige oplysninger?
Vi kan begynde med TypeScript.
I denne tutorial bygger vi en lille datamodel, validerer indholdet og skriver automatiske tests.
Vi beregner ikke priser og afgør ikke, om maskinarbejde kan udføres sikkert. De beslutninger kræver faglige oplysninger, som vores eksempel ikke har.
Målet er blot at skabe pålidelige administrative data.
1. Hvorfor bruge TypeScript?
JavaScript er fleksibelt.
Det kan være en fordel, men også en udfordring, hvis mange oplysninger skal registreres på samme måde.
Forestil dig, at et program modtager følgende objekt:
```javascript id="st01"
const job = {
area: "Kolding",
stumpCount: "three",
access: "unknown"
};
Her er `stumpCount` en tekst, selv om vi forventer et tal.
Det kan skabe problemer senere.
TypeScript kan hjælpe os med at beskrive den forventede struktur og opdage mange fejl under udviklingen.
Men der er en vigtig begrænsning:
**TypeScript-typer kontrollerer ikke automatisk data, der kommer udefra, mens programmet kører.**
Derfor skal vi både bruge typer og almindelig validering.
## 2. Definér opgavens oplysninger
Vi starter med en model til registrering af træstubbe.
Opret en fil med navnet `stump-jobs.ts`.
```typescript id="st02"
type AccessType =
| "open"
| "limited"
| "unknown";
type GroundUse =
| "lawn"
| "planting"
| "paving"
| "undecided";
type StumpJob = {
id: string;
area: string;
stumpCount: number;
access: AccessType;
futureUse: GroundUse;
undergroundServicesChecked: boolean;
};
Modellen indeholder seks felter.
id identificerer registreringen.
area beskriver det overordnede geografiske område.
stumpCount fortæller, hvor mange stubbe der er registreret.
access beskriver de foreløbige adgangsforhold.
futureUse viser, hvad kunden ønsker at bruge området til bagefter.
undergroundServicesChecked angiver, om oplysninger om nedgravede installationer er blevet gennemgået administrativt.
Det sidste felt er vigtigt at forstå korrekt.
En værdi på true betyder ikke, at stedet er sikkert at fræse. Det betyder kun, at den definerede kontrol er registreret som gennemført.
Den faktiske vurdering kræver en separat arbejdsproces.
3. Opret et eksempel på en opgave
Nu kan vi oprette en registrering med den nye type.
```typescript id="st03"
const exampleJob: StumpJob = {
id: "JOB-001",
area: "Kolding",
stumpCount: 3,
access: "limited",
futureUse: "lawn",
undergroundServicesChecked: false
};
Denne opgave indeholder tre stubbe.
Adgangsforholdene er foreløbigt beskrevet som begrænsede.
Kunden ønsker at bruge området til græsplæne.
Og oplysninger om nedgravede installationer er endnu ikke markeret som gennemgået.
Det er fiktive data, som kun bruges i tutorialen.
## 4. Hvorfor skal vi validere data igen?
Forestil dig, at en anden del af programmet sender dette:
```typescript id="st04"
const incomingData: unknown = {
id: "JOB-002",
area: "Kolding",
stumpCount: -4,
access: "very easy",
futureUse: "lawn",
undergroundServicesChecked: "yes"
};
Objektet indeholder flere problemer.
Antallet af stubbe er negativt.
Adgangstypen findes ikke på vores liste.
Og den sidste værdi er en tekst i stedet for en boolean.
Når data kommer fra en formular, en fil eller en API, bør vi behandle dem som unknown, indtil de er kontrolleret.
Det er netop det, vi skal gøre nu.
5. Byg en valideringsfunktion
Først opretter vi en type til resultatet.
```typescript id="st05"
type ValidationResult =
| {
valid: true;
data: StumpJob;
}
| {
valid: false;
errors: string[];
};
Dette er en *discriminated union*.
Når `valid` er `true`, ved TypeScript, at resultatet indeholder `data`.
Når `valid` er `false`, indeholder det en liste over fejl.
Nu skriver vi selve funktionen:
```typescript id="st06"
function validateStumpJob(
input: unknown
): ValidationResult {
const errors: string[] = [];
if (
typeof input !== "object" ||
input === null ||
Array.isArray(input)
) {
return {
valid: false,
errors: ["Opgaven skal være et objekt."]
};
}
const item = input as Record<string, unknown>;
if (
typeof item.id !== "string" ||
item.id.trim().length === 0
) {
errors.push("Opgaven mangler et gyldigt ID.");
}
if (
typeof item.area !== "string" ||
item.area.trim().length === 0
) {
errors.push("Område mangler.");
}
if (
typeof item.stumpCount !== "number" ||
!Number.isInteger(item.stumpCount) ||
item.stumpCount < 1
) {
errors.push(
"Antal stubbe skal være et positivt heltal."
);
}
const accessValues = [
"open",
"limited",
"unknown"
];
if (!accessValues.includes(String(item.access))) {
errors.push("Ugyldig adgangstype.");
}
const groundUses = [
"lawn",
"planting",
"paving",
"undecided"
];
if (!groundUses.includes(String(item.futureUse))) {
errors.push("Ugyldig anvendelse af området.");
}
if (
typeof item.undergroundServicesChecked !==
"boolean"
) {
errors.push(
"Kontrolstatus skal være true eller false."
);
}
if (errors.length > 0) {
return {
valid: false,
errors
};
}
return {
valid: true,
data: item as StumpJob
};
}
Funktionen kontrollerer hvert felt.
Hvis noget mangler eller har en ugyldig værdi, returnerer den en fejl.
Hvis alle oplysninger opfylder vores model, returnerer den det validerede objekt.
Bemærk forskellen mellem en korrekt datastruktur og en korrekt faglig beslutning.
Funktionen kontrollerer kun strukturen.
Den kan ikke vide, om den registrerede information stemmer med de faktiske forhold i haven.
6. Test resultatet
Vi starter med det gyldige eksempel.
```typescript id="st07"
const result = validateStumpJob(exampleJob);
if (result.valid) {
console.log(
Registreret ${result.data.stumpCount} stubbe
);
} else {
console.log(result.errors);
}
For vores eksempel bliver resultatet:
```text id="st08"
Registreret 3 stubbe
Hvis vi bruger de ugyldige data, får vi i stedet en liste med fejl.
Det gør det nemmere at give præcis feedback til den del af programmet, der sender oplysningerne.
7. Tilføj en funktion til administrative opfølgninger
En registreret opgave kan være teknisk gyldig, selv om nogle oplysninger endnu mangler at blive undersøgt.
For eksempel kan adgangsforholdene være ukendte.
Det betyder ikke, at registreringen skal afvises.
I stedet kan vi oprette en liste over administrative opfølgninger.
```typescript id="st09"
function getFollowUps(job: StumpJob): string[] {
const followUps: string[] = [];
if (job.access === "unknown") {
followUps.push(
"Adgangsforhold skal beskrives."
);
}
if (job.access === "limited") {
followUps.push(
"Maskinadgang skal vurderes af fagperson."
);
}
if (job.futureUse === "undecided") {
followUps.push(
"Kundens planer for området skal afklares."
);
}
if (!job.undergroundServicesChecked) {
followUps.push(
"Oplysninger om nedgravede installationer " +
"skal gennemgås."
);
}
return followUps;
}
Funktionen returnerer ikke en pris.
Den vælger heller ikke maskine, arbejdsdybde eller sikkerhedsafstande.
Den gør kun opmærksom på oplysninger, der kræver yderligere behandling.
For vores eksempel får vi to opfølgninger:
```typescript id="st10"
console.log(getFollowUps(exampleJob));
Resultat:
```text id="st11"
[
"Maskinadgang skal vurderes af fagperson.",
"Oplysninger om nedgravede installationer skal gennemgås."
]
Det er et eksempel på automatisering, der hjælper en medarbejder uden at erstatte vedkommendes vurdering.
## 8. Skriv automatiske tests
Nu skal vi sikre, at vores funktioner opfører sig som forventet.
Vi holder eksemplet enkelt og bruger en lille testfunktion uden eksterne testbiblioteker.
```typescript id="st12"
function assert(
condition: boolean,
message: string
): void {
if (!condition) {
throw new Error(`Test fejlede: ${message}`);
}
}
Herefter tilføjer vi vores tests.
```typescript id="st13"
const validResult = validateStumpJob(exampleJob);
assert(
validResult.valid,
"En gyldig opgave skal accepteres."
);
const invalidCount = validateStumpJob({
...exampleJob,
stumpCount: -2
});
assert(
!invalidCount.valid,
"Et negativt antal skal afvises."
);
const invalidAccess = validateStumpJob({
...exampleJob,
access: "very easy"
});
assert(
!invalidAccess.valid,
"Ukendte adgangstyper skal afvises."
);
const followUps = getFollowUps(exampleJob);
assert(
followUps.length === 2,
"Eksemplet skal give to opfølgninger."
);
console.log("Alle tests bestået.");
Hvis alle tests passerer, bliver resultatet:
```text id="st14"
Alle tests bestået.
Hvis en test fejler, bliver der kastet en fejl.
Det er en enkel måde at lære automatiseret testning på.
I en større applikation kan man bruge et egentligt testbibliotek, men principperne er de samme:
Definér den forventede adfærd, og kontrollér den automatisk.
9. Sådan kører du eksemplet
Du skal have Node.js og TypeScript installeret.
Opret et lille projekt:
```bash id="st15"
mkdir stump-jobs
cd stump-jobs
npm init -y
npm install --save-dev typescript
Gem alle TypeScript-eksemplerne i samme fil, `stump-jobs.ts`, i den rækkefølge, de er vist.
De ugyldige eksempeldata kan bruges direkte som testinput.
Kompilér filen:
```bash id="st16"
npx tsc stump-jobs.ts --target es2020 --module commonjs --strict
Kør derefter den genererede JavaScript-fil:
```bash id="st17"
node stump-jobs.js
Du bør se output fra både registreringen, opfølgningerne og testene.
Før koden bruges i et rigtigt system, bør tests og produktionskode placeres i separate filer.
## 10. Hvorfor må vi ikke automatisere arbejdsmetoden?
Nu har vi en datamodel, som kan håndtere oplysninger om stubfræsning.
Det kunne være fristende at udvide den med regler som:
"Hvis stubben er lille, skal der bruges en bestemt maskine."
Eller:
"Hvis der er god adgang, kan arbejdet udføres uden yderligere kontrol."
Men den slags regler ville være misvisende.
Størrelse og adgang fortæller ikke hele historien.
Der kan være kabler og rør under jorden, sten omkring stubben eller levende trærødder tæt på arbejdsområdet.
Derfor bør et almindeligt administrationssystem ikke automatisk fastslå, at en opgave er sikker.
Det bør i stedet gøre det tydeligt, hvilke oplysninger der er registreret, og hvad der kræver en faglig vurdering.
**Et gyldigt objekt er ikke det samme som en sikker arbejdsplads.**
## 11. En virkelig branchekontekst
Skovhugger Lund er en træservicevirksomhed med base i Kolding.
Virksomheden tilbyder blandt andet stubfræsning, rodfræsning og fjernelse af gamle hækstubbe i Syddanmark.
Opgaverne kan variere fra én enkelt stub i en privat have til større områder med mange stubbe og rødder.
På virksomhedens side om [stubfræsning i Kolding](https://www.skovhuggerlund.dk/stubfraesning/) beskrives både de forskellige maskintyper og muligheden for efterbehandling af området.
Det er et godt eksempel på, hvorfor en datamodel kan indeholde oplysninger om antal, adgang og fremtidig anvendelse.
Disse felter kan hjælpe med at organisere en forespørgsel, men de kan ikke alene afgøre, hvordan arbejdet skal udføres.
Tutorialen er et selvstændigt programmeringseksempel. Den beskriver ikke et system, som Skovhugger Lund bruger i dag.
## 12. Hvad ville jeg forbedre i en rigtig applikation?
Vores model er lille og overskuelig, men en produktionsløsning ville kræve mere arbejde.
Jeg ville især se på fire områder.
**Servervalidering:** Alle data, der kommer fra brugere eller eksterne tjenester, skal valideres på serveren.
**Databeskyttelse:** Et egentligt kundesystem skal håndtere personoplysninger sikkert og kun opbevare nødvendige data.
**Adgangskontrol:** Det skal være tydeligt, hvem der må oprette, læse og ændre opgaver.
**Sporbarhed:** Ændringer i administrative statusser bør kunne dokumenteres, så medarbejdere kan forstå, hvad der er blevet registreret.
Man kan også overveje at bruge et bibliotek til skemavalidering, hvis datamodellen bliver større.
Men det er en god øvelse først at forstå valideringen uden ekstra afhængigheder.
## Afslutning
Vi har nu oprettet en typesikker datamodel, bygget en valideringsfunktion og skrevet automatiske tests.
Eksemplet viser, hvordan TypeScript kan hjælpe med at skabe mere ensartede registreringer.
Det viser også, hvorfor et godt system skal kende sine egne begrænsninger.
Software kan sikre, at et antal er positivt, og at en opgavetype findes på en godkendt liste.
Men den kan ikke ud fra disse oplysninger alene vurdere jordforhold, maskinsikkerhed eller arbejdsmetoder.
Den forskel er vigtig.
**God kode organiserer det, vi ved, og gør det tydeligt, hvad vi stadig mangler at undersøge.**

Top comments (0)