parse-mxc/README.md

# @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 invalid = 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.