feat: GArray tuple support.

Much like JS Array tuples, there are a plethora of APIs that are
able to mutate the GArray tuple to violate the tuple typing. The
intent is that only basic set/get functions (which are type safe
for tuples) ought to be used.

For now I've opted not to add support for tuples to GArray's
proxy() types. Simply because the types involved are already very
complicated/slow. Perhaps this will be revisited in future.

Author: Benjamin-Dobell

.changeset/tolerant-sdeath-vestige.md

@@ -0,0 +1,7 @@
+---
+"@godot-js/editor": patch
+---
+
+**Feature:** `GArray` tuple support.
+
+For example, with the type `GArray<[number, string]>` `.get(0)` will return a `number` and `.get(1)` will return a `string`.

scripts/jsb.editor/src/jsb.editor.codegen.ts

@@ -293,68 +293,86 @@ const TypeMutations: Record<string, TypeMutation> = {
     GArray: {
         generic_parameters: {
             T: {
-                default: GodotAnyType,
+                default: `${GodotAnyType} | ${GodotAnyType}[]`,
+                extends: `${GodotAnyType} | ${GodotAnyType}[]`
             },
         },
         intro: [
             "/** Builder function that returns a GArray populated with elements from a JS array. */",
-            "static create<T>(elements: [T] extends [GArray<infer E>] ? Array<E | GProxyValueWrap<E>> : Array<T | GProxyValueWrap<T>>):",
-            "    [T] extends [GArray<infer E>]",
-            "        ? [GValueWrap<E>] extends [never]",
-            "            ? never",
-            "            : GArray<GValueWrap<T>>",
-            "        : [GValueWrap<T>] extends [never]",
-            "            ? never",
-            "            : GArray<GValueWrap<T>>",
-            "[Symbol.iterator](): IteratorObject<T>",
+            "static create<A extends any[]>(elements: A): GValueWrap<A>",
+            "static create<A extends GArray<any>>(",
+            "    elements: A extends GArray<infer T>",
+            "        ? [T] extends [any[]]",
+            "            ? { [I in keyof T]: GDataStructureCreateValue<T[I]> }",
+            "            : Array<GDataStructureCreateValue<T>>",
+            "        : never",
+            "): GValueWrap<A>",
+            "static create<E extends GAny>(elements: Array<GDataStructureCreateValue<E>>): GArray<E>",
+            "[Symbol.iterator](): IteratorObject<GArrayElement<T>>",
             "/** Returns a Proxy that targets this GArray but behaves similar to a JavaScript array. */",
-            "proxy<Write extends boolean = false>(): Write extends true ? GArrayProxy<T> : GArrayReadProxy<T>",
+            "proxy<Write extends boolean = false>(): Write extends true ? GArrayProxy<GArrayElement<T>> : GArrayReadProxy<GArrayElement<T>>",
             "",
-            `${names.get_member("set_indexed")}(index: number, value: T): void`,
-            `${names.get_member("get_indexed")}(index: number): T`,
+            `${names.get_member("set_indexed")}<I extends int64>(index: I, value: GArrayElement<T, I>): void`,
+            `${names.get_member("get_indexed")}<I extends int64>(index: I): GArrayElement<T, I>`,
         ],
         property_overrides: {
-            set: mutate_parameter_type("value", "T"),
-            push_back: mutate_parameter_type("value", "T"),
-            push_front: mutate_parameter_type("value", "T"),
-            append: mutate_parameter_type("value", "T"),
-            insert: mutate_parameter_type("value", "T"),
-            fill: mutate_parameter_type("value", "T"),
-            erase: mutate_parameter_type("value", "T"),
-            count: mutate_parameter_type("value", "T"),
-            has: mutate_parameter_type("value", "T"),
-            bsearch: mutate_parameter_type("value", "T"),
-            bsearch_custom: chain_mutators(mutate_parameter_type("value", "T"), mutate_parameter_type("func", "Callable2<T, T, boolean>")),
-            find: mutate_parameter_type("what", "T"),
-            rfind: mutate_parameter_type("what", "T"),
-            get: mutate_return_type("T"),
-            front: mutate_return_type("T"),
-            back: mutate_return_type("T"),
-            pick_random: mutate_return_type("T"),
-            pop_back: mutate_return_type("T"),
-            pop_front: mutate_return_type("T"),
-            pop_at: mutate_return_type("T"),
-            min: mutate_return_type("T"),
-            max: mutate_return_type("T"),
-            sort_custom: mutate_parameter_type("func", "Callable2<T, T, boolean>"),
-            all: mutate_parameter_type("method", "Callable1<T, boolean>"),
-            any: mutate_parameter_type("method", "Callable1<T, boolean>"),
-            filter: chain_mutators(mutate_parameter_type("method", "Callable1<T, boolean>"), mutate_return_type("GArray<T>")),
-            map: chain_mutators(mutate_parameter_type("method", "Callable1<T, U>"), mutate_return_type("GArray<U>"), mutate_template("U")),
-            append_array: mutate_parameter_type("array", "GArray<T>"),
-            duplicate: mutate_return_type("GArray<T>"),
-            slice: mutate_return_type("GArray<T>"),
+            set: [`set<I extends int64>(index: I, value: GArrayElement<T, I>): void`],
+            push_back: mutate_parameter_type("value", "GArrayElement<T>"),
+            push_front: mutate_parameter_type("value", "GArrayElement<T>"),
+            append: mutate_parameter_type("value", "GArrayElement<T>"),
+            insert: mutate_parameter_type("value", "GArrayElement<T>"),
+            fill: mutate_parameter_type("value", "GArrayElement<T>"),
+            erase: mutate_parameter_type("value", "GArrayElement<T>"),
+            count: mutate_parameter_type("value", "GArrayElement<T>"),
+            has: mutate_parameter_type("value", "GArrayElement<T>"),
+            bsearch: mutate_parameter_type("value", "GArrayElement<T>"),
+            bsearch_custom: chain_mutators(mutate_parameter_type("value", "GArrayElement<T>"), mutate_parameter_type("func", "Callable<(a: GArrayElement<T>, b: GArrayElement<T>) => boolean>")),
+            find: mutate_parameter_type("what", "GArrayElement<T>"),
+            rfind: mutate_parameter_type("what", "GArrayElement<T>"),
+            get: [`get<I extends int64>(index: I): GArrayElement<T, I>`],
+            front: mutate_return_type("GArrayElement<T>"),
+            back: mutate_return_type("GArrayElement<T>"),
+            pick_random: mutate_return_type("GArrayElement<T>"),
+            pop_back: mutate_return_type("GArrayElement<T>"),
+            pop_front: mutate_return_type("GArrayElement<T>"),
+            pop_at: mutate_return_type("GArrayElement<T>"),
+            min: mutate_return_type("GArrayElement<T>"),
+            max: mutate_return_type("GArrayElement<T>"),
+            sort_custom: mutate_parameter_type("func", "Callable<(a: GArrayElement<T>, b: GArrayElement<T>) => boolean>"),
+            all: mutate_parameter_type("method", "Callable<(value: GArrayElement<T>) => boolean>"),
+            any: mutate_parameter_type("method", "Callable<(value: GArrayElement<T>) => boolean>"),
+            filter: chain_mutators(mutate_parameter_type("method", "Callable<(value: GArrayElement<T>) => boolean>"), mutate_return_type("GArray<GArrayElement<T>>")),
+            map: chain_mutators(mutate_parameter_type("method", "Callable<(value: GArrayElement<T>) => U>"), mutate_return_type("GArray<U>"), mutate_template("U")),
+            append_array: mutate_parameter_type("array", "GArray<GArrayElement<T>>"),
+            duplicate: mutate_return_type("this"),
+            slice: mutate_return_type("GArray<GArrayElement<T>>"),
         },
     },
     GDictionary: {
+        prelude: [
+            "type GArrayCreateSource<T> = ReadonlyArray<T> | {",
+            "    [Symbol.iterator](): IteratorObject<GDataStructureCreateValue<T>>;",
+            "    [K: number]: GDataStructureCreateValue<T>;",
+            "}",
+            "type GDataStructureCreateValue<V> = V | (",
+            "     V extends GArray<infer T>",
+            " ? [T] extends [any[]]",
+            "     ? GArrayCreateSource<{ [I in keyof T]: GDataStructureCreateValue<T[I]> }>",
+            "     : GArrayCreateSource<GDataStructureCreateValue<T>>",
+            " : V extends GDictionary<infer T>",
+            "     ? { [K in keyof T]: GDataStructureCreateValue<T[K]> }",
+            "     : never",
+            "     )"
+        ],
         generic_parameters: {
             T: {
                 default: "Record<any, any>",
             },
         },
         intro: [
             "/** Builder function that returns a GDictionary with properties populated from a source JS object. */",
-            "static create<T>(properties: T extends GDictionary<infer S> ? GDictionaryProxy<S> : GDictionaryProxy<T>): T extends GDictionary<infer S> ? GValueWrap<S> : GValueWrap<T>",
+            "static create<V extends { [key: number | string]: GWrappableValue }>(properties: V): GValueWrap<V>",
+            "static create<V extends GDictionary<any>>(properties: V extends GDictionary<infer T> ? { [K in keyof T]: GDataStructureCreateValue<T[K]> } : never): V",
             "[Symbol.iterator](): IteratorObject<{ key: any, value: any }>",
             "/** Returns a Proxy that targets this GDictionary but behaves similar to a regular JavaScript object. Values are exposed as enumerable properties, so Object.keys(), Object.entries() etc. will work. */",
             "proxy<Write extends boolean = false>(): Write extends true ? GDictionaryProxy<T> : GDictionaryReadProxy<T>",

scripts/jsb.runtime/src/jsb.inject.ts

@@ -1,7 +1,7 @@
 import type * as Godot from "godot";
 import type * as GodotJsb from "godot-jsb";
 
-type GArrayProxy<T> = Godot.GArrayProxy<T> & {
+type GArrayProxy<T extends Godot.GAny> = Godot.GArrayProxy<T> & {
     [Godot.ProxyTarget]: Godot.GArray<T>;
 }
 
@@ -47,7 +47,7 @@ function get_helpers(): ProxyHelpers {
             },
             godot_wrap: function (value: any) {
                 if (Array.isArray(value)) {
-                    return GArray.create(value);
+                    return GArray.create<any>(value);
                 }
 
                 const proto = Object.getPrototypeOf(value);

scripts/typings/godot.generated.d.ts

@@ -11,28 +11,24 @@ declare module "godot" {
     class Script extends Resource { }
     interface ResourceTypes { }
 
-    class GArray<T = any> {
-        static create<T>(elements: [T] extends [GArray<infer E>] ? Array<E | GProxyValueWrap<E>> : Array<T | GProxyValueWrap<T>>):
-          [T] extends [GArray<infer E>]
-            ? [GValueWrap<E>] extends [never]
-              ? never
-              : GArray<GValueWrap<T>>
-            : [GValueWrap<T>] extends [never]
-              ? never
-              : GArray<GValueWrap<T>>
-        [Symbol.iterator](): IteratorObject<T>
-        proxy<Write extends boolean = false>(): Write extends true ? GArrayProxy<T> : GArrayReadProxy<T>;
-        get_indexed(index: number): T
-        get(index: int64): T
-        set(index: int64, value: T): void
-        size(): number
-        push_back(value: T): void
-        pop_back(): T
-        has(value: T): boolean
-        find(what: T, from: int64 = 0): int64
+    type GArrayCreateSource<T> = ReadonlyArray<T> | {
+        [Symbol.iterator](): IteratorObject<GDataStructureCreateValue<T>>;
+        [K: number]: GDataStructureCreateValue<T>;
     }
-    class GDictionary<T = any> {
-        static create<T>(properties: T extends GDictionary<infer S> ? GDictionaryProxy<S> : GDictionaryProxy<T>): T extends GDictionary<infer S> ? GValueWrap<S> : GValueWrap<T>
+
+    type GDataStructureCreateValue<V> = V | (
+        V extends GArray<infer T>
+            ? [T] extends [any[]]
+                ? GArrayCreateSource<{ [I in keyof T]: GDataStructureCreateValue<T[I]> }>
+                : GArrayCreateSource<GDataStructureCreateValue<T>>
+            : V extends GDictionary<infer T>
+                ? { [K in keyof T]: GDataStructureCreateValue<T[K]> }
+                : never
+        )
+
+    class GDictionary<T = Record<any, any>> {
+        static create<V extends { [key: number | string]: GWrappableValue }>(properties: V): GValueWrap<V>
+        static create<V extends GDictionary<any>>(properties: V extends GDictionary<infer T> ? { [K in keyof T]: GDataStructureCreateValue<T[K]> } : never): V
         proxy<Write extends boolean = false>(): Write extends true ? GDictionaryProxy<T> : GDictionaryReadProxy<T>;
         get<K extends keyof T>(key: K, default_: any = <any> {}): T[K]
         get_keyed<K extends keyof T>(index: K): T[K]
@@ -41,6 +37,27 @@ declare module "godot" {
         erase(key: keyof T): boolean
         has(key: keyof T): boolean
     }
+    class GArray<T extends GAny | GAny[] = GAny | GAny[]> {
+        static create<A extends any[]>(elements: A): GValueWrap<A>
+        static create<A extends GArray<any>>(
+            elements: A extends GArray<infer T>
+                ? [T] extends [any[]]
+                    ? { [I in keyof T]: GDataStructureCreateValue<T[I]> }
+                    : Array<GDataStructureCreateValue<T>>
+                : never
+        ): GValueWrap<A>
+        static create<E extends GAny>(elements: Array<GDataStructureCreateValue<E>>): GArray<E>
+        [Symbol.iterator](): IteratorObject<GArrayElement<T>>
+        proxy<Write extends boolean = false>(): Write extends true ? GArrayProxy<GArrayElement<T>> : GArrayReadProxy<GArrayElement<T>>
+        get_indexed<I extends int64>(index: I): GArrayElement<T, I>
+        get<I extends int64>(index: I): GArrayElement<T, I>
+        set<I extends int64>(index: I, value: GArrayElement<T, I>): void
+        size(): number
+        push_back(value: GArrayElement<T>): void
+        pop_back(): GArrayElement<T>
+        has(value: GArrayElement<T>): boolean
+        find(what: GArrayElement<T>, from: int64 = 0): int64
+    }
     type byte = number
     type int32 = number
     type uint32 = number

scripts/typings/godot.mix.d.ts

@@ -1,4 +1,3 @@
-///<reference path="godot.generated.d.ts" />
 declare module "godot" {
     const IntegerType: unique symbol;
     const FloatType: unique symbol;
@@ -199,6 +198,10 @@ declare module "godot" {
     type ResolveAnimationMixerPath<Map extends AnimationMixerPathMap, Path extends string, Default = never> =
         ResolvePath<Map, Path, Default, Animation, "", typeof __PathMappableDummyKeys['AnimationLibrary' | 'AnimationMixer']>;
 
+    type GArrayElement<T extends GAny | GAny[], I extends int64 = int64> = T extends any[]
+        ? T[I]
+        : T;
+
     /**
      * GArray elements are exposed with a subset of JavaScript's standard Array API. Array indexes are exposed as
      * enumerable properties, thus if you want to perform more complex operations you can convert to a regular
@@ -245,31 +248,45 @@ declare module "godot" {
 
     // Ideally this would be a class, but TS currently doesn't provide a way to type a class with mapped properties.
     /**
-     * GObject entries are exposed as enumerable properties, so Object.keys(), Object.entries() etc. will work.
+     * GObject entries are exposed as enumerable properties, so Object.keys(), GObject.entries() etc. will work.
      */
     type GDictionaryProxy<T> = {
         [K in keyof T]: T[K] | GProxyValueWrap<T[K]>; // More accurate get type blocked by https://github.com/microsoft/TypeScript/issues/43826
     };
 
-    type GProxyValueWrap<V> = V extends GArray<infer E>
-        ? GArrayProxy<E>
+    type GProxyValueWrap<V> = V extends GArray<infer T>
+        ? GArrayProxy<GArrayElement<T>>
         : V extends GDictionary<infer T>
             ? GDictionaryProxy<T>
             : V;
 
-    type GProxyValueUnwrap<V> = V extends GArray<infer E>
+    type GProxyValueUnwrap<V> = V extends GArrayProxy<infer E>
         ? E
-        : V extends GDictionary<infer T>
+        : V extends GDictionaryProxy<infer T>
             ? T
             : V;
 
-    type GWrappableValue = GAny | GWrappableValue[] | { [key: string]: GWrappableValue };
-    type GValueWrapUnchecked<V> = V extends Array<infer E>
-        ? GArray<GValueWrapUnchecked<E>>
+    type GWrappableValue = GAny | GWrappableValue[] | { [key: number | string]: GWrappableValue };
+    type GValueWrapUnchecked<V> = V extends any[]
+        ? number extends V["length"]
+            ? GArray<GValueWrapUnchecked<V[number]>>
+            : GArray<{ [I in keyof V]: GValueWrapUnchecked<V[I]> }>
         : V extends GAny
             ? V
             : GDictionary<{ [K in keyof V]: GValueWrapUnchecked<V[K]> }>;
-    type GValueWrap<V> = [V] extends [GWrappableValue] ? GValueWrapUnchecked<V> : never;
+    type GValueWrap<V> = [keyof V] extends [never]
+        ? GDictionary<{}>
+        : [V] extends [GWrappableValue]
+            ? GValueWrapUnchecked<V>
+            : never;
+
+    type GValueUnwrap<V> = V extends GArray<infer T>
+        ? T extends any[]
+            ? { [I in keyof T]: GValueUnwrap<T[I]> }
+            : Array<GValueUnwrap<T>>
+        : V extends GDictionary<infer T>
+            ? { [K in keyof T]: GValueUnwrap<T[K]> }
+            : V;
 
     /**
      * Semi-workaround for https://github.com/microsoft/TypeScript/issues/43826.