From 261d58904789b436fcc15a43cafdb5ef17b9fce2 Mon Sep 17 00:00:00 2001 From: Jamie Holding Date: Wed, 15 Apr 2026 14:18:09 +0000 Subject: [PATCH] fix(docs): make examples runnable as plain JS Cookbook and README code blocks were labeled \`ts\` but mixed TS-only syntax (type guards, generics, non-null assertions) into runnable examples. A user copy-pasting into \`test.mjs\` and running with node hit SyntaxErrors. Also Recipe 5's generic-alternative block referenced MAGIC_KINGDOM without declaring it. - Rename runnable blocks from \`ts\` to \`js\` and strip TS-only syntax. - Keep the single TypeScript example (Cache adapter with \`implements\`) labeled \`ts\` with a note on how to translate. - Add a preamble in both docs explaining the js vs ts file-extension swap so users know which runtime to use. - Add the missing MAGIC_KINGDOM constant in the generic-alternative block. - Replace \`wdw!.id\` (TS non-null assertion) with a real entity id in the low-level escape-hatch example. Co-Authored-By: Claude Opus 4.6 (1M context) --- README.md | 26 +++++++++++++++----------- docs/cookbook.md | 23 +++++++++++++++-------- 2 files changed, 30 insertions(+), 19 deletions(-) diff --git a/README.md b/README.md index 493d7e7..4c2de44 100644 --- a/README.md +++ b/README.md @@ -14,7 +14,11 @@ Runs on Node 18+, evergreen browsers, Deno, Bun, and Cloudflare Workers. Zero ru ## Print live wait times -```ts +Every example in this README works as plain JavaScript — save as `.mjs` and +run with `node`. To use them as TypeScript, rename to `.ts` and run with +`npx tsx`; the SDK ships full `.d.ts` types so TypeScript infers everything. + +```js import { ThemeParks, currentWaitTime } from 'themeparks'; const MAGIC_KINGDOM = '75ea578a-adc8-4116-a54d-dccb60765ef9'; @@ -56,7 +60,7 @@ Jungle Cruise 40 min Example: -```ts +```js const tp = new ThemeParks({ userAgent: 'my-app/1.2.3 (+https://example.com)', timeoutMs: 15_000, @@ -81,7 +85,7 @@ Each variant is exposed as a key on `entry.queue`. All are optional — `undefin ### Direct access -```ts +```js import { ThemeParks } from 'themeparks'; const tp = new ThemeParks(); @@ -116,7 +120,7 @@ for (const entry of live.liveData ?? []) { If branching on every variant is too verbose, `narrowQueues(queue)` flattens all populated variants into a typed discriminated union: -```ts +```js import { ThemeParks, narrowQueues } from 'themeparks'; const tp = new ThemeParks(); @@ -135,7 +139,7 @@ for (const entry of live.liveData ?? []) { ## Ergonomic helpers -```ts +```js import { ThemeParks } from 'themeparks'; const tp = new ThemeParks(); @@ -159,17 +163,17 @@ console.log(`${entries.length} schedule entries`); Every ergonomic helper is built on top of `tp.raw`, which is a thin, typed 1:1 wrapper over the OpenAPI operations. Use it directly when you want the raw response shape: -```ts +```js const live = await tp.raw.getEntityLive('75ea578a-adc8-4116-a54d-dccb60765ef9'); const dests = await tp.raw.getDestinations(); -const children = await tp.raw.getEntityChildren(wdw!.id); +const children = await tp.raw.getEntityChildren('e957da41-3552-4cf6-b636-5babc5cbc4e5'); ``` ## Error handling All SDK errors inherit from `ThemeParksError`. The ones you'll typically catch: -```ts +```js import { ThemeParks, ApiError, RateLimitError, NetworkError, TimeoutError } from 'themeparks'; const tp = new ThemeParks(); @@ -196,7 +200,7 @@ try { There's no built-in HTTP logger to flip on (we run directly on platform `fetch`). The clean idiom is to pass a wrapping `fetch` implementation: -```ts +```js import { ThemeParks } from 'themeparks'; const tp = new ThemeParks({ @@ -226,13 +230,13 @@ The default client caches `GET` responses in-memory (LRU) with sensible per-endp ### Disable caching -```ts +```js const tp = new ThemeParks({ cache: false }); ``` ### Plug in your own adapter -`Cache` is a structural interface — any object implementing `get`, `set`, and `delete` works. Redis, filesystem, IndexedDB, etc.: +`Cache` is a structural interface — any object implementing `get`, `set`, and `delete` works. Redis, filesystem, IndexedDB, etc. (TypeScript shown; drop the annotations for plain JS): ```ts import { ThemeParks, type Cache } from 'themeparks'; diff --git a/docs/cookbook.md b/docs/cookbook.md index 046649d..b468197 100644 --- a/docs/cookbook.md +++ b/docs/cookbook.md @@ -8,12 +8,17 @@ Entity IDs used throughout: - Magic Kingdom: `75ea578a-adc8-4116-a54d-dccb60765ef9` - Walt Disney World Resort: `e957da41-3552-4cf6-b636-5babc5cbc4e5` +Every example below is written as plain JavaScript with ES modules. Save any +block as `test.mjs` and run it with `node test.mjs` (Node ≥18). For +TypeScript just rename to `.ts` and run with `npx tsx test.ts` — the SDK +ships full `.d.ts` types so TypeScript will infer the shapes automatically. + ## Recipe 1 — Wait times in order (longest → shortest) Pull the live data for Magic Kingdom, keep only the rides that are reporting a wait time, and print them sorted from longest to shortest queue. -```ts +```js import { ThemeParks, currentWaitTime } from 'themeparks'; const MAGIC_KINGDOM = '75ea578a-adc8-4116-a54d-dccb60765ef9'; @@ -23,7 +28,7 @@ const live = await tp.entity(MAGIC_KINGDOM).live(); const waits = (live.liveData ?? []) .map((entry) => ({ name: entry.name, wait: currentWaitTime(entry) })) - .filter((w): w is { name: string; wait: number } => w.wait !== null) + .filter((w) => w.wait !== null) .sort((a, b) => b.wait - a.wait); for (const { name, wait } of waits) { @@ -56,7 +61,7 @@ EXTRA_HOURS (early entry / extended evening), and TICKETED_EVENT (after-hours events). `range()` returns them all in chronological order across any month boundaries. -```ts +```js import { ThemeParks } from 'themeparks'; const MAGIC_KINGDOM = '75ea578a-adc8-4116-a54d-dccb60765ef9'; @@ -98,14 +103,14 @@ coordinates by `entityType`: > tree in a single response, so even for the largest destinations this is > one HTTP request. -```ts +```js import { ThemeParks } from 'themeparks'; const WALT_DISNEY_WORLD = 'e957da41-3552-4cf6-b636-5babc5cbc4e5'; const tp = new ThemeParks(); -const byType = new Map>(); +const byType = new Map(); for await (const child of tp.entity(WALT_DISNEY_WORLD).walk()) { const loc = child.location; @@ -154,7 +159,7 @@ RESTAURANT (218) There's no built-in HTTP logger to flip on (the SDK runs directly on platform `fetch`). The clean idiom is to pass a wrapping `fetch` implementation: -```ts +```js import { ThemeParks } from 'themeparks'; const tp = new ThemeParks({ @@ -202,7 +207,7 @@ Lane) plus SINGLE_RIDER. The full set of variants is: Print all populated queue variants for every attraction at Magic Kingdom: -```ts +```js import { ThemeParks } from 'themeparks'; const MAGIC_KINGDOM = '75ea578a-adc8-4116-a54d-dccb60765ef9'; @@ -259,9 +264,11 @@ TRON Lightcycle / Run LIGHTNING LANE $20.00, return 2026-04- If branching on every variant is too verbose, `narrowQueues(queue)` flattens all populated variants into a typed discriminated union you can switch over: -```ts +```js import { ThemeParks, narrowQueues } from 'themeparks'; +const MAGIC_KINGDOM = '75ea578a-adc8-4116-a54d-dccb60765ef9'; + const tp = new ThemeParks(); const live = await tp.entity(MAGIC_KINGDOM).live();