JS - Maximum Tension

Maximum Tension™ . Teoman Deniz . maximum-tension.com

License: MIT . Created 2013/11/04

JS is a small utility framework that bundles the things you reach for on every project - type checks, cloning, iteration, string templating, DOM helpers, AJAX and storage - behind a compact, uppercase API. It has no build step and no dependencies: drop a file in and use the globals.

It ships as three environment-specific builds that share the same core naming, so code reads the same whether it runs in a modern browser, in legacy Internet Explorer, or under the Windows Script Host.

Build	File	Environment	Language level	AJAX style
Modern	JS.js	Modern browsers	ES6+ (const/let, arrow fns, Promise, async)	Asynchronous (Promise), XMLHttpRequest
Legacy	IE.js	Internet Explorer / old browsers	ES3/ES5 (var, function expressions)	Synchronous, ActiveXObject -> XMLHttpRequest fallback
Shell	WSCRIPT.js	Windows Script Host (cscript/wscript)	ES3/ES5 (var, function expressions)	Synchronous, ActiveXObject, normalized {STATUS, DATA}

Each build defines its API on plain globals - JS, and depending on the build some of WINDOW, DOM, AJAX, WS, LOCAL_STORAGE.

---

Which build should I use?

• JS.js - the default for anything running in an up-to-date browser. AJAX is promise-based, so you await it.
• IE.js - same surface as JS.js, but written to run on Internet Explorer and other old engines. It prefers ActiveXObject and falls back to XMLHttpRequest, and its AJAX is synchronous (no promises).
• WSCRIPT.js - for automation scripts run from the command line under the Windows Script Host. No browser exists here, so it drops every DOM/window helper and instead adds console I/O, file I/O and native message boxes. See WSCRIPT.md for its full API reference.

You load exactly one build per program; they are not meant to be combined.

You can also find Mini versions of these frameworks here.

---

Getting started

Browser (JS.js or IE.js)

<!--[if IE]>
 <script type="text/javascript" src="IE.js"></script>
<![endif]-->
<!--[if !IE]>-->
 <script type="text/javascript" src="JS.js"></script>
<!--<![endif]-->
<script>
DOM.START(
	function()
	{
		WINDOW.TITLE("Ready");
		var BOX = DOM.GET.ID("app");
		DOM.CLASS.ADD(BOX, "loaded");
	}
);
</script>

IE.js is a drop-in replacement - swap the src and the same code runs on old engines, with AJAX behaving synchronously instead of returning a promise.

Windows Script Host (WSCRIPT.js)

cscript //nologo yourscript.js

// yourscript.js
JS.ECHO("Building...\n");
var	RES = AJAX.GET("https://api.example.com/status");

if (RES.STATUS === 200)
	JS.INFO("Up: " + RES.DATA.state, "Status");
else
	JS.ERROR("Down (" + RES.STATUS + ")", "Status");

---

Namespace coverage

Not every namespace exists in every build - the browser-only ones are absent from the shell build by design.

Namespace	Purpose	JS.js	IE.js	WSCRIPT.js
JS (core utils)	Type checks, clone, merge, iterate, template	OK	OK	OK
JS (I/O + dialogs)	Console/file I/O, message boxes	-	-	OK
WINDOW	Title, favicon, popups, URL/navigation	OK	OK	-
DOM	Element create/query/class/attribute helpers	OK	OK	-
AJAX	HTTP GET/POST/DATA	OK (async)	OK (sync)	OK (sync)
WS	WebSocket helpers	OK	OK	-
LOCAL_STORAGE	Typed localStorage wrapper	OK	OK	-

---

The shared core (JS.*)

These utilities behave the same across all three builds (with minor, environment-driven adaptations noted below):

Function	Description
JS.IS_NULL(v)	true if v is null/undefined.
JS.IS_EMPTY(v)	true if v is empty for its type (null, 0, "", [], {}).
JS.IS_ARRAY(v)	true if v is an array.
JS.IS_OBJECT(v)	true if v is a non-null object.
JS.CLONE(src)	Shallow copy of an array/object; other types returned as-is.
JS.MERGE(target, source)	In-place merge: arrays concat, objects extend.
JS.ITERATE(obj, fn)	Runs fn(value, key|index) over each entry.
JS.ASYNC_ITERATE(obj, fn)	Async version of ITERATE. Browser builds only.
JS.TEMPLATE(str, data)	Interpolates ${dotted.path} placeholders from data.

Environment adaptations

• In JS.js / IE.js, IS_EMPTY and CLONE also understand DOM Nodes. The WSCRIPT.js build drops those branches - there is no DOM.
• JS.ASYNC_ITERATE is not in WSCRIPT.js: WSH JScript has no async/await, so only the synchronous JS.ITERATE is provided.

---

Browser builds (JS.js / IE.js)

Beyond the shared core, both browser builds add:

• WINDOW - TITLE, FAVICON, POPUP, REFRESH, CLOSE, and URL.{GO, NEW, GET, SET} for page/navigation control.
• DOM - element helpers: START (DOM-ready), CREATE.{ELEMENT, STRING}, REMOVE, REPLACE, CLASS.{ADD, CHECK, REMOVE}, ATTRIBUTE.{SET, GET, DELETE}, a GET.* query family (ID, CLASS, ELEMENTS/NAME, ALL, ATTRIBUTE, CHILDS, PARENT, ROOMMATES) and LOAD_SVGS for inlining <svg src="...">.
• WS - WebSocket helpers: OPEN, WAIT, CHECK, plus OPENED/CLOSED state constants.
• LOCAL_STORAGE - a typed localStorage wrapper (SET, GET, REMOVE, CHECK) that preserves the original value type on read-back.

The essential difference between the two is the runtime target:

• JS.js assumes a modern engine and uses promises for AJAX.
• IE.js avoids modern syntax, prefers ActiveXObject with an XMLHttpRequest fallback, and performs AJAX synchronously. Its AJAX.DATA additionally understands Blob, FormData and File payloads.

---

Shell build (WSCRIPT.js)

The Windows Script Host build swaps the browser layer for automation essentials. Full reference: WSCRIPT.md. Shortly:

• Console I/O - JS.ECHO, JS.INPUT.
• File I/O (Scripting.FileSystemObject) - JS.READ, JS.WRITE, JS.JSON.READ, JS.JSON.WRITE, and JS.INCLUDE (load + run a script in the global scope).
• Message boxes (WScript.Shell.Popup) - JS.LOG, JS.WARNING, JS.INFO, JS.ERROR.
• AJAX - synchronous GET, POST, DATA, all returning the normalized {STATUS, DATA} shape described below.

---

AJAX conventions

Heads-up: the three builds do not currently share a single AJAX return shape. Only WSCRIPT.js uses the normalized {STATUS, DATA} contract; the browser builds keep their original shapes. The differences are spelled out here so nothing surprises you.

WSCRIPT.js - normalized

Every request resolves to:

{STATUS: <number>, DATA: <object|string>}

• STATUS - the HTTP status code, or 0 when no HTTP response was received (transport failure / no ActiveX).
• DATA - the parsed JSON body when valid JSON, the raw text otherwise, or "" when empty/failed.

var	RES = AJAX.POST("https://api.example.com/login", {user: "ada"});

// {STATUS: 200, DATA: {token: "..."}}

JS.js - asynchronous (promises)

Call	Resolves to
AJAX.GET(url)	Promise<string | undefined>
AJAX.POST(url, body)	Promise<object | string> - parsed body with STATUS: 0 on success, or {STATUS, MESSAGE} on error
AJAX.DATA(url, data)	Promise<string>; rejects with {STATUS, MESSAGE} on error. Accepts JSON, FormData or Blob.

var	TEXT = await AJAX.GET("/data.json");

IE.js - synchronous

Call	Returns
AJAX.GET(url)	string | undefined
AJAX.POST(url, data)	parsed body with STATUS: 0 on success, or {STATUS, MESSAGE} on error
AJAX.DATA(url, data)	string on success, or {AJAX_STATUS, AJAX_MESSAGE} on error. Accepts JSON, FormData, Blob or File.

If you want one contract everywhere, the {STATUS, DATA} shape from WSCRIPT.js is the cleanest candidate to port back into the browser builds - ask and it can be unified.

---

Coding conventions

The framework follows a consistent house style; contributions should match it:

• Uppercase identifiers for the public API and local variables (JS.IS_NULL, VALUE, TARGET).
• Tabs for indentation.
• Parenthesized returns - return (VALUE);.
• JSDoc on every public function (@function / @param / @returns).

---

Notes & caveats

• Synchronous AJAX blocks. IE.js and WSCRIPT.js issue blocking requests; that is expected for shell scripts but will freeze a browser UI. Prefer JS.js where responsiveness matters.
• JSON under WSH. Classic JScript has no native JSON object. WSCRIPT.js uses JSON.parse/JSON.stringify, so run under an engine that provides them or include a JSON polyfill.
• IE.js AJAX.DATA + File. Reading a File uses a busy-wait with a 10-second cap to stay synchronous - usable, but not free.

---

License

MIT © Teoman Deniz - maximum-tension.com