From ab9513179c767534edccced7190d2578044064f1 Mon Sep 17 00:00:00 2001
From: sharpchen <77432836+sharpchen@users.noreply.github.com>
Date: Sun, 5 Jul 2026 19:12:52 +0800
Subject: [PATCH] =?UTF-8?q?=F0=9F=A4=96=20Merge=20PR=20#75211=20mpv-script?=
 =?UTF-8?q?:=20add=20more=20globals=20by=20@sharpchen?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 types/mpv-script/index.d.ts          | 67 ++++++++++++++++++++++++++++
 types/mpv-script/mpv-script-tests.ts | 34 ++++++++++++++
 2 files changed, 101 insertions(+)

diff --git a/types/mpv-script/index.d.ts b/types/mpv-script/index.d.ts
index ad1fbdc833ef53..340717b1a2b863 100644
--- a/types/mpv-script/index.d.ts
+++ b/types/mpv-script/index.d.ts
@@ -312,8 +312,75 @@ declare namespace mp {
     }
 }
 
+/**
+ * A convenient alias to `mp.msg.info`.
+ */
 declare function print(...msg: unknown[]): void;
 
+/**
+ * Like `print` but also expands objects and arrays recursively.
+ */
 declare function dump(...msg: unknown[]): void;
 
+/**
+ * Make the script exit at the end of the current event loop iteration. This does not terminate mpv itself or other scripts.
+ * This can be polyfilled to support mpv versions older than 0.40 with:
+ */
 declare function exit(): void;
+
+// nominal brand for setTimeout returns, in case a random number is passed to clearTimeout
+type __TimeoutId = number & { __brand: "setTimeout" };
+type __IntervalId = number & { __brand: "setInterval" };
+
+/**
+ * @param fn callback for each interval
+ * @param delay delay in millisecond
+ * @param args args for `fn`
+ * @returns id
+ */
+declare function setTimeout<TArgs extends any[]>(
+    fn: (...args: TArgs) => void,
+    delay?: number,
+    ...args: TArgs
+): __TimeoutId;
+
+/**
+ * @param codeString javascript code
+ * @param delay delay in millisecond
+ * @returns id
+ */
+declare function setTimeout(codeString: string, delay?: number): __TimeoutId;
+
+/**
+ * Cancels a scheduled timeout
+ */
+declare function clearTimeout(id: __TimeoutId): void;
+
+/**
+ * @param fn callback for each interval
+ * @param delay delay to first start and interval(millisecond)
+ * @param args args for `fn`
+ * @returns id
+ */
+declare function setInterval<TArgs extends any[]>(
+    fn: (...args: TArgs) => void,
+    delay?: number,
+    ...args: TArgs
+): __IntervalId;
+
+/**
+ * @param codeString javascript code
+ * @param delay delay in millisecond
+ * @returns id
+ */
+declare function setInterval(codeString: string, delay?: number): __IntervalId;
+
+/**
+ * Stop a recurring timer
+ */
+declare function clearInterval(id: __IntervalId): void;
+
+/**
+ * note: compilerOptions.module in tsconfig/jsconfig should be set properly otherwise it might not resolve shape of the exports
+ */
+declare function require(mod: string): any;
diff --git a/types/mpv-script/mpv-script-tests.ts b/types/mpv-script/mpv-script-tests.ts
index 3eda67700198d8..043c629f4fa848 100644
--- a/types/mpv-script/mpv-script-tests.ts
+++ b/types/mpv-script/mpv-script-tests.ts
@@ -184,3 +184,37 @@ if (osd_size) {
     // $ExpectType number | undefined
     osd_size.aspect;
 }
+
+// $ExpectType __IntervalId
+const interval_id = setInterval(
+    function(foo, bar) {
+        // $ExpectType string
+        const a = foo;
+        // $ExpectType number
+        const b = bar;
+    },
+    1000,
+    "foo",
+    1,
+);
+
+// @ts-expect-error
+clearInterval(100);
+
+// $ExpectType __TimeoutId
+const timeout_id = setTimeout(
+    function(foo, bar) {
+        // $ExpectType string
+        const a = foo;
+        // $ExpectType number
+        const b = bar;
+    },
+    1000,
+    "foo",
+    1,
+);
+
+// @ts-expect-error
+clearTimeout(interval_id);
+
+clearTimeout(timeout_id);