@stacksjs/utils 0.70.88 → 0.70.90

package/dist/markdown.js

@@ -0,0 +1,92 @@
+export function markdownTable(table, options = {}) {
+  const {
+    align = [],
+    padding = !0,
+    delimiter = "|",
+    delimiterStart = !0,
+    delimiterEnd = !0,
+    alignDelimiter = "-"
+  } = options;
+  if (!table || table.length === 0)
+    return "";
+  const normalized = table.map((row) => row.map((cell) => {
+    if (cell === null || cell === void 0)
+      return "";
+    return String(cell);
+  })), columnCount = Math.max(...normalized.map((row) => row.length)), columnWidths = Array.from({ length: columnCount }).fill(0);
+  for (const row of normalized)
+    for (let i = 0;i < row.length; i++) {
+      const cellLength = row[i]?.length ?? 0;
+      if (cellLength > (columnWidths[i] ?? 0))
+        columnWidths[i] = cellLength;
+    }
+  const rows = [];
+  if (normalized.length > 0) {
+    const header = normalized[0] ?? [];
+    rows.push(buildRow(header, columnWidths, padding, delimiter, delimiterStart, delimiterEnd));
+    const separatorCells = columnWidths.map((width, index) => {
+      const alignment = normalizeAlignment(align[index]);
+      return buildSeparator(width, alignment, alignDelimiter);
+    });
+    rows.push(buildRow(separatorCells, columnWidths, padding, delimiter, delimiterStart, delimiterEnd));
+    for (let i = 1;i < normalized.length; i++) {
+      const dataRow = normalized[i] ?? [];
+      rows.push(buildRow(dataRow, columnWidths, padding, delimiter, delimiterStart, delimiterEnd));
+    }
+  }
+  return rows.join(`
+`);
+}
+function buildRow(cells, columnWidths, padding, delimiter, delimiterStart, delimiterEnd) {
+  const paddedCells = cells.map((cell, index) => {
+    const width = columnWidths[index] ?? 0;
+    return cell.padEnd(width, " ");
+  }), space = padding ? " " : "";
+  let row = paddedCells.map((cell) => `${space}${cell}${space}`).join(delimiter);
+  if (delimiterStart)
+    row = delimiter + row;
+  if (delimiterEnd)
+    row = row + delimiter;
+  return row;
+}
+function buildSeparator(width, alignment, char) {
+  const minWidth = alignment === "center" ? 3 : alignment ? 2 : 1;
+  if (width < minWidth)
+    width = minWidth;
+  let separator = char.repeat(width);
+  if (alignment === "left")
+    separator = `:${separator.slice(1)}`;
+  else if (alignment === "right")
+    separator = separator.slice(0, -1) + ":";
+  else if (alignment === "center")
+    separator = `:${separator.slice(2)}:`;
+  return separator;
+}
+function normalizeAlignment(align) {
+  if (!align)
+    return null;
+  switch (align) {
+    case "l":
+    case "left":
+      return "left";
+    case "c":
+    case "center":
+      return "center";
+    case "r":
+    case "right":
+      return "right";
+    default:
+      return null;
+  }
+}
+export function markdownTableFromObjects(objects, options = {}) {
+  if (!objects || objects.length === 0)
+    return "";
+  const keys = Array.from(new Set(objects.flatMap((obj) => Object.keys(obj)))), table = [
+    keys,
+    ...objects.map((obj) => keys.map((key) => obj[key]))
+  ];
+  return markdownTable(table, options);
+}
+
+export { markdownTable as default };

package/dist/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/merge.js

@@ -0,0 +1,51 @@
+export function merge(...objects) {
+  const result = {};
+  for (const obj of objects) {
+    if (!obj || typeof obj !== "object")
+      continue;
+    for (const key in obj) {
+      const value = obj[key], existing = result[key];
+      if (value === void 0)
+        continue;
+      if (Array.isArray(value))
+        result[key] = Array.isArray(existing) ? [...existing, ...value] : [...value];
+      else if (value && typeof value === "object" && !isSpecialObject(value))
+        result[key] = merge(existing || {}, value);
+      else
+        result[key] = value;
+    }
+  }
+  return result;
+}
+export function createMerger(defaults) {
+  return (...objects) => {
+    return merge(defaults, ...objects);
+  };
+}
+export function mergeDefaults(obj, ...defaults) {
+  return merge({}, ...defaults, obj);
+}
+function isSpecialObject(obj) {
+  if (obj instanceof Date)
+    return !0;
+  if (obj instanceof RegExp)
+    return !0;
+  if (obj instanceof Error)
+    return !0;
+  if (obj instanceof Promise)
+    return !0;
+  if (obj instanceof Map)
+    return !0;
+  if (obj instanceof Set)
+    return !0;
+  if (obj instanceof WeakMap)
+    return !0;
+  if (obj instanceof WeakSet)
+    return !0;
+  if (ArrayBuffer.isView(obj))
+    return !0;
+  return !1;
+}
+export const defu = mergeDefaults, defuArrayFn = merge;
+
+export { merge as default };

package/dist/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/observer.js

@@ -0,0 +1,78 @@
+export function isResizeObserverSupported() {
+  return typeof window < "u" && "ResizeObserver" in window;
+}
+export function getResizeObserver() {
+  if (isResizeObserverSupported())
+    return window.ResizeObserver;
+  return class ResizeObserverPolyfill {
+    callback;
+    observedElements = new Set;
+    rafId = null;
+    constructor(callback) {
+      this.callback = callback;
+    }
+    observe(target) {
+      if (!this.observedElements.has(target)) {
+        this.observedElements.add(target);
+        this.scheduleCheck();
+      }
+    }
+    unobserve(target) {
+      this.observedElements.delete(target);
+      if (this.observedElements.size === 0 && this.rafId !== null) {
+        (typeof cancelAnimationFrame < "u" ? cancelAnimationFrame : clearTimeout)(this.rafId);
+        this.rafId = null;
+      }
+    }
+    disconnect() {
+      this.observedElements.clear();
+      if (this.rafId !== null) {
+        (typeof cancelAnimationFrame < "u" ? cancelAnimationFrame : clearTimeout)(this.rafId);
+        this.rafId = null;
+      }
+    }
+    scheduleCheck() {
+      if (this.rafId !== null)
+        return;
+      const raf = typeof requestAnimationFrame < "u" ? requestAnimationFrame : setTimeout;
+      this.rafId = raf(() => {
+        this.check();
+        this.rafId = null;
+        if (this.observedElements.size > 0)
+          this.scheduleCheck();
+      });
+    }
+    check() {
+      const entries = [];
+      for (const element of this.observedElements) {
+        const rect = element.getBoundingClientRect(), entry = {
+          target: element,
+          contentRect: rect,
+          borderBoxSize: [{ inlineSize: rect.width, blockSize: rect.height }],
+          contentBoxSize: [{ inlineSize: rect.width, blockSize: rect.height }],
+          devicePixelContentBoxSize: [{ inlineSize: rect.width, blockSize: rect.height }]
+        };
+        entries.push(entry);
+      }
+      if (entries.length > 0)
+        this.callback(entries, this);
+    }
+  };
+}
+export function createResizeObserver(callback, target) {
+  const observer = new (getResizeObserver())(callback), targets = Array.isArray(target) ? target : [target];
+  for (const element of targets)
+    observer.observe(element);
+  return () => {
+    observer.disconnect();
+  };
+}
+export function observeElementSize(element, callback) {
+  return createResizeObserver((entries) => {
+    const entry = entries.find((e) => e.target === element);
+    if (entry)
+      callback(entry);
+  }, element);
+}
+export const ResizeObserver = getResizeObserver();
+export default ResizeObserver;

package/dist/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/pipeline.js

@@ -0,0 +1,37 @@
+export class Pipeline {
+  passable;
+  pipes = [];
+  method = "handle";
+  static send(passable) {
+    const pipeline = new Pipeline;
+    pipeline.passable = passable;
+    return pipeline;
+  }
+  through(pipes) {
+    this.pipes = pipes;
+    return this;
+  }
+  pipe(...pipes) {
+    this.pipes.push(...pipes);
+    return this;
+  }
+  via(method) {
+    this.method = method;
+    return this;
+  }
+  then(destination) {
+    return this.pipes.reduceRight((next, pipe) => {
+      return (passable) => {
+        if (typeof pipe === "function")
+          return pipe(passable, next);
+        const handler = pipe[this.method];
+        if (typeof handler === "function")
+          return handler.call(pipe, passable, next);
+        return next(passable);
+      };
+    }, destination)(this.passable);
+  }
+  thenReturn() {
+    return this.then((passable) => passable);
+  }
+}

package/dist/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/safe-json.js

@@ -0,0 +1,33 @@
+export function safeJsonParse(text, defaultValue) {
+  if (typeof text !== "string" || text.length === 0)
+    return defaultValue;
+  try {
+    return JSON.parse(text);
+  } catch {
+    return defaultValue;
+  }
+}
+export function safeJsonParseResult(text) {
+  if (typeof text !== "string")
+    return { ok: !1, reason: "not-string" };
+  if (text.length === 0)
+    return { ok: !1, reason: "empty" };
+  try {
+    return { ok: !0, value: JSON.parse(text) };
+  } catch (err) {
+    return { ok: !1, reason: "malformed", error: err };
+  }
+}
+export function safeJsonStringify(value, space) {
+  const seen = new WeakSet;
+  return JSON.stringify(value, (_key, v) => {
+    if (typeof v === "bigint")
+      return v.toString();
+    if (v && typeof v === "object") {
+      if (seen.has(v))
+        return "[Circular]";
+      seen.add(v);
+    }
+    return v;
+  }, space);
+}

package/dist/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/size.js

@@ -0,0 +1,66 @@
+import { stat } from "node:fs/promises";
+import { join } from "node:path";
+import { formatBytes } from "./bytes";
+export async function getFileSize(filePath) {
+  try {
+    return (await stat(filePath)).size;
+  } catch {
+    return 0;
+  }
+}
+export async function getExportsSize(distPath) {
+  const exports = [];
+  let totalSize = 0;
+  try {
+    const files = await getAllJsFiles(distPath);
+    for (const file of files) {
+      const size = await getFileSize(file.path);
+      totalSize += size;
+      exports.push({
+        name: file.name,
+        size,
+        readable: formatBytes(size)
+      });
+    }
+  } catch (error) {}
+  return {
+    totalSize,
+    totalReadable: formatBytes(totalSize),
+    exports: exports.sort((a, b) => b.size - a.size)
+  };
+}
+async function getAllJsFiles(dir) {
+  const files = [];
+  try {
+    const entries = await Bun.$.throws(!1)`find ${dir} -type f \\( -name "*.js" -o -name "*.mjs" -o -name "*.cjs" \\)`.text();
+    for (const entry of entries.split(`
+`).filter(Boolean)) {
+      const name = entry.replace(dir, "").replace(/^\//, "");
+      files.push({ name, path: entry });
+    }
+  } catch {}
+  return files;
+}
+export function estimateGzipSize(size) {
+  return Math.floor(size * 0.3);
+}
+export function estimateBrotliSize(size) {
+  return Math.floor(size * 0.25);
+}
+export function formatExportSizes(result) {
+  if (result.exports.length === 0)
+    return "No exports found";
+  const lines = ["Export Sizes:", ""], maxNameLength = Math.max(...result.exports.map((e) => e.name.length));
+  for (const exp of result.exports) {
+    const name = exp.name.padEnd(maxNameLength, " ");
+    lines.push(`  ${name}  ${exp.readable}`);
+  }
+  lines.push("");
+  lines.push(`Total: ${result.totalReadable}`);
+  lines.push(`Estimated gzipped: ${formatBytes(estimateGzipSize(result.totalSize))}`);
+  lines.push(`Estimated brotli: ${formatBytes(estimateBrotliSize(result.totalSize))}`);
+  return lines.join(`
+`);
+}
+
+export { getExportsSize as default };

package/dist/utils.d.ts

@@ -0,0 +1,2 @@
+export declare const components: string[];
+export declare const functions: string[];

package/dist/utils.js

@@ -0,0 +1,6 @@
+var __dirname = "";
+import { resolve } from "@stacksjs/path";
+import { fs } from "@stacksjs/storage";
+import { kebabCase } from "@stacksjs/strings";
+const ignore = ["readme-md"];
+export const components = fs.readdirSync(resolve(__dirname, "./resources/components")).map((item) => kebabCase(item.replace(/\.(stx|vue)/g, ""))).filter((item) => !ignore.includes(item)), functions = fs.readdirSync(resolve(__dirname, "./resources/functions")).map((item) => kebabCase(item.replace(/.ts/g, ""))).filter((item) => !ignore.includes(item));

package/dist/versions.d.ts

@@ -0,0 +1,8 @@
+import { version } from '../package.json';
+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 declare const semver: typeof Bun.semver;
+export { version };

package/dist/versions.js

@@ -0,0 +1,19 @@
+import { version } from "../package.json";
+export const semver = Bun.semver;
+export function isVersionGreaterThan(version, compareVersion) {
+  return Bun.semver.order(version, compareVersion) === 1;
+}
+export function isVersionLessThan(version, compareVersion) {
+  return Bun.semver.order(version, compareVersion) === -1;
+}
+export function isVersionEqual(version, compareVersion) {
+  return Bun.semver.order(version, compareVersion) === 0;
+}
+export function isVersionGreaterThanOrEqual(version, compareVersion) {
+  return Bun.semver.order(version, compareVersion) >= 0;
+}
+export function isVersionLessThanOrEqual(version, compareVersion) {
+  return Bun.semver.order(version, compareVersion) <= 0;
+}
+
+export { version };

package/package.json

@@ -2,7 +2,7 @@
   "name": "@stacksjs/utils",
   "type": "module",
   "sideEffects": false,
-  "version": "0.70.88",
+  "version": "0.70.90",
   "description": "The Stacks helper functions.",
   "author": "Chris Breuer",
   "contributors": [
@@ -58,20 +58,20 @@
     "size": "bun scripts/export-size.ts"
   },
   "dependencies": {
-    "@stacksjs/browser": "0.70.88"
+    "@stacksjs/browser": "0.70.90"
   },
   "devDependencies": {
-    "@stacksjs/actions": "0.70.88",
-    "@stacksjs/arrays": "0.70.88",
-    "@stacksjs/cli": "0.70.88",
-    "@stacksjs/config": "0.70.88",
+    "@stacksjs/actions": "0.70.90",
+    "@stacksjs/arrays": "0.70.90",
+    "@stacksjs/cli": "0.70.90",
+    "@stacksjs/config": "0.70.90",
     "better-dx": "^0.2.16",
     "filesize": "^11.0.22",
     "markdown-table": "^3.0.4",
-    "@stacksjs/lint": "0.70.88",
-    "@stacksjs/path": "0.70.88",
-    "@stacksjs/storage": "0.70.88",
-    "@stacksjs/strings": "0.70.88",
-    "@stacksjs/types": "0.70.88"
+    "@stacksjs/lint": "0.70.90",
+    "@stacksjs/path": "0.70.90",
+    "@stacksjs/storage": "0.70.90",
+    "@stacksjs/strings": "0.70.90",
+    "@stacksjs/types": "0.70.90"
   }
 }