The plan for this section is to have examples for handling partial responses via UnprocessedKeys and batch size edge cases (i.e. chunking requests to 100 items per request).

I think it's better to sprinkle limits inside the examples, or at least give a warning (with :::caution admonitions for instance) that points to that section. Otherwise some devs might just overlook it.

Nitpick but you can remove the bracket (and simply use pokemonId as key):

const requests = pokemonIds.map((pokemonId) =>
  PokemonEntity.build(BatchGetRequest).key({ pokemonId })
)

Maybe this will be clearer?

// 👇 `Responses` is an array of size 1 as we only sent one `BatchGetCommand`
const [pokemons] = Responses

for (const pokemon of pokemons) {
  // ...do something with pokemon here
  // (note that pokemon might be `undefined`)
}

Yeah sure! I do think using .map() to iterate would translate better to real-world use cases though as internally we haven't come across a scenario where using a for of loop has been needed. I'm not too precious on syntax though, thoughts?

@ThomasAribart It turns out we don't have a use case internally where we need to retrieve multiple entities in batch so I'm coming up with an example myself. Since we're limited to one BatchGetCommand per table, I tried passing multiple types of BatchGetRequests into a BatchGetCommand but ran into a ts(2859) Excessive complexity comparing types error. Any recommendations on how to best approach this use case?

I also wonder whether this use case is even worth including in the documentation 🤔? Batch retrieving multiple entities from a single table screams code smell to me in the context of single table design -- I'm struggling to think of a scenario where this would be useful/valid. Perhaps we should remove it?

@ThomasAribart I've fleshed out the "Handling BatchGetItem Edge Cases" section, let me know what you think!

Still thinking about how to best write this section. Also considering rolling it into the previous section as we've handled this internally with a wrapper function, but I'm not 100% happy with the solution.