Skip to content
Permalink
Browse files

initial

  • Loading branch information
kenwheeler committed Jan 24, 2018
0 parents commit b97d64ab7ffabe5be7439135282553151c3585ea
Showing with 8,130 additions and 0 deletions.
  1. +26 −0 .babelrc
  2. +1 −0 .eslintignore
  3. +28 −0 .eslintrc
  4. +1 −0 .gitignore
  5. +3 −0 .vscode/settings.json
  6. +176 −0 README.md
  7. +19 −0 custom-typings/create-react-context.d.ts
  8. +7 −0 custom-typings/graphql-tag.d.ts
  9. +58 −0 demo/home.tsx
  10. +17 −0 demo/index.tsx
  11. +5 −0 demo/loading.tsx
  12. +30 −0 demo/todo-form.tsx
  13. +16 −0 demo/todo-list.tsx
  14. +187 −0 lib/components/client.js
  15. +30 −0 lib/components/connect.js
  16. +18 −0 lib/components/context.js
  17. +23 −0 lib/components/provider.js
  18. +100 −0 lib/index.js
  19. 0 lib/interfaces/client-options.js
  20. 0 lib/interfaces/client.js
  21. +37 −0 lib/interfaces/index.js
  22. 0 lib/interfaces/mutation.js
  23. 0 lib/interfaces/query.js
  24. +135 −0 lib/modules/client.js
  25. +70 −0 lib/modules/hash.js
  26. +16 −0 lib/modules/mutation.js
  27. +16 −0 lib/modules/query.js
  28. +78 −0 lib/modules/typenames.js
  29. +80 −0 package.json
  30. +16 −0 public/index.html
  31. +207 −0 src/components/client.tsx
  32. +41 −0 src/components/connect.tsx
  33. +5 −0 src/components/context.tsx
  34. +19 −0 src/components/provider.tsx
  35. +13 −0 src/index.ts
  36. +4 −0 src/interfaces/client-options.ts
  37. +12 −0 src/interfaces/client.ts
  38. +4 −0 src/interfaces/index.ts
  39. +5 −0 src/interfaces/mutation.ts
  40. +4 −0 src/interfaces/query.ts
  41. +13 −0 src/modules/client.test.ts
  42. +135 −0 src/modules/client.ts
  43. +73 −0 src/modules/hash.ts
  44. +8 −0 src/modules/mutation.ts
  45. +8 −0 src/modules/query.ts
  46. +85 −0 src/modules/typenames.ts
  47. +22 −0 tsconfig.json
  48. +44 −0 webpack.config.js
  49. +6,235 −0 yarn.lock
@@ -0,0 +1,26 @@
{
"plugins": [
"@babel/syntax-object-rest-spread",
"@babel/plugin-proposal-pipeline-operator",
[
"module-resolver",
{
"extensions": [".js", ".jsx", ".ts", ".tsx"],
"root": ["."]
}
]
],
"presets": [
"@babel/typescript",
"@babel/react",
"@babel/stage-3",
[
"@babel/env",
{
"targets": {
"browsers": "last 2 Chrome versions"
}
}
]
]
}
@@ -0,0 +1 @@
lib
@@ -0,0 +1,28 @@
{
"extends": "formidable/configurations/es6-react",
"parser": "typescript-eslint-parser",
"globals": { "__dirname": true },
"rules": {
"quotes": [2, "single", { "allowTemplateLiterals": true }],
"comma-dangle": [
"error",
{
"arrays": "always-multiline",
"objects": "always-multiline",
"imports": "always-multiline",
"exports": "always-multiline",
"functions": "ignore"
}
],
"no-magic-numbers": "off",
"func-style": "off",
"arrow-parens": "off",
"no-use-before-define": "off",
"react/jsx-filename-extension": "off",
"react/require-extension": "off",
"react/no-multi-comp": "warn",
"react/prop-types": "warn",
"react/sort-comp": "warn",
"react/sort-prop-types": "warn"
}
}
@@ -0,0 +1 @@
node_modules
@@ -0,0 +1,3 @@
{
"typescript.tsdk": "./node_modules/typescript/lib"
}
176 README.md
@@ -0,0 +1,176 @@
# urql

Universal React Query Library

![Urkel](https://media.giphy.com/media/Dc60NIUs12QvK/giphy.gif)

## What is `urql`

`urql` is a GraphQL client, exposed as a set of ReactJS components.

## Why this exists

In my experience, existing solutions have been a bit heavy on the API side of things, and I see people getting discouraged or turned away from the magic that is GraphQL. This library aims to make GraphQL on the client side as simple as possible.

## How its different

### React

`urql` is specifically for React. There have been no efforts made to abstract the core in order to work with other libaries. Usage with React was a priority from the get go, and it has been architected as such.

### Render Props

`urql` exposes its API via render props. Recent discussion has shown render props to be an extraordinarily flexible and appropriate API decision for libraries targeting React.

### Caching

`urql` takes a unique approach to caching. Many existing solutions normalize your data and parse your queries to try to invalidate cached data. I am not smart enough to implement this solution, and further, normalizing everything, on big datasets, can potentially lead to performance/memory issues.

`urql` takes a different approach. It takes your query signature and creates a hash, which it uses to cache the results of your query. It also adds `__typename` fields to both queries and mutations, and by default, will invalidate a cached query if it contains a type changed by a mutation. Further, handing control back to the users, it exposes a `shouldInvalidate` prop, which is a function that can be used to determine whether the cache is invalid based upon typenames, mutation response and your current data.

## Install

`npm install urql --save`

## Getting Started

The core of `urql` is three exports, `Provider`, `Connect` and `Client`. To get started, you simply create a `Client` instance, pass it to a `Provider` and then wrap any components you want to make queries or fire mutation from with a `Connect` component.

Lets look at a root level component and how you can get it set up:

```jsx
import React from 'react';
import ReactDOM from 'react-dom';
import { Provider, Client } from '../src/index';
import Home from './home';
const client = new Client({
url: 'http://localhost:3001/graphql',
});
export const App = () => (
<Provider client={client}>
<Home />
</Provider>
);
ReactDOM.render(<App />, document.getElementById('root'));
```

As you can see above, all that's required to get started is the `url` field on `Client` which tells us where your GraphQL API lives. After the client is created, and passed to the `Provider` that wraps your app, now you can wrap any component down in the tree with a `Connect` to start issuing queries.

Queries and mutations both have creation functions, which you can import. An `urql` `Connect` component can take multiple queries, and multiple mutations. The `render` prop exposes the internal logic to any component you`d like to provide it to.
Lets start by defining a query and a mutation:
```javascript
const TodoQuery = `
query {
todos {
id
text
}
}
`;
```

## HOLD UP FAM THIS IS IMPORTANT

It is absolutely necessary if you want this library to work properly, to create a valid mutation response. If you change a todo, return it. If you delete a todo, return it. If you add a todo, return it. If you don't return the thing that changed and file an issue, I'm going to screenshot this paragraph, paste it into the issue, and then drop my finger from a 3ft height onto the close button while making plane crash sounds.

```javascript
const AddTodo = `
mutation($text: String!) {
addTodo(text: $text) {
id
text
}
}
`;
```

Now we can use the `mutation` and `query` functions to format them in the way `urql` expects.

```javascript
const Home = () => (
<Connect
query={query(TodoQuery)}
mutation={{
addTodo: mutation(AddTodo),
}}
render={({ loaded, fetching, refetch, data, error, addTodo }) => {
//...Your Component
}}
/>
);
```

The render prop sends a couple of fields back by default:

* `loaded` - This is like `loading` but its false by default, and becomes true after the first time your query loads. This makes initial loading states easy and reduces flicker on subsequent fetch/refetches.
* `fetching` - This is what you might commonly think of as `loading`. Any time a query or mutation is taking place, this puppy equals true, resolving to false when complete.
* `refetch` - This is a method that you can use to manually refetch your query, skipping and repopulating the cache.
* `data` - This is where your data lives. Once the query returns, This would look like `{ todos: [...] }`.
* `error` - If there is an error returned when making the query, instead of data, you get this and you can handle it or show a `refetch` button or cry or whatever you wanna do.

Also, any mutations, because they are named, are also passed into this render prop.

As you can see above, the `query` accepts either a single query, or an array of queries. The `mutation` prop accepts an object, with the mutation names as keys.

So why do we use these `query` and `mutation` functions before passing them? Variables, thats why. If you wanted to pass a query with variables, you would construct it like so:

```javascript
query(TodoQuery, { myVariable: 5 });
```

Similarly, you can pass variables to your mutation. Mutation, however is a bit different, in the sense that it returns a function that you can call with a variable set:

```javascript
mutation(AddTodo); // No initial variables
// After you pass 'addTodo' from the render prop to a component:
addTodo({ text: `I'm a variable!` });
```

## Cache control

Normally in `urql`, the cache is aggressively invalidated based upon `__typename`, but if you want finer grained control over your cache, you can use the `shouldInvalidate` prop. It is a function, that returns boolean, much like `shouldComponentUpdate`, which you can use to determine whether your data needs a refresh from the server. It gets called after every mutation:

```javascript
const MyComponent = () => (
<Connect
query={query(MyQuery)}
shouldInvalidate={(changedTypenames, typenames, mutationResponse, data) => {
return data.todos.some(d => d.id === mutationResponse.id);
}}
render={({ loaded, fetching, refetch, data, error, addTodo }) => {
//...Your Component
}}
/>
);
```

The signature of `shouldComponentUpdate` is basically:

* `changedTypenames` - The typenames returned from the mutation. ex: `['Todo']`
* `typenames` - The typenames that are included in your `Connect` component. ex: `['Todo', 'User', 'Author']`
* `response` - The actual data returned from the mutation. ex: `{ id: 123 }`
* `data` - The data that is local to your `Connect` component as a result of a query. ex: `{ todos: [] }`

Using all or some of these arguments can give you the power to pretty accurately describe whether your connection has now been invalidated.

## API

## TODO

* [ ] Server Side Rendering
* [ ] Client HoC
* [ ] Client Side GraphQL
* [ ] Tests
* [ ] Fix Lint

## Prior Art

### Apollo
@@ -0,0 +1,19 @@
declare module 'create-react-context' {
import * as React from 'react';

export default function createReactContext<T>(defaultValue: T): Context<T>;

export type Context<T> = {
Provider: React.ComponentClass<ProviderProps<T>>;
Consumer: React.ComponentClass<ConsumerProps<T>>;
};

export type ProviderProps<T> = {
value: T;
children: React.ReactNode;
};

export type ConsumerProps<T> = {
children: (value: T) => React.ReactNode;
};
}
@@ -0,0 +1,7 @@
declare module 'graphql-tag' {
import { DocumentNode } from 'graphql';
export default function gql(
literals: TemplateStringsArray,
...placeholders: Array<string>
): DocumentNode;
}
@@ -0,0 +1,58 @@
import React from 'react';
import { Connect, query, mutation } from '../src/index';
import TodoList from './todo-list';
import TodoForm from './todo-form';
import Loading from './loading';

const Home = () => (
<Connect
query={query(TodoQuery)}
mutation={{
addTodo: mutation(AddTodo),
removeTodo: mutation(RemoveTodo),
}}
render={({ loaded, data, addTodo, removeTodo }) => {
return (
<div>
{!loaded ? (
<Loading />
) : (
<TodoList todos={data.todos} removeTodo={removeTodo} />
)}
<TodoForm addTodo={addTodo} />
</div>
);
}}
/>
);

const AddTodo = `
mutation($text: String!) {
addTodo(text: $text) {
id
text
}
}
`;

const RemoveTodo = `
mutation($id: ID!) {
removeTodo(id: $id) {
id
}
}
`;

const TodoQuery = `
query {
todos {
id
text
}
user {
name
}
}
`;

export default Home;
@@ -0,0 +1,17 @@
import React from 'react';
import ReactDOM from 'react-dom';

import { Provider, Client } from '../src/index';
import Home from './home';

const client = new Client({
url: 'http://localhost:3001/graphql',
});

export const App = () => (
<Provider client={client}>
<Home />
</Provider>
);

ReactDOM.render(<App />, document.getElementById('root'));
@@ -0,0 +1,5 @@
import React from 'react';

const Loading = () => <p>Loading...</p>;

export default Loading;
@@ -0,0 +1,30 @@
import React from 'react';

type TodoFormProps = {
addTodo: (text: object) => void;
};

class TodoForm extends React.Component<TodoFormProps> {
input: HTMLInputElement;
addTodo = () => {
this.props.addTodo({ text: this.input.value });
this.input.value = '';
};
render() {
return (
<div>
<input
type="text"
ref={i => {
this.input = i;
}}
/>
<button type="button" onClick={this.addTodo}>
Add Todo
</button>
</div>
);
}
}

export default TodoForm;

0 comments on commit b97d64a

Please sign in to comment.
You can’t perform that action at this time.