Teaching Parametric Design Backend

An Express + TypeScript API that takes JavaScript code and returns HTML-highlighted snippets with quick reference links.

Setup

1. Copy .env.example to .env and adjust as needed.
2. Install dependencies (requires Node.js 18+):

npm install

Scripts

• npm run dev — start the API in watch mode via ts-node.
• npm run build — compile TypeScript to dist/.
• npm start — run the compiled server from dist/.
• npm test — run the Vitest suite (uses JSDOM for HTML validation).
• npm run docs — generate TypeDoc output in docs/code/.
• npm run docs:api — build the Swagger UI bundle into docs/api/.

API

POST /api/linkify

Request body:

{
  "code": "const el = document.querySelector('.box');",
  "language": "en"
}

Behavior:

• Supports language: "en" | "de" (defaults to English) for localized links.
• Highlights the JavaScript with highlight.js and converts selected function names into links.

Response body:

{
  "html": "<pre><code class=\"hljs language-javascript\">…</code></pre>",
  "raw": "const el = document.querySelector('.box');",
  "functionCalls": [
    {
      "name": "createCanvas",
      "url": "https://parametric-design.fh-potsdam.de/en/2d/02_1-drawing/#canvas",
      "thumbnail": "/images/thumbnails/en_2d_drawing_canvas.png"
    },
    {
      "name": "max",
      "url": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/max",
      "thumbnail": null
    }
  ]
}

Browser bundle (no server needed)

browser/linkify.js is a single standalone file (~125 KB minified) containing the linkify logic, all link data and highlight.js. Rebuild it after changing src/ or data/:

npm run build:browser

Usage:

<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.11.1/styles/github.min.css">
<script src="linkify.js"></script>
<script>
  const { html, raw, functionCalls } = linkify("circle(10, 10, 5);", "de"); // language: "en" (default) | "de"
  document.querySelector("#out").innerHTML = html;
</script>

It returns the same shape as POST /api/linkify. The function is also available as ParametricLinkify.linkify.

GET /api/ping

Returns pong as a quick health check.

OpenAPI

See the OpenAPI 3.0 specification in openapi.yaml.

Swagger UI

Build the static Swagger UI bundle into docs/api/:

npm run docs:api

When the server is running, visit http://localhost:3000/docs/ to view the docs.

Code Docs

Generate the TypeDoc documentation into docs/code/:

npm run docs

Environment Variables

• PORT — API port (default: 3000).
• ALLOW_LOCALHOST_CORS — set to true to allow CORS requests from localhost/127.0.0.1.

Notes

• Function references are linked against MDN, p5.js, and Parametric Design references (localized when available).