chore: Add documentation and finalize initial API (#2)

lerna.json

@@ -3,7 +3,7 @@
   "packages": [
     "packages/*"
   ],
-  "version": "0.0.1-alpha.0",
+  "version": "0.0.0",
   "command": {
     "bootstrap": {
       "hoist": true

packages/hooks/README.md

@@ -1,6 +1,6 @@
 # Hooks
 
-[![Build Status](https://travis-ci.org/feathersjs/feathers.png?branch=master)](https://travis-ci.org/feathersjs/feathers)
+[![CI GitHub action](https://github.com/feathersjs/hooks/workflows/Node%20CI/badge.svg)](https://github.com/feathersjs/hooks/actions?query=workflow%3A%22Node+CI%22)
 [![Dependency Status](https://img.shields.io/david/feathersjs/feathers.svg?style=flat-square&path=packages/hooks)](https://david-dm.org/feathersjs/feathers?path=packages/hooks)
 [![Download Status](https://img.shields.io/npm/dm/@feathersjs/hooks.svg?style=flat-square)](https://www.npmjs.com/package/@feathersjs/hooks)
 
@@ -12,126 +12,9 @@
 npm install @feathersjs/hooks --save
 ```
 
-## Quick Example
-
-The following example logs the runtime of a function:
-
-```js
-const hooks = require('@feathersjs/hooks');
-const logRuntime = async (ctx, next) => {
-  const start = new Date().getTime();
-
-  await next();
-
-  const end = new Date().getTime();
-
-  console.log(`Function call took ${end - start}ms`);
-}
-
-const sayHello = hooks(async message => {
-  return `Hello ${message}!`;
-}, [ logRuntime ]);
-
-console.log(await sayHello('David'));
-```
-
 ## Documentation
 
-### Hook functions
-
-Hook functions take a context `ctx` and an asynchronous `next` function as their argument. The control flow is the exact same as in [KoaJS](). A hook function can do things before calling `await next()` and after all other hooks and the function call returned:
-
-```js
-const hooks = require('@feathersjs/hooks');
-
-const sayHello = async message => {
-  return `Hello ${message}!`;
-};
-
-const logMethod = async (ctx, next) => {
-  console.log('Before calling method');
-  console.log('Arguments are', ctx.arguments);
-
-  await next();
-
-  console.log('Method called');
-  console.log('Result is', ctx.result);
-}
-
-const hookedSayHello = hooks(sayHello, [ logMethod ]);
-```
-
-### Context
-
-- `ctx.arguments` - The arguments of the function as an array
-- `ctx.method` - The name of the function (if it belongs to an object)
-- `ctx.this` - The `this` context of the function being called
-
-### Decorators
-
-Hooks can also be attached through [ES expiremental](https://babeljs.io/docs/en/babel-plugin-proposal-decorators) or TypeScript decorators:
-
-```js
-import hooks from '@feathersjs/hooks';
-
-class App {
-  @hooks([ logMethod ])
-  async sayHi (name) {
-    return `Hello ${name}`;
-  }
-}
-```
-
-## More Examples
-
-### Cache results
-
-The following example is a simple hook that caches the results of a function call and uses the cached value if available. This is useful e.g. for external Ajax requests:
-
-```js
-const hooks = require('@feathersjs/hooks');
-const cache = () => {
-  const cacheData = {};
-
-  return async (ctx, next) => {
-    const key = JSON.stringify(ctx);
-
-    if (cacheData[key]) {
-      ctx.result = cacheData[key];
-
-      return next();
-    }
-
-    await next();
-
-    cacheData[key] = ctx.result;
-  }
-}
-
-const getData = hooks(async url => {
-  return axios.get(url);
-}, [ cache() ]);
-
-await getData('http://url-that-takes-long-to-respond');
-```
-
-### Decorators
-
-```js
-import hooks from '@feathersjs/hooks';
-
-class Api {
-  @hooks([
-    logRuntime,
-    cache()
-  ])
-  async getMessages () {
-    const { data } = axios.get('http://myserver.com/users');
-
-    return data;
-  }
-}
-```
+See [feathersjs/hooks](https://github.com/feathersjs/hooks/) for the complete documentation.
 
 ## License
 

packages/hooks/src/base.ts

@@ -22,8 +22,10 @@ export function getMiddleware (target: any): Middleware[] {
 /**
  * The base hook context.
  */
-export class HookContext<T = any> {
+export class HookContext<T = any, C = any> {
   result?: T;
+  method?: string;
+  self: C;
   arguments: any[];
   [key: string]: any;
 

packages/hooks/src/index.ts

@@ -25,7 +25,7 @@ export function hooks<F, T = any> (
 export function hooks (...args: any[]) {
   const [ target, _hooks, ...rest ] = args;
 
-  if (Array.isArray(_hooks)) {
+  if (Array.isArray(_hooks) && typeof target === 'function') {
     return functionHooks(target, _hooks, ...rest);
   }
 

packages/hooks/src/object.ts

@@ -1,6 +1,6 @@
 import { Middleware } from './compose';
 import { functionHooks } from './function';
-import { ContextUpdater, HookContext, withParams } from './base';
+import { ContextUpdater, HookContext, withParams, registerMiddleware } from './base';
 
 export interface MiddlewareMap {
   [key: string]: Middleware[];
@@ -10,9 +10,15 @@ export interface ContextUpdaterMap {
   [key: string]: ContextUpdater;
 }
 
-export const objectHooks = (_obj: any, hookMap: MiddlewareMap, contextMap?: ContextUpdaterMap) => {
+export const objectHooks = (_obj: any, hooks: MiddlewareMap|Middleware[], contextMap?: ContextUpdaterMap) => {
   const obj = typeof _obj === 'function' ? _obj.prototype : _obj;
 
+  if (Array.isArray(hooks)) {
+    return registerMiddleware(obj, hooks);
+  }
+
+  const hookMap = hooks as MiddlewareMap;
+
   return Object.keys(hookMap).reduce((result, method) => {
     const value = obj[method];
     const hooks = hookMap[method];

packages/hooks/test/object.test.ts

@@ -171,4 +171,24 @@ describe('objectHooks', () => {
 
     assert.strictEqual(await instance.sayHi('David'), 'Hi David?!');
   });
+
+  it('works with object level hooks', async () => {
+    hooks(obj, [
+      async (ctx: HookContext, next: NextFunction) => {
+        await next();
+
+        ctx.result += '!';
+      }
+    ]);
+
+    hooks(obj, {
+      sayHi: [async (ctx: HookContext, next: NextFunction) => {
+        await next();
+
+        ctx.result += '?';
+      }]
+    });
+
+    assert.equal(await obj.sayHi('Dave'), 'Hi Dave?!');
+  });
 });