@ibnlanre/portal/dist/index.d.cts

A simple, lightweight and flexible state management library for React applications.

import { Dispatch, DependencyList, FC, PropsWithChildren } from 'react';

/**
 * Represents the options for setting a cookie.
 */
type CookieOptions = {
    /**
     * The domain for which the cookie is valid.
     */
    domain?: string;
    /**
     * The expiration date or duration for the cookie.
     * It can be a number representing the number of seconds until expiration,
     * or a Date object specifying the exact expiration date and time.
     */
    expires?: Date | number;
    /**
     * Specifies if the cookie should be accessible only through HTTP requests and not through JavaScript code.
     */
    httpOnly?: boolean;
    /**
     * The maximum age of the cookie in seconds.
     */
    maxAge?: number;
    /**
     * Specifies if the cookie should be partitioned.
     */
    partitioned?: boolean;
    /**
     * The path for which the cookie is valid.
     */
    path?: string;
    /**
     * Specifies the SameSite attribute for the cookie.
     * It can be one of the following values: "Strict", "Lax", or "None".
     */
    sameSite?: "Lax" | "None" | "Strict";
    /**
     * Specifies if the cookie should only be transmitted over secure (HTTPS) connections.
     */
    secure?: boolean;
};

type CaseType = "camel" | "kebab" | "lower" | "pascal" | "sentence" | "title" | "upper";

type WordMappingSegments<CookieDescription extends string> = CookieDescription extends `${string} ${infer Tail}` ? [number, ...WordMappingSegments<Tail>] : [number];

interface CreateCookieKeyOptions<CookieFragmentDescription extends string> {
    /**
     * A descriptive phrase used to generate one or more fragments for the cookie key.
     * Often includes words to be shortened.
     *
     * @example "Verification Signature"
     */
    cookieFragmentDescription: CookieFragmentDescription;
    /**
     * Character(s) used to join the extracted word fragments.
     *
     * @default ""
     */
    cookieFragmentsConnector?: "" | "-" | "." | "_" | (string & {});
    /**
     * Array of numbers specifying how many letters to extract from each word in the description.
     * Defaults to extracting only one letter for each word if not provided.
     *
     * @example [2, 3]
     */
    cookieFragmentSizes?: number[] | WordMappingSegments<CookieFragmentDescription>;
    /**
     * Prefix added to the generated cookie key, e.g. for internal or system cookies.
     *
     * By convention, the prefix is usually one or two underscores.
     * The prefix is used to differentiate between regular and special cookies.
     *
     * @see {@link https://check-your-website.server-daten.de/prefix-cookies.html Why should you only use Prefix - Cookies?}
     *
     * @description
     *
     * - `""` (empty string) indicates no prefix.
     * - `"_"` is a common prefix for internal purposes (such as tracking user sessions).
     * - `"__"` is a common prefix for system-level operations (such as storing user preferences).
     *
     * @default ""
     */
    cookiePrefix?: "" | "_" | "__" | (string & {});
    /**
     * Logical scope indicating cookie usage context such as "host" or "secure".
     * Helps in classifying cookies based on their function.
     *
     * @default ""
     */
    cookieScope?: "" | "app" | "global" | "host" | "secure" | "session" | "user" | (string & {});
    /**
     * Specifies the casing format applied to the cookie scope.
     *
     * @default "title"
     */
    cookieScopeCase?: CaseType;
    /**
     * Symbol that separates the scope from the fragments in the final cookie key.
     *
     * @default "_"
     */
    cookieScopeFragmentConnector?: "-" | "." | "_" | (string & {});
    /**
     * Character(s) used to connect the scope and service strings, enhancing readability.
     *
     * @default "_"
     */
    cookieScopeServiceConnector?: "-" | "_" | (string & {});
    /**
     * Identifies the service or subsystem setting the cookie, like "auth" or "data".
     *
     * @default ""
     */
    cookieService?: "" | "auth" | "cache" | "config" | "data" | "log" | "store" | (string & {});
    /**
     * A suffix appended at the end of the cookie key, if required for differentiation.
     *
     * @default ""
     */
    cookieSuffix?: "" | "_" | "__" | (string & {});
}

/**
 * Represents the cookie storage.
 */
interface CookieStorage extends Storage {
    /**
     * Clears all cookies from cookieStorage.
     *
     * @returns {void}
     *
     * @example
     *
     * ```ts
     * cookieStorage.clear();
     * ```
     */
    clear: () => void;
    /**
     * Creates a cookie key based on the provided options.
     *
     * @param {CreateCookieKeyOptions} options The options to use when generating the cookie key.
     * @returns {string} The generated cookie key.
     *
     * @example
     *
     * ```ts
     * // __Secure-auth_vr-sgt
     *
     * cookieStorage.createKey({
     *  cookieFragmentDescription: "Verification Signature",
     *  cookiePrefix: "__",
     *  cookieFragmentSizes: [2, 3],
     *  cookieScope: "secure",
     *  cookieScopeCase: "title",
     *  cookieService: "auth",
     *  cookieScopeServiceConnector: "-",
     *  cookieScopeFragmentConnector: "_",
     *  cookieFragmentsConnector: "-",
     *  cookieSuffix: "",
     * });
     */
    createKey: <CookieFragmentDescription extends string>(options: CreateCookieKeyOptions<CookieFragmentDescription>) => string;
    /**
     * Retrieves the value of the cookie with the specified name from the document.cookie.
     *
     * @param {string} name The name of the cookie.
     * @returns {string|null} The value of the cookie, or null if the cookie is not found.
     *
     * @example
     *
     * ```ts
     * cookieStorage.getItem("cookie1"); // "value1"
     * ```
     */
    getItem: (name: string) => null | string;
    /**
     * Get a cookie by index from cookieStorage.
     *
     * @param {number} index The index of the cookie to retrieve.
     * @returns {string | null} The cookie value if found, or null if not found.
     *
     * @example
     *
     * ```ts
     * cookieStorage.key; // "cookie1"
     * ```
     */
    key: (index: number) => null | string;
    /**
     * Get the length of cookieStorage (the number of individual cookies).
     *
     * @returns {number} The number of cookies in cookieStorage.
     *
     * @example
     *
     * ```ts
     * cookieStorage.length; // 3
     * ```
     */
    length: number;
    /**
     * Removes a cookie with the specified name.
     *
     * @param {string} name The name of the cookie to be removed.
     * @param {string} [path] The path of the cookie to be removed.
     *
     * @returns {void}
     *
     * @example
     *
     * ```ts
     * cookieStorage.removeItem("cookie1");
     * ```
     */
    removeItem: (name: string, path?: string) => void;
    /**
     * Sets a cookie with the specified name and value.
     *
     * @param {string} name The name of the cookie.
     * @param {string} value The value to be set for the cookie.
     * @param {CookieOptions} [options] Optional cookie options.
     *
     * @returns {void}
     *
     * @example
     *
     * ```ts
     * cookieStorage.setItem("cookie1", "value1", { path: "/" });
     * ```
     */
    setItem: (name: string, value: string, options?: CookieOptions) => void;
    /**
     * Sign a cookie value.
     *
     * @param {string} value The value to sign.
     * @param {string} secret The secret to use for signing.
     *
     * @returns {string} The signed value.
     *
     * @example
     *
     * ```ts
     * cookieStorage.sign("unsignedValue", process.env.SECRET); // "signedValue"
     * ```
     */
    sign: (value: string, secret: string) => string;
    /**
     * Unsign a signed cookie.
     *
     * @param signedCookie The signed cookie to unsign.
     * @param secret The secret to use for unsigning.
     *
     * @returns The unsigned cookie or null if the signed cookie is invalid.
     *
     * @example
     *
     * ```ts
     * cookieStorage.unsign("signedValue", process.env.SECRET); // "unsignedValue"
     * ```
     */
    unsign: (signedCookie: string, secret: string) => null | string;
}

/**
 * An interface for a storage object.
 */
interface AsyncBrowserStorageAdapterOptions<State, StoredState = State> extends AsyncBrowserStorageTransforms<State, StoredState> {
    /**
     * Returns the current value associated with the given key, or null if the given key does not exist.
     *
     * @param key The key to retrieve the value for.
     * @returns The value associated with the key, or null if the key does not exist.
     */
    getItem(key: string): null | Promise<StoredState | undefined> | StoredState;
    /**
     * Removes the key/value pair with the given key, if a key/value pair with the given key exists.
     *
     * @param key The key to remove the value for.
     */
    removeItem(key: string): Promise<void> | void;
    /**
     * Sets the value of the pair identified by key to value, creating a new key/value pair if none existed for key previously.
     *
     * @param key The key to set the value for.
     * @param value The value to set.
     */
    setItem(key: string, value: StoredState): Promise<void> | void;
}
interface AsyncBrowserStorageTransforms<State, StoredState = State> {
    /**
     * A function to transform the value before setting it in storage.
     * This can be used to serialize or modify the value.
     *
     * @param value The value to transform.
     * @returns The transformed value.
     */
    beforeStorage?: (value: State) => StoredState;
    /**
     * A function to transform the value after getting it from storage.
     * This can be used to parse or modify the value.
     *
     * @param value The value to transform.
     * @returns The transformed value.
     */
    beforeUsage?: (value: StoredState) => State;
}
interface AsyncGetBrowserStorage<State> {
    /**
     * Get the state from storage or return a fallback state.
     *
     * @param fallback The fallback state to return if the state is not found in storage.
     * @returns The state from storage or the fallback state.
     */
    (fallback: State): Promise<State>;
    /**
     * Get the state from storage or return a fallback state.
     *
     * @param [fallback] The fallback state to return if the state is not found in storage.
     * @returns The state from storage, the fallback state, or undefined.
     */
    (fallback?: State): Promise<State | undefined>;
}
/**
 * Set the state in storage.
 *
 * @param value The state to set in storage.
 */
type AsyncSetBrowserStorage<State> = (value?: State) => Promise<void>;

type AsyncFunction<Data = unknown> = (controller: AbortController) => Promise<Data>;

type AsyncState<Data> = {
    data: Data;
    error: null;
    isLoading: false;
} | {
    data: null;
    error: Error;
    isLoading: false;
} | {
    data: null;
    error: null;
    isLoading: true;
};

interface StorageAdapterOptions<State> {
    /**
     * A function to parse the state from a string.
     *
     * @param value The string to parse.
     * @default JSON.parse
     *
     * @returns The parsed state.
     */
    parse?: (value: string) => State;
    /**
     * A function to serialize the state to a string.
     *
     * @param value The state to serialize.
     * @default JSON.stringify
     *
     * @returns The serialized state.
     */
    stringify?: (value: State) => string;
}

interface BrowserStorageAdapterOptions<State> extends StorageAdapterOptions<State>, StorageInterface {
}
interface GetBrowserStorage<State> {
    /**
     * Get the state from storage or return a fallback state.
     *
     * @param fallback The fallback state to return if the state is not found in storage.
     * @returns The state from storage or the fallback state.
     */
    (fallback: State): State;
    /**
     * Get the state from storage or return a fallback state.
     *
     * @param [fallback] The fallback state to return if the state is not found in storage.
     * @returns The state from storage, the fallback state, or undefined.
     */
    (fallback?: State): State | undefined;
}
/**
 * Set the state in storage.
 *
 * @param value The state to set in storage.
 */
type SetBrowserStorage<State> = (value?: State) => void;
/**
 * An interface for a storage object.
 */
interface StorageInterface {
    /**
     * Returns the current value associated with the given key, or null if the given key does not exist.
     *
     * @param key The key to retrieve the value for.
     * @returns The value associated with the key, or null if the key does not exist.
     */
    getItem(key: string): null | string;
    /**
     * Removes the key/value pair with the given key, if a key/value pair with the given key exists.
     *
     * @param key The key to remove the value for.
     */
    removeItem(key: string): void;
    /**
     * Sets the value of the pair identified by key to value, creating a new key/value pair if none existed for key previously.
     *
     * @param key The key to set the value for.
     * @param value The value to set.
     */
    setItem(key: string, value: string): void;
}

type Dictionary = {
    [k: number]: unknown;
    [k: string]: unknown;
    [k: symbol]: unknown;
};

type Prettify<T> = {
    [K in keyof T]: T[K];
} & {};

type Replace<Target, Source> = Target extends Dictionary ? Source extends Dictionary ? ReplaceHelper<Target, Source> : Source : Source;
type ReplaceHelper<Target extends Dictionary, Source extends Dictionary> = Prettify<Pick<Source, Exclude<keyof Source, keyof Target>> & Pick<Target, Exclude<keyof Target, keyof Source>> & {
    [Key in keyof Source & keyof Target]: Replace<Target[Key], Source[Key]>;
}>;

type UnionToIntersection<Union> = (Union extends unknown ? (k: Union) => void : never) extends (k: infer Intersection) => void ? Intersection : never;

type LastOfUnion<Union extends unknown> = UnionToIntersection<Union extends unknown ? (k: Union) => void : never> extends (k: infer Last) => void ? Last : never;

type UnionToTuple<Union> = UnionToTupleHelper<Union>;
type UnionToTupleHelper<Union, Tail = LastOfUnion<Union>, Rest = Exclude<Union, Tail>> = [Tail] extends [never] ? [] : [...UnionToTupleHelper<Rest>, Tail];

type Combine<Target extends Dictionary, Sources extends Dictionary[]> = UnionToTuple<Sources[number]> extends infer SourceTuple ? SourceTuple extends readonly Dictionary[] ? CombineHelper<Target, SourceTuple> : never : never;
type CombineHelper<Target extends Dictionary, Sources extends readonly Dictionary[]> = Sources extends [infer Head, ...infer Rest] ? Head extends Dictionary ? Rest extends readonly Dictionary[] ? CombineHelper<Replace<Target, Head>, Rest> : Replace<Target, Head> : Target : Target;

type Contains<T, Arr extends readonly unknown[]> = T extends Arr[number] ? 1 : 0;

type Paths<Store extends Dictionary, Delimiter extends string = "."> = PathsHelper<NonNullable<Store>, Delimiter>;
type PathsHelper<Store, Delimiter extends string, Visited extends readonly Dictionary[] = []> = Store extends Dictionary ? Contains<Store, Visited> extends 1 ? never : Exclude<{
    [Key in keyof Store]: Key extends number | string ? Store[Key] extends infer Value ? NonNullable<Value> extends Dictionary ? `${Key}${Delimiter}${PathsHelper<NonNullable<Value>, Delimiter, readonly [...Visited, Store]>}` | `${Key}` : `${Key}` : never : never;
}[keyof Store], undefined> : never;

type Primitives = bigint | boolean | null | number | string | symbol | undefined;

type DeepPartial<Argument> = Argument extends Primitives | Reference ? Argument : Argument extends Dictionary ? {
    [Key in keyof Argument]?: DeepPartial<Argument[Key]>;
} : never;
type Reference = Array<any> | ArrayBuffer | Atomics | BigInt64Array | BigUint64Array | DataView | Date | Error | Float32Array | Float64Array | Function | Int8Array | Int16Array | Int32Array | Map<any, any> | Promise<any> | ReadonlyArray<any> | ReadonlyMap<any, any> | ReadonlySet<any> | RegExp | Set<any> | SharedArrayBuffer | SharedArrayBufferConstructor | Uint8Array | Uint8ClampedArray | Uint16Array | Uint32Array | WeakMap<WeakKey, any> | WeakSet<WeakKey>;

type SetPartial<State> = DeepPartial<State> | Partial<State>;

type SetPartialStateAction<State> = ((prevState: State) => SetPartial<State>) | SetPartial<State>;

type PartialStateManager<State, Value = State> = [
    state: Value,
    dispatcher: Dispatch<SetPartialStateAction<State>>
];

type PartialStateSetter<State> = Dispatch<SetPartialStateAction<State>>;

type Selector<State, Value = State> = (state: State) => Value;

type Subscriber<State> = (value: State) => void;

type PrimitiveStore<State> = {
    readonly $act: (subscriber: Subscriber<State>, immediate?: boolean) => () => void;
    readonly $get: <Value = State>(selector?: Selector<State, Value>) => Value;
    readonly $set: PartialStateSetter<State>;
    readonly $use: <Value = State>(selector?: Selector<State, Value>, dependencies?: DependencyList) => PartialStateManager<State, Value>;
};

/**
 * Represents the value of a key in a store.
 *
 * @template Key The type of the key.
 */
type ParseAsNumber<Key extends number | string> = Key extends `${infer Value extends number}` ? Value : Key;

/**
 * Represents the split of a key.
 *
 * @template Key The type of the key.
 * @template Delimiter The type of the delimiter.
 *
 * @description It is a tuple of the split key.
 */
type Split<Key extends string, Delimiter extends string = "."> = SplitHelper<Key, Delimiter>;
type SplitHelper<Key extends string, Delimiter extends string, Result extends (number | string)[] = []> = Key extends `${infer Head}${Delimiter}${infer Tail}` ? SplitHelper<Tail, Delimiter, [...Result, ParseAsNumber<Head>]> : Key extends "" ? Result : [...Result, ParseAsNumber<Key>];

type Segments<Store extends Dictionary, Delimiter extends string = "."> = Split<Paths<Store, Delimiter>, Delimiter>;

type ResolveSegment<Store extends Dictionary, Key extends Segments<Store, Delimiter>, Delimiter extends string = "."> = Key extends [infer Head, ...infer Tail] ? Head extends keyof Store ? Tail extends [] ? Store[Head] : Store[Head] extends Dictionary ? Tail extends Segments<Store[Head], Delimiter> ? ResolveSegment<Store[Head], Tail, Delimiter> : never : never : never : never;

type ResolvePath<Store extends Dictionary, Key extends Paths<Store> = never, Delimiter extends string = "."> = Split<Key, Delimiter> extends infer Segment ? Segment extends Segments<Store, Delimiter> ? ResolveSegment<Store, Segment, Delimiter> : never : never;

type Defined<T> = (null | {}) & T;

type GenericFunction = (...args: any[]) => any;

type IsNever<T> = [T] extends [never] ? 1 : 0;

type StoreValueResolver<Value> = IsNever<Defined<Value>> extends 1 ? PrimitiveStore<undefined> : Defined<Value> extends Defined<Dictionary> ? CompositeStore<Defined<Value>> : Defined<Value> extends Defined<GenericFunction> ? Value : PrimitiveStore<Value>;

type KeyStore<State extends Dictionary> = PrimitiveStore<State> & {
    readonly $key: <Path extends Paths<State>>(path: Path) => StoreValueResolver<ResolvePath<State, Path>>;
};

type CompositeStore<Value extends Dictionary> = KeyStore<Value> & {
    readonly [Key in keyof Value]: StoreValueResolver<Value[Key]>;
};

type ContextStore<Context, Store> = [
    FC<PropsWithChildren<{
        value: Context;
    }>>,
    () => Store
];

type ContextValue<Context, Store> = (context: Context) => Store;

type CookieStorageAdapterOptions<State> = CookieDataOptions<State> & CookieSignature;
interface GetCookieStorage<State> {
    /**
     * Get the state from cookie storage.
     *
     * @returns The state from cookie storage or undefined.
     */
    (): State | undefined;
    /**
     * Get the state from cookie storage or return a fallback state.
     *
     * @param fallback The fallback state to return if the state is not found in cookie storage.
     * @returns The state from cookie storage or the fallback state.
     */
    (fallback: State): State;
}
/**
 * Set the state in cookie storage.
 *
 * @param value The state to set in cookie storage.
 * @param options The options to use when setting the cookie.
 */
type SetCookieStorage<State> = (value?: State, options?: CookieOptions) => void;
interface CookieDataOptions<State> extends CookieOptions, StorageAdapterOptions<State> {
}
type CookieSignature = {
    /**
     * The secret to use for signing the cookie.
     *
     * @throws An error if `signed` is true and `secret` is undefined.
     */
    secret: string | undefined;
    /**
     * Specifies if the cookie is designed for use by a single application.
     *
     * @throws An error if `signed` is true and `secret` is undefined.
     */
    signed: true;
} | {
    secret?: never;
    signed?: never;
} | {
    secret?: string;
    signed?: false;
};

type Initializer<State> = () => State;

type Factory<State> = Initializer<State> | State;

type InferType<Store extends PrimitiveStore<any>, Path extends Paths<Store extends CompositeStore<infer State> ? State : never> = never> = IsNever<Path> extends 1 ? Store extends PrimitiveStore<infer State> ? State : never : Store extends CompositeStore<infer State> ? ResolvePath<State, Path> : never;

interface GetLocalStorage<State> {
    /**
     * Get the state from local storage.
     *
     * @returns The state from local storage or undefined.
     */
    (): State | undefined;
    /**
     * Get the state from local storage or return a fallback state.
     *
     * @param fallback The fallback state to return if the state is not found in local storage.
     * @returns The state from local storage or the fallback state.
     */
    (fallback: State): State;
}
/**
 * Set the state in local storage.
 *
 * @param value The state to set in local storage.
 */
type SetLocalStorage<State> = (value?: State) => void;

type GenericObject = {
    [key: string]: any;
};

type Normalize<T extends GenericObject> = {
    [K in keyof (Dictionary | T)]: K extends keyof T ? T[K] : never;
};

interface GetSessionStorage<State> {
    /**
     * Get the state from session storage.
     *
     * @returns The state from session storage or undefined.
     */
    (): State | undefined;
    /**
     * Get the state from session storage or return a fallback state.
     *
     * @param fallback The fallback state to return if the state is not found in session storage.
     * @returns The state from session storage or the fallback state.
     */
    (fallback: State): State;
}
/**
 * Set the state in session storage.
 *
 * @param value The state to set in session storage.
 */
type SetSessionStorage<State> = (value?: State) => void;

type StatePath<State extends Dictionary, Path extends Paths<State> = never> = [Path] extends [never] ? State : ResolvePath<State, Path>;

/**
 * An object representing a cookie storage with various methods to interact with cookies.
 */
declare const cookieStorage: CookieStorage;

type Possible<Type> = Type | undefined;

/**
 * @example
 *
 * const count = createStore({
 *   value: 0,
 *   increase(amount: number = 1) {
 *     count.value.$set((state) => state + amount);
 *   },
 *   decrease(amount: number = 1) {
 *     count.value.$set((state) => state - amount);
 *   },
 * });
 *
 * count.increase(4);
 */
declare function createStore<State extends Dictionary>(state: Factory<State>): CompositeStore<State>;
/**
 * @example
 *
 * const fetchCount = async () => {
 *  const result = await fetch("https://api.example.com/count");
 *  const data = await result.json();
 *  return data.count;
 * };
 *
 * const count = await createStore(fetchCount);
 * count.$act((state) => console.log(state));
 * count.$set(78);
 */
declare function createStore<State>(state: Initializer<Promise<State>>): Promise<PrimitiveStore<State>>;
/**
 * @example
 *
 * const count = createStore(0);
 * count.$get(); // 0
 */
declare function createStore<State>(state: Factory<State>): PrimitiveStore<State>;
/**
 * @example
 *
 * const count = createStore<number>();
 */
declare function createStore<State>(state?: Possible<Factory<State | undefined>>): PrimitiveStore<State | undefined>;

declare function createAsyncBrowserStorageAdapter<State, StoredState = State>(key: string, { beforeStorage, beforeUsage, getItem, removeItem, setItem, }: AsyncBrowserStorageAdapterOptions<State, StoredState>): [
    getStorageState: AsyncGetBrowserStorage<State>,
    setStorageState: AsyncSetBrowserStorage<State>
];

declare function createBrowserStorageAdapter<State>(key: string, { getItem, parse, removeItem, setItem, stringify, }: BrowserStorageAdapterOptions<State>): [
    getStorageState: GetBrowserStorage<State>,
    setStorageState: SetBrowserStorage<State>
];

declare function createCookieStorageAdapter<State>(key: string, { parse, secret, signed, stringify, ...cookieOptions }?: CookieStorageAdapterOptions<State>): [
    getCookieStorageState: GetCookieStorage<State>,
    setCookieStorageState: SetCookieStorage<State>
];

declare function createLocalStorageAdapter<State>(key: string, { parse, stringify, }?: StorageAdapterOptions<State>): [
    getLocalStorageState: GetLocalStorage<State>,
    setLocalStorageState: SetLocalStorage<State>
];

declare function createSessionStorageAdapter<State>(key: string, { parse, stringify, }?: StorageAdapterOptions<State>): [
    getSessionStorageState: GetSessionStorage<State>,
    setSessionStorageState: SetSessionStorage<State>
];

/**
 * A simple and straightforward deep merge function that recursively merges objects.
 * Handles cyclic references to prevent infinite recursion.
 *
 * @param target The target object that will receive the merged values
 * @param source The source object to merge into the target
 *
 * @returns A new merged object without modifying any of the inputs
 */
declare function combine<Target extends Dictionary, Source extends Dictionary>(target: Target, source?: Source, cache?: WeakMap<object, object>): Source extends Dictionary ? Replace<Target, Source> : Target;
/**
 * A simple and straightforward deep merge function that recursively merges objects.
 * Handles cyclic references to prevent infinite recursion.
 *
 * @param target The target object that will receive the merged values
 * @param sources An array of source objects to merge into the target
 *
 * @returns A new merged object without modifying any of the inputs
 */
declare function combine<Target extends Dictionary, Sources extends Dictionary[]>(target: Target, sources: Sources, cache?: WeakMap<object, object>): Combine<Target, Sources>;

/**
 * A custom hook for handling asynchronous effects with loading, error, and data states.
 *
 * @param effect The async function to execute
 * @param dependencies Dependencies array to trigger re-execution
 *
 * @returns An object containing data, loading, error states and an execute function
 */
declare function useAsync<Data>(effect: AsyncFunction<Data>, dependencies?: DependencyList): AsyncState<Data>;

type SyncFunction<Data = unknown> = () => Data;

/**
 * A custom hook that computes data synchronously based on a factory function and optional dependencies.
 *
 * @param factory A function that produces the synchronous data.
 * @param dependencies An optional list of dependencies that, when changed, will trigger a re-computation of the data.
 *
 * @returns The computed data from the factory function.
 */
declare function useSync<Data>(factory: SyncFunction<Data>, dependencies?: DependencyList): Data;

/**
 * A custom hook that compares dependencies and returns a version number.
 * The version number increments only when the dependencies change.
 *
 * @param input The input value to compare against the previous value.
 * If not provided, it defaults to `undefined`.
 *
 * @returns An array containing the current version number.
 */
declare function useVersion(input?: unknown): number;

declare function createCompositeStore<State extends Dictionary>(initialState: State): CompositeStore<State>;

/**
 * Initializes a context store with a provider and a hook for accessing its value.
 *
 * @param use A hook function that generates the store from the given context.
 * @returns A tuple with the StoreProvider component and the useStore hook.
 */
declare function createContextStore<Context, Store>(use: ContextValue<Context, Store>): ContextStore<Context, Store>;

declare function createPrimitiveStore<State>(initialState: State): PrimitiveStore<State>;

declare function normalizeObject<State extends GenericObject>(state: State): Normalize<State>;

export { type AsyncBrowserStorageAdapterOptions, type AsyncBrowserStorageTransforms, type AsyncFunction, type AsyncGetBrowserStorage, type AsyncSetBrowserStorage, type AsyncState, type BrowserStorageAdapterOptions, type Combine, type CompositeStore, type ContextStore, type ContextValue, type CookieOptions, type CookieStorage, type CookieStorageAdapterOptions, type CreateCookieKeyOptions, type DeepPartial, type Dictionary, type Factory, type GetBrowserStorage, type GetCookieStorage, type GetLocalStorage, type GetSessionStorage, type InferType, type Initializer, type Normalize, type PartialStateManager, type PartialStateSetter, type Paths, type PrimitiveStore, type Replace, type ResolvePath, type Selector, type SetBrowserStorage, type SetCookieStorage, type SetLocalStorage, type SetPartial, type SetPartialStateAction, type SetSessionStorage, type StatePath, type StorageAdapterOptions, type StoreValueResolver, type Subscriber, type WordMappingSegments, combine, cookieStorage, createAsyncBrowserStorageAdapter, createBrowserStorageAdapter, createCompositeStore, createContextStore, createCookieStorageAdapter, createLocalStorageAdapter, createPrimitiveStore, createSessionStorageAdapter, createStore, normalizeObject, useAsync, useSync, useVersion };