Formalize issue / PR code blocks with self-contained query?

[karlhorky]

Is your feature request related to a problem? Please describe.

It is sometimes hard to understand how to reproduce issues if the reporter doesn't include a code block or their query requires a specific database schema.

Describe the solution you'd like

Issue and PR descriptions could have 2 Before/After (only "Before" for issues) code blocks showing a TS code example, with:

1. self-contained query, ideally without schema setup required
2. TypeScript type
3. SafeQL error message

I've done some in my issues like this before:

• Before: Regression: Field from LEFT JOIN LATERAL not nullable #418
• After: Regression: Field from LEFT JOIN LATERAL not nullable #418 (comment)

Before

// 💥 Query has incorrect type annotation.
//  Expected: { latest_is_completed: boolean | null }[]
//    Actual: { latest_is_completed: boolean }[]
await sql<{ latest_is_completed: boolean | null }[]>`
  WITH
    videos (id) AS (
      VALUES
        (1)
    ),
    video_progress_edits (video_id, new_is_completed) AS (
      VALUES
        (2, TRUE)
    )
  SELECT
    latest_video_progress_edit.new_is_completed AS latest_is_completed
  FROM
    videos
    LEFT JOIN LATERAL (
      SELECT
        video_progress_edits.new_is_completed
      FROM
        video_progress_edits
      WHERE
        video_progress_edits.video_id = videos.id
    ) latest_video_progress_edit ON TRUE
`;

After

// ✅
await sql<{ latest_is_completed: boolean | null }[]>`
  WITH
    videos (id) AS (
      VALUES
        (1)
    ),
    video_progress_edits (video_id, new_is_completed) AS (
      VALUES
        (2, TRUE)
    )
  SELECT
    latest_video_progress_edit.new_is_completed AS latest_is_completed
  FROM
    videos
    LEFT JOIN LATERAL (
      SELECT
        video_progress_edits.new_is_completed
      FROM
        video_progress_edits
      WHERE
        video_progress_edits.video_id = videos.id
    ) latest_video_progress_edit ON TRUE
`;

Describe alternatives you've considered

1. Provide an even more robust alternative
2. Do nothing

Additional context

I have been asking for this from issue reporters in a few places:

• fix: resolve branded types to their base type as query parameters #471 (comment)
• relName is undefined #180 (comment)

[Newbie012]

Sounds reasonable. Even simpler format would be enough - "Given the following setup [...], I expected to get [...] but instead got [...]" with additional metadata such as versions and whether or not it's a regression.

SafeQL isn't that popular and there aren't many new issues to track, so currently it's not too much painful for me personally, but I'm always open for suggestions

[karlhorky]

Yeah, the volume of issues / PRs is low luckily, so it's not a big problem currently

Given the following setup [...]

Could do this, but I guess the challenges are in the format for the schema or other setup characteristics. It could possibly just be 1+ CREATE TABLE SQL queries, but some people may have their table definitions scattered through multiple migrations (or even specified somehow without SQL)

That's why I was thinking that it would maybe be simpler for everyone (both users reporting the issues and also you and me and any other collaborators triaging) if they were self-contained...

[karlhorky]

Just thinking, actually a demoable playground like https://typescript-eslint.io/play/ would be best (any tables not referenced or created would show up immediately) 🤔

For example, this demo playground: https://typescript-eslint.io/play/#ts=5.9.2&fileType=.tsx&code=GYVwdgxgLglg9mABAQwBQEpEG8BQOC%2BOQA&eslintrc=N4KABGBEBOCuA2BTAzpAXGUEKQAIBcBPABxQGNoBLY-AWhXkoDt8B6Jge3oFsbDaAZrCZl8lDk3RRE0aB2iRwYAL4hlQA&tsconfig=N4KABGBEDGD2C2AHAlgGwKYCcDyiAuysAdgM6QBcYoEEkJemy0eAcgK6qoDCAFutAGsylBm3TgwAXxCSgA&tokens=false

This was introduced in 2021:

• original PR: chore(website): add playground to website typescript-eslint/typescript-eslint#4108
• one component in source code: https://github.com/typescript-eslint/typescript-eslint/blob/main/packages/website/src/components/Playground.tsx

What are your thoughts on that? It's a bit bigger, so I understand if you wouldn't have bandwidth to build it. But having a playground / live demo could not only help with issue and PR reproductions but also for marketing demos...

It would need some kind of database, maybe in the browser with PGlite...