@feathersjs/feathers 5.0.0-pre.6 → 5.0.0

package/src/declarations.ts

@@ -1,130 +1,207 @@
-import {
-  EventEmitter, NextFunction, HookContext as BaseHookContext
-} from './dependencies';
+import { EventEmitter } from 'events'
+import { NextFunction, HookContext as BaseHookContext } from '@feathersjs/hooks'
 
-type SelfOrArray<S> = S | S[];
+type SelfOrArray<S> = S | S[]
 type OptionalPick<T, K extends PropertyKey> = Pick<T, Extract<keyof T, K>>
 
-export type { NextFunction };
+export type { NextFunction }
 
+/**
+ * The object returned from `.find` call by standard database adapters
+ */
 export interface Paginated<T> {
-  total: number;
-  limit: number;
-  skip: number;
-  data: T[];
+  total: number
+  limit: number
+  skip: number
+  data: T[]
 }
 
-export interface ServiceOptions {
-  events?: string[];
-  methods?: string[];
-  serviceEvents?: string[];
+/**
+ * Options that can be passed when registering a service via `app.use(name, service, options)`
+ */
+export interface ServiceOptions<MethodTypes = string> {
+  /**
+   * A list of custom events that this service emits to clients
+   */
+  events?: string[] | readonly string[]
+  /**
+   * A list of service methods that should be available __externally__ to clients
+   */
+  methods?: MethodTypes[] | readonly MethodTypes[]
+  /**
+   * Provide a full list of events that this service should emit to clients.
+   * Unlike the `events` option, this will not be merged with the default events.
+   */
+  serviceEvents?: string[] | readonly string[]
+  /**
+   * Initial data to always add as route params to this service.
+   */
+  routeParams?: { [key: string]: any }
 }
 
-export interface ServiceMethods<T, D = Partial<T>> {
-  find (params?: Params): Promise<T | T[]>;
-
-  get (id: Id, params?: Params): Promise<T>;
+export interface ClientService<
+  Result = any,
+  Data = Partial<Result>,
+  PatchData = Data,
+  FindResult = Paginated<Result>,
+  P = Params
+> {
+  find(params?: P): Promise<FindResult>
 
-  create (data: D, params?: Params): Promise<T>;
+  get(id: Id, params?: P): Promise<Result>
 
-  update (id: NullableId, data: D, params?: Params): Promise<T | T[]>;
+  create(data: Data[], params?: P): Promise<Result[]>
+  create(data: Data, params?: P): Promise<Result>
 
-  patch (id: NullableId, data: D, params?: Params): Promise<T | T[]>;
+  update(id: Id, data: Data, params?: P): Promise<Result>
+  update(id: NullableId, data: Data, params?: P): Promise<Result | Result[]>
+  update(id: null, data: Data, params?: P): Promise<Result[]>
 
-  remove (id: NullableId, params?: Params): Promise<T | T[]>;
+  patch(id: NullableId, data: PatchData, params?: P): Promise<Result | Result[]>
+  patch(id: Id, data: PatchData, params?: P): Promise<Result>
+  patch(id: null, data: PatchData, params?: P): Promise<Result[]>
 
-  setup (app: Application, path: string): Promise<void>;
+  remove(id: NullableId, params?: P): Promise<Result | Result[]>
+  remove(id: Id, params?: P): Promise<Result>
+  remove(id: null, params?: P): Promise<Result[]>
 }
 
-export interface ServiceOverloads<T, D> {
-  create? (data: D[], params?: Params): Promise<T[]>;
+export interface ServiceMethods<
+  Result = any,
+  Data = Partial<Result>,
+  ServiceParams = Params,
+  PatchData = Partial<Data>
+> {
+  find(params?: ServiceParams): Promise<Result | Result[]>
 
-  update? (id: Id, data: D, params?: Params): Promise<T>;
+  get(id: Id, params?: ServiceParams): Promise<Result>
 
-  update? (id: null, data: D, params?: Params): Promise<T[]>;
+  create(data: Data, params?: ServiceParams): Promise<Result>
 
-  patch? (id: Id, data: D, params?: Params): Promise<T>;
+  update(id: NullableId, data: Data, params?: ServiceParams): Promise<Result | Result[]>
 
-  patch? (id: null, data: D, params?: Params): Promise<T[]>;
+  patch(id: NullableId, data: PatchData, params?: ServiceParams): Promise<Result | Result[]>
 
-  remove? (id: Id, params?: Params): Promise<T>;
+  remove(id: NullableId, params?: ServiceParams): Promise<Result | Result[]>
 
-  remove? (id: null, params?: Params): Promise<T[]>;
+  setup?(app: Application, path: string): Promise<void>
+
+  teardown?(app: Application, path: string): Promise<void>
 }
 
-export type Service<T, D = Partial<T>> =
-  ServiceMethods<T, D> &
-  ServiceOverloads<T, D>;
+export interface ServiceOverloads<
+  Result = any,
+  Data = Partial<Result>,
+  ServiceParams = Params,
+  PatchData = Partial<Data>
+> {
+  create?(data: Data[], params?: ServiceParams): Promise<Result[]>
+
+  update?(id: Id, data: Data, params?: ServiceParams): Promise<Result>
+
+  update?(id: null, data: Data, params?: ServiceParams): Promise<Result[]>
+
+  patch?(id: Id, data: PatchData, params?: ServiceParams): Promise<Result>
 
-export type ServiceInterface<T, D = Partial<T>> =
-  Partial<ServiceMethods<T, D>>;
+  patch?(id: null, data: PatchData, params?: ServiceParams): Promise<Result[]>
 
-export interface ServiceAddons<A = Application, S = Service<any, any>> extends EventEmitter {
-  id?: string;
-  hooks (options: HookOptions<A, S>): this;
+  remove?(id: Id, params?: ServiceParams): Promise<Result>
+
+  remove?(id: null, params?: ServiceParams): Promise<Result[]>
 }
 
-export interface ServiceHookOverloads<S> {
-  find (
-    params: Params,
-    context: HookContext
-  ): Promise<HookContext>;
+/**
+ * A complete service interface. The `ServiceInterface` type should be preferred for customs service
+ * implementations
+ */
+export type Service<
+  Result = any,
+  Data = Partial<Result>,
+  ServiceParams = Params,
+  PatchData = Partial<Data>
+> = ServiceMethods<Result, Data, ServiceParams> & ServiceOverloads<Result, Data, ServiceParams, PatchData>
+
+/**
+ * The `Service` service interface but with none of the methods required.
+ */
+export type ServiceInterface<
+  Result = any,
+  Data = Partial<Result>,
+  ServiceParams = Params,
+  PatchData = Partial<Data>
+> = Partial<ServiceMethods<Result, Data, ServiceParams, PatchData>>
+
+export interface ServiceAddons<A = Application, S = Service> extends EventEmitter {
+  id?: string
+  hooks(options: HookOptions<A, S>): this
+}
 
-  get (
-    id: Id,
-    params: Params,
-    context: HookContext
-  ): Promise<HookContext>;
+export interface ServiceHookOverloads<S, P = Params> {
+  find(params: P, context: HookContext): Promise<HookContext>
 
-  create (
+  get(id: Id, params: P, context: HookContext): Promise<HookContext>
+
+  create(
     data: ServiceGenericData<S> | ServiceGenericData<S>[],
-    params: Params,
+    params: P,
     context: HookContext
-  ): Promise<HookContext>;
+  ): Promise<HookContext>
 
-  update (
-    id: NullableId,
-    data: ServiceGenericData<S>,
-    params: Params,
-    context: HookContext
-  ): Promise<HookContext>;
+  update(id: NullableId, data: ServiceGenericData<S>, params: P, context: HookContext): Promise<HookContext>
 
-  patch (
-    id: NullableId,
-    data: ServiceGenericData<S>,
-    params: Params,
-    context: HookContext
-  ): Promise<HookContext>;
+  patch(id: NullableId, data: ServiceGenericData<S>, params: P, context: HookContext): Promise<HookContext>
 
-  remove (
-    id: NullableId,
-    params: Params,
-    context: HookContext
-  ): Promise<HookContext>;
+  remove(id: NullableId, params: P, context: HookContext): Promise<HookContext>
 }
 
-export type FeathersService<A = FeathersApplication, S = Service<any>> =
-  S & ServiceAddons<A, S> & OptionalPick<ServiceHookOverloads<S>, keyof S>;
+export type FeathersService<A = FeathersApplication, S = Service> = S &
+  ServiceAddons<A, S> &
+  OptionalPick<ServiceHookOverloads<S>, keyof S>
+
+export type CustomMethods<T extends { [key: string]: [any, any] }> = {
+  [K in keyof T]: (data: T[K][0], params?: Params) => Promise<T[K][1]>
+}
+
+/**
+ * An interface usually use by transport clients that represents a e.g. HTTP or websocket
+ * connection that can be configured on the application.
+ */
+export type TransportConnection<Services = any> = {
+  (app: Application<Services>): void
+  Service: any
+  service: <L extends keyof Services & string>(
+    name: L
+  ) => keyof any extends keyof Services ? ServiceInterface : Services[L]
+}
 
-export type CustomMethod<Methods extends string> = {
-  [k in Methods]: <X = any> (data: any, params?: Params) => Promise<X>;
+/**
+ * A real-time connection object
+ */
+export interface RealTimeConnection {
+  [key: string]: any
 }
 
-export type ServiceMixin<A> = (service: FeathersService<A>, path: string, options?: ServiceOptions) => void;
+/**
+ * The interface for a custom service method. Can e.g. be used to type client side services.
+ */
+export type CustomMethod<T = any, R = T, P extends Params = Params> = (data: T, params?: P) => Promise<R>
 
-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 type ServiceMixin<A> = (service: FeathersService<A>, path: string, options: ServiceOptions) => void
 
-export interface FeathersApplication<ServiceTypes = any, AppSettings = any> {
+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 type ServiceGenericParams<S> = S extends ServiceInterface<infer _T, infer _D, infer P> ? P : any
+
+export interface FeathersApplication<Services = any, Settings = any> {
   /**
    * The Feathers application version
    */
-  version: string;
+  version: string
 
   /**
    * A list of callbacks that run when a new service is registered
    */
-  mixins: ServiceMixin<Application<ServiceTypes, AppSettings>>[];
+  mixins: ServiceMixin<Application<Services, Settings>>[]
 
   /**
    * The index of all services keyed by their path.
@@ -132,30 +209,25 @@ export interface FeathersApplication<ServiceTypes = any, AppSettings = any> {
    * __Important:__ Services should always be retrieved via `app.service('name')`
    * not via `app.services`.
    */
-  services: ServiceTypes;
+  services: Services
 
   /**
    * The application settings that can be used via
    * `app.get` and `app.set`
    */
-  settings: AppSettings;
+  settings: Settings
 
   /**
    * 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>;
+  _isSetup: boolean
 
   /**
    * Retrieve an application setting by name
    *
    * @param name The setting name
    */
-  get<L extends keyof AppSettings & string> (name: L): AppSettings[L];
+  get<L extends keyof Settings & string>(name: L): Settings[L]
 
   /**
    * Set an application setting
@@ -163,14 +235,14 @@ export interface FeathersApplication<ServiceTypes = any, AppSettings = any> {
    * @param name The setting name
    * @param value The setting value
    */
-  set<L extends keyof AppSettings & string> (name: L, value: AppSettings[L]): this;
+  set<L extends keyof Settings & string>(name: L, value: Settings[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;
+  configure(callback: (this: this, app: this) => void): this
 
   /**
    * Returns a fallback service instance that will be registered
@@ -179,7 +251,7 @@ export interface FeathersApplication<ServiceTypes = any, AppSettings = any> {
    *
    * @param location The path of the service
    */
-  defaultService (location: string): ServiceInterface<any>;
+  defaultService(location: string): ServiceInterface
 
   /**
    * Register a new service or a sub-app. When passed another
@@ -191,11 +263,20 @@ export interface FeathersApplication<ServiceTypes = any, AppSettings = any> {
    * Feathers application to use a sub-app under the `path` prefix.
    * @param options The options for this service
    */
-  use<L extends keyof ServiceTypes & string> (
+  use<L extends keyof Services & string>(
     path: L,
-    service: keyof any extends keyof ServiceTypes ? ServiceInterface<any> | Application : ServiceTypes[L],
-    options?: ServiceOptions
-  ): this;
+    service: keyof any extends keyof Services ? ServiceInterface | Application : Services[L],
+    options?: ServiceOptions<keyof any extends keyof Services ? string : keyof Services[L]>
+  ): this
+
+  /**
+   * Unregister an existing service.
+   *
+   * @param path The name of the service to unregister
+   */
+  unuse<L extends keyof Services & string>(
+    path: L
+  ): Promise<FeathersService<this, keyof any extends keyof Services ? Service : Services[L]>>
 
   /**
    * Get the Feathers service instance for a path. This will
@@ -204,92 +285,119 @@ export interface FeathersApplication<ServiceTypes = any, AppSettings = any> {
    *
    * @param path The name of the service.
    */
-  service<L extends keyof ServiceTypes & string> (
+  service<L extends keyof Services & string>(
     path: L
-  ): FeathersService<this, keyof any extends keyof ServiceTypes ? Service<any> : ServiceTypes[L]>;
+  ): FeathersService<this, keyof any extends keyof Services ? Service : Services[L]>
+
+  /**
+   * Set up the application and call all services `.setup` method if available.
+   *
+   * @param server A server instance (optional)
+   */
+  setup(server?: any): Promise<this>
 
-  setup (server?: any): Promise<this>;
+  /**
+   * Tear down the application and call all services `.teardown` method if available.
+   *
+   * @param server A server instance (optional)
+   */
+  teardown(server?: any): Promise<this>
 
   /**
    * Register application level hooks.
    *
    * @param map The application hook settings.
    */
-  hooks (map: HookOptions<this, any>): this;
+  hooks(map: ApplicationHookOptions<this>): 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 interface Application<Services = any, Settings = any>
+  extends FeathersApplication<Services, Settings>,
+    EventEmitter {}
 
-}
-
-export type Id = number | string;
-export type NullableId = Id | null;
+export type Id = number | string
+export type NullableId = Id | null
 
 export interface Query {
-  [key: string]: any;
+  [key: string]: any
+}
+
+export interface Params<Q = Query> {
+  query?: Q
+  provider?: string
+  route?: { [key: string]: any }
+  headers?: { [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 Http {
+  /**
+   * A writeable, optional property with status code override.
+   */
+  status?: number
+  /**
+   * A writeable, optional property with headers.
+   */
+  headers?: { [key: string]: string | string[] }
+  /**
+   * A writeable, optional property with `Location` header's value.
+   */
+  location?: string
 }
 
+export type HookType = 'before' | 'after' | 'error' | 'around'
+
 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;
+  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;
+  readonly method: string
   /**
    * A read only property and contains the service name (or path) without leading or
    * trailing slashes.
    */
-  readonly path: string;
+  readonly path: string
   /**
    * A read only property and contains the service this hook currently runs on.
    */
-  readonly service: S;
+  readonly service: S
   /**
-   * A read only property with the hook type (one of before, after or error).
-   * Will be `null` for asynchronous hooks.
+   * A read only property with the hook type (one of 'around', 'before', 'after' or 'error').
    */
-  readonly type: null | 'before' | 'after' | 'error';
+  readonly type: HookType
   /**
    * The list of method arguments. Should not be modified, modify the
    * `params`, `data` and `id` properties instead.
    */
-  readonly arguments: any[];
+  readonly arguments: any[]
   /**
    * A writeable property containing the data of a create, update and patch service
    * method call.
    */
-  data?: ServiceGenericData<S>;
+  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;
+  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;
+  id?: Id
   /**
    * A writeable property that contains the service method parameters (including
    * params.query).
    */
-  params: Params;
+  params: ServiceGenericParams<S>
   /**
    * A writeable property containing the result of the successful service method call.
    * It is only available in after hooks.
@@ -299,50 +407,76 @@ export interface HookContext<A = Application, S = any> extends BaseHookContext<S
    * - 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>;
+  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>;
+  dispatch?: ServiceGenericType<S>
   /**
    * A writeable, optional property that allows to override the standard HTTP status
    * code that should be returned.
+   *
+   * @deprecated Use `http.status` instead.
    */
-  statusCode?: number;
+  statusCode?: number
+  /**
+   * A writeable, optional property with options specific to HTTP transports.
+   */
+  http?: Http
   /**
    * The event emitted by this method. Can be set to `null` to skip event emitting.
    */
-  event: string|null;
+  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);
+// Regular hook typings
+export type HookFunction<A = Application, S = Service> = (
+  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>;
+export type Hook<A = Application, S = Service> = HookFunction<A, S>
 
-type LegacyHookMethodMap<A, S> =
-  { [L in keyof S]?: SelfOrArray<LegacyHookFunction<A, S>>; } &
-  { all?: SelfOrArray<LegacyHookFunction<A, S>> };
+type HookMethodMap<A, S> = {
+  [L in keyof S]?: SelfOrArray<HookFunction<A, S>>
+} & { all?: SelfOrArray<HookFunction<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>
-}
+type HookTypeMap<A, S> = SelfOrArray<HookFunction<A, S>> | HookMethodMap<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 AroundHookFunction<A = Application, S = Service> = (
+  context: HookContext<A, S>,
+  next: NextFunction
+) => Promise<void>
+
+export type AroundHookMap<A, S> = {
+  [L in keyof S]?: AroundHookFunction<A, S>[]
+} & { all?: AroundHookFunction<A, S>[] }
 
 export type HookMap<A, S> = {
-  [L in keyof S]?: HookFunction<A, S>[];
-};
+  around?: AroundHookMap<A, S>
+  before?: HookTypeMap<A, S>
+  after?: HookTypeMap<A, S>
+  error?: HookTypeMap<A, S>
+}
+
+export type HookOptions<A, S> = AroundHookMap<A, S> | AroundHookFunction<A, S>[] | HookMap<A, S>
+
+export interface ApplicationHookContext<A = Application> extends BaseHookContext {
+  app: A
+  server: any
+}
+
+export type ApplicationHookFunction<A> = (
+  context: ApplicationHookContext<A>,
+  next: NextFunction
+) => Promise<void>
+
+export type ApplicationHookMap<A> = {
+  setup?: ApplicationHookFunction<A>[]
+  teardown?: ApplicationHookFunction<A>[]
+}
 
-export type HookOptions<A, S> =
-  HookMap<A, S> | HookFunction<A, S>[] | LegacyHookMap<A, S>;
+export type ApplicationHookOptions<A> = HookOptions<A, any> | ApplicationHookMap<A>

package/src/events.ts

@@ -1,31 +1,31 @@
-import { NextFunction, EventEmitter } from './dependencies';
-import { HookContext, FeathersService } from './declarations';
-import { getServiceOptions, defaultEventMap } from './service';
+import { EventEmitter } from 'events'
+import { NextFunction } from '@feathersjs/hooks'
+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;
+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;
+  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 ];
+      const results = Array.isArray(context.result) ? context.result : [context.result]
 
-      results.forEach(element => (context as any).self.emit(context.event, element, context));
+      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';
+export function eventMixin<A>(service: FeathersService<A>) {
+  const isEmitter = typeof service.on === 'function' && typeof service.emit === 'function'
 
   if (!isEmitter) {
-    Object.assign(service, EventEmitter.prototype);
+    Object.assign(service, EventEmitter.prototype)
   }
 
-  return service;
+  return service
 }