Newsworthy Presidential Mistakes

    jira-miner
    TypeScript icon, indicating that this package has built-in type declarations

    3.5.0 • Public • Published

    JIRA Miner CI Coverage Status

    A tool to gather data from JIRA and query them locally for better speed and more flexible query language than jql. The tool stores entries available in JIRA locally in Loki.js database in a file. This means the tool has no dependency but Node.js.

    Usage

    The tool is intended to act both as command line tool or a library in other projects. In order to be able to effectively query something, you need to populate the database first. Afterwards, you can query content of the database pretty easily.

    You can install the tool by running

    npm install -g jira-miner
    

    Command line usage follows next, make sure you consult jira-miner help if you need further information. You can also run the tool setting DEBUG=1 environment variable, which will provide bunyan log traces useful for debugging.

    Connecting to JIRA instance

    You need to point jira-miner to a JIRA instance you want to use as data source. You might need to provide your credentials as well in order to access restricted data. WARNING: Note that credentials are stored as plain text in your $HOME folder.

    jira-miner target [-t <id>] <jiraUri> [--user <user>] [--password [password]]
    

    Populate & update local database

    Once, you have targeted a jira, you can populate local database

    jira-miner populate [-t <id>] <jqlQuery>
    

    EXAMPLE: jira-miner populate "project in (AEROGEAR, ARQ)" downloads all issues (including their history) for projects AEROGEAR and ARQ)

    If you rerun the query, it will rewrite all updated items. It might be a good idea to update the database since the last query to limit the amount of fetched data. You can do that via --since argument that accepts a timestamp.

    TIP: For very large queries, you might run out of memory. You can increase memory of node process and reduce GC calls via following:

    npx -n "--max-old-space-size=4096" jira-miner populate
    

    Query the database

    JIRA miner provides an API to query the database. Query must be defined in one of following formats:

    import { HistoryCollection } from 'jira-miner/lib/db/LocalJiraDB'
    import { QueryResult } from 'jira-miner/lib/db/Query'
    import Logger from 'jira-miner/lib/logger'
    
    
    export async function query<T>(collection: HistoryCollection<Issue>, logger: Logger, args?: Record<string, unknown>): Promise<QueryResult<T>> {
      // async is optional here, for your convenience
    }
    
    // this is optional function
    export async function transform(result: QueryResult<T>) {
      // async is optional here, for your convenience
    }

    Supposing that this file, called my-example-query.ts is in current directory, and your TypeScript compiler compiles to dist directory, you call your query via following

    jira-miner query dist/my-example-query.js [--args]
    

    All arguments passed on command line will be available in args object. Example query files is available in src/tests/fixtures

    Debug output

    Simply run any command with --verbose parameter. You can provide it twice (e.g. -vv) to have further level of debug output.

    You can also setup environment variable DEBUG to include jira-miner value to get the equivalent of verbose logging.

    Testing

    Prerequisites:

    npm install -g ava typescript nyc coveralls
    

    Afterwards, you can run tests via following commands:

    npm run test
    

    Code coverage (via nyc tool):

    npm run coverage
    

    Install

    npm i jira-miner

    DownloadsWeekly Downloads

    66

    Version

    3.5.0

    License

    Apache-2.0

    Unpacked Size

    9.02 MB

    Total Files

    122

    Last publish

    Collaborators

    • kpiwko