Function Naming Reference

This reference documents the function naming patterns used throughout the codebase.

API Functions

API functions follow a consistent naming pattern based on their location in the file system.

Pattern

{routeName}PageAPI(...)

Where routeName is derived from the page’s file path:

src/pages/{routeName}/  →  {routeName}PageAPI

Examples

File Path	Function Name
src/pages/articles/_graphql/api.ts	articlesPageAPI()
src/pages/places/_graphql/api.ts	placesPageAPI()
src/pages/homepage/_graphql/api.ts	homepagePageAPI()
src/pages/about/_graphql/api.ts	aboutPageAPI()

Implementation

src/pages/articles/_graphql/api.ts

import { graphqlApi } from "#graphql/graphqlClient";
import ARTICLES_QUERY from "./page.query.graphql";

export async function articlesPageAPI(variables: ArticlesQueryVariables) {
  return graphqlApi({
    query: ARTICLES_QUERY,
    variables,
  });
}

Dynamic Routes

For dynamic routes, use the singular form of the parent route:

src/pages/articles/[slug]/_graphql/api.ts

export async function articlePageAPI({
  slug,
  previewEnabled,
  pathname,
}: {
  slug: string;
  previewEnabled?: boolean;
  pathname?: string;
}) {
  // Implementation
}

// ✅ articlePageAPI (singular of "articles")
// ❌ articlesPageAPI (don't use plural)
// ❌ articleSlugPageAPI (don't include param name)

Component-Level API Functions

Component-level API functions use the component name with API suffix:

src/components/relatedArticles/graphql/api.ts

export async function relatedArticlesAPI(slug: string) {
  // Implementation
}

// src/pages/articles/_components/saveControls/api.ts
export async function saveButtonAPI(props: Props) {
  // Implementation
}

// src/components/newsletterForm/graphql/api.ts
export async function newsletterFormAPI(data: FormData) {
  // Implementation
}

Validation Functions

Functions that validate data or parameters.

Pattern

validate{Entity}{Purpose}()
validate{Criteria}()

Examples

// ✅ Clear validation intent
export async function validateArticlePageAPI(slug: string) {}
export async function validateSlugFormat(slug: string) {}
export async function validateUserPermissions(userId: string) {}

// ❌ Unclear validation
export async function check(slug: string) {} // Too vague
export async function isValid(slug: string) {} // Not descriptive

Transform Functions

Functions that transform data from one shape to another.

Pattern

transform{Entity}Data()
transform{Source}To{Target}()
format{Entity}()

Examples

// ✅ Clear transformation intent
export function transformArticleData(raw: RawArticle): Article {}
export function transformGraphQLToViewModel(data: GraphQLData): ViewModel {}
export function formatReadingTime(minutes: number): string {}
export function formatDate(date: Date): string {}

// ❌ Unclear transformations
export function article(raw: RawArticle): Article {} // Not descriptive
export function convert(data: GraphQLData): ViewModel {} // Too generic
export function time(minutes: number): string {} // Vague

Utility Functions

Helper functions that perform specific operations.

Pattern

{verb}{Object}()
is{Condition}()
has{Property}()

Examples

// ✅ Clear utility functions
export function sanitizeHtml(content: string): string {}
export function validateEmail(email: string): boolean {}
export function isValidSlug(slug: string): boolean {}
export function hasRequiredFields(data: object): boolean {}
export function extractMetadata(content: string): Metadata {}

// ❌ Unclear utilities
export function clean(content: string): string {} // What's being cleaned?
export function check(email: string): boolean {} // Check what?
export function valid(slug: string): boolean {} // Incomplete

Error Handling Functions

Functions that handle errors or logging.

Pattern

handle{Context}Error()
log{Event}()
report{Issue}()

Examples

// ✅ Clear error handling
export function handleGraphQLError(error: Error, context: Context) {}
export function logApiFailure(endpoint: string, error: Error) {}
export function reportToAirbrake(error: Error, metadata: object) {}

// ❌ Unclear error handling
export function error(error: Error) {} // Too generic
export function handle(error: Error) {} // Handle what?

Naming Rules

DO

✅ Use descriptive, action-based names
✅ Include entity or resource in the name
✅ Use consistent verb prefixes (get, create, update, delete)
✅ Name based on route structure for page-level APIs
✅ Use camelCase for function names

DON’T

❌ Use single-word names like data(), fetch(), get()
❌ Use unclear abbreviations
❌ Mix naming patterns within the same file
❌ Use prefixes like do or suffixes like Func
❌ Omit action verbs for functions that perform actions

Quick Reference

Function Type	Pattern	Example
Page API	{routeName}PageAPI()	articlesPageAPI()
Page API (Dynamic)	{singularEntity}PageAPI()	articlePageAPI()
Component API	{componentName}API()	saveButtonAPI()
Validation	validate{Entity}{Purpose}()	validateArticlePageAPI()
Transform	transform{Entity}Data()	transformArticleData()
Format	format{Entity}()	formatReadingTime()
Boolean Check	is{Condition}()	isValidSlug()
Property Check	has{Property}()	hasRequiredFields()
Error Handling	handle{Context}Error()	handleGraphQLError()

Related

• GraphQL Naming - GraphQL operation naming patterns
• File Organization - Where to place API files
• Naming Conventions Guide - Comprehensive naming guide with examples