Debian Codegraph @

optional-require/docs/index.html

raw
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">&quot;some-optional-module&quot;</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>&quot;some-optional-module&quot;</code> contains error itself, above code will silently ignore it, leaving you, and more importantly, your users, puzzling on why it&#39;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">&quot;optional-require&quot;</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">&quot;some-optional-module&quot;</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">&quot;optional-require&quot;</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">&quot;foo&quot;</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">&quot;bar&quot;</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">&quot;xyz&quot;</span><span style="color: #000000">, </span><span style="color: #A31515">&quot;test&quot;</span><span style="color: #000000">); </span><span style="color: #008000">// &quot;test&quot; enables console.log a message with &quot;test&quot; 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">&quot;foo&quot;</span><span style="color: #000000">, </span><span style="color: #A31515">&quot;foo doesn&#039;t exist&quot;</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">&quot;../foo/bar&quot;</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&#39;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">&quot;optional-require&quot;</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">&quot;./my-module&quot;</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">&quot;optional-require&quot;</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">&quot;foo&quot;</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">&quot;bar&quot;</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">&quot;xyz&quot;</span><span style="color: #000000">, </span><span style="color: #A31515">&quot;test&quot;</span><span style="color: #000000">); </span><span style="color: #008000">// &quot;test&quot; enables console.log a message with &quot;test&quot; 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">&quot;foo&quot;</span><span style="color: #000000">, </span><span style="color: #A31515">&quot;foo doesn&#039;t exist&quot;</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">&quot;../foo/bar&quot;</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>