node-exist
Mostly a shallow wrapper for eXist's XML-RPC API. Attempts to translate terminologies into node world. Uses promises.
Install
npm install @existdb/node-exist
Use
Creating, reading and removing a collection:
const {connect} = require('@existdb/node-exist')
const db = connect()
db.collections.create('/db/apps/test')
.then(result => db.collections.describe('/db/apps/test'))
.then(result => console.log('collection description:', result))
.catch(e => console.error('fail', e))
Uploading an XML file into the database
const {connect} = require('@existdb/node-exist')
const db = connect()
db.documents.upload(Buffer.from('<root/>'))
.then(fileHandle => db.documents.parseLocal(fileHandle, '/db/apps/test/file.xml', {}))
.then(result => db.documents.read('/db/apps/test/file.xml'))
.then(result => console.log('test file contents', result))
.catch(error => console.error('fail', error))
Since all interactions with the database are promises you can also use async functions
const {connect} = require('@existdb/node-exist')
const db = connect()
async function uploadAndParse (filePath, contents) {
const fileHandle = await db.documents.upload(contents)
await db.documents.parseLocal(fileHandle, filePath, {})
return filePath
}
// top-level await is not available everywhere, yet
uploadAndParse('/db/apps/test-file.xml', Buffer.from('<root/>'))
.then(filePath => console.log("uploaded", filePath))
.catch(error => console.error(error))
You can now also import node-exist into an ES module
import {connect} from '@existdb/node-exist'
const db = connect()
// do something with the db connection
db.collections.describe('/db/apps')
.then(result => console.log(result))
You can also have a look at the examples for more use-cases.
Configuration
Connect as someone else than guest
exist.connect({
basic_auth: {
user: 'me',
pass: '1 troubadour artisanal #compost'
}
})
Connect to a local development server using HTTP
exist.connect({ secure: false, port: 8080 })
Connect to a server with an invalid or expired certificate
exist.connect({ rejectUnauthorized: false })
Read configuration from environment variables
readOptionsFromEnv
offers an comfortable way to read the connection options
from a set of environment variables
variable name | default | description |
---|---|---|
EXISTDB_USER |
none | the user used to connect to the database and to execute queries with |
EXISTDB_PASS |
none | the password to authenticate the user against the database |
EXISTDB_SERVER |
https://localhost:8443 |
the URL of the database instance to connect to (only http and https protocol allowed) |
const {connect, readOptionsFromEnv} = require('@existdb/node-exist')
const db = connect(readOptionsFromEnv())
For more details you can have a look how it is used in the connection script that is used for testing and in all example scripts and the examples.
Defaults
{
host: 'localhost',
port: '8443',
path: '/exist/xmlrpc', // you most likely do not need to change that
basic_auth: {
user: 'guest',
pass: 'guest'
},
secure: true
}
Components
The methods are grouped into components by what they operate on. Every method returns a promise.
Queries
Status: working
execute
db.queries.execute(query, options)
read
db.queries.read(query, options)
readAll
This convenience function calls queries.count then retrieves all result pages and returns them in an array.
db.queries.readAll(query, options)
Example:
const query = `xquery version "3.1";
xmldb:get-child-collections($collection)
=> string-join(",\n")
`
const options = { variables: collection: "/db/apps" }
db.queries.readAll(query, options)
.then(result => {
const response = Buffer.concat(result.pages).toString()
console.log(response)
})
.catch(error => console.error(error))
count
db.queries.count(resultHandle)
retrieve
db.queries.retrieveResult(resultHandle, page)
retrieveAll
db.queries.retrieveAll(resultHandle)
releaseResult
free result on server
db.queries.releaseResult(resultHandle)
Documents
A document can be seen as a file. It might be indexed if it's type is not binary.
upload
Resolves into a file handle which can then be used by db.documents.parseLocal
.
db.documents.upload(Buffer.from('test'))
parseLocal
db.documents.parseLocal(fileHandle, 'foo/test.txt', {})
read
db.documents.read('foo.xml')
remove
db.documents.remove('foo.xml')
Resources
Status: working
A resource is identified by its path in the database. Documents and collections are resources.
describe
db.resources.describe(resourcePath)
setPermissions
db.resources.setPermissions(resourcePath, 400)
getPermissions
db.resources.getPermissions(resourcePath)
Collections
Status: working
create
db.collections.create(collectionPath)
remove
db.collections.remove(collectionPath)
describe
db.collections.describe(collectionPath)
read
db.collections.read(collectionPath)
existsAndCanOpen
This function checks if the collection exists and if it does, if the current user can access it.
- returns
true
if the collection exists and the current user can open it - returns
false
if the collection does not exist - throws an exception if the collection exists but the current user cannot access it
db.collections.existsAndCanOpen(collectionPath)
App
Status: working
upload
After uploading a XAR you can install it
db.app.upload(xarBuffer, xarName)
Example:
const xarContents = fs.readFileSync('spec/files/test-app.xar')
db.app.upload(xarContents, 'test-app.xar')
.then(result => console.log(result))
.catch(error => console.error(error))
install
Install an uploaded XAR (this will call repo:install-and-deploy-from-db
).
For extra safety a previously installed version will be removed before
installing the new version.
Dependencies will be resolved from http://exist-db.org/exist/apps/public-repo
by default.
If you want to use a different repository provide the optional customPackageRepoUrl
.
db.app.install(xarName[, customPackageRepoUrl])
Example:
db.app.install('test-app.xar')
.then(result => console.log(result))
.catch(error => console.error(error))
Returns
{
"success": true,
"result": {
"update": false, // true if a previous version was found
"target": "/db/apps/test-app"
}
}
Error
{
success: false,
error: Error
}
remove
Uninstall and remove the application identified by its namespace URL.
If no app with packageUri
could be found then this counts as success.
db.app.remove(packageUri)
Example:
db.app.remove('http://exist-db.org/apps/test-app')
.then(result => console.log(result))
.catch(error => console.error(error))
Returns
{ success: true }
Error
{
success: false,
error: Object | Error
}
packageCollection
The path to the collection where node-exist will upload
packages to (/db/pkgtmp
). Useful for cleanup after
succesful installation.
Example:
db.documents.remove(`${db.app.packageCollection}/test-app.xar`)
Indices
Status: TODO
Users
Status: working
getUserInfo
Will return the information about the given user.
db.users.getUserInfo(username)
Example:
db.users.getUserInfo('admin')
Returns:
{
uid: 1048574,
'default-group-id': 1048575,
umask: 18,
metadata: {
'http://exist-db.org/security/description': 'System Administrator',
'http://axschema.org/namePerson': 'admin'
},
'default-group-name': 'dba',
'default-group-realmId': 'exist',
name: 'admin',
groups: [ 'dba' ],
enabled: 'true'
}
list
db.users.list()
Returns an array of user info objects (see getUserInfo()).
server
Status: working
syncToDisk
db.server.syncToDisk()
shutdown
db.server.shutdown()
Note: There is no way to bring it up again.
Command Line Scripts
You can use this library to interact with local or remote existdb instances on the command line. You can find a few basic examples in this repository.
To give you a taste all example scripts are exposed as binaries in the node_modules/.bin folder when you install this package.
You can run them using npx
npx -p @existdb/node-exist exist-ls /db/apps
If you want you can even install this package globally and then use these scripts like ls
or cd
.
npm install -g @existdb/node-exist
Now you can type
exist-ls /db/apps
anywhere on the system.
Test
All tests are in spec/tests and written for tape
npm test
NOTE: You can override connection settings with environment variables. See examples for more information.
To execute a single run using a different server you can also just define the variable directly:
EXISTDB_SERVER=http://localhost:8888 npm test
Roadmap
- switch to use eXist-db's REST-API.
- refactor to ES6 modules
- better type hints
Compatibility
node-exist is tested to be compatible with eXist-db 4, 5 and 6. It should be compatible with version 3, except for the XAR installation.
Disclaimer
Use at your own risk.
This software is safe for development. It may be used to work with a production instance, but think twice before your data is lost.