feat: Queries, Queryable, and useQuery

.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

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,
           );
         }

docs/core/api/Snapshot.md

@@ -18,6 +18,7 @@ allow safe and performant access to the denormalized data based on the current s
 
 ```ts
 interface Snapshot {
+  get(schema, ...args)​ => DenormalizeNullable<typeof schema> | undefined;
   getResponse(endpoint, ...args)​ => { data, expiryStatus, expiresAt };
   getError(endpoint, ...args)​ => ErrorTypes | undefined;
   fetchedAt: number;
@@ -37,6 +38,10 @@ Use [Controller.snapshot()](./Controller.md#snapshot) to construct a snapshot
 
 ## Members
 
+### get(schema, ...args) {#get}
+
+Looks up any [Queryable](./useQuery.md#queryable) [Schema](/rest/api/schema#schema-overview).
+
 ### getResponse(endpoint, ...args) {#getResponse}
 
 ```ts title="returns"
@@ -82,7 +87,6 @@ export enum ExpiryStatus {
 
 A number representing time when it expires. Compare to Date.now().
 
-
 ### getError(endpoint, ...args) {#getError}
 
 Gets the error, if any, for a given endpoint. Returns undefined for no errors.

docs/core/api/useCache.md

@@ -14,8 +14,8 @@ import { RestEndpoint } from '@data-client/rest';
 
 Data rendering without the fetch.
 
-General purpose store access can be useful when the data's existance is of interest (like if a user is authenticated),
-or general purpose store access like [Query](/rest/api/Query).
+Access any [Endpoint](/rest/api/Endpoint)'s response. If the response does not exist, returns
+`undefined`. This can be used to check for an `Endpoint's` existance like for authentication.
 
 `useCache()` is reactive to data [mutations](../getting-started/mutations.md); rerendering only when necessary.
 
@@ -147,75 +147,6 @@ function useCache<
 
 ## Examples
 
-### Query arbitrary Entities
-
-[Query](/rest/api/Query) provides programmatic access to the Reactive Data Client store.
-
-<HooksPlayground fixtures={[
-{
-endpoint: new RestEndpoint({path: '/users'}),
-args: [],
-response: [
-{ id: '123', name: 'Jim' },
-{ id: '456', name: 'Jane' },
-{ id: '777', name: 'Albatras', isAdmin: true },
-],
-delay: 150,
-},
-]} row>
-
-```ts title="UserResource" collapsed
-export class User extends Entity {
-  id = '';
-  name = '';
-  isAdmin = false;
-  pk() {
-    return this.id;
-  }
-  static key = 'User';
-}
-export const UserResource = createResource({
-  path: '/users/:id',
-  schema: User,
-});
-```
-
-```tsx title="UsersPage" {17}
-import { Query, schema } from '@data-client/rest';
-import { UserResource, User } from './UserResource';
-
-const sortedUsers = new Query(
-  new schema.All(User),
-  (entries, { asc } = { asc: false }) => {
-    const sorted = [...entries].sort((a, b) =>
-      a.name.localeCompare(b.name),
-    );
-    if (asc) return sorted;
-    return sorted.reverse();
-  },
-);
-
-function UsersPage() {
-  useFetch(UserResource.getList);
-  const users = useCache(sortedUsers, { asc: true });
-  if (!users) return <div>No users in cache yet</div>;
-  return (
-    <div>
-      {users.map(user => (
-        <div key={user.pk()}>{user.name}</div>
-      ))}
-    </div>
-  );
-}
-render(<UsersPage />);
-```
-
-</HooksPlayground>
-
-### Remaining Todo Query
-
-[Queries](/rest/api/Query) can also be used to compute aggregates
-
 <StackBlitz app="todo-app" file="src/resources/TodoResource.ts,src/pages/Home/TodoStats.tsx" />
 
 ### Github Navbar login/logout