utils
Create utility functions with one function per file
📖 中文导读:Create utility functions with one function per file 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。
name: utils description: Create utility functions with one function per file
Utility Functions
Write utility functions in src/utils/ that provide pure, reusable logic.
Requirements
- File naming: camelCase matching function name (e.g.,
findFreePosition.ts) - One function per file - enforced by ESLint
- No world/store access - pure functions only
Pattern
/**
* Function Name
*
* Brief description of what the function does.
*/
import { SOME_CONSTANT } from '../constants/domain';
import type { SomeType } from '../types/domain';
interface FunctionNameProps {
requiredParam: string;
optionalParam?: number | undefined;
}
interface FunctionNameReturn {
result: string;
metadata: number;
}
export function functionName(props: FunctionNameProps): FunctionNameReturn {
const { requiredParam, optionalParam } = props;
// Implementation
const result = requiredParam.toUpperCase();
const metadata = optionalParam ?? 0;
return { result, metadata };
}
Rules
- One function per file - File name matches function name
- Props interface - All parameters via single props object (unless single primitive)
- Return interface - Define return type for complex returns
- Pure functions - No side effects, no world/store access
- JSDoc header - Brief description at top of file
Shared Types
Use shared props types from src/types/ to reduce duplication:
import type { GridDimensionsProps, ItemDimensionsProps } from '../types/inventory';
interface MyFunctionProps extends GridDimensionsProps, ItemDimensionsProps {
additionalProp: string;
}
Simple Functions
For simple single-parameter functions, skip the props object:
// OK for simple cases
export function capitalizeString(value: string): string {
return value.charAt(0).toUpperCase() + value.slice(1);
}
Examples
Good utils:
findFreePosition- finds available grid positionisSpaceFree- checks if grid cells are unoccupiedshuffleArray- randomizes array orderrandomInt- generates random integer in range
Bad (belong elsewhere):
getEquippedItems- needs world access (use query)moveItem- mutates world (use system)GRID_SIZE- constant value (use constants)