Explicit typing on consts?

[wendrul]

We are using openapi-ts to generate a typescript client from an OpenAPI specification.
When trying to publish, we get an error related to slow types for the generated schemas:

$ npx jsr publis --dry-run

error[missing-explicit-type]: missing explicit type in the public API
   --> /home/wendrul/windmill-dev/jsr/typescript-client/src/schemas.gen.ts:543:14
    |
543 | export const $MySchema = {
    |              ^^^^^^^^^^^^^ this symbol is missing an explicit type
    = hint: add an explicit type annotation to the symbol

  info: all symbols in the public API must have an explicit type
  docs: https://jsr.io/go/slow-type-missing-explicit-type

I opened an issue (hey-api/openapi-ts#493) to see if openapi-ts could change to comply with the jsr type requirements but @mrlubos pointed out that these are constants and we wanted to know your opinion.

Should generators such as openapi-ts add the type for this kind of schema? (which would basically mean copy pasting the value on the type field). What would be the proper way to integrate with jsr in this case?

[mrlubos]

Related #444

[lucacasonato]

I don't think this is related - I'll answer separately there :)

[lucacasonato]

Hey!

I'll write the exact details about why JSR encourages code that has no slow types, and why we can not do inference in #444. I'll just respond to the exact question here in this thread, if that's ok :)

JSR considers types that are too complex to infer (ie require full type checking) as "slow types". These are any exported symbols (functions, classes, public class properties, public class methods, class class contructors, const bindings, let bindings, and var bindings) must be either explicitly annotated, or a type must be very simply inferable from immediate context. For example, we can infer that in the case const x = "foo";, x is a string, and some other simple cases like this, but we can not always infer.

I'd like to acknowledge that the docs are not clear enough about what cases we can and can not infer. I will update the docs later today with a more expansive description of what we can and can not infer.

Specifically in your case, I do not see what the right hand side of this const declaration is (please post it!), so I don't know whether we can or can not infer this (ie is it a bug, or is there something that means that we are not 100% sure that it is safe to infer). A common case though that may be what you are running into (again, I don't know for sure because I don't have the code :)):

If a object is not marked as const, and contains an array, and the array contains objects of different shapes, TypeScript will infer a type for the array property with not just information from each element individually, but rather from the union of all the element shapes. Doing this, requires type checking, because TypeScript is able to fold multiple shapes into one if they are semantically equivalent. Semantic equivalence of two types can not be checked purely based on the visual representation of the types (which is all that we have to go on). It requires a full on type checker.

For example, take the code below. TypeScript will emit declarations for this example that do not look at all like the input - it performed type checking and folding of the types for different elements, all to synthesise a new representation of the types:

// input
export const x = {
    list: [
        { a: "foo", b: [true] },
        { a: "foo", b: [1, true] },
        { a: 123, c: true  }
    ],
};

export declare const x: {
    list: ({
        a: string;
        b: (number | boolean)[];
        c?: undefined;
    } | {
        a: number;
        c: boolean;
        b?: undefined;
    })[];
};

In most cases, you can prevent this folding and type synthesis by marking an object as const. JSR is generally able to infer types from objects that are marked as const unless they are not purely made up of literals of objects, arrays, or primitives (ie they can not contain a reference to any other symbols).

[wendrul]

Yeah I realise it would have been better to share it from the start, here is one example that gets jsr to complain:

export const $Script = {
    type: 'object',
    properties: {
        workspace_id: {
            type: 'string'
        },
        hash: {
            type: 'string'
        },
        path: {
            type: 'string'
        },
        parent_hashes: {
            type: 'array',
            description: `The first element is the direct parent of the script, the second is the parent of the first, etc
`,
            items: {
                type: 'string'
            }
        },
        summary: {
            type: 'string'
        },
        description: {
            type: 'string'
        },
        content: {
            type: 'string'
        },
        created_by: {
            type: 'string'
        },
        created_at: {
            type: 'string',
            format: 'date-time'
        },
        archived: {
            type: 'boolean'
        },
        schema: {
            type: 'object'
        },
        deleted: {
            type: 'boolean'
        },
        is_template: {
            type: 'boolean'
        },
        extra_perms: {
            type: 'object',
            additionalProperties: {
                type: 'boolean'
            }
        },
        lock: {
            type: 'string'
        },
        lock_error_logs: {
            type: 'string'
        },
        language: {
            type: 'string',
            enum: ['python3', 'deno', 'go', 'bash', 'powershell', 'postgresql', 'mysql', 'bigquery', 'snowflake', 'mssql', 'graphql', 'nativets', 'bun']
        },
        kind: {
            type: 'string',
            enum: ['script', 'failure', 'trigger', 'command', 'approval']
        },
        starred: {
            type: 'boolean'
        },
        tag: {
            type: 'string'
        },
        has_draft: {
            type: 'boolean'
        },
        draft_only: {
            type: 'boolean'
        },
        envs: {
            type: 'array',
            items: {
                type: 'string'
            }
        },
        concurrent_limit: {
            type: 'integer'
        },
        concurrency_time_window_s: {
            type: 'integer'
        },
        cache_ttl: {
            type: 'number'
        },
        dedicated_worker: {
            type: 'boolean'
        },
        ws_error_handler_muted: {
            type: 'boolean'
        },
        priority: {
            type: 'integer'
        },
        restart_unless_cancelled: {
            type: 'boolean'
        },
        timeout: {
            type: 'integer'
        },
        delete_after_use: {
            type: 'boolean'
        },
        visible_to_runner_only: {
            type: 'boolean'
        },
        no_main_func: {
            type: 'boolean'
        }
    },
    required: ['hash', 'path', 'summary', 'description', 'content', 'created_by', 'created_at', 'archived', 'deleted', 'is_template', 'extra_perms', 'language', 'kind', 'starred', 'no_main_func']
} as const;

(sorry for the long snippet)

Also might be worth noting, in the same file there are multiple schemas (of different shapes) but we aren't getting an error for all of them

[lucacasonato]

Ah, great - I think the issue is that we are incorrectly rejecting all template literals instead of only tagged template literals. 😅

#453

[wendrul]

Oh great, I'm glad we found it! Thanks for all the very clear explanations and for your time!

[wendrul]

I just realised that all of the schemas that get an error have one thing in common, they have some field with a backtick delimited string containing newlines. I guess this is one probable reason for the const being flagged as a slow type. Let me know if you see another possibility.

In the example above I'm talking about this part:

 parent_hashes: {
            type: 'array',
            description: `The first element is the direct parent of the script, the second is the parent of the first, etc
`,
            items: {
                type: 'string'
            }
        },

[mrlubos]

@wendrul you could try generating these with the schemas.type = 'form' setting and see if it still complains?