[Docs] Incorrect callback arguments in PersistedModel#findOrCreate

[Jhoanegar]

Hi, I was reading the docs and I found that the documentation for the findOrCreate method in PersistedModel is wrong. It states that the callback function has 2 arguments, error and instance, as you can see here.
http://apidocs.strongloop.com/loopback/v/2.14.0/#persistedmodel-findorcreate

According to my tests, the callback function actually gets three arguments, (error, created, instance), where created is true if the instance was just created or false if it was found.

I'm using loopback's version 2.14.0 but, unless the signature changed in the latest version, I see the same mistake in the latest docs. That or I'm overlooking something.

Keep the awesome work.
Cheers.

[kevintechie]

Actually, the order of the arguments in the callback is (err, instance, created).

[superkhau]

@Jhoanegar Did @kevintechie resolve your issue? is this good to close?

[crandmck]

This is still an issue: https://apidocs.strongloop.com/loopback/v/2.25.0/#persistedmodel-findorcreate

[alankyshum]

Having exactly the same issue, and this issue is quite frustrating, as I expect instance to be null if not found and new record is inserted. Please update the doc 😄

Tested on loopback 2.25.0

[crandmck]

@superkhau Can you confirm that the callback function gets three arguments, (error, created, instance), where created is true if the instance was just created or false if it was found.
If, so I'll update the docs accordingly.

Unfortunately, it's not clear to me from the source code.

[superkhau]

findOrCreate(query, data, cb) - https://github.com/strongloop/loopback/blob/master/lib/persisted-model.js#L127

@Jhoanegar @kevintechie @alankyshum Which connectors are you guys using? Can you guy provide sample projects for me to confirm the issue on my end? I need to verify the bug based on your specific use cases.

[kevintechie]

The issue is not the findOrCreate signature, but rather the parameters passed to the callback.

I have included some sample code that demos the callback parameters. The code initializes database tables and then adds a user.

I've used the variable name user in place of instance in the callback parameters.

'use strict';
var async = require('async');
var server = require('./../server');
var log = require('debug')('boot:sample-data');
var ds = server.dataSources.mysqlDs;

var lbTables = [ 'accessToken', 'ACL', 'RoleMapping', 'Role', 'UserCredential', 'UserIdentity', 'User' ];

var User = server.models.User;

var initialUser = {
  email:       'testuser@example.com',
  password:    'test123',
  username:    'testuser',
  active:      true
};

async.series([

  function (next) {

    ds.automigrate(lbTables, function (er) {
      if (er) {
        throw er;
      }

      log('Looback tables [' + lbTables + '] created in ', ds.adapter.name);

      next(null, 'created tables');
    });
  },

  function (next) {

    User.findOrCreate(
      { where: { email: initialUser.email } },
      initialUser,
// callback
      function (err, user, created) {
        if (err) {
          throw err;
        }

        created ? log('created user:', user) : log('found user:', user);
        next(null, 'created user data');

      }
    );
  },

  function (next) {
    ds.disconnect();
    next(null, 'closed db');
  }
]);

I'm using the MySql database connector in this code, but I've also used the in-memory database and have the same experience.

[kevintechie]

I believe the callback is called in the loopback-datasource-juggler; specifically lines 672 through 685.:

https://github.com/strongloop/loopback-datasource-juggler/blob/80c3bd9d419e501d5b7beb0a623c8b1eaefdc258/lib/dao.js#L599

Specifically lines 672 through 685.

[noderat]

JSdoc for PersistedModel should be updated to reflect that the callback accepts 3 arguments error(Error), instance(obj), and created(bool). The JSdoc in loopback-data-source-juggler is correct.

Confirmed syntax with loopback-datasource-juggler 2.44.0

Example:

app.models.user.findOrCreate(
  { where: { username: 'foo' } },  // Where filter
  { username: 'foo', password: 'bar' },  // Data to insert
  function(error, instance, created) {  // Callback
    if (error) throw error;
    if (created) {
      console.log('Object already exists: \n', instance);
    } else {
      console.log('Already existed.');
    }
  });

Edit: Clarified 'where filter for queries' and indicated that documentation for PersistedModel is outdated, not loopback-datasource-juggler.

[noderat]

Created #1983 to update documentation

[crandmck]

Thanks for the PR, @noderat. Apparently this fell through the cracks and never got moved out of triage.