bare-url 2.5.2 → 2.5.3

package/CMakeLists.txt

@@ -9,7 +9,7 @@ fetch_package("github:holepunchto/libutf#a1ceca8")
 fetch_package("github:holepunchto/libpunycode#e91ee34")
 fetch_package("github:holepunchto/libnormalize#0e81f65")
 fetch_package("github:holepunchto/libidna#1471406")
-fetch_package("github:holepunchto/liburl#fc3abba")
+fetch_package("github:holepunchto/liburl#2efedc5")
 
 add_bare_module(bare_url)
 

package/README.md

@@ -26,146 +26,7 @@ require('bare-url/global')
 
 ## API
 
-#### `const url = new URL(input[, base])`
-
-Parse `input` as a URL. If `base` is provided, `input` is resolved relative to `base`. Throws if `input` is not a valid URL.
-
-#### `url.href`
-
-The full serialized URL string. Setting this property reparses the URL.
-
-#### `url.protocol`
-
-The URL scheme followed by `':'`, e.g. `'https:'`.
-
-#### `url.username`
-
-The username portion of the URL, or an empty string.
-
-#### `url.password`
-
-The password portion of the URL, or an empty string.
-
-#### `url.host`
-
-The hostname and port, e.g. `'example.com:8080'`.
-
-#### `url.hostname`
-
-The hostname without the port.
-
-#### `url.port`
-
-The port as a string, or an empty string if not present.
-
-#### `url.pathname`
-
-The path portion of the URL.
-
-#### `url.search`
-
-The query string including the leading `'?'`, or an empty string.
-
-#### `url.searchParams`
-
-A `URLSearchParams` object for the query string. Mutations to the params are reflected in the URL.
-
-#### `url.hash`
-
-The fragment including the leading `'#'`, or an empty string.
-
-#### `url.toString()`
-
-Returns the serialized URL string. Equivalent to `url.href`.
-
-#### `url.toJSON()`
-
-Returns the serialized URL string. Suitable for JSON serialization.
-
-#### `const params = new URLSearchParams([init])`
-
-Create a new `URLSearchParams` instance. `init` may be a query string, an iterable of `[name, value]` pairs, or an object of key-value pairs.
-
-#### `params.size`
-
-The total number of search parameters.
-
-#### `params.append(name, value)`
-
-Append a new `name`/`value` pair.
-
-#### `params.delete(name[, value])`
-
-Remove all pairs with `name`. If `value` is provided, only pairs with both the matching `name` and `value` are removed.
-
-#### `params.get(name)`
-
-Return the first value for `name`, or `null` if not present.
-
-#### `params.getAll(name)`
-
-Return all values for `name` as an array.
-
-#### `params.has(name[, value])`
-
-Return `true` if a pair with `name` exists. If `value` is provided, the pair must also match `value`.
-
-#### `params.set(name, value)`
-
-Set the value for `name`, replacing any existing pairs with that name.
-
-#### `params.toString()`
-
-Return the serialized query string without the leading `'?'`.
-
-#### `params.toJSON()`
-
-Return the parameters as an array of `[name, value]` pairs.
-
-#### `URL.isURL(value)`
-
-Return `true` if `value` is a `URL` instance.
-
-#### `URLSearchParams.isURLSearchParams(value)`
-
-Return `true` if `value` is a `URLSearchParams` instance.
-
-#### `const url = URL.parse(input[, base])`
-
-Parse `input` as a URL without throwing. Returns a `URL` instance on success, or `null` on failure.
-
-#### `const valid = URL.canParse(input[, base])`
-
-Return `true` if `input` can be parsed as a valid URL, optionally relative to `base`.
-
-#### `const pathname = URL.fileURLToPath(url)`
-
-Convert a `file:` URL to a platform-specific file path. `url` may be a `URL` instance or a string. Throws if the URL does not use the `file:` protocol or contains invalid path characters.
-
-#### `const url = URL.pathToFileURL(pathname)`
-
-Convert a platform-specific file path to a `file:` URL.
-
-#### `const href = URL.format(parts)`
-
-Format a URL from individual `parts`:
-
-```js
-parts = {
-  protocol,
-  auth,
-  host,
-  hostname,
-  port,
-  pathname,
-  search,
-  query,
-  hash,
-  slashes
-}
-```
-
-All properties are optional. If `host` is provided, `hostname` and `port` are ignored. If `search` is provided, `query` is ignored. Set `slashes` to `true` to include `'//'` after the protocol.
+See the [`bare-url` reference](https://docs.pears.com/reference/bare/modules/bare-url).
 
 ## License
 

package/binding.c

@@ -1,18 +1,134 @@
 #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 <utf.h>
 #include <utf/string.h>
+#include <uv.h>
 
 // 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;
+
+  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);
+
+  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);
+
+  *has_base = type == js_string;
+
+  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;
@@ -25,20 +141,23 @@ typedef struct {
 // 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. The result must be released with
-// bare_url__free_string().
-static inline void
+// 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);
-  assert(err == 0);
-
-  result->heap = NULL;
+  if (err < 0) return err;
 
   size_t utf8_len;
 
@@ -46,7 +165,7 @@ bare_url__read_string(js_env_t *env, js_value_t *value, utf8_t *stack, size_t st
     result->data = (const utf8_t *) data;
     result->len = len;
 
-    return;
+    return 0;
   }
 
   if (encoding == js_latin1) {
@@ -58,7 +177,7 @@ bare_url__read_string(js_env_t *env, js_value_t *value, utf8_t *stack, size_t st
       result->data = (const utf8_t *) data;
       result->len = len;
 
-      return;
+      return 0;
     }
   } else {
     assert(encoding == js_utf16le);
@@ -66,7 +185,20 @@ bare_url__read_string(js_env_t *env, js_value_t *value, utf8_t *stack, size_t st
     utf8_len = utf8_length_from_utf16le((const utf16_t *) data, len);
   }
 
-  utf8_t *buffer = utf8_len <= stack_len ? stack : (result->heap = malloc(utf8_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);
@@ -76,6 +208,8 @@ bare_url__read_string(js_env_t *env, js_value_t *value, utf8_t *stack, size_t st
 
   result->data = buffer;
   result->len = utf8_len;
+
+  return 0;
 }
 
 // Releases a string read with bare_url__read_string(), freeing its buffer only
@@ -87,6 +221,8 @@ bare_url__free_string(js_env_t *env, bare_url_string_t *string) {
 
   free(string->heap);
 
+  if (string->view == NULL) return;
+
   err = js_release_string_view(env, string->view);
   assert(err == 0);
 }
@@ -101,15 +237,25 @@ 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);
@@ -118,16 +264,20 @@ bare_url_parse(js_env_t *env, js_callback_info_t *info) {
     utf8_t stack[BARE_URL_STACK_STRING_MAX];
 
     bare_url_string_t input;
-    bare_url__read_string(env, argv[1], stack, sizeof(stack), &input);
+    err = bare_url__read_string(env, argv[1], stack, sizeof(stack), &input);
 
-    err = url_parse(&base, input.data, input.len, NULL);
+    if (err == 0) err = url_parse(&base, input.data, input.len, NULL);
+    else threw = true;
 
     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;
     }
@@ -136,12 +286,13 @@ bare_url_parse(js_env_t *env, js_callback_info_t *info) {
   utf8_t stack[BARE_URL_STACK_STRING_MAX];
 
   bare_url_string_t input;
-  bare_url__read_string(env, argv[0], stack, sizeof(stack), &input);
+  err = bare_url__read_string(env, argv[0], stack, sizeof(stack), &input);
 
   url_t url;
   url_init(&url);
 
-  err = url_parse(&url, input.data, input.len, has_base ? &base : NULL);
+  if (err == 0) err = url_parse(&url, input.data, input.len, has_base ? &base : NULL);
+  else threw = true;
 
   bare_url__free_string(env, &input);
 
@@ -149,24 +300,26 @@ bare_url_parse(js_env_t *env, js_callback_info_t *info) {
     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_latin1(env, (const latin1_t *) url.href.data, url.href.len, &href);
-  assert(err == 0);
-
-  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;
 }
 
@@ -180,11 +333,14 @@ 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);
@@ -193,15 +349,18 @@ bare_url_can_parse(js_env_t *env, js_callback_info_t *info) {
     utf8_t stack[BARE_URL_STACK_STRING_MAX];
 
     bare_url_string_t input;
-    bare_url__read_string(env, argv[1], stack, sizeof(stack), &input);
+    err = bare_url__read_string(env, argv[1], stack, sizeof(stack), &input);
 
-    err = url_parse(&base, input.data, input.len, NULL);
+    if (err == 0) err = url_parse(&base, input.data, input.len, NULL);
+    else threw = true;
 
     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);
@@ -213,18 +372,21 @@ bare_url_can_parse(js_env_t *env, js_callback_info_t *info) {
   utf8_t stack[BARE_URL_STACK_STRING_MAX];
 
   bare_url_string_t input;
-  bare_url__read_string(env, argv[0], stack, sizeof(stack), &input);
+  err = bare_url__read_string(env, argv[0], stack, sizeof(stack), &input);
 
   url_t url;
   url_init(&url);
 
-  err = url_parse(&url, input.data, input.len, has_base ? &base : NULL);
+  if (err == 0) err = url_parse(&url, input.data, input.len, has_base ? &base : NULL);
+  else threw = true;
 
   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);

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 }

package/index.js

@@ -17,6 +17,53 @@ const components = new Uint32Array(8)
 // The value used for a component that is not present in the URL.
 const unset = 0xffffffff
 
+// The schemes the parser treats specially. A URL cannot be switched between a
+// special and a non-special scheme, and a backslash only terminates a host for
+// the former.
+const special = new Set(['ftp', 'file', 'http', 'https', 'ws', 'wss'])
+
+// https://url.spec.whatwg.org/#scheme-start-state
+const scheme = /^[a-z][a-z0-9+\-.]*$/
+
+// ASCII tab and newline are removed from input before it is parsed rather than
+// percent-encoded like the other C0 controls.
+const whitespaceAll = /[\t\n\r]/g
+
+// The characters that terminate a host, and so bound the value the host and
+// hostname setters accept.
+const hostEnd = /[/\\?#]/
+const hostEndOpaque = /[/?#]/
+
+// The delimiters that would let a setter's value escape the component it is
+// spliced into. Everything else is left to the reparse, which applies the full
+// percent-encode set for the component. As elsewhere in this package, each set
+// needs two patterns because test() advances a global pattern's lastIndex.
+//
+// Credentials are not run through the parser and so keep their tabs and
+// newlines, percent-encoded, rather than having them stripped.
+const userinfoDelimiter = /[\t\n\r/\\?#@:]/
+const userinfoDelimiterAll = /[\t\n\r/\\?#@:]/g
+
+const pathDelimiter = /[?#]/
+const pathDelimiterAll = /[?#]/g
+
+// A leading or trailing run of C0 control or space in a value that ends up at
+// either end of the href. The parser strips those, but only when parsing a URL
+// as a whole, so a setter has to encode its own.
+const edges = /^[\u0000-\u0020]+|[\u0000-\u0020]+$/g
+
+const escapes = {
+  '\t': '%09',
+  '\n': '%0A',
+  '\r': '%0D',
+  '/': '%2F',
+  '\\': '%5C',
+  ':': '%3A',
+  '?': '%3F',
+  '@': '%40',
+  '#': '%23'
+}
+
 // The characters that pathToFileURL() has to percent-encode itself. A backslash
 // is a path separator on Windows and so is left alone there.
 const reserved = isWindows ? /[%#?\n\r\t]/ : /[%#?\n\r\t\\]/
@@ -57,7 +104,9 @@ class URL {
   }
 
   set href(value) {
-    this._update(value)
+    // Unlike every other setter, the href setter reports a parse failure rather
+    // than leaving the URL untouched.
+    this._parse(String(value), null, true)
 
     if (this._params) this._params._parse(this.search)
   }
@@ -69,7 +118,27 @@ class URL {
   }
 
   set protocol(value) {
-    this._update(this._replace(value.replace(/:+$/, ''), 0, this._schemeEnd))
+    value = strip(String(value))
+
+    const end = value.indexOf(':')
+
+    if (end !== -1) value = value.slice(0, end)
+
+    value = value.toLowerCase()
+
+    if (!scheme.test(value)) return
+
+    const current = this._slice(0, this._schemeEnd)
+
+    if (special.has(current) !== special.has(value)) return
+
+    if (value === 'file' && (this.username || this.password || this.port)) {
+      return
+    }
+
+    if (current === 'file' && this._hostStart === this._hostEnd) return
+
+    this._update(this._replace(value, 0, this._schemeEnd))
   }
 
   // https://url.spec.whatwg.org/#dom-url-username
@@ -83,7 +152,9 @@ class URL {
       return
     }
 
-    if (this.username === '') value += '@'
+    value = encodeUserinfo(String(value))
+
+    if (!hasCredentials(this)) value += '@'
 
     this._update(this._replace(value, this._schemeEnd + 3 /* :// */, this._usernameEnd))
   }
@@ -99,20 +170,16 @@ class URL {
       return
     }
 
-    let start = this._usernameEnd + 1 /* : */
-    let end = this._hostStart - 1 /* @ */
+    value = ':' + encodeUserinfo(String(value))
 
-    if (this.password === '') {
-      value = ':' + value
-      start--
-    }
+    let end = this._hostStart - 1 /* @ */
 
-    if (this.username === '') {
+    if (!hasCredentials(this)) {
       value += '@'
-      end++
+      end = this._usernameEnd
     }
 
-    this._update(this._replace(value, start, end))
+    this._update(this._replace(value, this._usernameEnd, end))
   }
 
   // https://url.spec.whatwg.org/#dom-url-host
@@ -126,9 +193,38 @@ class URL {
       return
     }
 
-    this._update(
-      this._replace(value, this._hostStart, value.includes(':') ? this._pathStart : this._hostEnd)
-    )
+    const protocol = this._slice(0, this._schemeEnd)
+
+    value = truncateHost(protocol, String(value))
+
+    // An `@` would make the reparse read the value as credentials rather than
+    // as a host, so it is rejected outright.
+    if (value.includes('@')) return
+
+    const separator = portSeparator(value)
+
+    let end = this._hostEnd
+
+    // A port in the value is parsed separately so that an invalid one leaves
+    // the existing port in place rather than rejecting the host along with it.
+    if (separator !== -1) {
+      // A file URL cannot have a port, so a value carrying one is rejected
+      // rather than split.
+      if (protocol === 'file') return
+
+      const port = parsePort(value.slice(separator + 1))
+
+      value = value.slice(0, separator)
+
+      if (port !== null) {
+        value += port
+        end = this._pathStart
+      }
+    }
+
+    if (value === '' && cannotHaveEmptyHost(protocol)) return
+
+    this._update(this._replace(value, this._hostStart, end))
   }
 
   // https://url.spec.whatwg.org/#dom-url-hostname
@@ -142,6 +238,17 @@ class URL {
       return
     }
 
+    const protocol = this._slice(0, this._schemeEnd)
+
+    value = truncateHost(protocol, String(value))
+
+    // A port cannot be set through this setter, and a value that carries one is
+    // rejected outright rather than truncated. An `@` would make the reparse
+    // read the value as credentials rather than as a host.
+    if (value.includes('@') || portSeparator(value) !== -1) return
+
+    if (value === '' && cannotHaveEmptyHost(protocol)) return
+
     this._update(this._replace(value, this._hostStart, this._hostEnd))
   }
 
@@ -156,14 +263,15 @@ class URL {
       return
     }
 
-    let start = this._hostEnd + 1 /* : */
+    value = strip(String(value))
 
-    if (this.port === '') {
-      value = ':' + value
-      start--
+    if (value !== '') {
+      value = parsePort(value)
+
+      if (value === null) return
     }
 
-    this._update(this._replace(value, start, this._pathStart))
+    this._update(this._replace(value, this._hostEnd, this._pathStart))
   }
 
   // https://url.spec.whatwg.org/#dom-url-pathname
@@ -177,7 +285,11 @@ class URL {
       return
     }
 
-    if (value[0] !== '/' && value[0] !== '\\') {
+    value = encodePath(encodeEdges(String(value)))
+
+    // An empty path is left alone, as only a special scheme is required to have
+    // one and the reparse inserts it there.
+    if (value !== '' && value[0] !== '/' && value[0] !== '\\') {
       value = '/' + value
     }
 
@@ -191,13 +303,17 @@ class URL {
   }
 
   set search(value) {
-    if (value && value[0] !== '?') value = '?' + value
+    value = String(value)
+
+    if (value !== '') {
+      if (value[0] === '?') value = value.slice(1)
+
+      value = '?' + encodeQuery(encodeEdges(value))
+    }
 
     this._update(
       this._replace(value, this._queryStart - 1 /* ? */, this._fragmentStart - 1 /* # */)
     )
-
-    if (this._params) this._params._parse(this.search)
   }
 
   // https://url.spec.whatwg.org/#dom-url-searchparams
@@ -217,7 +333,15 @@ class URL {
   }
 
   set hash(value) {
-    if (value && value[0] !== '#') value = '#' + value
+    value = String(value)
+
+    // The fragment runs to the end of the URL, so nothing in it can escape into
+    // another component and no delimiter needs encoding here.
+    if (value !== '') {
+      if (value[0] === '#') value = value.slice(1)
+
+      value = '#' + encodeEdges(value)
+    }
 
     this._update(this._replace(value, this._fragmentStart - 1 /* # */))
   }
@@ -262,7 +386,7 @@ class URL {
     try {
       href = binding.parse(input, base || null, components, shouldThrow)
     } catch (err) {
-      if (err instanceof TypeError) throw err
+      if (err instanceof TypeError || err.code !== undefined) throw err
 
       throw errors.INVALID_URL(`Invalid URL '${input}'`, input)
     }
@@ -290,7 +414,11 @@ class URL {
       this._parse(input, null, true)
     } catch (err) {
       if (err instanceof TypeError) throw err
+
+      return
     }
+
+    if (this._params) this._params._parse(this.search)
   }
 }
 
@@ -306,6 +434,93 @@ function cannotHaveCredentialsOrPort(url) {
   return url.hostname === '' || url.protocol === 'file:'
 }
 
+// Whether the URL carries a userinfo section, and so an `@` before its host.
+function hasCredentials(url) {
+  return url._hostStart !== url._usernameEnd
+}
+
+// Almost no input contains any of these, so it is worth ruling all three out
+// before rewriting anything.
+function strip(value) {
+  if (value.indexOf('\t') === -1 && value.indexOf('\n') === -1 && value.indexOf('\r') === -1) {
+    return value
+  }
+
+  return value.replace(whitespaceAll, '')
+}
+
+// https://url.spec.whatwg.org/#host-state
+//
+// Host parsing stops at the first character that starts another component, so
+// anything from there on is dropped rather than spliced into the host.
+function truncateHost(protocol, value) {
+  const end = value.search(special.has(protocol) ? hostEnd : hostEndOpaque)
+
+  return end === -1 ? value : value.slice(0, end)
+}
+
+// Only a special scheme other than file has to have a host.
+function cannotHaveEmptyHost(protocol) {
+  return protocol !== 'file' && special.has(protocol)
+}
+
+// The index of the colon that separates a host from its port, disregarding the
+// colons of an IPv6 address, or -1 if the host carries no port.
+function portSeparator(host) {
+  return host.indexOf(':', host[0] === '[' ? host.indexOf(']') : 0)
+}
+
+// https://url.spec.whatwg.org/#port-state
+//
+// Parsing stops at the first character that is not a digit, so a value with no
+// leading digits, or one that overflows, leaves the port as it was.
+function parsePort(value) {
+  value = /^\d*/.exec(value)[0]
+
+  if (value === '' || Number(value) > 65535) return null
+
+  return ':' + value
+}
+
+function encodeUserinfo(value) {
+  if (!userinfoDelimiter.test(value)) return value
+
+  return value.replace(userinfoDelimiterAll, (match) => escapes[match])
+}
+
+function encodePath(value) {
+  if (!pathDelimiter.test(value)) return value
+
+  return value.replace(pathDelimiterAll, (match) => escapes[match])
+}
+
+function encodeQuery(value) {
+  if (value.indexOf('#') === -1) return value
+
+  return value.replaceAll('#', '%23')
+}
+
+// Percent-encodes a leading or trailing run of C0 control or space, which the
+// parser would otherwise strip from a value that lands at either end of the
+// href. Every component that can end a URL encodes them anyway, so this only
+// brings the encoding forward.
+function encodeEdges(value) {
+  const len = value.length
+
+  if (len === 0) return value
+  if (value.charCodeAt(0) > 0x20 && value.charCodeAt(len - 1) > 0x20) return value
+
+  return value.replace(edges, (match) => {
+    let encoded = ''
+
+    for (let i = 0, n = match.length; i < n; i++) {
+      encoded += '%' + match.charCodeAt(i).toString(16).padStart(2, '0').toUpperCase()
+    }
+
+    return encoded
+  })
+}
+
 exports.URL = URL
 exports.URLSearchParams = URLSearchParams
 

package/lib/url-search-params.d.ts

@@ -1,22 +1,65 @@
 interface URLSearchParams extends Iterable<[name: string, value: string]> {
+  /** The total number of search parameters. */
   readonly size: number
 
+  /**
+   * Append a new `name`/`value` pair.
+   * @param name - The parameter name.
+   * @param value - The parameter value.
+   */
   append(name: string, value: string): void
+  /**
+   * Remove all pairs with `name`. If `value` is provided, only pairs with both the matching `name`
+   * and `value` are removed.
+   * @param name - The parameter name to remove.
+   * @param value - If provided, only pairs also matching this value are removed.
+   */
   delete(name: string, value?: string): void
+  /**
+   * Return the first value for `name`, or `null` if not present.
+   * @param name - The parameter name to look up.
+   */
   get(name: string): string | undefined
+  /**
+   * Return all values for `name` as an array.
+   * @param name - The parameter name to look up.
+   */
   getAll(name: string): string[]
+  /**
+   * Return `true` if a pair with `name` exists. If `value` is provided, the pair must also match
+   * `value`.
+   * @param name - The parameter name to check.
+   * @param value - If provided, the pair must also match this value.
+   */
   has(name: string, value?: string): boolean
+  /**
+   * Set the value for `name`, replacing any existing pairs with that name.
+   * @param name - The parameter name.
+   * @param value - The value to set.
+   */
   set(name: string, value: string): void
 
+  /** Returns the serialized string form. */
   toString(): string
+  /** Returns the serialized string form. Suitable for JSON serialization. */
   toJSON(): string
 }
 
 declare class URLSearchParams {
+  /**
+   * 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.
+   */
   constructor(init: string | Record<string, string> | Iterable<[string, string]>)
 }
 
 declare namespace URLSearchParams {
+  /**
+   * Return `true` if `value` is a `URLSearchParams` instance.
+   * @param value - The value to test.
+   */
   export function isURLSearchParams(value: unknown): value is URLSearchParams
 }
 

package/lib/url-search-params.js

@@ -1,8 +1,10 @@
 const kind = Symbol.for('bare.url.search-params.kind')
 
-class URLSearchParams {
-  static _urls = new WeakMap()
+// The URL each instance writes back to, if any. Kept module private so that the
+// setter it drives cannot be pointed at an arbitrary object.
+const urls = new WeakMap()
 
+class URLSearchParams {
   static get [kind]() {
     return 0 // Compatibility version
   }
@@ -11,7 +13,7 @@ class URLSearchParams {
   constructor(init, url = null) {
     this._params = null
 
-    if (url) URLSearchParams._urls.set(this, url)
+    if (url) urls.set(this, url)
 
     if (typeof init === 'string') {
       this._parse(init)
@@ -140,7 +142,7 @@ class URLSearchParams {
 
   // https://url.spec.whatwg.org/#concept-urlsearchparams-update
   _update() {
-    const url = URLSearchParams._urls.get(this)
+    const url = urls.get(this)
 
     if (url === undefined) return
 
@@ -234,8 +236,11 @@ const escapes = {
   '~': '%7E'
 }
 
-// A surrogate that is not part of a pair, and so does not encode a scalar value.
-const lone = /[\ud800-\udbff](?![\udc00-\udfff])|(?<![\ud800-\udbff])[\udc00-\udfff]/g
+// A surrogate pair, or a surrogate that is not part of one and so encodes no
+// scalar value. Pairs are matched first so that only the capture group can hold
+// a lone surrogate; a lookbehind would say this more directly but isn't
+// supported by every engine.
+const lone = /[\ud800-\udbff][\udc00-\udfff]|([\ud800-\udbff]|[\udc00-\udfff])/g
 
 function encode(component) {
   if (unencoded.test(component)) return component
@@ -249,7 +254,9 @@ function encode(component) {
   } catch {
     // encodeURIComponent() rejects lone surrogates, whereas the UTF-8 encoder the
     // serializer is defined in terms of replaces them with U+FFFD.
-    encoded = encodeURIComponent(component.replace(lone, '\ufffd'))
+    encoded = encodeURIComponent(
+      component.replace(lone, (match, single) => (single === undefined ? match : '\ufffd'))
+    )
   }
 
   if (encoded.includes('%20')) encoded = encoded.replaceAll('%20', '+')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bare-url",
-  "version": "2.5.2",
+  "version": "2.5.3",
   "description": "WHATWG URL implementation for JavaScript",
   "exports": {
     "./package": "./package.json",