Initial commit

.gitignore

@@ -0,0 +1 @@
+node_modules

README.md

@@ -0,0 +1,40 @@
+# @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.

index.js

@@ -0,0 +1,22 @@
+"use strict";
+
+const urlLib = require("url");
+const createError = require("create-error");
+
+let ParsingError = createError("ParsingError");
+
+module.exports = {
+	ParsingError: ParsingError,
+	parse: function parseMXC(uri) {
+		let parsed = urlLib.parse(uri);
+	
+		if (parsed.protocol === "mxc:" && parsed.slashes === true) {
+			return {
+				homeserver: parsed.host,
+				id: parsed.pathname.replace(/^\/+/, "")
+			};
+		} else {
+			throw new ParsingError("Specified URI is not an MXC URI");
+		}
+	}
+};

package.json

@@ -0,0 +1,11 @@
+{
+  "name": "parse-mxc",
+  "version": "1.0.0",
+  "main": "index.js",
+  "repository": "http://git.cryto.net/modular-matrix/parse-mxc.git",
+  "author": "Sven Slootweg <admin@cryto.net>",
+  "license": "WTFPL OR CC0-1.0",
+  "dependencies": {
+    "create-error": "^0.3.1"
+  }
+}

yarn.lock

@@ -0,0 +1,8 @@
+# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY.
+# yarn lockfile v1
+
+
+create-error@^0.3.1:
+  version "0.3.1"
+  resolved "https://registry.yarnpkg.com/create-error/-/create-error-0.3.1.tgz#69810245a629e654432bf04377360003a5351a23"
+  integrity sha1-aYECRaYp5lRDK/BDdzYAA6U1GiM=