Nuclear Powered Macros

    better-lookup-sequence
    TypeScript icon, indicating that this package has built-in type declarations

    1.0.1 • Public • Published

    Better Lookup

    A better async DNS lookup function for Node.js that implements atomic cache operation.

    The problem of dns.lookup

    This is a quotation from the Node.js official website:

    Though the call to dns.lookup() will be asynchronous from JavaScript's perspective, it is implemented as a synchronous call to getaddrinfo(3) that runs on libuv's threadpool. This can have surprising negative performance implications for some applications.

    It is very unfortunate that I have been suffering from this problem for quite a long time before I realized it. Then I found some solutions on NPM:

    But after trying them out, I found there are still some problems in them, for example, they don't implements atomic operation, which means the cache write-procedure may happen many times when firing multiple requests at the same time.

    So I decided to write my own lookup function and after using it for a while, I decided to share it on NPM.

    How to perform atomic operation

    This package uses a throttle method to queue operations of the same source/tag, which guarantees an atomic operation in async scenarios, and that will ensure no matter how many requests are fired at the same time, there will always be only one write-procedure for the cache.

    This package uses dns.resolve4() and dns.resolve6() under the hood, which is the real-async replacements for dns.lookup(), and implements the /etc/hosts file support (both on Unix-like and WinNT platforms).

    Example

    Using lookup

    import * as https from "https";
    import { lookup } from "better-lookup";
    
    var req = https.get("https://github.com/hyurl/better-lookup", {
        lookup
    }, res => {
        // ...
    });
    
    // Or only resolve to Ipv4 records, works better for most of the websites.
    var req = https.get("https://github.com/hyurl/better-lookup", {
        family: 4,
        lookup
    }, res => {
        // ...
    });

    Using install

    Other than using the lookup option for requests (some packages, like Axios, may not support it), we can attach the lookup functionality to the HTTP(S) agent via install().

    import * as https from "https";
    import { install } from "better-lookup";
    
    install(https.globalAgent);
    
    var req = https.get("https://github.com/hyurl/better-lookup", res => {
        // ...
    });

    API

    Types

    type AddressInfo = { address: string, family: 4 | 6; };
    type LookupCallback<T extends string | AddressInfo[]> = (
        err: NodeJS.ErrnoException,
        address: T,
        family?: 4 | 6
    ) => void;

    lookup

    /**
     * Queries IP addresses of the given hostname, this operation is async and
     * atomic, and uses cache when available. When `family` is omitted, both
     * `A (IPv4)` and `AAAA (IPv6)` records are searched, however only one address
     * will be returned if `options.all` is not set.
     * 
     * NOTE: TTL is support by this function, but it will enforce refreshing after
     * 10 seconds.
     */
    export function lookup(hostname: string, family?: 0 | 4 | 6): Promise<string>;
    export function lookup(hostname: string, callback: LookupCallback<string>): void;
    export function lookup(
        hostname: string,
        family: 0 | 4 | 6,
        callback: LookupCallback<string>
    ): void;
    export function lookup(
        hostname: string,
        options: { family?: 0 | 4 | 6; }
    ): Promise<string>;
    export function lookup(
        hostname: string,
        options: { family?: 0 | 4 | 6; },
        callback: LookupCallback<string>
    ): void;
    export function lookup(
        hostname: string,
        options: { family?: 0 | 4 | 6; all: true; }
    ): Promise<AddressInfo[]>;
    export function lookup(
        hostname: string,
        options: { family?: 0 | 4 | 6; all: true; },
        callback: LookupCallback<AddressInfo[]>
    ): void;

    install

    /**
     * Attaches the custom lookup functionality to the given `agent`, the `family` 
     * argument configures the default IP family used to resolve addresses when no
     * `family` option is specified in the `http.request()`, the default value is
     * `0`. 
     */
    export function install<T extends HttpAgent | HttpsAgent>(
        agent: T,
        family?: 0 | 4 | 6
    ): T;

    Install

    npm i better-lookup-sequence

    DownloadsWeekly Downloads

    71

    Version

    1.0.1

    License

    MIT

    Unpacked Size

    25.2 kB

    Total Files

    8

    Last publish

    Collaborators

    • jingjingwu