"The Billion-Dollar Fix" — Null Safety and the Type System

java.lang.NullPointerException: getDescription(...) must not be null
    at com.shelfwise.catalog.importer.TitlesKt.shelfTitle(Titles.kt:6)

// Fragment of story/Incident.kt
// The line from the staging crash: no '?', no '!!', and still a NullPointerException.
fun shelfTitle(item: SupplierItem): String = item.description.uppercase()

import java.util.Optional
import kotlin.jvm.optionals.getOrNull

// A Java API that returns Optional, as many repositories and clients do.
fun findPromotionCode(sku: String): Optional<String> =
    if (sku == "SUP-7781") Optional.of("DIWALI10") else Optional.empty()

fun main() {
    // getOrNull() turns Optional<T> into T?, and from there the null operators take over.
    val code: String? = findPromotionCode("SUP-7782").getOrNull()
    println(code ?: "no promotion") // -> no promotion
    println(findPromotionCode("SUP-7781").getOrNull()?.lowercase()) // -> diwali10
}

class Promotion(val code: String, val percentOff: Int)

class Product(val name: String, val promotion: Promotion?, val brand: String?)

fun main() {
    val ghee = Product("Desi Ghee 1L", Promotion("DIWALI10", 10), brand = null)
    val rice = Product("Sona Masoori 5kg", promotion = null, brand = "Shelfwise Basics")

    // val code: String = ghee.promotion.code  // error: only safe (?.) or non-null asserted (!!.) calls are allowed on a nullable receiver of type 'Promotion?'.

    // ?. : call if not null, otherwise the whole expression is null.
    println(ghee.promotion?.code) // -> DIWALI10
    println(rice.promotion?.code) // -> null

    // ?: (Elvis): the fallback when the left side is null.
    println(rice.promotion?.percentOff ?: 0) // -> 0
    println(ghee.brand ?: "Unbranded") // -> Unbranded

    // ?.let { } : run a block only for non-null values; 'it' is smart-cast to the non-null type.
    rice.brand?.let { println("Brand page: /brands/${it.lowercase().replace(' ', '-')}") } // -> Brand page: /brands/shelfwise-basics
    ghee.brand?.let { println("never printed") }

    // as? : a cast that yields null instead of throwing ClassCastException.
    val scanned: Any = 8_901_234_567_890L
    val barcode: String? = scanned as? String
    println(barcode ?: "not a string barcode") // -> not a string barcode

    // !! : "I know better". Throws NullPointerException when you don't.
    try {
        println(rice.promotion!!.code)
    } catch (e: NullPointerException) {
        println("NPE, message: ${e.message}") // -> NPE, message: null
    }
}

// Fragment of importer/SupplierImporter.kt
// Step 1: validation returns null for "no valid SKU" instead of throwing.
fun normaliseSku(raw: String?): String? =
    raw?.trim()?.uppercase()?.takeIf { it.matches(Regex("SUP-\\d{4}")) }

@org.jetbrains.annotations.Nullable
public static final String normaliseSku(@org.jetbrains.annotations.Nullable String raw);
  Code:
     0: aload_0
     1: dup
     2: ifnull        71    // raw == null      -> return null
     8: invokestatic  StringsKt.trim(CharSequence)
    14: dup
    15: ifnull        71    // trimmed == null  -> return null
    21: invokevirtual String.toUpperCase(Locale)
    27: invokestatic  Intrinsics.checkNotNullExpressionValue  // see "The checks Kotlin inserts"
    31: ifnull        71
    ...
    56: invokevirtual Regex.matches(CharSequence)
    60: ifeq          67    // takeIf: no match -> null
    63: aload_1
    64: goto          73
    67: aconst_null
    71: pop
    72: aconst_null
    73: areturn

// A non-null parameter is a promise Java callers can break. Kotlin checks it on entry.
fun normalise(sku: String): String = sku.trim().uppercase()

// LegacyCaller.java, in the same module
System.out.println(SkuRulesKt.normalise(" sup-7781 ")); // -> SUP-7781
try {
    SkuRulesKt.normalise(null);
} catch (NullPointerException e) {
    System.out.println(e.getMessage()); // -> Parameter specified as non-null is null: method com.shelfwise.part02.platform.SkuRulesKt.normalise, parameter sku
}

public static final String shelfTitle(SupplierItem item);
  Code:
     0: aload_0
     1: ldc           "item"
     3: invokestatic  Intrinsics.checkNotNullParameter      // entry check
     7: invokevirtual SupplierItem.getDescription()
    10: dup
    11: ldc           "getDescription(...)"
    13: invokestatic  Intrinsics.checkNotNullExpressionValue // platform value used as non-null
    19: invokevirtual String.toUpperCase(Locale)
    23: ldc           "toUpperCase(...)"
    25: invokestatic  Intrinsics.checkNotNullExpressionValue // even the JDK's return value is checked

open class Shelf(open val label: String?)

class Bay(var note: String?)

fun labelLength(shelf: Shelf): Int {
    // if (shelf.label != null) return shelf.label.length
    //   error: smart cast to 'String' is impossible, because 'label' is a property that has an open or custom getter.
    // A subclass could override 'label' with a getter that returns null on the second call.

    // Fix: read it once into a local val. Locals can't change behind your back.
    val label = shelf.label
    return if (label != null) label.length else 0
}

fun noteLength(bay: Bay): Int {
    // if (bay.note != null) return bay.note.length
    //   error: smart cast to 'String' is impossible, because 'note' is a mutable property that could be mutated concurrently.

    // Fix: let the safe-call chain carry the null, or copy to a local as above.
    return bay.note?.length ?: 0
}

fun describe(value: Any?): String {
    // Smart casts flow through conditions: after the null check, 'value' is Any; after 'is', String.
    if (value == null) return "nothing"
    if (value !is String) return "a ${value::class.simpleName}"
    return "text '${value.trim()}'" // smart cast: value is String here
}

fun main() {
    println(labelLength(Shelf("Spices"))) // -> 6
    println(noteLength(Bay(null))) // -> 0
    println(describe(null)) // -> nothing
    println(describe(42)) // -> a Int
    println(describe("  basmati ")) // -> text 'basmati'
}

fun main() {
    val item = SupplierItem("SUP-7781", null, listOf("gluten"))

    // item.description is a platform type, shown by the IDE as String!.
    // Kotlin lets you treat it as either String or String?, and checks nothing at compile time.

    // Option 1, the safe one: declare it nullable at the boundary and handle the null in Kotlin.
    val description: String? = item.description
    println(description ?: "(no description)") // -> (no description)

    // Option 2: declare it non-null. Kotlin inserts a check right here, so a null fails
    // at the boundary instead of three calls later.
    try {
        val strict: String = item.description
        println(strict)
    } catch (e: NullPointerException) {
        println(e.message) // -> getDescription(...) must not be null
    }

    // Option 3, the trap: let inference choose. 'inferred' keeps the platform type String!,
    // so nothing is checked here and the null travels on until something dereferences it.
    val inferred = item.description
    println("title: $inferred") // -> title: null
    try {
        println(inferred.length)
    } catch (e: NullPointerException) {
        println(e.message) // -> Cannot invoke "String.length()" because "inferred" is null
    }

    // With JSpecify annotations (@NullMarked package, @Nullable getter) there is no platform type:
    // Kotlin sees String? and the compiler forces you to deal with it.
    val v2 = SupplierItemV2("SUP-7781", null)
    // val title: String = v2.description  // error: initializer type mismatch: expected 'String', actual 'String?'.
    println(v2.description?.uppercase() ?: v2.code) // -> SUP-7781
    println(v2.code.length) // -> 8
}

class SupplierClient(val baseUrl: String)

class PriceSyncJob {
    // Set after construction by a framework or a test's @BeforeEach; never null once set.
    lateinit var client: SupplierClient

    // Computed on first access, then cached. Thread-safe by default. (Part 6 covers delegates.)
    val pilotStores: List<String> by lazy {
        println("loading pilot stores")
        listOf("PUN-014", "BLR-003")
    }

    // Genuinely optional: null is a meaningful value ("never ran").
    var lastRunSummary: String? = null

    fun describe(): String =
        if (::client.isInitialized) "client at ${client.baseUrl}" else "no client yet"

    // lateinit var retries: Int  // error: 'lateinit' modifier is not allowed on properties of primitive types.
    // lateinit val region: String  // error: 'lateinit' modifier is allowed only on mutable properties.
}

fun main() {
    val job = PriceSyncJob()
    println(job.describe()) // -> no client yet

    try {
        println(job.client.baseUrl)
    } catch (e: UninitializedPropertyAccessException) {
        println(e.message) // -> lateinit property client has not been initialized
    }

    job.client = SupplierClient("https://supplier.example/api")
    println(job.describe()) // -> client at https://supplier.example/api

    println(job.pilotStores.size) // -> loading pilot stores
    // -> 2
    println(job.pilotStores.first()) // -> PUN-014
    println(job.lastRunSummary ?: "never ran") // -> never ran
}

// Nothing: the return type of a function that never returns normally.
fun fail(reason: String): Nothing = throw IllegalArgumentException(reason)

fun parseSku(raw: String?): String {
    // Because fail() returns Nothing, the Elvis expression has type String, not String?.
    val sku = raw?.trim()?.takeIf { it.isNotEmpty() } ?: fail("blank SKU")
    return sku.uppercase()
}

fun parseQuantity(raw: String): Int {
    // error() is the standard library's fail(): it throws IllegalStateException and returns Nothing.
    val quantity = raw.toIntOrNull() ?: error("not a number: '$raw'")
    // 'if' with a throwing branch still has type Int: throw is an expression of type Nothing.
    return if (quantity >= 0) quantity else throw IllegalArgumentException("negative: $quantity")
}

fun main() {
    println(parseSku("  sup-7781 ")) // -> SUP-7781
    try {
        parseSku("   ")
    } catch (e: IllegalArgumentException) {
        println(e.message) // -> blank SKU
    }
    try {
        parseQuantity("twelve")
    } catch (e: IllegalStateException) {
        println(e.message) // -> not a number: 'twelve'
    }

    // Any is the root of non-null types; Any? is the root of everything.
    val things: List<Any?> = listOf("rice", 5, null)
    println(things.map { it?.javaClass?.simpleName ?: "null" }) // -> [String, Integer, null]
    // things.first()!!.getClass()  // error: unresolved reference 'getClass' on receiver of type 'Any'.
}

fun main() {
    // Nullable Ints are java.lang.Integer objects, with Java's -128..127 cache.
    val smallA: Int? = 100
    val smallB: Int? = 100
    val bigA: Int? = 1000
    val bigB: Int? = 1000
    // The compiler warns on these: identity equality for arguments of types 'Int?' and 'Int?' is prohibited.
    println(smallA === smallB) // -> true
    println(bigA === bigB) // -> false
    println(bigA == bigB) // -> true

    // Arrays are JVM arrays: == compares references (with a compiler warning). Use contentEquals.
    val todayCounts = intArrayOf(12, 0, 7)
    val expected = intArrayOf(12, 0, 7)
    println(todayCounts.contentEquals(expected)) // -> true
    println(todayCounts.contentToString()) // -> [12, 0, 7]

    // is / !is: instanceof that also smart-casts.
    val payload: Any = listOf("gluten", "nuts")
    if (payload is List<*> && payload.isNotEmpty()) println("${payload.size} allergens") // -> 2 allergens
    println(payload !is String) // -> true
}

// Fragment of importer/SupplierImporter.kt
class ImportedProduct(val sku: String, val title: String, val allergens: List<String>) {
    override fun toString() = "$sku | $title | allergens=$allergens"
}

class ImportReport {
    val imported = mutableListOf<ImportedProduct>()
    val rejected = mutableListOf<String>()
}

// Fragment of importer/SupplierImporter.kt
// Step 2: every platform value gets an explicit Kotlin type at the boundary.
fun titleFor(item: SupplierItem, sku: String): String {
    val description: String? = item.description // String! stops here
    return description?.trim()?.takeIf { it.isNotEmpty() } ?: "Uncatalogued item $sku"
}

// A Java List<String> is (Mutable)List<String!>!: the list and each element may be null.
fun allergensOf(item: SupplierItem): List<String> {
    val raw: List<String?>? = item.allergens
    return raw.orEmpty().filterNotNull().map { it.lowercase() }
}

// Fragment of importer/SupplierImporter.kt
// Step 3: the import loop. After the null check, 'sku' is smart-cast to String.
fun importAll(items: List<SupplierItem>): ImportReport {
    val report = ImportReport()
    for (item in items) {
        val sku = normaliseSku(item.code)
        if (sku == null) {
            report.rejected += "rejected code '${item.code}'"
            continue
        }
        report.imported += ImportedProduct(sku, titleFor(item, sku), allergensOf(item))
    }
    return report
}

// Fragment of importer/SupplierImporter.kt
fun main() {
    val feed = listOf(
        SupplierItem(" sup-7781 ", "Durum Wheat Penne 500g", listOf("Gluten")),
        SupplierItem("SUP-7782", null, null), // not catalogued yet, allergens unknown
        SupplierItem("SUP-7783", "  ", listOf("Milk", null, "Soy")), // blank text, a null element
        SupplierItem(null, "Mystery Item", listOf()), // no code at all
    )

    val report = importAll(feed)
    for (product in report.imported) println(product)
    // -> SUP-7781 | Durum Wheat Penne 500g | allergens=[gluten]
    // -> SUP-7782 | Uncatalogued item SUP-7782 | allergens=[]
    // -> SUP-7783 | Uncatalogued item SUP-7783 | allergens=[milk, soy]
    println(report.rejected) // -> [rejected code 'null']
}