@stacksjs/utils 0.70.88 → 0.70.91

package/dist/errors.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Error-handling helpers (stacksjs/stacks#1875 T-1).
+ *
+ * Background: a `catch (e: any)` block lets you reach `e.message`
+ * without a typecheck — but the thrown value isn't guaranteed to be
+ * an `Error`. Strings, numbers, plain objects, and even `null` can
+ * be thrown. `e.message` on a string returns `undefined`; on `null`
+ * it throws TypeError. `${e}` works but loses stack trace info.
+ *
+ * These helpers let catch blocks type `e` as `unknown` (the safe
+ * TypeScript default) and pull a useful string / stack out without
+ * branching at every site.
+ */
+/**
+ * Pull a human-readable message out of an unknown thrown value.
+ *
+ * Resolution order:
+ *   1. `Error.message` — the common case
+ *   2. plain-object `.message` — duck-typing for error-like values
+ *      from across a serialization boundary (HTTP responses, IPC, etc.)
+ *   3. `String(e)` — covers strings, numbers, booleans
+ *   4. `'Unknown error'` — for `null` / `undefined` thrown values
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await someAsyncOp()
+ * }
+ * catch (e: unknown) {
+ *   log.error(`Failed: ${getErrorMessage(e)}`)
+ * }
+ * ```
+ */
+export declare function getErrorMessage(e: unknown): string;
+/**
+ * Pull a stack trace out of an unknown thrown value, returning
+ * `undefined` when one isn't available. Useful for log enrichment
+ * without forcing the caller to narrow `e` first.
+ */
+export declare function getErrorStack(e: unknown): string | undefined;
+/**
+ * Pull a `.code` string out of an unknown thrown value. Common across
+ * AWS SDK errors (`'AlreadyExistsException'`, `'NoSuchEntity'`, …),
+ * Node fs errors (`'ENOENT'`, `'EACCES'`, …), and many HTTP-client
+ * libraries. Returns `undefined` when the input doesn't carry a
+ * string code, so callers can default-handle.
+ */
+export declare function getErrorCode(e: unknown): string | undefined;
+/**
+ * Pull an HTTP-style status code (`.statusCode` or `.status`) out of an
+ * unknown thrown value. AWS SDK errors use `.statusCode`; fetch/Node
+ * errors often use `.status`. Returns `undefined` when neither is a
+ * finite number — same default-handling pattern as `getErrorCode`.
+ */
+export declare function getErrorStatusCode(e: unknown): number | undefined;
+/**
+ * Coerce an unknown thrown value into a real `Error`. The thrown
+ * value is preserved on `.cause` (ES2022) when the input was a
+ * non-Error so debugging tools can still surface it. Idempotent —
+ * passing in an Error returns it unchanged.
+ *
+ * Use this when downstream APIs require an `Error` instance (e.g.
+ * tracing SDKs that want `captureException(Error)`).
+ */
+export declare function toError(e: unknown): Error;

package/dist/errors.js

@@ -0,0 +1,44 @@
+export function getErrorMessage(e) {
+  if (e instanceof Error)
+    return e.message;
+  if (typeof e === "string")
+    return e;
+  if (typeof e === "number" || typeof e === "boolean")
+    return String(e);
+  if (e && typeof e === "object" && "message" in e && typeof e.message === "string")
+    return e.message;
+  if (e == null)
+    return "Unknown error";
+  try {
+    return String(e);
+  } catch {
+    return "Unknown error";
+  }
+}
+export function getErrorStack(e) {
+  if (e instanceof Error)
+    return e.stack;
+  if (e && typeof e === "object" && "stack" in e && typeof e.stack === "string")
+    return e.stack;
+  return;
+}
+export function getErrorCode(e) {
+  if (e && typeof e === "object" && "code" in e && typeof e.code === "string")
+    return e.code;
+  return;
+}
+export function getErrorStatusCode(e) {
+  if (!e || typeof e !== "object")
+    return;
+  const obj = e;
+  if (typeof obj.statusCode === "number" && Number.isFinite(obj.statusCode))
+    return obj.statusCode;
+  if (typeof obj.status === "number" && Number.isFinite(obj.status))
+    return obj.status;
+  return;
+}
+export function toError(e) {
+  if (e instanceof Error)
+    return e;
+  return Error(getErrorMessage(e), { cause: e });
+}

package/dist/export-size.d.ts

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

package/dist/export-size.js

@@ -0,0 +1 @@
+export { getExportsSize } from "./size";

package/dist/find.d.ts

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

package/dist/find.js

@@ -0,0 +1,68 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { italic } from "@stacksjs/cli";
+import { log } from "@stacksjs/logging";
+const targetFileName = "buddy", alwaysExcludePatterns = [
+  "node_modules",
+  "dist",
+  "vendor",
+  "storage/framework",
+  /.*out.*/,
+  /.*\/\..*/
+], homeOnlyExcludePatterns = [
+  `${os.homedir()}/Documents`,
+  `${os.homedir()}/Pictures`,
+  `${os.homedir()}/Library`,
+  `${os.homedir()}/.Trash`
+];
+export async function findStacksProjects(dir, options) {
+  const dirWasExplicit = !!dir;
+  dir = dir || os.homedir();
+  const excludePatterns = dirWasExplicit ? alwaysExcludePatterns : [...alwaysExcludePatterns, ...homeOnlyExcludePatterns];
+  if (!options?.quiet) {
+    log.info(`Searching for Stacks projects in: ${italic(dir)}`);
+    log.info("This may take a few moments...");
+    console.log("");
+    console.log(italic("  Please note, while Stacks is searching for projects on your machine,"));
+    console.log(italic("  you may be asked for permissions to scan certain directories."));
+    console.log("");
+    log.debug(`Excluding directories: ${excludePatterns.join(", ")}`);
+  }
+  const foundProjects = await searchDirectory(dir, excludePatterns);
+  if (!foundProjects)
+    throw Error("No Stacks projects found");
+  return foundProjects;
+}
+async function searchDirectory(directory, excludePatterns) {
+  const foundProjects = [];
+  if (excludePatterns.some((pattern) => typeof pattern === "string" ? directory.includes(pattern) : pattern.test(directory)))
+    return foundProjects;
+  let items;
+  try {
+    items = await fs.readdir(directory, { withFileTypes: !0 });
+  } catch (error) {
+    console.error(`Error reading directory ${directory}:`, error);
+    return foundProjects;
+  }
+  let buddyFileFound = !1, storageDirFound = !1;
+  for (const item of items) {
+    if (item.isFile() && item.name === targetFileName)
+      buddyFileFound = !0;
+    if (item.isDirectory()) {
+      const fullPath = path.join(directory, item.name);
+      if (item.name === "storage") {
+        const storagePath = path.join(fullPath, "framework/core/buddy");
+        try {
+          await fs.access(storagePath);
+          storageDirFound = !0;
+        } catch {}
+      }
+      const subDirProjects = await searchDirectory(fullPath, excludePatterns);
+      foundProjects.push(...subDirProjects);
+    }
+  }
+  if (buddyFileFound && storageDirFound)
+    foundProjects.push(directory);
+  return foundProjects;
+}

package/dist/git.d.ts

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

package/dist/git.js

@@ -0,0 +1,11 @@
+import { execSync } from "node:child_process";
+import { handleError } from "@stacksjs/error-handling";
+export function isGitClean() {
+  try {
+    execSync("git diff-index --quiet HEAD --");
+    return !0;
+  } catch (error) {
+    handleError(error);
+    return !1;
+  }
+}

package/dist/glob.d.ts

@@ -0,0 +1 @@
+export { glob } from '@stacksjs/storage';

package/dist/glob.js

@@ -0,0 +1 @@
+export { glob } from "@stacksjs/storage";

package/dist/hash.d.ts

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

package/dist/hash.js

@@ -0,0 +1,36 @@
+import { config } from "@stacksjs/config";
+import { log } from "@stacksjs/logging";
+import { path } from "@stacksjs/path";
+import { hashPaths } from "@stacksjs/storage";
+export function originRequestFunctionHash() {
+  try {
+    return hashPaths(path.cloudPath("src/edge"));
+  } catch (error) {
+    log.error("Are we in a Docker container? Failed to hash paths. Error below:");
+    log.error(error);
+    return;
+  }
+}
+export function websiteSourceHash() {
+  const docsSrc = [
+    path.projectPath("docs"),
+    path.frameworkPath("docs/dist")
+  ], websiteSrc = [
+    path.projectPath("resources/views"),
+    path.projectPath("resources/assets"),
+    path.projectPath("resources/lang"),
+    path.projectPath("resources/functions"),
+    path.projectPath("resources/components"),
+    path.projectPath("resources/modules"),
+    path.projectPath("resources/stores"),
+    path.frameworkPath("views/web")
+  ];
+  return config.app.docMode === !0 ? hashPaths(docsSrc) : hashPaths(websiteSrc);
+}
+export function docsSourceHash() {
+  const docsSrc = [
+    path.projectPath("docs"),
+    path.frameworkPath("docs/dist")
+  ];
+  return hashPaths(docsSrc);
+}

package/dist/helpers.d.ts

@@ -0,0 +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>;
+/**
+ * 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;
+/**
+ * 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 declare function dumpYaml(content: any): string;
+export declare function loadYaml(content: string): any;

package/dist/helpers.js

@@ -0,0 +1,101 @@
+import { runAction } from "@stacksjs/actions";
+import { log, runCommand } from "@stacksjs/cli";
+import { app, ui } from "@stacksjs/config";
+import { Action } from "@stacksjs/enums";
+import { err, handleError, ok } from "@stacksjs/error-handling";
+import { frameworkPath, projectPath } from "@stacksjs/path";
+import { fs, readJsonFile, readPackageJson, readTextFile, writeTextFile } from "@stacksjs/storage";
+export async function packageManager() {
+  const { packageManager } = await readPackageJson(frameworkPath("package.json"));
+  return packageManager;
+}
+export async function initProject() {
+  if (app.env !== "production")
+    log.info("Project not yet initialized, generating application key...");
+  else
+    handleError("Please run `buddy key:generate` to generate an application key");
+  const result = await runAction(Action.KeyGenerate, { cwd: projectPath() });
+  if (result.isErr)
+    return err(handleError(result.error));
+  log.info("Application key generated.");
+  return ok(result.value);
+}
+export async function ensureProjectIsInitialized() {
+  if (fs.existsSync(projectPath(".env")))
+    return await isAppKeySet();
+  if (fs.existsSync(projectPath(".env.example")))
+    fs.copyFileSync(projectPath(".env.example"), projectPath(".env"));
+  else
+    console.error("no .env.example file found");
+  return await isAppKeySet();
+}
+export async function installIfVersionMismatch() {}
+export async function frameworkVersion() {
+  return (await readPackageJson(frameworkPath("package.json"))).version;
+}
+export async function isAppKeySet() {
+  const appKey = (await readTextFile(".env", projectPath())).data.split(`
+`).find((line) => line.startsWith("APP_KEY="));
+  return !!(appKey && appKey.length > 16);
+}
+export function determineResetPreset(preset) {
+  if (preset === void 0 && ui.reset)
+    preset = ui.reset;
+  if (preset === null)
+    return [];
+  const resetImport = {
+    tailwind: 'import { tailwindPreflight as reset } from "@cwcss/crosswind"',
+    preflight: 'import { tailwindPreflight as reset } from "@cwcss/crosswind"',
+    forms: 'import { tailwindFormsPreflight as reset } from "@cwcss/crosswind"'
+  }[preset ?? "tailwind"];
+  return resetImport ? [resetImport] : [];
+}
+export function isManifest(obj) {
+  return obj && typeof obj === "object" && isOptionalString(obj.name) && isOptionalString(obj.version) && isOptionalString(obj.description);
+}
+export function isOptionalString(value) {
+  const type = typeof value;
+  return value === null || type === "undefined" || type === "string";
+}
+export async function setEnvValue(key, value) {
+  const file = await readTextFile(projectPath(".env")), escapedKey = key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"), keyPattern = new RegExp(`^${escapedKey}=.*$`, "m"), nextValue = `${key}=${value}`, data = keyPattern.test(file.data) ? file.data.replace(keyPattern, nextValue) : `${file.data}${file.data.endsWith(`
+`) ? "" : `
+`}${nextValue}
+`;
+  await writeTextFile({
+    path: projectPath(".env"),
+    data
+  });
+}
+export async function runNpmScript(script, options) {
+  const { data: manifest } = await readJsonFile("package.json", frameworkPath());
+  if (isManifest(manifest) && hasScript(manifest, script))
+    return await runCommand(`bun run ${script}`, options);
+  return err(handleError(`The ${script} script does not exist in the package.json file.`));
+}
+export function hasScript(manifest, script) {
+  const scripts = manifest.scripts;
+  if (scripts && typeof scripts === "object")
+    return Boolean(scripts[script]);
+  return !1;
+}
+export function parseYaml(content) {
+  return Bun.YAML.parse(content);
+}
+export function determineDebugLevel(options) {
+  if (options?.verbose === !0)
+    return !0;
+  return app.debug === !0;
+}
+export function isIpv6(address) {
+  return address.family === "IPv6" || address.family === 6;
+}
+export function dumpYaml(content) {
+  const yaml = Bun.YAML;
+  if (typeof yaml.stringify === "function")
+    return yaml.stringify(content);
+  return JSON.stringify(content, null, 2);
+}
+export function loadYaml(content) {
+  return Bun.YAML.parse(content);
+}

package/dist/index.d.ts

@@ -0,0 +1,24 @@
+export * from './clean';
+export * from './config';
+export * from './equal';
+export * from './errors';
+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/index.js

@@ -0,0 +1,23 @@
+export * from "./clean";
+export * from "./config";
+export * from "./equal";
+export * from "./errors";
+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";
+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/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/macroable.js

@@ -0,0 +1,121 @@
+export class Macroable {
+  static macros = new Map;
+  static macro(name, fn, replace = !1) {
+    if (this.macros.has(name) && !replace)
+      throw Error(`Macro "${name}" is already registered`);
+    this.macros.set(name, fn);
+    Object.defineProperty(this.prototype, name, {
+      value: fn,
+      writable: !0,
+      configurable: !0,
+      enumerable: !1
+    });
+  }
+  static mixin(obj, replace = !0) {
+    const methods = Object.getOwnPropertyNames(obj);
+    for (const method of methods) {
+      if (method === "constructor")
+        continue;
+      if (this.macros.has(method) && !replace)
+        continue;
+      const descriptor = Object.getOwnPropertyDescriptor(obj, method);
+      if (descriptor && typeof descriptor.value === "function")
+        this.macro(method, descriptor.value, replace);
+    }
+  }
+  static hasMacro(name) {
+    return this.macros.has(name);
+  }
+  static flushMacros() {
+    for (const name of this.macros.keys())
+      delete this.prototype[name];
+    this.macros.clear();
+  }
+  static getMacros() {
+    return Array.from(this.macros.keys());
+  }
+  callMacro(name, ...args) {
+    const macro = this.constructor.macros.get(name);
+    if (!macro)
+      throw Error(`Macro "${name}" is not registered`);
+    return macro.apply(this, args);
+  }
+}
+export function createMacroable(BaseClass = class {
+}) {
+  return class extends BaseClass {
+    static macros = new Map;
+    static macro(name, fn, replace = !1) {
+      if (this.macros.has(name) && !replace)
+        throw Error(`Macro "${name}" is already registered`);
+      this.macros.set(name, fn);
+      Object.defineProperty(this.prototype, name, {
+        value: fn,
+        writable: !0,
+        configurable: !0,
+        enumerable: !1
+      });
+    }
+    static mixin(obj, replace = !0) {
+      const methods = Object.getOwnPropertyNames(obj);
+      for (const method of methods) {
+        if (method === "constructor")
+          continue;
+        if (this.macros.has(method) && !replace)
+          continue;
+        const descriptor = Object.getOwnPropertyDescriptor(obj, method);
+        if (descriptor && typeof descriptor.value === "function")
+          this.macro(method, descriptor.value, replace);
+      }
+    }
+    static hasMacro(name) {
+      return this.macros.has(name);
+    }
+    static flushMacros() {
+      for (const name of this.macros.keys())
+        delete this.prototype[name];
+      this.macros.clear();
+    }
+    static getMacros() {
+      return Array.from(this.macros.keys());
+    }
+  };
+}
+export function macroable(target) {
+  const macros = new Map;
+  target.macro = function(name, fn, replace = !1) {
+    if (macros.has(name) && !replace)
+      throw Error(`Macro "${name}" is already registered`);
+    macros.set(name, fn);
+    Object.defineProperty(target.prototype, name, {
+      value: fn,
+      writable: !0,
+      configurable: !0,
+      enumerable: !1
+    });
+  };
+  target.mixin = function(obj, replace = !0) {
+    const methods = Object.getOwnPropertyNames(obj);
+    for (const method of methods) {
+      if (method === "constructor")
+        continue;
+      if (macros.has(method) && !replace)
+        continue;
+      const descriptor = Object.getOwnPropertyDescriptor(obj, method);
+      if (descriptor && typeof descriptor.value === "function")
+        target.macro(method, descriptor.value, replace);
+    }
+  };
+  target.hasMacro = function(name) {
+    return macros.has(name);
+  };
+  target.flushMacros = function() {
+    for (const name of macros.keys())
+      delete target.prototype[name];
+    macros.clear();
+  };
+  target.getMacros = function() {
+    return Array.from(macros.keys());
+  };
+  return target;
+}

package/dist/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 };