Helper Functions Configuration

This document provides a reference for configuring helper function generation in Telescope.

Overview

Helper functions provide a simplified interface to interact with your blockchain's services. Telescope can automatically generate these functions based on your proto definitions, allowing for cleaner and more intuitive code.

Configuration

Helper function generation is configured in the helperFunctions section of your Telescope options:

import { TelescopeOptions } from "@cosmology/types";
 
const options: TelescopeOptions = {
  helperFunctions: {
    enabled: true,
    hooks: {
      react: true,
      vue: false,
    },
    include: {
      serviceTypes: ["Query", "Msg"],
      patterns: ["cosmos.gov.v1beta1.**", "cosmos.bank.v1beta1.*Send*"],
    },
    nameMappers: {
      All: {
        "cosmos.gov.v1beta1.*Vote*": {
          funcBody: (ctx: AliasNameMappersContext) => {
            return `helper${ctx.name}`;
          },
          hookPrefix: "use",
        },
      },
      Query: {
        funcBody: (ctx: AliasNameMappersContext) => {
          return `get${ctx.name}`;
        },
        hookPrefix: "use",
      },
      Msg: {
        funcBody: "unchanged",
        hookPrefix: "useTx",
      },
    },
  },
};

Configuration Properties

Basic Options

Include Options

Name Mapping Options

The nameMappers object allows you to customize how function names are generated. It has three categories:

1. All - Applied to all service types
2. Query - Applied only to Query services
3. Msg - Applied only to Msg services

For each category, you can specify:

Pattern Matching Priority

When multiple patterns match a service, the following priority rules apply:

1. Service-specific patterns (Query, Msg) take precedence over All patterns
2. More specific patterns take precedence over general patterns
3. Patterns are case-sensitive

Name Transformation

The funcBody property can be either:

1. A string value:

   • "unchanged" - Keep the original method name
   • Any other string - Use as a prefix for the method name

2. A function: (name: string) => string

   • Receives the original method name
   • Returns the transformed name

Example function transformation:

funcBody: (ctx: AliasNameMappersContext) => {
  return `execute${ctx.name.charAt(0).toUpperCase()}${ctx.name.slice(1)}`;
};

Generated Output Examples

Basic Helper Functions

For a service cosmos.gov.v1beta1.Query.proposals, with default configuration:

// Generated function
export function getProposals(
  rpcEndpoint: string,
  params: QueryProposalsRequest
): Promise<QueryProposalsResponse> {
  // Implementation
}

React Hooks

If React hooks are enabled:

// Generated React hook
export function useProposals(
  rpcEndpoint: string,
  params: QueryProposalsRequest,
  options?: UseQueryOptions<QueryProposalsResponse>
): UseQueryResult<QueryProposalsResponse, Error> {
  // Implementation
}

Custom Naming

With custom naming rules:

nameMappers: {
  Query: {
    "cosmos.gov.v1beta1.*Proposals*": {
      funcBody: (ctx: AliasNameMappersContext) => {
        return `fetch${ctx.name}`;
      },
      hookPrefix: "useGov"
    }
  }
}

Would generate:

// Generated function
export function fetchProposals(/* ... */) {
  /* ... */
}
 
// Generated React hook
export function useGovFetchProposals(/* ... */) {
  /* ... */
}

Best Practices

1. Limit the scope: Use include.patterns to generate helpers only for the services you need
2. Use consistent naming: Maintain a consistent naming convention across your codebase
3. Prefer descriptive names: Use prefixes that describe the action (e.g., get for queries, send for transactions)
4. Document custom mappers: If using complex name transformations, document the logic for your team