@dvirus-js/utils 0.0.1

package/lib/Result.d.ts

@@ -0,0 +1,79 @@
+/**
+ * A class representing a result of an operation that can either be a success (ok) or a failure (err).
+ * @template T - The type of the success value.
+ * @template E - The type of the error value, extending Error.
+ */
+export declare class Result<T, E extends Error = Error> {
+    #private;
+    /**
+     * Creates a successful result.
+     * @param {T} val - The success value.
+     * @returns {Result<T, never>} A Result instance representing a success.
+     */
+    static ok<T>(val: T): Result<T, never>;
+    /**
+     * Creates a failed result.
+     * @param {E | string} err - The error value or message.
+     * @returns {Result<never, E>} A Result instance representing a failure.
+     */
+    static err<E extends Error>(err: E | string): Result<never, E>;
+    /**
+     * Wraps a promise in a Result.
+     * @param {Promise<T>} promise - The promise to wrap.
+     * @returns {Promise<Result<T, E>>} A promise that resolves to a Result.
+     */
+    static promise<T, E extends Error = Error>(promise: Promise<T>): Promise<Result<T, E>>;
+    /**
+     * Wraps a function call in a Result.
+     * @param {(...args: any[]) => T} func - The function to call.
+     * @param {...any[]} args - The arguments to pass to the function.
+     * @returns {Result<T, E>} A Result instance representing the function call result.
+     */
+    static func<T, E extends Error = Error, TParam extends Array<unknown> = []>(func: (...args: TParam) => T, ...args: TParam): Result<T, E>;
+    /**
+     * @param {T | null} ok - The success value.
+     * @param {E | null} err - The error value.
+     * @throws {Error} If both ok and err are provided or neither is provided.
+     */
+    constructor(ok: T | null, err: E | null);
+    /**
+     * Gets the success value, throwing an error if the result is a failure.
+     * @returns {T} The success value.
+     * @throws {Error} If the result is a failure.
+     */
+    get value(): T;
+    /**
+     * Unwraps the result, returning the success value or throwing the error.
+     * @returns {T} The success value.
+     * @throws {E} If the result is a failure.
+     */
+    unwrap(): T;
+    /**
+     * Unwraps the result, returning the success value or a default value if the result is a failure.
+     * @param {T} defaultValue - The default value to return if the result is a failure.
+     * @returns {T} The success value or the default value.
+     */
+    unwrapOr(defaultValue: T): T;
+    /**
+     * Gets the success value, throwing a custom error message if the result is a failure.
+     * @param {string} msg - The custom error message.
+     * @returns {T} The success value.
+     * @throws {Error} If the result is a failure.
+     */
+    expect(msg: string): T;
+    /**
+     * Checks if the result is a success.
+     * @returns {boolean} True if the result is a success, false otherwise.
+     */
+    isOk(): this is Result<T, never>;
+    /**
+     * Checks if the result is a failure.
+     * @returns {boolean} True if the result is a failure, false otherwise.
+     */
+    isErr(): this is Result<never, E>;
+    /**
+     * Gets the error value.
+     * @returns {E | null} The error value, or null if the result is a success.
+     */
+    get error(): this extends Result<never, E> ? E : E | null;
+}

package/lib/brand-type/brand-factory.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Creates a nominally typed value by intersecting a base type with a hidden marker.
+ *
+ * @typeParam T - The underlying runtime type.
+ * @typeParam B - A unique compile-time brand marker.
+ */
+export type Brand<T, B> = T & {
+    readonly __brand: B;
+};
+/**
+ * Factory contract for creating and validating branded values.
+ *
+ * @typeParam BrandType - The branded output type.
+ * @typeParam Param - The accepted input type.
+ */
+export interface BrandFactory<BrandType, Param> {
+    /**
+     * Creates a branded value or throws when the input is invalid.
+     * @throws Error if the input does not satisfy the brand's validation predicate.
+     */
+    (value: Param): BrandType;
+    /**
+     * Creates a branded value when valid, otherwise returns `undefined`.
+     */
+    from(value: Param): BrandType | undefined;
+    /**
+     * Type guard that checks whether a value matches the branded type.
+     */
+    is(value: unknown): value is BrandType;
+}
+/**
+ * Builds a branding factory from a runtime validation predicate.
+ *
+ * @param name - For Debugging: Human-readable brand name used in validation errors.
+ * @param testFn - Predicate that validates whether a value matches the brand.
+ * @param parseFn - Optional function to transform the input before validation (e.g. parsing).
+ * @returns A callable factory with helper methods for safe parsing and checks.
+ */
+export declare function createBrand<BrandType, Param>(name: string, testFn: (value: unknown) => value is BrandType, parseFn?: (value: Param) => unknown): BrandFactory<BrandType, Param>;

package/lib/brand-type/index.d.ts

@@ -0,0 +1,2 @@
+export * from './brand-factory';
+export * from './numeric-string';

package/lib/brand-type/numeric-string.d.ts

@@ -0,0 +1,15 @@
+import { Brand } from './brand-factory';
+/**
+ * A branded string type that only contains digit characters (`0-9`).
+ *
+ * At runtime this is just a plain `string` — no wrapper objects.
+ * The brand prevents accidental assignment of arbitrary strings at compile time.
+ *
+ * @example
+ * ```ts
+ * const id: NumericString = NumericString('123'); // ok
+ * const id: NumericString = '123';                // compile error
+ * ```
+ */
+export type NumericString = Brand<string, 'NumericString'>;
+export declare const NumericString: import('./brand-factory').BrandFactory<NumericString, string | number>;

package/lib/convert-cases.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Normalizes any string to lowercase with spaces
+ * Handles various cases like special characters, extra spaces, and different formats
+ * @param input - The string to normalize
+ * @returns A normalized string in lowercase with single spaces
+ */
+export declare function normalizeString(input: string): string;
+/**
+ * Converts a string to various cases
+ * @param input - The string to convert
+ * @param caseType - The target case type
+ * @returns The string converted to the specified case
+ */
+export type CaseType = 'lowercase' | 'UPPERCASE' | 'Title Case' | 'kebab-case' | 'snake_case' | 'camelCase' | 'PascalCase' | 'dot.case' | 'path/case' | 'Sentence case' | 'Header-Case' | 'reverse';
+export declare function convertCase(input: string, caseType: CaseType): string;

package/lib/delay.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Delay for a given time
+ * @param ms - Time in milliseconds
+ * @returns Promise
+ */
+export declare function delay(ms: number): Promise<unknown>;
+/**
+ * Clamp a value between a minimum and maximum value
+ * @param min - Minimum value
+ * @param value - Value
+ * @param max - Maximum value
+ * @returns Clamped value
+ */
+export declare function clamp(min: number, value: number, max: number): number;
+/**
+ * Debounce a function
+ * @param func - Function to debounce
+ * @param delay - Delay in milliseconds
+ * @returns Debounced function
+ */
+export declare function debounce<T extends (...args: any[]) => void>(func: T, delay: number): (...args: Parameters<T>) => void;

package/lib/getProp.d.ts

@@ -0,0 +1,17 @@
+/**
+ * A utility type to get the value type at a given path in an object.
+ *
+ * @template T - The type of the object.
+ * @template P - The path as a string.
+ */
+export type PathValue<T, P extends string> = P extends `${infer K}.${infer Rest}` ? K extends keyof T ? PathValue<T[K], Rest> : undefined : P extends keyof T ? T[P] : undefined;
+/**
+ * Retrieves the value at a given path in an object.
+ *
+ * @template T - The type of the object.
+ * @template P - The path as a string.
+ * @param {T} obj - The object to retrieve the value from.
+ * @param {P} path - The path to the value in the object.
+ * @returns {PathValue<T, P>} The value at the given path, or undefined if the path is invalid.
+ */
+export declare function getProp<T, P extends string>(obj: T, path: P): PathValue<T, P>;

package/lib/group-by.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Groups the elements of an array based on the provided keyGetter function.
+ *
+ * @param value - The array to group.
+ * @param {function(item T, number, array T[]): string | number} keyGetter - A function that takes an element, its
+ * index, and
+ * the array, and returns a key to group by.
+ * @returns {Record<string, array T>} - An object where the keys are the results of the keyGetter function and the
+ * values are arrays of elements that correspond to those keys.
+ */
+export declare function groupBy<T>(value: T[], keyGetter: (item: T, index: number, array: T[]) => string | number | {
+    toString: () => string;
+}): Record<string, T[]>;

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

@@ -0,0 +1,19 @@
+/**
+ * Maps an HTML tag name to a CSS class applied to the segment.
+ * To add a new supported tag, add an entry here and a matching `.text--<style>` CSS class.
+ */
+export declare const RICH_TEXT_TAGS: Map<string, string>;
+/**
+ * Set of tag names that act as block/container-level elements.
+ * Their styles are NOT inherited by nested text segments — only their tag name
+ * is tracked in `containerTagNames` so the renderer can wrap groups accordingly.
+ */
+export declare const BLOCK_TAGS: Set<string>;
+export declare function getCssClassPrefix(): string;
+export declare function setCssClassPrefix(prefix: string): void;
+/**
+ * Maps self-closing HTML tag names to parser style keys.
+ * 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/html-text-parser.d.ts

@@ -0,0 +1,51 @@
+import { TextSegment } from './types';
+/**
+ * Parses a string containing supported inline tags into typed segments.
+ * Supports nested tags. All other content is treated as plain text.
+ *
+ * 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>!')
+ * // [
+ * //   { text: 'Hello ', styles: [], cssClass: '' },
+ * //   { text: 'world', styles: ['bold'] },
+ * //   { text: '!', styles: [] },
+ * // ]
+ */
+export declare function parseRichText(input: string): TextSegment[];
+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 generateStylesheet: typeof import("./methods").generateStylesheet;
+    var getStylesheet: typeof import("./methods").getStylesheet;
+    var groupByBlocks: typeof import("./methods").groupByBlocks;
+}
+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/index.d.ts

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

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

@@ -0,0 +1,28 @@
+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[];

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

@@ -0,0 +1,35 @@
+/**
+ * Represents a parsed segment of rich text with active style classes.
+ */
+export interface TextSegment {
+    /** The text content of the segment (e.g. 'Hello world') */
+    text: string;
+    /** Comma-separated list of active tag names (e.g. 'b,i') */
+    tagNames: string;
+    /** Array of active tag names (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']) */
+    containerTagNames: string[];
+    /** CSS class string for inline tags only (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[]`.
+ */
+export interface BlockGroup {
+    /** Block/container tag names active for this group (e.g. ['div']) */
+    containerTagNames: string[];
+    /** CSS class string for block-level tags (e.g. 'rtp-div rtp-p') */
+    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 */
+    segments: TextSegment[];
+}

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

@@ -0,0 +1,59 @@
+/**
+ * Represents a parsed segment of rich text with active style classes.
+ */
+export interface TextSegment {
+    /** The text content of the segment (e.g. 'Hello world') */
+    text: string;
+    /** Comma-separated list of active tag names (e.g. 'b,i') */
+    tagNames: string;
+    /** Array of active tag names (e.g. ['b', 'i']) */
+    tagNamesList: string[];
+    /** CSS style string (e.g. 'font-weight: bold; font-style: italic') */
+    style: string;
+    /** Optional style object for easier programmatic access (e.g. { 'font-weight': 'bold', 'font-style': 'italic' }) */
+    styleObject?: Record<string, string>;
+}
+/**
+ * Parses a string containing supported inline tags into typed segments.
+ * Supports nested tags. All other content is treated as plain text.
+ *
+ * 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>!')
+ * // [
+ * //   { text: 'Hello ', styles: [], cssClass: '' },
+ * //   { text: 'world', styles: ['bold'] },
+ * //   { text: '!', styles: [] },
+ * // ]
+ */
+export declare function parseRichText(input: string): TextSegment[];
+export declare namespace parseRichText {
+    var addTag: typeof addRichTextTag;
+    var addSelfClosingTag: typeof import("./html-text-parser___").addSelfClosingTag;
+}
+export declare function addRichTextTag(tag: {
+    tag: string;
+    tagName?: string;
+    style?: Record<string, string>;
+}): void;
+export declare function addRichTextTag(tags: {
+    tag: string;
+    tagName?: string;
+    style?: Record<string, string>;
+}[]): void;
+export declare function addSelfClosingTag(tag: {
+    tag: string;
+    tagName?: string;
+    style?: Record<string, string>;
+}): void;
+export declare function addSelfClosingTag(tags: {
+    tag: string;
+    tagName?: string;
+    style?: Record<string, string>;
+}[]): void;

package/lib/http.d.ts

@@ -0,0 +1,58 @@
+/**
+ * A utility object for making HTTP requests.
+ */
+export declare const http: {
+    /**
+     * Makes a GET request to the specified URL.
+     *
+     * @param {string} url - The URL to send the GET request to.
+     * @param {RequestInit} [options] - Optional request options.
+     * @returns {Promise<any>} The response data.
+     * @throws {Error} If the response is not ok.
+     */
+    get: <R = any>(url: string, options?: RequestInit) => Promise<R>;
+    /**
+     * Makes a POST request to the specified URL with the given data.
+     *
+     * @template R
+     * @param {string} url - The URL to send the POST request to.
+     * @param {unknown} data - The data 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.
+     */
+    post: <R = any>(url: string, data: unknown, options?: RequestInit) => Promise<R>;
+    /**
+     * Makes a DELETE request to the specified URL with the given ID.
+     *
+     * @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>;
+    /**
+     * Makes a PATCH request to the specified URL with the given data.
+     *
+     * @template R
+     * @param {string} url - The URL to send the PATCH request to.
+     * @param {unknown} data - The data 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.
+     */
+    patch: <R = any>(url: string, data: unknown, options?: RequestInit) => Promise<R>;
+    /**
+     * Makes a PUT request to the specified URL with the given data.
+     *
+     * @template R
+     * @param {string} url - The URL to send the PUT request to.
+     * @param {unknown} data - The data 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.
+     */
+    put: <R = any>(url: string, data: unknown, options?: RequestInit) => Promise<R>;
+};

package/lib/signals.d.ts

@@ -0,0 +1,72 @@
+type Subscriber<T> = (value: T) => void;
+type CleanupFn = () => void;
+type UpdateFn<T> = (current: T) => T;
+export declare const SIGNAL: unique symbol;
+export declare const isSignal: (value: unknown) => value is Signal<unknown>;
+export interface Signal<T> {
+    (): T;
+    [SIGNAL]: true;
+    subscribe: (fn: Subscriber<T>) => CleanupFn;
+}
+export interface WritableSignal<T> extends Signal<T> {
+    set: (value: T) => void;
+    update: (fn: UpdateFn<T>) => void;
+    asReadonly: () => Signal<T>;
+}
+export interface EffectRef {
+    destroy: CleanupFn;
+}
+type ResourceStatus = 'idle' | 'loading' | 'resolved' | 'error';
+export type ResourceStreamItem<T> = {
+    value: T;
+} | {
+    error: unknown;
+};
+export interface ResourceRef<T> {
+    readonly value: Signal<T | undefined>;
+    readonly status: Signal<ResourceStatus>;
+    readonly error: Signal<unknown>;
+    readonly isLoading: Signal<boolean>;
+    set: (value: T) => void;
+    update: (fn: UpdateFn<T | undefined>) => void;
+    reload: () => void;
+    destroy: CleanupFn;
+}
+export interface ResourceLoaderParamsNoParams {
+    abortSignal: AbortSignal;
+}
+export interface ResourceLoaderParams<R> extends ResourceLoaderParamsNoParams {
+    params?: NoInfer<R>;
+}
+interface ResourceLoaderWithParams<T, R> {
+    params: () => R;
+    loader: (params: ResourceLoaderParams<R>) => Promise<T>;
+}
+interface ResourceLoaderWithoutParams<T> {
+    loader: (params: ResourceLoaderParamsNoParams) => Promise<T>;
+}
+interface ResourceStreamWithParams<T, R> {
+    params: () => R;
+    stream: (params: ResourceLoaderParams<R>) => Signal<ResourceStreamItem<T> | undefined>;
+}
+interface ResourceStreamWithoutParams<T> {
+    stream: (params: ResourceLoaderParamsNoParams) => Signal<ResourceStreamItem<T> | undefined>;
+}
+export declare const untracked: <T>(fn: () => T) => T;
+export declare const signal: <T>(initial: T) => WritableSignal<T>;
+export declare const effect: (fn: (onCleanup: (cleanupFn: CleanupFn) => void) => void) => EffectRef;
+export declare const computed: <T>(fn: () => T) => Signal<T>;
+interface LinkedSignalOptions<S, T> {
+    source: () => S;
+    computation: (source: S, previous: {
+        source: S;
+        value: T;
+    } | undefined) => T;
+}
+export declare function linkedSignal<T>(computation: () => T): WritableSignal<T>;
+export declare function linkedSignal<S, T>(options: LinkedSignalOptions<S, T>): WritableSignal<T>;
+export declare function resource<T, R>(options: ResourceLoaderWithParams<T, R>): ResourceRef<T>;
+export declare function resource<T>(options: ResourceLoaderWithoutParams<T>): ResourceRef<T>;
+export declare function resource<T, R>(options: ResourceStreamWithParams<T, R>): ResourceRef<T>;
+export declare function resource<T>(options: ResourceStreamWithoutParams<T>): ResourceRef<T>;
+export {};

package/lib/to-array.d.ts

@@ -0,0 +1 @@
+export declare function toArray<T>(obj: T | T[] | undefined | null, defaultValue?: T[]): T[];

package/lib/tryCatch.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Types for the result tuple with discriminated union
+ * @template T - Type of the successful result
+ * @template E - Type of the error, defaults to Error
+ */
+export type TryResult<T, E = Error> = [T, null] | [null, E];
+/**
+ * Main wrapper function to handle promise with try-catch
+ * @template T - Type of the successful result
+ * @template E - Type of the error, defaults to Error
+ * @param {Promise<T>} promise - The promise to handle
+ * @returns {Promise<TryResult<T, E>>} - A promise that resolves to a tuple with either the result or the error
+ */
+export declare function tryCatchAsync<T, E = Error>(promise: Promise<T>): Promise<TryResult<T, E>>;
+/**
+ * Main wrapper function to handle promise with try-catch
+ * @template T - Type of the successful result
+ * @template E - Type of the error, defaults to Error
+ * @param {()=> T} fn - The function to handle
+ * @returns {TryResult<T, E>} - A tuple with either the result or the error
+ */
+export declare function tryCatch<T, E = Error>(fn: () => T): TryResult<T, E>;

package/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "@dvirus-js/utils",
+  "version": "0.0.1",
+  "type": "module",
+  "main": "./index.js",
+  "types": "./index.d.ts",
+  "dependencies": {},
+  "publishConfig": {
+    "access": "public"
+  }
+}