Closes #51 : Added index.d.ts + documentation for javascript and type…

…script (#59)

Co-authored-by: Lachlan Heywood <lachieh@users.noreply.github.com>

README.md

@@ -49,17 +49,17 @@ It acts in the same way as the original cowsay, so consult `cowsay(1)` or run `c
 ## Usage as a module
 
 cowsay can be used as any other npm dependency
+```js
+var cowsay = require("cowsay");
 
-    var cowsay = require("cowsay");
-
-    console.log(cowsay.say({
-    	text : "I'm a moooodule",
-    	e : "oO",
-    	T : "U "
-    }));
-
-    // or cowsay.think()
+console.log(cowsay.say({
+    text : "I'm a moooodule",
+    e : "oO",
+    T : "U "
+}));
 
+// or cowsay.think()
+```
 ````
  _________________
 ( I'm a moooodule )
@@ -71,6 +71,57 @@ cowsay can be used as any other npm dependency
                 ||     ||
 ````
 
+getting a list of cow names:
+```js
+function get_cows(error, cow_names) {
+    if (error) {
+        console.log(error)
+    }
+    else if (cow_names) {
+        console.log(`Number of cows available: ${cow_names.length}`);
+    }
+}
+
+cowsay.list(get_cows);
+```
+
+#### Typescript examples:
+```ts
+import * as cowsay from "cowsay"
+
+let output: string = cowsay.say({ text: 'Hello from typescript!' });
+
+console.log(output);
+```
+
+getting a list of cow names:
+```ts
+function get_cows(error: NodeJS.ErrnoException, cow_names: Array<string>): void {
+    if (error) {
+        console.log(`Error getting cow names: ${error.message}`)
+    }
+    else if (cow_names) {
+        console.log(`Number of cows available: ${cow_names.length}`);
+    }
+}
+
+cowsay.list(get_cows);
+```
+
+importing the `IOptions` interface directly:
+```ts
+import { IOptions } from "cowsay" // optional
+
+let opts: IOptions = {
+    text: "Hello from TypeScript!",
+    e: '^^',
+    r: true,
+};
+
+console.log(cowsay.say(opts));
+```
+
+
 ## Pipe from standard input
 
     echo please repeat | cowsay

index.d.ts

@@ -0,0 +1,162 @@
+/**
+ * @property text : text
+ * 
+ * @Cow
+ * @property f : cow name
+ * @property r : random selection
+ * 
+ * @Face
+ * @property T : Tongue
+ * @property e : eyes
+ * 
+ * @Modes
+ * @property b : borg 
+ * @property d : dead
+ * @property g : greedy
+ * @property p : paranoia
+ * @property s : stoned
+ * @property t : tired
+ * @property w : wired
+ * @property y : youthful
+ */
+export interface IOptions {
+    text: string,
+    // cow
+    f?: string, // cow name
+    r?: boolean, // random mode
+    // face
+    e?: string, // eyes
+    T?: string, // tongue
+    // modes
+    b?: boolean, // borg 
+    d?: boolean, // dead
+    g?: boolean, // greedy
+    p?: boolean, // paranoia
+    s?: boolean, // stoned
+    t?: boolean, // tired
+    w?: boolean, // wired
+    y?: boolean, // youthful
+}
+
+type callback_type = (error: NodeJS.ErrnoException, cow_names: string[]) => void;
+
+/**
+ * @param callback
+ * @returns a list of cow names from the cows folder without the .cow extension.
+ * @example
+ * ```
+ * function get_cows(error: NodeJS.ErrnoException, cow_names: Array<string>): void {
+ *    if (error) {
+ *        console.log(`Error getting cow names: ${error.message}`);
+ *    }
+ *    else if (cow_names) {
+ *        console.log(`Number of cows available: ${cow_names.length}`);
+ *    }
+ *  }
+ * 
+ * cowsay.list(get_cows);
+ * ```
+ */
+export function list(callback: callback_type): Promise<string[]>;
+
+/**
+ * @param options
+ * ## Face :
+ * Either choose a mode (set the value as true) **_or_**
+ * set your own defined eyes and tongue to `e` and `T`.
+ * - ### `e` : eyes
+ * - ### `T` : tongue
+ * 
+ * ## Cow :
+ * Either specify a cow name (e.g. "fox") **_or_**
+ * set the value of `r` to true which selects a random cow.
+ * - ### `r` : random selection
+ * - ### `f` : cow name - from `cows` folder
+ * 
+ * ## Modes :
+ * Modes are just ready-to-use faces, here's their list:
+ * - #### `b` : borg
+ * - #### `d` : dead      
+ * - #### `g` : greedy
+ * - #### `p` : paranoia
+ * - #### `s` : stoned
+ * - #### `t` : tired
+ * - #### `w` : wired
+ * - #### `y` : youthful
+ * 
+ * @example
+ * ```
+ * // custom cow and face
+ * cowsay.say({
+ *     text: 'Hello world!',
+ *     e: '^^', // eyes
+ *     T: 'U ', // tongue
+ *     f: 'USA' // name of the cow from `cows` folder
+ * })
+ * 
+ * // using a random cow
+ * cowsay.say({
+ *     text: 'Hello world!',
+ *     e: 'xx', // eyes
+ *     r: true, // random mode - use a random cow.
+ * })
+ * 
+ * // using a mode
+ * cowsay.say({
+ *     text: 'Hello world!',
+ *     y: true, // using y mode - youthful mode
+ * })
+ * ```
+ */
+export function say(options: IOptions): string;
+
+/**
+ * @param options
+ * ## Face :
+ * Either choose a mode (set the value as true) **_or_**
+ * set your own defined eyes and tongue to `e` and `T`.
+ * - ### `e` : eyes
+ * - ### `T` : tongue
+ * 
+ * ## Cow :
+ * Either specify a cow name (e.g. "fox") **_or_**
+ * set the value of `r` to true which selects a random cow.
+ * - ### `r` : random selection
+ * - ### `f` : cow name - from `cows` folder
+ * 
+ * ## Modes :
+ * Modes are just ready-to-use faces, here's their list:
+ * - #### `b` : borg
+ * - #### `d` : dead      
+ * - #### `g` : greedy
+ * - #### `p` : paranoia
+ * - #### `s` : stoned
+ * - #### `t` : tired
+ * - #### `w` : youthful
+ * - #### `y` : wired
+ * 
+ * @example
+ * ```
+ * // custom cow and face
+ * cowsay.think({
+ *     text: 'Hello world!',
+ *     e: '^^', // eyes
+ *     T: 'U ', // tongue
+ *     f: 'USA' // name of the cow from `cows` folder
+ * })
+ * 
+ * // using a random cow
+ * cowsay.think({
+ *     text: 'Hello world!',
+ *     e: 'xx', // eyes
+ *     r: true, // random mode - use a random cow.
+ * })
+ * 
+ * // using a mode
+ * cowsay.think({
+ *     text: 'Hello world!',
+ *     y: true, // using y mode - youthful mode
+ * })
+ * ```
+ */
+export function think(options: IOptions): string;

index.js

@@ -2,14 +2,133 @@ var balloon = require("./lib/balloon");
 var cows = require("./lib/cows");
 var faces = require("./lib/faces");
 
+/**
+ * @param options
+ * ## Face :
+ * Either choose a mode (set the value as true) **_or_**
+ * set your own defined eyes and tongue to `e` and `T`.
+ * - ### `e` : eyes
+ * - ### `T` : tongue
+ * 
+ * ## Cow :
+ * Either specify a cow name (e.g. "fox") **_or_**
+ * set the value of `r` to true which selects a random cow.
+ * - ### `r` : random selection
+ * - ### `f` : cow name - from `cows` folder
+ * 
+ * ## Modes :
+ * Modes are just ready-to-use faces, here's their list:
+ * - #### `b` : borg
+ * - #### `d` : dead      
+ * - #### `g` : greedy
+ * - #### `p` : paranoia
+ * - #### `s` : stoned
+ * - #### `t` : tired
+ * - #### `w` : wired
+ * - #### `y` : youthful
+ * 
+ * @example
+ * ```
+ * // custom cow and face
+ * cowsay.say({
+ *     text: 'Hello world!',
+ *     e: '^^', // eyes
+ *     T: 'U ', // tongue
+ *     f: 'USA' // name of the cow from `cows` folder
+ * })
+ * 
+ * // using a random cow
+ * cowsay.say({
+ *     text: 'Hello world!',
+ *     e: 'xx', // eyes
+ *     r: true, // random mode - use a random cow.
+ * })
+ * 
+ * // using a mode
+ * cowsay.say({
+ *     text: 'Hello world!',
+ *     y: true, // using y mode - youthful mode
+ * })
+ * ```
+ * 
+ * @returns {string} compiled cow
+ */
 exports.say = function (options) {
 	return doIt(options, true);
 };
 
+/**
+ * @param options
+ * ## Face :
+ * Either choose a mode (set the value as true) **_or_**
+ * set your own defined eyes and tongue to `e` and `T`.
+ * - ### `e` : eyes
+ * - ### `T` : tongue
+ * 
+ * ## Cow :
+ * Either specify a cow name (e.g. "fox") **_or_**
+ * set the value of `r` to true which selects a random cow.
+ * - ### `r` : random selection
+ * - ### `f` : cow name - from `cows` folder
+ * 
+ * ## Modes :
+ * Modes are just ready-to-use faces, here's their list:
+ * - #### `b` : borg
+ * - #### `d` : dead      
+ * - #### `g` : greedy
+ * - #### `p` : paranoia
+ * - #### `s` : stoned
+ * - #### `t` : tired
+ * - #### `w` : wired
+ * - #### `y` : youthful
+ * 
+ * @example
+ * ```
+ * // custom cow and face
+ * cowsay.think({
+ *     text: 'Hello world!',
+ *     e: '^^', // eyes
+ *     T: 'U ', // tongue
+ *     f: 'USA' // name of the cow from `cows` folder
+ * })
+ * 
+ * // using a random cow
+ * cowsay.think({
+ *     text: 'Hello world!',
+ *     e: 'xx', // eyes
+ *     r: true, // random mode - use a random cow.
+ * })
+ * 
+ * // using a mode
+ * cowsay.think({
+ *     text: 'Hello world!',
+ *     y: true, // using y mode - youthful mode
+ * })
+ * ```
+ * 
+ * @returns {string} compiled cow
+ */
 exports.think = function (options) {
 	return doIt(options, false);
 };
 
+/**
+ * @example
+ * ```
+ * function get_cows(error, cow_names) {
+ *    if (error) {
+ *        console.log(error);
+ *    }
+ *    else if (cow_names) {
+ *        console.log(`Number of cows available: ${cow_names.length}`);
+ *    }
+ *  }
+ * 
+ * cowsay.list(get_cows);
+ * ```
+ * @param callback
+ * @returns {Promise} promise
+ */
 exports.list = cows.list;
 
 function doIt (options, sayAloud) {

package.json

@@ -18,6 +18,7 @@
   },
   "license": "MIT",
   "main": "./index",
+  "types": "./index.d.ts",
   "module": "./build/cowsay.es.js",
   "browser": "./build/cowsay.umd.js",
   "bin": {