You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
41 lines
1.6 KiB
Markdown
41 lines
1.6 KiB
Markdown
5 years ago
|
# @modular-matrix/parse-mxc
|
||
|
|
|
||
|
|
A utility library for (validating and) parsing an MXC URI into an object.
|
||
|
|
|
||
|
|
Part of the [Modular Matrix](https://modular-matrix.cryto.net/) toolkit, a set of modular libraries for working with the [Matrix](https://matrix.org/) protocol.
|
||
|
|
|
||
|
|
## Example
|
||
|
|
|
||
|
|
```js
|
||
|
|
const parseMXC = require("@modular-matrix/parse-mxc");
|
||
|
|
|
||
|
|
let parsed = parseMXC.parse("mxc://pixie.town/qBpNzYpOknBxnSdcbFWrbqWT");
|
||
|
|
|
||
|
|
console.log(parsed); // { homeserver: 'pixie.town', id: 'qBpNzYpOknBxnSdcbFWrbqWT' }
|
||
|
|
|
||
|
|
let parsed = parseMXC("http://example.com/"); // throws a parseMXC.ParsingError
|
||
|
|
```
|
||
|
|
|
||
|
|
## API
|
||
|
|
|
||
|
|
### parseMXC.parse(uri)
|
||
|
|
|
||
|
|
Parses a string containing an MXC URI.
|
||
|
|
|
||
|
|
- __uri:__ The URI string to parse.
|
||
|
|
|
||
|
|
Upon successful parsing, returns an object with the following structure:
|
||
|
|
|
||
|
|
- __homeserver:__ The hostname of the homeserver encoded in the URI. Note that this is the *source* HS for the content; when eg. generating thumbnails, the request for that will usually be made to your *own* HS, and the hostname in this object only becomes part of the request path.
|
||
|
|
- __id:__ The MXC ID, identifying the specific piece of content.
|
||
|
|
|
||
|
|
The returned object can be passed into other *Modular Matrix* libraries that expect an MXC object.
|
||
|
|
|
||
|
|
If the provided URI is *not* a valid MXC URI, a `parseMXC.ParsingError` will be thrown.
|
||
|
|
|
||
|
|
### parseMXC.ParsingError
|
||
|
|
|
||
|
|
An error type (constructor) representing a failure to parse an MXC URI, due to the URI being invalid in some way.
|
||
|
|
|
||
|
|
This is an error type that inherits from `Error`, and so can be used with `instanceof` (and mechanisms based on it, such as Bluebird's filtered `.catch`) to detect errors of this specific type.
|