---
title: Utilisation de feature
slug: oip-next/v3/features-library/utilisation
icon: {"lucideIcon":"📘"}
createdAt: 2025-10-13T13:55:24.000Z
---

# Développement

Toutes les *features* doivent partager la même signature.

## Input

```typescript
{
  service?: {
    url: string;
    apiKey: string;
  };
  rabbitmq?: {
    messageBuilder: (response: unknown) => { message: unknown; queue: string };
  };
  onUpdateTaskState?: (args: { error?: string; metadata?: unknown; state: { status: string; statusCode: number } }) => Promise<void>;
};
```

### Paramètres

- `service` : porte l'url et la clé d'API permettant de se connecter au service dont dépend la feature
- `rabbitmq` : porte un handler de construction de message afin d'envoyer des evènements dans une queue rabbit lors de l'exécution de la feature. `messageBuilder` est responsable de la construction du message et doit à minima renvoyer le nom de la queue rabbit destinataire du message dans une variable `queue`.
- `onUpdateTaskState` : un *handler* pour la gestion des notifications. Le *handler* `onUpdateTaskState` sert à notifier un évènement relatif à la tâche dont la *feature* fait partie. Il est donc uniquement pertinent quand la *feature* est utilisée dans le contexte d'une tâche, pour mettre à jour l'état de celle-ci.

## Ouput

En sortie, une *feature* retourne un dictionnaire de l'ensemble des APIs qu'elle propose. Chaque élément de ce dictionnaire est une fonction qui doit prendre la signature suivante :

```typescript
func1: (
    projectEntity: Object,
    args?: unknown,
    taskState?: TaskState
  ) => Promise<{ projectEntity: Object; metadata?: unknown }>;
```

Des données complémentaires peuvent être passés directement aux fonctions exposées par la *feature* dans l'objet `args`

Lorsque vous utilisez une feature OIP dans le contexte d'une task, le paramètre `taskState` permet de définir les status que vous souhaitez appliquer à cette task lors du traitement de la feature.

```typescript
export type TaskState = {
  starting: { status: string; statusCode: number };
  success: { status: string; statusCode: number };
  failure: { status: string; statusCode: number };
};
```

# Utilisation

## Comment déclarer une feature

La convention est de suffixer le nom d'une *feature* par `Feature.`

Considérons la feature `DocumentFeature` qui offre trois services :

- `uploadDocument` : étant donné un objet document, upload ce document vers le service `file_storage` et enregistre ce document sous forme d'entité `Document` au sein de l'entité `Project`.
- `downloadDocument` : étant donné l'identifiant d'une entié `Document`, télécharge ce document depuis le service `file_storage`.
- `deleteDocument` : étant donné l'identifiant d'une entié `Document`, supprime ce document auprès du service `file_storage` et ainsi que l'entité `Document` correspondante.

```javascript
import { updateTaskStateHandler, rabbitmqHandler } from '@fasstech/oip-features-utils';
import { $download } from './download.js';
import { $delete } from './delete.js';
import { $upload } from './upload.js';

/**
 * Initialise la feature Document.
 *
 * @param {import('@fasstech/oip-features-utils').FeatureOptions} options - Options de configuration de la feature :
 *   - service?: { url: string, apiKey: string }
 *   - rabbitmq?: { messageBuilder: function }
 *   - onUpdateTaskState?: function
 * @returns {Object} Objet contenant les fonctions uploadDocument, downloadDocument, deleteDocument
 */
export function DocumentFeature(options) {
  const updateTaskState = updateTaskStateHandler(options?.onUpdateTaskState);
  const sendMessage = rabbitmqHandler(options?.rabbitmq);
  return {
    uploadDocument: $upload({ updateTaskState, sendMessage, options }),
    downloadDocument: $download({ updateTaskState, sendMessage, options }),
    deleteDocument: $delete({ updateTaskState, sendMessage, options }),
  };
}
```

## Comment déclarer un service d'une feature

```javascript
/**
 * Sauvegarde un document dans FileStorage (stratégie DB slt pour l'instant) et l'entité projet.
 * @param {Object} params
 * @param {Object} params.projectEntity - L'entité projet concernée.
 * @param {Object} params.args
 * @param {Object} params.args.document - Le document à sauvegarder.
 * @param {string} params.args.document.type - Type du document.
 * @param {string} params.args.document.fileName - Nom du fichier.
 * @param {string} [params.args.document.originalFileName] - Nom du fichier.
 * @param {string} params.args.document.path - Chemin du fichier.
 * @param {string} [params.args.document.mimeType] - Type MIME du fichier.
 * @param {string} [params.args.document.key] - Clé de stockage.
 * @param {unknown} [params.args.document.metadata] - Métadonnées associées.
 * @param {Object} [params.taskState] - États de tâche optionnels ({ success, failure }).
 * @returns {Promise<{ projectEntity: Object, metadata?: unknown }>}
*/
export const $upload = ({ updateTaskState, sendMessage, options }) => async ({ projectEntity, args, taskState }) => {
  // 1. upload file to file_storage
  // 2. get the file_storage uploadId
  // 3. Create a Document entity & set externalId, fileName, mimeType, etc..
  // 4. Save it to Project entity
  // 5. Return the updated project entity & the newly created Document entity id
};
```

## Comment appeler une feature

```javascript
import { DocumentFeature } from '@fasstech/oip-features-document';

const document = {
  fileName: 'test.txt',
  mimeType: 'text/plain',
  path: `/tmp/test.txt`,
  type: DocumentTypeEnum.OTHER
};

const { uploadDocument } = DocumentFeature({ service: { url: SERVICE_FILESTORAGE_URL }});
const { projectEntity: updatedProjectEntity, metadata } = await uploadDocument({
  projectEntity,
  args: { document }
});
```
