wiznetic-kernel-js-front-end

Programmable lifecycle microkernel for the frontend by Wiznetic.

Frontend mirror of wiznetic/kernel (PHP).

Installation

npm install wiznetic-kernel-js-front-end

Lifecycle

The kernel runs three ordered steps on boot:

| Step | Purpose | |---------|--------------------------------| | init | Early setup, service bootstrap | | ready | DOM work, component init | | done | Finalization, cleanup |

Each step has three phases: before → on → after.

Usage

Boot

Call Kernel.boot() once from your entry file. It waits for the DOM automatically.

import { Kernel } from 'wiznetic-kernel-js-front-end'

Kernel.boot()

Lifecycle hooks

import { Kernel } from 'wiznetic-kernel-js-front-end'

Kernel.on('ready', async (ctx) => {
    console.log('DOM is ready')
})

Kernel.before('ready', async (ctx) => {
    // runs before 'on:ready'
})

Kernel.after('done', async (ctx) => {
    // runs after everything
})

Custom events

Define an event class:

import { Event } from 'wiznetic-kernel-js-front-end'

export class UserLoggedIn extends Event {
    constructor(user) {
        super()
        this.user = user
    }
}

Listen and dispatch:

import { Kernel }      from 'wiznetic-kernel-js-front-end'
import { UserLoggedIn } from './events/UserLoggedIn.js'

// Register listener
Kernel.listen(UserLoggedIn, async (event) => {
    console.log('User:', event.user)
})

// Dispatch
await Kernel.dispatch(new UserLoggedIn({ id: 1, name: 'John' }))

Stop propagation:

Kernel.listen(UserLoggedIn, async (event) => {
    event.stopPropagation() // next listeners won't run
})

Listing — bind event listener to lifecycle step

import { Kernel }      from 'wiznetic-kernel-js-front-end'
import { UserLoggedIn } from './events/UserLoggedIn.js'
import { AuthHandler }  from './handlers/AuthHandler.js'

Kernel.listen(UserLoggedIn, AuthHandler)
      .on('ready')              // run AuthHandler when UserLoggedIn is dispatched, during on:ready
      .after('done')            // also run after done

Receive modes:

.on('ready', 'event')          // handler receives only the event
.on('ready', 'ctx')            // handler receives only the context
.on('ready', 'all')            // handler receives (ctx, event) — default
.on('ready', (ctx, e) => [e])  // custom resolver

Context

The ctx object is available in all hooks and carries shared data across the lifecycle:

Kernel.on('init', async (ctx) => {
    ctx.data.set('user', { id: 1 })
})

Kernel.on('ready', async (ctx) => {
    const user = ctx.data.get('user')
})

Trace

Enable timing records for debugging:

Kernel.trace(true)

await Kernel.boot()

console.log(Kernel.getTrace())
// [{ phase, step, handler, duration (ms), at }]

API Reference

Kernel

| Method | Description | |--------|-------------| | Kernel.boot() | Start the lifecycle. Waits for DOMContentLoaded. Returns Promise. | | Kernel.before(step, cb) | Register hook before a step | | Kernel.on(step, cb) | Register hook on a step | | Kernel.after(step, cb) | Register hook after a step | | Kernel.listen(EventClass, handler) | Register event listener. Returns Listing. | | Kernel.dispatch(event) | Dispatch an event. Returns Promise. | | Kernel.trace(enabled) | Enable/disable trace recording | | Kernel.getTrace() | Get recorded trace entries |

Event

| Method | Description | |--------|-------------| | event.stopPropagation() | Stop remaining listeners | | event.isPropagationStopped() | Check if stopped |

Listing

| Method | Description | |--------|-------------| | .before(step, receive?) | Bind to before phase of step | | .on(step, receive?) | Bind to on phase of step | | .after(step, receive?) | Bind to after phase of step |

Trace entry

{
    phase:    'on',
    step:     'ready',
    handler:  'MyHandler',
    duration: 1.23,   // ms
    at:       1234.5  // performance.now()
}

License

MIT