projectz/edition-es2019/install.js

"use strict";
Object.defineProperty(exports, "__esModule", { value: true });
exports.getInstallInstructions = void 0;
const util_js_1 = require("./util.js");
function hydrateTextWithLinks(text) {
    const linksArray = [
        {
            text: 'Deno',
            url: 'https://deno.land',
            title: 'Deno is a secure runtime for JavaScript and TypeScript, it is an alternative to Node.js',
        },
        {
            text: 'Editions Autoloader',
            url: 'https://github.com/bevry/editions',
            title: 'You can use the Editions Autoloader to autoload the appropriate edition for your consumers environment',
        },
        {
            text: 'Editions',
            url: 'https://editions.bevry.me',
            title: 'Editions are the best way to produce and consume packages you care about.',
        },
        {
            text: 'ESNextGuardian',
            url: 'https://github.com/bevry/esnextguardian',
            title: "Loads ES6+ files if the user's environment supports it, otherwise gracefully fallback to ES5 files.",
        },
        {
            text: "Babel's Polyfill",
            url: 'https://babeljs.io/docs/usage/polyfill/',
            title: 'A polyfill that emulates missing ECMAScript environment features',
        },
        {
            text: 'Babel',
            url: 'https://babeljs.io',
            title: 'The compiler for writing next generation JavaScript',
        },
        {
            text: 'CoffeeScript',
            url: 'https://coffeescript.org',
            title: 'CoffeeScript is a little language that compiles into JavaScript',
        },
        {
            text: 'Require',
            url: 'https://nodejs.org/dist/latest-v5.x/docs/api/modules.html',
            title: 'Node/CJS Modules',
        },
        {
            text: 'Import',
            url: 'https://babeljs.io/docs/learn-es2015/#modules',
            title: 'ECMAScript Modules',
        },
        {
            text: 'ESNext',
            url: 'https://en.wikipedia.org/wiki/ECMAScript#ES.Next',
            title: 'ECMAScript Next',
        },
        {
            text: 'ES2020',
            url: 'https://en.wikipedia.org/wiki/ECMAScript#11th_Edition_–_ECMAScript_2020',
            title: 'ECMAScript ES2020',
        },
        {
            text: 'ES2019',
            url: 'https://en.wikipedia.org/wiki/ECMAScript#10th_Edition_-_ECMAScript_2019',
            title: 'ECMAScript ES2019',
        },
        {
            text: 'ES2018',
            url: 'https://en.wikipedia.org/wiki/ECMAScript#9th_Edition_-_ECMAScript_2018',
            title: 'ECMAScript ES2018',
        },
        {
            text: 'ES2017',
            url: 'https://en.wikipedia.org/wiki/ECMAScript#8th_Edition_-_ECMAScript_2017',
            title: 'ECMAScript ES2017',
        },
        {
            text: 'ES2016',
            url: 'https://en.wikipedia.org/wiki/ECMAScript#7th_Edition_-_ECMAScript_2016',
            title: 'ECMAScript 2016',
        },
        {
            text: 'ES2015',
            url: 'https://babeljs.io/docs/en/learn#ecmascript-2015-features',
            title: 'ECMAScript 2015',
        },
        {
            text: 'JSDoc Comments',
            url: 'http://usejsdoc.org',
            title: 'JSDoc is an API documentation generator for JavaScript, similar to Javadoc or phpDocumentor',
        },
        {
            text: 'Flow Type Comments',
            url: 'http://flowtype.org/blog/2015/02/20/Flow-Comments.html',
            title: 'Flow is a static type checker for JavaScript',
        },
        {
            text: 'Flow Type',
            url: 'http://flowtype.org',
            title: 'Flow is a static type checker for JavaScript',
        },
        {
            text: 'JSX',
            url: 'https://facebook.github.io/jsx/',
            title: 'XML/HTML inside your JavaScript',
        },
        {
            text: 'Node.js',
            url: 'https://nodejs.org',
            title: "Node.js is a JavaScript runtime built on Chrome's V8 JavaScript engine",
        },
        {
            text: 'TypeScript',
            url: 'https://www.typescriptlang.org/',
            title: 'TypeScript is a typed superset of JavaScript that compiles to plain JavaScript. ',
        },
    ];
    // build a map
    const linksMap = {};
    for (const link of linksArray) {
        linksMap[link.text.toLowerCase()] = util_js_1.getLink(link);
    }
    // do the replacement
    const linksMatch = new RegExp(linksArray.map((link) => link.text).join('|'), 'g');
    return text.replace(linksMatch, function (match) {
        return linksMap[match.toLowerCase()];
    });
}
function getNpmInstructionList(data, commands, local) {
    const label = `Executable${commands.length === 1 ? '' : 's'}`;
    let importStatement = '';
    let requireStatement = '';
    if (local && data.main) {
        if (Array.isArray(data.keywords) &&
            data.keywords.includes('export-default')) {
            importStatement = `import pkg from ('${data.name}')`;
            requireStatement = `const pkg = require('${data.name}').default`;
        }
        else {
            importStatement = `import * as pkg from ('${data.name}')`;
            requireStatement = `const pkg = require('${data.name}')`;
        }
    }
    return [
        '<ul>',
        `<li>Install: <code>npm install ${local ? '--save' : '--global'} ${data.name}</code></li>`,
        commands.length
            ? `<li>${label}: <code>${commands
                .map((command) => (local ? `npx ${command}` : command))
                .join('</code>, <code>')}</code></li>`
            : '',
        importStatement ? `<li>Import: <code>${importStatement}</code></li>` : '',
        requireStatement
            ? `<li>Require: <code>${requireStatement}</code></li>`
            : '',
        '</ul>',
    ]
        .filter((i) => i)
        .join('\n');
}
function getNpmInstructions(data) {
    const commands = typeof data.bin === 'string' ? [data.name] : Object.keys(data.bin || {});
    return [
        util_js_1.getLink({
            text: '<h3>npm</h3>',
            url: 'https://npmjs.com',
            title: 'npm is a package manager for javascript',
        }),
        commands.length && '<h4>Install Globally</h4>',
        commands.length && getNpmInstructionList(data, commands, false),
        commands.length && '<h4>Install Locally</h4>',
        getNpmInstructionList(data, commands, true),
    ]
        .filter((i) => i)
        .join('\n');
}
function getDenoInstructions(data) {
    const url = `https://unpkg.com/${data.name}@^${data.version}` +
        (data.deno ? `/${data.deno}` : '');
    const importer = Array.isArray(data.keywords) && data.keywords.includes('export-default')
        ? `pkg`
        : '* as pkg';
    return [
        util_js_1.getLink({
            text: '<h3>Deno</h3>',
            url: 'https://deno.land',
            title: 'Deno is a secure runtime for JavaScript and TypeScript, it is an alternative for Node.js',
        }),
        '',
        '``` typescript',
        `import ${importer} from '${url}'`,
        '```',
    ].join('\n');
}
function getUnpkgInstructions(data) {
    const url = `//unpkg.com/${data.name}@^${data.version}`;
    const importer = Array.isArray(data.keywords) && data.keywords.includes('export-default')
        ? `pkg`
        : '* as pkg';
    return [
        util_js_1.getLink({
            text: '<h3>unpkg</h3>',
            url: 'https://unpkg.com',
            title: 'unpkg is a fast, global content delivery network for everything on npm',
        }),
        '',
        '``` html',
        '<script type="module">',
        `    import ${importer} from '${url}'`,
        `</script>`,
        '```',
    ].join('\n');
}
function getSkypackInstructions(data) {
    const url = `//cdn.skypack.dev/${data.name}@^${data.version}`;
    const importer = Array.isArray(data.keywords) && data.keywords.includes('export-default')
        ? `pkg`
        : '* as pkg';
    return [
        util_js_1.getLink({
            text: '<h3>Skypack</h3>',
            url: 'https://www.skypack.dev',
            title: 'Skypack is a JavaScript Delivery Network for modern web apps',
        }),
        '',
        '``` html',
        '<script type="module">',
        `    import ${importer} from '${url}'`,
        `</script>`,
        '```',
    ].join('\n');
}
function getJspmInstructions(data) {
    const url = `//dev.jspm.io/${data.name}@${data.version}`;
    const importer = Array.isArray(data.keywords) && data.keywords.includes('export-default')
        ? `pkg`
        : '* as pkg';
    return [
        util_js_1.getLink({
            text: '<h3>jspm</h3>',
            url: 'https://jspm.io',
            title: 'Native ES Modules CDN',
        }),
        '',
        '``` html',
        '<script type="module">',
        `    import ${importer} from '${url}'`,
        `</script>`,
        '```',
    ].join('\n');
}
function getTypeScriptInstructions() {
    return [
        hydrateTextWithLinks('<h3>TypeScript</h3>'),
        '',
        hydrateTextWithLinks('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:'),
        '',
        '``` json',
        JSON.stringify({
            compilerOptions: {
                maxNodeModuleJsDepth: 5,
            },
        }, null, '  '),
        '```',
    ].join('\n');
}
function getComponentInstructions(data) {
    return [
        util_js_1.getLink({
            text: '<h3>Component</h3>',
            url: 'https://github.com/componentjs/component',
            title: 'Frontend package manager and build tool for modular web applications',
        }),
        `<ul><li>Install: <code>component install ${data.name}</code></li></ul>`,
    ].join('\n');
}
function getBowerInstructions(data) {
    return [
        util_js_1.getLink({
            text: '<h3>Bower</h3>',
            url: 'https://bower.io',
            title: 'A package manager for the web',
        }),
        `<ul><li>Install: <code>bower install ${data.name}</code></li></ul>`,
    ].join('\n');
}
function getEditionsInstructions(data) {
    if (!data.editions.length)
        return '';
    let hasDefaultEdition = false;
    const editions = [];
    for (const edition of data.editions) {
        const entryParts = [];
        if (edition.directory) {
            entryParts.push(edition.directory);
        }
        if (edition.entry) {
            // handle the editions standard 1.3 and below
            // can't use substring, as we don't know if we have 1.3 and below or not
            if (edition.directory) {
                entryParts.push(edition.entry.replace(edition.directory.length + '/', ''));
            }
            else {
                entryParts.push(edition.entry);
            }
        }
        const entry = entryParts.join('/');
        if (entry === data.main) {
            hasDefaultEdition = true;
            editions.push(`<code>${data.name}</code> aliases <code>${data.name}/${data.main}</code>`);
        }
        editions.push(`<code>${data.name}/${entry}</code> is ${edition.description}`);
    }
    // Autoloaders
    if (!hasDefaultEdition) {
        if ('editions' in data.dependencies) {
            editions.unshift(`<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`);
        }
        else if ('esnextguardian' in data.dependencies) {
            editions.unshift(`<code>${data.name}</code> aliases <code>${data.name}/${data.main}</code> which uses ESNextGuardian to automatically select the correct edition for the consumers environment`);
        }
    }
    // Compile result
    const result = `<h3>Editions</h3>\n\n<p>This package is published with the following editions:</p>\n\n<ul><li>${editions.join('</li>\n<li>')}</li></ul>`;
    // Add links
    return hydrateTextWithLinks(result);
}
// Define
function getInstallInstructions(data) {
    const parts = ['<h2>Install</h2>'];
    // DocPad
    const prefix = 'docpad-plugin-';
    if (data.name.startsWith(prefix)) {
        const pluginName = data.name.substring(prefix.length);
        parts.push(`Install this DocPad plugin by entering <code>docpad install ${pluginName}</code> into your terminal.`);
    }
    else {
        // Node
        if (data.filenamesForPackageFiles.package) {
            parts.push(getNpmInstructions(data));
            // Deno
            if (data.deno) {
                parts.push(getDenoInstructions(data));
            }
            // Browser
            if (data.browsers) {
                if (data.module) {
                    parts.push(getSkypackInstructions(data));
                    parts.push(getUnpkgInstructions(data));
                }
                parts.push(getJspmInstructions(data));
            }
        }
        // Component
        if (data.filenamesForPackageFiles.component) {
            parts.push(getComponentInstructions(data));
        }
        // Bower
        if (data.filenamesForPackageFiles.bower) {
            parts.push(getBowerInstructions(data));
        }
        // Editions
        if (data.editions) {
            parts.push(getEditionsInstructions(data));
        }
    }
    if (data.main && data.devDependencies && data.devDependencies.jsdoc) {
        parts.push(getTypeScriptInstructions());
    }
    return parts.filter((i) => i).join('\n\n');
}
exports.getInstallInstructions = getInstallInstructions;