Merge pull request #340 from macbre/typing/initial

Initial typing for Bot() constructor and a few methods

.github/workflows/nodejs.yml

@@ -12,6 +12,7 @@ jobs:
     runs-on: ubuntu-latest
 
     strategy:
+      fail-fast: false
       matrix:
         node-version:
         - "14.x"
@@ -28,5 +29,9 @@ jobs:
         cache: npm
         node-version: ${{ matrix.node-version }}
 
-    - run: npm ci
-    - run: npm test
+    - name: Install dependencies
+      run: npm ci
+    - name: Run the tests
+      run: npm test
+    - name: Check types definition
+      run: npm run check-dts

.gitignore

@@ -17,3 +17,4 @@ npm-debug.log
 .idea
 
 config.js
+.eslintcache

examples/article.js

@@ -4,13 +4,14 @@
  */
 'use strict';
 
-const Bot = require( '..' ),
-	wikipedia = new Bot( {
-		protocol: 'https',
-		server: 'pl.wikipedia.org',
-		path: '/w',
-		debug: true
-	} );
+const Bot = require( '..' );
+
+const wikipedia = new Bot( {
+	protocol: 'https',
+	server: 'pl.wikipedia.org',
+	path: '/w',
+	debug: true
+} );
 
 wikipedia.getArticleRevisions( 'Tórshavna', ( err, data ) => {
 	if ( err ) {

examples/config.wikipedia.json

@@ -0,0 +1,4 @@
+{
+	"server": "en.wikipedia.org",
+	"path": "/w"
+}

examples/editSandbox.js

@@ -1,21 +1,24 @@
 #!/usr/bin/env node
+// @ts-check
 'use strict';
 
-const Bot = require( '..' ),
-	client = new Bot( {
-		protocol: 'https',
-		server: 'www.mediawiki.org',
-		path: '/w',
-		debug: true
-	} ),
-	// text = 'nodemw test';
-	text = 'nodemw test http://clicky.pk/foo'; // https://github.com/macbre/nodemw/issues/131
+// This example makes an edit tp https://test.wikipedia.org/wiki/Test
+const Bot = require( '..' );
+const client = new Bot( {
+	protocol: 'https',
+	server: 'test.wikipedia.org',
+	path: '/w',
+	debug: true
+} );
+
+const text = 'nodemw test';
 
-client.append( 'Project:Sandbox', '\n\n' + text + ' --~~~~', 'nodemw test edit', function ( err, res ) {
+client.append( 'Test', '\n\n' + text + ' --~~~~', 'nodemw test edit', function ( err, res ) {
 	if ( err ) {
 		client.log( 'Sandbox edit failed: ' + JSON.stringify( err ) );
 	} else {
-		client.log( 'Sandbox edited' );
-		client.log( res );
+		client.log( `Edited "${res.title}" as revision #${res.newrevid} on ${res.newtimestamp}.` );
+
+		// console.log( Object.keys(res).map( key => `${key}: ${typeof res[key]};`).join('\n') );
 	}
 } );

examples/mwVersion.js

@@ -1,28 +1,31 @@
+// @ts-check
 /**
  * Example script getting MW version
  */
 'use strict';
 
-const Bot = require( '..' ),
-	wikia = new Bot( {
-		server: 'wikia.com',
-		path: '',
-		debug: true
-	} ),
-	wikipedia = new Bot( {
-		server: 'pl.wikipedia.org',
-		path: '/w',
-		debug: true
-	} );
+const Bot = require( '..' );
+
+const wikia = new Bot( {
+	server: 'wikia.com',
+	path: '',
+	debug: true
+} );
+
+const wikipedia = new Bot( {
+	server: 'pl.wikipedia.org',
+	path: '/w',
+	debug: true
+} );
 
 /**
  * info:    Wikipedia: MediaWiki 1.27.0-wmf.19 -> 1.27.0
  * info:    Wikia: MediaWiki 1.19.24 -> 1.19.24
  */
-wikia.getMediaWikiVersion( function ( err, version ) {
-	wikia.log( 'Wikia:', version );
+wikia.getMediaWikiVersion( function ( _, version ) {
+	wikia.log( `Wikia: ${version}` );
 } );
 
-wikipedia.getMediaWikiVersion( function ( err, version ) {
-	wikipedia.log( 'Wikipedia:', version );
+wikipedia.getMediaWikiVersion( function ( _, version ) {
+	wikipedia.log( `Wikipedia: ${version}` );
 } );

examples/pagesInCategory.js

@@ -1,3 +1,4 @@
+// @ts-check
 /**
  * Example script getting pages from "Bosons" category on English Wikipedia
  *
@@ -6,18 +7,19 @@
  */
 'use strict';
 
-const Bot = require( '..' ),
-	client = new Bot( {
-		server: 'en.wikipedia.org',
-		path: '/w'
-	} );
+const Bot = require( '..' );
+
+const client = new Bot( {
+	server: 'en.wikipedia.org',
+	path: '/w'
+} );
 
-client.getPagesInCategory( 'Sports_cars', function ( _, pages ) {
+client.getPagesInCategory( 'Sports_cars', ( _, pages ) => {
 	client.log( 'Pages in category: %d', pages.length );
-	client.logData( pages );
+	console.log( '%j', pages );
 
-	pages.forEach( function ( page ) {
-		client.getArticle( page.title, function ( err, content ) {
+	pages.forEach( ( page ) => {
+		client.getArticle( page.title, ( __, content ) => {
 			console.log( '%s: %s', page.title, content.slice( 0, 75 ).replace( /\n/g, ' ' ) );
 		} );
 	} );

examples/siteInfo.js

@@ -1,34 +1,51 @@
+// @ts-check
 /**
  * Example script getting wiki information
  */
 'use strict';
 
-const Bot = require( '..' ),
-	client = new Bot( {
-		server: '8bit.wikia.com',
-		path: '',
-		debug: true
-	} );
+const Bot = require( '..' );
+// const { dumpObjectTypes } = require( '../lib/utils' );
 
-client.getSiteInfo( [ 'general', 'namespaces' ], function ( err, info ) {
-	client.log( 'General:', info.general );
-	client.log( 'Namespaces:', info.namespaces );
+const client = new Bot( {
+	server: '8bit.wikia.com',
+	debug: true
 } );
 
-client.getSiteStats( function ( err, stats ) {
-	client.log( 'Statistics:', stats );
+client.getSiteInfo( [ 'general', 'namespaces', 'dbrepllag' ], function ( _, info ) {
+	// dumpObjectTypes( 'SiteInfo', info );
+	// dumpObjectTypes( 'SiteInfoGeneral', info.general );
+	// dumpObjectTypes( 'SiteInfoNamespaces', info.namespaces );
+	// dumpObjectTypes( 'SiteInfoDBReplLag', info.dbrepllag );
+
+	// console.log( 'General:', info.general );
+	// console.log( 'Namespaces:', info.namespaces );
+
+	// e.g. This site uses PHP v7.3.33 and mysql v8.0.25-15
+	console.log( `This site uses PHP v${info.general.phpversion} and ${info.general.dbtype} v${info.general.dbversion}` );
+} );
+
+client.getSiteStats( function ( _, stats ) {
+	// dumpObjectTypes( 'SiteStatistics', stats );
+
+	// e.g. This wiki has 179 articles with 30886001 users that made 1917 edits.
+	console.log( `This wiki has ${stats.articles} articles with ${stats.users} users that made ${stats.edits} edits.` );
 } );
 
 // Wikia-specific stuff
-client.wikia.getWikiVariables( function ( err, vars ) {
-	client.log( 'Site name:', vars.siteName );
-	client.log( 'Theme:', vars.theme );
+client.wikia.getWikiVariables( function ( _, vars ) {
+	// dumpObjectTypes( 'WikiaWikiVariables', vars );
+
+	// e.g. This wiki has ID 443275 (DB name pl8bit) and is a part of lifestyle vertical.
+	console.log( `This wiki has ID ${vars.id} (DB name ${vars.dbName}) and is a part of ${vars.vertical} vertical.` );
 } );
 
-client.wikia.getUsers( [ 2, 1, 16 ], function ( err, users ) {
-	console.log( users );
+client.wikia.getUsers( [ 2, 1, 16 ], function ( _, users ) {
+	// dumpObjectTypes( 'WikiaUserInfo', users[0] );
+	console.log( 'Users: %j', users );
 } );
 
-client.wikia.getUser( 119245, function ( err, userInfo ) {
-	client.log( 'My Wikia avatar:', userInfo.avatar );
+client.wikia.getUser( 119245, function ( _, userInfo ) {
+	// e.g. Hi, I'm Macbre and I've made 15541 edits
+	console.log( `Hi, I'm ${userInfo.name} and I've made ${userInfo.numberofedits} edits` );
 } );

examples/upload.js

@@ -1,24 +1,29 @@
+// @ts-check
 /**
  * Example script for file uploads
  *
  * @see http://www.mediawiki.org/wiki/API:Upload
  */
 'use strict';
 
-const Bot = require( '..' ),
-	client = new Bot( 'config.js' ),
-	url = 'http://upload.wikimedia.org/wikipedia/en/b/bc/Wiki.png',
-	fileName = 'UploadTest.png',
-	summary = 'Testing upload ąęź...';
+const Bot = require( '..' );
 
-client.logIn( function () {
+const client = new Bot( __dirname + '/config.wikipedia.json' );
+const url = 'http://upload.wikimedia.org/wikipedia/en/b/bc/Wiki.png';
+const fileName = 'UploadTest.png';
+const summary = 'Testing upload ąęź...';
+
+client.logIn( ( _, res ) => {
 	console.log( `Uploading ${url}...` );
+	console.log( res );
 
-	client.uploadByUrl( fileName, url, summary, function () {
+	client.uploadByUrl( fileName, url, summary, ( __, uploadRes ) => {
 		console.log( 'Upload completed!' );
+		console.log( uploadRes );
 
-		client.edit( `File:${fileName}`, 'File description goes here ąęź\n\n[[Category:Foo]]', 'Adding a file description', function () {
+		client.edit( `File:${fileName}`, 'File description goes here ąęź\n\n[[Category:Foo]]', 'Adding a file description', ( ___, editRes ) => {
 			console.log( 'File description edited' );
+			console.log( editRes );
 		} );
 	} );
 } );

examples/whois.js

@@ -1,12 +1,13 @@
+// @ts-check
 /**
  * Example script getting user information on a specific user
  *
  * @see https://www.mediawiki.org/wiki/API:Users
  */
 'use strict';
 
-const Bot = require( '..' ),
-	client = new Bot( 'config.js' );
+const Bot = require( '..' );
+const client = new Bot( __dirname + '/config.wikipedia.json' );
 
 // get current account information
 client.whois( 'Jimbo Wales', function ( err, userData ) {
@@ -15,5 +16,9 @@ client.whois( 'Jimbo Wales', function ( err, userData ) {
 		return;
 	}
 
-	console.log( JSON.stringify( userData, null, '\t' ) );
+	console.log(
+		`${userData.name} made ${userData.editcount} edits since registering on ${userData.registration}.`
+	);
+
+	// console.log( JSON.stringify( userData, null, '\t' ) );
 } );