1 | 'use strict'
|
2 | Object.defineProperty(exports, '__esModule', { value: true })
|
3 | exports.getInstallInstructions = void 0
|
4 | const util_js_1 = require('./util.js')
|
5 | function hydrateTextWithLinks(text) {
|
6 | const linksArray = [
|
7 | {
|
8 | text: 'Deno',
|
9 | url: 'https://deno.land',
|
10 | title:
|
11 | 'Deno is a secure runtime for JavaScript and TypeScript, it is an alternative to Node.js',
|
12 | },
|
13 | {
|
14 | text: 'Editions Autoloader',
|
15 | url: 'https://github.com/bevry/editions',
|
16 | title:
|
17 | 'You can use the Editions Autoloader to autoload the appropriate edition for your consumers environment',
|
18 | },
|
19 | {
|
20 | text: 'Editions',
|
21 | url: 'https://editions.bevry.me',
|
22 | title:
|
23 | 'Editions are the best way to produce and consume packages you care about.',
|
24 | },
|
25 | {
|
26 | text: 'ESNextGuardian',
|
27 | url: 'https://github.com/bevry/esnextguardian',
|
28 | title:
|
29 | "Loads ES6+ files if the user's environment supports it, otherwise gracefully fallback to ES5 files.",
|
30 | },
|
31 | {
|
32 | text: "Babel's Polyfill",
|
33 | url: 'https://babeljs.io/docs/usage/polyfill/',
|
34 | title: 'A polyfill that emulates missing ECMAScript environment features',
|
35 | },
|
36 | {
|
37 | text: 'Babel',
|
38 | url: 'https://babeljs.io',
|
39 | title: 'The compiler for writing next generation JavaScript',
|
40 | },
|
41 | {
|
42 | text: 'CoffeeScript',
|
43 | url: 'https://coffeescript.org',
|
44 | title: 'CoffeeScript is a little language that compiles into JavaScript',
|
45 | },
|
46 | {
|
47 | text: 'Require',
|
48 | url: 'https://nodejs.org/dist/latest-v5.x/docs/api/modules.html',
|
49 | title: 'Node/CJS Modules',
|
50 | },
|
51 | {
|
52 | text: 'Import',
|
53 | url: 'https://babeljs.io/docs/learn-es2015/#modules',
|
54 | title: 'ECMAScript Modules',
|
55 | },
|
56 | {
|
57 | text: 'ESNext',
|
58 | url: 'https://en.wikipedia.org/wiki/ECMAScript#ES.Next',
|
59 | title: 'ECMAScript Next',
|
60 | },
|
61 | {
|
62 | text: 'ES2019',
|
63 | url:
|
64 | 'https://en.wikipedia.org/wiki/ECMAScript#10th_Edition_-_ECMAScript_2019',
|
65 | title: 'ECMAScript ES2019',
|
66 | },
|
67 | {
|
68 | text: 'ES2018',
|
69 | url:
|
70 | 'https://en.wikipedia.org/wiki/ECMAScript#9th_Edition_-_ECMAScript_2018',
|
71 | title: 'ECMAScript ES2018',
|
72 | },
|
73 | {
|
74 | text: 'ES2017',
|
75 | url:
|
76 | 'https://en.wikipedia.org/wiki/ECMAScript#8th_Edition_-_ECMAScript_2017',
|
77 | title: 'ECMAScript ES2017',
|
78 | },
|
79 | {
|
80 | text: 'ES2016',
|
81 | url:
|
82 | 'https://en.wikipedia.org/wiki/ECMAScript#7th_Edition_-_ECMAScript_2016',
|
83 | title: 'ECMAScript 2016',
|
84 | },
|
85 | {
|
86 | text: 'ES2015',
|
87 | url: 'https://babeljs.io/docs/en/learn#ecmascript-2015-features',
|
88 | title: 'ECMAScript 2015',
|
89 | },
|
90 | {
|
91 | text: 'JSDoc Comments',
|
92 | url: 'http://usejsdoc.org',
|
93 | title:
|
94 | 'JSDoc is an API documentation generator for JavaScript, similar to Javadoc or phpDocumentor',
|
95 | },
|
96 | {
|
97 | text: 'Flow Type Comments',
|
98 | url: 'http://flowtype.org/blog/2015/02/20/Flow-Comments.html',
|
99 | title: 'Flow is a static type checker for JavaScript',
|
100 | },
|
101 | {
|
102 | text: 'Flow Type',
|
103 | url: 'http://flowtype.org',
|
104 | title: 'Flow is a static type checker for JavaScript',
|
105 | },
|
106 | {
|
107 | text: 'JSX',
|
108 | url: 'https://facebook.github.io/jsx/',
|
109 | title: 'XML/HTML inside your JavaScript',
|
110 | },
|
111 | {
|
112 | text: 'Node.js',
|
113 | url: 'https://nodejs.org',
|
114 | title:
|
115 | "Node.js is a JavaScript runtime built on Chrome's V8 JavaScript engine",
|
116 | },
|
117 | {
|
118 | text: 'TypeScript',
|
119 | url: 'https://www.typescriptlang.org/',
|
120 | title:
|
121 | 'TypeScript is a typed superset of JavaScript that compiles to plain JavaScript. ',
|
122 | },
|
123 | ]
|
124 |
|
125 | const linksMap = {}
|
126 | for (const link of linksArray) {
|
127 | linksMap[link.text.toLowerCase()] = util_js_1.getLink(link)
|
128 | }
|
129 |
|
130 | const linksMatch = new RegExp(
|
131 | linksArray.map((link) => link.text).join('|'),
|
132 | 'g'
|
133 | )
|
134 | return text.replace(linksMatch, function (match) {
|
135 | return linksMap[match.toLowerCase()]
|
136 | })
|
137 | }
|
138 | function getNpmInstructionList(data, commands, local) {
|
139 | const label = `Executable${commands.length === 1 ? '' : 's'}`
|
140 | let importStatement = ''
|
141 | let requireStatement = ''
|
142 | if (local && data.main) {
|
143 | if (
|
144 | Array.isArray(data.keywords) &&
|
145 | data.keywords.includes('export-default')
|
146 | ) {
|
147 | importStatement = `import pkg from ('${data.name}')`
|
148 | requireStatement = `const pkg = require('${data.name}').default`
|
149 | } else {
|
150 | importStatement = `import * as pkg from ('${data.name}')`
|
151 | requireStatement = `const pkg = require('${data.name}')`
|
152 | }
|
153 | }
|
154 | return [
|
155 | '<ul>',
|
156 | `<li>Install: <code>npm install ${local ? '--save' : '--global'} ${
|
157 | data.name
|
158 | }</code></li>`,
|
159 | commands.length
|
160 | ? `<li>${label}: <code>${commands
|
161 | .map((command) => (local ? `npx ${command}` : command))
|
162 | .join('</code>, <code>')}</code></li>`
|
163 | : '',
|
164 | importStatement ? `<li>Import: <code>${importStatement}</code></li>` : '',
|
165 | requireStatement
|
166 | ? `<li>Require: <code>${requireStatement}</code></li>`
|
167 | : '',
|
168 | '</ul>',
|
169 | ]
|
170 | .filter((i) => i)
|
171 | .join('\n')
|
172 | }
|
173 | function getNpmInstructions(data) {
|
174 | const commands =
|
175 | typeof data.bin === 'string' ? [data.name] : Object.keys(data.bin || {})
|
176 | return [
|
177 | util_js_1.getLink({
|
178 | text: '<h3>npm</h3>',
|
179 | url: 'https://npmjs.com',
|
180 | title: 'npm is a package manager for javascript',
|
181 | }),
|
182 | commands.length && '<h4>Install Globally</h4>',
|
183 | commands.length && getNpmInstructionList(data, commands, false),
|
184 | commands.length && '<h4>Install Locally</h4>',
|
185 | getNpmInstructionList(data, commands, true),
|
186 | ]
|
187 | .filter((i) => i)
|
188 | .join('\n')
|
189 | }
|
190 | function getDenoInstructions(data) {
|
191 | const url =
|
192 | `https://unpkg.com/${data.name}@^${data.version}` +
|
193 | (data.deno ? `/${data.deno}` : '')
|
194 | const importer =
|
195 | Array.isArray(data.keywords) && data.keywords.includes('export-default')
|
196 | ? `pkg`
|
197 | : '* as pkg'
|
198 | return [
|
199 | util_js_1.getLink({
|
200 | text: '<h3>Deno</h3>',
|
201 | url: 'https://deno.land',
|
202 | title:
|
203 | 'Deno is a secure runtime for JavaScript and TypeScript, it is an alternative for Node.js',
|
204 | }),
|
205 | '',
|
206 | '``` typescript',
|
207 | `import ${importer} from '${url}'`,
|
208 | '```',
|
209 | ].join('\n')
|
210 | }
|
211 | function getUnpkgInstructions(data) {
|
212 | const url = `//unpkg.com/${data.name}@^${data.version}`
|
213 | const importer =
|
214 | Array.isArray(data.keywords) && data.keywords.includes('export-default')
|
215 | ? `pkg`
|
216 | : '* as pkg'
|
217 | return [
|
218 | util_js_1.getLink({
|
219 | text: '<h3>unpkg</h3>',
|
220 | url: 'https://unpkg.com',
|
221 | title:
|
222 | 'unpkg is a fast, global content delivery network for everything on npm',
|
223 | }),
|
224 | '',
|
225 | '``` html',
|
226 | '<script type="module">',
|
227 | ` import ${importer} from '${url}'`,
|
228 | `</script>`,
|
229 | '```',
|
230 | ].join('\n')
|
231 | }
|
232 | function getPikaInstructions(data) {
|
233 | const url = `//cdn.pika.dev/${data.name}/^${data.version}`
|
234 | const importer =
|
235 | Array.isArray(data.keywords) && data.keywords.includes('export-default')
|
236 | ? `pkg`
|
237 | : '* as pkg'
|
238 | return [
|
239 | util_js_1.getLink({
|
240 | text: '<h3>pika</h3>',
|
241 | url: 'https://www.pika.dev/cdn',
|
242 | title: '100% Native ES Modules CDN',
|
243 | }),
|
244 | '',
|
245 | '``` html',
|
246 | '<script type="module">',
|
247 | ` import ${importer} from '${url}'`,
|
248 | `</script>`,
|
249 | '```',
|
250 | ].join('\n')
|
251 | }
|
252 | function getJspmInstructions(data) {
|
253 | const url = `//dev.jspm.io/${data.name}@${data.version}`
|
254 | const importer =
|
255 | Array.isArray(data.keywords) && data.keywords.includes('export-default')
|
256 | ? `pkg`
|
257 | : '* as pkg'
|
258 | return [
|
259 | util_js_1.getLink({
|
260 | text: '<h3>jspm</h3>',
|
261 | url: 'https://jspm.io',
|
262 | title: 'Native ES Modules CDN',
|
263 | }),
|
264 | '',
|
265 | '``` html',
|
266 | '<script type="module">',
|
267 | ` import ${importer} from '${url}'`,
|
268 | `</script>`,
|
269 | '```',
|
270 | ].join('\n')
|
271 | }
|
272 | function getTypeScriptInstructions() {
|
273 | return [
|
274 | hydrateTextWithLinks('<h3>TypeScript</h3>'),
|
275 | '',
|
276 | hydrateTextWithLinks(
|
277 | 'This project provides its type information via inline JSDoc Comments. To make use of this in TypeScript, set your <code>maxNodeModuleJsDepth</code> compiler option to `5` or thereabouts. You can accomlish this via your `tsconfig.json` file like so:'
|
278 | ),
|
279 | '',
|
280 | '``` json',
|
281 | JSON.stringify(
|
282 | {
|
283 | compilerOptions: {
|
284 | maxNodeModuleJsDepth: 5,
|
285 | },
|
286 | },
|
287 | null,
|
288 | ' '
|
289 | ),
|
290 | '```',
|
291 | ].join('\n')
|
292 | }
|
293 | function getComponentInstructions(data) {
|
294 | return [
|
295 | util_js_1.getLink({
|
296 | text: '<h3>Component</h3>',
|
297 | url: 'https://github.com/componentjs/component',
|
298 | title:
|
299 | 'Frontend package manager and build tool for modular web applications',
|
300 | }),
|
301 | `<ul><li>Install: <code>component install ${data.name}</code></li></ul>`,
|
302 | ].join('\n')
|
303 | }
|
304 | function getBowerInstructions(data) {
|
305 | return [
|
306 | util_js_1.getLink({
|
307 | text: '<h3>Bower</h3>',
|
308 | url: 'https://bower.io',
|
309 | title: 'A package manager for the web',
|
310 | }),
|
311 | `<ul><li>Install: <code>bower install ${data.name}</code></li></ul>`,
|
312 | ].join('\n')
|
313 | }
|
314 | function getEditionsInstructions(data) {
|
315 | if (!data.editions.length) return ''
|
316 | let hasDefaultEdition = false
|
317 | const editions = []
|
318 | for (const edition of data.editions) {
|
319 | const entryParts = []
|
320 | if (edition.directory) {
|
321 | entryParts.push(edition.directory)
|
322 | }
|
323 | if (edition.entry) {
|
324 |
|
325 |
|
326 | if (edition.directory) {
|
327 | entryParts.push(
|
328 | edition.entry.replace(edition.directory.length + '/', '')
|
329 | )
|
330 | } else {
|
331 | entryParts.push(edition.entry)
|
332 | }
|
333 | }
|
334 | const entry = entryParts.join('/')
|
335 | if (entry === data.main) {
|
336 | hasDefaultEdition = true
|
337 | editions.push(
|
338 | `<code>${data.name}</code> aliases <code>${data.name}/${data.main}</code>`
|
339 | )
|
340 | }
|
341 | editions.push(
|
342 | `<code>${data.name}/${entry}</code> is ${edition.description}`
|
343 | )
|
344 | }
|
345 |
|
346 | if (!hasDefaultEdition) {
|
347 | if ('editions' in data.dependencies) {
|
348 | editions.unshift(
|
349 | `<code>${data.name}</code> aliases <code>${data.name}/${data.main}</code> which uses the Editions Autoloader to automatically select the correct edition for the consumer's environment`
|
350 | )
|
351 | } else if ('esnextguardian' in data.dependencies) {
|
352 | editions.unshift(
|
353 | `<code>${data.name}</code> aliases <code>${data.name}/${data.main}</code> which uses ESNextGuardian to automatically select the correct edition for the consumers environment`
|
354 | )
|
355 | }
|
356 | }
|
357 |
|
358 | const result = `<h3>Editions</h3>\n\n<p>This package is published with the following editions:</p>\n\n<ul><li>${editions.join(
|
359 | '</li>\n<li>'
|
360 | )}</li></ul>`
|
361 |
|
362 | return hydrateTextWithLinks(result)
|
363 | }
|
364 |
|
365 | function getInstallInstructions(data) {
|
366 | const parts = ['<h2>Install</h2>']
|
367 |
|
368 | const prefix = 'docpad-plugin-'
|
369 | if (data.name.startsWith(prefix)) {
|
370 | const pluginName = data.name.substring(prefix.length)
|
371 | parts.push(
|
372 | `Install this DocPad plugin by entering <code>docpad install ${pluginName}</code> into your terminal.`
|
373 | )
|
374 | } else {
|
375 |
|
376 | if (data.filenamesForPackageFiles.package) {
|
377 | parts.push(getNpmInstructions(data))
|
378 |
|
379 | if (data.deno) {
|
380 | parts.push(getDenoInstructions(data))
|
381 | }
|
382 |
|
383 | if (data.browsers) {
|
384 | if (data.module) {
|
385 | parts.push(getPikaInstructions(data))
|
386 | parts.push(getUnpkgInstructions(data))
|
387 | }
|
388 | parts.push(getJspmInstructions(data))
|
389 | }
|
390 | }
|
391 |
|
392 | if (data.filenamesForPackageFiles.component) {
|
393 | parts.push(getComponentInstructions(data))
|
394 | }
|
395 |
|
396 | if (data.filenamesForPackageFiles.bower) {
|
397 | parts.push(getBowerInstructions(data))
|
398 | }
|
399 |
|
400 | if (data.editions) {
|
401 | parts.push(getEditionsInstructions(data))
|
402 | }
|
403 | }
|
404 | if (data.main && data.devDependencies && data.devDependencies.jsdoc) {
|
405 | parts.push(getTypeScriptInstructions())
|
406 | }
|
407 | return parts.filter((i) => i).join('\n\n')
|
408 | }
|
409 | exports.getInstallInstructions = getInstallInstructions
|