Expose Loader Type Conversion Metadata

[AshutoshSharma-pixel]

Is your feature request related to a problem?

Loader type conversions are currently implemented within individual loader implementations, but the conversion metadata itself is not exposed in a structured or queryable form.

For example, loaders contain mappings between language-specific types and MetaCall reflect types, as well as mappings from MetaCall reflect types back into target language types. These relationships are currently embedded in loader conversion logic and are not centrally represented.

As a result:

• Cross-language type mappings are difficult to inspect.
• Tooling cannot reliably consume conversion information.
• Documentation must be reconstructed from implementation details.
• There is no single source of truth for conversion metadata.

Describe the solution you’d like

Provide a mechanism for exposing loader type conversion metadata as a structured data model.

One possible approach would be to derive the metadata directly from runtime behavior and export it through a dedicated API, configuration artifact, or generated metadata file.

The primary goal is to make conversion information available to:

• Documentation tooling
• Declaration generators
• IntelliSense / LSP integrations
• Cross-language analysis tools
• Debugging and inspection utilities

Describe alternatives you’ve considered

• Manually maintaining conversion metadata alongside loader implementations.
• Static analysis of loader source code.
• Dedicated registration mechanisms where loaders explicitly declare supported conversions.
• Runtime-derived metadata generated from observed loader behavior.

Additional context

This topic emerged during discussions around meta-ast, declaration generation, and cross-language IntelliSense support.

A related challenge is ensuring that any exposed metadata remains aligned with actual loader behavior and does not diverge from the implemented conversion logic over time.

[viferga]

There's two options (I would do the first one):

1. We make an identity function for each language:

def identity(a):
   return a

And then we call it for each language, passing all types and then from the returned value, query the type. This is a dirty trick but it will work, we can put it as a post-build command.

This is also good because it will force to implement all types in all languages, even if we just do:

throw Error("Not implemented")

2. Create a common interface at C level for type conversions, which forced to register the type info and the callback for each type conversion.

In this second case if we don't do it properly may induce an error where the conversion does not match the registered type info, so for that we should find a robust way to implement it.

It will also imply that we have to refactor all loaders. It also introduces other problems because it adds an abstraction that it's very implementation dependant, for example the c loader never does conversions like node loader where integers are doubles, it just uses pointers normally.

The type conversion functions are only shared with ports, and that's why I unified them with loaders, but the core itself doesn't need to know about those or operate with them (or at least I don't see a real need now).

[AshutoshSharma-pixel]

While looking at the TODO loop in metacall_node_conversion_test.cpp, I went through all 19 METACALL_* types to check which ones metacall_value_create() can handle safely when the loop is uncommented.

Update: I initially assumed the complex types would crash, but after reading the first PoC commit (876046a) more carefully I can see metacall_value_create() was added in that same commit with safe construction for all types. Good design.

After tracing each type through the node loader, the actual picture is:

---

Will round-trip cleanly:

Type | Node return type -- | -- METACALL_BOOL | METACALL_BOOL METACALL_CHAR | METACALL_DOUBLE METACALL_SHORT | METACALL_DOUBLE METACALL_INT | METACALL_DOUBLE ← already confirmed METACALL_LONG | METACALL_DOUBLE METACALL_FLOAT | METACALL_DOUBLE METACALL_DOUBLE | METACALL_DOUBLE METACALL_STRING | METACALL_STRING METACALL_BUFFER | METACALL_BUFFER METACALL_ARRAY | METACALL_ARRAY METACALL_MAP | METACALL_MAP METACALL_NULL | METACALL_NULL METACALL_PTR | METACALL_PTR (wrapped NULL, no dereference) METACALL_FUNCTION | METACALL_FUNCTION (closure wrapped safely)

---

Will throw a JS error (not crash, but EXPECT_NE(ret, NULL) may fail or produce noisy output):

• METACALL_FUTURE — throws "NodeJS Loader future is not implemented"
• METACALL_OBJECT — throws "NodeJS Loader object is not implemented"
• METACALL_CLASS — falls through to undefined, maps back as METACALL_NULL
• METACALL_EXCEPTION / METACALL_THROWABLE — construction is safe but node-side handling is unclear

---

So the loop can likely run without guards for the most part. The only noisy types are the unimplemented ones on the node loader side. Might be worth wrapping those 4-5 in a skip or just letting them print whatever they return, depending on how strict the test assertions need to be.