Document memoize (maybe lazySelfie?)

[nedtwigg]

Use https://github.com/aallam/openai-kotlin as an example.

Might want to change our navbar to be:

• why
• get started
• memoize
• facets

or

• why
• get started
• lazy
• facets

Might also want to change the landing page, maybe: literal, lensable, lazy, and like a filesystem.

The function name lazy is already taken by kotlin-stdlib. Renaming to lazySelfie might be a better fit.

EDIT: landed on cacheSelfie, because memoizing random data is bad, and selfie is good for that.

[nedtwigg]

Possible landing page copy, eventually:

Sometimes a test has a component which is slow, expensive, or non-deterministic. API calls to AI services are all three, for example.

In cases like this, it can be really useful to save the result of a previous execution of the API call, and use that as a mock for future tests.

var client = ExpensiveAiService();
var chatResponse = cacheSelfie(() -> {
  return client.chat("What's your favorite number today?");
}).toBe("Since it's March 14, my favorite number is π")
// build other stuff with the chat response

You can cache simple strings, but you can also cache complex API objects, binary data, or anything else you can serialize to a string or a byte array.

var imageBytes = cacheSelfie(() -> {
  return client.generateImage("A robot making a self portrait");
}).toBeFile("selfie.png")

For more information on how to use cacheSelfie, see the cache example.

[nedtwigg]

• Implemented by Improve cache docs #238