major changes

kudos to @xmodar

Author: howion

.editorconfig

@@ -0,0 +1,9 @@
+root = true
+
+[*]
+indent_style = space
+indent_size = 4
+end_of_line = crlf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true

.gitignore

@@ -1,3 +1,7 @@
+# IGNORE LOCK FILES
+package-lock.json
+yarn.lock
+
 # IGNORE NODE FOLDERS
 node_modules/
 

.npmignore

@@ -0,0 +1,5 @@
+.editorconfig
+.gitattributes
+.gitignore
+.prettier*
+gulpfile.js

.npmrc

@@ -0,0 +1 @@
+package-lock=false

.prettierignore

@@ -0,0 +1,3 @@
+dist/
+node_modules/
+*.md

.prettierrc

@@ -0,0 +1,18 @@
+{
+    "arrowParens": "always",
+    "bracketSameLine": false,
+    "bracketSpacing": true,
+    "cursorOffset": -1,
+    "embeddedLanguageFormatting": "auto",
+    "endOfLine": "crlf",
+    "insertPragma": false,
+    "printWidth": 120,
+    "proseWrap": "preserve",
+    "quoteProps": "consistent",
+    "requirePragma": false,
+    "semi": false,
+    "singleQuote": true,
+    "tabWidth": 4,
+    "trailingComma": "none",
+    "useTabs": false
+}

README.md

@@ -1,47 +1,70 @@
 # lambert-w-function
 
-Javascript implementation of [**Lambert W function**](https://en.wikipedia.org/wiki/Lambert_W_function) aka **Omega Function**.
+![GitHub last commit](https://img.shields.io/github/last-commit/howion/lambert-w-function) ![npm](https://img.shields.io/npm/dt/lambert-w-function?label=npm%20downloads) ![npm](https://img.shields.io/npm/dw/lambert-w-function?label=npm%20downloads%20weekly) ![NPM](https://img.shields.io/npm/l/lambert-w-function) ![Libraries.io dependency status for latest release](https://img.shields.io/librariesio/release/npm/lambert-w-function)
 
-### Notes
-* This library **does not** support **complex** numbers.
-* This implementation **does not** support inputs **smaller** than **Euler's number** ( 2.718... ). [See on Desmos.](https://www.desmos.com/calculator/5kf9gammls)
+This is a JavaScript implementation for the [**Lambert W Function**](https://en.wikipedia.org/wiki/Lambert_W_function) which is also known as **Omega Function** on the principal branch `W_0`.
+
+Please note that this library **does not** support **complex** numbers and only supports the **principal branch**.
 
 ## Installation
 
-From [**NPM**](https://www.npmjs.com/package/lambert-w-function)
+From [**npm**](https://www.npmjs.com/package/lambert-w-function) via npm
 
-```bash
-$ npm install lambert-w-function
+```console
+npm install lambert-w-function
 ```
 
-## Usage
-
-#### Import
+or via yarn
 
-```js
-const W = require('lambert-w-function') // COMMON JS
+```console
+yarn add lambert-w-function
 ```
 
-```js
-import W from 'lambert-w-function' // ES6 OR TYPESCRIPT
-```
+## Import
 
-#### Use
+For CommonJS
 
 ```js
-W($x: number, $iterations: number = 10): number
+const {
+    lambertW0, // same as lambertW0_IaconoBoyd
+    lambertW0_IaconoBoyd,
+    lambertW0Log, // same as lambertW0Log_xmodar
+    lambertW0Log_xmodar,
+    lambertW0_SimpleIteration_LT_E,
+    lambertW0_SimpleIteration_GT_E,
+    W0_LIMIT_POINT
+} = require('lambert-w-function')
 ```
 
-## Method
+otherwise
 
-```
-W(x) = ln(x) - ln(ln(x) - ln(ln(x) - ...))
+```js
+import { ... } from 'lambert-w-function'
 ```
 
-from
+## Usage / Documentation
 
-![](https://wikimedia.org/api/rest_v1/media/math/render/svg/442ef6693fdf0589b4ec212a6f1e73d5ecbd610e)
+```js
+// A good approximation with a maximum relative error 5E-3
+// Same as lambertW0Log(x) if is_x_log set to true.
+// -
+// See: https://gist.github.com/xmodar/baa392fc2bec447d10c2c20bbdcaf687
+// See: https://link.springer.com/content/pdf/10.1007/s10444-017-9530-3.pdf
+lambertW0(x: number, is_x_log = false): number
+
+// Computes W(y) where y of the form log(x)
+// -
+// See: https://gist.github.com/xmodar/baa392fc2bec447d10c2c20bbdcaf687
+lambertW0Log(logX: number): number
+
+// Approximates W(X) with a straightforward algoritm for x <= E (respectively
+// x > E) but it is highly recommended to use lambertW0 instead.
+// -
+// See: https://doi.org/10.1145%2F258726.258783
+lambertW0_SimpleIteration_LT_E(x: number, iterations = 10): number
+lambertW0_SimpleIteration_GT_E(x: number, iterations = 10): number
+```
 
 ## License
 
-[**MIT**](https://github.com/howion/lambert-w-function/blob/master/LICENSE)
+This project is licensed under the [**MIT**](https://github.com/howion/lambert-w-function/blob/master/LICENSE) license so that you can just do whatever you want with it.

dist/definitions/index.d.ts

@@ -1,8 +1,46 @@
+declare const W0_LIMIT_POINT: number;
 /**
- * Computes Y from X=Y*exp(Y)
+ * Lambert W Function for the principal branch.
  *
- * @param $x
- * @param $iterations - Precision
+ * @link https://gist.github.com/xmodar/baa392fc2bec447d10c2c20bbdcaf687
+ * @link https://link.springer.com/content/pdf/10.1007/s10444-017-9530-3.pdf
+ *
+ * @author xmodar
+ *
+ * @param x
+ * @param is_x_log - if true, x is of the form log(x)
+ * @returns W_0(x)
+ */
+declare function lambertW0_IaconoBoyd(x: number, is_x_log?: boolean): number;
+/**
+ * Lambert W Function for log(x) for the principal branch.
+ *
+ * {@link https://gist.github.com/xmodar/baa392fc2bec447d10c2c20bbdcaf687}
+ *
+ * @author xmodar
+ *
+ * @param logX
+ * @returns
+ */
+declare function lambertW0Log_xmodar(logX: number): number;
+/**
+ * Simple Lambert W Function approximation for (x <= Math.E). Note that it won't raise an error if x is greater than E.
+ *
+ * @author howion
+ *
+ * @param x
+ * @param iterations
+ * @returns W(x)
+ */
+declare function lambertW0_SimpleIteration_LT_E(x: number, iterations?: number): number;
+/**
+ * Simple Lambert W Function approximation for (x > Math.E). Note that it won't raise an error if x is less than E.
+ *
+ * @author howion
+ *
+ * @param x
+ * @param iterations
+ * @returns W(x)
  */
-declare function W($x: number, $iterations?: number): number;
-export { W, W as default };
+declare function lambertW0_SimpleIteration_GT_E(x: number, iterations?: number): number;
+export { lambertW0_IaconoBoyd as lambertW0, lambertW0_IaconoBoyd, lambertW0Log_xmodar as lambertW0Log, lambertW0Log_xmodar, lambertW0_SimpleIteration_LT_E, lambertW0_SimpleIteration_GT_E, W0_LIMIT_POINT };

dist/js/index.js

@@ -1,18 +1,66 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-function ln($x) { return Math.log($x); }
-function W($x, $iterations) {
-    if ($iterations === void 0) { $iterations = 10; }
-    if ($x <= Math.E)
-        throw new Error('This library cannot compute the W(x) value of numbers less than Euler\'s number.');
-    if ($iterations < 1)
-        throw new Error('Iterations cannot be smaller than 1.');
-    var $result = ln($x);
+exports.W0_LIMIT_POINT = exports.lambertW0_SimpleIteration_GT_E = exports.lambertW0_SimpleIteration_LT_E = exports.lambertW0Log_xmodar = exports.lambertW0Log = exports.lambertW0_IaconoBoyd = exports.lambertW0 = void 0;
+var E = Math.E, PI = Math.PI, log = Math.log, exp = Math.exp;
+var W0_LIMIT_POINT = -(1 / E);
+exports.W0_LIMIT_POINT = W0_LIMIT_POINT;
+function lambertW0_IaconoBoyd(x, is_x_log) {
+    if (is_x_log === void 0) { is_x_log = false; }
+    if (is_x_log)
+        return lambertW0Log_xmodar(x);
+    if (x >= 0)
+        return lambertW0Log_xmodar(log(x));
+    var xE = x * E;
+    if (isNaN(x) || xE < -1)
+        return NaN;
+    var y = Math.pow((1 + xE), 0.5);
+    var z = log(y + 1);
+    var n = 1 + 1.1495613113577325 * y;
+    var d = 1 + 0.4549574005654461 * z;
+    var w = -1 + 2.036 * log(n / d);
+    w *= log(xE / w) / (1 + w);
+    w *= log(xE / w) / (1 + w);
+    w *= log(xE / w) / (1 + w);
+    return isNaN(w) ? (xE < -0.5 ? -1 : x) : w;
+}
+exports.lambertW0 = lambertW0_IaconoBoyd;
+exports.lambertW0_IaconoBoyd = lambertW0_IaconoBoyd;
+function lambertW0Log_xmodar(logX) {
+    if (isNaN(logX))
+        return NaN;
+    var logXE = +logX + 1;
+    var logY = 0.5 * log1Exp(logXE);
+    var logZ = log(log1Exp(logY));
+    var logN = log1Exp(0.13938040121300527 + logY);
+    var logD = log1Exp(-0.7875514895451805 + logZ);
+    var w = -1 + 2.036 * (logN - logD);
+    w *= (logXE - log(w)) / (1 + w);
+    w *= (logXE - log(w)) / (1 + w);
+    w *= (logXE - log(w)) / (1 + w);
+    return isNaN(w) ? (logXE < 0 ? 0 : Infinity) : w;
+}
+exports.lambertW0Log = lambertW0Log_xmodar;
+exports.lambertW0Log_xmodar = lambertW0Log_xmodar;
+function log1Exp(x) {
+    return x <= 0 ? Math.log1p(Math.exp(x)) : x + log1Exp(-x);
+}
+function lambertW0_SimpleIteration_LT_E(x, iterations) {
+    if (iterations === void 0) { iterations = 10; }
+    var y = 1;
+    do {
+        y = x / exp(y);
+        iterations--;
+    } while (iterations > 0);
+    return y;
+}
+exports.lambertW0_SimpleIteration_LT_E = lambertW0_SimpleIteration_LT_E;
+function lambertW0_SimpleIteration_GT_E(x, iterations) {
+    if (iterations === void 0) { iterations = 10; }
+    var y = 1;
     do {
-        $result = ln($x) - ln($result);
-        $iterations--;
-    } while ($iterations > 0);
-    return $result;
+        y = log(x) - log(y);
+        iterations--;
+    } while (iterations > 0);
+    return y;
 }
-exports.W = W;
-exports.default = W;
+exports.lambertW0_SimpleIteration_GT_E = lambertW0_SimpleIteration_GT_E;

gulpfile.js

@@ -1,60 +1,47 @@
-// CONFIGS
+// Config
 const RELEASE_DIR = './dist'
 const DEFINITIONS_RELEASE_DIR = RELEASE_DIR + '/definitions'
 const JS_RELEASE_DIR = RELEASE_DIR + '/js'
 const DEV_DIR = './src'
 
-// PATTERNS
+// Patterns
 const DEV_DIR_TS = DEV_DIR + '/**/*.ts'
 
-// PACKAGES
+// Packages
 const { task, src, dest, series, watch } = require('gulp'),
-       plumber = require('gulp-plumber'),
-       del     = require('del'),
-       ts      = require('gulp-typescript'),
-       merge2  = require('merge2'),
-       clip    = require('gulp-clip-empty-files')
+    plumber = require('gulp-plumber'),
+    del = require('del'),
+    ts = require('gulp-typescript'),
+    merge2 = require('merge2'),
+    clip = require('gulp-clip-empty-files')
 
-// FOR GENERATING JS FILES
 let tsProjectJs = ts.createProject('tsconfig.json', {
     declaration: false
 })
 
-// FOR GENERATING DEFINITION FILES WITH TSDOC
 let tsProjectDefinition = ts.createProject('tsconfig.json', {
     declaration: true,
     removeComments: false
 })
 
-// FRESH START
-task('clean', function() {
-    return del([ RELEASE_DIR ], { force: true })
+task('clean', function () {
+    return del([RELEASE_DIR], { force: true })
 })
 
-// COMPILE SCRIPTS
-task('scripts', function() {
-    // GENERATE RESOURCE
+task('scripts', function () {
     let tsResource = src(DEV_DIR_TS).pipe(plumber())
 
-    // MERGE DEFINITION AND JS FILES
     return merge2([
-        // DEFINITIONS
-        tsResource.pipe(tsProjectDefinition())
-                  .dts
-                  .pipe(clip())
-                  .pipe(dest(DEFINITIONS_RELEASE_DIR)),
+        // DEFS
+        tsResource.pipe(tsProjectDefinition()).dts.pipe(clip()).pipe(dest(DEFINITIONS_RELEASE_DIR)),
         // JS
-        tsResource.pipe(tsProjectJs())
-                  .js
-                  .pipe(clip())
-                  .pipe(dest(JS_RELEASE_DIR))
+        tsResource.pipe(tsProjectJs()).js.pipe(clip()).pipe(dest(JS_RELEASE_DIR))
     ])
 })
 
-// WATCH CHANGES
-task('watch', function() {
-    return watch(DEV_DIR_TS, series([ 'scripts' ]))
+task('watch', function () {
+    return watch(DEV_DIR_TS, series(['scripts']))
 })
 
-// DEFAULT TASK
-task('default', series([ 'scripts', 'watch' ]))
+task('build', series(['clean', 'scripts']))
+task('default', series(['clean', 'scripts', 'watch']))