persistoid__expo-file-engine.ts

import * as FileSystem from 'expo-file-system';
import { Platform } from 'react-native';

import { IStorageEngine } from 'lib/persistoid';
import { addDebugBreadcrumb, addErrorBreadcrumb } from 'lib/sentry';

function isAndroidMissingFileOrDirectoryError(error: unknown) {
  if (
    Platform.OS === 'android' &&
    hasMessage(error) &&
    /.*? \(No such file or directory\)/.test(error.message)
  ) {
    return true;
  }

  return false;
}

/**
 * Note: path should not start with "/", it will be prefixed with
 * Filesystem.documentDirectory which contains the trailing "/".
 */
const expoFileEngine: IStorageEngine = {
  getItem: async function getItem(path) {
    if (!FileSystem.documentDirectory) {
      throw new Error('FileSystem.documentDirectory is not defined');
    }

    const fileUri = FileSystem.documentDirectory + path;
    try {
      return await FileSystem.readAsStringAsync(fileUri);
    } catch (error) {
      if (isAndroidMissingFileOrDirectoryError(error)) {
        // IStorageEngine says null should be returned when no file found.
        return null;
      } else if (
        Platform.OS === 'ios' &&
        hasCode(error) &&
        error.code === 'ERR_FILE_NOT_READABLE'
        // /File \'.*?\' could not be read./.test(error.message)
      ) {
        // On iOS, expo-file-system is lumping file could not be read with file could
        // not be found. Do an existence check here, if it doesn't exist, then
        // return null, if it exists, then throw original error, as it exists
        // but could not be read.

        let fileInfo;
        try {
          fileInfo = await FileSystem.getInfoAsync(fileUri);
        } catch (getFileInfoError) {
          addErrorBreadcrumb(
            'expo-file-engine.getItem.getInfoAsync.file',
            getFileInfoError,
            {
              fileUri
            }
          );

          throw error;
        }

        if (fileInfo.exists) {
          // Throw original error, as FileSystem.readAsStringAsync failed to
          // read an existing file.

          addDebugBreadcrumb(
            'expo-file-engine',
            'Failed to read file even though it exists',
            { fileInfo, fileUri }
          );

          throw error;
        } else {
          // File does not exist, that's why FileSystem.readAsStringAsync
          // errored, so just return `null` as all is well, just file does not
          // exist.
          return null;
        }
      } else {
        // Unhandled error
        throw error;
      }
    }
  },

  setItem: async function setItem(path, value) {
    if (!FileSystem.documentDirectory) {
      throw new Error('FileSystem.documentDirectory is not defined');
    }

    const fileUri = FileSystem.documentDirectory + path;
    try {
      return await FileSystem.writeAsStringAsync(fileUri, value);
    } catch (error) {
      if (
        isAndroidMissingFileOrDirectoryError(error) ||
        (Platform.OS === 'ios' &&
          hasCode(error) &&
          error.code === 'ERR_FILE_NOT_WRITABLE')
      ) {
        const dirUri = fileUri.substring(0, fileUri.lastIndexOf('/'));

        let dirInfo;
        try {
          dirInfo = await FileSystem.getInfoAsync(dirUri);
        } catch (getDirInfoError) {
          addErrorBreadcrumb(
            'expo-file-engine.setItem.dir.getInfoAsync',
            getDirInfoError,
            {
              dirUri,
              fileUri
            }
          );

          throw error;
        }

        if (dirInfo.exists) {
          addDebugBreadcrumb(
            'expo-file-engine',
            'Failed to write file even though directory exists.',
            { dirInfo, dirUri, fileUri }
          );

          let fileInfo;
          try {
            fileInfo = await FileSystem.getInfoAsync(fileUri);
          } catch (getFileInfoError) {
            addErrorBreadcrumb(
              'expo-file-engine.setItem.file.getInfoAsync',
              getFileInfoError,
              {
                fileUri
              }
            );

            throw error;
          }

          addDebugBreadcrumb(
            'expo-file-engine',
            'Failed to write file even though file exists.',
            { fileInfo, fileUri }
          );

          throw error;
        } else {
          // Tried to write file but directory didn't exist. So create directory
          // then retry.

          addDebugBreadcrumb(
            'expo-file-engine',
            'Failed to write file due to missing directory, will create directory then retry.'
          );

          try {
            await FileSystem.makeDirectoryAsync(dirUri, {
              intermediates: true
            });
          } catch (createDirectoryError) {
            addErrorBreadcrumb(
              'expo-file-engine.setItem.makeDirectoryAsync',
              createDirectoryError,
              {
                dirUri,
                fileUri
              }
            );

            throw error;
          }

          addDebugBreadcrumb('expo-file-engine', 'Directory created');

          return expoFileEngine.setItem(path, value);
        }
      } else {
        // Unhandled error
        throw error;
      }
    }
  },

  removeItem: function removeItem(path) {
    if (!FileSystem.documentDirectory) {
      throw new Error('FileSystem.documentDirectory is not defined');
    }

    return FileSystem.deleteAsync(FileSystem.documentDirectory + path, {
      idempotent: true
    });
  },

  getAllKeys: function getAllKeys(path) {
    if (!FileSystem.documentDirectory) {
      throw new Error('FileSystem.documentDirectory is not defined');
    }

    return FileSystem.readDirectoryAsync(FileSystem.documentDirectory + path);
  }
};

function hasCode(anything: any): anything is { code: any } {
  return anything && typeof anything === 'object' && 'code' in anything;
}

function hasMessage(anything: any): anything is { message: string } {
  return (
    anything &&
    typeof anything === 'object' &&
    'message' in anything &&
    typeof anything.message === 'string'
  );
}

export default expoFileEngine;

persistoid__index.ts

import AsyncLock from 'async-lock';

import retry from 'lib/retry';
import { addDebugBreadcrumb, captureSentry } from 'lib/sentry';

export type IStorageEngine = {
  // returns null if file not exists
  getItem: (path: string) => string | null | Promise<string | null>;

  setItem: (path: string, value: string) => void | Promise<void>;
  removeItem: (path: string) => void | Promise<void>;
  getAllKeys: (path: string) => string[] | Promise<string[]>;
};

type IVersion = number;

type IMigrate<TState> = (prevState: TState) => Promise<TState> | TState;

export type IPersistoidInputs<TState> = {
  path: string;
  initialState: TState;
  version: IVersion;
  getStorageEngine: () => IStorageEngine | Promise<IStorageEngine>;
  migrations: Record<IVersion, IMigrate<TState> | undefined>;
};

type TReadOptions = { onMissingPersistedState?: () => void };

type IPersistoid<TState> = {
  read: (options: TReadOptions) => Promise<TState>;
  write: (state: TState) => Promise<void>;
  getInitialState: () => TState;
};
function createPersistoid<TState>(
  inputs: IPersistoidInputs<TState>
): IPersistoid<TState> {
  let storageEngine: IStorageEngine;

  const setStorageEngine = () =>
    retry(
      'persistoid.setStorageEngine',
      async () => {
        storageEngine = await inputs.getStorageEngine();
      },
      { extraLogData: { tags: { path: inputs.path } } }
    );

  async function read(options?: TReadOptions) {
    if (!storageEngine) {
      await setStorageEngine();
    }

    const content = await retry(
      'persistoid.read.getItem',
      async () => {
        const stringifiedContent = await storageEngine.getItem(inputs.path);
        if (stringifiedContent === null) {
          options?.onMissingPersistedState?.();
          // File does not exist so user didn't have any state persisted, so use
          // initial state.
          return {
            version: inputs.version,
            state: inputs.initialState
          };
        } else {
          return JSON.parse(stringifiedContent);
        }
      },
      { extraLogData: { tags: { path: inputs.path } } }
    );

    const shouldMigrate = content.version !== inputs.version;
    if (shouldMigrate) {
      const initialVersion = content.version;
      const goalVersion = inputs.version;
      const initialState = JSON.stringify(content.state);

      for (
        let nextVersion = content.version + 1;
        nextVersion <= goalVersion;
        nextVersion++
      ) {
        const migrate = inputs.migrations[nextVersion];

        if (migrate) {
          try {
            content.state = await migrate(content.state);

            // Just keep track of version so I can captureSentry this in case a
            // consequent migrate in this for-loop fails.
            content.version = nextVersion;
          } catch (error) {
            const isErrorInstance = error instanceof Error;

            captureSentry(
              isErrorInstance
                ? error
                : new Error(
                    'Non-Error type error during migration, see extras for error'
                  ),
              'persistoid.read.migrate',
              {
                tags: {
                  initialVersion,
                  goalVersion,
                  nextVersion,
                  prevVersion: content.version
                },
                extras: {
                  initialState,
                  error: isErrorInstance ? error : undefined
                }
              }
            );

            throw error;
          }
        }
      }

      // Do it async so that we dont block the user
      write(content.state);
    }

    return content.state;
  }

  const writeLock = new AsyncLock({
    // All but last task are canceled/discarded. Last task has latest state, and
    // all others have outdated state.
    maxPending: Infinity
  });
  const WRITE_TASK_CANCELED = new Error('WRITE_TASK_CANCELED');

  async function write(state: TState) {
    // When support writing multiple files at once, the key will be the path of
    // the file.
    const lockKey = inputs.path;

    // When this is the only task running in the queue,
    // writeLock.queues[lockKey] will be empty. If nothing running for a key,
    // then the lockKey will not exist in the dict of `writeLock.queues`. I only
    // want to run the latest `write` in the queue, so discard all others but
    // the latest one. As the latest one has the latest state. Otherwise we will
    // waste writes writing outdated states.
    const hasPendingTasks = () =>
      lockKey in writeLock.queues && writeLock.queues[lockKey].length > 0;

    const exitIfCanceled = () => {
      if (hasPendingTasks()) {
        addDebugBreadcrumb(
          'persistoid',
          'Write task canceled because a more recent task (and thus with latest state) is pending',
          { queueLength: writeLock.queues[lockKey].length }
        );

        throw WRITE_TASK_CANCELED;
      }
    };

    return writeLock.acquire(lockKey, async function lockedWrite() {
      if (!storageEngine) {
        await setStorageEngine();
      }

      const content = {
        state,
        version: inputs.version
      };

      await retry(
        'persistoid.write.setItem',
        () => {
          exitIfCanceled();

          return storageEngine.setItem(inputs.path, JSON.stringify(content));
        },
        {
          extraLogData: { tags: { path: inputs.path } },
          isTerminalError: error => error === WRITE_TASK_CANCELED
        }
      );
    });
  }

  return { read, write, getInitialState: () => inputs.initialState };
}

export default createPersistoid;

persistoid__proxy-with-persist__index.ts

import { proxy, subscribe } from 'valtio';
import { subscribeKey } from 'valtio/utils';

import createPersistoid, { IPersistoidInputs } from 'lib/persistoid';

type IProxyWithPersistInputs<T> = IPersistoidInputs<T> & {
  onChange: (data: T) => void;
};

type IBaseState<T> = {
  load: (options?: { shouldLoadInitialState?: boolean }) => Promise<void>;
  loadInitialState: () => Promise<void>;
  write: () => void;
};

type IIdleState<T> = IBaseState<T> & {
  status: 'idle';
  error: null;
  data: null;
};

type ILoadingState<T> = IBaseState<T> & {
  status: 'loading';
  error: null;
  data: null;
};

type ISuccessState<T> = IBaseState<T> & {
  status: 'success';
  error: null;
  data: T;
  didNotFindPersistedState?: true;
};

type IFailureState<T> = IBaseState<T> & {
  status: 'error';
  error: any;
  data: null;
};

type IState<T> =
  | IIdleState<T>
  | ILoadingState<T>
  | ISuccessState<T>
  | IFailureState<T>;

export type TProxyWithPersist = ReturnType<typeof proxyWithPersist>;

export type LoadedProxy<T extends TProxyWithPersist> = Extract<
  T,
  { status: 'success' }
>;

function proxyWithPersist<T>(inputs: IProxyWithPersistInputs<T>) {
  const persistoid = createPersistoid<T>(inputs);

  const stateProxy: IState<T> = proxy<IState<T>>({
    status: 'idle',
    error: null,
    data: null,

    // This will never re-load. If already succesfully loaded, it will no-op. If
    // it's loading it will wait for it to finish loading.
    load: async function load(options): Promise<void> {
      if (stateProxy.status === 'success') {
        return;
      }

      if (stateProxy.status === 'loading') {
        return new Promise<void>(resolve => {
          const unsubscribe = subscribeKey(stateProxy, 'status', status => {
            if (status !== 'loading') {
              unsubscribe();
              resolve();
            }
          });
        });
      }

      // If it's in error state, move it to idle state.
      stateProxy.status = 'loading';
      stateProxy.error = null;
      let didNotFindPersistedState = false;
      try {
        if (options?.shouldLoadInitialState) {
          stateProxy.data = persistoid.getInitialState();
        } else {
          stateProxy.data = await persistoid.read({
            onMissingPersistedState: function markFileMissing() {
              didNotFindPersistedState = true;
            }
          });
        }

        stateProxy.status = 'success';
        if (didNotFindPersistedState) {
          stateProxy.didNotFindPersistedState = true;
        }

        // Crticial note: Once "success" is set, nothing in the stateProxy
        // should ever change except `data`. As valtio v1.7.1 doesn't support
        // watching a key deeply anymore. So I assume any change on stateProxy
        // is a change on `data`.
        subscribe(stateProxy, () => {
          inputs.onChange(
            // For sure `data` is now T so it's safe to cast.
            stateProxy.data as T
          );
        });
      } catch (error) {
        // Don't log error to Sentry here as persistoid.read() will handle this.
        stateProxy.error = error;
        stateProxy.status = 'error';
      }
    },

    loadInitialState: function loadWithInitialState() {
      return stateProxy.load({ shouldLoadInitialState: true });
    },

    write: function write() {
      if (stateProxy.status === 'success') {
        // sateProxy.success is only set to true once the data has been loaded,
        // so it's safe to cast to T.
        persistoid.write(stateProxy.data as T);
      } else {
        throw new Error('Not loaded, nothing to write');
      }
    }
  });

  return stateProxy;
}

export function tillProxyLoaded(proxy: TProxyWithPersist): Promise<void> {
  if (proxy.status === 'success') {
    return Promise.resolve();
  }

  return new Promise(resolve => {
    const unsubscribe = subscribeKey(proxy, 'status', status => {
      if (
        // @ts-ignore: TS doesn't realize that status can change to 'success'
        status === 'success'
      ) {
        unsubscribe();
        resolve();
      }
    });
  });
}

export default proxyWithPersist;

savedFieldValuesProxy.ts

import { debounce } from 'lodash';
import { AppState as NativeAppState } from 'react-native';

import expoFileEngine from 'lib/persistoid/expo-file-engine';
import proxyWithPersist, {
  LoadedProxy,
} from 'lib/persistoid/proxy-with-persist';

type TSavedFieldValues = {
  [fieldName: string]: string;
};

export const writeSavedFieldValues = debounce(function writeSavedFieldValues() {
  savedFieldValuesProxy.write();
}, 1000);

export type TLoadedSavedFieldValuesProxy = LoadedProxy<
  typeof savedFieldValuesProxy
>;

export const savedFieldValuesProxy = proxyWithPersist<TSavedFieldValues>({
  path: 'state/saved-field-values.json',
  initialState: {},
  version: 1,
  migrations: {},
  getStorageEngine: () => expoFileEngine,
  onChange: writeSavedFieldValues
});

NativeAppState.addEventListener(
  'change',
  function persistAppStateOnBackground(nextAppState) {
    if (nextAppState === 'background') {
      writeSavedFieldValues.flush();
    }
  }
);