npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2022 – Pkg Stats / Ryan Hefner

@existdb/node-exist

v4.9.1

Published

promise based interaction with eXist DB's XML-RPC API

Downloads

217

Readme

node-exist

semantic release status js-standard-style

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 exist = require('@existdb/node-exist')
const db = exist.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 exist = require('@existdb/node-exist')
const db = exist.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 exist = require('@existdb/node-exist')
const db = exist.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 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.