bare-url 2.4.1 → 2.4.3

package/CMakeLists.txt

@@ -6,7 +6,7 @@ find_package(cmake-fetch REQUIRED PATHS node_modules/cmake-fetch)
 project(bare_url C)
 
 fetch_package("github:holepunchto/libutf#6b1a36f")
-fetch_package("github:holepunchto/liburl#03f1488")
+fetch_package("github:holepunchto/liburl#2215632")
 
 add_bare_module(bare_url)
 

package/README.md

@@ -1,6 +1,6 @@
 # bare-url
 
-WHATWG URL implementation for JavaScript.
+WHATWG URL implementation for JavaScript, built on <https://github.com/holepunchto/liburl>. Provides `URL` and `URLSearchParams` classes compatible with the WHATWG URL Standard.
 
 ```
 npm i bare-url
@@ -9,11 +9,164 @@ npm i bare-url
 ## Usage
 
 ```js
-const url = require('bare-url')
+const { URL, URLSearchParams } = require('bare-url')
 
-const p = url.fileURLToPath('file:///foo') // --> /foo
+const url = new URL('https://example.com/path?foo=bar#hash')
+
+console.log(url.hostname) // 'example.com'
+console.log(url.pathname) // '/path'
+console.log(url.searchParams.get('foo')) // 'bar'
+```
+
+To register `URL` and `URLSearchParams` as globals:
+
+```js
+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.
+
 ## License
 
 Apache-2.0

package/package.json

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