naive-gh-events v1.1.0

naive-gh-events

Render event objects from the GitHub API to natural English, in plaintext or markdown. TypeScript definitions are included. Check out a demo here.

Example output:

Markdown:

timfitzzz started watching repository mohebifar/react-use-context-selector

pgillan145 created repository pgillan145/AudioPulse

kii-chan-reloaded created wiki page Pain in kii-chan-reloaded/GeneticChickengineering

kii-chan-reloaded edited 2 wiki pages in kii-chan-reloaded/GeneticChickengineering

• Home
• Settings

plaintext:

timfitzzz started watching repository mohebifar/react-use-context-selector 
pgillan145 created repository pgillan145/AudioPulse 
kii-chan-reloaded created wiki page Pain in kii-chan-reloaded/GeneticChickengineering 
kii-chan-reloaded edited 2 wiki pages in kii-chan-reloaded/GeneticChickengineering 
  Home (https://github.com/kii-chan-reloaded/GeneticChickengineering/wiki/Home)
  Settings (https://github.com/kii-chan-reloaded/GeneticChickengineering/wiki/Settings)

Table of Contents

1. How it Works
2. Supported Event Types
3. How to Install
4. How to Use
5. API

How it Works

naive-gh-events takes a generalized approach to interpreting the contents of GitHub event objects. Each event type can be boiled down into several linguistic abstractions, based on various properties of the event:

• actor: the user (person or bot) whose action generates the event
• verb: expresses the action taken
• result: in general terms, the result of the action
• subject: the product(s) of the action
• target: what the action is taken upon
• parent: the context within which the action occurs

By generating event-specific language outputs, each of these can be manipulated sensitively to provide natural language summaries for single events, as well as to group events in a way that makes sense.

In addition, naive-gh-events' markdown output (default) contains URIs, making it quite easy to use this library to create a custom GitHub event tracking solution using only Markdown rendering.

In sum, this implementation provides natural language and event collation functionality already used to generate social feeds on GitHub.com, but which are not provided by existing official or semi-official GitHub API libraries.

Supported Event Types

Supported event types and subtypes (see note on untested or missing types):

How to install

With NPM:

> npm install naive-gh-events

With Yarn:

> yarn add naive-gh-events

How to use

First, import the module in your TypeScript or JavaScript file:

EJS

import { renderEvents } from 'naive-gh-events'

CJS

const { renderEvents } = require('naive-gh-events')

Now you can use renderEvents to generate human-readable English from any* Github API event:

import axios from 'axios'

axios.request('https://api.github.com/events').then(data => {

  let renderedEventCollectionSets = data.data

  renderedEventCollectionSets.map(renderedEventCollectionSet => {
    
    console.log(renderedEventCollectionSet.startDate) 
    // startDate: falls on or before first event date

    console.log(renderedEventCollectionSet.endDate)
    // endDate: falls on or after final event date

    console.log(renderedEventCollectionSet.renderedEventCollections.join(""))
    // renderedEventCollections is an array of strings, each containing a summary of one or more events, and possibly subsequent lines of text containing further contents.

  })

})

API

renderEvents(events: GHEvents[], options: NaiveOptions): RenderedEventCollectionSet[]

renderEvents accepts two arguments:

• events: an array of GitHub events
• options: a NaiveConfig object containing configuration options that affect rendering output

And it returns an array of RenderedEventCollectionSet objects:

These string sets are designed to be joined without further manipulation, rendering complete sets of events over a specific range of time. They are nonetheless returned as an array of strings to allow further processing without losing knowledge of which lines of text share closer relationship.

NaiveConfig: { [key: string]: value }

You can provide the following options to renderEvents to control the resulting output. You can demo the result of changing these settings on the naive-gh-events demo here.

Outstanding Type Definitions

It turns out that GitHub's API defines some event types that either are never or rarely publicly displayed or no longer used (SponsorshipEvent). Pending further work to define and test event mappings for these types, they are not supported.

Additionally, several types of GitHub events have two or more subtypes. While mappings are often similar for different subtypes, I have not yet seen several of them while scraping the API. As such, these are awaiting further testing for full support.