bee-jokes/dist/index.d.mts

bee-jokes is a lightweight TypeScript/JavaScript package that delivers clean, categorized, and multilingual jokes — fast and ready to sting your apps with humor!

type Lang = 'en' | 'hi' | 'es' | 'fr' | 'de' | 'it' | 'pt' | 'ru' | 'ja' | 'ko' | 'bn' | 'ur' | 'zh' | 'ar' | 'ta' | 'te' | 'gu' | 'ml' | 'pa' | 'mr';
type Category = 'programming' | 'general' | 'dadjokes' | 'puns' | 'science' | 'officelife' | 'animals' | 'relationships' | 'school' | 'food' | 'sports' | 'history' | 'travel' | 'medical' | 'tech' | 'music' | 'financial' | 'popculture' | 'holiday' | 'family' | 'sarcasm';
interface IJoke {
    id: string;
    joke: string;
    category: Category;
    langCode: Lang;
    tags: string[];
}
type GetJokeByIdParam = string;
interface IGetJokesParams {
    category?: Category;
    lang?: Lang;
}
interface IGetManyJokesParams {
    category?: Category;
    lang?: Lang;
    range?: number;
}
interface IGetSafeJokesParams {
    category?: Category;
    lang?: Lang;
    range?: number;
}
interface ILanguage {
    code: string;
    language: Lang;
}
interface ICategory {
    name: Category;
    description: string;
}

declare class Joke {
    /**
     * Retrieves a joke by its unique ID.
     *
     * @param id - The ID of the joke to retrieve.
     * @returns The matching joke object if found, otherwise `null`.
     */
    getJokeById(id: GetJokeByIdParam): null | IJoke;
    /**
     * Retrieves all jokes
     * @returns A list of all available jokes
     */
    getAllJokes(): IJoke[];
    /**
     * Retrieves a single joke based on the specified category and language.
     *
     * @param category - The category of the joke (defaults to `"programming"` if not provided).
     * @param lang - The language code for the joke (defaults to `"en"` if not provided).
     * @returns A matching joke object if found, otherwise `null`.
     */
    getJoke({ category, lang }: IGetJokesParams): IJoke | null;
    /**
     * Retrieves multiple jokes based on the specified category, language, and range.
     *
     * @param category - The category of jokes to retrieve (defaults to `"programming"`).
     * @param lang - The language code for the jokes (defaults to `"en"`).
     * @param range - The maximum number of jokes to return (defaults to `10`).
     * @returns An array of jokes matching the filters, limited by the given range, or `null` if no jokes are found.
     */
    getManyJokes({ category, lang, range, }: IGetManyJokesParams): IJoke[] | null;
    /**
     * Retrieves jokes that contain at least one of the specified keyword tags.
     *
     * @param tags - An array of keyword tags to match against joke tags.
     * @param range - The maximum number of jokes to return (defaults to `10`).
     * @returns An array of jokes that match at least one tag, limited by the given range, or `null` if no matches are found.
     */
    getJokeByKeyword(tags: string[], range?: number): IJoke[] | null;
    /**
     * Retrieves a random joke in the specified language.
     *
     * @param lang - The language code of the joke (defaults to `"en"` for English).
     * @returns A joke object in the given language if available, otherwise `null`.
     */
    getRandomJoke(lang?: Lang): IJoke | null;
    /**
     * Retrieves a list of safe jokes based on the specified category, language, and range.
     * Safe jokes are filtered using the `filterSafeJokes` utility.
     *
     * @param category - The category of jokes to retrieve (defaults to `"programming"`).
     * @param lang - The language code for the jokes (defaults to `"en"`).
     * @param range - The maximum number of safe jokes to return (defaults to `10`).
     * @returns An array of safe jokes limited by the given range, or `null` if no safe jokes are found.
     */
    getSafeJokes({ category, lang, range, }: IGetSafeJokesParams): IJoke[] | null;
    /**
     * Retrieves the list of supported languages.
     *
     * @returns An array of language objects, each containing a language code and its corresponding name.
     */
    getLanguages(): ILanguage[];
    /**
     * Retrieves the list of available joke categories.
     *
     * @returns An array of category objects, each containing the category name.
     */
    getCategories(): ICategory[];
}

export { type Category, type GetJokeByIdParam, type ICategory, type IGetJokesParams, type IGetManyJokesParams, type IGetSafeJokesParams, type IJoke, type ILanguage, Joke, type Lang };