@dvirus-js/utils 0.0.7 → 0.0.13

package/lib/get-empty-keys.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Returns the keys whose values are considered empty.
+ *
+ * Empty values are:
+ * - empty string (`''`)
+ * - `null`
+ * - `undefined`
+ *
+ * @template T Object type to inspect.
+ * @param obj Object to scan.
+ * @returns Array of keys from `obj` whose values are empty.
+ *
+ * @example
+ * getEmptyKeys({ title: '', count: 0, note: undefined });
+ * // ['title', 'note']
+ */
+export declare function getEmptyKeys<T extends object>(obj: T): (keyof T)[];
+/**
+ *  Joins an array of strings into a human-readable sentence.
+ *
+ * Example:
+ * ```ts
+ * joinToSentence(["Title", "Content"])           //  "Title and Content"
+ * joinToSentence(["Title", "Content", "Author"]) //  "Title, Content and Author"
+ * ```
+ * @param arr - Array of strings to join
+ * @returns A human-readable sentence
+ */
+export declare function joinToSentence(arr: string[]): string;

package/lib/html-text-parser/api.d.ts

@@ -0,0 +1,62 @@
+import { setCssClassPrefix } from './constant';
+import { appendToDom } from './dom-renderer';
+import { generateStylesheet, getStylesheet, setOverrideStyles } from './stylesheet';
+import { groupSegments, parseSegments } from './parsing';
+import { removeBlockTag, setBlockTag, setSelfClosingTag, setTag } from './tags';
+import { BlockGroup, TextSegment, RichTextOverrideStyles } from './types';
+type _TextSegment = TextSegment;
+type _BlockGroup = BlockGroup;
+type _RichTextOverrideStyles = RichTextOverrideStyles;
+export interface HtmlTextParser {
+    /**
+     * Parse an input string and append safe DOM nodes into the target element.
+     * This avoids `innerHTML` and only creates known elements explicitly.
+     */
+    appendToDom: typeof appendToDom;
+    /** Parse input into flat text segments with active tag context. */
+    parseSegments: typeof parseSegments;
+    /** Group flat segments by their active block/container tags. */
+    groupSegments: typeof groupSegments;
+    /** Register custom inline/block tags and optional style mappings. */
+    setTag: typeof setTag;
+    /** Register custom self-closing tags and optional style mappings. */
+    setSelfClosingTag: typeof setSelfClosingTag;
+    /** Mark a tag as block/container. */
+    setBlockTag: typeof setBlockTag;
+    /** Remove block/container behavior for a tag. */
+    removeBlockTag: typeof removeBlockTag;
+    /** Set the CSS class prefix used by generated classes (default: `rtp-`). */
+    setCssClassPrefix: typeof setCssClassPrefix;
+    /** Get the generated stylesheet content as a string. */
+    getStylesheet: typeof getStylesheet;
+    /** Inject or refresh the parser stylesheet in `document.head`. */
+    generateStylesheet: typeof generateStylesheet;
+    /** Override per-tag stylesheet fragments (merged with `!important`). */
+    overrideStyles: typeof setOverrideStyles;
+}
+/**
+ * Rich text parser toolkit.
+ * Useful for dialog or toast content, or any time you want to allow rich text input without trusting raw HTML.
+ *
+ * Includes safe DOM rendering (`appendToDom`), parsing utilities,
+ * tag registration, and stylesheet customization methods.
+ */
+export declare const htmlTextParser: HtmlTextParser;
+/**
+ * Namespace-style type access for html-text-parser.
+ *
+ * @example
+ * const segment: HtmlTextParser.TextSegment = {
+ *   text: 'Hello',
+ *   tagNames: '',
+ *   tagNamesList: [],
+ *   containerTagNames: [],
+ *   cssClass: '',
+ * };
+ */
+export declare namespace HtmlTextParser {
+    type TextSegment = _TextSegment;
+    type BlockGroup = _BlockGroup;
+    type OverrideStyles = _RichTextOverrideStyles;
+}
+export {};

package/lib/html-text-parser/constant.d.ts

@@ -16,4 +16,3 @@ export declare function setCssClassPrefix(prefix: string): void;
  * Example: `<br/>` creates an empty segment with the `br` style key.
  */
 export declare const SELF_CLOSING_TAGS: Map<string, string>;
-export declare const styleTagMap: Map<string, Map<string, string>>;

package/lib/html-text-parser/dom-renderer.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Parses a rich-text string and appends the result as real DOM nodes.
+ * This is a **safe alternative to `innerHTML`** — no HTML parsing happens in the browser.
+ *
+ * Supported tags: `<b>/<strong>`, `<i>/<em>`, `<u>`, `<s>`, `<mark>`, `<small>`,
+ * `<sup>`, `<sub>`, `<h1>`–`<h6>`, `<code>`, `<span>`, `<p>`, `<div>`,
+ * `<ul>`, `<ol>`, `<li>`, `<br/>`, `<hr/>`
+ *
+ * @example
+ * // replaces: element.innerHTML = 'Hello <b>world</b>!';
+ * htmlTextParser.appendToDom(element, 'Hello <b>world</b>!');
+ *
+ * @example
+ * // Disable generated classes entirely
+ * htmlTextParser.appendToDom(element, '<mark>highlight</mark>', { useClasses: false });
+ */
+export declare function appendToDom<T extends object>(htmlElement: T, input: string): void;

package/lib/html-text-parser/grouping.d.ts

@@ -0,0 +1,2 @@
+import { BlockGroup, TextSegment } from './types';
+export declare function groupSegments(segments: TextSegment[]): BlockGroup[];

package/lib/html-text-parser/index.d.ts

@@ -1,2 +1,2 @@
-export * from './html-text-parser';
-export type { TextSegment, BlockGroup } from './types';
+export * from './api';
+export * from './types';

package/lib/html-text-parser/parsing.d.ts

@@ -0,0 +1,26 @@
+import { BlockGroup, TextSegment } from './types';
+/**
+ * Parses a rich text string into a flat array of typed segments.
+ * Each segment carries its text, active tag names, CSS class, and inline style info.
+ *
+ * @example
+ * parseSegments('Hello <b>world</b>!')
+ * // [
+ * //   { text: 'Hello ',  tagNamesList: [],    cssClass: '' },
+ * //   { text: 'world',   tagNamesList: ['b'], cssClass: 'rtp-b' },
+ * //   { text: '!',       tagNamesList: [],    cssClass: '' },
+ * // ]
+ */
+export declare function parseSegments(input: string): TextSegment[];
+/**
+ * Groups a flat segment array by block/container context.
+ * Consecutive segments sharing the same container tags are merged into one `BlockGroup`.
+ *
+ * @example
+ * groupSegments(parseSegments('<p>Hello <b>world</b></p> outside'))
+ * // [
+ * //   { containerTagNames: ['p'], segments: [...] },
+ * //   { containerTagNames: [],    segments: [...] },
+ * // ]
+ */
+export declare function groupSegments(segments: TextSegment[]): BlockGroup[];

package/lib/html-text-parser/segment.d.ts

@@ -0,0 +1,2 @@
+import { TextSegment } from './types';
+export declare const createTagSegment: (activeTagsKeys: string[], input: string, lastIndex: number, index: number, text?: string) => TextSegment;

package/lib/html-text-parser/stylesheet.d.ts

@@ -0,0 +1,21 @@
+import { RichTextOverrideStyles } from './types';
+/** Returns the full CSS stylesheet string for all registered tags. */
+export declare function getStylesheet(): string;
+/**
+ * Injects (or refreshes) a `<style>` tag in the document `<head>`.
+ * Safe to call multiple times — updates the existing tag if already present.
+ */
+export declare function generateStylesheet(): void;
+/**
+ * Overrides default CSS for specific tags.
+ * Values are CSS property strings, e.g. `"color: red; font-size: 1.2em;"`.
+ * All overrides are automatically marked `!important`.
+ * Calling this in a browser re-injects the stylesheet immediately.
+ *
+ * @example
+ * setOverrideStyles({
+ *   mark: 'background-color: pink; color: black;',
+ *   code: 'font-family: "Fira Code", monospace;',
+ * });
+ */
+export declare function setOverrideStyles(newStyles: RichTextOverrideStyles): void;

package/lib/html-text-parser/tag-regex.d.ts

@@ -0,0 +1,3 @@
+export declare const getTagNames: () => string;
+export declare const getSelfClosingTagNames: () => string;
+export declare const getTagRegex: () => RegExp;

package/lib/html-text-parser/tags.d.ts

@@ -0,0 +1,43 @@
+type TagConfig = {
+    tag: string;
+    tagName?: string;
+};
+/**
+ * Register a new supported tag for the parser.
+ *
+ * Use this when you want the parser to recognize custom tags and optionally map
+ * them to another normalized tag key.
+ *
+ * @example
+ * registerTag({ tag: 'kbd' });
+ *
+ * @example
+ * registerTag([
+ *   { tag: 'kbd' },
+ *   { tag: 'del', tagName: 's' },
+ * ]);
+ */
+export declare function setTag(tag: TagConfig): void;
+export declare function setTag(tags: TagConfig[]): void;
+/**
+ * Register a self-closing tag (for example `<br/>`, `<hr/>`) so it can be
+ * parsed as an element even when there is no text content.
+ *
+ * @example
+ * setSelfClosingTag({
+ *   tag: 'divider',
+ *   tagName: 'hr',
+ * });
+ */
+export declare function setSelfClosingTag(tag: TagConfig): void;
+export declare function setSelfClosingTag(tags: TagConfig[]): void;
+/**
+ * Mark a tag as a block/container tag.
+ * Block tags wrap grouped segments (e.g. `p`, `div`, `ul`, `li`).
+ */
+export declare function setBlockTag(tag: string): void;
+/**
+ * Remove a tag from block/container behavior and treat it as inline.
+ */
+export declare function removeBlockTag(tag: string): void;
+export {};

package/lib/html-text-parser/types.d.ts

@@ -1,35 +1,53 @@
 /**
- * Represents a parsed segment of rich text with active style classes.
+ * A parsed run of text with its active tag context.
  */
 export interface TextSegment {
-    /** The text content of the segment (e.g. 'Hello world') */
+    /** Plain text content of this run */
     text: string;
-    /** Comma-separated list of active tag names (e.g. 'b,i') */
+    /** All active tag names as a comma-separated string (e.g. 'b,i') */
     tagNames: string;
-    /** Array of active tag names (e.g. ['b', 'i']) */
+    /** All active tag names as an array (e.g. ['b', 'i']) */
     tagNamesList: string[];
-    /** CSS style string — only inline tag styles, excludes block/container styles */
-    style: string;
-    /** Style object — only inline tag styles, excludes block/container styles */
-    styleObject?: Record<string, string>;
-    /** Array of active block/container tag names (e.g. ['div', 'p']) */
+    /** Active block/container tag names for this run (e.g. ['div', 'p']) */
     containerTagNames: string[];
-    /** CSS class string for inline tags only (e.g. 'rtp-b rtp-i') */
+    /** CSS class string for inline tags (e.g. 'rtp-b rtp-i') */
     cssClass: string;
 }
 /**
- * A group of consecutive segments sharing the same block/container context.
- * Use `groupByBlocks()` to produce these from a flat `TextSegment[]`.
+ * A group of segments that share the same block/container context.
+ * Produced by `groupSegments()`.
  */
 export interface BlockGroup {
-    /** Block/container tag names active for this group (e.g. ['div']) */
+    /** Block tag names wrapping this group (e.g. ['ul', 'li']) */
     containerTagNames: string[];
-    /** CSS class string for block-level tags (e.g. 'rtp-div rtp-p') */
+    /** CSS classes for the block wrapper (e.g. 'rtp-ul rtp-li') */
     cssClass: string;
-    /** Inline CSS style string for block-level tags */
-    style: string;
-    /** Style object for block-level tags */
-    styleObject: Record<string, string>;
-    /** The text segments inside this block group */
+    /** The text segments inside this block */
     segments: TextSegment[];
 }
+/** Override default CSS for specific tags. Values are CSS property strings. */
+export type RichTextOverrideStyles = Partial<{
+    b: string;
+    i: string;
+    u: string;
+    s: string;
+    mark: string;
+    small: string;
+    sup: string;
+    sub: string;
+    h1: string;
+    h2: string;
+    h3: string;
+    h4: string;
+    h5: string;
+    h6: string;
+    code: string;
+    span: string;
+    p: string;
+    div: string;
+    ul: string;
+    ol: string;
+    li: string;
+    br: string;
+    hr: string;
+}>;

package/lib/http.d.ts

@@ -1,18 +1,148 @@
-export type HttpError = Error & {
-    status?: number;
-    statusText?: string;
-    body?: string;
-    code?: string;
-    isNetworkError?: boolean;
-    cause?: unknown;
-};
+export interface HttpError<TData> extends Error, _Response<TData> {
+}
 export interface RequestInit extends globalThis.RequestInit {
     parse?: 'JSON' | 'TEXT' | 'BLOB' | 'ARRAYBUFFER';
 }
+interface _Response<T> extends Omit<globalThis.Response, 'body' | 'json' | 'text' | 'blob' | 'arrayBuffer'> {
+    data: T;
+}
+export type Response<T> = _Response<T>;
+export declare namespace Http {
+    type Response<T> = _Response<T>;
+}
+export declare const HttpCodeNames: {
+    100: string;
+    101: string;
+    102: string;
+    103: string;
+    200: string;
+    201: string;
+    202: string;
+    203: string;
+    204: string;
+    205: string;
+    206: string;
+    207: string;
+    208: string;
+    226: string;
+    300: string;
+    301: string;
+    302: string;
+    303: string;
+    304: string;
+    305: string;
+    307: string;
+    308: string;
+    400: string;
+    401: string;
+    402: string;
+    403: string;
+    404: string;
+    405: string;
+    406: string;
+    407: string;
+    408: string;
+    409: string;
+    410: string;
+    411: string;
+    412: string;
+    413: string;
+    414: string;
+    415: string;
+    416: string;
+    417: string;
+    418: string;
+    421: string;
+    422: string;
+    423: string;
+    424: string;
+    425: string;
+    426: string;
+    428: string;
+    429: string;
+    431: string;
+    451: string;
+    500: string;
+    501: string;
+    502: string;
+    503: string;
+    504: string;
+    505: string;
+    506: string;
+    507: string;
+    508: string;
+    510: string;
+    511: string;
+};
 /**
  * A utility object for making HTTP requests.
  */
-export declare const http: {
+export declare const Http: {
+    setBaseUrl: (url: string) => void;
+    CodeNames: {
+        100: string;
+        101: string;
+        102: string;
+        103: string;
+        200: string;
+        201: string;
+        202: string;
+        203: string;
+        204: string;
+        205: string;
+        206: string;
+        207: string;
+        208: string;
+        226: string;
+        300: string;
+        301: string;
+        302: string;
+        303: string;
+        304: string;
+        305: string;
+        307: string;
+        308: string;
+        400: string;
+        401: string;
+        402: string;
+        403: string;
+        404: string;
+        405: string;
+        406: string;
+        407: string;
+        408: string;
+        409: string;
+        410: string;
+        411: string;
+        412: string;
+        413: string;
+        414: string;
+        415: string;
+        416: string;
+        417: string;
+        418: string;
+        421: string;
+        422: string;
+        423: string;
+        424: string;
+        425: string;
+        426: string;
+        428: string;
+        429: string;
+        431: string;
+        451: string;
+        500: string;
+        501: string;
+        502: string;
+        503: string;
+        504: string;
+        505: string;
+        506: string;
+        507: string;
+        508: string;
+        510: string;
+        511: string;
+    };
     /**
      * Makes a GET request to the specified URL.
      *
@@ -21,7 +151,7 @@ export declare const http: {
      * @returns {Promise<any>} The response data.
      * @throws {Error} If the response is not ok.
      */
-    get: <R = any>(url: string, options?: RequestInit) => Promise<R>;
+    get: <R = any>(url: string, options?: RequestInit) => Promise<Response<R>>;
     /**
      * Makes a POST request to the specified URL with the given data.
      *
@@ -32,18 +162,17 @@ export declare const http: {
      * @returns {Promise<R>} The response data.
      * @throws {Error} If the response is not ok.
      */
-    post: <R = any>(url: string, data: unknown, options?: RequestInit) => Promise<R>;
+    post: <R = any>(url: string, data: unknown, options?: RequestInit) => Promise<Response<R>>;
     /**
-     * Makes a DELETE request to the specified URL with the given ID.
+     * Makes a DELETE request to the specified URL.
      *
      * @template R
      * @param {string} url - The URL to send the DELETE request to.
-     * @param {string} id - The ID to send in the request body.
      * @param {RequestInit} [options] - Optional request options.
      * @returns {Promise<R>} The response data.
      * @throws {Error} If the response is not ok.
      */
-    delete: <R = any>(url: string, id: string, options?: RequestInit) => Promise<R>;
+    delete: <R = any>(url: string, options?: RequestInit) => Promise<Response<R>>;
     /**
      * Makes a PATCH request to the specified URL with the given data.
      *
@@ -54,7 +183,7 @@ export declare const http: {
      * @returns {Promise<R>} The response data.
      * @throws {Error} If the response is not ok.
      */
-    patch: <R = any>(url: string, data: unknown, options?: RequestInit) => Promise<R>;
+    patch: <R = any>(url: string, data: unknown, options?: RequestInit) => Promise<Response<R>>;
     /**
      * Makes a PUT request to the specified URL with the given data.
      *
@@ -65,5 +194,6 @@ export declare const http: {
      * @returns {Promise<R>} The response data.
      * @throws {Error} If the response is not ok.
      */
-    put: <R = any>(url: string, data: unknown, options?: RequestInit) => Promise<R>;
+    put: <R = any>(url: string, data: unknown, options?: RequestInit) => Promise<Response<R>>;
 };
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dvirus-js/utils",
-  "version": "0.0.7",
+  "version": "0.0.13",
   "type": "module",
   "main": "./index.js",
   "types": "./index.d.ts",

package/lib/html-text-parser/html-text-parser.d.ts

@@ -1,70 +0,0 @@
-import { TextSegment, BlockGroup } from './types';
-/**
- * Parses a string containing supported inline tags into block groups.
- * Supports nested tags. All other content is treated as plain text.
- * Returns segments grouped by their block/container context.
- *
- * For a flat array of segments without block grouping, use `parseRichText.flat()`.
- *
- * Supported tags (add more in `RICH_TEXT_TAGS`):
- * `<b>` / `<strong>`, `<i>` / `<em>`, `<u>`, `<s>`, `<mark>`, `<small>`,
- * `<h1>` - `<h6>`, `<code>`, `<p>`, `<div>`
- *
- * Supported self-closing tags (add more in `SELF_CLOSING_TAGS`):
- * `<br/>`
- *
- * @example
- * parseRichText('Hello <b>world</b>!')
- * // [
- * //   { containerTagNames: [], cssClass: '', style: '', styleObject: {}, segments: [
- * //     { text: 'Hello ', ... },
- * //     { text: 'world', ... },
- * //     { text: '!', ... },
- * //   ]},
- * // ]
- */
-export declare function parseRichText(input: string): BlockGroup[];
-export declare namespace parseRichText {
-    var setTag: typeof setRichTextTag;
-    var setSelfClosingTag: typeof import("./html-text-parser").setSelfClosingTag;
-    var setBlockTag: (tag: string) => Set<string>;
-    var removeBlockTag: (tag: string) => boolean;
-    var setCssClassPrefix: typeof import("./constant").setCssClassPrefix;
-    var getStylesheet: typeof import("./methods").getStylesheet;
-    var flat: typeof parseRichTextFlat;
-    var generateStylesheet: typeof import("./methods").generateStylesheet;
-    var appendToDom: typeof import("./methods").appendToDom;
-}
-/**
- * Parses a string containing supported inline tags into a flat array of typed segments.
- * Supports nested tags. All other content is treated as plain text.
- *
- * @example
- * parseRichTextFlat('Hello <b>world</b>!')
- * // [
- * //   { text: 'Hello ', tagNames: '', cssClass: '' },
- * //   { text: 'world', tagNames: 'b', cssClass: 'rtp-b' },
- * //   { text: '!', tagNames: '', cssClass: '' },
- * // ]
- */
-export declare function parseRichTextFlat(input: string): TextSegment[];
-export declare function setRichTextTag(tag: {
-    tag: string;
-    tagName?: string;
-    style?: Record<string, string>;
-}): void;
-export declare function setRichTextTag(tags: {
-    tag: string;
-    tagName?: string;
-    style?: Record<string, string>;
-}[]): void;
-export declare function setSelfClosingTag(tag: {
-    tag: string;
-    tagName?: string;
-    style?: Record<string, string>;
-}): void;
-export declare function setSelfClosingTag(tags: {
-    tag: string;
-    tagName?: string;
-    style?: Record<string, string>;
-}[]): void;

package/lib/html-text-parser/methods.d.ts

@@ -1,51 +0,0 @@
-import { TextSegment, BlockGroup } from './types';
-export declare const createTagSegment: (activeTagsKeys: string[], input: string, lastIndex: number, index: number, text?: string) => TextSegment;
-export declare const getTagNames: () => string;
-export declare const getSelfClosingTagNames: () => string;
-export declare const getTagRegex: () => RegExp;
-export declare function setStyleMap(key: string, style: Record<string, string>): void;
-/**
- * Generates a CSS stylesheet string from all registered tags and their styles.
- * Each tag gets a class like `.rtp-b { font-weight: bold; }`.
- *
- * @example
- * const css = generateStylesheet();
- * // '.rtp-b { font-weight: bold; }\n.rtp-i { font-style: italic; }\n...'
- */
-export declare function getStylesheet(): string;
-export declare function generateStylesheet(): void;
-/**
- * Groups a flat array of segments by their block/container context.
- * Consecutive segments with the same `containerTagNames` are merged into one `BlockGroup`.
- *
- * @example
- * const groups = groupByBlocks(parseRichText('<div>Hello <b>world</b></div> outside'));
- * // [
- * //   { containerTagNames: ['div'], cssClass: 'rtp-div', segments: [...] },
- * //   { containerTagNames: [],      cssClass: '',        segments: [...] },
- * // ]
- */
-export declare function groupByBlocks(segments: TextSegment[]): BlockGroup[];
-/**
- * Appends parsed rich text segments to a DOM element, creating nested elements
- * for each block group and its inline segments.
- *
- * @param htmlElement - The target DOM element to append content to. Must support `appendChild`.
- * @param segments - An array of `BlockGroup` objects (e.g. from `groupByBlocks`).
- * @param config - Optional configuration for styling behavior.
- * @param config.useClasses - Whether to apply CSS class names to elements. Defaults to `true`.
- * @param config.useStyles - Whether to apply inline styles to elements. Defaults to `false`.
- *
- * @example
- * const el = document.getElementById('output');
- * const groups = groupByBlocks(parseRichText('<b>Hello</b> <i>world</i>'));
- * appendToDom(el, groups);
- *
- * @example
- * // With inline styles instead of classes
- * appendToDom(el, groups, { useClasses: false, useStyles: true });
- */
-export declare function appendToDom<T extends object>(htmlElement: T, segments: BlockGroup[], config?: {
-    useClasses?: boolean;
-    useStyles?: boolean;
-}): void;