From b2a7cfe0c2a094b974c628cbd8d51ff2d3f0a250 Mon Sep 17 00:00:00 2001
From: Laurence Rowe <l@lrowe.co.uk>
Date: Mon, 18 Sep 2023 16:48:13 -0700
Subject: [PATCH] fix(Symbol): deprecate `for_global` in favour of `for_key`
 and `for_api` (#1324)

`for_global` was documented as `for_key` but implemented as `for_api`.

Closes #1323
---
 src/symbol.rs     | 36 ++++++++++++++++++++++++++++++++++++
 tests/test_api.rs | 14 ++++++++++++--
 2 files changed, 48 insertions(+), 2 deletions(-)

diff --git a/src/symbol.rs b/src/symbol.rs
index 42e0da83..a118092f 100644
--- a/src/symbol.rs
+++ b/src/symbol.rs
@@ -10,6 +10,10 @@ extern "C" {
     isolate: *mut Isolate,
     description: *const String,
   ) -> *const Symbol;
+  fn v8__Symbol__For(
+    isolate: *mut Isolate,
+    description: *const String,
+  ) -> *const Symbol;
   fn v8__Symbol__ForApi(
     isolate: *mut Isolate,
     description: *const String,
@@ -58,6 +62,38 @@ impl Symbol {
   /// To minimize the potential for clashes, use qualified descriptions as keys.
   /// Corresponds to v8::Symbol::For() in C++.
   #[inline(always)]
+  pub fn for_key<'s>(
+    scope: &mut HandleScope<'s, ()>,
+    description: Local<String>,
+  ) -> Local<'s, Symbol> {
+    unsafe {
+      scope
+        .cast_local(|sd| v8__Symbol__For(sd.get_isolate_ptr(), &*description))
+    }
+    .unwrap()
+  }
+
+  /// Retrieve a global symbol. Similar to `for_key`, but using a separate
+  /// registry that is not accessible by (and cannot clash with) JavaScript code.
+  /// Corresponds to v8::Symbol::ForApi() in C++.
+  #[inline(always)]
+  pub fn for_api<'s>(
+    scope: &mut HandleScope<'s, ()>,
+    description: Local<String>,
+  ) -> Local<'s, Symbol> {
+    unsafe {
+      scope.cast_local(|sd| {
+        v8__Symbol__ForApi(sd.get_isolate_ptr(), &*description)
+      })
+    }
+    .unwrap()
+  }
+
+  #[deprecated(
+    since = "0.77.0",
+    note = "This was documented as `for_key` but implemented as `for_api`"
+  )]
+  #[inline(always)]
   pub fn for_global<'s>(
     scope: &mut HandleScope<'s, ()>,
     description: Local<String>,
diff --git a/tests/test_api.rs b/tests/test_api.rs
index 6c418bce..804ae2af 100644
--- a/tests/test_api.rs
+++ b/tests/test_api.rs
@@ -7374,14 +7374,24 @@ fn symbol() {
   let s = v8::Symbol::new(scope, Some(desc));
   assert!(s.description(scope) == desc);
 
-  let s_pub = v8::Symbol::for_global(scope, desc);
+  let s_pub = v8::Symbol::for_key(scope, desc);
   assert!(s_pub.description(scope) == desc);
   assert!(s_pub != s);
 
-  let s_pub2 = v8::Symbol::for_global(scope, desc);
+  let s_pub2 = v8::Symbol::for_key(scope, desc);
   assert!(s_pub2 != s);
   assert!(s_pub == s_pub2);
 
+  let s_api = v8::Symbol::for_api(scope, desc);
+  assert!(s_api.description(scope) == desc);
+  assert!(s_api != s);
+  assert!(s_api != s_pub);
+
+  let s_api2 = v8::Symbol::for_api(scope, desc);
+  assert!(s_api2 != s);
+  assert!(s_api2 != s_pub);
+  assert!(s_api == s_api2);
+
   let context = v8::Context::new(scope);
   let scope = &mut v8::ContextScope::new(scope, context);