@schuelerconnect/schema v1.2.1

🌎 Deutsch | English

@schuelerconnect/schema ist eine leichte (~4kb) package, die es erlaubt, einfach und ohne redundanz typensichere GraphQL-Schemen zu schreiben:

import * as $ from "@schuelerconnect/schema";

const meinSchema = $.schema(
  // queries
  {
    zaehler: $.int,
  },
  // mutationen
  {
    zaehlerSetzen: $.resolver({ zahl: $.int.required() }, $.boolean),
  }
);

const meineResolver: $.Infer<typeof meinSchema> = {
  // ...
};

// type Query {
//   zaehler: Int,
// }
//
// type Mutation {
// ...
const graphQLCode = meinSchema.toGraphQL();

API

$.schema(): Schema

Definiert ein GraphQL-Schema.

Parameter:

• queries – felder für type Query im GraphQL-Schema.
• mutations – felder für type Mutation im GraphQL-Schema

$.{datentyp}: SchemaType

Eingebaute datentypen:

• int (GraphQL: Int) – Ganzahl
• float (GraphQL: Float) – Dezimalzahl
• boolean (GraphQL: Boolean) – Boole'scher wert
• string (GraphQL: String) – Zeichenkette
• id (GraphQL: ID) – Nicht für Menschen lesbare Zeichenkette

SchemaType#required(): SchemaType

Erforderliche (nicht-nullbare) version eines Datentypen. Diese Methode ist bei allen Datentypen, inklusive denen, die bspw. mit $.array oder $.type definiert wurden.

Beispiel:

$.string.required(); // GraphQL: String!

$.array()

Eine liste.

Parameter:

• type – Datentyp der elemente in der Liste

Rückgabe: Ein Datentyp für eine liste des übergebenen Datentypen type

Beispiel:

// GraphQL: `[String]`
$.array($.string);

// GraphQL: `[[String]]`
$.array($.array($.string));

$.type(): SchemaType

Definiert einen neuen type im GraphQL-Schema. In Typescript ist es der Äquivalent eines interfaces.

Parameter:

• name – Name des typen im GraphQL-Schema
• shape – Felder des Datentypen (siehe Beispiele)

Rückgabe: Ein neuer Datentyp im Schema

Beispiele:

// GraphQL:
// type Book {
//   name: String,
//   author: String,
//   year: Int
// }
const book = $.type("Book", {
  name: $.string,
  author: $.string,
  year: $.int,
});

Dokumentationskommentar pro Datentyp

Um über der definition des Datentypen einen Dokumentationskommentar anzuzeigen, verwenden Sie .typeDocstring(). Diese Methode verhält sich ansonsten genau wie .docstring().

Erweitern

Typen die mit $.type generiert wurden können mit .extend() erweitert werden.

Parameter:

• name – Name des neuen typen im GraphQL-Schema
• shape – Zusätzliche / Überschriebene Felder des neuen Datentypen

Rückgabe: Ein erweiterter datentyp

Beispiel:

// GraphQL:
// type BookWithVolumes {
//   name: String,
//   author: String,
//   year: Int,
//   volumes: Int,
// }
const bookWithVolumes = book.extend("BookWithVolumes", { volumes: $.int });

Wichtig: Datentypen nie zweimal definieren! Wenn die Definition "B" mehrmals im Code vorkommt, kommt sie auch mehrmals im Schema vor:

// FALSCH:
$.type("A", {
	b1: $.type("B", { b: $.string }),
	b2: $.type("B", { b: $.string }),
});

Speichern sie Datentypen stattdessen in einer variable:

// RICHTIG:
const B = $.type("B", { b: $.string });

$.type("A", { b1: B, b2: B });

$.resolver(): SchemaType

Diese Methode definiert einen Resolver der bestimmte Argumente annimt.

Parameter:

• args – Angenommene argumente in der Form { arg1: datentyp1, arg2: datentyp2 }
• returns – Rückgabedatentyp des resolvers

Beispiel:

// GraphQL:
// type A {
//   abc(xyz: String): Boolean
// }
$.type("A", {
  abc: $.resolver({ xyz: $.string }, $.boolean),
});

SchemaType#docstring()

Definiert ein Dokumentationskommentar auf ein feld. Diese methode ist bei allen datentypen verfübar.

Parameter:

• doc – Dokumentationskomentar

$.schema({
  test: $.string.docstring("test test");
}, {});

// type Query {
//   """
//   test test
//   """
//   test: String
// }
$.toGraphQL();

Datentypsicherheit

Um korrekte TypeScript-Datentypen für das Schema zur verfügung zu stellen, exportiert @schuelerconnect/schema den Datentypen Infer<T>:

const meinSchema = $.schema(/* ... */);

type schemaDatentypen = $.Infer<typeof meinSchema>;

const meineResolver: schemaDatentypen = {
  // ...
};

Bekannte Mängel

• unions werden nicht unterstützt
• enums werden nicht unterstützt
• Eigene scalar-datentypen werden nicht unterstützt