Best Practice

When writing scripts in ReAPI, following best practices ensures maintainability, scalability, and a smooth development experience.

Plan Your Script

Before diving into implementation, careful planning is essential for creating robust and maintainable scripts. Consider these key aspects:

Analyze Project Requirements

• Domain-Specific Needs: Identify unique data structures and formats your project requires
  • Date/time formatting requirements (timezone handling, specific formats)
  • Domain-specific data validation rules
  • Custom data transformation needs

Plan Naming Conventions

• Establish Prefix Strategy: Decide on organization or project prefixes
  • Use ’$$’ as a simple, compatible prefix that won’t conflict with ReAPI’s ’$’
  • Or use organization/project specific prefixes (e.g., ‘ACME_’, ‘MY_’)
  • Ensure consistency across team members
  • Consider long-term maintainability
• Define Naming Patterns: Create clear guidelines for:
  • Class names (e.g., ‘ACME_DateUtils’, ‘MY_ValidationUtils’)
  • Method names (e.g., ‘formatToTimezone’, ‘isValidEmail’)
  • Parameter names

Identify Reusable Components

• Map out utility classes you’ll need:

  // Example utility classes you might need
  $$DateUtils; // Date formatting, timezone conversion
  $$FormatUtils; // Data formatting and transformation
  $$ValidationUtils; // Domain-specific validation rules
  $$ConfigUtils; // Environment-specific configuration

Choose Implementation Strategy

Consider these factors when deciding between global scripts and external libraries:

Implementation

Wrap Functions in a Class

Encapsulate related functions within a class with static methods. This avoids global namespace pollution and ensures better organization.
Example:

class $$MathUtils {
  static add(a, b) {
    return a + b;
  }
 
  static subtract(a, b) {
    return a - b;
  }
}

Name Class and Functions Properly

Use descriptive and consistent names for your class and functions.

⚠️ Warning: Class and function names cannot be changed once they are used by other scripts, as this will break existing references. Choose names carefully during initial development. If renaming is absolutely necessary, create an adapter function that maintains the old name while calling the new implementation, and mark it as deprecated.

Example of handling necessary rename:

class ACME_NewDateUtils {
  static formatDate(date) {
    // New implementation
  }
}
 
class ACME_DateUtils {
  /** @deprecated Use ACME_NewDateUtils.formatDate instead */
  static formatDate(date) {
    return ACME_NewDateUtils.formatDate(date);
  }
}

• Choose a prefix strategy for your utility classes:
  • Use $$ as a simple prefix that’s compatible with ReAPI’s $ prefix but avoids conflicts
  • Or use organization/project specific prefixes (e.g., MY_DateUtils, ACME_DateUtils)
• Use clear, action-based names for functions (e.g., formatToTimezone, isValidUUID)

Example:

// Using simple '$$' prefix
class $$DateUtils {
  static formatToTimezone(date, timezone) {
    // Implementation
  }
}
 
// Using organization prefix 'ACME_'
class ACME_ValidationUtils {
  static isValidEmail(email) {
    // Implementation
  }
}

Use API Hook References Over Inline Hooks

Whenever possible, use reusable API hook references instead of inline hooks. This ensures consistency, improves maintainability, and reduces duplication.

Use AI to Generate Functions with JSDoc

Leverage AI tools to quickly generate well-documented functions with JSDoc comments. This approach:

• Saves development time
• Ensures consistent documentation
• Provides comprehensive parameter and return type descriptions

Simply describe your function requirements to an AI assistant, and it can generate the complete function structure with proper JSDoc documentation in seconds.

Add JSDoc Comments

Include JSDoc comments to document the purpose, parameters, and return values of each function. This improves readability and assists others using your scripts.

Important: When using AI tools for type generation, always write JSDoc comments in your javascript code first. This ensures consistency in type definitions and prevents merge conflicts that could arise from slightly different AI-generated types.

Example:

class $$DateUtils {
  /**
   * Formats a date to a specific timezone.
   * @param {string|Date} date - The date to format.
   * @param {string} timezone - The target timezone.
   * @returns {string} The formatted date string.
   */
  static formatToTimezone(date, timezone) {
    const options = { timeZone: timezone, hour12: false };
    return new Intl.DateTimeFormat("en-US", options).format(new Date(date));
  }
}

Add TypeScript Type Declaration

Provide TypeScript type declarations to enable intellisense, autocomplete, and type checking.

Keep Main Logic in Global Script or External Library

Separate the core logic from assertion or hook-specific functionality by storing it in a global script or external library. This ensures better reusability across different components.

By following these best practices, you ensure your ReAPI scripts are modular, reusable, and easy to maintain across different projects and environments.