maticzav / kayu Goto Github PK

We should have a feature template that notably indicates that everyone creating an issue/pr has read our community guidelines.

We should make it possible that developers reuse existing tools like urql and Apollo and only make a selection using Kayu.

Let's aim for a thin wrapper around both of those libraries that correctly fixates the types and forwards selection and variables to given functions.

Generated code should include detailed examples and documentation of every function that Kayu supports. Our end goal is that every function has some sort of meaningful documentation. Ideally, developers shouldn't have to read our documentation to start using Kayu or any of our libraries.

SelectionSet class should contain some general utility functions that let developers convert their named-type decoders into nullable and list types.

Those should include:

• list
• nullable
• nonNullOrFail
• selection

As the title describes, generator functionality should live in @kayu/codegen. I think it'd be best if we included @kayu/codegen as a peer-dependency in @kayu/client and have it trigger some post-install scripts.

Project landing page should briefly explain what Kayu aims to solve, what most notable features are, point to the documentation and include a sandbox.

Layout

• Navigation
• Hero
• Sandbox
• Problems it aims to solve
• Features
• Call to action

Problems it aims to solve

• Easily approachable. ("We wanted to make a client that is easy to use for beginners and scales with your project no matter the size. Most existing GraphQL clients rely on third-party code to generate their types. Kayu is type-safe down to its core.")
• Allow programmatic queries. ("It's prevalent for bigger projects to rely on fragments and lots of queries. Even though that works in theory, bugs creep into string selections, and we have to introduce lots of additional tooling to our project to prevent it. Kayu relies on TS compiler and makes sure your queries work as expected in every project size.")
• Learn GraphQL schema as you write your code. ("My usual workflow when working with an API is reading the docs, opening Playground and writing the code. Kayu lets you merge all three of these into one. We generate expressive documentation for every function. This way, you can start exploring the docs by typing o.query and end up with a working implementation once you've found everything you need.")

Features

Include an image of every feature next to it.

• Fantastic IDE suggestions. with a screenshot of VSCode ("Kayu generates meaningful docs for every function it exports.")
• Forget GraphQL. with GraphQL in sparkles/magic ("Kayu abstracts GraphQL layer from you. You need no knowledge of GraphQL to start querying GraphQL APIs. You'll get a feeling that you are working with an official SDK, not an API")
• TypeSafe with TS/JS logo ("Kayu uses intelligent TypeScript compiler to verify your queries during build time. If your project compiles, your queries work.")

Call to Action

Ready to get started? Read our 5 min getting started guide!

We should write extensive documentation that outlines how Kayu works. If possible, we should try to extend functionality from examples with twoslash.

Guides

• Quick Start guide ("Get started using Kayu in 5 minutes.")
• Custom Scalars ("Should cover how to introduce custom Codecs in Kayu and reference to ref-docs")
• Creating selections/Writing Queries ("Deep dive into how queries and type-checking with Phantom types works.")

Reference

• Generator configuration and running
• SelectionSet - all available functions
• Data fetching and headers
• Codecs with reference to recepies

Recepies

• Common Codecs
• Authorization mechanism
• Recursive types, Going crazy with Kayu

I see huge potential in having GraphQL clients as a service when it comes to deno. Kayu abstracts GraphQL in a way that makes clients of many existing GraphQL schemas act more as an official SDK than an API.

I see two possible strategies for evolving this:

1. Create a proxy (i.e. a service) that generates the SDK from GraphQL schema for a particular endpoint on the go and serves that to some deno code;
2. Implement an express middleware or whatnot that does that for clients who want to opt-in.

The first option seems a bit better since we take control of distribution, but we could develop the second one first and extend it to the first one.

We should implement a library that would allow developers to easily use their queries in their React projects. Having a hook (e.g. useKayu) seems like a good idea. The first version shouldn't do much more besides fetching the data and reloading the view on change.

The hook should also accept headers and be easily extensible so that people may write custom wrappers for authorization (for example). We should also add a recipes tab to the documentation that would show example.

Example

function View() {
    // Query
    const [data, err] = useKayu(query, {
        headers: {
            Authorization: "Bearer"
        }
    })

    // View
    return <div>{data?.name}</div>
}

We should export "official" Kayu packages of some of the bigger companies that use GraphQL. Hopefully, this project can gain some financial support this way.

To corroborate on the task, these packages should be autogenerated every now and then and published under @kayu/<name> tag. These packages would include predefined codecs and be tested from our side. We should have them in the build/test process of Kayu to make sure we catch any potential bug in Kayu before it reaches end-users.

Companies

• GitHub (@kayu/github)
• Shopify (@kayu/shopify)

This list should be extended with comments