initial commit

Author: jgillich

.devcontainer/Dockerfile

@@ -0,0 +1,7 @@
+# See here for image contents: https://github.com/microsoft/vscode-dev-containers/tree/v0.245.2/containers/alpine/.devcontainer/base.Dockerfile
+
+# [Choice] Alpine version: 3.16, 3.15, 3.14, 3.13
+ARG VARIANT="3.16"
+FROM mcr.microsoft.com/vscode/devcontainers/base:0-alpine-${VARIANT}
+
+RUN apk add python3 py3-pip

.devcontainer/devcontainer.json

@@ -0,0 +1,22 @@
+// For format details, see https://aka.ms/devcontainer.json. For config options, see the README at:
+// https://github.com/microsoft/vscode-dev-containers/tree/v0.245.2/containers/alpine
+{
+	"name": "Alpine",
+	"build": {
+		"dockerfile": "Dockerfile",
+		// Update 'VARIANT' to pick an Alpine version: 3.13, 3.14, 3.15, 3.16
+		"args": { "VARIANT": "3.16" }
+	},
+
+	// Use 'forwardPorts' to make a list of ports inside the container available locally.
+	// "forwardPorts": [],
+
+	// Use 'postCreateCommand' to run commands after the container is created.
+	// "postCreateCommand": "uname -a",
+
+	// Replace when using a ptrace-based debugger like C++, Go, and Rust
+	// "runArgs": [ "--init", "--cap-add=SYS_PTRACE", "--security-opt", "seccomp=unconfined" ],
+
+	// Comment out to connect as root instead. More info: https://aka.ms/vscode-remote/containers/non-root.
+	"remoteUser": "vscode"
+}

.github/workflows/publish.yaml

@@ -0,0 +1,19 @@
+name: Publish docs via GitHub Pages
+on:
+  push:
+    branches:
+      - main
+jobs:
+  build:
+    name: Deploy docs
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout main
+        uses: actions/checkout@v2
+      - name: Deploy docs
+        uses: mhausenblas/mkdocs-deploy-gh-pages@master
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          CONFIG_FILE: mkdocs.yaml
+          EXTRA_PACKAGES: build-base
+          REQUIREMENTS: requirements.txt

README.md

@@ -0,0 +1,6 @@
+# Docs
+
+```
+pip install -r requirements.txt
+mkdocs serve
+```

docs/index.md

@@ -0,0 +1,337 @@
+![Logo](https://raw.githubusercontent.com/graphql-crystal/graphql/main/assets/logo.svg)
+
+GraphQL server library for Crystal.
+
+- **Boilerplate-free**: Schema generated at compile time
+- **Type-safe**: Crystal guarantees your code matches your schema
+- **High performance**: See [benchmarks](https://github.com/graphql-crystal/benchmarks)
+
+## Getting Started
+
+Install the shard by adding the following to our `shard.yml`:
+
+```yaml
+dependencies:
+  graphql:
+    github: graphql-crystal/graphql
+```
+
+Then run `shards install`.
+
+The first step is to define a query object. This is the root type for all
+queries and it looks like this:
+
+```crystal
+require "graphql"
+
+@[GraphQL::Object]
+class Query < GraphQL::BaseQuery
+  @[GraphQL::Field]
+  def hello(name : String) : String
+    "Hello, #{name}!"
+  end
+end
+```
+
+Now we can create a schema object:
+
+```crystal
+schema = GraphQL::Schema.new(Query.new)
+```
+
+To verify we did everything correctly, we can print out the schema:
+
+```crystal
+puts schema.document.to_s
+```
+
+Which, among several built-in types, prints our query type:
+
+```graphql
+type Query {
+  hello(name: String!): String!
+}
+```
+
+To serve our API over HTTP we call `schema.execute` with the request parameters and receive a JSON string. Here is an example for Kemal:
+
+```crystal
+post "/graphql" do |env|
+  env.response.content_type = "application/json"
+
+  query = env.params.json["query"].as(String)
+  variables = env.params.json["variables"]?.as(Hash(String, JSON::Any)?)
+  operation_name = env.params.json["operationName"]?.as(String?)
+
+  schema.execute(query, variables, operation_name)
+end
+```
+
+Now we're ready to query our API:
+
+```bash
+curl \
+  -X POST \
+  -H "Content-Type: application/json" \
+  --data '{ "query": "{ hello(name: \"John Doe\") }" }' \
+  http://0.0.0.0:3000/graphql
+```
+
+This should return:
+
+```json
+{ "data": { "hello": "Hello, John Doe!" } }
+```
+
+For easier development, we recommend using [GraphiQL](https://github.com/graphql/graphiql).
+A starter template combining Kemal and GraphiQL is found at [examples/graphiql](examples/graphiql).
+
+## Context
+
+`context` is a optional argument that our fields can retrieve. It lets fields
+access global data, like database connections.
+
+```crystal
+# Define our own context type
+class MyContext < GraphQL::Context
+  @pi : Float64
+  def initialize(@pi)
+  end
+end
+
+# Pass it to schema.execute
+context = MyContext.new(Math::PI)
+schema.execute(query, variables, operation_name, context)
+
+# Access it in our fields
+@[GraphQL::Object]
+class MyMath < GraphQL::BaseObject
+  @[GraphQL::Field]
+  def pi(context : MyContext) : Float64
+    context.pi
+  end
+end
+```
+
+Context instances must not be reused for multiple executions.
+
+## Objects
+
+Objects are perhaps the most commonly used type in GraphQL. They are implemented
+as classes. To define a object, we need a `GraphQL::Object` annotation and to inherit
+`GraphQL::BaseObject`. Fields are methods with a `GraphQL::Field` annotation.
+
+```crystal
+@[GraphQL::Object]
+class Foo < GraphQL::BaseObject
+  # type restrictions are mandatory on fields
+  @[GraphQL::Field]
+  def hello(first_name : String, last_name : String) : String
+    "Hello #{first_name} #{last_name}"
+  end
+
+  # besides basic types, we can also return other objects
+  @[GraphQL::Field]
+  def bar : Bar
+    Bar.new
+  end
+end
+
+@[GraphQL::Object]
+class Bar < GraphQL::BaseObject
+  @[GraphQL::Field]
+  def baz : Float64
+    42_f64
+  end
+end
+```
+
+For simple objects, we can use instance variables:
+
+```crystal
+@[GraphQL::Object]
+class Foo < GraphQL::BaseObject
+  @[GraphQL::Field]
+  property bar : String
+
+  @[GraphQL::Field]
+  getter baz : Float64
+end
+```
+
+## Query
+
+Query is the root type of all queries.
+
+```crystal
+@[GraphQL::Object]
+class Query < GraphQL::BaseQuery
+  @[GraphQL::Field]
+  def echo(str : String) : String
+    str
+  end
+end
+
+schema = GraphQL::Schema.new(Query.new)
+```
+
+## Mutation
+
+Mutation is the root type for all mutations.
+
+```crystal
+@[GraphQL::Object]
+class Mutation < GraphQL::BaseMutation
+  @[GraphQL::Field]
+  def echo(str : String) : String
+    str
+  end
+end
+
+schema = GraphQL::Schema.new(Query.new, Mutation.new)
+```
+
+## Input Objects
+
+Input objects are objects that are used as field arguments. To define an input
+object, use a `GraphQL::InputObject` annotation and inherit `GraphQL::BaseInputObject`.
+It must define a constructor with a `GraphQL::Field` annotation.
+
+```crystal
+@[GraphQL::InputObject]
+class User < GraphQL::BaseInputObject
+  getter first_name : String?
+  getter last_name : String?
+
+  @[GraphQL::Field]
+  def initialize(@first_name : String?, @last_name : String?)
+  end
+end
+```
+
+## Enums
+
+Defining enums is straightforward. Just add a `GraphQL::Enum` annotation:
+
+```crystal
+@[GraphQL::Enum]
+enum IPAddressType
+  IPv4
+  IPv6
+end
+```
+
+## Scalars
+
+The following scalar values are supported:
+
+- `Int32` <-> `Int`
+- `Float64` <-> `Float`
+- `String` <-> `String`
+- `Bool` <-> `Boolean`
+- `GraphQL::Scalars::ID` <-> `String`
+
+Built-in custom scalars:
+
+- `GraphQL::Scalars::BigInt` <-> `String`
+
+Custom scalars are created by implementing from_json/to_json:
+
+```crystal
+@[GraphQL::Scalar]
+class ReverseStringScalar < GraphQL::BaseScalar
+  @value : String
+
+  def initialize(@value)
+  end
+
+  def self.from_json(string_or_io)
+    self.new(String.from_json(string_or_io).reverse)
+  end
+
+  def to_json(builder : JSON::Builder)
+    builder.scalar(@value.reverse)
+  end
+end
+```
+
+## Interfaces
+
+Interfaces are not supported.
+
+## Subscriptions
+
+Subscriptions are not supported.
+
+## Annotation Arguments
+
+### name
+
+Supported on: `Object`, `InputObject`, `Field`, `Enum`, `Scalar`
+
+We can use the `name` argument to customize the introspection type name of a
+type. This is not needed in most situations because type names are automatically
+converted to PascalCase or camelCase. However, `item_id` converts to
+`itemId`, but we might want to use `itemID`. For this, we can use the `name`
+argument.
+
+```crystal
+@[GraphQL::Object(name: "Sheep")]
+class Wolf
+  @[GraphQL::Field(name: "baa")]
+  def howl : String
+    "baa"
+  end
+end
+```
+
+### description
+
+Supported on: `Object`, `InputObject`, `Field`, `Enum`, `Scalar`
+
+Describes the type. Descriptions are available through the introspection interface
+so it's always a good idea to set this argument.
+
+```crystal
+@[GraphQL::Object(description: "I'm a sheep, I promise!")]
+class Wolf
+end
+```
+
+### deprecated
+
+Supported on: `Field`
+
+The deprecated argument marks a type as deprecated.
+
+```crystal
+class Sheep
+  @[GraphQL::Field(deprecated: "This was a bad idea.")]
+  def fight_wolf : String
+    "Wolf ate sheep"
+  end
+end
+```
+
+### arguments
+
+Sets names and descriptions for field arguments. Note that
+arguments cannot be marked as deprecated.
+
+```crystal
+class Sheep
+  @[GraphQL::Field(arguments: {weapon: {name: "weaponName", description: "The weapon the sheep should use."}})]
+  def fight_wolf(weapon : String) : String
+    if weapon == "Atomic Bomb"
+      "Sheep killed wolf"
+    else
+      "Wolf ate sheep"
+    end
+  end
+end
+```
+
+## Field Arguments
+
+Field arguments are automatically resolved. A type with a default value becomes
+optional. A nilable type is also considered a optional type.