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 🙏

© 2024 – Pkg Stats / Ryan Hefner

@dadi/api-wrapper

v4.3.2

Published

A high-level library for interacting with DADI API

Downloads

170

Readme

DADI API wrapper

A high-level library for interacting with DADI API

npm (scoped) Coverage Status Build Status JavaScript Style Guide

Overview

DADI API is a high performance RESTful API layer designed in support of API-first development and the principle of COPE.

This library provides a high-level abstraction of the REST architecture style, exposing a set of chainable methods that allow developers to compose complex read and write operations using a simplistic and natural syntax.

Getting started

  1. Install the @dadi/api-wrapper module:

    npm install @dadi/api-wrapper --save
  2. Add the library and configure the API settings:

    const DadiAPI = require('@dadi/api-wrapper')
    const api = new DadiAPI({
      uri: 'http://api.example.com',
      port: 80,
      credentials: {
        clientId: 'johndoe',
        secret: 'f00b4r'
      },
      property: 'test'
    })
  3. Make a query:

    // Example: getting all documents where `name` contains "john" and age is greater than 18
    api
      .in('users')
      .whereFieldContains('name', 'john')
      .whereFieldIsGreaterThan('age', 18)
      .find()
      .then(response => {
        // Use documents here
      })

Methods

Each query consists of a series of chained methods to form the request, always containing a terminator method. Terminators return a Promise with the result of one or more requests to the database and can make use of a series of filtering methods to create the desired subset of documents to operate on.

Terminators

.apply(callback)

Updates a list of documents with the result of individually applying callback to them.

api
  .in('users')
  .whereFieldExists('gender')
  .apply(document => {
    document.name =
      document.gender === 'male'
        ? `Mr ${document.name}`
        : `Mrs ${document.name}`

    return document
  })

.create()

Creates a document.

// Example
api
  .in('users')
  .create({
    name: 'John Doe',
    age: 45,
    address: '123 Fake St'
  })
  .then(function(doc) {
    console.log('New document:', doc)
  })
  .catch(function(err) {
    console.log('! Error:', err)
  })

.delete()

Deletes one or more documents.

api
  .in('users')
  .whereFieldDoesNotExist('name')
  .delete()

.find(options)

Returns a list of documents.

api
  .in('users')
  .whereFieldIsGreaterThan('age', 21)
  .useFields(['name', 'age'])
  .find(options)

options is one of the following:

  • extractResults (Boolean): Selects whether just the results array should be returned, rather than the entire API response.
  • extractMetadata (Boolean): Selects whether just the metadata object should be returned, rather than the entire API response.

.getCollections()

Gets the list of collections for the API.

api.getCollections()

.getConfig()

Gets the config for a collection or for the API.

// Gets the collection config
api.in('users').getConfig()
// Gets the API config
api.getConfig()

.getLanguages()

Gets the list of languages supported by the API.

api.getLanguages().then(({metadata, results}) => {
  /*
    {
      "defaultLanguage": {
        "code": "en",
        "name": "English",
        "local": "English"
      },
      "totalCount": 2
    }  
  */
  console.log(metadata)

  /*
    [
      {
        "code": "en",
        "name": "English",
        "local": "English",
        "default": true
      },
      {
        "code": "pt",
        "name": "Portuguese",
        "local": "Português"
      }
    ]
  */
  console.log(results)
})

.getSignedUrl()

Gets a signed URL from a media collection.

api.in('images').getSignedUrl({
  fileName: 'foobar.jpg'
})

.getStats()

Gets collection stats.

api.in('users').getStats()

.getStatus()

Gets the the API status.

api.getStatus()

.update(update)

Updates a list of documents.

api
  .in('users')
  .whereFieldIsLessThan('age', 18)
  .update({
    adult: false
  })

Filters

Filtering methods are used to create a subset of documents that will be affected by subsequent operation terminators.

.goToPage(page)

Defines the page of documents to be used.

// Example
api.goToPage(3)

.limitTo(limit)

Defines a maximum number of documents to be retrieved.

// Example
api.limitTo(10)

.requireFeature(featureCode)

Queries the API for support of a given feature and throws a MISSING_FEATURES error if it's not supported.

// Example
api.requestFeature('aclv1')

.setSearchQuery(query)

Sets the query to use for a collection search.

// Example
api
  .in('users')
  .setSearchQuery('John')
  .find()

.sortBy(field, order)

Selects a field to sort on and the sort direction. Order defaults to ascending (asc).

// Example
api.sortBy('age', 'desc')

.useFields(fields)

Selects the fields to be returned in the response. Accepts array format.

// Example
api.useFields(['name', 'age'])

.useLanguage(language)

Sets the language to be used when querying. Accepts an ISO 639 language code in string format.

// Example
api.useLanguage('en')

.where(query)

Filters documents using a MongoDB query object or a Aggregation Pipeline array. The methods above are ultimately just syntatic sugar for where(). This method can be used for complex queries that require operations not implemented by any other method.

// Example
api.where({name: 'John Doe'})

.whereClientIs(value)

Applicable when in "client mode". Selects the client with ID equal to value.

// Example
api.inClients().whereClientIs('testClient')

.whereClientIsSelf()

Applicable when in "client mode". Selects the client associated with the bearer token being used.

// Example
api.inClients().whereClientIsSelf()

.whereFieldBeginsWith(field, text)

Filters documents where field begins with text.

// Example
api.whereFieldBeginsWith('name', 'john')

.whereFieldContains(field, text)

Filters documents where field contains text.

// Example
api.whereFieldContains('name', 'john')

.whereFieldDoesNotContain(field, text)

Filters documents field does not contain text.

// Example
api.whereFieldDoesNotContain('name', 'john')

.whereFieldEndsWith(field, text)

Filters documents where field starts with text.

// Example
api.whereFieldEndsWith('name', 'john')

.whereFieldExists(field)

Filters documents that contain a field.

// Example
api.whereFieldExists('name')

.whereFieldDoesNotExist(field)

Filters documents that do not contain a field.

// Example
api.whereFieldDoesNotExist('address')

.whereFieldIsEqualTo(field, value)

Filters documents where field is equal to value.

// Example
api.whereFieldIsEqualTo('age', 53)

.whereFieldIsGreaterThan(field, value)

Filters documents where field is greater than value.

// Example
api.whereFieldIsGreaterThan('age', 18)

.whereFieldIsGreaterThanOrEqualTo(field, value)

Filters documents where field is greater than or equal to value.

// Example
api.whereFieldIsGreaterThanOrEqualTo('age', 19)

.whereFieldIsLessThan(field, value)

Filters documents where field is less than value.

// Example
api.whereFieldIsLessThan('age', 65)

.whereFieldIsLessThanOrEqualTo(field, value)

Filters documents where field is less than or equal to value.

// Example
api.whereFieldIsLessThanOrEqualTo('age', 64)

.whereFieldIsOneOf(field, matches)

Filters documents where the value of field is one of the elements of matches.

// Example
api.whereFieldIsOneOf('name', ['John', 'Jack', 'Peter'])

.whereFieldIsNotEqualTo(field, value)

Filters documents where field is not equal to value.

// Example
api.whereFieldIsEqualTo('age', 53)

.whereFieldIsNotOneOf(field, matches)

Filters documents where the value of field is not one of the elements of matches.

// Example
api.whereFieldIsNotOneOf('name', ['Mark', 'Nathan', 'David'])

.whereHookNameIs(name)

Selects the hook with a given name.

// Example
api.whereFieldIsNotOneOf('name', ['Mark', 'Nathan', 'David'])

.withComposition(value)

Defines whether nested documents should be resolved using composition. The default is to let API decide based on the queried collection's settings.

// Example
api.withComposition()
api.withComposition(true) // same as above
api.withComposition(false)

Other methods

.fromEndpoint(endpoint)

Selects a custom endpoint to use. Please note that unlike collections, custom endpoints do not have a standardised syntax, so it is up to the authors to make sure the endpoint complies with standard DADI API formats, or they will not function as expected.

// Example
api.fromEndpoint('custom-endpoint')

.in(collection)

Selects the collection to use.

// Example
api.in('users')

.inClients()

Selects "client mode", meaning filters and terminators will operate on clients and not on documents.

// Example
api.inClients()

.inHooks()

Selects "hook mode", meaning filters and terminators will operate on hooks and not on documents.

// Example
api.inMedia('images')

.inMedia(bucket)

Selects a media bucket to be used.

// Example
api.inMedia('images')

.inProperty(property)

Selects the property to use. Overrides any property defined in the initialisation options, and is reset when called without arguments.

// Example
api.inProperty('test')