TO_SYMBOL

Well-known symbol for the lazy-symbol-creation protocol used by external library descriptors. Objects implementing [TO_SYMBOL]() are recognized as LibrarySymbolReference values that can be passed anywhere a refkey is accepted.

TO_SYMBOL: unique symbol

Remarks

Implement [TO_SYMBOL]() on a descriptor object to register it as a referenceable library symbol. Inside the method:

1. Call Binder context accessor to get the current binder context.
2. Look up (or create) the symbol for that binder in a WeakMap<object, OutputSymbol> (use a sentinel object for the no-binder case, since WeakMap keys must be objects).
3. On first creation, construct the symbol and register it into the appropriate space for your library, passing { binder } (see [unresolved link]).

The method is called by language package code each time the descriptor is used as a reference (e.g. inside ref()). It is NOT called by the binder itself.

Example

const defaultKey = {};
const symbols = new WeakMap<object, MySymbol>();
const descriptor: LibrarySymbolReference = {
  [REFKEYABLE]() {
    return descriptor[TO_SYMBOL]().refkeys[0];
  },
  [TO_SYMBOL]() {
    const binder = useBinder();
    const key = binder ?? defaultKey;
    let sym = symbols.get(key);
    if (!sym) {
      sym = new MySymbol("SomeType", space, { binder });
      symbols.set(key, sym);
    }
    return sym;
  },
};