Choose A Movie For Me - Data Source

Una libreria TypeScript moderna e completa per interagire con le API di TMDB (The Movie Database) v3

📖 Documentazione • 🚀 Quick Start • 💡 Esempi • 📝 Changelog

📦 Installazione

# Con npm
npm install choose-a-movie-for-me-data-source

# Con yarn
yarn add choose-a-movie-for-me-data-source

# Con pnpm
pnpm add choose-a-movie-for-me-data-source

✨ Caratteristiche

• 🎯 Completamente tipizzata con TypeScript per massima type safety
• 🚀 API moderna con Promise, async/await e sintassi intuitiva
• 🛡️ Gestione errori robusta con classi di errore specifiche
• 🔧 Altamente configurabile con supporto per lingue, regioni e URL personalizzati
• 📦 Tree-shakable per bundle ottimizzati e performance migliori
• 🧪 Completamente testata con suite di test comprensiva
• 📚 Documentazione estesa con esempi pratici e guide dettagliate
• ⚡ Leggera e performante con dipendenze minime

🎬 Cosa Puoi Fare

| Categoria | Funzionalità | |-----------|-------------| | 🎥 Film | Ricerca, dettagli, liste curate, scoperta avanzata, raccomandazioni, cast/crew | | 📺 Serie TV | Ricerca, dettagli, stagioni/episodi, liste, scoperta, raccomandazioni | | 👥 Persone | Ricerca attori/registi, biografie, filmografie, trending | | 📱 Watch Providers | Provider streaming per regione, piattaforme per film/TV, regioni disponibili | | 🔍 Ricerca | Multi-search universale, generi, filtri avanzati |

📦 Installazione

npm install choose-a-movie-for-me-data-source

yarn add choose-a-movie-for-me-data-source

🚀 Quick Start

1. Ottieni una API Key

Registrati gratuitamente su themoviedb.org e ottieni la tua API key.

2. Inizializza il Client

import { TMDB } from 'choose-a-movie-for-me-data-source';

const tmdb = new TMDB({
  apiKey: 'your-api-key-here',
  language: 'it-IT', // Opzionale: lingua dei risultati
  region: 'IT',      // Opzionale: regione per contenuti localizzati
});

3. Inizia a Esplorare!

// 🎬 Cerca i film più popolari
const popularMovies = await tmdb.movies.getPopularMovies();
console.log('Film popolari:', popularMovies.results);

// 🔍 Cerca un film specifico
const searchResults = await tmdb.movies.searchMovies('Matrix');
const matrix = searchResults.results[0];

// 📋 Ottieni dettagli completi
const movieDetails = await tmdb.movies.getMovie(matrix.id);
console.log(`${movieDetails.title} (${movieDetails.release_date.split('-')[0]})`);
console.log(`Generi: ${movieDetails.genres.map(g => g.name).join(', ')}`);
console.log(`Voto: ${movieDetails.vote_average}/10`);

// Ottenere dettagli + crediti e video in un'unica chiamata
const fullDetails = await tmdb.movies.getMovie(matrix.id, ['credits', 'videos']);
console.log(fullDetails.credits?.cast?.slice(0, 5));

// 🎭 Analizza il cast
const credits = await tmdb.movies.getMovieCredits(matrix.id);
console.log('Attori principali:', credits.cast.slice(0, 5));

📚 API Overview

🎥 Movies (tmdb.movies)

// Ricerca e dettagli
await tmdb.movies.searchMovies('Inception', { page: 1, year: 2010 });
await tmdb.movies.getMovie(27205); // Inception

// Liste curate
await tmdb.movies.getPopularMovies();
await tmdb.movies.getTopRatedMovies();
await tmdb.movies.getUpcomingMovies();
await tmdb.movies.getNowPlayingMovies();

// Relazioni e raccomandazioni
await tmdb.movies.getMovieCredits(27205);
await tmdb.movies.getSimilarMovies(27205);
await tmdb.movies.getMovieRecommendations(27205);

// Scoperta avanzata con filtri
await tmdb.movies.discoverMovies({
  withGenres: '28,12',        // Action, Adventure
  primaryReleaseYear: 2023,
  voteAverageGte: 7.0,
  sortBy: 'popularity.desc'
});

📺 TV Shows (tmdb.tv)

// Ricerca e dettagli
await tmdb.tv.searchTVShows('Breaking Bad');
await tmdb.tv.getTVShow(1396); // Breaking Bad

// Liste e scoperta
await tmdb.tv.getPopularTVShows();
await tmdb.tv.getTopRatedTVShows();
await tmdb.tv.getTVShowsAiringToday();

// Stagioni ed episodi
await tmdb.tv.getSeason(1396, 1);      // Breaking Bad Season 1
await tmdb.tv.getEpisode(1396, 1, 1);  // S01E01

// Filtri avanzati
await tmdb.tv.discoverTVShows({
  withGenres: '18,80',        // Drama, Crime
  firstAirDateYear: 2008,
  voteAverageGte: 8.0
});

👥 People (tmdb.people)

// Ricerca persone
await tmdb.people.searchPeople('Leonardo DiCaprio');
await tmdb.people.getPerson(6193);    // Leonardo DiCaprio
await tmdb.people.getPopularPeople();

🔍 Universal Search (tmdb.search)

// Ricerca multi-contenuto
const results = await tmdb.search.searchMulti('Avengers');
// Filtra per tipo: movie, tv, person
const movies = results.results.filter(item => item.media_type === 'movie');

// Generi
await tmdb.search.getMovieGenres();
await tmdb.search.getTVGenres();

📺 Watch Providers (tmdb.watchProviders)

// Ottieni tutte le regioni disponibili per i provider streaming
const regions = await tmdb.watchProviders.getAvailableRegions();
console.log('Regioni disponibili:', regions.results);

// Provider streaming per film in una regione specifica
const movieProviders = await tmdb.watchProviders.getMovieProviders('IT'); // Italia
console.log('Provider film in Italia:', movieProviders.results);

// Provider streaming per serie TV in una regione specifica
const tvProviders = await tmdb.watchProviders.getTVProviders('US'); // Stati Uniti
console.log('Provider TV negli USA:', tvProviders.results);

// Ottieni tutti i provider (film + TV) per una regione
const allProviders = await tmdb.watchProviders.getAllProvidersByRegion('GB'); // Regno Unito
console.log('Provider film:', allProviders.movieProviders.results);
console.log('Provider TV:', allProviders.tvProviders.results);

// Esempi di codici regione: 'IT' (Italia), 'US' (USA), 'GB' (Regno Unito), 'FR' (Francia), 'DE' (Germania)

🛡️ Gestione Errori

La libreria fornisce classi di errore specifiche per una gestione robusta:

import { TMDBApiError, TMDBConfigError, TMDBNetworkError } from 'choose-a-movie-for-me-data-source';

try {
  const movie = await tmdb.movies.getMovie(999999);
} catch (error) {
  if (error instanceof TMDBApiError) {
    // Errore dall'API TMDB (es. risorsa non trovata)
    console.error(`TMDB API Error ${error.statusCode}: ${error.statusMessage}`);
  } else if (error instanceof TMDBNetworkError) {
    // Errore di rete/connessione
    console.error('Network Error:', error.message);
  } else if (error instanceof TMDBConfigError) {
    // Errore di configurazione (es. API key mancante)
    console.error('Configuration Error:', error.message);
  }
}

⚙️ Configurazione Avanzata

const tmdb = new TMDB({
  apiKey: process.env.TMDB_API_KEY!,
  baseUrl: 'https://api.themoviedb.org/3', // URL personalizzato
  language: 'it-IT',                       // Lingua risultati
  region: 'IT'                            // Regione per contenuti localizzati
});

// Aggiorna configurazione a runtime
tmdb.updateConfig({
  language: 'en-US',
  region: 'US'
});

💡 Esempi Avanzati

App di Raccomandazione Film

class MovieRecommendationEngine {
  constructor(private tmdb: TMDB) {}

  async getRecommendationsFor(movieTitle: string) {
    // Trova il film
    const searchResults = await this.tmdb.movies.searchMovies(movieTitle);
    if (!searchResults.results?.length) return [];

    const movie = searchResults.results[0];
    
    // Ottieni raccomandazioni multiple
    const [similar, recommendations, sameGenre] = await Promise.all([
      this.tmdb.movies.getSimilarMovies(movie.id),
      this.tmdb.movies.getMovieRecommendations(movie.id),
      this.tmdb.movies.discoverMovies({
        withGenres: movie.genre_ids.join(','),
        voteAverageGte: 7.0,
        sortBy: 'vote_average.desc'
      })
    ]);

    return {
      originalMovie: movie,
      similarMovies: similar.results?.slice(0, 5),
      recommendations: recommendations.results?.slice(0, 5),
      sameGenreTopRated: sameGenre.results?.slice(0, 5)
    };
  }
}

const engine = new MovieRecommendationEngine(tmdb);
const recs = await engine.getRecommendationsFor('The Matrix');

Dashboard Serie TV

class TVDashboard {
  constructor(private tmdb: TMDB) {}

  async getDashboard() {
    const [popular, topRated, airingToday, onTheAir] = await Promise.all([
      this.tmdb.tv.getPopularTVShows(),
      this.tmdb.tv.getTopRatedTVShows(), 
      this.tmdb.tv.getTVShowsAiringToday(),
      this.tmdb.tv.getTVShowsOnTheAir()
    ]);

    return {
      popular: popular.results?.slice(0, 10),
      topRated: topRated.results?.slice(0, 10),
      airingToday: airingToday.results?.slice(0, 10),
      onTheAir: onTheAir.results?.slice(0, 10)
    };
  }
}

🚀 Sviluppo

# Clona il repository
git clone https://github.com/isametal88/choose-a-movie-for-me-data-source.git
cd choose-a-movie-for-me-data-source

# Installa dipendenze
npm install

# Sviluppo con watch mode
npm run dev

# Build di produzione
npm run build

# Esegui test
npm test

# Test con coverage
npm run test:coverage

# Linting e formattazione
npm run lint
npm run format

# Esempio di utilizzo
TMDB_API_KEY=your-key npm run example

📊 Bundle Size

| Format | Size | Gzipped | |--------|------|---------| | CommonJS | ~15KB | ~4KB | | ES Module | ~14KB | ~4KB | | TypeScript Definitions | Complete | - |

🔧 TypeScript Support

Tutti i tipi sono esportati e utilizzabili:

import type {
  Movie,
  MovieDetails,
  TVShow,
  TVShowDetails,
  Person,
  PersonDetails,
  Credits,
  Genre,
  TMDBConfig,
  MoviesResponse,
  TVShowsResponse
} from 'choose-a-movie-for-me-data-source';

// Usa i tipi nelle tue applicazioni
const processMovie = (movie: MovieDetails) => {
  console.log(`${movie.title} - Budget: $${movie.budget.toLocaleString()}`);
};

🧾 Tipi avanzati e enum

La libreria ora esporta alcuni enum e tipi aggiuntivi per rendere l'uso delle risposte TMDB più sicuro e leggibile:

• TMDBGender — enum numerico per i campi gender (NotSpecified = 0, Female = 1, Male = 2).
• MovieStatus — enum stringa con i valori comuni di TMDB per lo stato di un film/serie (Rumored, Planned, In Production, Post Production, Released, Canceled).
• ReleaseDateType — enum numerico per i tipi di release (Premiere = 1, TheatricalLimited = 2, Theatrical = 3, Digital = 4, Physical = 5, TV = 6).

Inoltre abbiamo aggiunto tipi completi per i campi che si possono ottenere con il parametro append_to_response (es. videos, images, translations, release_dates, external_ids, keywords, reviews, alternative_titles, changes, watch/providers). Per i dettagli e gli esempi vedi il documento dedicato:

docs/typed-append-to-response.md

Esempi d'uso degli enum

Ecco alcuni esempi rapidi che mostrano come usare gli enum esportati dalla libreria.

import { TMDB, TMDBGender, MovieStatus, ReleaseDateType } from 'choose-a-movie-for-me-data-source';

const tmdb = new TMDB({ apiKey: process.env.TMDB_API_KEY! });

// Confrontare lo stato di un movie
const movie = await tmdb.movies.getMovie(550); // Fight Club
if (movie.status === MovieStatus.Released) {
  console.log(`${movie.title} è già uscito`);
}

// Usare il gender enum (reverse mapping funziona per enum numerici)
const person = await tmdb.people.getPerson(287); // Brad Pitt
if (person.gender === TMDBGender.Male) {
  console.log(`${person.name} è di genere maschile`);
}

// Controllare il tipo di release di una release_date
const releaseInfo = movie.release_dates?.results?.[0];
if (releaseInfo) {
  const first = releaseInfo.release_dates?.[0];
  if (first && first.type === ReleaseDateType.Digital) {
    console.log('Prima release digitale:', first.release_date);
  }
}

// Ottenere dettagli + videos in una singola chiamata (usando array tipati con enum)
import { MovieAppendToResponse } from 'choose-a-movie-for-me-data-source';

const details = await tmdb.movies.getMovie(movie.id, [
  MovieAppendToResponse.Videos,
  MovieAppendToResponse.Credits,
]);
console.log('Video disponibili:', details.videos?.results?.length);

// --- Esempio rapido: importare tipi e usare `append_to_response` con enum
import type { VideosResponse, ImagesResponse, ReleaseDatesResponse } from 'choose-a-movie-for-me-data-source';

const fullDetails = await tmdb.movies.getMovie(movie.id, [
  MovieAppendToResponse.Videos,
  MovieAppendToResponse.Images,
  MovieAppendToResponse.ReleaseDates,
]);

const videos = fullDetails.videos as VideosResponse | undefined;
const images = fullDetails.images as ImagesResponse | undefined;
const releases = fullDetails.release_dates as ReleaseDatesResponse | undefined;

console.log('Trailer trovati:', videos?.results?.length ?? 0);
console.log('Poster trovati:', images?.posters?.length ?? 0);
console.log('Primo attore:', details.credits?.cast?.[0]?.name);

### ✅ Come usare gli enum (consigliato)

Usare gli enum esportati rende il codice più leggibile e tipato. Esempio rapido:

```typescript
import { TMDB, MovieAppendToResponse, VideoType, VideoSite, MediaType } from 'choose-a-movie-for-me-data-source';

const tmdb = new TMDB({ apiKey: process.env.TMDB_API_KEY! });

const details = await tmdb.movies.getMovie(550, [MovieAppendToResponse.Videos]);
const first = details.videos?.results?.[0];
if (first && first.type === VideoType.Trailer && first.site === VideoSite.YouTube) {
  console.log('Trailer ufficiale su YouTube:', first.name);
}

const search = await tmdb.search.searchMulti('Inception');
const onlyMovies = search.results?.filter(r => r.media_type === MediaType.Movie) ?? [];

Esempio: mappare stringhe runtime (input utente) a enum

Se ricevi valori in ingresso come stringhe (es. da query params o da UI), puoi mapparli agli enum in modo sicuro:

import { MovieAppendToResponse, MediaType, WatchProviderCategory } from 'choose-a-movie-for-me-data-source';

// funzione helper generica per mappare string -> enum member se valido
function mapToEnum<T extends { [k: string]: string }>(enumObj: T, value: string): T[keyof T] | undefined {
  const match = Object.values(enumObj).find(v => v === value);
  return match as T[keyof T] | undefined;
}

// esempio d'uso: mappare un query param
const userRequested = 'videos'; // es. req.query.append
const mapped = mapToEnum(MovieAppendToResponse, userRequested);
if (mapped) {
  const details = await tmdb.movies.getMovie(550, [mapped]);
}

// mappare media type
const inputType = 'movie';
const media = mapToEnum(MediaType, inputType);
if (media === MediaType.Movie) {
  // filtro per film
}

// mappare watch provider category
const monetizationInput = 'flatrate';
const monetization = mapToEnum(WatchProviderCategory, monetizationInput);
if (monetization === WatchProviderCategory.Flatrate) {
  // handle flatrate
}

## Esempi rapidi — append_to_response

Per maggiori dettagli sui tipi e esempi estesi vedi: [docs/typed-append-to-response.md](./docs/typed-append-to-response.md)

Ecco un esempio rapido che mostra come richiedere più campi tramite `append_to_response` e come usare i tipi esportati per tipare i risultati aggiuntivi:

```typescript
// Richiedi videos, images e release_dates in un'unica chiamata
const full = await tmdb.movies.getMovie(550, ['videos', 'images', 'release_dates']);

// Tipare i risultati aggiunti (opzionale ma utile per mapping/test)
import type { VideosResponse, ImagesResponse, ReleaseDatesResponse } from 'choose-a-movie-for-me-data-source';

const typedVideos = full.videos as VideosResponse | undefined;
const typedImages = full.images as ImagesResponse | undefined;
const typedReleases = full.release_dates as ReleaseDatesResponse | undefined;

console.log('Trailer:', typedVideos?.results?.[0]?.name);
console.log('Poster:', typedImages?.posters?.[0]?.file_path);
console.log('Release type (first):', typedReleases?.results?.[0]?.release_dates?.[0]?.type);

📈 Performance Tips

Caching

const cache = new Map();

const getCachedMovie = async (id: number) => {
  if (cache.has(id)) return cache.get(id);
  
  const movie = await tmdb.movies.getMovie(id);
  cache.set(id, movie);
  return movie;
};

Batch Requests

// Invece di richieste sequenziali
const movieIds = [1, 2, 3, 4, 5];
const movies = await Promise.all(
  movieIds.map(id => tmdb.movies.getMovie(id))
);

Debounced Search

const debouncedSearch = debounce(async (query: string) => {
  return await tmdb.search.searchMulti(query);
}, 300);

🌐 Rate Limiting

TMDB API ha i seguenti limiti:

• 40 richieste per 10 secondi per IP
• 1000 richieste al giorno per API key gratuita

La libreria non implementa rate limiting automatico. Per applicazioni ad alto traffico, considera:

• Cache dei risultati
• Debouncing delle ricerche
• Queue delle richieste
• Upgrade a piano TMDB a pagamento

🤝 Contribuire

Contributi benvenuti! Vedi la Guida per Contribuire per dettagli.

1. Fork del progetto
2. Crea il tuo Feature Branch (git checkout -b feature/amazing-feature)
3. Commit delle modifiche (git commit -m 'Add amazing feature')
4. Push al Branch (git push origin feature/amazing-feature)
5. Apri una Pull Request

📄 Licenza

Distribuito sotto licenza MIT. Vedi LICENSE per maggiori informazioni.

🙏 Riconoscimenti

• TMDB per le fantastiche API
• Axios per il client HTTP
• Community TypeScript per l'ecosistema di strumenti

🔗 Link Utili

• 📖 Documentazione Completa
• 🚀 Guida Introduttiva
• 📋 API Reference
• 💡 Esempi Pratici
• � Watch Providers
• �🛡️ Gestione Errori
• 🤝 Come Contribuire
• 📝 Changelog
• 🐛 Issues
• 💬 Discussions

Fatto con ❤️ per la community degli sviluppatori

⭐ Star su GitHub • 📦 NPM Package