math2-platform/shared/types

@math-platform/shared-types

TypeScript type definitions shared between frontend and backend applications.

Purpose

Eliminates duplication and misalignment between frontend and backend type definitions.

Structure

shared/types/
├── package.json          # Package configuration
├── tsconfig.json         # TypeScript configuration
└── src/
    ├── index.ts          # Main entry point - exports all types
    ├── auth.ts           # Authentication types
    ├── exercise.ts       # Exercise and attempt types
    ├── module.ts         # Module and topic types
    ├── progress.ts       # Progress tracking types
    ├── achievement.ts    # Achievement and badge types
    ├── ranking.ts        # Leaderboard types
    ├── api.ts            # Generic API types
    ├── error.ts          # Error types and classes
    └── utils.ts          # Utility types

Installation

Frontend

Types are accessed via path mapping in tsconfig.json:

{
  "compilerOptions": {
    "paths": {
      "@math-platform/shared-types": ["../shared/types/src"],
      "@math-platform/shared-types/*": ["../shared/types/src/*"]
    }
  }
}

Backend

Same path mapping in tsconfig.json:

{
  "compilerOptions": {
    "paths": {
      "@math-platform/shared-types": ["../../shared/types/src"],
      "@math-platform/shared-types/*": ["../../shared/types/src/*"]
    }
  }
}

Usage

Import Types

// Import specific types
import type { 
  User, 
  Exercise, 
  LoginRequest, 
  LoginResponse,
  SubmitAttemptRequest,
  SubmitAttemptResponse,
  ApiResponse 
} from '@math-platform/shared-types';

// Import from specific module
import type { LoginRequest, LoginResponse } from '@math-platform/shared-types/auth';
import type { Exercise, SubmitAttemptRequest } from '@math-platform/shared-types/exercise';

Import Classes

// Error classes are exported as values
import { 
  ApplicationError,
  ValidationError,
  NotFoundError 
} from '@math-platform/shared-types';

Key Contracts

1. Submit Attempt

Request:

interface SubmitAttemptRequest {
  answer: string;
  timeSpent: number;
  hintsUsed?: number;
  skipped?: boolean;
}

Response:

interface SubmitAttemptResponse {
  isCorrect: boolean;
  points: number;
  message: string;
  correctAnswer?: string;
  solutionSteps?: SolutionStep[];
  newAchievements?: AchievementUnlock[];
}

2. Auth

Login Request:

interface LoginRequest {
  email: string;
  password: string;
}

Login Response:

interface LoginResponse {
  token: string;
  refreshToken?: string;
  expiresIn?: number;
  user: User;
}

3. API Response

interface ApiResponse<T = unknown> {
  success: boolean;
  data?: T;
  error?: ApiError;
  meta?: ApiMeta;
}

Migration Guide

Before (Duplicated)

Frontend: frontend/src/types/index.ts

export interface LoginData {
  email: string;
  password: string;
}

Backend: backend/src/shared/types/index.ts

export interface LoginInput {
  email: string;
  password: string;
}

After (Shared)

Both use:

import type { LoginRequest } from '@math-platform/shared-types';

Best Practices

1. Always use type imports for type-only imports to avoid circular dependencies
2. Keep types serializable - use string for dates, not Date objects
3. Document breaking changes in CHANGELOG.md
4. Don't import from specific backend/frontend packages - keep this package independent

Building

cd shared/types
npm install
npm run build

Type Checking

npm run type-check