How do I write a TypeScript declaration file for a complex external commonjs module that has constructor, such as imap?

Question

This question is a refinement of my earlier one: How do I write a TypeScript declaration file for an external commonjs module that has constructor?

I'm trying to write a declaration file for the imap module: - imap on npm - node-imap What should this file look like?

After not finding a satisfactory answer to my original question above, I realize there are some competing features of the language:

• any export or import makes a module an external module
• there appears to be no way to export multiple entities from an external module that has a (module-level) constructor so shared entities must be outside the module (ambient).
  See my previous question (above).
• there is no way to import external modules into a declaration file outside of the declared module
  The following pattern is disallowed: import fs = require('fs'); declare module 'A' {}

Here is what I have for the declaration file so far:

interface IIMAPAccount {
    user:           string;
    password:       string;
    host:           string;
    port:           number;
    tls?:           boolean;
}

interface IEMail {
    mail:            any;
}

interface ICriteria {
    // The following message flags are valid types that do not have arguments:
    ALL:            void;    // All messages.
    ANSWERED:       void;    // Messages with the Answered flag set.
    DELETED:        void;    // Messages with the Deleted flag set.
    DRAFT:          void;    // Messages with the Draft flag set.
    FLAGGED:        void;    // Messages with the Flagged flag set.
    NEW:            void;    // Messages that have the Recent flag set but not the Seen flag.
    SEEN:           void;    // Messages that have the Seen flag set.
    RECENT:         void;    // Messages that have the Recent flag set.
    OLD:            void;    // Messages that do not have the Recent flag set. This is functionally equivalent to "!RECENT" (as opposed to "!NEW").
    UNANSWERED:     void;    // Messages that do not have the Answered flag set.
    UNDELETED:      void;    // Messages that do not have the Deleted flag set.
    UNDRAFT:        void;    // Messages that do not have the Draft flag set.
    UNFLAGGED:      void;    // Messages that do not have the Flagged flag set.
    UNSEEN:         void;    // Messages that do not have the Seen flag set.

    // The following are valid types that require string value(s):

    BCC:            any;    // Messages that contain the specified string in the BCC field.
    CC:             any;    // Messages that contain the specified string in the CC field.
    FROM:           any;    // Messages that contain the specified string in the FROM field.
    SUBJECT:        any;    // Messages that contain the specified string in the SUBJECT field.
    TO:             any;    // Messages that contain the specified string in the TO field.
    BODY:           any;    // Messages that contain the specified string in the message body.
    TEXT:           any;    // Messages that contain the specified string in the header OR the message body.
    KEYWORD:        any;    // Messages with the specified keyword set.
    HEADER:         any;    // Requires two string values, with the first being the header name and the second being the value to search for. If this second string is empty, all messages that contain the given header name will be returned.
    // The following are valid types that require a string parseable by JavaScripts Date object OR a Date instance:
    BEFORE:         any;    // Messages whose internal date (disregarding time and timezone) is earlier than the specified date.
    ON:             any;    // Messages whose internal date (disregarding time and timezone) is within the specified date.
    SINCE:          any;    // Messages whose internal date (disregarding time and timezone) is within or later than the specified date.
    SENTBEFORE:     any;    // Messages whose Date header (disregarding time and timezone) is earlier than the specified date.
    SENTON:         any;    // Messages whose Date header (disregarding time and timezone) is within the specified date.
    SENTSINCE:      any;    // Messages whose Date header (disregarding time and timezone) is within or later than the specified date.
    //The following are valid types that require one Integer value:
    LARGER:         number;    // Messages with a size larger than the specified number of bytes.
    SMALLER:        number;    // Messages with a size smaller than the specified number of bytes.
    // The following are valid criterion that require one or more Integer values:
    UID:            any;    // Messages with UIDs corresponding to the specified UID set. Ranges are permitted (e.g. '2504:2507' or '*' or '2504:*').
}

interface IFetchOptions {
    markSeen:       boolean;  // Mark message(s) as read when fetched. Default: false
    struct:         boolean;  // Fetch the message structure. Default: false
    envelope:       boolean;  // Fetch the message envelope. Default: false
    size:           boolean;  // Fetch the RFC822 size. Default: false
    modifiers:      any;      // Fetch modifiers defined by IMAP extensions. Default: (none)
    bodies:         any;      // A string or Array of strings containing the body part section to fetch. Default: (none) Example sections:
}

declare module "imap" {
    import events                           = require('events');
    import EventEmitter                     = events.EventEmitter;

    interface IMAPFetch extends EventEmitter {
    }

    class IMAP extends EventEmitter {
        constructor(account : IIMAPAccount);
        connect();
        openBox(name : string, flag : boolean, cb : (err : Error, box) => void);
        search(criteria : ICriteria, cb : (error : Error, uids : string[]) => void);
        fetch(source : any, object : IFetchOptions) : IMAPFetch;
    }

    var out: typeof IMAP;
    export = out;
}

Ideally, all of the interfaces will be defined inside of module "imap", so there is no pollution of the global scope.

Answer 1

Ideally, all of the interfaces will be defined inside of module "imap", so there is no pollution of the global scope

Instead of:

interface IFetchOptions {
    markSeen:       boolean;
    // so on
}
interface ICriteria {        
    ALL:            void;
}

Do the following

module imap {
    interface IFetchOptions {
        markSeen:       boolean;
        // so on
    }
    interface ICriteria {        
        ALL:            void;
    }
}

And you only pollute the global scope with imap. Which is a non-initializaed module and can only be used for Type Information.

Reference : look at ghost modules : http://definitelytyped.org/guides/best-practices.html

Answer 2

After continuing to investigate this problem, I have written the definition file, but still haven't found a way to put all of the interfaces inside of the module, to avoid pollution of the global scope.

I submitted the definition file in a pull request to DefinitelyTyped, and you can view it here: https://github.com/psnider/DefinitelyTyped/commit/460bb6d63e349918b20e49d7a62f3d2a7c2aea0a

---

EDITED

Thanks, basarat, for pointing me in the right direction, although I was unable to sew it together until I found a few more missing pieces.

I reviewed other answers and definition files and found a method that appears to work, and have updated my pull request: https://github.com/borisyankov/DefinitelyTyped/pull/3324

I used this pattern in imap.d.ts:

declare module IMAP {
    export interface Config {}
    export class Connection {
        constructor(config : Config);
    }
}
declare module "imap" {
    var out: IMAP.Connection;
    export = out;
}

Where IMAP is a non-initializaed module, as basarat suggested, and it makes the interfaces accessible within the IMAP namespace.

Then in the code that uses the imap module, example.ts:

/// <reference path='imap.d.ts' />   // brings module IMAP into scope
import Imap = require('imap');       // gets the connection class
var conn = new Imap({/* omitted for brevity*/});  // creates an imap connection