@stacksjs/utils 0.70.23 → 0.70.25

package/dist/src/bytes.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Format bytes to human-readable string
+ *
+ * @example
+ * ```ts
+ * formatBytes(1024) // '1 KB'
+ * formatBytes(1024, { binary: true }) // '1 KiB'
+ * formatBytes(1234567) // '1.2 MB'
+ * formatBytes(1234567, { precision: 2 }) // '1.23 MB'
+ * ```
+ */
+export declare function formatBytes(bytes: number, options?: BytesOptions): string;
+/**
+ * Parse human-readable byte string to number
+ *
+ * @example
+ * ```ts
+ * parseBytes('1 KB') // 1000
+ * parseBytes('1 KiB') // 1024
+ * parseBytes('1.5 MB') // 1500000
+ * ```
+ */
+export declare function parseBytes(input: string): number;
+/**
+ * Compare two byte values
+ */
+export declare function compareBytes(a: number | string, b: number | string): number;
+// Aliases
+export declare const prettyBytes: unknown;
+export declare const readableSize: unknown;
+/**
+ * Format bytes to human-readable string (pretty-bytes replacement)
+ */
+export declare interface BytesOptions {
+  precision?: number
+  binary?: boolean
+  space?: boolean
+  locale?: string
+  minimumFractionDigits?: number
+  maximumFractionDigits?: number
+}
+export { formatBytes as default };

package/dist/src/clean.d.ts

@@ -0,0 +1 @@
+export declare function cleanProject(): Promise<void>;

package/dist/src/colors.d.ts

@@ -0,0 +1,96 @@
+// Strip colors from text
+export declare function stripColors(text: string): string;
+// Check if colors are supported
+export declare function supportsColor(): boolean;
+// Color functions
+export declare const black: unknown;
+export declare const red: unknown;
+export declare const green: unknown;
+export declare const yellow: unknown;
+export declare const blue: unknown;
+export declare const magenta: unknown;
+export declare const cyan: unknown;
+export declare const white: unknown;
+export declare const gray: unknown;
+export declare const grey: unknown;
+// Bright colors
+export declare const lightRed: unknown;
+export declare const lightGreen: unknown;
+export declare const lightYellow: unknown;
+export declare const lightBlue: unknown;
+export declare const lightMagenta: unknown;
+export declare const lightCyan: unknown;
+export declare const lightGray: unknown;
+export declare const lightGrey: unknown;
+// Background colors
+export declare const bgBlack: unknown;
+export declare const bgRed: unknown;
+export declare const bgGreen: unknown;
+export declare const bgYellow: unknown;
+export declare const bgBlue: unknown;
+export declare const bgMagenta: unknown;
+export declare const bgCyan: unknown;
+export declare const bgWhite: unknown;
+// Bright background colors
+export declare const bgLightRed: unknown;
+export declare const bgLightGreen: unknown;
+export declare const bgLightYellow: unknown;
+export declare const bgLightBlue: unknown;
+export declare const bgLightMagenta: unknown;
+export declare const bgLightCyan: unknown;
+// Text formatting
+export declare const bold: unknown;
+export declare const dim: unknown;
+export declare const italic: unknown;
+export declare const underline: unknown;
+export declare const inverse: unknown;
+export declare const hidden: unknown;
+export declare const strikethrough: unknown;
+// Reset
+export declare const reset: unknown;
+declare type ColorFn = (_text: string | number) => string;
+// Default export
+export default {
+  black,
+  red,
+  green,
+  yellow,
+  blue,
+  magenta,
+  cyan,
+  white,
+  gray,
+  grey,
+  lightRed,
+  lightGreen,
+  lightYellow,
+  lightBlue,
+  lightMagenta,
+  lightCyan,
+  lightGray,
+  lightGrey,
+  bgBlack,
+  bgRed,
+  bgGreen,
+  bgYellow,
+  bgBlue,
+  bgMagenta,
+  bgCyan,
+  bgWhite,
+  bgLightRed,
+  bgLightGreen,
+  bgLightYellow,
+  bgLightBlue,
+  bgLightMagenta,
+  bgLightCyan,
+  bold,
+  dim,
+  italic,
+  underline,
+  inverse,
+  hidden,
+  strikethrough,
+  reset,
+  stripColors,
+  supportsColor,
+};

package/dist/{config.d.ts → src/config.d.ts}

@@ -18,6 +18,6 @@ export {
   defineSearchEngine,
   defineServices,
   defineSms,
-  defineStorage,
+  defineFilesystems,
   defineUi,
-} from '@stacksjs/config'
+} from '@stacksjs/config';

package/dist/src/debounce.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Creates a debounced function that delays invoking func until after wait milliseconds
+ * have elapsed since the last time the debounced function was invoked.
+ *
+ * @param fn - The function to debounce
+ * @param wait - The number of milliseconds to delay
+ * @param options - Options object
+ * @returns The debounced function
+ */
+export declare function debounce<T extends (..._args: any[]) => any>(fn: T, wait?: number, options?: DebounceOptions): T & { cancel: () => void; flush: () => void };
+/**
+ * Creates a throttled function that only invokes func at most once per every wait milliseconds
+ *
+ * @param fn - The function to throttle
+ * @param wait - The number of milliseconds to throttle
+ * @returns The throttled function
+ */
+export declare function throttle<T extends (...args: any[]) => any>(fn: T, wait?: number): T & { cancel: () => void };
+/**
+ * Delays execution of a function
+ */
+export declare function delay(ms: number): Promise<void>;
+/**
+ * Debounce and throttle utilities (perfect-debounce replacement)
+ */
+export declare interface DebounceOptions {
+  leading?: boolean
+  trailing?: boolean
+}

package/dist/src/detect.d.ts

@@ -0,0 +1,35 @@
+export declare function detectIndent(text: string): IndentInfo;
+/**
+ * Detect newline type in a string
+ *
+ * @returns '\r\n' (CRLF - Windows), '\n' (LF - Unix), '\r' (CR - old Mac), or null
+ */
+export declare function detectNewline(text: string): '\r\n' | '\n' | '\r' | null;
+/**
+ * Detect newline type with graceful fallback
+ */
+export declare function detectNewlineGraceful(text: string, fallback?: '\r\n' | '\n'): '\r\n' | '\n' | '\r';
+/**
+ * Normalize newlines in text to specified type
+ */
+export declare function normalizeNewlines(text: string, newline?: '\r\n' | '\n' | '\r'): string;
+/**
+ * Count different types of newlines in text
+ */
+export declare function countNewlines(text: string): {
+  crlf: number
+  lf: number
+  cr: number
+  total: number
+};
+/**
+ * Text detection utilities (detect-indent and detect-newline replacements)
+ */
+/**
+ * Detect indentation type and amount in a string
+ */
+export declare interface IndentInfo {
+  amount: number
+  type: 'space' | 'tab' | null
+  indent: string
+}

package/dist/src/equal.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Deep equality with NaN-safety and cycle detection.
+ *
+ * - `NaN === NaN` is false in JavaScript, so the previous `Object.is`
+ *   tail correctly handled that case but only at the leaf — a
+ *   `[NaN, NaN]` pair compared element-by-element worked, but compound
+ *   structures relied on the tail. The new shape preserves that.
+ * - Circular references used to send isDeepEqual into infinite recursion
+ *   (`a.self = a; isDeepEqual(a, a)` blew the stack). A WeakSet of
+ *   already-visited objects breaks the cycle and treats two structurally
+ *   identical cycles as equal.
+ */
+export declare function isDeepEqual(value1: any, value2: any, seen?: WeakMap<object, object>): boolean;

package/dist/src/export-size.d.ts

@@ -0,0 +1,2 @@
+// Re-export from our native implementation
+export { getExportsSize } from './size';

package/dist/{find.d.ts → src/find.d.ts}

@@ -1,6 +1,4 @@
-declare const targetFileName: unknown;
+export declare function findStacksProjects(dir?: string, options?: FindStacksProjectsOptions): Promise<string[]>;
 declare interface FindStacksProjectsOptions {
   quiet?: boolean
 }
-export declare function findStacksProjects(dir?: string, options?: FindStacksProjectsOptions): Promise<string[]>;
-declare function searchDirectory(directory: string): Promise<string[]>;

package/dist/src/git.d.ts

@@ -0,0 +1 @@
+export declare function isGitClean(): boolean;

package/dist/{hash.d.ts → src/hash.d.ts}

@@ -1,3 +1,3 @@
 export declare function originRequestFunctionHash(): string | undefined;
 export declare function websiteSourceHash(): string | undefined;
-export declare function docsSourceHash(): string | undefined;
+export declare function docsSourceHash(): string | undefined;

package/dist/{helpers.d.ts → src/helpers.d.ts}

@@ -1,21 +1,53 @@
 import type { AddressInfo } from 'node:net';
 import type { CliOptions, Manifest, Subprocess } from '@stacksjs/types';
 import type { NpmScript } from '@stacksjs/enums';
-
+import type { Result } from '@stacksjs/error-handling';
+// Bun has native YAML support via Bun.YAML
+// import { semver } from './versions'
 export declare function packageManager(): Promise<string>;
 export declare function initProject(): Promise<Result<Subprocess, Error>>;
 export declare function ensureProjectIsInitialized(): Promise<boolean>;
 export declare function installIfVersionMismatch(): Promise<void>;
 export declare function frameworkVersion(): Promise<string>;
 export declare function isAppKeySet(): Promise<boolean>;
-export declare function determineResetPreset(preset?: string): string[];
+/**
+ * Determines the utilized reset preset.
+ *
+ * @url https://github.com/cwcss/crosswind
+ * @param preset
+ */
+export declare function determineResetPreset(preset?: string | null): string[];
+/**
+ * Determines whether the specified value is a package manifest.
+ */
 export declare function isManifest(obj: any): obj is Manifest;
-export declare function isOptionalString(value: any): value is string | undefined;
+/**
+ * Determines whether the specified value is a string, null, or undefined.
+ */
+export declare function isOptionalString(value: any): value is string | null | undefined;
 export declare function setEnvValue(key: string, value: string): Promise<void>;
+/**
+ * Runs the specified NPM script in the package.json file.
+ */
 export declare function runNpmScript(script: NpmScript, options?: CliOptions): Promise<Result<Subprocess, Error>>;
+/**
+ * Determines whether the specified NPM script exists in the given manifest.
+ */
 export declare function hasScript(manifest: Manifest, script: NpmScript): boolean;
 export 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
+ */
 export declare function determineDebugLevel(options?: CliOptions): boolean;
 export declare function isIpv6(address: AddressInfo): boolean;
-
-export { dump as dumpYaml, load as loadYaml } from 'js-yaml'
+export declare function dumpYaml(content: any): string;
+export declare function loadYaml(content: string): any;

package/dist/src/index.d.ts

@@ -0,0 +1,23 @@
+export * from './clean';
+export * from './config';
+export * from './equal';
+export * from './export-size';
+export * from './find';
+export * from './git';
+export * from './hash';
+export * from './helpers';
+export * from './macroable';
+export * from './safe-json';
+export * from './versions';
+export * as browserUtils from '@stacksjs/browser';
+export { clamp, notNullish, retry, useOnline } from '@stacksjs/browser';
+// Native utility replacements
+export * from './merge';
+export * from './detect';
+export * from './debounce';
+export * from './bytes';
+export * from './colors';
+export * from './markdown';
+export * from './size';
+export * from './observer';
+export * from './pipeline';

package/dist/src/macroable.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Create a macroable class
+ */
+export declare function createMacroable<T extends new (..._args: any[]) => any>(BaseClass?: T): T & MacroableConstructor;
+/**
+ * Mixin for adding macroable functionality to existing classes
+ */
+export declare function macroable<T extends new (..._args: any[]) => any>(target: T): T & MacroableConstructor;
+/**
+ * Native Macroable implementation
+ * Inspired by Laravel's Macroable trait - allows adding methods dynamically to classes
+ */
+export declare interface MacroableConstructor {
+  new (...args: any[]): any
+  macro(name: string, fn: Function, replace?: boolean): void
+  mixin(obj: Record<string, any>, replace?: boolean): void
+  hasMacro(name: string): boolean
+  flushMacros(): void
+  getMacros(): string[]
+}
+export declare class Macroable {
+  static macro(name: string, fn: Function, replace?: boolean): void;
+  static mixin(obj: Record<string, any>, replace?: boolean): void;
+  static hasMacro(name: string): boolean;
+  static flushMacros(): void;
+  static getMacros(): string[];
+  protected callMacro(name: string, ...args: any[]): any;
+}

package/dist/src/markdown.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Generate a markdown table from a 2D array
+ *
+ * @example
+ * ```ts
+ * const table = markdownTable([
+ *   ['Name', 'Age', 'City'],
+ *   ['Alice', 30, 'NYC'],
+ *   ['Bob', 25, 'LA']
+ * ])
+ * // | Name  | Age | City |
+ * // | ----- | --- | ---- |
+ * // | Alice | 30  | NYC  |
+ * // | Bob   | 25  | LA   |
+ * ```
+ */
+export declare function markdownTable(table: Table, options?: MarkdownTableOptions): string;
+/**
+ * Create a markdown table from objects
+ *
+ * @example
+ * ```ts
+ * const data = [
+ *   { name: 'Alice', age: 30 },
+ *   { name: 'Bob', age: 25 }
+ * ]
+ * const table = markdownTableFromObjects(data)
+ * ```
+ */
+export declare function markdownTableFromObjects<T extends Record<string, any>>(objects: T[], options?: MarkdownTableOptions): string;
+/**
+ * Markdown table generation (markdown-table replacement)
+ */
+export declare interface MarkdownTableOptions {
+  align?: Array<'l' | 'c' | 'r' | 'left' | 'center' | 'right' | null>
+  padding?: boolean
+  delimiter?: string
+  delimiterStart?: boolean
+  delimiterEnd?: boolean
+  alignDelimiter?: string
+}
+declare type CellValue = string | number | boolean | null | undefined;
+declare type Row = CellValue[];
+declare type Table = Row[];
+// Alias
+export { markdownTable as default };

package/dist/src/merge.d.ts

@@ -0,0 +1,20 @@
+export declare function merge<T extends Record<string, any>>(...objects: DeepPartial<T>[]): T;
+/**
+ * Create a merger function with defaults (defu-like API)
+ */
+export declare function createMerger<T extends Record<string, any>>(defaults: T): void;
+/**
+ * Merge with defaults (defu API)
+ */
+export declare function mergeDefaults<T extends Record<string, any>>(obj: DeepPartial<T>, ...defaults: DeepPartial<T>[]): T;
+// Aliases for defu compatibility
+export declare const defu: unknown;
+export declare const defuArrayFn: unknown;
+/**
+ * Deep merge objects (defu replacement)
+ *
+ * Merges multiple objects together, with later objects taking precedence.
+ * Arrays are concatenated, objects are recursively merged.
+ */
+declare type DeepPartial<T> = T extends object ? { [P in keyof T]?: DeepPartial<T[P]> } : T;
+export { merge as default };

package/dist/src/observer.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Check if ResizeObserver is supported natively
+ */
+export declare function isResizeObserverSupported(): boolean;
+/**
+ * Get ResizeObserver (native or polyfill)
+ *
+ * Modern browsers all support ResizeObserver, but this provides a fallback
+ */
+export declare function getResizeObserver(): any;
+/**
+ * Create a resize observer with automatic cleanup
+ *
+ * @example
+ * ```ts
+ * const cleanup = createResizeObserver((entries) => {
+ *   for (const entry of entries) {
+ *     console.log('Element resized:', entry.target)
+ *   }
+ * }, element)
+ *
+ * // Later, clean up
+ * cleanup()
+ * ```
+ */
+export declare function createResizeObserver(callback: ResizeObserverCallback, target: Element | Element[]): () => void;
+/**
+ * Observe element size changes
+ *
+ * @example
+ * ```ts
+ * const stop = observeElementSize(element, (entry) => {
+ *   console.log('Size:', entry.contentRect.width, entry.contentRect.height)
+ * })
+ *
+ * // Stop observing
+ * stop()
+ * ```
+ */
+export declare function observeElementSize(element: Element, callback: (entry: ResizeObserverEntry) => void): () => void;
+// Export the native ResizeObserver if available, or the polyfill
+export declare const ResizeObserver: any;
+/**
+ * ResizeObserver polyfill (resize-observer-polyfill replacement)
+ *
+ * Note: Modern browsers all support ResizeObserver natively now.
+ * This provides a simple fallback for older browsers.
+ */
+export declare interface ResizeObserverSize {
+  readonly inlineSize: number
+  readonly blockSize: number
+}
+export declare interface ResizeObserverEntry {
+  readonly target: Element
+  readonly contentRect: DOMRectReadOnly
+  readonly borderBoxSize: ReadonlyArray<ResizeObserverSize>
+  readonly contentBoxSize: ReadonlyArray<ResizeObserverSize>
+  readonly devicePixelContentBoxSize: ReadonlyArray<ResizeObserverSize>
+}
+export type ResizeObserverCallback = (
+  entries: ResizeObserverEntry[],
+  observer: ResizeObserver,
+) => void;
+export default ResizeObserver;

package/dist/src/pipeline.d.ts

@@ -0,0 +1,13 @@
+declare interface PipeClass<T> {
+  handle: PipeFunction<T>
+}
+declare type PipeFunction<T> = (data: T, next: (data: T) => T) => T;
+declare type Pipe<T> = PipeFunction<T> | PipeClass<T>;
+export declare class Pipeline<T> {
+  static send<T>(passable: T): Pipeline<T>;
+  through(pipes: Pipe<T>[]): this;
+  pipe(...pipes: Pipe<T>[]): this;
+  via(method: string): this;
+  then(destination: (data: T) => T): T;
+  thenReturn(): T;
+}

package/dist/src/safe-json.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Parse `text` as JSON, returning `defaultValue` (default: `undefined`)
+ * when the input isn't valid JSON.
+ *
+ * @example
+ * ```ts
+ * const config = safeJsonParse<Config>(rawText, { mode: 'default' })
+ * ```
+ */
+export declare function safeJsonParse<T = unknown>(text: unknown, defaultValue?: T): T | undefined;
+/**
+ * Result-flavored variant: surfaces *why* a parse failed when callers
+ * want to log the difference between "empty input" and "malformed input".
+ */
+// eslint-disable-next-line pickier/no-unused-vars
+export declare function safeJsonParseResult<T = unknown>(text: unknown): { ok: true, value: T } | { ok: false, reason: 'not-string' | 'empty' | 'malformed', error?: unknown };
+/**
+ * Stringify with cycle and bigint safety.
+ *
+ * `JSON.stringify` throws on circular refs (rare but real, e.g. logger
+ * captures of an Express-style req object) and on bigint values (common
+ * with database IDs that overflow Number). This wrapper substitutes
+ * `[Circular]` for cycles and converts bigints to strings — same shape
+ * downstream consumers expect from a "best-effort serialize this for
+ * logs" call.
+ */
+export declare function safeJsonStringify(value: unknown, space?: number): string;
+/**
+ * Safe JSON wrappers.
+ *
+ * Bare `JSON.parse(s)` throws `SyntaxError` on malformed input —
+ * which 90% of the time is exactly what you want, except in:
+ *
+ *   - Webhook handlers: a malformed payload should produce a 400, not crash
+ *   - Cache reads: a corrupt cache entry should miss, not throw
+ *   - Log readers: a bad line should be skipped, not stop the parser
+ *   - User-supplied config: a typo should produce a clear "X is invalid" error
+ *
+ * `safeJsonParse` returns `undefined` for malformed input (or a typed
+ * default), so call sites don't need a try/catch ladder around every
+ * untrusted input. `safeJsonParseResult` returns a discriminated union
+ * for cases where the failure reason matters.
+ */
+export type JsonValue = | string
+  | number
+  | boolean
+  | null
+  | JsonValue[]
+  | { [key: string]: JsonValue }

package/dist/src/size.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Get the size of a file
+ */
+export declare function getFileSize(filePath: string): Promise<number>;
+/**
+ * Get sizes of all exports in a package
+ *
+ * @example
+ * ```ts
+ * const sizes = await getExportsSize('./dist')
+ * console.log(sizes.totalReadable) // "42.5 KB"
+ * ```
+ */
+export declare function getExportsSize(distPath: string): Promise<PackageExportsSizeResult>;
+/**
+ * Get gzipped size estimate
+ */
+export declare function estimateGzipSize(size: number): number;
+/**
+ * Get brotli size estimate
+ */
+export declare function estimateBrotliSize(size: number): number;
+/**
+ * Format export sizes as a table
+ */
+export declare function formatExportSizes(result: PackageExportsSizeResult): string;
+export declare interface ExportSize {
+  name: string
+  size: number
+  readable: string
+}
+export declare interface PackageExportsSizeResult {
+  totalSize: number
+  totalReadable: string
+  exports: ExportSize[]
+}
+export { getExportsSize as default };

package/dist/{versions.d.ts → src/versions.d.ts}

@@ -1,10 +1,8 @@
 import { version } from '../package.json';
-
-export declare const semver: typeof Bun.semver;
 export declare function isVersionGreaterThan(version: string, compareVersion: string): boolean;
 export declare function isVersionLessThan(version: string, compareVersion: string): boolean;
 export declare function isVersionEqual(version: string, compareVersion: string): boolean;
 export declare function isVersionGreaterThanOrEqual(version: string, compareVersion: string): boolean;
 export declare function isVersionLessThanOrEqual(version: string, compareVersion: string): boolean;
-
-export { version }
+export declare const semver: typeof Bun.semver;
+export { version };