TypeScript Integration

Use the local ESM module

The repository includes index.d.ts declarations. Keep the declaration and the two JavaScript files in your local helper folder, then import the ESM entry.

import SoftHoursDiary, {
  emojiUrl,
  flagUrl,
  flagIconUrl
} from "./soft-hours-diary.esm.mjs";

export { emojiUrl, flagUrl, flagIconUrl };
export default SoftHoursDiary;

Typed asset options

The declarations expose unions for the quality values supported by each collection.

import {
  getUrl,
  type AssetOptions,
  type EmojiQuality,
  type FlagQuality,
  type FlagIconQuality
} from "./lib/shd";

const emojiOptions: AssetOptions = {
  type: "emoji",
  quality: "svg",
  id: "1f632"
};

const flagOptions: AssetOptions = {
  type: "flag",
  quality: "l",
  id: "IN"
};

const emojiSrc: string = getUrl(emojiOptions);
const flagSrc: string = getUrl(flagOptions);

Use the exact unions: emoji svg | png, flag s | m | l, flag icon 1x1 | 4x3.

Helper function types

import {
  emojiUrl,
  flagUrl,
  flagIconUrl
} from "./lib/shd";

const emoji: string = emojiUrl("1f632", {
  quality: "svg"
});

const flag: string = flagUrl("IN", {
  quality: "l"
});

const icon: string = flagIconUrl("IN", {
  quality: "4x3"
});

Custom element JSX typing

If your React JSX runtime reports an unknown custom element, add a local declaration in your application rather than weakening all JSX types.

import type { DetailedHTMLProps, HTMLAttributes } from "react";

type ShdAttributes = DetailedHTMLProps<
  HTMLAttributes,
  HTMLElement
> & {
  type?: "emoji" | "flag" | "flags";
  "asset-id"?: string;
  quality?: string;
  alt?: string;
  width?: number | string;
  height?: number | string;
};

declare global {
  namespace JSX {
    interface IntrinsicElements {
      "shd-asset": ShdAttributes;
      "shd-emoji": ShdAttributes;
      "shd-flag": ShdAttributes;
      "shd-flag-icon": ShdAttributes;
    }
  }
}

Runtime error handling

Static types help during development, but runtime validation remains active. Catch errors when the asset ID or quality comes from user-controlled or external data.

function safeAssetUrl(
  options: AssetOptions
): string | null {
  try {
    return SoftHoursDiary.getUrl(options);
  } catch (error) {
    console.warn("Invalid asset options", error);
    return null;
  }
}

A typed URL still may point to a file that is missing from the CDN. Types cannot confirm network availability.

Package status