@stacksjs/browser 0.65.0

package/dist/utils/base.d.ts

@@ -0,0 +1,2 @@
+export { toString } from "@stacksjs/strings";
+export declare function loop(times: number, callback: any): Promise<void>;

package/dist/utils/debounce.d.ts

@@ -0,0 +1 @@
+export { debounce } from "perfect-debounce";

package/dist/utils/function.d.ts

@@ -0,0 +1,18 @@
+import type { Fn, Nullable } from "@stacksjs/types";
+/**
+* Call every function in an array
+*/
+export 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
+*   })
+* }
+* ```
+*/
+export declare function tap<T>(value: T, callback: (value: T) => void): T;

package/dist/utils/guards.d.ts

@@ -0,0 +1,28 @@
+/**
+* Type guard to filter out null-ish values
+*
+* @category Guards
+* @example array.filter(notNullish)
+*/
+export 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)
+*/
+export 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)
+*/
+export declare function notUndefined<T>(v: T): v is Exclude<T, undefined>;
+/**
+* Type guard to filter out falsy values
+*
+* @category Guards
+* @example array.filter(isTruthy)
+*/
+export declare function isTruthy<T>(v: T): v is NonNullable<T>;

package/dist/utils/index.d.ts

@@ -0,0 +1,11 @@
+export * from "./base";
+export * from "./debounce";
+export * from "./function";
+export * from "./guards";
+export * from "./math";
+export * from "./promise";
+export * from "./regex";
+export * from "./retry";
+export * from "./sleep";
+export * from "./throttle";
+export * from "./vendors";

package/dist/utils/math.d.ts

@@ -0,0 +1,3 @@
+export declare const clamp: (n: number, min: number, max: number) => number;
+export declare function rand(min: number, max: number): number;
+export { and, createGenericProjection, createProjection, logicNot, logicOr, or, useAbs, useAverage, useCeil, useClamp, useFloor, useMath, useMax, useMin, usePrecision, useProjection, useRound, useSum, useTrunc } from "@vueuse/math";

package/dist/utils/promise.d.ts

@@ -0,0 +1,58 @@
+export 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
+*/
+export interface ControlledPromise<T = void> extends Promise<T> {
+	resolve: (value: T | PromiseLike<T>) => void;
+	reject: (reason?: any) => void;
+}
+/**
+* Create singleton promise function.
+*
+* @category Promise
+*/
+export 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
+* ```
+*/
+export 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)
+* ```
+*/
+export declare function createControlledPromise<T>(): ControlledPromise<T>;

package/dist/utils/regex.d.ts

@@ -0,0 +1,3 @@
+export type { Flag, Input, MagicRegExp, MagicRegExpMatchArray, MapToStringCapturedBy, StringCapturedBy } from "magic-regexp";
+export { anyOf, carriageReturn, caseInsensitive, char, charIn, charNotIn, digit, dotAll, exactly, global, letter, linefeed, maybe, multiline, not, oneOrMore, sticky, tab, unicode, whitespace, withIndices, word, wordBoundary, wordChar } from "magic-regexp";
+export declare function createRegExp(pattern: string, options?: { flags?: string }): RegExp;

package/dist/utils/retry.d.ts

@@ -0,0 +1,2 @@
+export declare function retry(fn: Function, options: any): Promise<any>;
+export declare function calculateDelay(attemptCount: number, initialDelay: number, backoffFactor: number, jitter?: boolean): number;

package/dist/utils/sleep.d.ts

@@ -0,0 +1,37 @@
+export type NonNegativeInteger<T extends number> = number extends T ? never : `${T}` extends `-${string}` | `${string}.${string}` ? never : T;
+/**
+* Pauses execution for a specified number of milliseconds.
+* @param ms The number of milliseconds to pause execution.
+* @returns A promise that resolves after the specified delay.
+*/
+export declare function sleep(ms: number): Promise<void>;
+/**
+* Pauses execution for a specified number of milliseconds.
+* @param ms The number of milliseconds to pause execution.
+* @returns A promise that resolves after the specified delay.
+*/
+export declare function wait(ms: number): Promise<void>;
+/**
+* Pauses execution for a specified number of milliseconds.
+* @param ms The number of milliseconds to pause execution.
+* @returns A promise that resolves after the specified delay.
+*/
+export declare function delay(ms: number): Promise<void>;
+export type WaitOptions = number | {
+	interval?: number;
+	timeout?: number;
+};
+/**
+* Pauses execution until a specified condition is met.
+* @param condition The condition to wait for.
+* @param interval The interval at which to check the condition, in milliseconds. Defaults to 1000.
+* @returns A promise that resolves when the condition is met.
+*/
+export declare function waitUntil(condition: () => boolean, options?: WaitOptions): Promise<void>;
+/**
+* Pauses execution while a specified condition is met.
+* @param condition The condition to wait while.
+* @param interval The interval at which to check the condition, in milliseconds. Defaults to 1000.
+* @returns A promise that resolves when the condition is no longer met.
+*/
+export declare function waitWhile(condition: () => boolean, options?: WaitOptions): Promise<void>;

package/dist/utils/throttle.d.ts

@@ -0,0 +1,20 @@
+/**
+* Throttle a function.
+*
+* @param {Function} fn - The function to throttle.
+* @param {number} [wait] - The time to wait between function calls.
+* @returns {Function} - A new function that throttles the calls to the original function.
+*
+* @example
+* ```ts
+* // logs window dimensions at most every 250ms
+* window.addEventListener(
+*   "resize",
+*   throttle(function (evt) {
+*     console.log(window.innerWidth)
+*     console.log(window.innerHeight)
+*   }, 250)
+* )
+* ```
+*/
+export declare function throttle(fn: Function, wait?: number): (this: unknown, ...args: any[]) => void;

package/dist/utils/vendors.d.ts

@@ -0,0 +1,4 @@
+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, injectLocal, isDefined, makeDestructurable, mapGamepadToXbox360Controller, onClickOutside, onKeyDown, onKeyPressed, onKeyStroke, onKeyUp, onLongPress, onStartTyping, pausableWatch, provideLocal, reactify, reactifyObject, reactiveComputed, reactiveOmit, reactivePick, refAutoReset, refDebounced, refDefault, refThrottled, refWithControl, resolveRef, resolveUnref, setSSRHandler, syncRef, syncRefs, templateRef, throttledRef, throttledWatch, toReactive, tryOnBeforeMount, tryOnBeforeUnmount, tryOnMounted, tryOnScopeDispose, tryOnUnmounted, unrefElement, until, useActiveElement, useAnimate, useArrayDifference, useArrayEvery, useArrayFilter, useArrayFind, useArrayFindIndex, useArrayIncludes, useArrayMap, useArrayReduce, useArraySome, useArrayUnique, useAsyncQueue, useAsyncState, useBase64, useBattery, useBluetooth, useBreakpoints, useBroadcastChannel, useBrowserLocation, useCached, useClipboard, useClipboardItems, useCloned, useColorMode, useConfirmDialog, useCounter, useCssVar, useCurrentElement, useCycleList, useDark, useDateFormat, useDebounce, useDebouncedRefHistory, useDebounceFn, 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, useInterval, useIntervalFn, useKeyModifier, useLastChanged, 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, useTextareaAutosize, useTextDirection, useTextSelection, useThrottle, useThrottledRefHistory, useThrottleFn, useTimeAgo, useTimeout, useTimeoutFn, useTimeoutPoll, useTimestamp, useTitle, useToggle, useToNumber, useToString, useTransition, useUrlSearchParams, useUserMedia, useVibrate, useVirtualList, useVModel, useVModels, useWakeLock, useWebNotification, useWebSocket, useWebWorker, useWebWorkerFn, useWindowFocus, useWindowScroll, useWindowSize, watchArray, watchAtMost, watchDebounced, watchDeep, watchIgnorable, watchImmediate, watchOnce, watchPausable, watchThrottled, watchTriggerable, watchWithFilter, whenever } from "@vueuse/core";
+export type { HeadObject, HeadObjectPlain } from "@vueuse/head";
+export { createHead, Head, HeadVuePlugin, renderHeadToString } from "@vueuse/head";
+export { default as readableSize } from "pretty-bytes";

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@stacksjs/browser",
+  "type": "module",
+  "version": "0.65.0",
+  "description": "Stacks core frontend/browser functionalities.",
+  "author": "Chris Breuer",
+  "contributors": ["Chris Breuer <chris@stacksjs.org>"],
+  "license": "MIT",
+  "funding": "https://github.com/sponsors/chrisbbreuer",
+  "homepage": "https://github.com/stacksjs/stacks/tree/main/storage/framework/core/browser#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/stacksjs/stacks.git",
+    "directory": "./storage/framework/core/browser"
+  },
+  "bugs": {
+    "url": "https://github.com/stacksjs/stacks/issues"
+  },
+  "keywords": ["frontend", "browser", "stacks", "api"],
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "import": "./dist/index.js"
+    },
+    "./*": {
+      "bun": "./src/*",
+      "import": "./dist/*"
+    }
+  },
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": ["README.md", "dist", "src"],
+  "scripts": {
+    "build": "bun build.ts",
+    "typecheck": "bun tsc --noEmit",
+    "prepublishOnly": "bun run build"
+  },
+  "dependencies": {
+    "@stacksjs/utils": "0.64.6"
+  },
+  "devDependencies": {
+    "@stacksjs/development": "0.64.6"
+  }
+}

package/src/index.ts

@@ -0,0 +1 @@
+export * from './utils/'

package/src/utils/base.ts

@@ -0,0 +1,12 @@
+export { toString } from '@stacksjs/strings'
+
+// export function assert(condition: boolean, message: string): asserts condition {
+//   if (!condition)
+//     throw new Error(message)
+// }
+
+// export function noop() {}
+
+export async function loop(times: number, callback: any): Promise<void> {
+  Array.from({ length: times }).forEach(async (_, i) => await callback(i))
+}

package/src/utils/debounce.ts

@@ -0,0 +1 @@
+export { debounce } from 'perfect-debounce'

package/src/utils/function.ts

@@ -0,0 +1,32 @@
+import type { Fn, Nullable } from '@stacksjs/types'
+
+/**
+ * Call every function in an array
+ */
+export function batchInvoke(functions: Nullable<Fn>[]): void {
+  functions.forEach(fn => fn?.())
+}
+
+// /**
+//  * Call the function
+//  */
+// export function invoke(fn: Fn) {
+//   return fn()
+// }
+
+/**
+ * Pass the value through the callback, and return the value
+ *
+ * @example
+ * ```
+ * function createUser(name: string): User {
+ *   return tap(new User, user => {
+ *     user.name = name
+ *   })
+ * }
+ * ```
+ */
+export function tap<T>(value: T, callback: (value: T) => void): T {
+  callback(value)
+  return value
+}

package/src/utils/guards.ts

@@ -0,0 +1,39 @@
+/**
+ * Type guard to filter out null-ish values
+ *
+ * @category Guards
+ * @example array.filter(notNullish)
+ */
+export function notNullish<T>(v: T | null | undefined): v is NonNullable<T> {
+  return v != null
+}
+
+/**
+ * Type guard to filter out null values
+ *
+ * @category Guards
+ * @example array.filter(noNull)
+ */
+export function noNull<T>(v: T | null): v is Exclude<T, null> {
+  return v !== null
+}
+
+/**
+ * Type guard to filter out null-ish values
+ *
+ * @category Guards
+ * @example array.filter(notUndefined)
+ */
+export function notUndefined<T>(v: T): v is Exclude<T, undefined> {
+  return v !== undefined
+}
+
+/**
+ * Type guard to filter out falsy values
+ *
+ * @category Guards
+ * @example array.filter(isTruthy)
+ */
+export function isTruthy<T>(v: T): v is NonNullable<T> {
+  return Boolean(v)
+}

package/src/utils/index.ts

@@ -0,0 +1,11 @@
+export * from './base'
+export * from './debounce'
+export * from './function'
+export * from './guards'
+export * from './math'
+export * from './promise'
+export * from './regex'
+export * from './retry'
+export * from './sleep'
+export * from './throttle'
+export * from './vendors'

package/src/utils/math.ts

@@ -0,0 +1,30 @@
+export const clamp = (n: number, min: number, max: number): number => Math.min(max, Math.max(min, n))
+
+export function rand(min: number, max: number): number {
+  min = Math.ceil(min)
+  max = Math.floor(max)
+  return Math.floor(Math.random() * (max - min + 1)) + min
+}
+
+// not, -> exported as well in ../regex
+export {
+  and,
+  createGenericProjection,
+  createProjection,
+  logicNot,
+  logicOr,
+  or,
+  useAbs,
+  useAverage,
+  useCeil,
+  useClamp,
+  useFloor,
+  useMath,
+  useMax,
+  useMin,
+  usePrecision,
+  useProjection,
+  useRound,
+  useSum,
+  useTrunc,
+} from '@vueuse/math'

package/src/utils/promise.ts

@@ -0,0 +1,134 @@
+export interface SingletonPromiseReturn<T> {
+  (): Promise<T>
+  /**
+   * Reset current staled promise.
+   * Await it to have proper shutdown.
+   */
+  reset: () => Promise<void>
+}
+
+// export { peek } from 'bun'
+
+/**
+ * Promise with `resolve` and `reject` methods of itself
+ */
+export interface ControlledPromise<T = void> extends Promise<T> {
+  resolve: (value: T | PromiseLike<T>) => void
+  reject: (reason?: any) => void
+}
+
+/**
+ * Create singleton promise function.
+ *
+ * @category Promise
+ */
+export function createSingletonPromise<T>(fn: () => Promise<T>): SingletonPromiseReturn<T> {
+  let _promise: Promise<T> | undefined
+
+  function wrapper() {
+    if (!_promise)
+      _promise = fn()
+    return _promise
+  }
+
+  wrapper.reset = async () => {
+    const _prev = _promise
+    _promise = undefined
+    if (_prev)
+      await _prev
+  }
+
+  return wrapper
+}
+
+/**
+ * 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
+ * ```
+ */
+export function createPromiseLock() {
+  let currentPromise = Promise.resolve()
+  const queue: Promise<any>[] = []
+
+  return {
+    async run<T = void>(fn: () => Promise<T>): Promise<T> {
+      const runTask = async (): Promise<T> => {
+        await currentPromise
+        return fn()
+      }
+
+      const taskPromise = runTask()
+      queue.push(taskPromise)
+
+      currentPromise = taskPromise
+        .catch(() => {})
+        .finally(() => {
+          const index = queue.indexOf(taskPromise)
+          if (index > -1)
+            queue.splice(index, 1)
+        }) as Promise<void>
+
+      return taskPromise
+    },
+
+    async wait(): Promise<void> {
+      while (queue.length > 0) {
+        await Promise.all(queue)
+      }
+    },
+
+    isWaiting(): boolean {
+      return queue.length > 0
+    },
+
+    clear(): void {
+      queue.length = 0
+      currentPromise = Promise.resolve()
+    },
+  }
+}
+
+/**
+ * Return a Promise with `resolve` and `reject` methods
+ *
+ * @category Promise
+ * @example
+ * ```
+ * const promise = createControlledPromise()
+ *
+ * await promise
+ *
+ * // in anther context:
+ * promise.resolve(data)
+ * ```
+ */
+export function createControlledPromise<T>(): ControlledPromise<T> {
+  let resolve: any
+  let reject: any
+
+  const promise = new Promise<T>((_resolve, _reject) => {
+    resolve = _resolve
+    reject = _reject
+  }) as ControlledPromise<T>
+
+  promise.resolve = resolve
+
+  promise.reject = reject
+  return promise
+}
+
+/**
+ * Create a promise that will be resolved after `ms` milliseconds.
+ */
+// export { sleep, sleepSync } from 'bun'

package/src/utils/regex.ts

@@ -0,0 +1,42 @@
+export type {
+  Flag,
+  Input,
+  MagicRegExp,
+  MagicRegExpMatchArray,
+  MapToStringCapturedBy,
+  StringCapturedBy,
+} from 'magic-regexp'
+export {
+  anyOf,
+  carriageReturn,
+  caseInsensitive,
+  char,
+  charIn,
+  charNotIn,
+  digit,
+  dotAll,
+  exactly,
+  global,
+  letter,
+  linefeed,
+  maybe,
+  multiline,
+  not,
+  oneOrMore,
+  sticky,
+  tab,
+  unicode,
+  whitespace,
+  withIndices,
+  word,
+  wordBoundary,
+  wordChar,
+} from 'magic-regexp'
+
+// export function caseInsensitive(pattern: string): RegExp {
+//   return new RegExp(pattern, 'i')
+// }
+
+export function createRegExp(pattern: string, options: { flags?: string } = {}): RegExp {
+  return new RegExp(pattern, options.flags)
+}

package/src/utils/retry.ts

@@ -0,0 +1,43 @@
+// eslint-disable-next-line ts/no-unsafe-function-type
+export function retry(fn: Function, options: any): Promise<any> {
+  const { retries = 3, initialDelay = 1000, backoffFactor = 2, jitter = true } = options
+
+  return new Promise((resolve, reject) => {
+    let attemptCount = 0
+
+    const attempt = async () => {
+      try {
+        resolve(await fn())
+      }
+      catch (err) {
+        if (attemptCount >= retries) {
+          reject(err)
+        }
+        else {
+          const delay = calculateDelay(attemptCount, initialDelay, backoffFactor, jitter)
+          setTimeout(() => attempt(), delay)
+          attemptCount++
+        }
+      }
+    }
+
+    attempt()
+  })
+}
+
+export function calculateDelay(
+  attemptCount: number,
+  initialDelay: number,
+  backoffFactor: number,
+  jitter?: boolean,
+): number {
+  let delay = initialDelay * backoffFactor ** attemptCount
+
+  if (jitter) {
+    const random = Math.random() // Generates a number between 0 and 1
+    const jitterValue = delay * 0.3 // Jitter will be up to 30% of the delay
+    delay = delay + jitterValue * (random - 0.5) * 2 // Adjust delay randomly within ±30%
+  }
+
+  return delay
+}