Snappy.Kit

Snappy.Kit is a lightweight, zero-dependency TypeScript utility library for working with the DOM, primitives (strings and numbers), events, HTML, and more. Designed for component-based development without the overhead of a framework.

Installation

npm install snappykit

Import

All utilities are organized into logical modules. Import directly from the package:

import {
  css,
  addClass,
  make,
  show, // DOM
  on,
  off,
  rebind, // Events
  formatBytes,
  toCamelCase, // Primitives (String and Number Utils)
  parseHtml,
  escapeHtml, // HTML
  createStore, // Store
  // ...
} from 'snappykit';

API Reference

1. Primitives (String and Number Utils)

Functions for string and number validation, transformation, and formatting.

| Method | Arguments | Return | Description | | --------------- | ------------------------------------------------------------------------------ | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | isEmptyString | (str: string \| null \| undefined) | boolean | Returns true if the string is empty, null, undefined, or contains only whitespace/invisible characters. | | isNullOrEmpty | (str: string \| null \| undefined) | boolean | Returns true if the string is null, undefined, or "". | | isWhitespace | (str: string) | boolean | Returns true if the string is not empty but consists entirely of whitespace. | | upper | (str: string) | string | Converts the entire string to uppercase. | | lower | (str: string) | string | Converts the entire string to lowercase. | | upperFirst | (str: string) | string | Converts the first character to uppercase, leaving the rest unchanged. | | lowerFirst | (str: string) | string | Converts the first character to lowercase, leaving the rest unchanged. | | replaceAll | (find: string, replace: string, str: string) | string | Replaces all occurrences of find with replace (no regex, uses split-join). | | truncate | (str: string, maxLength: number, suffix?: string, cutFromStart?: boolean) | string | Truncates the string to maxLength and appends suffix (default "..."). If cutFromStart is true, truncates from the beginning. | | toCamelCase | (str: string) | string | Converts kebab-case, snake_case, or space-separated strings to camelCase. | | toKebabCase | (str: string) | string | Converts camelCase, PascalCase, or snake_case to kebab-case. | | toSnakeCase | (str: string) | string | Converts camelCase, PascalCase, or kebab-case to snake_case. | | reverse | (str: string) | string | Reverses the string. | | formatBytes | (bytes: number, decimals?: number, forcedLocale?: string) | string | Formats a byte count into a human-readable string (e.g., "1.5 MB"). | | randString | (length: number, charset?: "alphanumeric" \| "alpha" \| "numeric" \| "hex") | string | Generates a random string of the given length using the specified charset (default "alphanumeric"). | | mask | (str: string, startVisible?: number, endVisible?: number, maskChar?: string) | string | Masks the middle portion of a string, leaving startVisible and endVisible characters visible (default 4). Uses maskChar (default "*") for hidden characters. | | pluralize | (number: number, forms: [string, string, string], showNumber?: boolean) | string | Returns the correct plural form for a number using 3 pluralization rules. |

2. DOM Utilities

DOM manipulation, traversal, creation, and style management.

| Method | Arguments | Return | Description | | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | css | (element: HTMLElement, prop: string \| Record<string, string \| number \| null>, value?: string \| number \| null) | string | Gets or sets CSS styles. Accepts camelCase or kebab-case property names, or an object of properties. Numeric values get "px" appended automatically. Returns computed style when getting. | | hasClass | (element: HTMLElement \| null, className: string) | boolean | Checks if the element has the specified CSS class. | | addClass | (el: HTMLElement, className: string \| string[]) | void | Adds one or more CSS classes to the element. | | removeClass | (el: HTMLElement, className: string \| string[]) | void | Removes one or more CSS classes from the element. | | toggleClass | (el: HTMLElement, className: string \| string[]) | void | Toggles one or more CSS classes on the element. | | make | <T extends HTMLElement = HTMLElement>(name: string, callback?: (el: T) => void) | T | Creates a new HTML element. An optional callback receives the created element for further configuration. | | makeText | (content?: string) | Text | Creates a new text node with the given content. | | remove | (element: Element \| Element[] \| NodeListOf<Element> | void | Removes the element from its parent in the DOM. | | query | <T extends Element = Element>(selector: string, callback: (el: T, index: number) => void, context: Element \| Document = document) | number | Queries elements matching the CSS selector and executes callback for each. Returns the number of matched elements. | | queryList | <T extends Element = Element>(selector: string, context: Element \| Document = document) | T[] | Returns an array of all elements matching the CSS selector. | | queryLength | (selector: string, context: Element \| Document = document) | number | Returns the count of elements matching the CSS selector. | | html | (el: HTMLElement, value?: string \| null): string; (el: HTMLElement, value: string): HTMLElement; | string \| HTMLElement | Gets or sets the innerHTML of an element. Returns the HTML string when getting, returns the element when setting. | | toHtml | (data: string \| Node \| Node[] \| HTMLElement \| HTMLElement[]) | string | Converts a node, element, array of nodes/elements, or string to an HTML string representation. | | append | <T extends DomNode = DomNode>(el: T, child: DomChildNode) | T | Appends a child node, NodeList, or array of nodes to the end of the parent element. Returns the parent. | | prepend | <T extends DomNode = DomNode>(el: T, child: DomChildNode) | T | Prepends a child node, NodeList, or array of nodes to the beginning of the parent element. Returns the parent. | | before | <T extends Element>(el: T): Element \| null; (el: T, child: DomChildNode): T; | T \| Element \| null | Inserts a node or array of nodes before the reference element. Returns the reference element. | | after | <T extends Element>(el: T): Element \| null; (el: T, child: DomChildNode): T; | T \| Element \| null | Inserts a node or array of nodes after the reference element. Returns the reference element. | | attr | (el: Element \| HTMLElement, key: string \| Record<string, string>, value?: string) | string \| undefined \| void | Gets or sets an attribute on an element. Accepts a single key-value pair or an object of attributes. Returns the attribute value when getting. | | removeAttr | (el: Element \| HTMLElement, attrName: string \| string[]) | void | Removes an attribute or array of attributes from the element. | | data | (el: HTMLElement, key: string \| Record<string, string>, value?: string) | string \| undefined \| void | Gets or sets a data-* attribute on an element. Accepts a single key-value pair or an object. Returns the value when getting. | | dataByPrefix | (element: HTMLElement, prefix: string) | Record<string, string \| number> | Retrieves all data-* attributes that start with the given prefix. Keys are camelCased, and numeric values are parsed to numbers. | | val | (el: ValueElement): string; (el: ValueElement, value: string): ValueElement; | string \| ValueElement | Gets or sets the value of a form element. Returns the value when getting, returns the element when setting. | | closest | <C extends Node = HTMLElement, P extends Node = HTMLElement>(child: C \| EventTarget \| null, parent: P \| EventTarget \| null) | P \| false | Walks up the DOM tree from child and returns the parent if found in the ancestry, otherwise false. | | offset | (el: HTMLElement) | { top: number; left: number } | Returns the element's position relative to the document, accounting for scroll offset. | | outerSize | (el: HTMLElement) | { width: number; height: number } | Returns the element's outer dimensions including margin. | | empty | <T extends HTMLElement = HTMLElement>(el: T) | T | Removes all child nodes from the element. Returns the emptied element. | | show | (el: VisibleElement) | void | Shows a previously hidden element by restoring its display value. | | hide | (el: VisibleElement) | void | Hides the element and stores its current display value for later restoration. | | toggle | (el: VisibleElement) | void | Toggles the visibility of the element. | | appendText | (el: DomNode, text: string) | DomNode | Appends a text node to the element. | | toTextNode | (text: string) | Node | Creates a text node from the given string. | | mergeAdjacentTextNodes | (element: HTMLElement) | void | Merges all adjacent text nodes within the element into single text nodes. | | replaceWithChildren | (element: HTMLElement) | void | Replaces the element with its child nodes, effectively removing the wrapper element. | | getChildNodes | (element: Node) | Node[] | Returns an array of all child nodes of the element. | | getText | (node: Node \| Node[]) | string | Returns the combined textContent of a node or array of nodes. | | getLength | (node: Node \| Node[]) | number | Returns the total text length of a node or array of nodes. |

Types:

type DomNode = Node | Element | HTMLElement;
type DomChildNode = Node | Node[] | NodeList;
type ValueElement = HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement;
type VisibleElement = HTMLElement & { __visibleStatus?: string };

3. Event Utilities

Wraps native addEventListener/removeEventListener with automatic handler tracking and namespacing.

| Method | Arguments | Return | Description | | -------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | on | (element: HTMLElement \| Document \| Window, eventName: string, handler: EventHandler<T>, options?: AddEventListenerOptions \| boolean) | void | Registers an event listener with automatic tracking. Supports ID namespacing via dot notation (e.g., "click.myButton"). Overwrites existing handlers with the same ID. | | off | (element: HTMLElement \| Document \| Window, eventName: string, options?: AddEventListenerOptions \| boolean) | void | Removes a tracked event listener. If an ID is provided (e.g., "click.myButton"), removes only that specific handler. If no ID is given, removes all tracked handlers for that event type. | | rebind | (element: HTMLElement \| Document \| Window, eventName: string, handler: EventHandler<T>, options?: AddEventListenerOptions \| boolean) | void | Convenience method that calls off() followed by on() to replace an existing listener with a new handler. |

Types:

export type EventHandler<T extends Event = Event> = (evt: T) => void;

4. HTML Utilities

Safe HTML string manipulation and parsing.

| Method | Arguments | Return | Description | | --------------- | ------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | stripHtml | (str: string) | string | Removes all HTML tags from the string, leaving only text content. | | stripFragment | (html: string) | string | Removes <!--StartFragment--> and <!--EndFragment--> wrapper tags, commonly found in clipboard or editor output. | | escapeHtml | (input: string) | string | Escapes HTML special characters (&, ", ', <, >) into their corresponding HTML entities. | | decodeHtml | (input: string) | string | Decodes common HTML entities (&, ", ', <, >) back to their characters. | | parseHtml | (html: string, isStripFragment?: boolean) | Node[] | Parses an HTML string into an array of DOM nodes using DOMParser. If isStripFragment is true, strips fragment tags before parsing. |

5. Store Utility

Lightweight key-value storage.

createStore

| Method | Arguments | Return | Description | | ------------- | ------------------------------------ | ---------- | ------------------------------------------------ | | createStore | <T extends object>(storeObject: T) | Store<T> | Creates a store instance from an initial object. |

Store API (Store<T>)

| Method | Arguments | Return | Description | | -------- | ------------------------------------------ | ------------ | ----------------------------------------------------------------------------------- | | get | (key: keyof T) | T[keyof T] | Retrieves the value associated with the given key. | | set | <K extends keyof T>(key: K, value: T[K]) | void | Sets the value for the given key. | | has | (key: string) | boolean | Returns true if the key exists in the store. | | delete | (key: keyof T) | boolean | Deletes the key from the store. Returns true if the key was successfully deleted. |

Example:

import { createStore } from 'snappykit';

const userStore = createStore<{ name: string; age: number }>({ name: 'Alice', age: 25 });

userStore.get('name'); // "Alice"
userStore.set('name', 'Bob');
userStore.has('age'); // true
userStore.delete('age'); // true

License

MIT