Skip to content

CEP-0018: Contextful Iterator Families

Draft

Draft proposal for iterator contracts whose step operation requires explicit external context. V1 canonical Iterator(Item) remains context-free.

Summary

Catalyst should add contextful iterator families as separate contracts instead of adding hidden ambient context to canonical iteration.

Example

Possible future shape:

fn ContextIterator(comptime Item: Type, comptime Context: Type) => contract {
  fn next(self: *Self, ctx: Context) ?Item
}

The exact name is deferred. The important rule is that a contextful step takes ordinary parameters, and any loop form that uses it must show the context at the loop site.

Motivation

Some iterators need additional authority or state for each step: allocation, diagnostics, IO, decode tables, cancellation, or policy context. V1 canonical Iterator(Item) intentionally has no hidden contextual authority.

Contextful iteration needs an explicit contract family so ordinary for item in iter remains predictable and allocation/context-free.

Proposed Direction

Contextful stepping should use a separate future contract family. Future contextful iterator loops must not discover context implicitly from local variables, names such as ctx, destructured parameters, module state, or ambient authority.

If a loop supports contextful stepping, the context argument must be visible in source.

V1 Compatibility

V1 for loop-source selection stays tied to context-free Iterator(Item) and Iterable(Item) unless a later loop form explicitly supplies context.