Detailed API Docs about graphql-utilities

[steffenmllr]

That would be great. Do have an example of using scalar type ? Couldn't really figure out how to pass them into the build function

[migueloller]

Hi @steffenmllr, sorry for the lack of detailed API docs. They're coming soon! 😆

To make a scalar type you have two options.

Pass in your configuration:

build(`
  scalar MyCustomScalar
`, {
  serialize: (value) => { ... },
  parseValue: (value) => { ... },
  parseLiteral: (valueAST) => { ... },
});

Pass in another scalar (this option simply renames the type):

build(`
  scalar MyGraphQLJSON
`, GraphQLJSON); // from `graphql-type-json` package

Let me know if you have any other questions!

[steffenmllr]

@migueloller Thanks for the feedback. Hmm that somehow doesn't work:

const {build} = require('graphql-utilities');
const GraphQLDate = new GraphQLScalarType({

    name: 'Date',

    serialize: value => {
        return value;
    },

    parseValue: value => {
        value = value === 'now' ? moment().toISOString() : value;
        const result = Joi.validate(value, Joi.date().iso());
        if (result.error) {
            throw new GraphQLError('Parse error: Not a valid ISO Date');
        }
        return value;
    },

    parseLiteral: ast => {
        if (ast.kind !== Kind.STRING) {
            throw new GraphQLError(`Query error: Can only parse strings got a: ${ast.kind}`, [ast]);
        }
        const value = ast.value === 'now' ? moment().toISOString() : ast.value;
        const result = Joi.validate(value, Joi.date().iso());

        if (result.error) {
            throw new GraphQLError('Query error: Not a valid ISO Date', [ast]);
        }
        return value;
    }
});

const User = build(`
    scalar Date
    type User {
        id: String!
        name: String
        email: String!
        password: String
        create_at: Date
        updated_at: Date
    }
`, GraphQLDate);

And one more thing? How do I set the description for the type and the field within the type?

[migueloller]

Ahh, I see your issue. When you have multiple types defined in the template string you need a config map instead of a config. This is something that will be added to the docs!

Try something like this:

const { User, Date } = build(`
    scalar Date
    type User {
        id: String!
        name: String
        email: String!
        password: String
        create_at: Date
        updated_at: Date
    }
`, {
  Date: GraphQLDate,
});

But really what you want is to do something like this:

const User = build(`
    type User {
        id: String!
        name: String
        email: String!
        password: String
        create_at: Date
        updated_at: Date
    }
`, () => [GraphQLDate]);

The arguments to build are typeDefinitions, config/configMap, and typeDependencies. If you depend on any types in your schema you can simply pass it as an array (or array thunk if you have circular dependencies).

EDIT: I know it's very confusing that sometimes build returns an object of types and other times it returns a type (depending on how many types you define). This is the main motivation behind the changes in #12!

[steffenmllr]

Yeah to be hontest, that is really confusing :) Because my next thing would be to get two Scalars in one definition. Something like:

const {User} = build(`
    scalar Date
    scalar UUID
    type User {
        id: UUID!
        name: String
        email: String!
        created_at: Date!
        updated_at: Date!
    }
`, {UUID: GraphQLUUID, Date: GraphQLDate});

Which throws Schema must contain unique named types but contains multiple types named "UUID"

[migueloller]

Hmm, interesting. It shouldn't be throwing that error unless you're defining UUID again somewhere else. There's no need to type scalar Date and scalar UUID in the template string if you already have them defined elsewhere. If you want to use them then just pass them in as type dependencies via the last argument.

Do this:

const User = build(`
    type User {
        id: UUID!
        name: String
        email: String!
        created_at: Date!
        updated_at: Date!
    }
`, () => [GraphQLUUID, GraphQLDate]);

[steffenmllr]

Ah ok now I get it. I thought you needed some kind of Object Mapping in the second parameter. Had a look in the code and now it makes sense :)

Thanks! Great lib!

[migueloller]

Thanks man! Appreciate you using it and hopefully it will be even more useful once we implement the planned changes. 😄

[steffenmllr]

Ok I have on more question on resolving fields:

const User = build(`
    type User {
        id: UUID!
        name: String
        first_name: String
        last_name: String
        created_at: Date!
        updated_at: Date!
    }
`, {
    fields: {
        name: (user) => `${user.first_name} ${user.last_name}`
    }
}, [GraphQLUUID, GraphQLDate]);

Shouldn't that work?

And might I suggest a API Change to build(typeDef='', config=Object||Array) ? where config has a resolve and and types and get rid of the inferred option (I'm using your lib since it only let's me build types and not the whole thing)

config could also be an array of types for a shortcut. What do you think ?

Edit: When you show me the resolve exmaple you can just put this in readme and your done with the docs :)

[migueloller]

@steffenmllr, yes! We will be completely revamping the API so that it's not as confusing. Take a look at #12 for more info on how the API will change.

With regards to your question, here is how you would do it:

const User = build(`
    type User {
        id: UUID!
        name: String
        first_name: String
        last_name: String
        created_at: Date!
        updated_at: Date!
    }
`, {
    name: (user) => `${user.first_name} ${user.last_name}`
}, [GraphQLUUID, GraphQLDate]);

The way you mentioned also works but we provide a shortcut so that you don't have to type fields each time.

EDIT: I'll add a quick update to the docs this weekend while I work on the new implementation changes!