From 0d4810c1b84c418401e6d8352c5d2906d8107cff Mon Sep 17 00:00:00 2001 From: tada5hi Date: Sun, 14 Jan 2024 19:36:59 +0100 Subject: [PATCH] docs: updated documentation --- docs/guide/fields-api-reference.md | 49 +++++++ docs/guide/filters-api-reference.md | 48 ++++++ docs/guide/pagination-api-reference.md | 47 ++++++ docs/guide/parse-api-reference.md | 193 +++---------------------- docs/guide/relations-api-reference.md | 48 ++++++ docs/guide/sort-api-reference.md | 48 ++++++ src/parse/parameter/type.ts | 10 +- 7 files changed, 262 insertions(+), 181 deletions(-) diff --git a/docs/guide/fields-api-reference.md b/docs/guide/fields-api-reference.md index 0e5daf5..adc7da4 100644 --- a/docs/guide/fields-api-reference.md +++ b/docs/guide/fields-api-reference.md @@ -1,5 +1,54 @@ # Fields +## `parseQueryFields` + +**Type** +```ts +declare function parseQueryFields( + input: unknown, + options?: FieldsParseOptions +): FieldsParseOutput +``` + +**Example** + +```typescript +import { + parseQueryFields, +} from 'rapiq'; + +const output = parseQueryFields( + ['+name'], + { + allowed: ['id', 'name'], + defaultAlias: 'user' + } +); + +console.log(output); +// [{key: 'id', value: FieldOperator.INCLUDE}] || +// [{key: 'id', value: '+'}] +``` + +**Type parameters** + +| Name | Description | +|:------|:------------| + + +**Parameters** + +| Name | Type | Description | +|:----------|:------------------------|:-------------------------------------------------------------| +| `input` | `unknown` | Query input data passed e.g. via URL . | +| `options` | `FieldsParseOptions` | Options for parsing fields data [more](#fieldsparseoptions). | + +**Returns** + +[FieldsParseOutput](#fieldsparseoutput) + +The function returns an object. + ## `FieldsBuildInput` The following types are defined, to illustrate which kind of input data is covered by the `FieldsBuildInput` type. diff --git a/docs/guide/filters-api-reference.md b/docs/guide/filters-api-reference.md index 9d6d521..8b12101 100644 --- a/docs/guide/filters-api-reference.md +++ b/docs/guide/filters-api-reference.md @@ -1,5 +1,53 @@ # Filters +## `parseQueryFilters` + +**Type** +```ts +declare function parseQueryFilters( + input: unknown, + options?: FiltersParseOptions +): FiltersParseOutput +``` + +**Example** + +```typescript +import { + parseQueryFilters +} from 'rapiq'; + +const output = parseQueryFilters( + {id: 1}, + { + allowed: ['id', 'name'], + defaultAlias: 'user' + } +); + +console.log(output); +// [{alias: 'user', key: 'id', value: 1, }] +``` + +**Type parameters** + +| Name | Description | +|:------|:------------| + + +**Parameters** + +| Name | Type | Description | +|:----------|:-------------------------|:---------------------------------------------------------------| +| `input` | `unknown` | Query input data passed e.g. via URL . | +| `options` | `FiltersParseOptions` | Options for parsing filters data [more](#filtersparseoptions). | + +**Returns** + +[FiltersParseOutput](#filtersparseoutput) + +The function returns an object. + ## `FiltersBuildInput` The following types are defined, to illustrate which kind of input data is covered by the diff --git a/docs/guide/pagination-api-reference.md b/docs/guide/pagination-api-reference.md index b5bdd91..7011681 100644 --- a/docs/guide/pagination-api-reference.md +++ b/docs/guide/pagination-api-reference.md @@ -1,5 +1,52 @@ # Pagination +## `parseQueryPagination` + +**Type** +```ts +declare function parseQueryPagination( + input: unknown, + options?: PaginationParseOptions +): PaginationParseOutput +``` + +**Example** + +```typescript +import { + parseQueryPagination +} from 'rapiq'; + +const output = parseQueryPagination( + {limit: 100}, + { + maxLimit: 50 + } +); + +console.log(output); +// {limit: 50} +``` + +**Type parameters** + +| Name | Description | +|:------|:------------| + + +**Parameters** + +| Name | Type | Description | +|:----------|:----------------------------|:---------------------------------------------------------------------| +| `input` | `unknown` | Query input data passed e.g. via URL . | +| `options` | `PaginationParseOptions` | Options for parsing pagination data [more](#paginationparseoptions). | + +**Returns** + +[PaginationParseOutput](#paginationparseoutput) + +The function returns an object. + ## `PaginationBuildInput` ```typescript diff --git a/docs/guide/parse-api-reference.md b/docs/guide/parse-api-reference.md index f5b3f7f..0344f65 100644 --- a/docs/guide/parse-api-reference.md +++ b/docs/guide/parse-api-reference.md @@ -59,165 +59,26 @@ The function returns an object. - [ParseOutput](#parseoutput) - [ParseOptions](#parseoptions) -## `parseQueryParameter` - -Parse a query string to an efficient data structure ⚡. The output will -be an object with each possible value of the [Parameter](parameter-api-reference#parameter) enum as property key and the -parsed data as value. - -**Type** -```ts -declare function parseQueryParameter( - key: T, - input: unknown, - options?: ParseParameterOptions -): ParseParameterOutput -``` - -**Example: Fields** - -```typescript -import { - parseQueryParameter, -} from 'rapiq'; - -const output = parseQueryParameter( - // 'fields' || - // Parameter.FIELDS | URLParameter.FIELDS - 'fields', - ['+name'], - { - allowed: ['id', 'name'], - defaultAlias: 'user' - } -); - -console.log(output); -// [{key: 'id', value: FieldOperator.INCLUDE}] || -// [{key: 'id', value: '+'}] -``` - -**Example: Filters** - -```typescript -import { - parseQueryParameter -} from 'rapiq'; - -const output = parseQueryParameter( - // 'filters' | 'filter' | - // Parameter.FILTERS | URLParameter.FILTERS - 'filters', - {id: 1}, - { - allowed: ['id', 'name'], - defaultAlias: 'user' - } -); - -console.log(output); -// [{alias: 'user', key: 'id', value: 1, }] -``` - -**Example: Pagination** - -```typescript -import { - parseQueryParameter -} from 'rapiq'; - -const output = parseQueryParameter( - // 'pagination' | 'page' | - // Parameter.PAGINATION | URLParameter.PAGINATION - 'pagination', - {limit: 100}, - { - maxLimit: 50 - } -); - -console.log(output); -// {limit: 50} -``` - -**Example: Relations** - -```typescript -import { - parseQueryParameter -} from 'rapiq'; - -const output = parseQueryParameter( - // 'relations' || 'include' || - // Parameter.RELATIONS | URLParameter.RELATIONS - 'relations', - ['roles'], - { - allowed: ['roles', 'photos'], - defaultAlias: 'user' - } -); - -console.log(output); -// [{key: 'user.roles', value: 'roles'}] -``` - -**Example: Sort** - -```typescript -import { - parseQueryParameter -} from 'rapiq'; - -const output = parseQueryParameter( - // 'sort' || - // Parameter.SORT || URLParameter.SORT - 'sort', - ['-name'], - { - allowed: ['id', 'name'], - defaultAlias: 'user' - } -); - -console.log(output); -// [{alias: 'user', key: 'name', value: 'DESC'}] -``` - -**Type parameters** - -| Name | Description | -|:------|:------------| - - -**Parameters** - -| Name | Type | Description | -|:----------|:-----------------------------------|:-----------------------------------------------------------------------| -| `input` | `unknown` | Query input data passed e.g. via URL [more](#parseinput). | -| `options` | `ParseParameterOptions` | Options for parsing fields, filter, include, ... [more](#parseoptions) | - -**Returns** - -[ParseOutput](#parseoutput) - -The function returns an object. - ## ParseOptions ```typescript type ParseOptions = { - /** - * On default all query keys are enabled. - */ - [K in Parameter]?: ParseParameterOptions | boolean -} & { + [Parameter.FIELDS]?: FieldsParseOptions | boolean, + [Parameter.FILTERS]?: FiltersParseOptions | boolean, + [Parameter.RELATIONS]?: RelationsParseOptions | boolean, + [Parameter.PAGINATION]?: PaginationParseOptions | boolean, + [Parameter.SORT]?: SortParseOptions | boolean, defaultPath?: string, throwOnFailure?: boolean } ``` **References** -- [ParseParameterOptions](#parseparameteroptions) +- [Parameter](parameter-api-reference#parameter) +- [FieldsParseOptions](fields-api-reference.md#fieldsparseoptions), +- [FiltersParseOptions](filters-api-reference.md#filtersparseoptions) +- [PaginationParseOptions](pagination-api-reference.md#paginationparseoptions) +- [RelationsParseOptions](relations-api-reference.md#relationsparseoptions) +- [SortParseOptions](sort-api-reference.md#sortparseoptions) ## ParseInput @@ -234,35 +95,15 @@ type ParseInput = { ```typescript type ParseOutput = { - [K in Parameter]?: ParseParameterOutput + [Parameter.FIELDS]?: FieldsParseOutput, + [Parameter.FILTERS]?: FiltersParseOutput, + [Parameter.RELATIONS]?: RelationsParseOutput, + [Parameter.PAGINATION]?: PaginationParseOutput, + [Parameter.SORT]?: SortParseOutput, } ``` **References** -- [ParseParameterOutput](#parseparameteroutput) - -## ParseParameterOptions -```typescript -type ParseParameterOptions< - P extends ParameterType | URLParameterType, - T extends Record = Record ->; -``` -is a generic type and returns the available options for a given parameter type: -**References** -- [FieldsParseOptions](fields-api-reference.md#fieldsparseoptions), -- [FiltersParseOptions](filters-api-reference.md#filtersparseoptions) -- [PaginationParseOptions](pagination-api-reference.md#paginationparseoptions) -- [RelationsParseOptions](relations-api-reference.md#relationsparseoptions) -- [SortParseOptions](sort-api-reference.md#sortparseoptions) - -## ParseParameterOutput -```typescript -type ParseParameterOutput

; -``` - -is a generic type and returns the parsed output data for a given parameter type: - -**References** +- [Parameter](parameter-api-reference#parameter) - [FieldsParseOutput](fields-api-reference.md#fieldsparseoutput) - [FiltersParseOutput](filters-api-reference.md#filtersparseoutput) - [PaginationParseOutput](pagination-api-reference.md#paginationparseoutput) diff --git a/docs/guide/relations-api-reference.md b/docs/guide/relations-api-reference.md index 7e1719e..b9bd1e2 100644 --- a/docs/guide/relations-api-reference.md +++ b/docs/guide/relations-api-reference.md @@ -1,5 +1,53 @@ # Relations +## `parseQueryRelations` + +**Type** +```ts +declare function parseQueryRelations( + input: unknown, + options?: RelationsParseOptions +): RelationsParseOutput +``` + +**Example** + +```typescript +import { + parseQueryRelations +} from 'rapiq'; + +const output = parseQueryRelations( + ['roles'], + { + allowed: ['roles', 'photos'], + defaultAlias: 'user' + } +); + +console.log(output); +// [{key: 'user.roles', value: 'roles'}] +``` + +**Type parameters** + +| Name | Description | +|:------|:------------| + + +**Parameters** + +| Name | Type | Description | +|:----------|:---------------------------|:-------------------------------------------------------------------| +| `input` | `unknown` | Query input data passed e.g. via URL . | +| `options` | `RelationsParseOptions` | Options for parsing relations data [more](#relationsparseoptions). | + +**Returns** + +[RelationsParseOutput](#relationsparseoutput) + +The function returns an object. + ## `RelationsBuildInput` The following types are defined, to illustrate which kind of input data is covered by the diff --git a/docs/guide/sort-api-reference.md b/docs/guide/sort-api-reference.md index 3c41655..f67be5d 100644 --- a/docs/guide/sort-api-reference.md +++ b/docs/guide/sort-api-reference.md @@ -1,5 +1,53 @@ # Sort +## `parseQuerySort` + +**Type** +```ts +declare function parseQuerySort( + input: unknown, + options?: SortParseOptions +): SortParseOutput +``` + +**Example** + +```typescript +import { + parseQuerySort +} from 'rapiq'; + +const output = parseQuerySort( + ['-name'], + { + allowed: ['id', 'name'], + defaultAlias: 'user' + } +); + +console.log(output); +// [{alias: 'user', key: 'name', value: 'DESC'}] +``` + +**Type parameters** + +| Name | Description | +|:------|:------------| + + +**Parameters** + +| Name | Type | Description | +|:----------|:----------------------|:---------------------------------------------------------| +| `input` | `unknown` | Query input data passed e.g. via URL . | +| `options` | `SortParseOptions` | Options for parsing sort data [more](#sortparseoptions). | + +**Returns** + +[SortParseOutput](#sortparseoutput) + +The function returns an object. + ## `SortBuildInput` The following types are defined, to illustrate which kind of input data is covered by the diff --git a/src/parse/parameter/type.ts b/src/parse/parameter/type.ts index cd5fc32..6660d39 100644 --- a/src/parse/parameter/type.ts +++ b/src/parse/parameter/type.ts @@ -30,9 +30,9 @@ export type ParseParametersOptions = { }; export type ParseParametersOutput = { - [Parameter.FIELDS]?: FieldsParseOutput | boolean, - [Parameter.FILTERS]?: FiltersParseOutput | boolean, - [Parameter.RELATIONS]?: RelationsParseOutput | boolean, - [Parameter.PAGINATION]?: PaginationParseOutput | boolean, - [Parameter.SORT]?: SortParseOutput | boolean, + [Parameter.FIELDS]?: FieldsParseOutput, + [Parameter.FILTERS]?: FiltersParseOutput, + [Parameter.RELATIONS]?: RelationsParseOutput, + [Parameter.PAGINATION]?: PaginationParseOutput, + [Parameter.SORT]?: SortParseOutput, };