cpuabuse-system v0.6.0

Files & Data

• Default file extension is added, if missing
• For empty value in key/value pair, value equal to key is assumed
• In absent key/value child pairs, default values for missing keys are assumed

JSDoc - Member Declaration

Structure

system

System is intended more than anything, for centralized managment.

• system
  • static
    • .System ⇐ Loader
      • new System(options, [behaviors])
      • instance
        • .events : Object
          • "errorExists"
          • "systemLoad"
          • "behaviorAttach"
          • "behaviorAttachFail"
          • "behaviorAttachRequestFail"
          • "typeError"
          • "eventFail"
        • .behaviors : Object
        • .system : options
          • .behavior : Behavior
          • .error : Object
          • .file : Object
            • .filter : Object
              • .isFile(filterContext) ⇒ Promise
              • .isDir(filterContext) ⇒ Promise
            • .toRelative(rootDir, target) ⇒ Promise
            • .join(rootDir, target) ⇒ Promise
            • .getFile(dir, file) ⇒ Promise
            • .getYaml(dir, file) ⇒ Promise
            • .list(dir, file) ⇒ Promise
        • .addError(code, message)
        • .addBehaviors(behaviors)
        • .log(text)
        • .error(text)
        • .fire(name, [message])
        • .behave(event)
        • .on(event, callback)
      • static
        • .checkOptionsFailure(options) ⇒ boolean
        • .error(text)
        • .log(text)
      • inner
        • ~options : Object
        • ~filterContext : Object
        • ~behavior : Object
    • .AtomicLock
      • new AtomicLock()
      • .locked : boolean ℗
      • .lock() ⇒ Promise
      • .release()
  • inner
    • ~Loader
      • new Loader(rootDir, relativeInitDir, initFilename, callback)
      • static
        • .getFile(rootDir, relativeDir, file) ⇒ external.Promise
        • .toRelative(dir, target) ⇒ string | Array.<string>
        • .join(rootDir, target) ⇒ string | Array.<string>
        • .isFile(rootDir, relativeDir, filename) ⇒ boolean
        • .isDir(rootDir, relativeDir) ⇒ boolean
        • .list(rootDir, relativeDir) ⇒ Promise
        • .yamlToObject(string) ⇒ Object
      • inner
        • ~initRecursion(rootDir, relativePath, initFilename, targetObject, extend) ⇒ Promise
        • ~initSettings(rootDir, initPath, filename) ⇒ Object
        • ~loadYaml(rootDir, relativeDir, filename) ⇒ Promise
    • ~SystemError ⇐ Error
      • new SystemError(code, message)
      • instance
        • .code : string ℗
      • static
        • .isSystemError(error) ⇒ boolean
    • ~Behavior ⇐ EventEmitter
      • new Behavior()
      • .atomicLock : AtomicLock ℗
      • .behaviorId : Object ℗
      • .behaviorIndex : Array.<string> ℗
      • .nextBehaviorCounter : number ℗
      • .addBehavior(name, callback) ⇒ number
      • .behave(name)
    • ~test
      • .Loader
        • .toRelative
        • .join
        • .isFile

system.System ⇐ Loader

Provides wide range of functionality for file loading and event exchange. Throws standard error if failed to perform basic initializations, or system failure that cannot be reported otherwise has occured.

Kind: static class of system
Extends: Loader
Emits: systemLoad

• .System ⇐ Loader
  • new System(options, [behaviors])
  • instance
    • .events : Object
      • "errorExists"
      • "systemLoad"
      • "behaviorAttach"
      • "behaviorAttachFail"
      • "behaviorAttachRequestFail"
      • "typeError"
      • "eventFail"
    • .behaviors : Object
    • .system : options
      • .behavior : Behavior
      • .error : Object
      • .file : Object
        • .filter : Object
          • .isFile(filterContext) ⇒ Promise
          • .isDir(filterContext) ⇒ Promise
        • .toRelative(rootDir, target) ⇒ Promise
        • .join(rootDir, target) ⇒ Promise
        • .getFile(dir, file) ⇒ Promise
        • .getYaml(dir, file) ⇒ Promise
        • .list(dir, file) ⇒ Promise
    • .addError(code, message)
    • .addBehaviors(behaviors)
    • .log(text)
    • .error(text)
    • .fire(name, [message])
    • .behave(event)
    • .on(event, callback)
  • static
    • .checkOptionsFailure(options) ⇒ boolean
    • .error(text)
    • .log(text)
  • inner
    • ~options : Object
    • ~filterContext : Object
    • ~behavior : Object

new System(options, behaviors)

The constructor will perform necessary preparations, so that failures can be processed with system events. Up until these preparations are complete, the failure will result in thrown standard Error.

Throws:

• Error - loader_failed - Loader did not construct the mandatory properties

system.events : Object

Events to be populated by the loader. System by itself does not deal with events, it only confirms that the events were initialized. Although, if the events are fired, and failure to fire event is set to throw, or undocumented events encountered, it would throw errors.

Kind: instance abstract property of System

• .events : Object
  • "errorExists"
  • "systemLoad"
  • "behaviorAttach"
  • "behaviorAttachFail"
  • "behaviorAttachRequestFail"
  • "typeError"
  • "eventFail"

"errorExists"

Error could not be added, because error with same code already exists.

Kind: event emitted by events
Default: error_exists

"systemLoad"

System load event. Fires at the end of system load, so it is safe to execute code in the then() directive of behavior associated.

Kind: event emitted by events
Default: system_load

"behaviorAttach"

Behavior has been attached.

Kind: event emitted by events
Default: behavior_attach

"behaviorAttachFail"

Behavior could not be attached.

Kind: event emitted by events
Default: behavior_attach_fail

"behaviorAttachRequestFail"

Incorrect behavior attach request.

Kind: event emitted by events
Default: behavior_attach_request_fail

"typeError"

Type error has been encountered.

Kind: event emitted by events
Default: type_error

"eventFail"

Failed to fire an event.

Kind: event emitted by events
Default: event_fail

system.behaviors : Object

Behavior describtions initialized by loader.

Kind: instance abstract property of System

system.system : options

Contains system info.

Kind: instance property of System
Read only: true
Properties

• .system : options
  • .behavior : Behavior
  • .error : Object
  • .file : Object
    • .filter : Object
      • .isFile(filterContext) ⇒ Promise
      • .isDir(filterContext) ⇒ Promise
    • .toRelative(rootDir, target) ⇒ Promise
    • .join(rootDir, target) ⇒ Promise
    • .getFile(dir, file) ⇒ Promise
    • .getYaml(dir, file) ⇒ Promise
    • .list(dir, file) ⇒ Promise

system.behavior : Behavior

Actual behaviors are located here.

Kind: static property of system

system.error : Object

Actual errors are located here.

Kind: static abstract property of system

system.file : Object

File system methods.

Kind: static property of system

• .file : Object
  • .filter : Object
    • .isFile(filterContext) ⇒ Promise
    • .isDir(filterContext) ⇒ Promise
  • .toRelative(rootDir, target) ⇒ Promise
  • .join(rootDir, target) ⇒ Promise
  • .getFile(dir, file) ⇒ Promise
  • .getYaml(dir, file) ⇒ Promise
  • .list(dir, file) ⇒ Promise

file.filter : Object

File level filters.

Kind: static property of file

• .filter : Object
  • .isFile(filterContext) ⇒ Promise
  • .isDir(filterContext) ⇒ Promise

filter.isFile(filterContext) ⇒ Promise

Check if argument is a file (relative to system root directory).

Kind: static method of filter
Returns: Promise - Promise, containing boolean result.

filter.isDir(filterContext) ⇒ Promise

Check if argument is a folder (relative to system root directory).

Kind: static method of filter
Returns: Promise - Promise, containing boolean result.

file.toRelative(rootDir, target) ⇒ Promise

Converts absolute path to relative path.

Kind: static method of file
Returns: Promise - Promise, containing string relative path.

file.join(rootDir, target) ⇒ Promise

Joins two paths.

Kind: static method of file
Returns: Promise - Promise, containing string path.

file.getFile(dir, file) ⇒ Promise

Get file contents relative to system root directory.

Kind: static method of file
Returns: Promise - Promise, containing string with file contents..

file.getYaml(dir, file) ⇒ Promise

Get contents of yaml file relative to system root directory.

Kind: static method of file
Returns: Promise - Promise, containing string with file contents..

file.list(dir, file) ⇒ Promise

List the contents of the folder, relative to system root directory.

Kind: static method of file
Returns: Promise - Promise, containing an array of filtered strings - files/folders relative to system root.

Example (List folders)

systemInstance.system.file.list("css", systemInstance.system.file.filter.isDir);

system.addError(code, message)

Adds an error to the System dynamically

Kind: instance method of System
Emits: errorExists

Example (Usage)

code = "no_beakers"
message = "Beakers out of stock."
var options = {
  id: "lab_inventory",
  rootDir: "labs",
  relativeInitDir: "black_mesa",
  initFilename: "inventory.yml",
  notMute: true
};
var labInventory = new System(options);

labInventory.addError(code, message);

system.addBehaviors(behaviors)

Adds behaviors to the system, and fires post-addtion events. Firstly, this function attempts to add the behaviors. When the behavior addition has been processed, the function will attempt to fire post-addition events, depending on success/failure of behavior additions.

Kind: instance method of System
Emits: behaviorAttach, behaviorAttachFail, behaviorAttachRequestFail

Example (Usage)

var options = {
  id: "lab_inventory",
  rootDir: "labs",
  relativeInitDir: "black_mesa",
  initFilename: "inventory.yml",
  notMute: true
};
var behavior = {
  "check_inventory": () => {
    // Behavior functionality
    // ...
  }
}

var labInventory = new System(options);
labInventory.addBehaviors([behavior]).then(function(){
  console.log("Behavior added.");
});

system.log(text)

Log message from the System context

Kind: instance method of System
Emits: module:system.System~event:type_error

Example (Usage)

var options = {
  id: "lab_inventory",
  rootDir: "labs",
  relativeInitDir: "black_mesa",
  initFilename: "inventory.yml",
  notMute: true
};
var text = "Lab Inventory working.";

var labInventory = new System(options);
labInventory.log(text);

system.error(text)

Log an error message from the System context

Kind: instance method of System
Emits: module:system.System~event:type_error

Example (Usage)

var options = {
  id: "lab_inventory",
  rootDir: "labs",
  relativeInitDir: "black_mesa",
  initFilename: "inventory.yml",
  notMute: true
};
var text = "Testing Lab Inventory error log.";

var labInventory = new System(options);
labInventory.error(text);

system.fire(name, message)

Fires a system event

Kind: instance method of System
Throws:

• Error Will throw error_hell. The inability to process error - if eventFail event fails.

Emits: eventFail

Example (Usage)

var options = {
  id: "lab_inventory",
  rootDir: "labs",
  relativeInitDir: "black_mesa",
  initFilename: "inventory.yml",
  notMute: true
};

var labInventory = new System(options);
labInventory.fire("system_load_aux", "Auxiliary system loaded.");

system.behave(event)

Emit an event as a behavior.

Kind: instance method of System

Example (Usage)

// From the lab inventory system context
{
  // ...

  this.behave("system_load_aux");

  // ...
}

system.on(event, callback)

Adds a behavior bound to "this".

Kind: instance method of System

Example (Usage)

var options = {
  id: "lab_inventory",
  rootDir: "labs",
  relativeInitDir: "black_mesa",
  initFilename: "inventory.yml",
  notMute: true
};

var labInventory = new System(options);
labInventory.on("system_load_aux", function(that){
  console.log("Auxiliary system loaded - " + that.system.id);
});

System.checkOptionsFailure(options) ⇒ boolean

Checks options argument for missing incorrect property types

Kind: static method of System
Returns: boolean - Returns true if the arguments is corrupt; false if OK

Example (Usage)

var options = {
  id: "stars",
  rootDir: "test",
  relativeInitDir: "stars",
  initFilename: "stars.yml",
  notMute: true
};

if (System.checkOptionsFailure(options)){
  throw new Error ("Options inconsistent.");
}

System.error(text)

Access stderr

Kind: static method of System

Example (Usage)

system.System.error("Not enough resources.");

System.log(text)

Access stdout

Kind: static method of System

Example (Usage)

system.System.log("Resources loaded.");

System~options : Object

System options

Kind: inner typedef of System
Properties

System~filterContext : Object

System options

Kind: inner typedef of System
Properties

System~behavior : Object

System behavior - an object, with a property where key is the name of the behavior, and value is the function, taking a system context as an argument.

Kind: inner typedef of System
Properties

Example (Behavior - argument outline)

amazing_behavior: (that) => {
  // Process system instance on "amazing_behavior"
  amazingProcessor(that);
}

system.AtomicLock

Creates an instance of AtomicLock. It is not intended to be actually used for parallel processing, and mutual exlusion. It is intended for abstraction of atomic logic more than anything.

Note: To be eventually split into a primitive lock to objectify the functionality of a lock, and a lock with timout and a queue.

Kind: static class of system

• .AtomicLock
  • new AtomicLock()
  • .locked : boolean ℗
  • .lock() ⇒ Promise
  • .release()

new AtomicLock()

Creates an instance of AtomicLock. Does not take any arguments or return any values.

atomicLock.locked : boolean ℗

Indicates the locked/unlocked state.

Kind: instance property of AtomicLock
Access: private

atomicLock.lock() ⇒ Promise

Lock an atomic lock.

Kind: instance method of AtomicLock
Returns: Promise - Resolves when lock succeeds
Example (Usage)

// Lock
exampleAtomicLock.lock();

atomicLock.release()

Release atomic lock

Kind: instance method of AtomicLock
Example (Usage)

// Release
exampleAtomicLock.release();

system~Loader

Required by system to perform file initialization.

Kind: inner class of system

• ~Loader
  • new Loader(rootDir, relativeInitDir, initFilename, callback)
  • static
    • .getFile(rootDir, relativeDir, file) ⇒ external.Promise
    • .toRelative(dir, target) ⇒ string | Array.<string>
    • .join(rootDir, target) ⇒ string | Array.<string>
    • .isFile(rootDir, relativeDir, filename) ⇒ boolean
    • .isDir(rootDir, relativeDir) ⇒ boolean
    • .list(rootDir, relativeDir) ⇒ Promise
    • .yamlToObject(string) ⇒ Object
  • inner
    • ~initRecursion(rootDir, relativePath, initFilename, targetObject, extend) ⇒ Promise
    • ~initSettings(rootDir, initPath, filename) ⇒ Object
    • ~loadYaml(rootDir, relativeDir, filename) ⇒ Promise

new Loader(rootDir, relativeInitDir, initFilename, callback)

Loader.getFile(rootDir, relativeDir, file) ⇒ external.Promise

Gets file contents.

Kind: static method of Loader
Returns: external.Promise - File contents.

Example (Usage)

// Load files
var grapefruitJuicer = Loader.getFile("c:\machines", "appliances", "grapefruitJuicer.txt");

// Output the result
grapefruitJuicer.then(function(result){ // grapefruitJuicer - on resolve
  console.log(result);
}, function(error){ // grapefruitJuicer - on reject
  console.error("Could not load a file.");
});

// Input - grapefruitJuicer.txt
// 1000W powerful juicer

// Output
// 1000W powerful juicer

Loader.toRelative(dir, target) ⇒ string | Array.<string>

Extracts relative path from rootDir to target.

Kind: static method of Loader
Returns: string | Array.<string> - Relative path|paths.

Example (Usage)

// Convert path and output the result
console.log(Loader.toRelative("c:\machines\refrigerators", "c:\machines\appliances"));

// Output
// ..\appliances

Loader.join(rootDir, target) ⇒ string | Array.<string>

Join a root directory with a file/folder or an array of files/folders to absolute path.

Kind: static method of Loader
Returns: string | Array.<string> - Absolute path|paths.

Example (Usage)

// Join and log result
console.log(Loader.join("c:\machines", "appliances"))

// Output
// c:\machines\appliances

Loader.isFile(rootDir, relativeDir, filename) ⇒ boolean

Checks if is a file

Kind: static method of Loader
Returns: boolean - Returns true if a file, false if not.

Example (Usage)

// Verify file
Loader.isFile("c:\machines","appliances","grapefruitJuicer.txt").then(function(result){
  console.log(result);
});

// Input - grapefruitJuicer.txt
// 1000W powerful juicer

// Output
// true

Loader.isDir(rootDir, relativeDir) ⇒ boolean

Checks if is a directory.

Kind: static method of Loader
Returns: boolean - Returns true if a directory, false if not.

Example (Usage)

// Verify directory
Loader.isDir("c:\machines\appliances","grapefruitJuicer.txt").then(function(result){
  console.log(result);
});

// Input - grapefruitJuicer.txt
// 1000W powerful juicer

// Output
// false

Loader.list(rootDir, relativeDir) ⇒ Promise

Returns an array of strings, representing the contents of a folder.

Kind: static method of Loader
Returns: Promise - Array with contents; Rejects with errors from fs.readdir.

Example (Usage)

// List directory contents
Loader.list("c:","machines").then(function(result){
  console.log(result);
}, function(error){
  console.error("Folder not found.");
});

// Output
// ["machines", "appliances"]

Loader.yamlToObject(string) ⇒ Object

Converts YAML string to a JS object.

Kind: static method of Loader
Returns: Object - Javascript object.

Example (Usage)

// Ouput conversion of YAML to JSON
console.log(Loader.yamlToObject("Wine: Red"));

// Output
// {"Wine": "Red"}

Loader~initRecursion(rootDir, relativePath, initFilename, targetObject, extend) ⇒ Promise

System loader recursion.

Note:

• Default values are assumed for unspecified or empty values.
• Extension means recursive loading of data into variable, as if loading a new file into the current variable as new system.
• Relative path is relative to the directory location of current file.

Kind: inner method of Loader
Throws:

• Will throw an error if the directive is not an allowed one (folder, file, path, extend).

Example (Default filename - null)

# Variable settings to be populated with data from "system_root_dir/settings.yml"
settings: # Defaults to "settings"

Example (Default filename - empty string)

# Variable settings to be populated with data from "system_root_dir/settings.yml"
settings: "" # Defaults to "settings"

Example (Specified filename)

# Variable settings to be populated with data from "system_root_dir/xxx.yml"
settings: "xxx"

Example (Default values)

# Variable settings to be populated with data from "system_root_dir/settings.yml"
settings:
  folder: # Defaults to "./"
  file: # Defaults to "settings"
  path: # Defaults to "absolute"
  extend: # Defaults to "false"

Example (Specified values)

# Variable settings to be populated with data from "current_dir/hello/xxx.yml"
settings:
  folder: "hello"
  file: xxx
  path: relative
  extend: false

Example (Extension)

# Variable settings to be populated **recursively** with data from "current_dir/hello/xxx.yml"
settings:
  folder: "hello"
  file: xxx
  path: relative
  extend: true

Example (Usage)

// Input - ./settings/init.yml
// settings:
//   path: relative

// Input - ./settings/settings.yml
// apples: red
// bananas: yellow

// Target object to fill
var targetObject = {};

initRecursion("./", "settings", "init.yml", targetObject, true));

Loader~initSettings(rootDir, initPath, filename) ⇒ Object

Init and populate globalspace with settings - specific global object member per file. Semantically this function has broader purpose than loadYaml.

Kind: inner method of Loader
Returns: Object - Javascript object with settings.

Example (Usage)

var settings = await initSettings("./", "settings", "settings");

Loader~loadYaml(rootDir, relativeDir, filename) ⇒ Promise

Parses YAML file, and returns and object; Adds extension if absent.

Kind: inner method of Loader
Returns: Promise - Javascript object.

Example (Usage)

var settings = await loadYaml("./", "settings", "settings");

system~SystemError ⇐ Error

Extended system error class.

Kind: inner class of system
Extends: Error

• ~SystemError ⇐ Error
  • new SystemError(code, message)
  • instance
    • .code : string ℗
  • static
    • .isSystemError(error) ⇒ boolean

new SystemError(code, message)

Creates an instance of SystemError.

systemError.code : string ℗

Error code.

Kind: instance property of SystemError
Access: private

SystemError.isSystemError(error) ⇒ boolean

Check if an object is indeed a functional SystemError.

Note:

• Not checking for presence of code property, or for it being a string, as assuming that the object of SystemError type would have it initialized.
• Empty code errors will return false, due to the ambiguity.

Kind: static method of SystemError
Returns: boolean - Returns true if is is a SystemError, false if not.

Example (Usage)

// Try to load JSON
try{
  loadJson();
} catch(error) {
  if (SystemError.isSystemError(error)){
    // If error is something that we have defined, throw a more generic error
    throw new SystemError("json_load_fail", "Failed to load JSON file.");
  } else {
    // Rethrow the original error
    throw error;
  }
}

system~Behavior ⇐ EventEmitter

System behavior class

Kind: inner class of system
Extends: EventEmitter

• ~Behavior ⇐ EventEmitter
  • new Behavior()
  • .atomicLock : AtomicLock ℗
  • .behaviorId : Object ℗
  • .behaviorIndex : Array.<string> ℗
  • .nextBehaviorCounter : number ℗
  • .addBehavior(name, callback) ⇒ number
  • .behave(name)

new Behavior()

Initializes system behavior

behavior.atomicLock : AtomicLock ℗

Atomic lock to perform counter increments

Kind: instance property of Behavior
Access: private

behavior.behaviorId : Object ℗

IDs to use as actual event identifiers

Kind: instance property of Behavior
Access: private

behavior.behaviorIndex : Array.<string> ℗

Index to link id's back to behavior names

Kind: instance property of Behavior
Access: private

behavior.nextBehaviorCounter : number ℗

Counter to use to generate IDs

Kind: instance property of Behavior
Access: private

behavior.addBehavior(name, callback) ⇒ number

Adds a behavior to the behavior class instance.

Note:

Does not check for inconsistencies within ID and index arrays, as if it is internally managed by this class, inconsistencies should not happen.

Kind: instance method of Behavior
Returns: number - ID of the behavior; -1 if creation failed

Example (Usage)

// Create a new instance of Behavior
var behavior = new Behavior();

// Add a behavior
behavior.addBehavior("hello_behavior", () => console.log("Hello World"));

behavior.behave(name)

Triggers behaviors registered for name

Kind: instance method of Behavior

Example (Usage)

// Create a new instance of Behavior
var behavior = new Behavior();

// Add a behavior
behavior.addBehavior("hello_behavior", () => console.log("Hello World"));

// Call a behavior
behavior.behave("hello_behavior");

// Output:
// "Hello World"

system~test

Series of tests for the system.

Kind: inner property of system

• ~test
  • .Loader
    • .toRelative
    • .join
    • .isFile

test.Loader

Tests for the Loader class.

Kind: static property of test

• .Loader
  • .toRelative
  • .join
  • .isFile

Loader.toRelative

Tests the toRelative function.

Kind: static property of Loader

Loader.join

Tests the join function.

Kind: static property of Loader

Loader.isFile

Tests the isFile function.

Kind: static property of Loader