diff --git a/ChangeLog.md b/ChangeLog.md --- a/ChangeLog.md +++ b/ChangeLog.md @@ -30,4 +30,8 @@ ## 0.1.0.7 -- 2018-10-26 -* json file schema +* json file schema + +## 0.2.0.0 -- 2018-11-05 + +* variables are available diff --git a/graphql-w-persistent.cabal b/graphql-w-persistent.cabal --- a/graphql-w-persistent.cabal +++ b/graphql-w-persistent.cabal @@ -10,7 +10,7 @@ -- PVP summary: +-+------- breaking API changes -- | | +----- non-breaking API additions -- | | | +--- code changes with no API change -version: 0.1.0.7 +version: 0.2.0.0 -- A short (one-line) description of the package. synopsis: Haskell GraphQL query parser-interpreter-data processor. @@ -65,8 +65,9 @@ Components.ObjectHandlers.ObjectsHandler, Components.ObjectHandlers.ServerObjectValidator, Components.ObjectHandlers.ServerObjectTrimmer, - Components.Parsers.QueryParser, + Components.Parsers.VariablesParser, Components.Parsers.ServerSchemaJsonParser, + Components.Parsers.QueryParser, Components.QueryComposers.SQLQueryComposer, Model.ServerObjectTypes, Model.ServerExceptions, diff --git a/src/Components/ObjectHandlers/ObjectsHandler.hs b/src/Components/ObjectHandlers/ObjectsHandler.hs --- a/src/Components/ObjectHandlers/ObjectsHandler.hs +++ b/src/Components/ObjectHandlers/ObjectsHandler.hs @@ -18,12 +18,14 @@ -} -- EFFECT: returns exclusive list of valid fields that are found in the database table for each Server object -- this is used to check queries against valid subfields -isValidServerObjectScalarField :: ServerObject -> String -> [(String,[String])] -> Bool +isValidServerObjectScalarField :: ServerObject -> String -> [(String,[(String,String)])] -> Bool isValidServerObjectScalarField _ _ [] = E.throw InvalidObjectException isValidServerObjectScalarField sobj name ((a,b):t) - | sobj==a&&(elem name b)==True = True + | sobj==a&&(elem name $ getScalarNames b)==True = True | sobj==a = False | otherwise = isValidServerObjectScalarField sobj name t +getScalarNames :: [(String,String)] -> [String] +getScalarNames lst = [a | (a,b) <- lst] -- you can create as many relationships as you want with your server... isValidServerObjectNestedObjectField :: ServerObject -> String -> [(String,[String])] -> Bool isValidServerObjectNestedObjectField _ _ [] = E.throw InvalidObjectException diff --git a/src/Components/ObjectHandlers/ServerObjectValidator.hs b/src/Components/ObjectHandlers/ServerObjectValidator.hs --- a/src/Components/ObjectHandlers/ServerObjectValidator.hs +++ b/src/Components/ObjectHandlers/ServerObjectValidator.hs @@ -1,4 +1,4 @@ -module Components.ObjectHandlers.ServerObjectValidator (checkObjectsAttributes) where +module Components.ObjectHandlers.ServerObjectValidator (checkObjectsAttributes,replaceObjectsVariables) where import qualified Control.Exception as E import Data.Maybe @@ -9,16 +9,16 @@ -- check that all nested objects are with valid properties -checkObjectsAttributes :: [RootObject] -> [(String,[String])] -> [(String,[String])] -> Bool +checkObjectsAttributes :: [RootObject] -> [(String,[(String,String)])] -> [(String,[String])] -> Bool checkObjectsAttributes objs sss sos = foldr (\x y -> (hasValidAttributes x sss sos)&&y) True objs -hasValidAttributes :: NestedObject -> [(String,[String])] -> [(String,[String])] -> Bool +hasValidAttributes :: NestedObject -> [(String,[(String,String)])] -> [(String,[String])] -> Bool hasValidAttributes (NestedObject alias name sobject ss sfs) sss sos = (if ss==Nothing then True else isValidSubSelection sobject (fromJust ss) sss)&&(isValidSubFields sobject sfs sss sos) -isValidSubSelection :: ServerObject -> ScalarType -> [(String,[String])] -> Bool +isValidSubSelection :: ServerObject -> ScalarType -> [(String,[(String,String)])] -> Bool isValidSubSelection obj (ScalarType alias name trans arg) sss = (isValidServerObjectScalarField obj name sss) -- &&(isValidScalarTransformation obj name trans arg) -isValidSubFields :: ServerObject -> [Field] -> [(String,[String])] -> [(String,[String])] -> Bool +isValidSubFields :: ServerObject -> [Field] -> [(String,[(String,String)])] -> [(String,[String])] -> Bool isValidSubFields _ [] _ _ = False -- we should not get an empty query isValidSubFields obj sfs sss sos = foldr (\x y -> (isValidSubField obj x sss sos)&&y) True sfs -isValidSubField :: ServerObject -> Field -> [(String,[String])]-> [(String,[String])] -> Bool +isValidSubField :: ServerObject -> Field -> [(String,[(String,String)])]-> [(String,[String])] -> Bool isValidSubField obj (Left sf) sss sos = (isValidServerObjectScalarField obj sname sss) -- &&(isValidScalarTransformation obj sname trans arg) where sname = getScalarName sf @@ -26,3 +26,32 @@ where nestedObjectField = fromRight (E.throw InvalidObjectException) sf ofname = getObjectName nestedObjectField +-- replace variables with values and do type checking +-- ASSUME: variables are prefixed with $ +replaceObjectsVariables :: [(String,[(String,String)])] -> [RootObject] -> [(String,String,String)] -> [RootObject] +replaceObjectsVariables _ [] _ = [] +replaceObjectsVariables sss objs vars = [replaceObjectVariables sss obj vars | obj<-objs] +replaceObjectVariables :: [(String,[(String,String)])] -> RootObject -> [(String,String,String)] -> RootObject +replaceObjectVariables sss (NestedObject alias name sobject ss sfs) vars = NestedObject alias name sobject (if ss/=Nothing then (replaceScalarVariable (findScalars sss sobject) vars $ fromJust ss) else Nothing) [replaceSubfieldVariables sss sobject vars sf | sf<-sfs] +findScalars :: [(String,[(String,String)])] -> String -> [(String,String)] +findScalars [] _ = E.throw InvalidObjectException +findScalars ((name,sclrs):t) sobj = if (sobj==name) then sclrs else (findScalars t sobj) +replaceScalarVariable :: [(String,String)] -> [(String,String,String)] -> ScalarType -> SubSelection +replaceScalarVariable sclrs vars (ScalarType alias name trans arg) = if (isValue arg)&&(elem '$' $ getValue arg) then (Just $ ScalarType alias name trans (Just $ findReplacement (findScalarType sclrs name) (getValue arg) vars)) else (Just $ ScalarType alias name trans arg) +findScalarType :: [(String,String)] -> String -> String +findScalarType [] _ = E.throw InvalidObjectScalarFieldException +findScalarType ((name,typ):t) sname = if sname==name then typ else (findScalarType t sname) +findReplacement :: String -> String -> [(String,String,String)] -> String +findReplacement styp arg [] = E.throw InvalidVariableNameException +findReplacement styp arg ((name,typ,val):t) + | (name==arg)&&(typ==styp) = val + | (name==arg) = E.throw MismatchedVariableTypeException + | otherwise = findReplacement styp arg t +replaceSubfieldVariables :: [(String,[(String,String)])] -> String -> [(String,String,String)] -> Field -> Field +replaceSubfieldVariables sss sobj vars (Right (NestedObject alias name nsobj ss sfs)) = (Right $ NestedObject alias name sobj (if ss/=Nothing then (replaceScalarVariable (findScalars sss sobj) vars $ fromJust ss) else Nothing) [replaceSubfieldVariables sss nsobj vars sf | sf<-sfs]) :: Field +replaceSubfieldVariables sss sobj vars (Left (ScalarType alias name trans arg)) = if (isValue arg)&&(elem '$' $ getValue arg) then (Left (ScalarType alias name trans (Just $ findReplacement (findScalarType (findScalars sss sobj) name) (getValue arg) vars)) :: Field) else (Left (ScalarType alias name trans arg) :: Field) +isValue :: Maybe String -> Bool +isValue Nothing = False +isValue _ = True +getValue :: Maybe String -> String +getValue arg = fromJust arg diff --git a/src/Components/Parsers/ServerSchemaJsonParser.hs b/src/Components/Parsers/ServerSchemaJsonParser.hs --- a/src/Components/Parsers/ServerSchemaJsonParser.hs +++ b/src/Components/Parsers/ServerSchemaJsonParser.hs @@ -5,25 +5,25 @@ import Model.ServerExceptions -fetchArguments :: FilePath -> IO ([(String,[String])],[(String,[String])],[(String,[String])],[(String,[String])],[(String,String,[String])]) +fetchArguments :: FilePath -> IO ([(String,[String])],[(String,[(String,String)])],[(String,[String])],[(String,[String])],[(String,String,[String])]) fetchArguments fp = do schema <- Prelude.readFile fp let parsed = schema return $ parseSchema parsed -parseSchema :: String -> ([(String,[String])],[(String,[String])],[(String,[String])],[(String,[String])],[(String,String,[String])]) -parseSchema str = parseHelper [] [] [] [] [] $ checkJSValueListValue (decode str :: Result [JSValue]) -checkJSValueListValue :: Result [JSValue] -> [JSValue] +parseSchema :: String -> ([(String,[String])],[(String,[(String,String)])],[(String,[String])],[(String,[String])],[(String,String,[String])]) +parseSchema str = parseHelper [] [] [] [] [] $ checkJSValueListValue (decode str :: Result [JSObject JSValue]) +checkJSValueListValue :: Result [JSObject JSValue] -> [JSObject JSValue] checkJSValueListValue (Error str) = E.throw ImportSchemaException checkJSValueListValue (Ok a) = a -parseHelper :: [(String,[String])] -> [(String,[String])] -> [(String,[String])] -> [(String,[String])] -> [(String,String,[String])] -> [JSValue] -> ([(String,[String])],[(String,[String])],[(String,[String])],[(String,[String])],[(String,String,[String])]) +parseHelper :: [(String,[String])] -> [(String,[(String,String)])] -> [(String,[String])] -> [(String,[String])] -> [(String,String,[String])] -> [JSObject JSValue] -> ([(String,[String])],[(String,[(String,String)])],[(String,[String])],[(String,[String])],[(String,String,[String])]) parseHelper svrobjs sss sos sdbn sor [] = (svrobjs,sss,sos,sdbn,sor) -parseHelper svrobjs sss sos sdbn sor ((JSObject obj):t) = parseHelper ((name,pseudonyms):svrobjs) ((name,scalars):sss) ((name,nestedobjects):sos) ((name,tables):sdbn) (sor++(processRelationships relationships)) t +parseHelper svrobjs sss sos sdbn sor (obj:t) = parseHelper ((name,pseudonyms):svrobjs) ((name,scalars):sss) ((name,nestedobjects):sos) ((name,tables):sdbn) (sor++(processRelationships relationships)) t where name = getServerName (valFromObj "servername" obj :: Result String) pseudonyms = getStringList (valFromObj "pseudonyms" obj :: Result [String]) 0 - scalars = getStringList (valFromObj "scalarfields" obj :: Result [String]) 1 - nestedobjects = getStringList (valFromObj "objectfields" obj :: Result [String]) 2 - tables = getStringList (valFromObj "databasetables" obj :: Result [String]) 3 + scalars = checkScalars (valFromObj "scalarfields" obj :: Result [JSValue]) + nestedobjects = getStringList (valFromObj "objectfields" obj :: Result [String]) 1 + tables = getStringList (valFromObj "databasetables" obj :: Result [String]) 2 relationships = getListStringList (valFromObj "databaserelationships" obj :: Result [[String]]) getServerName :: Result String -> String getServerName (Error str) = E.throw ImportSchemaServerNameException @@ -32,13 +32,34 @@ getStringList (Ok rlt) _ = rlt getStringList _ t | t==0 = E.throw ImportSchemaPseudonymsException - | t==1 = E.throw ImportSchemaScalarFieldsException - | t==2 = E.throw ImportSchemaObjectFieldsException - | t==3 = E.throw ImportSchemaDatabaseTablesException + | t==1 = E.throw ImportSchemaObjectFieldsException + | t==2 = E.throw ImportSchemaDatabaseTablesException | otherwise = E.throw ImportSchemaException getListStringList :: Result [[String]] -> [[String]] getListStringList (Error str) = E.throw ImportSchemaDatabaseRelationshipsException getListStringList (Ok rlt) = rlt +checkScalars :: Result [JSValue] -> [(String,String)] +checkScalars (Error str) = E.throw ImportSchemaScalarFieldsException +checkScalars (Ok a) = getScalars a +getScalars :: [JSValue] -> [(String,String)] +getScalars [] = [] +getScalars ((JSObject obj):t) = (getString (valFromObj "name" obj :: Result String),getType (valFromObj "type" obj :: Result String)):(getScalars t) +getString :: Result String -> String +getString (Error str) = E.throw ImportSchemaScalarFieldsException +getString (Ok a) = a +getType :: Result String -> String +getType (Error str) = E.throw ImportSchemaScalarFieldsException +getType (Ok a) + | a=="Text" = a + | a=="ByteString" = a + | a=="Int" = a + | a=="Double" = a + | a=="Rational" = a + | a=="Bool" = a + | a=="Day" = a + | a=="TimeOfDay" = a + | a=="UTCTime" = a + | otherwise = E.throw ImportSchemaScalarFieldsException processRelationships :: [[String]] -> [(String,String,[String])] processRelationships lst = foldr (\x y -> (getFirst x,getThird x, x):y) [] lst getFirst :: [String] -> String diff --git a/src/Components/Parsers/VariablesParser.hs b/src/Components/Parsers/VariablesParser.hs new file mode 100644 --- /dev/null +++ b/src/Components/Parsers/VariablesParser.hs @@ -0,0 +1,67 @@ +module Components.Parsers.VariablesParser where + +import Text.JSON +import Data.Maybe +import qualified Control.Exception as E +import Model.ServerExceptions + + +-- with a variables string and query string, we want the query variables, the type, and the value +parseVariables :: String -> String -> [(String,String,String)] +parseVariables [] _ = [] +parseVariables var qry = filterToDesired (parseVariableValuePairs var) (getVariableTypePairs qry) +-- with variable-values and variable-types, we want query variable-type-values +filterToDesired :: [(String,String)] -> [(String,String,Maybe String)] -> [(String,String,String)] +filterToDesired _ [] = [] +filterToDesired [] tvar = E.throw MissingVariableValueException +filterToDesired vvar tvars = [findVariableValue tvar vvar | tvar<-tvars] +findVariableValue :: (String,String,Maybe String) -> [(String,String)] -> (String,String,String) +findVariableValue (vname,vtype,vval) [] = if vval==Nothing then E.throw MissingVariableValueException else (vname,vtype,fromJust vval :: String) +findVariableValue (vname1,vtype,vval1) ((vname2,vval2):t) = if (vname1==vname2) then (vname1,vtype,vval2) else (findVariableValue (vname1,vtype,vval1) t) +-- from given variables argument, we want variable-values +parseVariableValuePairs :: String -> [(String,String)] +parseVariableValuePairs vars = castValues $ fromJSObject $ checkVariables (decode vars :: Result (JSObject JSValue)) +checkVariables :: Result (JSObject JSValue) -> JSObject JSValue +checkVariables (Error str) = E.throw ReadVariablesException +checkVariables (Ok vars) = vars +castValues :: [(String,JSValue)] -> [(String,String)] +castValues vars = [("$"++(removeQuotations name),encode val) | (name,val)<-vars] +removeQuotations :: String -> String +removeQuotations (h1:h2:t) = if (h1=='\\')&&(h2=='"') then (removeQuotations t) else h1:(removeQuotations (h2:t)) +removeQuotations str = str +getVariableTypePairs :: String -> [(String,String,Maybe String)] +getVariableTypePairs [] = E.throw EmptyQueryException +getVariableTypePairs qry + | (elem '(' epilogue)&&(elem ')' epilogue) = separateVariables False "" False "" "" $ removeLeadingSpaces $ foldl (\y x -> if x=='(' then [] else y++[x]) [] $ foldr (\x y -> if x==')' then [] else x:y) [] epilogue + | (elem '(' epilogue) = E.throw VariablesSyntaxException + | (elem ')' epilogue) = E.throw VariablesSyntaxException + | otherwise = [] + where + epilogue = getQueryEpilogue qry +getQueryEpilogue :: String -> String +getQueryEpilogue [] = E.throw EmptyQueryException +getQueryEpilogue (h:t) = if (h=='{') then [] else h:(getQueryEpilogue t) +removeLeadingSpaces :: String -> String +removeLeadingSpaces str = foldl (\y x -> if x==' ' then [] else y++[x]) [] str +separateVariables :: Bool -> String -> Bool -> String -> String -> String -> [(String,String,Maybe String)] +separateVariables _ [] _ _ _ [] = [] +separateVariables _ var _ [] _ [] = E.throw VariablesSyntaxException +separateVariables _ var _ typ [] [] = if (isValidBaseType typ) then (var,typ,Nothing):[] else E.throw InvalidVariableTypeException +separateVariables _ var _ typ dval [] = if (isValidBaseType typ) then (var,typ,Just dval):[] else E.throw InvalidVariableTypeException +separateVariables var acc1 typ acc2 acc3 (h:t) + | (var==False)&&(h/=':') = separateVariables var (acc1++[h]) typ acc2 acc3 t + | (var==False) = separateVariables True (removeTailSpaces acc1) False [] [] (removeLeadingSpaces t) + | (typ==False)&&(h/='=') = separateVariables var acc1 typ (acc2++[h]) [] t + | (typ==False)&&(isValidBaseType finalizedType) = separateVariables var acc1 True finalizedType [] (removeLeadingSpaces t) + | (typ==False) = E.throw InvalidVariableTypeException + | (h=='$') = E.throw VariablesSyntaxException + | (h==':') = E.throw VariablesSyntaxException + | (h=='=') = E.throw VariablesSyntaxException + | (h/=',') = separateVariables var acc1 typ acc2 (acc3++[h]) t + | otherwise = (acc1,acc2,if (length acc3)==0 then Nothing else (Just $ removeTailSpaces acc3)):(separateVariables False [] False [] [] t) + where + finalizedType = removeTailSpaces acc2 +removeTailSpaces :: String -> String +removeTailSpaces str = foldr (\x y -> if x==' ' then [] else x:y) [] str +isValidBaseType :: String -> Bool +isValidBaseType typ = elem typ ["Text","ByteString","Int","Double","Rational","Bool","Day","TimeOfDay","UTCTime"] diff --git a/src/GraphQL.hs b/src/GraphQL.hs --- a/src/GraphQL.hs +++ b/src/GraphQL.hs @@ -7,40 +7,11 @@ is a link to the official documentations. You can learn and get a feel on how can you implement this package which is a GraphQL-to-SQL translator with Persistent package return value processing to make a GraphQL format return object string. -This module is made to enable interpreting your GraphQL queries. The expected query type is a single string to comprise all your GraphQL queries and fragments. +This module is made to enable interpreting your GraphQL queries. The expected query type is a single string to comprise all your GraphQL queries and fragments. Expected variable type is a single string to your variable to value definitions. When errors are encountered, this module is simply going to throw an uncaught Exception. The Exception name is some hint to where was the error encountered. More information is provided in the below function description. -Not all GraphQL features are currently supported. For a list of updates and current state, you should check the GitHub updates and example . - -__Instructions to make server schema:__ - -(1) make a list of all server objects in the heirarchy in separate tuples with a list to all pseudonyms (that's including the ones that are referred by relationships) -(2) make a list of all above mentioned server objects in separate tuples with a list to all valid scalar subfields as you read them from your database -(3) make a list of all above mentioned server objects in separate tuples with a list to all valid nested object subfields as you want them to be named (also include these in the first list) -(4) make a list of all above mentioned server objects in separate tuples with a list to all reference database table name(s) as you read them -(5) make a list of database table names in separate tuples with another database table name and a list to the SQL database tables that are between the two first tables; the list order is... -identity table name (the first String in this tuple), identity leaving-field name, referring table name (the table that's corresponding to the second String in this tuple), referring table entering-field name, and (if present) -three String sequences that is intermediary-table name, intermediary-table entering-column name, and intermediary-table leaving-column name. The intermediary tables are ordered from closest to indentity table to closest to referencing table. - -These lists are later used as arguments in a query parsing function. - -__To implement server type heirarchy:__ - - * add new tuple to first schema argument, - * add new tuple to second schema argument (where list is the intersection fields on all children), - * add new tuple to third schema argument (where list is the intersection fields on all children), - * and add new tuple to fourth schema argument (where list is all children database tables). - - You should not need more cases within fifth schema argument, but you may find a child database table and third schema argument list elements pair that is not included. - - Then, you will need to include this, or error is thrown. - - As a final note, we turn our attention to what is posted on the official GraphQL docs: - - @"In contrast, GraphQL only returns the data that's explicitly requested, so new capabilities can be added via new types and new fields on those types without creating a breaking change. This has lead to a common practice of always avoiding breaking changes and serving a versionless API."@ - - - With respect to that, you should be sure to be explicit with your here representation on your data schema. You should give as much detail as possible (sorry for the bad pun), and you should make adjustments when you feel to evolve your server with your desired schema. +Not all GraphQL features are currently supported. For a list to updates and current state, you should check the GitHub updates and example . -} module GraphQL ( @@ -53,34 +24,38 @@ ) where import Data.Text (Text) +import Control.Monad.IO.Class as IO import qualified Components.Parsers.QueryParser as QP +import qualified Components.Parsers.ServerSchemaJsonParser as JP +import qualified Components.Parsers.VariablesParser as VP import qualified Components.DataProcessors.PersistentDataProcessor as DP import Model.ServerObjectTypes import GraphQLHelper -import Components.Parsers.ServerSchemaJsonParser as JP -import Control.Monad.IO.Class as IO {- | - This is the function to call to get queries from a GraphQL query. + This is the simplest function to call to get queries from a GraphQL query. Below are methods where schema is given as json file and not argument strings if this is preferred. - The ordered arguments are: + __Instructions to give server schema arguments:__ - * the GraphQL query as a string - * a list of tuple of String and list of String that is unique server object names and all names that are referencing them with any query - * a list of tuple of String and list of String that is exact same unique server object names while the list is the valid server object - scalar subfields as they are spelt in the database - * a list of tuple of String and list of String that is exact same unique server object names while the list is the valid server object - nested object subfields as you want them named and as they are listed in first schema argument - * a list of tuple of String, String, and list of String that is database table name to make an identity name, a reference database table name, - and a list of String that is identity table, escape identity column name, reference table, arrival reference column name, and a from-to - order of intermediate table triplet strings of intermediate table name, intermediate table arrival column name, and intermediate table - departure column name - - The return value is a tuple of server representation objects and a list of sql queries. The first list is holding lists that are - grouping queries from the same GraphQL query. The inner list is holding the String value sql queries. The server representation objects - is later used to format database results to the GraphQL return value syntax. + (1) make a list of all server objects in the heirarchy in separate tuples with a list to all pseudonyms (that's including the ones that are referred by relationships) + (2) make a list of all above mentioned server objects in separate tuples with a list to all valid scalar subfields as you read them from your database (valid types are Text, ByteString, Int, Double, Rational, Bool, Day, TimeOfDay, or UTCTime) + (3) make a list of all above mentioned server objects in separate tuples with a list to all valid nested object subfields as you want them to be named (also include these in the first list) + (4) make a list of all above mentioned server objects in separate tuples with a list to all reference database table name(s) as you read them + (5) make a list of database table names in separate tuples with another database table name and a list to the SQL database tables that are between the two first tables; the list order is... + identity table name (the first String in this tuple), identity leaving-field name, referring table name (the table that's corresponding to the second String in this tuple), referring table entering-field name, and (if present) + three String sequences that is intermediary-table name, intermediary-table entering-column name, and intermediary-table leaving-column name. The intermediary tables are ordered from closest to indentity table to closest to referencing table. + __To implement server type heirarchy:__ + + * add new tuple to first schema argument, + * add new tuple to second schema argument (where list is the intersection fields on all children), + * add new tuple to third schema argument (where list is the intersection fields on all children), + * and add new tuple to fourth schema argument (where list is all children database tables). + + You should not need more cases within fifth schema argument, but you may find a child database table and third schema argument list elements pair that is not included. + + You then will need to include this, or error is thrown. Here is an example of the GraphQL schema arguments that are expected from the last five arguments. We'll use the GitHub database schema @@ -93,14 +68,16 @@ [("Person",["Person","person","owner"]),("Family",["Family","family"]),("Genus",["Genus","genus"]),("Species",["Species","species"]),("Breed",["Breed","breed"]),("Pet",["Pet","pet"]),("Taxonomy",["Taxonomy","taxonomy"])] @ - * The second schema argument is a mapping to valid scalar subfields from every server object that is listed in the first schema argument: + * The second schema argument is a mapping to valid scalar subfields and type from every server object that is listed in the first schema argument: @ - [("Person",["name","gender"]),("Family",["name"]),("Genus",["name"]),("Species",["name"]),("Breed",["name"]),("Pet",["name","gender"]),("Taxonomy",["name"])] + [("Person",[("id","Int"),("name","Text"),("gender","Int")]),("Family",[("id","Int"),("name","Text")]),("Genus",[("name","Text")]),("Species",[("id","Int"),("name","Text")]),("Breed",[("id","Int"),("name","Text")]),("Pet",[("id","Int"),("name","Text"),("gender","Int")]),("Taxonomy",[("name","Text")])] @ NOTE: You should give only the intersection subfields set to parent server objects with all the children server objects. + NOTE: Valid scalar types are Text, ByteString, Int, Double, Rational, Bool, Day, TimeOfDay, or UTCTime. + * The third schema argument is a mapping to valid nested object (or entity) subfields from every server object that is listed in the first schema argument: @ @@ -180,34 +157,73 @@ * RelationshipConfigurationException (when the relationship schema fifth arugment is incorrect number of String values or when an unrecognized pairing is found) * FailedObjectEqualityException (when we could not match identical queries) * DuplicateRootObjectsException (when there is an overlapping query) + + As a final note, we turn our attention to what is posted on the official GraphQL docs: + + @"In contrast, GraphQL only returns the data that's explicitly requested, so new capabilities can be added via new types and new fields on those types without creating a breaking change. This has lead to a common practice of always avoiding breaking changes and serving a versionless API."@ - + + With respect to that, you should be sure to be explicit with your here representation on your data schema. You should give as much detail as possible (sorry for the bad pun), and you should make adjustments when you feel to evolve your server with your desired schema. -} -processQueryString :: String -- ^ GraphQL query argument as String. - -> [(String,[String])] -- ^ Server object name to list of query reference names. - -> [(String,[String])] -- ^ Server object name to list of valid scalar subfields (which are exactly named after database column names). - -> [(String,[String])] -- ^ Server object name to list of valid nested object subfields (which are named as pleased, though you must include these in the tuple list in the first argument list) - -> [(String,[String])] -- ^ Server object name to list of database table names (which are exact references to table names). - -> [(String,String,[String])] -- ^ two database table names to list of from-to-and intermediate triplet strings as described above to identify all GraphQL relationships with database sequences. - -> ([RootObject],[[String]]) -- ^ The return value is one tuple with server objects and list of grouped sql query strings. -processQueryString str svrobjs sss sos sodn sor = checkObjectsToSql sss sos sodn sor $ flip checkString svrobjs $ QP.processString str +processQueryString :: String -- ^ GraphQL query argument as String. + -> [(String,[String])] -- ^ unique server object name to list of query reference names. + -> [(String,[(String,String)])] -- ^ unique server object name to list of valid scalar subfields (which are exactly named after database column names) and the subfield type. + -> [(String,[String])] -- ^ unique server object name to list of valid nested object subfields (which are named to your preference, though you must include these in the tuple list in the first argument list) + -> [(String,[String])] -- ^ unique server object name to list of database table names (which are exact references to table names). + -> [(String,String,[String])] -- ^ two database table names to list of from-to-and intermediate triplet strings as described above to identify all GraphQL relationships with database sequences. + -> ([RootObject],[[String]]) -- ^ The return value is one tuple with server objects and list with grouped sql query strings. +processQueryString str svrobjs sss sos sodn sor = checkObjectsToSql sss sos sodn sor $ checkStringToObjects svrobjs $ QP.processString str + {- | + This method is same as above, but another second argument is a string to give variables in your query. + + The expected variables string is json syntax. + + When you declare variable types at the beginning of the query, valid types are Text, ByteString, Int, Double, Rational, Bool, Day, TimeOfDay, or UTCTime + + There are additional thrown exceptions: + + * MissingVariableValueException (when we are missing variables in the variables-value string to the query) + * InvalidVariableNameException (when we cannot find a variable in the query with given variables-value string) + * MismatchedVariableTypeException (when query variable type is not matching object scalar type) + * InvalidVariableTypeException (when variable type is invalid or missing) + * ReadVariablesException (when the variables json string syntax is incorrect or was not correctly read) + * VariablesSyntaxException (when the query variables declaration is invalid syntax) + + NOTE: the variable-value json string is variable names without $ at the beginning while all other calls are with preceding $. +-} +processQueryStringWithVariables :: String -- ^ This is the GraphQL query + -> String -- ^ This is the variables string + -> [(String,[String])] -- ^ unique server object name to list of query reference names. + -> [(String,[(String,String)])] -- ^ unique server object name to list of valid scalar subfields (which are exactly named after database column names) and the subfield type. + -> [(String,[String])] -- ^ unique server object name to list of valid nested object subfields (which are named to your preference, though you must include these in the tuple list in the first argument list) + -> [(String,[String])] -- ^ unique server object name to list of database table names (which are exact references to table names). + -> [(String,String,[String])] -- ^ two database table names to list of from-to-and intermediate triplet strings as described above to identify all GraphQL relationships with database sequences. + -> ([RootObject],[[String]]) -- ^ The return value is one tuple with server objects and list with grouped sql query strings. +processQueryStringWithVariables qry vars svrobjs sss sos sodn sor = checkObjectsToSqlWithVariables sss sos sodn sor (VP.parseVariables vars qry) $ checkStringToObjects svrobjs $ QP.processString qry + +{- | Except being nested in a monad, this funcion is same as above. - It is provided a convenience to use json file to configure your schema. + It is allowing you to use a json file to declare your server data schema. - The json format is a list of objects. We're allowing you to here detail your schema with a list of objects to refer to server objects... + The json format is a list of objects. You detail your schema with a list of objects to refer to server objects... + __Instructions to give server schema:__ + The every object is... (1) "servername" is a string to name the server object (2) "pseudonyms" is a list of string to give all query reference - (3) "scalarfields" is a list of scalar type fields + (3) "scalarfields" is a list of objects that are scalar name under "name" and scalar type under "type" (4) "objectfields" is a list of nested object fields (5) "databasetables" is a list of tables in your database - (6) "databaserelationships" is a list of database relationships from this refering table to another table + (6) "databaserelationships" is a list of database relationships from this refering table to another table NOTE: You do not need to repeat databaserelationships in any objects. A relationship is given once, and more is redundant... + NOTE: You should put every objectfields value in some pseudonym list value. + Here is an example: @ @@ -220,9 +236,18 @@ "owner" ], "scalarfields": [ - "id", - "name", - "gender" + { + "name": "id", + "type": "Int" + }, + { + "name": "name", + "type": "Text" + }, + { + "name": "gender", + "type": "Int" + } ], "objectfields": [ "pet" @@ -241,9 +266,18 @@ "Pet" ], "scalarfields": [ - "name", - "gender", - "id" + { + "name": "id", + "type": "Int" + }, + { + "name": "name", + "type": "Text" + }, + { + "name": "gender", + "type": "Int" + } ], "objectfields": [ "owner" @@ -258,9 +292,17 @@ ] @ - The exceptions thrown with this function are same as above function, but there are a few more... + __To implement server type heirarchy:__ + + * add new object to list, + * give the intersection scalar fields in the scalarfields argument, + * give the intersection object fields in the objectfields argument, + * and add all referring children database table names to the databasetables argument. + NOTE: You should not need more cases in the databaserelationships argument, but you may find a child database table and object field database table pair that is not included. + The exceptions thrown with this function are same as above function, but there are a few more... + * ImportSchemaException (when there is a problem with reading your schema) * ImportSchemaServerNameException (when there is a problem with reading your servername argument) * ImportSchemaPseudonymsException (when there is a problem with reading your pseudonyms list argument) @@ -268,29 +310,61 @@ * ImportSchemaObjectFieldsException (when there is a problem with reading your objectfields list argument) * ImportSchemaDatabaseTablesException (when there is a problem with reading your databasetables list argument) * ImportSchemaDatabaseRelationshipsException (when there is a problem with reading your databaserelationships list argument) + + As a final note, we turn our attention to what is posted on the official GraphQL docs: + + @"In contrast, GraphQL only returns the data that's explicitly requested, so new capabilities can be added via new types and new fields on those types without creating a breaking change. This has lead to a common practice of always avoiding breaking changes and serving a versionless API."@ - + + With respect to that, you should be sure to be explicit with your here representation on your data schema. You should give as much detail as possible (sorry for the bad pun), and you should make adjustments when you feel to evolve your server with your desired schema. -} processQueryStringWithJson :: (MonadIO m) - => String -- ^ This is the GraphQL query - -> FilePath -- ^ This is the filepath to your server schema json file - -> m ([RootObject],[[String]]) -- ^ Return value is same as above, but it is nested in a Monad -processQueryStringWithJson str fp = do - schema <- IO.liftIO $ JP.fetchArguments fp - let (svrobjs,sss,sos,sodn,sor) = schema - return $ checkObjectsToSql sss sos sodn sor $ flip checkString svrobjs $ QP.processString str + => String -- ^ This is the GraphQL query + -> FilePath -- ^ This is the filepath to your server schema json file + -> m ([RootObject],[[String]]) -- ^ The return value is a monad of one tuple with server objects and list with grouped sql query strings. +processQueryStringWithJson qry fp = do + (svrobjs,sss,sos,sodn,sor) <- IO.liftIO $ JP.fetchArguments fp + return $ checkObjectsToSql sss sos sodn sor $ checkStringToObjects svrobjs $ QP.processString qry + {- | + This method is same as above, but another third argument is a string to give variables in your query. + + The expected variables string is json syntax. + + When you declare variable types at the beginning of the query, valid types are Text, ByteString, Int, Double, Rational, Bool, Day, TimeOfDay, or UTCTime + + There are additional thrown exceptions: + + * MissingVariableValueException (when we are missing variables in the variables-value string to the query) + * InvalidVariableNameException (when we cannot find a variable in the query with given variables-value string) + * MismatchedVariableTypeException (when query variable type is not matching object scalar type) + * InvalidVariableTypeException (when variable type is invalid or missing) + * ReadVariablesException (when the variables json string syntax is incorrect or was not correctly read) + * VariablesSyntaxException (when the query variables declaration is invalid syntax) + + NOTE: the variable-value json string is variable names without $ at the beginning while all other calls are with preceding $. +-} +processQueryStringWithJsonAndVariables :: (MonadIO m) + => String -- ^ This is the GraphQL query + -> String -- ^ This is the variables string + -> FilePath -- ^ This is the filepath to your server schema json file + -> m ([RootObject],[[String]]) -- ^ The return value is a monad of one tuple with server objects and list with grouped sql query strings. +processQueryStringWithJsonAndVariables qry vars fp = do + (svrobjs,sss,sos,sodn,sor) <- IO.liftIO $ JP.fetchArguments fp + let dvars = VP.parseVariables vars qry + return $ checkObjectsToSqlWithVariables sss sos sodn sor dvars $ checkStringToObjects svrobjs $ QP.processString qry + +{- | This is the function to call after casting PersistValues to Text from processQueryString. The ordered arguments are: * all the data that is cast to Text type - * an unmodified copy of the RootObject list that is returned from processQueryString. + * an unmodified copy of the RootObject list that is returned from processing the query string. The return result is a string to resemble the GraphQL return value. - Making the first argument is demonstrated in the GitHub . - - Current implementation is to cast all values to Text since arbitrary columns data types are not inferred. + Current implementation is to cast all values to Text since arbitrary columns data types are not inferred, though next update is changing this limitation. When an error is encountered, an uncaught exception is thrown. The exceptions thrown are of: @@ -300,7 +374,7 @@ * EOFDataProcessingException (when the given data is shorter than expected in reference to the given serve objects) * InvalidArgumentException (when there is an internal argument error - you should not observe this) -} -processPersistentData :: [[[[Text]]]] -- ^ database query return value as casted to only Text data types and with no other alterations (a list of GraphQL-grouped results list of SQL query results list of data row lists) - -> [RootObject] -- ^ unmodified server objects that was given by the previous processQueryString function. - -> String -- ^ The return value is a string type to describe the GraphQL-organized return values. +processPersistentData :: [[[[Text]]]] -- ^ database query return value as casted to only Text data types and with no other alterations (a list of GraphQL-grouped results list of SQL query results list of data row lists) + -> [RootObject] -- ^ unmodified server objects that was given by the previous processQueryString function. + -> String -- ^ The return value is a string type to describe the GraphQL-organized return values. processPersistentData dt ro = DP.processReturnedValues ro dt diff --git a/src/GraphQLHelper.hs b/src/GraphQLHelper.hs --- a/src/GraphQLHelper.hs +++ b/src/GraphQLHelper.hs @@ -9,8 +9,13 @@ import Model.ServerExceptions -checkString :: String -> [(String,[String])] -> [RootObject] -checkString str svrobjs = if (QP.validateQuery str)==True then (QP.parseStringToObjects str svrobjs) else E.throw SyntaxException -checkObjectsToSql :: [(String,[String])] -> [(String,[String])] -> [(String,[String])] -> [(String,String,[String])] -> [RootObject] -> ([RootObject],[[String]]) -checkObjectsToSql sss sos sodn sor ros = if (SOV.checkObjectsAttributes ros sss sos)==True then (reducedObjects,QC.makeSqlQueries reducedObjects sodn sor) else (E.throw InvalidObjectSubFieldException) - where reducedObjects = SOT.mergeDuplicatedRootObjects ros +checkStringToObjects :: [(String,[String])] -> String -> [RootObject] +checkStringToObjects svrobjs str = if (QP.validateQuery str)==True then (QP.parseStringToObjects str svrobjs) else E.throw SyntaxException +checkObjectsToSql :: [(String,[(String,String)])] -> [(String,[String])] -> [(String,[String])] -> [(String,String,[String])] -> [RootObject] -> ([RootObject],[[String]]) +checkObjectsToSql sss sos sodn sor ros = if (SOV.checkObjectsAttributes reducedRobjs sss sos)==True then (reducedRobjs,QC.makeSqlQueries reducedRobjs sodn sor) else (E.throw InvalidObjectException) + where reducedRobjs = SOT.mergeDuplicatedRootObjects ros +checkObjectsToSqlWithVariables :: [(String,[(String,String)])] -> [(String,[String])] -> [(String,[String])] -> [(String,String,[String])] -> [(String,String,String)] -> [RootObject] -> ([RootObject],[[String]]) +checkObjectsToSqlWithVariables sss sos sodn sor vars ros = if (SOV.checkObjectsAttributes valueObjects sss sos)==True then (valueObjects,QC.makeSqlQueries valueObjects sodn sor) else (E.throw InvalidObjectSubFieldException) + where + reducedObjects = SOT.mergeDuplicatedRootObjects ros + valueObjects = SOV.replaceObjectsVariables sss reducedObjects vars diff --git a/src/Model/ServerExceptions.hs b/src/Model/ServerExceptions.hs --- a/src/Model/ServerExceptions.hs +++ b/src/Model/ServerExceptions.hs @@ -9,11 +9,18 @@ EmptyQueryException | InvalidObjectException | InvalidScalarException | + InvalidObjectNestedObjectFieldException | + InvalidObjectScalarFieldException | InvalidObjectSubFieldException | + InvalidAttributeTransformation | NullArgumentException | CreatingSqlQueryObjectFieldsException | + CreatingSqlQueryObjectsException | + TooManyTablesException | + EmptyRowException | EOFDataProcessingException | InvalidArgumentException | + Foundlinebreakexception | RelationshipConfigurationException | FailedObjectEqualityException | DuplicateRootObjectsException | @@ -23,7 +30,13 @@ ImportSchemaScalarFieldsException | ImportSchemaObjectFieldsException | ImportSchemaDatabaseTablesException | - ImportSchemaDatabaseRelationshipsException + ImportSchemaDatabaseRelationshipsException | + MissingVariableValueException | + InvalidVariableNameException | + MismatchedVariableTypeException | + InvalidVariableTypeException | + ReadVariablesException | + VariablesSyntaxException deriving Show -- InvalidObjectNestedObjectFieldException | diff --git a/src/Model/ServerObjectTypes.hs b/src/Model/ServerObjectTypes.hs --- a/src/Model/ServerObjectTypes.hs +++ b/src/Model/ServerObjectTypes.hs @@ -8,7 +8,6 @@ -- | NestedObjects are the general object type. They are found as RootObjects or as object Subfields. data NestedObject = NestedObject Alias Name ServerObject SubSelection SubFields deriving Show - type Alias = Maybe String type ServerObject = String type SubSelection = Maybe ScalarType