From 0dce4e014cc79b24ed7e12a44e9131f4942f47a7 Mon Sep 17 00:00:00 2001 From: Harminder virk Date: Thu, 19 Dec 2019 21:57:12 +0530 Subject: [PATCH] docs(readme): update usage docs --- README.md | 83 +++++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 63 insertions(+), 20 deletions(-) diff --git a/README.md b/README.md index 8bdcc0c..09be75e 100644 --- a/README.md +++ b/README.md @@ -1,33 +1,37 @@ -
- -
+
# Hooks > A no brainer module to execute lifecycle hooks in sequence. -[![circleci-image]][circleci-url] [![npm-image]][npm-url] ![][typescript-image] [![license-image]][license-url] +[![circleci-image]][circleci-url] [![typescript-image]][typescript-url] [![npm-image]][npm-url] [![license-image]][license-url] + +I find myself re-writing the code for hooks in multiple packages, so decided to extract it to it's own module, that can be re-used by other modules of AdonisJS. -I find myself re-writing the code for hooks in multiple packages, so decided to extract it to it's own module, that can be re-used by other modules of AdonisJs. ## Table of contents - [How it works?](#how-it-works) +- [Installation](#installation) - [Usage](#usage) -- [API Docs](#api-docs) -- [Maintainers](#maintainers) +- [API](#api) + - [add(lifecycle: 'before' | 'after', action: string, handler: Function | string)](#addlifecycle-before--after-action-string-handler-function--string) + - [exec(lifecycle: 'before' | 'after', action: string, ...data: any[])](#execlifecycle-before--after-action-string-data-any) + - [remove (lifecycle: 'before' | 'after', action: string, handler: HooksHandler | string)](#remove-lifecycle-before--after-action-string-handler-hookshandler--string) + - [clear(lifecycle: 'before' | 'after', action?: string)](#clearlifecycle-before--after-action-string) ## How it works? -The hooks class exposes the API to `register`, `remove` and `exec` lifecycle hooks for any number of actions or events. The class API is meant to be used internally by user facing code, so that you can improve the autocomplete UX. +The hooks class exposes the API to `register`, `remove` and `exec` lifecycle hooks for any number of actions or events. The class API is meant to be used internally and not by the user facing code, so that you can improve the autocomplete UX. For example: The Lucid models uses this class internally and expose `before` and `after` methods on the model itself. Doing this, Lucid can control the autocomplete, type checking for the `before` and `after` methods itself, without relying on this package to expose the generics API. -> Also generics increases the number of types, Typescript has to generate. So it's better to avoid them whenever possible. +> Also generics increases the number of types Typescript has to generate and it's better to avoid them whenever possible. -## Usage +## Installation Install the package from npm registry as follows: ```sh @@ -37,7 +41,8 @@ npm i @poppinss/hooks yarn add @poppinss/hooks ``` -and use it as follows +## Usage +Use it as follows ```ts import { Hooks } from '@poppinss/hooks' @@ -66,21 +71,59 @@ The resolver allows the end user to pass the hook reference as string and hooks hooks.add('before', 'save', 'User.encryptPassword') ``` -## API Docs -Following are the autogenerated files via Typedoc +## API + +#### add(lifecycle: 'before' | 'after', action: string, handler: Function | string) + +Add a new hook handler. + +```ts +hooks.add('before', 'save', (data) => { + console.log(data) +}) +``` + + +#### exec(lifecycle: 'before' | 'after', action: string, ...data: any[]) + +Execute a given hook for a selected lifecycle. + +```ts +hooks.exec('before', 'save', { username: 'virk' }) +``` + +#### remove (lifecycle: 'before' | 'after', action: string, handler: HooksHandler | string) + +Remove an earlier registered hook. If you are using the IoC container bindings, then passing the binding string is enough, otherwise you need to store the reference of the function. + +```ts +function onSave () {} + +hooks.add('before', 'save', onSave) + +// Later remove it +hooks.remove('before', 'save', onSave) +``` -* [API](docs/README.md) +#### clear(lifecycle: 'before' | 'after', action?: string) -## Maintainers -[Harminder virk](https://github.com/thetutlage) +Clear all hooks for a given lifecycle and optionally an action. + +```ts +hooks.clear('before') + +// Clear just for the save action +hooks.clear('before', 'save') +``` [circleci-image]: https://img.shields.io/circleci/project/github/poppinss/hooks/master.svg?style=for-the-badge&logo=circleci [circleci-url]: https://circleci.com/gh/poppinss/hooks "circleci" +[typescript-image]: https://img.shields.io/badge/Typescript-294E80.svg?style=for-the-badge&logo=typescript +[typescript-url]: "typescript" + [npm-image]: https://img.shields.io/npm/v/@poppinss/hooks.svg?style=for-the-badge&logo=npm [npm-url]: https://npmjs.org/package/@poppinss/hooks "npm" -[typescript-image]: https://img.shields.io/badge/Typescript-294E80.svg?style=for-the-badge&logo=typescript - -[license-url]: LICENSE.md -[license-image]: https://img.shields.io/aur/license/pac.svg?style=for-the-badge +[license-image]: https://img.shields.io/npm/l/@poppinss/hooks?color=blueviolet&style=for-the-badge +[license-url]: LICENSE.md "license"