feat: simplify filter and where usage for constraint, schema, and OpenAPI mapping

docs/site/Controller-generator.md

@@ -100,6 +100,7 @@ import {
   Count,
   CountSchema,
   Filter,
+  FilterExcludingWhere,
   repository,
   Where
 } from '@loopback/repository';
@@ -152,7 +153,7 @@ export class TodoController {
     },
   })
   async count(
-    @param.query.object('where', getWhereSchemaFor(Todo)) where?: Where<Todo>,
+    @param.where(Todo) where?: Where<Todo>,
   ): Promise<Count> {
     return this.todoRepository.count(where);
   }
@@ -170,7 +171,7 @@ export class TodoController {
     },
   })
   async find(
-    @param.query.object('filter', getFilterSchemaFor(Todo))
+    @param.filter(Todo)
     filter?: Filter<Todo>,
   ): Promise<Todo[]> {
     return this.todoRepository.find(filter);
@@ -193,7 +194,7 @@ export class TodoController {
       },
     })
     todo: Partial<Todo>
-    @param.query.object('where', getWhereSchemaFor(Todo)) where?: Where<Todo>,
+    @param.where(Todo) where?: Where<Todo>,
   ): Promise<Count> {
     return this.todoRepository.updateAll(todo, where);
   }
@@ -212,7 +213,7 @@ export class TodoController {
   })
   async findById(
     @param.path.number('id') id: number,
-    @param.query.object('filter', getFilterSchemaFor(Todo)) filter?: Filter<Todo>
+    @param.filter(Todo, {exclude: 'where'}) filter?: FilterExcludingWhere<Todo>
   ): Promise<Todo> {
     return this.todoRepository.findById(id, filter);
   }

docs/site/Sequence.md

@@ -241,7 +241,7 @@ from the path object.
 })
 async findById(
   @param.path.string('id') id: string,
-  @param.query.object('filter', getFilterSchemaFor(Note)) filter?: Filter<Note>
+  @param.filter(Note, {exclude: 'where'}) filter?: FilterExcludingWhere<Note>
 ): Promise<Note> {
   return this.noteRepository.findById(id, filter);
 }

docs/site/decorators/Decorators_openapi.md

@@ -794,3 +794,63 @@ This decorator does not affect the top-level `tags` section defined in the
 [OpenAPI Tag Object specification](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#tag-object).
 This decorator only affects the spec partial generated at the class level. You
 may find that your final tags also include a tag for the controller name.
+
+## Shortcuts for Filter and Where params
+
+CRUD APIs often expose REST endpoints that take `filter` and `where` query
+parameters. For example:
+
+```ts
+class TodoController {
+  async find(
+    @param.query.object('filter', getFilterSchemaFor(Todo))
+    filter?: Filter<Todo>,
+  ): Promise<Todo[]> {
+    return this.todoRepository.find(filter);
+  }
+
+  async findById(
+    @param.path.number('id') id: number,
+    @param.query.object('filter', getFilterSchemaFor(Todo))
+    filter?: Filter<Todo>,
+  ): Promise<Todo> {
+    return this.todoRepository.findById(id, filter);
+  }
+
+  async count(
+    @param.query.object('where', getWhereSchemaFor(Todo)) where?: Where<Todo>,
+  ): Promise<Count> {
+    return this.todoRepository.count(where);
+  }
+}
+```
+
+To simplify the parameter decoration for `filter` and `where`, we introduce two
+sugar decorators:
+
+- `@param.filter`: For a `filter` query parameter
+- `@param.where`: For a `where` query parameter
+
+Now the code from above can be refined as follows:
+
+```ts
+class TodoController {
+  async find(
+    @param.filter(Todo)
+    filter?: Filter<Todo>,
+  ): Promise<Todo[]> {
+    return this.todoRepository.find(filter);
+  }
+
+  async findById(
+    @param.path.number('id') id: number,
+    @param.filter(Todo, {exclude: 'where'}) filter?: FilterExcludingWhere<Todo>,
+  ): Promise<Todo> {
+    return this.todoRepository.findById(id, filter);
+  }
+
+  async count(@param.where(Todo) where?: Where<Todo>): Promise<Count> {
+    return this.todoRepository.count(where);
+  }
+}
+```

examples/express-composition/src/controllers/note.controller.ts

@@ -13,9 +13,7 @@ import {
 import {
   del,
   get,
-  getFilterSchemaFor,
   getModelSchemaRef,
-  getWhereSchemaFor,
   param,
   patch,
   post,
@@ -60,9 +58,7 @@ export class NoteController {
       },
     },
   })
-  async count(
-    @param.query.object('where', getWhereSchemaFor(Note)) where?: Where<Note>,
-  ): Promise<Count> {
+  async count(@param.where(Note) where?: Where<Note>): Promise<Count> {
     return this.noteRepository.count(where);
   }
 
@@ -79,7 +75,7 @@ export class NoteController {
     },
   })
   async find(
-    @param.query.object('filter', getFilterSchemaFor(Note))
+    @param.filter(Note)
     filter?: Filter<Note>,
   ): Promise<Note[]> {
     return this.noteRepository.find(filter);
@@ -102,7 +98,7 @@ export class NoteController {
       },
     })
     note: Partial<Note>,
-    @param.query.object('where', getWhereSchemaFor(Note)) where?: Where<Note>,
+    @param.where(Note) where?: Where<Note>,
   ): Promise<Count> {
     return this.noteRepository.updateAll(note, where);
   }

examples/todo-list/src/controllers/todo-list-todo.controller.ts

@@ -14,7 +14,6 @@ import {
   del,
   get,
   getModelSchemaRef,
-  getWhereSchemaFor,
   param,
   patch,
   post,
@@ -91,7 +90,7 @@ export class TodoListTodoController {
       },
     })
     todo: Partial<Todo>,
-    @param.query.object('where', getWhereSchemaFor(Todo)) where?: Where<Todo>,
+    @param.where(Todo) where?: Where<Todo>,
   ): Promise<Count> {
     return this.todoListRepo.todos(id).patch(todo, where);
   }
@@ -106,7 +105,7 @@ export class TodoListTodoController {
   })
   async delete(
     @param.path.number('id') id: number,
-    @param.query.object('where', getWhereSchemaFor(Todo)) where?: Where<Todo>,
+    @param.where(Todo) where?: Where<Todo>,
   ): Promise<Count> {
     return this.todoListRepo.todos(id).delete(where);
   }

examples/todo-list/src/controllers/todo-list.controller.ts

@@ -7,6 +7,7 @@ import {
   Count,
   CountSchema,
   Filter,
+  FilterExcludingWhere,
   repository,
   Where,
 } from '@loopback/repository';
@@ -15,7 +16,6 @@ import {
   get,
   getFilterSchemaFor,
   getModelSchemaRef,
-  getWhereSchemaFor,
   param,
   patch,
   post,
@@ -63,7 +63,7 @@ export class TodoListController {
     },
   })
   async count(
-    @param.query.object('where', getWhereSchemaFor(TodoList))
+    @param.where(TodoList)
     where?: Where<TodoList>,
   ): Promise<Count> {
     return this.todoListRepository.count(where);
@@ -85,7 +85,7 @@ export class TodoListController {
     },
   })
   async find(
-    @param.query.object('filter', getFilterSchemaFor(TodoList))
+    @param.filter(TodoList)
     filter?: Filter<TodoList>,
   ): Promise<TodoList[]> {
     return this.todoListRepository.find(filter);
@@ -108,7 +108,7 @@ export class TodoListController {
       },
     })
     todoList: Partial<TodoList>,
-    @param.query.object('where', getWhereSchemaFor(TodoList))
+    @param.where(TodoList)
     where?: Where<TodoList>,
   ): Promise<Count> {
     return this.todoListRepository.updateAll(todoList, where);
@@ -128,8 +128,11 @@ export class TodoListController {
   })
   async findById(
     @param.path.number('id') id: number,
-    @param.query.object('filter', getFilterSchemaFor(TodoList))
-    filter?: Filter<TodoList>,
+    @param.query.object(
+      'filter',
+      getFilterSchemaFor(TodoList, {exclude: 'where'}),
+    )
+    filter?: FilterExcludingWhere<TodoList>,
   ): Promise<TodoList> {
     return this.todoListRepository.findById(id, filter);
   }

examples/todo-list/src/controllers/todo.controller.ts

@@ -7,7 +7,6 @@ import {Filter, repository} from '@loopback/repository';
 import {
   del,
   get,
-  getFilterSchemaFor,
   getModelSchemaRef,
   param,
   patch,
@@ -58,7 +57,7 @@ export class TodoController {
   })
   async findTodoById(
     @param.path.number('id') id: number,
-    @param.query.object('filter', getFilterSchemaFor(Todo))
+    @param.filter(Todo)
     filter?: Filter<Todo>,
   ): Promise<Todo> {
     return this.todoRepository.findById(id, filter);
@@ -80,7 +79,7 @@ export class TodoController {
     },
   })
   async findTodos(
-    @param.query.object('filter', getFilterSchemaFor(Todo))
+    @param.filter(Todo)
     filter?: Filter<Todo>,
   ): Promise<Todo[]> {
     return this.todoRepository.find(filter);

examples/todo/src/controllers/todo.controller.ts

@@ -8,7 +8,6 @@ import {Filter, repository} from '@loopback/repository';
 import {
   del,
   get,
-  getFilterSchemaFor,
   getModelSchemaRef,
   HttpErrors,
   param,
@@ -90,7 +89,7 @@ export class TodoController {
     },
   })
   async findTodos(
-    @param.query.object('filter', getFilterSchemaFor(Todo))
+    @param.filter(Todo)
     filter?: Filter<Todo>,
   ): Promise<Todo[]> {
     return this.todoRepository.find(filter);

packages/cli/generators/controller/templates/src/controllers/controller-rest-template.ts.ejs

@@ -2,6 +2,7 @@ import {
   Count,
   CountSchema,
   Filter,
+  FilterExcludingWhere,
   repository,
   Where,
 } from '@loopback/repository';
@@ -59,7 +60,7 @@ export class <%= className %>Controller {
     },
   })
   async count(
-    @param.query.object('where', getWhereSchemaFor(<%= modelName %>)) where?: Where<<%= modelName %>>,
+    @param.where(<%= modelName %>) where?: Where<<%= modelName %>>,
   ): Promise<Count> {
     return this.<%= repositoryNameCamel %>.count(where);
   }
@@ -80,7 +81,7 @@ export class <%= className %>Controller {
     },
   })
   async find(
-    @param.query.object('filter', getFilterSchemaFor(<%= modelName %>)) filter?: Filter<<%= modelName %>>,
+    @param.filter(<%= modelName %>) filter?: Filter<<%= modelName %>>,
   ): Promise<<%= modelName %>[]> {
     return this.<%= repositoryNameCamel %>.find(filter);
   }
@@ -102,7 +103,7 @@ export class <%= className %>Controller {
       },
     })
     <%= modelVariableName %>: <%= modelName %>,
-    @param.query.object('where', getWhereSchemaFor(<%= modelName %>)) where?: Where<<%= modelName %>>,
+    @param.where(<%= modelName %>) where?: Where<<%= modelName %>>,
   ): Promise<Count> {
     return this.<%= repositoryNameCamel %>.updateAll(<%= modelVariableName %>, where);
   }
@@ -121,7 +122,7 @@ export class <%= className %>Controller {
   })
   async findById(
     @param.path.<%= idType %>('id') id: <%= idType %>,
-    @param.query.object('filter', getFilterSchemaFor(<%= modelName %>)) filter?: Filter<<%= modelName %>>
+    @param.filter(<%= modelName %>, {exclude: 'where'}) filter?: FilterExcludingWhere<<%= modelName %>>
   ): Promise<<%= modelName %>> {
     return this.<%= repositoryNameCamel %>.findById(id, filter);
   }