Replace magic strings with shared constants

[cliftonmcintosh]

As part of the work in #9621, we created a new shared constants library (@medic/constants) to reduce the use of magic strings throughout the codebase. The initial work added DOC_IDS.SERVICE_WORKER_META, DOC_TYPES.TRANSLATIONS, HTTP_HEADERS.REQUEST_ID, SENTINEL_METADATA.TRANSITIONS_SEQ, SENTINEL_METADATA.BACKGROUND_SEQ, and USER_ROLES.ONLINE.

However, there are many more magic strings used throughout the codebase that should be converted to use shared constants. This parent issue tracks the work to add constants across multiple categories including document IDs, document types, and other common strings.

Why this matters

Magic strings scattered throughout the codebase can lead to typos and make refactoring difficult. By centralizing these constants in a shared library, we:

• Reduce the risk of typos (if you misspell DOC_IDS.SETTINGS, you'll get a clear error)
• Make it easier to find all usages of a particular document ID
• Create a single source of truth for important values
• Make the code more maintainable and self-documenting

Constants to add

Based on an analysis of the codebase, here are the most common magic strings that could be converted to constants:

Document IDs (DOC_IDS)

• settings
• resources
• privacy-policies
• branding
• partners
• target-aggregates
• migration-log
• extension-libs
• zscore-charts

Document Types (DOC_TYPES)

• data_record
• person
• clinic
• contact
• district_hospital
• health_center
• task
• target
• user-settings
• form
• token_login

Other constant categories

Additional constants may be identified in other categories:

• HTTP Headers - Common header names
• User Roles - Role strings used throughout the application
• Sentinel Metadata - Local document IDs and sentinel-specific constants
• Common Prefixes/Patterns - Reusable string patterns like org.couchdb.user: or messages-

Implementation approach

Each constant (or small group of related constants) should be added as a separate sub-issue to keep pull requests focused and easy to review.

To succeed on this ticket, please:

1. Set up your development environment and ensure it works by logging into your CHT instance.

2. Read the shared constants library file at shared-libs/constants/src/index.js to understand its structure. Notice how it exports several constant categories like DOC_IDS, DOC_TYPES, HTTP_HEADERS, etc.

3. Search for how existing constants are used throughout the codebase to understand the pattern:

   • For example, DOC_IDS.SERVICE_WORKER_META is used in files like api/src/generate-service-worker.js, webapp/src/ts/services/db-sync.service.ts, and api/src/services/authorization.js
   • Notice how the constant is imported from @medic/constants and used in place of the magic string

4. For the specific constant(s) you're working on:

   • Add the constant to shared-libs/constants/src/index.js in the appropriate category object (e.g., DOC_IDS, DOC_TYPES, etc.)
   • Follow the pattern of existing constants in that category
   • Search for all usages of the magic string throughout the codebase (use grep or your IDE's search)
   • Replace each occurrence with the new constant
   • Ensure imports from @medic/constants are added where needed

5. Build the project and run unit tests to ensure everything compiles and works correctly:

   npm ci
   npm run build-dev
   npm run unit

   Note: The constants library itself doesn't have unit tests, but running the full unit test suite should verify that your changes work correctly throughout the codebase.

6. If all tests pass, create a git commit with your changes following the contribution guidelines.

Proposed sub-issues

The following sub-issues could be added to track individual constants or groups of constants:

Document ID constants

High-frequency document IDs (individual issues):

• Add constant for 'settings' document ID
• Add constant for 'resources' document ID
• Add constant for 'privacy-policies' document ID
• Add constant for 'branding' document ID
• Add constant for 'partners' document ID

Lower-frequency document IDs (grouped):

• Add constants for 'target-aggregates', 'migration-log', 'extension-libs', and 'zscore-charts' document IDs

Document Type constants

Very high-frequency document types (individual issues):

• Add constant for 'data_record' document type
• Add constant for 'person' document type
• Add constant for 'clinic' document type
• Add constant for 'contact' document type
• Add constant for 'district_hospital' document type
• Add constant for 'health_center' document type

Lower-frequency document types (grouped):

• Add constants for 'task', 'target', and 'user-settings' document types
• Add constants for 'form' and 'token_login' document types

Other constants

Based on the existing constant categories in the shared constants library:

• Add constants for HTTP headers (e.g., common header names beyond REQUEST_ID)
• Add constants for user roles (e.g., common role strings beyond ONLINE)
• Add constants for Sentinel metadata (e.g., additional local document IDs)
• Add constants for common prefixes or patterns (e.g., org.couchdb.user:, messages- for translations)

Additional constant categories can be added as sub-issues as they are identified.

[cliftonmcintosh]

@dianabarsan

As per our discussion in #9621, here is an issue for adding another constant. In the earlier chore, I documented some possible constants in a comment: #10457 (comment). The doc ID "settings" was one of them.

Does an issue for just that one seem appropriate? I believe there are about 100 instances of the "settings" doc ID in maybe a dozen files.

Or would it be better to have an issue for several doc IDs?

[dianabarsan]

I think either way works. The best way is to add a parent issue, which is verbose and detailed like this one and then sub-issues with less details for individual work (individual work can over one or more constants).

[cliftonmcintosh]

@dianabarsan

I've updated this issue to be a "parent issue". Your feedback would be appreciated.

[dianabarsan]

I love it! so thorough!

[cliftonmcintosh]

What's the preferred way to create sub-issues?
A. Go ahead and create them now so people (including me), can pick them up? Or
B. Wait and create them when someone is ready to pick one up?

I feel like A probably makes sense, but I defer to your judgment.

If A makes sense, I'm happy to create them.

[dianabarsan]

I think A would make the work more approachable and ready to pick up. I know it could be a large influx of issues if we target each property in one sub-issue.

[cliftonmcintosh]

Hmm. The list of proposed sub-issues includes a menu that has a "Convert to sub-issue" item in it, but when I select that item, nothing happens for me. Is this a permissions thing? Do you have the ability to make sub-issues from that list, @dianabarsan? If so, would you be willing to do so? I would be happy to fill in descriptions for them.