MIGRATION.md

Migrating from v6 to v7

v7 is a full rewrite. The package name on npm is still themeparks, but the import surface has changed. This guide walks through the common patterns.

If you are blocked on a migration detail not covered here, please open an issue: https://github.com/ThemeParks/ThemeParks_JavaScript/issues

TL;DR

• Replace the default/namespace import with a named ThemeParks import.
• One client object; tp.destinations, tp.entity(...), and tp.raw.* replace the per-resource classes.
• All response types are real TypeScript types — no more any.
• Ad-hoc { body, response, status } error shapes are replaced with typed ApiError / RateLimitError / NetworkError / TimeoutError.

Imports and client setup

v6

const Themeparks = require('themeparks');
// or: import Themeparks from 'themeparks';

const destinationsApi = new Themeparks.DestinationsApi();
const entitiesApi = new Themeparks.EntitiesApi();

v7

import { ThemeParks } from 'themeparks';

const tp = new ThemeParks();
// tp.destinations, tp.entity(...), tp.raw.*

One client, fully typed.

Listing destinations

v6

const response = await destinationsApi.getDestinations();
for (const d of response.destinations) {
  console.log(d.id, d.name);
}

v7

// Ergonomic
const resp = await tp.destinations.list();
for (const d of resp.destinations ?? []) {
  console.log(d.id, d.name);
}

// Or raw (same return type)
const resp2 = await tp.raw.getDestinations();

Fetching an entity

v6

const entity = await entitiesApi.getEntity(entityId);
console.log(entity.name, entity.entityType);

v7

const entity = await tp.entity(entityId).get(); // ergonomic
const entityRaw = await tp.raw.getEntity(entityId); // raw
console.log(entity.name, entity.entityType);

Live wait times

Queue fields are now correctly typed end-to-end. Null waitTime is number | null rather than an untyped surprise.

v7

import { ThemeParks, currentWaitTime } from 'themeparks';

const tp = new ThemeParks();
const live = await tp.entity(parkId).live();
for (const item of live.liveData ?? []) {
  const wait = currentWaitTime(item);
  if (wait === null) {
    console.log(`${item.name}: closed / no data`);
  } else {
    console.log(`${item.name}: ${wait} min`);
  }
}

Error handling

v6

try {
  await entitiesApi.getEntity(entityId);
} catch (err) {
  // ad-hoc shape — { body, response, status } or a raw superagent error
  console.log(err.status, err.body);
}

v7

import { ApiError, RateLimitError, NetworkError, TimeoutError } from 'themeparks';

try {
  await tp.entity(entityId).get();
} catch (err) {
  if (err instanceof RateLimitError) {
    // 429: err.retryAfterMs is set if the server sent a Retry-After header
  } else if (err instanceof ApiError) {
    console.log(err.status, err.url, err.body);
  } else if (err instanceof NetworkError || err instanceof TimeoutError) {
    // transport failure
  } else {
    throw err;
  }
}

All four inherit from ThemeParksError if you want a single catch-all.

New in v7 (not in v6)

• tp.entity(id).walk() — async iterator over every descendant in a single API call (the /children endpoint already returns the full subtree).
• tp.entity(id).schedule.range(start, end) — stitches monthly schedule responses into a sorted, filtered list across a date range.
• tp.destinations.find(query) — case-insensitive lookup by slug or name.
• currentWaitTime(entry) — null-safe standby-wait accessor.
• narrowQueues(queue) — typed discriminated-union iterator over populated queue variants.
• Default-on response caching with per-endpoint TTLs (see README).
• Automatic 429 Retry-After handling.
• First-class TypeScript types generated from the upstream OpenAPI spec.