@data-client/core 0.1.0 → 0.2.0

package/src/controller/Controller.ts

@@ -1,15 +1,97 @@
-import type { EndpointInterface } from '@data-client/normalizr';
+import type {
+  ErrorTypes,
+  SnapshotInterface,
+  DenormalizeCache,
+  Schema,
+  Denormalize,
+} from '@data-client/normalizr';
+import {
+  WeakEntityMap,
+  ExpiryStatus,
+  EndpointInterface,
+  FetchFunction,
+  ResolveType,
+  DenormalizeNullable,
+  Path,
+  denormalizeCached,
+  isEntity,
+  denormalize,
+} from '@data-client/normalizr';
+import { inferResults, validateInference } from '@data-client/normalizr';
 
-import BaseController, {
-  CompatibleDispatch,
-  GenericDispatch,
-} from './BaseController.js';
 import createFetch from './createFetch.js';
+import createInvalidate from './createInvalidate.js';
+import createInvalidateAll from './createInvalidateAll.js';
+import createReset from './createReset.js';
+import createSet from './createSet.js';
+import {
+  createUnsubscription,
+  createSubscription,
+} from './createSubscription.js';
 import type { EndpointUpdateFunction } from './types.js';
+import { initialState } from '../state/reducer/createReducer.js';
+import selectMeta from '../state/selectMeta.js';
+import type { ActionTypes, State } from '../types.js';
 
+export type GenericDispatch = (value: any) => Promise<void>;
+export type DataClientDispatch = (value: ActionTypes) => Promise<void>;
+
+interface ConstructorProps<D extends GenericDispatch = DataClientDispatch> {
+  dispatch?: D;
+  getState?: () => State<unknown>;
+  globalCache?: DenormalizeCache;
+}
+
+const unsetDispatch = (action: unknown): Promise<void> => {
+  throw new Error(
+    `Dispatching while constructing your middleware is not allowed. ` +
+      `Other middleware would not be applied to this dispatch.`,
+  );
+};
+const unsetState = (): State<unknown> => {
+  // This is only the value until it is set by the CacheProvider
+  /* istanbul ignore next */
+  return initialState;
+};
+
+/**
+ * Imperative control of Rest Hooks store
+ * @see https://resthooks.io/docs/api/Controller
+ */
 export default class Controller<
-  D extends GenericDispatch = CompatibleDispatch,
-> extends BaseController<D> {
+  D extends GenericDispatch = DataClientDispatch,
+> {
+  /**
+   * Dispatches an action to Rest Hooks reducer.
+   *
+   * @see https://resthooks.io/docs/api/Controller#dispatch
+   */
+  declare readonly dispatch: D;
+  /**
+   * Gets the latest state snapshot that is fully committed.
+   *
+   * This can be useful for imperative use-cases like event handlers.
+   * This should *not* be used to render; instead useSuspense() or useCache()
+   * @see https://resthooks.io/docs/api/Controller#getState
+   */
+  declare readonly getState: () => State<unknown>;
+  declare readonly globalCache: DenormalizeCache;
+
+  constructor({
+    dispatch = unsetDispatch as any,
+    getState = unsetState,
+    globalCache = {
+      entities: {},
+      results: {},
+    },
+  }: ConstructorProps<D> = {}) {
+    this.dispatch = dispatch;
+    this.getState = getState;
+    this.globalCache = globalCache;
+  }
+
+  /*************** Action Dispatchers ***************/
+
   /**
    * Fetches the endpoint with given args, updating the Rest Hooks cache with the response or error upon completion.
    * @see https://resthooks.io/docs/api/Controller#fetch
@@ -19,14 +101,413 @@ export default class Controller<
   >(
     endpoint: E,
     ...args: readonly [...Parameters<E>]
-  ): ReturnType<E> => {
+  ): E['schema'] extends undefined | null
+    ? ReturnType<E>
+    : Promise<Denormalize<E['schema']>> => {
     const action = createFetch(endpoint, {
       args,
     });
     this.dispatch(action);
 
-    return action.meta.promise as ReturnType<E>;
+    if (endpoint.schema) {
+      return action.meta.promise.then(input =>
+        denormalize(input, endpoint.schema, {}, args),
+      ) as any;
+    }
+    return action.meta.promise as any;
+  };
+
+  /**
+   * Forces refetching and suspense on useSuspense with the same Endpoint and parameters.
+   * @see https://resthooks.io/docs/api/Controller#invalidate
+   */
+  invalidate = <E extends EndpointInterface>(
+    endpoint: E,
+    ...args: readonly [...Parameters<E>] | readonly [null]
+  ): Promise<void> =>
+    args[0] !== null
+      ? this.dispatch(
+          createInvalidate(endpoint, {
+            args: args as readonly [...Parameters<E>],
+          }),
+        )
+      : Promise.resolve();
+
+  /**
+   * Forces refetching and suspense on useSuspense on all matching endpoint result keys.
+   * @see https://resthooks.io/docs/api/Controller#invalidateAll
+   */
+  invalidateAll = (options: { testKey: (key: string) => boolean }) =>
+    this.dispatch(createInvalidateAll((key: string) => options.testKey(key)));
+
+  /**
+   * Resets the entire Rest Hooks cache. All inflight requests will not resolve.
+   * @see https://resthooks.io/docs/api/Controller#resetEntireStore
+   */
+  resetEntireStore = (): Promise<void> => this.dispatch(createReset());
+
+  /**
+   * Stores response in cache for given Endpoint and args.
+   * @see https://resthooks.io/docs/api/Controller#set
+   */
+  setResponse = <
+    E extends EndpointInterface & {
+      update?: EndpointUpdateFunction<E>;
+    },
+  >(
+    endpoint: E,
+    ...rest: readonly [...Parameters<E>, any]
+  ): Promise<void> => {
+    const response: ResolveType<E> = rest[rest.length - 1];
+    const action = createSet(endpoint, {
+      args: rest.slice(0, rest.length - 1) as Parameters<E>,
+      response,
+    });
+    return this.dispatch(action);
+  };
+
+  /**
+   * @deprecated use https://resthooks.io/docs/api/Controller#setResponse instead
+   */
+  /* istanbul ignore next */ receive = <
+    E extends EndpointInterface & {
+      update?: EndpointUpdateFunction<E>;
+    },
+  >(
+    endpoint: E,
+    ...rest: readonly [...Parameters<E>, any]
+  ): Promise<void> => {
+    /* istanbul ignore next */
+    return this.setResponse(endpoint, ...rest);
+  };
+
+  /**
+   * Stores the result of Endpoint and args as the error provided.
+   * @see https://resthooks.io/docs/api/Controller#setError
+   */
+  setError = <
+    E extends EndpointInterface & {
+      update?: EndpointUpdateFunction<E>;
+    },
+  >(
+    endpoint: E,
+    ...rest: readonly [...Parameters<E>, Error]
+  ): Promise<void> => {
+    const response: Error = rest[rest.length - 1];
+    const action = createSet(endpoint, {
+      args: rest.slice(0, rest.length - 1) as Parameters<E>,
+      response,
+      error: true,
+    });
+    return this.dispatch(action);
+  };
+
+  /**
+   * Another name for setError
+   * @deprecated use https://resthooks.io/docs/api/Controller#setError instead
+   */
+  /* istanbul ignore next */ receiveError = <
+    E extends EndpointInterface & {
+      update?: EndpointUpdateFunction<E>;
+    },
+  >(
+    endpoint: E,
+    ...rest: readonly [...Parameters<E>, Error]
+  ): Promise<void> => {
+    /* istanbul ignore next */
+    return this.setError(endpoint, ...rest);
+  };
+
+  /**
+   * Resolves an inflight fetch. `fetchedAt` should `fetch`'s `createdAt`
+   * @see https://resthooks.io/docs/api/Controller#resolve
+   */
+  resolve = <
+    E extends EndpointInterface & {
+      update?: EndpointUpdateFunction<E>;
+    },
+  >(
+    endpoint: E,
+    meta:
+      | {
+          args: readonly [...Parameters<E>];
+          response: Error;
+          fetchedAt: number;
+          error: true;
+        }
+      | {
+          args: readonly [...Parameters<E>];
+          response: any;
+          fetchedAt: number;
+          error?: false;
+        },
+  ): Promise<void> => {
+    return this.dispatch(createSet(endpoint, meta as any));
+  };
+
+  /**
+   * Marks a new subscription to a given Endpoint.
+   * @see https://resthooks.io/docs/api/Controller#subscribe
+   */
+  subscribe = <
+    E extends EndpointInterface<
+      FetchFunction,
+      Schema | undefined,
+      undefined | false
+    >,
+  >(
+    endpoint: E,
+    ...args: readonly [...Parameters<E>] | readonly [null]
+  ): Promise<void> =>
+    args[0] !== null
+      ? this.dispatch(
+          createSubscription(endpoint, {
+            args: args as readonly [...Parameters<E>],
+          }),
+        )
+      : Promise.resolve();
+
+  /**
+   * Marks completion of subscription to a given Endpoint.
+   * @see https://resthooks.io/docs/api/Controller#unsubscribe
+   */
+  unsubscribe = <
+    E extends EndpointInterface<
+      FetchFunction,
+      Schema | undefined,
+      undefined | false
+    >,
+  >(
+    endpoint: E,
+    ...args: readonly [...Parameters<E>] | readonly [null]
+  ): Promise<void> =>
+    args[0] !== null
+      ? this.dispatch(
+          createUnsubscription(endpoint, {
+            args: args as readonly [...Parameters<E>],
+          }),
+        )
+      : Promise.resolve();
+
+  /*************** More ***************/
+
+  /* TODO:
+  abort = <E extends EndpointInterface>(
+    endpoint: E,
+    ...args: readonly [...Parameters<E>]
+  ): Promise<void>
+  */
+
+  /**
+   * Gets a snapshot (https://resthooks.io/docs/api/Snapshot)
+   * @see https://resthooks.io/docs/api/Controller#snapshot
+   */
+  snapshot = (state: State<unknown>, fetchedAt?: number): SnapshotInterface => {
+    return new Snapshot(this, state, fetchedAt);
+  };
+
+  /**
+   * Gets the error, if any, for a given endpoint. Returns undefined for no errors.
+   * @see https://resthooks.io/docs/api/Controller#getError
+   */
+  getError = <
+    E extends Pick<EndpointInterface, 'key'>,
+    Args extends readonly [...Parameters<E['key']>] | readonly [null],
+  >(
+    endpoint: E,
+    ...rest: [...Args, State<unknown>]
+  ): ErrorTypes | undefined => {
+    if (rest[0] === null) return;
+    const state = rest[rest.length - 1] as State<unknown>;
+    // this is typescript generics breaking
+    const args: any = rest.slice(0, rest.length - 1) as Parameters<E['key']>;
+    const key = endpoint.key(...args);
+
+    const meta = selectMeta(state, key);
+    const results = state.results[key];
+
+    if (results !== undefined && meta?.errorPolicy === 'soft') return;
+
+    return meta?.error as any;
   };
+
+  /**
+   * Gets the (globally referentially stable) response for a given endpoint/args pair from state given.
+   * @see https://resthooks.io/docs/api/Controller#getResponse
+   */
+  getResponse = <
+    E extends Pick<EndpointInterface, 'key' | 'schema' | 'invalidIfStale'>,
+    Args extends readonly [...Parameters<E['key']>] | readonly [null],
+  >(
+    endpoint: E,
+    ...rest: [...Args, State<unknown>]
+  ): {
+    data: DenormalizeNullable<E['schema']>;
+    expiryStatus: ExpiryStatus;
+    expiresAt: number;
+  } => {
+    const state = rest[rest.length - 1] as State<unknown>;
+    // this is typescript generics breaking
+    const args: any = rest.slice(0, rest.length - 1) as Parameters<E['key']>;
+    const isActive = args.length !== 1 || args[0] !== null;
+    const key = isActive ? endpoint.key(...args) : '';
+    const cacheResults = isActive ? state.results[key] : undefined;
+    const schema = endpoint.schema;
+    const meta = selectMeta(state, key);
+    let expiresAt = meta?.expiresAt;
+
+    let invalidResults = false;
+    let results;
+    if (cacheResults === undefined && endpoint.schema !== undefined) {
+      results = inferResults(
+        endpoint.schema,
+        args,
+        state.indexes,
+        state.entities,
+      );
+      invalidResults = !validateInference(results);
+      if (!expiresAt && invalidResults) expiresAt = 1;
+    } else {
+      results = cacheResults;
+    }
+
+    if (!isActive) {
+      return {
+        data: results as any,
+        expiryStatus: ExpiryStatus.Valid,
+        expiresAt: Infinity,
+      };
+    }
+
+    if (!endpoint.schema || !schemaHasEntity(endpoint.schema)) {
+      return {
+        data: results,
+        expiryStatus: meta?.invalidated
+          ? ExpiryStatus.Invalid
+          : cacheResults && !endpoint.invalidIfStale
+          ? ExpiryStatus.Valid
+          : ExpiryStatus.InvalidIfStale,
+        expiresAt: expiresAt || 0,
+      } as {
+        data: DenormalizeNullable<E['schema']>;
+        expiryStatus: ExpiryStatus;
+        expiresAt: number;
+      };
+    }
+
+    if (!this.globalCache.results[key])
+      this.globalCache.results[key] = new WeakEntityMap();
+
+    // second argument is false if any entities are missing
+    // eslint-disable-next-line prefer-const
+    const { data, paths } = denormalizeCached(
+      results,
+      schema,
+      state.entities,
+      this.globalCache.entities,
+      this.globalCache.results[key],
+      args,
+    ) as { data: DenormalizeNullable<E['schema']>; paths: Path[] };
+    const invalidDenormalize = typeof data === 'symbol';
+
+    // fallback to entity expiry time
+    if (!expiresAt) {
+      expiresAt = entityExpiresAt(paths, state.entityMeta);
+    }
+
+    // https://resthooks.io/docs/concepts/expiry-policy#expiry-status
+    // we don't track the difference between stale or fresh because that is tied to triggering
+    // conditions
+    const expiryStatus =
+      meta?.invalidated || (invalidDenormalize && !meta?.error)
+        ? ExpiryStatus.Invalid
+        : invalidDenormalize || endpoint.invalidIfStale || invalidResults
+        ? ExpiryStatus.InvalidIfStale
+        : ExpiryStatus.Valid;
+
+    return { data, expiryStatus, expiresAt };
+  };
+}
+
+// benchmark: https://www.measurethat.net/Benchmarks/Show/24691/0/min-reducer-vs-imperative-with-paths
+// earliest expiry dictates age
+function entityExpiresAt(
+  paths: Path[],
+  entityMeta: {
+    readonly [entityKey: string]: {
+      readonly [pk: string]: {
+        readonly date: number;
+        readonly expiresAt: number;
+        readonly fetchedAt: number; // This is only the value until it is set by the CacheProvider
+      };
+    };
+  },
+) {
+  let expiresAt = Infinity;
+  for (const { pk, key } of paths) {
+    const entityExpiry = entityMeta[key]?.[pk]?.expiresAt;
+    // expiresAt will always resolve to false with any comparison
+    if (entityExpiry < expiresAt) expiresAt = entityExpiry;
+  }
+  return expiresAt;
 }
 
-export * from './BaseController.js';
+/** Determine whether the schema has any entities.
+ *
+ * Without entities, denormalization is not needed, and results should not be inferred.
+ */
+function schemaHasEntity(schema: Schema): boolean {
+  if (isEntity(schema)) return true;
+  if (Array.isArray(schema))
+    return schema.length !== 0 && schemaHasEntity(schema[0]);
+  if (schema && (typeof schema === 'object' || typeof schema === 'function')) {
+    const nestedSchema =
+      'schema' in schema ? (schema.schema as Record<string, Schema>) : schema;
+    if (typeof nestedSchema === 'function') {
+      return schemaHasEntity(nestedSchema);
+    }
+    return Object.values(nestedSchema).some(x => schemaHasEntity(x));
+  }
+  return false;
+}
+
+export type { ErrorTypes };
+
+class Snapshot<T = unknown> implements SnapshotInterface {
+  private state: State<T>;
+  private controller: Controller;
+  readonly fetchedAt: number;
+
+  constructor(controller: Controller, state: State<T>, fetchedAt = 0) {
+    this.state = state;
+    this.controller = controller;
+    this.fetchedAt = fetchedAt;
+  }
+
+  /*************** Data Access ***************/
+  /** @see https://resthooks.io/docs/api/Snapshot#getResponse */
+  getResponse = <
+    E extends Pick<EndpointInterface, 'key' | 'schema' | 'invalidIfStale'>,
+    Args extends readonly [...Parameters<E['key']>],
+  >(
+    endpoint: E,
+    ...args: Args
+  ): {
+    data: DenormalizeNullable<E['schema']>;
+    expiryStatus: ExpiryStatus;
+    expiresAt: number;
+  } => {
+    return this.controller.getResponse(endpoint, ...args, this.state);
+  };
+
+  /** @see https://resthooks.io/docs/api/Snapshot#getError */
+  getError = <
+    E extends Pick<EndpointInterface, 'key'>,
+    Args extends readonly [...Parameters<E['key']>],
+  >(
+    endpoint: E,
+    ...args: Args
+  ): ErrorTypes | undefined => {
+    return this.controller.getError(endpoint, ...args, this.state);
+  };
+}

package/src/controller/createFetch.ts

@@ -2,10 +2,7 @@ import type { EndpointInterface } from '@data-client/normalizr';
 
 import { EndpointUpdateFunction } from './types.js';
 import { FETCH_TYPE } from '../actionTypes.js';
-import type {
-  CompatibleFetchAction,
-  CompatibleFetchMeta,
-} from '../compatibleActions.js';
+import type { FetchAction, FetchMeta } from '../types.js';
 
 /**
  * Requesting a fetch to begin
@@ -15,36 +12,24 @@ export default function createFetch<
 >(
   endpoint: E,
   { args }: { args: readonly [...Parameters<E>] },
-): CompatibleFetchAction<E> {
+): FetchAction<E> {
   const key = endpoint.key(...args);
   let resolve: (value?: any | PromiseLike<any>) => void = 0 as any;
   let reject: (reason?: any) => void = 0 as any;
   const promise = new Promise<any>((a, b) => {
     [resolve, reject] = [a, b];
   });
-  const meta: CompatibleFetchMeta = {
-    schema: endpoint.schema,
-    type: endpoint.sideEffect ? ('mutate' as const) : ('read' as const),
+  const meta: FetchMeta = {
     args,
     key,
     throttle: !endpoint.sideEffect,
-    options: endpoint,
     resolve,
     reject,
     promise,
     createdAt: Date.now(),
+    nm: false,
   };
 
-  if (endpoint.update) {
-    meta.update = endpoint.update;
-  }
-
-  // TODO: Remove once EOL on this deprecated piece
-  /* istanbul ignore if */
-  if (endpoint.optimisticUpdate) {
-    meta.optimisticResponse = endpoint.optimisticUpdate(...args);
-  }
-
   return {
     type: FETCH_TYPE,
     payload: () => endpoint(...args) as any,

package/src/controller/createInvalidate.ts

@@ -1,7 +1,7 @@
 import type { EndpointInterface } from '@data-client/normalizr';
 
 import { INVALIDATE_TYPE } from '../actionTypes.js';
-import type { InvalidateAction } from '../newActions.js';
+import type { InvalidateAction } from '../types.js';
 
 export default function createInvalidate<E extends EndpointInterface>(
   endpoint: E,

package/src/controller/createInvalidateAll.ts

@@ -1,5 +1,5 @@
 import { INVALIDATEALL_TYPE } from '../actionTypes.js';
-import type { InvalidateAllAction } from '../newActions.js';
+import type { InvalidateAllAction } from '../types.js';
 
 export default function createInvalidateAll(
   testKey: (key: string) => boolean,

package/src/controller/createOptimistic.ts

@@ -1,8 +1,8 @@
 import type { EndpointInterface } from '@data-client/normalizr';
 
-import { EndpointUpdateFunction } from './types.js';
+import type { EndpointUpdateFunction } from './types.js';
 import { OPTIMISTIC_TYPE } from '../actionTypes.js';
-import { OptimisticAction } from '../newActions.js';
+import type { OptimisticAction } from '../types.js';
 
 export default function createOptimistic<
   E extends EndpointInterface & {
@@ -24,19 +24,13 @@ export default function createOptimistic<
     throw new Error('Negative expiry length are not allowed.');
   }
   const now = Date.now();
-  // TODO: Use correct type once we no longer need backcompat
-  const meta: any = {
+  const meta: OptimisticAction['meta'] = {
     args,
     fetchedAt,
     date: now,
     expiresAt: now + expiryLength,
-    // For legacy support; TODO: remove
-    schema: endpoint.schema,
     key: endpoint.key(...args),
   };
-  // For legacy support; TODO: remove
-  if (endpoint.update) meta.update = endpoint.update;
-  if (endpoint.errorPolicy) meta.errorPolicy = endpoint.errorPolicy;
 
   const action: OptimisticAction<E> = {
     type: OPTIMISTIC_TYPE,

package/src/controller/createReset.ts

@@ -1,5 +1,5 @@
 import { RESET_TYPE } from '../actionTypes.js';
-import type { ResetAction } from '../newActions.js';
+import type { ResetAction } from '../types.js';
 
 export default function createReset(): ResetAction {
   return {

package/src/controller/{createReceive.ts → createSet.ts}

@@ -2,12 +2,9 @@ import type { EndpointInterface, ResolveType } from '@data-client/normalizr';
 
 import { EndpointUpdateFunction } from './types.js';
 import { SET_TYPE } from '../actionTypes.js';
-import type {
-  CompatibleReceiveAction,
-  CompatibleReceiveMeta,
-} from '../compatibleActions.js';
+import type { SetAction, SetMeta } from '../types.js';
 
-export default function createReceive<
+export default function createSet<
   E extends EndpointInterface & {
     update?: EndpointUpdateFunction<E>;
   },
@@ -19,9 +16,9 @@ export default function createReceive<
     fetchedAt?: number;
     error: true;
   },
-): CompatibleReceiveAction<E>;
+): SetAction<E>;
 
-export default function createReceive<
+export default function createSet<
   E extends EndpointInterface & {
     update?: EndpointUpdateFunction<E>;
   },
@@ -33,9 +30,9 @@ export default function createReceive<
     fetchedAt?: number;
     error?: false;
   },
-): CompatibleReceiveAction<E>;
+): SetAction<E>;
 
-export default function createReceive<
+export default function createSet<
   E extends EndpointInterface & {
     update?: EndpointUpdateFunction<E>;
   },
@@ -52,7 +49,7 @@ export default function createReceive<
     fetchedAt?: number;
     error?: boolean;
   },
-): CompatibleReceiveAction<E> {
+): SetAction<E> {
   const expiryLength: number = error
     ? endpoint.errorExpiryLength ?? 1000
     : endpoint.dataExpiryLength ?? 60000;
@@ -61,20 +58,15 @@ export default function createReceive<
     throw new Error('Negative expiry length are not allowed.');
   }
   const now = Date.now();
-  const meta: CompatibleReceiveMeta = {
+  const meta: SetMeta = {
     args,
     fetchedAt: fetchedAt ?? now,
     date: now,
     expiresAt: now + expiryLength,
-    // For legacy support; TODO: remove
-    schema: endpoint.schema,
     key: endpoint.key(...args),
   };
-  // For legacy support; TODO: remove
-  if (endpoint.update) meta.update = endpoint.update;
-  if (endpoint.errorPolicy) meta.errorPolicy = endpoint.errorPolicy;
 
-  const action: CompatibleReceiveAction<E> = {
+  const action: SetAction<E> = {
     type: SET_TYPE,
     payload: response,
     endpoint: endpoint,