# How to Use the Exercises Dataset with TypeScript: A Complete Integration Guide

> Learn to integrate the exercises dataset into your TypeScript projects. This guide shows you how to import JSON data and generate compile-time types for seamless development.

- Repository: [Hasan Emir Yıldırım/exercises-dataset](https://github.com/hasaneyldrm/exercises-dataset)
- Tags: how-to-guide
- Published: 2026-08-01

---

**The exercises dataset from `hasaneyldrm/exercises-dataset` provides 1,324 fitness records as a static JSON file you can consume in TypeScript by importing [`data/exercises.json`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/data/exercises.json) directly and generating compile-time types from [`data/exercises.schema.json`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/data/exercises.schema.json).**

The `hasaneyldrm/exercises-dataset` repository offers a production-ready collection of fitness exercise metadata designed for immediate consumption in modern TypeScript applications. Because the dataset is entirely static—consisting of a single JSON file and associated media assets—you can integrate it into Node.js servers, Deno runtimes, or front-end bundles without managing external APIs or database connections.

## Understanding the Dataset Architecture

### The Data Layer

The core dataset resides in [`data/exercises.json`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/data/exercises.json) [[source]](https://github.com/hasaneyldrm/exercises-dataset/blob/main/data/exercises.json) and contains an array of **1,324 exercise objects**. Each record includes multilingual step-by-step instructions, equipment requirements, target muscle groups, and relative paths to associated media files.

### The Schema Layer

The repository includes [`data/exercises.schema.json`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/data/exercises.schema.json) [[source]](https://github.com/hasaneyldrm/exercises-dataset/blob/main/data/exercises.schema.json), a JSON Schema (Draft 2020-12) that defines type constraints and validation rules for every field. This schema enables automatic TypeScript interface generation, ensuring compile-time safety when accessing nested properties like `instructions.en` or `secondary_muscles`.

### Media Assets

Static assets are organized in `images/` (thumbnails) and `videos/` (animation GIFs), referenced by relative paths in each record's `image` and `gif_url` properties.

## Generating TypeScript Types from JSON Schema

To achieve full type safety and IDE autocompletion, generate interfaces from the provided schema using `json-schema-to-typescript`.

First, install the development dependency:

```bash
npm i -D json-schema-to-typescript

```

Generate the type definitions:

```bash
npx json2ts -i data/exercises.schema.json -o src/types/exercise.d.ts

```

The generated [`src/types/exercise.d.ts`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/src/types/exercise.d.ts) file contains a comprehensive interface matching the JSON structure:

```typescript
export 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: Record<string, string[]>;
  muscle_group: string;
  secondary_muscles: string[];
  target: string;
  media_id: string;
  image: string;
  gif_url: string;
  attribution: string;
}

```

## Loading the Dataset in TypeScript

### Node.js with ES Module Import Assertions

For Node.js 17+ using ES modules, import the JSON file directly with type assertions. This approach bundles the data at compile time, eliminating runtime fetch overhead.

```typescript
// src/data.ts
import type { Exercise } from './types/exercise';
import exercisesRaw from '../data/exercises.json' assert { type: 'json' };

export const exercises: Exercise[] = exercisesRaw as Exercise[];

```

### Browser and Fetch API

When serving the file from a static CDN or local development server, use the Fetch API with explicit type casting to populate your application state.

```typescript
export async function loadExercises(): Promise<Exercise[]> {
  const res = await fetch('/data/exercises.json');
  if (!res.ok) throw new Error('Failed to fetch exercises');
  const data = (await res.json()) as Exercise[];
  return data;
}

// Usage in a front-end component
loadExercises().then(exs => console.log(`Loaded ${exs.length} exercises`));

```

## Querying and Filtering Exercises

Once loaded into a typed array, you can leverage standard JavaScript array methods to search and filter the dataset efficiently.

### Searching by Name

Implement case-insensitive search to find specific movements:

```typescript
import { exercises } from './data';

export function searchByName(query: string): Exercise[] {
  const lowered = query.toLowerCase();
  return exercises.filter(e => e.name.toLowerCase().includes(lowered));
}

// Usage
const benchPresses = searchByName('bench press');
console.log(`Found ${benchPresses.length} bench-press variations`);

```

### Filtering by Equipment

Filter the dataset by equipment type to build targeted workout generators:

```typescript
export function filterByEquipment(equipment: string): Exercise[] {
  const lowered = equipment.toLowerCase();
  return exercises.filter(e => e.equipment.toLowerCase() === lowered);
}

// Example: Get all dumbbell exercises
const dumbbellExercises = filterByEquipment('dumbbell');
console.log(dumbbellExercises.slice(0, 3)); // first three results

```

### Bulk Inserting into SQLite

For persistent storage or complex querying, bulk-insert records into SQLite using prepared statements and transactions:

```typescript
import Database from 'better-sqlite3';
import { exercises } from './data';

const db = new Database('exercises.db');

db.exec(`
  CREATE TABLE IF NOT EXISTS exercises (
    id TEXT PRIMARY KEY,
    name TEXT,
    category TEXT,
    body_part TEXT,
    equipment TEXT,
    instructions TEXT,
    muscle_group TEXT,
    target TEXT,
    image TEXT,
    gif_url TEXT,
    attribution TEXT
  );
`);

const insert = db.prepare(`
  INSERT OR REPLACE INTO exercises
  (id, name, category, body_part, equipment, instructions, muscle_group, target, image, gif_url, attribution)
  VALUES (@id, @name, @category, @body_part, @equipment, @instructions, @muscle_group, @target, @image, @gif_url, @attribution);
`);

const insertMany = db.transaction((list: Exercise[]) => {
  for (const e of list) {
    insert.run({
      id: e.id,
      name: e.name,
      category: e.category,
      body_part: e.body_part,
      equipment: e.equipment,
      instructions: JSON.stringify(e.instructions),
      muscle_group: e.muscle_group,
      target: e.target,
      image: e.image,
      gif_url: e.gif_url,
      attribution: e.attribution,
    });
  }
});

insertMany(exercises);
console.log('All exercises inserted into SQLite');

```

## Summary

- The **exercises dataset** from `hasaneyldrm/exercises-dataset` contains **1,324 records** in [`data/exercises.json`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/data/exercises.json) with comprehensive metadata and multilingual instructions.
- Generate **TypeScript interfaces** automatically from [`data/exercises.schema.json`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/data/exercises.schema.json) using `json-schema-to-typescript` for compile-time safety and IDE autocompletion.
- Import the data directly using **ES module JSON assertions** (Node.js 17+) or the **Fetch API** for browser environments.
- Query records efficiently using standard array methods like `filter()` and `find()` on the typed `Exercise[]` array.
- Persist data to **SQLite**, PostgreSQL, or other databases using bulk-insert transactions for production performance.

## Frequently Asked Questions

### Can I use the exercises dataset with TypeScript without generating types?

Yes, you can import the JSON file directly and cast it using `as Exercise[]` or `any`, but generating types from [`data/exercises.schema.json`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/data/exercises.schema.json) provides compile-time checking and IDE autocomplete that prevents runtime errors when accessing nested properties like `instruction_steps.en`.

### How do I handle the image and GIF assets in a TypeScript application?

Each exercise record stores relative paths in the `image` and `gif_url` fields pointing to the `images/` and `videos/` directories. Resolve these by either copying the media folders to your public static directory (for Next.js, Vite, or similar) or prepending a CDN base URL to the path strings before rendering.

### Is the exercises dataset compatible with Deno?

Yes. Because the dataset is pure JSON, Deno can import it directly using `import exercises from './data/exercises.json' with { type: 'json' }` (note that Deno uses the `with` keyword for import attributes rather than Node.js's `assert` keyword). The same TypeScript interfaces generated from the schema work identically in Deno.

### What is the performance impact of loading all 1,324 exercises into memory?

The uncompressed JSON file is approximately a few hundred kilobytes, making it suitable for in-memory operations in most TypeScript environments. For high-frequency serverless functions or large-scale applications, consider loading the data once at startup, or bulk-inserting into a database as demonstrated in the SQLite example above to leverage SQL indexing for complex queries.