reflecting to types, e.g. for TypeGPU

[mighdoll]

In #159 (comment), we started a discussion about how to handle runtime conditions for reflecting into TypeScript.

from @iwoplaza:

---

Hmm, let's explore this a bit. Currently we're able to import structs as named exports from a shader file, like so:

// shader.wgsl
struct Boid {
  position: vec3f,
  velocity: vec3f,
}

// main.ts
import { Boid } from './shader.wgsl?typegpu';

However, if the definitions were dependent on runtime constants, we would have to provide them before getting reified references back:

// shader.wgsl
import constants::boids;

@if(boids)
struct Boid {
  position: vec3f,
  velocity: vec3f,
}

// main.ts
import shaderReflection from './shader.wgsl?typegpu';

const { Boid } = shaderReflection({
  boids: true,
});

The dynamically generated code of ./shader.wgsl?typegpu could be:

import * as d from 'typegpu';

const Boid = d.struct({
  position: d.vec3f,
  velocity: d.vec3f,
});

interface Constants {
  boids: boolean;
};

function reflection<T extends Constants>(constants: T):
  T['boids'] extends true
    ? { boids: typeof Boid }
    : { boids: undefined } {
  return {
    Boid: constants.boids ? Boid : undefined,
  };
}

export default reflection;

We can also handle more complex cases, like using constants inside of struct definitions, but lets omit that for now.

Solutions

I see a couple possible solutions we could try out:

1. Export static definitions (those independent of runtime-constants) as named exports, as those are going to be a majority, and house the rest in the default "reflection" export.
2. Export everything always as the default export.

The latter is simpler to implement and maintain, but also sours the DX for most common use-cases. What do we think? 🤔

[mighdoll]

There's understandably a tension between runtime control and static types..

I can imagine three general approaches:

• generate fixed types for a default case
• generate flexible types that cover all cases
• generate fixed types for user selected cases

fixed types default case
Generating fixed types for a default case will just work most of the time of course. Relatively few conditions will matter. e.g. emitting a definition for Boid that's unused would seem relatively benign. As long as there's a way to manually fix up the definitions for relatively rare situations where e.g. conditions change the shape of a struct, we could just defer finding a more elegant solution..

fully flexible generic types
Generating fully flexible types sounds snazzy, but tricky. T['boids'] is clever! But already there are complications of course. The current spec allows for combinations like @if(boids && !mobile), and you have to apply conditions to members (as you noted).. In the future, users will probably ask for more const expression evaluation in conditions like @if(lights == 4) or @if(shadowsSupported()). I'm less confident in this fully flexible type approach, seems likely it eventually runs into trouble and then we've done a lot of type system work and still have to fall back to less elegant solutions in some situations. Complicated types are difficult for users to debug, and it'd be especially hard if users need to figure out when and how to override the types in certain situations..

I suppose if we're sufficiently dedicated, nothing will really be unsolvable in types. The type system can run Doom, right? So surely it can handle conditional variables.. It's just a question of how difficult it'll be is to use and maintain the potentially very complicated types that we'd need. There's always a cost benefit tradeoff to fancy typing, and I fear that we may go over budget in this direction..

fixed types user selected cases
Another flexible but less elegant approach would be to let the user select the case, or even multiple cases. Perhaps something like:

  import { Boid as MobileBoid } from './shader.wgsl MOBILE=true ?typegpu';
  import { Boid as RegularBoid } from './shader.wgsl MOBILE=false ?typegpu';

Then the user could select which combination of runtime variables they want to see reflected in types, and the types would be relatively simple.

(I added something like this syntax at the last minute in M1 for ?static. The syntax feels a bit hacky, hopefully there's something better we can find.)

[iwoplaza]

I think we can spec out a very sensible fallback for the "fully flexible generic types" case, which would apply for every constant expression that cannot be easily represented as type expressions.

Conditional definitions

If a whole definition Foo is guarded behind an @if(expr) or an @else condition, we can represent that as typeof FooTrue | typeof FooFalse in the fallback case. This would mean typeof Foo | undefined if no @else branch is defined. If we can statically analyze expr and represent that in types, then we can do more type magic, and ... ? typeof FooTrue : typeof FooFalse

For conditionals inside definitions, we can do a similar thing. E.g., struct definition that depends on a runtime constant:

// shader.wgsl
import constants::half;

struct Boid {
  position: @if(half) vec3h @else vec3f,
  velocity: @if(half) vec3h @else vec3f,
}

And generate approximately the following TS: https://tsplay.dev/N5oaMW
(hover over every definition to see the inferred types based on the given conditions)

[mighdoll]

Nice. Union types as fallback seems promising. I imagine TS users are already pretty familiar with dealing with union types in cases where the ts type checker can't figure things out. And allowing union types sometimes saves the type machinery from having to be fully complete. That nicely addresses the concern that the type machinery could get too complicated and/or be too hard to wrangle for users.

Do you have some ideas about what we might add to #164 for this? (or do you imagine that it's library specific)