Empty Collection Return¶

API contract — instantiates First-Class Absence Modeling

Makes 'nothing found' return an empty collection of the right type rather than null, so every caller can iterate without a special case.

Version: v1 · 2026-08-24 · History
Mechanism #: 3116
Type: Api Contract
Form family: Rule, Policy & Commitment
Solution family: Representation & Modeling
Problem family: Representation, Classification & Model Misfit
Problem subfamily: Ontology, Identity, State & Part–Whole Modeling
Origin domain: Computer Science & Software Engineering
Instantiates: First-Class Absence Modeling

Empty Collection Return is a contract, not a value: any function that can find nothing returns an empty collection of its declared type — never null, never an exception thrown to signal "no results." Its defining idea is that absence is delivered in the same shape as presence, so the caller writes exactly one code path for both. Where Empty Set Literal is the empty value itself, this mechanism is the convention about returning it: a promise made by every method signature that the reader can loop over the result without first asking whether it exists. And unlike Option or Maybe Type, which models a single value that may be absent, the contract here governs the zero-or-many case — a list, set, or map that may simply have no members.

Example¶

An e-commerce backend exposes orderRepository.findByCustomer(id): List<Order>. A brand-new customer has placed nothing. If the method returned null, every one of its dozens of callers would need a ?. guard, and the one place a developer forgets it fails with a null-pointer exception at 2 a.m. Under the empty-collection contract, findByCustomer returns emptyList(). Now for (order in orders) runs zero times, orders.sumOf { it.total } yields 0, and orders.isEmpty() cleanly drives the "no orders yet" view. The empty list then propagates through the mapping and filtering pipeline unchanged; only at the service boundary does a policy decide whether empty is expected (a new customer — fine) or anomalous (a long-standing account that should have orders — raise an alert). The outcome: one uniform result shape, no null branch anywhere, and a single deliberate decision about when emptiness is worth escalating.

How it works¶

Return-type discipline. The method's signature returns the collection type unconditionally; "no results" is expressed as the empty instance of that type, so callers never receive null.
Total operations. Iteration, map, filter, and forEach over the empty collection are well-defined no-ops, which is what removes the special case at every call site.
Propagation, then escalation. The empty collection flows downstream unchanged by default; a boundary policy names the specific contexts in which emptiness stops being routine and must trigger a warning, a fallback, or an alert.

Tuning parameters¶

Mutable vs. immutable empty — returning a shared immutable emptyList() singleton is cheapest and safest; a fresh mutable empty is needed only when the caller will add to it.
Escalation boundary — where you draw the line between "empty is fine, pass it on" and "empty here is suspicious, alert." Draw it too eagerly and you cry wolf; too late and a masked failure sails through.
Metadata carried — whether the empty result travels bare or with context. Bare is simplest; if consumers need to know the query ran, that is a job for Zero-Row Result with Schema, not this contract.
Exception boundary — which conditions still throw (a genuine failure) versus return empty (a legitimate no-result). Blurring the two is the central hazard below.

When it helps, and when it misleads¶

Its strength is that it deletes an entire class of bug: the null check. A codebase that guarantees empty-not-null never suffers the null-reference dereference that Tony Hoare famously called his "billion-dollar mistake."^[1] Callers get shorter, flatter code, and emptiness composes through pipelines instead of exploding them.

Its failure mode is masked failure: a catch block that swallows an error and returns emptyList() to look healthy makes a broken query indistinguishable from a genuinely empty one. The empty collection can report that there is nothing but never why — it has no room for a cause. The guarding discipline is to reserve the empty return for true no-result cases, never for swallowed exceptions, and to pair it with an explicit reason channel — an Absence Reason Enum — wherever a consumer must tell "found nothing" from "failed."

How it implements the components¶

operation_behavior_rule — fixes how iteration, mapping, and filtering behave on the returned empty collection: total, and a safe no-op.
propagation_and_escalation_policy — specifies when the empty result flows downstream untouched and when a boundary must convert it, warn, or escalate.
type_or_schema_inclusion — the empty result is the same declared collection type as a populated one, so no caller needs a separate handler.

It does not define the empty value's algebra or its set-membership status — aggregation_identity_rule, membership_boundary — that belongs to Empty Set Literal, the value this contract hands back.

Instantiates: First-Class Absence Modeling — this contract is the discipline of delivering absence in the ordinary result shape.
Consumes: Empty Set Literal supplies the empty value the contract returns.
Sibling mechanisms: Empty Set Literal · Zero-Row Result with Schema · Option or Maybe Type · Null Object Pattern · No-Op Command · Absence Reason Enum · Empty-State Message · Identity Element Test · Sentinel Value Retirement

Editorial Notes¶

Form Classification¶

Form family: Rule, Policy & Commitment

Rationale: Empty Collection Return operates as a standing rule, threshold, contractual commitment, or policy constraint governing future conduct because it makes 'nothing found' return an empty collection of the right type rather than null, so every caller can iterate without a special case.

Independent corroboration: The frozen evidence defines Empty Collection Return as 'Makes 'nothing found' return an empty collection of the right type rather than null, so every caller can iterate without a special case', so its operative form is Rule, Policy & Commitment.

Review outcome: Independent reviewer agreement; high confidence.

Origin Attribution¶

Primary origin: Computer Science & Software Engineering

Origin pattern: Single lineage

Present-day reach: Specialized

Rationale: API and programming-language design cohered the empty typed collection as a first-class return value that preserves iteration and avoids null special cases.