feat: Queries, Queryable, and useQuery

[ntucker]

Motivation

• Reduce API footprint
  • Reduce bundle size
  • Easier to learn
  • Less code to write
• Writing getOptimisticResponse() and other concepts based on state are significantly cleaner
• eliminates the need to refer to endpoints or resources in endpoint arguments (which caused a lot of typing challenges)

Solution

• Remove Query and Index endpoints
• useCache() can take any Queryable schemas directly.
• Add schema.Query()
  • This only accepts Queryable schemas.
• Collection.query(queryFn) is shorthand for taking an existing collection and just adding the process (like Collection.push, returns a schema)

Mechanism

Schemas now have Args - this can be used to get possible args in useQuery()

Examples

class User extends Entity {
  id = '';
  username = '';

  pk() { return this.id;}
  static indexes = ['username'] as const;
}

Before

const UserIndex = new Index(User)

const bob = useCache(UserIndex, { username: 'bob' });

After

const bob = useQuery(User, { username: 'bob' });

Before

const getUserCount = new Query(
  new schema.All(User),
  (entries, { isAdmin } = { }) => {
    if (isAdmin !== undefined)
      return entries.filter(user => user.isAdmin === isAdmin).length;
    return entries.length;
  },
);

const userCount = useCache(getUserCount);
const adminCount = useCache(getUserCount, { isAdmin: true });

After

const getUserCount = new schema.Query(
  new schema.All(User),
  (entries, { isAdmin } = { }) => {
    if (isAdmin !== undefined)
      return entries.filter(user => user.isAdmin === isAdmin).length;
    return entries.length;
  },
);

const userCount = useQuery(getUserCount);
const adminCount = useQuery(getUserCount, { isAdmin: true });

Before

export const PostResource = createResource({
  path: '/posts/:id',
  schema: Post,
}).extend(Base => ({
  vote: new RestEndpoint({
    path: '/posts/:id/vote',
    method: 'POST',
    body: undefined,
    schema: Post,
    getOptimisticResponse(snapshot, { id }) {
      const { data } = snapshot.getResponse(Base.get, { id });
      if (!data) throw new AbortOptimistic();
      return {
        id,
        votes: data.votes + 1,
      };
    },
  }),
}));

After

export const PostResource = createResource({
  path: '/posts/:id',
  schema: Post,
}).extend('vote',
  {
    path: '/posts/:id/vote',
    method: 'POST',
    body: undefined,
    schema: Post,
    getOptimisticResponse(snapshot, { id }) {
      const post = snapshot.get(Post, { id });
      if (!post) throw new AbortOptimistic();
      return {
        id,
        votes: post.votes + 1,
      };
    },
  },
);

TODO

• Add controller.get and snapshot.get
• Add useQuery
• Add Query schema
• Handle Union inference needing extra arguments (useQuery should not use generics for args, but should accept schema's args, we need to do something about url using these extra args...)
• Remove queryEndpoint, Index
• Update docs to use snap.get() in getOptimisticResponse
• Docs: Schema table, add Query schema, remove Query and Index from endpoints
• docs: update README references
• docs: Add blog draft with changes

Followup

• infer -> buildKey?
• Infer caching
• codemod and link in release docs
• Future release:
  • ctrl.set()

Open Questions

• Should we get rid of AbortOptimistic and simply abort on any exception?
  • If so we could simply try to access data and if it doesn't exist, it would abort
  • If we lied about the types here to make types work then it wouldn't work well for middlewares that don't want to throw. We could change types just for snapshot but would probably be unexpected
  • Answer: No, the explicit handling makes it more readable; This will definitely silence errors that people can easily fix.

[changeset-bot]

🦋 Changeset detected

Latest commit: c8944cb

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 16 packages

Name	Type
@data-client/normalizr	Minor
@data-client/endpoint	Minor
@data-client/react	Minor
@data-client/core	Minor
@data-client/rest	Minor
@data-client/graphql	Minor
@data-client/redux	Minor
@data-client/test	Minor
@data-client/hooks	Patch
example-benchmark	Patch
normalizr-github-example	Patch
normalizr-redux-example	Patch
normalizr-relationships	Patch
@data-client/img	Minor
rdc-website	Patch
coinbase-lite	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
rest-hooks	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Jan 18, 2024 11:39am

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 98.70%. Comparing base (3e0e917) to head (c8944cb).

Additional details and impacted files

@@           Coverage Diff           @@
##           master    #2921   +/-   ##
=======================================
  Coverage   98.70%   98.70%           
=======================================
  Files         117      117           
  Lines        2081     2085    +4     
  Branches      418      417    -1     
=======================================
+ Hits         2054     2058    +4     
  Misses         16       16           
  Partials       11       11           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.