| 1 |
<!doctype html> |
| 2 |
<html class="default no-js"> |
| 3 |
<head> |
| 4 |
<meta charset="utf-8"> |
| 5 |
<meta http-equiv="X-UA-Compatible" content="IE=edge"> |
| 6 |
<title>optional-require</title> |
| 7 |
<meta name="description" content="Documentation for optional-require"> |
| 8 |
<meta name="viewport" content="width=device-width, initial-scale=1"> |
| 9 |
<link rel="stylesheet" href="assets/css/main.css"> |
| 10 |
<script async src="assets/js/search.js" id="search-script"></script> |
| 11 |
</head> |
| 12 |
<body> |
| 13 |
<header> |
| 14 |
<div class="tsd-page-toolbar"> |
| 15 |
<div class="container"> |
| 16 |
<div class="table-wrap"> |
| 17 |
<div class="table-cell" id="tsd-search" data-index="assets/js/search.json" data-base="."> |
| 18 |
<div class="field"> |
| 19 |
<label for="tsd-search-field" class="tsd-widget search no-caption">Search</label> |
| 20 |
<input id="tsd-search-field" type="text" /> |
| 21 |
</div> |
| 22 |
<ul class="results"> |
| 23 |
<li class="state loading">Preparing search index...</li> |
| 24 |
<li class="state failure">The search index is not available</li> |
| 25 |
</ul> |
| 26 |
<a href="index.html" class="title">optional-require</a> |
| 27 |
</div> |
| 28 |
<div class="table-cell" id="tsd-widgets"> |
| 29 |
<div id="tsd-filter"> |
| 30 |
<a href="#" class="tsd-widget options no-caption" data-toggle="options">Options</a> |
| 31 |
<div class="tsd-filter-group"> |
| 32 |
<div class="tsd-select" id="tsd-filter-visibility"> |
| 33 |
<span class="tsd-select-label">All</span> |
| 34 |
<ul class="tsd-select-list"> |
| 35 |
<li data-value="public">Public</li> |
| 36 |
<li data-value="protected">Public/Protected</li> |
| 37 |
<li data-value="private" class="selected">All</li> |
| 38 |
</ul> |
| 39 |
</div> |
| 40 |
<input type="checkbox" id="tsd-filter-inherited" checked /> |
| 41 |
<label class="tsd-widget" for="tsd-filter-inherited">Inherited</label> |
| 42 |
<input type="checkbox" id="tsd-filter-externals" checked /> |
| 43 |
<label class="tsd-widget" for="tsd-filter-externals">Externals</label> |
| 44 |
</div> |
| 45 |
</div> |
| 46 |
<a href="#" class="tsd-widget menu no-caption" data-toggle="menu">Menu</a> |
| 47 |
</div> |
| 48 |
</div> |
| 49 |
</div> |
| 50 |
</div> |
| 51 |
<div class="tsd-page-title"> |
| 52 |
<div class="container"> |
| 53 |
<h1>optional-require</h1> |
| 54 |
</div> |
| 55 |
</div> |
| 56 |
</header> |
| 57 |
<div class="container container-main"> |
| 58 |
<div class="row"> |
| 59 |
<div class="col-8 col-content"> |
| 60 |
<div class="tsd-panel tsd-typography"> |
| 61 |
<p><a href="https://npmjs.org/package/optional-require"><img src="https://badge.fury.io/js/optional-require.svg" alt="NPM version"></a> <a href="https://travis-ci.org/jchip/optional-require"><img src="https://travis-ci.org/jchip/optional-require.svg?branch=master" alt="Build Status"></a> |
| 62 |
<a href="https://david-dm.org/jchip/optional-require"><img src="https://david-dm.org/jchip/optional-require/status.svg" alt="Dependency Status"></a> <a href="https://david-dm.org/jchip/optional-require?type=dev"><img src="https://david-dm.org/jchip/optional-require/dev-status.svg" alt="devDependency Status"></a></p> |
| 63 |
<a href="#optional-require" id="optional-require" style="color: inherit; text-decoration: none;"> |
| 64 |
<h1>Optional Require</h1> |
| 65 |
</a> |
| 66 |
<p>node.js require that let you handle module not found error without try/catch. Allows you to gracefully require a module only if it exists and contains no error.</p> |
| 67 |
<a href="#why-not-trycatch" id="why-not-trycatch" style="color: inherit; text-decoration: none;"> |
| 68 |
<h2>Why not try/catch?</h2> |
| 69 |
</a> |
| 70 |
<p>So why not just do:</p> |
| 71 |
<pre><code class="language-ts"><span style="color: #0000FF">let</span><span style="color: #000000"> </span><span style="color: #001080">some</span><span style="color: #000000">;</span> |
| 72 |
<span style="color: #AF00DB">try</span><span style="color: #000000"> {</span> |
| 73 |
<span style="color: #000000"> </span><span style="color: #001080">some</span><span style="color: #000000"> = </span><span style="color: #795E26">require</span><span style="color: #000000">(</span><span style="color: #A31515">"some-optional-module"</span><span style="color: #000000">);</span> |
| 74 |
<span style="color: #000000">} </span><span style="color: #AF00DB">catch</span><span style="color: #000000"> {</span> |
| 75 |
<span style="color: #000000"> </span><span style="color: #008000">// do nothing</span> |
| 76 |
<span style="color: #000000">}</span> |
| 77 |
</code></pre> |
| 78 |
<ol> |
| 79 |
<li>You need to keep the variable outside: <code>let some</code> before try/catch</li> |
| 80 |
<li>If <code>"some-optional-module"</code> contains error itself, above code will silently ignore it, leaving you, and more importantly, your users, puzzling on why it's not working.</li> |
| 81 |
</ol> |
| 82 |
<a href="#usage" id="usage" style="color: inherit; text-decoration: none;"> |
| 83 |
<h2>Usage</h2> |
| 84 |
</a> |
| 85 |
<p>TypeScript:</p> |
| 86 |
<pre><code class="language-ts"><span style="color: #AF00DB">import</span><span style="color: #000000"> { </span><span style="color: #001080">optionalRequire</span><span style="color: #000000"> } </span><span style="color: #AF00DB">from</span><span style="color: #000000"> </span><span style="color: #A31515">"optional-require"</span><span style="color: #000000">;</span> |
| 87 |
|
| 88 |
<span style="color: #0000FF">const</span><span style="color: #000000"> </span><span style="color: #0070C1">some</span><span style="color: #000000"> = </span><span style="color: #795E26">optionalRequire</span><span style="color: #000000">(</span><span style="color: #A31515">"some-optional-module"</span><span style="color: #000000">);</span> |
| 89 |
</code></pre> |
| 90 |
<p>JavaScript:</p> |
| 91 |
<pre><code class="language-js"><span style="color: #0000FF">const</span><span style="color: #000000"> { </span><span style="color: #0070C1">optionalRequire</span><span style="color: #000000"> } = </span><span style="color: #795E26">require</span><span style="color: #000000">(</span><span style="color: #A31515">"optional-require"</span><span style="color: #000000">);</span> |
| 92 |
|
| 93 |
<span style="color: #0000FF">const</span><span style="color: #000000"> </span><span style="color: #0070C1">foo</span><span style="color: #000000"> = </span><span style="color: #795E26">optionalRequire</span><span style="color: #000000">(</span><span style="color: #A31515">"foo"</span><span style="color: #000000">) || {};</span> |
| 94 |
<span style="color: #0000FF">const</span><span style="color: #000000"> </span><span style="color: #0070C1">bar</span><span style="color: #000000"> = </span><span style="color: #795E26">optionalRequire</span><span style="color: #000000">(</span><span style="color: #A31515">"bar"</span><span style="color: #000000">, </span><span style="color: #0000FF">true</span><span style="color: #000000">); </span><span style="color: #008000">// true enables console.log a message when not found</span> |
| 95 |
<span style="color: #0000FF">const</span><span style="color: #000000"> </span><span style="color: #0070C1">xyz</span><span style="color: #000000"> = </span><span style="color: #795E26">optionalRequire</span><span style="color: #000000">(</span><span style="color: #A31515">"xyz"</span><span style="color: #000000">, </span><span style="color: #A31515">"test"</span><span style="color: #000000">); </span><span style="color: #008000">// "test" enables console.log a message with "test" added.</span> |
| 96 |
<span style="color: #0000FF">const</span><span style="color: #000000"> </span><span style="color: #0070C1">fbPath</span><span style="color: #000000"> = </span><span style="color: #001080">optionalRequire</span><span style="color: #000000">.</span><span style="color: #795E26">resolve</span><span style="color: #000000">(</span><span style="color: #A31515">"foo"</span><span style="color: #000000">, </span><span style="color: #A31515">"foo doesn't exist"</span><span style="color: #000000">);</span> |
| 97 |
<span style="color: #008000">// relative module path works - *but* you need to pass in `require` from your file</span> |
| 98 |
<span style="color: #0000FF">const</span><span style="color: #000000"> </span><span style="color: #0070C1">rel</span><span style="color: #000000"> = </span><span style="color: #795E26">optionalRequire</span><span style="color: #000000">(</span><span style="color: #A31515">"../foo/bar"</span><span style="color: #000000">, { </span><span style="color: #001080">require</span><span style="color: #000000"> });</span> |
| 99 |
</code></pre> |
| 100 |
<a href="#binding-require" id="binding-require" style="color: inherit; text-decoration: none;"> |
| 101 |
<h3>Binding <code>require</code></h3> |
| 102 |
</a> |
| 103 |
<p>The default <code>optionalRequire</code> uses <code>require</code> from the context of this module. While you can pass in your <code>require</code> in <code>options</code>, if you want to create your own function that's bound to your <code>require</code>, you can do it with <code>makeOptionalRequire</code>:</p> |
| 104 |
<pre><code class="language-ts"><span style="color: #AF00DB">import</span><span style="color: #000000"> { </span><span style="color: #001080">makeOptionalRequire</span><span style="color: #000000"> } </span><span style="color: #AF00DB">from</span><span style="color: #000000"> </span><span style="color: #A31515">"optional-require"</span><span style="color: #000000">;</span> |
| 105 |
|
| 106 |
<span style="color: #0000FF">const</span><span style="color: #000000"> </span><span style="color: #0070C1">optionalRequire</span><span style="color: #000000"> = </span><span style="color: #795E26">makeOptionalRequire</span><span style="color: #000000">(</span><span style="color: #001080">require</span><span style="color: #000000">);</span> |
| 107 |
|
| 108 |
<span style="color: #008000">// now you can optional require files in same dir as your file</span> |
| 109 |
<span style="color: #0000FF">const</span><span style="color: #000000"> </span><span style="color: #0070C1">myModule</span><span style="color: #000000"> = </span><span style="color: #795E26">optionalRequire</span><span style="color: #000000">(</span><span style="color: #A31515">"./my-module"</span><span style="color: #000000">);</span> |
| 110 |
</code></pre> |
| 111 |
<a href="#legacy-usage" id="legacy-usage" style="color: inherit; text-decoration: none;"> |
| 112 |
<h3>Legacy Usage</h3> |
| 113 |
</a> |
| 114 |
<p>In older versions, this module exports <code>makeOptionalRequire</code> directly and this is the legacy usage in JavaScript, which is still supported:</p> |
| 115 |
<pre><code class="language-js"><span style="color: #0000FF">const</span><span style="color: #000000"> </span><span style="color: #0070C1">optionalRequire</span><span style="color: #000000"> = </span><span style="color: #795E26">require</span><span style="color: #000000">(</span><span style="color: #A31515">"optional-require"</span><span style="color: #000000">)(</span><span style="color: #001080">require</span><span style="color: #000000">);</span> |
| 116 |
|
| 117 |
<span style="color: #0000FF">const</span><span style="color: #000000"> </span><span style="color: #0070C1">foo</span><span style="color: #000000"> = </span><span style="color: #795E26">optionalRequire</span><span style="color: #000000">(</span><span style="color: #A31515">"foo"</span><span style="color: #000000">) || {};</span> |
| 118 |
<span style="color: #0000FF">const</span><span style="color: #000000"> </span><span style="color: #0070C1">bar</span><span style="color: #000000"> = </span><span style="color: #795E26">optionalRequire</span><span style="color: #000000">(</span><span style="color: #A31515">"bar"</span><span style="color: #000000">, </span><span style="color: #0000FF">true</span><span style="color: #000000">); </span><span style="color: #008000">// true enables console.log a message when not found</span> |
| 119 |
<span style="color: #0000FF">const</span><span style="color: #000000"> </span><span style="color: #0070C1">xyz</span><span style="color: #000000"> = </span><span style="color: #795E26">optionalRequire</span><span style="color: #000000">(</span><span style="color: #A31515">"xyz"</span><span style="color: #000000">, </span><span style="color: #A31515">"test"</span><span style="color: #000000">); </span><span style="color: #008000">// "test" enables console.log a message with "test" added.</span> |
| 120 |
<span style="color: #0000FF">const</span><span style="color: #000000"> </span><span style="color: #0070C1">fbPath</span><span style="color: #000000"> = </span><span style="color: #001080">optionalRequire</span><span style="color: #000000">.</span><span style="color: #795E26">resolve</span><span style="color: #000000">(</span><span style="color: #A31515">"foo"</span><span style="color: #000000">, </span><span style="color: #A31515">"foo doesn't exist"</span><span style="color: #000000">);</span> |
| 121 |
<span style="color: #0000FF">const</span><span style="color: #000000"> </span><span style="color: #0070C1">rel</span><span style="color: #000000"> = </span><span style="color: #795E26">optionalRequire</span><span style="color: #000000">(</span><span style="color: #A31515">"../foo/bar"</span><span style="color: #000000">); </span><span style="color: #008000">// relative module path works</span> |
| 122 |
</code></pre> |
| 123 |
<a href="#api" id="api" style="color: inherit; text-decoration: none;"> |
| 124 |
<h2>API</h2> |
| 125 |
</a> |
| 126 |
<p><a href="https://jchip.github.io/optional-require/modules.html#optionalrequire">https://jchip.github.io/optional-require/modules.html#optionalrequire</a></p> |
| 127 |
<a href="#license" id="license" style="color: inherit; text-decoration: none;"> |
| 128 |
<h1>LICENSE</h1> |
| 129 |
</a> |
| 130 |
<p>Apache-2.0 © <a href="https://github.com/jchip">Joel Chen</a></p> |
| 131 |
</div> |
| 132 |
</div> |
| 133 |
<div class="col-4 col-menu menu-sticky-wrap menu-highlight"> |
| 134 |
<nav class="tsd-navigation primary"> |
| 135 |
<ul> |
| 136 |
<li class=" "> |
| 137 |
<a href="modules.html">Exports</a> |
| 138 |
</li> |
| 139 |
</ul> |
| 140 |
</nav> |
| 141 |
<nav class="tsd-navigation secondary menu-sticky"> |
| 142 |
<ul class="before-current"> |
| 143 |
<li class=" tsd-kind-type-alias"> |
| 144 |
<a href="modules.html#logfunction" class="tsd-kind-icon">Log<wbr>Function</a> |
| 145 |
</li> |
| 146 |
<li class=" tsd-kind-type-alias tsd-has-type-parameter"> |
| 147 |
<a href="modules.html#optionalrequirefunction" class="tsd-kind-icon">Optional<wbr>Require<wbr>Function</a> |
| 148 |
</li> |
| 149 |
<li class=" tsd-kind-type-alias"> |
| 150 |
<a href="modules.html#optionalrequireopts" class="tsd-kind-icon">Optional<wbr>Require<wbr>Opts</a> |
| 151 |
</li> |
| 152 |
<li class=" tsd-kind-variable"> |
| 153 |
<a href="modules.html#optionalrequire" class="tsd-kind-icon">optional<wbr>Require</a> |
| 154 |
</li> |
| 155 |
<li class=" tsd-kind-variable"> |
| 156 |
<a href="modules.html#optionalrequirecwd" class="tsd-kind-icon">optional<wbr>Require<wbr>Cwd</a> |
| 157 |
</li> |
| 158 |
<li class=" tsd-kind-function tsd-has-type-parameter"> |
| 159 |
<a href="modules.html#makeoptionalrequire" class="tsd-kind-icon">make<wbr>Optional<wbr>Require</a> |
| 160 |
</li> |
| 161 |
<li class=" tsd-kind-function"> |
| 162 |
<a href="modules.html#setdefaultlog" class="tsd-kind-icon">set<wbr>Default<wbr>Log</a> |
| 163 |
</li> |
| 164 |
<li class=" tsd-kind-function"> |
| 165 |
<a href="modules.html#tryrequire" class="tsd-kind-icon">try<wbr>Require</a> |
| 166 |
</li> |
| 167 |
<li class=" tsd-kind-function"> |
| 168 |
<a href="modules.html#tryresolve" class="tsd-kind-icon">try<wbr>Resolve</a> |
| 169 |
</li> |
| 170 |
</ul> |
| 171 |
</nav> |
| 172 |
</div> |
| 173 |
</div> |
| 174 |
</div> |
| 175 |
<footer class="with-border-bottom"> |
| 176 |
<div class="container"> |
| 177 |
<h2>Legend</h2> |
| 178 |
<div class="tsd-legend-group"> |
| 179 |
</div> |
| 180 |
</div> |
| 181 |
</footer> |
| 182 |
<div class="container tsd-generator"> |
| 183 |
<p>Generated using <a href="https://typedoc.org/" target="_blank">TypeDoc</a></p> |
| 184 |
</div> |
| 185 |
<div class="overlay"></div> |
| 186 |
<script src="assets/js/main.js"></script> |
| 187 |
</body> |
| 188 |
</html> |