Présentation

Il s'agit d'une bibliothèque de polyfills et d'helpers pour simplifier le développement des API avec FeathersJS ainsi que leurs connexions entre elles.

Contenu

• Meilleure gestion des queries par requêtes et par services
• Propose un manager de ressources externes pour simplifier les populate et le filtrage avec des services externes provenant d'autres API.
• Ajoute une sélection de polyfills et de methods pour simplifier le développement

Requirements

• FeathersJS ^3.3.1
• NodeJS ^10.15.1

Installation

L'installation se fait via npm :

npm i @bit/superdev.ts-node.feathers-across-galaxy

Utilisation

1. Resource

Une ressource représente un champ ou un groupe de champ customisés dans le model de votre service. Ce champ customisé n'existe pas dans la base de donnée liée à votre service.

Ce champ peut venir d'une API externe, d'un service interne ou externe, ou simplement d'un callback.

La Resource se charge elle-même de permettre les actions de base dessus (filters / sort / populate).

Interface :

export interface IRessource {
  _service: string; 
  // ↳ Le nom du service a appelé pour la ressource
  _foreignKey: string; 
  // ↳ L'index du champ contenant l'id de l'entité externe liée à l'entité
  _primaryKeyIndex?: string; 
  // ↳ L'index de la clé primaire ('_id' par défault)
  _query?: object; 
  // ↳ Les queries a ajouté utilisées pour toutes les requêtes vers cette ressource
  _chain?: string|false; 
  // ↳ Par défault ce champ prend le nom de la ressource parent. Il permet de chainner les ressources avec d'autres ressources définits pour le service. 
  // Si cette valeur est à "false", la ressource n'a besoin d'aucune chainne pour fonctionner
  _mapping?: string|string[]|object 
  // ↳ Cette valeur permet de mapper les queries envoyées par l'utilisateur pour permettre aux ressources d'appliquer les bons filtres.
  // Il peut s'apparenter comme une query : { $or: [ { name: 'la valeur' } ] }
  _key?: string;
  // ↳ Par défault cette valeur prend le nom de votre ressource.
  // La key est utilisée pour populate vos résultats et aussi par rapport aux filtres
  _populate?: string;
  // ↳ Il s'agit de la query pour demander au ResourceManager de populate votre requête. Par défault elle est à "$populate".
}

Exemples

Resource simple :

// Resource "userName" représente "firstName" et "lastName"
const resource = new Resource({
  userName: ["firstName", "lastName"]
});

Resource lié à un service :

// Resource "user" lié à un service externe
const resource = new Resource({
  user: {
    _primaryKeyIndex: '_id',
    _query: { applicationId: true },
    _service: 'auth/users',
    _foreignKey: 'userId'
  }
});

Resource avec enfants :

// Resource "user" contenant une ressource enfant.
// Ici "payload" est une ressource enfant de "user"
const resource = new Resource({
  user: {
    _primaryKeyIndex: '_id',
    _query: { applicationId: true },
    _service: 'auth/users',
    _foreignKey: 'userId',
    payload: {
      _query: { applicationId: true },
      _primaryKeyIndex: 'userId',
      _service: 'auth/users-payloads',
      _chain: false,
      _foreignKey: 'userId',
      _mapping: 'payload',
    }
  }
});

2. ResourcesMananger

Cet outil permet de lier de gérer plusieurs ressources que vous avez définit pour model. Ainsi il sera possible de populate les entités retournées par votre APi ou de filtrer les résultats avec des champs externes.

Ces services externes sont appelés Resource.

Exemple d'utilisation :

// FILE:  projects.service.ts

import { ResourcesManager } from '@bit/superdev.ts-node.feathers-across-galaxy';
import { App } from '../../app.interface';
import createService from 'feathers-mongoose';
import createModel from '../../models/projects.model';
import hooks from './projects.hooks';

let moduleExports = function (app: any) {
  let Model = createModel(app);
  let paginate = app.get('paginate');
  let options = {
    Model,
    paginate,
    // ---------------
    // Parti à ajouter
    externalResources: {
      _primaryKeyIndex: '_id',
      user: {
        _query: { applicationId: true, $permissionsToString: true },
        _primaryKeyIndex: '_id',
        _service: 'auth/users',
        _foreignKey: 'userId',
        test: 'firstName',
        payload: {
          _query: { applicationId: true },
          _primaryKeyIndex: 'userId',
          _service: 'auth/users-payloads',
          _foreignKey: 'userId',
          _mapping: 'payload',
          _chain: false 
          // Si a "false" cette ressource ne cherchera pas dans son/ses parent(s)
        }
      },
      salesMan: {
        _primaryKeyIndex: '_id',
        _service: 'ud/sales-man',
        _chain: 'payload',
        _populate: '$populateSalesMan',
        _foreignKey: 'payload.salesManId'
      }
    }
    // ---------------
  };

  // ---------------
  // Parti à modifier
  app.use('/ud/projects', ResourcesManager.addExternalRessources(createService(options), hooks));
  // ---------------

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

export default moduleExports;

Avec cette configuration il sera possible de réaliser les requêtes suivantes :

// Rechercher tous les projets par le prénom, nom, company, 
// reference, commercial de l'utilisateur 
// ----------------------
// https://localhost:3036/ud/projects
// ?$ignoreSoftDelete=true&$or[0][user.firstName]=Admin&$or[1][user.lastName]=Admin&$or[2][user.payload.company]=Admin&$or[3][user.payload.customerRef]=Admin&$or[4][salesMan.lastName]=Admin&$populate=true

const queries = {
  $ignoreSoftDelete: true,
  $populate: true,
  $or: [
    { "user.firstName": "Admin" },
    { "user.lastName": "Admin" },
    { "user.payload.company": "Admin" },
    { "user.payload.customerRed": "Admin" },
    { "salesMan.lastName": "Admin" }
  ]
};

const response = [
  {
    _id: '111ab61daf61f64634dbe',
    name: 'Mon gros projet',
    description: 'Il est quand même très gros mon projet.',
    user: {
      firstName: 'Admin', // Le filtre s'applique grâce à ce champ
      lastName: 'GrosTuyau',
      payload: {
        company: 'Saucisse',
        customerRef: 'Tabouret'
      }
      ...
    },
    salesMan: {
      lastName: ''
      ...
    }
  }
  ...
];

// Utiliser le filtre custom "user.test" que l'on a créé
// dans la config
// ----------------------
// https://localhost:3036/ud/projects
// ?$ignoreSoftDelete=true&user.test=Root&$populate=true

const queries = {
  $ignoreSoftDelete: true,
  $populate: true,
  user: {
    test: 'Root'
  }
};

const response = [
  {
    _id: '111ab61daf61f64634dbe',
    name: 'Mon gros projet',
    description: 'Il est quand même très gros mon projet.',
    user: {
      firstName: 'Root', // Le filtre s'applique grâce à ce champ
      lastName: 'GrosTuyau'
      ...
    }
  }
  ...
];

3. Helpers

Query

Cette classe permet de gérer plus facilement les queries provenant des requêtes.

Interface

export interface IQuery {
  keys: string[];
  originKeys: string[];
  hasOperator(operatorIndex: string): boolean;
  originHasOperator(operatorIndex: string): boolean;
  getKeysWithPath(query?: any): any;
  getOriginKeysWithPath(): any;
  map(_mapping: any): Query;
  extractAndMap(_mapping: any, needCrush: boolean): Query;
  duplicate(keysToExtract?: string[]): Query;
  extract(keysToExtract: string[], needCrush: boolean): Query;
  merge(query: any): void;
  unset(key: string): void;
  set(key: string, data: any): void;
  get(key: string): any;
  has(key: string): boolean;
  toObject(): any;
}

Exemple dans FeathersJS

// FILE: un-hook-sauvage-apparait.ts
import { Query } from '@bit/superdev.ts-node.feathers-across-galaxy';

export (context: HookContext) => {
  let query: Query = new Query(context.params!.query);

  query.merge({
    newQuery: true,
    $newArray: ['test']
  });

  context.params!.query = query.toObject();

  return context;
}

Each

Cette function permet de boucler sur les résultats qu'importe que vous soyez dans un hook find, get, update, patch, delete

Exemple dans FeathersJS

// FILE: un-hook-sauvage-apparait.ts
import { each } from '@bit/superdev.ts-node.feathers-across-galaxy';

export (context: HookContext) => {
  let records: Project[] = getItems(context);

  records = await each(context, records, (record: any) => {
    console.log(record);
  }, { context });

  replaceItems(context, records);
  return context;
}