virst v0.12.8

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 domReflect (using attributeName="...attributeValues;");

    • optional templating using:

      • html page based template;
      • our Component instances;

  • 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;

• 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

• $

• App

• Component

• CRUD

• DefinePageTemplate

• DefineQRouter

• DefineShortCuts

• DefineStorage

• Derived

• documentScope

• Event_

• For

• Let

• Lifecycle

• lifecycleHandler

• List

• Ping

• ShortCut

• Try_

• WorkerMainThread

• WorkerThread

• _

*) 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

*) go to exported list

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;

*) go to exported list

*) go to exported list

component creation helper using class initiation; behaviour:

• it rendered directly to real DOM;

  • library like bootstrap css and it's js parts can select your elements for it's functionality;
  • you have to manually scope your style by

// on Component scope
html`<style>
	[${thisInstance.attr}]{
		...nestedCSSRules
	}
</style>
...
`

• also you might need to explicitly use ">" directChildOf selector, as when you try to render childComponent
• it could also be accidentally selected;
• render method:
• you put returned value of thisInstance.attr on an html element, which
• it will be rendered as it's innerHTML at the onConnected event, then
• it will used MutationObserver to look for changes;

*) go to exported list

*) go to exported list

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 refreshSignal; /** @template V

*) go to exported list

*) go to exported list

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

// main page
<div ${templateName}="${path};${selector}"></div>

// 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 element with selected element from template;
  • fetched page will be then be cached, along with any [targetAttribute] on that page

*) go to exported list

*) go to exported list

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

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

*) go to exported list

*) go to exported list

create shortcuts through class instantiation;

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

*) go to exported list

*) go to exported list

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

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

*) go to exported list

*) go to exported list

• 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

*) go to exported list

type helper for documentScope

*) go to exported list

*) go to exported list

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

*) go to exported list

• 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

*) go to exported list

signal based reactivity; assigning newValue to Let insance:

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

dataOnly:

const dataOnlyExample = Let.dataOnly(args0);

• methods:

  • call$: manually triggers effects subscribed to thisInstance;
  • remove$: unubscribe thisInstance from specific effect;
  • removeAll$: unubscribe thisInstance from all of its effects;

*) go to exported list

*) go to exported list

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

*) go to exported list

*) go to exported list

type helper for lifecycleHandler & attributeChangedLifecycle

*) go to exported list

*) go to exported 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

*) go to exported list

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

*) go to exported list

*) go to exported list

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

*) go to exported list

*) go to exported list

error handling helper; method(s):

• async;
• sync;

*) go to exported list

*) go to exported list

helper class for registering and postMessage to webWorker

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

*) go to exported list

*) go to exported list

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

*) 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