From 95980426595beaae4d40393eebc8ebad523d9b95 Mon Sep 17 00:00:00 2001 From: Alan Marko Date: Fri, 20 Oct 2023 14:12:31 +0100 Subject: [PATCH 1/6] First draft --- docs/api/url_search_params.md | 207 ++++++++++++++++++++++++++++++++++ 1 file changed, 207 insertions(+) create mode 100644 docs/api/url_search_params.md diff --git a/docs/api/url_search_params.md b/docs/api/url_search_params.md new file mode 100644 index 000000000..d249af546 --- /dev/null +++ b/docs/api/url_search_params.md @@ -0,0 +1,207 @@ +# 🔗 URLSearchParams + +`jstz` implementation of an API with utility methods for working with the query string of a URL according to the [URLSearchParams specification](https://url.spec.whatwg.org/#urlsearchparams). It is used for building and manipulating search parameters. + +## Example + +```typescript +// Parse query string from URL +let url = new URL("https://example.com?foo=1&bar=2"); +let params = new UrlSearchParams(url.search); + +// Add a new parameter +params.append("baz", 3); + +// Remove parameter +params.delete("bar"); + +// Loop through parameters +for (let [key, value] of params) { + // ... +} +``` + +## Constructor + +### `UrlSearchParams(values: Array<[Name: string, Value: string]>)` + +Creates a new instance of `UrlSearchParams` with the provided key-value pairs. + +- **values**: An array of key-value pairs. Each pair is an array where the first element is the key (Name) and the second is the value. + +## Instance Methods + +### `len(): number` + +- **Returns**: The number of search parameters present. + +### `append(name: string, value: string): void` + +Appends a specified key/value pair as a new search parameter. + +- **name**: The name of the search parameter. +- **value**: The value of the search parameter. + +**More information**: + +- [WHATWG specification](https://url.spec.whatwg.org/#dom-urlsearchparams-append) + +### `remove(name: string, value?: string): void` + +Removes search parameters that match the given name. If a value is provided, only parameters with that name-value pair are removed. + +- **name**: The name of the search parameter to be removed. +- **value** (optional): The specific value of the search parameter to be removed. + +**More information**: + +- [WHATWG specification](https://url.spec.whatwg.org/#dom-urlsearchparams-delete) + +### `get(name: string): string | null` + +Returns the first value associated with the given search parameter. + +- **name**: The name of the search parameter. + +- **Returns**: The value associated with the given search parameter or `null` if not found. + +**More information**: + +- [WHATWG specification](https://url.spec.whatwg.org/#dom-urlsearchparams-get) + +### `getAll(name: string): Array` + +Returns all the values associated with a given search parameter. + +- **name**: The name of the search parameter. + +- **Returns**: An array of values associated with the given search parameter. + +**More information**: + +- [WHATWG specification](https://url.spec.whatwg.org/#dom-urlsearchparams-getall) + +Note: The documentation provided here is tailored for JavaScript usage, based on the Rust code you provided that is designed for a JS runtime. + +```typescript +let url: URL = new URL(`tezos://${my_contract.address}/entrypoint`); +let url2: URL = new URL("../entrypoint_2", url.href); +``` + +Jstz smart functions each have their own unique address which is generated by jstz when the contract is deployed. +These are loosely analagous to http addresses. Jszt has its own URI scheme `tezos` to refer to contracts. +An example host of a jstz smart function would therefore be `tezos://tz4w42Gt5zkiGaHPm1ya4MgLomgkL1k7Dy7q`. + +The constructor will raise and exception if the arguments cannot be parsed into a valid url. +The [`URL.canParse()`](#canParse) method can be used to check if the arguments can be parsed correctly. + +```typescript +if (URL.canParse(relativePath, baseUrl)) { + let url = new URL(relativePath, baseUrl); + console.log(url.href); +} else { + // the URL cannot be parsed, take appropriate action. + console.error("Invalid URL"); +} +``` + +We may edit or construct a url by setting values for its properties. + +```typescript +let url = new URL('tezos://domain/); // not a valid jstz hostname, we'll have to change it +url.hostname = Ledger.selfAddress; +url.pathname = "my_entrypoint" +url.hash = "my_fragment" +console.log(url.href) // tezos://tz4../my_entrypoint#my_fagment +``` + +The [`URLSearchParams`](./url_search_params.md) API may be used to build and manipulate search parameters. To get the search parameters from the URL, you may use the `.searchParams` instance property. + +```typescript +let url = new URL(`tezos://${address}/?first_name=Dave`); +switch (url.searchParams.get("first_name")) { + case "Jim": + url.searchParams.set("last_name", "Jones"); + break; + case "Sarah": + url.searchParams.set("last_name", "Smith"); + break; + case "Dave": + url.searchParams.set("last_name", "Davies"); + break; +} +``` + +## Constructor + +### `URL(url: string, base?: string): URL` + +Constructs a URL from a url string and an optional base string. +If `base` if present then `url` will be interpreted as a relative url. +If `base` is not present then `url` will be interpreted as an absolute url. + +## Instance Properties + +### `hash: string` + +The fragment identifier of the URL. + +### `host: string` + +The host, a string containing the hostname (see below), followed by a ':' and the port of the url. + +### `hostname: string` + +The hostname of the url. In `jstz` this will usually be a `tz4` address of a smart function. + +### `href: string` {#href} + +A stringifier, returns the whole url. + +### `readonly origin: string` + +The origin of the url, specifically the scheme, the domain and the port. + +### `password: string` + +The password specified before the domain name. + +### `pathname: string` + +The url path. This will always begin with a `'/'` and contains the part of the url up until the query string or fragment. + +### `port: string` + +The port number of the url. This has no special meaning within `jstz` and will not usually be present. + +### `protocol: string` + +The protocol scheme of the url. Within `jstz` this will usually be `tezos:` + +### `search: string` + +The URL's search parameter string, This will include all the search parameters of the url, each of which begins with a `'?'`. + +### `readonly searchParams: URLSearchParams` + +The search parameter object. See [`URLSearchParams`](./url_search_params.md) for more information. + +### `username: string` + +The username specified before the domain name. + +## Static Methods + +### `canParse(url: string, base?: string): boolean` {#canParse} + +Returns `true` if the url and base string can be parsed into a valid URL. + +## Instance Methods + +### `toString(): string` + +An alias for [`href`](#href); returns the whole url as a string. + +### `toJSON(): string` + +An alias for [`href`](#href); returns the whole url as a string. From 913b3a36e0778cda68fb62e6aa90c51be31aae06 Mon Sep 17 00:00:00 2001 From: Alan Marko Date: Fri, 20 Oct 2023 16:05:46 +0100 Subject: [PATCH 2/6] URLSearchParams documentation --- docs/api/url_search_params.md | 158 ++++++---------------------------- 1 file changed, 25 insertions(+), 133 deletions(-) diff --git a/docs/api/url_search_params.md b/docs/api/url_search_params.md index d249af546..5a6642cf6 100644 --- a/docs/api/url_search_params.md +++ b/docs/api/url_search_params.md @@ -23,7 +23,7 @@ for (let [key, value] of params) { ## Constructor -### `UrlSearchParams(values: Array<[Name: string, Value: string]>)` +### `UrlSearchParams(values: Array<[Name: string, Value: string]>, url?: URL)` Creates a new instance of `UrlSearchParams` with the provided key-value pairs. @@ -31,6 +31,18 @@ Creates a new instance of `UrlSearchParams` with the provided key-value pairs. ## Instance Methods +### `setValues(values: Array<[Name: string, Value: string]>): void` + +Sets the current values with the provided array of key-value pairs. + +- **values**: An array of key-value pairs. Each pair consists of a name (key) and value. + +### `setUrl(url: JsNativeObject): void` + +Associates the `UrlSearchParams` with a given `Url` object. + +- **url**: A reference to the `Url` object. + ### `len(): number` - **Returns**: The number of search parameters present. @@ -42,10 +54,6 @@ Appends a specified key/value pair as a new search parameter. - **name**: The name of the search parameter. - **value**: The value of the search parameter. -**More information**: - -- [WHATWG specification](https://url.spec.whatwg.org/#dom-urlsearchparams-append) - ### `remove(name: string, value?: string): void` Removes search parameters that match the given name. If a value is provided, only parameters with that name-value pair are removed. @@ -53,10 +61,6 @@ Removes search parameters that match the given name. If a value is provided, onl - **name**: The name of the search parameter to be removed. - **value** (optional): The specific value of the search parameter to be removed. -**More information**: - -- [WHATWG specification](https://url.spec.whatwg.org/#dom-urlsearchparams-delete) - ### `get(name: string): string | null` Returns the first value associated with the given search parameter. @@ -65,10 +69,6 @@ Returns the first value associated with the given search parameter. - **Returns**: The value associated with the given search parameter or `null` if not found. -**More information**: - -- [WHATWG specification](https://url.spec.whatwg.org/#dom-urlsearchparams-get) - ### `getAll(name: string): Array` Returns all the values associated with a given search parameter. @@ -77,131 +77,23 @@ Returns all the values associated with a given search parameter. - **Returns**: An array of values associated with the given search parameter. -**More information**: - -- [WHATWG specification](https://url.spec.whatwg.org/#dom-urlsearchparams-getall) - -Note: The documentation provided here is tailored for JavaScript usage, based on the Rust code you provided that is designed for a JS runtime. - -```typescript -let url: URL = new URL(`tezos://${my_contract.address}/entrypoint`); -let url2: URL = new URL("../entrypoint_2", url.href); -``` - -Jstz smart functions each have their own unique address which is generated by jstz when the contract is deployed. -These are loosely analagous to http addresses. Jszt has its own URI scheme `tezos` to refer to contracts. -An example host of a jstz smart function would therefore be `tezos://tz4w42Gt5zkiGaHPm1ya4MgLomgkL1k7Dy7q`. - -The constructor will raise and exception if the arguments cannot be parsed into a valid url. -The [`URL.canParse()`](#canParse) method can be used to check if the arguments can be parsed correctly. - -```typescript -if (URL.canParse(relativePath, baseUrl)) { - let url = new URL(relativePath, baseUrl); - console.log(url.href); -} else { - // the URL cannot be parsed, take appropriate action. - console.error("Invalid URL"); -} -``` - -We may edit or construct a url by setting values for its properties. - -```typescript -let url = new URL('tezos://domain/); // not a valid jstz hostname, we'll have to change it -url.hostname = Ledger.selfAddress; -url.pathname = "my_entrypoint" -url.hash = "my_fragment" -console.log(url.href) // tezos://tz4../my_entrypoint#my_fagment -``` - -The [`URLSearchParams`](./url_search_params.md) API may be used to build and manipulate search parameters. To get the search parameters from the URL, you may use the `.searchParams` instance property. - -```typescript -let url = new URL(`tezos://${address}/?first_name=Dave`); -switch (url.searchParams.get("first_name")) { - case "Jim": - url.searchParams.set("last_name", "Jones"); - break; - case "Sarah": - url.searchParams.set("last_name", "Smith"); - break; - case "Dave": - url.searchParams.set("last_name", "Davies"); - break; -} -``` - -## Constructor - -### `URL(url: string, base?: string): URL` - -Constructs a URL from a url string and an optional base string. -If `base` if present then `url` will be interpreted as a relative url. -If `base` is not present then `url` will be interpreted as an absolute url. - -## Instance Properties - -### `hash: string` - -The fragment identifier of the URL. - -### `host: string` - -The host, a string containing the hostname (see below), followed by a ':' and the port of the url. - -### `hostname: string` - -The hostname of the url. In `jstz` this will usually be a `tz4` address of a smart function. - -### `href: string` {#href} - -A stringifier, returns the whole url. - -### `readonly origin: string` - -The origin of the url, specifically the scheme, the domain and the port. +### `contains(name: string, value?: string): boolean` -### `password: string` +Determines whether the `UrlSearchParams` object has a certain parameter, optionally with a specific value. -The password specified before the domain name. +- **name**: The name of the parameter you want to check for. +- **value** (optional): The value of the parameter you want to check for. +- **Returns**: `true` if the parameter, or parameter-value pair, exists. Otherwise, returns `false`. -### `pathname: string` +### `set(name: string, value: string): void` -The url path. This will always begin with a `'/'` and contains the part of the url up until the query string or fragment. - -### `port: string` - -The port number of the url. This has no special meaning within `jstz` and will not usually be present. - -### `protocol: string` - -The protocol scheme of the url. Within `jstz` this will usually be `tezos:` - -### `search: string` - -The URL's search parameter string, This will include all the search parameters of the url, each of which begins with a `'?'`. - -### `readonly searchParams: URLSearchParams` - -The search parameter object. See [`URLSearchParams`](./url_search_params.md) for more information. - -### `username: string` - -The username specified before the domain name. - -## Static Methods - -### `canParse(url: string, base?: string): boolean` {#canParse} - -Returns `true` if the url and base string can be parsed into a valid URL. - -## Instance Methods +Sets the value associated with a given parameter. If there are several matching parameters, it updates the first and removes the others. -### `toString(): string` +- **name**: The name of the parameter you want to set or update. +- **value**: The new value for the parameter. -An alias for [`href`](#href); returns the whole url as a string. +If the parameter does not exist, this method will append the parameter-value pair. -### `toJSON(): string` +### `sort(): void` -An alias for [`href`](#href); returns the whole url as a string. +Sorts all key/value pairs in the `UrlSearchParams` object by their keys. The sorting is done by comparing the code units of the keys. The relative order between pairs with equal names is preserved. From 503991fe3ce8d4049717a18778d4efdcc8cd015c Mon Sep 17 00:00:00 2001 From: Alan Marko Date: Fri, 20 Oct 2023 16:13:23 +0100 Subject: [PATCH 3/6] Added to config.mjs --- docs/.vitepress/config.mjs | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/.vitepress/config.mjs b/docs/.vitepress/config.mjs index 22c5fb64d..9f6b73cfa 100644 --- a/docs/.vitepress/config.mjs +++ b/docs/.vitepress/config.mjs @@ -39,6 +39,7 @@ export default defineConfig({ { text: "Ledger", link: "/api/ledger" }, { text: "Headers", link: "/api/headers" }, { text: "Response", link: "/api/response" }, + { text: "URLSearchParams", link: "/api/url_search_params" }, ], }, ], From 40b83f06843c521318314d13ee0e78c80fcf9053 Mon Sep 17 00:00:00 2001 From: Alan Marko Date: Tue, 24 Oct 2023 11:53:48 +0100 Subject: [PATCH 4/6] Updated with JS methods instead of Rust interface --- docs/api/url_search_params.md | 43 +++++++++++++++-------------------- 1 file changed, 18 insertions(+), 25 deletions(-) diff --git a/docs/api/url_search_params.md b/docs/api/url_search_params.md index 5a6642cf6..63d26f6fa 100644 --- a/docs/api/url_search_params.md +++ b/docs/api/url_search_params.md @@ -1,6 +1,6 @@ # 🔗 URLSearchParams -`jstz` implementation of an API with utility methods for working with the query string of a URL according to the [URLSearchParams specification](https://url.spec.whatwg.org/#urlsearchparams). It is used for building and manipulating search parameters. +`jstz`'s implementation of the `URLSearchParams` API defines utility methods for working with the query string of a URL according to the [URL specification](https://url.spec.whatwg.org/#urlsearchparams). It is used for building and manipulating search parameters. ## Example @@ -14,39 +14,28 @@ params.append("baz", 3); // Remove parameter params.delete("bar"); - -// Loop through parameters -for (let [key, value] of params) { - // ... -} ``` ## Constructor -### `UrlSearchParams(values: Array<[Name: string, Value: string]>, url?: URL)` +### `new UrlSearchParams(init?: [string, string][] | Record | string)` Creates a new instance of `UrlSearchParams` with the provided key-value pairs. -- **values**: An array of key-value pairs. Each pair is an array where the first element is the key (Name) and the second is the value. - -## Instance Methods - -### `setValues(values: Array<[Name: string, Value: string]>): void` - -Sets the current values with the provided array of key-value pairs. - -- **values**: An array of key-value pairs. Each pair consists of a name (key) and value. +- **init**: + One of: + - An array of key-value pairs. Each pair is an array where the first element is the key (Name) and the second is the value. + - A record of string keys and string values. + - A string, which will be parsed from application/x-www-form-urlencoded format. A leading '?' character is ignored. -### `setUrl(url: JsNativeObject): void` +## Instance Properties -Associates the `UrlSearchParams` with a given `Url` object. - -- **url**: A reference to the `Url` object. - -### `len(): number` +### `size: number` - **Returns**: The number of search parameters present. +## Instance Methods + ### `append(name: string, value: string): void` Appends a specified key/value pair as a new search parameter. @@ -54,7 +43,7 @@ Appends a specified key/value pair as a new search parameter. - **name**: The name of the search parameter. - **value**: The value of the search parameter. -### `remove(name: string, value?: string): void` +### `delete(name: string, value?: string): void` Removes search parameters that match the given name. If a value is provided, only parameters with that name-value pair are removed. @@ -69,7 +58,7 @@ Returns the first value associated with the given search parameter. - **Returns**: The value associated with the given search parameter or `null` if not found. -### `getAll(name: string): Array` +### `getAll(name: string): string[]` Returns all the values associated with a given search parameter. @@ -77,7 +66,7 @@ Returns all the values associated with a given search parameter. - **Returns**: An array of values associated with the given search parameter. -### `contains(name: string, value?: string): boolean` +### `has(name: string, value?: string): boolean` Determines whether the `UrlSearchParams` object has a certain parameter, optionally with a specific value. @@ -97,3 +86,7 @@ If the parameter does not exist, this method will append the parameter-value pai ### `sort(): void` Sorts all key/value pairs in the `UrlSearchParams` object by their keys. The sorting is done by comparing the code units of the keys. The relative order between pairs with equal names is preserved. + +### `toString(): string` + +Returns a query string suitable for use in a URL. From 5215905832576f3d3b3e014715b24a2b0b149475 Mon Sep 17 00:00:00 2001 From: Alistair Date: Tue, 24 Oct 2023 12:12:51 +0100 Subject: [PATCH 5/6] Docs: Update attribute of `.size` --- docs/api/url_search_params.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api/url_search_params.md b/docs/api/url_search_params.md index 63d26f6fa..2bda6c5bc 100644 --- a/docs/api/url_search_params.md +++ b/docs/api/url_search_params.md @@ -30,7 +30,7 @@ Creates a new instance of `UrlSearchParams` with the provided key-value pairs. ## Instance Properties -### `size: number` +### `readonly size: number` - **Returns**: The number of search parameters present. From 1c0b037067ae51a175b881b1cdcbe24458aee691 Mon Sep 17 00:00:00 2001 From: Alistair Date: Tue, 24 Oct 2023 15:24:06 +0100 Subject: [PATCH 6/6] Git: Configure dependabot --- .github/dependabot.yml | 68 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 68 insertions(+) create mode 100644 .github/dependabot.yml diff --git a/.github/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 000000000..c513eb23d --- /dev/null +++ b/.github/dependabot.yml @@ -0,0 +1,68 @@ +version: 2 +updates: + - package-ecosystem: npm + directory: / + schedule: + interval: daily + commit-message: + prefix: "Deps (NPM)" + - package-ecosystem: npm + directory: /packages/jstz/ + schedule: + interval: daily + commit-message: + prefix: "Deps (NPM)" + - package-ecosystem: npm + directory: /packages/jstz-types/ + schedule: + interval: daily + commit-message: + prefix: "Deps (NPM)" + - package-ecosystem: github-actions + directory: / + schedule: + interval: daily + commit-message: + prefix: "Deps (Actions)" + - package-ecosystem: cargo + directory: / + schedule: + interval: daily + commit-message: + prefix: "Deps (Cargo)" + - package-ecosystem: cargo + directory: /jstz_api/ + schedule: + interval: daily + commit-message: + prefix: "Deps (Cargo)" + - package-ecosystem: cargo + directory: /jstz_cli/ + schedule: + interval: daily + commit-message: + prefix: "Deps (Cargo)" + - package-ecosystem: cargo + directory: /jstz_core/ + schedule: + interval: daily + commit-message: + prefix: "Deps (Cargo)" + - package-ecosystem: cargo + directory: /jstz_crypto/ + schedule: + interval: daily + commit-message: + prefix: "Deps (Cargo)" + - package-ecosystem: cargo + directory: /jstz_kernel/ + schedule: + interval: daily + commit-message: + prefix: "Deps (Cargo)" + - package-ecosystem: cargo + directory: /jstz_proto/ + schedule: + interval: daily + commit-message: + prefix: "Deps (Cargo)"