feat(adapter): Add patch data type to adapters and refactor AdapterBa…

…se usage (#2906)

docs/api/databases/common.md

@@ -39,11 +39,15 @@ app.use('/messages', service({ id, events, paginate }))
 ### Options
 
 - `id` (_optional_) - The name of the id field property (usually set by default to `id` or `_id`).
-- `events` (_optional_) - A list of [custom service events](../events.md#custom-events) sent by this service
 - `paginate` (_optional_) - A [pagination object](#pagination) containing a `default` and `max` page size
-- `allow` (_optional_) - A list of additional non-standard query parameters to allow (e.g `[ '$regex', '$populate' ]`)
 - `multi` (_optional_, default: `false`) - Allow `create` with arrays and `patch` and `remove` with id `null` to change multiple items. Can be `true` for all methods or an array of allowed methods (e.g. `[ 'remove', 'create' ]`)
 
+The following legacy options are still available but should be avoided:
+
+- `events` (_optional_, **deprecated**) - A list of [custom service events](../events.md#custom-events) sent by this service. Use the `events` option when [registering the service with app.use](../application.md#usepath-service--options) instead.
+- `operators` (_optional_, **deprecated**) - A list of additional non-standard query parameters to allow (e.g `[ '$regex' ]`). Not necessary when using a [query schema validator](../schema/validators.md#validatequery)
+- `filters` (_optional_, **deprecated**) - A list of top level `$` query parameters to allow (e.g. `[ '$populate' ]`). Not necessary when using a [query schema validator](../schema/validators.md#validatequery)
+
 ## Pagination
 
 When initializing an adapter you can set the following pagination options in the `paginate` object:
@@ -92,13 +96,17 @@ app.service('todos').find({
 })
 ```
 
-> **Note:** Disabling or changing the default pagination is not available in the client. Only `params.query` is passed to the server (also see a [workaround here](https://github.com/feathersjs/feathers/issues/382#issuecomment-238407741))
+<BlockQuote type="info" label="note">
+
+Disabling or changing the default pagination is not available in the client. Only `params.query` is passed to the server (also see a [workaround here](https://github.com/feathersjs/feathers/issues/382#issuecomment-238407741))
+
+</BlockQuote>
 
 ## Extending Adapters
 
-There are two ways to extend existing database adapters. Either by extending the ES6 base class or by adding functionality through hooks.
+There are two ways to extend existing database adapters. Either by extending the base class or by adding functionality through hooks.
 
-### Classes (ES6)
+### Classes
 
 All modules also export an [ES6 class](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Classes) as `Service` that can be directly extended like this:
 

packages/adapter-commons/src/declarations.ts

@@ -1,4 +1,4 @@
-import { Query, Params, Paginated, Id, NullableId } from '@feathersjs/feathers'
+import { Query, Params, Paginated, Id } from '@feathersjs/feathers'
 
 export type FilterQueryOptions = {
   filters?: FilterSettings
@@ -34,19 +34,23 @@ export interface AdapterServiceOptions {
   paginate?: PaginationParams
   /**
    * A list of additional property query operators to allow in a query
+   *
+   * @deprecated No longer needed when a query schema is used
    */
   operators?: string[]
   /**
    * An object of additional top level query filters, e.g. `{ $populate: true }`
    * Can also be a converter function like `{ $ignoreCase: (value) => value === 'true' ? true : false }`
+   *
+   * @deprecated No longer needed when a query schema is used
    */
   filters?: FilterSettings
   /**
    * @deprecated Use service `events` option when registering the service with `app.use`.
    */
   events?: string[]
   /**
-   * @deprecated renamed to `operators`.
+   * @deprecated No longer needed when a query schema is used
    */
   whitelist?: string[]
 }
@@ -80,16 +84,22 @@ export interface AdapterParams<
  *
  * @see {@link https://docs.feathersjs.com/guides/migrating.html#hook-less-service-methods}
  */
-export interface InternalServiceMethods<T = any, D = T, P extends AdapterParams = AdapterParams> {
+export interface InternalServiceMethods<
+  Result = any,
+  Data = Result,
+  PatchData = Partial<Data>,
+  Params extends AdapterParams = AdapterParams,
+  IdType = Id
+> {
   /**
    * Retrieve all resources from this service.
    * Does not sanitize the query and should only be used on the server.
    *
    * @param _params - Service call parameters {@link Params}
    */
-  $find(_params?: P & { paginate?: PaginationOptions }): Promise<Paginated<T>>
-  $find(_params?: P & { paginate: false }): Promise<T[]>
-  $find(params?: P): Promise<T[] | Paginated<T>>
+  _find(_params?: Params & { paginate?: PaginationOptions }): Promise<Paginated<Result>>
+  _find(_params?: Params & { paginate: false }): Promise<Result[]>
+  _find(params?: Params): Promise<Result[] | Paginated<Result>>
 
   /**
    * Retrieve a single resource matching the given ID, skipping any service-level hooks.
@@ -100,7 +110,7 @@ export interface InternalServiceMethods<T = any, D = T, P extends AdapterParams
    * @see {@link HookLessServiceMethods}
    * @see {@link https://docs.feathersjs.com/api/services.html#get-id-params|Feathers API Documentation: .get(id, params)}
    */
-  $get(id: Id, params?: P): Promise<T>
+  _get(id: IdType, params?: Params): Promise<Result>
 
   /**
    * Create a new resource for this service, skipping any service-level hooks.
@@ -111,9 +121,9 @@ export interface InternalServiceMethods<T = any, D = T, P extends AdapterParams
    * @see {@link HookLessServiceMethods}
    * @see {@link https://docs.feathersjs.com/api/services.html#create-data-params|Feathers API Documentation: .create(data, params)}
    */
-  $create(data: Partial<D>, params?: P): Promise<T>
-  $create(data: Partial<D>[], params?: P): Promise<T[]>
-  $create(data: Partial<D> | Partial<D>[], params?: P): Promise<T | T[]>
+  _create(data: Data, params?: Params): Promise<Result>
+  _create(data: Data[], params?: Params): Promise<Result[]>
+  _create(data: Data | Data[], params?: Params): Promise<Result | Result[]>
 
   /**
    * Completely replace the resource identified by id, skipping any service-level hooks.
@@ -125,7 +135,7 @@ export interface InternalServiceMethods<T = any, D = T, P extends AdapterParams
    * @see {@link HookLessServiceMethods}
    * @see {@link https://docs.feathersjs.com/api/services.html#update-id-data-params|Feathers API Documentation: .update(id, data, params)}
    */
-  $update(id: Id, data: D, params?: P): Promise<T>
+  _update(id: IdType, data: Data, params?: Params): Promise<Result>
 
   /**
    * Merge any resources matching the given ID with the given data, skipping any service-level hooks.
@@ -137,9 +147,9 @@ export interface InternalServiceMethods<T = any, D = T, P extends AdapterParams
    * @see {@link HookLessServiceMethods}
    * @see {@link https://docs.feathersjs.com/api/services.html#patch-id-data-params|Feathers API Documentation: .patch(id, data, params)}
    */
-  $patch(id: null, data: Partial<D>, params?: P): Promise<T[]>
-  $patch(id: Id, data: Partial<D>, params?: P): Promise<T>
-  $patch(id: NullableId, data: Partial<D>, params?: P): Promise<T | T[]>
+  _patch(id: null, data: PatchData, params?: Params): Promise<Result[]>
+  _patch(id: IdType, data: PatchData, params?: Params): Promise<Result>
+  _patch(id: IdType | null, data: PatchData, params?: Params): Promise<Result | Result[]>
 
   /**
    * Remove resources matching the given ID from the this service, skipping any service-level hooks.
@@ -150,7 +160,7 @@ export interface InternalServiceMethods<T = any, D = T, P extends AdapterParams
    * @see {@link HookLessServiceMethods}
    * @see {@link https://docs.feathersjs.com/api/services.html#remove-id-params|Feathers API Documentation: .remove(id, params)}
    */
-  $remove(id: null, params?: P): Promise<T[]>
-  $remove(id: Id, params?: P): Promise<T>
-  $remove(id: NullableId, params?: P): Promise<T | T[]>
+  _remove(id: null, params?: Params): Promise<Result[]>
+  _remove(id: IdType, params?: Params): Promise<Result>
+  _remove(id: IdType | null, params?: Params): Promise<Result | Result[]>
 }