New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Change API of Model methods #177

Closed
jimlambie opened this Issue Jan 23, 2017 · 2 comments

Comments

Projects
4 participants
@jimlambie
Copy link
Member

jimlambie commented Jan 23, 2017

Currently API (v1.15.0) uses a callback approach when calling methods on the model, such as find(), update() and delete().

Requesting support for callbacks and Promises together.

@jimlambie jimlambie added in progress and removed help wanted labels Jan 31, 2017

@jimlambie jimlambie added this to Backlog in API Version 2 Feb 14, 2017

@jimlambie jimlambie added this to the 2.0.0 milestone Mar 5, 2017

@jimlambie jimlambie modified the milestones: 2.0.0, 3.0.0 May 31, 2017

@jimlambie jimlambie removed this from Backlog in API Version 2 May 31, 2017

@jimlambie jimlambie added this to Backlog in API Version 3.0 May 31, 2017

@eduardoboucas eduardoboucas changed the title Add Promise support to Model Change API of Model methods Jul 13, 2017

@eduardoboucas

This comment has been minimized.

Copy link
Member

eduardoboucas commented Jul 13, 2017

Repurposed the issue to include changing Model methods to use named parameters.

@eduardoboucas

This comment has been minimized.

Copy link
Member

eduardoboucas commented Mar 19, 2018

DADI API Model

To document:

  • Query options object
  • Metadata object
  • Stats object

The Model module is responsible for creating, storing and retrieving instances of entities represented in the data store. It exports two methods.

  • new(): creates a new model with the name, schema and settings passed as arguments

    Example:

    const Model = require('@dadi/api').Model
    const users = Model.new({
      name: 'users',
      fields: {
        field1: {
          type: 'String'
        }
      },
      settings: {
        displayName: 'List of users'
      },
      connection: optionalConnectionVar
    })
  • Main export: used to retrieve an existing instance of a given model, throwing an error if a model with the given name is not found

    Example:

    const users = Model('users')
    const otherModel = Model('doesNotExist') // Throws error

1. Operations

1.1. count

Counts the number of records matching a given query.

Parameters

  • query: the search query (default: {})
  • options: a query options object (default: {})

Return value

A Promise resolved with a metadata object.

Legacy

If the number of arguments is greater than one, the following sequence of arguments is used, calling any callback defined in done:

query, options, done

Example

const users = Model('users')

users.count({
  query: {
    age: 53
  }
}).then(result => {
  console.log('Count:', result.totalCount)
})

1.2. create

Inserts one or more documents.

Parameters

  • documents: an object if a single document is to be inserted, an array of objects for multiple
  • internals: an object containing meta (internal) fields to be added to the documents (default: {})
  • rawOutput: whether to by pass the formatting and sanitisation routines before outputing the data (default: false)
  • req: an instance of a Request object to be made available to hooks (default: undefined)

Return value

A Promise resolved with an array of documents inserted.

Legacy

If the number of arguments is greater than one, the following sequence of arguments is used, calling any callback defined in done:

documents, internals, done, req, bypassOutputFormatting

Example

const users = Model('users')

users.create({
  documents: [
    {name: 'John Doe'},
    {name: 'Jane Doe'}
  ],
  internals: {
    _createdBy: 'testClient'
  }
}).then(({metadata, results}) => {
  console.log('Created documents:', results)
})

1.3. createIndex

Creates database indexes for the fields defined in the index block of the collection schema.

Parameters

N/A

Return value

A Promise resolved with an array of indexes created, each containing a collection and index properties indicating the name of the collection and the name of the field that was indexes, respectively.

Legacy

If the number of arguments is greater than zero, the following sequence of arguments is used, calling any callback defined in done:

done

Example

const users = Model('users')

users.createIndex().then(result => {
  result.forEach(({collection, index}) => {
    console.log(`New index in collection ${collection}: ${index}`)
  })
})

1.4. delete

Deletes one or multiple documents.

Parameters

  • query: the search query (default: {})
  • req: an instance of a Request object to be made available to hooks (default: undefined)

Return value

A Promise resolved with an object with the properties deletedCount and totalCount, indicating the number of documents that were deleted by the operation and the new total number of documents remaining in the collection, respectively.

Legacy

If the number of arguments is greater than one, the following sequence of arguments is used, calling any callback defined in done:

query, done, req

Example

const users = Model('users')

users.delete({
  query: {
    _id: '59f1b4b8b339b85e713fdbb2'
  }
}).then(({deletedCount, totalCount}) => {
  console.log('Deleted documents:', deletedCount)
})

1.5. find

Retrieves documents from the database in their raw format, bypassing any formatting and sanitisation routines as well as hooks.

Parameters

  • query: the search query (default: {})
  • options: a query options object (default: {})

Return value

A Promise resolved with an object containing a metadata and results properties.

Legacy

If the number of arguments is greater than one, the following sequence of arguments is used, calling any callback defined in done:

query, options, done

Example

const users = Model('users')

users.find({
  query: {
    name: 'John Doe'
  }
}).then(({metadata, results}) => {
  console.log('Results:', results)
})

1.6. get

Retrieves documents from the database.

Parameters

  • query: the search query (default: {})
  • options: a query options object (default: {})
  • req: an instance of a Request object to be made available to hooks (default: undefined)

Return value

A Promise resolved with an object containing a metadata and results properties.

Legacy

If the number of arguments is greater than one, the following sequence of arguments is used, calling any callback defined in done:

query, options, done, req

Example

const users = Model('users')

users.get({
  query: {
    name: 'John Doe'
  },
  req
}).then(({metadata, results}) => {
  console.log('Results:', results)
})

1.7. getIndexes

Gets the current list of indexes.

Parameters

N/A

Return value

A Promise resolved with an array of index objects, each with a name property corresponding to the name of the index.

Legacy

If the number of arguments is greater than zero, the following sequence of arguments is used, calling any callback defined in done:

done

Example

const users = Model('users')

users.getIndexes().then(result => {
  console.log('Indexes:', result)
})

1.8. stats

Retrieves stats for the given collection.

Parameters

  • options: a query options object (default: {})

Return value

A Promise resolved with a stats object.

Legacy

If the number of arguments is greater than one, the following sequence of arguments is used, calling any callback defined in done:

options, done

Example

const users = Model('users')

users.stats().then(result => {
  console.log('Number of documents:', result.count)
})

1.9. update

Updates one or multiple documents.

Parameters

  • query: the search query (default: {})
  • internals: an object containing meta (internal) fields to be added to the documents (default: {})
  • options: a query options object (default: {})
  • rawOutput: whether to by pass the formatting and sanitisation routines before outputing the data (default: false)
  • req: an instance of a Request object to be made available to hooks (default: undefined)
  • update: an object containing the properties to be updated

Return value

A Promise resolved with an array of updated documents.

Legacy

If the number of arguments is greater than one, the following sequence of arguments is used, calling any callback defined in done:

query, update, internals, done, req, bypassOutputFormatting

Example

const users = Model('users')

users.update({
  query: {
    name: 'John Doe'
  },
  update: {
    name: 'John F. Doe'
  }
}).then(result => {
  console.log('Updated documents:', result)
})
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment