challenges.json

[
  {
    "date": "2026-02-19",
    "name": "Typed Middleware Pipeline with Retry & Cancellation",
    "difficulty": "Hard",
    "description": "You're building an internal HTTP gateway layer that processes outgoing requests through a chain of typed middleware (auth injection, logging, rate-limit headers). Each middleware can transform the request context, short-circuit with a typed error, and the pipeline runner supports per-request cancellation and automatic retry with exponential back-off.",
    "snippet": "\n// Key types at a glance\n\ntype Milliseconds = number & { readonly __brand: \"Milliseconds\" };\n\ninterface PipelineContext<TBody = unknown> {\n  readonly requestId: string;\n  url: string;\n  method: \"GET\" | \"POST\" | \"PUT\" | \"PATCH\" | \"DELETE\";\n  headers: Record<string, string>;\n  body: TBody | undefined;\n  meta: Record<string, unknown>;\n}\n\ntype PipelineResult<TResponse, TError> =\n  | { readonly kind: \"success\"; readonly response: TResponse;\n      readonly durationMs: Milliseconds; readonly attempts: number }\n  | { readonly kind: \"failure\"; readonly error: TError;\n      readonly durationMs: Milliseconds; readonly attempts: number };\n\n// TODO (a) — fill in the body:\ntype Middleware<TBody, TResponse, TError> = never;\n\n// TODO (f) — implement this:\nasync function runPipeline<TBody, TResponse, TError>(\n  options: PipelineOptions<TBody, TResponse, TError>\n): Promise<PipelineResult<TResponse, TError>> { ... }\n",
    "goals": [
      "Define `Middleware`, `Executor`, `RetryPolicy`, and `PipelineOptions` as fully-typed generic aliases/interfaces with no `any` or `never` placeholders.",
      "Implement `runPipeline` with a recursive `dispatch` function that threads context through middlewares, supports short-circuiting, and retries failed attempts using the supplied `RetryPolicy` with exponential back-off.",
      "Implement the three middleware factories (`withBearerAuth`, `withRequestLogger`, `withRateLimitHeader`) and the `exponentialBackoff` helper so all five test cases pass.",
      "Implement `sleep` so it respects an optional `AbortSignal`, rejecting immediately with the signal's reason when already aborted or when aborted mid-sleep."
    ],
    "hints": [
      "For `Middleware<TBody, TResponse, TError>`, the `next` parameter's type is the same async function shape as the middleware itself minus the `next` arg — write it as an inline function type `(ctx: PipelineContext<TBody>) => Promise<PipelineResult<TResponse, TError>>`.",
      "In `runPipeline`, track `startTime = Date.now()` before the attempt loop and compute `durationMs` only once when you're ready to return — the `durationMs` fields from the executor are intentionally ignored at the pipeline level.",
      "For `sleep` + `AbortSignal`, register a one-shot `'abort'` event listener and also check `signal.aborted` synchronously at the top of the function before creating the timeout."
    ],
    "docs": [
      {
        "title": "TypeScript Handbook — Generics",
        "url": "https://www.typescriptlang.org/docs/handbook/2/generics.html"
      },
      {
        "title": "TypeScript Handbook — Conditional Types & infer",
        "url": "https://www.typescriptlang.org/docs/handbook/2/conditional-types.html"
      },
      {
        "title": "MDN — AbortSignal & AbortController",
        "url": "https://developer.mozilla.org/en-US/docs/Web/API/AbortController"
      },
      {
        "title": "TypeScript Handbook — Utility Types (Extract, Record, Pick…)",
        "url": "https://www.typescriptlang.org/docs/handbook/utility-types.html"
      }
    ]
  },
  {
    "date": "2026-02-20",
    "name": "Typed Inventory Aggregator",
    "difficulty": "Easy",
    "description": "You're building a dashboard for a small e-commerce warehouse. Given a flat list of product entries (each with a category, SKU, price, and stock count), aggregate them into a per-category summary — the hardest part is getting the TypeScript types exactly right.",
    "snippet": "// Key types & main function signature\n\ntype Sku = string & { readonly _brand: \"Sku\" };\n\ninterface InventoryItem {\n  sku:          Sku;\n  name:         string;\n  category:     string;\n  priceUsd:     number;\n  stock:        number;\n}\n\ninterface CategorySummary {\n  totalItems:     number;\n  totalStock:     number;\n  totalValueUsd:  number;\n  cheapestSku:    Sku;\n  mostStockedSku: Sku;\n}\n\ntype InventorySummary = Record<string, CategorySummary>;\n\nfunction aggregateInventory(items: InventoryItem[]): InventorySummary { ... }\nfunction topCategories(summary: InventorySummary, n: number): string[] { ... }",
    "goals": [
      "Define a branded `Sku` type and implement `toSku` without using `any` or a type assertion.",
      "Build the `InventoryItem` and `CategorySummary` interfaces with all required fields typed correctly.",
      "Implement `aggregateInventory` to produce a correct per-category summary in a single pass over the items array.",
      "Implement `topCategories` returning category names sorted by total inventory value descending, capped at n results."
    ],
    "hints": [
      "For `toSku`, look at how TypeScript's `satisfies` operator or a simple return-type annotation can coerce a `string` to a branded type without writing `as Sku`.",
      "Use a `for...of` loop or `Array.reduce` over the items and build up the `InventorySummary` object incrementally — initialise each category bucket on first encounter.",
      "For `topCategories`, `Object.entries` gives you `[category, summary]` pairs you can sort by `totalValueUsd` before slicing to `n`."
    ],
    "docs": [
      {
        "title": "TypeScript Handbook — Utility Types (Record)",
        "url": "https://www.typescriptlang.org/docs/handbook/utility-types.html#recordkeys-type"
      },
      {
        "title": "TypeScript Handbook — Interfaces",
        "url": "https://www.typescriptlang.org/docs/handbook/2/objects.html"
      },
      {
        "title": "TypeScript 5.0 — satisfies operator",
        "url": "https://www.typescriptlang.org/docs/handbook/release-notes/typescript-4-9.html#the-satisfies-operator"
      },
      {
        "title": "MDN — Array.prototype.reduce",
        "url": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/reduce"
      }
    ]
  },
  {
    "date": "2026-02-21",
    "name": "Paginated API Client with Typed Result Accumulation",
    "difficulty": "Hard",
    "description": "You're building a typed API client for an analytics platform that exposes cursor-based paginated endpoints. The client must traverse all pages concurrently (up to a configurable limit), accumulate results into a strongly-typed aggregate, and surface per-page errors without aborting the entire fetch — all without a single `any` or type assertion.",
    "snippet": "// Key types and main function signature\n\ndeclare const __brand: unique symbol;\ntype Brand<B> = { readonly [__brand]: B };\n\ntype Cursor      = string & Brand<\"Cursor\">;\ntype EndpointPath = string & Brand<\"EndpointPath\">;\n\ntype PageResponse<T> = {\n  items:      T[];\n  nextCursor: Cursor | undefined;\n  pageIndex:  number;\n};\n\ntype FetchResult<T> =\n  | { ok: true;  data: T }\n  | { ok: false; error: PageError };\n\ntype AccumulatedResult<T> = /* discriminated by `ok` — you define it */;\n\ntype PageFetcher<T> =\n  (req: PageRequest) => Promise<FetchResult<PageResponse<T>>>;\n\n// ── Core entry point ──────────────────────────────────────────\nasync function fetchAllPages<T>(\n  endpoint: EndpointPath,\n  fetcher:  PageFetcher<T>,\n  options?: FetchAllOptions\n): Promise<AccumulatedResult<T>>\n",
    "goals": [
      "Define branded string types `Cursor` and `EndpointPath` using a `unique symbol` brand and a single generic branding helper — no `as` outside that helper.",
      "Model `FetchResult<T>` and `AccumulatedResult<T>` as discriminated unions so TypeScript can narrow them without type assertions.",
      "Implement `withConcurrencyLimit<R>` that runs async task factories with a configurable concurrency cap and returns results in original order.",
      "Implement `fetchAllPages<T>` that traverses cursor-based pages using `withConcurrencyLimit`, collects items in page order, and accumulates per-page errors without aborting the traversal."
    ],
    "hints": [
      "For `withConcurrencyLimit`, track results by index in a pre-allocated array and maintain a pointer to the next task to start — avoid `Promise.all` on the full set.",
      "The `AccumulatedResult<T>` discriminated union should mirror `FetchResult` — an `ok: true` branch with no `errors` field forces callers through `handleAccumulatedResult` to access errors safely.",
      "When traversing pages, only enqueue the next cursor if the current page succeeded — failed pages cannot yield a `nextCursor`, so that branch of the graph is naturally pruned."
    ],
    "docs": [
      {
        "title": "TypeScript Handbook — Branded / Nominal Types",
        "url": "https://www.typescriptlang.org/docs/handbook/2/types-from-types.html"
      },
      {
        "title": "TypeScript Handbook — Narrowing & Discriminated Unions",
        "url": "https://www.typescriptlang.org/docs/handbook/2/narrowing.html#discriminated-unions"
      },
      {
        "title": "MDN — Promise.allSettled",
        "url": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/allSettled"
      },
      {
        "title": "TypeScript Handbook — Generics",
        "url": "https://www.typescriptlang.org/docs/handbook/2/generics.html"
      }
    ]
  },
  {
    "date": "2026-02-22",
    "name": "Typed Event Log Parser",
    "difficulty": "Easy",
    "description": "You're building a monitoring dashboard for a cloud platform. Raw event logs arrive as untyped JSON blobs — your job is to safely parse them into a discriminated union of strongly-typed events, then aggregate counts and extract the latest timestamp per event kind.",
    "snippet": "/** All supported event kinds */\ntype EventKind = \"deploy\" | \"error\" | \"scale\" | \"alert\";\n\ninterface AlertEvent {\n  kind: \"alert\";\n  timestamp: number;\n  alertName: string;\n  severity: \"low\" | \"medium\" | \"high\" | \"critical\";\n}\n\ntype AppEvent = DeployEvent | ErrorEvent | ScaleEvent | AlertEvent;\n\n/** Mapped over EventKind — adding a new kind extends this automatically */\ntype EventSummary = {\n  [K in EventKind]: {\n    count: number;\n    latestTimestamp: number | null;\n  };\n};\n\n/** Parse one unknown blob → typed AppEvent or null if invalid */\nfunction parseEvent(raw: unknown): AppEvent | null { ... }\n\n/** Parse an array of unknown blobs, silently dropping invalid entries */\nfunction parseEventLog(raw: unknown): AppEvent[] { ... }\n\n/** Aggregate parsed events into per-kind counts + latest timestamps */\nfunction summariseEvents(events: AppEvent[]): EventSummary { ... }\n",
    "goals": [
      "Implement `parseEvent` to safely narrow `unknown` input into a typed `AppEvent` discriminated union — no `any`, no type assertions.",
      "Implement `parseEventLog` to filter an unknown array, silently dropping entries that fail validation.",
      "Define `EventSummary` as a mapped type over `EventKind` so the shape automatically extends when a new kind is added.",
      "Implement `summariseEvents` to aggregate event counts and track the latest timestamp per kind, seeding all keys up front for compile-time exhaustiveness."
    ],
    "hints": [
      "Use `typeof raw === 'object' && raw !== null && 'kind' in raw` to safely access fields on an `unknown` value — no casting needed.",
      "A `switch` on `event.kind` after you've confirmed it's a valid `EventKind` lets TypeScript narrow each branch to the correct interface.",
      "Initialise the `EventSummary` accumulator by listing every `EventKind` literal explicitly — TypeScript will flag a missing key as a compile error."
    ],
    "docs": [
      {
        "title": "TypeScript Handbook — Narrowing",
        "url": "https://www.typescriptlang.org/docs/handbook/2/narrowing.html"
      },
      {
        "title": "TypeScript Handbook — Discriminated Unions",
        "url": "https://www.typescriptlang.org/docs/handbook/2/narrowing.html#discriminated-unions"
      },
      {
        "title": "TypeScript Handbook — Mapped Types",
        "url": "https://www.typescriptlang.org/docs/handbook/2/mapped-types.html"
      },
      {
        "title": "MDN — Array.isArray",
        "url": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/isArray"
      }
    ]
  },
  {
    "date": "2026-02-23",
    "name": "Typed Reactive State Machine",
    "difficulty": "Hard",
    "description": "You're building the core of a checkout flow for an e-commerce platform. The checkout process moves through well-defined states (idle → validating → payment → confirmed / failed), and every transition must be explicitly allowed, carry typed payloads, and notify strongly-typed subscribers — all enforced at compile time.",
    "snippet": "export type CheckoutState =\n  | IdleState\n  | ValidatingState\n  | PaymentState\n  | ConfirmedState\n  | FailedState;\n\n// Each event variant carries only the payload its transition needs:\nexport type CheckoutEvent = never; // TODO: your discriminated union here\n\n// TransitionMap maps every event `type` to its allowed source states\n// and a pure reduce function — narrowed at the type level:\nexport type TransitionMap = {\n  [E in CheckoutEvent as E[\"type\"]]: {\n    from: ReadonlyArray<CheckoutState[\"kind\"]>;\n    reduce: (state: /* narrowed */ CheckoutState, event: E) => CheckoutState;\n  };\n};\n\nexport class CheckoutMachine {\n  constructor(initialCart: CartItem[]);\n  getState(): CheckoutState;\n  send(event: CheckoutEvent): CheckoutState;\n  subscribe(fn: Subscriber): () => void;\n  reset(newCart?: CartItem[]): CheckoutState;\n}\n",
    "goals": [
      "Define a discriminated `CheckoutEvent` union whose variants carry only the payload each transition needs, and a `TransitionMap` mapped type where `reduce` receives narrowed state and event types — not the full unions.",
      "Implement `CheckoutMachine` so that `send()` enforces allowed transitions at runtime, throws a `TypeError` on illegal ones, and notifies subscribers with `(nextState, prevState)`.",
      "Implement `subscribe()` returning a working unsubscribe function, and `reset()` as a convenience wrapper that guards against calls from non-terminal states.",
      "Implement `cartTotal` using a single `reduce` call and `assertNeverState` as an exhaustive compile-time + runtime safety net."
    ],
    "hints": [
      "To get narrowed types in `TransitionMap`, try a helper type like `type EventByType<T extends CheckoutEvent[\"type\"]> = Extract<CheckoutEvent, { type: T }>` and use it in the mapped type's `reduce` signature.",
      "Use `Extract<CheckoutState, { kind: K }>` to narrow the `state` parameter in each `reduce` function — this keeps the transition table fully type-safe without any casts.",
      "Store subscribers in a `Set<Subscriber>` so that returning `() => set.delete(fn)` from `subscribe()` gives you a clean, allocation-light unsubscribe pattern."
    ],
    "docs": [
      {
        "title": "TypeScript Handbook — Discriminated Unions",
        "url": "https://www.typescriptlang.org/docs/handbook/2/narrowing.html#discriminated-unions"
      },
      {
        "title": "TypeScript Handbook — Mapped Types",
        "url": "https://www.typescriptlang.org/docs/handbook/2/mapped-types.html"
      },
      {
        "title": "TypeScript Handbook — Conditional Types & infer",
        "url": "https://www.typescriptlang.org/docs/handbook/2/conditional-types.html"
      },
      {
        "title": "TypeScript Handbook — Extract Utility Type",
        "url": "https://www.typescriptlang.org/docs/handbook/utility-types.html#extracttype-union"
      }
    ]
  },
  {
    "date": "2026-02-24",
    "name": "Typed Contact Book Lookup",
    "difficulty": "Easy",
    "description": "You're building a small contact book utility for an internal HR tool. Given a list of contacts with varying optional fields, you must build a strongly-typed lookup index and implement search/filter helpers — the challenge is in the types, not the logic.",
    "snippet": "/** The department a contact belongs to. */\ntype Department = \"engineering\" | \"design\" | \"marketing\" | \"hr\" | \"finance\";\n\n/** A contact's role seniority. */\ntype Seniority = \"junior\" | \"mid\" | \"senior\" | \"lead\" | \"manager\";\n\ninterface Contact {\n  id: string;\n  name: string;\n  email: string;\n  department: Department;\n  seniority: Seniority;\n  phone?: string;\n  tags?: string[];\n}\n\n// Your job: define these three types using built-in utility types...\ntype ContactIndex  = Record<string, Contact>;       // TODO: use Record<>\ntype ContactSummary = Pick<Contact, \"id\" | ...>;    // TODO: use Pick<>\ntype SearchFilters  = Partial<Contact>;             // TODO: use Partial<>\n\n// ...then implement these three functions:\nfunction buildIndex(contacts: Contact[]): ContactIndex { ... }\nfunction summarise(index: ContactIndex): ContactSummary[] { ... }\nfunction filterContacts(contacts: Contact[], filters: SearchFilters): Contact[] { ... }",
    "goals": [
      "Define `ContactIndex`, `ContactSummary`, and `SearchFilters` using the `Record`, `Pick`, and `Partial` built-in utility types respectively.",
      "Implement `buildIndex` to convert a `Contact[]` into a `ContactIndex` keyed by each contact's `id`.",
      "Implement `summarise` to extract only the `id`, `name`, `email`, and `department` fields from every contact in a `ContactIndex`.",
      "Implement `filterContacts` to return contacts matching ALL provided filter fields, with special subset-matching logic for the optional `tags` array."
    ],
    "hints": [
      "For `filterContacts`, iterate over the keys of the `filters` object with `Object.keys` — but remember each value may be `undefined` (Partial!), so skip those keys entirely.",
      "When checking `tags`, `Array.prototype.every` paired with `Array.prototype.includes` is your friend for verifying that all filter tags exist on the contact.",
      "The `Pick` utility type takes a type and a union of string literal keys: `Pick<Contact, 'id' | 'name'>` — make sure you only name the four required fields for `ContactSummary`."
    ],
    "docs": [
      {
        "title": "TypeScript Utility Types (Pick, Partial, Record)",
        "url": "https://www.typescriptlang.org/docs/handbook/utility-types.html"
      },
      {
        "title": "TypeScript Handbook — Object Types & Optional Properties",
        "url": "https://www.typescriptlang.org/docs/handbook/2/objects.html"
      },
      {
        "title": "MDN — Array.prototype.every()",
        "url": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/every"
      },
      {
        "title": "MDN — Object.keys() / Object.values()",
        "url": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/keys"
      }
    ]
  },
  {
    "date": "2026-02-25",
    "name": "Typed Middleware Pipeline Builder",
    "difficulty": "Medium",
    "description": "You're building the request-handling core of an internal HTTP gateway. Middleware functions transform a typed context object one step at a time — the challenge is composing them into a pipeline where each middleware's output type flows into the next middleware's input type, all enforced at compile time.",
    "snippet": "/** A single middleware: receives a context of type In, returns Out. */\ntype Middleware<In, Out> = (ctx: In) => Out;\n\n/** Unwrap a Promise<T> → T; leave non-promise types unchanged. */\ntype Awaited_<T> = /* TODO: conditional type using infer */;\n\n/** Infer the output type of the last middleware in a tuple. */\ntype PipelineOutput<\n  Middlewares extends readonly Middleware<unknown, unknown>[]\n> = /* TODO: recursive conditional type */;\n\n/** Discriminated union returned by runPipeline. */\ntype PipelineResult<T> =\n  | { ok: true; value: T }\n  | { ok: false; error: string; step: number };\n\n/** Chain two middlewares — intermediate type is fully inferred. */\ndeclare function compose<A, B, C>(\n  f: Middleware<A, B>,\n  g: Middleware<B, C>\n): Middleware<A, C>;\n\n/** Run an ordered array of middlewares, catching per-step errors. */\ndeclare function runPipeline(\n  initial: unknown,\n  middlewares: Array<Middleware<unknown, unknown>>\n): PipelineResult<unknown>;\n",
    "goals": [
      "Implement `Awaited_<T>` and `PipelineOutput<Middlewares>` as conditional types that use `infer` to extract inner and last-middleware output types.",
      "Implement `compose` and `composeAsync` as fully generic functions that chain two middlewares with no manual type annotations at call sites.",
      "Implement `runPipeline` to execute middlewares sequentially, returning a typed `PipelineResult` discriminated union that captures both success and per-step failure.",
      "Define the `Brand` helper and `AuthedContext` branded type, then implement `withAuth` as a middleware that narrows a plain `RequestContext` into an `AuthedContext` or throws."
    ],
    "hints": [
      "For `PipelineOutput`, use a variadic tuple pattern: `Middlewares extends [...infer _Init, infer Last]` to grab only the final element, then extract its output with a second `infer`.",
      "A branded type is just an intersection with a phantom property: `T & { readonly __brand: B }` — this makes two structurally identical types nominally distinct.",
      "In `runPipeline`, keep a `current: unknown` variable and iterate with a `for` loop so you can track the step index when catching errors."
    ],
    "docs": [
      {
        "title": "TypeScript Handbook: Conditional Types",
        "url": "https://www.typescriptlang.org/docs/handbook/2/conditional-types.html"
      },
      {
        "title": "TypeScript Handbook: Inferring Within Conditional Types",
        "url": "https://www.typescriptlang.org/docs/handbook/2/conditional-types.html#inferring-within-conditional-types"
      },
      {
        "title": "TypeScript Handbook: Generics",
        "url": "https://www.typescriptlang.org/docs/handbook/2/generics.html"
      },
      {
        "title": "TypeScript Deep Dive: Branded Types",
        "url": "https://basarat.gitbook.io/typescript/main-1/nominaltyping"
      }
    ]
  },
  {
    "date": "2026-02-26",
    "name": "Typed Product Inventory Aggregator",
    "difficulty": "Easy",
    "description": "You're building a back-office tool for an e-commerce warehouse. Raw inventory records arrive as unknown JSON, and you must safely validate them, group them by category, and compute per-category summaries — the challenge is keeping every step fully typed without reaching for `any`.",
    "snippet": "\n// Key types\nexport type Category = \"electronics\" | \"clothing\" | \"food\" | \"furniture\";\n\nexport interface Product {\n  id: string;\n  name: string;\n  category: Category;\n  priceUsd: number;   // > 0\n  stock: number;      // non-negative integer\n}\n\nexport type Result<T, E> =\n  | { ok: true;  value: T }\n  | { ok: false; error: E };\n\nexport interface CategorySummary {\n  category: Category;\n  productCount: number;\n  totalStock: number;\n  averagePriceUsd: number;\n  cheapestProduct: Pick<Product, \"id\" | \"name\" | \"priceUsd\">;\n}\n\n// Functions to implement\nexport function parseProduct(raw: unknown): Result<Product, string> { ... }\nexport function groupByCategory(products: Product[]): Map<Category, Product[]> { ... }\nexport function summariseCategory(category: Category, products: Product[]): CategorySummary { ... }\nexport function buildInventoryReport(rawRecords: unknown[]): InventoryReport { ... }\n",
    "goals": [
      "Implement `parseProduct` to safely narrow `unknown` → `Product` using a `Result` discriminated union — no `any` or `as` allowed.",
      "Implement `groupByCategory` to bucket valid products into a `Map<Category, Product[]>`.",
      "Implement `summariseCategory` to compute per-category totals, averages (2 d.p.), and the cheapest product using `Pick<Product, ...>`.",
      "Implement `buildInventoryReport` to orchestrate the full pipeline: parse all raw records, collect indexed `ParseError`s, aggregate summaries, and return a sorted `InventoryReport`."
    ],
    "hints": [
      "Narrow `unknown` incrementally: first check `typeof raw === 'object' && raw !== null`, then use the `in` operator to confirm each field exists before checking its type or value.",
      "The `Result<T, E>` union is discriminated on the `ok` boolean — TypeScript will narrow `value` vs `error` automatically inside an `if (result.ok)` block.",
      "For `Pick<Product, 'id' | 'name' | 'priceUsd'>`, you don't need to construct a new type — just return an object literal with exactly those three keys and TypeScript will enforce the shape."
    ],
    "docs": [
      {
        "title": "TypeScript – Narrowing",
        "url": "https://www.typescriptlang.org/docs/handbook/2/narrowing.html"
      },
      {
        "title": "TypeScript – Utility Types (Pick, Record, …)",
        "url": "https://www.typescriptlang.org/docs/handbook/utility-types.html"
      },
      {
        "title": "TypeScript – Discriminated Unions",
        "url": "https://www.typescriptlang.org/docs/handbook/2/narrowing.html#discriminated-unions"
      },
      {
        "title": "MDN – Map",
        "url": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map"
      }
    ]
  },
  {
    "date": "2026-02-27",
    "name": "Typed Paginated API Client with Retry & Concurrency",
    "difficulty": "Hard",
    "description": "You're building a typed data-ingestion pipeline for an analytics platform. Remote REST endpoints return paginated results, requests can fail transiently, and multiple endpoints must be fetched in parallel — but with a concurrency cap to avoid hammering the servers.",
    "snippet": "\n// Core result type — discriminated union\nexport type Ok<T>  = { ok: true;  value: T };\nexport type Err<E> = { ok: false; error: E };\nexport type Result<T, E> = Ok<T> | Err<E>;\n\n// Paginated API shape\nexport interface PagedResponse<T> {\n  items:    T[];\n  nextPage: number | null;\n  total:    number;\n}\nexport type FetchPage<T> = (page: number) => Promise<PagedResponse<T>>;\n\n// Typed error hierarchy\nexport type ApiError =\n  | { kind: \"transient\"; message: string; retryAfterMs: number }\n  | { kind: \"permanent\"; message: string; statusCode: number };\n\n// Main orchestrator signature\nexport async function ingestEndpoints<T>(\n  endpoints: ReadonlyArray<EndpointConfig<T>>,\n  concurrencyLimit: number,\n): Promise<{\n  successes: Array<{ id: string; items: T[] }>;\n  failures:  Array<{ id: string; error: ApiError }>;\n}>;\n",
    "goals": [
      "Define a fully-typed discriminated-union Result<T,E> and a two-variant ApiError type, then implement ok() and err() constructor helpers.",
      "Implement withRetry to transparently retry transient ApiErrors up to maxAttempts times while short-circuiting on permanent errors.",
      "Implement fetchAllPages to sequentially follow the nextPage cursor and fetchWithConcurrencyLimit to run tasks in parallel with a sliding-window concurrency cap.",
      "Wire all helpers together in ingestEndpoints, bridging the Result world into the FetchPage contract and returning partitioned successes and failures."
    ],
    "hints": [
      "For withRetry, narrow on both result.ok and error.kind — TypeScript will ensure the transient branch has retryAfterMs and the permanent branch has statusCode without extra casting.",
      "fetchWithConcurrencyLimit is easiest with a running pool: kick off `limit` tasks immediately, then as each one settles, start the next unstarted task — track indices carefully to preserve output order.",
      "In ingestEndpoints, you need to adapt FetchPage<T> (which returns a plain Promise) to work with withRetry (which expects () => Promise<Result<T,ApiError>>). Create a small local wrapper per page call that maps fetch errors to ApiError results."
    ],
    "docs": [
      {
        "title": "TypeScript Handbook — Discriminated Unions",
        "url": "https://www.typescriptlang.org/docs/handbook/2/narrowing.html#discriminated-unions"
      },
      {
        "title": "TypeScript Handbook — Generics",
        "url": "https://www.typescriptlang.org/docs/handbook/2/generics.html"
      },
      {
        "title": "MDN — Promise.race / concurrency patterns",
        "url": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/race"
      },
      {
        "title": "TypeScript 5.x — const Type Parameters & satisfies",
        "url": "https://www.typescriptlang.org/docs/handbook/release-notes/typescript-5-0.html"
      }
    ]
  },
  {
    "date": "2026-02-28",
    "name": "Typed Event Aggregator with Windowed Rollups",
    "difficulty": "Medium",
    "description": "You're building the analytics backbone of a real-time dashboard for a SaaS platform. Raw telemetry events (page views, clicks, errors, purchases) stream in continuously, and the dashboard needs per-event-type rollups aggregated over fixed time windows — all with zero `any` and full type safety on every event shape and its aggregated form.",
    "snippet": "\n// Core event union & kind extraction\ntype TelemetryEvent = PageViewEvent | ClickEvent | ErrorEvent | PurchaseEvent;\ntype EventKind = TelemetryEvent[\"kind\"]; // \"pageView\" | \"click\" | \"error\" | \"purchase\"\n\n// Map each kind to its rollup shape\ntype RollupMap = { [K in EventKind]: /* matching rollup type */ never };\n\n// Generic reducer interface\ninterface Reducer<K extends EventKind> {\n  reduce(acc: RollupMap[K] | undefined, event: ExtractEvent<K>): RollupMap[K];\n}\n\n// Main aggregation function — groups events into time windows and folds them\nfunction aggregateEvents<K extends EventKind>(\n  events: TelemetryEvent[],\n  kind: K,\n  reducer: Reducer<K>,\n  windowMs?: number        // default 60_000 ms\n): Map<string, RollupMap[K]>\n",
    "goals": [
      "Define `TelemetryEvent` as a discriminated union and derive `EventKind` and `ExtractEvent<K>` from it using utility/conditional types — no hand-written string literals.",
      "Build `RollupMap` as a mapped type over `EventKind` that associates each event kind with its rollup shape.",
      "Implement the generic `Reducer<K>` interface and all four concrete reducers (`pageViewReducer`, `clickReducer`, `errorReducer`, `purchaseReducer`) with correct types.",
      "Implement `windowKey` and `aggregateEvents` so that events are bucketed by time window and folded through the correct reducer, returning a fully-typed `Map<string, RollupMap[K]>`."
    ],
    "hints": [
      "For `ExtractEvent<K>`, `Extract<TelemetryEvent, { kind: K }>` is the most concise approach — it leverages distributive conditional types built into `Extract`.",
      "Inside `aggregateEvents`, after filtering with `event.kind === kind`, TypeScript may still need a type assertion-free cast — try a type predicate helper `(e): e is ExtractEvent<K> => e.kind === kind` to keep things clean.",
      "For `RollupMap`, write `[K in EventKind]: ...` and use a conditional type (or explicit mapping) to select the right rollup type for each key — this is the one place a conditional type inside a mapped type really shines."
    ],
    "docs": [
      {
        "title": "TypeScript Handbook — Discriminated Unions",
        "url": "https://www.typescriptlang.org/docs/handbook/2/narrowing.html#discriminated-unions"
      },
      {
        "title": "TypeScript Handbook — Mapped Types",
        "url": "https://www.typescriptlang.org/docs/handbook/2/mapped-types.html"
      },
      {
        "title": "TypeScript Handbook — Conditional Types",
        "url": "https://www.typescriptlang.org/docs/handbook/2/conditional-types.html"
      },
      {
        "title": "TypeScript Utility Types — Extract",
        "url": "https://www.typescriptlang.org/docs/handbook/utility-types.html#extracttype-union"
      }
    ]
  },
  {
    "date": "2026-03-01",
    "name": "Typed Distributed Cache with TTL & Eviction Policies",
    "difficulty": "Hard",
    "description": "You're building the caching layer for a high-throughput microservice platform. Each cache namespace has its own value shape, TTL strategy, and eviction policy — and the orchestrator must coordinate reads, writes, and invalidations across multiple namespaces with full compile-time safety on every key-value pair.",
    "snippet": "// Key types at a glance\n\ntype AppSchema = {\n  users: { id: number; name: string };\n  tokens: string;\n  counters: number;\n};\n\nexport type EvictionPolicy =\n  | { kind: \"lru\"; maxSize: number }\n  | { kind: \"ttl\"; defaultTtlMs: number }\n  | { kind: \"none\" };\n\nexport type NamespaceConfig<V> = {\n  policy: EvictionPolicy;\n  serialize?:   (value: V) => string;\n  deserialize?: (raw: string) => V;\n};\n\nexport type NamespaceConfigs<S extends CacheSchema> = {\n  [K in keyof S]: NamespaceConfig<S[K]>;\n};\n\nexport interface CacheOrchestrator<S extends CacheSchema> {\n  set<K extends keyof S>(ns: K, key: string, value: S[K], ttlMs?: number): void;\n  get<K extends keyof S>(ns: K, key: string): S[K] | undefined;\n  delete<K extends keyof S>(ns: K, key: string): boolean;\n  invalidateNamespace<K extends keyof S>(ns: K): void;\n  stats<K extends keyof S>(ns: K): NamespaceStats;\n}\n\nexport function createCacheOrchestrator<S extends CacheSchema>(\n  configs: NamespaceConfigs<S>\n): CacheOrchestrator<S> { /* TODO */ throw new Error(\"Not implemented\"); }",
    "goals": [
      "Define the `EvictionPolicy` discriminated union and `NamespaceConfig<V>` generic with optional serialize/deserialize pair.",
      "Implement `NamespaceConfigs<S>` as a mapped type so each namespace key binds to the correctly-typed config.",
      "Implement `createCacheOrchestrator` with per-namespace LRU eviction, lazy TTL expiry, accurate stats counters, and full `CacheOrchestrator<S>` interface compliance.",
      "Implement the `cacheKey` branded-type helper with runtime length validation."
    ],
    "hints": [
      "A `Map<string, Entry<V>>` preserves insertion order — delete then re-insert a key on every access to cheaply maintain LRU order without a doubly-linked list.",
      "Narrow the eviction policy with a `switch (policy.kind)` inside `set` and `get` so TypeScript's exhaustiveness checking guides you through each branch.",
      "The `NamespaceConfigs<S>` mapped type only needs one line: `[K in keyof S]: NamespaceConfig<S[K]>` — the hard part is making sure the orchestrator's internal store is also keyed generically over `keyof S`."
    ],
    "docs": [
      {
        "title": "TypeScript Mapped Types",
        "url": "https://www.typescriptlang.org/docs/handbook/2/mapped-types.html"
      },
      {
        "title": "TypeScript Discriminated Unions",
        "url": "https://www.typescriptlang.org/docs/handbook/2/narrowing.html#discriminated-unions"
      },
      {
        "title": "TypeScript Generics — Keyof & Indexed Access",
        "url": "https://www.typescriptlang.org/docs/handbook/2/indexed-access-types.html"
      },
      {
        "title": "MDN — Map (insertion-order iteration)",
        "url": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map"
      }
    ]
  },
  {
    "date": "2026-03-02",
    "name": "Typed Contact Book with Safe Parsing & Lookup",
    "difficulty": "Easy",
    "description": "You're building a lightweight contact management module for a small business app. Raw contact data arrives as unknown JSON from an import file, and you must validate it into strongly-typed records, build an efficient lookup index, and expose typed query helpers — all without reaching for `any`.",
    "snippet": "export type PhoneType = \"mobile\" | \"home\" | \"work\";\n\nexport interface PhoneNumber {\n  type: PhoneType;\n  number: string;\n}\n\nexport interface Contact {\n  id: string;\n  firstName: string;\n  lastName: string;\n  email: string;\n  phones: PhoneNumber[]; // at least one entry\n  tags: string[];\n}\n\nexport type Result<T, E> = never; // TODO: define discriminated union\n\nexport type ParseError = never;   // TODO: define discriminated union\n\nexport type ContactIndex = never; // TODO: use Record utility type\n\nexport function parseContact(raw: unknown): Result<Contact, ParseError> { ... }\nexport function buildIndex(contacts: Contact[]): ContactIndex { ... }\nexport function findById(index: ContactIndex, id: string): Contact | undefined { ... }\nexport function filterByTags(index: ContactIndex, requiredTags: string[]): Contact[] { ... }\nexport function searchByName(index: ContactIndex, prefix: string): Contact[] { ... }",
    "goals": [
      "Define a generic `Result<T, E>` discriminated union and a `ParseError` discriminated union with at least three variants.",
      "Implement `parseContact` to safely narrow `unknown` input into a typed `Contact`, returning descriptive `ParseError` values for every invalid case.",
      "Implement `buildIndex` using the `Record` utility type and `findById` returning `Contact | undefined` without any type assertions.",
      "Implement `filterByTags` and `searchByName` using typed iteration over the `ContactIndex`."
    ],
    "hints": [
      "A discriminated union needs a shared literal-typed field (e.g. `ok` or `kind`) so TypeScript can narrow between variants in `if`/`switch` blocks.",
      "To validate `phones` entries, check `Array.isArray` first, then iterate and verify each entry's `type` is one of the three `PhoneType` literals — a `const VALID_PHONE_TYPES` tuple with `includes` (after a cast-free helper) works well here.",
      "`Object.values(index)` gives you a `Contact[]` you can then `filter` and `sort` without any extra type work."
    ],
    "docs": [
      {
        "title": "TypeScript Handbook — Discriminated Unions",
        "url": "https://www.typescriptlang.org/docs/handbook/2/narrowing.html#discriminated-unions"
      },
      {
        "title": "TypeScript Handbook — Generics",
        "url": "https://www.typescriptlang.org/docs/handbook/2/generics.html"
      },
      {
        "title": "TypeScript Utility Types (Record, Pick, Omit…)",
        "url": "https://www.typescriptlang.org/docs/handbook/utility-types.html"
      },
      {
        "title": "MDN — Array.prototype.every (used for tag filtering)",
        "url": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/every"
      }
    ]
  },
  {
    "date": "2026-03-03",
    "name": "Typed Workflow State Machine",
    "difficulty": "Medium",
    "description": "You're building the order-processing engine for a fulfilment platform. Each order moves through a strict lifecycle — from placement to delivery or cancellation — and only certain transitions are legal at any given state. The challenge is encoding that lifecycle entirely in the type system so that illegal transitions are caught at compile time, not at runtime.",
    "snippet": "// Key types — fill in the TODOs to make this compile\nexport type OrderState =\n  | \"pending\" | \"confirmed\" | \"picking\"\n  | \"shipped\" | \"delivered\" | \"cancelled\";\n\nexport type TransitionMap = {\n  [S in OrderState]: ReadonlyArray<OrderState>; // narrow each value!\n};\n\nexport type LegalTransition<S extends OrderState> = TODO; // indexed into TransitionMap\n\nexport type OrderEvent =\n  | { type: \"CONFIRM\";       orderId: string; timestamp: number }\n  | { type: \"START_PICKING\"; orderId: string; timestamp: number }\n  | { type: \"SHIP\";          orderId: string; timestamp: number; trackingCode: string }\n  | { type: \"DELIVER\";       orderId: string; timestamp: number }\n  | { type: \"CANCEL\";        orderId: string; timestamp: number; reason: string };\n\n// Main functions you must implement:\nexport function buildOrder(id: string, createdAt: number): Order { … }\nexport function transition(order: Order, event: OrderEvent): Order { … }\nexport function getValidNextEvents(order: Order): ReadonlyArray<OrderEvent[\"type\"]> { … }\n",
    "goals": [
      "Define `TransitionMap` as a mapped type and derive `LegalTransition<S>` from it using indexed access so illegal states resolve to `never`.",
      "Model `OrderEvent` as a discriminated union where event-specific fields (trackingCode, reason) only appear on the relevant member.",
      "Implement `transition` with function overloads, throwing a `TypeError` on any illegal state transition.",
      "Implement `getValidNextEvents` to return only the event-type strings that are currently legal for the order's state."
    ],
    "hints": [
      "For `LegalTransition<S>`, index into `TransitionMap` with `S` and then use `[number]` to convert the readonly array type into a union.",
      "Inside `transition`, narrow the event with a `switch (event.type)` — TypeScript will automatically narrow the event shape in each branch, letting you access `trackingCode` or `reason` safely.",
      "The provided `STATE_LEGAL_EVENTS` constant is keyed by `OrderState` and valued by `ReadonlyArray<OrderEvent[\"type\"]>` — lean on it inside both `transition` (for validation) and `getValidNextEvents` (for the return value)."
    ],
    "docs": [
      {
        "title": "TypeScript Handbook — Mapped Types",
        "url": "https://www.typescriptlang.org/docs/handbook/2/mapped-types.html"
      },
      {
        "title": "TypeScript Handbook — Conditional Types",
        "url": "https://www.typescriptlang.org/docs/handbook/2/conditional-types.html"
      },
      {
        "title": "TypeScript Handbook — Discriminated Unions",
        "url": "https://www.typescriptlang.org/docs/handbook/2/narrowing.html#discriminated-unions"
      },
      {
        "title": "TypeScript Handbook — Function Overloads",
        "url": "https://www.typescriptlang.org/docs/handbook/2/functions.html#function-overloads"
      }
    ]
  },
  {
    "date": "2026-03-04",
    "name": "Typed Plugin Middleware Chain with Typed Error Hierarchy",
    "difficulty": "Hard",
    "description": "You're building the request-processing core of an API gateway. Incoming requests pass through a chain of strongly-typed middleware plugins (auth, rate-limiting, transformation, logging). Each plugin can either pass the request downstream, short-circuit with a typed error, or mutate the request context — and the orchestrator must collect per-plugin results, surface a typed error hierarchy, and guarantee exhaustive handling at every exit point.",
    "snippet": "// Key types and main function signature\n\nexport type RequestId  = string & { readonly __brand: \"RequestId\" };\nexport type PluginName = string & { readonly __brand: \"PluginName\" };\n\nexport type PluginError =\n  | { kind: \"auth\";       reason: string }\n  | { kind: \"rate_limit\"; retryAfterMs: number }\n  | { kind: \"validation\"; field: string; issue: string }\n  | { kind: \"upstream\";   statusCode: number; body: string };\n\nexport type Result<T, E> =\n  | { ok: true;  value: T }\n  | { ok: false; error: E };\n\nexport interface Plugin {\n  name: PluginName;\n  execute(ctx: RequestContext): Promise<Result<RequestContext, PluginError>>;\n}\n\nexport type ChainResult =\n  | { outcome: \"success\"; finalContext: RequestContext; audit: PluginRecord[] }\n  | { outcome: \"failure\"; failedPlugin: PluginName; error: PluginError; audit: PluginRecord[] };\n\nexport async function runChain(\n  plugins: Plugin[],\n  initialContext: RequestContext\n): Promise<ChainResult> { /* TODO */ }\n",
    "goals": [
      "Define the full typed error hierarchy (AuthError, RateLimitError, ValidationError, UpstreamError) as a discriminated union and wire it through Result<T,E> and Plugin.",
      "Implement runChain to execute plugins sequentially, short-circuit on the first failure, record accurate durationMs per plugin, and mark unexecuted plugins as 'skipped'.",
      "Implement renderError with an exhaustive switch over all PluginError variants, using a never-assertion in the default branch to guarantee compile-time completeness.",
      "Implement summariseAudit to aggregate a PluginRecord[] into an AuditSummary — narrowing each record variant to compute counts, total duration, and per-plugin error details."
    ],
    "hints": [
      "A `never`-assertion helper like `function assertNever(x: never): never { throw new Error(...) }` makes the default branch of your switch exhaustive at compile time.",
      "For PluginRecord, keep `durationMs` only on the `passed` and `failed` variants — the `skipped` variant has no timing to record, which naturally guides your summariseAudit accumulator.",
      "In runChain, capture `Date.now()` before and after each `await plugin.execute(ctx)` call; store the delta as `durationMs` before deciding which PluginRecord variant to push."
    ],
    "docs": [
      {
        "title": "TypeScript Handbook — Discriminated Unions",
        "url": "https://www.typescriptlang.org/docs/handbook/2/narrowing.html#discriminated-unions"
      },
      {
        "title": "TypeScript Handbook — Conditional & Mapped Types",
        "url": "https://www.typescriptlang.org/docs/handbook/2/types-from-types.html"
      },
      {
        "title": "TypeScript Handbook — Generics",
        "url": "https://www.typescriptlang.org/docs/handbook/2/generics.html"
      },
      {
        "title": "TypeScript Deep Dive — Branded Types",
        "url": "https://basarat.gitbook.io/typescript/main-1/nominaltyping"
      }
    ]
  },
  {
    "date": "2026-03-05",
    "name": "Typed Paginated API Client with Result Chaining",
    "difficulty": "Medium",
    "description": "You're building the data-fetching layer for an admin dashboard that queries a paginated REST API. Each endpoint returns a different resource shape, and the client must transparently walk pages, accumulate results, and surface typed errors — all without a single `any`.",
    "snippet": "// Key types\nexport type Ok<T>     = { readonly kind: \"ok\";  readonly value: T };\nexport type Err<E>    = { readonly kind: \"err\"; readonly error: E };\nexport type Result<T, E> = Ok<T> | Err<E>;\n\nexport type ApiError =\n  | { readonly kind: \"network\";   readonly message: string }\n  | { readonly kind: \"not_found\"; readonly resource: string }\n  | { readonly kind: \"parse\";     readonly raw: string };\n\nexport interface Page<T> {\n  readonly items:      T[];\n  readonly nextCursor: string | null;\n  readonly total:      number;\n}\n\nexport type PageFetcher<T> =\n  (cursor: string | null) => Promise<Result<Page<T>, ApiError>>;\n\n// Core functions you must implement:\nexport async function fetchAllPages<T>(\n  fetcher: PageFetcher<T>\n): Promise<Result<T[], ApiError>> { /* TODO */ }\n\nexport function mapResult<T, U, E>(\n  result: Result<T, E>, fn: (value: T) => U\n): Result<U, E> { /* TODO */ }\n\nexport function groupById<T extends { id: string }>(\n  items: T[]\n): ReadonlyMap<string, T> { /* TODO */ }\n",
    "goals": [
      "Define and use a discriminated-union Result<T,E> type with Ok and Err variants throughout all functions.",
      "Implement fetchAllPages to walk paginated cursors sequentially, accumulating items and short-circuiting on the first error.",
      "Write runtime validators (validateUser, validateAuditLog, validatePage) that narrow unknown to typed structs using only typeof/in guards — no type assertions.",
      "Implement mapResult, flatMapResult, and pipeResults to enable safe, composable result chaining."
    ],
    "hints": [
      "For validateUser, check typeof on each field individually before constructing the User — the compiler will track the narrowed type for you.",
      "fetchAllPages should use a while loop driven by nextCursor: start with null, replace it with the cursor from each successful page until it's null again.",
      "pipeResults can be solved in a single pass with Array.reduce — accumulate values into an Ok([]) and short-circuit to Err on the first Err you encounter."
    ],
    "docs": [
      {
        "title": "TypeScript Handbook: Narrowing",
        "url": "https://www.typescriptlang.org/docs/handbook/2/narrowing.html"
      },
      {
        "title": "TypeScript Handbook: Generics",
        "url": "https://www.typescriptlang.org/docs/handbook/2/generics.html"
      },
      {
        "title": "TypeScript Handbook: Discriminated Unions",
        "url": "https://www.typescriptlang.org/docs/handbook/typescript-in-5-minutes-func.html#discriminated-unions"
      },
      {
        "title": "MDN: Promise — sequential vs parallel",
        "url": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise#sequential_composition"
      }
    ]
  },
  {
    "date": "2026-03-06",
    "name": "Typed Real-Time Event Aggregator with Windowed Metrics",
    "difficulty": "Hard",
    "description": "You're building the analytics backbone of a live-streaming platform. Raw telemetry events (views, reactions, chat messages, errors) arrive in bursts and must be funnelled through a strongly-typed aggregation pipeline that groups them into fixed time windows, computes per-event-kind statistics, and surfaces a typed Result for every query — all with zero `any`.",
    "snippet": "\n// Key types and main class signature\n\ntype EventKind = \"view\" | \"reaction\" | \"chat\" | \"error\";\n\n// TODO: define this conditional/mapped type\ntype EventMetrics<K extends EventKind> = never; // ← replace\n\ninterface WindowSnapshot {\n  windowId: WindowId;\n  startTs: TimestampMs;\n  endTs: TimestampMs;\n  metrics: { [K in EventKind]?: EventMetrics<K> };\n}\n\ntype Result<T, E> = { ok: true; value: T } | { ok: false; error: E };\n\ntype AggregatorError =\n  | { kind: \"EMPTY_WINDOW\";    windowId: WindowId }\n  | { kind: \"WINDOW_NOT_FOUND\"; windowId: WindowId }\n  | { kind: \"INVALID_RANGE\";   startTs: TimestampMs; endTs: TimestampMs };\n\nclass EventAggregator {\n  constructor(private readonly windowSizeMs: number) {}\n  ingest(events: readonly TelemetryEvent[]): void { ... }\n  computeWindow(windowId: WindowId): Result<WindowSnapshot, AggregatorError> { ... }\n  queryRange(startTs: TimestampMs, endTs: TimestampMs): Result<WindowSnapshot[], AggregatorError> { ... }\n  getMetricsForKind<K extends EventKind>(windowId: WindowId, kind: K): Result<EventMetrics<K>, AggregatorError> { ... }\n}\n",
    "goals": [
      "Define `EventMetrics<K extends EventKind>` as a conditional or mapped type that resolves to the exact metrics interface for each event kind.",
      "Implement `EventAggregator` — ingest events into fixed time windows, compute per-kind metrics, and surface typed Results for window queries and range queries.",
      "Implement the generic `getMetricsForKind<K>` so TypeScript infers `EventMetrics<K>` at the call site without any type assertions.",
      "Implement `renderMetrics` with an exhaustive switch over `EventKind` using `assertNever`, so adding a new kind to the union is a compile-time error."
    ],
    "hints": [
      "For `EventMetrics<K>`, a conditional type chain (`K extends 'view' ? ViewMetrics : K extends 'reaction' ? ...`) is the cleanest approach — TypeScript can then narrow the return type of `getMetricsForKind` without casts.",
      "Inside `getMetricsForKind`, index `snapshot.metrics[kind]` — because `metrics` is typed as `{ [K in EventKind]?: EventMetrics<K> }`, the lookup already returns `EventMetrics<K> | undefined`, so no assertion is needed.",
      "For exhaustiveness in `renderMetrics`, switch over the `kind` key of each metrics entry; the `default` branch should call `assertNever(kind)` where `kind: never`."
    ],
    "docs": [
      {
        "title": "TypeScript Handbook — Conditional Types",
        "url": "https://www.typescriptlang.org/docs/handbook/2/conditional-types.html"
      },
      {
        "title": "TypeScript Handbook — Mapped Types",
        "url": "https://www.typescriptlang.org/docs/handbook/2/mapped-types.html"
      },
      {
        "title": "TypeScript Handbook — Narrowing & Exhaustiveness",
        "url": "https://www.typescriptlang.org/docs/handbook/2/narrowing.html#exhaustiveness-checking"
      },
      {
        "title": "TypeScript Handbook — Generics",
        "url": "https://www.typescriptlang.org/docs/handbook/2/generics.html"
      }
    ]
  },
  {
    "date": "2026-03-07",
    "name": "Typed Job Queue with Retry Logic & Concurrency Limits",
    "difficulty": "Medium",
    "description": "You're building the background job runner for a SaaS platform. Jobs arrive with different payloads and priorities, each handler is typed to its payload, and the runner must enforce a concurrency cap, retry failed jobs with exponential back-off, and report a typed summary when the queue drains.",
    "snippet": "// Key types — core of the challenge\n\nexport type JobKind = \"email\" | \"report\" | \"webhook\";\n\n// Each concrete job locks `kind` and `payload` together\nexport type EmailJob   = Job<EmailPayload>   & { kind: \"email\" };\nexport type ReportJob  = Job<ReportPayload>  & { kind: \"report\" };\nexport type WebhookJob = Job<WebhookPayload> & { kind: \"webhook\" };\nexport type AnyJob     = EmailJob | ReportJob | WebhookJob;\n\n// Resolve the right payload type for each kind (conditional type)\ntype PayloadFor<K extends JobKind> = TODO;\n\n// Registry maps every kind to the correctly-typed handler\nexport type JobRegistry = {\n  [K in JobKind]: JobHandler<PayloadFor<K>>;\n};\n\n// Factory — enforce concurrency cap + retry logic\nexport function createJobRunner(\n  registry: JobRegistry,\n  options: RunnerOptions   // { maxConcurrency, baseDelayMs }\n): JobRunner {             // { enqueue(job), run(): Promise<RunSummary> }\n  throw new Error(\"Not implemented\");\n}",
    "goals": [
      "Define a discriminated-union `AnyJob` and a conditional `PayloadFor<K>` type so that `JobRegistry` maps each job kind to a handler that only accepts the matching payload type.",
      "Implement `createJobRunner` so that `run()` never executes more than `maxConcurrency` jobs simultaneously, using a Promise-slot pool or equivalent pattern.",
      "Implement exponential back-off retry: on handler failure, wait `baseDelayMs * 2^attemptsMade` ms and retry up to `job.maxRetries` times before recording a final failure.",
      "Return a fully-typed `RunSummary` from `run()` whose `results` array contains a `JobOutcome` discriminated union for every job processed."
    ],
    "hints": [
      "For `PayloadFor<K>`, write a conditional type that maps `\"email\"` → `EmailPayload`, `\"report\"` → `ReportPayload`, `\"webhook\"` → `WebhookPayload` — then use it inside the mapped `JobRegistry` type.",
      "To dispatch a job to its handler without a type assertion, narrow on `job.kind` inside a `switch` statement; TypeScript will infer the correct payload type in each branch.",
      "A simple concurrency pool: keep a `Set` of in-flight Promises; when the set reaches `maxConcurrency`, `await Promise.race(activeSet)` before starting the next job."
    ],
    "docs": [
      {
        "title": "TypeScript Handbook — Conditional Types",
        "url": "https://www.typescriptlang.org/docs/handbook/2/conditional-types.html"
      },
      {
        "title": "TypeScript Handbook — Mapped Types",
        "url": "https://www.typescriptlang.org/docs/handbook/2/mapped-types.html"
      },
      {
        "title": "TypeScript Handbook — Discriminated Unions",
        "url": "https://www.typescriptlang.org/docs/handbook/2/narrowing.html#discriminated-unions"
      },
      {
        "title": "MDN — Promise.race()",
        "url": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/race"
      }
    ]
  },
  {
    "date": "2026-03-08",
    "name": "Typed Inventory Aggregator",
    "difficulty": "Easy",
    "description": "You're building the stock-management module for an e-commerce back-office. Raw inventory records arrive from multiple warehouses and must be validated, grouped by category, and summarised — all with zero `any` and fully typed results.",
    "snippet": "\n// Key types & main signatures at a glance\n\nexport type Category = \"electronics\" | \"clothing\" | \"food\" | \"furniture\";\n\nexport type Result<T, E> =\n  | { ok: true;  value: T }\n  | { ok: false; error: E };\n\nexport interface InventoryItem extends Omit<RawRecord, \"category\"> {\n  category: Category;           // narrowed from raw string\n}\n\nexport interface CategorySummary {\n  category: Category;\n  totalItems: number;\n  totalQuantity: number;\n  totalValue: number;           // sum of quantity * unitPrice (cents)\n  averageUnitPrice: number;     // rounded mean unitPrice across SKUs\n}\n\n// ── Functions you must implement ──────────────────────────────────────────────\nexport function validateRecord(raw: RawRecord): Result<InventoryItem, ValidationError>;\nexport function partitionRecords(raws: RawRecord[]): { valid: InventoryItem[]; errors: ValidationError[] };\nexport function aggregateByCategory(items: InventoryItem[]): Partial<Record<Category, CategorySummary>>;\nexport function processInventory(raws: RawRecord[]): { summary: Partial<Record<Category, CategorySummary>>; errors: ValidationError[] };\n",
    "goals": [
      "Implement `validateRecord` to narrow a `RawRecord` into an `InventoryItem` or return a typed `ValidationError` using a `Result` discriminated union.",
      "Implement `partitionRecords` to collect all valid items and all errors in a single pass without short-circuiting.",
      "Implement `aggregateByCategory` to group items and compute per-category statistics (`totalItems`, `totalQuantity`, `totalValue`, `averageUnitPrice`) in a single loop.",
      "Compose the full pipeline in `processInventory`, returning both the aggregated summary and any validation errors."
    ],
    "hints": [
      "A `Set` or tuple literal like `[\"electronics\", \"clothing\", \"food\", \"furniture\"] as const` makes it easy to check whether a raw string is a valid `Category` — and TypeScript will narrow the type for you after the check.",
      "For `aggregateByCategory`, use `Array.prototype.reduce` with a `Partial<Record<Category, CategorySummary>>` accumulator so you can build each entry on first encounter and update it on subsequent ones — all in one pass.",
      "The `Result<T, E>` discriminated union lets you branch on `.ok` without any type assertions — lean on that in `partitionRecords` to route each outcome to the right bucket."
    ],
    "docs": [
      {
        "title": "TypeScript Utility Types (Pick, Omit, Record)",
        "url": "https://www.typescriptlang.org/docs/handbook/utility-types.html"
      },
      {
        "title": "TypeScript Narrowing",
        "url": "https://www.typescriptlang.org/docs/handbook/2/narrowing.html"
      },
      {
        "title": "Discriminated Unions",
        "url": "https://www.typescriptlang.org/docs/handbook/2/narrowing.html#discriminated-unions"
      },
      {
        "title": "Array.prototype.reduce – MDN",
        "url": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/reduce"
      }
    ]
  },
  {
    "date": "2026-03-09",
    "name": "Typed State Machine Executor with Transition Guards",
    "difficulty": "Hard",
    "description": "You're building the order-lifecycle engine for a fulfilment platform. Each order moves through a strict set of states (e.g. `pending → confirmed → shipped → delivered`), and every transition must pass a typed guard before it fires. The engine must enforce exhaustive state/event coverage at the type level, accumulate a typed audit log, and surface a discriminated `Result` for every attempted transition — with zero `any`.",
    "snippet": "// Core types at a glance\n\ntype OrderState = \"pending\" | \"confirmed\" | \"processing\" | \"shipped\" | \"delivered\" | \"cancelled\";\ntype OrderEvent = \"CONFIRM\" | \"START_PROCESSING\" | \"SHIP\" | \"DELIVER\" | \"CANCEL\";\n\ntype Guard = (ctx: OrderContext) => true | string; // true = allow, string = deny reason\n\ninterface TransitionDef<S extends OrderState> {\n  readonly target: Exclude<OrderState, S>; // can't transition to yourself\n  readonly guards?: readonly Guard[];\n}\n\ntype TransitionMap = {\n  readonly [S in OrderState]?: {\n    readonly [E in OrderEvent]?: TransitionDef<S>;\n  };\n};\n\n// Main class signature\nclass StateMachine {\n  constructor(map: TransitionMap);\n  transition(ctx: OrderContext, currentState: OrderState, event: OrderEvent): TransitionResult;\n  getAuditLog(): readonly AuditEntry[];\n  getAuditLogFor(orderId: OrderId): readonly AuditEntry[];\n}",
    "goals": [
      "Define a branded `OrderId` type and a safe factory function using a `unique symbol` brand.",
      "Implement the `StateMachine` class so it correctly resolves transitions, runs typed guards in order, and appends discriminated `AuditEntry` records to an internal log.",
      "Implement `replayToState` so it drives the machine through a sequence of events and returns a fully typed `ReplaySummary` with success/failure breakdowns.",
      "Implement `buildTransitionMap` as a generic dual-constraint helper that preserves literal target types at the call site without any type assertions."
    ],
    "hints": [
      "The `Exclude<OrderState, S>` on `TransitionDef.target` is enforced at the type level — lean on it to see how the generic `S` flows through the mapped type.",
      "For `buildTransitionMap`, a single `return map` is the entire implementation — the heavy lifting is in the dual generic constraint `T extends TransitionMap` combined with the parameter type `T & TransitionMap`.",
      "When narrowing `TransitionResult` in `replayToState`, use the `ok` discriminant to update your running state only on success, keeping the final state stable after a failure."
    ],
    "docs": [
      {
        "title": "TypeScript Handbook – Mapped Types",
        "url": "https://www.typescriptlang.org/docs/handbook/2/mapped-types.html"
      },
      {
        "title": "TypeScript Handbook – Conditional Types & infer",
        "url": "https://www.typescriptlang.org/docs/handbook/2/conditional-types.html"
      },
      {
        "title": "TypeScript Handbook – Utility Types (Extract, Exclude, Omit…)",
        "url": "https://www.typescriptlang.org/docs/handbook/utility-types.html"
      },
      {
        "title": "TypeScript 4.9 – satisfies operator",
        "url": "https://www.typescriptlang.org/docs/handbook/release-notes/typescript-4-9.html#the-satisfies-operator"
      }
    ]
  },
  {
    "date": "2026-03-10",
    "name": "Typed Contact Book Merger",
    "difficulty": "Easy",
    "description": "You're building the import feature for a personal CRM app. Users can sync contacts from multiple sources (phone, email, LinkedIn), and your job is to validate raw unknown input, merge duplicate contacts by email, and produce a clean, strongly-typed contact list — all with zero `any`.",
    "snippet": "export type ContactSource = \"phone\" | \"email\" | \"linkedin\";\n\nexport interface Contact {\n  email: string;\n  name: string;\n  phone: string | null;\n  sources: ContactSource[];\n}\n\nexport type ParseResult<T> =\n  | { ok: true; value: T }\n  | { ok: false; error: string };\n\n// Narrows an unknown value to a ContactSource literal\nexport function isContactSource(value: unknown): value is ContactSource { /* TODO */ }\n\n// Validates & normalises a single unknown record\nexport function parseRawContact(raw: unknown): ParseResult<Contact> { /* TODO */ }\n\n// Merges an array of unknown records, deduplicating by email\nexport function mergeContacts(\n  rawRecords: unknown[]\n): { contacts: Contact[]; failures: Array<{ ok: false; error: string }> } { /* TODO */ }",
    "goals": [
      "Implement `isContactSource` as a type guard that narrows `unknown` to the `ContactSource` union.",
      "Implement `parseRawContact` to validate every field of an unknown record and return a typed `ParseResult<Contact>` with normalised values.",
      "Implement `mergeContacts` to run the parser over all raw records, collect failures, and merge duplicate contacts by email using a `Map` — keeping the first non-null phone and unioning sources."
    ],
    "hints": [
      "A type guard function returns `value is SomeType` — use `===` checks against each literal string to narrow `ContactSource`.",
      "In `parseRawContact`, check `typeof raw === 'object' && raw !== null && !Array.isArray(raw)` first, then use `'email' in raw` before accessing any property.",
      "Use `new Map<string, Contact>()` in `mergeContacts` and `new Set(existing.sources)` to deduplicate sources when merging a duplicate email."
    ],
    "docs": [
      {
        "title": "TypeScript — Narrowing & Type Guards",
        "url": "https://www.typescriptlang.org/docs/handbook/2/narrowing.html"
      },
      {
        "title": "TypeScript — Discriminated Unions",
        "url": "https://www.typescriptlang.org/docs/handbook/2/narrowing.html#discriminated-unions"
      },
      {
        "title": "MDN — Map",
        "url": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map"
      },
      {
        "title": "MDN — Set",
        "url": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set"
      }
    ]
  },
  {
    "date": "2026-03-11",
    "name": "Typed Paginated API Client with Result Chaining",
    "difficulty": "Medium",
    "description": "You're building the data-fetching layer for an admin dashboard that pulls paginated records from a REST API. Each page arrives as raw `unknown` JSON, must be validated into a typed shape, and pages must be lazily fetched until exhausted — all surfaced through a `Result<T, E>` type so callers never face surprise runtime exceptions.",
    "snippet": "// Key types & main function signature\n\nexport type Result<T, E> =\n  | { ok: true;  value: T }\n  | { ok: false; error: E };\n\nexport type Page<T> = {\n  items:     T[];\n  page:      number;\n  nextPage?: number;\n};\n\ndeclare const ParseErrorBrand: unique symbol;\nexport type ParseError = { message: string; [ParseErrorBrand]: true };\n\ndeclare const FetchErrorBrand: unique symbol;\nexport type FetchError  = { message: string; cause?: unknown; [FetchErrorBrand]: true };\n\n/** Validates raw unknown data into a typed Page<T>. */\nexport function parsePage<T>(\n  raw: unknown,\n  parseItem: (item: unknown) => Result<T, ParseError>\n): Result<Page<T>, ParseError> { /* TODO */ throw 0; }\n\n/** Fetches every page, collects all items, returns Result or first error. */\nexport async function fetchAllPages<T>(\n  fetcher:   (page: number) => Promise<unknown>,\n  parseItem: (item: unknown) => Result<T, ParseError>\n): Promise<Result<T[], FetchError>> { /* TODO */ throw 0; }",
    "goals": [
      "Define the generic `Result<T, E>` discriminated union and its `ok()` / `err()` constructor helpers.",
      "Implement `parsePage<T>` to validate raw `unknown` API responses into a typed `Page<T>`, rejecting bad shapes with a branded `ParseError`.",
      "Implement `fetchAllPages<T>` to lazily follow `nextPage` links, accumulate items, and surface the first failure as a branded `FetchError`.",
      "Implement the `mapResult` and `chainResult` combinators to enable type-safe transformation and flat-mapping of `Result` values."
    ],
    "hints": [
      "Branded types use a `unique symbol` as a key — add it to the object type so the brand is structurally unforged.",
      "In `parsePage`, use `Array.isArray` for the items check and `typeof x === 'number'` for numeric fields — TypeScript will narrow correctly inside those branches.",
      "In `fetchAllPages`, wrap the `fetcher` call in a `try/catch`; convert a caught `ParseError` to a `FetchError` by reading its `.message` and passing the original as `cause`."
    ],
    "docs": [
      {
        "title": "TypeScript Handbook — Discriminated Unions",
        "url": "https://www.typescriptlang.org/docs/handbook/2/narrowing.html#discriminated-unions"
      },
      {
        "title": "TypeScript Handbook — Generics",
        "url": "https://www.typescriptlang.org/docs/handbook/2/generics.html"
      },
      {
        "title": "TypeScript Handbook — Narrowing (unknown)",
        "url": "https://www.typescriptlang.org/docs/handbook/2/narrowing.html"
      },
      {
        "title": "MDN — async function / await",
        "url": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function"
      }
    ]
  },
  {
    "date": "2026-03-12",
    "name": "Typed Expense Report Summariser",
    "difficulty": "Easy",
    "description": "You're building the finance module for a small business app. Raw expense entries arrive as unknown JSON from a mobile upload, and you must validate them, categorise them, and produce a per-category summary — all with zero `any` and fully typed results.",
    "snippet": "\n// Core domain types\ntype ExpenseCategory = \"travel\" | \"meals\" | \"software\" | \"hardware\" | \"other\";\n\ninterface Expense {\n  id: string;\n  description: string;\n  amountCents: number;   // integer > 0\n  category: ExpenseCategory;\n  date: string;          // \"YYYY-MM-DD\"\n  submittedBy: string;\n}\n\n// Result discriminated union — your job to define it!\ntype Result<T, E> = /* TODO */;\n\n// Type guard — must narrow to ExpenseCategory\nfunction isExpenseCategory(value: unknown): value is ExpenseCategory { /* TODO */ }\n\n// Validates raw unknown → typed Expense, collecting ALL field errors\nfunction validateExpense(raw: unknown): Result<Expense, ValidationError[]> { /* TODO */ }\n\n// Groups a validated list into a Map keyed by category\nfunction groupByCategory(expenses: Expense[]): Map<ExpenseCategory, Expense[]> { /* TODO */ }\n\n// Orchestrates validation + grouping → final typed report\nfunction processRawExpenses(rawEntries: unknown[]): {\n  report: ExpenseReport;\n  invalid: Array<{ raw: unknown; errors: ValidationError[] }>;\n} { /* TODO */ }\n",
    "goals": [
      "Define a generic discriminated-union `Result<T, E>` type and use it as the return type of `validateExpense`.",
      "Implement `isExpenseCategory` as a proper TypeScript type guard that narrows `unknown` to `ExpenseCategory`.",
      "Write `validateExpense` so it collects ALL field-level `ValidationError`s in a single pass before returning `ok: false`.",
      "Wire everything together in `processRawExpenses`, separating valid expenses from invalid ones and building a sorted `ExpenseReport`."
    ],
    "hints": [
      "A discriminated union on a boolean literal (`ok: true` vs `ok: false`) is the cleanest way to model `Result<T, E>` — TypeScript will narrow the type automatically in `if (result.ok)` branches.",
      "In `validateExpense`, check `typeof raw === 'object' && raw !== null` first, then use `'id' in raw` + `typeof (raw as Record<string, unknown>).id` to access each field safely without `any`.",
      "`Array.prototype.reduce` over `Map.entries()` is a clean single-pass way to compute `totalCents` and `count` for each `ExpenseSummary` inside `buildReport`."
    ],
    "docs": [
      {
        "title": "TypeScript Handbook — Narrowing",
        "url": "https://www.typescriptlang.org/docs/handbook/2/narrowing.html"
      },
      {
        "title": "TypeScript Handbook — Discriminated Unions",
        "url": "https://www.typescriptlang.org/docs/handbook/typescript-in-5-minutes-func.html#discriminated-unions"
      },
      {
        "title": "MDN — Map",
        "url": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map"
      },
      {
        "title": "TypeScript Handbook — Type Guards & Type Predicates",
        "url": "https://www.typescriptlang.org/docs/handbook/2/narrowing.html#using-type-predicates"
      }
    ]
  },
  {
    "date": "2026-03-13",
    "name": "Typed Concurrent Task Scheduler with Priority Queues",
    "difficulty": "Hard",
    "description": "You're building the background job engine for a data-pipeline platform. Tasks arrive with a priority level and resource tags, must be executed with a concurrency cap per resource group, and every outcome — success, failure, or cancellation — must be surfaced through a fully typed Result hierarchy with zero `any`.",
    "snippet": "// Key types and main entry-point — enough to understand the challenge\n\ndeclare const __taskIdBrand: unique symbol;\nexport type TaskId = string & { readonly [__taskIdBrand]: true };\n\nexport type Priority = \"low\" | \"normal\" | \"high\" | \"critical\";\n\nexport type TaskError =\n  | { kind: \"timeout\";  durationMs: number }\n  | { kind: \"runtime\";  message: string; cause?: unknown }\n  | { kind: \"overflow\"; queueSize: number };\n\nexport type TaskResult<T> =\n  | { status: \"fulfilled\"; id: TaskId; value: T }\n  | { status: \"rejected\";  id: TaskId; error: TaskError }\n  | { status: \"cancelled\"; id: TaskId; reason: string };\n\nexport interface TaskDefinition<T> {\n  id: TaskId;\n  priority: Priority;\n  resourceGroup: string;\n  run: () => Promise<T>;\n  timeoutMs?: number;\n}\n\nexport interface Scheduler {\n  submit<T>(task: TaskDefinition<T>): Promise<TaskResult<T>>;\n  cancel(id: TaskId): boolean;\n  stats(): SchedulerStats;\n}\n\nexport function createScheduler(config: SchedulerConfig): Scheduler { /* TODO */ }",
    "goals": [
      "Define branded TaskId, Priority, TaskError, and TaskResult<T> types with zero `any` and no type casts.",
      "Implement createScheduler() so tasks are dispatched in priority order while respecting both per-group and global concurrency caps.",
      "Handle timeout races, runtime rejections, and queue-overflow cancellations — each surfaced as the correct TaskResult variant.",
      "Derive SchedulerStats.totals via a mapped type over GroupCounts keys so the shape stays in sync automatically."
    ],
    "hints": [
      "A priority queue can be a plain array you re-sort on insert — use the PRIORITY_ORDER weight map to compare entries.",
      "To race a task against its timeout, wrap both in Promise.race: one resolves with the value, the other rejects after timeoutMs ms.",
      "Store each queued task alongside its resolve function so that cancel() and overflow can settle the promise from outside the run loop."
    ],
    "docs": [
      {
        "title": "TypeScript — Branded / Nominal Types",
        "url": "https://www.typescriptlang.org/docs/handbook/2/types-from-types.html"
      },
      {
        "title": "TypeScript — Mapped Types",
        "url": "https://www.typescriptlang.org/docs/handbook/2/mapped-types.html"
      },
      {
        "title": "TypeScript — satisfies operator",
        "url": "https://www.typescriptlang.org/docs/handbook/release-notes/typescript-4-9.html#the-satisfies-operator"
      },
      {
        "title": "MDN — Promise.race()",
        "url": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/race"
      }
    ]
  },
  {
    "date": "2026-03-14",
    "name": "Typed Recipe Ingredient Scaler",
    "difficulty": "Easy",
    "description": "You're building the recipe feature for a meal-planning app. Users can scale any recipe up or down by a multiplier, and your job is to parse raw unknown ingredient data, convert quantities to a common unit system, and return a fully typed scaled ingredient list — with zero `any`.",
    "snippet": "// Key types and main function signatures\n\nexport type VolumeUnit = \"tsp\" | \"tbsp\" | \"cup\" | \"ml\" | \"l\";\nexport type WeightUnit = \"g\" | \"kg\" | \"oz\" | \"lb\";\nexport type CountUnit  = \"whole\" | \"pinch\" | \"slice\";\n\nexport type Unit =\n  | { kind: \"volume\"; unit: VolumeUnit }\n  | { kind: \"weight\"; unit: WeightUnit }\n  | { kind: \"count\";  unit: CountUnit  };\n\nexport type Result<T, E> =\n  | { ok: true;  value: T }\n  | { ok: false; error: E };\n\nexport interface ScaledIngredient {\n  name: string;\n  scaledQuantity: number;  // multiplied & converted to canonical unit\n  canonicalUnit: string;   // \"ml\" | \"g\" | original CountUnit string\n  note?: string;\n}\n\n// Parse one raw unknown value → typed Ingredient or ValidationError\nexport function parseIngredient(raw: unknown): Result<Ingredient, ValidationError>;\n\n// Validate + scale an entire list; short-circuits on first bad entry\nexport function scaleRecipe(\n  rawIngredients: unknown[],\n  multiplier: number\n): Result<ScaledIngredient[], ValidationError>;\n",
    "goals": [
      "Define `VolumeUnit`, `WeightUnit`, `CountUnit`, and a discriminated `Unit` union, plus a generic `Result<T,E>` and a discriminated `ValidationError` union.",
      "Implement `parseIngredient` to validate an `unknown` value into a typed `Ingredient`, returning the correct `ValidationError` variant on any bad field.",
      "Populate the `Record<VolumeUnit, number>` and `Record<WeightUnit, number>` conversion tables, then use them inside `scaleRecipe` to convert and scale each ingredient to its canonical unit.",
      "Implement `scaleRecipe` to short-circuit on the first parse failure and return a fully typed `Result<ScaledIngredient[], ValidationError>`."
    ],
    "hints": [
      "A `Record<VolumeUnit, number>` will cause a compile error if you forget any member of the union — use that to your advantage when filling in the conversion tables.",
      "Inside `scaleRecipe`, narrow `ingredient.unit.kind` with an `if`/`switch` to access the correct sub-type — TypeScript will enforce exhaustiveness and give you the right `unit` field in each branch.",
      "For `parseIngredient`, build small typed constant arrays like `const VOLUME_UNITS: VolumeUnit[] = [...]` and use `Array.prototype.includes` with a type predicate to validate `unitValue` without casting."
    ],
    "docs": [
      {
        "title": "TypeScript Handbook — Discriminated Unions",
        "url": "https://www.typescriptlang.org/docs/handbook/2/narrowing.html#discriminated-unions"
      },
      {
        "title": "TypeScript Handbook — Utility Types (Record)",
        "url": "https://www.typescriptlang.org/docs/handbook/utility-types.html#recordkeys-type"
      },
      {
        "title": "TypeScript Handbook — Narrowing (typeof / in)",
        "url": "https://www.typescriptlang.org/docs/handbook/2/narrowing.html"
      },
      {
        "title": "TypeScript Handbook — Generic Types",
        "url": "https://www.typescriptlang.org/docs/handbook/2/generics.html"
      }
    ]
  },
  {
    "date": "2026-03-15",
    "name": "Typed Real-Time Event Stream Processor",
    "difficulty": "Hard",
    "description": "You're building the analytics backbone for a live dashboard that ingests a heterogeneous stream of server-sent events (user actions, system alerts, and metric snapshots). Each event must be parsed from raw `unknown` input, routed through a typed middleware pipeline, and aggregated into a strongly-typed per-event-kind summary — all with zero `any`.",
    "snippet": "\n// Core discriminated union\ntype StreamEvent = UserActionEvent | SystemAlertEvent | MetricSnapshotEvent;\n\n// Per-kind middleware — E is bound to the correct event subtype\ntype Middleware<E extends StreamEvent = StreamEvent> = (\n  event: E,\n  next: (event: E) => E | null\n) => E | null;\n\n// Mapped middleware map — keys tied to EventKind, values typed via Extract\ntype KindMiddlewareMap = {\n  [K in EventKind]?: Middleware<Extract<StreamEvent, { kind: K }>>;\n};\n\n// StreamSummary: a mapped type you must define (Requirement 6)\ntype StreamSummary = unknown; // TODO: replace with mapped type over EventKind\n\n// Main orchestrator\nfunction processStream(\n  rawPayloads: unknown[],\n  middlewareMap: KindMiddlewareMap\n): { summary: StreamSummary; parseErrors: ParseError[] } {\n  throw new Error(\"Not implemented\");\n}\n",
    "goals": [
      "Implement `parseEvent` to safely narrow `unknown` input into a `StreamEvent` discriminated union, returning typed `Result<StreamEvent, ParseError>` with specific error codes.",
      "Define `StreamSummary` as a mapped type over `EventKind` using the `KindSummaryMap` helper, then implement `buildSummary` for a single-pass aggregation.",
      "Implement `runPipeline` using `Extract<StreamEvent, { kind: K }>` to route each event to its correctly-typed middleware without any type assertions.",
      "Wire everything together in `processStream`, accumulating parse errors and discarding middleware-dropped events before producing the final summary."
    ],
    "hints": [
      "For `StreamSummary`, think `{ [K in EventKind]: KindSummaryMap[K] }` — the mapped type directly indexes your helper map.",
      "In `runPipeline`, the middleware map value has type `Middleware<Extract<StreamEvent, { kind: typeof event.kind }>>` — narrow the event's kind first, then look it up.",
      "For `parseEvent`, write a helper like `isObject(v: unknown): v is Record<string, unknown>` to safely access fields before checking their types."
    ],
    "docs": [
      {
        "title": "TypeScript — Discriminated Unions",
        "url": "https://www.typescriptlang.org/docs/handbook/2/narrowing.html#discriminated-unions"
      },
      {
        "title": "TypeScript — Mapped Types",
        "url": "https://www.typescriptlang.org/docs/handbook/2/mapped-types.html"
      },
      {
        "title": "TypeScript — Conditional Types & Extract",
        "url": "https://www.typescriptlang.org/docs/handbook/2/conditional-types.html#distributive-conditional-types"
      },
      {
        "title": "TypeScript — Utility Types (Record, Extract, etc.)",
        "url": "https://www.typescriptlang.org/docs/handbook/utility-types.html"
      }
    ]
  },
  {
    "date": "2026-03-16",
    "name": "Typed Notification Preference Engine",
    "difficulty": "Medium",
    "description": "You're building the notification settings module for a SaaS platform. Users configure per-channel delivery rules (email, SMS, push), and your engine must validate raw unknown config payloads, merge them with system-level defaults, and produce a resolved, strongly-typed preference map — surfaced through a `Result<T, E>` type so callers can handle every failure mode explicitly.",
    "snippet": "// Key types & main function signatures\n\nexport type Channel = \"email\" | \"sms\" | \"push\";\n\nexport interface ChannelOptionMap {\n  email: { enabled: boolean; frequency: \"instant\" | \"daily\" | \"weekly\" };\n  sms:   { enabled: boolean; quietHoursStart: number; quietHoursEnd: number };\n  push:  { enabled: boolean; badge: boolean; sound: boolean };\n}\n\n// Mapped: every channel optional (user overrides)\nexport type UserPreferences    = { [C in Channel]?: ChannelOptionMap[C] };\n// Mapped: every channel required (defaults filled in)\nexport type ResolvedPreferences = { [C in Channel]: ChannelOptionMap[C] };\n\nexport type PreferenceError =\n  | { kind: \"validation_error\"; field: string; message: string }\n  | { kind: \"unknown_channel\"; channel: string };\n\nexport type Result<T, E> = Ok<T> | Err<E>;\n\n// Template literal summary keys: \"email_summary\" | \"sms_summary\" | \"push_summary\"\nexport type ChannelSummaryKey = `${Channel}_summary`;\n\nexport function parsePreferences(raw: unknown): Result<UserPreferences, PreferenceError>;\nexport function mergeWithDefaults(prefs: UserPreferences): ResolvedPreferences;\nexport function resolvePreferences(raw: unknown): Result<ResolvedPreferences, PreferenceError>;\nexport function describeResolved(resolved: ResolvedPreferences): ChannelSummaryMap;\n",
    "goals": [
      "Define Ok<T>/Err<E> discriminated union and generic ok()/err() constructors, then use them throughout the module.",
      "Build ChannelOptionMap, UserPreferences, and ResolvedPreferences using mapped types over the Channel union so the structure is DRY and extensible.",
      "Implement parsePreferences to safely narrow an unknown payload field-by-field, returning typed PreferenceError variants on every failure path.",
      "Implement mergeWithDefaults and compose it with parsePreferences inside resolvePreferences, then produce a ChannelSummaryMap via describeResolved using the ChannelSummaryKey template literal type."
    ],
    "hints": [
      "A mapped type `{ [C in Channel]?: ChannelOptionMap[C] }` is all you need for UserPreferences — no need to repeat each channel manually.",
      "In parsePreferences, narrow the unknown value with `typeof` and `in` checks before reading any property; TypeScript will track the narrowed type for you.",
      "Use `satisfies ResolvedPreferences` on SYSTEM_DEFAULTS so you get literal-type inference (e.g. `\"daily\"`) while still having the type checked at compile time."
    ],
    "docs": [
      {
        "title": "TypeScript Mapped Types",
        "url": "https://www.typescriptlang.org/docs/handbook/2/mapped-types.html"
      },
      {
        "title": "TypeScript Template Literal Types",
        "url": "https://www.typescriptlang.org/docs/handbook/2/template-literal-types.html"
      },
      {
        "title": "TypeScript Narrowing",
        "url": "https://www.typescriptlang.org/docs/handbook/2/narrowing.html"
      },
      {
        "title": "TypeScript `satisfies` operator",
        "url": "https://www.typescriptlang.org/docs/handbook/release-notes/typescript-4-9.html#the-satisfies-operator"
      }
    ]
  },
  {
    "date": "2026-03-17",
    "name": "Typed Book Club Reading List Builder",
    "difficulty": "Easy",
    "description": "You're building the reading list feature for a book club app. Members submit raw book entries from a form, and you must validate them, tag each book with a derived reading status, and produce a sorted, fully typed reading list — with zero `any`.",
    "snippet": "\nexport type Genre = \"fiction\" | \"non-fiction\" | \"biography\" | \"science\" | \"history\";\nexport type ReadingStatus = \"not-started\" | \"in-progress\" | \"completed\";\n\nexport interface Book {\n  id: string;\n  title: string;\n  author: string;\n  genre: Genre;\n  totalPages: number;\n  pagesRead: number;\n  status: ReadingStatus; // derived — NOT accepted from raw input\n}\n\nexport type Result<T, E> =\n  | { ok: true;  value: T }\n  | { ok: false; error: E };\n\nexport interface ReadingList {\n  books: Book[];                               // sorted A-Z by title\n  summary: Record<ReadingStatus, number>;      // count per status (all keys present)\n  rejected: Array<{ input: unknown; error: BookValidationError }>;\n}\n\n// Main entry point\nexport function buildReadingList(rawEntries: unknown[]): ReadingList { ... }\n",
    "goals": [
      "Implement `ok` and `err` generic helpers that construct a discriminated-union `Result<T, E>`.",
      "Write `isGenre` as a type-predicate function that narrows `unknown` to the `Genre` union.",
      "Implement `parseBook` to validate every field of an `unknown` input against the `Book` interface, deriving `status` via `deriveStatus` and returning the first `BookValidationError` on failure.",
      "Implement `buildReadingList` to parse all raw entries, sort valid books case-insensitively by title, and produce a `summary` `Record` with a count for every `ReadingStatus` key — even zeros."
    ],
    "hints": [
      "A type-predicate (`value is Genre`) lets TypeScript narrow the type in the caller's scope — use an array of the valid strings and `.includes()` after a `typeof` check.",
      "When building the `summary` Record, initialise all three `ReadingStatus` keys to `0` before iterating so no key is ever missing — `Record<ReadingStatus, number>` requires all keys.",
      "In `parseBook`, check `typeof input === 'object' && input !== null` first, then use `'id' in input` before indexing — this keeps you `any`-free under `strict: true`."
    ],
    "docs": [
      {
        "title": "TypeScript Handbook — Narrowing",
        "url": "https://www.typescriptlang.org/docs/handbook/2/narrowing.html"
      },
      {
        "title": "TypeScript Handbook — Utility Types (Record, Pick…)",
        "url": "https://www.typescriptlang.org/docs/handbook/utility-types.html"
      },
      {
        "title": "TypeScript Handbook — Generics",
        "url": "https://www.typescriptlang.org/docs/handbook/2/generics.html"
      },
      {
        "title": "MDN — Array.prototype.sort()",
        "url": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort"
      }
    ]
  },
  {
    "date": "2026-03-18",
    "name": "Typed API Pagination Cursor Engine",
    "difficulty": "Medium",
    "description": "You're building the data-fetching layer for an analytics dashboard that loads large datasets from a paginated REST API. Each resource type has its own shape, and the engine must handle cursor-based pagination, typed per-resource response validation, and aggregation into a single fully-typed result — surfaced through a `Result<T, E>` type with zero `any`.",
    "snippet": "// Core types you'll work with:\n\ntype ResourceMap = {\n  users:    UserRecord;\n  orders:   OrderRecord;\n  products: ProductRecord;\n};\n\ntype ResourceKind = keyof ResourceMap;   // \"users\" | \"orders\" | \"products\"\n\ntype ValidatorRegistry = {\n  [K in ResourceKind]: Validator<ResourceMap[K]>;\n};\n\n// Main functions to implement:\n\nfunction parseRawPage<K extends ResourceKind>(\n  kind: K,\n  raw: unknown,\n  registry: ValidatorRegistry\n): Result<PageResult<K>, PaginationError>;\n\nasync function fetchAllPages<K extends ResourceKind>(\n  kind: K,\n  fetcher: PageFetcher,\n  registry: ValidatorRegistry,\n  maxPages?: number\n): Promise<Result<AggregatedResult<K>, PaginationError>>;\n\nfunction buildValidatorRegistry(): ValidatorRegistry;",
    "goals": [
      "Implement `buildValidatorRegistry` with runtime validators that narrow `unknown` to each resource type using only type-safe field checks.",
      "Implement `parseRawPage` to validate the raw API response shape and each record using the registry, returning the correct discriminated `PaginationError` variant on failure.",
      "Implement `fetchAllPages` to drive cursor-based pagination, accumulate records across pages, and handle both fetch errors and validation errors through the `Result<T, E>` type.",
      "Use the mapped type `ValidatorRegistry` and indexed access `ResourceMap[K]` so that every function is fully generic over `ResourceKind` with no `any` or type assertions."
    ],
    "hints": [
      "A mapped type `{ [K in ResourceKind]: Validator<ResourceMap[K]> }` lets you index the registry with a generic `K` and get back the right validator type automatically — lean on that to avoid casting.",
      "To narrow `unknown` to an object with known keys, check `typeof raw === 'object' && raw !== null` first, then use `'fieldName' in raw` before accessing the property — TypeScript will accept this without assertions.",
      "In `fetchAllPages`, keep a `cursor: string | null = null` variable, loop with a `while` condition, and break out when `nextCursor` is null or you've hit `maxPages` — wrap the entire fetcher call in a `try/catch`."
    ],
    "docs": [
      {
        "title": "TypeScript Handbook — Mapped Types",
        "url": "https://www.typescriptlang.org/docs/handbook/2/mapped-types.html"
      },
      {
        "title": "TypeScript Handbook — Narrowing",
        "url": "https://www.typescriptlang.org/docs/handbook/2/narrowing.html"
      },
      {
        "title": "TypeScript Handbook — Generics",
        "url": "https://www.typescriptlang.org/docs/handbook/2/generics.html"
      },
      {
        "title": "TypeScript Utility Types (Extract, Record, etc.)",
        "url": "https://www.typescriptlang.org/docs/handbook/utility-types.html"
      }
    ]
  },
  {
    "date": "2026-03-19",
    "name": "Typed Task Priority Queue",
    "difficulty": "Easy",
    "description": "You're building the task management feature for a lightweight project tool. Users submit raw task entries, and your engine must validate them, assign a computed urgency tier, and serve them back in priority order — all with zero `any`.",
    "snippet": "\n// Key types & main function signatures:\n\ntype RawPriority = \"low\" | \"medium\" | \"high\";\ntype UrgencyTier = 1 | 2 | 3 | 4 | 5;\ntype TaskStatus  = \"pending\" | \"in-progress\" | \"done\";\n\ninterface Task {\n  id: string;\n  title: string;\n  priority: RawPriority;\n  dueDate: Date;\n  status: TaskStatus;\n  tags: string[];\n  urgencyTier: UrgencyTier; // computed from priority + dueDate\n}\n\ntype Ok<T>       = { ok: true;  value: T };\ntype Err<E>      = { ok: false; error: E };\ntype Result<T,E> = Ok<T> | Err<E>;\n\n// Validate one unknown input → typed Task or a ValidationError\nfunction validateTask(input: unknown): Result<Task, ValidationError> { ... }\n\n// Validate all inputs, collect errors, return sorted Task[]\nfunction buildPriorityQueue(rawInputs: unknown[]): {\n  tasks:  Task[];\n  errors: Array<{ index: number; error: ValidationError }>;\n} { ... }\n",
    "goals": [
      "Implement `computeUrgency` to map priority + days-until-due to the correct UrgencyTier using the provided matrix.",
      "Implement `validateTask` to narrow `unknown` input field-by-field and return a fully typed `Result<Task, ValidationError>` — no `as`, no `any`.",
      "Implement `buildPriorityQueue` to collect all errors across inputs and return valid tasks sorted by urgencyTier DESC then dueDate ASC.",
      "Implement `filterByStatus` and `groupByUrgency`, ensuring `groupByUrgency` always returns all five tier keys typed as `Record<UrgencyTier, Task[]>`."
    ],
    "hints": [
      "For `unknown` narrowing, check `typeof field === 'string'` and membership in a const array (e.g. `const PRIORITIES = ['low','medium','high'] as const`) — TypeScript will narrow the type for you.",
      "A `Result<T,E>` discriminated union is narrowed by checking `.ok`: inside `if (result.ok)` the value is `Ok<T>`, otherwise `Err<E>`.",
      "To satisfy `Record<UrgencyTier, Task[]>`, initialise the object with all five keys before pushing into it — e.g. `{ 1: [], 2: [], 3: [], 4: [], 5: [] }`."
    ],
    "docs": [
      {
        "title": "TypeScript Handbook — Narrowing",
        "url": "https://www.typescriptlang.org/docs/handbook/2/narrowing.html"
      },
      {
        "title": "TypeScript Handbook — Discriminated Unions",
        "url": "https://www.typescriptlang.org/docs/handbook/2/narrowing.html#discriminated-unions"
      },
      {
        "title": "TypeScript Utility Types — Record",
        "url": "https://www.typescriptlang.org/docs/handbook/utility-types.html#recordkeys-type"
      },
      {
        "title": "MDN — Array.prototype.sort()",
        "url": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort"
      }
    ]
  },
  {
    "date": "2026-03-20",
    "name": "Typed Workflow State Machine Executor",
    "difficulty": "Hard",
    "description": "You're building the automation backbone for a CI/CD platform. Each pipeline is a finite state machine whose transitions are guarded by typed conditions, carry typed payloads, and emit strongly-typed side-effect events — all resolved through a `Result<T, E>` monad with exhaustive error handling and zero `any`.",
    "snippet": "// Core types and main class signature — no solution code included\n\ntype StateKind = 'idle' | 'queued' | 'running' | 'succeeded' | 'failed' | 'cancelled';\n\ntype WorkflowState<K extends StateKind> = { readonly kind: K } & StatePayloadMap[K];\ntype AnyWorkflowState = { [K in StateKind]: WorkflowState<K> }[StateKind];\n\ntype Guard<\n  From extends StateKind,\n  To extends AllowedTransitions[From][number]\n> = (current: WorkflowState<From>, rawPayload: unknown) => Result<true, TransitionError>;\n\nclass StateMachine {\n  constructor(\n    workflowId: string,\n    initial: WorkflowState<'idle'>,\n    emit: EventEmitter\n  ) { /* TODO */ }\n\n  get state(): AnyWorkflowState { /* TODO */ }\n\n  transition<To extends AllowedTransitions[StateKind][number]>(\n    to: To,\n    rawPayload: unknown,\n    ...guards: ReadonlyArray<Guard<StateKind, To>>\n  ): Result<WorkflowState<To>, TransitionError> { /* TODO */ }\n\n  history(): ReadonlyArray<AnyWorkflowState> { /* TODO */ }\n}\n",
    "goals": [
      "Define `WorkflowState<K>` via intersection of a discriminant and a mapped payload lookup, and encode `AllowedTransitions` as a mapped type over `StateKind`.",
      "Implement `validatePayload` using a `switch` on `StateKind` and `typeof` narrowing to convert `unknown` payloads into typed `StatePayloadMap[K]` values — no `any`, no assertions.",
      "Implement `StateMachine` with a generic `transition` method that enforces the transition graph, runs variadic guards in sequence, validates the payload, updates state, and emits the correct `WorkflowEvent`.",
      "Implement `aggregateRuns` in a single `reduce` pass that computes total count, per-final-state breakdown, average duration of succeeded runs, and a sorted unique list of failure reasons."
    ],
    "hints": [
      "For `validatePayload`, a `switch (kind)` gives you a narrowed `K` in each branch — then use `typeof` checks on individual fields and return `err({ kind: 'PayloadValidationError', ... })` on the first mismatch.",
      "The `AllowedTransitions[From][number]` indexed access type is the key to constraining `To` in both `Guard` and `transition` — make sure `ALLOWED_TRANSITIONS` is typed as `AllowedTransitions` (not inferred) so the literal arrays stay narrow.",
      "In `aggregateRuns`, accumulate a `Set<string>` for failure reasons inside the reduce, then convert to a sorted array only once at the end — and track `totalDuration` + `succeededCount` separately to compute the average without a second pass."
    ],
    "docs": [
      {
        "title": "TypeScript — Mapped Types",
        "url": "https://www.typescriptlang.org/docs/handbook/2/mapped-types.html"
      },
      {
        "title": "TypeScript — Indexed Access Types",
        "url": "https://www.typescriptlang.org/docs/handbook/2/indexed-access-types.html"
      },
      {
        "title": "TypeScript — Narrowing",
        "url": "https://www.typescriptlang.org/docs/handbook/2/narrowing.html"
      },
      {
        "title": "TypeScript — Generic Constraints",
        "url": "https://www.typescriptlang.org/docs/handbook/2/generics.html#generic-constraints"
      }
    ]
  },
  {
    "date": "2026-03-21",
    "name": "Typed Expense Report Aggregator",
    "difficulty": "Easy",
    "description": "You're building the expense reporting module for a small business finance tool. Employees submit raw expense entries from a form, and your engine must validate them, tag each with a derived reimbursement status, and produce a grouped, fully typed summary — with zero `any`.",
    "snippet": "\n// Key types & main function signature\n\ntype ExpenseCategory = \"travel\" | \"meals\" | \"software\" | \"equipment\" | \"other\";\n\ntype ReimbursementStatus =\n  | { readonly kind: \"auto_approved\"; readonly approvedAt: Date }\n  | { readonly kind: \"needs_review\"; readonly reason: string }\n  | { readonly kind: \"flagged\"; readonly reason: string; readonly flaggedAmount: number };\n\ntype Result<T, E> =\n  | { readonly ok: true;  readonly value: T }\n  | { readonly ok: false; readonly error: E };\n\ninterface TaggedExpenseEntry extends ExpenseEntry {\n  readonly status: ReimbursementStatus;\n}\n\ninterface ExpenseReport {\n  readonly entries: ReadonlyArray<TaggedExpenseEntry>;\n  readonly sortedByAmount: ReadonlyArray<TaggedExpenseEntry>;\n  readonly categorySummaries: ReadonlyArray<CategorySummary>;\n  readonly grandTotalUSD: number;\n  readonly rejected: ReadonlyArray<{ raw: RawExpenseEntry; error: ValidationError }>;\n}\n\n// --- Functions to implement ---\nfunction validateExpenseEntry(raw: RawExpenseEntry): Result<ExpenseEntry, ValidationError> { ... }\nfunction deriveStatus(entry: ExpenseEntry): ReimbursementStatus { ... }\nfunction buildExpenseReport(raws: ReadonlyArray<RawExpenseEntry>): ExpenseReport { ... }\n",
    "goals": [
      "Implement `validateExpenseEntry` to narrow all `unknown` fields into a fully-typed `ExpenseEntry`, returning the first `ValidationError` encountered.",
      "Implement `deriveStatus` to map an `ExpenseEntry`'s amount to the correct `ReimbursementStatus` discriminated union branch.",
      "Implement `buildExpenseReport` to validate, tag, sort, and aggregate raw entries into a complete `ExpenseReport` — collecting both valid tagged entries and rejected ones.",
      "Produce correct `CategorySummary` objects with per-status counts using `Record<ReimbursementStatus[\"kind\"], number>` — with no `any`."
    ],
    "hints": [
      "When narrowing `unknown` fields, use `typeof` checks and `Array.prototype.includes` with a `const` tuple of valid categories to satisfy the type checker without casting.",
      "For `buildExpenseReport`'s aggregation, a `Map<ExpenseCategory, CategorySummary>` makes grouping and updating per-category totals straightforward in a single pass.",
      "The `Record<ReimbursementStatus['kind'], number>` in `CategorySummary.byStatus` needs all three keys (`auto_approved`, `needs_review`, `flagged`) initialised to `0` before counting."
    ],
    "docs": [
      {
        "title": "TypeScript Handbook — Narrowing",
        "url": "https://www.typescriptlang.org/docs/handbook/2/narrowing.html"
      },
      {
        "title": "TypeScript Handbook — Discriminated Unions",
        "url": "https://www.typescriptlang.org/docs/handbook/2/narrowing.html#discriminated-unions"
      },
      {
        "title": "TypeScript Utility Types (Record, Pick, Omit…)",
        "url": "https://www.typescriptlang.org/docs/handbook/utility-types.html"
      },
      {
        "title": "MDN — Date constructor & Date.parse",
        "url": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/Date"
      }
    ]
  },
  {
    "date": "2026-03-22",
    "name": "Typed Notification Dispatch Router",
    "difficulty": "Medium",
    "description": "You're building the notification layer for a SaaS platform. Users can subscribe to different channels (email, SMS, push), and your router must validate raw subscription configs, fan out typed messages to each channel's handler, and collect a structured per-channel delivery report — surfaced through a `Result<T, E>` type with zero `any`.",
    "snippet": "// Core types and main function signatures\n\ntype Result<T, E> = { ok: true; value: T } | { ok: false; error: E };\n\ntype Channel =\n  | { kind: \"email\"; address: string }\n  | { kind: \"sms\";   phone: string }\n  | { kind: \"push\";  deviceToken: string };\n\ntype NotificationMessage =\n  | { kind: \"email\"; subject: string; body: string }\n  | { kind: \"sms\";   text: string }\n  | { kind: \"push\";  title: string; payload: Record<string, string> };\n\n// Mapped over Channel[\"kind\"] — every channel kind gets a delivery slot\ntype DeliveryOutcome = { [K in Channel[\"kind\"]]: { status: DeliveryStatus; detail: string } };\n\n// Each registry slot is narrowed to the exact Channel + Message pair for kind K\ntype HandlerRegistry = { [K in Channel[\"kind\"]]: ChannelHandler<Extract<Channel, { kind: K }>, Extract<NotificationMessage, { kind: K }>> };\n\nfunction validateSubscription(raw: RawSubscription): Result<ValidatedSubscription, DispatchError>;\n\nasync function dispatchNotifications(\n  subscription: ValidatedSubscription,\n  messages: readonly NotificationMessage[],\n  registry: HandlerRegistry\n): Promise<Result<DeliveryOutcome, never>>;\n",
    "goals": [
      "Define `Channel`, `NotificationMessage`, and `DispatchError` as discriminated unions with the specified members.",
      "Define `DeliveryOutcome` as a mapped type keyed over `Channel[\"kind\"]` and `HandlerRegistry` as a mapped type that narrows each handler to its exact channel and message pair using `Extract<>`.",
      "Implement `validateSubscription` to parse an unknown channel array, silently drop invalid entries, and return a typed `Result` with the appropriate `DispatchError` code.",
      "Implement `dispatchNotifications` to concurrently invoke per-channel handlers from the registry, record sent/failed/skipped outcomes, and always return `Result<DeliveryOutcome, never>`."
    ],
    "hints": [
      "For `HandlerRegistry`, use `Extract<Channel, { kind: K }>` inside a mapped type to get the exact channel variant for each key — this is what gives each handler its precise parameter types.",
      "In `validateSubscription`, narrow `raw.channels` step by step: first check `Array.isArray`, then use a type predicate or inline guard to filter each element into a valid `Channel`.",
      "In `dispatchNotifications`, build one Promise per channel in the subscription, then pass them all to `Promise.all` — each promise resolves to a `[kind, { status, detail }]` tuple you can assemble into a `DeliveryOutcome`."
    ],
    "docs": [
      {
        "title": "TypeScript Handbook — Discriminated Unions",
        "url": "https://www.typescriptlang.org/docs/handbook/2/narrowing.html#discriminated-unions"
      },
      {
        "title": "TypeScript Handbook — Mapped Types",
        "url": "https://www.typescriptlang.org/docs/handbook/2/mapped-types.html"
      },
      {
        "title": "TypeScript Handbook — Conditional Types & Extract",
        "url": "https://www.typescriptlang.org/docs/handbook/2/conditional-types.html#distributive-conditional-types"
      },
      {
        "title": "MDN — Promise.all",
        "url": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/all"
      }
    ]
  },
  {
    "date": "2026-03-23",
    "name": "Typed Plugin Middleware Chain Executor",
    "difficulty": "Hard",
    "description": "You're building the extensibility core for a developer platform where third-party plugins can register typed middleware that transforms a shared request context. Each plugin declares the exact context shape it reads and the shape it writes, and the chain executor must thread them together in order — surfacing typed errors and a full execution trace through a `Result<T, E>` monad with zero `any`.",
    "snippet": "// Key types — understand these before implementing\n\nexport type Result<T, E> =\n  | { ok: true;  value: T }\n  | { ok: false; error: E };\n\nexport interface BaseContext {\n  readonly requestId: string;\n  meta: Record<string, unknown>;\n}\n\nexport type MiddlewareFn<In extends BaseContext, Out extends In> = (\n  ctx: In\n) => Promise<Result<Out, PluginError>>;\n\nexport interface Plugin<In extends BaseContext, Out extends In> {\n  id: string;\n  timeoutMs: number;\n  run: MiddlewareFn<In, Out>;\n}\n\n// Main entry point\nexport async function executeChain(\n  initCtx: BaseContext,\n  registry: PluginRegistry\n): Promise<ChainResult<BaseContext>>;\n",
    "goals": [
      "Define a `Result<T,E>` discriminated union and implement `ok`/`err` constructors, then build a `PluginError` discriminated union covering validation, timeout, and dependency variants.",
      "Model `Plugin<In, Out>` with a generic constraint `Out extends In` that enforces context-only-grows semantics, and implement `PluginRegistry` with a fluent `register()` builder.",
      "Implement `executeChain` that runs plugins sequentially, enforces per-plugin timeouts via `Promise.race`, accumulates a `TraceEntry` for every started plugin, and short-circuits on the first error.",
      "Implement `formatPluginError` with an exhaustive `switch` over `PluginError` kinds, using a `never`-typed default branch so TypeScript proves no variant is unhandled."
    ],
    "hints": [
      "For the timeout race, create a `Promise<Result<never, PluginError>>` that rejects (or resolves to `err(...)`) after `timeoutMs` milliseconds — then `Promise.race` it against the plugin's own promise.",
      "Store plugins in `PluginRegistry` as `Plugin<BaseContext, BaseContext>[]`; the `register<In, Out>` generic signature is safe to accept because `Plugin<In, Out>` is assignable to `Plugin<BaseContext, BaseContext>` given the covariant/contravariant positions here — but you may need a targeted cast only inside `register`.",
      "The `never`-typed default in `formatPluginError` looks like: `default: { const _exhaustive: never = error; throw new Error(...); }` — TypeScript will error if you ever add a new `PluginError` variant without handling it."
    ],
    "docs": [
      {
        "title": "TypeScript Handbook — Discriminated Unions",
        "url": "https://www.typescriptlang.org/docs/handbook/2/narrowing.html#discriminated-unions"
      },
      {
        "title": "TypeScript Handbook — Generic Constraints",
        "url": "https://www.typescriptlang.org/docs/handbook/2/generics.html#generic-constraints"
      },
      {
        "title": "MDN — Promise.race()",
        "url": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/race"
      },
      {
        "title": "TypeScript Handbook — Utility Types",
        "url": "https://www.typescriptlang.org/docs/handbook/utility-types.html"
      }
    ]
  },
  {
    "date": "2026-03-24",
    "name": "Typed Paginated API Response Aggregator",
    "difficulty": "Medium",
    "description": "You're building the data-sync layer for a dashboard that pulls records from a paginated REST API. The fetcher must handle typed pages, collect results across all pages with a concurrency limit, and surface either a fully aggregated dataset or a structured `Result<T, E>` error — with zero `any`.",
    "snippet": "// Core types at a glance\n\ntype ApiRecord<T> = { id: string; createdAt: string; payload: T };\ntype Page<T>      = { page: number; totalPages: number; items: ApiRecord<T>[] };\n\ntype FetchError =\n  | { kind: \"network\"; message: string; page: number }\n  | { kind: \"timeout\"; page: number; afterMs: number }\n  | { kind: \"parse\";   page: number; raw: string }\n  | { kind: \"unknown\"; page: number; cause: unknown };\n\ntype PageFetcher<T> = (page: number) => Promise<Result<Page<T>, FetchError>>;\n\n// Main function to implement:\nasync function aggregatePages<T>(\n  fetchPage: PageFetcher<T>,\n  config: { concurrency: number; failFast: boolean }\n): Promise<Result<AggregateSuccess<T>, AggregateError>> { ... }",
    "goals": [
      "Implement the `ok` and `err` Result constructors and use them throughout without type assertions.",
      "Fetch page 1 first to discover `totalPages`, then fetch remaining pages in concurrency-limited batches.",
      "Respect the `failFast` flag — abort with `Err<AggregateError>` on the first failure, or accumulate errors into `failedPages` when lenient.",
      "Implement `formatFetchError` with an exhaustive discriminated-union switch so TypeScript catches any missing case."
    ],
    "hints": [
      "Batch an array of page numbers into chunks of size `concurrency` and `await Promise.all(chunk.map(...))` each batch sequentially.",
      "The `Result<T, E>` discriminant is `ok: true/false` — narrow it with an `if (result.ok)` check, never with `as`.",
      "For exhaustive matching in `formatFetchError`, add a `default` branch that assigns to a `never` variable to get a compile-time safety net."
    ],
    "docs": [
      {
        "title": "TypeScript Handbook — Narrowing",
        "url": "https://www.typescriptlang.org/docs/handbook/2/narrowing.html"
      },
      {
        "title": "TypeScript Handbook — Generics",
        "url": "https://www.typescriptlang.org/docs/handbook/2/generics.html"
      },
      {
        "title": "MDN — Promise.all",
        "url": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/all"
      },
      {
        "title": "TypeScript Handbook — Discriminated Unions",
        "url": "https://www.typescriptlang.org/docs/handbook/2/narrowing.html#discriminated-unions"
      }
    ]
  },
  {
    "date": "2026-03-25",
    "name": "Typed Product Catalog Filter & Sorter",
    "difficulty": "Easy",
    "description": "You're building the browse experience for a small e-commerce storefront. Shoppers can filter products by category, price range, and availability, then sort the results — your engine must validate raw filter inputs and return a fully typed, sorted product list.",
    "snippet": "export type Category = \"electronics\" | \"clothing\" | \"books\" | \"home\" | \"sports\";\n\nexport type Product = {\n  id: string;\n  name: string;\n  category: Category;\n  priceUsd: number;\n  inStock: boolean;\n  rating: number; // 0–5\n};\n\nexport type RawFilterInput = {\n  category?: string;\n  minPrice?: string;\n  maxPrice?: string;\n  inStockOnly?: string; // \"true\" | \"false\" | anything else\n};\n\nexport type ValidatedFilter = {\n  category?: Category;\n  minPrice?: number;\n  maxPrice?: number;\n  inStockOnly?: boolean;\n};\n\nexport type SortField = \"priceUsd\" | \"rating\" | \"name\";\nexport type SortDirection = \"asc\" | \"desc\";\nexport type SortOptions = { field: SortField; direction: SortDirection };\n\nexport type Result<T, E> =\n  | { ok: true; value: T }\n  | { ok: false; errors: E[] };\n\nexport function validateFilter(raw: RawFilterInput): Result<ValidatedFilter, ValidationError> { ... }\nexport function applyFilter(products: Product[], filter: ValidatedFilter): Product[] { ... }\nexport function sortProducts(products: Product[], options: SortOptions): Product[] { ... }",
    "goals": [
      "Implement `validateFilter` to parse a `RawFilterInput` into a `Result<ValidatedFilter, ValidationError>`, collecting all validation errors independently.",
      "Implement `applyFilter` to apply each field of a `ValidatedFilter` as a composable predicate over a `Product[]`, returning a new array.",
      "Implement `sortProducts` to sort a `Product[]` by any `SortField` in either direction, using `localeCompare` for strings and numeric comparison for numbers.",
      "Use the `Result` discriminated union correctly so callers must narrow on `ok` before accessing `value` or `errors`."
    ],
    "hints": [
      "A `Set` or `Array.includes` over the `Category` literal values is the cleanest way to narrow a `string` to `Category` — TypeScript needs the array typed `as const` or compared against a typed tuple.",
      "Collect ALL validation errors into a local array before deciding whether to return `ok: true` or `ok: false` — that way each field is checked independently.",
      "For `sortProducts`, index into the product with `options.field` (e.g. `product[options.field]`) — TypeScript will infer the correct union type from `SortField`, letting you branch on string vs. number without casting."
    ],
    "docs": [
      {
        "title": "TypeScript — Narrowing",
        "url": "https://www.typescriptlang.org/docs/handbook/2/narrowing.html"
      },
      {
        "title": "TypeScript — Discriminated Unions",
        "url": "https://www.typescriptlang.org/docs/handbook/2/narrowing.html#discriminated-unions"
      },
      {
        "title": "TypeScript — Utility Types (keyof, Pick, etc.)",
        "url": "https://www.typescriptlang.org/docs/handbook/utility-types.html"
      },
      {
        "title": "MDN — String.prototype.localeCompare",
        "url": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/localeCompare"
      }
    ]
  },
  {
    "date": "2026-03-26",
    "name": "Typed Job Queue Retry Scheduler",
    "difficulty": "Medium",
    "description": "You're building the background job processing layer for a workflow automation platform. Jobs can succeed, fail with a retryable error, or fail fatally — your scheduler must execute them with typed retry policies, collect per-job outcomes, and surface a structured run report through a `Result<T, E>` type with zero `any`.",
    "snippet": "\n// Core types you must define:\n\ntype Result<T, E> =\n  | { ok: true;  value: T }\n  | { ok: false; error: E };\n\ntype JobError =\n  | { kind: \"retryable\"; message: string; retryAfterMs: number }\n  | { kind: \"fatal\";     message: string; code: string }\n  | { kind: \"timeout\";   message: string; elapsedMs: number };\n\ntype Job<P> = {\n  id:      string;\n  name:    string;\n  payload: P;\n  policy:  RetryPolicy;\n  execute: (payload: P) => Promise<Result<unknown, JobError>>;\n};\n\n// Function signatures you must implement:\n\nasync function scheduleJob<P>(job: Job<P>): Promise<JobOutcome<P>>;\n\nasync function runQueue(jobs: Job<unknown>[]): Promise<RunReport>;\n",
    "goals": [
      "Define the `Result<T, E>`, `JobError`, `RetryPolicy`, `Job<P>`, `JobOutcome<P>`, and `RunReport` types with no `any`.",
      "Implement `scheduleJob<P>` to run a job with per-attempt timeout racing, retry only on `retryable` errors, and a backoff delay between retries.",
      "Implement `runQueue` to fan out all jobs concurrently with `Promise.all` and fold outcomes into a typed `RunReport`.",
      "Narrow the `JobError` discriminated union by `kind` to drive control flow — never use type assertions."
    ],
    "hints": [
      "A `while (attempts < policy.maxAttempts)` loop combined with a `break` on non-retryable errors is the cleanest shape for `scheduleJob`.",
      "Use the provided `withTimeout` helper to race each `execute()` call — its return type is already `Promise<Result<T, JobError>>`, so plug it straight into your loop.",
      "In `runQueue`, derive `succeeded` and `failed` from `outcomes` with a single `reduce` or `filter` — avoid a separate counter variable."
    ],
    "docs": [
      {
        "title": "TypeScript Handbook — Discriminated Unions",
        "url": "https://www.typescriptlang.org/docs/handbook/2/narrowing.html#discriminated-unions"
      },
      {
        "title": "TypeScript Handbook — Generics",
        "url": "https://www.typescriptlang.org/docs/handbook/2/generics.html"
      },
      {
        "title": "MDN — Promise.race()",
        "url": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/race"
      },
      {
        "title": "MDN — Promise.all()",
        "url": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/all"
      }
    ]
  },
  {
    "date": "2026-03-27",
    "name": "Typed Student Grade Book Aggregator",
    "difficulty": "Easy",
    "description": "You're building the reporting module for an online learning platform. Teachers submit raw grade entries for students across multiple subjects, and your aggregator must validate the entries, compute per-student summaries, and assign letter grades — all with fully typed inputs and outputs.",
    "snippet": "/** A score confirmed to be in [0, 100]. */\ntype ValidScore = number & { readonly __brand: \"ValidScore\" };\n\n/** ValidatedEntry — same as RawGradeEntry but score is ValidScore. */\ntype ValidatedEntry = Omit<RawGradeEntry, \"score\"> & { score: ValidScore };\n\ntype LetterGrade = \"A\" | \"B\" | \"C\" | \"D\" | \"F\";\n\ninterface StudentSummary {\n  studentId: string;\n  studentName: string;\n  subjects: string[];       // unique, sorted A→Z\n  averageScore: number;     // rounded to 2 dp\n  letterGrade: LetterGrade;\n}\n\ninterface GradeBookResult {\n  summaries: StudentSummary[];\n  errors: ValidationError[];\n}\n\n// Main function signature:\nfunction aggregateGrades(entries: RawGradeEntry[]): GradeBookResult { ... }",
    "goals": [
      "Define a `ValidScore` branded type and a `ValidatedEntry` mapped type that swaps in the brand without re-listing every field.",
      "Implement `toValidScore` to safely narrow a raw `number` into `ValidScore | null` using a range check — no type assertions.",
      "Implement `toLetterGrade` that accepts only a `ValidScore` parameter and returns the correct `LetterGrade` band.",
      "Implement `aggregateGrades` to validate all entries, group by student, compute sorted subjects and rounded averages, and return a typed `GradeBookResult`."
    ],
    "hints": [
      "For the branded type, intersect `number` with a readonly object literal: `number & { readonly __brand: 'ValidScore' }` — then use an explicit cast only inside `toValidScore` where you've already verified the range.",
      "For `ValidatedEntry`, reach for `Omit<RawGradeEntry, 'score'> & { score: ValidScore }` to surgically replace just the one field.",
      "When computing `averageScore` (a plain `number`) before calling `toLetterGrade`, you'll need to pass it through `toValidScore` first — think about what to do if it somehow returns `null` (hint: a clamped average can't be out of range, but TypeScript doesn't know that)."
    ],
    "docs": [
      {
        "title": "TypeScript Handbook — Branded / Nominal Types",
        "url": "https://www.typescriptlang.org/docs/handbook/2/narrowing.html"
      },
      {
        "title": "TypeScript Handbook — Utility Types (Omit, Pick, etc.)",
        "url": "https://www.typescriptlang.org/docs/handbook/utility-types.html"
      },
      {
        "title": "TypeScript Handbook — Narrowing & Type Guards",
        "url": "https://www.typescriptlang.org/docs/handbook/2/narrowing.html#using-type-predicates"
      },
      {
        "title": "MDN — Array.prototype.reduce (for groupBy aggregation)",
        "url": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/reduce"
      }
    ]
  },
  {
    "date": "2026-03-28",
    "name": "Typed Event-Sourced State Machine",
    "difficulty": "Hard",
    "description": "You're building the order-lifecycle engine for a commerce platform. Orders move through a strict set of states via typed events — your state machine must enforce legal transitions at the type level, fold an event log into the current state, and surface a fully typed `Result<T, E>` for every operation with zero `any`.",
    "snippet": "// Key types and main function signatures\n\ntype OrderState =\n  | { kind: \"Pending\" }\n  | { kind: \"Confirmed\"; confirmedAt: Date }\n  | { kind: \"Shipped\";   confirmedAt: Date; shippedAt: Date; trackingCode: string }\n  | { kind: \"Delivered\"; confirmedAt: Date; shippedAt: Date; trackingCode: string; deliveredAt: Date }\n  | { kind: \"Cancelled\"; cancelledAt: Date; reason: string };\n\ntype OrderEvent =\n  | { id: EventId; occurredAt: Date; type: \"OrderPlaced\" }\n  | { id: EventId; occurredAt: Date; type: \"OrderConfirmed\" }\n  | { id: EventId; occurredAt: Date; type: \"OrderShipped\";   trackingCode: string }\n  | { id: EventId; occurredAt: Date; type: \"OrderDelivered\" }\n  | { id: EventId; occurredAt: Date; type: \"OrderCancelled\"; reason: string };\n\ntype Result<T, E> = { kind: \"Ok\"; value: T } | { kind: \"Err\"; error: E };\n\n// Applies a single event to the current state, enforcing legal transitions\nfunction applyEvent(\n  currentState: OrderState | null,\n  event: OrderEvent\n): Result<OrderState, MachineError> { /* TODO */ }\n\n// Replays an ordered event log and returns the final state or first error\nfunction foldEvents(\n  events: ReadonlyArray<OrderEvent>\n): Result<OrderState, MachineError> { /* TODO */ }\n\n// Narrows a Result to a specific state variant by its `kind` discriminant\nfunction assertState<K extends OrderState[\"kind\"]>(\n  result: Result<OrderState, MachineError>,\n  kind: K\n): StateByKind<K> | null { /* TODO */ }\n",
    "goals": [
      "Define fully typed discriminated unions for `OrderState`, `OrderEvent`, and `MachineError` with the correct structural fields per variant.",
      "Implement `applyEvent` that validates transitions against `LEGAL_TRANSITIONS` and returns a typed `Result<OrderState, MachineError>` with no `any`.",
      "Implement `foldEvents` to sequentially replay an event log, short-circuiting on the first error and returning the final folded state.",
      "Implement `assertState<K>` using the conditional type `StateByKind<K>` to narrow a `Result<OrderState, MachineError>` to a specific state variant without type assertions."
    ],
    "hints": [
      "For `StateByKind<K>`, use `Extract<OrderState, { kind: K }>` — it resolves to exactly the union member whose `kind` matches K.",
      "In `applyEvent`, a `switch` on `event.type` with exhaustive case handling lets TypeScript narrow both the event shape and the expected prior state simultaneously.",
      "The `satisfies` operator on `LEGAL_TRANSITIONS` lets you keep the precise literal types of each array while still enforcing the `LegalTransitions` contract."
    ],
    "docs": [
      {
        "title": "TypeScript Handbook — Discriminated Unions",
        "url": "https://www.typescriptlang.org/docs/handbook/2/narrowing.html#discriminated-unions"
      },
      {
        "title": "TypeScript Handbook — Conditional Types & Extract",
        "url": "https://www.typescriptlang.org/docs/handbook/2/conditional-types.html"
      },
      {
        "title": "TypeScript Handbook — The `satisfies` Operator",
        "url": "https://www.typescriptlang.org/docs/handbook/release-notes/typescript-4-9.html#the-satisfies-operator"
      },
      {
        "title": "TypeScript Handbook — Mapped Types & Record",
        "url": "https://www.typescriptlang.org/docs/handbook/2/mapped-types.html"
      }
    ]
  },
  {
    "date": "2026-03-29",
    "name": "Typed Recipe Ingredient Scaler",
    "difficulty": "Easy",
    "description": "You're building the recipe customization feature for a cooking app. Users can scale any recipe up or down by a multiplier, and your engine must validate raw ingredient inputs, convert between units, and return a fully typed scaled recipe — with zero `any`.",
    "snippet": "// Key types & main function signatures\n\nexport type Multiplier     = number & { readonly __brand: \"Multiplier\" };\nexport type IngredientName = string & { readonly __brand: \"IngredientName\" };\n\nexport type UnitGroup =\n  | { kind: \"volume\"; unit: VolumeUnit }\n  | { kind: \"weight\"; unit: WeightUnit };\n\nexport type Result<T, E> =\n  | { ok: true;  value: T }\n  | { ok: false; error: E };\n\nexport interface RawIngredient { name: unknown; quantity: unknown; unit: unknown; }\nexport interface Ingredient    { name: IngredientName; quantity: number; unitGroup: UnitGroup; }\nexport interface ScaledIngredient extends Ingredient { readonly scaledBy: Multiplier; }\n\n// --- Functions you must implement ---\nexport function parseIngredient(raw: RawIngredient): Result<Ingredient, ValidationError>;\nexport function scaleIngredient(ingredient: Ingredient, multiplier: Multiplier): ScaledIngredient;\nexport function scaleRecipe(rawIngredients: RawIngredient[], rawMultiplier: number): ScaledRecipeResult;",
    "goals": [
      "Define `UnitGroup` as a discriminated union that cleanly separates volume and weight units at the type level.",
      "Implement `parseIngredient` to narrow all `unknown` fields and return a typed `Result<Ingredient, ValidationError>` with ordered validation.",
      "Implement `scaleIngredient` to produce a `ScaledIngredient` that records the branded `Multiplier` used.",
      "Implement `scaleRecipe` to orchestrate validation and scaling across an array of raw inputs, collecting both successes and indexed failures into a `ScaledRecipeResult`."
    ],
    "hints": [
      "To narrow `unknown` to a specific type, use `typeof value === 'string'` or `typeof value === 'number'` guards — TypeScript will narrow the type inside the `if` block.",
      "A `Set<VolumeUnit>` with a `.has()` check is a clean way to narrow an `unknown` unit string into a `VolumeUnit` — but you'll need to first confirm it's a `string`.",
      "Branded types like `Multiplier` can only be created via a trusted constructor (like `makeMultiplier`); call it inside `scaleRecipe` to avoid unsafe casts."
    ],
    "docs": [
      {
        "title": "TypeScript Handbook — Narrowing",
        "url": "https://www.typescriptlang.org/docs/handbook/2/narrowing.html"
      },
      {
        "title": "TypeScript Handbook — Discriminated Unions",
        "url": "https://www.typescriptlang.org/docs/handbook/2/narrowing.html#discriminated-unions"
      },
      {
        "title": "TypeScript Handbook — Branded / Opaque Types (Enums & Literal Types)",
        "url": "https://www.typescriptlang.org/docs/handbook/2/template-literal-types.html"
      },
      {
        "title": "MDN — Set.prototype.has()",
        "url": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set/has"
      }
    ]
  },
  {
    "date": "2026-03-30",
    "name": "Typed API Response Paginator",
    "difficulty": "Medium",
    "description": "You're building the data-fetching layer for an analytics dashboard that consumes a paginated REST API. The client must fetch pages sequentially or in parallel up to a concurrency limit, validate each raw response at runtime, and aggregate all records into a typed `Result<T, E>` — with clean handling for partial failures.",
    "snippet": "// Key types & main function signature\n\nexport type Result<T, E> =\n  | { ok: true;  value: T }\n  | { ok: false; error: E };\n\nexport type PaginatorError =\n  | { kind: \"validation\"; page: number; reason: string }\n  | { kind: \"fetch\";      page: number; reason: string }\n  | { kind: \"partial\";   errors: PaginatorError[]; records: AnalyticsRecord[] };\n\nexport interface PaginatorConfig {\n  totalPages:  number;\n  concurrency: number; // max in-flight fetches\n}\n\n/** Injected fetcher — never throws, returns Result. */\nexport type FetchPage = (page: number) => Promise<Result<RawEnvelope, string>>;\n\n/** Concurrency-limited task runner — preserves result order. */\nexport async function withConcurrency<T>(\n  tasks: ReadonlyArray<() => Promise<T>>,\n  limit: number\n): Promise<T[]> { /* TODO */ }\n\n/** Fetch, validate, and aggregate all pages into a single Result. */\nexport async function paginateAll(\n  fetchPage: FetchPage,\n  config: PaginatorConfig\n): Promise<Result<AnalyticsRecord[], PaginatorError>> { /* TODO */ }\n",
    "goals": [
      "Implement `validateRecord` and `validateEnvelope` to narrow `Record<string, unknown>` into fully typed domain objects, returning a `Result<T, string>` on the first failing field.",
      "Implement `withConcurrency<T>` to run an array of async tasks with at most `limit` concurrent executions while preserving the original result order.",
      "Implement `paginateAll` to fetch all pages via the injected `FetchPage`, using `withConcurrency` to respect the concurrency limit, and return a success or partial-failure `Result`.",
      "Ensure the final success `value` (and the partial `records`) are sorted ascending by `timestamp` string."
    ],
    "hints": [
      "For `withConcurrency`, consider processing tasks in fixed-size batches using `Promise.all` — slice the task array into chunks of size `limit` and await each chunk sequentially.",
      "In `validateRecord`, use `typeof` guards and `Array.isArray` to narrow each field from `unknown` before assigning — the compiler will reject assignments without explicit narrowing.",
      "In `paginateAll`, collect both errors and valid records in the same pass so you can return a `{ kind: 'partial' }` error that still carries the successfully parsed records (R4e)."
    ],
    "docs": [
      {
        "title": "TypeScript — Narrowing",
        "url": "https://www.typescriptlang.org/docs/handbook/2/narrowing.html"
      },
      {
        "title": "TypeScript — Generics",
        "url": "https://www.typescriptlang.org/docs/handbook/2/generics.html"
      },
      {
        "title": "MDN — Promise.all",
        "url": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/all"
      },
      {
        "title": "TypeScript — Utility Types",
        "url": "https://www.typescriptlang.org/docs/handbook/utility-types.html"
      }
    ]
  },
  {
    "date": "2026-03-31",
    "name": "Typed Product Inventory Filter & Sorter",
    "difficulty": "Easy",
    "description": "You're building the catalog browsing feature for an e-commerce storefront. Shoppers can filter products by category, availability, and price range, then sort the results — your engine must validate raw catalog inputs and return a fully typed filtered and sorted result with zero `any`.",
    "snippet": "// Key types and main function signature\n\ntype Category = \"electronics\" | \"clothing\" | \"food\" | \"books\" | \"toys\";\n\ninterface RawProduct { id: unknown; name: unknown; category: unknown; priceUsd: unknown; inStock: unknown; }\ninterface Product    { id: string;  name: string;  category: Category; priceUsd: number;  inStock: boolean; }\n\ntype ValidationOk<T> = { ok: true;  value: T };\ntype ValidationErr   = { ok: false; field: string; reason: string };\ntype ValidationResult<T> = ValidationOk<T> | ValidationErr;\n\ninterface FilterOptions { categories?: Category[]; minPrice?: number; maxPrice?: number; onlyInStock?: boolean; }\ninterface SortOptions   { field: \"priceUsd\" | \"name\"; direction: \"asc\" | \"desc\"; }\ninterface CatalogResult { products: Product[]; errors: Array<{ rawId: unknown; field: string; reason: string }>; }\n\n// Orchestrates validate → filter → sort in one typed pipeline\ndeclare function processCatalog(\n  rawProducts: RawProduct[],\n  filter: FilterOptions,\n  sort: SortOptions\n): CatalogResult;",
    "goals": [
      "Implement `validateProduct` to narrow each `unknown` field of a `RawProduct` into a fully-typed `Product`, returning a discriminated-union `ValidationResult<Product>`.",
      "Implement `filterProducts` to apply up to four independent, ANDed filter conditions from `FilterOptions` without mutating the input array.",
      "Implement `sortProducts` to sort by `priceUsd` or `name` in either direction, breaking ties by `id` ascending, without mutating the input array.",
      "Wire all three functions together in `processCatalog`, collecting validation errors and returning a complete `CatalogResult`."
    ],
    "hints": [
      "For `validateProduct`, use `typeof` guards and `Array.includes` to narrow each `unknown` field — define a readonly tuple of valid categories so TypeScript can infer the `Category` type from `.includes()`.",
      "For `sortProducts`, `Array.prototype.slice()` (or spread) gives you a new array to sort safely; build a comparator that checks the primary field first, then falls back to `id`.",
      "In `processCatalog`, a single `reduce` (or a `forEach` with two accumulators) lets you split the validated results into the `products` and `errors` arrays in one pass."
    ],
    "docs": [
      {
        "title": "TypeScript Handbook — Narrowing",
        "url": "https://www.typescriptlang.org/docs/handbook/2/narrowing.html"
      },
      {
        "title": "TypeScript Handbook — Discriminated Unions",
        "url": "https://www.typescriptlang.org/docs/handbook/2/narrowing.html#discriminated-unions"
      },
      {
        "title": "MDN — Array.prototype.sort()",
        "url": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort"
      },
      {
        "title": "TypeScript Handbook — Utility Types",
        "url": "https://www.typescriptlang.org/docs/handbook/utility-types.html"
      }
    ]
  },
  {
    "date": "2026-04-01",
    "name": "Typed Notification Dispatcher",
    "difficulty": "Medium",
    "description": "You're building the notification service for a SaaS platform. The system must dispatch typed notifications across multiple channels (email, SMS, push), fan out deliveries concurrently with a configurable limit, and collect a fully typed per-channel Result for every recipient — with zero `any`.",
    "snippet": "// Key types & main function signature\n\ntype Brand<T, B extends string> = T & { readonly __brand: B };\ntype RecipientId   = Brand<string, \"RecipientId\">;\ntype NotificationId = Brand<string, \"NotificationId\">;\n\ntype Result<T, E> =\n  | { readonly ok: true;  readonly value: T }\n  | { readonly ok: false; readonly error: E };\n\ntype Notification = EmailNotification | SmsNotification | PushNotification;\n\n// Mapped type — your job to fill in the body:\ntype ChannelSenders = {\n  [K in Notification[\"channel\"]]: ChannelSender<Extract<Notification, { channel: K }>>;\n};\n\ntype DispatchConfig = {\n  readonly concurrencyLimit: number;\n  readonly senders: ChannelSenders;\n};\n\n// Fan out raw payloads → validate → dispatch (concurrency-limited) → summary\nasync function fanOutDispatch(\n  rawPayloads: readonly unknown[],\n  config: DispatchConfig\n): Promise<DispatchSummary>;\n",
    "goals": [
      "Define the three-channel discriminated union `Notification` type with branded `id` and `recipientId` fields.",
      "Implement `validateNotification` to narrow `unknown → Result<Notification, ValidationError>` with per-field checks.",
      "Implement `dispatch` using the correct `ChannelSender` selected via a type-safe switch on `notification.channel`.",
      "Implement `fanOutDispatch` to validate all payloads, fan out dispatches in batches of `config.concurrencyLimit`, and return a fully typed `DispatchSummary`."
    ],
    "hints": [
      "For `ChannelSenders`, use a mapped type `{ [K in Notification[\"channel\"]]: ChannelSender<Extract<Notification, { channel: K }>> }` — this lets TypeScript infer the exact sub-type per key.",
      "In `fanOutDispatch`, slice the validated notifications into chunks of size `concurrencyLimit` and `await Promise.all(chunk.map(...))` per chunk to honour the limit.",
      "Use a `switch (notification.channel)` with a final `default` branch that calls a `(c: never) => never` helper — this gives you exhaustiveness checking for free."
    ],
    "docs": [
      {
        "title": "TypeScript – Discriminated Unions",
        "url": "https://www.typescriptlang.org/docs/handbook/2/narrowing.html#discriminated-unions"
      },
      {
        "title": "TypeScript – Mapped Types",
        "url": "https://www.typescriptlang.org/docs/handbook/2/mapped-types.html"
      },
      {
        "title": "TypeScript – Conditional Types & Extract",
        "url": "https://www.typescriptlang.org/docs/handbook/2/conditional-types.html"
      },
      {
        "title": "MDN – Promise.all",
        "url": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/all"
      }
    ]
  },
  {
    "date": "2026-04-04",
    "name": "Typed User Profile Merger",
    "difficulty": "Easy",
    "description": "You're building the account-settings feature for a SaaS app. When a user submits a partial profile update, your engine must validate the raw incoming fields, deep-merge them onto the existing profile, and return a fully typed `Result<T, E>` — with zero `any`.",
    "snippet": "/** Supported social-link platforms. */\ntype Platform = \"github\" | \"twitter\" | \"linkedin\";\n\ninterface SocialLink { platform: Platform; url: string; }\n\ninterface UserProfile {\n  id: string; displayName: string; email: string;\n  bio: string; avatarUrl: string; socials: SocialLink[];\n  updatedAt: string; // system-managed\n}\n\n// All user-editable fields are optional; id & updatedAt are excluded\ntype ProfileUpdate = Omit<Partial<UserProfile>, \"id\" | \"updatedAt\">;\n\ntype Result<T, E> = { ok: true; value: T } | { ok: false; error: E };\n\ntype MergeError =\n  | { kind: \"INVALID_EMAIL\";    provided: string }\n  | { kind: \"INVALID_URL\";      field: string; provided: string }\n  | { kind: \"UNKNOWN_PLATFORM\"; provided: string };\n\ndeclare function mergeProfile(\n  existing: UserProfile,\n  update: ProfileUpdate\n): Result<UserProfile, MergeError>;\n",
    "goals": [
      "Define `ProfileUpdate` as a mapped/utility type that makes all user-editable `UserProfile` fields optional while excluding `id` and `updatedAt`.",
      "Define `MergeError` as a discriminated union with three `kind` variants, each carrying appropriate detail fields.",
      "Implement the three type-predicate validators (`validateEmail`, `validateHttpsUrl`, `validatePlatform`) with correct narrowing signatures.",
      "Implement `mergeProfile` to validate all incoming fields in order, return typed `MergeError` on the first failure, and return a new immutable `UserProfile` with a refreshed `updatedAt` on success."
    ],
    "hints": [
      "For `ProfileUpdate`, you only need two built-in utility types composed in a single expression — think about which one makes fields optional and which one removes fields.",
      "A type predicate has the return type `value is SomeType`; your `validatePlatform` predicate should narrow `string` all the way down to the `Platform` union.",
      "In `mergeProfile`, validate fields in order and `return` early on the first error — you never need a nested `if/else` tree."
    ],
    "docs": [
      {
        "title": "TypeScript Utility Types (Partial, Omit, Pick)",
        "url": "https://www.typescriptlang.org/docs/handbook/utility-types.html"
      },
      {
        "title": "TypeScript Narrowing — Type Predicates",
        "url": "https://www.typescriptlang.org/docs/handbook/2/narrowing.html#using-type-predicates"
      },
      {
        "title": "TypeScript Discriminated Unions",
        "url": "https://www.typescriptlang.org/docs/handbook/2/narrowing.html#discriminated-unions"
      },
      {
        "title": "TypeScript Generics",
        "url": "https://www.typescriptlang.org/docs/handbook/2/generics.html"
      }
    ]
  },
  {
    "date": "2026-04-04",
    "name": "Typed Workflow State Machine",
    "difficulty": "Hard",
    "description": "You're building the order-fulfillment engine for a logistics platform. Every order moves through a strict lifecycle — and your state machine must enforce legal transitions at the type level, accumulate a typed audit log, and return exhaustively-matched `Result<T, E>` outcomes, all with zero `any`.",
    "snippet": "// Key types and main function signatures\n\nexport type StateName =\n  | \"pending\" | \"confirmed\" | \"picking\"\n  | \"packed\"  | \"shipped\"  | \"delivered\" | \"cancelled\";\n\n// TODO 1 — build this from StatePayloadMap\nexport type OrderState =\n  | { kind: \"pending\";   orderId: string; placedAt: string }\n  | { kind: \"confirmed\"; orderId: string; confirmedAt: string; warehouseId: string }\n  | /* ... all 7 variants */ never;\n\n// TODO 2 — phantom-branded transition\nexport type Transition<From extends StateName, To extends StateName> = never;\n\n// TODO 3 — registry validated with `satisfies`\nexport const TRANSITIONS = { /* \"pending->confirmed\": ..., ... */ } as const;\n\nexport function applyTransition(\n  ctx: MachineContext,\n  input: TransitionInput\n): Result<MachineContext, TransitionError>;\n\nexport function runWorkflow(\n  initialPayload: { orderId: string; placedAt: string },\n  transitions: readonly TransitionInput[]\n): Result<MachineContext, TransitionError>;\n\nexport function summariseMachine(ctx: MachineContext): WorkflowSummary;\n",
    "goals": [
      "Define `OrderState` as a discriminated union where each variant's payload is derived from `StatePayloadMap` and the `kind` field is the literal `StateName` key.",
      "Brand `Transition<From, To>` with phantom type parameters so that transitions between incompatible states are rejected at compile time, and register all legal transitions using `satisfies`.",
      "Implement `applyTransition` to validate the target state, check the TRANSITIONS registry, verify all required payload fields are present, and return a typed `Result<MachineContext, TransitionError>`.",
      "Implement `runWorkflow` and `summariseMachine` — the former short-circuits on the first error, the latter produces a `WorkflowSummary` using a single `reduce` pass with no intermediate arrays."
    ],
    "hints": [
      "For the `OrderState` union, try using a mapped type over `StatePayloadMap` and then `[StateName][number]` to distribute it into a flat union.",
      "A phantom type is just a structural type that includes a field (or intersection) whose type encodes `From` and `To` but is never actually present at runtime — look at how `{ readonly _brand: readonly [From, To] }` can be intersected.",
      "In `applyTransition`, build a `REQUIRED_FIELDS` lookup (keyed by `StateName`) to know which payload keys to check — you can derive it from `StatePayloadMap` at the type level and mirror it as a runtime constant."
    ],
    "docs": [
      {
        "title": "TypeScript — Discriminated Unions",
        "url": "https://www.typescriptlang.org/docs/handbook/2/narrowing.html#discriminated-unions"
      },
      {
        "title": "TypeScript — satisfies operator",
        "url": "https://www.typescriptlang.org/docs/handbook/release-notes/typescript-4-9.html#the-satisfies-operator"
      },
      {
        "title": "TypeScript — Template Literal Types",
        "url": "https://www.typescriptlang.org/docs/handbook/2/template-literal-types.html"
      },
      {
        "title": "TypeScript — Mapped Types",
        "url": "https://www.typescriptlang.org/docs/handbook/2/mapped-types.html"
      }
    ]
  },
  {
    "date": "2026-04-05",
    "name": "Typed Event Stream Aggregator",
    "difficulty": "Medium",
    "description": "You're building the real-time analytics engine for a live-streaming platform. Raw events arrive as unknown JSON blobs from multiple sources; your engine must validate them, fan out processing concurrently with a limit, and aggregate per-stream statistics into a fully typed report — with zero `any`.",
    "snippet": "// Core types & main function signature\n\ntype Brand<T, B extends string> = T & { readonly __brand: B };\n\ntype EventId     = Brand<string, \"EventId\">;\ntype StreamId    = Brand<string, \"StreamId\">;\ntype TimestampMs = Brand<number, \"TimestampMs\">;\ntype EventKind   = \"view\" | \"like\" | \"comment\" | \"share\" | \"donation\";\n\ninterface StreamEvent {\n  id: EventId;\n  streamId: StreamId;\n  kind: EventKind;\n  value: number;\n  timestamp: TimestampMs;\n}\n\ntype Result<T, E> =\n  | { ok: true;  value: T }\n  | { ok: false; error: E };\n\ntype EventProcessor = (event: StreamEvent) => Promise<void>;\n\n// --- implement this ---\nasync function aggregateEvents(\n  rawEvents: RawEvent[],\n  processor: EventProcessor,\n  concurrencyLimit?: number,\n): Promise<AggregationReport> { /* TODO */ }",
    "goals": [
      "Declare `Brand<T, B>` and apply it to `EventId`, `StreamId`, and `TimestampMs` — then use those branded types throughout `StreamEvent` and `StreamStats`.",
      "Implement `validateEvent` using a `Result<T, E>` discriminated union and user-defined type guards to narrow every `unknown` field without `as` or `any`.",
      "Implement `aggregateEvents` to fan out `EventProcessor` calls concurrently up to `concurrencyLimit`, then aggregate per-stream `StreamStats` (counts, totals, firstSeen/lastSeen) into an `AggregationReport`.",
      "Implement `lookupStream` to convert a plain `string` to a branded `StreamId` via a type guard and return `Result<StreamStats, string>` — no non-null assertions."
    ],
    "hints": [
      "A type guard of the form `function isEventId(x: string): x is EventId` lets you refine a plain string into a branded type without `as` — apply the same pattern for `StreamId` and `TimestampMs`.",
      "For `Result<T, E>`, a discriminated union on a boolean `ok` field (`{ ok: true; value: T } | { ok: false; error: E }`) gives you exhaustive narrowing with a simple `if (result.ok)` check.",
      "To respect `concurrencyLimit` without a library, slice the validated events array into chunks of that size and `await Promise.all(chunk.map(processor))` — iterate chunk by chunk sequentially."
    ],
    "docs": [
      {
        "title": "TypeScript Handbook — Narrowing & Type Guards",
        "url": "https://www.typescriptlang.org/docs/handbook/2/narrowing.html"
      },
      {
        "title": "TypeScript Handbook — Generics",
        "url": "https://www.typescriptlang.org/docs/handbook/2/generics.html"
      },
      {
        "title": "MDN — Promise.all",
        "url": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/all"
      },
      {
        "title": "TypeScript Handbook — Utility Types (Record, Pick, etc.)",
        "url": "https://www.typescriptlang.org/docs/handbook/utility-types.html"
      }
    ]
  },
  {
    "date": "2026-04-06",
    "name": "Typed Contact Book Grouper",
    "difficulty": "Easy",
    "description": "You're building the \"All Contacts\" view for a mobile address book app. Raw contact entries arrive from storage as unknown blobs; your engine must validate them, group them by the first letter of their last name, and return a fully typed alphabetical index — with zero `any`.",
    "snippet": "/** A validated, fully-typed contact record. */\ninterface Contact {\n  id: string;\n  firstName: string;\n  lastName: string;\n  email: string;\n  phone?: string;\n  birthday?: string;\n  tags: string[];\n}\n\ntype ValidationError =\n  | { kind: \"missing_field\"; field: string }\n  | { kind: \"wrong_type\"; field: string; expected: string }\n  | { kind: \"invalid_email\"; value: string };\n\ntype Result<T, E> = { ok: true; value: T } | { ok: false; error: E };\n\n// TODO: define AlphaKey  →  \"A\" | \"B\" | … | \"Z\" | \"#\"\ntype AlphaKey = TODO;\n\n// TODO: define ContactIndex  →  Record<AlphaKey, Contact[]>\ntype ContactIndex = TODO;\n\n// Validate a raw unknown blob into a typed Contact\nfunction validateContact(raw: unknown): Result<Contact, ValidationError> { … }\n\n// Map a Contact to its alphabetical bucket key\nfunction getAlphaKey(contact: Contact): AlphaKey { … }\n\n// Build a complete A–Z + \"#\" index from an array of raw blobs\nfunction buildContactIndex(raws: unknown[]): ContactIndex { … }",
    "goals": [
      "Define `AlphaKey` as a union of all 26 uppercase letter strings plus \"#\", and `ContactIndex` as a `Record<AlphaKey, Contact[]>`.",
      "Implement `validateContact` to narrow an `unknown` blob into a typed `Contact`, returning a discriminated `Result<Contact, ValidationError>` with the first error encountered.",
      "Implement `getAlphaKey` to map a contact's last name to the correct `AlphaKey` bucket (A–Z or \"#\").",
      "Implement `buildContactIndex` so every one of the 27 keys is always present, invalid entries are silently skipped, and each bucket is sorted by `lastName` then `firstName`."
    ],
    "hints": [
      "For `AlphaKey`, you can write it as an explicit union `\"A\" | \"B\" | ... | \"Z\" | \"#\"` — or use a mapped type over a tuple of letters with `infer` if you want a stretch challenge.",
      "In `validateContact`, narrow `raw` step-by-step: first check `typeof raw === 'object' && raw !== null`, then use `'id' in raw` before accessing each field — TypeScript will track the narrowed type for you.",
      "To guarantee all 27 keys exist in `buildContactIndex`, initialise the accumulator with `Object.fromEntries(expectedKeys.map(k => [k, []]))` and cast it with `satisfies ContactIndex` rather than `as`."
    ],
    "docs": [
      {
        "title": "TypeScript Handbook — Narrowing",
        "url": "https://www.typescriptlang.org/docs/handbook/2/narrowing.html"
      },
      {
        "title": "TypeScript Handbook — Template Literal Types",
        "url": "https://www.typescriptlang.org/docs/handbook/2/template-literal-types.html"
      },
      {
        "title": "TypeScript Handbook — Utility Types (Record)",
        "url": "https://www.typescriptlang.org/docs/handbook/utility-types.html#recordkeys-type"
      },
      {
        "title": "TypeScript 4.9 — satisfies operator",
        "url": "https://www.typescriptlang.org/docs/handbook/release-notes/typescript-4-9.html#the-satisfies-operator"
      }
    ]
  },
  {
    "date": "2026-04-07",
    "name": "Typed Query Plan Optimizer",
    "difficulty": "Hard",
    "description": "You're building the query execution layer for an in-browser analytics engine. Raw query descriptors arrive as unknown JSON; your optimizer must validate them, build a typed expression tree, walk it with a recursive visitor, and return a fully typed execution plan with cost estimates — with zero `any`.",
    "snippet": "\n// Core types and main entry point\n\nexport type Expr =\n  | { kind: \"literal\"; value: string | number | boolean | null }\n  | { kind: \"column\";  table: string; name: string }\n  | { kind: \"binary\";  op: BinaryOp; left: Expr; right: Expr }\n  | { kind: \"agg\";     fn: AggFn;    source: ColumnRef }\n  | { kind: \"case\";    whens: ReadonlyArray<{ when: Expr; then: Expr }>; else: Expr };\n\nexport type QueryNode =\n  | { op: \"scan\";    table: string; alias: string }\n  | { op: \"filter\";  predicate: Expr; child: QueryNode }\n  | { op: \"project\"; outputs: ReadonlyArray<{ alias: string; expr: Expr }>; child: QueryNode }\n  | { op: \"join\";    condition: Expr; left: QueryNode; right: QueryNode }\n  | { op: \"agg\";     groupBy: ReadonlyArray<ColumnRef>; aggregates: ReadonlyArray<{ alias: string; expr: AggExpr }>; child: QueryNode };\n\nexport interface ExprVisitor<R> {\n  visitLiteral(e: LiteralExpr): R;\n  visitColumn (e: ColumnRef):   R;\n  visitBinary (e: BinaryExpr):  R;\n  visitAgg    (e: AggExpr):     R;\n  visitCase   (e: CaseExpr):    R;\n}\n\n// Main entry point — parse, plan, and cost an unknown query descriptor\nexport function optimize(raw: unknown): Result<ExecutionPlan, OptimizerError>;\n",
    "goals": [
      "Define the `Expr` and `QueryNode` discriminated union types and the generic `ExprVisitor<R>` interface.",
      "Implement `walkExpr` with an exhaustive switch so TypeScript catches any missing branch at compile time.",
      "Implement `parseExpr` and `parseQueryNode` to safely validate unknown blobs into fully typed trees, returning `Result<T, ParseError>`.",
      "Implement `estimateRows`, `buildPlan`, and the top-level `optimize` function, propagating errors and accumulating large-table warnings correctly."
    ],
    "hints": [
      "Use a `switch (expr.kind)` with a `default: satisfies never` (or an exhaustive helper) to guarantee every Expr variant is handled in `walkExpr`.",
      "In `parseExpr` and `parseQueryNode`, narrow `unknown` step-by-step: check `typeof`, then `'kind' in raw`, then check specific string values before casting to the target type.",
      "The `totalCost` in `optimize` is the sum of `estimatedRows` across every node in the `PlanNode` tree — write a small private recursive helper that mirrors the structure of `PlanNode`."
    ],
    "docs": [
      {
        "title": "TypeScript Handbook — Narrowing",
        "url": "https://www.typescriptlang.org/docs/handbook/2/narrowing.html"
      },
      {
        "title": "TypeScript Handbook — Discriminated Unions",
        "url": "https://www.typescriptlang.org/docs/handbook/typescript-in-5-minutes-func.html#discriminated-unions"
      },
      {
        "title": "TypeScript Handbook — Generics",
        "url": "https://www.typescriptlang.org/docs/handbook/2/generics.html"
      },
      {
        "title": "TypeScript 5.x — `satisfies` operator",
        "url": "https://www.typescriptlang.org/docs/handbook/release-notes/typescript-4-9.html#the-satisfies-operator"
      }
    ]
  },
  {
    "date": "2026-04-08",
    "name": "Typed Shopping Cart Summarizer",
    "difficulty": "Easy",
    "description": "You're building the checkout screen for an e-commerce app. Raw cart items arrive from local storage as unknown blobs; your engine must validate them, apply typed discount rules, and return a fully typed order summary — with zero `any`.",
    "snippet": "// Key types & main function signature\n\ntype Category = \"electronics\" | \"clothing\" | \"food\" | \"books\";\n\ninterface CartItem {\n  id: string; name: string; category: Category;\n  priceUsd: number; quantity: number;\n}\n\ntype Discount =\n  | { kind: \"flat\";           amountUsd: number }\n  | { kind: \"percent\";        percent: number   }\n  | { kind: \"buyNGetOneFree\"; category: Category; n: number };\n\ntype Result<T, E> = { ok: true; value: T } | { ok: false; error: E };\n\ninterface OrderSummary {\n  lines: SummaryLine[];\n  subtotalUsd: number;\n  discountAmountUsd: number;\n  totalUsd: number;\n  itemCount: number;\n}\n\n// Validate one unknown blob → CartItem\ndeclare function validateCartItem(raw: unknown): Result<CartItem, string>;\n\n// Compute total discount across all discount rules\ndeclare function calculateDiscount(\n  items: CartItem[], subtotal: number, discounts: Discount[]\n): number;\n\n// Full pipeline: validate → build lines → apply discounts → summarize\ndeclare function summarizeCart(\n  rawItems: unknown[], discounts: Discount[]\n): Result<OrderSummary, CartValidationError>;",
    "goals": [
      "Implement `validateCartItem` to safely narrow an `unknown` blob into a fully typed `CartItem`, returning a `Result<CartItem, string>` on any validation failure.",
      "Implement `calculateDiscount` to exhaustively handle all three `Discount` variants — including the `buyNGetOneFree` per-category logic — and clamp the result to the subtotal.",
      "Implement `summarizeCart` to orchestrate validation, line building, and discount application, returning a `Result<OrderSummary, CartValidationError>` with the correct error index on the first invalid item.",
      "Ensure all discriminated-union branches are exhaustively matched and no `any` or `as` type assertions are used anywhere."
    ],
    "hints": [
      "Use a `switch (discount.kind)` with all three branches — TypeScript will narrow the type inside each case automatically.",
      "To check that a value belongs to the `Category` union at runtime, call `VALID_CATEGORIES.has(value as Category)` — but first confirm `typeof value === 'string'` so strict mode is satisfied without a raw cast.",
      "For `buyNGetOneFree`, filter `items` by `category`, then use `Math.floor(totalQty / (n + 1))` and `Math.min(...prices)` to compute the free-item value."
    ],
    "docs": [
      {
        "title": "TypeScript – Narrowing",
        "url": "https://www.typescriptlang.org/docs/handbook/2/narrowing.html"
      },
      {
        "title": "TypeScript – Discriminated Unions",
        "url": "https://www.typescriptlang.org/docs/handbook/2/narrowing.html#discriminated-unions"
      },
      {
        "title": "TypeScript – Utility Types (Pick, Omit, Record…)",
        "url": "https://www.typescriptlang.org/docs/handbook/utility-types.html"
      },
      {
        "title": "MDN – Array.prototype.reduce()",
        "url": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/reduce"
      }
    ]
  },
  {
    "date": "2026-04-09",
    "name": "Typed API Pagination Crawler",
    "difficulty": "Medium",
    "description": "You're building the data-sync layer for a SaaS dashboard that must pull all records from a paginated REST API. Pages arrive as unknown JSON; your crawler must validate each page, fetch all pages concurrently up to a limit, and aggregate the results into a fully typed report — with zero `any`.",
    "snippet": "// Key types & main function signature\n\nexport type ProductCategory = \"electronics\" | \"clothing\" | \"food\" | \"books\";\n\nexport interface Product {\n  id: string; name: string;\n  category: ProductCategory; priceUsd: number; inStock: boolean;\n}\n\nexport type Ok<T>  = { ok: true;  value: T };\nexport type Err<E> = { ok: false; error: E };\nexport type Result<T, E> = Ok<T> | Err<E>;\n\nexport type CrawlError =\n  | { kind: \"network\";    message: string }\n  | { kind: \"validation\"; page: number; message: string }\n  | { kind: \"timeout\";    page: number };\n\nexport type CategoryReport = Record<ProductCategory, CategoryStats>;\n\nexport interface CrawlReport {\n  totalProducts: number; totalPages: number;\n  byCategory: CategoryReport; errors: CrawlError[];\n}\n\nexport type PageFetcher = (page: number) => Promise<unknown>;\n\nexport async function crawlAllPages(\n  fetcher: PageFetcher,\n  concurrencyLimit: number = 3\n): Promise<Result<CrawlReport, CrawlError>> { /* TODO */ }\n",
    "goals": [
      "Implement `isProductCategory`, `validateProduct`, and `validateRawPage` as strict runtime type guards that narrow `unknown` to typed domain values.",
      "Implement `withConcurrencyLimit<T>` to run async tasks in parallel up to a fixed concurrency cap while preserving result order.",
      "Implement `crawlAllPages` to discover total pages from page 1, fetch remaining pages concurrently, and aggregate all valid products into a `CrawlReport` keyed by all four `ProductCategory` values.",
      "Surface every failure — network rejections and page validation errors — as typed `CrawlError` entries inside `CrawlReport.errors`, never as thrown exceptions."
    ],
    "hints": [
      "A `Record<ProductCategory, CategoryStats>` must include all four keys — initialise them all to `{ count: 0, totalValueUsd: 0, inStockCount: 0 }` before iterating products.",
      "For `withConcurrencyLimit`, maintain a running count of active promises and a queue index; use a recursive 'slot' pattern rather than `Promise.all` on all tasks at once.",
      "In `validateProduct` and `validateRawPage`, narrow `unknown` step-by-step with `typeof` and `Array.isArray` checks — the compiler will track each narrowing for you without any assertions."
    ],
    "docs": [
      {
        "title": "TypeScript — Narrowing",
        "url": "https://www.typescriptlang.org/docs/handbook/2/narrowing.html"
      },
      {
        "title": "TypeScript — Utility Types (Record, Pick, Omit…)",
        "url": "https://www.typescriptlang.org/docs/handbook/utility-types.html"
      },
      {
        "title": "MDN — Promise.allSettled",
        "url": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/allSettled"
      },
      {
        "title": "TypeScript — Generics",
        "url": "https://www.typescriptlang.org/docs/handbook/2/generics.html"
      }
    ]
  },
  {
    "date": "2026-04-10",
    "name": "Typed Task Queue Scheduler",
    "difficulty": "Easy",
    "description": "You're building the background job runner for a productivity app. Raw task definitions arrive from a local database as unknown blobs; your scheduler must validate them, sort them by priority and deadline, and return a fully typed execution plan — with zero `any`.",
    "snippet": "\n// Key types and main function signature\n\nexport type Priority = \"low\" | \"medium\" | \"high\";\n\nexport interface Task {\n  id: string;\n  title: string;\n  priority: Priority;\n  deadline: string;         // ISO-8601 e.g. \"2026-04-15\"\n  estimatedMinutes: number; // positive integer\n}\n\nexport type Result<T, E> =\n  | { ok: true;  value: T }\n  | { ok: false; error: E };\n\nexport type ValidationError =\n  | { kind: \"missing_field\";  field: string }\n  | { kind: \"invalid_type\";   field: string; expected: string }\n  | { kind: \"invalid_value\";  field: string; message: string };\n\nexport type ScheduleRank = number & { readonly __brand: \"ScheduleRank\" };\n\nexport interface ExecutionPlan {\n  scheduled: { task: Task; rank: ScheduleRank }[];\n  totalEstimatedMinutes: number;\n  generatedAt: string;\n}\n\n// Entry point — validate, rank, sort, and plan\nexport function scheduleTasks(\n  rawTasks: unknown[],\n  now?: string\n): ExecutionPlan { /* TODO */ }\n",
    "goals": [
      "Define PRIORITY_WEIGHTS using the `satisfies` operator so every Priority key is present and all values are numbers.",
      "Implement `validateTask` to safely narrow `unknown` → `Result<Task, ValidationError>`, returning the first validation error found.",
      "Implement `computeRank` to produce a branded `ScheduleRank` using the priority weight formula.",
      "Implement `scheduleTasks` to validate, rank, sort, re-number, and aggregate all valid tasks into a typed `ExecutionPlan`."
    ],
    "hints": [
      "For `validateTask`, check `typeof raw === 'object' && raw !== null` first, then use `'field' in raw` guards to safely access each property.",
      "The `satisfies` operator lets you keep a concrete literal type while still checking the shape — put it right after the object literal: `{ ... } satisfies Record<Priority, number>`.",
      "To brand a plain number as `ScheduleRank`, the one allowed cast site is the return of `computeRank`: `return computedNumber as ScheduleRank`."
    ],
    "docs": [
      {
        "title": "TypeScript — satisfies operator",
        "url": "https://www.typescriptlang.org/docs/handbook/release-notes/typescript-4-9.html#the-satisfies-operator"
      },
      {
        "title": "TypeScript — Narrowing",
        "url": "https://www.typescriptlang.org/docs/handbook/2/narrowing.html"
      },
      {
        "title": "TypeScript — Utility Types (Record, Pick, Omit…)",
        "url": "https://www.typescriptlang.org/docs/handbook/utility-types.html"
      },
      {
        "title": "TypeScript — Branded / Nominal Types pattern",
        "url": "https://www.typescriptlang.org/play#example/nominal-typing"
      }
    ]
  },
  {
    "date": "2026-04-11",
    "name": "Typed Event Sourcing Ledger",
    "difficulty": "Hard",
    "description": "You're building the audit-log replay engine for a fintech platform. Raw domain events arrive as unknown JSON streams; your engine must validate them, fold them into a strongly-typed account ledger via a discriminated-union event bus, and expose a typed projection API — with zero `any`.",
    "snippet": "// Key types + main function signatures at a glance\n\nexport type EventId   = string & { readonly _brand: \"EventId\" };\nexport type AccountId = string & { readonly _brand: \"AccountId\" };\n\nexport type DomainEvent =\n  | AccountOpened | MoneyDeposited | MoneyWithdrawn | AccountClosed;\n\nexport type Result<T, E> =\n  | { ok: true;  value: T }\n  | { ok: false; error: E };\n\nexport type AccountProjection = {\n  accountId:  AccountId;\n  ownerName:  string;\n  balance:    number;\n  status:     \"open\" | \"closed\";\n  eventCount: number;\n  openedAt:   string;\n  closedAt:   string | null;\n};\n\n// Parse a raw unknown blob → typed DomainEvent or ValidationError\nexport function parseDomainEvent(raw: unknown): Result<DomainEvent, ValidationError>;\n\n// Fold one event onto a projection (or null for first event)\nexport function applyEvent(\n  projection: AccountProjection | null,\n  event: DomainEvent\n): Result<AccountProjection, ValidationError>;\n\n// Process a whole stream, collect projections + errors\nexport function buildLedger(rawEvents: unknown[]): LedgerReport;\n\n// Single-pass aggregate over all projections\nexport function summariseLedger(report: LedgerReport): LedgerSummary;",
    "goals": [
      "Define all branded types, discriminated-union events, and a generic Result<T,E> type with zero `any`.",
      "Implement fail-fast runtime validators that narrow `unknown` inputs to fully-typed `DomainEvent` values.",
      "Implement `applyEvent` with exhaustive discriminated-union matching and business-rule enforcement (e.g., no overdrafts).",
      "Implement `buildLedger` and `summariseLedger` — the latter must aggregate all fields in a single pass over the accounts Map."
    ],
    "hints": [
      "For branded types, an intersection like `string & { readonly _brand: \"EventId\" }` lets you keep string assignability while blocking accidental mixing — use a helper cast only in your validators where you've already confirmed the raw value is a string.",
      "In `applyEvent`, a `switch (event.type)` over the discriminated union gives you exhaustive narrowing for free — TypeScript will tell you if you miss a branch.",
      "For the single-pass `summariseLedger`, use `Array.from(report.accounts.values()).reduce(...)` and accumulate all fields (open count, closed count, total balance, max balance, most-active ID) in one reducer accumulator object."
    ],
    "docs": [
      {
        "title": "TypeScript Handbook — Discriminated Unions",
        "url": "https://www.typescriptlang.org/docs/handbook/2/narrowing.html#discriminated-unions"
      },
      {
        "title": "TypeScript Handbook — Generics",
        "url": "https://www.typescriptlang.org/docs/handbook/2/generics.html"
      },
      {
        "title": "TypeScript Handbook — keyof & Mapped Types",
        "url": "https://www.typescriptlang.org/docs/handbook/2/mapped-types.html"
      },
      {
        "title": "MDN — Map (with typed keys in TS)",
        "url": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map"
      }
    ]
  },
  {
    "date": "2026-04-12",
    "name": "Typed Notification Dispatcher",
    "difficulty": "Medium",
    "description": "You're building the notification delivery layer for a team collaboration app. Raw notification payloads arrive from a message broker as unknown blobs; your dispatcher must validate them, route them through a registry of typed channel handlers, and return a fully typed delivery report — with zero `any`.",
    "snippet": "// Core types + main function signature preview\n\nexport type ChannelKind = \"email\" | \"sms\" | \"push\" | \"webhook\";\n\n// Each channel has its own payload shape (discriminated by `channel`)\nexport type NotificationPayload =\n  | EmailPayload | SmsPayload | PushPayload | WebhookPayload;\n\n// Mapped type: each ChannelKind → handler for the *matching* payload\nexport type ChannelHandlerMap = {\n  [K in ChannelKind]: (payload: Extract<NotificationPayload, { channel: K }>) => Promise<DeliveryResult>;\n};\n\nexport interface DispatchReport {\n  total: number; sent: number; failed: number; skipped: number;\n  results: DeliveryResult[];\n}\n\n// Validate unknown blob → typed payload or null\nexport function validatePayload(raw: unknown): NotificationPayload | null { /* TODO */ return null; }\n\n// Concurrently dispatch all payloads, aggregate into a DispatchReport\nexport async function dispatchAll(\n  rawPayloads: unknown[],\n  handlers: ChannelHandlerMap\n): Promise<DispatchReport> { /* TODO */ return { total:0, sent:0, failed:0, skipped:0, results:[] }; }",
    "goals": [
      "Define `NotificationPayload` as a discriminated union and `ChannelHandlerMap` as a mapped type that pairs each `ChannelKind` with its exact payload variant.",
      "Implement `validatePayload` to narrow an `unknown` blob to a `NotificationPayload` using type guards — no `as` or `any`.",
      "Implement `dispatchAll` to concurrently dispatch all valid payloads via `Promise.allSettled`, capturing failures without short-circuiting, and return a typed `DispatchReport`.",
      "Implement `createHandlerRegistry` to merge partial handler overrides with a default 'skipped' fallback, returning a complete `ChannelHandlerMap`."
    ],
    "hints": [
      "For `ChannelHandlerMap`, try `{ [K in ChannelKind]: (p: Extract<NotificationPayload, { channel: K }>) => Promise<DeliveryResult> }` — `Extract` pulls the exact union member for each key.",
      "In `validatePayload`, start with `if (typeof raw !== 'object' || raw === null) return null`, then use `'to' in raw` and `typeof (raw as Record<string, unknown>).to === 'string'` style checks to drill down safely.",
      "`Promise.allSettled` never rejects — check each result's `.status` field (`'fulfilled'` vs `'rejected'`) to build your `DeliveryResult` without a try/catch around the whole batch."
    ],
    "docs": [
      {
        "title": "TypeScript — Discriminated Unions",
        "url": "https://www.typescriptlang.org/docs/handbook/2/narrowing.html#discriminated-unions"
      },
      {
        "title": "TypeScript — Mapped Types",
        "url": "https://www.typescriptlang.org/docs/handbook/2/mapped-types.html"
      },
      {
        "title": "TypeScript — Conditional Types & Extract",
        "url": "https://www.typescriptlang.org/docs/handbook/2/conditional-types.html"
      },
      {
        "title": "MDN — Promise.allSettled()",
        "url": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/allSettled"
      }
    ]
  },
  {
    "date": "2026-04-13",
    "name": "Typed Workflow Orchestrator",
    "difficulty": "Hard",
    "description": "You're building the execution engine for a low-code automation platform. Raw workflow definitions arrive as unknown JSON blobs from a database; your orchestrator must validate them, compile them into a strongly-typed execution graph, run steps through a typed middleware pipeline with retry logic, and surface a discriminated-union result per step — with zero `any`.",
    "snippet": "// Core types and main orchestrator signature\n\ntype Result<T, E> =\n  | { readonly ok: true;  value: T }\n  | { readonly ok: false; error: E };\n\ntype WorkflowStep = HttpStep | TransformStep | ConditionStep | NotifyStep;\n\n// TODO 2: Define this as a mapped type\ntype HandlerRegistry = /* mapped over WorkflowStep[\"kind\"] */ unknown;\n\ntype MiddlewareFn = (\n  step: WorkflowStep,\n  next: () => Promise<Result<unknown, ExecutionError>>\n) => Promise<Result<unknown, ExecutionError>>;\n\n// Main entry point — parse, compose, execute, report\ndeclare function runWorkflow(\n  raw: unknown,\n  registry: HandlerRegistry,\n  middlewares?: readonly MiddlewareFn[]\n): Promise<Result<WorkflowReport, OrchestratorError>>;\n",
    "goals": [
      "Define `HandlerRegistry` as a mapped type over `WorkflowStep[\"kind\"]` using `Extract` to bind each key to the correct `StepHandler` generic instantiation.",
      "Implement `parseWorkflowDef` to validate unknown input into a fully-typed `WorkflowDef`, checking all structural invariants and returning the first `ValidationError` encountered.",
      "Implement `composeMiddleware` to chain an array of `MiddlewareFn` wrappers around a terminal handler, preserving outermost-first execution order.",
      "Implement `runWorkflow` to parse, dispatch, retry, branch on conditions, collect `StepOutcome` records, and return a typed `WorkflowReport` — handling every discriminated step kind exhaustively."
    ],
    "hints": [
      "For `HandlerRegistry`, try: `{ [K in WorkflowStep[\"kind\"]]: StepHandler<Extract<WorkflowStep, { kind: K }>> }` — the mapped type does the narrowing for you.",
      "In `composeMiddleware`, build the chain from the inside out using `reduceRight` so that the first middleware in the array becomes the outermost wrapper.",
      "In `withRetry`, thread the attempt index through a recursive async helper rather than a `for` loop — it makes the exponential back-off calculation cleaner and avoids mutable state."
    ],
    "docs": [
      {
        "title": "TypeScript Handbook — Mapped Types",
        "url": "https://www.typescriptlang.org/docs/handbook/2/mapped-types.html"
      },
      {
        "title": "TypeScript Handbook — Conditional Types & Extract",
        "url": "https://www.typescriptlang.org/docs/handbook/2/conditional-types.html"
      },
      {
        "title": "TypeScript Handbook — Narrowing & Type Guards",
        "url": "https://www.typescriptlang.org/docs/handbook/2/narrowing.html"
      },
      {
        "title": "MDN — Promise & async/await patterns",
        "url": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise"
      }
    ]
  },
  {
    "date": "2026-04-14",
    "name": "Typed Feature Flag Evaluator",
    "difficulty": "Medium",
    "description": "You're building the feature-flag evaluation engine for a product experimentation platform. Raw flag configurations arrive from a remote config service as unknown JSON; your engine must validate them, evaluate each flag against a typed user context, and return a strongly-typed rollout report — with zero `any`.",
    "snippet": "// Core domain types + main function signature\n\ntype Audience = \"internal\" | \"beta\" | \"public\";\ntype Operator = \"eq\" | \"neq\" | \"in\" | \"not_in\" | \"gte\" | \"lte\";\n\ninterface UserContext {\n  userId: string; email: string; plan: string;\n  country: string; accountAgeDays: number; audience: Audience;\n}\n\ntype FlagVariant =\n  | { kind: \"boolean\"; enabled: boolean }\n  | { kind: \"string\";  variant: string  }\n  | { kind: \"number\";  variant: number  };\n\ntype FlagResult =\n  | { status: \"matched\"; flagId: string; rule: TargetingRule; variant: FlagVariant }\n  | { status: \"default\"; flagId: string; variant: FlagVariant }\n  | { status: \"invalid\"; flagId: string; error: string };\n\ninterface EvaluationReport {\n  userId: string; evaluatedAt: string;\n  results: FlagResult[];\n  summary: { total: number; matched: number; defaulted: number; invalid: number };\n}\n\n// Entry point — validate raw blobs, evaluate rules, return typed report\nfunction evaluateFlags(rawFlags: unknown[], user: UserContext): EvaluationReport { ... }\n",
    "goals": [
      "Implement `isAudience`, `isOperator`, and `isVariantKind` as proper type-guard functions that narrow `unknown` to their respective union types.",
      "Implement `parseFlagVariant`, `parseTargetingRule`, and `parseFeatureFlag` to safely validate raw `unknown` JSON into typed domain objects, throwing descriptive errors on bad input.",
      "Implement `evaluateRule` to correctly evaluate all six operators (`eq`, `neq`, `in`, `not_in`, `gte`, `lte`) against a `UserContext`.",
      "Implement `evaluateFlags` to orchestrate validation, audience gating, rule matching, and aggregate the results into a fully typed `EvaluationReport` with accurate summary counts."
    ],
    "hints": [
      "Use an `as const` array (e.g. `const VALID_AUDIENCES = [...] as const`) combined with `.includes()` to implement membership-check type guards without `any` — you may need a small cast on the `includes` call since TS widens the array type; consider `(arr as readonly unknown[]).includes(value)`.",
      "In `parseFlagVariant`, switch on `kind` after validating it with `isVariantKind` — TypeScript will narrow the discriminated union branch for you inside each `case`.",
      "In `evaluateFlags`, the audience gate rule is: a flag is eligible if `flag.audience === 'public'` OR `flag.audience === user.audience`; anything else resolves to `status: 'default'` before rules are even checked."
    ],
    "docs": [
      {
        "title": "TypeScript Handbook — Narrowing & Type Guards",
        "url": "https://www.typescriptlang.org/docs/handbook/2/narrowing.html"
      },
      {
        "title": "TypeScript Handbook — Discriminated Unions",
        "url": "https://www.typescriptlang.org/docs/handbook/2/narrowing.html#discriminated-unions"
      },
      {
        "title": "TypeScript Handbook — keyof Type Operator",
        "url": "https://www.typescriptlang.org/docs/handbook/2/keyof-types.html"
      },
      {
        "title": "TypeScript Handbook — Utility Types (Extract, Record, etc.)",
        "url": "https://www.typescriptlang.org/docs/handbook/utility-types.html"
      }
    ]
  },
  {
    "date": "2026-04-15",
    "name": "Typed CSV Report Parser",
    "difficulty": "Easy",
    "description": "You're building the data-import pipeline for a sales analytics dashboard. Raw CSV text arrives from uploaded files as plain strings; your parser must validate each row, transform it into a strongly-typed record, and return a typed parse report — with zero `any`.",
    "snippet": "// Core domain types + main function signature\n\nexport type Region = \"NA\" | \"EU\" | \"APAC\" | \"LATAM\";\n\nexport interface SaleRecord {\n  id: string;\n  region: Region;\n  product: string;\n  quantity: number;\n  unitPrice: number;\n  saleDate: Date;\n}\n\n// Generic column descriptor — T defaults to string\nexport interface ColumnSchema<T = string> {\n  header: string;\n  parse: (raw: string) => T;        // may throw on bad input\n  validate: (value: T) => string | null; // null = valid\n}\n\n// Discriminated union for per-row parse outcome\nexport type RowResult =\n  | { ok: true;  value: SaleRecord }\n  | { ok: false; rowIndex: number; raw: string; errors: string[] };\n\n// Main entry point\nexport function parseCSV(csv: string): ParseReport { /* TODO */ }\n",
    "goals": [
      "Define the `RowResult` discriminated union and complete the `ParseReport` interface, including using `Extract<>` for the `failures` field.",
      "Implement the generic `ColumnSchema<T>` interface and fill in all six `SALE_COLUMNS` entries with correct parse and validate logic, using `satisfies`.",
      "Implement `parseRow` to validate cell counts, catch parse errors, collect validation errors, and return the correct `RowResult` variant.",
      "Implement `parseCSV` (header validation, blank-line skipping, report assembly) and `revenueByRegion` (per-region sum via `Record<Region, number>`, zero-initialised, rounded to 2 dp)."
    ],
    "hints": [
      "The `failures` field type in `ParseReport` should use `Extract<RowResult, { ok: false }>[]` — let TypeScript derive the narrowed type rather than duplicating it.",
      "For `SALE_COLUMNS`, each entry has its own concrete `T`; annotate the array with `satisfies ReadonlyArray<ColumnSchema<unknown>>` so TypeScript checks each entry without widening individual `parse` return types.",
      "Inside `parseRow`, iterate over `schemas` with an index; wrap each `schema.parse(cells[i])` in a try/catch and only call `schema.validate` if parsing succeeded — then decide `ok: true` or `ok: false` at the end."
    ],
    "docs": [
      {
        "title": "TypeScript – Discriminated Unions",
        "url": "https://www.typescriptlang.org/docs/handbook/2/narrowing.html#discriminated-unions"
      },
      {
        "title": "TypeScript – Generic Interfaces",
        "url": "https://www.typescriptlang.org/docs/handbook/2/generics.html#generic-interfaces"
      },
      {
        "title": "TypeScript – satisfies operator",
        "url": "https://www.typescriptlang.org/docs/handbook/release-notes/typescript-4-9.html#the-satisfies-operator"
      },
      {
        "title": "TypeScript – Extract<Type, Union> utility type",
        "url": "https://www.typescriptlang.org/docs/handbook/utility-types.html#extracttype-union"
      }
    ]
  },
  {
    "date": "2026-04-16",
    "name": "Typed API Rate Limiter",
    "difficulty": "Medium",
    "description": "You're building the outbound API gateway for a SaaS integration platform. Multiple services make concurrent requests to third-party APIs with different rate limits; your gateway must validate raw endpoint configurations, enforce per-client token-bucket limits, execute requests with typed results, and return a structured dispatch report — with zero `any`.",
    "snippet": "// Key types and main function signature\n\ntype TokenCount  = number & { readonly __brand: \"TokenCount\" };\ntype ClientId    = string & { readonly __brand: \"ClientId\" };\ntype EndpointUrl = string & { readonly __brand: \"EndpointUrl\" };\n\ninterface EndpointConfig {\n  readonly url:       EndpointUrl;\n  readonly method:    \"GET\" | \"POST\" | \"PUT\" | \"PATCH\" | \"DELETE\";\n  readonly rateLimit: TokenCount;\n  readonly windowMs:  number;\n}\n\ninterface ApiRequest<TPayload> {\n  readonly requestId: string;\n  readonly clientId:  ClientId;\n  readonly endpoint:  EndpointConfig;\n  readonly payload:   TPayload;\n}\n\ntype RequestResult<TPayload, TResponse> =\n  | { status: \"fulfilled\";    requestId: string; clientId: ClientId; payload: TPayload; response: TResponse; tokensRemaining: number }\n  | { status: \"rate_limited\"; requestId: string; clientId: ClientId; payload: TPayload; retryAfterMs: number }\n  | { status: \"rejected\";     requestId: string; clientId: ClientId; payload: TPayload; error: string };\n\ntype FetchFn<TPayload, TResponse> = (req: ApiRequest<TPayload>) => Promise<TResponse>;\n\n// --- Main entry point ---\nasync function dispatchBatch<TPayload, TResponse>(\n  requests:  ReadonlyArray<ApiRequest<TPayload>>,\n  fetchFn:   FetchFn<TPayload, TResponse>,\n  registry:  RateLimiterRegistry\n): Promise<DispatchReport<TPayload, TResponse>>\n",
    "goals": [
      "Implement runtime brand constructors (`makeTokenCount`, `makeClientId`, `makeEndpointUrl`) that validate and narrow `unknown` inputs to nominal branded types.",
      "Build a `TokenBucket` class with typed getters and a `tryConsume()` method, plus a `RateLimiterRegistry` that manages one bucket per (clientId × endpointUrl) pair.",
      "Implement `validateEndpointConfig` that parses an `unknown` blob into a fully-typed `EndpointConfig`, throwing descriptive `TypeError`s for any violation.",
      "Implement `dispatchBatch` using `Promise.allSettled` to concurrently dispatch all requests through the registry, returning a typed `DispatchReport` with per-client fulfillment counts."
    ],
    "hints": [
      "Branded types are just intersection types — your brand constructors do the runtime guard and then `return value as TokenCount` (the one place a cast is justified: inside the constructor whose sole job is establishing the invariant).",
      "For `dispatchBatch`, consume the token *before* calling `fetchFn`; wrap the `fetchFn` call in a try/catch inside the `Promise.allSettled` worker so a rejected fetch still lands in `allSettled` as fulfilled (with a `rejected` result), keeping order stable.",
      "Build `clientSummary` in a single `reduce` pass over the results array, using a `Map<ClientId, number>` — then wrap it in a `ReadonlyMap` cast when returning."
    ],
    "docs": [
      {
        "title": "TypeScript — Branded / Nominal Types",
        "url": "https://www.typescriptlang.org/docs/handbook/2/types-from-types.html"
      },
      {
        "title": "Promise.allSettled — MDN",
        "url": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/allSettled"
      },
      {
        "title": "TypeScript — Generics",
        "url": "https://www.typescriptlang.org/docs/handbook/2/generics.html"
      },
      {
        "title": "TypeScript — Narrowing (unknown)",
        "url": "https://www.typescriptlang.org/docs/handbook/2/narrowing.html"
      }
    ]
  },
  {
    "date": "2026-04-17",
    "name": "Typed Query Plan Builder",
    "difficulty": "Hard",
    "description": "You're building the query planning layer for an in-memory analytics engine. Raw query descriptors arrive as unknown JSON from a REST API; your planner must validate them, compile them into a strongly-typed execution plan through a composable operator pipeline, execute each operator with typed intermediate results, and surface a discriminated-union outcome per stage — with zero `any`.",
    "snippet": "// Key types and main orchestrator signature\n\ntype OperatorExecutor<O extends PlanOperator> =\n  (operator: O, rows: ReadonlyArray<Row>, registry: TableRegistry)\n    => Result<ReadonlyArray<Row>, QueryError>;\n\ntype ExecutorRegistry = {\n  [K in OperatorKind]: OperatorExecutor<Extract<PlanOperator, { kind: K }>>;\n};\n\n// Discriminated operator union (one variant shown):\ninterface FilterOperatorNode { readonly kind: \"filter\"; readonly clause: FilterClause; }\ninterface ScanOperator       { readonly kind: \"scan\";   readonly table: TableName; }\n// … + project | groupBy | sort | limit\n\n// Top-level orchestrator — compose all four stages:\nfunction runQuery(\n  raw: unknown,\n  registry: TableRegistry\n): Result<QueryReport, QueryError>;\n",
    "goals": [
      "Define `OperatorExecutor<O>` as a generic function type constrained to `PlanOperator` variants, and `ExecutorRegistry` as a mapped type using `Extract` to pair each `OperatorKind` key with its correctly-typed executor.",
      "Implement `validateQuery` to safely narrow `unknown` input into a `ValidatedQuery`, branding all field and table name strings, and returning typed `QueryError` discriminants on every violation.",
      "Implement `buildPlan` to compile a `ValidatedQuery` into an ordered `ExecutionPlan`, enforcing the groupBy-select compatibility rule and emitting only the operators that apply.",
      "Implement `executePlan` to fold over the plan's operator array, dispatch each operator through the `ExecutorRegistry`, collect per-stage metrics, and short-circuit on the first execution error."
    ],
    "hints": [
      "For `ExecutorRegistry`, the mapped type key `K` extends `OperatorKind` — use `Extract<PlanOperator, { kind: K }>` as the type argument to `OperatorExecutor<…>` so each executor is narrowed to its exact operator variant.",
      "Inside `executePlan`, a `switch (operator.kind)` over the discriminant lets TypeScript narrow `operator` to the specific variant, allowing you to index `executors[operator.kind]` with the correctly-typed argument without any cast.",
      "Brand `FieldName` and `TableName` by writing a runtime-validated helper (e.g. `toFieldName(s: string): FieldName`) that asserts the non-empty invariant before returning `s as FieldName` — keep the cast inside the helper so the rest of the code stays assertion-free."
    ],
    "docs": [
      {
        "title": "TypeScript Handbook — Mapped Types",
        "url": "https://www.typescriptlang.org/docs/handbook/2/mapped-types.html"
      },
      {
        "title": "TypeScript Handbook — Conditional Types & Extract",
        "url": "https://www.typescriptlang.org/docs/handbook/2/conditional-types.html"
      },
      {
        "title": "TypeScript Handbook — Narrowing (type predicates & discriminated unions)",
        "url": "https://www.typescriptlang.org/docs/handbook/2/narrowing.html"
      },
      {
        "title": "TypeScript Handbook — Generics (constraints)",
        "url": "https://www.typescriptlang.org/docs/handbook/2/generics.html#generic-constraints"
      }
    ]
  },
  {
    "date": "2026-04-18",
    "name": "Typed Notification Router",
    "difficulty": "Medium",
    "description": "You're building the notification dispatch layer for a multi-channel messaging platform. Raw notification payloads arrive as unknown JSON from a message queue; your router must validate them, fan-out to the correct typed channel handlers, and produce a structured per-recipient delivery report — with zero `any`.",
    "snippet": "// Core discriminated union — channel is the discriminant\ntype NotificationPayload =\n  | { channel: \"email\";   to: string; subject: string; body: string }\n  | { channel: \"sms\";     to: string; body: string }\n  | { channel: \"push\";    deviceToken: string; title: string; body: string }\n  | { channel: \"webhook\"; url: string; eventType: string; data: Record<string, string | number | boolean> };\n\n// Generic handler constrained to one variant\ntype ChannelHandler<T extends NotificationPayload> = (payload: T) => Promise<DeliveryResult>;\n\n// Mapped registry — Extract picks the right variant per key\ntype HandlerRegistry = {\n  [K in NotificationPayload[\"channel\"]]: ChannelHandler<\n    Extract<NotificationPayload, { channel: K }>\n  >;\n};\n\n// Validate unknown → NotificationPayload or throw\nfunction validatePayload(raw: unknown): NotificationPayload { ... }\n\n// Fan-out to handlers concurrently, aggregate into a report\nasync function routeNotifications(\n  rawPayloads: unknown[],\n  registry: HandlerRegistry\n): Promise<DispatchReport> { ... }\n",
    "goals": [
      "Implement `validatePayload` to narrow `unknown` → `NotificationPayload` with channel-specific field rules, throwing descriptive errors on any violation.",
      "Define the `HandlerRegistry` mapped type so each channel key maps to a `ChannelHandler` typed to the exact matching `NotificationPayload` variant via `Extract<>`.",
      "Implement `routeNotifications` to validate and fan-out all payloads concurrently with `Promise.allSettled`, capturing both validation and handler errors as `DeliveryFailure`.",
      "Implement `createRegistry` as a one-liner using the `satisfies` operator so the caller's object is type-checked against `HandlerRegistry` without widening its inferred type."
    ],
    "hints": [
      "For the `HandlerRegistry` mapped type, `[K in NotificationPayload[\"channel\"]]` gives you each channel string as a key — pair it with `Extract<NotificationPayload, { channel: K }>` to get the exact variant.",
      "In `validatePayload`, a `switch` on the `channel` field after confirming it's a string lets TypeScript narrow subsequent field checks — no type assertions needed.",
      "`Promise.allSettled` returns `PromiseSettledResult<T>[]`; check `.status === 'fulfilled'` vs `'rejected'` to safely extract values or error messages for the report."
    ],
    "docs": [
      {
        "title": "TypeScript Handbook — Discriminated Unions",
        "url": "https://www.typescriptlang.org/docs/handbook/2/narrowing.html#discriminated-unions"
      },
      {
        "title": "TypeScript Handbook — Mapped Types",
        "url": "https://www.typescriptlang.org/docs/handbook/2/mapped-types.html"
      },
      {
        "title": "TypeScript Utility Types — Extract",
        "url": "https://www.typescriptlang.org/docs/handbook/utility-types.html#extracttype-union"
      },
      {
        "title": "MDN — Promise.allSettled",
        "url": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/allSettled"
      }
    ]
  },
  {
    "date": "2026-04-19",
    "name": "Typed Workflow Orchestrator",
    "difficulty": "Hard",
    "description": "You're building the workflow execution engine for a low-code automation platform. Raw workflow definitions arrive as unknown JSON from a user-facing editor; your orchestrator must validate them, compile each step into a strongly-typed execution graph, run steps with concurrency limits and retry logic, and emit a discriminated-union result per step — with zero `any`.",
    "snippet": "\n// Key types at a glance\n\ntype WorkflowStep =\n  | HttpStep        // { kind: \"http\";      url, method, body?, dependsOn }\n  | TransformStep   // { kind: \"transform\"; expression, dependsOn }\n  | ConditionStep   // { kind: \"condition\"; predicate, thenStepId, elseStepId, dependsOn }\n  | DelayStep;      // { kind: \"delay\";     ms, dependsOn }\n\n// Mapped type: each step kind → a strongly-typed async handler\ntype StepHandlerMap = {\n  [K in WorkflowStep[\"kind\"]]: (\n    step: Extract<WorkflowStep, { kind: K }>,\n    ctx: ExecutionContext\n  ) => Promise<unknown>;\n};\n\n// Result monad used throughout\ntype Result<T, E> = { ok: true; value: T } | { ok: false; error: E };\n\n// Main entry point\nasync function runWorkflow(\n  rawWorkflow: unknown,       // validated at runtime\n  handlers:    StepHandlerMap,\n  config:      ExecutorConfig // { concurrency, maxRetries, retryBaseMs }\n): Promise<ExecutionReport>\n",
    "goals": [
      "Implement `validateStep` and `validateWorkflow` to narrow `unknown` JSON into the `WorkflowStep` discriminated union and `Workflow` type using the `Result<T,E>` pattern — with zero `as` casts in your logic.",
      "Implement `topoSort` using Kahn's algorithm to produce a dependency-respecting execution order and return `Err` on cycle detection.",
      "Implement `orchestrate` to execute steps concurrently (up to `config.concurrency`), skip steps whose dependencies failed, handle `ConditionStep` branch skipping, and retry failing steps with exponential back-off.",
      "Implement `runWorkflow` as the public entry point that composes validation and orchestration, returning a well-formed `ExecutionReport` even when validation fails."
    ],
    "hints": [
      "For `StepHandlerMap`, write `[K in WorkflowStep[\"kind\"]]` and use `Extract<WorkflowStep, { kind: K }>` to get the exact step type for each handler — this is the core mapped-type trick.",
      "In `orchestrate`, maintain a `Set<StepId>` of completed/failed steps and a queue; on each tick, dispatch all steps whose `dependsOn` are fully resolved, then `await Promise.race` to stay within the concurrency limit.",
      "For retry back-off, a simple `await new Promise(r => setTimeout(r, config.retryBaseMs * 2 ** attempt))` inside a loop is all you need — track `attempts` to populate `StepFailure`."
    ],
    "docs": [
      {
        "title": "TS Handbook — Mapped Types",
        "url": "https://www.typescriptlang.org/docs/handbook/2/mapped-types.html"
      },
      {
        "title": "TS Handbook — Conditional Types & Extract",
        "url": "https://www.typescriptlang.org/docs/handbook/2/conditional-types.html"
      },
      {
        "title": "TS Handbook — Narrowing",
        "url": "https://www.typescriptlang.org/docs/handbook/2/narrowing.html"
      },
      {
        "title": "MDN — Promise.race",
        "url": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/race"
      }
    ]
  },
  {
    "date": "2026-04-20",
    "name": "Typed Event Stream Aggregator",
    "difficulty": "Medium",
    "description": "You're building the real-time analytics backend for a product telemetry platform. Raw event objects arrive as `unknown` from a WebSocket feed; your aggregator must validate them, route them to per-event-type handlers, and produce a strongly-typed session summary — with zero `any`.",
    "snippet": "// Key types and main function signature preview\n\nexport type EventKind =\n  | \"page_view\" | \"button_click\" | \"error\" | \"purchase\" | \"session_end\";\n\n// Discriminated union — one member shown as example:\n// { kind: \"purchase\"; sessionId: string; timestamp: number;\n//   orderId: string; amountCents: number; currency: string }\nexport type TelemetryEvent = /* your discriminated union */ never;\n\nexport type SessionSummary = {\n  sessionId      : string;\n  pageViews      : string[];\n  clicks         : Record<string, number>;\n  errors         : Array<{ code: number; message: string; fatal: boolean }>;\n  totalSpentCents: number;\n  currencies     : Set<string>;\n  endedAt        : number | null;\n};\n\nexport type EventHandlerMap =\n  { [K in EventKind]: (event: Extract<TelemetryEvent, { kind: K }>) => void };\n\nexport function parseTelemetryEvent(raw: unknown): TelemetryEvent | null { /* TODO */ return null; }\n\nexport function aggregateSession(\n  sessionId : string,\n  rawEvents : unknown[],\n): AggregationReport { /* TODO */ return null!; }",
    "goals": [
      "Define a discriminated union `TelemetryEvent` with 5 variants sharing `sessionId` and `timestamp` fields.",
      "Implement `parseTelemetryEvent` as a type-guard that narrows `unknown` to `TelemetryEvent | null` using narrowing only — no `as`.",
      "Build an `EventHandlerMap` mapped type and `createHandlerMap` factory that routes each event kind to a handler mutating a `SessionSummary`.",
      "Implement `aggregateSession` that parses, filters by session ID, routes events, and returns a fully-typed `AggregationReport`."
    ],
    "hints": [
      "A mapped type `{ [K in EventKind]: (e: Extract<TelemetryEvent, { kind: K }>) => void }` lets TypeScript verify every kind has a handler — and gives each handler a narrowed event type for free.",
      "In `parseTelemetryEvent`, check `typeof raw === 'object' && raw !== null` first, then use `'url' in raw` style checks for each variant — the compiler will narrow the type at each step.",
      "Track `kindCounts` as `Record<EventKind, number>` initialised with all five keys set to `0`; updating it inside `aggregateSession` (not inside the handlers) keeps the report logic clean."
    ],
    "docs": [
      {
        "title": "TypeScript Handbook — Discriminated Unions",
        "url": "https://www.typescriptlang.org/docs/handbook/2/narrowing.html#discriminated-unions"
      },
      {
        "title": "TypeScript Handbook — Mapped Types",
        "url": "https://www.typescriptlang.org/docs/handbook/2/mapped-types.html"
      },
      {
        "title": "TypeScript Utility Types — Extract",
        "url": "https://www.typescriptlang.org/docs/handbook/utility-types.html#extracttype-union"
      },
      {
        "title": "TypeScript Handbook — Narrowing (type guards)",
        "url": "https://www.typescriptlang.org/docs/handbook/2/narrowing.html"
      }
    ]
  },
  {
    "date": "2026-04-21",
    "name": "Typed Schema Migration Engine",
    "difficulty": "Hard",
    "description": "You're building the schema migration engine for a multi-tenant database platform. Raw migration manifests arrive as `unknown` JSON from a CI/CD pipeline; your engine must validate them, compile each migration into a strongly-typed dependency graph, execute migrations in topological order with concurrency limits and rollback support, and emit a discriminated-union result per migration — with zero `any`.",
    "snippet": "\n// Key types & main orchestrator signature\n\nexport type MigrationId = string & { readonly __brand: \"MigrationId\" };\n\nexport type MigrationResult =\n  | { status: \"applied\";    id: MigrationId; durationMs: number }\n  | { status: \"skipped\";    id: MigrationId; reason: string }\n  | { status: \"failed\";     id: MigrationId; error: ExecutionError }\n  | { status: \"rolledBack\"; id: MigrationId; error: ExecutionError };\n\nexport type EngineReport =\n  | { outcome: \"success\";         results: MigrationResult[]; totalMs: number }\n  | { outcome: \"partial_failure\"; results: MigrationResult[]; totalMs: number; firstFailure: MigrationId }\n  | { outcome: \"validation_error\"; errors: ValidationError[] }\n  | { outcome: \"graph_error\";      error: GraphError };\n\nexport type ExecutorFn = (\n  id: MigrationId,\n  sql: string,\n  direction: \"up\" | \"down\"\n) => Promise<{ ok: true } | { ok: false; reason: string }>;\n\n/** Validates → compiles graph → executes waves → returns structured report. */\nexport async function runEngine(\n  rawManifest: unknown,\n  executor: ExecutorFn,\n  options?: Partial<EngineOptions>\n): Promise<EngineReport> { /* TODO */ }\n",
    "goals": [
      "Implement `validateManifest` to narrow `unknown` input into `ValidMigration[]`, accumulating ALL `ValidationError`s (field errors, duplicates, unknown deps) without short-circuiting, and brand valid ids as `MigrationId` without using `as`.",
      "Implement `compileGraph` to build a typed dependency graph, detect cycles with a path-reporting DFS or Kahn's algorithm, and produce topologically sorted `waves` of concurrently-runnable migrations.",
      "Implement `runMigrations` to process waves sequentially with bounded concurrency (`Promise.allSettled`), skip already-applied migrations, and on failure optionally roll back all applied migrations in reverse order — emitting a discriminated-union `MigrationResult` per migration.",
      "Wire everything together in `runEngine` with proper `Partial<EngineOptions>` default-filling and correct `EngineReport` propagation from each stage."
    ],
    "hints": [
      "For branding `MigrationId` without `as`, write a type predicate `function isMigrationId(s: string): s is MigrationId` that validates the string, then call it inside `validateManifest` — the narrowed type flows automatically.",
      "Kahn's algorithm (in-degree queue) naturally produces topological waves: all nodes with in-degree 0 form wave 0; decrement neighbors and collect the next zero-in-degree batch for wave 1, and so on — cycle detection is free (remaining non-zero in-degree nodes).",
      "Track applied migrations in a local `MigrationId[]` (push on success); on rollback iterate with `.reverse()` and call the executor with `direction: \"down\"` — `Promise.allSettled` ensures you capture every settled result even when some reject."
    ],
    "docs": [
      {
        "title": "TypeScript Handbook — Narrowing",
        "url": "https://www.typescriptlang.org/docs/handbook/2/narrowing.html"
      },
      {
        "title": "TypeScript Handbook — Template Literal & Branded Types",
        "url": "https://www.typescriptlang.org/docs/handbook/2/template-literal-types.html"
      },
      {
        "title": "MDN — Promise.allSettled()",
        "url": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/allSettled"
      },
      {
        "title": "TypeScript Deep Dive — Discriminated Unions",
        "url": "https://basarat.gitbook.io/typescript/type-system/discriminated-unions"
      }
    ]
  },
  {
    "date": "2026-04-22",
    "name": "Typed API Response Cache",
    "difficulty": "Medium",
    "description": "You're building the caching layer for a typed REST API client used across a large frontend monorepo. Raw responses arrive as `unknown` from fetch; your cache must validate them, store them with TTL-aware entries, and serve requests through a stale-while-revalidate strategy — with zero `any`.",
    "snippet": "// Core types and main class signature\n\nexport type Result<T, E extends string = string> =\n  | { ok: true; value: T }\n  | { ok: false; error: E };\n\nexport type Validator<T> = (raw: unknown) => Result<T, string>;\n\nexport type CacheEntry<T> = { /* value, storedAt, ttl */ };\n\nexport type CacheStatus<T> =\n  | { status: \"hit\";   value: T }\n  | { status: \"stale\"; value: T }\n  | { status: \"miss\" };\n\nexport type RevalidationResult<T> =\n  | { revalidated: true;  key: string; value: T }\n  | { revalidated: false; key: string; error: string };\n\nexport class TypedCache<T> {\n  constructor(\n    private readonly defaultTtl: number,\n    private readonly validator: Validator<T>\n  ) {}\n\n  set(key: string, raw: unknown, ttl?: number): Result<T, string> { ... }\n  get(key: string): CacheStatus<T> { ... }\n  delete(key: string): boolean { ... }\n  async revalidate(key: string, fetchFn: FetchFn): Promise<RevalidationResult<T>> { ... }\n  async getOrFetch(key: string, fetchFn: FetchFn): Promise<Result<T, string>> { ... }\n  purgeExpired(): number { ... }\n}",
    "goals": [
      "Define `CacheEntry<T>`, `CacheStatus<T>`, and `RevalidationResult<T>` as fully-typed discriminated unions and generic types.",
      "Implement `buildValidator` using a mapped-type `shape` parameter that narrows `unknown` to `T` without `any` or type assertions.",
      "Implement all six `TypedCache<T>` methods (`set`, `get`, `delete`, `revalidate`, `getOrFetch`, `purgeExpired`) with correct TTL logic and typed return values.",
      "Ensure every code path is covered by the discriminant checks so TypeScript's exhaustiveness analysis is satisfied."
    ],
    "hints": [
      "For `CacheStatus<T>`, give each variant a `status` string literal field — TypeScript will use it as the discriminant when you narrow with `if (s.status === 'hit')`.",
      "In `buildValidator`, iterate over `Object.keys(shape)` and cast the key as `keyof T` — the mapped-type constraint on `shape` gives you the predicate for each field without needing `any`.",
      "In `getOrFetch`, check the result of `this.get(key)` first: only skip the fetch when `status === 'hit'`; treat both `'miss'` and `'stale'` as needing a fresh fetch."
    ],
    "docs": [
      {
        "title": "TypeScript Handbook — Discriminated Unions",
        "url": "https://www.typescriptlang.org/docs/handbook/2/narrowing.html#discriminated-unions"
      },
      {
        "title": "TypeScript Handbook — Mapped Types",
        "url": "https://www.typescriptlang.org/docs/handbook/2/mapped-types.html"
      },
      {
        "title": "TypeScript Handbook — Generics",
        "url": "https://www.typescriptlang.org/docs/handbook/2/generics.html"
      },
      {
        "title": "MDN — Map object",
        "url": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map"
      }
    ]
  }
]