Variables

Workflow

1. Inspect the consuming repository's conventions and configuration.
2. Let explicit repository conventions take precedence over this opinionated guidance.
3. Apply, review, or explain only the guidance relevant to the task.
4. State important tradeoffs when the appropriate choice depends on context or judgment.

Boundaries

• Keep TypeScript and ESLint responsible for checks they can enforce automatically.
• Do not introduce unrelated TypeScript Style Guide conventions merely because this skill is active.

Related Guidance

Application State

typescript-discriminated-unions

Variables

Const Assertion

as const

• Type Narrowing - Using

  as const

  ensures that literal values (e.g., numbers, strings) are treated as exact values instead of generalized types like

  number

  or

  string

  .
• Readonly Properties - Objects and arrays get readonly properties, so TypeScript catches direct mutations.

• Objects
  ts

  // ❌ Avoid
  const FOO_LOCATION = { x: 50, y: 130 }; // Type { x: number; y: number; }
  FOO_LOCATION.x = 10;
  
  // ✅ Use
  const FOO_LOCATION = { x: 50, y: 130 } as const; // Type '{ readonly x: 50; readonly y: 130; }'
  FOO_LOCATION.x = 10; // Error

• Arrays
  ts

  // ❌ Avoid
  const BAR_LOCATION = [50, 130]; // Type number[]
  BAR_LOCATION.push(10);
  
  // ✅ Use
  const BAR_LOCATION = [50, 130] as const; // Type 'readonly [50, 130]'
  BAR_LOCATION.push(10); // Error

• Template Literals
  ts

  // ❌ Avoid
  const RATE_LIMIT = 25;
  const RATE_LIMIT_MESSAGE = `Max number of requests/min is ${RATE_LIMIT}.`; // Type string
  
  // ✅ Use
  const RATE_LIMIT = 25;
  const RATE_LIMIT_MESSAGE = `Max number of requests/min is ${RATE_LIMIT}.` as const; // Type 'Max number of requests/min is 25.'

Enums & Const Assertion

'no-restricted-syntax': [     'error',     {       selector: 'TSEnumDeclaration',       message: 'Replace enum with a literal type or a const assertion.',     }, ]

• Literal types whenever possible.
• Const assertion arrays when looping through values.
• Const assertion objects when enumerating arbitrary values.

• Use literal types to avoid runtime objects and reduce bundle size.
  ts

  // ❌ Avoid using enums as they increase the bundle size
  enum UserRole {
    GUEST = 'guest',
    MODERATOR = 'moderator',
    ADMINISTRATOR = 'administrator',
  }
  
  // Transpiled JavaScript
  ('use strict');
  var UserRole;
  (function (UserRole) {
    UserRole['GUEST'] = 'guest';
    UserRole['MODERATOR'] = 'moderator';
    UserRole['ADMINISTRATOR'] = 'administrator';
  })(UserRole || (UserRole = {}));
  
  // ✅ Use literal types - Types are stripped during transpilation
  type UserRole = 'guest' | 'moderator' | 'administrator';
  
  const isGuest = (role: UserRole) => role === 'guest';

• Use const assertion arrays when looping through values.
  tsx

  // ❌ Avoid using enums
  enum USER_ROLES {
    guest = 'guest',
    moderator = 'moderator',
    administrator = 'administrator',
  }
  
  // ✅ Use const assertions arrays
  const USER_ROLES = ['guest', 'moderator', 'administrator'] as const;
  type UserRole = (typeof USER_ROLES)[number];
  
  const seedDatabase = () => {
    USER_ROLES.forEach((role) => {
      db.roles.insert(role);
    }
  }
  const insert = (role: UserRole) => {...
  
  const UsersRoleList = () => {
    return (
      <div>
        {USER_ROLES.map((role) => (
          <Item key={role} role={role} />
        ))}
      </div>
    );
  };
  const Item = ({ role }: { role: UserRole }) => {...

• Use const assertion objects when enumerating arbitrary values.
  ts

  // ❌ Avoid using enums
  enum COLORS {
    primary = '#B33930',
    secondary = '#113A5C',
    brand = '#9C0E7D',
  }
  
  // ✅ Use const assertions objects
  const COLORS = {
    primary: '#B33930',
    secondary: '#113A5C',
    brand: '#9C0E7D',
  } as const;
  
  type Colors = typeof COLORS;
  type ColorKey = keyof Colors; // Type "primary" | "secondary" | "brand"
  type ColorValue = Colors[ColorKey]; // Type "#B33930" | "#113A5C" | "#9C0E7D"
  
  const setColor = (color: ColorValue) => {...
  
  setColor(COLORS.primary);
  setColor('#B33930');

Type Union & Boolean Flags

// ❌ Avoid introducing multiple boolean flag variables
const isPending, isProcessing, isConfirmed, isExpired;

// ✅ Use type union variable
type UserStatus = 'pending' | 'processing' | 'confirmed' | 'expired';
const userStatus: UserStatus;

Null & Undefined

strictNullChecks

null

undefined

• Use

  null

  when a value is explicitly empty, such as an assignment or function return value.
• Use

  undefined

  when a value is missing or omitted, such as an optional field in a form, request payload, or database query (Prisma differentiation).