watch-selector/dist/types/api/type-predicates.d.ts

Runs a function when a selector is added to dom

/**
 * Type Predicates for User Disambiguation
 *
 * This module provides type guard functions that help users disambiguate
 * argument types when working with the watch-selector library's overloaded
 * functions. These predicates provide runtime type checking with TypeScript
 * type narrowing support.
 */
import type { ElementFn, Workflow } from "../types";
/**
 * Checks if a value is an HTMLElement.
 *
 * This predicate helps TypeScript understand when you're working with
 * actual DOM elements versus selectors or other types.
 *
 * @param value - The value to check
 * @returns True if the value is an HTMLElement, with type narrowing
 *
 * @example
 * ```typescript
 * import { isElement, text } from 'watch-selector';
 *
 * function processTarget(target: HTMLElement | string) {
 *   if (isElement(target)) {
 *     // TypeScript knows target is HTMLElement here
 *     text(target, 'Direct element');
 *   } else {
 *     // TypeScript knows target is string here
 *     text(target, 'CSS selector');
 *   }
 * }
 * ```
 */
export declare function isElement(value: any): value is HTMLElement;
/**
 * Checks if a value is a specific type of HTML element.
 *
 * This generic predicate allows checking for specific element types
 * like HTMLInputElement, HTMLButtonElement, etc.
 *
 * @param value - The value to check
 * @param constructor - The element constructor to check against
 * @returns True if the value is an instance of the specified element type
 *
 * @example
 * ```typescript
 * import { isElementType, value } from 'watch-selector';
 *
 * const element = document.getElementById('myInput');
 * if (isElementType(element, HTMLInputElement)) {
 *   // TypeScript knows element is HTMLInputElement
 *   value(element, 'typed value');
 * }
 * ```
 */
export declare function isElementType<T extends HTMLElement>(value: any, constructor: new () => T): value is T;
/**
 * Checks if a value is an input element (input, textarea, or select).
 *
 * Useful when working with form-related functions like value() and checked().
 *
 * @param value - The value to check
 * @returns True if the value is a form input element
 *
 * @example
 * ```typescript
 * import { isInputElement, value } from 'watch-selector';
 *
 * const element = document.querySelector('.form-field');
 * if (isInputElement(element)) {
 *   // Safe to use value() function
 *   value(element, 'new value');
 * }
 * ```
 */
export declare function isInputElement(value: any): value is HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement;
/**
 * Checks if a string is likely a CSS selector.
 *
 * This predicate uses heuristics to determine if a string looks like
 * a CSS selector versus plain text or other content.
 *
 * @param value - The value to check
 * @returns True if the value appears to be a CSS selector
 *
 * @example
 * ```typescript
 * import { isSelector, text } from 'watch-selector';
 *
 * function updateContent(target: string) {
 *   if (isSelector(target)) {
 *     // Treat as selector
 *     text(target, 'Updated via selector');
 *   } else {
 *     // Treat as content for generator mode
 *     return text(target);
 *   }
 * }
 * ```
 */
export declare function isSelector(value: any): value is string;
/**
 * Checks if a string represents a space-separated list of class names.
 *
 * Useful for distinguishing between CSS selectors and class lists
 * when using addClass, removeClass, etc.
 *
 * @param value - The value to check
 * @returns True if the value appears to be a class list
 *
 * @example
 * ```typescript
 * import { isClassList, addClass } from 'watch-selector';
 *
 * const classes = 'active highlighted selected';
 * if (isClassList(classes)) {
 *   // Safe to use as class names
 *   addClass(element, classes);
 * }
 * ```
 */
export declare function isClassList(value: any): value is string;
/**
 * Checks if a value is a valid style object.
 *
 * Used to distinguish between style objects and other types when
 * using the style() function.
 *
 * @param value - The value to check
 * @returns True if the value is a partial CSSStyleDeclaration object
 *
 * @example
 * ```typescript
 * import { isStyleObject, style } from 'watch-selector';
 *
 * const styles = { color: 'red', fontSize: '16px' };
 * if (isStyleObject(styles)) {
 *   // TypeScript knows this is a style object
 *   style(element, styles);
 * }
 * ```
 */
export declare function isStyleObject(value: any): value is Partial<CSSStyleDeclaration>;
/**
 * Checks if a value is an attribute object.
 *
 * Used to distinguish between attribute objects and other types
 * when using attr() or data() functions.
 *
 * @param value - The value to check
 * @returns True if the value is a plain object suitable for attributes
 *
 * @example
 * ```typescript
 * import { isAttributeObject, attr } from 'watch-selector';
 *
 * const attrs = { 'data-id': '123', 'aria-label': 'Button' };
 * if (isAttributeObject(attrs)) {
 *   attr(element, attrs);
 * }
 * ```
 */
export declare function isAttributeObject(value: any): value is Record<string, any>;
/**
 * Checks if a value is an ElementFn function.
 *
 * ElementFn functions are returned by DOM manipulation functions
 * when called in generator context.
 *
 * @param value - The value to check
 * @returns True if the value is an ElementFn
 *
 * @example
 * ```typescript
 * import { isElementFn, text } from 'watch-selector';
 *
 * const result = text('content');
 * if (isElementFn(result)) {
 *   // This is a generator function
 *   yield result;
 * }
 * ```
 */
export declare function isElementFn(value: any): value is ElementFn<any, any>;
/**
 * Checks if a value is a Workflow (async generator function).
 *
 * Workflows are used in the new async generator pattern with yield*.
 *
 * @param value - The value to check
 * @returns True if the value is a Workflow
 *
 * @example
 * ```typescript
 * import { isWorkflow } from 'watch-selector';
 *
 * async function* myWorkflow() {
 *   // workflow implementation
 * }
 *
 * if (isWorkflow(myWorkflow)) {
 *   yield* myWorkflow();
 * }
 * ```
 */
export declare function isWorkflow(value: any): value is Workflow<any>;
/**
 * Checks if a function is a generator function.
 *
 * @param value - The value to check
 * @returns True if the value is a generator function
 *
 * @example
 * ```typescript
 * import { isGeneratorFunction } from 'watch-selector';
 *
 * function* myGenerator() {
 *   yield 'value';
 * }
 *
 * if (isGeneratorFunction(myGenerator)) {
 *   // Handle as generator
 * }
 * ```
 */
export declare function isGeneratorFunction(value: any): value is GeneratorFunction;
/**
 * Checks if a function is an async generator function.
 *
 * @param value - The value to check
 * @returns True if the value is an async generator function
 *
 * @example
 * ```typescript
 * import { isAsyncGeneratorFunction } from 'watch-selector';
 *
 * async function* myAsyncGen() {
 *   yield 'value';
 * }
 *
 * if (isAsyncGeneratorFunction(myAsyncGen)) {
 *   // Handle as async generator
 * }
 * ```
 */
export declare function isAsyncGeneratorFunction(value: any): value is AsyncGeneratorFunction;
/**
 * Checks if a value is element-like (element or selector string).
 *
 * This combines the isElement and string check for functions that
 * accept either elements or selectors.
 *
 * @param value - The value to check
 * @returns True if the value is an element or string
 *
 * @example
 * ```typescript
 * import { isElementLike, text } from 'watch-selector';
 *
 * function updateText(target: any, content: string) {
 *   if (isElementLike(target)) {
 *     text(target, content);
 *   }
 * }
 * ```
 */
export declare function isElementLike(value: any): value is HTMLElement | string;
/**
 * Checks if we're currently in a generator context.
 *
 * This is useful for determining whether to return ElementFn
 * or execute directly.
 *
 * @returns True if code is executing within a generator
 *
 * @example
 * ```typescript
 * import { isInGeneratorContext, text } from 'watch-selector';
 *
 * function adaptiveText(content: string) {
 *   if (isInGeneratorContext()) {
 *     return text(content); // Return ElementFn
 *   } else {
 *     // Need element for direct mode
 *     throw new Error('Element required outside generator');
 *   }
 * }
 * ```
 */
export declare function isInGeneratorContext(): boolean;
type GeneratorFunction = (...args: any[]) => Generator<any, any, any>;
type AsyncGeneratorFunction = (...args: any[]) => AsyncGenerator<any, any, any>;
/**
 * Utility to cast a value to a specific element type after validation.
 *
 * This is a convenience function that combines type checking with casting.
 *
 * @param value - The value to cast
 * @param constructor - The element constructor to check against
 * @returns The value cast to the specified type, or null if invalid
 *
 * @example
 * ```typescript
 * import { asElement, value } from 'watch-selector';
 *
 * const input = asElement(element, HTMLInputElement);
 * if (input) {
 *   value(input, 'new value');
 * }
 * ```
 */
export declare function asElement<T extends HTMLElement>(value: any, constructor: new () => T): T | null;
/**
 * Type guard for checking if a value is null or undefined.
 *
 * Useful for filtering and null checks with proper type narrowing.
 *
 * @param value - The value to check
 * @returns True if the value is not null or undefined
 *
 * @example
 * ```typescript
 * import { isDefined } from 'watch-selector';
 *
 * const elements = [element1, null, element2, undefined]
 *   .filter(isDefined);
 * // elements is now HTMLElement[]
 * ```
 */
export declare function isDefined<T>(value: T | null | undefined): value is T;
/**
 * Combined predicate for valid DOM manipulation targets.
 *
 * Checks if a value can be used as a target for DOM functions.
 *
 * @param value - The value to check
 * @returns True if the value is a valid DOM target
 *
 * @example
 * ```typescript
 * import { isValidTarget, text } from 'watch-selector';
 *
 * if (isValidTarget(target)) {
 *   text(target, 'content');
 * }
 * ```
 */
export declare function isValidTarget(value: any): value is HTMLElement | string | null;
export {};
//# sourceMappingURL=type-predicates.d.ts.map