Add TypeScript support (#321)

Author: SiarheiFedartsou

.github/workflows/ci.yml

@@ -11,16 +11,45 @@ on:
 jobs:
   test:
     runs-on: ubuntu-24.04
+    strategy:
+      matrix:
+        node-version: ['18', '20', '22']
     steps:
       - name: Checkout code
         uses: actions/checkout@v3
-      - name: Set up Node.js
+      - name: Set up Node.js ${{ matrix.node-version }}
         uses: actions/setup-node@v3
         with:
-          node-version: '22'
+          node-version: ${{ matrix.node-version }}
       - name: Install dependencies
         run: npm install
       - name: Run lint
         run: npm run lint
       - name: Run tests
-        run: npm run test
+        run: npm run test
+
+  typescript:
+    runs-on: ubuntu-24.04
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v3
+      - name: Set up Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: '22'
+      - name: Install dependencies
+        run: npm install
+      - name: Validate TypeScript declarations
+        run: npm run validate-types
+      - name: Type check TypeScript example
+        run: npm run type-check
+      - name: Test TypeScript example compilation and execution
+        run: |
+          npx tsc example.ts
+          node example.js
+          rm example.js
+      - name: Verify TypeScript can consume the package
+        run: |
+          echo "import osrmTextInstructions = require('./index'); const compiler = osrmTextInstructions('v5'); console.log('TypeScript import works!');" > test-import.ts
+          npx tsc --noEmit test-import.ts
+          rm test-import.ts

CHANGELOG.md

@@ -1,6 +1,9 @@
 # Change Log
 All notable changes to this project will be documented in this file. For change log formatting, see http://keepachangelog.com/
 
+## Unreleased
+- Add TypeScript support. [#321](https://github.com/Project-OSRM/osrm-text-instructions/pull/321)
+
 ## 0.15.0 2024-03-03
 
 - This package now requires Node 16 and above. [#312](https://github.com/Project-OSRM/osrm-text-instructions/pull/312)

README.md

@@ -8,6 +8,7 @@ OSRM Text Instructions is a Node.js library that transforms route data generated
 * **Customizable**: Flexible options allow you to format and tweak the results to your liking.
 * **Cross-platform**: A data-driven approach facilitates implementations in other programming languages. OSRM Text Instructions is also available [in Swift and Objective-C](https://github.com/Project-OSRM/osrm-text-instructions.swift/) (for iOS, macOS, tvOS, and watchOS) and [in Java](https://github.com/Project-OSRM/osrm-text-instructions.java/) (for Android and Java SE).
 * **Well-tested**: A data-driven test suite ensures compatibility across languages and platforms.
+* **TypeScript Support**: Full TypeScript type definitions are included for enhanced development experience.
 
 ## Usage
 
@@ -24,6 +25,32 @@ response.legs.forEach(function(leg) {
 });
 ```
 
+### TypeScript Usage
+
+```typescript
+import osrmTextInstructions = require('osrm-text-instructions');
+
+const compiler = osrmTextInstructions('v5');
+
+const step: osrmTextInstructions.RouteStep = {
+  maneuver: {
+    type: 'turn',
+    modifier: 'left'
+  },
+  name: 'Main Street'
+};
+
+const options: osrmTextInstructions.CompileOptions = {
+  legCount: 2,
+  legIndex: 0,
+  formatToken: (token: string, value: string) => {
+    return token === 'way_name' ? `<strong>${value}</strong>` : value;
+  }
+};
+
+const instruction = compiler.compile('en', step, options);
+```
+
 If you are unsure if the user's locale is supported by osrm-text-inustrctions, use [@mapbox/locale-utils](https://github.com/mapbox/locale-utils) for finding the best fitting language.
 
 #### Parameters `require('osrm-text-instructions')(version)`

example.ts

@@ -0,0 +1,107 @@
+// Example usage of osrm-text-instructions with TypeScript
+
+import osrmTextInstructions = require('./index');
+
+// Initialize the compiler for OSRM v5
+const compiler = osrmTextInstructions('v5');
+
+// Example route step data
+const step: osrmTextInstructions.RouteStep = {
+  maneuver: {
+    type: 'turn',
+    modifier: 'left',
+    bearing_after: 90
+  },
+  name: 'Main Street',
+  ref: 'A1',
+  mode: 'driving',
+  intersections: [
+    {
+      lanes: [
+        { valid: false },
+        { valid: true }
+      ]
+    }
+  ]
+};
+
+// Compile options
+const options: osrmTextInstructions.CompileOptions = {
+  legCount: 2,
+  legIndex: 0,
+  classes: ['primary'],
+  formatToken: (token: string, value: string) => {
+    if (token === 'way_name') {
+      return `<strong>${value}</strong>`;
+    }
+    return value;
+  }
+};
+
+try {
+  // Generate instruction
+  const instruction = compiler.compile('en', step, options);
+  console.log('Instruction:', instruction);
+
+  // Get way name
+  const wayName = compiler.getWayName('en', step, options);
+  console.log('Way name:', wayName);
+
+  // Get direction from degree
+  const direction = compiler.directionFromDegree('en', 90);
+  console.log('Direction:', direction);
+
+  // Ordinalize number
+  const ordinal = compiler.ordinalize('en', 1);
+  console.log('Ordinal:', ordinal);
+
+  // Generate lane configuration
+  const laneConfig = compiler.laneConfig(step);
+  console.log('Lane config:', laneConfig);
+
+  // Capitalize first letter
+  const capitalized = compiler.capitalizeFirstLetter('en', 'hello world');
+  console.log('Capitalized:', capitalized);
+
+  // Access abbreviations
+  const abbreviations = compiler.abbreviations;
+  console.log('Available abbreviations:', Object.keys(abbreviations));
+
+} catch (error) {
+  console.error('Error:', error);
+}
+
+// Example with different maneuver types
+const departStep: osrmTextInstructions.RouteStep = {
+  maneuver: {
+    type: 'depart',
+    bearing_after: 0
+  },
+  name: 'Start Street'
+};
+
+const arriveStep: osrmTextInstructions.RouteStep = {
+  maneuver: {
+    type: 'arrive',
+    modifier: 'right'
+  },
+  name: 'Destination Avenue'
+};
+
+const roundaboutStep: osrmTextInstructions.RouteStep = {
+  maneuver: {
+    type: 'roundabout',
+    modifier: 'right',
+    exit: 2
+  },
+  rotary_name: 'Main Roundabout'
+};
+
+// Compile different instruction types
+const departInstruction = compiler.compile('en', departStep);
+const arriveInstruction = compiler.compile('en', arriveStep, { waypointName: 'Home' });
+const roundaboutInstruction = compiler.compile('en', roundaboutStep);
+
+console.log('Depart:', departInstruction);
+console.log('Arrive:', arriveInstruction);
+console.log('Roundabout:', roundaboutInstruction);