feathers-hooks-common

You can perform recursive operations by nesting joins within a resolver. To do this, the resolver function must return the data that is to be recursively operated on.

Syntax for Recursive Joins:

comments: {
  resolver: (args) => async (record) => {
    record.comments = await service.find(...);
    return record.comments; // CRITICAL: Must return the data to be operated on
  },
  joins: {
    author: ... // This will operate on the returned comments
  }
}

const postResolvers = {
  joins: {
    comments: {
      resolver: ($select, $limit, $sort) => async post => {
        post.comments = await comments.find({
          query: { postId: post.id, $select: $select, $limit: $limit || 5, [$sort]: { createdAt: -1 } },
          paginate: false
        });
        return post.comments; // Return the comments so the nested 'joins' can run on them
      },
      joins: {
        author: $select => async comment => {
          comment.author = (await users.find({
            query: { id: comment.userId, $select: $select },
            paginate: false
          }))[0];
        }
      }
    }
  }
};

In fastJoin, the joins object defines the operations to perform on each record. Each key in joins represents a property name used in the query to control execution.

Resolver Structure:

• joins: {}: Defines the operations.
• property_name:: The name of the field to be added/modified.
• (...args) =>: Allows passing parameters from the query to the resolver.
• async (record, context) => ...: The resolver function receives the record and the Feathers context. It must modify the record (e.g., post.author = ...).

Querying and Shaping Results:

• Shaping: The query object determines which resolvers run. If a property is not in the query, the resolver for that property is skipped, and the field will not appear in the result.
• Parameters: You can pass arrays to the query to provide arguments to the resolver (e.g., $select fields).
• Dynamic Queries: Use context => query to allow the client to control which fields are joined.

// Shaping the result with a query
const query = {
  author: true, // Only runs the 'author' resolver
  starers: [['id', 'name']] // Runs 'starers' and passes ['id', 'name'] as $select
};

module.exports = {
  after: {
    all: [fastJoin(postResolvers, context => query)]
  }
};

You can share validation logic between your front-end and back-end by exporting validation functions from a common module. The validate hook can execute these functions on the server.

• Synchronous Validation: A function that takes values and returns an errors object. If the object is empty, validation passes. If it contains keys, those keys represent the field names and values represent the error messages.
• Asynchronous Validation: A function that returns a Promise. Resolve with null if validation passes (or with sanitized values), and reject with a Feathers error if validation fails.

This pattern ensures that the exact same rules applied to the user in the browser are enforced by the server.

// /common/usersClientValidations

// Sync validation: returns an object of errors
clientValidations.signup = values => {
  const errors = {};
  if (!values.email) errors.email = 'Email is required.';
  return errors;
};

// Async validation: returns a Promise
clientValidations.signupAsync = values =>
  new Promise((resolve, reject) => {
    const errs = {};
    // Logic to check if email is taken...
    if (emailTaken) {
      errs.email = 'Already taken.';
      // Reject with an error object containing the field errors
      return reject(new errors.BadRequest('Values already taken.', { errors: errs }));
    }
    resolve(null);
  });

In Feathers, hooks typically mutate context.data (for before hooks) or context.result (for after hooks). This is the 'default' behavior.

actOnDispatch allows you to run a series of hooks that instead mutate context.dispatch. context.dispatch is an optional, writable property that contains a "safe" version of the data intended for clients (e.g., via REST or Socket.io). If context.dispatch is not set, Feathers sends context.result to the client instead.

actOnDefault is used to "undo" actOnDispatch by running hooks that mutate the standard context.data or context.result instead of the dispatch object. This allows for nested hook execution where some hooks target the client-facing data and others target the internal service data.

```js
const { actOnDefault, actOnDispatch } = require('feathers-hooks-common');

module.exports = {
  after: {
    find: [
      hook1(), 
      actOnDispatch(
        hook2(), 
        actOnDefault(hook3()), 
        hook4()
      ), 
      hook5()
    ]
  }
};

In this example:

• hook1, hook3, and hook5 mutate context.result (default behavior).
• hook2 and hook4 mutate context.dispatch.

By default, BatchLoaders use a per-request cache. To share cached records across different requests, use a persistent cache (like @feathers-plus/cache) with your BatchLoader.

Requirements:

1. Create a CacheMap (e.g., using CacheMap({ max: 100 })).
2. Pass the cacheMap to the BatchLoader options.
3. Crucial: The cache hook must be registered in both the before and after hooks of the service to ensure both reads and writes are cached.

When configured correctly, the number of service calls for subsequent requests can drop to 0.

const { cache, fastJoin, makeCallingParams } = require('feathers-hooks-common');
const BatchLoader = require('@feathers-plus/batch-loader');
const CacheMap = require('@feathers-plus/cache');

const cacheMapUsers = CacheMap({ max: 100 });

const userBatchLoader = new BatchLoader(
  async keys => { /* ... fetch logic ... */ },
  { cacheMap: cacheMapUsers }
);

module.exports = {
  before: {
    all: cache(cacheMapUsers)
  },
  after: {
    all: [cache(cacheMapUsers), fastJoin(postResolvers, () => query)]
  }
};

You can use a function for the schema option in populate to return different inclusion sets based on the incoming request. This allows clients to request specific data shapes (e.g., an 'Accounting' view vs a 'Receiving' view).

1. Client side: Use paramsForServer to pass a schema identifier.
2. Server side: Use paramsFromClient to extract the identifier and a function in populate to select the correct schema.

// 1. Client side
import { paramsForServer } from 'feathers-hooks-common';
// Request a specific schema named 'po-acct'
purchaseOrders.get(id, paramsForServer({ schema: 'po-acct' }));

// 2. Server side
import { paramsFromClient } from 'feathers-hooks-common';

const poSchemas = {
  'po-acct': { include: [ /* Accounting specific includes */ ] },
  'po-rec': { include: [ /* Receiving specific includes */ ] }
};

purchaseOrders.before({
  all: paramsFromClient('schema')
});

purchaseOrders.after({
  all: populate({ 
    schema: (hook) => poSchemas[hook.params.schema] 
  })
});