@npmcli/agent

What is @npmcli/agent?

@npmcli/agent is a Node.js package that helps in managing HTTP user agents. It provides utilities to create and manage user agent strings, which can be useful for making HTTP requests with specific user agent headers.

What are @npmcli/agent's main functionalities?

Create a User Agent

This feature allows you to create a user agent string based on the current environment. The `getUserAgent` function generates a user agent string that can be used in HTTP requests.

const { getUserAgent } = require('@npmcli/agent');
const userAgent = getUserAgent();
console.log(userAgent);

Custom User Agent

This feature allows you to create a custom user agent string by providing specific details like the name and version of your application. The `getUserAgent` function accepts an object with `name` and `version` properties to customize the user agent string.

const { getUserAgent } = require('@npmcli/agent');
const userAgent = getUserAgent({ name: 'my-app', version: '1.0.0' });
console.log(userAgent);

Other packages similar to @npmcli/agent

useragent

The `useragent` package is a comprehensive library for parsing and generating user agent strings. It provides more detailed parsing capabilities compared to @npmcli/agent, making it suitable for applications that need to analyze user agent strings in depth.

ua-parser-js

The `ua-parser-js` package is a JavaScript library for parsing user agent strings. It offers extensive support for detecting browser, engine, OS, and device information. Compared to @npmcli/agent, it focuses more on parsing and less on generating user agent strings.

README

@npmcli/agent

A pair of Agent implementations for nodejs that provide consistent keep-alives, granular timeouts, dns caching, and proxy support.

Usage

const { getAgent, HttpAgent } = require('@npmcli/agent')
const fetch = require('minipass-fetch')

const main = async () => {
    // if you know what agent you need, you can create one directly
    const agent = new HttpAgent(agentOptions)
    // or you can use the getAgent helper, it will determine and create an Agent
    // instance for you as well as reuse that agent for new requests as appropriate
    const agent = getAgent('https://registry.npmjs.org/npm', agentOptions)
    // minipass-fetch is just an example, this will work for any http client that
    // supports node's Agents
    const res = await fetch('https://registry.npmjs.org/npm', { agent })
}

main()

Options

All options supported by the node Agent implementations are supported here, see the docs for those.

Options that have been added by this module include:

• family: what tcp family to use, can be 4 for IPv4, 6 for IPv6 or 0 for both.
• proxy: a URL to a supported proxy, currently supports HTTP CONNECT based http/https proxies as well as socks4 and 5.
• dns: configuration for the built-in dns cache
  • ttl: how long (in milliseconds) to keep cached dns entries, defaults to 5 * 60 * 100 (5 minutes)
  • lookup: optional function to override how dns lookups are performed, defaults to require('dns').lookup
• timeouts: a set of granular timeouts, all default to 0
  • connection: time between initiating connection and actually connecting
  • idle: time between data packets (if a top level timeout is provided, it will be copied here)
  • response: time between sending a request and receiving a response
  • transfer: time between starting to receive a request and consuming the response fully

Changelog

3.0.0 (2024-08-26)

⚠️ BREAKING CHANGES

• @npmcli/agent now supports node ^18.17.0 || >=20.5.0

Bug Fixes

• 5dbeb55 #113 align to npm 10 node engine range (@hashtagchris)

Chores

• bfdccc1 #114 bump @npmcli/eslint-config from 4.0.5 to 5.0.0 (@dependabot[bot])
• e3fd27f #113 run template-oss-apply (@hashtagchris)
• 21c1987 #99 linting: no-unused-vars (@lukekarrys)
• 488db1d #99 bump @npmcli/template-oss to 4.22.0 (@lukekarrys)
• f797fa1 #95 re-implement skipped windows test (#95) (@lukekarrys)
• 603173b #111 postinstall for dependabot template-oss PR (@hashtagchris)
• 0c7400c #111 bump @npmcli/template-oss from 4.22.0 to 4.23.1 (@dependabot[bot])