cycle-web-extensions
TypeScript icon, indicating that this package has built-in type declarations

0.5.1 • Public • Published

cycle-web-extensions

Cycle.js drivers to use in Chrome extensions and WebExtensions.

Forked from cycle-extensions to rewrite it with xstream. Additionally support for the tabs and windows APIs was added, and the MessagesDriver now supports more than one simultaneous connection.

Drivers

MessagesDriver

In the Web Extension architecture, logic and state both live in a long-running background page. The user interface lives in a separate page called a popup. The two pages communicate by passing messages between each other. The background page awaits connections; the popup initiates them.

messagesDriver accepts a stream of messages to send to the other page and returns a stream of messages received from the other page.

makeMessagesDriver takes a single named argument, shouldInitiate. Set it to false in the background page and true in any other pages.

Here's an example of a simple counter. Notice that when the popup opens, it sends a request for the current state to the background page. The response it receives creates the first frame of DOM.

import { run } from '@cycle/run'
import xs from 'xstream'
import sampleCombine from 'xstream/extra/sampleCombine'
 
import {
    makeMessagesDriver,
    newMessage,
    pickType,
} from 'cycle-web-extensions'
 
function Background({ messages: messages$ }) {
    const initialState = { count: 0 }
 
    const state$ = messages$.reduce(
        (state, message) => {
            if (message.type === 'increment') { return { ...state, count: state.count + 1 } }
            if (message.type === 'decrement') { return { ...state, count: state.count - 1 } }
            return state
        },
        initialState,
    )
 
    return {
        messages: xs.merge(
            state$.map(state => newMessage(['state_changed', state])),
            pickType(messages$, 'current_state_requested')
                .compose(sampleCombine(state$))
                .map(([, state]) => newMessage(['state_changed'], state))
            ),
    }
}
 
run(
    Background,
    { messages: makeMessagesDriver({ shouldInitiate: false }) },
)
 
// and in your popup script
import {
    makeMessagesDriver,
    newMessage,
} from 'cycle-web-extensions'
import { button, div } from 'hyperscript-helpers'
 
function Popup({ DOM, messages: messages$ }) {
    const count$ = pickType(messages$, 'state_changed')
        .map(payload => payload.count) // Why no pluck in xstream?
 
    return {
        messages: xs.merge(
            DOM.select('.increment').events('click').mapTo(newMessage(['increment'])),
            DOM.select('.decrement').events('click').mapTo(newMessage(['decrement'])),
        ).startWith(newMessage('current_state_requested')),
        DOM: count$.map(
            count => (
                div([
                    `The count is now ${count}.`,
                    div([button('.decrement', ['-1']), button('.increment', ['+1'])]),
                ])
            ),
        ),
    }
}
 
function intent(DOM) {
    const increment$ = DOM.select('.increment').events('click')
        .mapTo(newMessage(['increment']))
    const decrement$ = DOM.select('.decrement').events('click')
        .mapTo(newMessage(['decrement']))
 
    return {
        messages: xs.merge(increment$, decrement$)
            .startWith(newMessage(['current_state_requested'])),
    }
}
 
run(
    Popup,
    {
        DOM: makeDOMDriver('#root'),
        messages: makeMessagesDriver({ shouldInitiate: true }),
    },
)

WindowsDriver

  • TODO: Document this

TabsDriver

  • TODO: Document this

To see a real extension written with these drivers, check out nspaeth/tab-manager.

Installation

yarn add cycle-web-extensions

License

Apache 2.0

Package Sidebar

Install

npm i cycle-web-extensions

Weekly Downloads

1

Version

0.5.1

License

Apache-2.0

Unpacked Size

55.6 kB

Total Files

11

Last publish

Collaborators

  • spaethnl