Swamp Thing

A better Twitter client.

What is this?

It's a Twitter client, like node-twitter or twit, but with some key differences:

• Endpoints are exposed as methods. No more spelunking through Twitter's documentation — just use Intellisense. It's much easier!
• Sensible defaults — e.g. stringify_ids and dnt (privacy setting) default to true, and count defaults to the maximum value
• undefined and null values are omitted from queries, so you don't have to conditionally add parameters like max_id. Just do max_id: null (this is a really dumb gotcha with the Twitter API that has wasted a lot of my time)
• Helper functions like decrement, for subtracting 1 from ID strings

Limitations

• It is unfinished. Only GET requests for now, and a few endpoints are missing

Usage

import { Client, decrement } from 'swamp-thing';

const client = new Client({
	"consumer_key": "A_CONSUMER_KEY",
	"consumer_secret": "A_CONSUMER_SECRET",
	"access_token_key": "AN_ACCESS_TOKEN_KEY",
	"access_token_secret": "AN_ACCESS_TOKEN_SECRET"
});

async function get_all_tweets(screen_name) {
	const tweets = [];
	let max_id = null;

	while (true) {
		const chunk = await client.get.statuses.user_timeline({
			screen_name,
			max_id
		});

		if (chunk.length === 0) return tweets;

		tweets.push(...chunk);

		const { id_str } = chunk.pop();
		max_id = decrement(id_str);
	}
}

get_all_tweets('rich_harris').then(tweets => {
	console.log('these are bad tweets:', tweets);
});

You can also create iterators for paging through responses:

import { Client } from 'swamp-thing';

const client = new Client(credentials);

async function get_all_tweets(screen_name) {
	const iterator = client.iterator.get.statuses.user_timeline({ screen_name });
	const tweets = [];

	while (true) {
		const { done, value } = await iterator.next();
		if (done) return tweets;
		tweets.push(...value);
	}
}

get_all_tweets('rich_harris').then(tweets => {
	console.log('these are bad tweets:', tweets);
});

Client pools

If you need to access large amounts of data from the Twitter API, you are likely to hit rate limits. You can circumvent these limits by pooling clients and rotating through them. Swamp Thing automates this process.

import { Pool, decrement } from 'swamp-thing';

const pool = new Pool([
	{
		"consumer_key": "A_CONSUMER_KEY",
		"consumer_secret": "A_CONSUMER_SECRET",
		"access_token_key": "AN_ACCESS_TOKEN_KEY",
		"access_token_secret": "AN_ACCESS_TOKEN_SECRET"
	},
	{
		"consumer_key": "A_CONSUMER_KEY",
		"consumer_secret": "A_CONSUMER_SECRET",
		"access_token_key": "AN_ACCESS_TOKEN_KEY",
		"access_token_secret": "AN_ACCESS_TOKEN_SECRET"
	},
	{
		"consumer_key": "A_CONSUMER_KEY",
		"consumer_secret": "A_CONSUMER_SECRET",
		"access_token_key": "AN_ACCESS_TOKEN_KEY",
		"access_token_secret": "AN_ACCESS_TOKEN_SECRET"
	},
	// ...
]);

After the pool has been created, it has the same API as a regular client.

Why the name?

Because Twitter is a fetid swamp.

License

LIL