katanakit-js 2.1.5

package/dist/core/services/timing.service.js

@@ -0,0 +1,217 @@
+import { useLog } from "./logger.service.js";
+/**
+ * Timing utilities: delays, debouncing, throttling and timeouts.
+ * Implemented as a Singleton facade with factory methods.
+ */
+export default class TimingService {
+    static instance;
+    constructor() { }
+    static getInstance() {
+        if (!TimingService.instance) {
+            TimingService.instance = new TimingService();
+        }
+        return TimingService.instance;
+    }
+    useDelay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+    /** Alias for delay, more semantic for sleep operations. */
+    useSleep = (ms) => this.useDelay(ms);
+    useSetTimeout = (callback, ms) => {
+        let timerId;
+        let isCancelled = false;
+        const promise = new Promise((resolve, reject) => {
+            timerId = setTimeout(async () => {
+                if (isCancelled)
+                    return;
+                try {
+                    const result = await callback();
+                    resolve(result);
+                }
+                catch (error) {
+                    reject(error);
+                }
+            }, ms);
+        });
+        const cancel = () => {
+            isCancelled = true;
+            clearTimeout(timerId);
+        };
+        return { promise, cancel };
+    };
+    useInterval = (callback, ms, immediate = false) => {
+        let timerId = null;
+        let isPaused = false;
+        let isStopped = false;
+        let isExecuting = false;
+        const execute = async () => {
+            if (isPaused || isStopped || isExecuting)
+                return;
+            isExecuting = true;
+            try {
+                await callback();
+            }
+            catch (error) {
+                useLog("error", "[interval] Callback error:", error);
+            }
+            finally {
+                isExecuting = false;
+            }
+        };
+        const scheduleNext = () => {
+            if (isStopped || isPaused)
+                return;
+            timerId = setTimeout(async () => {
+                await execute();
+                scheduleNext();
+            }, ms);
+        };
+        const stop = () => {
+            isStopped = true;
+            isPaused = false;
+            if (timerId) {
+                clearTimeout(timerId);
+                timerId = null;
+            }
+        };
+        const pause = () => {
+            if (isStopped)
+                return;
+            isPaused = true;
+            if (timerId) {
+                clearTimeout(timerId);
+                timerId = null;
+            }
+        };
+        const resume = () => {
+            if (isStopped || !isPaused)
+                return;
+            isPaused = false;
+            scheduleNext();
+        };
+        const isRunning = () => !isStopped && !isPaused;
+        if (immediate) {
+            execute().then(() => scheduleNext());
+        }
+        else {
+            scheduleNext();
+        }
+        return { pause, resume, stop, isRunning };
+    };
+    useDebounce = (func, delayMs) => {
+        let timeoutId;
+        return (...args) => {
+            if (timeoutId !== undefined) {
+                clearTimeout(timeoutId);
+            }
+            timeoutId = setTimeout(() => {
+                try {
+                    func(...args);
+                }
+                catch (error) {
+                    useLog("error", "[debounce] Callback error:", error);
+                }
+                timeoutId = undefined;
+            }, delayMs);
+        };
+    };
+    useDebounceImmediate = (func, delayMs) => {
+        let timeoutId;
+        let lastCallTime;
+        return (...args) => {
+            const now = Date.now();
+            const isFirstCall = lastCallTime === undefined;
+            lastCallTime = now;
+            if (isFirstCall) {
+                try {
+                    func(...args);
+                }
+                catch (error) {
+                    useLog("error", "[debounceImmediate] Callback error:", error);
+                }
+            }
+            if (timeoutId !== undefined) {
+                clearTimeout(timeoutId);
+            }
+            timeoutId = setTimeout(() => {
+                if (Date.now() - Number(lastCallTime) >= delayMs) {
+                    try {
+                        func(...args);
+                    }
+                    catch (error) {
+                        useLog("error", "[debounceImmediate] Callback error:", error);
+                    }
+                }
+                timeoutId = undefined;
+                lastCallTime = undefined;
+            }, delayMs);
+        };
+    };
+    useThrottle = (func, limitMs) => {
+        let inThrottle = false;
+        return (...args) => {
+            if (!inThrottle) {
+                try {
+                    func(...args);
+                }
+                catch (error) {
+                    useLog("error", "[throttle] Callback error:", error);
+                }
+                inThrottle = true;
+                setTimeout(() => {
+                    inThrottle = false;
+                }, limitMs);
+            }
+        };
+    };
+    useThrottleTrailing = (func, limitMs) => {
+        let inThrottle = false;
+        let lastArgs = null;
+        return (...args) => {
+            if (!inThrottle) {
+                try {
+                    func(...args);
+                }
+                catch (error) {
+                    useLog("error", "[throttleTrailing] Callback error:", error);
+                }
+                inThrottle = true;
+                lastArgs = null;
+                setTimeout(() => {
+                    inThrottle = false;
+                    if (lastArgs) {
+                        try {
+                            func(...lastArgs);
+                        }
+                        catch (error) {
+                            useLog("error", "[throttleTrailing] Callback error:", error);
+                        }
+                    }
+                }, limitMs);
+            }
+            else {
+                lastArgs = args;
+            }
+        };
+    };
+    useRepeat = async (callback, iterations, delayMs = 0) => {
+        for (let i = 0; i < iterations; i++) {
+            try {
+                await callback(i);
+            }
+            catch (error) {
+                useLog("error", "[repeat] Callback error:", error);
+            }
+            if (i < iterations - 1 && delayMs > 0) {
+                await this.useDelay(delayMs);
+            }
+        }
+    };
+    useRace = async (promise, timeoutMs, errorMessage = "Operation timed out") => {
+        const timeoutPromise = new Promise((_, reject) => {
+            setTimeout(() => reject(new Error(errorMessage)), timeoutMs);
+        });
+        return Promise.race([promise, timeoutPromise]);
+    };
+}
+// Singleton instance and destructured exports.
+export const { useDelay, useSetTimeout, useInterval, useDebounce, useDebounceImmediate, useThrottle, useThrottleTrailing, useRepeat, useRace, } = TimingService.getInstance();
+//# sourceMappingURL=timing.service.js.map

package/dist/core/services/timing.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"timing.service.js","sourceRoot":"","sources":["../../../src/core/services/timing.service.ts"],"names":[],"mappings":"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"}

package/dist/core/services/utils.service.d.ts

@@ -0,0 +1,44 @@
+import type { IAppUtils, IDataUtils, ISystemUtils } from "../../types/index.js";
+/**
+ * Data utilities implemented as a Singleton.
+ */
+export declare class DataUtils implements IDataUtils {
+    private static instance;
+    private constructor();
+    static getInstance(): DataUtils;
+    useUnique: <T>(array: T[]) => T[];
+    useChunk: <T>(array: T[], size: number) => T[][];
+    useGroupBy: <T>(array: T[], key: keyof T | ((item: T) => string)) => Record<string, T[]>;
+    useIsObject: (item: unknown) => item is Record<string, unknown>;
+    useDeepClone: <T>(value: T) => T;
+    useDeepMerge: <T extends Record<string, unknown>>(target: T, source: Record<string, unknown>) => T;
+    usePick: <T extends object, K extends keyof T>(obj: T, keys: K[]) => Pick<T, K>;
+    useOmit: <T extends object, K extends keyof T>(obj: T, keys: K[]) => Omit<T, K>;
+}
+/**
+ * System utilities implemented as a Singleton.
+ */
+export declare class SystemUtils implements ISystemUtils {
+    private static instance;
+    private constructor();
+    static getInstance(): SystemUtils;
+    useSleep: (ms: number) => Promise<void>;
+    useRetry: <T>(fn: () => Promise<T>, retries?: number, delayMs?: number) => Promise<T>;
+    useCopyToClipboard: (text: string) => Promise<boolean>;
+    useGetUrlParams: (urlString: string) => Record<string, string>;
+    useRound: (value: string | number, decimals?: number) => number;
+    useAverage: (numbers: number[]) => number;
+}
+/**
+ * Main facade composing data and system utilities.
+ */
+export declare class AppUtils implements IAppUtils {
+    private static instance;
+    readonly data: IDataUtils;
+    readonly system: ISystemUtils;
+    private constructor();
+    static getInstance(): AppUtils;
+}
+export declare const useUnique: <T>(array: T[]) => T[], useChunk: <T>(array: T[], size: number) => T[][], useGroupBy: <T>(array: T[], key: ((item: T) => string) | keyof T) => Record<string, T[]>, useIsObject: (item: unknown) => item is Record<string, unknown>, useDeepClone: <T>(value: T) => T, useDeepMerge: <T extends Record<string, unknown>>(target: T, source: Record<string, unknown>) => T, usePick: <T extends object, K extends keyof T>(obj: T, keys: K[]) => Pick<T, K>, useOmit: <T extends object, K extends keyof T>(obj: T, keys: K[]) => Omit<T, K>;
+export declare const useSleep: (ms: number) => Promise<void>, useRetry: <T>(fn: () => Promise<T>, retries?: number, delayMs?: number) => Promise<T>, useCopyToClipboard: (text: string) => Promise<boolean>, useGetUrlParams: (urlString: string) => Record<string, string>, useRound: (value: string | number, decimals?: number) => number, useAverage: (numbers: number[]) => number;
+//# sourceMappingURL=utils.service.d.ts.map

package/dist/core/services/utils.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.service.d.ts","sourceRoot":"","sources":["../../../src/core/services/utils.service.ts"],"names":[],"mappings":"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"}

package/dist/core/services/utils.service.js

@@ -0,0 +1,143 @@
+/**
+ * Data utilities implemented as a Singleton.
+ */
+export class DataUtils {
+    static instance;
+    constructor() { }
+    static getInstance() {
+        if (!DataUtils.instance) {
+            DataUtils.instance = new DataUtils();
+        }
+        return DataUtils.instance;
+    }
+    useUnique = (array) => [...new Set(array)];
+    useChunk = (array, size) => {
+        if (size <= 0)
+            throw new Error("Chunk size must be greater than 0");
+        return Array.from({ length: Math.ceil(array.length / size) }, (_, i) => array.slice(i * size, i * size + size));
+    };
+    useGroupBy = (array, key) => {
+        return array.reduce((acc, item) => {
+            const groupKey = typeof key === "function" ? key(item) : String(item[key]);
+            if (!acc[groupKey]) {
+                acc[groupKey] = [];
+            }
+            acc[groupKey].push(item);
+            return acc;
+        }, {});
+    };
+    useIsObject = (item) => typeof item === "object" && item !== null && !Array.isArray(item);
+    useDeepClone = (value) => {
+        if (typeof structuredClone === "function") {
+            return structuredClone(value);
+        }
+        return JSON.parse(JSON.stringify(value));
+    };
+    useDeepMerge = (target, source) => {
+        if (!target || !source)
+            return { ...target };
+        const output = { ...target };
+        for (const key of Object.keys(source)) {
+            const targetVal = target[key];
+            const sourceVal = source[key];
+            if (this.useIsObject(targetVal) && this.useIsObject(sourceVal)) {
+                output[key] = this.useDeepMerge(targetVal, sourceVal);
+            }
+            else {
+                output[key] = sourceVal;
+            }
+        }
+        return output;
+    };
+    usePick = (obj, keys) => {
+        return keys.reduce((acc, key) => {
+            if (key in obj)
+                acc[key] = obj[key];
+            return acc;
+        }, {});
+    };
+    useOmit = (obj, keys) => {
+        const result = this.useDeepClone(obj);
+        for (const key of keys)
+            delete result[key];
+        return result;
+    };
+}
+/**
+ * System utilities implemented as a Singleton.
+ */
+export class SystemUtils {
+    static instance;
+    constructor() { }
+    static getInstance() {
+        if (!SystemUtils.instance) {
+            SystemUtils.instance = new SystemUtils();
+        }
+        return SystemUtils.instance;
+    }
+    useSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+    useRetry = async (fn, retries = 3, delayMs = 1000) => {
+        try {
+            return await fn();
+        }
+        catch (error) {
+            if (retries <= 0)
+                throw error;
+            await this.useSleep(delayMs);
+            return this.useRetry(fn, retries - 1, delayMs);
+        }
+    };
+    useCopyToClipboard = async (text) => {
+        try {
+            await navigator.clipboard.writeText(text);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    };
+    useGetUrlParams = (urlString) => {
+        try {
+            const url = new URL(urlString);
+            return Object.fromEntries(url.searchParams.entries());
+        }
+        catch {
+            return {};
+        }
+    };
+    useRound = (value, decimals = 2) => {
+        const num = typeof value === "string" ? Number.parseFloat(value) : value;
+        if (Number.isNaN(num))
+            return 0;
+        const factor = 10 ** decimals;
+        return Math.round(num * factor) / factor;
+    };
+    useAverage = (numbers) => {
+        if (numbers.length === 0)
+            return 0;
+        const sum = numbers.reduce((acc, n) => acc + n, 0);
+        return sum / numbers.length;
+    };
+}
+/**
+ * Main facade composing data and system utilities.
+ */
+export class AppUtils {
+    static instance;
+    data;
+    system;
+    constructor() {
+        this.data = DataUtils.getInstance();
+        this.system = SystemUtils.getInstance();
+    }
+    static getInstance() {
+        if (!AppUtils.instance) {
+            AppUtils.instance = new AppUtils();
+        }
+        return AppUtils.instance;
+    }
+}
+// Singleton instances and destructured exports.
+export const { useUnique, useChunk, useGroupBy, useIsObject, useDeepClone, useDeepMerge, usePick, useOmit, } = DataUtils.getInstance();
+export const { useSleep, useRetry, useCopyToClipboard, useGetUrlParams, useRound, useAverage, } = SystemUtils.getInstance();
+//# sourceMappingURL=utils.service.js.map

package/dist/core/services/utils.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.service.js","sourceRoot":"","sources":["../../../src/core/services/utils.service.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./adapters/astro/index.js";
+export * from "./config/index.js";
+export * from "./core/index.js";
+export * from "./infrastructure/index.js";
+export * from "./types/index.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,2BAA2B,CAAC;AAC1C,cAAc,mBAAmB,CAAC;AAClC,cAAc,iBAAiB,CAAC;AAChC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,kBAAkB,CAAC"}

package/dist/index.js

@@ -0,0 +1,6 @@
+export * from "./adapters/astro/index.js";
+export * from "./config/index.js";
+export * from "./core/index.js";
+export * from "./infrastructure/index.js";
+export * from "./types/index.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,2BAA2B,CAAC;AAC1C,cAAc,mBAAmB,CAAC;AAClC,cAAc,iBAAiB,CAAC;AAChC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,kBAAkB,CAAC"}

package/dist/infrastructure/dom/dom.service.d.ts

@@ -0,0 +1,49 @@
+import type { IDomService } from "../../types/index.js";
+export declare class DomService implements IDomService {
+    private static instance;
+    private constructor();
+    static getInstance(): DomService;
+    useIsBrowser: () => boolean;
+    useGetRoot: () => HTMLElement | null;
+    useGetBody: () => HTMLBodyElement | null;
+    private RESOLVE;
+    useGetElementById: <T extends HTMLElement = HTMLElement>(id: string) => T | null;
+    useGetElementByClass: <T extends HTMLElement = HTMLElement>(className: string) => T | null;
+    useQuerySelector: {
+        <K extends keyof HTMLElementTagNameMap>(selector: K): HTMLElementTagNameMap[K] | null;
+        <E extends Element = HTMLElement>(selector: string): E | null;
+    };
+    useQuerySelectorAll: {
+        <K extends keyof HTMLElementTagNameMap>(selector: K): HTMLElementTagNameMap[K][];
+        <E extends Element = HTMLElement>(selector: string): E[];
+    };
+    useAddClass: (target: Element | string, className: string) => void;
+    useRemoveClass: (target: Element | string, className: string | string[]) => void;
+    useToggleClass: (target: Element | string, className: string, force?: boolean) => boolean | undefined;
+    useHasClass: (target: Element | string, className: string) => boolean;
+    useGetAttribute: (target: Element | string, attr: string) => string | null;
+    useSetAttribute: (target: Element | string, attr: string, value: string) => void;
+    useRemoveAttribute: (target: Element | string, attr: string) => void;
+    useGetDataAttribute: (target: HTMLElement | string, key: string) => string | undefined;
+    useSetDataAttribute: (target: HTMLElement | string, key: string, value: string) => void;
+    useOn: <K extends keyof HTMLElementEventMap>(target: EventTarget | string, event: K, callback: (event: HTMLElementEventMap[K]) => void, options?: boolean | AddEventListenerOptions) => (() => void) | null;
+    useCreateElement: <T extends keyof HTMLElementTagNameMap>(tagName: T, options?: ElementCreationOptions) => HTMLElementTagNameMap[T];
+    /**
+     * Sets innerHTML on the target element.
+     * WARNING: this is an XSS sink. Only pass trusted HTML. For user-supplied
+     * content, use `useSetText` (textContent) instead, or sanitize with DOMPurify.
+     */
+    useSetHtml: (target: Element | string, html: string) => void;
+    useSetText: (target: Element | string, text: string) => void;
+    useAppend: (target: Element | string, child: Element | string) => void;
+    useRemove: (target: Element | string) => void;
+}
+export declare const DOM_SERVICE: DomService;
+export declare const useIsBrowser: () => boolean, useGetRoot: () => HTMLElement | null, useGetBody: () => HTMLBodyElement | null, useGetElementById: <T extends HTMLElement = HTMLElement>(id: string) => T | null, useGetElementByClass: <T extends HTMLElement = HTMLElement>(className: string) => T | null, useQuerySelector: {
+    <K extends keyof HTMLElementTagNameMap>(selector: K): HTMLElementTagNameMap[K] | null;
+    <E extends Element = HTMLElement>(selector: string): E | null;
+}, useQuerySelectorAll: {
+    <K extends keyof HTMLElementTagNameMap>(selector: K): HTMLElementTagNameMap[K][];
+    <E extends Element = HTMLElement>(selector: string): E[];
+}, useAddClass: (target: Element | string, className: string) => void, useRemoveClass: (target: Element | string, className: string | string[]) => void, useToggleClass: (target: Element | string, className: string, force?: boolean) => boolean | undefined, useHasClass: (target: Element | string, className: string) => boolean, useGetAttribute: (target: Element | string, attr: string) => string | null, useSetAttribute: (target: Element | string, attr: string, value: string) => void, useRemoveAttribute: (target: Element | string, attr: string) => void, useGetDataAttribute: (target: HTMLElement | string, key: string) => string | undefined, useSetDataAttribute: (target: HTMLElement | string, key: string, value: string) => void, useOn: <K extends keyof HTMLElementEventMap>(target: EventTarget | string, event: K, callback: (event: HTMLElementEventMap[K]) => void, options?: boolean | AddEventListenerOptions) => (() => void) | null, useCreateElement: <T extends keyof HTMLElementTagNameMap>(tagName: T, options?: ElementCreationOptions) => HTMLElementTagNameMap[T], useSetHtml: (target: Element | string, html: string) => void, useSetText: (target: Element | string, text: string) => void, useAppend: (target: Element | string, child: Element | string) => void, useRemove: (target: Element | string) => void;
+//# sourceMappingURL=dom.service.d.ts.map

package/dist/infrastructure/dom/dom.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dom.service.d.ts","sourceRoot":"","sources":["../../../src/infrastructure/dom/dom.service.ts"],"names":[],"mappings":"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"}

package/dist/infrastructure/dom/dom.service.js

@@ -0,0 +1,133 @@
+// ============================================================
+// DOM facade (Singleton) over `document`, with SSR-safe guards.
+// ============================================================
+export class DomService {
+    static instance;
+    constructor() { }
+    static getInstance() {
+        if (!DomService.instance) {
+            DomService.instance = new DomService();
+        }
+        return DomService.instance;
+    }
+    useIsBrowser = () => typeof window !== "undefined" && typeof document !== "undefined";
+    useGetRoot = () => {
+        if (!this.useIsBrowser())
+            return null;
+        return document.documentElement;
+    };
+    useGetBody = () => {
+        if (!this.useIsBrowser())
+            return null;
+        return document.body;
+    };
+    RESOLVE = (target) => {
+        return typeof target === "string" ? this.useQuerySelector(target) : target;
+    };
+    useGetElementById = (id) => {
+        if (!this.useIsBrowser())
+            return null;
+        return document.getElementById(id);
+    };
+    useGetElementByClass = (className) => {
+        if (!this.useIsBrowser())
+            return null;
+        const formattedSelector = className.startsWith(".") ? className : `.${className}`;
+        return document.querySelector(formattedSelector);
+    };
+    useQuerySelector = (selector) => {
+        if (!this.useIsBrowser())
+            return null;
+        return document.querySelector(selector);
+    };
+    useQuerySelectorAll = (selector) => {
+        if (!this.useIsBrowser())
+            return [];
+        return Array.from(document.querySelectorAll(selector));
+    };
+    useAddClass = (target, className) => {
+        this.RESOLVE(target)?.classList.add(className);
+    };
+    useRemoveClass = (target, className) => {
+        const el = this.RESOLVE(target);
+        if (!el)
+            return;
+        if (Array.isArray(className)) {
+            el.classList.remove(...className);
+        }
+        else {
+            el.classList.remove(className);
+        }
+    };
+    useToggleClass = (target, className, force) => {
+        return this.RESOLVE(target)?.classList.toggle(className, force);
+    };
+    useHasClass = (target, className) => {
+        return this.RESOLVE(target)?.classList.contains(className) ?? false;
+    };
+    useGetAttribute = (target, attr) => {
+        return this.RESOLVE(target)?.getAttribute(attr) ?? null;
+    };
+    useSetAttribute = (target, attr, value) => {
+        // Block event-handler attributes to prevent XSS.
+        if (/^on/i.test(attr)) {
+            throw new Error(`[DomService] Attribute "${attr}" is not allowed. Use useOn() for events.`);
+        }
+        this.RESOLVE(target)?.setAttribute(attr, value);
+    };
+    useRemoveAttribute = (target, attr) => {
+        this.RESOLVE(target)?.removeAttribute(attr);
+    };
+    useGetDataAttribute = (target, key) => {
+        return this.RESOLVE(target)?.dataset[key];
+    };
+    useSetDataAttribute = (target, key, value) => {
+        const el = this.RESOLVE(target);
+        if (el)
+            el.dataset[key] = value;
+    };
+    useOn = (target, event, callback, options) => {
+        if (!this.useIsBrowser())
+            return null;
+        const el = typeof target === "string" ? this.useQuerySelector(target) : target;
+        if (!el)
+            return null;
+        const handler = callback;
+        el.addEventListener(event, handler, options);
+        return () => el.removeEventListener(event, handler, options);
+    };
+    useCreateElement = (tagName, options) => {
+        if (!this.useIsBrowser()) {
+            throw new Error("Cannot create elements in non-browser environment");
+        }
+        return document.createElement(tagName, options);
+    };
+    /**
+     * Sets innerHTML on the target element.
+     * WARNING: this is an XSS sink. Only pass trusted HTML. For user-supplied
+     * content, use `useSetText` (textContent) instead, or sanitize with DOMPurify.
+     */
+    useSetHtml = (target, html) => {
+        const el = this.RESOLVE(target);
+        if (el)
+            el.innerHTML = html ?? "";
+    };
+    useSetText = (target, text) => {
+        const el = this.RESOLVE(target);
+        if (el)
+            el.textContent = text;
+    };
+    useAppend = (target, child) => {
+        const parent = this.RESOLVE(target);
+        const childEl = this.RESOLVE(child);
+        if (parent && childEl)
+            parent.appendChild(childEl);
+    };
+    useRemove = (target) => {
+        this.RESOLVE(target)?.remove();
+    };
+}
+// Singleton instance and destructured exports.
+export const DOM_SERVICE = DomService.getInstance();
+export const { useIsBrowser, useGetRoot, useGetBody, useGetElementById, useGetElementByClass, useQuerySelector, useQuerySelectorAll, useAddClass, useRemoveClass, useToggleClass, useHasClass, useGetAttribute, useSetAttribute, useRemoveAttribute, useGetDataAttribute, useSetDataAttribute, useOn, useCreateElement, useSetHtml, useSetText, useAppend, useRemove, } = DOM_SERVICE;
+//# sourceMappingURL=dom.service.js.map