From bacbaf28608200c859cf33e2d9543617a9fe42f3 Mon Sep 17 00:00:00 2001
From: Tim Streicher <tim.streicher@singular-it.de>
Date: Thu, 16 Nov 2023 15:27:03 +0100
Subject: [PATCH] feat: add type docs

---
 docs/advanced-typescript.md    | 107 ++++++++++++++++++++++++++++++++-
 docs/de/advanced-typescript.md | 107 ++++++++++++++++++++++++++++++++-
 2 files changed, 211 insertions(+), 3 deletions(-)

diff --git a/docs/advanced-typescript.md b/docs/advanced-typescript.md
index ba63997..7b6c42d 100644
--- a/docs/advanced-typescript.md
+++ b/docs/advanced-typescript.md
@@ -1,5 +1,110 @@
 # Typescript
 
+This package exposes the type `FilterSetConfig` for typing hints. 
+The Type is generic and expects at least one Parameter.
+In the following section examples are given on how to use these types to achieve different typing behaviours.
+
+
+## Data Parameter
+Let's assume there exists a model `Category`:
+``` ts
+interface Category {
+    id: number
+    name: string
+}
+```
+Passing the `Category` type as the first type parameter allows only attributes that the interface actually posses:
+``` ts
+const config: FilterSetConfig<Category> = {
+    id: { 
+        in: [1,2,3]
+    }
+}
+```
+
+### Nested Types
+Nested types are also supported:
+``` ts
+interface Book {
+    id: number
+    category: Category
+}
+
+...
+
+const config: FilterSetConfig<Book> = {
+    category: { 
+        id:{
+            in: [1,2,3]
+        }
+    }
+}
+```
+
+## Key-Configuration
+
+With a key configuration it is possible to specify which filters are valid for a specific parameter.
+``` ts
+interface CategoryKeyConfig {
+    name : 'exact' | 'startwith' | 'endswith'
+}
+
+...
+
+const config: FilterSetConfig<Category, CategoryKeyConfig> = {
+    name: { 
+        exact: 'Fantasy'
+    }
+}
+```
+This would only allow `exact`, `startwith` and `endswith` for the `name` attribute
+
+::: tip
+Attributes that are not mentioned in the key configuration still allow all filters. 
+Note that the `value` filter cannot be disallowed.
+:::
+
+### Nested Types
+
+For nested types the config could look like so:
+``` ts
+interface BookKeyConfig {
+    category : {
+        name: 'exact' | 'startwith' | 'endswith'
+    }
+}
+```
+This is a little redundant but that way it is possible to define different behaviours for the models.
+To remove the redundant Part the config can also be written like this:
+``` ts
+interface BookKeyConfig {
+    category : CategoryKeyConfig
+}
+```
+
+## Custom Filter
+Custom Filter can be defined via:
+``` ts
+interface CustomFilter {
+  notIn: any[]
+}
+```
 ::: warning
-This is a work in progress. The documentation is not complete yet.
+There is no generic type hinting for custom filters yet.
+Using `any` as the type allows the filter to be used everywhere but also loosens the typing of the passed value.
 :::
+
+To enable type hinting them they need to be added to a key configuration.
+``` ts
+interface CategoryKeyConfig {
+  id: 'in' | 'notIn'
+}
+
+...
+
+const config: FilterSetConfig<Category, CategoryKeyConfig, CustomFilter> = {
+    id: { 
+        notIn: [1,2,3]
+    }
+}
+```
diff --git a/docs/de/advanced-typescript.md b/docs/de/advanced-typescript.md
index 2f2c302..bd12712 100644
--- a/docs/de/advanced-typescript.md
+++ b/docs/de/advanced-typescript.md
@@ -1,5 +1,108 @@
 # Typescript
 
-::: warning
-Diese Seite ist noch in Arbeit. Die Dokumentation ist noch nicht vollständig.
+Dieses Package nutzt den Typ `FilterSetConfig` für Type-Hints.
+Der Typ ist Generisch aud erwartet mindestens einen Parameter.
+Im den folgenden Abschnitten werden beispiele Vorgestellt, wie diese genutzt werden können um verschiedene Verhalten abzubilden.
+
+
+## Data Parameter
+Angenommen es existiert ein Model `Category`:
+``` ts
+interface Category {
+    id: number
+    name: string
+}
+```
+`Category` als Parameter zu übergeben bewirkt, dass nur Attribute des Interfaces in der Konfiguration erlaubt sind:
+``` ts
+const config: FilterSetConfig<Category> = {
+    id: { 
+        in: [1,2,3]
+    }
+}
+```
+
+### Nested Types
+Nested-Types werden auch unterstützt:
+``` ts
+interface Book {
+    id: number
+    category: Category
+}
+
+...
+
+const config: FilterSetConfig<Book> = {
+    category: { 
+        id:{
+            in: [1,2,3]
+        }
+    }
+}
+```
+
+## Key-Configuration
+Mit einer Key-Konfiguration ist es möglich zu spezifizieren welche Filter für eine Attribut erlaubt sind.
+``` ts
+interface CategoryKeyConfig {
+    name : 'exact' | 'startwith' | 'endswith'
+}
+
+...
+
+const config: FilterSetConfig<Category, CategoryKeyConfig> = {
+    name: { 
+        exact: 'Fantasy'
+    }
+}
+```
+Diese Konfiguration erlaubt nur  `exact`, `startwith` und `endswith` für das Attribut `name`
+
+::: tip
+Attribute, die in der Key-Konnfiguration nicht erwähnt werden, erlauben weiterhin alle Filter.
+Beachte, dass der `value`-Filter nicht ausgeschlossen werden kann.
 :::
+
+### Nested Types
+
+Für Nested-Types wie folgt aussehen:
+``` ts
+interface BookKeyConfig {
+    category : {
+        name: 'exact' | 'startwith' | 'endswith'
+    }
+}
+```
+Das ist zwar etwas redundant, aber ermöglicht es, unterschiedliche Verhaltensweisen für die Modelle zu definieren.
+Um den redundanten Teil zu entfernen, kann die Konfiguration auch folgendermaßen geschrieben werden:
+``` ts
+interface BookKeyConfig {
+    category : CategoryKeyConfig
+}
+```
+
+## Custom Filter
+Custom-Filter können wie folgt definiert werden:
+``` ts
+interface CustomFilter {
+  notIn: any[]
+}
+```
+::: warning
+Es gibt noch keine generische Type-Hints für benutzerdefinierte Filter.
+Die Verwendung von `any` als Typ erlaubt die Verwendung des Filters überall, lockert aber auch die Typisierung des übergebenen Wertes.:::
+
+Um die Type-Hints zu aktivieren, muss der Filter einer Schlüsselkonfiguration hinzugefügt werden.
+``` ts
+interface CategoryKeyConfig {
+  id: 'in' | 'notIn'
+}
+
+...
+
+const config: FilterSetConfig<Category, CategoryKeyConfig, CustomFilter> = {
+    id: { 
+        notIn: [1,2,3]
+    }
+}
+```