@feathersjs/feathers 5.0.0-pre.10

package/src/declarations.ts

@@ -0,0 +1,348 @@
+import {
+  EventEmitter, NextFunction, HookContext as BaseHookContext
+} from './dependencies';
+
+type SelfOrArray<S> = S | S[];
+type OptionalPick<T, K extends PropertyKey> = Pick<T, Extract<keyof T, K>>
+
+export type { NextFunction };
+
+export interface Paginated<T> {
+  total: number;
+  limit: number;
+  skip: number;
+  data: T[];
+}
+
+export interface ServiceOptions {
+  events?: string[];
+  methods?: string[];
+  serviceEvents?: string[];
+}
+
+export interface ServiceMethods<T, D = Partial<T>> {
+  find (params?: Params): Promise<T | T[]>;
+
+  get (id: Id, params?: Params): Promise<T>;
+
+  create (data: D, params?: Params): Promise<T>;
+
+  update (id: NullableId, data: D, params?: Params): Promise<T | T[]>;
+
+  patch (id: NullableId, data: D, params?: Params): Promise<T | T[]>;
+
+  remove (id: NullableId, params?: Params): Promise<T | T[]>;
+
+  setup (app: Application, path: string): Promise<void>;
+}
+
+export interface ServiceOverloads<T, D> {
+  create? (data: D[], params?: Params): Promise<T[]>;
+
+  update? (id: Id, data: D, params?: Params): Promise<T>;
+
+  update? (id: null, data: D, params?: Params): Promise<T[]>;
+
+  patch? (id: Id, data: D, params?: Params): Promise<T>;
+
+  patch? (id: null, data: D, params?: Params): Promise<T[]>;
+
+  remove? (id: Id, params?: Params): Promise<T>;
+
+  remove? (id: null, params?: Params): Promise<T[]>;
+}
+
+export type Service<T, D = Partial<T>> =
+  ServiceMethods<T, D> &
+  ServiceOverloads<T, D>;
+
+export type ServiceInterface<T, D = Partial<T>> =
+  Partial<ServiceMethods<T, D>>;
+
+export interface ServiceAddons<A = Application, S = Service<any, any>> extends EventEmitter {
+  id?: string;
+  hooks (options: HookOptions<A, S>): this;
+}
+
+export interface ServiceHookOverloads<S> {
+  find (
+    params: Params,
+    context: HookContext
+  ): Promise<HookContext>;
+
+  get (
+    id: Id,
+    params: Params,
+    context: HookContext
+  ): Promise<HookContext>;
+
+  create (
+    data: ServiceGenericData<S> | ServiceGenericData<S>[],
+    params: Params,
+    context: HookContext
+  ): Promise<HookContext>;
+
+  update (
+    id: NullableId,
+    data: ServiceGenericData<S>,
+    params: Params,
+    context: HookContext
+  ): Promise<HookContext>;
+
+  patch (
+    id: NullableId,
+    data: ServiceGenericData<S>,
+    params: Params,
+    context: HookContext
+  ): Promise<HookContext>;
+
+  remove (
+    id: NullableId,
+    params: Params,
+    context: HookContext
+  ): Promise<HookContext>;
+}
+
+export type FeathersService<A = FeathersApplication, S = Service<any>> =
+  S & ServiceAddons<A, S> & OptionalPick<ServiceHookOverloads<S>, keyof S>;
+
+export type CustomMethod<Methods extends string> = {
+  [k in Methods]: <X = any> (data: any, params?: Params) => Promise<X>;
+}
+
+export type ServiceMixin<A> = (service: FeathersService<A>, path: string, options?: ServiceOptions) => void;
+
+export type ServiceGenericType<S> = S extends ServiceInterface<infer T> ? T : any;
+export type ServiceGenericData<S> = S extends ServiceInterface<infer _T, infer D> ? D : any;
+
+export interface FeathersApplication<ServiceTypes = any, AppSettings = any> {
+  /**
+   * The Feathers application version
+   */
+  version: string;
+
+  /**
+   * A list of callbacks that run when a new service is registered
+   */
+  mixins: ServiceMixin<Application<ServiceTypes, AppSettings>>[];
+
+  /**
+   * The index of all services keyed by their path.
+   *
+   * __Important:__ Services should always be retrieved via `app.service('name')`
+   * not via `app.services`.
+   */
+  services: ServiceTypes;
+
+  /**
+   * The application settings that can be used via
+   * `app.get` and `app.set`
+   */
+  settings: AppSettings;
+
+  /**
+   * A private-ish indicator if `app.setup()` has been called already
+   */
+  _isSetup: boolean;
+
+  /**
+   * Contains all registered application level hooks.
+   */
+  appHooks: HookMap<Application<ServiceTypes, AppSettings>, any>;
+
+  /**
+   * Retrieve an application setting by name
+   *
+   * @param name The setting name
+   */
+  get<L extends keyof AppSettings & string> (name: L): AppSettings[L];
+
+  /**
+   * Set an application setting
+   *
+   * @param name The setting name
+   * @param value The setting value
+   */
+  set<L extends keyof AppSettings & string> (name: L, value: AppSettings[L]): this;
+
+  /**
+   * Runs a callback configure function with the current application instance.
+   *
+   * @param callback The callback `(app: Application) => {}` to run
+   */
+  configure (callback: (this: this, app: this) => void): this;
+
+  /**
+   * Returns a fallback service instance that will be registered
+   * when no service was found. Usually throws a `NotFound` error
+   * but also used to instantiate client side services.
+   *
+   * @param location The path of the service
+   */
+  defaultService (location: string): ServiceInterface<any>;
+
+  /**
+   * Register a new service or a sub-app. When passed another
+   * Feathers application, all its services will be re-registered
+   * with the `path` prefix.
+   *
+   * @param path The path for the service to register
+   * @param service The service object to register or another
+   * Feathers application to use a sub-app under the `path` prefix.
+   * @param options The options for this service
+   */
+  use<L extends keyof ServiceTypes & string> (
+    path: L,
+    service: keyof any extends keyof ServiceTypes ? ServiceInterface<any> | Application : ServiceTypes[L],
+    options?: ServiceOptions
+  ): this;
+
+  /**
+   * Get the Feathers service instance for a path. This will
+   * be the service originally registered with Feathers functionality
+   * like hooks and events added.
+   *
+   * @param path The name of the service.
+   */
+  service<L extends keyof ServiceTypes & string> (
+    path: L
+  ): FeathersService<this, keyof any extends keyof ServiceTypes ? Service<any> : ServiceTypes[L]>;
+
+  setup (server?: any): Promise<this>;
+
+  /**
+   * Register application level hooks.
+   *
+   * @param map The application hook settings.
+   */
+  hooks (map: HookOptions<this, any>): this;
+}
+
+// This needs to be an interface instead of a type
+// so that the declaration can be extended by other modules
+export interface Application<ServiceTypes = any, AppSettings = any> extends FeathersApplication<ServiceTypes, AppSettings>, EventEmitter {
+
+}
+
+export type Id = number | string;
+export type NullableId = Id | null;
+
+export interface Query {
+  [key: string]: any;
+}
+
+export interface Params {
+  query?: Query;
+  provider?: string;
+  route?: { [key: string]: string };
+  headers?: { [key: string]: any };
+  [key: string]: any; // (JL) not sure if we want this
+}
+
+export interface HookContext<A = Application, S = any> extends BaseHookContext<ServiceGenericType<S>> {
+  /**
+   * A read only property that contains the Feathers application object. This can be used to
+   * retrieve other services (via context.app.service('name')) or configuration values.
+   */
+  readonly app: A;
+  /**
+   * A read only property with the name of the service method (one of find, get,
+   * create, update, patch, remove).
+   */
+  readonly method: string;
+  /**
+   * A read only property and contains the service name (or path) without leading or
+   * trailing slashes.
+   */
+  readonly path: string;
+  /**
+   * A read only property and contains the service this hook currently runs on.
+   */
+  readonly service: S;
+  /**
+   * A read only property with the hook type (one of before, after or error).
+   * Will be `null` for asynchronous hooks.
+   */
+  readonly type: null | 'before' | 'after' | 'error';
+  /**
+   * The list of method arguments. Should not be modified, modify the
+   * `params`, `data` and `id` properties instead.
+   */
+  readonly arguments: any[];
+  /**
+   * A writeable property containing the data of a create, update and patch service
+   * method call.
+   */
+  data?: ServiceGenericData<S>;
+  /**
+   * A writeable property with the error object that was thrown in a failed method call.
+   * It is only available in error hooks.
+   */
+  error?: any;
+  /**
+   * A writeable property and the id for a get, remove, update and patch service
+   * method call. For remove, update and patch context.id can also be null when
+   * modifying multiple entries. In all other cases it will be undefined.
+   */
+  id?: Id;
+  /**
+   * A writeable property that contains the service method parameters (including
+   * params.query).
+   */
+  params: Params;
+  /**
+   * A writeable property containing the result of the successful service method call.
+   * It is only available in after hooks.
+   *
+   * `context.result` can also be set in
+   *
+   * - A before hook to skip the actual service method (database) call
+   * - An error hook to swallow the error and return a result instead
+   */
+  result?: ServiceGenericType<S>;
+  /**
+   * A writeable, optional property and contains a 'safe' version of the data that
+   * should be sent to any client. If context.dispatch has not been set context.result
+   * will be sent to the client instead.
+   */
+  dispatch?: ServiceGenericType<S>;
+  /**
+   * A writeable, optional property that allows to override the standard HTTP status
+   * code that should be returned.
+   */
+  statusCode?: number;
+  /**
+   * The event emitted by this method. Can be set to `null` to skip event emitting.
+   */
+  event: string|null;
+}
+
+// Legacy hook typings
+export type LegacyHookFunction<A = Application, S = Service<any, any>> =
+  (this: S, context: HookContext<A, S>) => (Promise<HookContext<Application, S> | void> | HookContext<Application, S> | void);
+
+export type Hook<A = Application, S = Service<any, any>> = LegacyHookFunction<A, S>;
+
+type LegacyHookMethodMap<A, S> =
+  { [L in keyof S]?: SelfOrArray<LegacyHookFunction<A, S>>; } &
+  { all?: SelfOrArray<LegacyHookFunction<A, S>> };
+
+type LegacyHookTypeMap<A, S> =
+  SelfOrArray<LegacyHookFunction<A, S>> | LegacyHookMethodMap<A, S>;
+
+export type LegacyHookMap<A, S> = {
+  before?: LegacyHookTypeMap<A, S>,
+  after?: LegacyHookTypeMap<A, S>,
+  error?: LegacyHookTypeMap<A, S>
+}
+
+// New @feathersjs/hook typings
+export type HookFunction<A = Application, S = Service<any, any>> =
+  (context: HookContext<A, S>, next: NextFunction) => Promise<void>;
+
+export type HookMap<A, S> = {
+  [L in keyof S]?: HookFunction<A, S>[];
+};
+
+export type HookOptions<A, S> =
+  HookMap<A, S> | HookFunction<A, S>[] | LegacyHookMap<A, S>;

package/src/dependencies.ts

@@ -0,0 +1,5 @@
+import { EventEmitter } from 'events';
+export * from '@feathersjs/commons';
+export * from '@feathersjs/hooks';
+
+export { EventEmitter };

package/src/events.ts

@@ -0,0 +1,31 @@
+import { NextFunction, EventEmitter } from './dependencies';
+import { HookContext, FeathersService } from './declarations';
+import { getServiceOptions, defaultEventMap } from './service';
+
+export function eventHook (context: HookContext, next: NextFunction) {
+  const { events } = getServiceOptions((context as any).self);
+  const defaultEvent = (defaultEventMap as any)[context.method] || null;
+
+  context.event = defaultEvent;
+
+  return next().then(() => {
+    // Send the event only if the service does not do so already (indicated in the `events` option)
+    // This is used for custom events and for client services receiving event from the server
+    if (typeof context.event === 'string' && !events.includes(context.event)) {
+      const results = Array.isArray(context.result) ? context.result : [ context.result ];
+
+      results.forEach(element => (context as any).self.emit(context.event, element, context));
+    }
+  });
+}
+
+export function eventMixin<A> (service: FeathersService<A>) {
+  const isEmitter = typeof service.on === 'function' &&
+    typeof service.emit === 'function';
+
+  if (!isEmitter) {
+    Object.assign(service, EventEmitter.prototype);
+  }
+
+  return service;
+}

package/src/hooks/index.ts

@@ -0,0 +1,109 @@
+import {
+  getManager, HookContextData, HookManager, HookMap, HOOKS, hooks, Middleware
+} from '../dependencies';
+import {
+  Service, ServiceOptions, HookContext, FeathersService, Application
+} from '../declarations';
+import { defaultServiceArguments, getHookMethods } from '../service';
+import {
+  collectLegacyHooks,
+  enableLegacyHooks,
+  fromAfterHook,
+  fromBeforeHook,
+  fromErrorHooks
+} from './legacy';
+
+export { fromAfterHook, fromBeforeHook, fromErrorHooks };
+
+export function createContext (service: Service<any>, method: string, data: HookContextData = {}) {
+  const createContext = (service as any)[method].createContext;
+
+  if (typeof createContext !== 'function') {
+    throw new Error(`Can not create context for method ${method}`);
+  }
+
+  return createContext(data) as HookContext;
+}
+
+export class FeathersHookManager<A> extends HookManager {
+  constructor (public app: A, public method: string) {
+    super();
+    this._middleware = [];
+  }
+
+  collectMiddleware (self: any, args: any[]): Middleware[] {
+    const app = this.app as any as Application;
+    const appHooks = app.appHooks[HOOKS].concat(app.appHooks[this.method] || []);
+    const legacyAppHooks = collectLegacyHooks(this.app, this.method);
+    const middleware = super.collectMiddleware(self, args);
+    const legacyHooks = collectLegacyHooks(self, this.method);
+
+    return [...appHooks, ...legacyAppHooks, ...middleware, ...legacyHooks];
+  }
+
+  initializeContext (self: any, args: any[], context: HookContext) {
+    const ctx = super.initializeContext(self, args, context);
+
+    ctx.params = ctx.params || {};
+
+    return ctx;
+  }
+
+  middleware (mw: Middleware[]) {
+    this._middleware.push(...mw);
+    return this;
+  }
+}
+
+export function hookMixin<A> (
+  this: A, service: FeathersService<A>, path: string, options: ServiceOptions
+) {
+  if (typeof service.hooks === 'function') {
+    return service;
+  }
+
+  const app = this;
+  const serviceMethodHooks = getHookMethods(service, options).reduce((res, method) => {
+    const params = (defaultServiceArguments as any)[method] || [ 'data', 'params' ];
+
+    res[method] = new FeathersHookManager<A>(app, method)
+      .params(...params)
+      .props({
+        app,
+        path,
+        method,
+        service,
+        event: null,
+        type: null
+      });
+
+    return res;
+  }, {} as HookMap);
+  const handleLegacyHooks = enableLegacyHooks(service);
+
+  hooks(service, serviceMethodHooks);
+
+  service.hooks = function (this: any, hookOptions: any) {
+    if (hookOptions.before || hookOptions.after || hookOptions.error) {
+      return handleLegacyHooks.call(this, hookOptions);
+    }
+
+    if (Array.isArray(hookOptions)) {
+      return hooks(this, hookOptions);
+    }
+
+    Object.keys(hookOptions).forEach(method => {
+      const manager = getManager(this[method]);
+
+      if (!(manager instanceof FeathersHookManager)) {
+        throw new Error(`Method ${method} is not a Feathers hooks enabled service method`);
+      }
+
+      manager.middleware(hookOptions[method]);
+    });
+
+    return this;
+  }
+
+  return service;
+}

package/src/hooks/legacy.ts

@@ -0,0 +1,138 @@
+import { _ } from '../dependencies';
+import { LegacyHookFunction } from '../declarations';
+
+const { each } = _;
+
+export function fromBeforeHook (hook: LegacyHookFunction) {
+  return (context: any, next: any) => {
+    context.type = 'before';
+
+    return Promise.resolve(hook.call(context.self, context)).then(() => {
+      context.type = null;
+      return next();
+    });
+  };
+}
+
+export function fromAfterHook (hook: LegacyHookFunction) {
+  return (context: any, next: any) => {
+    return next().then(() => {
+      context.type = 'after';
+      return hook.call(context.self, context)
+    }).then(() => {
+      context.type = null;
+    });
+  }
+}
+
+export function fromErrorHooks (hooks: LegacyHookFunction[]) {
+  return (context: any, next: any) => {
+    return next().catch((error: any) => {
+      let promise: Promise<any> = Promise.resolve();
+
+      context.original = { ...context };
+      context.error = error;
+      context.type = 'error';
+
+      delete context.result;
+
+      for (const hook of hooks) {
+        promise = promise.then(() => hook.call(context.self, context))
+      }
+
+      return promise.then(() => {
+        context.type = null;
+
+        if (context.result === undefined) {
+          throw context.error;
+        }
+      });
+    });
+  }
+}
+
+export function collectLegacyHooks (target: any, method: string) {
+  const {
+    before: { [method]: before = [] },
+    after: { [method]: after = [] },
+    error: { [method]: error = [] }
+  } = target.__hooks;
+  const beforeHooks = before;
+  const afterHooks = [...after].reverse();
+  const errorHook = fromErrorHooks(error);
+
+  return [errorHook, ...beforeHooks, ...afterHooks];
+}
+
+// Converts different hook registration formats into the
+// same internal format
+export function convertHookData (obj: any) {
+  let hook: any = {};
+
+  if (Array.isArray(obj)) {
+    hook = { all: obj };
+  } else if (typeof obj !== 'object') {
+    hook = { all: [ obj ] };
+  } else {
+    each(obj, function (value, key) {
+      hook[key] = !Array.isArray(value) ? [ value ] : value;
+    });
+  }
+
+  return hook;
+}
+
+// Add `.hooks` functionality to an object
+export function enableLegacyHooks (
+  obj: any,
+  methods: string[] = ['find', 'get', 'create', 'update', 'patch', 'remove'],
+  types: string[] = ['before', 'after', 'error']
+) {
+  const hookData: any = {};
+
+  types.forEach(type => {
+    // Initialize properties where hook functions are stored
+    hookData[type] = {};
+  });
+
+  // Add non-enumerable `__hooks` property to the object
+  Object.defineProperty(obj, '__hooks', {
+    configurable: true,
+    value: hookData,
+    writable: true
+  });
+
+  return function legacyHooks (this: any, allHooks: any) {
+    each(allHooks, (current: any, type) => {
+      if (!this.__hooks[type]) {
+        throw new Error(`'${type}' is not a valid hook type`);
+      }
+
+      const hooks = convertHookData(current);
+
+      each(hooks, (_value, method) => {
+        if (method !== 'all' && methods.indexOf(method) === -1) {
+          throw new Error(`'${method}' is not a valid hook method`);
+        }
+      });
+
+      methods.forEach(method => {
+        let currentHooks = [...(hooks.all || []), ...(hooks[method] || [])];
+
+        this.__hooks[type][method] = this.__hooks[type][method] || [];
+
+        if (type === 'before') {
+          currentHooks = currentHooks.map(fromBeforeHook);
+        }
+
+        if (type === 'after') {
+          currentHooks = currentHooks.map(fromAfterHook);
+        }
+
+        this.__hooks[type][method].push(...currentHooks);
+      });
+    });
+
+    return this;
+  }
+}

package/src/index.ts

@@ -0,0 +1,19 @@
+import { setDebug } from './dependencies';
+import version from './version';
+import { Feathers } from './application';
+import { Application } from './declarations';
+
+export function feathers<T = any, S = any> () {
+  return new Feathers<T, S>() as Application<T, S>;
+}
+
+feathers.setDebug = setDebug;
+
+export { version, Feathers };
+export * from './hooks/index';
+export * from './declarations';
+export * from './service';
+
+if (typeof module !== 'undefined') {
+  module.exports = Object.assign(feathers, module.exports);
+}