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