@fxjs/handbag NPM

👝 @fxjs/handbag

Pre-requisite

fibjs >= 0.26.0

Usage

npm install @fxjs/handbag

Sample

const fxHandbag = require('@fxjs/handbag')

const fpug = require('fib-pug')
function registerPugAsHtml (vbox) {
    const compilerOptions = {
        filters: {
            typescript: require('jstransformer-typescript').render,
            stylus: require('jstransformer-stylus').render,
        }
    }

    fxHandbag.vboxUtils.setCompilerForVbox(vbox, {
        suffix: '.pug',
        compiler: (buf, info) => fxHandbag.vboxUtils.wrapAsString(
            fpug.renderFile(info.filename, compilerOptions)
        )
    })
}

const vm = require('vm')

vbox = new vm.SandBox(moduleHash)
registerPugAsHtml(vbox)

// just require one pug as rendered html string
const renderedHtml = vbox.require('./test.pug', __dirname)

you can also do like this:

const compilerOptions = {
    filters: {
        typescript: require('jstransformer-typescript').render,
        stylus: require('jstransformer-stylus').render,
    }
}

const vbox = new vm.SandBox(moduleHash)
fxHandbag.registers.pug.registerPugAsHtml(vbox, { compilerOptions })

const renderedHtml = vbox.require('./test.pug', __dirname)

APIs

vboxUtils

vboxUtils is some basic operation for one vbox generated by new vm.SandBox(...)

setCompilerForVbox(vbox: Class_SandBox, options: SetCompilerForVBoxOptions)

set one compiler function for vbox, the compiler is used for vbox.setModuleCompiler.

interface SetVboxOptions {
    suffix: string|string[],
    compiler: Function,
    compile_to_iife_script?: boolean
}

registers

Common Option

{
    // compilerOptions passed to render of register.
    compilerOptions: {...},
    // timeout that module keep required file id,
	// - if it is 0, keep module always
	// - if it is lower than 0, it would NIRVANA after remove it, that means module required would be updated after burnout_timeout.
    burnout_timeout: {...}
}

Register: Plain

plain.registerAsPlain(vbox, options)

options.suffix: default ['.txt']

Register: Pug

pug.registerPugAsRender(vbox, options)

options.suffix: default ['.pug', '.jade']

pug.registerPugAsHtml(vbox, options)

options.suffix: default ['.pug', '.jade']

Register: Stylus

stylus.registerStylusAsCss(vbox, options)

options.suffix: default ['.styl', '.stylus']

Register: Typescript

required dependencies

typescript

typescript.registerTypescriptAsModule(vbox, options)

options.suffix: default ['.ts']

typescript.registerTypescriptAsPlainJavascript(vbox, options)

options.suffix: default ['.ts']

Package Register: Rollup

rollup.registerAsModule(vbox, options)

options.suffix: default ['.ts', '.tsx']
options.rollup

extra dependencies

rollup.registerAsPlainJavascript(vbox, options)

options.suffix: default ['.ts', '.tsx']
options.rollup

extra dependencies

Register: Vue

vue.registerVueAsRollupedJavascript(vbox, options)

options.suffix: default ['.vue']
options.rollup
options.rollupPluginVueOptions: default {}, options passwd to rollup-plugin-vue
options.transpileLib: default 'babel'
- any value equals to false: no transpile
- 'babel': transpile component with babel
- 'buble': transpile component with buble

NOTICE it's not recommend use async/await in vue component, if you do so, the transpiled vue component's size would be large.

it would compile vue component js to 'es5' by default. If <script lang="ts"> set, it always transpile component js with typescript

extra dependencies

fib-rollup
rollup-plugin-commonjs
rollup-plugin-vue
rollup-plugin-buble (if use options.transpileLib="buble")
rollup-plugin-typescript (if use lang="ts")
- tslib
- typescript

Register: React

react.registerReactAsRollupedJavascript(vbox, options)

started from 0.2.7

options.suffix: default ['.ts', '.jsx', '.tsx']
options.rollup
options.transpileLib: default 'babel'
- any value equals to false: no transpile
- 'babel': transpile component with babel
- 'buble': transpile component with buble

NOTICE it's not recommend use async/await in react component, if you do so, the transpiled vue component's size would be large.

extra dependencies

fib-rollup
rollup-plugin-commonjs
rollup-plugin-buble (if use options.transpileLib="buble")
rollup-plugin-typescript (if support suffix .ts, .tsx)
- tslib
- typescript

Register: Riot

riot.registerRiotAsJs(vbox, options)

started from 0.2.3

options.suffix: default ['.tag', '.tsx']
options.compress_js: default true

Register: Image

image.registerImageAsBase64(vbox, options)

options.suffix: default ['.png', '.jpg', '.jpeg', '.gif', '.bmp']

Register: GraphQL

graphql.registerGraphQLParser(vbox, options)

started from 0.2.4

options.suffix: default ['.gql', '.graphql']

extra dependencies

graphql.registerGraphQLAsQueryBuilder(vbox, options)

started from 0.2.4

options.suffix: default ['.gql', '.graphql']

// index.js
graphql.registerGraphQLAsQueryBuilder(vbox)

vbox.require('./foo.gql')({foo: 'bar'}) // result is { q1(foo: 'bar'){} }

// foo.gql
{ q1(foo: $foo){} }

common options

`registerOptions.compilerOptions`

options passed to register's compiler/transpilor/renderer, view details in specified register

`registerOptions.hooks`

there's one emitter option with EventEmitter type in registerOptions, all key in registerOptions.hooks would be registered as emitter's event_name with handler from registerOptions.hooks[key], e.g:

{
	...
	hooks: {
		before_transpile: (payload) => {
			// print required file's information
			console.log(payload.info)
		},
		generated: (payload) => {
			// change content from every file required by this Sandbox to 'always online'
			payload.result = 'always online'
		}
	}
	...
}

supported hooks

before_transpile - param payload.raw: original content's buffer - param payload.info: file information
generated: payload: {result} - param payload.result: transpiled content

`registerOptions.rollup`

There's register based on rollup, its registerOptions has those options:

options.rollup.bundleConfig: default {}, config passed to
- const bundle = rollup.rollup({...})
options.rollup.writeConfig: default {}, config passed to
- bundle.write({...})
- bundle.generate({...})
options.rollup.onGenerateUmdName: default (buf, info) => 's'. generate name for rollup's umd/iife mode

`registerOptions.burnout_timeout`

In some cases, we want vbox to remove required module by ID after burnout_timeout.

For example, you are developing one website's user profile page, which rendered from path/user-profile.pug, you serve it with http.Server and mq.Routing, and require the pug file as require('path/user-profile.pug', __dirname) with special vbox generated by registers in @fxjs/handbag or by your own manual registering. You change the pug file, then you wish the next calling to require('path/user-profile.pug', __dirname) would return the latest file resource. So, you need remove the required content every other times(such as 300ms), which is burnout_timeout.

All reigsters's option in @fxjs/handbag supports burnout_timeout option.

NOTICE

nirvana

if burnout_timeout set as Integer lower than 0, after one module(with moduleId mid) removed from Sandbox(that would happend after burnout_timeout), it would be require right away. e.g.

non-nirvana mode:

: user: burnout_timeout = 200
: user: sandbox.require(mid)
: ---> burnout_timeout gone...
: sandbox.remove(mid)
: user: sandbox.require(mid)

nirvana mode:

: user: burnout_timeout = -200
: user: sandbox.require(mid)
: ---> burnout_timeout gone...
: sandbox.remove(mid) and sandbox.require(mid)

20ms

In general, there's time-range about lower than 20ms(it's tested) when you require one file as plain via registered box in @fxjs/handbag, but it would over 20ms in these cases: