Client usage

[DarkoKukovec]

Initialization:

const client = createClient({
  QueryBuilder: SomeQueryBuilder,
  network: new Network.Promise(),
  store: new Collection(),
  options: {
    optimistic: true,
  },
})

Usage:

client.from(Todo).id(1).fetch();
client.from(Todo).match({ open: true }).fetch();

client.from(Todo).id(1).update({  open: false }); // defined in the client
client.from(Todo).id(1).optimisticUpdate({  open: false }); // explicit
client.from(Todo).id(1).pesimisticUpdate({  open: false }); // explicit

client.from(Todo).id(1).delete();
client.fromInstance(todoItem).delete();

client.from(Todo).create({ open: true, title: 'Support for creation' });

Chaining:

client.from(User).id(1).chain(
  (user) => client.from(Todo).match({ owner: user.id }),
).fetch();

[isBatak]

Optimistic update

const client = createClient({
  QueryBuilder: SomeQueryBuilder,
  network: new Network.Promise(),
  store: new Collection(),
  options: {
    optimistic: true,
  },
})

Client should not be responsible for optimistic update behaviour. Optimistic update is a View layer and should be handled in the user land.

Optimistic update is more complex than just some flag.
So this is not enough:

client.from(Todo).id(1).optimisticUpdate({  open: false }); // explicit
client.from(Todo).id(1).pesimisticUpdate({  open: false }); // explicit

We need some API for rolling back in case of error.
This is how we can do it in React land:

const { data, mutate } = useQuery(queryTodo);
const [create, { status }] = useMutation(createTodo, {
    onMutate: ({ input }) => {
       // get current data from the cache
       
       // do optimistic update and trigger re-render
       
       // rollback
       return () => {
          //  return to previous state 
       };
    },
    onFailure: ({ rollback }) => {
       rollback();
    }
  });

Chaining:

client.from(User).id(1).chain(
  (user) => client.from(Todo).match({ owner: user.id }),
).fetch();

Chain functions should be pure and accept client too so we can reuse already existing queries:

client.from(User).id(1).chain(
  (client, user) => client.from(Todo).match({ owner: user.id }),
);

so we can decouple it like this

const queryTodoByUser = (client, { id }) => client.from(Todo).match({ owner: id });
const queryUser = (client, { id }) => client.from(User).id(id).chain(queryTodoByUser);

const data = queryUser(client, { id: 1 }).fetch();

Only problem with this example is that we don't have a way to avoid waterfalls.
Actually we don't have to chain them because only dependency is id which we know right away.
So this is better approach:

const userFetcher = queryUser(client, { id: 1 }).fetch();
const todoFetcher = queryTodoByUser(client, { id: 1 }).fetch();
const [user, todo] => await Promise.all([userFetcher, todoFetcher]);

JSON:API relationship

For JSON:API (or any RESTful api) we can extend QueryBuilder with relationship keyword, similar to match which can fetch related resources that are not included in the main response.

client.from(User).id(1).relationship('todos').id(1).fetch();

This way you can fetch todos of specific user.

[DarkoKukovec]

Optimistic update

Why would it need to be in user land? If you call an update function with new data, the lib knows when an API call fails (how else would it call onFailure?) and it already has the ability to roll back changes (using patches). I'm not sure what exactly is the issue? If you really need something custom, you could always use pessimistic update and implement your own logic.

Chaining

I agree on the client parameter. I was thinking about it, but didn't include it in the initial example...
As for the example here, yes, it is a bad example because the requests are independent, but there are some other examples that would benefit from that:

client.from(User).chain(
  (client, users) => client.from(Todo).match({ owner: users.map(({ id }) => id).join(',') }), // Get todos owned by any of the fetched users
).fetchList(); // Get the paginated users list

JSON:API relationship

Yes, I guess so, but this would depend on the specific QueryBuilder implementation

[isBatak]

Why would it need to be in user land? If you call an update function with new data, the lib knows when an API call fails (how else would it call onFailure?) and it already has the ability to roll back changes (using patches). I'm not sure what exactly is the issue? If you really need something custom, you could always use pessimistic update and implement your own logic.

1. to cut down the scope and simplify things. We can do experiments in the user land and then move this logic to client, but not in the first phase.
2. better code splitting
3. colocating view logic with the View layer, if we bake-in optimistic logic in the client it will be included in every page/component whether it's needed or not and we can't leverage DCE because it's dynamic property.
4. We can maybe experiment with AbortSignal in the user land for cases when component is unmounted or out of viewport

[isBatak]

We also need to think about SSR mode:

const client = createClient({
  ssr: typeof window === 'undefined',
})

This way we can bypass storing data in the collection and just return raw responses from the API, and we don't have to create an entirely new instance of Datx Client for each request.

[DarkoKukovec]

Makes sense, but I wouldn't call this ssr because it might also have other use cases.

Edit - actually, why would you need that? The point is to create a new client with a new collection for each request.
My concern is that this adds a completely new flow of handling data and is basically a completely different approach.

[isBatak]

To be able to have one instance on server and client.
I have a feeling It's more convenient, because right now we need to create a hook that handles this behaviour.
I call it useSafeClient https://github.com/infinum/datx/blob/react/packages/react/src/hooks/useSafeClient.ts but it seems suboptimal.
It is tightly coupled with React and can't be applied to other frameworks.

What I would like to do is to move this logic inside client like this:

export const createClient = () => new Client({ 
  ssr: typeof window === 'undefined' 
});

const client = createClient();

function ExampleApp({ Component, pageProps }: AppProps) {
 // no need to hook into React lifecycle and create store
 
  return (
    <DatxProvider client={client}>
      <Component {...pageProps} />
    </DatxProvider>
  );
}

ultimately we can just skip Cache Normalization by not passing store prop, we talked about this before.

export const createClient = () => {
  if (typeof window === 'undefined') {
     return new Client({ 
        store: undefined, // or not setting this prop
     });
  } else {
    return new Client({ 
        store: new Collection(),
     });
  }
};

but if we move this logic inside client we could use module singleton pattern

export default new Client({ 
    ssr: typeof window === 'undefined',
    store: new Collection(),
 });

import client form './datx/client';

function ExampleApp({ Component, pageProps }: AppProps) {
  return (
    <DatxProvider client={client}>
      <Component {...pageProps} />
    </DatxProvider>
  );
}