From 17187021c5e3fcdfc954e92adbe8743bf4b04753 Mon Sep 17 00:00:00 2001 From: Sven Slootweg Date: Sun, 18 Aug 2019 00:09:13 +0200 Subject: [PATCH] Initial commit --- .gitignore | 1 + README.md | 40 ++++++++++++++++++++++++++++++++++++++++ index.js | 22 ++++++++++++++++++++++ package.json | 11 +++++++++++ yarn.lock | 8 ++++++++ 5 files changed, 82 insertions(+) create mode 100644 .gitignore create mode 100644 README.md create mode 100644 index.js create mode 100644 package.json create mode 100644 yarn.lock diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..3c3629e --- /dev/null +++ b/.gitignore @@ -0,0 +1 @@ +node_modules diff --git a/README.md b/README.md new file mode 100644 index 0000000..0faee4f --- /dev/null +++ b/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. diff --git a/index.js b/index.js new file mode 100644 index 0000000..a0ccd36 --- /dev/null +++ b/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"); + } + } +}; diff --git a/package.json b/package.json new file mode 100644 index 0000000..9c521ba --- /dev/null +++ b/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 ", + "license": "WTFPL OR CC0-1.0", + "dependencies": { + "create-error": "^0.3.1" + } +} diff --git a/yarn.lock b/yarn.lock new file mode 100644 index 0000000..18fdc6d --- /dev/null +++ b/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=