gulp-exist
A gulp plugin to deploy to and query an eXist-db using eXist's XML-RPC API.
Prerequisites
In order to make use of gulp-exist
you will need to have
gulp installed (in version 4 or later).
And a running existdb instance, of course (version 4.7.1 or higher recommended).
Installation
In your project folder run
npm install --save-dev gulp @existdb/gulp-exist
Usage
Then create a file with the name gulpfile.js
in the root of your project with the following contents
const gulp = exist = // authenticate against local eXist instance for development const connectionOptions = basic_auth: user: "admin" pass: "" const exClient = exist // deploy all { return gulp
Now, gulp deploy
will store all files in the build
directory to
/db/apps/myapp collection in eXist.
Also note, that non-existing collections and sub-folders will be created automatically for you.
Have a look at the example gulpfile for a more complete gulpfile offering more advanced tasks.
API
exist.createClient(options)
Returns a set of functions to interact with an eXist-db instance. What you can do is dependent on the permissions of the user specified in the connection options.
NOTE: The connection options are passed through to the XMLRPC client library. So it might be possible to use different authentication methods or to pass in more options than mentioned below as long as your eXist-db installation understands them.
Options
host
Type: string
Default: 'localhost'
port
Type: number
Default: 8080
path
Path to eXist's XML-RPC endpoint
Type: string
Default: '/exist/xmlrpc'
basic_auth
The credentials used to authenticate requests. What you can and cannot do depends on the permissions this user has.
Type: Object
Default:
user: 'guest' pass: 'guest'
secure
Use HTTPS to connect to the database instance. Needs a valid certificate installed in the keystore of exist.
Type: Boolean
Default: false
Example
const exClient = exist
existClient.dest(options)
Uploads input files to a target collection in eXist.
Options
target
Remote deployment target collection. Non-existent collections will be created.
Type: string
Default '/db'
html5AsBinary
When set to true, any HTML file that cannot be parsed as valid XML, will be uploaded as a binary file instead. HTML5 documents tend to be non well-formed XML.
Formerly binary_fallback
.
NOTE: Binary documents can not be indexed and therefore are also not
searchable by the eXist-db. This option is only useful for template files.
Type: boolean
Default: false
permissions
Specify remote permissions for files as path-permission pairs.
Type: Object{path: permissions}
Default: {}
'.secrets/key': 'rwx------' 'controller.xql': 'rwxr-xr-x'
Example
const src = const createClient = // override defaultsconst exist = { return } exportsdefault = deployWithPermissions
existClient.install(options)
Options
packageUri
The unique package descriptor of the application to be installed.
customPackageRepoUrl
The application repository that will be used to resolve dependencies. Only needs to be set if the default repository cannot be used.
Example
const src = const createClient = // override defaultsconst exist = // this MUST be the unique package identifier of the XAR you want to install const packageUri = 'http://exist-db.org/apps/test-app' { return }
existClient.newer(options)
Filters the input stream for files that are newer than their remote counterpart.
Options
target
Which collection to compare the local files to.
Example
Only upload modified files.
const src = const createClient = // override some default connection optionsconst exist = const target = '/db/apps/myapp/' // the collection to write toconst html5AsBinary = true // upload HTML5 templates as binary { return ;} exportsdefault = deployNewer
existClient.query(options)
Execute input files as XQuery on the server.
The input files will not be stored in eXist but read locally and executed
directly. The query results will be logged in the console (can be disabled by
setting printXqlResults
to false
). For each input file, the result
of the query will also be emitted as an output file that can optionally be
copied into a local directory for logging. Timestamps will be appended to the
filename. The filename extension of the output files can be controlled with
xqlOutputExt
(default is xml
).
Query options
printXqlResults
Whether to print the results of executed XQuerys to console.
Type: boolean
Default: true
xqlOutputExt
The filename extension that will be used for XQuery result files emitted by
exist.query()
. Possible values are 'xml' or 'json'.
Type: string
Default: 'xml'
Example
Upload a collection index configuration file and re-index the collection
scripts/reindex.xq
xquery version "3.1";declare option exist:serialize "method=json media-type=text/javascript"; map { "success": xmldb:reindex('/db/apps/myapp/data') }
gulpfile.js
const src dest = const createClient = // override some default connection optionsconst exist = const queryConfig = target: '/db/apps/myapp' xqlOutputExt: 'json' { return } { return } exportsdefault =
Define Custom Mime Types
Override the mime type used to store files in exist based on their extension.
defineMimeTypes
just exposes mime.define()
.
NOTE: attempt to redefine a registered extension will throw an error.
Extended by default:
'application/xquery': 'xq' 'xquery' 'xqs' 'xql' 'xqm' 'application/xml': 'xconf' 'odd'
Type: Object {mimetype: [extensions]}
Example
exist
More examples
Have a look at the example gulpfile.
Watch File Changes
watch
will report when a file has changed. deployBuild
will run
each time that happens uploading all files that have changed since its
last execution.
const watch src dest lastRun = const createClient = // override defaultsconst connectionOptions = basic_auth: user: "admin" pass: "" const exist = { return } exportsdeploy = deployBuild { ;}exportswatch = watchBuild exportsdefault =
Create and Install XAR Archive
const src dest = zip = pkg = createClient = // override some default connection optionsconst exist = { return ;} { return } exportsdefault =
Test
Prerequisites
A running instance of eXist-db v2.2+ at localhost port 8080 with an admin user that has a blank password.
Run the Tests
npm test