Narwhals Poke Mammals

    crnk-filtering
    TypeScript icon, indicating that this package has built-in type declarations

    3.3.0 • Public • Published

    Crnk-filtering

    Crnk-filtering is a Typescript package for generating CRNK resource filter strings.

    weekly downloads from npm npm version

    Maintenance code style: prettier FOSSA Status

    Features

    View live demo on StackBlitz.

    Installation

    $ npm install --save crnk-filtering

    Usage

    A filter parameter is represented by a FilterSpec. It holds the path to the attribute, the filter value and the operator. The attribute specifies what gets filtered. The operator specifies how it is filtered. And the value specifies after what should be filtered.

    An example looks like:

    const filterSpecUser = new FilterSpec('user.id', 12, FilterOperator.Equals);

    The filter value is strongly typed. Typically (by default) it is assumed that the filter value matches the attribute type and Crnk will attempt to parse passed String-based filter value accordingly. There are exceptions, for example, the LIKE filter operator always requires the filter value to be a string to support wildcards for not just String types.

    Operators within FilterSpec are represented by the FilterOperator class. By default, QuerySpec uses the EQ operator if no operator was provided. Crnk comes with a set of default filters as in the backend.

    To apply generated CRNK filter in HTTP calls, define HTTP parameter params like in example bellow:

      getData(
        filter: BasicFilter | NestedFilter,
      ): Observable<any> {
        return this.http.get<any>(
          'YOUR_URL',
          {
            params: filter.getHttpParams(),
          }
        );
      }

    Basic filtering

    const basicFilter = new BasicFilter({
    	filterSpecs: [
    		new FilterSpec('user.id', 12, FilterOperator.Equals),
    		new FilterSpec('user.name', 'Dino', FilterOperator.Like),
    		new FilterSpec('user.age', 25, FilterOperator.GreaterOrEquals)
    	]
    }).getHttpParams();

    Above basic filter will result with following string:

    'filter[user.id][EQ]=12&filter[user.name][LIKE]=Dino%&filter[user.age][GE]=25';

    Nested filtering

    const nestedFilter = new NestedFilter({
    	filterSpecs: [
    		new FilterSpec('user.id', 12, FilterOperator.Equals),
    		new FilterSpec('user.name', 'Dino', FilterOperator.Like),
    		new FilterSpec('user.age', 25, FilterOperator.GreaterOrEquals)
    	],
    	nestingCondition: NestingOperator.And
    }).getHttpParams();

    Above nested filter will result with the following string:

    {"AND":
        [
          {"user": {"EQ": {"id": "12"}}},
          {"user": {"LIKE": {"name": "Dino%"}}},
          {"user": {"GE": {"age": "25"}}},
        ]
    }

    It also supports creating a nested filter inside already nested filter string like in below example: {"name": "Great Task", "OR": {"id": 122, "name": "Other Task"}}

    // First create inner nested filter string:
    const innerNestedFilter = new NestedFilter({filterSpecs: innerFilterSpecArray, nestingCondition: NestingOperator.Or});
    // Example of created part filter string:
    {"OR": [{"user":{"EQ": {"id": "100"}}}, {"user":{"EQ": {"age": "30"}}}]}
    
    // Then create main filter string calling this method:
    const nestedFilter = new NestedFilter({filterSpecs: filterSpecArray, nestingCondition: NestingOperator.And, innerNestedFilter: innerNestedFilter.buildFilterString()}); // You can add multiple inner nested filters
    
    // Result example of the whole filter string:
    {"AND": [{"EQ": {"zip": "70"}}, {"OR": [{"user":{"EQ": {"id": "100"}}}, {"user":{"EQ": {"age": "30"}}}]}]}

    Sorting filtering

    Sorting information for the resources can be achieved by providing SortSpec parameter.

    const sortSpec = new SortSpec('user.id', SortDirection.ASC);

    Sorting parameters are represented by SortSpec similar to FilterSpec above.

    An example looks like:

    const basicFilter = new BasicFilter({
    	filterSpecs: [
    		new FilterSpec('user.id', 12, FilterOperator.Equals),
    		new FilterSpec('user.name', 'Dino', FilterOperator.Like),
    		new FilterSpec('user.age', 25, FilterOperator.GreaterOrEquals)
    	]
    });
    
    basicFilter.sortBy([
    	new SortSpec('user.id', SortDirection.ASC),
    	new SortSpec('user.name', SortDirection.DESC)
    ]);
    
    ('filter[user.id][EQ]=12&filter[user.name][LIKE]=Dino%&filter[user.age][GE]=25&sort=user.id,-user.name');

    The same logic applied for creating sorting with nesting filter string.

    Inclusion of Related Resources

    Information about relationships to include in the response can be achieved by providing an includeResources parameters.

    const basicFilter = new BasicFilter({
    	filterSpecs: [
    		new FilterSpec('user.id', 12, FilterOperator.Equals),
    		new FilterSpec('user.name', 'Dino', FilterOperator.Like),
    		new FilterSpec(
    			'client.personalInfo.age',
    			25,
    			FilterOperator.GreaterOrEquals
    		)
    	],
    	relatedResources: ['client', 'car'] // Included resources
    }).getHttpParams();
    
    basicFilter.sortBy([
    	new SortSpec('client.id', SortDirection.ASC),
    	new SortSpec('car.name', SortDirection.DESC)
    ]);
    
    // basicFilter.getHttpParams() returns:
    ('include=client,car&filter[user.id][EQ]=12&filter[user.name][LIKE]=Dino%&filter[client.personalInfo.age][GE]=25&sort=client.id,-car.name');

    It is important to note that the requested main resource will be affected by included filter params or sorting params.

    Pagination

    Crnk filtering can be used with mat-paginator elements in your table component. Pagination comes by default with support for offset/limit paging:

      public paginationSpec: PaginationSpec;
    
      constructor() {
        this.paginationSpec = new PaginationSpec(); // creates default paging with params - pageIndex = 0, pageSize = 10, length = 0
    
        // Or create custom pagination specification
        this.paginationSpec = new PaginationSpec(); // creates default paging with params - pageIndex = 1, pageSize = 20, length = 10
      }

    Example of URL:

    GET /tasks?page[offset]=0&page[limit]=10

    It is only useful with Angular material tables and declared mat-paginator in HTML:

    <mat-paginator
    	showFirstLastButtons
    	[pageSizeOptions]="[10, 25, 50, 100, 200]"
    	[length]="paginationSpec.pageEvent.length"
    	[pageSize]="paginationSpec.pageEvent.pageSize"
    	[pageIndex]="0"
    	(page)="onChangePaginatorPage($event)"
    ></mat-paginator>

    In the component are declared methods to track changing page events and resetting pagination:

      onChangePaginatorPage(e: PageEvent): void {
        this.paginationSpec.setPagination(e);
        // Fetch data again
      }
    
      // Resetting pagination
      resetPagination(): void {
        this.paginationSpec.resetPaginator();
      }

    To apply generated pagination, define HTTP parameter params like in example bellow:

      getData(
        filter: BasicFilter | NestedFilter,
        paginationSpec: PaginationSpec
      ): Observable<any> {
        return this.http.get<any>(
          'YOUR_URL',
          {
            params: paginationSpec.setHttpParams(filter.getHttpParams()),
          }
        );
      }
    
    // paginationSpec.setHttpParams(filter.getHttpParams()) returns example:
    ("filter[user.id][EQ]=12&filter[user.name][LIKE]=Dino%&filter[client.personalInfo.age][GE]=25&sort=client.id,-car.name&page[limit]=10&page[offset]=0");

    Sparse fieldsets

    Information about fields to include in the response can be achieved by providing fields parameter:

    GET /tasks?fields=name,description

    const nestedFilter = new NestedFilter({
    	filterSpecs: [
    		new FilterSpec('user.id', 12, FilterOperator.Equals),
    		new FilterSpec('user.name', 'Dino', FilterOperator.Like),
    		new FilterSpec('user.age', 25, FilterOperator.GreaterOrEquals)
    	],
    	nestingCondition: NestingOperator.And,
    	sparseFieldsets: ['user.id', 'user.age'] // include those fields in the response
    }).getHttpParams();

    License

    Apache License

    Copyright (c) 2021 Dino Klicek

    Install

    npm i crnk-filtering

    DownloadsWeekly Downloads

    0

    Version

    3.3.0

    License

    Apache

    Unpacked Size

    268 kB

    Total Files

    33

    Last publish

    Collaborators

    • dklicek