Feature: Const-literal typing for import-attribute imports

🔍 Search Terms

Keywords: Import Attributes, Const Literal Typing, Type Providers, DSL Integration, JSON Schema

Related Issues

• https://github.com/microsoft/TypeScript/issues/3136
• https://github.com/microsoft/TypeScript/issues/32063
• https://github.com/microsoft/TypeScript/issues/26552

✅ Viability Checklist

• This wouldn't be a breaking change in existing TypeScript/JavaScript code
• This wouldn't change the runtime behavior of existing JavaScript code
• This could be implemented without emitting different JS based on the types of the expressions
• This isn't a runtime feature (e.g. library functionality, non-ECMAScript syntax with JavaScript output, new syntax sugar for JS, etc.)
• This isn't a request to add a new utility type: https://github.com/microsoft/TypeScript/wiki/No-New-Utility-Types
• This feature would agree with the rest of our Design Goals: https://github.com/Microsoft/TypeScript/wiki/TypeScript-Design-Goals

⭐ Suggestion

It should be possible to import a fully typed value representation via import-attributes

Problem

When importing Json with import-attributes, TypeScript produces a non-constant data structure.

// ----------------------------------------------------------------
// vector.json
// ----------------------------------------------------------------
{ "x": 1, "y": 2, "z": 3 }

// ----------------------------------------------------------------
// index.ts
// ----------------------------------------------------------------
import Vector from "./vector.json" with { type: "json" };

const { x, y, z } = Vector     // actual = { x: number, y: number, z: number }
                               // 
                               // expect = { x: 1, y: 2, z: 3 }

Information is lost regarding the literal values 1, 2, 3 (replaced by number). As information is lost on import, this makes type-mapping metadata encoded in the Json virtually impossible.

📃 Motivating Example

Import Json Schema

It should be possible for libraries to infer data structures from imported schematics like Json Schema. The minimum requirement is that the imported type be a literal representation of the data.

Ref: Inline Provided Type

import { type Static } from 'typebox'

// Vector3 is Provided Type

type Vector3 = Static<{                // type Vector3 = {
  type: 'object',                      //   x: number;
  required: ['x', 'y', 'z'],           //   y: number;
  properties: {                        //   z: number;
    x: { type: 'number' },             // }
    y: { type: 'number' },
    z: { type: 'number' }
  }
}>

... but as import-attributes lose information for property values, the following isn't possible.

// ----------------------------------------------------------------
// vector.json
// ----------------------------------------------------------------
{
  "type": "object",         
  "required": ["x", "y", "z"],
  "properties": {      
    "x": { "type": "number" }, // observed as { type: string }
    "y": { "type": "number" },
    "z": { "type": "number" }
  }
}

// ----------------------------------------------------------------
// index.ts
// ----------------------------------------------------------------

import { type Static } from 'typebox'

import Vector3 from './vector.json' with { type: 'json'  }

// Vector3 is Provided Type | Incorrect

type Vector3 = Static<typeof Vector3>  // type Vector3 = {
                                       //   x?: unknown;
                                       //   y?: unknown;
                                       //   z?: unknown;
                                       // }

Import TypeScript via Text

If import-attributes with { type: 'text' } could also return literal string types. This would enable type safe DSL parsers to be developed for formats such as GraphQL, gRPC IDL or even TypeScript itself.

Ref: Parse TypeScript via Constant String Literal

import { type TScript, type Static } from 'typebox'

// Definition Parsing
type Math = TScript<{}, `
  export type Vector2 = {
    x: number
    y: number
  }
  export type Vector3 = {
    x: number
    y: number
    z: number
  }
`>

// Vector3 | Vector2 as Provided Types
type Vector2 = Static<Math['Vector2']>  // type Vector2 = {
                                        //   x: number;
                                        //   y: number;
                                        // }
type Vector3 = Static<Math['Vector3']>  // type Vector3 = {
                                        //   x: number;
                                        //   y: number;
                                        //   z: number;
                                        // }

💻 Use Cases

What do you want to use this for?

At a high level:

• Use the TypeScript compiler to auto sync MCP protocol schematics loaded via URI (Deno). Example
• Use the TypeScript compiler to parse and infer WAT/WASM interface definitions Example
• Use the TypeScript compiler to parse foreign IDL formats like GraphQL Reference
• Use the TypeScript compiler to derive structures from WebGL/WebGPU (WGSL) compute programs Reference

---

What workarounds are you using in the meantime?

For inference, the current workaround is to encode structures in constant string literals.

// workable: would prefer to edit in '.graphql' and load via { type: 'text' } attribute
export const GraphQLTypes = `
type Starship {
  id: ID!
  name: String!
  length(unit: LengthUnit = METER): Float
}
`

No source files, tests, or compiler entry points are named; start by locating the existing import-attribute handling and related type-inference tests. Compare the proposed literal-preserving behavior for JSON and text imports with the linked issues, and define tests that establish the intended inferred types.