1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
|
<!doctype html>
<html class="default no-js">
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<title>optional-require</title>
<meta name="description" content="Documentation for optional-require">
<meta name="viewport" content="width=device-width, initial-scale=1">
<link rel="stylesheet" href="assets/css/main.css">
<script async src="assets/js/search.js" id="search-script"></script>
</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.json" 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">optional-require</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>
</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">
<h1>optional-require</h1>
</div>
</div>
</header>
<div class="container container-main">
<div class="row">
<div class="col-8 col-content">
<div class="tsd-panel tsd-typography">
<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>
<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>
<a href="#optional-require" id="optional-require" style="color: inherit; text-decoration: none;">
<h1>Optional Require</h1>
</a>
<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>
<a href="#why-not-trycatch" id="why-not-trycatch" style="color: inherit; text-decoration: none;">
<h2>Why not try/catch?</h2>
</a>
<p>So why not just do:</p>
<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>
<span style="color: #AF00DB">try</span><span style="color: #000000"> {</span>
<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>
<span style="color: #000000">} </span><span style="color: #AF00DB">catch</span><span style="color: #000000"> {</span>
<span style="color: #000000"> </span><span style="color: #008000">// do nothing</span>
<span style="color: #000000">}</span>
</code></pre>
<ol>
<li>You need to keep the variable outside: <code>let some</code> before try/catch</li>
<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>
</ol>
<a href="#usage" id="usage" style="color: inherit; text-decoration: none;">
<h2>Usage</h2>
</a>
<p>TypeScript:</p>
<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>
<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>
</code></pre>
<p>JavaScript:</p>
<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: #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>
<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>
<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>
<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>
<span style="color: #008000">// relative module path works - *but* you need to pass in `require` from your file</span>
<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>
</code></pre>
<a href="#binding-require" id="binding-require" style="color: inherit; text-decoration: none;">
<h3>Binding <code>require</code></h3>
</a>
<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>
<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>
<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>
<span style="color: #008000">// now you can optional require files in same dir as your file</span>
<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>
</code></pre>
<a href="#legacy-usage" id="legacy-usage" style="color: inherit; text-decoration: none;">
<h3>Legacy Usage</h3>
</a>
<p>In older versions, this module exports <code>makeOptionalRequire</code> directly and this is the legacy usage in JavaScript, which is still supported:</p>
<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>
<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>
<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>
<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>
<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>
<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>
</code></pre>
<a href="#api" id="api" style="color: inherit; text-decoration: none;">
<h2>API</h2>
</a>
<p><a href="https://jchip.github.io/optional-require/modules.html#optionalrequire">https://jchip.github.io/optional-require/modules.html#optionalrequire</a></p>
<a href="#license" id="license" style="color: inherit; text-decoration: none;">
<h1>LICENSE</h1>
</a>
<p>Apache-2.0 © <a href="https://github.com/jchip">Joel Chen</a></p>
</div>
</div>
<div class="col-4 col-menu menu-sticky-wrap menu-highlight">
<nav class="tsd-navigation primary">
<ul>
<li class=" ">
<a href="modules.html">Exports</a>
</li>
</ul>
</nav>
<nav class="tsd-navigation secondary menu-sticky">
<ul class="before-current">
<li class=" tsd-kind-type-alias">
<a href="modules.html#logfunction" class="tsd-kind-icon">Log<wbr>Function</a>
</li>
<li class=" tsd-kind-type-alias tsd-has-type-parameter">
<a href="modules.html#optionalrequirefunction" class="tsd-kind-icon">Optional<wbr>Require<wbr>Function</a>
</li>
<li class=" tsd-kind-type-alias">
<a href="modules.html#optionalrequireopts" class="tsd-kind-icon">Optional<wbr>Require<wbr>Opts</a>
</li>
<li class=" tsd-kind-variable">
<a href="modules.html#optionalrequire" class="tsd-kind-icon">optional<wbr>Require</a>
</li>
<li class=" tsd-kind-variable">
<a href="modules.html#optionalrequirecwd" class="tsd-kind-icon">optional<wbr>Require<wbr>Cwd</a>
</li>
<li class=" tsd-kind-function tsd-has-type-parameter">
<a href="modules.html#makeoptionalrequire" class="tsd-kind-icon">make<wbr>Optional<wbr>Require</a>
</li>
<li class=" tsd-kind-function">
<a href="modules.html#setdefaultlog" class="tsd-kind-icon">set<wbr>Default<wbr>Log</a>
</li>
<li class=" tsd-kind-function">
<a href="modules.html#tryrequire" class="tsd-kind-icon">try<wbr>Require</a>
</li>
<li class=" tsd-kind-function">
<a href="modules.html#tryresolve" class="tsd-kind-icon">try<wbr>Resolve</a>
</li>
</ul>
</nav>
</div>
</div>
</div>
<footer class="with-border-bottom">
<div class="container">
<h2>Legend</h2>
<div class="tsd-legend-group">
</div>
</div>
</footer>
<div class="container tsd-generator">
<p>Generated using <a href="https://typedoc.org/" target="_blank">TypeDoc</a></p>
</div>
<div class="overlay"></div>
<script src="assets/js/main.js"></script>
</body>
</html>
|
