squared

setHostname(value)

Use another CORS-enabled server for processing assets.

Arguments:

  • value (string()) – http(s)://hostname(:port)

Usage:

squared.setHostname("https://localhost:8000");

squared.setHostname(); // Reset to window.location (e.g. localhost:3000)
setEndpoint(name, value)

Set alternate pathname for API v1 functions.

Arguments:

  • name (string()) – ASSETS_COPY | ASSETS_ARCHIVE | LOADER_DATA | THREADS_KILL | WEBSOCKET_OBSERVE

  • value (string()) – Absolute path to server GET/POST method

Usage:

squared.setEndpoint("ASSETS_COPY", "/api/v2/assets/copy");
setLocalAddress(...values)

Additional hostnames which are interpreted as localhost. Protocol and port are not required.

Arguments:

  • values (string()) – Same format as URL.hostname

Usage:

squared.setLocalAddress("127.0.0.1", "nodejs-001");

Alternate:

squared.setLocalAddress(new URL("http://0.0.0.0"));
auth(token)

Set JWT authorization token for all requests

Arguments:

  • token (string()) – Three concatenated Base64url-encoded strings separated by dots

Usage:

squared.auth("eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VybmFtZSI6InNxdWFyZWQiLCJwYXNzd29yZCI6Imp3dDEyMyIsImlhdCI6MTY1MjcxNDQwMH0.xqwQ96LsItilsB1dskzJQqXORaZ4mGMu0FeZezo297c");
kill([pid, timeout])

Abort request if not completed in the given amount of time.

Arguments:

  • pid (number()) – (optional) File request self-assigned number (options.pid)

  • timeout (number()) – (optional) Seconds until request expires

Returns:

Promise<number>

Usage:

squared.saveAs("example.zip", { pid: 100 });
squared.kill(100).then(result => {
  if (result > 0) {
    /* KILLED */
  }
});

squared.kill(); // Terminate previous request
squared.kill(0); // By username (auth required)

squared.kill(-1, 10); // Terminate previous request in 10 seconds
squared.kill(NaN, 0.5); // Terminate next request in 500 milliseconds

Alternate:

squared.kill(-1, "10s"); // Terminate previous request in 10 seconds
squared.kill("500ms"); // Terminate next request in 500 milliseconds
broadcast(callback, socketId)

Redirect stdout messages to DevTools console.

Arguments:

  • callback (function()) – See BroadcastMessageCallback

  • socketId (string()) – Unique identifier assigned during server initialization

Returns:

boolean

Usage:

squared.broadcast(result => { console.log(result.value); }, "111-111-111"); // Uses "socketId"
squared.broadcast(result => { console.log(result.value); }, "222-222-222");

squared.copyTo("/path/to/project", { broadcastId: ["111-111-111", "222-222-222"] });

Alternate:

squared.copyTo("/path/to/project", {
  broadcast: {
    socketId: "111-111-111",
    callback: result => {
      console.log(result.value);
    }
  }
});

// Messages sent from another API (FileBroadcastOptions)
squared.broadcast(result => { console.log(result.value); }, { // Uses "socket_id"
  socketId: "333-333-333",
  socketKey: "socket_id",
  secure: true,
  hostname: "1.1.1.1",
  port: 8080
});
setFramework(target[, options, cache])

Install application interpreter. (e.g. android.framework.js)

Arguments:

  • target (object()) – Global object implementing AppFramework

  • options (object()) – (optional) Initialize settings with non-default values

  • cache (boolean()) – (optional) Load previous cached instance and settings

Usage:

squared.setFramework(android);
squared.setFramework(android, true); // Used when switching frameworks
squared.setFramework(android, { targetAPI: 34, idNamingStyle: "html" });

Alternate:

// Save
squared.setFramework(android, { targetAPI: 26, enabledIncludes: true }, "example"); // Local storage

// Load
squared.setFramework(android, "example");
extend(map[, framework])

Add functions and initial variables to the Node prototype including overwriting preexisting class definitions. Accessor properties are supported using the get/set object syntax.

Arguments:

  • map (object()) – Attribute object consisting of extensions and overrides

  • framework (number()) – (optional) See APP_FRAMEWORK

Usage:

squared.extend({
  _id: 1,
  altId: {
    get() {
      return this._id;
    },
    set(value) {
      this._id += value;
    }
  },
  customId: {
    value: 2,
    configurable: false,
    enumerable: false
  },
  addEvent(eventName, callback) {
    this.element.addEventListener(eventName, callback);
  }
});
squared.setFramework(vdom);

const body = await squared.fromElement(document.body);
body.altId = 2; // 3
body.altId = 2; // 5
body.addEvent("click", function (ev) {
  this.classList.toggle("example");
});

squared.extend({ _preferInitial: true }, APP_FRAMEWORK.VDOM /* 1 */ | APP_FRAMEWORK.CHROME /* 4 */); // squared.base.lib.constant
squared.setFramework(chrome);
clear()

Calls Application.clear() for any loaded frameworks and deletes all cached sessions.

Usage:

squared.clear();
add(...targets)

Include extensions to be processed with any built-in extensions.

Arguments:

  • targets – Name of disabled extension or control implementing Extension

  • targets – Tuple of extension and configuration object

Returns:

number

Usage:

class Drawer extends squared.base.ExtensionUI {
  constructor(name, framework, options) {
    super(name, framework, options);
    this.options = {
      element: {},
      resource: {},
      self: {},
      navigationView: {}
    };
    this.documentBase = true;
    this.require({ name: "android.external", leading: true });
    this.require("android.widget.menu");
    this.require("android.widget.coordinator");
  }
}

const drawer = new Drawer("android.widget.drawer", squared.base.lib.constant.APP_FRAMEWORK.ANDROID /* 2 */);
squared.add(drawer);

// Built-in
squared.add("android.resource.includes");

const options = {
  element: {
    content: { android: { layout_width: "match_parent" } }
  }
};
squared.add(["android.substitute", options]);
remove(...targets)

Exclude extensions by name or control.

Arguments:

  • targets – Name or control of extensions

Returns:

number

Usage:

const drawer = new Drawer("android.widget.drawer", 2);
squared.add(drawer);

squared.remove(drawer);
/* OR */
squared.remove("android.widget.drawer");
get(...targets)

Retrieve extensions by name only.

Arguments:

  • targets (string()) – Name of extension

Returns:

Usage:

const drawer = squared.get("android.widget.drawer");
const [drawer, menu] = squared.get("android.widget.drawer", "android.widget.menu");

drawer.options.navigationView.android = { fitsSystemWindows: "true" };
menu.project.set(document.getElementId("child-item-id"), await fetch("http://localhost:3000/drawer/menu.json"), "project-1" /* optional */); // Add project data
attr(target, name[, value])

Set or get extension options. typeof is enforced and will only set existing attributes.

Arguments:

  • target – Name or control of extension

  • name (string()) – Name of attribute in Extension.options

  • value – Any value of an existing attribute

Returns:

unknown

Usage:

const items = squared.attr("android.substitute", "viewAttributes" /* string[] */);
items.push("hint", "buttonTint");
/* OR */
squared.attr("android.substitute", "viewAttributes", items.concat(["hint", "buttonTint"]));

squared.attr("android.substitute", "attributeMapping", { "android:src": "app:srcCompat", "icon": "navigationIcon" }); // Set only and does not merge
apply(target, options[, setting])

Find extension and merge a configuration object with existing Extension.options.

Arguments:

  • target – Name or control of extension

  • options (object()) – Overriding configuration values

  • setting (string()) – (optional) Name to use when saving to local storage

Returns:

boolean

Usage:

squared.apply("android.widget.toolbar", {
  element: {
    "toolbar-id": {
      android: {
        background: "?android:attr/windowBackground"
      },
      appBar: {
        android: {
          theme: "@style/ThemeOverlay.AppCompat.Dark.ActionBar"
        }
      }
    }
  },
  "toolbar-example" // Save
});

Alternate:

squared.apply("android.widget.toolbar", "toolbar-example"); // Load
prefetch(type[, all, ...targets])

Downloads assets to a memory cache which can be used by an Application framework. Provides cross-origin support for CSS.

Arguments:

  • type (string()) – css | javascript | image | svg

  • all (boolean()) – (optional) Accept request from any origin

  • targets – (optional) URL string or root element of a contained Document

Returns:

Promise<PrefetchItem[]>

Usage:

squared.prefetch("css").then(() => squared.parseDocument()); // Cross-origin support

Promise.all(
  squared.prefetch("css", true), // All stylesheets
  squared.prefetch("css", "./undetected.css", document.getElementById("shadow-id").shadowRoot),
  squared.prefetch("svg", "http://example.com/icon.svg", "../images/android.svg")
)
.then(() => squared.parseDocument());
parseDocument(...elements)

Starts at the root target element and creates a virtual DOM structure by cascading into all the children. Assets can be preloaded (e.g. images) which is required with the android framework.

Arguments:

  • elements – (optional) Element target by either an id string or HTMLElement

  • elements – (optional) See ElementSettings

Returns:

  • Promise<Node | void>

  • Promise<Node[]> (multiple)

Usage:

const body = await squared.parseDocument();

const section = await squared.parseDocument({
  element: "section-1",
  projectId: "sqd",
  resourceQualifier: "land",
  enabledIncludes: true
});
parseDocumentSync(...elements)

Starts at the root target element and creates a virtual DOM structure by cascading into all the children. No assets are preloaded which is sufficient for the vdom framework.

Arguments:

  • elements – (optional) Element target by either an id string or HTMLElement

  • elements – (optional) See ElementSettings

Returns:

Usage:

const body = squared.parseDocumentSync();

const content = squared.parseDocumentSync("content-1");
findDocumentNode(target[, all, projectId])

Can be used before saving rendered document to modify auto-generated Node attributes.

Arguments:

  • target – Element target by either an id string or HTMLElement (selectors are supported)

  • all (boolean()) – (optional) Uses filter to return multiple results

  • projectId (string()) – (optional) Uses an existing project in the current framework

Returns:

Usage:

const body = squared.findDocumentNode(document.body);
const content = squared.findDocumentNode("content-1");

const section1 = squared.findDocumentNode("section"); // Only if no element has id="section"
const [section2, section3] = squared.findDocumentNode("main > section", true); // Always an array with "all"

Alternate:

const layout = squared.findDocumentNode("relativelayout-1", "project-1"); // Control id
layout.android("layout_width", "match_parent");
latest([count = 1])

Get any stored session ids from parseDocument() since the last time clear() was called.

Arguments:

  • count (number()) – (optional) How many ids at most to be retrieved

Returns:

string | string[] | undefined

Usage:

squared.parseDocument("id-1", "id-2", "id-3").then(() => {
  // ["00001", "00002", "00003"]
  const id3 = squared.latest();
  const id1 = squared.latest(-1);
  const [id2, id3] = squared.latest(2);
  const [id2, id1] = squared.latest(-2);
});
close([projectId])

Ends the current session or selected project preventing any further modifications. It is called internally when saving or copying.

Arguments:

  • projectId (string()) – (optional) Targets a project that is not the latest

Returns:

Promise<boolean>

Usage:

await squared.close(); // Optional
reset([projectId])

Abandons all stored projects and sets a loaded Application to its initial state. The current user settings are retained.

Arguments:

  • projectId (string()) – (optional) Targets a project that is not the latest

Usage:

squared.reset(); // Optional
save([projectId, timeout])

Uses the default Application.settings to generate an archive of the current session or selected project.

Arguments:

  • projectId (string()) – (optional) Targets a project that is not the default project

  • timeout (number()) – (optional) Maximum time in seconds for build to complete

Returns:

Promise<ResponseData>

Usage:

squared.save().then(result => console.log(result)); // Default project "_" is used

await squared.save("project-1", 10); // 10 seconds for "project-1" to build

Alternate:

squared.broadcast(result => { console.log(result.value); }, "111-111-111");
await squared.save("project-1", "111-111-111"); // broadcastId
saveAs(filename[, options, setting, overwrite])

Save current session or selected project as a new archive using filename extension.

Arguments:

  • filename (string()) – Name of file with a valid archive extension

  • options (object()) – (optional) See FileActionOptions

  • setting (string()) – (optional) Name of setting for local storage

  • overwrite (boolean()) – (optional) Will not merge previously saved settings with options

Returns:

Promise<ResponseData>

Usage:

await squared.parseDocument();
await squared.saveAs("android.zip", { timeout: 15, log: { showSize: true } }); // Uses default unnamed project "_"

await squared.parseDocument({ element: document.body, projectId: "project-1" });
await squared.saveAs("project-1.7z", { projectId: "project-1", throwErrors: true }).catch(err => { // Will cancel partial archive download
  console.log(err);
});

Alternate:

// Save
squared.saveAs("android.zip", { timeout: 15, log: { showSize: true } }, "android-example"); // Uses own "saveAs" namespace

// Load
squared.saveAs("android.zip", "android-example"); // Any page in same domain
appendTo(uri[, options, setting, overwrite])

Save current session or selected project into a copy of an existing archive if found or as a new archive using the file extension.

Arguments:

  • uri (string()) – Location of file with a valid archive extension

  • options (object()) – (optional) See FileActionOptions

  • setting (string()) – (optional) Name of setting for local storage

  • overwrite (boolean()) – (optional) Will not merge previously saved settings with options

Returns:

Promise<ResponseData>

Usage:

squared.parseDocument().then(async () => {
  await squared.appendTo("http://localhost:3000/archives/android.001", { format: "tar" }); // "tar" is explicit (ignored filename)
});

await squared.parseDocument({ element: document.body, projectId: "project-1" });
squared.appendTo("../data/project-1.7z", { projectId: "project-1" }).then(result => { // Uses NodeJS process.cwd() resolution
  console.log(result);
});

Alternate:

// Save
squared.appendTo("./android.zip", { timeout: 20, log: { showSize: true } }, "android-example"); // Uses own "appendTo" namespace

// Load
squared.appendTo("./android.zip", "android-example"); // Any page in same domain
copyTo(pathname[, options, setting, overwrite])

Save current session or selected project to a local directory.

Arguments:

  • pathname (string()) – Location of a directory accessible to the server process

  • options (object()) – (optional) See FileActionOptions

  • setting (string()) – (optional) Name of setting for local storage

  • overwrite (boolean()) – (optional) Will not merge previously saved settings with options

Returns:

Promise<ResponseData>

Usage:

await squared.parseDocument();
await squared.copyTo("./path/to/project", { timeout: 10, log: { showSize: true } });

squared.parseDocument({ element: document.body, projectId: "project-1" }).then(() => {
  squared.copyTo("/path/project", { projectId: "project-1" }).then(result => console.log(result));
});

Alternate:

// Multiple
squared.copyTo(["/path/project1", "/path/project2"]); // Copies processed files to "project1" and "project2"

// Save
squared.copyTo("./path/to/project", { timeout: 10, log: { showSize: true } }, "android-example"); // Uses own "copyTo" namespace

// Load
squared.copyTo("./path/to/project", "android-example"); // Any page in same domain
saveFiles(filename[, options, setting, overwrite])

Save selected assets as a new archive using filename extension.

Arguments:

  • filename (string()) – Name of file with a valid archive extension

  • options (object()) – (optional) See FileActionOptions

  • setting (string()) – (optional) Name of setting for local storage

  • overwrite (boolean()) – (optional) Will not merge previously saved settings with options

Returns:

Promise<ResponseData>

Usage:

const options = {
  assets: [
    {
      pathname: "images",
      filename: "android.png",
      uri: "http://localhost:3000/common/images/android.png"
    },
    {
      pathname: "images",
      filename: "android-ldpi.png",
      uri: "http://localhost:3000/common/images/android-ldpi.png"
    },
    {
      pathname: "images",
      filename: "android-hdpi.png",
      uri: "http://localhost:3000/common/images/android-hdpi.png"
    }
  ]
};
await squared.saveFiles("android.zip", options);

Alternate:

// Save
squared.saveFiles("android.zip", options, "android-example"); // Uses own "saveFiles" namespace

// Load
squared.saveFiles("android.zip", "android-example"); // Any page in same domain
appendFiles(uri[, options, setting, overwrite])

Save selected assets into a copy of an existing archive if found or as a new archive using the file extension.

Arguments:

  • uri (string()) – Location of file with a valid archive extension

  • options (object()) – (optional) See FileActionOptions

  • setting (string()) – (optional) Name of setting for local storage

  • overwrite (boolean()) – (optional) Will not merge previously saved settings with options

Returns:

Promise<ResponseData>

Usage:

const options = {
  format: "7z",
  assets: [
    {
      pathname: "images",
      filename: "android-xhdpi.png",
      uri: "http://localhost:3000/common/images/android-xhdpi.png"
    },
    {
      pathname: "images",
      filename: "android-xxhdpi.png",
      uri: "http://localhost:3000/common/images/android-xxhdpi.png"
    },
    {
      pathname: "images",
      filename: "android-xxxhdpi.png",
      uri: "http://localhost:3000/common/images/android-xxxhdpi.png"
    }
  ]
};
await squared.appendFiles("http://localhost:3000/archives/android.001", options);

Alternate:

// Save
squared.appendFiles("android.zip", options, "android-example"); // Uses own "appendFiles" namespace

// Load
squared.appendFiles("android.zip", "android-example"); // Any page in same domain
copyFiles(pathname[, options, setting, overwrite])

Save selected assets to a local directory.

Arguments:

  • pathname (string()) – Location of a directory accessible to the server process

  • options (object()) – (optional) See FileActionOptions

  • setting (string()) – (optional) Name of setting for local storage

  • overwrite (boolean()) – (optional) Will not merge previously saved settings with options

Returns:

Promise<ResponseData>

Usage:

const options = {
  assets: [
    {
      pathname: "images",
      filename: "android-xhdpi.png",
      uri: "http://localhost:3000/common/images/android-xhdpi.png"
    },
    {
      pathname: "images",
      filename: "android-xxhdpi.png",
      uri: "http://localhost:3000/common/images/android-xxhdpi.png"
    },
    {
      pathname: "images",
      filename: "android-xxxhdpi.png",
      uri: "http://localhost:3000/common/images/android-xxxhdpi.png"
    }
  ]
};
await squared.copyFiles("/path/project", options);

Alternate:

// Multiple
squared.copyFiles(["/path/project1", "/path/project2"], options); // Copies assets to "project1" and "project2"

// Save
squared.copyFiles("./path/to/project", options, "android-example"); // Uses own "copyFiles" namespace

// Load
squared.copyFiles("./path/to/project", "android-example"); // Any page in same domain
toString([projectId])

Writes the system name of the currently installed non-UI framework.

Arguments:

  • projectId (string()) – (optional) Targets a project that is not the default project

Returns:

string

Usage:

squared.setFramework(chrome);
const systemName = squared.toString(); // "chrome"

Alternate:

squared.setFramework(android);
await squared.parseDocument();
await squared.close();
const activityMain = squared.toString("project1"); // XML content
getElementById(value[, sync, cache = true])

Same behavior as native document.getElementById [1] except returns a Node instance.

Arguments:

  • value (string()) – Case-sensitive match against Element.id property

  • sync (boolean()) – (optional) Will block and not wrap query in a Promise

  • cache (boolean()) – (optional) Use any existing Node instance of Element

Returns:

  • Promise<Node | null>

  • Node | null (sync)

Usage:

const { element, attributes } = await squared.getElementById("content-id");

const content = squared.getElementById("content-id", true); // Synchronous
const child = content?.find(item => item.elementId === "child-id", { cascade: true });
querySelector(selector[, sync, cache = true])

Same behavior as native document.querySelector [2] except returns a Node instance.

Arguments:

  • selector (string()) – Selector or selectors matching one or more elements

  • sync (boolean()) – (optional) Will block and not wrap query in a Promise

  • cache (boolean()) – (optional) Use any existing Node instance of Element

Returns:

  • Promise<Node | null>

  • Node | null (sync)

Usage:

const { element, attributes } = await squared.querySelector("section img[src=vdom.png]");

squared.querySelector("body > p", true)?.each(item => { // Synchronous
  if (item.inline) {
    item.css("display", "inline-block");
  }
});
querySelectorAll(selector[, sync, cache = true])

Same behavior as native document.querySelectorAll [3] except returns an array of Node instances.

Arguments:

  • selector (string()) – Selector or selectors matching one or more elements

  • sync (boolean()) – (optional) Will block and not wrap query in a Promise

  • cache (boolean()) – (optional) Use any existing Node instance of Element

Returns:

  • Promise<Node[] | null>

  • Node[] | null (sync)

Usage:

const [img1, img2] = await squared.querySelectorAll("section img");

const children = await squared.getElementById("content-id")?.querySelectorAll("*");
fromElement(element[, sync, cache])

Same behavior as getElementById() except it also accepts a native Element. The cache parameter by default is not enabled.

Arguments:

  • element – Element target by either an id string or HTMLElement

  • sync (boolean()) – (optional) Will block and not wrap query in a Promise

  • cache (boolean()) – (optional) Use any existing Node instance of Element

Returns:

  • Promise<Node[] | null>

  • Node[] | null (sync)

Usage:

const { element, attributes } = await squared.fromElement(document.body);

const content = squared.fromElement("content-id", true); // Synchronous
const child = content?.find(item => item.elementId === "child-id", { cascade: true });
fromNode(node[, sync, cache])

Uses an existing Node instance and creates a new instance with any modifications. The cache parameter by default is not enabled.

Arguments:

  • node (object()) – See Node

  • sync (boolean()) – (optional) Will block and not wrap query in a Promise

  • cache (boolean()) – (optional) Use any existing Node instance

Returns:

  • Promise<Node[] | null>

  • Node[] | null (sync)

Usage:

let body = await squared.fromElement(document.body);
document.querySelectorAll("body div").forEach(item => document.body.removeChild(item));
body = await squared.fromNode(body);

const img = squared.fromNode(body, true).find(item => item.imageElement); // Synchronous
observe([enable = true])

Uses MutationObserver to watch for any changes to the parseDocument() root element. Start after DOM and third-party libraries are initialized.

Arguments:

  • enable (boolean()) – (optional) Start or stop all root elements who are monitoring

Usage:

await squared.parseDocument({
  element: document.body,
  projectId: "project-1",
  observe(mutations, observer, settings) {
    squared.reset("project-1");
    squared.parseDocument(settings).then(() => {
      squared.copyTo("/path/project", { projectId: "project-1", modified: true }).then(result => console.log(result));
    });
  }
});

await squared.copyTo("/path/project", { projectId: "project-1", useOriginalHtmlPage: false }).then(() => {
  squared.observe();
});

squared.observe(false); // Discontinue monitoring for changes

Alternate:

squared.observe({
  subtree: true,
  childList: true,
  attributes: true,
  characterData: false,
  attributeOldValue: false,
  characterDataOldValue: false
});
observeSrc(targets[, callback, options])

Can be used to watch external elements which contain modifiable source files.

Arguments:

  • targets – Elements by either selector or HTMLElement (src or href attribute is required)

  • callback (function()) – (optional (options)) Method to call when a modified event is received

  • options (object()) – (optional) See FileObserveOptions

Returns:

Promise<ObserveSocket | ObserveSocket[]>

Usage:

const settings = { element: document.body, projectId: "project-1" };
squared.parseDocument(settings).then(() => {
  squared.observeSrc(
    "link[rel=stylesheet]",
    (ev, element) => {
      squared.reset("project-1");
      squared.parseDocument(settings).then(() => squared.copyTo("/path/project"));
    },
    { port: 8080, secure: false, action: "reload", expires: "1h" } // Optional
  );
});

Alternate:

await squared.observeSrc("link[rel=stylesheet]"); // Will call location.reload()