Iterator
Iterador · Cursor
Permite recorrer los elementos de una colección uno a uno sin exponer cómo está organizada por dentro.
“Quiero recorrer una colección sin exponer cómo está guardada.”
workEl caso real
Tu sistema sincroniza todos los clientes de un CRM externo. La API del CRM devuelve los clientes de 100 en 100 y, para pedir la página siguiente, hay que enviar el cursor que llegó en la respuesta anterior. Varios procesos necesitan recorrer todos los clientes: la sincronización, una exportación y un informe mensual.
warningEl problema sin el patrón
Cada proceso repite el mismo bucle de paginación: pedir una página, leer el cursor y detectar el final. Si el CRM cambia su forma de paginar, hay que corregir todos los bucles.
check_circleCómo lo resuelve el patrón
Un iterador encapsula el recorrido: quien lo usa solo pide "el siguiente cliente" hasta que no quedan más. Cómo se piden las páginas y se maneja el cursor queda oculto. En TypeScript se implementa de forma natural con un generador asíncrono.
schemaDiagrama de clases
Diagrama interactivo: puedes acercar, mover el lienzo y pasar el cursor sobre cada clase para ver su detalle.
codeEl código, antes y después
let cursor: string | undefined;
do {
const pagina = await crm.listarClientes({ limite: 100, cursor });
for (const cliente of pagina.datos) await sincronizar(cliente);
cursor = pagina.siguienteCursor; // el mismo bucle, copiado en cada proceso
} while (cursor);class ClientesCrm implements AsyncIterable<Cliente> {
constructor(private crm: ApiCrm) {}
async *[Symbol.asyncIterator]() {
let cursor: string | undefined;
do {
const pagina = await this.crm.listarClientes({ limite: 100, cursor });
yield* pagina.datos;
cursor = pagina.siguienteCursor;
} while (cursor);
}
}
// Cualquier proceso recorre los clientes sin saber nada de páginas ni cursores
for await (const cliente of new ClientesCrm(crm)) {
await sincronizar(cliente);
}Ejemplos en TypeScript, simplificados para mostrar la idea: los tipos auxiliares (Pedido, Cliente…) se omiten.
Matiz importante
La mayoría de lenguajes modernos traen el patrón integrado: Symbol.iterator y generadores en JavaScript y TypeScript, IEnumerable y yield return en C#, Iterator en Java y generadores en Python. Rara vez hace falta escribir hasNext() y next() a mano.
thumb_upCuándo usarlo
- ✓La colección tiene una estructura interna compleja (páginas, árbol, grafo) que no quieres exponer.
- ✓Necesitas varias formas de recorrer la misma colección, o un recorrido perezoso que carga a medida que avanza.
- ✓Necesitas varios recorridos a la vez sobre la misma colección, o pausar uno y retomarlo más tarde: cada iterador guarda su propia posición.
do_not_disturb_onCuándo no usarlo
- ✕Es una lista o un array simple: los bucles del lenguaje ya usan iteradores.
- ✕Necesitas acceso aleatorio por posición más que un recorrido secuencial.
- ✕En colecciones muy especializadas, un iterador genérico puede ser más lento que acceder directamente a sus elementos.
memoryPrincipios en juego
- •Responsabilidad única: el recorrido se separa de la colección y de quien la usa.
- •Ocultamiento de información: el cliente no conoce la estructura interna (páginas, árbol, grafo).
hubPatrones relacionados
- •Composite: los iteradores permiten recorrer un árbol sin conocer su estructura.
- •Factory Method: una colección puede devolver el iterador adecuado mediante un método fábrica.
- •Memento: se puede guardar la posición de un recorrido para continuarlo después.
quizPon a prueba lo que leíste
Dos preguntas al azar sobre este patrón. Cada vez que las cambias salen otras.
code_blocksIterator en tu lenguaje
El mismo caso, implementado completo y de forma idiomática. Se puede copiar y ejecutar.
LO IDIOMÁTICO EN TYPESCRIPT: Un generador asíncrono (async *) implementa AsyncIterable y el cliente lo recorre con for await: no hace falta escribir next() a mano. Además el recorrido es perezoso: si el cliente sale del bucle antes, no se piden más páginas.
interface Cliente { id: number; nombre: string }
interface Pagina { datos: Cliente[]; siguienteCursor?: string }
// API simulada que devuelve los clientes de dos en dos
class ApiCrm {
readonly #clientes: Cliente[] = ['Ana', 'Luis', 'Marta', 'Jorge', 'Elena'].map((nombre, i) => ({ id: i + 1, nombre }));
peticiones = 0;
async listarClientes({ limite, cursor }: { limite: number; cursor?: string }): Promise<Pagina> {
this.peticiones++;
const desde = cursor ? Number(cursor) : 0;
const hasta = desde + limite;
return {
datos: this.#clientes.slice(desde, hasta),
siguienteCursor: hasta < this.#clientes.length ? String(hasta) : undefined,
};
}
}
export class ClientesCrm implements AsyncIterable<Cliente> {
constructor(private readonly crm: ApiCrm, private readonly limite = 2) {}
async *[Symbol.asyncIterator](): AsyncGenerator<Cliente> {
let cursor: string | undefined;
do {
const pagina = await this.crm.listarClientes({ limite: this.limite, cursor });
yield* pagina.datos;
cursor = pagina.siguienteCursor;
} while (cursor);
}
}
// ── Uso ──
const crm = new ApiCrm();
for await (const cliente of new ClientesCrm(crm)) {
console.log(cliente.nombre);
}
console.log(`Peticiones a la API: ${crm.peticiones}`); // 3
// Perezoso: si se corta antes, no se piden más páginas
const otroCrm = new ApiCrm();
for await (const cliente of new ClientesCrm(otroCrm)) {
if (cliente.id === 2) break;
}
console.log(`Peticiones a la API: ${otroCrm.peticiones}`); // 1LO IDIOMÁTICO EN C# / .NET: async + yield return crea un IAsyncEnumerable<T>: un iterador que espera cada página sin bloquear el hilo. El cliente lo recorre con await foreach, y si sale del bucle con break, no se piden más páginas.
var crm = new ApiCrm();
await foreach (var cliente in ClientesCrm.Recorrer(crm))
Console.WriteLine(cliente.Nombre);
Console.WriteLine($"Peticiones a la API: {crm.Peticiones}"); // 3
var otroCrm = new ApiCrm();
await foreach (var cliente in ClientesCrm.Recorrer(otroCrm))
{
if (cliente.Id == 2) break;
}
Console.WriteLine($"Peticiones a la API: {otroCrm.Peticiones}"); // 1
public record Cliente(int Id, string Nombre);
public record Pagina(IReadOnlyList<Cliente> Datos, string? SiguienteCursor);
public class ApiCrm
{
private readonly Cliente[] _clientes = [new(1, "Ana"), new(2, "Luis"), new(3, "Marta"), new(4, "Jorge"), new(5, "Elena")];
public int Peticiones { get; private set; }
public async Task<Pagina> ListarClientesAsync(int limite, string? cursor)
{
await Task.Yield(); // simula la llamada HTTP
Peticiones++;
var desde = cursor is null ? 0 : int.Parse(cursor);
var hasta = Math.Min(desde + limite, _clientes.Length);
return new Pagina(_clientes[desde..hasta], hasta < _clientes.Length ? hasta.ToString() : null);
}
}
public static class ClientesCrm
{
public static async IAsyncEnumerable<Cliente> Recorrer(ApiCrm api, int limite = 2)
{
string? cursor = null;
do
{
var pagina = await api.ListarClientesAsync(limite, cursor);
foreach (var cliente in pagina.Datos) yield return cliente;
cursor = pagina.SiguienteCursor;
} while (cursor is not null);
}
}LO IDIOMÁTICO EN JAVA: La colección implementa Iterable<Cliente>, así que se recorre con un for normal. El iterador guarda la página actual y solo pide la siguiente cuando hasNext() llega al final: si el bucle sale antes con break, no se hacen más peticiones.
void main() {
var crm = new ApiCrm();
for (var cliente : new ClientesCrm(crm, 2)) {
IO.println(cliente.nombre());
}
IO.println("Peticiones a la API: " + crm.peticiones()); // 3
var otroCrm = new ApiCrm();
for (var cliente : new ClientesCrm(otroCrm, 2)) {
if (cliente.id() == 2) break;
}
IO.println("Peticiones a la API: " + otroCrm.peticiones()); // 1
}
record Cliente(int id, String nombre) {}
record Pagina(List<Cliente> datos, String siguienteCursor) {}
final class ApiCrm {
private final List<Cliente> clientes = List.of(
new Cliente(1, "Ana"), new Cliente(2, "Luis"), new Cliente(3, "Marta"),
new Cliente(4, "Jorge"), new Cliente(5, "Elena"));
private int peticiones;
Pagina listarClientes(int limite, String cursor) {
peticiones++;
var desde = cursor == null ? 0 : Integer.parseInt(cursor);
var hasta = Math.min(desde + limite, clientes.size());
return new Pagina(clientes.subList(desde, hasta), hasta < clientes.size() ? String.valueOf(hasta) : null);
}
int peticiones() { return peticiones; }
}
final class ClientesCrm implements Iterable<Cliente> {
private final ApiCrm api;
private final int limite;
ClientesCrm(ApiCrm api, int limite) {
this.api = api;
this.limite = limite;
}
@Override
public java.util.Iterator<Cliente> iterator() {
return new java.util.Iterator<>() {
private Pagina pagina = api.listarClientes(limite, null);
private int posicion;
@Override
public boolean hasNext() {
if (posicion < pagina.datos().size()) return true;
if (pagina.siguienteCursor() == null) return false;
pagina = api.listarClientes(limite, pagina.siguienteCursor()); // pide la siguiente página
posicion = 0;
return !pagina.datos().isEmpty();
}
@Override
public Cliente next() {
if (!hasNext()) throw new NoSuchElementException();
return pagina.datos().get(posicion++);
}
};
}
}LO IDIOMÁTICO EN JAVASCRIPT: Una función generadora asíncrona (async function*) es el iterador: no hace falta ninguna clase. El cliente la recorre con for await, y el recorrido es perezoso: si sale del bucle antes, no se piden más páginas.
function crearApiCrm() {
const clientes = ['Ana', 'Luis', 'Marta', 'Jorge', 'Elena'].map((nombre, i) => ({ id: i + 1, nombre }));
const api = {
peticiones: 0,
async listarClientes({ limite, cursor }) {
api.peticiones++;
const desde = cursor ? Number(cursor) : 0;
const hasta = desde + limite;
return {
datos: clientes.slice(desde, hasta),
siguienteCursor: hasta < clientes.length ? String(hasta) : undefined,
};
},
};
return api;
}
export async function* clientesCrm(crm, limite = 2) {
let cursor;
do {
const pagina = await crm.listarClientes({ limite, cursor });
yield* pagina.datos;
cursor = pagina.siguienteCursor;
} while (cursor);
}
// ── Uso ──
const crm = crearApiCrm();
for await (const cliente of clientesCrm(crm)) {
console.log(cliente.nombre);
}
console.log(`Peticiones a la API: ${crm.peticiones}`); // 3
const otroCrm = crearApiCrm();
for await (const cliente of clientesCrm(otroCrm)) {
if (cliente.id === 2) break; // perezoso: no se piden más páginas
}
console.log(`Peticiones a la API: ${otroCrm.peticiones}`); // 1LO IDIOMÁTICO EN PYTHON: Una función generadora (yield) es el iterador: Python la recorre con for y la ejecuta de forma perezosa, pidiendo una página nueva solo cuando hace falta. yield from entrega los elementos de cada página e itertools.islice toma los primeros sin recorrer todo.
from collections.abc import Iterator
from dataclasses import dataclass
from itertools import islice
@dataclass(frozen=True)
class Cliente:
id: int
nombre: str
@dataclass(frozen=True)
class Pagina:
datos: list[Cliente]
siguiente_cursor: str | None
class ApiCrm:
def __init__(self) -> None:
self._clientes = [Cliente(i, n) for i, n in enumerate(["Ana", "Luis", "Marta", "Jorge", "Elena"], start=1)]
self.peticiones = 0
def listar_clientes(self, limite: int, cursor: str | None = None) -> Pagina:
self.peticiones += 1
desde = int(cursor) if cursor else 0
hasta = desde + limite
siguiente = str(hasta) if hasta < len(self._clientes) else None
return Pagina(self._clientes[desde:hasta], siguiente)
def clientes_crm(crm: ApiCrm, limite: int = 2) -> Iterator[Cliente]:
cursor: str | None = None
while True:
pagina = crm.listar_clientes(limite, cursor)
yield from pagina.datos
if (cursor := pagina.siguiente_cursor) is None:
return
if __name__ == "__main__":
crm = ApiCrm()
for cliente in clientes_crm(crm):
print(cliente.nombre)
print(f"Peticiones a la API: {crm.peticiones}") # 3
otro_crm = ApiCrm()
primeros = [c.nombre for c in islice(clientes_crm(otro_crm), 2)]
print(primeros, f"· peticiones: {otro_crm.peticiones}") # ['Ana', 'Luis'] · peticiones: 1LO IDIOMÁTICO EN GO: Desde Go 1.23 se puede recorrer una función con for range (range-over-func). El iterador es un iter.Seq2 que entrega cada cliente junto con un posible error; si el bucle hace break, yield devuelve false y el iterador deja de pedir páginas.
package main
import (
"fmt"
"iter"
"strconv"
)
type Cliente struct {
ID int
Nombre string
}
type Pagina struct {
Datos []Cliente
SiguienteCursor string
}
type ApiCrm struct {
clientes []Cliente
Peticiones int
}
func NuevaApiCrm() *ApiCrm {
api := &ApiCrm{}
for i, nombre := range []string{"Ana", "Luis", "Marta", "Jorge", "Elena"} {
api.clientes = append(api.clientes, Cliente{i + 1, nombre})
}
return api
}
func (a *ApiCrm) ListarClientes(limite int, cursor string) (Pagina, error) {
a.Peticiones++
desde := 0
if cursor != "" {
var err error
if desde, err = strconv.Atoi(cursor); err != nil {
return Pagina{}, fmt.Errorf("cursor inválido: %w", err)
}
}
hasta := min(desde+limite, len(a.clientes))
pagina := Pagina{Datos: a.clientes[desde:hasta]}
if hasta < len(a.clientes) {
pagina.SiguienteCursor = strconv.Itoa(hasta)
}
return pagina, nil
}
func ClientesCrm(api *ApiCrm, limite int) iter.Seq2[Cliente, error] {
return func(yield func(Cliente, error) bool) {
cursor := ""
for {
pagina, err := api.ListarClientes(limite, cursor)
if err != nil {
yield(Cliente{}, err)
return
}
for _, cliente := range pagina.Datos {
if !yield(cliente, nil) {
return // el cliente salió del bucle: no se piden más páginas
}
}
if pagina.SiguienteCursor == "" {
return
}
cursor = pagina.SiguienteCursor
}
}
}
func main() {
api := NuevaApiCrm()
for cliente, err := range ClientesCrm(api, 2) {
if err != nil {
fmt.Println("error:", err)
break
}
fmt.Println(cliente.Nombre)
}
fmt.Println("Peticiones a la API:", api.Peticiones) // 3
otra := NuevaApiCrm()
for cliente := range ClientesCrm(otra, 2) {
if cliente.ID == 2 {
break
}
}
fmt.Println("Peticiones a la API:", otra.Peticiones) // 1
}LO IDIOMÁTICO EN RUST: Implementar el trait Iterator (solo el método next) da gratis todos sus adaptadores: map, filter, take... Los iteradores de Rust son perezosos, así que take(2) solo provoca la petición de la primera página.
#[derive(Clone, Copy)]
struct Cliente {
id: u32,
nombre: &'static str,
}
struct Pagina {
datos: Vec<Cliente>,
siguiente_cursor: Option<usize>,
}
struct ApiCrm {
clientes: Vec<Cliente>,
peticiones: u32,
}
impl ApiCrm {
fn new() -> Self {
let nombres = ["Ana", "Luis", "Marta", "Jorge", "Elena"];
let clientes = (1..)
.zip(nombres)
.map(|(id, nombre)| Cliente { id, nombre })
.collect();
Self {
clientes,
peticiones: 0,
}
}
fn listar_clientes(&mut self, limite: usize, cursor: usize) -> Pagina {
self.peticiones += 1;
let hasta = (cursor + limite).min(self.clientes.len());
Pagina {
datos: self.clientes[cursor..hasta].to_vec(),
siguiente_cursor: (hasta < self.clientes.len()).then_some(hasta),
}
}
}
struct ClientesCrm<'a> {
api: &'a mut ApiCrm,
limite: usize,
pagina: std::vec::IntoIter<Cliente>,
siguiente: Option<usize>,
}
impl<'a> ClientesCrm<'a> {
fn new(api: &'a mut ApiCrm, limite: usize) -> Self {
Self {
api,
limite,
pagina: Vec::new().into_iter(),
siguiente: Some(0),
}
}
}
impl Iterator for ClientesCrm<'_> {
type Item = Cliente;
fn next(&mut self) -> Option<Cliente> {
loop {
if let Some(cliente) = self.pagina.next() {
return Some(cliente);
}
let cursor = self.siguiente?; // no hay más páginas: el iterador termina
let pagina = self.api.listar_clientes(self.limite, cursor);
self.siguiente = pagina.siguiente_cursor;
self.pagina = pagina.datos.into_iter();
}
}
}
fn main() {
let mut crm = ApiCrm::new();
for cliente in ClientesCrm::new(&mut crm, 2) {
println!("{} {}", cliente.id, cliente.nombre);
}
println!("Peticiones a la API: {}", crm.peticiones); // 3
let mut otro_crm = ApiCrm::new();
let primeros: Vec<&str> = ClientesCrm::new(&mut otro_crm, 2)
.take(2)
.map(|c| c.nombre)
.collect();
println!("{primeros:?} · peticiones: {}", otro_crm.peticiones); // ["Ana", "Luis"] · peticiones: 1
}LO IDIOMÁTICO EN PHP: La colección implementa IteratorAggregate y su getIterator() es un generador: con yield from entrega los clientes de cada página. Se recorre con foreach, y como los generadores son perezosos, un break evita pedir más páginas.
<?php
declare(strict_types=1);
final readonly class Cliente
{
public function __construct(public int $id, public string $nombre) {}
}
final class ApiCrm
{
public int $peticiones = 0;
/** @var list<Cliente> */
private array $clientes;
public function __construct()
{
$this->clientes = array_map(
fn (int $i, string $nombre) => new Cliente($i + 1, $nombre),
array_keys($nombres = ['Ana', 'Luis', 'Marta', 'Jorge', 'Elena']),
$nombres,
);
}
/** @return array{datos: list<Cliente>, siguiente: ?int} */
public function listarClientes(int $limite, int $cursor): array
{
$this->peticiones++;
$hasta = min($cursor + $limite, count($this->clientes));
return [
'datos' => array_slice($this->clientes, $cursor, $limite),
'siguiente' => $hasta < count($this->clientes) ? $hasta : null,
];
}
}
/** @implements IteratorAggregate<int, Cliente> */
final readonly class ClientesCrm implements IteratorAggregate
{
public function __construct(private ApiCrm $api, private int $limite = 2) {}
public function getIterator(): Generator
{
$cursor = 0;
do {
$pagina = $this->api->listarClientes($this->limite, $cursor);
yield from $pagina['datos'];
$cursor = $pagina['siguiente'];
} while ($cursor !== null);
}
}
$crm = new ApiCrm();
foreach (new ClientesCrm($crm) as $cliente) {
echo $cliente->nombre, "\n";
}
echo "Peticiones a la API: {$crm->peticiones}\n"; // 3
$otroCrm = new ApiCrm();
foreach (new ClientesCrm($otroCrm) as $cliente) {
if ($cliente->id === 2) break;
}
echo "Peticiones a la API: {$otroCrm->peticiones}\n"; // 1