feat: Queries, Queryable, and useQuery

.changeset/brave-rockets-bake.md

@@ -0,0 +1,36 @@
+---
+"@data-client/normalizr": minor
+"@data-client/endpoint": minor
+"@data-client/react": minor
+"@data-client/core": minor
+"@data-client/rest": minor
+"@data-client/graphql": minor
+---
+
+BREAKING: new AbortOptimistic() -> [snapshot.abort](https://dataclient/docs/api/Snapshot#abort)
+
+#### Before
+
+```ts
+getOptimisticResponse(snapshot, { id }) {
+  const { data } = snapshot.getResponse(Base.get, { id });
+  if (!data) throw new AbortOptimistic();
+  return {
+    id,
+    votes: data.votes + 1,
+  };
+}
+```
+
+#### After
+
+```ts
+getOptimisticResponse(snapshot, { id }) {
+  const { data } = snapshot.getResponse(Base.get, { id });
+  if (!data) throw snapshot.abort;
+  return {
+    id,
+    votes: data.votes + 1,
+  };
+}
+```

.changeset/fresh-rice-provide.md

@@ -0,0 +1,39 @@
+---
+"@data-client/endpoint": minor
+"@data-client/rest": minor
+"@data-client/graphql": minor
+---
+
+BREAKING: new Query -> [new schema.Query](https://dataclient.io/rest/api/Query)
+
+#### Before
+
+```jsx
+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
+
+```jsx
+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 });
+```

.changeset/mean-cougars-confess.md

@@ -0,0 +1,9 @@
+---
+"@data-client/react": patch
+"@data-client/core": patch
+---
+
+Improve controller.getResponse() type matching
+
+Uses function overloading to more precisely match argument
+expectations for fetchable Endpoints vs only keyable Endpoints.

.changeset/purple-pandas-confess.md

@@ -0,0 +1,43 @@
+---
+"@data-client/react": minor
+---
+
+Add [useQuery()](https://dataclient.io/docs/api/useQuery) to render [Querable Schemas](https://dataclient.io/docs/api/useQuery#queryable)
+
+```ts
+class User extends Entity {
+  username = '';
+  id = '';
+  groupId = '';
+  pk() {
+    return this.id;
+  }
+  static index = ['username' as const];
+}
+
+const bob = useQuery(User, { username: 'bob' });
+```
+
+```ts
+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 });
+```
+
+```ts
+const UserCollection = new schema.Collection([User], {
+  argsKey: (urlParams: { groupId?: string }) => ({
+    ...urlParams,
+  }),
+});
+
+const usersInGroup = useQuery(UserCollection, { groupId: '5' });
+```

.changeset/quick-flies-taste.md

@@ -0,0 +1,11 @@
+---
+"@data-client/normalizr": patch
+"@data-client/endpoint": patch
+"@data-client/react": patch
+"@data-client/redux": patch
+"@data-client/core": patch
+"@data-client/rest": patch
+"@data-client/test": patch
+---
+
+Update README

.changeset/sweet-coins-deliver.md

@@ -0,0 +1,54 @@
+---
+"@data-client/react": minor
+"@data-client/core": minor
+---
+
+Add [controller.get](https://dataclient.io/docs/api/Controller#get) / [snapshot.get](https://dataclient.io/docs/api/Snapshot#get) to directly read [Querable Schemas](https://dataclient.io/docs/api/useQuery#queryable)
+
+#### Before
+
+```tsx
+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
+
+```tsx
+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,
+      };
+    },
+  },
+);
+```

.changeset/thirty-ants-grin.md

@@ -0,0 +1,21 @@
+---
+"@data-client/endpoint": minor
+"@data-client/rest": minor
+"@data-client/graphql": minor
+---
+
+BREAKING: useCache(new Index(MyEntity)) -> useQuery(MyEntity)
+
+#### Before
+
+```jsx
+const UserIndex = new Index(User)
+
+const bob = useCache(UserIndex, { username: 'bob' });
+```
+
+#### After
+
+```jsx
+const bob = useQuery(User, { username: 'bob' });
+```

README.md

@@ -135,7 +135,7 @@ ctrl.fetch(ArticleResource.get, { id });
 ### [Programmatic queries](https://dataclient.io/rest/api/Query)
 
 ```tsx
-const queryTotalVotes = new Query(
+const queryTotalVotes = new schema.Query(
   new schema.All(Post),
   (posts, { userId } = {}) => {
     if (userId !== undefined)
@@ -144,8 +144,8 @@ const queryTotalVotes = new Query(
   },
 );
 
-const totalVotes = useCache(queryTotalVotes);
-const totalVotesForUser = useCache(queryTotalVotes, { userId });
+const totalVotes = useQuery(queryTotalVotes);
+const totalVotesForUser = useQuery(queryTotalVotes, { userId });
 ```
 
 ### [Powerful Middlewares](https://dataclient.io/docs/concepts/managers)
@@ -271,5 +271,6 @@ For the small price of 9kb gziped.    [🏁Get started now](https://da
   - [Values](https://dataclient.io/rest/api/Values)
   - [All](https://dataclient.io/rest/api/All)
   - [Collection](https://dataclient.io/rest/api/Collection)
+  - [Query](https://dataclient.io/rest/api/Query)
   - [Union](https://dataclient.io/rest/api/Union)
   - [Invalidate](https://dataclient.io/rest/api/Invalidate)

__tests__/new.ts

@@ -1,7 +1,6 @@
 import {
   schema,
   Endpoint,
-  Index,
   createResource,
   RestEndpoint,
   Schema,
@@ -188,6 +187,13 @@ export class Article extends Entity {
     author: User,
   };
 }
+
+export class ArticleWithSlug extends Article {
+  readonly slug: string = '';
+
+  static indexes = ['slug'] as const;
+}
+
 class ArticleData {
   readonly id: number | undefined = undefined;
   readonly title: string = '';
@@ -265,6 +271,9 @@ function createArticleResource<O extends ArticleGenerics>({
   return resource as any;
 }
 export const ArticleResource = createArticleResource({ schema: Article });
+export const ArticleSlugResource = createArticleResource({
+  schema: ArticleWithSlug,
+});
 
 export const AuthContext = createContext('');
 
@@ -518,13 +527,10 @@ export const CoolerArticleDetail = new Endpoint(
 export class IndexedUser extends User {
   static readonly indexes = ['username'];
 }
-export const IndexedUserResource = {
-  ...createResource({
-    path: 'http\\://test.com/user/:id',
-    schema: IndexedUser,
-  }),
-  getIndex: new Index(IndexedUser),
-};
+export const IndexedUserResource = createResource({
+  path: 'http\\://test.com/user/:id',
+  schema: IndexedUser,
+});
 
 class InvalidIfStaleEndpoint<
   O extends RestGenerics = any,

docs/core/api/Controller.md

@@ -27,6 +27,7 @@ class Controller {
   subscribe(endpoint, ...args): Promise<void>;
   unsubscribe(endpoint, ...args): Promise<void>;
   /*************** Data Access ***************/
+  get(queryable, ...args, state): Denormalized<typeof queryable>;
   getResponse(endpoint, ...args, state): { data; expiryStatus; expiresAt };
   getError(endpoint, ...args, state): ErrorTypes | undefined;
   snapshot(state: State<unknown>, fetchedAt?: number): SnapshotInterface;
@@ -124,7 +125,10 @@ When using schemas, the denormalized value is returned
 // highlight-next-line
 import { useController } from '@data-client/react';
 
-const post = await controller.fetch(PostResource.getList.push, createPayload);
+const post = await controller.fetch(
+  PostResource.getList.push,
+  createPayload,
+);
 post.title;
 post.pk();
 ```
@@ -364,7 +368,11 @@ useEffect(() => {
   const websocket = new Websocket(url);
 
   websocket.onmessage = event =>
-    ctrl.setResponse(EndpointLookup[event.endpoint], ...event.args, event.data);
+    ctrl.setResponse(
+      EndpointLookup[event.endpoint],
+      ...event.args,
+      event.data,
+    );
 
   return () => websocket.close();
 });
@@ -412,6 +420,36 @@ decrement the subscription and if the count reaches 0, more updates won't be rec
 
 [useSubscription](./useSubscription.md) and [useLive](./useLive.md) call this on unmount.
 
+## get(schema, ...args, state) {#get}
+
+Looks up any [Queryable](./useQuery.md#queryable) [Schema](/rest/api/schema#schema-overview) in `state`.
+
+### Example
+
+This is used in [useQuery](./useQuery.md) and can be used in
+[Managers](./Manager.md) to safely access the store.
+
+```tsx title="useQuery.ts"
+import {
+  useController,
+  useCacheState,
+  type Queryable,
+  type SchemaArgs,
+  type DenormalizeNullable,
+} from '@data-client/core';
+
+/** Oversimplified useQuery */
+function useQuery<S extends Queryable>(
+  schema: S,
+  ...args: SchemaArgs<S>
+): DenormalizeNullable<S> | undefined {
+  const state = useCacheState();
+  const controller = useController();
+
+  return controller.get(schema, ...args, state);
+}
+```
+
 ## getResponse(endpoint, ...args, state) {#getResponse}
 
 ```ts title="returns"
@@ -487,15 +525,15 @@ import type { EndpointInterface } from '@data-client/endpoint';
 export default class MyManager implements Manager {
   protected declare middleware: Middleware;
   constructor() {
-    this.middleware = ({ controller, getState }) => {
+    this.middleware = controller => {
       return next => async action => {
         if (action.type === actionTypes.FETCH_TYPE) {
           console.log('The existing response of the requested fetch');
           console.log(
             controller.getResponse(
               action.endpoint,
               ...(action.meta.args as Parameters<typeof action.endpoint>),
-              getState(),
+              controller.getState(),
             ).data,
           );
         }