we need a utility for unwrapping tracked properties

[NullVoxPopuli]

This should probably live in starbeam or something (eventually), but the problem is shown here, in the docs: https://github.com/NullVoxPopuli/ember-resources/blob/main/docs/docs/ember.md#for-library-authors

This looks like a lot, and generally library authors are used to jumping through hoops to making things nice for their users, but we should strive to make things as easy as possible for library authors as well.

Specifically, this code

    let input = typeof markdownText === 'function' ? markdownText() : markdownText;
    let maybeObject = 
      typeof maybeOptions === 'function' ? maybeOptions() : maybeOptions;

but the gist is that, in order to have lazily evaluated reactive properties, we need to pass functions.
the Cell concepts gets around this by lazily evaluating upon access of .current (or .read()), but @tracked properties don't have these capabilities.

For this example, the call-site may look like this:

class X {
  @tracked text = '...';
  @tracked format = 'gjs';
  
  @use compiled = Compiled(() => this.text, () => this.format);
  // or
  @use compiled = Compiled(() => this.text, () => ({ format: this.format });
  // or
  compiled = use(this, Compiled( ... ))
}

The way @tracked properties are fine-grainedly consumed in a resource API is entirely up to the resource-author -- they can choose how fine-grained they want their arguments to be.

So, to help, we should provide a utility, which would turn the above snippet in to this:

import { unwrap } from 'ember-resources/unwrap';

// ...

    let input = unwrap(markdownText);
    let maybeObject = unwrap(maybeOptions);

Thanks @simonihmig for pushing me on this 🎉

[NullVoxPopuli]

Also,

type Arg<T> = T | (() => T)

So that they 5 overloads can be compacted to:

export function buildCompiler(markdownText: Arg<Input>, options?: Arg<Format | ExtraOptions>): State;

This would be a utility type that library authors would use to ... not have a ton of overloads.

Combined with unwrap, it makes managing the args, pretty easy, I think

Questions:

• how do you handle with T is a function?