docs: /docs/reference/metagen + /docs/guides/wasm-functions (#751)

- Adds `/docs/reference/metagen`
- Adds `/docs/guides/wasm-functions`
- Adds a codegen section to `/docs/guides/external-functions`

MDK-492.

#### Migration notes

...

- [ ] The change comes with new or modified tests
- [ ] Hard-to-understand functions have explanatory comments
- [x] End-user documentation is updated to reflect the change


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->

## Summary by CodeRabbit

- **New Features**
- Added new targets for `metagen` with different generators and paths
for TypeScript, Python, and Rust.
- Introduced new functionality for defining and exposing typegraphs with
policies in various environments (Deno, Python, Rust).
- Added automated Rust WebAssembly project generation and compilation
script.
- Enhanced documentation with new sections and updated code examples
using `TGExample`.

- **Bug Fixes**
  - Updated `.gitignore` to exclude `*.wasm` files.

- **Documentation**
- Updated links and added detailed instructions for generating types
using `metagen`.

- **Refactor**
- Switched from `HashMap` to `BTreeMap` and `HashSet` to `BTreeSet` in
various modules for better data structure handling.
  - Added logging enhancements in the `Typegate` class.

- **Chores**
  - Updated build script for Rust WebAssembly target.

<!-- end of auto-generated comment: release notes by coderabbit.ai -->

.gitignore

@@ -48,4 +48,5 @@ typegraph/python/typegraph/gen
 *.egg-info/
 
 examples/typegraphs/migrations
+examples/typegraphs/**/*.wasm
 libs/pyrt_wit_wire/wit_wire

examples/metatype.yaml

@@ -144,4 +144,15 @@ typegraphs:
 
 metagen:
   targets:
-    main:
+    metagen_deno:
+      - generator: mdk_typescript
+        path: ./typegraphs/metagen/ts/
+        typegraph_path: ./typegraphs/metagen-deno.ts
+    metagen_py:
+      - generator: mdk_python
+        path: ./typegraphs/metagen/py/
+        typegraph_path: ./typegraphs/metagen-py.ts
+    metagen_rs:
+      - generator: mdk_rust
+        path: ./typegraphs/metagen/rs/
+        typegraph_path: ./typegraphs/metagen-rs.ts

examples/typegraphs/metagen-deno.py

@@ -0,0 +1,34 @@
+# skip:start
+from typegraph import typegraph, Policy, t, Graph
+from typegraph.graph.params import Cors
+from typegraph.runtimes.deno import DenoRuntime
+# skip:end
+
+
+@typegraph(
+    # skip:start
+    cors=Cors(allow_origin=["https://metatype.dev", "http://localhost:3000"]),
+    # skip:end
+)
+def metagen_deno(g: Graph):
+    idv3 = t.struct(
+        {
+            "title": t.string(),
+            "artist": t.string(),
+            "releaseTime": t.datetime(),
+            "mp3Url": t.uri(),
+            # explicit type names help when generating code
+        }
+    ).rename("idv3")
+    deno = DenoRuntime()
+
+    g.expose(
+        Policy.public(),
+        remix=deno.import_(
+            idv3,
+            idv3,
+            module="./metagen/ts/remix.ts",
+            deps=["./metagen/ts/mdk.ts"],
+            name="remix_track",
+        ).rename("remix_track"),  # explicit names help
+    )

examples/typegraphs/metagen-deno.ts

@@ -0,0 +1,32 @@
+// skip:start
+import { Policy, t, typegraph } from "@typegraph/sdk/index.js";
+import { DenoRuntime } from "@typegraph/sdk/runtimes/deno.js";
+// skip:end
+
+await typegraph({
+  name: "metagen-deno",
+  // skip:next-line
+  cors: { allowOrigin: ["https://metatype.dev", "http://localhost:3000"] },
+}, (g) => {
+  const idv3 = t.struct({
+    title: t.string(),
+    artist: t.string(),
+    releaseTime: t.datetime(),
+    mp3Url: t.uri(),
+    // explicit type names help when generating code
+  }).rename("idv3");
+
+  const deno = new DenoRuntime();
+
+  g.expose({
+    remix: deno.import(
+      idv3,
+      idv3,
+      {
+        module: "./metagen/ts/remix.ts",
+        deps: ["./metagen/ts/mdk.ts"],
+        name: "remix_track",
+      },
+    ).rename("remix_track"), // explicit names help 
+  }, Policy.public());
+});

examples/typegraphs/metagen-py.ts

@@ -0,0 +1,32 @@
+// skip:start
+import { Policy, t, typegraph } from "@typegraph/sdk/index.js";
+import { PythonRuntime } from "@typegraph/sdk/runtimes/python.js";
+// skip:end
+
+await typegraph({
+  name: "metagen-py",
+  // skip:next-line
+  cors: { allowOrigin: ["https://metatype.dev", "http://localhost:3000"] },
+}, (g) => {
+  const idv3 = t.struct({
+    title: t.string(),
+    artist: t.string(),
+    releaseTime: t.datetime(),
+    mp3Url: t.uri(),
+    // explicit type names help when generating code
+  }).rename("idv3");
+
+  const python = new PythonRuntime();
+
+  g.expose({
+    remix: python.import(
+      idv3,
+      idv3,
+      {
+        module: "./metagen/py/remix.py",
+        deps: ["./metagen/py/remix_types.py"],
+        name: "remix_track",
+      },
+    ).rename("remix_track"), // explicit names help 
+  }, Policy.public());
+});

examples/typegraphs/metagen-rs.py

@@ -0,0 +1,35 @@
+# skip:start
+from typegraph import typegraph, Policy, t, Graph
+from typegraph.graph.params import Cors
+from typegraph.runtimes.wasm import WasmRuntime
+# skip:end
+
+
+@typegraph(
+    # skip:start
+    cors=Cors(allow_origin=["https://metatype.dev", "http://localhost:3000"]),
+    # skip:end
+)
+def metagen_rs(g: Graph):
+    idv3 = t.struct(
+        {
+            "title": t.string(),
+            "artist": t.string(),
+            "releaseTime": t.datetime(),
+            "mp3Url": t.uri(),
+            # explicit type names help when generating code
+        }
+    ).rename("idv3")
+
+    # the wire flavour is availible through a static
+    # constructor
+    wasm = WasmRuntime.wire("metagen/rust.wasm")
+
+    g.expose(
+        Policy.public(),
+        remix=wasm.handler(
+            idv3,
+            idv3,
+            name="remix_track",
+        ).rename("remix_track"),  # explicit names help
+    )

examples/typegraphs/metagen-rs.ts

@@ -0,0 +1,34 @@
+// skip:start
+import { Policy, t, typegraph } from "@typegraph/sdk/index.js";
+import { WasmRuntime } from "@typegraph/sdk/runtimes/wasm.js";
+// skip:end
+
+await typegraph({
+  name: "metagen-rs",
+  // skip:next-line
+  cors: { allowOrigin: ["https://metatype.dev", "http://localhost:3000"] },
+}, (g) => {
+  const idv3 = t.struct({
+    title: t.string(),
+    artist: t.string(),
+    releaseTime: t.datetime(),
+    mp3Url: t.uri(),
+    // explicit type names help when generating code
+  }).rename("idv3");
+
+  // the wire flavour is availible through a static
+  // constructor
+  const wasm = WasmRuntime.wire("metagen/rust.wasm");
+
+  g.expose({
+    remix: wasm.handler(
+      idv3,
+      idv3,
+      {
+        name: "remix_track",
+      },
+      // the traits will map to the name of the materializer
+      // and also the the name of the handler mentioned above
+    ).rename("remix_track"),
+  }, Policy.public());
+});

examples/typegraphs/metagen-sdk.py

@@ -0,0 +1,58 @@
+# skip:start
+from typegraph import typegraph, Policy, t, Graph
+from typegraph.runtimes.deno import DenoRuntime
+from typegraph.graph.params import Cors
+
+# skip:end
+import os
+from typegraph.graph.metagen import Metagen
+
+
+@typegraph(
+    # skip:start
+    cors=Cors(allow_origin=["https://metatype.dev", "http://localhost:3000"]),
+    # skip:end
+)
+def metagen_sdk(g: Graph):
+    idv3 = t.struct(
+        {
+            "title": t.string(),
+            "artist": t.string(),
+            "releaseTime": t.datetime(),
+            "mp3Url": t.uri(),
+        }
+    ).rename("idv3")
+    deno = DenoRuntime()
+
+    g.expose(
+        Policy.public(),
+        remix=deno.import_(
+            idv3,
+            idv3,
+            module="./metagen/ts/remix.ts",
+            deps=["./metagen/ts/mdk.ts"],
+            name="remix_track",
+        ).rename("remix_track"),
+    )
+
+
+if __name__ == "__main__" and False:
+    metagen = Metagen(
+        # the workspace root that our config is relative to
+        os.path.dirname(os.path.abspath(__file__)),
+        # the rest is pretty similar to the CLI config
+        {
+            "targets": {
+                "main": [
+                    {
+                        "generator": "mdk_typescript",
+                        "typegraph_path": __file__,
+                        "path": "funcs/",
+                    },
+                ],
+            },
+        },
+    )
+    tg = metagen_sdk()
+    # dry_run doesn't write to disk
+    items = metagen.dry_run(tg, "main", None)

examples/typegraphs/metagen-sdk.ts

@@ -0,0 +1,55 @@
+// skip:start
+import { Policy, t, typegraph } from "@typegraph/sdk/index.js";
+import { DenoRuntime } from "@typegraph/sdk/runtimes/deno.js";
+// skip:end
+import { Metagen } from "@typegraph/sdk/metagen.js";
+
+// get typegraph desc here
+const tg = await typegraph({
+  name: "metagen-sdk",
+  // skip:next-line
+  cors: { allowOrigin: ["https://metatype.dev", "http://localhost:3000"] },
+}, (g) => {
+  const idv3 = t.struct({
+    title: t.string(),
+    artist: t.string(),
+    releaseTime: t.datetime(),
+    mp3Url: t.uri(),
+  }).rename("idv3");
+
+  const deno = new DenoRuntime();
+
+  g.expose({
+    remix: deno.import(
+      idv3,
+      idv3,
+      {
+        module: "./metagen/ts/remix.ts",
+        deps: ["./metagen/ts/mdk.ts"],
+        name: "remix_track",
+      },
+    ).rename("remix_track")
+  }, Policy.public());
+});
+
+if (false) {
+  const myPath = import.meta.url.replace("file://", "");
+  const metagen = new Metagen(
+    // the workspace root that our config is relative to
+    myPath + "/..",
+    // this rest of the config is similmilar to the CLI config
+    {
+      "targets": {
+        "main": [
+          {
+            "generator": "mdk_typescript",
+            "typegraph_path": myPath,
+            "path": "funcs/",
+          },
+        ],
+      },
+    }
+  );
+  // dry_run doesn't write to disk
+  metagen.dryRun(tg, "main")
+}