@data-client/core 0.1.0

package/src/fsa.ts

@@ -0,0 +1,99 @@
+import {
+  ErrorFluxStandardActionWithPayloadAndMeta,
+  ErrorFluxStandardActionWithPayload,
+  FSA,
+} from 'flux-standard-action';
+
+export type ErrorableFSAWithPayloadAndMeta<
+  Type extends string = string,
+  Payload = undefined,
+  Meta = undefined,
+  CustomError extends Error = Error,
+> =
+  | ErrorFluxStandardActionWithPayloadAndMeta<Type, CustomError, Meta>
+  | NoErrorFluxStandardActionWithPayloadAndMeta<Type, Payload, Meta>;
+
+export type ErrorableFSAWithMeta<
+  Type extends string = string,
+  Payload = undefined,
+  Meta = undefined,
+  CustomError extends Error = Error,
+> =
+  | ErrorFluxStandardActionWithPayloadAndMeta<Type, CustomError, Meta>
+  | NoErrorFluxStandardActionWithMeta<Type, Payload, Meta>;
+
+export type ErrorableFSAWithPayload<
+  Type extends string = string,
+  Payload = undefined,
+  Meta = undefined,
+  CustomError extends Error = Error,
+> =
+  | ErrorFluxStandardActionWithPayload<Type, CustomError, Meta>
+  | NoErrorFluxStandardActionWithPayload<Type, Payload, Meta>;
+
+export interface NoErrorFluxStandardAction<
+  Type extends string = string,
+  Payload = undefined,
+  Meta = undefined,
+> extends FSA<Type, Payload, Meta> {
+  error?: false;
+}
+
+/**
+ * A Flux Standard action with a required payload property.
+ */
+export interface NoErrorFluxStandardActionWithPayload<
+  Type extends string = string,
+  Payload = undefined,
+  Meta = undefined,
+> extends NoErrorFluxStandardAction<Type, Payload, Meta> {
+  /**
+   * The required `payload` property MAY be any type of value.
+   * It represents the payload of the action.
+   * Any information about the action that is not the type or status of the action should be part of the `payload` field.
+   * By convention, if `error` is `true`, the `payload` SHOULD be an error object.
+   * This is akin to rejecting a promise with an error object.
+   */
+  payload: Payload;
+}
+
+/**
+ * A Flux Standard action with a required metadata property.
+ */
+export interface NoErrorFluxStandardActionWithMeta<
+  Type extends string = string,
+  Payload = undefined,
+  Meta = undefined,
+> extends NoErrorFluxStandardAction<Type, Payload, Meta> {
+  /**
+   * The required `meta` property MAY be any type of value.
+   * It is intended for any extra information that is not part of the payload.
+   */
+  meta: Meta;
+}
+/**
+ * A Flux Standard action with required payload and metadata properties.
+ */
+export type NoErrorFluxStandardActionWithPayloadAndMeta<
+  Type extends string = string,
+  Payload = undefined,
+  Meta = undefined,
+> = NoErrorFluxStandardActionWithPayload<Type, Payload, Meta> &
+  NoErrorFluxStandardActionWithMeta<Type, Payload, Meta>;
+
+/**
+ * A Flux Standard action with inferred requirements for the payload and metadata properties.
+ * The `payload` and `meta` properties will be required if the corresponding type argument
+ * if not the `undefined` type.
+ */
+export type NoErrorFluxStandardActionAuto<
+  Type extends string = string,
+  Payload = undefined,
+  Meta = undefined,
+> = Payload extends undefined
+  ? Meta extends undefined
+    ? NoErrorFluxStandardAction<Type, Payload, Meta>
+    : NoErrorFluxStandardActionWithMeta<Type, Payload, Meta>
+  : Meta extends undefined
+  ? NoErrorFluxStandardActionWithPayload<Type, Payload, Meta>
+  : NoErrorFluxStandardActionWithPayloadAndMeta<Type, Payload, Meta>;

package/src/index.ts

@@ -0,0 +1,61 @@
+Object.hasOwn =
+  Object.hasOwn ||
+  /* istanbul ignore next */ function hasOwn(it, key) {
+    return Object.prototype.hasOwnProperty.call(it, key);
+  };
+
+export * as __INTERNAL__ from './internal.js';
+export type {
+  NetworkError,
+  UnknownError,
+  ErrorTypes,
+  Schema,
+  EndpointInterface,
+  EntityInterface,
+  ResolveType,
+  DenormalizeCache,
+  DenormalizeNullable,
+  Denormalize,
+  Normalize,
+  NormalizeNullable,
+  FetchFunction,
+  EndpointExtraOptions,
+} from '@data-client/normalizr';
+export { ExpiryStatus } from '@data-client/normalizr';
+export {
+  default as NetworkManager,
+  ResetError,
+} from './manager/NetworkManager.js';
+export {
+  default as createReducer,
+  initialState,
+} from './state/reducer/createReducer.js';
+export { default as reducer } from './state/reducerInstance.js';
+export { default as applyManager } from './manager/applyManager.js';
+
+export { default as Controller } from './controller/Controller.js';
+export type {
+  CompatibleDispatch,
+  GenericDispatch,
+} from './controller/Controller.js';
+export { default as createFetch } from './controller/createFetch.js';
+export { default as createReceive } from './controller/createReceive.js';
+
+export * from './controller/types.js';
+export * as legacyActions from './state/legacy-actions/index.js';
+export * as actionTypes from './actionTypes.js';
+/* istanbul ignore next */
+export * from './types.js';
+export type {
+  FetchShape,
+  ReadShape,
+  MutateShape,
+  DeleteShape,
+} from './endpoint/shapes.js';
+export type {
+  SetShapeParams,
+  ParamsFromShape,
+  BodyFromShape,
+  ReturnFromShape,
+} from './endpoint/types.js';
+export * from './manager/index.js';

package/src/internal.ts

@@ -0,0 +1,3 @@
+export { inferResults, DELETED } from '@data-client/normalizr';
+export { default as RIC } from './state/RIC.js';
+export { initialState } from './state/reducer/createReducer.js';

package/src/legacyActions.ts

@@ -0,0 +1,163 @@
+import type {
+  UpdateFunction,
+  Schema,
+  EndpointExtraOptions,
+  EndpointInterface,
+} from '@data-client/normalizr';
+import { FSAWithPayloadAndMeta, FSAWithMeta } from 'flux-standard-action';
+
+import {
+  RECEIVE_TYPE,
+  RESET_TYPE,
+  FETCH_TYPE,
+  SUBSCRIBE_TYPE,
+  UNSUBSCRIBE_TYPE,
+  INVALIDATE_TYPE,
+  GC_TYPE,
+  OPTIMISTIC_TYPE,
+} from './actionTypes.js';
+import type { EndpointUpdateFunction } from './controller/types.js';
+import { FetchShape } from './endpoint/index.js';
+import { ErrorableFSAWithPayloadAndMeta } from './fsa.js';
+
+export interface ReceiveMeta<S extends Schema | undefined> {
+  schema?: S;
+  key: string;
+  args?: readonly any[];
+  updaters?: Record<string, UpdateFunction<S, any>>;
+  update?: (result: any, ...args: any) => Record<string, (...args: any) => any>;
+  fetchedAt?: number;
+  date: number;
+  expiresAt: number;
+  errorPolicy?: (error: any) => 'hard' | 'soft' | undefined;
+}
+
+export type ReceiveAction<
+  Payload extends object | string | number | null =
+    | object
+    | string
+    | number
+    | null,
+  S extends Schema | undefined = any,
+> = ErrorableFSAWithPayloadAndMeta<
+  typeof RECEIVE_TYPE,
+  Payload,
+  ReceiveMeta<S>
+>;
+
+export type OptimisticAction<
+  E extends EndpointInterface & {
+    update?: EndpointUpdateFunction<E>;
+  } = EndpointInterface & {
+    update?: EndpointUpdateFunction<EndpointInterface>;
+  },
+> = {
+  type: typeof OPTIMISTIC_TYPE;
+  meta: {
+    schema: E['schema'];
+    key: string;
+    args: readonly any[];
+    update?: (
+      result: any,
+      ...args: any
+    ) => Record<string, (...args: any) => any>;
+    fetchedAt: number;
+    date: number;
+    expiresAt: number;
+    errorPolicy?: (error: any) => 'hard' | 'soft' | undefined;
+  };
+  endpoint: E;
+  error?: undefined;
+};
+
+export interface ResetAction {
+  type: typeof RESET_TYPE;
+  date: number | Date;
+}
+
+interface FetchMeta<
+  Payload extends object | string | number | null =
+    | object
+    | string
+    | number
+    | null,
+  S extends Schema | undefined = any,
+> {
+  type: FetchShape<any, any>['type'];
+  schema?: S;
+  key: string;
+  args?: readonly any[];
+  updaters?: Record<string, UpdateFunction<S, any>>;
+  update?: (result: any, ...args: any) => Record<string, (...args: any) => any>;
+  options?: EndpointExtraOptions;
+  throttle: boolean;
+  resolve: (value?: any | PromiseLike<any>) => void;
+  reject: (reason?: any) => void;
+  promise: PromiseLike<any>;
+  createdAt: number | Date;
+  optimisticResponse?: Payload;
+  // indicates whether network manager processed it
+  nm?: boolean;
+}
+
+export interface FetchAction<
+  Payload extends object | string | number | null =
+    | object
+    | string
+    | number
+    | null,
+  S extends Schema | undefined = any,
+> extends FSAWithPayloadAndMeta<
+    typeof FETCH_TYPE,
+    () => Promise<Payload>,
+    FetchMeta<any, any>
+  > {
+  meta: FetchMeta<Payload, S>;
+  endpoint?: undefined;
+}
+
+export interface SubscribeAction
+  extends FSAWithMeta<typeof SUBSCRIBE_TYPE, undefined, any> {
+  meta: {
+    args?: readonly any[];
+    schema: Schema | undefined;
+    fetch: () => Promise<any>;
+    key: string;
+    options: EndpointExtraOptions | undefined;
+  };
+  endpoint?: undefined;
+}
+
+export interface UnsubscribeAction
+  extends FSAWithMeta<typeof UNSUBSCRIBE_TYPE, undefined, any> {
+  meta: {
+    args?: readonly any[];
+    key: string;
+    options: EndpointExtraOptions | undefined;
+  };
+  endpoint?: undefined;
+}
+
+export interface InvalidateAction
+  extends FSAWithMeta<typeof INVALIDATE_TYPE, undefined, any> {
+  meta: {
+    key: string;
+  };
+}
+
+export interface GCAction {
+  type: typeof GC_TYPE;
+  entities: [string, string][];
+  results: string[];
+}
+
+// put other actions here in union
+export type ActionTypes =
+  | FetchAction
+  | OptimisticAction
+  | ReceiveAction
+  | SubscribeAction
+  | UnsubscribeAction
+  | InvalidateAction
+  | ResetAction
+  | GCAction;

package/src/manager/ConnectionListener.ts

@@ -0,0 +1,7 @@
+export default interface ConnectionListener {
+  isOnline: () => boolean;
+  addOnlineListener: (handler: () => void) => void;
+  removeOnlineListener: (handler: () => void) => void;
+  addOfflineListener: (handler: () => void) => void;
+  removeOfflineListener: (handler: () => void) => void;
+}

package/src/manager/DefaultConnectionListener.ts

@@ -0,0 +1,54 @@
+import ConnectionListener from './ConnectionListener.js';
+
+export class BrowserConnectionListener implements ConnectionListener {
+  isOnline() {
+    if (navigator.onLine !== undefined) {
+      return navigator.onLine;
+    }
+    return true;
+  }
+
+  addOnlineListener(handler: () => void) {
+    addEventListener('online', handler);
+  }
+
+  removeOnlineListener(handler: () => void) {
+    removeEventListener('online', handler);
+  }
+
+  addOfflineListener(handler: () => void) {
+    addEventListener('offline', handler);
+  }
+
+  removeOfflineListener(handler: () => void) {
+    removeEventListener('offline', handler);
+  }
+}
+
+export class AlwaysOnlineConnectionListener implements ConnectionListener {
+  isOnline() {
+    /* istanbul ignore next */
+    return true;
+  }
+
+  addOnlineListener() {}
+
+  removeOnlineListener() {}
+
+  addOfflineListener() {}
+
+  removeOfflineListener() {}
+}
+
+let DefaultConnectionListener: { new (): ConnectionListener };
+/* istanbul ignore if */
+if (
+  typeof navigator !== 'undefined' &&
+  typeof addEventListener === 'function'
+) {
+  DefaultConnectionListener = BrowserConnectionListener;
+} else {
+  /* istanbul ignore next */
+  DefaultConnectionListener = AlwaysOnlineConnectionListener;
+}
+export default DefaultConnectionListener;

package/src/manager/DevtoolsManager.ts

@@ -0,0 +1,99 @@
+import type { DevToolsConfig } from './devtoolsTypes.js';
+import type { Middleware } from './LogoutManager.js';
+import createReducer from '../state/reducer/createReducer.js';
+import type { Manager, State, ActionTypes } from '../types.js';
+
+export type { DevToolsConfig };
+
+const HASINTL = typeof Intl !== 'undefined';
+const DEFAULT_CONFIG = {
+  name: `Rest Hooks: ${globalThis.document?.title}`,
+  autoPause: true,
+  serialize: {
+    options: undefined,
+    /* istanbul ignore next */
+    replacer: HASINTL
+      ? (key: string | number | symbol, value: unknown) => {
+          if (
+            typeof value === 'number' &&
+            typeof key === 'string' &&
+            isFinite(value) &&
+            (key === 'date' || key.endsWith('At'))
+          ) {
+            return Intl.DateTimeFormat('en-US', {
+              hour: 'numeric',
+              minute: 'numeric',
+              second: 'numeric',
+              fractionalSecondDigits: 3,
+            }).format(value);
+          }
+          return value;
+        }
+      : undefined,
+  },
+};
+
+/** Integrates with https://github.com/reduxjs/redux-devtools
+ *
+ * Options: https://github.com/reduxjs/redux-devtools/blob/main/extension/docs/API/Arguments.md
+ *
+ * @see https://resthooks.io/docs/api/DevToolsManager
+ */
+export default class DevToolsManager implements Manager {
+  protected declare middleware: Middleware;
+  protected declare devTools: undefined | any;
+
+  constructor(
+    config?: DevToolsConfig,
+    skipLogging?: (action: ActionTypes) => boolean,
+  ) {
+    /* istanbul ignore next */
+    this.devTools =
+      typeof window !== 'undefined' &&
+      (window as any).__REDUX_DEVTOOLS_EXTENSION__ &&
+      (window as any).__REDUX_DEVTOOLS_EXTENSION__.connect({
+        ...DEFAULT_CONFIG,
+        config,
+      });
+
+    /* istanbul ignore if */
+    /* istanbul ignore next */
+    if (this.devTools) {
+      this.middleware = controller => {
+        const reducer = createReducer(controller as any);
+        return next => action => {
+          const ret = next(action);
+          ret.then(() => {
+            if (skipLogging?.(action)) return;
+            const state = controller.getState();
+            this.devTools.send(
+              action,
+              state.optimistic.reduce(reducer, state),
+              undefined,
+              'REST_HOOKS',
+            );
+          });
+          return ret;
+        };
+      };
+    } else {
+      this.middleware = () => next => action => next(action);
+    }
+  }
+
+  /** Called when initial state is ready */
+  init(state: State<any>) {
+    /* istanbul ignore if */
+    if (this.devTools) this.devTools.init(state);
+  }
+
+  /** Ensures all subscriptions are cleaned up. */
+  cleanup() {}
+
+  /** Attaches Manager to store
+   *
+   */
+  getMiddleware() {
+    return this.middleware;
+  }
+}

package/src/manager/LogoutManager.ts

@@ -0,0 +1,57 @@
+import { SET_TYPE } from '../actionTypes.js';
+import Controller from '../controller/Controller.js';
+import { UnknownError } from '../index.js';
+import type { CombinedActionTypes } from '../types.js';
+import { Manager } from '../types.js';
+
+/** Handling network unauthorized indicators like HTTP 401
+ *
+ * @see https://resthooks.io/docs/api/LogoutManager
+ */
+export default class LogoutManager implements Manager<CombinedActionTypes> {
+  protected declare middleware: Middleware;
+
+  constructor({ handleLogout, shouldLogout }: Props = {}) {
+    if (handleLogout) this.handleLogout = handleLogout;
+    if (shouldLogout) this.shouldLogout = shouldLogout;
+    this.middleware = controller => next => async action => {
+      await next(action);
+      if (
+        action.type === SET_TYPE &&
+        action.error &&
+        this.shouldLogout(action.payload)
+      ) {
+        this.handleLogout(controller);
+      }
+    };
+  }
+
+  cleanup() {}
+
+  getMiddleware() {
+    return this.middleware;
+  }
+
+  protected shouldLogout(error: UnknownError) {
+    // 401 indicates reauthorization is needed
+    return error.status === 401;
+  }
+
+  handleLogout(controller: Controller<Dispatch>) {
+    controller.resetEntireStore();
+  }
+}
+
+type Dispatch = (value: CombinedActionTypes) => Promise<void>;
+
+// this further restricts the types to be future compatible
+export type Middleware = <C extends Controller<Dispatch>>(
+  controller: C,
+) => (next: C['dispatch']) => C['dispatch'];
+
+type HandleLogout = (controller: Controller<Dispatch>) => void;
+
+interface Props {
+  handleLogout?: HandleLogout;
+  shouldLogout?: (error: UnknownError) => boolean;
+}