Utilities

callingParams

Build params for a service call.

Arguments
- {Object} options

Argument	Type	Default	Description
`options`	`Object`		How to construct params for service call.

`options`	Argument	Type	Default
`query`	`Object`		The `params.query` for the calling params.
`propNames`	`Array< String >`	`[]`	The names of the props in `context.params` to include in the new params.
`newProps`	`Object`	`{}`	Additional props to add to the new params.
`hooksToDisable`	`Array< String >`	`[]`	The names of hooks to disable during the service call. `populate`, `fastJoin`, `softDelete` and `stashBefore` are supported.
`ignoreDefaults`	`Boolean`		Ignore the defaults `propNames` and `newProps`.

Returns
- {Function}
- Arguments
- {Object} context

Argument	Type	Default	Description
`context`	`Object`		The `context` of the hook which will make the service call.

Returns
- {Object} newParams

Name	Type	Description
`newParams`	`Object`	The params for the service call.

Example

const { callingParams, callingParamsDefaults } = require('feathers-hooks-common');
// Authentication props to always copy. Suitable for feathers-authentication-management.
callingParamsDefaults(['provider', 'authenticated', 'user', 'isVerified']);

async function myCustomHook(context) {
  // ...
  const result = await service.find(callingParams({
    query: { { id: { $in: [1, 2, 3] } } },
    propNames: ['customProp'],
    newProps: { mongoose: ... },
    hooksToDisable: 'populate'
  }))(context);
  // ...
}

Details
When calling another service within a hook, consideration must be given to what the params should be for the called service. For example, should the called service see that a client is making the call, or the server? What authentication and authorization information should be provided? You can use this convenience function to help create that params.
The properties provider, authenticated and user are the standard authentication properties used by Feathers. They are copied automatically.
These defaults and others can be changed app-wide by calling the callingParamsDefaults utility.

callingParamsDefaults

Set defaults for building params for service calls with callingParams.

Arguments
- {Array< String >} propNames
- {Object} newProps

Argument	Type	Default	Description
`propNames`	`Array< String >`		The names of the props in `context.params` to automatically include in the new params.
`newProps`	`Object`		Additional props to add to the new params.

Example

const { callingParams, callingParamsDefaults } = require('feathers-hooks-common');
// Authentication props to always copy. Suitable for feathers-authentication-management.
// Only hooks will be calling `callingParams`. Set a flag so other hooks recognize such a call.
callingParamsDefaults(['provider', 'authenticated', 'user', 'isVerified'], { _calledByHook: true });

async function myCustomHook(context) {
  // ...
  const result = await service.find(callingParams({
    query: { { id: { $in: [1, 2, 3] } } },
    propNames: ['customProp'],
    newProps: { mongoose: ... },
    hooksToDisable: 'populate'
  }), context);
  // ...
}

Details
When calling another service within a hook, consideration must be given to what the params should be for the called service. For example, should the called service see that a client is making the call, or the server? What authentication and authorization information should be provided? You can use this convenience function to help create that params.
The properties provider, authenticated and user are the standard authentication properties used by Feathers. They are copied automatically.
These defaults and others can be changed app-wide by calling the callingParamsDefaults utility.

checkContext

Restrict a hook to run for certain methods and method types.

Arguments
- {Object} context
- {String | Array< String >} [ type ]
- {String | Array< String >} [ methods ]
- {String} [ label ]

| Argument | Type | Default | Description | | --------- | :------: | ---------------- | --------------------------------- | --------------------------------------------------------------- | | context | Object | | The hook context. | | type | String | Array< String > | all types | The service type allowed - before, after, error. | | methods | String | Array< String > | all methods | The service methods allowed - find, get, update, patch, remove. | | label | String | 'anonymous' | Name of hook to use with throw. |

Example

const { checkContext } = require('feathers-hooks-common');

function myHook(context) {
  checkContext(context, 'after', ['create', 'remove']);
  ...
}

module.exports = { before: {
    create: [ myHook ] // throws
} };

// checkContext(hook, 'before', ['update', 'patch'], 'hookName');
// checkContext(hook, null, ['update', 'patch']);
// checkContext(hook, 'before', null, 'hookName');
// checkContext(hook, 'before');

Details
Its important to ensure the hook is being used as intended. checkContext let's you restrict the hook to a hook type and a set of service methods.

combine

Sequentially execute multiple sync or async hooks.

before	after	methods	multi	details
yes	yes	all	n/a	source

Arguments
- {Array< Function >} hookFuncs

Argument	Type	Default	Description
`hookFuncs`	`Array<Function >`		Hooks, used the same way as when you register them.

Example

const { combine, createdAt, updatedAt } = require('feathers-hooks-common');

async function myCustomHook(context) {
  const newContext = await combine(setNow('createdAt'), setNow('updatedAt')).call(this, context);
  return newContext;
}

Details
combine has the signature of a hook, but is primarily intended to be used within your custom hooks, not when registering hooks.

The following is a better technique to use when registering hooks.

const workflow = [createdAt(), updatedAt(), ...];

module.exports = { before: {
  update: [...workflow],
  patch: [...workflow],
} };

every

Return the and of a series of sync or async predicate functions.

before	after	methods	multi	details
yes	yes	all	yes	source

Arguments
- {Array< Function >} predicates

Argument	Type	Default	Description
`predicates`	`Array< Function >`		Functions which take the current hook as a param and return a boolean result.

Returns

{Boolean} result

Name	Type	Description
result	Boolean	The logical and of predicates

Example

const { iff, every } = require('feathers-hooks-common');

module.exports = { before: {
    create: iff(every(hook1, hook2, ...), hookA, hookB, ...)
} };

Details
every is a predicate function for use in conditional hooks. The predicate functions are run in parallel, and true is returned if every predicate returns a truthy value.

getItems

Get the records in context.data or context.result

Arguments
- {Object} context

Argument	Type	Default	Description
`context`	`Object`		The hook context.

Returns

{Array< Object > | Object | undefined} records

| Name | Type | Description | | ------- | --------------- | ----------- | --------- | ------------ | | records | Array< Object > | Object | undefined | The records. |

Example

const { getItems, replaceItems } = require('feathers-hooks-common');

const insertCode = code => context => {
  const items = getItems(context);
  if (Array.isArray(items)) {
    items.forEach(item => {
      item.code = code;
    });
  } else {
    items.code = code;
  }
  replaceItems(context, items);
};

module.exports = {
  before: {
    create: insertCode('a')
  }
};

Details
getItems gets the records from the hook context: context.data (before hook) or context.result[.data] (after hook).

isNot

Negate a sync or async predicate function.

before	after	methods	multi	details
yes	yes	all	yes	source

Arguments
- {Function | Boolean} predicate

Argument	Type	Default	Description
`predicate`	`Function` `Boolean`		A sync or async function which take the current hook as a param and returns a boolean result.

Returns

{Boolean} result

Name	Type	Description
result	Boolean	The not of predicate

Example

const { iff, isNot, isProvider, discard } = require('feathers-hooks-common');
const isRequestor = () => context => new Promise(resolve, reject) => ... );

module.exports = { after: {
    create: iff(isNot(isRequestor()), discard('password'))
} };

Details
isNot is a predicate function for use in conditional hooks.

isProvider

Check which transport provided the service call.

before	after	methods	multi	details
yes	yes	all	yes	source

Arguments
- {Array< String >} transports

Name	Type	Default	Description
`transports`	`Array< String >`		The transports you want to allow.

`transports`	Value	Description
`socketio`	Allow calls by Socket.IO transport.
`rest`	Allow calls by REST transport.
`external`	Allow calls other than from server.
`server`	Allow calls from server.

Returns

{Boolean} result

Name	Type	Description
result	Boolean	If the call was made by one of the transports.

Example

const { iff, isProvider, discard } = require('feathers-hooks-common');

module.exports = {
  after: {
    create: iff(isProvider('external'), discard('password'))
  }
};

Details
isProvider is a predicate function for use in conditional hooks. Its determines which transport provided the service call by checking context.params.provider.

makeCallingParams

Build context.params for service calls.

Tip: You should prefer using the callingParams utility to makeCallingParams.

Arguments
- {Object} context
- {Object} [ query ]
- {Array< String > | String} [ include ]
- {Object} [ inject ]

Argument	Type	Description
`context`	`Object`	The existing hook context.
`query`	`Object`	The `context.params.query` for the new context.
`include`	`Array< String >`	The names of the props in `context` to include in the new context.
`inject`	`Object`	Additional props to add to the new context.

Returns
- {Object} newContext

Variable	Type	Default	Description
`newContext`	`Object`		The new context created.

Example

const { makeCallingParams } = require('feathers-hooks-common');

async function myCustomHook(context) {
  // ...
  const result = await service.find(makeCallingParams(
    context, { id: { $in: [1, 2, 3] } }, 'user',
    { _populate: false, mongoose: ... }
  ));
  // ...
}

Details
When calling another service within a hook, consideration must be given to what the context.params should be for the called service. For example, should the called service see that a client is making the call, or the server? What authentication and authorization information should be provided? You can use this convenience function to help create that context.params.
The value context.params._populate: 'skip' is automatically added to skip any fastJoin or populate hooks registered on the called service. Set it to false, like in the example above, to make those hooks run.

paramsForServer

Pass an explicit context.params from client to server. Client-side.

Arguments
- {Object} params
- {Array< String >} [ whitelist ]

Argument	Type	Default	Description
`params`	`Object`		The `context.params` to use for the service call, including any query object.
`whitelist`	dot notation	all props in `context.params`	Names of the props in `context.params` to transfer to the server. This is a security feature. All props are transferred if no `whitelist` is provided.

Example

// client
const { paramsForServer } = require('feathers-hooks-common');

service.update(
  id,
  data,
  paramsForServer({
    query: { dept: 'a' },
    populate: 'po-1',
    serialize: 'po-mgr'
  })
);

// server
const { paramsFromClient } = require('feathers-hooks-common');

module.exports = {
  before: {
    all: [paramsFromClient('populate', 'serialize', 'otherProp'), myHook]
  }
};

// myHook's `context.params` will now be
// { query: { dept: 'a' }, populate: 'po-1', serialize: 'po-mgr' } }

Details
By default, only the context.params.query object is transferred from a Feathers client to the server, for security among other reasons. However you can explicitly transfer other context.params props with the client utility function paramsForServer in conjunction with the paramsFromClient hook on the server.
This technique also works for service calls made on the server.
The data is transfered using `context.params.query.$client`. If that field already exists, it must be an Object.

replaceItems

Replace the records in context.data or context.result[.data].

Arguments
- {Object} context
- {Array< Object > | Object} records

Argument	Type	Default	Description
`context`	`Object`		The hook context.
`records`	`Array< Object >` `Object`		The new records.

Example

const { getItems, replaceItems } = require('feathers-hooks-common');

const insertCode = code => context {
  const items = getItems(context);
  if (Array.isArray(items)) {
    items.forEach(item => { item.code = code; });
  } else {
    items.code = code;
  }
  replaceItems(context, items);
};

module.exports = { before: {
  create: insertCode('a')
} };

Details
replaceItems replaces the records in the hook context: context.data (before hook) or context.result[.data] (after hook).

runHook

Let's you call a hook right after the service call.

Arguments
- {Object} [ hookContext ]
- {Function} hookFunc

Argument	Type	Default	Description
`hookContext`	`Object`	`{}`	The `context` for `hookFunc`.
`hookFunc`	`Function`		The hook to run.

Example

const { keep, runHook } = require('feathers-hooks-common');

user.get(...)
  .then( runHook()(keep('name', 'address.state')) )
  .then(data => ...); // [{ name: 'Marshall', address: { state: 'UT' }}]

const data = await user.get(...);
const result = await runHook()(data)(keep('name', 'address.state'));

const { fastJoin, runHook } = require('feathers-hooks-common');
const runHookFinds = runHook({ app: app, method: 'find' });

const paymentsRecords = [
  { _id: 101, amount: 100, patientId: 1 },
  { _id: 102, amount: 105, patientId: 1 },
  { _id: 103, amount: 110, patientId: 1 },
  { _id: 104, amount: 115, patientId: 2 },
  { _id: 105, amount: 120, patientId: 3 },
  { _id: 106, amount: 125, patientId: 3 }
];
await payments.create(paymentsRecords);

const patientsRecords = [
  { _id: 1, name: 'John' },
  { _id: 2, name: 'Marshall' },
  { _id: 3, name: 'David' }
];
await patients.create(patientsRecords);

const paymentResolvers = {
  joins: {
    patient: () => async payment => {
      payment.patient = (
        await patients.find({
          query: {
            id: payment.patientId
          }
        })
      )[0];
    }
  }
};

await payments
  .find()
  .then(runHookFinds(fastJoin(paymentResolvers)))
  .then(data => console.log(data));

// log
[
  { _id: 101, amount: 100, patientId: 1, patient: { _id: 1, name: 'John' } },
  { _id: 102, amount: 105, patientId: 1, patient: { _id: 1, name: 'John' } },
  { _id: 103, amount: 110, patientId: 1, patient: { _id: 1, name: 'John' } },
  {
    _id: 104,
    amount: 115,
    patientId: 2,
    patient: { _id: 2, name: 'Marshall' }
  },
  { _id: 105, amount: 120, patientId: 3, patient: { _id: 3, name: 'David' } },
  { _id: 106, amount: 125, patientId: 3, patient: { _id: 3, name: 'David' } }
];

Details
Hooks are normally registered for a service, e.g. in project/src/services /posts/posts.hooks.js. This is nice and simple when, for example, all the find hooks have to run for every find call.
The conditional hooks can be used when hooks have to be conditionally run based on the current environment. For example, we can discard the password field when the call is made by a client.
However things are not always so straightforward. There can be that one call for which we want to join specific records. We could add a conditional hook that runs just for that one call, however we may soon find ourselves with a second and a third special case.
runHook is designed for such cases. Instead of having to register a conditioned hook, it allows us to run the hook in a .then() right after the service call.

some

Return the or of a series of sync or async predicate functions.

before	after	methods	multi	details
yes	yes	all	yes	source

Arguments
- {Array< Function >} predicates

Argument	Type	Default	Description
`predicates`	`Array< Function >`		Functions which take the current hook as a param and return a boolean result.

Returns

{Boolean} result

Name	Type	Description
result	Boolean	The logical or of predicates

Example

const { iff, some } = require('feathers-hooks-common');

module.exports = { before: {
    create: iff(some(hook1, hook2, ...), hookA, hookB, ...)
} };

Details
some is a predicate function for use in conditional hooks. The predicate functions are run in parallel, and true is returned if any predicate returns a truthy value.

Utilities ​

callingParams ​

callingParamsDefaults ​

checkContext ​

combine ​

every ​

getItems ​

isNot ​

isProvider ​

makeCallingParams ​

paramsForServer ​

replaceItems ​

runHook ​

some ​

Utilities

callingParams

callingParamsDefaults

checkContext

combine

every

getItems

isNot

isProvider

makeCallingParams

paramsForServer

replaceItems

runHook

some