[RFC] @external decorator rework to define module exports?

[jtenner]

Under direction of @dcodeIO I would like to open up discussion for changing the behavior of a decorator. Currently, the only way to define exports is by explicitly exporting something from the entry file.

export function add(a: i32, b: i32): i32 {
  return a + b;
}

It would be useful for some developers when consuming an AssemblyScript library from npm to have some functions automatically exported for convenience using the @external decorator.

Currently, the @external decorator is used to define imported functions like this.

@external("Math", "random")
declare function random(): f64;

Calling this declared random() function will actually call the imported function provided to the WebAssembly module. However, the @external behavior for AssemblyScript defined functions is currently undefined. We can instead use it to define a forced export like this.

@external("imageLoaded")
function imageLoadedInternal(img: Image, width: i32, height: i32): void {
  // do something with the image reference
}

Then it would be usable from the host under the name imageLoaded.

const wasm = instantiateBuffer(buffer, imports);
// obtain an image reference
var imgPointer = wasm.createImage();
// call the internal function
wasm.imageLoaded(imgPointer, 100, 200);

Note, these sorts of exports are best placed inside downstream libraries, because it's not a great user experience for developers to have to manually export downstream glue code functions like this.

// we could avoid ugly exports like this
export { imageLoaded } from "node_modules/myLib/assembly/index";

We could also avoid having to need to define additional entry points for the asc compiler. Currently, this is how https://github.com/as2d/as2d-example/ works.

asc assembly/index.ts node_modules/as2d/assembly/glue.ts -b build/optimized.wasm -t build/optimized.wat --sourceMap --validate --optimize --use Math=JSMath

Any thoughts?

[MaxGraey]

Personally I'm not fan of this approach in several reasons. First of all this break portability. It also makes it harder to clear the code. Usually we just need check root's index.ts for figure outing which actually methods exposed to host. In your scenario it could be much harder do this and require documentation which could be missed or not well synced with actual codebase

[dcodeIO]

For perspective: One situation where this can be useful in is if you ship both an AS library and a respective JS glue, while allowing a user to write their own program that uses your library, but is then intended to be used with your JS glue. Currently, you have to tell the user to reexport all the helpers the AS library needs, or instruct the user to include another entry file.

I agree though that providing this as an option might as well lead to overuse of @external in situations that do not actually require it, unnecessarily complicating things. Hmm...

[MaxGraey]

Basically all this could be resolved if we have our own asconfig.json I guess. In config we also could add some set of forced exported functions like:

{
   "compiler": {
      "target": "wasm",
      "opt-level": 3
   },
   "includes": { // optional
       "assembly/index.ts",
       "glue/code.ts"
   },
   "exports": { // optinal
      "imageLoaded",
      "patternFill"
   }
}

[jtenner]

I want to make sure this discussion is honest. If you can control the imports, then all you have to do is import a function that accepts function pointers.

const imports =  {
  __canvas_sys: {
    functionPointers(imageLoaded: number): void {
      wasm.imageLoaded = wasm.getFunction(imageLoaded).bind(wasm);
    }
  }
}

In typescript, simply link to that function and return a pointer to that function.

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[jtenner]

This is not actually an issue. Any time I need to control an export from a library, it's much easier to include a single file when the binary is compiled. If I need to dynamically export a function, it can be done by returning a function pointer. This is a non-issue. Should we close this?

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.