core-plex v1.6.9

⁘ Core-Plex

JavaScript Property Ventilation For Node Or Browser Environments
 ⋄ Manage events for any project with plexible implementation, inheritance, and instantiation.
 ⋄ Target events on any event-targetable properties with path notation or direct references.
   ⬥ Supports Outmatch Syntax
 ⋄ Default event-target API support:
   ⬥ Browser EventTarget (including HTMLElement),
   ⬥ Node EventTarget, EventEmitter.
 ⋄ Custom event target API support for anything else.

❖ Impetus

 ⋄ Managing event addition/removal/dispatch is necessary for most application development.
 ⋄ Add/Remove/Dispatch event statements are usually disparately located throughout codebases.
 ⋄ Event assignment/deassignment/transsignment differentiate based on event-targetable class prototype.
   ⬥ e.g. EventTarget versus EventEmitter.

❖ Introduction

Core-Plex Is An Event Management System For Frontend/backend Applications.
 ⋄ Map Events To Scoped Event Targets With Property Paths
 ⋄ Add/Remove, Enable/Disable Pathed Events
 ⋄ Define Property Paths With Dot-Notation, Globbing, And Pattern Matching
 ⋄ Enable/Disable Events, Emit Events Dynamically
 ⋄ Implement Core-Plex On Existing Objects, Class Instances
 ⋄ Extend Core-Plex On Custom Classes

❖ Installation

Install core-plex via npm CLI.

npm install core-plex

❖ Importation

Core Class is an ES Module exported from core-plex.

import { Core } from 'core-plex'

❖ Implementation

Manage events for properties on provided $target.

⬦ Example A.1. - Browser HTML Event Management

Example A.1. Code
Core.implement adds, enables click events...

import { Core } from 'core-plex'
Core.implement(app, {
  events: {
    'qs.app click': function appClick($event) {
      console.log($event.type, $event.target
     }
    'qs.menuButton.[0-9] click': function menuButtonClick($event) {
      console.log($event.type, $event.target)
    },
    'qs.sectionButton.[0-9] click': function sectionButtonClick($event) {
      console.log($event.type, $event.target)
    },
  },
  enableEvents: true,
})

...for arbitray HTML app structure.

const app = {
  parentElement: document.querySelector('body'),
  template: `
    <app>
      <nav class="menu">
        <button data-id="menu-a">Menu A</button>
        <button data-id="menu-b">Menu B</button>
        <button data-id="menu-c">Menu C</button>
      </nav>
      <nav class="section">
        <button data-id="section-a">Section A</button>
        <button data-id="section-b">Section B</button>
        <button data-id="section-c">Section C</button>
      </nav>
    </app>
  `,
  qs: Object.defineProperties({}, {
    app: { get() {
      return document.querySelector('app')
    }, enumerable: true },
    menuButton: { get() {
      return document.querySelectorAll('app > nav.menu > button')
    }, enumerable: true },
    sectionButton: { get() {
      return document.querySelectorAll('app > nav.section > button')
    }, enumerable: true },
  }),
  render: function() {
    const app = this.qs.app
    this.disableEvents()
    if(app) app.removeChild()
    this.parentElement.insertAdjacentHTML('afterbegin', this.template)
    this.enableEvents()
    return this
  }
}.render()

⬦ Example A.2. - Node Chokidar Event Management

Example A.2. Code
Core ministrates Chokidar watcher events.

import chokidar from 'chokidar'
import { Core } from 'core-plex'
const watchers = {
  styleWatcher: chokidar.watch(path.join(__dirname, 'some-files/index.css')),
  scriptWatcher: chokidar.watch(path.join(__dirname, 'some-files/index.js')),
  structWatcher: chokidar.watch(path.join(__dirname, 'some-files/index.html')),
}
const core = Core.implement(watchers, {
  events: {
    // Styles
    'styleWatcher add': function styleWatcherAdd($path) {
      console.log("add", $path)
    },
    'styleWatcher change': function styleWatcherChange($path) {
      console.log("change", $path)
    },
    'styleWatcher unlink': function styleWatcherUnlink($path) {
      console.log("unlink", $path)
    },
    // Scripts
    'scriptWatcher add': function scriptWatcherAdd($path) {
      console.log("add", $path)
    },
    'scriptWatcher change': function scriptWatcherChange($path) {
      console.log("change", $path)
    },
    'scriptWatcher unlink': function scriptWatcherUnlink($path) {
      console.log("unlink", $path)
    },
    // Structs
    'structWatcher add': function structWatcherAdd($path) {
      console.log("add", $path)
    },
    'structWatcher change': function structWatcherChange($path) {
      console.log("change", $path)
    },
    'structWatcher unlink': function structWatcherUnlink($path) {
      console.log("unlink", $path)
    },
  },
  enableEvents: true,
  assign: 'on', deassign: 'off', 
})

⬦ Example A.3. - Node, Browser EventTarget

Example A.3. Browser Code
Example A.3. Node Code
Add, enable target property events with Core.implement...

import { Core } from 'core-plex'
const app = Core.implement(Object.assign(new EventTarget(), {
  propertyA: new EventTarget(),
  propertyB: {
    propertyC: {
      propertyD: new EventTarget(),
    }
  },
  propertyE: [{
    propertyF: new EventTarget()
  }, {
    propertyF: new EventTarget()
  }, {
    propertyF: new EventTarget()
  }]
}), {
  events: {
    'customEvent': ($event) => console.log($event.type, $event.detail),
    'propertyA customEvent': ($event) => console.log($event.type, $event.detail),
    'propertyB.propertyC.propertyD customEvent': ($event) => console.log($event.type, $event.detail),
    'propertyE.[0-9].propertyF customEvent': ($event) => console.log($event.type, $event.detail),
  },
  enableEvents: true
})

...then dispatchEvent from target properties.

for(const $eventDefinition of app.getEvents([
  { path: ':scope' },
  { path: 'propertyA' },
  { path: 'propertyB.propertyC.propertyD' },
  { path: 'propertyE.[0-9].propertyF' },
])) {
  $eventDefinition.emit(
    new CustomEvent('customEvent', { detail: $eventDefinition })
  )
}

❖ Inheritance

Manage events for properties on new extended Core instance.

⬦ Example A.4. - CustomCore With CustomCore Subproperties

Example A.4. Code
CustomCore accepts a $properties argument that populates instance with nested CustomCore instances.

import { Core } from 'core-plex'
class CustomCore extends Core {
  constructor($settings, $properties = {}) {
    super($settings)
    for(const [
      $propertyKey, $propertyValue
    ] of Object.entries($properties)) {
      if($propertyValue && typeof $propertyValue === 'object') {
        const subpropertySettings = Object.assign({}, {
          defineProperties: $settings.defineProperties
        })
        Object.defineProperty(this, $propertyKey, {
          enumerable: true, writable: false,
          value: new CustomCore({}, $propertyValue),
        })
      }
      else {
        Object.defineProperty(this, $propertyKey, {
          enumerable: true, writable: false,
          value: $propertyValue,
        })
      }
    }
    if($settings.enableEvents === true) { this.enableEvents() }
  }
}
const customCore = new CustomCore({
  events: {
    'propertyA customEvent': ($event) => {
      console.log($event.type, $event.detail),
    },
    'propertyA.propertyB customEvent': ($event) => {
      console.log($event.type, $event.detail),
    },
    'propertyD.[0-9] customEvent': ($event) => {
      console.log($event.type, $event.detail),
    },
  },
  enableEvents: true,
}, {
  propertyA: {
    propertyB: {
      propertyC: 333
    }
  },
  propertyD: [{
    propertyE: 555
  }, {
    propertyF: 666
  }, {
    propertyE: 777
  }]
})

❖ Instantiation

Manage events for properties defined on Core instance events.

⬦ Example A.5. - Core Instance With EventDefinition.target Definitions

Example A.5. Code

import chokidar from 'chokidar'
import { Core } from 'core-plex'
const styleWatcher = chokidar.watch(path.join(__dirname, 'some-files/index.css'))
const scriptWatcher = chokidar.watch(path.join(__dirname, 'some-files/index.js'))
const structWatcher = chokidar.watch(path.join(__dirname, 'some-files/index.html'))
const coreInstance = new Core({ assign: 'on', deassign: 'off' })
// Struct Events
coreInstance.addEvents([{
  path: "styleWatcher", type: "add", 
  target: styleWatcher, listener: ($path) => console.log("add", $path),
}, {
  path: "styleWatcher", type: "change", 
  target: styleWatcher, listener: ($path) => console.log("change", $path),
}, {
  path: "styleWatcher", type: "unlink", 
  target: styleWatcher, listener: ($path) => console.log("unlink", $path),
}, {
  path: "styleWatcher", type: "error", 
  target: styleWatcher, listener: ($err) => console.log("error", $err),
}])
// Script Events
coreInstance.addEvents([{
  path: "scriptWatcher", type: "add", 
  target: scriptWatcher, listener: ($path) => console.log("add", $path),
}, {
  path: "scriptWatcher", type: "change", 
  target: scriptWatcher, listener: ($path) => console.log("change", $path),
}, {
  path: "scriptWatcher", type: "unlink", 
  target: scriptWatcher, listener: ($path) => console.log("unlink", $path),
}, {
  path: "scriptWatcher", type: "error", 
  target: scriptWatcher, listener: ($err) => console.log("error", $err),
}])
// Struct Events
coreInstance.addEvents([{
  path: "structWatcher", type: "add", 
  target: structWatcher, listener: ($path) => console.log("add", $path),
}, {
  path: "structWatcher", type: "change", 
  target: structWatcher, listener: ($path) => console.log("change", $path),
}, {
  path: "structWatcher", type: "unlink", 
  target: structWatcher, listener: ($path) => console.log("unlink", $path),
}, {
  path: "structWatcher", type: "error", 
  target: structWatcher, listener: ($err) => console.log("error", $err),
}])
.enableEvents()