How to Integrate the TypeScript Interface for Dataset Access in hasaneyldrm/exercises-dataset

Import the JSON data from data/exercises.json, cast it to the Exercise[] type defined in the README, and enable resolveJsonModule in your tsconfig.json to achieve full compile-time type safety when accessing the multilingual exercise dataset.

The hasaneyldrm/exercises-dataset repository provides a comprehensive catalogue of fitness exercises stored in a structured JSON format. To integrate the TypeScript interface for dataset access, you import the data file and apply the Exercise interface documented in README.md at lines 998–1036. This method provides IntelliSense autocomplete and compile-time validation for all properties including nested multilingual instruction objects.

Understanding the Dataset Structure

The raw dataset resides in data/exercises.json, which exports a JSON array where each element conforms to the Exercise interface schema. According to the hasaneyldrm/exercises-dataset source code, the interface defines primitive fields including id, name, category, body_part, equipment, muscle_group, target, media_id, image, gif_url, attribution, and created_at.

The schema also contains complex nested structures for internationalization:

• instructions: An object with string properties for ten languages (en, es, it, tr, ru, zh, hi, pl, ko, fr)
• instruction_steps: A parallel object where each language maps to a string array
• secondary_muscles: A string array listing additional muscle groups targeted by the exercise

Configuring TypeScript for JSON Imports

Before integrating the interface, ensure your TypeScript compiler can resolve JSON modules. Create or update your tsconfig.json to include these compiler options:

{
  "compilerOptions": {
    "resolveJsonModule": true,
    "esModuleInterop": true,
    "strict": true
  }
}

The resolveJsonModule flag allows direct imports of .json files with type inference, while esModuleInterop ensures compatibility between CommonJS and ES module formats when loading the dataset.

Implementing the TypeScript Integration

Follow this workflow to integrate the TypeScript interface for dataset access in your application.

Import the Dataset and Interface

First, import the exercise data and define the Exercise interface in your TypeScript file. The interface declaration mirrors the schema documented in the repository's README.md:

import exercises from "./data/exercises.json";

interface Exercise {
  id: string;
  name: string;
  category: string;
  body_part: string;
  equipment: string;
  instructions: {
    en: string;
    es: string;
    it: string;
    tr: string;
    ru: string;
    zh: string;
    hi: string;
    pl: string;
    ko: string;
    fr: string;
  };
  instruction_steps: {
    en: string[];
    es: string[];
    it: string[];
    tr: string[];
    ru: string[];
    zh: string[];
    hi: string[];
    pl: string[];
    ko: string[];
    fr: string[];
  };
  muscle_group: string;
  secondary_muscles: string[];
  target: string;
  media_id: string;
  image: string;
  gif_url: string;
  attribution: string;
  created_at: string;
}

Type Assertion and Basic Queries

Cast the imported JSON to the Exercise[] type to enable full type safety. This assertion tells the TypeScript compiler to treat the raw JSON data as an array of Exercise objects:

const data = exercises as Exercise[];

// Filter with type-safe property access
const bodyweight = data.filter(ex => ex.equipment === "body weight");
console.log(`Found ${bodyweight.length} body-weight exercises`);

Accessing Multilingual Content

Use dot notation to access language-specific instructions. The nested structure provides type-safe access to each supported language without runtime guesswork:

function getEnglishInstruction(id: string): string | undefined {
  const ex = data.find(e => e.id === id);
  return ex?.instructions.en;
}

// Retrieve step-by-step instructions for Turkish users
const turkishSteps = data[0].instruction_steps.tr;

Advanced Data Operations

Leverage TypeScript's type inference when transforming the dataset. The compiler validates property access in array methods like filter, map, and reduce:

// Build a random workout with compile-time validation
const randomWorkout = data
  .sort(() => Math.random() - 0.5)
  .slice(0, 6)
  .map(e => `${e.name} (${e.target})`);

// Group exercises by muscle group with proper typing
const byMuscle = data.reduce<Record<string, Exercise[]>>((acc, ex) => {
  acc[ex.muscle_group] = acc[ex.muscle_group] ?? [];
  acc[ex.muscle_group].push(ex);
  return acc;
}, {});

Working with the Exercise Interface

The Exercise interface serves as a self-documenting contract between the dataset and your application logic. By implementing this interface, you ensure that any consumer—whether frontend components, backend APIs, or data processing scripts—can safely access properties without runtime errors.

When integrating the TypeScript interface for dataset access, remember that the secondary_muscles field is typed as string[] and the created_at field follows ISO 8601 formatting as a string. The multilingual objects ensure your application can serve content in English, Spanish, Italian, Turkish, Russian, Chinese, Hindi, Polish, Korean, or French with full type safety.

Summary

• Import path: Load the dataset from data/exercises.json using ES6 import syntax after enabling resolveJsonModule and esModuleInterop in tsconfig.json
• Type definition: The Exercise interface is defined in README.md lines 998–1036 and provides complete type coverage for all JSON properties including nested multilingual fields
• Type safety: Cast imported data to Exercise[] to enable compile-time checking for property names, data types, and language codes
• Multilingual access: Reference ten languages through the instructions and instruction_steps nested objects using standard dot notation (e.g., ex.instructions.es, ex.instruction_steps.fr)
• Zero dependencies: The dataset requires no external packages—only standard TypeScript JSON module resolution

Frequently Asked Questions

Where is the Exercise interface defined in the repository?

The Exercise interface is documented in the README.md file at lines 998–1036 of the hasaneyldrm/exercises-dataset repository. This definition includes all primitive fields, nested multilingual objects, and array types that mirror the structure of data/exercises.json.

Do I need to install any npm packages to use this dataset?

No. The hasaneyldrm/exercises-dataset repository contains no external dependencies. You only need TypeScript configured with resolveJsonModule: true in your tsconfig.json to import the JSON file directly and apply the interface type definitions.

How do I handle missing or optional fields in the Exercise interface?

While the interface defines secondary_muscles as string[], you should use optional chaining (?.) when accessing potentially undefined nested properties. The TypeScript compiler will enforce that you check for property existence before accessing multilingual instruction fields.

Can I use this interface in a JavaScript project without TypeScript?

Yes, you can use the data/exercises.json file in JavaScript, but you will lose compile-time type safety. The interface serves as documentation for the expected schema. JavaScript consumers should manually validate the data structure or use runtime validation libraries like Zod that match the Exercise interface shape.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}