TypeScript for real code · Chapter 31 of 36

Describing JavaScript

By the end of this chapter you can describe JavaScript that TypeScript cannot see (globals from other scripts, libraries with no types) with declarations, and add your own property to globalThis without a cast. Build it in your browser: a real editor and terminal, AI that explains, and tests that tell you when it works.

  • Part: Real-world TypeScript
  • 4 tasks
  • TypeScript
  • In the all labs plan

The first 2 chapters of TypeScript for real code are free. This one comes with the all labs plan.

Why you need this

Tapri's web page loads two scripts before the app: one sets the shop's config, and the other is the receipt printer's library from a vendor. A third, from the UPI vendor, adds a payment function. None of them has types. Kabir cannot rewrite the vendors' code, and Bunty has been calling all of it through any. Last week a receipt read Total ₹undefined: the printer wanted a list of lines and got one string.

TypeScript only knows what it can see. A name that some other script creates is "Cannot find name", and with any every call compiles, right or wrong. What it needs is a description it can check every use against.

What you build: 4 tasks

Each task has tests. You write the code in the lab's editor and press Check.

  1. Task 1

    TAPRI_CONFIG: declare the shop's config

    The shop's config is a global called TAPRI_CONFIG, set by a script tag before the app runs, for example { city: 'Bengaluru', gstPercent: 5 }. Declare it, so shopConfig and gstFor type-check: city is a string and gstPercent a number, so shopConfig().city is a string, shopConfig().gstPercent is a number, and reading shopConfig().gst is a type error.

    With gstPercent 5, gstFor(40) is 42; with gstPercent 18, gstFor(100) is 118. Declare the value only: the page creates it, not exercise.ts.

  2. Task 2

    ChaiPrinter: describe the printer library

    The vendor's printer library is a global called chaiPrinter. Describe it as an exported interface ChaiPrinter with two methods: print(lines) takes the receipt's lines, a string[], and returns the job id, a number; status(jobId) takes a number and returns 'queued', 'printing' or 'done'. Then print('masala chai') is a type error (a receipt is a list of lines), so is status('job-1'), and so is comparing a status with 'lost'.

    Declare chaiPrinter with that interface instead of Bunty's any, so printReceipt returns a number and isPrinted returns a boolean.

  3. Task 3

    upiPay: declare the vendor's payment function

    The UPI vendor's script adds a global function upiPay(amountPaise, vpa): the amount is a number of paise, the vpa is a string, and it returns a promise of { ok: boolean; ref: string }. Declare it, so payForOrder type-checks and returns exactly Promise<string>.

    payForOrder(65, 'meera@upi') calls upiPay(6500, 'meera@upi') and resolves to the ref; when ok is false it rejects.

  4. Task 4 · interview question

    Interview: tapriVersion on globalThis, without a cast

    The build puts the app's version on globalThis.tapriVersion (a string), and it is missing in development, so its type is string | undefined. Add it to the global scope with declare global, so globalThis.tapriVersion type-checks with no cast, and setting it to 7 is a type error.

    Remove Bunty's as any, so appVersion returns exactly string: appVersion() is 'dev' when no version is set, and '2.4.0' when globalThis.tapriVersion is '2.4.0'. Dev will ask why a declare const would not do here, and why the cast is worse.

What you will learn

  • declare: tell TypeScript a value exists, and its type, without creating it.
  • Describing a library: an interface for its methods, and one declared global with that type; .d.ts files and declare module for packages.
  • declare global: add a property to globalThis from a module, so it needs no cast.

More in Real-world TypeScript

Build "Describing JavaScript" yourself

Tapri’s codebase grows, and types keep it honest. A real editor and terminal in your browser, AI that explains, and a Check that says when it works.

The first 2 chapters of TypeScript for real code are free. This one comes with the all labs plan.