basex-standalone

Process data using XQuery with BaseX in standalone mode.

Getting Started

Install the module with: npm install basex-standalone

 
var basex = require('basex-standalone');
 
// prints '1 2 3 4 5 6 7 8 9 10'
basex({xquery: '1 to 10'}, function(error, data){
    if(e) throw e
    else console.log(data) 
})

Or create a partial to set individual defaults

 
var basex = require('basex-standalone');
 
var b = basex.partial({
    debug: true,
    basexpath: '/tmp/basex'
})
 
// prints '/tmp/basex/data'
b({
    serializer: { method: 'text' },
    xquery: 'db:system()/mainoptions/dbpath/text()'
}, function(error, data){
    if(e) throw e
    else console.log(data) 
})

Documentation

BaseX includes a fast, feature-rich XQuery processor that can juggle json, xml, csv and other data easily and provides powerful document manipulation facilities by implementing the XQuery Update specification.

For more information about BaseX, what you can do with it, and how to do it, read through the excellent documentation on docs.basex.org

This module acts as a simple wrapper around BaseX's Standalone Mode passing arguments via cli and reading back stdout/stderr output.

Tip: For better performance, prefer Command Scripts over sequential invocations (ie multiple ADD, SET commands)

Usage

Use buffered output by passing a callback

 
var basex = require('basex')
 
basex({xquery: '1 to 10', function(error, data){
    if(e) throw e
    else console.log(data) 
})

or directly access the ChildProcess:

 
var basex = require('basex')
 
var custom = basex.partial({classpath: 'path/to/basex.jar'})
 
var cp = custom({xquery: '1 to 10'})
 
cp.stdout.pipe(process.stdout)

Partials

Partials are a convenience to facilitate with default options handling.

 
var basex = require('basex-standalone')
 
var partial = basex.partial({debug: true, newlines: true})
 
partial('1 to 10')
partial('test.xql')

`basex.partial(defaults)`

Returns: Function

Returns a partially applied function that will always use the provided options as defaults.

`partial(options, callback)`

Returns: ChildProcess

Calling the partial will execute an operation.

Options

Options are converted to BaseX standalone arguments. For better understanding of these arguments see Startup Options.

Options object is also passed on to child_process.spawn() more

`run`

Type: String

Default value: ''

The actual operation to run.

Similar to RUN command. docs

Note: run argument will directly evaluate as XQuery by BaseX if it doesn't point to a file. It is preferable to use the option.xquery in order to evaluate XQuery code.

`java`

Type: String

Default value: /usr/bin/env java

Java executable to use.

`classpath`

Type: String|Array

Default value: null

CLASSPATH definition to be used by Java more.

In order for the module to work java needs access to org.basex.BaseX class.

Download the latest version from here

Alternatively org.basex.BaseX class must be available to java system-wide (i.e. by setting the CLASSPATH environment variable).

Other useful files to include to the classpath are:

tagsoup For HTML parsing
saxon For XSLT transforms and XSD validations

`basexpath`

Type: String

Default value: null

Path for BaseX Home Directory

Note that all file paths in commands / script etc remain relative to node's cwd

Examples

Modify a document in-place using xquery

basex({
    input: 'path/to/some/file.xml',
    update: true,
    xquery: 'for $a in //a return replace value of node $a/@href with "#test"'
})
.then(function(data){
    // Updating xquery expressions have no output
})

Execute an XQuery script file to query a folder with multiple xml files

basex({
    input: 'path/to/some/dir',
    run: 'path/to/some/script.xql'
})
.then(function(output){
    console.log(output)
})

Execute a BaseX Command Script to batch-process json and xml data

<!-- some/command/script.bxs  -->
<commands>
    <info/>
    <create-db name="test"/>
    <add path="test.xml">some/file.xml</add>
    <set option="parser">json</set>
    <set option="createfilter">*.json</set>
    <add>somedir/with/json/files</add>
    <xquery>
    <![CDATA[
        for $book in //json/book
            let $author = $book//author
            group by $author/@id
            return 
            <author books="{{count($book)}}">{{$author/text()}}</author>"
 
     ]]>
     </xquery>
    <drop-db name="test"/>
<commands>

basex('some/command/script.bxs', function(error, data)
        if(e) throw e
        else console.log(data)
    })

Release History

1.4.0 - basex.Job moved to it's own module 1.3.0 - Lets the user handle the classpath 1.2.0 - Simplify API and drop Q dependency 1.1.0 - Include jar via downloading upon installation 1.0.2 - fix order of required modules 1.0.1 - fix multiple values for options.classpath 1.0.0 - First Official Release