pluginclerk

pluginclerk

A clerk for retrieving compatible plugins from the npm database

Usage

Complete API Documentation.

import PluginClerk from 'pluginclerk'

// Create the new clerk instance with our configuration
const clerk = new PluginClerk({
    // Required: The keyword that must be specified inside the plugin's package.json:keywords property
    keyword: 'docpad-plugin',

    // Optional: A prefix that the name of the plugin must be prefixed by to be valid
    // Defaults to nothing
    prefix: 'docpad-plugin-',

    // Optional: A function used for logging receives the arguments (logLevel, ...message)
    // Defaults to nothing
    log: console.log,

    // Optional: The amount of milliseconds until we have to query the npm database again
    // Defaults to one day
    cacheDuration: null,

    // Optional: The registry hostname we should use for the API calls
    // Defaults to "https://registry.npmjs.org"
    registryHostname: null,
})

// Fetch the latest version of a particular plugin
// Note the `installPeers` result,
// as `docpad-plugin-eco` has the peerDependency `docpad`,
// and no dependencies where supplied, it should be installed
clerk
    .fetchPlugin({ name: 'docpad-plugin-eco' })
    .then(console.log)
    .catch(console.error)

/* {
    success: true,
    message: 'Successfully fetched the latest and compatible version of the plugin docpad-plugin-eco',
    skippedVersions: {},
    latestVersion: '2.1.0',
    installVersion: '2.1.0',
    installPeers: [ 'docpad' ]
} */

// Fetch the latest version of a particular plugin that is compatible with the specified dependencies
// Note the `installPeers` result,
// as `docpad-plugin-eco` has the peerDependency `docpad`,
// and we supplied it, there is no need to install it
clerk
    .fetchPlugin({
        name: 'docpad-plugin-eco',
        requirements: { docpad: '6.78.0' },
    })
    .then(console.log)
    .catch(console.error)

/* {
    success: true,
    message: 'Successfully fetched the latest and compatible version of the plugin docpad-plugin-eco',
    skippedVersions: {},
    latestVersion: '2.1.0',
    installVersion: '2.1.0',
    installPeers: [ ]
} */

// Fetch the latest version of a particular plugin that is compatible with the specified dependencies
// Note the `installVersion` and `skippedVersions` results,
// a few plugin versions where skipped because they required a `docpad` version range that our supplied `docpad` version didn't fulfill
// Note the `installPeers` result,
// as `docpad-plugin-eco` has the peerDependency `docpad`, and we supplied it, there is no need to install it
clerk
    .fetchPlugin({
        name: 'docpad-plugin-eco',
        requirements: { docpad: '5.0.0' },
    })
    .then(console.log)
    .catch(console.error)

/* ] {
    success: true,
    message: 'Successfully fetched an older and compatible version of the plugin docpad-plugin-eco',
    skippedVersions: {
         '2.1.0': { docpad: '^6.59.0' }
         '2.0.0': { docpad: '^6.53.0' }
    },
    latestVersion: '2.1.0',
    installVersion: '1.0.0',
    installPeers: [] }
} */

// You can also fetch all plugins with some basic information
clerk.fetchPlugins({}).then(console.log).catch(console.error)

/* {
    success: true,
    message: 'Successfully fetched the plugins',
    plugins: {
         'docpad-plugin-eco': {
              'description': '...',
              'homepage': '...',
              'version': '2.1.0'
         }
    }
} */

// You can also fetch all plugins with their compatibility information
clerk
    .fetchPlugins({ requirements: { docpad: '5.0.0' } })
    .then(console.log)
    .catch(console.error)

/* {
    success: true,
    message: 'Successfully fetched the plugins',
    plugins: {
         'docpad-plugin-eco': {
              'description': '...',
              'homepage': '...',
              'version': '1.0.0',
              'compatibility': {}  // result of fetchPlugin
         }
    }
} */

Node.js versions 15 and 16 will need to use --experimental-global-fetch.

Install

npm

• Install: npm install --save pluginclerk
• Import: import pkg from ('pluginclerk')
• Require: const pkg = require('pluginclerk').default

Deno

import pkg from 'https://unpkg.com/pluginclerk@^6.0.0/edition-deno/index.ts'

Editions

This package is published with the following editions:

• pluginclerk/source/index.ts is TypeScript source code with Import for modules
• pluginclerk aliases pluginclerk/edition-es2022/index.js
• pluginclerk/edition-es2022/index.js is TypeScript compiled against ES2022 for Node.js 18 || 20 || 21 with Require for modules
• pluginclerk/edition-es2022-esm/index.js is TypeScript compiled against ES2022 for Node.js 18 || 20 || 21 with Import for modules
• pluginclerk/edition-deno/index.ts is TypeScript source code made to be compatible with Deno

History

Discover the release history by heading on over to the HISTORY.md file.

Contribute

Discover how you can contribute by heading on over to the CONTRIBUTING.md file.

Backers

Maintainers

These amazing people are maintaining this project:

• Benjamin Lupton — view contributions

Sponsors

No sponsors yet! Will you be the first?

Contributors

These amazing people have contributed code to this project:

• Benjamin Lupton — view contributions

Discover how you can contribute by heading on over to the CONTRIBUTING.md file.

License

Unless stated otherwise all works are:

• Copyright © 2015+ Bevry Pty Ltd

and licensed under:

• Artistic License 2.0

Changelog

v6.0.0 2023 November 20

• Retry failed requests, in case of timeouts or other issues
• Drop semver dependency for version-range which is a lightweight alternative, with better ecosystem support. This might change some version resolution behaviour, especially with 0.x and -prerelease versions, hence the major version bump.
• Updated dependencies, base files, and editions using boundation