Téléchargement avalon - Téléchargement du code source avalon

Avalon

Micro-Framework JavaScript pour la création d'applications Web d'une seule page

Installer

Téléchargez les versions CJS, ESM, UMD ou installer via NPM:

npm install @ryanmorr/avalon

Usage

Avalon est une solution tout-en-un pour gérer l'état, le routage et les vues pour les applications Web:

 import avalon from '@ryanmorr/avalon' ;

const app = avalon ( {
    count : 0
} ) ;

app . mutation ( 'increment' , ( { count } ) => {
    return {
        count : count + 1
    } ;
} ) ;

app . action ( 'handleClick' , ( { commit } ) => {
    commit ( 'increment' ) ;
} ) ;

app . view ( parent , ( html , { count } , dispatch ) => html `
    < div >
        < p > Count: ${ count } </ p >
        < button onclick = ${ dispatch ( 'handleClick' ) } > Increment </ button >
    </ div >
` ) ;

Consultez l'exemple ToDomvc.

API

`avalon(state?)`

Créez une instance d'application avec un état initial en tant qu'objet clé / valeur simple. La propriété title est réservée au titre actuel du document, le modifiant mettra à jour automatiquement le titre du document:

 const app = avalon ( {
    title : 'Hello World' ,
    foo : 1 ,
    bar : 2
} ) ;

`mutation(name, callback)`

Définissez une mutation en fournissant un nom et une fonction de rappel qui change de manière synchrone en renvoyant un objet d'état partiel qui sera fusionné dans l'état d'application:

 app . mutation ( 'foo' , ( state , payload ) => {
    return {
        foo : payload
    } ;
} ) ;

`commit(name, payload?)`

Appelez une mutation pour mettre à jour l'état d'application en fournissant son nom et une charge utile en option, renvoie l'état partiel résultant de la mutation:

 app . mutation ( 'foo' , ( state , n ) => ( { foo : n + 10 } ) ) ;

app . commit ( 'foo' , 10 ) ; //=> {foo: 20}

`action(name, callback)`

Définissez une action en fournissant un nom et une fonction de rappel qui peut être utilisée pour répondre aux écouteurs d'événements DOM, effectuer des opérations asynchrones, répartir d'autres actions, commettre des mutations, etc. La fonction de rappel d'action reçoit un objet de données pertinentes et de fonctions de commodité comme premier paramètre:

 app . action ( 'foo' , ( { state , params , event , dispatch , commit , navigate , redirect , emit } ) => {
    /**
     * state - the current state of the app
     * params - key/value object provided to the dispatcher or null if not provided
     * event - the event object of user triggered DOM events or null if not applicable
     * commit - function for calling mutations
     * dispatch - function for dispatching actions or routes
     * navigate - function for navigating to a URL path and dispatching a route
     * redirect - function for redirecting to a URL path and dispatching a route
     * emit - function for emitting a custom event
     */
} ) ;

Pour mieux prendre en charge les opérations asynchrones, définissez un deuxième paramètre pour résoudre un appel (et éventuellement un troisième paramètre pour rejeter un appel) dans le cadre de la signature de la fonction de rappel d'action. L'envoi d'une action asynchrone renvoie automatiquement une promesse. Voici un exemple de la façon dont vous pourriez implémenter une action asynchrone pour récupérer les données du serveur:

 app . action ( 'load' , ( { params , commit } , resolve , reject ) => {
    commit ( 'isLoading' , true ) ;
    request ( '/get' , params ) . then ( ( data ) => {
        commit ( 'isLoading' , false ) ;
        commit ( 'setData' , data ) ;
        resolve ( data ) ;
    } ) . catch ( ( error ) => {
        commit ( 'isLoading' , false ) ;
        commit ( 'setError' , error ) ;
        reject ( error ) ;
    } ) ;
} ) ;

app . dispatch ( 'load' , { id : 'foo' } ) . then ( ( data ) => {
    // Handle data
} ) . catch ( ( error ) => {
    // Handle error
} ) ;

`route(path, callback)`

Les routes fonctionnent exactement comme les actions, sauf qu'elles répondent également aux modifications du chemin d'accès à l'URL, telles que les événements de clic déclenché par l'utilisateur et les soumis de formulaire, les appels programmatiques pour la navigate et redirect des méthodes, et pour aller de l'avant et vers l'arrière dans la pile d'historique de session. Un itinéraire doit être défini avec une barre basse avant:

 app . route ( '/' , ( { state , path , params , event , dispatch , commit , navigate , redirect , emit } ) => {
    /**
     * state - the current state of the app
     * path - the URL path that matched the route
     * params - key/value object extracted from a route's parameters or null if static path
     * event - the event object of user triggered DOM events or null if not applicable
     * commit - function for calling mutations
     * dispatch - function for dispatching actions or routes
     * navigate - function for navigating to a URL path and dispatching a route
     * redirect - function for redirecting to a URL path and dispatching a route
     * emit - function for emitting a custom event
     */
} ) ;

Les paramètres de support des routes, les paramètres facultatifs et les caractères génériques:

 // Matches routes like "/a/b/c" and "/x/y/z"
app . route ( '/:foo/:bar/:baz' , ( { params : { foo , bar , baz } } ) => {
    // Do something
} ) ;

// Matches routes like "/a/b" and "/a"
app . route ( '/:foo/:bar?' , ( { params : { foo , bar } } ) => {
    // Do something
} ) ;

// Matches routes like "/", "/a", and "/a/b/c"
app . route ( '/*' , ( { params : { wildcard } } ) => {
    // Do something
} ) ;

`dispatch(name?, params?)`

Envoyez une action avec des paramètres facultatifs ou un itinéraire. Si aucun argument n'est fourni, le chemin URL actuel est utilisé par défaut. Renvoie la valeur de retour de la fonction de rappel Action / Route ou une promesse s'il s'agit d'une action / itinéraire asynchrone.

 // Dispatch an action with parameters
app . dispatch ( 'foo' , { foo : 1 , bar : 2 } ) ;

// Dispatch the first matching route (parameters are extracted from the URL path)
app . dispatch ( '/foo/bar/baz' ) ;

// Dispatching an async action/route returns a promise
app . dispatch ( 'load' ) . then ( ( data ) => {
    // Do something
} )

`view(element, callback)`

Définissez une vue à rendre immédiatement rendu et automatiquement mis à jour via Virtual DOM lorsque l'état change. La fonction de rappel de vue est fournie un constructeur DOM virtuel via des modèles tagués, l'état actuel et une fonction de répartition pratique pour la répartition des actions et des itinéraires à la suite d'un écouteur d'événements DOM avec des paramètres facultatifs en tant qu'objet clé / valeur:

 app . view ( parentElement , ( html , state , dispatch ) => html `
    < div >
        < p > Name: ${ state . name } </ p >
        < button onclick = ${ dispatch ( 'handleClick' , { foo : 1 , bar : 2 } ) } > Increment </ button >
    </ div >
` ) ;

Vues Prise en charge des attributs / propriétés, des styles CSS comme une chaîne ou un objet, des écouteurs d'événements indiqués par un préfixe de "ON", des nœuds à clé pour des difficultés de liste efficaces et des composants fonctionnels sans état:

 const Item = ( html , props , dispatch ) => html `
    < li key = ${ props . id } onclick = ${ dispatch ( 'handleClick' , { id : props . id } ) } >
        ${ props . children }
    </ li >
` ;

app . view ( parentElement , ( html , state ) => html `
    < ul class =" list " >
        ${ state . items . map ( ( item ) => html `
            < ${ Item } id = ${ item . id } > ${ item . name } </ />
        ` ) }
    </ ul >
` ) ;

`navigate(path)`

Pousse une nouvelle entrée sur la pile d'historique avec le chemin d'url fourni et envoie le premier itinéraire correspondant. Renvoie la valeur de retour de la fonction de rappel d'itinéraire ou une promesse s'il s'agit d'un itinéraire asynchrone:

 app . route ( '/foo' , ( ) => 'bar' ) ;

app . path ( ) ; //=> "/"
history . length ; //=> 0

app . navigate ( '/foo' ) ; //=> "bar"

app . path ( ) ; //=> "/foo"
history . length ; //=> 1

`redirect(path)`

Remplace l'entrée historique actuelle par le chemin d'url fourni et envoie le premier itinéraire de correspondance. Renvoie la valeur de retour de la fonction de rappel d'itinéraire ou une promesse s'il s'agit d'un itinéraire asynchrone:

 app . route ( '/foo' , ( ) => 'bar' ) ;

app . path ( ) ; //=> "/"
history . length ; //=> 0

app . redirect ( '/foo' ) ; //=> "bar"

app . path ( ) ; //=> "/foo"
history . length ; //=> 0

`on(name, callback)`

Abonnez-vous aux événements d'application, renvoie une fonction pour supprimer cet écouteur spécifique:

 // Listen for state changes
app . on ( 'mutation' , ( name , nextState , prevState , partialState ) => {
    // Do something
} ) ;

// Listen for when an action/route is dispatched
app . on ( 'dispatch' , ( type , state , name , params , event , returnValue ) => {
    // Do something
} ) ;

// Listen for when the URL path changes
app . on ( 'pathchange' , ( path ) => {
    // Do something
} ) ;

// Listen for when a view has been rendered
app . on ( 'render' , ( parentElement ) => {
    // Do something
} ) ;

// Define your own custom event with parameters
const stop = app . on ( 'foo' , ( a , b , c , d ) => {
    // Do something
} ) ;

// Stop listening for custom event
stop ( ) ;

`emit(name, ...args?)`

Déclencher un événement personnalisé avec des arguments facultatifs:

 app . on ( 'foo' , ( a , b , c , d ) => {
    // Do something
} ) ;

app . emit ( 'foo' , 1 , 2 , 3 , 4 ) ;

`state()`

Obtenez l'objet d'état actuel:

 const app = avalon ( {
    title : 'Hello World'
    foo : 1 ,
    bar : 2
} ) ;

app . state ( ) ; //=> {title: "Hello World", foo: 1, bar: 2}

`path()`

Obtenez le chemin de l'URL actuel:

 app . navigate ( '/foo' ) ;

app . path ( ) ; //=> "/foo"

`use(plugin)`

Ajoutez un plugin en fournissant une fonction de rappel qui est immédiatement invoquée avec l'instance d'application et l'état actuel. Renvoie la valeur de retour de la fonction de rappel du plugin:

 // A simple logging plugin
const log = app . use ( ( app , state ) => {
    const events = [
        'mutation' ,
        'dispatch' ,
        'pathchange' ,
        'render'
    ] ;
    events . forEach ( ( name ) => app . on ( name , console . log . bind ( console , name ) ) ) ;
    return console . log . bind ( console , 'avalon' ) ;
} ) ;