feat: allow users to customize the TypeScript type of a custom scalar

[freeatnet]

Why?

This PR adds the ability for users of the queries generator to override the TypeScript types of custom scalar variables via OverrideCodecType. The default scalar types are non-overrideable.

Example:

1. Set up a schema and a query:
   default.gel:

module default {
  scalar type EvmAddress extending str {
    constraint expression on ( re_test(r'^0x[a-f0-9]{40}$', __subject__) );
  }

  scalar type HumanAge extending int16 {
    constraint max_value(120);
  }

  type User {
    required property primaryAddress -> EvmAddress {
      constraint exclusive;
    };
    required property firstName -> str;
    property username -> str {
      constraint exclusive;
    };
    property age -> HumanAge;
  }
}

findUser.edgeql:

select User {
  id,
  primaryAddress,
  username,
  age
} filter .id = <uuid>$id

2. Run generate queries --target ts --use-resolved-codec-type

3. Verify findUser.query.ts includes the overridable types:

export type FindUserReturns = {
  "primaryAddress": ResolvedCodecType<"EvmAddress", string>;
  "age": ResolvedCodecType<"HumanAge", number>;
  "id": string;
  "username": string | null;
} | null;

// Checking types -- should be types for base scalars
let result: NonNullable<FindUserReturns>;
result.username
    // ^? (property) "username": string | null

result.primaryAddress
    // ^? (property) "primaryAddress": string

result.age
    // ^? (property) "age": number

4. Add an override:

declare module "gel" {
  export interface OverrideCodecType {
    "EvmAddress": `0x${string}`;
  }
}

5. Check types with overrides:

let result: NonNullable<FindUserReturns>;
result.username
    // ^? (property) "username": string | null

result.primaryAddress
    // ^? (property) "primaryAddress": `0x${string}`

result.age
    // ^? (property) "age": number

How?

This PR attempts to implement this functionality in a backwards-compatible way, since analyzeQuery is technically a public API.¹

Footnotes

1. Although it's only used in the queries generator within the repo, it's mentioned in the README as the primary API to build a custom generator, and it looks like other projects are using it. ↩

[scotttrinh]

I think it's fine to expand the existing public function to take options (let's use the existing CommandOptions type instead of this anonymous type) and make it default to {} like you're doing here. The main first-party consumer of this function is just this queries generator, so it'd be weird if the public one was not the one that the queries generator used.

[freeatnet]

@scotttrinh updated. Didn't use CommandOptions in analyzeQuery because the command options are defined in generate, while analyzeQuery is in the main package. Let me know if that doesn't work for you!

[scotttrinh]

👏 Thanks for bearing with me on the back and forth!

[freeatnet]

@scotttrinh no worries at all — I appreciate your responsiveness!

[MartinCura]

Neat!

i'm trying this and because of TS magic i'm not familiar with claude had to add

import type {} from "gel"

to the overrides.d.ts so the gel type import in my autogenerated.ts didn't fail

[scotttrinh]

Oh, thanks for the report! What is autogenerated.ts?

[MartinCura]

Oh, thanks for the report! What is autogenerated.ts?

Should've been explicit, i use

pnpm exec generate queries --target ts --use-resolved-codec-type --file ./queries/autogenerated && prettier --experimental-cli -w ./queries

autogenerated.ts is the one file where all my generated queries go, now starts with

// GENERATED by @gel/generate v0.6.4
// This file is automatically generated from .edgeql query files.
// To make changes, edit the source .edgeql file and regenerate.

import type {Executor, ResolvedCodecType} from "gel";

// ...

Also

// overrides.d.ts
// This import makes this file a module, enabling proper module augmentation
import type {} from "gel"

declare module "gel" {
  export interface OverrideCodecType {
    "default::ShopHandle": `@${string}`
  }
}