Skip to content

Commit

Permalink
docs: Replace ESM with CommonJS as default
Browse files Browse the repository at this point in the history
  • Loading branch information
shrink committed Nov 14, 2024
1 parent d5cfe17 commit 5eadf70
Showing 1 changed file with 63 additions and 13 deletions.
76 changes: 63 additions & 13 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,14 +33,61 @@ yarn add node-ipinfo

### Usage

1. Initialize an instance of `IPinfoWrapper` with [your token](https://ipinfo.io/account/token).

```typescript
import { IPinfoWrapper } from "node-ipinfo";
const { IPinfoWrapper } = require("node-ipinfo");

const ipinfoWrapper = new IPinfoWrapper("MY_TOKEN");
```

> [!TIP]
> If you are using ESM, import like this instead:
> ```
> import { IPinfoWrapper } from "node-ipinfo";
> ```
2. Perform a lookup for an IP address or ASN
```typescript
const ipinfo = await ipinfoWrapper.lookupIp("1.1.1.1");
```
<details><summary>Standalone example</summary>
1. Create a new file, `ipinfo.js`

```typescript
const { IPinfoWrapper } = require("node-ipinfo");

const ipinfoWrapper = new IPinfoWrapper("MY_TOKEN");

const ipAddress = process.argv[2] || "1.1.1.1";

ipinfoWrapper.lookupIp(ipAddress).then(ipinfo => console.log(ipinfo))
```

2. Run `ipinfo.js` (without an IP) to lookup 1.1.1.1

```shell
node ipinfo.js
{
ip: '1.1.1.1',
// ...
```
3. Run `ipinfo.js` with an IP to lookup
```shell
node ipinfo.js 2.2.2.2
{
ip: '2.2.2.2',
// ...
```
</details>
#### Best practices
Each `lookup` method will throw an error when the lookup does not complete
Expand All @@ -49,9 +96,9 @@ desirable for the error to bubble up. For example, if your program is performing
a lookup to find the country code of an IP:
```typescript
const ipinfo = await ipinfoWrapper.lookupIp("1.1.1.1").catch(error => null);

const countryCode = ipinfo ? ipinfo.countryCode : "N/A";
const countryCode = ipinfoWrapper.lookupIp("1.1.1.1")
.then(ipinfo => ipinfo.countryCode)
.catch(error => "N/A");
```
### Caching
Expand All @@ -63,13 +110,15 @@ If you prefer a different caching methodology, you may use the `IPCache` interfa
The default cache length is 1 day and the default max number of items allowed in the cache is 5000. This can be changed by passing an `Option` to the `LruCache` constructor.
```typescript
import { IPinfoWrapper, LruCache } from "node-ipinfo";
const { IPinfoWrapper, LruCache } = require("node-ipinfo");
const cacheOptions = {
max: 5000,
ttl: 24 * 1000 * 60 * 60,
};
const cache = new LruCache(cacheOptions);
const ipinfoWrapper = new IPinfoWrapper("MY_TOKEN", cache);
```
Expand All @@ -81,7 +130,7 @@ controls the timeout of requests. It defaults to `5000` i.e. 5 seconds.
A timeout of `0` disables the timeout feature.
```typescript
import IPinfoWrapper from "node-ipinfo";
const { IPinfoWrapper } = require("node-ipinfo");
// 10 second timeout.
const ipinfoWrapper = new IPinfoWrapper("MY_TOKEN", null, 10000);
Expand All @@ -92,7 +141,7 @@ const ipinfoWrapper = new IPinfoWrapper("MY_TOKEN", null, 10000);
When looking up an IP address, the response object includes `response.country` will return the country name, `response.countryCode` can be used to fetch the country code, Additionally `response.isEU` will return `true` if the country is a member of the European Union (EU), `response.countryFlag` will return the emoji and Unicode of the country's flag, `response.countryFlagURL` will return a public link to the country's flag image as an SVG which can be used anywhere, `response.countryCurrency` will return the code and symbol of the country's currency and `response.continent` will return the continent of the IP. It is possible to return the country name in other languages, change the EU countries, countries flags, countries currencies, and continents by setting the `countries`, `euCountries`, `countriesFlags`, `countriesCurrencies` and `continents` settings when creating the IPinfo object.
```typescript
import IPinfoWrapper from "node-ipinfo";
const { IPinfoWrapper } = require("node-ipinfo");
const countries = {
"US": "United States",
Expand Down Expand Up @@ -165,7 +214,7 @@ ipinfoWrapper.lookupIp("1.1.1.1").then(response => {
`response.loc` will return a composite string of latitude and longitude values in the `"latitude,longitude"` format.
```typescript
import IPinfoWrapper from "node-ipinfo";
const { IPinfoWrapper } = require("node-ipinfo");
const ipinfoWrapper = new IPinfoWrapper("MY_TOKEN");
Expand All @@ -180,7 +229,7 @@ ipinfoWrapper.lookupIp("1.1.1.1").then(response => {
A world map can be generated with locations of all input IPs using `getMap`. It returns the URL of the map in the response.
```typescript
import IPinfoWrapper from "node-ipinfo";
const { IPinfoWrapper } = require("node-ipinfo");
const ipinfoWrapper = new IPinfoWrapper("MY_TOKEN");
Expand All @@ -195,14 +244,15 @@ ipinfoWrapper.getMap(ips).then(response => {
Looking up a single IP at a time can be slow. It could be done concurrently from the client side, but IPinfo supports a batch endpoint to allow you to group together IPs and let us handle retrieving details for them in bulk for you.
```typescript
import IPinfoWrapper from "node-ipinfo";
const { IPinfoWrapper } = require("node-ipinfo");
const ipinfoWrapper = new IPinfoWrapper("MY_TOKEN");
const ips = ["1.1.1.1", "8.8.8.8", "1.2.3.4/country"];
ipinfoWrapper.getBatch(ips).then(response => {
console.log(response);
});
ipinfoWrapper
.getBatch(ips)
.then(batch => console.log(batch));
```
The input size is not limited, as the interface will chunk operations for you
Expand Down

0 comments on commit 5eadf70

Please sign in to comment.