Return Literal::Undefined from collection lookups, never a fabricated nil

Any `Literal::Hash` or `Literal::Array` method that promises an element
now returns the element or `Literal::Undefined` — a missing key, an
out-of-bounds index, an empty array, or a value that isn't found never
fabricates a nil the type doesn't permit. `#[]` accepts a fetch-style
fallback block (`hash[key] { fallback }`) that fires only on the
undefined case; bare `fetch` still raises, so the two spellings stay
distinct. Backing hash defaults are no longer consulted, since a
`default_proc` could leak values the types never checked.

`Literal::Tuple#[]` instead raises `IndexError` out of bounds, mirroring
`#[]=`: a tuple's length is part of its type, so there is no missing
case. Range lookups, which leaked an untyped `Array`, now raise too.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: joeldrapper

lib/literal/array.rb

@@ -12,6 +12,12 @@
 #
 # The element type is fixed at construction and never changes in place — it can
 # neither be widened nor narrowed. `narrow` and `widen` return new instances.
+#
+# Methods that promise an element return `Literal::Undefined` when there is no
+# element to return — an out-of-bounds index, an empty array, a value that
+# isn't found — never `nil`. `nil` only ever appears when the element type
+# actually permits it. For a per-lookup fallback, pass a block —
+# `array[index] { fallback }` — or use `fetch` to raise on a missing index.
 class Literal::Array
 	class Generic
 		include Literal::Type
@@ -142,19 +148,24 @@ def ==(other)
 		Literal::Array === other && @__value__ == other.__value__
 	end
 
-	def [](index, length = nil)
-		if length
-			slice = @__value__[index, length]
-			slice && __with__(slice)
+	# Returns the element or slice. When there is nothing at the index — out of
+	# bounds, or a slice starting beyond the end — yields the index to the block
+	# if one is given, and returns `Literal::Undefined` otherwise.
+	def [](index, length = nil, &fallback)
+		slice = if length
+			@__value__[index, length]
+		elsif Range === index
+			@__value__[index]
 		else
-			case index
-			when Range
-				slice = @__value__[index]
-				slice && __with__(slice)
-			else
-				@__value__[index]
-			end
+			return @__value__.fetch(index, &fallback) if fallback
+
+			return @__value__.fetch(index) { Literal::Undefined }
 		end
+
+		return __with__(slice) if slice
+		return yield(index) if fallback
+
+		Literal::Undefined
 	end
 
 	def []=(index, value)
@@ -206,16 +217,22 @@ def count(...)
 		@__value__.count(...)
 	end
 
-	def delete(...)
-		@__value__.delete(...)
+	def delete(value, &block)
+		return @__value__.delete(value, &block) if block
+
+		@__value__.delete(value) { Literal::Undefined }
 	end
 
-	def delete_at(...)
-		@__value__.delete_at(...)
+	def delete_at(index)
+		@__value__.fetch(index) { return Literal::Undefined }
+
+		@__value__.delete_at(index)
 	end
 
-	def dig(...)
-		@__value__.dig(...)
+	def dig(index, *indexes)
+		@__value__.fetch(index) { return Literal::Undefined }
+
+		@__value__.dig(index, *indexes)
 	end
 
 	def drop(n)
@@ -254,7 +271,10 @@ def filter_map(type, &block)
 	end
 
 	def first(n = nil)
-		n ? __with__(@__value__.first(n)) : @__value__.first
+		return __with__(@__value__.first(n)) if n
+		return Literal::Undefined if @__value__.empty?
+
+		@__value__.first
 	end
 
 	def flat_map(type, &block)
@@ -319,7 +339,10 @@ def join(...)
 	end
 
 	def last(n = nil)
-		n ? __with__(@__value__.last(n)) : @__value__.last
+		return __with__(@__value__.last(n)) if n
+		return Literal::Undefined if @__value__.empty?
+
+		@__value__.last
 	end
 
 	def map(type, &block)
@@ -354,23 +377,35 @@ def map!(&block)
 	end
 
 	def max(n = nil, &)
-		n ? __with__(@__value__.max(n, &)) : @__value__.max(&)
+		return __with__(@__value__.max(n, &)) if n
+		return Literal::Undefined if @__value__.empty?
+
+		@__value__.max(&)
 	end
 
 	def max_by(n = nil, &block)
 		raise ArgumentError.new("#max_by requires a block.") unless block
 
-		n ? __with__(@__value__.max_by(n, &block)) : @__value__.max_by(&block)
+		return __with__(@__value__.max_by(n, &block)) if n
+		return Literal::Undefined if @__value__.empty?
+
+		@__value__.max_by(&block)
 	end
 
 	def min(n = nil, &)
-		n ? __with__(@__value__.min(n, &)) : @__value__.min(&)
+		return __with__(@__value__.min(n, &)) if n
+		return Literal::Undefined if @__value__.empty?
+
+		@__value__.min(&)
 	end
 
 	def min_by(n = nil, &block)
 		raise ArgumentError.new("#min_by requires a block.") unless block
 
-		n ? __with__(@__value__.min_by(n, &block)) : @__value__.min_by(&block)
+		return __with__(@__value__.min_by(n, &block)) if n
+		return Literal::Undefined if @__value__.empty?
+
+		@__value__.min_by(&block)
 	end
 
 	def minmax(&)
@@ -431,7 +466,10 @@ def partition(&block)
 	end
 
 	def pop(n = nil)
-		n ? __with__(@__value__.pop(n)) : @__value__.pop
+		return __with__(@__value__.pop(n)) if n
+		return Literal::Undefined if @__value__.empty?
+
+		@__value__.pop
 	end
 
 	# Returns a Literal::Array of Literal::Tuples with every combination of our
@@ -509,7 +547,10 @@ def rotate!(count = 1)
 	end
 
 	def sample(n = nil, random: Random)
-		n ? __with__(@__value__.sample(n, random:)) : @__value__.sample(random:)
+		return __with__(@__value__.sample(n, random:)) if n
+		return Literal::Undefined if @__value__.empty?
+
+		@__value__.sample(random:)
 	end
 
 	def select(&block)
@@ -526,7 +567,10 @@ def select!(&block)
 	end
 
 	def shift(n = nil)
-		n ? __with__(@__value__.shift(n)) : @__value__.shift
+		return __with__(@__value__.shift(n)) if n
+		return Literal::Undefined if @__value__.empty?
+
+		@__value__.shift
 	end
 
 	def shuffle(random: Random)

lib/literal/hash.rb

@@ -13,6 +13,12 @@
 # The key and value types are fixed at construction and never change in place —
 # they can neither be widened nor narrowed. `narrow` and `widen` return new
 # instances.
+#
+# Looking up a missing key returns `Literal::Undefined`, never `nil` — `nil` is
+# only ever a value the value type actually permits. For the same reason, a
+# `Literal::Hash` has no default value machinery: a default could fabricate
+# values the types never checked. For a per-lookup fallback, pass a block —
+# `hash[key] { fallback }` — or use `fetch` to raise on a missing key.
 class Literal::Hash
 	class Generic
 		include Literal::Type
@@ -110,8 +116,12 @@ def ==(other)
 		Literal::Hash === other && @__value__ == other.__value__
 	end
 
-	def [](key)
-		@__value__[key]
+	# Returns the value for the key. For a missing key, yields the key to the
+	# block if one is given, and returns `Literal::Undefined` otherwise.
+	def [](key, &fallback)
+		return @__value__.fetch(key, &fallback) if fallback
+
+		@__value__.fetch(key) { Literal::Undefined }
 	end
 
 	def []=(key, value)
@@ -157,12 +167,16 @@ def compact!
 		self
 	end
 
-	def delete(...)
-		@__value__.delete(...)
+	def delete(key, &block)
+		return @__value__.delete(key, &block) if block
+
+		@__value__.delete(key) { Literal::Undefined }
 	end
 
-	def dig(...)
-		@__value__.dig(...)
+	def dig(key, *keys)
+		return Literal::Undefined unless @__value__.key?(key)
+
+		@__value__.dig(key, *keys)
 	end
 
 	def each(&block)

lib/literal/tuple.rb

@@ -137,8 +137,22 @@ def ==(other)
 		Literal::Tuple === other && @__value__ == other.__value__
 	end
 
+	# Every valid tuple index always holds a value, so lookups never need a
+	# "missing" representation — an index outside the tuple is a programmer
+	# error and raises, exactly like `#[]=`.
 	def [](index)
-		@__value__[index]
+		size = @__value__.size
+		normalized = index
+
+		if (Integer === normalized) && (normalized < 0)
+			normalized += size
+		end
+
+		unless Integer === normalized && normalized >= 0 && normalized < size
+			raise IndexError.new("Index #{index.inspect} is out of bounds for a tuple of size #{size}.")
+		end
+
+		@__value__[normalized]
 	end
 
 	def []=(index, value)

test/array.test.rb

@@ -219,21 +219,26 @@ def refute_shared_storage(a, b)
 
 	assert_equal array[0], 1
 	assert_equal array[-1], 3
-	assert_equal array[3], nil
+	assert_equal array[3], Literal::Undefined
+	assert_equal array[3] { |index| index }, 3
+	assert_equal array[0] { |index| index }, 1
 end
 
 test "#[] with a range returns a typed sub-array" do
 	array = Literal::Array(Integer).new(1, 2, 3)
 
 	assert_literal_array array[0..1], type: Integer, values: [1, 2]
 	assert_literal_array array[2..], type: Integer, values: [3]
-	assert_equal array[5..], nil
+	assert_equal array[5..], Literal::Undefined
+	assert_equal array[5..] { :fallback }, :fallback
 end
 
 test "#[] with a start and length returns a typed sub-array" do
 	array = Literal::Array(Integer).new(1, 2, 3)
 
 	assert_literal_array array[1, 2], type: Integer, values: [2, 3]
+	assert_equal array[5, 2], Literal::Undefined
+	assert_equal array[5, 2] { :fallback }, :fallback
 end
 
 test "#fetch" do
@@ -250,7 +255,8 @@ def refute_shared_storage(a, b)
 
 	assert_equal array.first, 1
 	assert_equal array.last, 3
-	assert_equal Literal::Array(Integer).new.first, nil
+	assert_equal Literal::Array(Integer).new.first, Literal::Undefined
+	assert_equal Literal::Array(Integer).new.last, Literal::Undefined
 end
 
 test "#first and #last return typed arrays with an argument" do
@@ -827,6 +833,28 @@ def refute_shared_storage(a, b)
 	assert_equal array.to_a, [3]
 end
 
+test "element lookups return Literal::Undefined when there is no element, never nil" do
+	empty = Literal::Array(Integer).new
+	nilable = Literal::Array(_Nilable(Integer)).new(nil)
+
+	assert_equal empty.pop, Literal::Undefined
+	assert_equal empty.shift, Literal::Undefined
+	assert_equal empty.sample, Literal::Undefined
+	assert_equal empty.min, Literal::Undefined
+	assert_equal empty.max, Literal::Undefined
+	assert_equal empty.min_by(&:itself), Literal::Undefined
+	assert_equal empty.max_by(&:itself), Literal::Undefined
+	assert_equal empty.delete(1), Literal::Undefined
+	assert_equal empty.delete(1) { |element| element }, 1
+	assert_equal empty.delete_at(0), Literal::Undefined
+	assert_equal empty.dig(0, 0), Literal::Undefined
+
+	# A nil element is a real element, so it is returned as itself.
+	assert_equal nilable.first, nil
+	assert_equal nilable[0], nil
+	assert_equal nilable.pop, nil
+end
+
 test "#pop and #shift return elements without an argument" do
 	array = Literal::Array(Integer).new(1, 2, 3)
 

test/hash.test.rb

@@ -128,7 +128,7 @@ def assert_literal_hash(hash, key_type:, value_type:, entries:)
 	hash = Literal::Hash(Symbol, Integer).new({ a: 1, b: 2 })
 
 	assert_equal hash[:a], 1
-	assert_equal hash[:c], nil
+	assert_equal hash[:c], Literal::Undefined
 	assert_equal hash.fetch(:b), 2
 	assert_equal hash.fetch(:c, 3), 3
 	assert_raises(KeyError) { hash.fetch(:c) }
@@ -143,6 +143,31 @@ def assert_literal_hash(hash, key_type:, value_type:, entries:)
 	assert Literal::Hash(Symbol, Integer).new.empty?
 end
 
+test "#[] yields the key to a given block when it is missing" do
+	hash = Literal::Hash(Symbol, Integer).new({ a: 1 })
+
+	assert_equal hash[:a] { |key| key }, 1
+	assert_equal hash[:b] { |key| key }, :b
+	assert_equal hash[:b] { 0 }, 0
+end
+
+test "looking up a missing key returns Literal::Undefined, distinct from a nil value" do
+	hash = Literal::Hash(Symbol, _Nilable(Integer)).new({ a: nil })
+
+	assert_equal hash[:a], nil
+	assert_equal hash[:b], Literal::Undefined
+	assert_equal hash.dig(:b, :deeper), Literal::Undefined
+end
+
+test "a backing hash's default value never leaks through lookups" do
+	# The default was never type checked, so honoring it would break the
+	# guarantee that lookups only return values the value type permits.
+	hash = Literal::Hash(Symbol, Integer).new(Hash.new("unchecked").merge(a: 1))
+
+	assert_equal hash[:b], Literal::Undefined
+	assert_equal hash.dig(:b, :deeper), Literal::Undefined
+end
+
 test "#each yields pairs and returns self" do
 	hash = Literal::Hash(Symbol, Integer).new({ a: 1, b: 2 })
 	yielded = []
@@ -317,10 +342,17 @@ def assert_literal_hash(hash, key_type:, value_type:, entries:)
 	hash = Literal::Hash(Symbol, Integer).new({ a: 1 })
 
 	assert_equal hash.delete(:a), 1
-	assert_equal hash.delete(:a), nil
+	assert_equal hash.delete(:a), Literal::Undefined
 	assert hash.empty?
 end
 
+test "#delete yields the key to a given block when it is missing" do
+	hash = Literal::Hash(Symbol, Integer).new({ a: 1 })
+
+	assert_equal hash.delete(:b) { |key| key }, :b
+	assert_equal hash.delete(:a) { |key| key }, 1
+end
+
 test "#select!, #reject!, #compact! and #clear return self" do
 	hash = Literal::Hash(Symbol, _Nilable(Integer)).new({ a: 1, b: 2, c: nil })
 

test/tuple.test.rb

@@ -139,7 +139,9 @@ def assert_type_equal(actual, expected)
 
 	assert_equal tuple[0], "a"
 	assert_equal tuple[-1], 1
-	assert_equal tuple[2], nil
+	assert_raises(IndexError) { tuple[2] }
+	assert_raises(IndexError) { tuple[-3] }
+	assert_raises(IndexError) { tuple[0..1] }
 	assert_equal tuple.fetch(1), 1
 	assert_raises(IndexError) { tuple.fetch(2) }
 	assert_equal tuple.first, "a"