1  # Table of contents
  2  
  3  - [Overview](#overview)
  4    - [Graphql core](#graphql-core)
  5    - [Security features](#security-features)
  6    - [Unicode support](#unicode-support)
  7  
  8  - [Tutorial](tutorial.md)
  9    - [Important notes](tutorial.md#important-notes)
 10    - [Star Wars tutorial](tutorial.md#star-wars-tutorial)
 11  
 12  - [Resolver explained](resolver.md)
 13    - [How resolver works](resolver.md#how-resolver-works)
 14    - [Userdata](resolver.md#userdata)
 15    - [Resolver parameters](resolver.md#resolver-parameters)
 16    - [Response object](resolver.md#response-object)
 17  
 18  - [Scalars](scalars.md)
 19    - [Builtin scalars](scalars.md#builtin-scalars)
 20    - [Custom scalars](scalars.md#custom-scalars)
 21    - [Variable coercion](scalars.md#variable-coercion)
 22  
 23  - [Directives](directives.md)
 24    - [Builtin directives](directives.md#)
 25    - [Custom directives](directives.md#)
 26  
 27  - [Introspection](introspection.md)
 28    - [Introspection API](introspection.md#introspection-api)
 29    - [Non-standard features](introspection.md#non-standard-features)
 30  
 31  - [nim-graphql API](api.md)
 32    - [API index](api.md#api-index)
 33    - [Datatypes](api.md#datatypes)
 34  
 35  - [Server](server.md)
 36    - [Server API index](server.md#server-api-index)
 37    - [Serving over HTTP](server.md#serving-over-http)
 38  
 39  - [Client](client.md)
 40    - [Client API index](client.md#client-api-index)
 41    - [Request over HTTP](client.md#request-over-http)
 42  
 43  ## Overview
 44  
 45  nim-graphql designed with simplicity in mind without compromising performance and
 46  robustsness. Every part of nim-graphql can be tested and debugged relatively easy.
 47  nim-graphql comes with comprehensive test suite touching every features as much as possible.
 48  This gives us confidence when deploying a graphql service in performance critical and secure
 49  application.
 50  
 51  ### Graphql core
 52  
 53  The core of nim-graphql is built upon these components:
 54  
 55    - a performant `Name` or identifiers table.
 56    - an [almost] exception free lexer designed with security in mind.
 57    - Three kind of parsers to to help you build responsive graphql service:
 58      - `Schema parser`. This parser parse graphql type system document a.k.a schema.
 59      - `Query parser`. This parser only parse graphql query language and validating user input.
 60      - `Full parser`. This is a combination of `Schema parser` and `Query parser`.
 61    - A validator aiming at implementing all features described in the official specification.
 62    - An execution engine that can accept external datasources easily and exposing the interface
 63      using only plain Nim without hiding behind magical macros.
 64    - A complete but simple type system introspection described in the specification covering not only
 65      user defined types but also capable to query built in types using the same syntax, same output.
 66  
 67  ### Security features
 68  
 69  Because nim-graphql lexer and parser are dealing with potentially malicious/malformed input that
 70  can bring down the service, both lexer and parser are configurable to mitigate this problem.
 71  
 72    - Lexer config options:
 73      - `maxIdentChars`. Identifiers length must be within `maxIdentChars` or trigger an error. (default = 128)
 74      - `maxDigits`. nim-graphql support arbitrary number of digits for integer and float, but is limited by `maxDigits`. (default = 128)
 75      - `maxStringChars`. Single line string and multi line string length should not become too long. (default = 2048)
 76  
 77    - Parser config options:
 78      - `maxRecursionLimit`. Field selection recursion must be within this limit. (default = 25)
 79      - `maxListElems`. Arrays and lists maximum elements is limited by this option. (default = 128)
 80      - `maxFields`. Type fields, input object fields, and operation fields number should be within this limit. (default = 128)
 81      - `maxArguments`. Fields and directives usually don't require too much arguments. (default = 32)
 82      - `maxSchemaElems`. Graphql specification tells us it can only contains max 3 elems. (default = 3)
 83      - `maxEnumVals`. We have efficient identifers comparison, but should not too much enums. (default = 64)
 84      - `maxDefinitions`. Queries, mutations, subscriptions, and fragments total number should be reasonable. (default = 512)
 85      - `maxChoices`. Unions and directive's locations are limited by this number. (default = 64)
 86  
 87  ### Unicode support
 88  
 89    - Input string:
 90      - Accepted encoding for input string are UTF-8.
 91      - Escaped unicode in quoted string take the form of UTF-16 BE:
 92        - Fixed length notation using 4 digit hex: e.g. `\u000A`.
 93        - Variable length notation using curly braces `\u{1F4A9}` with range (0x0000..0xD7FF, 0xE000..0x10FFFF).
 94        - Escape sequences are only meaningful within a single-quoted string.
 95        - In multiline string, unicode char must be encoded using UTF-8.
 96        - Surrogate pair using fixed length notation "\uD83D\uDCA9" is equal to variable length notation "\u{1F4A9}".
 97        - Orphaned surrogate will result in error.
 98  
 99    - Output string:
100      - Output string subject to output serialization format specification.
101      - For example, output using json as serialization format will result in UTF-8 encoded string.
102      - If the escape flag is set, it will use UTF-16 BE 4 digit hex fixed length similar to GraphQL escape sequence.