Started to document the scalars

Author: bbakerman

readme.md

@@ -1,7 +1,169 @@
+# Extended Scalars for graphql-java
 
+This library provides extended scalars for [graphql-java](https://github.com/graphql-java/graphql-java)
 
-# Big work in PROGRESS
+Scalars in graphql are the leaf nodes of a query, the non compound values that cant be queried further via sub field selections.
 
-Not released and not ready for external consumption yet!
+The graphql standard specifies `String`, `Int`, `Float`, `Boolean` and `ID` must be present in a graphql type 
+system but after that it is up to an implementation about what custom scalars are present.
 
-Still exploring what it could be
+You would use custom scalars when you want to describe more meaningful behavior or ranges of values.
+
+## DateTime Scalars
+
+* `DateTime`
+  * An RFC-3339 compliant date time scalar that accepts string values like `1996-12-19T16:39:57-08:00` and produces 
+  `java.time.OffsetDateTime` objects at runtime  
+* `Time`
+  * An RFC-3339 compliant time scalar that accepts string values like `16:39:57-08:00` and produces 
+  `java.time.LocalDate` objects at runtime  
+* `Date`
+  * An RFC-3339 compliant date scalar that accepts string values like `1996-12-19` and produces 
+  `java.time.LocalDate` objects at runtime  
+
+See [the rfc3339 spec](https://www.ietf.org/rfc/rfc3339.txt) for more details on the format.
+
+An example declaration in SDL might be:
+
+```graphql
+
+    type Customer {
+        birthDay : Date
+        workStartTime : Time
+        bornAt : DateTime
+    }
+    
+    type Query {
+        customers(bornAfter : DateTime) : [Customers]
+    }
+    
+``` 
+
+And example query might look like:
+```graphql
+    
+    query {
+        customers(bornAfter : "1996-12-19T16:39:57-08:00") {
+            birthDay
+            bornAt
+        }
+    }
+    
+``` 
+
+## Object / Json Scalars
+
+* `Object`
+  * An object scalar that accepts any object as a scalar value
+
+* `Json`
+  * A synonym for the `Object` scalar, it will accept any object as a scalar value
+  
+One of the design goals of graphql, is that the type system describes the shape of the data returned.
+
+The `Object` / `Json` scalars work against this some what because they can return compound values outside the type system.  As such 
+they should be used sparingly.  In general your should aim to describe the data via the graphql type system where you can and only
+resort to the `Object` / `Json` scalars in very rare circumstances. 
+
+An example might be an extensible graphql system where systems can input custom metadata objects that cant be known at 
+schema type design time.
+
+An example declaration in SDL might be:
+
+```graphql
+
+    type Customer {
+        name : String
+        associatedMetaData : Json
+    }
+    
+    type Query {
+        customers(filterSyntax : Json) : [Customers]
+    }
+    
+``` 
+
+And example query might look like:
+
+```graphql
+    
+    query {
+        customers(filterSyntax : {
+                startSpan : "First",
+                matchCriteria : {
+                    countryCode : "AU",
+                    isoCodes : ["27B-34R", "95A-E23"],
+                    
+                }
+            }) {
+            name
+            associatedMetaData    
+        }
+    }
+    
+``` 
+   
+Note : The `Json` scalar is a simple alias type to the `Object` scalar because often the returned data is a blob of JSON.  They are 
+all just objects at runtime in graphql-java terms and what network serialisation protocol is up to you.  Choose whichever name you think
+adds more semantic readers to your schema consumers. 
+
+
+## Numeric Scalars
+
+
+* `PositiveInt`
+  * An `Int` scalar that MUST be a greater than zero   
+* `NegativeInt`
+  * An `Int` scalar that MUST be a less than zero   
+* `NonPositiveInt`
+  * An `Int` scalar that MUST be a less than or equal to zero   
+* `NonNegativeInt`
+  * An `Int` scalar that MUST be a greater than or equal to zero   
+* `PositiveFloat`
+  * An `Float` scalar that MUST be a greater than zero   
+* `NegativeFloat`
+  * An `Float` scalar that MUST be a less than zero   
+* `NonPositiveFloat`
+  * An `Float` scalar that MUST be a less than or equal to zero   
+* `NonNegativeFloat`
+  * An `Float` scalar that MUST be a greater than or equal to zero   
+
+The numeric scalars are derivations of the standard graphql `Int` and `Float` scalars that enforce range limits.
+
+An example declaration in SDL might be:
+
+```graphql
+
+    type Customer {
+        name : String
+        currentHeight : PositiveInt
+        weightLossGoal : NonPositiveInt
+        averageWeightLoss : NegativeFloat
+    }
+    
+    type Query {
+        customers(height : PositiveInt) : [Customers]
+    }
+    
+``` 
+
+And example query might look like:
+
+```graphql
+    
+    query {
+        customers(height : 182) {
+            name
+            height
+            weightLossGoal    
+        }
+    }
+    
+``` 
+
+
+## Other Scalars
+
+* `Url`
+  * An url scalar that accepts string values like `https://www.w3.org/Addressing/URL/url-spec.txt` and produces 
+  `java.net.URL` objects at runtime  

src/main/java/graphql/scalars/ExtendedScalars.java

@@ -2,16 +2,16 @@
 
 import graphql.PublicApi;
 import graphql.scalars.datetime.DateTimeScalar;
-import graphql.scalars.datetime.FullDateScalar;
-import graphql.scalars.datetime.FullTimeScalar;
-import graphql.scalars.numbers.NegativeFloatScalar;
-import graphql.scalars.numbers.NegativeIntScalar;
-import graphql.scalars.numbers.NonNegativeFloatScalar;
-import graphql.scalars.numbers.NonNegativeIntScalar;
-import graphql.scalars.numbers.NonPositiveFloatScalar;
-import graphql.scalars.numbers.NonPositiveIntScalar;
-import graphql.scalars.numbers.PositiveFloatScalar;
-import graphql.scalars.numbers.PositiveIntScalar;
+import graphql.scalars.datetime.DateScalar;
+import graphql.scalars.datetime.TimeScalar;
+import graphql.scalars.numeric.NegativeFloatScalar;
+import graphql.scalars.numeric.NegativeIntScalar;
+import graphql.scalars.numeric.NonNegativeFloatScalar;
+import graphql.scalars.numeric.NonNegativeIntScalar;
+import graphql.scalars.numeric.NonPositiveFloatScalar;
+import graphql.scalars.numeric.NonPositiveIntScalar;
+import graphql.scalars.numeric.PositiveFloatScalar;
+import graphql.scalars.numeric.PositiveIntScalar;
 import graphql.scalars.object.JsonScalar;
 import graphql.scalars.object.ObjectScalar;
 import graphql.scalars.url.UrlScalar;
@@ -22,8 +22,8 @@ public class ExtendedScalars {
 
 
     public static GraphQLScalarType DateTime = new DateTimeScalar();
-    public static GraphQLScalarType Date = new FullDateScalar();
-    public static GraphQLScalarType Time = new FullTimeScalar();
+    public static GraphQLScalarType Date = new DateScalar();
+    public static GraphQLScalarType Time = new TimeScalar();
 
     /**
      * An object scalar allows you to have a multi level data value without defining it in the graphql schema.

src/main/java/graphql/scalars/datetime/FullDateScalar.java renamed to src/main/java/graphql/scalars/datetime/DateScalar.java

@@ -17,13 +17,15 @@
 
 import static graphql.scalars.util.Kit.typeName;
 
+/**
+ * Access this via {@link graphql.scalars.ExtendedScalars#Date}
+ */
 @Internal
-public class FullDateScalar extends GraphQLScalarType {
+public class DateScalar extends GraphQLScalarType {
 
     private final static DateTimeFormatter dateFormatter = DateTimeFormatter.ofPattern("yyyy-MM-dd");
-    ;
 
-    public FullDateScalar() {
+    public DateScalar() {
         super("Date", "An RFC-3339 compliant Full Date Scalar", new Coercing<LocalDate, String>() {
             @Override
             public String serialize(Object input) throws CoercingSerializeException {

src/main/java/graphql/scalars/datetime/DateTimeScalar.java

@@ -17,6 +17,9 @@
 
 import static graphql.scalars.util.Kit.typeName;
 
+/**
+ * Access this via {@link graphql.scalars.ExtendedScalars#DateTime}
+ */
 @Internal
 public class DateTimeScalar extends GraphQLScalarType {
 

src/main/java/graphql/scalars/datetime/FullTimeScalar.java renamed to src/main/java/graphql/scalars/datetime/TimeScalar.java

@@ -17,12 +17,15 @@
 
 import static graphql.scalars.util.Kit.typeName;
 
+/**
+ * Access this via {@link graphql.scalars.ExtendedScalars#Time}
+ */
 @Internal
-public class FullTimeScalar extends GraphQLScalarType {
+public class TimeScalar extends GraphQLScalarType {
 
     private final static DateTimeFormatter dateFormatter = DateTimeFormatter.ISO_OFFSET_TIME;
 
-    public FullTimeScalar() {
+    public TimeScalar() {
         super("Time", "An RFC-3339 compliant Full Time Scalar", new Coercing<OffsetTime, String>() {
             @Override
             public String serialize(Object input) throws CoercingSerializeException {

src/main/java/graphql/scalars/numbers/FloatCoercing.java renamed to src/main/java/graphql/scalars/numeric/FloatCoercing.java

@@ -1,5 +1,6 @@
-package graphql.scalars.numbers;
+package graphql.scalars.numeric;
 
+import graphql.Internal;
 import graphql.schema.Coercing;
 import graphql.schema.CoercingParseLiteralException;
 import graphql.schema.CoercingParseValueException;
@@ -9,6 +10,7 @@
 
 import static graphql.Scalars.GraphQLFloat;
 
+@Internal
 abstract class FloatCoercing implements Coercing<Double, Double> {
 
     abstract protected Double check(Double d, Function<String, RuntimeException> exceptionMaker);

src/main/java/graphql/scalars/numbers/IntCoercing.java renamed to src/main/java/graphql/scalars/numeric/IntCoercing.java

@@ -1,5 +1,6 @@
-package graphql.scalars.numbers;
+package graphql.scalars.numeric;
 
+import graphql.Internal;
 import graphql.schema.Coercing;
 import graphql.schema.CoercingParseLiteralException;
 import graphql.schema.CoercingParseValueException;
@@ -9,6 +10,7 @@
 
 import static graphql.Scalars.GraphQLInt;
 
+@Internal
 abstract class IntCoercing implements Coercing<Integer, Integer> {
 
     abstract protected Integer check(Integer i, Function<String, RuntimeException> exceptionMaker);

src/main/java/graphql/scalars/numbers/NegativeFloatScalar.java renamed to src/main/java/graphql/scalars/numeric/NegativeFloatScalar.java

@@ -1,9 +1,14 @@
-package graphql.scalars.numbers;
+package graphql.scalars.numeric;
 
+import graphql.Internal;
 import graphql.schema.GraphQLScalarType;
 
 import java.util.function.Function;
 
+/**
+ * Access this via {@link graphql.scalars.ExtendedScalars#NegativeFloat}
+ */
+@Internal
 public class NegativeFloatScalar extends GraphQLScalarType {
     public NegativeFloatScalar() {
         super("NegativeFloat", "An Float scalar that must be a negative value", new FloatCoercing() {

src/main/java/graphql/scalars/numbers/NegativeIntScalar.java renamed to src/main/java/graphql/scalars/numeric/NegativeIntScalar.java

@@ -1,9 +1,14 @@
-package graphql.scalars.numbers;
+package graphql.scalars.numeric;
 
+import graphql.Internal;
 import graphql.schema.GraphQLScalarType;
 
 import java.util.function.Function;
 
+/**
+ * Access this via {@link graphql.scalars.ExtendedScalars#NegativeInt}
+ */
+@Internal
 public class NegativeIntScalar extends GraphQLScalarType {
     public NegativeIntScalar() {
         super("NegativeInt", "An Int scalar that must be a negative value", new IntCoercing() {

src/main/java/graphql/scalars/numbers/NonNegativeFloatScalar.java renamed to src/main/java/graphql/scalars/numeric/NonNegativeFloatScalar.java

@@ -1,9 +1,14 @@
-package graphql.scalars.numbers;
+package graphql.scalars.numeric;
 
+import graphql.Internal;
 import graphql.schema.GraphQLScalarType;
 
 import java.util.function.Function;
 
+/**
+ * Access this via {@link graphql.scalars.ExtendedScalars#NonNegativeFloat}
+ */
+@Internal
 public class NonNegativeFloatScalar extends GraphQLScalarType {
     public NonNegativeFloatScalar() {
         super("NonNegativeFloat", "An Float scalar that must be greater than or equal to zero", new FloatCoercing() {