docs(transpile): use writeFiles in README, add examples

Author: vados-cosmonic

packages/jco-transpile/README.md

@@ -16,29 +16,22 @@ and `jco` derives it's use of transpilation from this library.
 
 To use `@bytecodealliance/jco-transpile` as a library in your own code, you can use some of the exported functions.
 
+Check out our [examples on GitHub][gh-examples].
+
+[gh-examples]: https://github.com/bytecodealliance/jco/tree/main/examples/transpile
+
 ## Transpiling
 
 To transpile an existing WebAssembly component (path on disk, `Buffer`):
 
 ```js
-import { dirname } from "node:path";
-import { mkdir, writeFile } from "node:fs/promises";
-
-import { transpile } from '@bytecodealliance/jco-transpile';
+import { transpile, writeFiles } from '@bytecodealliance/jco-transpile';
 
 async function example() {
+    // Transpile a given WebAssembly component into JS runnabe in NodeJS
     const { files, imports, exports } = await transpile('path/to/component.wasm', { outDir: 'path/to/output/dir' });
-
-    // NOTE: Files is a serialization of the files produced of the following type:
-    // type FileBytes = { [filepath: string]: Uint8Array; };
-    //
-    // You can use the code below to write out all files to a given directory
-    await Promise.all(
-        Object.entries(files).map(async ([filePath, bytes]) => {
-            await mkdir(dirname(filePath), { recursive: true });
-            await writeFile(filePath, bytes);
-        })
-    );
+    // Write out the files that have been generated to disk
+    await writeFiles(files);
 }
 ```
 
@@ -48,46 +41,59 @@ async function example() {
 > `outDir` controls the prefix of generated file paths, so it is specified, despite the fact that no files
 > are actually written to disk.
 
-## Generating host types
-
-To generate host types:
+### Transpilation example
 
-```js
-import { dirname } from "node:path";
-import { mkdir, writeFile } from "node:fs/promises";
+If you write a component with the given WIT:
 
-import { generateHostTypes } from '@bytecodealliance/jco-transpile';
+```wit
+package docs:adder@0.1.0;
 
-async function example() {
-    const files = await generateHostTypes('path/to/wit/dir-or-file, { outDir: 'path/to/output/dir' });
+interface add {
+    add: func(x: u32, y: u32) -> u32;
+}
 
-    // NOTE: Files is a serialization of the files produced of the following type:
-    // type FileBytes = { [filepath: string]: Uint8Array; };
-    //
-    // You can use the code below to write out all files to a given directory
-    await Promise.all(
-        Object.entries(files).map(async ([filePath, bytes]) => {
-            await mkdir(dirname(filePath), { recursive: true });
-            await writeFile(filePath, bytes);
-        })
-    );
+world adder {
+    export add;
 }
 ```
 
-Host types are the implementations of WIT interfaces that are used by *post-transpilation* JS code,
-i.e. on the "host" (NodeJS + V8 or the browser), to make platform *imports* work.
+After tranpsilation of that component, you should see output like the following:
+
+```console
+dist
+└── transpiled
+    ├── add.core.wasm
+    ├── add.d.ts
+    ├── adder.core.wasm
+    ├── adder.d.ts
+    ├── adder.js
+    ├── add.js
+    ├── add.mjs
+    └── interfaces
+        └── docs-adder-add.d.ts
+
+3 directories, 8 files
+```
+
+`dist/transpiled/adder.js` is the entrypoint that can be used from "host" code:
+
+```js
+import { add } from "./dist/transpiled/adder.js";
 
-For a given import in a WIT world, this type generation would enable *implementation* of the interface.
+console.log("1 + 2 = " + add.add(1, 2));
+```
 
-## Generating guest types
+You can try this example for yourself [in GitHub][gh-examples-transpile-adder].
 
-To generate guest types:
+[gh-examples-transpile-adder]: https://github.com/bytecodealliance/jco/tree/main/examples/transpile/adder
 
-```js
-import { dirname } from "node:path";
-import { mkdir, writeFile } from "node:fs/promises";
+## Generating guest (component) types
 
-import { generateGuestTypes } from '@bytecodealliance/jco-transpile';
+When writing components, you can generate the Typescript declarations that correspond to your
+[WebAssembly Interface Types (WIT)][wit] imports and exports by generating guest tyeps:
+
+```js
+import { generateGuestTypes, writeFiles } from '@bytecodealliance/jco-transpile';
 
 async function example() {
     const files = await generateGuestTypes('path/to/wit/dir-or-file, { outDir: 'path/to/output/dir' });
@@ -110,6 +116,78 @@ turned into a component (by `jco componentize`/`componentize-js`) and performing
 
 For a given import in a WIT world, this type generation would enable *calling*/*using* the interface.
 
+### Guest type generation example
+
+For example, given the following WIT interface:
+
+```wit
+package docs:adder@0.1.0;
+
+interface add {
+    add: func(x: u32, y: u32) -> u32;
+}
+
+world adder {
+    export add;
+}
+```
+
+The Typescript declaration produced is:
+
+```
+declare module 'docs:adder/add@0.1.0' {
+  export function add(x: number, y: number): number;
+}
+```
+
+[wit]: https://github.com/WebAssembly/component-model/blob/main/design/mvp/WIT.md
+
+## Generating host types
+
+When building platforms that run transpiled components, you can generate Typescript
+declarations that correspond to the [WebAssembly Interface Types (WIT)][wit] imports (that the component requires)
+by generating host types:
+
+```js
+import { generateHostTypes, writeFiles } from '@bytecodealliance/jco-transpile';
+
+async function example() {
+    // Generate types for a host binding (i.e. supplying imports to a transpiled component)
+    const files = await generateHostTypes('path/to/wit/dir-or-file, { outDir: 'path/to/output/dir' });
+    // Write out the files that have been generated to disk
+    await writeFiles(files);
+}
+```
+
+Host types are the implementations of WIT interfaces that are used by *post-transpilation* JS code,
+i.e. on the "host" (NodeJS + V8 or the browser), to make platform *imports* work.
+
+For a given import in a WIT world, this type generation would enable *implementation* of the imported
+functionality interface.
+
+### Host type generation example
+
+For example, given the following WIT interface:
+
+```wit
+package docs:adder@0.1.0;
+
+interface add {
+    add: func(x: u32, y: u32) -> u32;
+}
+
+world adder {
+    export add;
+}
+```
+
+The Typescript declaration produced is:
+
+```
+/** @module Interface docs:adder/add@0.1.0 **/
+export function add(x: number, y: number): number;
+```
+
 # License
 
 This project is licensed under the Apache 2.0 license with the LLVM exception.