Support memoization

jvm/CHANGELOG.md

@@ -11,6 +11,15 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
+### Added
+- **Memoization** ([#219](https://github.com/diffplug/selfie/pull/219) implements [#215](https://github.com/diffplug/selfie/issues/215))
+  - like `expectSelfie`, all are available as `Selfie.memoize` or as `suspend fun` in `com.diffplug.selfie.coroutines`. 
+```kotlin
+val cachedResult: ByteArray = Selfie.memoizeBinary { dalleJpeg() }.toBePath("example.jpg")
+val cachedResult: String    = Selfie.memoize { someString() }.toBe("what it was earlier")
+val cachedResult: T         = Selfie.memoizeAsJson { anyKotlinxSerializable() }.toBe("""{"key": "value"}""")
+val cachedResult: T         = Selfie.memoizeBinarySerializable { anyJavaIoSerializable() }.toMatchDisk()
+```
 
 ## [1.2.0] - 2024-02-12
 ### Added

jvm/gradle/spotless.gradle

@@ -16,8 +16,8 @@ spotless {
             target 'src/**/*.kt'
             licenseHeaderFile 干.file("spotless/license-${license}.java")
             ktfmt()
-            for (modifier in ['', 'override ', 'public ', 'protected ', 'private ', 'internal ', 'infix ', 'expected ', 'actual ', 'suspend ']) {
-                for (key in ['inline', 'fun', 'abstract fun', 'val', 'override']) {
+            for (modifier in ['', 'override ', 'public ', 'protected ', 'private ', 'internal ', 'infix ', 'expected ', 'actual ']) {
+                for (key in ['inline', 'fun', 'abstract fun', 'suspend fun', 'val', 'override']) {
                     String toCheck = "$modifier$key"
                     replaceRegex("dense $toCheck", "\n\n(\\s*)$toCheck ", "\n\$1$toCheck ")
                 }

jvm/selfie-lib/build.gradle

@@ -26,11 +26,16 @@ kotlin {
     nodejs()
   }
   sourceSets {
-    commonMain {}
+    commonMain {
+      dependencies {
+        compileOnly("org.jetbrains.kotlinx:kotlinx-serialization-json:1.6.2")
+      }
+    }
     commonTest {
       dependencies {
         implementation kotlin('test')
         implementation("io.kotest:kotest-assertions-core:$ver_KOTEST")
+        implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.6.2")
       }
     }
   }

jvm/selfie-lib/src/commonMain/kotlin/com/diffplug/selfie/MemoBinary.kt

@@ -0,0 +1,84 @@
+/*
+ * Copyright (C) 2024 DiffPlug
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package com.diffplug.selfie
+
+import com.diffplug.selfie.guts.DiskSnapshotTodo
+import com.diffplug.selfie.guts.DiskStorage
+import com.diffplug.selfie.guts.ToBeFileTodo
+import com.diffplug.selfie.guts.recordCall
+
+class MemoBinary<T>(
+    private val disk: DiskStorage,
+    private val roundtrip: Roundtrip<T, ByteArray>,
+    private val generator: () -> T
+) {
+  fun toMatchDisk(sub: String = ""): T {
+    return toMatchDiskImpl(sub, false)
+  }
+  fun toMatchDisk_TODO(sub: String = ""): T {
+    return toMatchDiskImpl(sub, true)
+  }
+  private fun toMatchDiskImpl(sub: String, isTodo: Boolean): T {
+    val call = recordCall(false)
+    if (Selfie.system.mode.canWrite(isTodo, call, Selfie.system)) {
+      val actual = generator()
+      disk.writeDisk(Snapshot.of(roundtrip.serialize(actual)), sub, call)
+      if (isTodo) {
+        Selfie.system.writeInline(DiskSnapshotTodo.createLiteral(), call)
+      }
+      return actual
+    } else {
+      if (isTodo) {
+        throw Selfie.system.fs.assertFailed(
+            "Can't call `toMatchDisk_TODO` in ${Mode.readonly} mode!")
+      } else {
+        val snapshot =
+            disk.readDisk(sub, call)
+                ?: throw Selfie.system.fs.assertFailed(Selfie.system.mode.msgSnapshotNotFound())
+        if (!snapshot.subject.isBinary || snapshot.facets.isNotEmpty()) {
+          throw Selfie.system.fs.assertFailed(
+              "Expected a binary subject with no facets, got ${snapshot}")
+        }
+        return roundtrip.parse(snapshot.subject.valueBinary())
+      }
+    }
+  }
+  private fun resolvePath(subpath: String) = Selfie.system.layout.rootFolder.resolveFile(subpath)
+  fun toBeFile_TODO(subpath: String): T {
+    return toBeFileImpl(subpath, true)
+  }
+  fun toBeFile(subpath: String): T {
+    return toBeFileImpl(subpath, false)
+  }
+  private fun toBeFileImpl(subpath: String, isTodo: Boolean): T {
+    val call = recordCall(false)
+    val writable = Selfie.system.mode.canWrite(isTodo, call, Selfie.system)
+    if (writable) {
+      val actual = generator()
+      if (isTodo) {
+        Selfie.system.writeInline(ToBeFileTodo.createLiteral(), call)
+      }
+      Selfie.system.fs.fileWriteBinary(resolvePath(subpath), roundtrip.serialize(actual))
+      return actual
+    } else {
+      if (isTodo) {
+        throw Selfie.system.fs.assertFailed("Can't call `toBeFile_TODO` in ${Mode.readonly} mode!")
+      } else {
+        return roundtrip.parse(Selfie.system.fs.fileReadBinary(resolvePath(subpath)))
+      }
+    }
+  }
+}

jvm/selfie-lib/src/commonMain/kotlin/com/diffplug/selfie/MemoString.kt

@@ -0,0 +1,82 @@
+/*
+ * Copyright (C) 2024 DiffPlug
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package com.diffplug.selfie
+
+import com.diffplug.selfie.guts.DiskSnapshotTodo
+import com.diffplug.selfie.guts.DiskStorage
+import com.diffplug.selfie.guts.LiteralString
+import com.diffplug.selfie.guts.LiteralValue
+import com.diffplug.selfie.guts.recordCall
+
+class MemoString<T>(
+    private val disk: DiskStorage,
+    private val roundtrip: Roundtrip<T, String>,
+    private val generator: () -> T
+) {
+  fun toMatchDisk(sub: String = ""): T {
+    return toMatchDiskImpl(sub, false)
+  }
+  fun toMatchDisk_TODO(sub: String = ""): T {
+    return toMatchDiskImpl(sub, true)
+  }
+  private fun toMatchDiskImpl(sub: String, isTodo: Boolean): T {
+    val call = recordCall(false)
+    if (Selfie.system.mode.canWrite(isTodo, call, Selfie.system)) {
+      val actual = generator()
+      disk.writeDisk(Snapshot.of(roundtrip.serialize(actual)), sub, call)
+      if (isTodo) {
+        Selfie.system.writeInline(DiskSnapshotTodo.createLiteral(), call)
+      }
+      return actual
+    } else {
+      if (isTodo) {
+        throw Selfie.system.fs.assertFailed(
+            "Can't call `toMatchDisk_TODO` in ${Mode.readonly} mode!")
+      } else {
+        val snapshot =
+            disk.readDisk(sub, call)
+                ?: throw Selfie.system.fs.assertFailed(Selfie.system.mode.msgSnapshotNotFound())
+        if (snapshot.subject.isBinary || snapshot.facets.isNotEmpty()) {
+          throw Selfie.system.fs.assertFailed(
+              "Expected a string subject with no facets, got ${snapshot}")
+        }
+        return roundtrip.parse(snapshot.subject.valueString())
+      }
+    }
+  }
+  fun toBe_TODO(unusedArg: Any? = null): T {
+    return toBeImpl(null)
+  }
+  fun toBe(expected: String): T {
+    return toBeImpl(expected)
+  }
+  private fun toBeImpl(snapshot: String?): T {
+    val call = recordCall(false)
+    val writable = Selfie.system.mode.canWrite(snapshot == null, call, Selfie.system)
+    if (writable) {
+      val actual = generator()
+      Selfie.system.writeInline(
+          LiteralValue(snapshot, roundtrip.serialize(actual), LiteralString), call)
+      return actual
+    } else {
+      if (snapshot == null) {
+        throw Selfie.system.fs.assertFailed("Can't call `toBe_TODO` in ${Mode.readonly} mode!")
+      } else {
+        return roundtrip.parse(snapshot)
+      }
+    }
+  }
+}

jvm/selfie-lib/src/commonMain/kotlin/com/diffplug/selfie/Roundtrip.kt

@@ -0,0 +1,46 @@
+/*
+ * Copyright (C) 2024 DiffPlug
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package com.diffplug.selfie
+
+interface Roundtrip<T, SerializedForm> {
+  fun serialize(value: T): SerializedForm
+  fun parse(serialized: SerializedForm): T
+
+  companion object {
+    fun <T : Any> identity(): Roundtrip<T, T> = IDENTITY as Roundtrip<T, T>
+    private val IDENTITY =
+        object : Roundtrip<Any, Any> {
+          override fun serialize(value: Any): Any = value
+          override fun parse(serialized: Any): Any = serialized
+        }
+  }
+}
+
+/** Roundtrips the given type into pretty-printed Json. */
+class RoundtripJson<T>(private val strategy: kotlinx.serialization.KSerializer<T>) :
+    Roundtrip<T, String> {
+  private val json =
+      kotlinx.serialization.json.Json {
+        prettyPrint = true
+        prettyPrintIndent = "  "
+      }
+  override fun serialize(value: T): String = json.encodeToString(strategy, value)
+  override fun parse(serialized: String): T = json.decodeFromString(strategy, serialized)
+
+  companion object {
+    inline fun <reified T> of() = RoundtripJson<T>(kotlinx.serialization.serializer())
+  }
+}

jvm/selfie-lib/src/commonMain/kotlin/com/diffplug/selfie/Selfie.kt

@@ -237,6 +237,25 @@ object Selfie {
       writer.toString()
     }
   }
+
+  @JvmStatic fun memoize(toMemoize: () -> String) = memoize(Roundtrip.identity(), toMemoize)
+
+  @JvmStatic
+  fun <T> memoize(roundtrip: Roundtrip<T, String>, toMemoize: () -> T) =
+      MemoString(deferredDiskStorage, roundtrip, toMemoize)
+  /**
+   * Memoizes any type which is marked with `@kotlinx.serialization.Serializable` as pretty-printed
+   * json.
+   */
+  inline fun <reified T> memoizeAsJson(noinline toMemoize: () -> T) =
+      memoize(RoundtripJson.of<T>(), toMemoize)
+
+  @JvmStatic
+  fun memoizeBinary(toMemoize: () -> ByteArray) = memoizeBinary(Roundtrip.identity(), toMemoize)
+
+  @JvmStatic
+  fun <T> memoizeBinary(roundtrip: Roundtrip<T, ByteArray>, toMemoize: () -> T) =
+      MemoBinary<T>(deferredDiskStorage, roundtrip, toMemoize)
 }
 
 /**

jvm/selfie-lib/src/commonMain/kotlin/com/diffplug/selfie/coroutines/Coroutines.kt

@@ -16,6 +16,8 @@
 package com.diffplug.selfie.coroutines
 
 import com.diffplug.selfie.Camera
+import com.diffplug.selfie.Roundtrip
+import com.diffplug.selfie.RoundtripJson
 import com.diffplug.selfie.Selfie
 import com.diffplug.selfie.Snapshot
 import com.diffplug.selfie.guts.CoroutineDiskStorage
@@ -53,3 +55,16 @@ suspend fun preserveSelfiesOnDisk(vararg subsToKeep: String) {
     subsToKeep.forEach { disk.keep(it) }
   }
 }
+suspend fun memoize(toMemoize: suspend () -> String) = memoize(Roundtrip.identity(), toMemoize)
+suspend fun <T> memoize(roundtrip: Roundtrip<T, String>, toMemoize: suspend () -> T) =
+    MemoStringSuspend(disk(), roundtrip, toMemoize)
+/**
+ * Memoizes any type which is marked with `@kotlinx.serialization.Serializable` as pretty-printed
+ * json.
+ */
+suspend inline fun <reified T> memoizeAsJson(noinline toMemoize: suspend () -> T) =
+    memoize(RoundtripJson.of<T>(), toMemoize)
+suspend fun memoizeBinary(toMemoize: suspend () -> ByteArray) =
+    memoizeBinary(Roundtrip.identity(), toMemoize)
+suspend fun <T> memoizeBinary(roundtrip: Roundtrip<T, ByteArray>, toMemoize: suspend () -> T) =
+    MemoBinarySuspend(disk(), roundtrip, toMemoize)