docs/index.html
<!doctype html>
<html class="default no-js">
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<title>tiny-shortener</title>
<meta name="description" content="">
<meta name="viewport" content="width=device-width, initial-scale=1">
<link rel="stylesheet" href="assets/css/main.css">
</head>
<body>
<header>
<div class="tsd-page-toolbar">
<div class="container">
<div class="table-wrap">
<div class="table-cell" id="tsd-search" data-index="assets/js/search.js" data-base=".">
<div class="field">
<label for="tsd-search-field" class="tsd-widget search no-caption">Search</label>
<input id="tsd-search-field" type="text" />
</div>
<ul class="results">
<li class="state loading">Preparing search index...</li>
<li class="state failure">The search index is not available</li>
</ul>
<a href="index.html" class="title">tiny-shortener</a>
</div>
<div class="table-cell" id="tsd-widgets">
<div id="tsd-filter">
<a href="#" class="tsd-widget options no-caption" data-toggle="options">Options</a>
<div class="tsd-filter-group">
<div class="tsd-select" id="tsd-filter-visibility">
<span class="tsd-select-label">All</span>
<ul class="tsd-select-list">
<li data-value="public">Public</li>
<li data-value="protected">Public/Protected</li>
<li data-value="private" class="selected">All</li>
</ul>
</div>
<input type="checkbox" id="tsd-filter-inherited" checked />
<label class="tsd-widget" for="tsd-filter-inherited">Inherited</label>
<input type="checkbox" id="tsd-filter-externals" checked />
<label class="tsd-widget" for="tsd-filter-externals">Externals</label>
<input type="checkbox" id="tsd-filter-only-exported" />
<label class="tsd-widget" for="tsd-filter-only-exported">Only exported</label>
</div>
</div>
<a href="#" class="tsd-widget menu no-caption" data-toggle="menu">Menu</a>
</div>
</div>
</div>
</div>
<div class="tsd-page-title">
<div class="container">
<ul class="tsd-breadcrumb">
<li>
<a href="globals.html">Globals</a>
</li>
</ul>
<h1> tiny-shortener</h1>
</div>
</div>
</header>
<div class="container container-main">
<div class="row">
<div class="col-8 col-content">
<div class="tsd-panel tsd-typography">
<h1 id="tiny-shortener">tiny-shortener</h1>
<div align="center">
<br>
<img width="260" src="./logo/tiny-shortener.png" /img>
<br>
<p><a href="./README.md"><img src="https://img.shields.io/badge/Language-EN-blue.svg?longCache=true&style=for-the-badge" alt="English README"></a>
<a href="./README.PT.md"><img src="https://img.shields.io/badge/Linguagem-PT-green.svg?longCache=true&style=for-the-badge" alt="Portuguese README"></a></p>
<p><a href="https://www.npmjs.com/package/tiny-shortener"><img src="https://img.shields.io/npm/v/tiny-shortener.svg?style=flat-square" alt="npm"></a>
<a href="https://www.npmjs.com/package/tiny-shortener"><img src="https://img.shields.io/npm/dt/tiny-shortener.svg?style=flat-square" alt="npm"></a>
<a href="https://codeclimate.com/github/Fazendaaa/tiny-shortener/maintainability"><img src="https://api.codeclimate.com/v1/badges/04c334bbe522d8a0823f/maintainability" alt="Maintainability"></a>
<a href="https://travis-ci.org/Fazendaaa/tiny-shortener"><img src="https://travis-ci.org/Fazendaaa/tiny-shortener.svg?branch=master" alt="Build Status"></a>
<a href="https://github.com/Fazendaaa/tiny-shortener/blob/master/package.json"><img src="https://david-dm.org/Fazendaaa/tiny-shortener.svg?style=flat-square" alt="Dependencies"></a>
<a href="https://codecov.io/gh/Fazendaaa/tiny-shortener"><img src="https://img.shields.io/codecov/c/github/Fazendaaa/endeavor.svg?style=flat-square" alt="codecov"></a></p>
</div>
<blockquote>
<p>A new Tiny URL package for Node.js with promise/async and alias support.</p>
</blockquote>
<h2 id="about">About</h2>
<p>The idea behind this package is for a Open Source class taken at college. The professor wanted us to make a contribution to an OSS project.</p>
<p>Since the <a href="https://www.npmjs.com/package/tinyurl">TinyURL</a> package is a great option after <a href="https://www.theverge.com/2018/3/31/17184164/google-alphabet-url-shortening-service-closed">Google</a> has shut down it's shortener service. But the TinyURL has no Promise support, making it difficult to use with any new <a href="https://www.w3schools.com/js/js_versions.asp">ECMA</a> standards. As there is a Pull Request(PR) opened supporting this in the project and still isn't merged, the idea behind <strong>tiny-shortener</strong> is to make a new package that supports this and goes a step further supporting alias, letting the user personalize the shortened URL.</p>
<p>obs: in case that that the alias isn't available the request still works but falls back to an default shortened link.</p>
<h2 id="installing">Installing</h2>
<h3 id="requirements">Requirements</h3>
<p>Since this package uses only <a href="https://nodejs.org/">Node</a> packages as support, Node will be needed as <a href="https://www.npmjs.com/">npm</a> installed.</p>
<h3 id="npm">npm</h3>
<pre><code class="language-bash">npm install tiny-shortener --save</code></pre>
<h2 id="using-it">Using it</h2>
<h3 id="tiny-url-alias-">tiny(url, [alias])</h3>
<ul>
<li>url <string> - Link to be shortened;</li>
<li>alias <string> - Wanted personalization link;</li>
<li>Returns <Promise<string>> - Shortened link or rejects an error.</li>
</ul>
<h3 id="examples">Examples</h3>
<h4 id="typescript">TypeScript</h4>
<p>With async/await support but works with Promises as well:</p>
<pre><code class="language-typescript"><span class="hljs-keyword">import</span> { tiny } <span class="hljs-keyword">from</span> <span class="hljs-string">'tiny-shortener'</span>;
<span class="hljs-keyword">const</span> asyncRequest = <span class="hljs-keyword">async</span> (): <span class="hljs-built_in">Promise</span><<span class="hljs-built_in">void</span>> => {
<span class="hljs-keyword">const</span> shortened = <<span class="hljs-built_in">string</span>> <span class="hljs-keyword">await</span> tiny(<span class="hljs-string">'www.microsoft.com'</span>);
<span class="hljs-keyword">const</span> aliased = <<span class="hljs-built_in">string</span>> <span class="hljs-keyword">await</span> tiny(<span class="hljs-string">'www.typescriptlang.org/'</span>, <span class="hljs-string">'tslang'</span>);
<span class="hljs-built_in">console</span>.log(<span class="hljs-string">`Without alias is: <span class="hljs-subst">${shortened}</span>\nWith alias: <span class="hljs-subst">${aliased}</span>`</span>);
};</code></pre>
<h4 id="javascript">JavaScript</h4>
<p>With Promises support but works with async/await as well:</p>
<pre><code class="language-javascript"><span class="hljs-keyword">const</span> tiny = <span class="hljs-built_in">require</span>(<span class="hljs-string">'tiny-shortener'</span>).tiny;
tiny(<span class="hljs-string">'www.microsoft.com'</span>)
.then(<span class="hljs-built_in">console</span>.log)
.catch(<span class="hljs-built_in">console</span>.error);
<span class="hljs-comment">// with alias</span>
tiny(<span class="hljs-string">'www.typescriptlang.org/'</span>, <span class="hljs-string">'tslang'</span>)
.then(<span class="hljs-built_in">console</span>.log)
.catch(<span class="hljs-built_in">console</span>.error);
});</code></pre>
<h4 id="cli">CLI</h4>
<pre><code class="language-shell">tiny-shortener --url www.example.com</code></pre>
<p>Or even with alias support:</p>
<pre><code class="language-shell">tiny-shortener --url www.foo.com --personalization bar</code></pre>
<h4 id="see-more">See more</h4>
<p>See more in the <a href="./examples">examples</a> folder.</p>
<h2 id="why-typescript-">Why TypeScript?</h2>
<p>TS users suffer from having to make the typings for a large part of little projects. We've decide to make this as a TS project to allow a painless interoperability.</p>
<h3 id="style-code">Style code</h3>
<p>Using the <a href="https://github.com/Microsoft/tslint-microsoft-contrib">Microsoft</a> style code.</p>
<h2 id="testing">Testing</h2>
<p>With <a href="https://en.wikipedia.org/wiki/Test-driven_development">Test Driven Development(TDD)</a> in mind, we've used the Facebook's <a href="https://facebook.github.io/jest/">Jest</a> test runner through the <a href="https://www.npmjs.com/package/ts-jest">ts-jest</a> package to run with the need to compiling the code. See more in <a href="./ci">ci</a> folder;</p>
<h2 id="versioning">Versioning</h2>
<p>Versioning is made through npm versioning system. You can see what version is in the badge at the top of this README.</p>
<h2 id="build-with">Build with</h2>
<ul>
<li><a href="https://github.com/tj/commander.js">commander</a>.</li>
</ul>
<h2 id="contributing">Contributing</h2>
<p>We're opened to PRs as long you open an issue before explaining what you will be pushing and we will see if fits.</p>
<h2 id="todo">TODO</h2>
<ul>
<li>Write some more examples</li>
</ul>
<h2 id="authors">Authors</h2>
<ul>
<li><a href="https://github.com/Fazendaaa">Fazendaaa</a> - The one and only;</li>
<li><a href="https://github.com/pit00">pit00</a> - Du Hast.</li>
</ul>
<h2 id="license">License</h2>
<p>See <a href="./LICENSE">LICENSE</a> for more about it.</p>
<h2 id="acknowledges">Acknowledges</h2>
<ul>
<li><a href="app.mocklab.io">Mocklab</a> - System of mocking API request for testing;</li>
<li>Stormpath - <a href="https://stormpath.com/blog/how-to-write-middleware-for-express-apps">This</a> express tutorial for writing examples;</li>
<li>Object Calisthenics - <a href="https://medium.com/web-engineering-vox/improving-code-quality-with-object-calisthenics-aa4ad67a61f1">This</a> post helped to understand a new concept thanks to <a href="https://t.me/vinicius73">@vinicius73</a> feedback on a <a href="https://t.me/NodejsBR">Node.js</a> Telegram group.</li>
</ul>
</div>
</div>
<div class="col-4 col-menu menu-sticky-wrap menu-highlight">
<nav class="tsd-navigation primary">
<ul>
<li class="globals ">
<a href="globals.html"><em>Globals</em></a>
</li>
<li class=" tsd-kind-external-module">
<a href="modules/_lib_parse_.html">"lib/parse"</a>
</li>
<li class=" tsd-kind-external-module">
<a href="modules/_lib_wrapper_.html">"lib/wrapper"</a>
</li>
<li class=" tsd-kind-external-module">
<a href="modules/_tiny_shortener_.html">"tiny-<wbr>shortener"</a>
</li>
</ul>
</nav>
<nav class="tsd-navigation secondary menu-sticky">
<ul class="before-current">
</ul>
</nav>
</div>
</div>
</div>
<footer class="with-border-bottom">
<div class="container">
<h2>Legend</h2>
<div class="tsd-legend-group">
<ul class="tsd-legend">
<li class="tsd-kind-module"><span class="tsd-kind-icon">Module</span></li>
<li class="tsd-kind-object-literal"><span class="tsd-kind-icon">Object literal</span></li>
<li class="tsd-kind-variable"><span class="tsd-kind-icon">Variable</span></li>
<li class="tsd-kind-function"><span class="tsd-kind-icon">Function</span></li>
<li class="tsd-kind-function tsd-has-type-parameter"><span class="tsd-kind-icon">Function with type parameter</span></li>
<li class="tsd-kind-index-signature"><span class="tsd-kind-icon">Index signature</span></li>
<li class="tsd-kind-type-alias"><span class="tsd-kind-icon">Type alias</span></li>
</ul>
<ul class="tsd-legend">
<li class="tsd-kind-enum"><span class="tsd-kind-icon">Enumeration</span></li>
<li class="tsd-kind-enum-member"><span class="tsd-kind-icon">Enumeration member</span></li>
<li class="tsd-kind-property tsd-parent-kind-enum"><span class="tsd-kind-icon">Property</span></li>
<li class="tsd-kind-method tsd-parent-kind-enum"><span class="tsd-kind-icon">Method</span></li>
</ul>
<ul class="tsd-legend">
<li class="tsd-kind-interface"><span class="tsd-kind-icon">Interface</span></li>
<li class="tsd-kind-interface tsd-has-type-parameter"><span class="tsd-kind-icon">Interface with type parameter</span></li>
<li class="tsd-kind-constructor tsd-parent-kind-interface"><span class="tsd-kind-icon">Constructor</span></li>
<li class="tsd-kind-property tsd-parent-kind-interface"><span class="tsd-kind-icon">Property</span></li>
<li class="tsd-kind-method tsd-parent-kind-interface"><span class="tsd-kind-icon">Method</span></li>
<li class="tsd-kind-index-signature tsd-parent-kind-interface"><span class="tsd-kind-icon">Index signature</span></li>
</ul>
<ul class="tsd-legend">
<li class="tsd-kind-class"><span class="tsd-kind-icon">Class</span></li>
<li class="tsd-kind-class tsd-has-type-parameter"><span class="tsd-kind-icon">Class with type parameter</span></li>
<li class="tsd-kind-constructor tsd-parent-kind-class"><span class="tsd-kind-icon">Constructor</span></li>
<li class="tsd-kind-property tsd-parent-kind-class"><span class="tsd-kind-icon">Property</span></li>
<li class="tsd-kind-method tsd-parent-kind-class"><span class="tsd-kind-icon">Method</span></li>
<li class="tsd-kind-accessor tsd-parent-kind-class"><span class="tsd-kind-icon">Accessor</span></li>
<li class="tsd-kind-index-signature tsd-parent-kind-class"><span class="tsd-kind-icon">Index signature</span></li>
</ul>
<ul class="tsd-legend">
<li class="tsd-kind-constructor tsd-parent-kind-class tsd-is-inherited"><span class="tsd-kind-icon">Inherited constructor</span></li>
<li class="tsd-kind-property tsd-parent-kind-class tsd-is-inherited"><span class="tsd-kind-icon">Inherited property</span></li>
<li class="tsd-kind-method tsd-parent-kind-class tsd-is-inherited"><span class="tsd-kind-icon">Inherited method</span></li>
<li class="tsd-kind-accessor tsd-parent-kind-class tsd-is-inherited"><span class="tsd-kind-icon">Inherited accessor</span></li>
</ul>
<ul class="tsd-legend">
<li class="tsd-kind-property tsd-parent-kind-class tsd-is-protected"><span class="tsd-kind-icon">Protected property</span></li>
<li class="tsd-kind-method tsd-parent-kind-class tsd-is-protected"><span class="tsd-kind-icon">Protected method</span></li>
<li class="tsd-kind-accessor tsd-parent-kind-class tsd-is-protected"><span class="tsd-kind-icon">Protected accessor</span></li>
</ul>
<ul class="tsd-legend">
<li class="tsd-kind-property tsd-parent-kind-class tsd-is-private"><span class="tsd-kind-icon">Private property</span></li>
<li class="tsd-kind-method tsd-parent-kind-class tsd-is-private"><span class="tsd-kind-icon">Private method</span></li>
<li class="tsd-kind-accessor tsd-parent-kind-class tsd-is-private"><span class="tsd-kind-icon">Private accessor</span></li>
</ul>
<ul class="tsd-legend">
<li class="tsd-kind-property tsd-parent-kind-class tsd-is-static"><span class="tsd-kind-icon">Static property</span></li>
<li class="tsd-kind-call-signature tsd-parent-kind-class tsd-is-static"><span class="tsd-kind-icon">Static method</span></li>
</ul>
</div>
</div>
</footer>
<div class="container tsd-generator">
<p>Generated using <a href="http://typedoc.org/" target="_blank">TypeDoc</a></p>
</div>
<div class="overlay"></div>
<script src="assets/js/main.js"></script>
<script>if (location.protocol == 'file:') document.write('<script src="assets/js/search.js"><' + '/script>');</script>
</body>
</html>