@pivanov/utils 0.0.3 → 1.0.0

package/dist/types/string/index.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Converts a string to camelCase.
+ *
+ * @example
+ * ```ts
+ * camelCase('foo-bar');  // 'fooBar'
+ * camelCase('FOO_BAR');  // 'fooBar'
+ * ```
+ */
+export declare const camelCase: (str: string) => string;
+/**
+ * Converts a string to PascalCase.
+ *
+ * @example
+ * ```ts
+ * pascalCase('foo-bar');      // 'FooBar'
+ * pascalCase('foo123bar');    // 'Foo123Bar'
+ * ```
+ */
+export declare const pascalCase: (str: string) => string;
+/**
+ * Capitalizes the first character of a string (runtime).
+ * For TypeScript literal-type preservation, use `capitalize` instead.
+ */
+export declare const capitalizeFirstLetter: (string: string) => string;
+/**
+ * Converts a string to kebab-case.
+ *
+ * @example
+ * ```ts
+ * kebabCase('fooBar');         // 'foo-bar'
+ * kebabCase('XMLHttpRequest'); // 'xml-http-request'
+ * ```
+ */
+export declare const kebabCase: (str: string) => string;
+/**
+ * Converts a string to snake_case.
+ *
+ * @example
+ * ```ts
+ * snakeCase('fooBar');         // 'foo_bar'
+ * snakeCase('XMLHttpRequest'); // 'xml_http_request'
+ * ```
+ */
+export declare const snakeCase: (str: string) => string;
+/**
+ * Converts a string to Title Case - each word capitalized, separators
+ * normalized to single spaces.
+ *
+ * @example
+ * ```ts
+ * titleCase('hello world');       // 'Hello World'
+ * titleCase('foo-bar_baz');       // 'Foo Bar Baz'
+ * ```
+ */
+export declare const titleCase: (str: string) => string;
+/**
+ * Converts a string into a URL-friendly slug. More aggressive than
+ * `kebabCase` - strips all non-ASCII-word characters.
+ *
+ * @example
+ * ```ts
+ * slugify('Hello World!');     // 'hello-world'
+ * slugify('Über Café');         // 'uber-cafe'
+ * ```
+ */
+export declare const slugify: (str: string) => string;
+/**
+ * Capitalizes the first character; preserves TypeScript literal types.
+ */
+export declare const capitalize: <S extends string>(str: S) => Capitalize<S>;
+/**
+ * Lower-cases the first character; preserves TypeScript literal types.
+ */
+export declare const uncapitalize: <S extends string>(str: S) => Uncapitalize<S>;
+/**
+ * Truncates a string to `maxLength` characters, appending an ellipsis
+ * (default `…`) if truncation happened. The ellipsis is included in
+ * the final length.
+ *
+ * @example
+ * ```ts
+ * truncate('Hello, world!', 8);        // 'Hello, …'
+ * truncate('Hello, world!', 8, '...'); // 'Hello...'
+ * truncate('Short', 20);               // 'Short'
+ * ```
+ */
+export declare const truncate: (str: string, maxLength: number, ellipsis?: string) => string;
+/**
+ * Escapes HTML special characters for safe interpolation into markup.
+ *
+ * @example
+ * ```ts
+ * escapeHtml('<script>alert(1)</script>');
+ * // '&lt;script&gt;alert(1)&lt;/script&gt;'
+ * ```
+ */
+export declare const escapeHtml: (str: string) => string;
+/**
+ * Escapes characters that have special meaning in a regular expression so the
+ * string can be safely embedded as a literal match.
+ *
+ * @example
+ * ```ts
+ * new RegExp(escapeRegExp('a.b*c')); // matches the literal "a.b*c"
+ * ```
+ */
+export declare const escapeRegExp: (str: string) => string;
+/**
+ * Splits a string into words by whitespace, dashes, and underscores.
+ * Preserves case; filters out empty segments.
+ *
+ * @example
+ * ```ts
+ * words('hello_world-foo bar'); // ['hello', 'world', 'foo', 'bar']
+ * ```
+ */
+export declare const words: (str: string) => string[];
+/**
+ * Splits a string by line breaks (`\r\n`, `\n`, or `\r`).
+ *
+ * @example
+ * ```ts
+ * lines('a\nb\r\nc'); // ['a', 'b', 'c']
+ * ```
+ */
+export declare const lines: (str: string) => string[];

package/dist/types/tools/cache-api/index.d.ts

@@ -0,0 +1,75 @@
+/**
+ * `JSON.stringify` replacer that converts `BigInt` values to strings.
+ *
+ * @example
+ * ```ts
+ * JSON.stringify({ id: 9007199254740993n }, stringifyBigIntValues);
+ * ```
+ */
+export declare const stringifyBigIntValues: (_key: string, value: unknown) => unknown;
+/**
+ * Stores a JSON-serializable value in the browser Cache API.
+ *
+ * Note: values are serialized via `JSON.stringify`. `Date`, `Map`, `Set`,
+ * `undefined`, and `Symbol` values are lossy. `BigInt` is auto-stringified.
+ */
+export declare const storageSetItem: (cacheName: string, key: string, value: unknown) => Promise<void>;
+/**
+ * Retrieves a value from the Cache API. Returns `null` if not found.
+ */
+export declare const storageGetItem: <T>(cacheName: string, key: string) => Promise<T | null>;
+/**
+ * Stores a value with a TTL (time-to-live in milliseconds). After the TTL
+ * elapses, reads via `storageGetItemWithTTL` will return `null` and delete
+ * the expired entry.
+ *
+ * Wire format is a self-describing envelope: `{ __ttl: true, v, exp }`.
+ * Entries stored this way are only correctly read via the `WithTTL` variants.
+ *
+ * @example
+ * ```ts
+ * await storageSetItemWithTTL('my-cache', 'token', 'abc123', 60_000);
+ * const token = await storageGetItemWithTTL<string>('my-cache', 'token');
+ * ```
+ */
+export declare const storageSetItemWithTTL: (cacheName: string, key: string, value: unknown, ttlMs: number) => Promise<void>;
+/**
+ * Reads a value previously stored with `storageSetItemWithTTL`. Returns
+ * `null` if absent or expired; expired entries are deleted.
+ */
+export declare const storageGetItemWithTTL: <T>(cacheName: string, key: string) => Promise<T | null>;
+/**
+ * Removes a single key. Returns `true` if the key existed and was deleted.
+ */
+export declare const storageRemoveItem: (cacheName: string, key: string) => Promise<boolean>;
+/**
+ * Clears every entry in the named cache.
+ */
+export declare const storageClear: (cacheName: string) => Promise<void>;
+/**
+ * Clears every cache entry whose key matches `str` as prefix or suffix.
+ *
+ * @deprecated Prefer `storageClearByPrefix` / `storageClearBySuffix` for
+ *   readability. This function will remain through v1.x.
+ */
+export declare const storageClearByPrefixOrSuffix: (cacheName: string, str: string, isPrefix?: boolean) => Promise<void>;
+/**
+ * Clears every cache entry whose key starts with `prefix`.
+ */
+export declare const storageClearByPrefix: (cacheName: string, prefix: string) => Promise<void>;
+/**
+ * Clears every cache entry whose key ends with `suffix`.
+ */
+export declare const storageClearBySuffix: (cacheName: string, suffix: string) => Promise<void>;
+/**
+ * Checks whether a key exists in the cache.
+ */
+export declare const storageExists: (cacheName: string, key: string) => Promise<boolean>;
+/**
+ * Returns every key currently stored in the cache.
+ */
+export declare const storageGetAllKeys: (cacheName: string) => Promise<string[]>;
+/**
+ * Calculates the size in bytes of the cache, or of a single entry.
+ */
+export declare const storageCalculateSize: (cacheName: string, cacheKey?: string) => Promise<number>;

package/dist/types/tools/deepClone.d.ts

@@ -0,0 +1,2 @@
+export type TCloneable = object | number | string | boolean | symbol | bigint | null | undefined;
+export declare const deepClone: <T extends TCloneable>(obj: T) => T;

package/dist/types/tools/dom.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Returns true when running in a browser-like environment.
+ *
+ * Checks for both `window` and `document` so service-worker and
+ * partially-mocked contexts are correctly reported as non-browser.
+ *
+ * @example
+ * ```ts
+ * if (isBrowser()) window.addEventListener('resize', onResize);
+ * ```
+ */
+export declare const isBrowser: () => boolean;
+/**
+ * Sets CSS custom properties on an element. Safely no-ops when element is null.
+ *
+ * @example
+ * ```ts
+ * setStyleProperties(el, { '--primary': '#3b82f6', '--gap': '1rem' });
+ * ```
+ */
+export declare const setStyleProperties: (el: HTMLElement | null, cssVars: Record<string, string>) => void;
+interface CheckVisibilityOptions {
+    /** Require the element to intersect the viewport. Default: true. */
+    checkViewport?: boolean;
+    /** Require computed `display` to be non-"none". Default: true. */
+    checkDisplay?: boolean;
+    /** Require computed `visibility` to be "visible". Default: true. */
+    checkVisibility?: boolean;
+    /** Require computed `opacity` to be > 0. Default: true. */
+    checkOpacity?: boolean;
+}
+/**
+ * Checks whether an element is visible to the user.
+ *
+ * By default verifies: attached to DOM, `display` not `none`,
+ * `visibility` is `visible`, `opacity > 0`, and intersects the viewport
+ * on both axes. Each check can be toggled via options.
+ *
+ * @example
+ * ```ts
+ * if (checkVisibility(el)) el.classList.add('seen');
+ * checkVisibility(el, { checkViewport: false }); // visible per CSS only
+ * ```
+ */
+export declare const checkVisibility: (element: HTMLElement, options?: CheckVisibilityOptions) => boolean;
+/**
+ * @internal Resets the cached canvas - for tests only.
+ */
+export declare const __resetTextMeasurementCache: () => void;
+interface IViewportOptions {
+    /** Require vertical intersection. Default: true. */
+    vertical?: boolean;
+    /** Require horizontal intersection. Default: true. */
+    horizontal?: boolean;
+}
+/**
+ * Returns true when the element's bounding rect intersects the viewport.
+ * Pure geometry - ignores CSS visibility. Use `checkVisibility` for a full
+ * visibility check.
+ *
+ * Zero-sized rects (no layout yet) return true - we can't clip against
+ * nothing, and failing them would produce false negatives in test environments.
+ *
+ * @example
+ * ```ts
+ * if (isInViewport(el)) track();
+ * isInViewport(el, { horizontal: false }); // vertical only
+ * ```
+ */
+export declare const isInViewport: (element: HTMLElement, options?: IViewportOptions) => boolean;
+/**
+ * Measures the rendered width of text in pixels using a cached off-screen
+ * canvas. Returns `0` when 2D context is unavailable.
+ *
+ * @example
+ * ```ts
+ * calculateRenderedTextWidth('Hello World', 16);
+ * calculateRenderedTextWidth('Hi', 14, true, 'Arial');
+ * ```
+ */
+export declare const calculateRenderedTextWidth: (text: string, fontSize: number, isUppercase?: boolean, fontFamily?: string) => number;
+export {};

package/dist/types/tools/eventBus/eventBus.d.ts

@@ -0,0 +1,37 @@
+import type { IEventBus, IEventBusSubscribeOptions, TEventBusListener, TEventBusUnsubscribe } from "./types";
+/**
+ * Dispatches a message to every subscriber on `topic`.
+ *
+ * @example
+ * ```ts
+ * busDispatch('user-updated', { id: 1, name: 'John' });
+ * ```
+ */
+export declare const busDispatch: <T extends IEventBus>(topic: T["topic"], message: T["message"]) => void;
+/**
+ * Subscribes to messages on a specific topic. Returns an unsubscribe function.
+ *
+ * Pass `options.onError` to handle listener exceptions (default: `console.error`).
+ *
+ * @example
+ * ```ts
+ * const unsubscribe = busSubscribe('user-updated', (msg) => {
+ *   console.log(msg);
+ * });
+ * unsubscribe();
+ *
+ * // Custom error handler
+ * busSubscribe('x', handler, { onError: (e) => reportBug(e) });
+ * ```
+ */
+export declare const busSubscribe: <T extends IEventBus>(topic: T["topic"], listener: TEventBusListener<T["message"]>, options?: IEventBusSubscribeOptions) => TEventBusUnsubscribe;
+/**
+ * Subscribes to a topic and automatically unsubscribes after the first
+ * matching dispatch.
+ *
+ * @example
+ * ```ts
+ * busOnce('ready', () => startApp());
+ * ```
+ */
+export declare const busOnce: <T extends IEventBus>(topic: T["topic"], listener: TEventBusListener<T["message"]>, options?: IEventBusSubscribeOptions) => TEventBusUnsubscribe;

package/dist/types/tools/eventBus/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./eventBus";
+export type { IEventBus, IEventBusSubscribeOptions, TEventBusListener, TEventBusUnsubscribe, TEventMessage, TEventTopic, } from "./types";
+export * from "./useEventBus";

package/dist/types/tools/eventBus/types.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Generic event-bus shape. Extend this interface for typed dispatch/subscribe.
+ *
+ * @example
+ * ```ts
+ * interface UserLoggedIn extends IEventBus<{ id: number; name: string }> {
+ *   topic: 'user:logged-in';
+ * }
+ * busDispatch<UserLoggedIn>('user:logged-in', { id: 1, name: 'John' });
+ * ```
+ */
+export interface IEventBus<T = unknown> {
+    topic: string;
+    message: T;
+}
+/**
+ * Listener callback shape.
+ */
+export type TEventBusListener<T = unknown> = (message: T) => void;
+/**
+ * Function returned by `busSubscribe` that removes the subscription.
+ */
+export type TEventBusUnsubscribe = () => void;
+/**
+ * Optional behavior for a subscription.
+ */
+export interface IEventBusSubscribeOptions {
+    /** Called with the error when the listener throws. Defaults to `console.error`. */
+    onError?: (error: unknown) => void;
+}
+/**
+ * Type helper: given an event map, extract the set of valid topic names.
+ *
+ * @example
+ * ```ts
+ * type Events = {
+ *   'user:login': { id: number };
+ *   'user:logout': void;
+ * };
+ * type Topic = TEventTopic<Events>; // 'user:login' | 'user:logout'
+ * ```
+ */
+export type TEventTopic<Map> = keyof Map & string;
+/**
+ * Type helper: given an event map and a topic, extract the message payload.
+ */
+export type TEventMessage<Map, Topic extends TEventTopic<Map>> = Map[Topic];

package/dist/types/tools/eventBus/useEventBus.d.ts

@@ -0,0 +1,3 @@
+import { type DependencyList } from "react";
+import type { IEventBus, TEventBusListener } from "./types";
+export declare const useEventBus: <T extends IEventBus>(topic: T["topic"], listener: TEventBusListener<T["message"]>, deps?: DependencyList) => void;

package/dist/types/tools/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./cache-api";
+export * from "./deepClone";
+export * from "./dom";
+export * from "./eventBus";
+export * from "./isEqual";

package/dist/types/tools/isEqual.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Deeply compares two values for structural equality.
+ *
+ * Supports: primitives (with NaN-equals-NaN), Arrays, Sets, Maps, Dates,
+ * RegExp (source + flags), Errors (name + message), TypedArrays,
+ * ArrayBuffer/DataView (byte-wise), and plain objects. Handles circular
+ * references via cycle tracking.
+ *
+ * Sets with non-primitive members use order-independent deep comparison
+ * (O(n²) worst case).
+ *
+ * @example
+ * ```ts
+ * isEqual({ a: 1, b: 2 }, { b: 2, a: 1 }); // true
+ * isEqual([1, 2, 3], [1, 2, 3]); // true
+ * isEqual(new Set([{ id: 1 }]), new Set([{ id: 1 }])); // true
+ * isEqual(/foo/gi, /foo/gi); // true
+ * isEqual(new Uint8Array([1, 2]), new Uint8Array([1, 2])); // true
+ * ```
+ */
+export declare const isEqual: <T, K>(obj: T | T[], objToCompare: K | K[]) => boolean;

package/dist/types/types/index.d.ts

@@ -0,0 +1,61 @@
+/**
+ * A dictionary with string keys and values of type T.
+ */
+export type TDict<T = unknown> = Record<string, T>;
+/**
+ * Object with string or number keys and values of type T.
+ */
+export type TObjType<T = unknown> = {
+    [key: string | number]: T;
+};
+/**
+ * Recursively applies `Partial` to every nested object property. Primitives
+ * and arrays pass through unchanged.
+ *
+ * @example
+ * ```ts
+ * type A = DeepPartial<{ a: { b: { c: number } } }>;
+ * // { a?: { b?: { c?: number } } }
+ * ```
+ */
+export type DeepPartial<T> = T extends object ? {
+    [K in keyof T]?: DeepPartial<T[K]>;
+} : T;
+/**
+ * Recursively applies `Readonly` to every nested object property.
+ *
+ * @example
+ * ```ts
+ * type Config = DeepReadonly<{ flags: { debug: boolean } }>;
+ * // { readonly flags: { readonly debug: boolean } }
+ * ```
+ */
+export type DeepReadonly<T> = T extends object ? {
+    readonly [K in keyof T]: DeepReadonly<T[K]>;
+} : T;
+/**
+ * Removes `readonly` modifiers from every property (top level only).
+ *
+ * @example
+ * ```ts
+ * const tuple = [1, 2, 3] as const;
+ * type T = Mutable<typeof tuple>; // number[]
+ * ```
+ */
+export type Mutable<T> = {
+    -readonly [K in keyof T]: T[K];
+};
+/**
+ * Flattens an intersection or mapped type into a single object literal so it
+ * shows up clean in IDE tooltips. Pure type-level; no runtime impact.
+ *
+ * @example
+ * ```ts
+ * type A = { a: number };
+ * type B = { b: string };
+ * type C = Prettify<A & B>; // { a: number; b: string }
+ * ```
+ */
+export type Prettify<T> = {
+    [K in keyof T]: T[K];
+} & {};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pivanov/utils",
-  "version": "0.0.3",
-  "description": "A collection of personal utilities to live a happier life",
+  "version": "1.0.0",
+  "description": "A focused collection of TypeScript utilities for modern web development",
   "type": "module",
   "repository": {
     "type": "git",
@@ -11,6 +11,20 @@
   "bugs": {
     "url": "https://github.com/pivanov/pivanov-utils/issues"
   },
+  "scripts": {
+    "build": "rm -rf dist && bun run scripts/build.ts && bun x tsc --emitDeclarationOnly",
+    "test": "bun test",
+    "test:coverage": "bun test --coverage",
+    "lint": "biome lint .",
+    "format": "biome format . --write",
+    "check": "biome check . --write",
+    "typecheck": "bun x tsc --noEmit",
+    "docs:dev": "bun x vitepress dev docs",
+    "docs:build": "bun x vitepress build docs",
+    "docs:preview": "bun x vitepress preview docs",
+    "prepublishOnly": "bun run build",
+    "publish": "npm publish --access public"
+  },
   "author": {
     "name": "Pavel Ivanov",
     "email": "iweb.ivanov@gmail.com",
@@ -29,14 +43,45 @@
     "promise"
   ],
   "license": "MIT",
-  "main": "dist/cjs/index.js",
-  "module": "dist/esm/index.js",
-  "types": "dist/index.d.ts",
+  "sideEffects": false,
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/types/index.d.ts",
   "exports": {
     ".": {
-      "types": "./dist/index.d.ts",
+      "types": "./dist/types/index.d.ts",
       "import": "./dist/esm/index.js",
       "require": "./dist/cjs/index.js"
+    },
+    "./assertion": {
+      "types": "./dist/types/assertion/index.d.ts",
+      "import": "./dist/esm/assertion/index.js",
+      "require": "./dist/cjs/assertion/index.js"
+    },
+    "./object": {
+      "types": "./dist/types/object/index.d.ts",
+      "import": "./dist/esm/object/index.js",
+      "require": "./dist/cjs/object/index.js"
+    },
+    "./promise": {
+      "types": "./dist/types/promise/index.d.ts",
+      "import": "./dist/esm/promise/index.js",
+      "require": "./dist/cjs/promise/index.js"
+    },
+    "./string": {
+      "types": "./dist/types/string/index.d.ts",
+      "import": "./dist/esm/string/index.js",
+      "require": "./dist/cjs/string/index.js"
+    },
+    "./tools": {
+      "types": "./dist/types/tools/index.d.ts",
+      "import": "./dist/esm/tools/index.js",
+      "require": "./dist/cjs/tools/index.js"
+    },
+    "./types": {
+      "types": "./dist/types/types/index.d.ts",
+      "import": "./dist/esm/types/index.js",
+      "require": "./dist/cjs/types/index.js"
     }
   },
   "files": [
@@ -46,42 +91,27 @@
     "react": ">=18",
     "react-dom": ">=18"
   },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    }
+  },
   "devDependencies": {
-    "@biomejs/biome": "^1.9.4",
-    "@rollup/plugin-commonjs": "^28.0.0",
-    "@rollup/plugin-node-resolve": "^15.3.0",
-    "@rollup/plugin-typescript": "^12.1.1",
-    "@testing-library/dom": "^10.4.0",
+    "@biomejs/biome": "^2.4.11",
+    "@happy-dom/global-registrator": "^15.11.7",
     "@testing-library/react": "^16.0.1",
-    "@testing-library/react-hooks": "^8.0.1",
-    "@types/node": "^22.9.0",
+    "@types/bun": "^1.1.14",
     "@types/react": "^18.3.12",
     "@types/react-dom": "^18.3.1",
-    "@vercel/ncc": "0.38.2",
-    "@vitest/coverage-v8": "^2.1.4",
-    "evt": "^2.4.18",
-    "glob": "^11.0.0",
-    "husky": "^4.3.0",
-    "jsdom": "^25.0.1",
     "react": "^18.3.1",
     "react-dom": "^18.3.1",
-    "rollup": "^4.23.0",
-    "rollup-plugin-dts": "^6.1.1",
-    "rollup-plugin-terser": "^7.0.2",
-    "tslib": "^2.7.0",
-    "typescript": "5.7.2",
-    "vitest": "^2.1.4"
+    "typescript": "^5.7.2",
+    "vitepress": "~1.5.0"
   },
   "publishConfig": {
     "access": "public"
-  },
-  "scripts": {
-    "build": "rm -rf dist && pnpm rollup -c",
-    "test": "pnpm vitest",
-    "test:coverage": "pnpm vitest --coverage",
-    "test:ui": "pnpm vitest --ui",
-    "lint": "biome lint .",
-    "format": "biome format . --write",
-    "check": "biome check . --write"
   }
-}
+}