feat: structuredClone typing

Co-Authored-By: Kisaragi <48310258+KisaragiEffective@users.noreply.github.com>

Author: uhyo

lib/lib.dom.d.ts

@@ -66,3 +66,89 @@ interface FontFaceSet extends EventTarget {
     thisArg?: This
   ): void;
 }
+
+declare namespace BetterTypeScriptLibInternals {
+  export namespace StructuredClone {
+    type Basics = [EvalError, RangeError, ReferenceError, TypeError, SyntaxError, URIError, Error, Boolean, String, Date, RegExp]
+    type DOMSpecifics = [
+        DOMException,
+        DOMMatrix,
+        DOMMatrixReadOnly,
+        DOMPoint,
+        DOMPointReadOnly,
+        DOMQuad,
+        DOMRect,
+        DOMRectReadOnly,
+    ]
+    type FileSystemTypeFamily = [
+        FileSystemDirectoryHandle,
+        FileSystemFileHandle,
+        FileSystemHandle,
+    ]
+    type WebGPURelatedTypeFamily = [
+        // GPUCompilationInfo,
+        // GPUCompilationMessage,
+    ]
+    type TypedArrayFamily = [
+        Int8Array, Int16Array, Int32Array, BigInt64Array, Uint8Array, Uint16Array, Uint32Array, BigUint64Array, Uint8ClampedArray,
+    ]
+    type Weaken = [
+        ...Basics,
+        // AudioData,
+        Blob,
+        // CropTarget,
+        // CryptoTarget,
+        ...DOMSpecifics,
+        ...FileSystemTypeFamily,
+        ...WebGPURelatedTypeFamily,
+        File, FileList,
+        ...TypedArrayFamily,
+        DataView, ImageBitmap, ImageData,
+        RTCCertificate,
+        VideoFrame,
+    ];
+
+    type MapSubtype<R> = {[k in keyof Weaken]: R extends Weaken[k] ? true : false};
+    type SelectNumericLiteral<H> = number extends H ? never : H;
+    type FilterByNumericLiteralKey<R extends Record<string | number, any>> = {[
+        k in keyof R as `${R[k] extends true ? Exclude<SelectNumericLiteral<k>, symbol> : never}`
+    ]: []};
+    type HitWeakenEntry<E> = keyof FilterByNumericLiteralKey<MapSubtype<E>>;
+
+    type NonCloneablePrimitive = Function | { new(...args: any[]): any } | ((...args: any[]) => any) | symbol;
+
+    type Writeable<T> = T extends readonly [] ? [] : T extends readonly [infer X, ...infer XS] ? [X, ...XS] : T extends { [x: PropertyKey]: any } ? {
+        -readonly [P in keyof T]: Writeable<T[P]>;
+    } : T;
+
+    type StructuredCloneOutput<T> = 
+        T extends NonCloneablePrimitive
+            ? never
+            : T extends ReadonlyArray<any>
+                ? number extends T["length"]
+                    ? Array<StructuredCloneOutput<T[number]>>
+                    : T extends [infer X, ...infer XS]
+                        ? [StructuredCloneOutput<X>, ...StructuredCloneOutput<XS>]
+                        : Writeable<T>
+                : T extends Map<infer K, infer V>
+            ? Map<StructuredCloneOutput<K>, StructuredCloneOutput<V>>
+            : T extends Set<infer E>
+            ? Set<StructuredCloneOutput<E>>
+            : T extends Record<any, any>
+                ? HitWeakenEntry<T> extends never
+                    ? Writeable<{-readonly [k in Exclude<keyof T, symbol> as `${[StructuredCloneOutput<T[k]>] extends [never] ? never : k}`]: StructuredCloneOutput<T[k]>}>
+                    // hit
+                    : Weaken[HitWeakenEntry<T>]
+                : T
+
+    type AvoidCyclicConstraint<T> = [T] extends [infer R] ? R : never;
+
+    // 上限が不正にきつくなっているのを無視する
+    type NeverOrUnknown<T> = [T] extends [never] ? never : unknown;
+  }
+}
+
+/** [MDN Reference](https://developer.mozilla.org/docs/Web/API/structuredClone) */
+declare function structuredClone<const T extends BetterTypeScriptLibInternals.StructuredClone.NeverOrUnknown<BetterTypeScriptLibInternals.StructuredClone.StructuredCloneOutput<BetterTypeScriptLibInternals.StructuredClone.AvoidCyclicConstraint<T>>>>(
+    value: T, options?: StructuredSerializeOptions,
+): BetterTypeScriptLibInternals.StructuredClone.StructuredCloneOutput<T>

tests/src/dom.ts

@@ -1,7 +1,113 @@
-import { expectType } from "tsd";
+import { expectNotType, expectType } from "tsd";
 
 const test = async (url: string) => {
   const response = await fetch(url);
   const json = await response.json();
   expectType<JSONValue>(json);
 };
+
+// structuredClone
+{
+  // primitives
+  expectType<5>(structuredClone(5));
+  expectType<"hello">(structuredClone("hello"));
+  expectType<true>(structuredClone(true));
+  expectType<undefined>(structuredClone(undefined));
+  expectType<null>(structuredClone(null));
+  // plain objects
+  expectType<{ a: 5 }>(structuredClone({ a: 5 }));
+  expectType<{
+    a: 5;
+    nested: {
+      b: "hello";
+    };
+  }>(structuredClone({ a: 5, nested: { b: "hello" } }));
+  const obj = { a: 5 };
+  expectType<{ a: number }>(structuredClone(obj));
+  // arrays
+  expectType<[1, 2, 3]>(structuredClone([1, 2, 3]));
+  expectType<["a", "b", "c"]>(structuredClone(["a", "b", "c"]));
+  const arr = [1, 2, 3];
+  expectType<number[]>(structuredClone(arr));
+  // read-onlyness is removed
+  {
+    const a: readonly number[] = [1, 2, 3];
+    const b = structuredClone(a);
+    expectType<number[]>(b);
+    b.push(4);
+  }
+  // TypedArrays
+  expectType<Int16Array>(structuredClone(new Int16Array()));
+  {
+    // class instances are converted to base built-in types
+    class Weirdo extends Int16Array {
+      public weirdo: undefined = undefined;
+    }
+
+    class Weirdo2 extends Int32Array {
+      public weirdo2: undefined = undefined;
+    }
+
+    expectType<Int16Array>(structuredClone(new Weirdo()));
+
+    // @ts-expect-error property does not exist
+    structuredClone(new Weirdo()).weirdo;
+    const f: readonly [Weirdo] = [new Weirdo()] as const;
+    expectType<[Int16Array]>(structuredClone(f));
+    // @ts-expect-error property does not exist
+    structuredClone(f)[0].weirdo;
+
+    const g = { a: new Weirdo() };
+    const g2 = structuredClone(g);
+    expectType<{ a: Int16Array }>(g2);
+    // @ts-expect-error property does not exist
+    g2.a.weirdo;
+
+    const h = new Map([[new Weirdo(), new Weirdo2()]]);
+    const i = structuredClone(h);
+    expectType<Map<Int16Array, Int32Array>>(i);
+    expectNotType<Map<Weirdo, Weirdo2>>(i);
+
+    const j = new Set([new Weirdo()]);
+    const k: Set<Int16Array> = structuredClone(j);
+    expectNotType<Set<Weirdo>>(k);
+
+    class Empty {}
+    expectType<{}>(structuredClone(new Empty()));
+    class SingleProp {
+      hello: number = 3;
+    }
+    expectType<{ hello: number }>(structuredClone(new SingleProp()));
+
+    class WithConstructor {
+      hi: number;
+      constructor(hi: number) {
+        this.hi = hi;
+      }
+    }
+
+    expectType<{ hi: number }>(structuredClone(new WithConstructor(1)));
+
+    class WithFunction {
+      hello(): "hi" {
+        return "hi";
+      }
+    }
+
+    expectType<{}>(structuredClone(new WithFunction()));
+    // @ts-expect-error
+    structuredClone(new WithFunction()).hello();
+    //    ^?
+    const x = structuredClone({ s: () => 1 });
+    //    ^?
+  }
+  // non-clonable objects
+  {
+    // @ts-expect-error
+    const m = structuredClone(class {});
+    // @ts-expect-error
+    const n = structuredClone(Symbol.iterator);
+    // @ts-expect-error
+    const p = structuredClone(() => 1);
+  }
+}