Types

All types are defined in typings.ts and re-exported from the package root. Import them with the type keyword:

import { type Insult, type InsultPack, type InsultPackMap, type InsultPackInfo, type CreateArrayConfig } from 'demotivator';

Insult

type Insult = string;

A semantic alias for string. Every insult in the package is typed as Insult rather than raw string to improve readability across the codebase. You can use it interchangeably with string — it exists purely for intent signaling.

InsultPack

interface InsultPack {
  key: string;
  title: string;
  explicit: boolean;
  insults: Insult[];
}

Represents a single themed collection of insults. Each pack has:

• key — A unique identifier used to look up the pack (e.g. 'original', 'profane').
• title — A human-readable display name (e.g. 'Halloween 🎃').
• explicit — Whether the pack contains profanity or mature content. Useful for filtering in consumer applications.
• insults — The array of Insult strings belonging to this pack.

InsultPackMap

type InsultPackMap = Record<string, InsultPack>;

A dictionary that maps pack keys to their InsultPack definitions. This is the type of the exported insultPacks object, which lets you look up any pack by its string key.

InsultPackKey

type InsultPackKey = keyof typeof import('./insults').insultPacks;

A union of the literal string keys for every built-in insult pack. As of the current version, this resolves to:

'original' | 'profane' | 'halloween' | 'christmas' | 'valentines' | 'stPatricks'

This type is derived directly from the insultPacks object at compile time, so it updates automatically when new packs are added to the source. It is used to enforce type safety on functions like createArray, ensuring you can only pass valid pack identifiers.

CreateArrayConfig<TPackKey>

interface CreateArrayConfig<TPackKey extends string = InsultPackKey> {
  packs: TPackKey[];
  customPacks?: InsultPack[];
}

The configuration object accepted by createArray. It has two fields:

• packs — An array of built-in pack keys to include. The generic parameter TPackKey defaults to InsultPackKey, which means you get autocomplete and compile-time validation of pack names out of the box.
• customPacks (optional) — An array of user-supplied InsultPack objects. Their insults are appended after those from packs. Duplicate key values within customPacks are deduplicated — only the first occurrence of each key is used.

Example

import { defineCustomPack, createArray, type CreateArrayConfig } from 'demotivator';

// TypeScript will error if you pass an invalid built-in pack key
const config: CreateArrayConfig = {
  packs: ['original', 'halloween'],
};

// Extend with your own insults via customPacks
const myPack = defineCustomPack({ key: 'byoi', title: 'My Pack', explicit: false, insults: ['You tried.'] });
const poolWithCustom = createArray({ packs: ['original'], customPacks: [myPack] });

InsultPackInfo<TPackKey>

interface InsultPackInfo<TPackKey extends string = InsultPackKey> {
  insult: Insult;
  packKey: TPackKey;
  packTitle: string;
  explicit: boolean;
  position: number;
}

The metadata object returned by packInfo. It tells you where a specific insult was found in the built-in pack registry.

• insult — The exact insult string you looked up.
• packKey — The key of the first matching pack.
• packTitle — Human-readable title for that pack.
• explicit — Whether the pack is marked explicit.
• position — 1-based insult position inside the pack, compatible with insultAt.

packInfo can be called with:

• packInfo(insult)
• packInfo(position, array?)
• packInfo(searchResult, array?) where searchResult comes from searchInsults(..., true)

__DeMotivator<TPackKey>

interface __DeMotivator<TPackKey extends string = InsultPackKey> {
  insults: Insult[];
  profaneInsults: Insult[];
  halloweenInsults: Insult[];
  christmasInsults: Insult[];
  valentinesInsults: Insult[];
  stPatricksInsults: Insult[];
  insultPacks: InsultPackMap;
  insultPackList: InsultPack[];
  createArray: (configuration: CreateArrayConfig<TPackKey>) => Insult[];
  defineCustomPack: (pack: InsultPack) => InsultPack;
  generateInsult: (array: Insult[]) => Insult;
  insultAt: (position: number, array: Insult[]) => Insult;
  searchInsults: SearchInsultsFunction;
  purify: (insult: Insult, symbol?: string) => Insult;
  packInfo: PackInfoFunction<TPackKey>;
  porkify: (insult: Insult, amount?: number) => Insult;
  makeAngry: (insult: Insult, exclamationCount?: number) => Insult;
}

The internal interface that both the deMotivator plain object and the DeMotivator class implement. It defines the full shape of the package’s API surface. The double-underscore prefix signals that this type is intended for internal use — you generally won’t need to reference it directly, but it is exported for advanced use cases like building custom wrappers.