# API

# Generated Modules

# src/service-name/service-name.validate.?s

This module exports functions for validating data for that service name.

• Exports

  • {Object} create
  • {Object} update
  • {Object} patch
  • {Function} validateCreate
  • {Function} validateUpdate
  • {Function} validatePatch
  • {Function} quickValidate

• Example

Obtaining the JSON-schema.

const { create } = require('path/to/src/users/users.validate');
console.log(create);

{
    title: "Users",
    description: "Users database.",
    required: [
      "email",
      "firstName",
      "lastName"
    ],
    uniqueItemProperties: [],
    properties: {
      _id: {
        type: "string"
      },
      email: {
        type: "string"
      },
      firstName: {
        type: "string"
      },
      lastName: {
        type: "string"
      }
    }
  }

Configuring hooks.

const { validateCreate } = require('path/to/src/users/users.validate');
module.exports = {
  before: {
    create: validateCreate(),
  }
};  

Generic validation anywhere.

const { quickValidate } = require('path/to/src/users/users.validate');
const isValid = quickValidate(
  'create', { firstName: ..., lastName: ..., email: ... }, ajvOptions
);

• Details

  There are some good tutorials on using JSON-Schema with Ajv.

  The hook functions call the common hook validateSchema.

  There is no validation module for the service for the GraphQL endpoint.

# Service Adapters

# graphql

The custom service handling GraphQL requests.

• Arguments

  • {Object} options

• Example

// src/services/graphql/graphql.service.js
const createService = require('@feathers-plus/graphql');
// Feathers hooks like cli-generator-example/js-sequelize-services/src/services/graphql/graphql.hooks.js
const hooks = require('./graphql.hooks');
// GraphQL schema like .../services/graphql/graphql.schemas.js
const schemas = require('./graphql.schemas');
// GraphQL resolver functions like .../services/graphql/service.resolvers.js or .../services/graphql/batchloader.resolvers.js
const resolvers = require('./service.resolvers');

module.exports = function () {
  const app = this;

  let options = {
    schemas,
    resolvers,
  };

  const createdService = createService(options);
  app.use('/graphql', createdService);

  const service = app.service('/graphql');
  service.hooks(hooks);
};

// src/services/graphql/graphql.service.js
const createService = require('@feathers-plus/graphql');
// Feathers hooks like cli-generator-example/js-sequelize-sql/src/services/graphql/graphql.hooks.js
const hooks = require('./graphql.hooks');
// GraphQL schema like .../services/graphql/graphql.schemas.js
const schemas = require('./graphql.schemas');
// GraphQL resolver functions like .../services/graphql/sql.resolvers.js
const resolvers = require('./service.resolvers');
// join-monster metadata like .../services/graphql/sql.metadata.js
const sqlJoins = require('./sql.metadata');
// Module to execute raw SQL statements like .../services/graphql/sql.execute.sequelize.js or .../services/graphql/sql.execute.knex.js or .../services/graphql/sql.execute.custom.js
const sqlExecute = require('./sql.execute.sequelize');

module.exports = function () {
  const app = this;
  let { dialect, executeSql, openDb } = sqlExecute(app);

  if (!dialect) {
    throw new Error('services/graphql/sql.execute.js has not been configured.');
  }

  const options = {
    schemas,
    resolvers,
    sqlJoins,
    
    dialect,
    executeSql,
    openDb,
    logSql: false,
  };

  // Initialize our service with any options it requires.
  const createdService = createService(options);
  app.use('/graphql', createdService);

  const service = app.service('/graphql');
  service.hooks(hooks);
};

• Details

  The custom GraphQL schema type JSON is automatically added to (copies of) the schemas and resolvers options. It supports valid JSON values, allowing arguments like query: { dept: 'a' }.

  option may contain these optional properties.

  • {Array(String) | String} extraAuthProps - See context below.
  • {Function} openDB - Function will be called to open SQL database. Feathers will usually automatically open the database.

  These properties are added to (a clone of) options and passed to the GraphQL resolver function module.

  • convertArgsToFeathers
  • convertArgsToParams
  • convertArgsToOrderBy - creates SQL ORDER clause from GraphQL arguments.
  • convertArgsToWhere - creates SQL WHERE clause from GraphQL arguments.
  • extractAllItems
  • extractFirstItem
  • feathersBatchLoader
  • genAndRunSql
  • resolverTypes - resolver for JSON scalar type.
  • schemaTypes - schema for JSON scalar type.

  // .../services/graphql/service.resolvers.js or
  // .../batchloader.resolvers.js or 
  // .../sql.resolvers.js
  module.exports = function (app, options) { /* ... */ };
  

• context

  The content passed to the GraphQL resolver function calls contains

  • app - The Feathers app
  • provider - params.provider from the /graphql service call.
  • user - params.user from the /graphql service call.
  • authenticated - params.authenticated from the /graphql service call.
  • prop names contained in the extraAuthProps option - Taken from the same prop names in the /graphql service call.
  • batchLoaders - An object, initially empty, to cache BatchLoaders created for this GraphQL request.
  • cache - An object, initially empty, to cache the contents of select tables. For example, all the records in users would be cached if another table contains an array of foreign keys to it, e.g. the members table contains the array memberIds: [user1, user2, ...]. A cache is used as the Feathers common database API cannot select these records in users, so the cache is scanned to select them.
  Show GraphQL resolver function calls.

  // .../services/graphql/service.resolvers.js or .../batchloader.resolvers.js or .../sql.resolvers.js
  module.exports = function (app, options) {
    return {
      User: {
        comments:
          (parent, args, content, ast) => {
            const feathersParams = convertArgs(args, content, ast, {
              query: { authorUuid: parent.uuid, $sort: undefined }, paginate: false
            });
            return comments.find(feathersParams).then(extractAllItems);
          }
        },
       Query: {
         getUser(parent, args, content, ast) {
           const feathersParams = convertArgs(args, content, ast);
           return users.get(args.key, feathersParams).then(extractFirstItem);
         },
         findUser(parent, args, content, ast) {
           const feathersParams = convertArgs(args, content, ast, {
             query: { $sort: {   uuid: 1 } }
           });
           return users.find(feathersParams)
             .then(paginate(content)).then(extractAllItems);
         },        
       }  
    };
  
    function paginate(content) {
      return result => {
        content.pagination = !result.data ? undefined : {
          total: result.total,
          limit: result.limit,
          skip: result.skip,
        };
  
        return result;
      };
    }
  };
  

• Errors

  GraphQL swallows any other errors if it throws during initialization for a new request. That GraphQL error will be thrown as a Feathers BadRequest error.

  The service adapter will reformat other GraphQL errors so they are acceptable to Feathers. Specifically the Feathers message will identify the line number, column number and path in the GraphQL request of the first error detected by GraphQL.

  GraphQL errors

  GraphQL error messages can be obtuse.

# Utility Routines

These routines are used by the generated code handling GraphQL requests. You may be using them should you customize the generated code.

# convertArgsToFeathers

Returns a function which will convert the arguments in a GraphQL resolver call into the params for a Feathers service call.

• Arguments

  • {Array(String) | String} extraAuthPropNames

• Returns

  • {Function} argsToParamsFunction

• Example

// src/services/graphql/service.resolvers.?s or /batchloader.resolvers.?s
let moduleExports = function (app, { convertArgsToFeathers }) {
  const convertArgs = convertArgsToFeathers('isVerified');
  
  return {
    Role: {
      users: (parent, args, content, ast) => {
          const feathersParams = convertArgs(args, content, ast, {
            query: { roleId: parent._id, $sort: undefined }, paginate: false
          });
          return users.find(feathersParams).then(extractAllItems);
      },
    }
  };
}

• Details

  convertArgsToFeathers constructs the params for a Feathers service call containing

  • provider - context.provider from the GraphQL's service call,
  • user - context.user,
  • authenticated - context.authenticated,
  • graphql - The resolver path for the call,
  • query - args.query.
  • property values provided by moreParams,
  • property names specified by extraAuthPropNames.

# convertArgsToParams

Replace all property names starting with __ with ones starting with $.

• Arguments

  • {Object} obj

• Returns

  • {Object} $obj

• Example

// src/services/graphql/service.resolvers.?s or /batchloader.resolvers.?s
let moduleExports = function (app, { convertArgsToParams }) {
  console.log(
    convertArgsToParams({ a: 1, __b: { __c: 3, d: 4 } }) // { a: 1, $b: { $c: 3, d: 4 } }
  );
}

• Details

  This function is not directly called within the generated code. It is called by convertArgsToFeathers.

  A null or undefined object is returned as is.

# extractAllItems

Returns an array of the records returned by the service call.

• Arguments

  • {Object} serviceCallResult

• Returns

  • {Array(Object) | null} records

• Example

// src/services/graphql/service.resolvers.?s or /batchloader.resolvers.?s
let moduleExports = function (app, { extractAllItems }) {
  const userRecords = app.service('users').find()
    .then(result => extractAllItems(result));
}

• Details

  Returns an array of the records returned by the service call. The array may have 0 elements.

  null is returned if serviceCallResult or serviceCallResult.data is falsey.

# extractFirstItem

Returns the single record returned by the service call.

• Arguments

  • {Object} serviceCallResult

• Returns

  • {Object | null} record

• Example

// src/services/graphql/service.resolvers.?s or /batchloader.resolvers.?s
let moduleExports = function (app, { extractFirstItem }) {
  const userRecords = app.service('users').get(0)
    .then(result => extractFirstItem(result));
}

• Details

  Returns an array of the records returned by the service call. The array may have 0 elements.

  null is returned if serviceCallResult or serviceCallResult.data is falsey, or if there is no record.

  Throws if there are multiple records.

# feathersBatchLoader

Creates a batch-loader.

• Arguments

  • {String} resolverName}
  • {String} graphqlType
  • {String|Function} serializeRecordKey1
  • {Promise} getRecords
  • {Number} maxBatchSize
  • {Number} maxCacheSize
  • {String|Function} serializeBatchLoaderKey1

• Returns

  • {Function} batchLoader

• Example

// src/services/graphql/batchloader.resolvers.?s
let moduleExports = function batchLoaderResolvers(app, options) {
  let { convertArgsToFeathers, feathersBatchLoader: { feathersBatchLoader } } = options;
  
  const convertArgs = convertArgsToFeathers([]);
  const defaultPaginate = app.get('paginate');
  const maxBatchSize = defaultPaginate && typeof defaultPaginate.max === 'number' ?
      defaultPaginate.max : undefined;
  
  const roleUsersBatchLoader = feathersBatchLoader('Role.users', '[!]', 'roleId',
    keys => {
      const feathersParams = convertArgs(args, content, null, {
        query: { roleId: { $in: keys }, $sort: undefined },
        _populate: 'skip', paginate: false
      });
      return users.find(feathersParams);
    },
    maxBatchSize // Max #keys in a BatchLoader func call.
  );
}

# genAndRunSql

Runs a raw SQL statement.

• Arguments

  • {Function} execSql
  • {Object} jmOptions
  • {Object} options

• Returns

  • `{Function} callJoinMonster

• Example

// src/services/graphql/sql.resolvers.?s
let moduleExports = function sqlResolvers(app, options) {
  let { dialect, executeSql, genAndRunSql } = options;
  let genRunSql = genAndRunSql(executeSql, { dialect }, options);
  
  return {
    Query: {
      getUser: (parent, args, content, ast) => genRunSql(content, ast),
      findUser: (parent, args, content, ast) => genRunSql(content, ast)
    }
  };  
}