bare-url 2.5.1 → 2.5.3

package/binding.c

@@ -1,113 +1,230 @@
 #include <assert.h>
 #include <bare.h>
 #include <js.h>
+#include <stdbool.h>
 #include <stddef.h>
 #include <stdlib.h>
 #include <string.h>
 #include <url.h>
-#include <url/character-set.h>
-#include <url/percent-encode.h>
 #include <utf.h>
 #include <utf/string.h>
+#include <uv.h>
 
-// https://url.spec.whatwg.org/#concept-urlencoded-byte-serializer
-//
-// Everything except ASCII alphanumerics and `*-._` is percent-encoded. A space
-// (0x20) is a special case, encoded as `+` rather than `%20`, so it is left out
-// of the set and handled separately below.
-static url_character_set_t bare_url__form_urlencoded_percent_encode_set = {
-  // 00    01     02     03     04     05     06     07
-  0x01 | 0x02 | 0x04 | 0x08 | 0x10 | 0x20 | 0x40 | 0x80,
-  // 08    09     0a     0b     0c     0d     0e     0f
-  0x01 | 0x02 | 0x04 | 0x08 | 0x10 | 0x20 | 0x40 | 0x80,
-  // 10    11     12     13     14     15     16     17
-  0x01 | 0x02 | 0x04 | 0x08 | 0x10 | 0x20 | 0x40 | 0x80,
-  // 18    19     1a     1b     1c     1d     1e     1f
-  0x01 | 0x02 | 0x04 | 0x08 | 0x10 | 0x20 | 0x40 | 0x80,
-  // 20    21     22     23     24     25     26     27
-  0x00 | 0x02 | 0x04 | 0x08 | 0x10 | 0x20 | 0x40 | 0x80,
-  // 28    29     2a     2b     2c     2d     2e     2f
-  0x01 | 0x02 | 0x00 | 0x08 | 0x10 | 0x00 | 0x00 | 0x80,
-  // 30    31     32     33     34     35     36     37
-  0x00 | 0x00 | 0x00 | 0x00 | 0x00 | 0x00 | 0x00 | 0x00,
-  // 38    39     3a     3b     3c     3d     3e     3f
-  0x00 | 0x00 | 0x04 | 0x08 | 0x10 | 0x20 | 0x40 | 0x80,
-  // 40    41     42     43     44     45     46     47
-  0x01 | 0x00 | 0x00 | 0x00 | 0x00 | 0x00 | 0x00 | 0x00,
-  // 48    49     4a     4b     4c     4d     4e     4f
-  0x00 | 0x00 | 0x00 | 0x00 | 0x00 | 0x00 | 0x00 | 0x00,
-  // 50    51     52     53     54     55     56     57
-  0x00 | 0x00 | 0x00 | 0x00 | 0x00 | 0x00 | 0x00 | 0x00,
-  // 58    59     5a     5b     5c     5d     5e     5f
-  0x00 | 0x00 | 0x00 | 0x08 | 0x10 | 0x20 | 0x40 | 0x00,
-  // 60    61     62     63     64     65     66     67
-  0x01 | 0x00 | 0x00 | 0x00 | 0x00 | 0x00 | 0x00 | 0x00,
-  // 68    69     6a     6b     6c     6d     6e     6f
-  0x00 | 0x00 | 0x00 | 0x00 | 0x00 | 0x00 | 0x00 | 0x00,
-  // 70    71     72     73     74     75     76     77
-  0x00 | 0x00 | 0x00 | 0x00 | 0x00 | 0x00 | 0x00 | 0x00,
-  // 78    79     7a     7b     7c     7d     7e     7f
-  0x00 | 0x00 | 0x00 | 0x08 | 0x10 | 0x20 | 0x40 | 0x80,
-  // 80    81     82     83     84     85     86     87
-  0x01 | 0x02 | 0x04 | 0x08 | 0x10 | 0x20 | 0x40 | 0x80,
-  // 88    89     8a     8b     8c     8d     8e     8f
-  0x01 | 0x02 | 0x04 | 0x08 | 0x10 | 0x20 | 0x40 | 0x80,
-  // 90    91     92     93     94     95     96     97
-  0x01 | 0x02 | 0x04 | 0x08 | 0x10 | 0x20 | 0x40 | 0x80,
-  // 98    99     9a     9b     9c     9d     9e     9f
-  0x01 | 0x02 | 0x04 | 0x08 | 0x10 | 0x20 | 0x40 | 0x80,
-  // a0    a1     a2     a3     a4     a5     a6     a7
-  0x01 | 0x02 | 0x04 | 0x08 | 0x10 | 0x20 | 0x40 | 0x80,
-  // a8    a9     aa     ab     ac     ad     ae     af
-  0x01 | 0x02 | 0x04 | 0x08 | 0x10 | 0x20 | 0x40 | 0x80,
-  // b0    b1     b2     b3     b4     b5     b6     b7
-  0x01 | 0x02 | 0x04 | 0x08 | 0x10 | 0x20 | 0x40 | 0x80,
-  // b8    b9     ba     bb     bc     bd     be     bf
-  0x01 | 0x02 | 0x04 | 0x08 | 0x10 | 0x20 | 0x40 | 0x80,
-  // c0    c1     c2     c3     c4     c5     c6     c7
-  0x01 | 0x02 | 0x04 | 0x08 | 0x10 | 0x20 | 0x40 | 0x80,
-  // c8    c9     ca     cb     cc     cd     ce     cf
-  0x01 | 0x02 | 0x04 | 0x08 | 0x10 | 0x20 | 0x40 | 0x80,
-  // d0    d1     d2     d3     d4     d5     d6     d7
-  0x01 | 0x02 | 0x04 | 0x08 | 0x10 | 0x20 | 0x40 | 0x80,
-  // d8    d9     da     db     dc     dd     de     df
-  0x01 | 0x02 | 0x04 | 0x08 | 0x10 | 0x20 | 0x40 | 0x80,
-  // e0    e1     e2     e3     e4     e5     e6     e7
-  0x01 | 0x02 | 0x04 | 0x08 | 0x10 | 0x20 | 0x40 | 0x80,
-  // e8    e9     ea     eb     ec     ed     ee     ef
-  0x01 | 0x02 | 0x04 | 0x08 | 0x10 | 0x20 | 0x40 | 0x80,
-  // f0    f1     f2     f3     f4     f5     f6     f7
-  0x01 | 0x02 | 0x04 | 0x08 | 0x10 | 0x20 | 0x40 | 0x80,
-  // f8    f9     fa     fb     fc     fd     fe     ff
-  0x01 | 0x02 | 0x04 | 0x08 | 0x10 | 0x20 | 0x40 | 0x80,
-};
-
-// https://url.spec.whatwg.org/#concept-urlencoded-serializer
-static void
-bare_url__serialize_form_urlencoded_component(js_env_t *env, js_value_t *value, utf8_string_t *result) {
+// Maximum length, in bytes, of a UTF-8 string that is read into a stack buffer.
+// Longer strings fall back to a heap allocation. This covers the vast majority
+// of URLs without touching the heap.
+#define BARE_URL_STACK_STRING_MAX 1024
+
+// The number of component offsets the parser writes out.
+#define BARE_URL_COMPONENTS_LEN (sizeof(((url_t *) 0)->components) / sizeof(url_component_t))
+
+static bool
+bare_url__check_argc(js_env_t *env, size_t argc, size_t expected) {
   int err;
 
-  size_t len;
-  err = js_get_value_string_utf8(env, value, NULL, 0, &len);
+  if (argc < expected) {
+    err = js_throw_type_errorf(env, NULL, "Expected %zu arguments, got %zu", expected, argc);
+    assert(err == 0);
+
+    return false;
+  }
+
+  return true;
+}
+
+static bool
+bare_url__check_string(js_env_t *env, js_value_t *value, const char *message) {
+  int err;
+
+  bool is_string;
+  err = js_is_string(env, value, &is_string);
   assert(err == 0);
 
-  utf8_t *input = malloc(len);
-  err = js_get_value_string_utf8(env, value, input, len, NULL);
+  if (!is_string) {
+    err = js_throw_type_error(env, NULL, message);
+    assert(err == 0);
+  }
+
+  return is_string;
+}
+
+static bool
+bare_url__check_base(js_env_t *env, js_value_t *value, bool *has_base) {
+  int err;
+
+  js_value_type_t type;
+  err = js_typeof(env, value, &type);
   assert(err == 0);
 
-  for (size_t i = 0; i < len; i++) {
-    utf8_t c = input[i];
+  *has_base = type == js_string;
 
-    if (c == 0x20 /* space */) {
-      err = utf8_string_append_character(result, '+');
-    } else {
-      err = url__percent_encode_character(c, bare_url__form_urlencoded_percent_encode_set, result);
-    }
+  if (type == js_string || type == js_null || type == js_undefined) return true;
+
+  err = js_throw_type_error(env, NULL, "Base must be a string, null, or undefined");
+  assert(err == 0);
+
+  return false;
+}
+
+static bool
+bare_url__check_boolean(js_env_t *env, js_value_t *value, const char *message) {
+  int err;
+
+  bool is_boolean;
+  err = js_is_boolean(env, value, &is_boolean);
+  assert(err == 0);
+
+  if (!is_boolean) {
+    err = js_throw_type_error(env, NULL, message);
+    assert(err == 0);
+  }
+
+  return is_boolean;
+}
+
+static bool
+bare_url__check_components(js_env_t *env, js_value_t *value, uint32_t **result) {
+  int err;
+
+  bool is_typedarray;
+  err = js_is_typedarray(env, value, &is_typedarray);
+  assert(err == 0);
+
+  js_typedarray_type_t type;
+  size_t len;
+  js_value_t *arraybuffer;
+
+  if (is_typedarray) {
+    err = js_get_typedarray_info(env, value, &type, (void **) result, &len, &arraybuffer, NULL);
+    if (err < 0) return false;
+  }
+
+  if (!is_typedarray || type != js_uint32array) {
+    err = js_throw_type_error(env, NULL, "Components must be a Uint32Array");
+    assert(err == 0);
 
+    return false;
+  }
+
+  // A detached typed array reports no length of its own, but its data pointer
+  // is stale rather than null and so must not be written to.
+  bool is_detached;
+  err = js_is_detached_arraybuffer(env, arraybuffer, &is_detached);
+  assert(err == 0);
+
+  if (is_detached) {
+    err = js_throw_type_error(env, NULL, "Components must not be detached");
     assert(err == 0);
+
+    return false;
+  }
+
+  if (len < BARE_URL_COMPONENTS_LEN) {
+    err = js_throw_range_errorf(env, NULL, "Components must have at least %zu elements, got %zu", (size_t) BARE_URL_COMPONENTS_LEN, len);
+    assert(err == 0);
+
+    return false;
+  }
+
+  return true;
+}
+
+// The UTF-8 encoding of a JavaScript string, together with whatever backs it.
+typedef struct {
+  const utf8_t *data;
+  size_t len;
+
+  js_string_view_t *view;
+  utf8_t *heap;
+} bare_url_string_t;
+
+// Exposes `value` as UTF-8. Strings that are stored as ASCII, which is nearly
+// all of them, are borrowed directly from the engine without being copied.
+// Anything else is transcoded into `stack`, or into a freshly allocated heap
+// buffer when it does not fit. A non-zero return leaves an exception pending.
+// The result must be released with bare_url__free_string() either way.
+static inline int
+bare_url__read_string(js_env_t *env, js_value_t *value, utf8_t *stack, size_t stack_len, bare_url_string_t *result) {
+  int err;
+
+  result->data = NULL;
+  result->len = 0;
+  result->view = NULL;
+  result->heap = NULL;
+
+  js_string_encoding_t encoding;
+  const void *data;
+  size_t len;
+
+  err = js_get_string_view(env, value, &encoding, &data, &len, &result->view);
+  if (err < 0) return err;
+
+  size_t utf8_len;
+
+  if (encoding == js_utf8) {
+    result->data = (const utf8_t *) data;
+    result->len = len;
+
+    return 0;
+  }
+
+  if (encoding == js_latin1) {
+    utf8_len = utf8_length_from_latin1((const latin1_t *) data, len);
+
+    // A Latin-1 string that is no longer as UTF-8 contains only ASCII, whose
+    // Latin-1 and UTF-8 encodings are identical.
+    if (utf8_len == len) {
+      result->data = (const utf8_t *) data;
+      result->len = len;
+
+      return 0;
+    }
+  } else {
+    assert(encoding == js_utf16le);
+
+    utf8_len = utf8_length_from_utf16le((const utf16_t *) data, len);
+  }
+
+  utf8_t *buffer;
+
+  if (utf8_len <= stack_len) {
+    buffer = stack;
+  } else {
+    buffer = result->heap = malloc(utf8_len);
+
+    if (buffer == NULL) {
+      err = js_throw_error(env, uv_err_name(UV_ENOMEM), uv_strerror(UV_ENOMEM));
+      assert(err == 0);
+
+      return -1;
+    }
+  }
+
+  if (encoding == js_latin1) {
+    latin1_convert_to_utf8((const latin1_t *) data, len, buffer);
+  } else {
+    utf16le_convert_to_utf8((const utf16_t *) data, len, buffer);
   }
 
-  free(input);
+  result->data = buffer;
+  result->len = utf8_len;
+
+  return 0;
+}
+
+// Releases a string read with bare_url__read_string(), freeing its buffer only
+// when it was heap allocated rather than borrowed or written to the caller's
+// stack buffer.
+static inline void
+bare_url__free_string(js_env_t *env, bare_url_string_t *string) {
+  int err;
+
+  free(string->heap);
+
+  if (string->view == NULL) return;
+
+  err = js_release_string_view(env, string->view);
+  assert(err == 0);
 }
 
 static js_value_t *
@@ -120,80 +237,89 @@ bare_url_parse(js_env_t *env, js_callback_info_t *info) {
   err = js_get_callback_info(env, info, &argc, argv, NULL, NULL);
   assert(err == 0);
 
-  assert(argc == 4);
+  if (!bare_url__check_argc(env, argc, 4)) return NULL;
+
+  if (!bare_url__check_string(env, argv[0], "Input must be a string")) return NULL;
+
+  bool has_base;
+  if (!bare_url__check_base(env, argv[1], &has_base)) return NULL;
+
+  uint32_t *components;
+  if (!bare_url__check_components(env, argv[2], &components)) return NULL;
+
+  if (!bare_url__check_boolean(env, argv[3], "Throw must be a boolean")) return NULL;
 
   bool should_throw;
   err = js_get_value_bool(env, argv[3], &should_throw);
   assert(err == 0);
 
-  bool has_base;
-  err = js_is_string(env, argv[1], &has_base);
-  assert(err == 0);
+  // Set when the input could not be read, which leaves an exception of its own
+  // pending and so must not be reported as a parse failure on top.
+  bool threw = false;
 
   url_t base;
   url_init(&base);
 
   if (has_base) {
-    size_t len;
-    err = js_get_value_string_utf8(env, argv[1], NULL, 0, &len);
-    assert(err == 0);
+    utf8_t stack[BARE_URL_STACK_STRING_MAX];
 
-    utf8_t *input = malloc(len);
-    err = js_get_value_string_utf8(env, argv[1], input, len, NULL);
-    assert(err == 0);
+    bare_url_string_t input;
+    err = bare_url__read_string(env, argv[1], stack, sizeof(stack), &input);
 
-    err = url_parse(&base, input, len, NULL);
+    if (err == 0) err = url_parse(&base, input.data, input.len, NULL);
+    else threw = true;
 
-    free(input);
+    bare_url__free_string(env, &input);
 
     if (err < 0) {
       url_destroy(&base);
 
-      if (should_throw) js_throw_error(env, NULL, "Invalid base URL");
+      if (should_throw && !threw) {
+        err = js_throw_error(env, NULL, "Invalid base URL");
+        assert(err == 0);
+      }
 
       return NULL;
     }
   }
 
-  size_t len;
-  err = js_get_value_string_utf8(env, argv[0], NULL, 0, &len);
-  assert(err == 0);
-
-  utf8_t *input = malloc(len);
-  err = js_get_value_string_utf8(env, argv[0], input, len, NULL);
-  assert(err == 0);
+  utf8_t stack[BARE_URL_STACK_STRING_MAX];
 
-  js_value_t *handle;
+  bare_url_string_t input;
+  err = bare_url__read_string(env, argv[0], stack, sizeof(stack), &input);
 
   url_t url;
   url_init(&url);
 
-  err = url_parse(&url, input, len, has_base ? &base : NULL);
+  if (err == 0) err = url_parse(&url, input.data, input.len, has_base ? &base : NULL);
+  else threw = true;
 
-  free(input);
+  bare_url__free_string(env, &input);
 
   if (err < 0) {
     url_destroy(&base);
     url_destroy(&url);
 
-    if (should_throw) js_throw_error(env, NULL, "Invalid URL");
+    if (should_throw && !threw) {
+      err = js_throw_error(env, NULL, "Invalid URL");
+      assert(err == 0);
+    }
 
     return NULL;
   }
 
   js_value_t *href;
-  err = js_create_string_utf8(env, url.href.data, url.href.len, &href);
-  assert(err == 0);
+  err = js_create_string_latin1(env, (const latin1_t *) url.href.data, url.href.len, &href);
 
-  uint32_t *components;
-  err = js_get_typedarray_info(env, argv[2], NULL, (void **) &components, NULL, NULL, NULL);
-  assert(err == 0);
-
-  memcpy(components, &url.components, sizeof(url.components));
+  // The offsets are only handed over once the href they refer to is, so a
+  // failure here leaves the caller's buffer as it was.
+  if (err == 0) memcpy(components, &url.components, sizeof(url.components));
 
   url_destroy(&base);
   url_destroy(&url);
 
+  if (err < 0) return NULL;
+
   return href;
 }
 
@@ -207,31 +333,34 @@ bare_url_can_parse(js_env_t *env, js_callback_info_t *info) {
   err = js_get_callback_info(env, info, &argc, argv, NULL, NULL);
   assert(err == 0);
 
-  assert(argc == 2);
+  if (!bare_url__check_argc(env, argc, 2)) return NULL;
+
+  if (!bare_url__check_string(env, argv[0], "Input must be a string")) return NULL;
 
   bool has_base;
-  err = js_is_string(env, argv[1], &has_base);
-  assert(err == 0);
+  if (!bare_url__check_base(env, argv[1], &has_base)) return NULL;
+
+  bool threw = false;
 
   url_t base;
   url_init(&base);
 
   if (has_base) {
-    size_t len;
-    err = js_get_value_string_utf8(env, argv[1], NULL, 0, &len);
-    assert(err == 0);
+    utf8_t stack[BARE_URL_STACK_STRING_MAX];
 
-    utf8_t *input = malloc(len);
-    err = js_get_value_string_utf8(env, argv[1], input, len, NULL);
-    assert(err == 0);
+    bare_url_string_t input;
+    err = bare_url__read_string(env, argv[1], stack, sizeof(stack), &input);
 
-    err = url_parse(&base, input, len, NULL);
+    if (err == 0) err = url_parse(&base, input.data, input.len, NULL);
+    else threw = true;
 
-    free(input);
+    bare_url__free_string(env, &input);
 
     if (err < 0) {
       url_destroy(&base);
 
+      if (threw) return NULL;
+
       js_value_t *result;
       err = js_get_boolean(env, false, &result);
       assert(err == 0);
@@ -240,24 +369,24 @@ bare_url_can_parse(js_env_t *env, js_callback_info_t *info) {
     }
   }
 
-  size_t len;
-  err = js_get_value_string_utf8(env, argv[0], NULL, 0, &len);
-  assert(err == 0);
+  utf8_t stack[BARE_URL_STACK_STRING_MAX];
 
-  utf8_t *input = malloc(len);
-  err = js_get_value_string_utf8(env, argv[0], input, len, NULL);
-  assert(err == 0);
+  bare_url_string_t input;
+  err = bare_url__read_string(env, argv[0], stack, sizeof(stack), &input);
 
   url_t url;
   url_init(&url);
 
-  err = url_parse(&url, input, len, has_base ? &base : NULL);
+  if (err == 0) err = url_parse(&url, input.data, input.len, has_base ? &base : NULL);
+  else threw = true;
 
-  free(input);
+  bare_url__free_string(env, &input);
 
   url_destroy(&base);
   url_destroy(&url);
 
+  if (threw) return NULL;
+
   js_value_t *result;
   err = js_get_boolean(env, err == 0, &result);
   assert(err == 0);
@@ -265,56 +394,6 @@ bare_url_can_parse(js_env_t *env, js_callback_info_t *info) {
   return result;
 }
 
-static js_value_t *
-bare_url_serialize_form_urlencoded(js_env_t *env, js_callback_info_t *info) {
-  int err;
-
-  size_t argc = 1;
-  js_value_t *argv[1];
-
-  err = js_get_callback_info(env, info, &argc, argv, NULL, NULL);
-  assert(err == 0);
-
-  assert(argc == 1);
-
-  uint32_t len;
-  err = js_get_array_length(env, argv[0], &len);
-  assert(err == 0);
-
-  utf8_string_t result;
-  utf8_string_init(&result);
-
-  for (uint32_t i = 0; i + 1 < len; i += 2) {
-    js_value_t *pair[2];
-
-    err = js_get_element(env, argv[0], i, &pair[0]);
-    assert(err == 0);
-
-    err = js_get_element(env, argv[0], i + 1, &pair[1]);
-    assert(err == 0);
-
-    if (i != 0) {
-      err = utf8_string_append_character(&result, '&');
-      assert(err == 0);
-    }
-
-    bare_url__serialize_form_urlencoded_component(env, pair[0], &result);
-
-    err = utf8_string_append_character(&result, '=');
-    assert(err == 0);
-
-    bare_url__serialize_form_urlencoded_component(env, pair[1], &result);
-  }
-
-  js_value_t *output;
-  err = js_create_string_utf8(env, result.data, result.len, &output);
-  assert(err == 0);
-
-  utf8_string_destroy(&result);
-
-  return output;
-}
-
 static js_value_t *
 bare_url_exports(js_env_t *env, js_value_t *exports) {
   int err;
@@ -330,7 +409,6 @@ bare_url_exports(js_env_t *env, js_value_t *exports) {
 
   V("parse", bare_url_parse)
   V("canParse", bare_url_can_parse)
-  V("serializeSearchParams", bare_url_serialize_form_urlencoded)
 #undef V
 
   return exports;

package/global.d.ts

@@ -4,7 +4,19 @@ type URLConstructor = typeof url.URL
 type URLSearchParamsConstructor = typeof url.URLSearchParams
 
 declare global {
+  /**
+   * Parse `input` as a URL. If `base` is provided, `input` is resolved relative to `base`.
+   * @param input - The URL string to parse.
+   * @param base - A base URL that `input` is resolved relative to, if provided.
+   * @throws {INVALID_URL} `input` is not a valid URL.
+   */
   type URL = url.URL
+  /**
+   * Create a new `URLSearchParams` instance. `init` may be a query string, an iterable of `[name,
+   * value]` pairs, or an object of key-value pairs.
+   * @param init - A query string, an iterable of `[name, value]` pairs, or an object of key-value
+   * pairs to initialize the params from.
+   */
   type URLSearchParams = url.URLSearchParams
 
   const URL: URLConstructor

package/index.d.ts

@@ -2,37 +2,92 @@ import URLError from './lib/errors'
 import URLSearchParams from './lib/url-search-params'
 
 interface URL {
+  /** The full serialized URL string. Setting this property reparses the URL. */
   href: string
+  /** The URL scheme followed by `':'`, for example `'https:'`. */
   protocol: string
+  /** The username portion of the URL, or an empty string. */
   username: string
+  /** The password portion of the URL, or an empty string. */
   password: string
+  /** The hostname and port, for example `'example.com:8080'`. */
   host: string
+  /** The hostname without the port. */
   hostname: string
+  /** The port as a string, or an empty string if not present. */
   port: string
+  /** The path portion of the URL. */
   pathname: string
+  /** The query string including the leading `'?'`, or an empty string. */
   search: string
+  /**
+   * A `URLSearchParams` object for the query string. Mutations to the params are reflected in the
+   * URL.
+   */
   searchParams: URLSearchParams
+  /** The fragment including the leading `'#'`, or an empty string. */
   hash: string
 
+  /** Returns the serialized string form. */
   toString(): string
+  /** Returns the serialized string form. Suitable for JSON serialization. */
   toJSON(): string
 }
 
 declare class URL {
+  /**
+   * Parse `input` as a URL. If `base` is provided, `input` is resolved relative to `base`.
+   * @param input - The URL string to parse.
+   * @param base - A base URL that `input` is resolved relative to, if provided.
+   * @throws {INVALID_URL} `input` is not a valid URL.
+   */
   constructor(input: string | URL, base?: string | URL)
 }
 
 declare namespace URL {
+  /**
+   * Return `true` if `value` is a `URL` instance.
+   * @param value - The value to test.
+   */
   export function isURL(value: unknown): value is URL
 
+  /**
+   * Return `true` if `value` is a `URLSearchParams` instance.
+   * @param value - The value to test.
+   */
   export function isURLSearchParams(value: unknown): value is URLSearchParams
 
+  /**
+   * Parse `input` as a URL without throwing.
+   * @param input - The URL string to parse.
+   * @param base - A base URL that `input` is resolved relative to, if provided.
+   * @returns A `URL` instance if `input` parses successfully, or `null` on failure.
+   */
   export function parse(input: string, base?: string | URL): URL | null
 
+  /**
+   * Return `true` if `input` can be parsed as a valid URL, optionally relative to `base`.
+   * @param input - The URL string to test.
+   * @param base - A base URL that `input` is resolved relative to, if provided.
+   */
   export function canParse(input: string, base?: string | URL): boolean
 
+  /**
+   * Convert a `file:` URL to a platform-specific file path. `url` may be a `URL` instance or a
+   * string.
+   * @param url - The `file:` URL to convert, as a `URL` instance or a string.
+   * @throws {INVALID_URL_SCHEME} the URL does not use the `file:` protocol.
+   * @throws {INVALID_FILE_URL_HOST} (non-Windows) the URL has a host other than empty or
+   * `'localhost'`.
+   * @throws {INVALID_FILE_URL_PATH} the URL path contains an encoded path-separator or NUL
+   * character, or, on Windows, is not an absolute drive path.
+   */
   export function fileURLToPath(url: URL | string): string
 
+  /**
+   * Convert a platform-specific file path to a `file:` URL.
+   * @param pathname - The platform-specific file path to convert.
+   */
   export function pathToFileURL(pathname: string): URL
 
   export { URL, type URLError, URLError as errors, URLSearchParams }