@stacksjs/utils 0.53.1 → 0.56.23

package/dist/index.d.ts

@@ -1,15 +1,377 @@
-export * from './base';
-export * from './config';
-export * from './currency';
-export * from './debounce';
-export * from './delete';
-export * from './equal';
-export * from './function';
-export * from './guards';
-export * from './helpers';
-export * from './math';
-export * from './p';
-export * from './promise';
-export * from './throttle';
-export * from './vendors';
-export * from './versions';
+import { AppOptions, CacheOptions, CdnOptions, UserCliOptions, CronJobOptions, JobOptions, DatabaseOptions, DebugOptions, DnsOptions, EmailOptions, Events, GitOptions, HashingOptions, LibraryOptions, Model, NotificationOptions, PagesOption, PaymentOptions, QueueOptions, SearchEngineOptions, ServicesOptions, StorageOptions, UiOptions, Nullable, Fn, Manifest, NpmScript, CliOptions, CommandResult } from '@stacksjs/types';
+export { Currency, Dinero, add, allocate, compare, convert, dinero as currency, dinero, equal, greaterThan, greaterThanOrEqual, hasSubUnits, haveSameAmount, haveSameCurrency, isZero, lessThan, lessThanOrEqual, maximum, minimum, dinero as money, multiply, normalizeScale, subtract, toDecimal, toSnapshot, toUnits, trimScale } from 'dinero.js';
+export { USD } from '@dinero.js/currencies';
+export { debounce } from 'perfect-debounce';
+export { rimraf as del, rimraf } from 'rimraf';
+import { AddressInfo } from 'node:net';
+export { asyncComputed, autoResetRef, breakpointsAntDesign, breakpointsBootstrapV5, breakpointsMasterCss, breakpointsQuasar, breakpointsSematic, breakpointsTailwind, breakpointsVuetify, cloneFnJSON, computedAsync, computedEager, computedInject, computedWithControl, controlledComputed, controlledRef, createEventHook, createFetch, createGlobalState, createInjectionState, createReactiveFn, createReusableTemplate, createSharedComposable, createTemplatePromise, createUnrefFn, customStorageEventName, debouncedRef, debouncedWatch, defaultDocument, defaultLocation, defaultNavigator, defaultWindow, eagerComputed, executeTransition, extendRef, formatTimeAgo, getSSRHandler, ignorableWatch, isDefined, mapGamepadToXbox360Controller, onClickOutside, onKeyDown, onKeyPressed, onKeyStroke, onKeyUp, onLongPress, onStartTyping, setSSRHandler, syncRef, syncRefs, templateRef, throttledRef, throttledWatch, toReactive, tryOnBeforeMount, tryOnBeforeUnmount, tryOnMounted, tryOnScopeDispose, tryOnUnmounted, unrefElement, until, useActiveElement, useAnimate, useAsyncQueue, useAsyncState, useBase64, useBattery, useBluetooth, useBreakpoints, useBroadcastChannel, useBrowserLocation, useCached, useClipboard, useCloned, useColorMode, useConfirmDialog, useCssVar, useCurrentElement, useCycleList, useDark, useDateFormat, useDebouncedRefHistory, useDeviceMotion, useDeviceOrientation, useDevicePixelRatio, useDevicesList, useDisplayMedia, useDocumentVisibility, useDraggable, useDropZone, useElementBounding, useElementByPoint, useElementHover, useElementSize, useElementVisibility, useEventBus, useEventListener, useEventSource, useEyeDropper, useFavicon, useFetch, useFileDialog, useFileSystemAccess, useFocus, useFocusWithin, useFps, useFullscreen, useGamepad, useGeolocation, useIdle, useImage, useInfiniteScroll, useIntersectionObserver, useKeyModifier, useLocalStorage, useMagicKeys, useManualRefHistory, useMediaControls, useMediaQuery, useMemoize, useMemory, useMounted, useMouse, useMouseInElement, useMousePressed, useMutationObserver, useNavigatorLanguage, useNetwork, useNow, useObjectUrl, useOffsetPagination, useOnline, usePageLeave, useParallax, useParentElement, usePerformanceObserver, usePermission, usePointer, usePointerLock, usePointerSwipe, usePreferredColorScheme, usePreferredContrast, usePreferredDark, usePreferredLanguages, usePreferredReducedMotion, usePrevious, useRafFn, useRefHistory, useResizeObserver, useScreenOrientation, useScreenSafeArea, useScriptTag, useScroll, useScrollLock, useSessionStorage, useShare, useSorted, useSpeechRecognition, useSpeechSynthesis, useStepper, useStorage, useStorageAsync, useStyleTag, useSupported, useSwipe, useTemplateRefsList, useTextDirection, useTextSelection, useTextareaAutosize, useThrottledRefHistory, useTimeAgo, useTimeoutPoll, useTimestamp, useTitle, useToggle, useTransition, useUrlSearchParams, useUserMedia, useVModel, useVModels, useVibrate, useVirtualList, useWakeLock, useWebNotification, useWebSocket, useWebWorker, useWebWorkerFn, useWindowFocus, useWindowScroll, useWindowSize, watchArray, watchAtMost, watchDebounced, watchDeep, watchIgnorable, watchImmediate, watchOnce, watchPausable, watchThrottled, watchTriggerable, watchWithFilter, whenever } from '@vueuse/core';
+export { Head, HeadClient, HeadObject, HeadObjectPlain, HeadVuePlugin, HookBeforeDomUpdate, HookEntriesResolved, HookTagsResolved, LegacyHeadOptions, createHead, renderHeadToString } from '@vueuse/head';
+import * as semver from 'semver';
+export { semver };
+export { loadStacksConfig as config } from '@stacksjs/config';
+export { and, createGenericProjection, createProjection, logicNot, logicOr, not, or, useAbs, useAverage, useCeil, useClamp, useFloor, useMath, useMax, useMin, usePrecision, useProjection, useRound, useSum, useTrunc } from '@vueuse/math';
+
+declare function toString(v: any): string;
+declare function loop(times: number, callback: any): void;
+declare function getTypeName(v: any): string;
+
+declare function defineApp(config: Partial<AppOptions>): Partial<AppOptions>;
+declare function defineCache(config: Partial<CacheOptions>): Partial<CacheOptions>;
+declare function defineCdn(config: Partial<CdnOptions>): Partial<CdnOptions>;
+declare function defineCli(config: Partial<UserCliOptions>): Partial<UserCliOptions>;
+declare function defineCronJobsConfig(config: Partial<CronJobOptions>[]): Partial<CronJobOptions>[];
+declare function defineJobsConfig(config: Partial<JobOptions>[]): Partial<JobOptions>[];
+declare function defineDatabase(config: Partial<DatabaseOptions>): Partial<DatabaseOptions>;
+declare function defineDebugConfig(config: Partial<DebugOptions>): Partial<DebugOptions>;
+declare function defineDns(config: Partial<DnsOptions>): Partial<DnsOptions>;
+declare function defineEmailConfig(config: Partial<EmailOptions>): Partial<EmailOptions>;
+declare function defineEvents(config: Partial<Events>): Partial<Events>;
+declare function defineGit(config: Partial<GitOptions>): Partial<GitOptions>;
+declare function defineHashing(config: Partial<HashingOptions>): Partial<HashingOptions>;
+declare function defineLibrary(config: Partial<LibraryOptions>): Partial<LibraryOptions>;
+declare function defineModel(config: Partial<Model>): Partial<Model>;
+declare function defineNotification(config: Partial<NotificationOptions>): Partial<NotificationOptions>;
+declare function defineSms(config: Partial<NotificationOptions['sms']>): Partial<{
+    default: string;
+    from: string;
+    drivers: {
+        twilio: {
+            sid: string;
+            authToken: string;
+        };
+        nexmo: {
+            key: string;
+            secret: string;
+        };
+        gupshup: {
+            user: string;
+            password: string;
+        };
+        plivo: {
+            sid: string;
+            authToken: string;
+        };
+        sms77: {
+            key: string;
+        };
+        sns: {
+            region: string;
+            key: string;
+            secret: string;
+        };
+        telnyx: {
+            key: string;
+            messageProfileId: string;
+        };
+        termii: {
+            key: string;
+        };
+    };
+}>;
+declare function defineEmail(config: Partial<NotificationOptions['email']>): Partial<{
+    default: string;
+    from: {
+        name: string;
+        address: string;
+    };
+    drivers: {
+        smtp: {
+            host: string;
+            port: number;
+            secure: boolean;
+            auth: {
+                user: string;
+                pass: string;
+            };
+        };
+        sendgrid: {
+            key: string;
+            senderName: string;
+        };
+        emailjs: {
+            host: string;
+            user: string;
+            password: string;
+            port: number;
+            secure: boolean;
+        };
+        mailgun: {
+            key: string;
+            domain: string;
+            username: string;
+        };
+        mailjet: {
+            key: string;
+            secret: string;
+        };
+        mandrill: {
+            key: string;
+        };
+        netcore: {
+            key: string;
+        };
+        nodemailer: {
+            host: string;
+            user: string;
+            password: string;
+            port: number;
+            secure: boolean;
+        };
+        postmark: {
+            key: string;
+        };
+        ses: {
+            region: string;
+            key: string;
+            secret: string;
+        };
+    };
+}>;
+declare function defineChat(config: Partial<NotificationOptions['chat']>): Partial<{
+    default: string;
+    from: string;
+    drivers: {
+        slack?: {
+            appId: string;
+            clientId: string;
+            secret: string;
+        } | undefined;
+        msTeams?: {
+            appId: string;
+            clientId: string;
+            secret: string;
+        } | undefined;
+        discord?: {} | undefined;
+    };
+}>;
+declare function definePage(config: Partial<PagesOption>): Partial<PagesOption>;
+declare function definePayment(config: Partial<PaymentOptions>): Partial<PaymentOptions>;
+declare function defineQueue(config: Partial<QueueOptions>): Partial<QueueOptions>;
+declare function defineSearchEngine(config: Partial<SearchEngineOptions>): Partial<SearchEngineOptions>;
+declare function defineServices(config: Partial<ServicesOptions>): Partial<ServicesOptions>;
+declare function defineStorage(config: Partial<StorageOptions>): Partial<StorageOptions>;
+declare function defineUi(config: Partial<UiOptions>): Partial<UiOptions>;
+
+declare function isDeepEqual(value1: any, value2: any): boolean;
+
+/**
+ * Call every function in an array
+ */
+declare function batchInvoke(functions: Nullable<Fn>[]): void;
+/**
+ * Pass the value through the callback, and return the value
+ *
+ * @example
+ * ```
+ * function createUser(name: string): User {
+ *   return tap(new User, user => {
+ *     user.name = name
+ *   })
+ * }
+ * ```
+ */
+declare function tap<T>(value: T, callback: (value: T) => void): T;
+
+/**
+ * Type guard to filter out null-ish values
+ *
+ * @category Guards
+ * @example array.filter(notNullish)
+ */
+declare function notNullish<T>(v: T | null | undefined): v is NonNullable<T>;
+/**
+ * Type guard to filter out null values
+ *
+ * @category Guards
+ * @example array.filter(noNull)
+ */
+declare function noNull<T>(v: T | null): v is Exclude<T, null>;
+/**
+ * Type guard to filter out null-ish values
+ *
+ * @category Guards
+ * @example array.filter(notUndefined)
+ */
+declare function notUndefined<T>(v: T): v is Exclude<T, undefined>;
+/**
+ * Type guard to filter out falsy values
+ *
+ * @category Guards
+ * @example array.filter(isTruthy)
+ */
+declare function isTruthy<T>(v: T): v is NonNullable<T>;
+
+declare function isProjectCreated(): Promise<boolean>;
+declare function installIfVersionMismatch(): Promise<void>;
+declare function frameworkVersion(): Promise<string>;
+declare function isAppKeySet(): Promise<boolean>;
+/**
+ * Determines the utilized reset preset.
+ *
+ * @url https://www.npmjs.com/package/@unocss/reset
+ * @param preset
+ */
+declare function determineResetPreset(preset?: string): string[];
+/**
+ * Determines whether the specified value is a package manifest.
+ */
+declare function isManifest(obj: any): obj is Manifest;
+/**
+ * Determines whether the specified value is a string, null, or undefined.
+ */
+declare function isOptionalString(value: any): value is string | undefined;
+declare function setEnvValue(key: string, value: string): Promise<void>;
+/**
+ * Runs the specified NPM script in the package.json file.
+ */
+declare function runNpmScript(script: NpmScript, options?: CliOptions): Promise<CommandResult>;
+/**
+ * Determines whether the specified NPM script exists in the given manifest.
+ */
+declare function hasScript(manifest: Manifest, script: NpmScript): boolean;
+declare function parseYaml(content: any): any;
+/**
+ * Determines the level of debugging.
+ *
+ * The debug level is determined by the following:
+ * 1. The --verbose flag
+ * 2. The debug property in the app configuration
+ *
+ * Currently, we don't support a custom debug level,
+ * though, we would like to in the future.
+ *
+ * @param options
+ */
+declare function determineDebugLevel(options?: CliOptions): boolean;
+declare function isIpv6(address: AddressInfo): boolean;
+
+declare const clamp: (n: number, min: number, max: number) => number;
+declare function rand(min: number, max: number): number;
+
+interface POptions {
+    /**
+     * How many promises are resolved at the same time.
+     */
+    concurrency?: number | undefined;
+}
+declare class PInstance<T = any> extends Promise<Awaited<T>[]> {
+    items: Iterable<T>;
+    options?: POptions | undefined;
+    private promises;
+    get promise(): Promise<Awaited<T>[]>;
+    constructor(items?: Iterable<T>, options?: POptions | undefined);
+    add(...args: (T | Promise<T>)[]): void;
+    map<U>(fn: (value: Awaited<T>, index: number) => U): PInstance<Promise<U>>;
+    filter(fn: (value: Awaited<T>, index: number) => boolean | Promise<boolean>): PInstance<Promise<T>>;
+    forEach(fn: (value: Awaited<T>, index: number) => void): Promise<void>;
+    reduce<U>(fn: (previousValue: U, currentValue: Awaited<T>, currentIndex: number, array: Awaited<T>[]) => U, initialValue: U): Promise<U>;
+    clear(): void;
+    then(fn?: () => PromiseLike<any>): Promise<any>;
+    catch(fn?: (err: unknown) => PromiseLike<any>): Promise<any>;
+    finally(fn?: () => void): Promise<Awaited<T>[]>;
+}
+/**
+ * Utility for managing multiple promises.
+ *
+ * @see https://github.com/antfu/utils/tree/main/docs/p.md
+ * @category Promise
+ * @example
+ * ```
+ * import { p } from '@stacksjs/utils'
+ *
+ * const items = [1, 2, 3, 4, 5]
+ *
+ * await p(items)
+ *   .map(async i => await multiply(i, 3))
+ *   .filter(async i => await isEven(i))
+ * // [6, 12]
+ * ```
+ */
+declare function p<T = any>(items?: Iterable<T>, options?: POptions): PInstance<T>;
+
+interface SingletonPromiseReturn<T> {
+    (): Promise<T>;
+    /**
+     * Reset current staled promise.
+     * Await it to have proper shutdown.
+     */
+    reset: () => Promise<void>;
+}
+/**
+ * Promise with `resolve` and `reject` methods of itself
+ */
+interface ControlledPromise<T = void> extends Promise<T> {
+    resolve(value: T | PromiseLike<T>): void;
+    reject(reason?: any): void;
+}
+/**
+ * Create singleton promise function.
+ *
+ * @category Promise
+ */
+declare function createSingletonPromise<T>(fn: () => Promise<T>): SingletonPromiseReturn<T>;
+/**
+ * Create a promise lock.
+ *
+ * @category Promise
+ * @example
+ * ```
+ * const lock = createPromiseLock()
+ *
+ * lock.run(async () => {
+ *   await doSomething()
+ * })
+ *
+ * // in anther context:
+ * await lock.wait() // it will wait all tasking finished
+ * ```
+ */
+declare function createPromiseLock(): {
+    run<T = void>(fn: () => Promise<T>): Promise<T>;
+    wait(): Promise<void>;
+    isWaiting(): boolean;
+    clear(): void;
+};
+/**
+ * Return a Promise with `resolve` and `reject` methods
+ *
+ * @category Promise
+ * @example
+ * ```
+ * const promise = createControlledPromise()
+ *
+ * await promise
+ *
+ * // in anther context:
+ * promise.resolve(data)
+ * ```
+ */
+declare function createControlledPromise<T>(): ControlledPromise<T>;
+/**
+ * Promised `setTimeout`.
+ *
+ * @category Promise
+ */
+declare function sleep(ms: number, callback?: Fn<any>): Promise<void>;
+
+/**
+ * Throttle a function.
+ *
+ * @param fn
+ * @param wait
+ * @returns
+ *
+ * @example
+ * ```ts
+ * // logs window dimensions at most every 250ms
+ * window.addEventListener(
+ *   "resize",
+ *   throttle(function (evt) {
+ *     console.log(window.innerWidth)
+ *     console.log(window.innerHeight)
+ *   }, 250)
+ * )
+ */
+declare function throttle(fn: Function, wait?: number): (this: unknown, ...args: any[]) => void;
+
+export { ControlledPromise, SingletonPromiseReturn, batchInvoke, clamp, createControlledPromise, createPromiseLock, createSingletonPromise, defineApp, defineCache, defineCdn, defineChat, defineCli, defineCronJobsConfig, defineDatabase, defineDebugConfig, defineDns, defineEmail, defineEmailConfig, defineEvents, defineGit, defineHashing, defineJobsConfig, defineLibrary, defineModel, defineNotification, definePage, definePayment, defineQueue, defineSearchEngine, defineServices, defineSms, defineStorage, defineUi, determineDebugLevel, determineResetPreset, frameworkVersion, getTypeName, hasScript, installIfVersionMismatch, isAppKeySet, isDeepEqual, isIpv6, isManifest, isOptionalString, isProjectCreated, isTruthy, loop, noNull, notNullish, notUndefined, p, parseYaml, rand, runNpmScript, setEnvValue, sleep, tap, throttle, toString };