Merge pull request #41956 from callstack-internal/pac-guerreiro/refac…

…tor/39129-add-comments-to-remaining-onyx-types

[No QA][TS Migration] Add comments for remaining properties in Onyx types

.eslintrc.js

@@ -235,8 +235,21 @@ module.exports = {
  ],
  },
 
- // Remove once no JS files are left
  overrides: [
+ // Enforces every Onyx type and its properties to have a comment explaining its purpose.
+ {
+ files: ['src/types/onyx/**/*.ts'],
+ rules: {
+ 'jsdoc/require-jsdoc': [
+ 'error',
+ {
+ contexts: ['TSInterfaceDeclaration', 'TSTypeAliasDeclaration', 'TSPropertySignature'],
+ },
+ ],
+ },
+ },
+
+ // Remove once no JS files are left
  {
  files: ['*.js', '*.jsx'],
  rules: {

src/libs/ModifiedExpenseMessage.ts

@@ -3,12 +3,12 @@ import type {OnyxCollection, OnyxEntry} from 'react-native-onyx';
 import CONST from '@src/CONST';
 import ONYXKEYS from '@src/ONYXKEYS';
 import type {PolicyTagList, ReportAction} from '@src/types/onyx';
+import type {ModifiedExpense} from '@src/types/onyx/OriginalMessage';
 import * as CurrencyUtils from './CurrencyUtils';
 import DateUtils from './DateUtils';
 import getReportPolicyID from './getReportPolicyID';
 import * as Localize from './Localize';
 import * as PolicyUtils from './PolicyUtils';
-import type {ExpenseOriginalMessage} from './ReportUtils';
 import * as TransactionUtils from './TransactionUtils';
 
 let allPolicyTags: OnyxCollection<PolicyTagList> = {};
@@ -109,7 +109,7 @@ function getForReportAction(reportID: string | undefined, reportAction: OnyxEntr
  if (reportAction?.actionName !== CONST.REPORT.ACTIONS.TYPE.MODIFIED_EXPENSE) {
  return '';
  }
- const reportActionOriginalMessage = reportAction?.originalMessage as ExpenseOriginalMessage | undefined;
+ const reportActionOriginalMessage = reportAction?.originalMessage as ModifiedExpense | undefined;
  const policyID = getReportPolicyID(reportID) ?? '';
 
  const removalFragments: string[] = [];

src/libs/ReportActionsUtils.ts

@@ -11,6 +11,7 @@ import type {
  ActionName,
  ChangeLog,
  IOUMessage,
+ JoinWorkspaceResolution,
  OriginalMessageActionableMentionWhisper,
  OriginalMessageActionableReportMentionWhisper,
  OriginalMessageActionableTrackedExpenseWhisper,
@@ -1205,7 +1206,9 @@ function isActionableJoinRequest(reportAction: OnyxEntry<ReportAction>): reportA
  */
 function isActionableJoinRequestPending(reportID: string): boolean {
  const sortedReportActions = getSortedReportActions(Object.values(getAllReportActions(reportID)));
- const findPendingRequest = sortedReportActions.find((reportActionItem) => isActionableJoinRequest(reportActionItem) && reportActionItem.originalMessage.choice === '');
+ const findPendingRequest = sortedReportActions.find(
+ (reportActionItem) => isActionableJoinRequest(reportActionItem) && reportActionItem.originalMessage.choice === ('' as JoinWorkspaceResolution),
+ );
  return !!findPendingRequest;
 }
 

src/libs/ReportUtils.ts

@@ -40,13 +40,15 @@ import type {Errors, Icon, PendingAction} from '@src/types/onyx/OnyxCommon';
 import type {
  ChangeLog,
  IOUMessage,
+ ModifiedExpense,
  OriginalMessageActionName,
+ OriginalMessageApproved,
  OriginalMessageCreated,
  OriginalMessageDismissedViolation,
  OriginalMessageReimbursementDequeued,
  OriginalMessageRenamed,
+ OriginalMessageSubmitted,
  PaymentMethodType,
- ReimbursementDeQueuedMessage,
 } from '@src/types/onyx/OriginalMessage';
 import type {Status} from '@src/types/onyx/PersonalDetails';
 import type {NotificationPreference, Participants, PendingChatMember, Participant as ReportParticipant} from '@src/types/onyx/Report';
@@ -87,30 +89,6 @@ type AvatarRange = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 |
 
 type WelcomeMessage = {showReportName: boolean; phrase1?: string; phrase2?: string};
 
-type ExpenseOriginalMessage = {
- oldComment?: string;
- newComment?: string;
- comment?: string;
- merchant?: string;
- oldCreated?: string;
- created?: string;
- oldMerchant?: string;
- oldAmount?: number;
- amount?: number;
- oldCurrency?: string;
- currency?: string;
- category?: string;
- oldCategory?: string;
- tag?: string;
- oldTag?: string;
- billable?: string;
- oldBillable?: string;
- oldTaxAmount?: number;
- taxAmount?: number;
- taxRate?: string;
- oldTaxRate?: string;
-};
-
 type SpendBreakdown = {
  nonReimbursableSpend: number;
  reimbursableSpend: number;
@@ -211,12 +189,12 @@ type ReportOfflinePendingActionAndErrors = {
 };
 
 type OptimisticApprovedReportAction = Pick<
- ReportAction,
+ ReportAction & OriginalMessageApproved,
  'actionName' | 'actorAccountID' | 'automatic' | 'avatar' | 'isAttachment' | 'originalMessage' | 'message' | 'person' | 'reportActionID' | 'shouldShow' | 'created' | 'pendingAction'
 >;
 
 type OptimisticSubmittedReportAction = Pick<
- ReportAction,
+ ReportAction & OriginalMessageSubmitted,
  | 'actionName'
  | 'actorAccountID'
  | 'adminAccountID'
@@ -2208,7 +2186,7 @@ function getReimbursementDeQueuedActionMessage(
  report: OnyxEntry<Report> | EmptyObject,
  isLHNPreview = false,
 ): string {
- const originalMessage = reportAction?.originalMessage as ReimbursementDeQueuedMessage | undefined;
+ const originalMessage = reportAction?.originalMessage;
  const amount = originalMessage?.amount;
  const currency = originalMessage?.currency;
  const formattedAmount = CurrencyUtils.convertToDisplayString(amount, currency);
@@ -3024,8 +3002,8 @@ function getModifiedExpenseOriginalMessage(
  transactionChanges: TransactionChanges,
  isFromExpenseReport: boolean,
  policy: OnyxEntry<Policy>,
-): ExpenseOriginalMessage {
- const originalMessage: ExpenseOriginalMessage = {};
+): ModifiedExpense {
+ const originalMessage: ModifiedExpense = {};
  // Remark: Comment field is the only one which has new/old prefixes for the keys (newComment/ oldComment),
  // all others have old/- pattern such as oldCreated/created
  if ('comment' in transactionChanges) {
@@ -7151,7 +7129,6 @@ export {
 export type {
  Ancestor,
  DisplayNameWithTooltips,
- ExpenseOriginalMessage,
  OptimisticAddCommentReportAction,
  OptimisticChatReport,
  OptimisticClosedReportAction,

src/libs/actions/Card.ts

@@ -5,7 +5,7 @@ import type {ActivatePhysicalExpensifyCardParams, ReportVirtualExpensifyCardFrau
 import {SIDE_EFFECT_REQUEST_COMMANDS, WRITE_COMMANDS} from '@libs/API/types';
 import CONST from '@src/CONST';
 import ONYXKEYS from '@src/ONYXKEYS';
-import type {Response} from '@src/types/onyx';
+import type {ExpensifyCardDetails} from '@src/types/onyx/Card';
 
 type ReplacementReason = 'damaged' | 'stolen';
 
@@ -158,7 +158,7 @@ function clearCardListErrors(cardID: number) {
  *
  * @returns promise with card details object
  */
-function revealVirtualCardDetails(cardID: number): Promise<Response> {
+function revealVirtualCardDetails(cardID: number): Promise<ExpensifyCardDetails> {
  return new Promise((resolve, reject) => {
  const parameters: RevealExpensifyCardDetailsParams = {cardID};
 
@@ -170,7 +170,7 @@ function revealVirtualCardDetails(cardID: number): Promise<Response> {
  reject('cardPage.cardDetailsLoadingFailure');
  return;
  }
- resolve(response);
+ resolve(response as ExpensifyCardDetails);
  })
  // eslint-disable-next-line prefer-promise-reject-errors
  .catch(() => reject('cardPage.cardDetailsLoadingFailure'));

src/libs/actions/Wallet.ts

@@ -61,10 +61,6 @@ function setAdditionalDetailsErrors(errorFields: OnyxCommon.ErrorFields) {
  Onyx.merge(ONYXKEYS.WALLET_ADDITIONAL_DETAILS, {errorFields});
 }
 
-function setAdditionalDetailsErrorMessage(additionalErrorMessage: string) {
- Onyx.merge(ONYXKEYS.WALLET_ADDITIONAL_DETAILS, {additionalErrorMessage});
-}
-
 /**
  * Save the source that triggered the KYC wall and optionally the chat report ID associated with the IOU
  */
@@ -304,7 +300,6 @@ export {
  openInitialSettingsPage,
  openEnablePaymentsPage,
  setAdditionalDetailsErrors,
- setAdditionalDetailsErrorMessage,
  setAdditionalDetailsQuestions,
  updateCurrentStep,
  answerQuestionsForWallet,

src/libs/models/BankAccount.ts

@@ -1,7 +1,7 @@
 import {Str} from 'expensify-common';
 import type {ValueOf} from 'type-fest';
 import CONST from '@src/CONST';
-import type {AdditionalData} from '@src/types/onyx/BankAccount';
+import type {BankAccountAdditionalData} from '@src/types/onyx/BankAccount';
 import type BankAccountJSON from '@src/types/onyx/BankAccount';
 
 type State = ValueOf<typeof BankAccount.STATE>;
@@ -194,7 +194,7 @@ class BankAccount {
  /**
  * Get the additional data of a bankAccount
  */
- getAdditionalData(): Partial<AdditionalData> {
+ getAdditionalData(): Partial<BankAccountAdditionalData> {
  return this.json.accountData?.additionalData ?? {};
  }
 

src/pages/home/ReportScreen.tsx

@@ -68,6 +68,7 @@ type ReportScreenOnyxProps = {
  /** An array containing all report actions related to this report, sorted based on a date criterion */
  sortedAllReportActions: OnyxTypes.ReportAction[];
 
+ /** Additional report details */
  reportNameValuePairs: OnyxEntry<OnyxTypes.ReportNameValuePairs>;
 
  /** The report metadata loading states */

src/pages/home/report/ReportActionItem.tsx

@@ -67,6 +67,7 @@ import ONYXKEYS from '@src/ONYXKEYS';
 import ROUTES from '@src/ROUTES';
 import type * as OnyxTypes from '@src/types/onyx';
 import type {Errors} from '@src/types/onyx/OnyxCommon';
+import type {JoinWorkspaceResolution} from '@src/types/onyx/OriginalMessage';
 import {isEmptyObject} from '@src/types/utils/EmptyObject';
 import AnimatedEmptyStateBackground from './AnimatedEmptyStateBackground';
 import {RestrictedReadOnlyContextMenuActions} from './ContextMenu/ContextMenuActions';
@@ -398,7 +399,7 @@ function ReportActionItem({
  const attachmentContextValue = useMemo(() => ({reportID: report.reportID, type: CONST.ATTACHMENT_TYPE.REPORT}), [report.reportID]);
 
  const actionableItemButtons: ActionableItem[] = useMemo(() => {
- if (!isActionableWhisper && (!ReportActionsUtils.isActionableJoinRequest(action) || action.originalMessage.choice !== '')) {
+ if (!isActionableWhisper && (!ReportActionsUtils.isActionableJoinRequest(action) || action.originalMessage.choice !== ('' as JoinWorkspaceResolution))) {
  return [];
  }
 

src/pages/home/report/ReportFooter.tsx

@@ -34,8 +34,10 @@ type ReportFooterProps = {
  /** Report object for the current report */
  report?: OnyxTypes.Report;
 
+ /** Report metadata */
  reportMetadata?: OnyxEntry<OnyxTypes.ReportMetadata>;
 
+ /** Additional report details */
  reportNameValuePairs?: OnyxEntry<OnyxTypes.ReportNameValuePairs>;
 
  /** The policy of the report */

src/pages/settings/Wallet/ExpensifyCardPage.tsx

@@ -32,7 +32,7 @@ import ROUTES from '@src/ROUTES';
 import type SCREENS from '@src/SCREENS';
 import type {GetPhysicalCardForm} from '@src/types/form';
 import type {LoginList, Card as OnyxCard, PrivatePersonalDetails} from '@src/types/onyx';
-import type {TCardDetails} from '@src/types/onyx/Card';
+import type {ExpensifyCardDetails} from '@src/types/onyx/Card';
 import RedDotCardSection from './RedDotCardSection';
 import CardDetails from './WalletPage/CardDetails';
 
@@ -101,7 +101,7 @@ function ExpensifyCardPage({
 
  const virtualCards = useMemo(() => cardsToShow?.filter((card) => card?.nameValuePairs?.isVirtual), [cardsToShow]);
  const physicalCards = useMemo(() => cardsToShow?.filter((card) => !card?.nameValuePairs?.isVirtual), [cardsToShow]);
- const [cardsDetails, setCardsDetails] = useState<Record<number, TCardDetails | null>>({});
+ const [cardsDetails, setCardsDetails] = useState<Record<number, ExpensifyCardDetails | null>>({});
  const [isCardDetailsLoading, setIsCardDetailsLoading] = useState<Record<number, boolean>>({});
  const [cardsDetailsErrors, setCardsDetailsErrors] = useState<Record<number, string>>({});
 
@@ -116,7 +116,7 @@ function ExpensifyCardPage({
  // eslint-disable-next-line rulesdir/no-thenable-actions-in-views
  Card.revealVirtualCardDetails(revealedCardID)
  .then((value) => {
- setCardsDetails((prevState: Record<number, TCardDetails | null>) => ({...prevState, [revealedCardID]: value as TCardDetails}));
+ setCardsDetails((prevState: Record<number, ExpensifyCardDetails | null>) => ({...prevState, [revealedCardID]: value}));
  setCardsDetailsErrors((prevState) => ({
  ...prevState,
  [revealedCardID]: '',

src/types/onyx/Account.ts

@@ -4,8 +4,10 @@ import type DismissedReferralBanners from './DismissedReferralBanners';
 import type * as OnyxCommon from './OnyxCommon';
 import type {TravelSettings} from './TravelSettings';
 
+/** Two factor authentication steps */
 type TwoFactorAuthStep = ValueOf<typeof CONST.TWO_FACTOR_AUTH_STEPS> | '';
 
+/** Model of user account */
 type Account = {
  /** Whether SAML is enabled for the current account */
  isSAMLEnabled?: boolean;
@@ -55,10 +57,19 @@ type Account = {
  /** Whether a sign is loading */
  isLoading?: boolean;
 
+ /** Authentication failure errors */
  errors?: OnyxCommon.Errors | null;
+
+ /** Authentication success message */
  success?: string;
+
+ /** Whether the two factor authentication codes were copied */
  codesAreCopied?: boolean;
+
+ /** Current two factor authentication step */
  twoFactorAuthStep?: TwoFactorAuthStep;
+
+ /** Referral banners that the user dismissed */
  dismissedReferralBanners?: DismissedReferralBanners;
 
  /** Object containing all account information necessary to connect with Spontana */

src/types/onyx/AccountData.ts

@@ -1,15 +1,7 @@
-import type {BankName} from './Bank';
+import type {BankAccountAdditionalData} from './BankAccount';
 import type * as OnyxCommon from './OnyxCommon';
 
-type AdditionalData = {
- isP2PDebitCard?: boolean;
- beneficialOwners?: string[];
- currency?: string;
- bankName?: BankName;
- fieldsType?: string;
- country?: string;
-};
-
+/** Model of bank account data */
 type AccountData = {
  /** The masked bank account number */
  accountNumber?: string;
@@ -38,20 +30,22 @@ type AccountData = {
  /** All user emails that have access to this bank account */
  sharees?: string[];
 
+ /** Institution that processes the account payments */
  processor?: string;
 
  /** The bankAccountID in the bankAccounts db */
  bankAccountID?: number;
 
  /** All data related to the bank account */
- additionalData?: AdditionalData;
+ additionalData?: BankAccountAdditionalData;
 
  /** The bank account type */
  type?: string;
 
  /** Any error message to show */
  errors?: OnyxCommon.Errors;
 
+ /** The debit card ID */
  fundID?: number;
 };
 

src/types/onyx/Bank.ts

@@ -3,15 +3,28 @@ import type {ValueOf} from 'type-fest';
 import type CONST from '@src/CONST';
 import type IconAsset from '@src/types/utils/IconAsset';
 
+/** Bank icon configurations */
 type BankIcon = {
+ /** Source of the icon, can be a component or an image */
  icon: IconAsset;
+
+ /** Size of the icon */
  iconSize?: number;
+
+ /** Height of the icon */
  iconHeight?: number;
+
+ /** Width of the icon */
  iconWidth?: number;
+
+ /** Icon wrapper styles */
  iconStyles?: ViewStyle[];
 };
 
+/** Bank names */
 type BankName = ValueOf<typeof CONST.BANK_NAMES>;
+
+/** Bank name keys */
 type BankNameKey = keyof typeof CONST.BANK_NAMES;
 
 export type {BankIcon, BankName, BankNameKey};