JSPM

about virst

virst is:

• pronounced /fɜrst/ ("technically" pun of first /fɜrst/ and burst /bɜrst/);
• new repo/library based on @html_first/simple_signal;

  • which itself are inspired by solidJS signal based reactivity

    • which then simple_signal will be discontinued effective immediately;

• collections of library for creating:

  • reactive(and if necessary, declarative) SPA web app, including functionalities such as:

    • client side routing (using query parameter with our DefineQRouter);
    • signal based asyncrhonous reactivity, which supports:

      • dataOnly;
      • with "dom reflector" (using attributeName="...attributeValues;");

    • templating using:

      • native web component with WebComponent Instance;
      • Lifecycle Instance with:

        • html onConnectedOptions to modify element innerHTML;
        • DefinePageTemplate attributeName template on other page with swap

  • client side JS library that are relying on attributeName to track the element lifecycle, using our Lifecyle class api:

    • you can use it to create your own HATEOAS (like htmx) client side library, to interprete returned htmlString which have certain attributeName;
    • handle non editable static site generated exports/publish such as:

      • bootstrap studio;
      • pinegrow;
      • WYSIWYG web builder;
      • or bassically any kind of SSG software;

    • added globals in window object window["virst"]["QUnique"] and window["virst"]["QFIFO"] so any library that, targets client side bundled and, are written using virst Lifecycle will share the same queue handler;

• comes with asyncQueue handler in the background;

  • no need to scratch your head too much for async processes;

• all of our class api are typed with jsdoc:

  • if you cannot find the documentation in this readme, you can allways rely on your IDE intellisense

about this readme

• this repo/lib only serves for api-documentation purposes;
• as for example on how to use on different useCase refer to html-first-virst

how to install

npm i virst
// or
bun i virst
// or any js package manager with npm capability

v0.^9.x

• drop supports for Animation

  • it's better to use more dedicated library like animeJS

v0.^12.x

• drop supports for Component
• uses native web component instead using WebComponent class
• it's a fix for Lifecycle behaviour and simple WebComponent generation class

v0.^15.x

• fixed Lifecycle scope mechanism
• added class attributeSelector to dynamically proportional binding conditionally by using signal value;

v0.^16.x

• semantics and fixes for onViewPort;

  • onViewPort will no longer be exported to virst main module;

exported-api-and-type-list

• Lifecycle

• Ping

• Q

• QueuedBlock

• $

• Derived

• Let

• List

• _

• App

• CRUD

• DefinePageTemplate

• DefineQRouter

• DefineShortCuts

• DefineStorage

• Event_

• For

• FSsrc

• helper

• ShortCut

• Try_

• virst

• WebComponent

• WorkerMainThread

• WorkerThread

  Lifecycle

• helper class to track connected/disconnected/attributeChanged of an element;

• instead of manually assigning whether attributeName should be global or not, outOffScoped attributeName will produce warning in the runtime;

  • you can ignore it, as the most local Lifecycle will take priority, and when there are no other scope, the most global will take place, the warning is only to notify that you can still optimize your code further by renaming the conflicting attributeName by abiding more to the semantics;

*) _{go to exported list}

Ping

trigger based callback integrated to the internal library queue handler; can be created using class instantiation;

*) _{go to exported list}

Q

helper methods for creating Promise to block execution code that return { resume } to allow subsequent calls to proceed;

const { resume } = await Q.fifo(); // or Q.unique(id)
// code
 resume(); // before return

*) _{go to exported list}

QueuedBlock

function wrapper that turns callback into queued calls;

*) _{go to exported list}

$

generate side effect for signal based reactivity such as for:

• Let

const letExample = new Let('')
new $(async(first)=>{
 const value = test.value;
 if(first){
     return;
     // return early if you want to opt out from handling the effect immediately,
     // also by doing this you can make the `$` slightly more performance 1) when dealing with `async await` on hydration,
     // such as data fetching;
 }
     // handle value
})
// 1) and when all of the effects is registered, you can call `letExample.call$` to call for effect in parallel;

• Derived

// bassically the same with `Let` but use `new Derived`

*) _{go to exported list}

Derived

• this class is extended from Let Let
• signal based reactivity, wich value are derived from reacting to Let<T>.value effects that are called in the asyncCallback this class instantiation;

// @ts-check
const letSingle = new Let(1);
const doubleExample = new Derived(async()=>{
    const value = letSingle.value; // autoscubscribed to `letSingle` value changes;
return value * 2; // returned value are to be derivedValue
});

• dataOnly:

const dataOnlyExample = Derived.dataOnly(asyncCallback);

• this will automatically opt you out from domReflector;

• make sure to check argument documentation in your IDE typeHint;

*) _{go to exported list}

Let

signal based reactivity; assigning newValue to Let insance:

• dataOnly:

const dataOnlyExample = Let.dataOnly(args0);

• with domReflector;

const letSingle = new Let(1, ...args);
letSingle.value++; // 2;
letSingle.value = 3 // 3;

• the domReflector will automatically synchronise the value with the element on the dom;

<div attributeName="...selectorsSeparatedBySemicolon"></div>

• selector can be attributeName or propertyName:

  • special selector value: will automatically bind the value with oninput event;
  • special selector class: will dynamically add/remove classes, must be formated like this {class: "strings of HTMLClassNames separated by space"}

*) _{go to exported list}

List

• helper class to create list that satisfy Array<Record<string, string>>

const listExample = new List([
     {key1: "test", ...keys},
     {key1: "test3", ...keys},
])

• usefull for loops;
• instance method: 'push'|'unshift'|'slice'|'splice'|'swap'|'modify'|'shift', serves as helper to mutate, and notify for signal for effects:

  • slice uses splice in the background, you don't need to manually reindex when using it;

*) _{go to exported list}

_

• auto attributeName assign for signal based reactifity stored in static Method of class _;
• if you use our Component class, use this class static method, instead of their respective class, for generating attributeName to watch, which then you can use it's attr returned value to mark the element

// on Component scope
onConnected(async()=>{
    const data = _.l('test');
    html`<div ${data.attr}="innerText"></div>`
})

*) _{go to exported list}

App

App starter helper for module environtment:

• the sole purpose is just to auto import the necessary global file in your main js file;
• if it's elementScoped instances/statics methods, it will be better to just leave it for the parentModule to import it accordingly;

/**
 * @typedef {Object} constructorOptions
 * - for efficiency, only fill this options when you intent to use the library as sole `View` part of your stack;
 * - the inputed root component must manually fills attr option argument, to target root element on the real dom;
 * @property {(import("../lifecycle/Lifecycle.mjs").Lifecycle)[]} [options.lifecycles]
 * @property {(import("./For.mjs").For)[]} [options.forS]
 * @property {import('./DefineShortCuts.mjs').DefineShortCuts} [options.defineShortcuts]
 * @property {import('./DefineQRouter.mjs').DefineQRouter} [options.defineQRouter]
 * @property {import('./DefinePageTemplate.mjs').DefinePageTemplate} [options.definePageTemplate]
 * @property {number} [options.pingDebounce]
 * in ms;
 * @property {import('./DefineStorage.mjs').DefineStorage} [options.defineStorage]
 * @property {typeof helper["webComponentGlobalStyles"]} [options.webComponentGlobalStyles]
 * @property {import('./FSsrc.mjs')} [options.defineFSSourceMapper]
 * use custom encoding(eg. base64) to replace original file's source path;
 * usefull when using `web-app` as `View` stack for `desktop-app`, `mobile-app` or other bundle target, removing the need to setup http server to display the file on the `browser`;
 */

*) _{go to exported list}

CRUD

CRUD wrapper class;

• signal will be updated from returned value of read;
• read will be called after calling thisInstance.create/update/delete_ that have true updateRead; /** @template V

*) _{go to exported list}

DefinePageTemplate

• instantiate this class to opt in page templating, by saving html template string on a html document page;
• html implementation:

// main page
<div ${templateName}="${path};${templateName};${mode}"></div>
// mode = 'inner' | 'outer'

• templateName of head & body are reserved for document.body and document.body of the template document, you can use it without adding targetAttribute="head" or targetAttribute="body" on the respective element;

// template document
<div ${targetAttribute}="${selector}"></div>

• how it works:

  • the class itself register a Lifecycle for templateName, which then upon connected, it will fetch the path then selects targetAttribute="selector" as template that then replace main page innerHTML with selected element innerHTML from template;
  • fetched page will be then be cached, along with any [targetAttribute] on that page

*) _{go to exported list}

DefineQRouter

allow the usage of search query based router through class instantiation;

• register by App.constructorOptions.defineQRouter

*) _{go to exported list}

DefineShortCuts

create shortcuts through class instantiation;

• register by App.constructorOptions.defineShortcuts

*) _{go to exported list}

DefineStorage

create named storage (localStorage or sessionStorage) through class instantiation;

• register by putting import this instance on your js main file

*) _{go to exported list}

Event_

use this instead of normal eventListener declaration for:

• creating autoqueued listener;
• autoScope _ static methods, inside Component scope;

// @ts-check
someObject.addEventListener('click', Event_.listener( (event) => {
// code
}))

*) _{go to exported list}

For

• assign element to loop through 'List' as data to render child element using class instantiation;
• loped childElement:

  • must have HTMLElement as first children;
  • only first children will be used to loop through List, all other children will be deleted from the dom before onConnected event of parentElement;

• use ListInstance method helpers to mutate the data;

*) _{go to exported list}

FSsrc

• use custom encoding(eg. base64) to replace original file's source path;
• usefull when using web-app as View stack for desktop-app, mobile-app or other bundle target, removing the need to setup http server to display the file on the browser;
• register by App.constructorOptions.defineFSSourceMapper

*) _{go to exported list}

helper

shared statics

*) _{go to exported list}

ShortCut

• helper class to create ShortCut through class instantiation;
• call thisInstance.ping to manually trigger action

*) _{go to exported list}

Try_

error as value helper; method(s):

• async;
• sync;

*) _{go to exported list}

virst

centralized virst object for lib making

*) _{go to exported list}

WebComponent

• native web component creation helper;
• you can add global css rules by inputing urls to AppInstantiation arg0.globalStyles;

*) _{go to exported list}

WorkerMainThread

helper class for registering and postMessage to webWorker

const worker = new WorkerMainThread(options);
worker.postMessage(message);

*) _{go to exported list}

WorkerThread

helper class to define web worker thread;

new WorkerThread({
    onMessage: ({ event, postMessage }) => {
        const message = undefined;
        // code to handle the message
        postMessage(message);
    },
});

*) _{go to exported list}