@socketsecurity/lib 5.28.0 → 6.0.0

package/dist/spinner/format.d.ts

@@ -0,0 +1,64 @@
+/**
+ * @file Stateless helpers shared by `spinner/*` modules — the `ciSpinner`
+ *   constant for non-interactive output, the `COLOR_INHERIT` sentinel for
+ *   shimmer color references, plus pure formatters (`desc`, `formatProgress`,
+ *   `normalizeText`, `renderProgressBar`) used by both the factory and the
+ *   `withSpinner*` wrappers.
+ */
+import type { ProgressInfo, SpinnerStyle } from './types';
+/**
+ * Sentinel value indicating the shimmer should track the spinner's current
+ * color rather than holding its own palette reference.
+ */
+export declare const COLOR_INHERIT = "inherit";
+/**
+ * Minimal spinner style for CI environments. Uses empty frame and max interval
+ * to effectively disable animation in CI.
+ */
+export declare const ciSpinner: SpinnerStyle;
+/**
+ * Create a property descriptor for defining non-enumerable properties. Used for
+ * adding aliased methods to the Spinner prototype.
+ *
+ * @param value - Value for the property.
+ *
+ * @returns Property descriptor object
+ */
+export declare function desc(value: unknown): {
+    __proto__: null;
+    configurable: boolean;
+    value: unknown;
+    writable: boolean;
+};
+/**
+ * Format progress information as a visual progress bar with percentage and
+ * count.
+ *
+ * @example
+ *   '███████░░░░░░░░░░░░░ 35% (7/20 files)'
+ *
+ * @param progress - Progress tracking information.
+ *
+ * @returns Formatted string with colored progress bar, percentage, and count
+ */
+export declare function formatProgress(progress: ProgressInfo): string;
+/**
+ * Normalize text input by trimming leading whitespace. Non-string values are
+ * converted to empty string.
+ *
+ * @param value - Text to normalize.
+ *
+ * @returns Normalized string with leading whitespace removed
+ */
+export declare function normalizeText(value: unknown): string;
+/**
+ * Render a progress bar using block characters (█ for filled, ░ for empty).
+ *
+ * @default width=20
+ *
+ * @param percentage - Progress percentage (0-100)
+ * @param width - Total width of progress bar in characters.
+ *
+ * @returns Colored progress bar string
+ */
+export declare function renderProgressBar(percentage: number, width?: number): string;

package/dist/spinner/format.js

@@ -0,0 +1,83 @@
+"use strict";
+/* Socket Lib - Built with esbuild */
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc2) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc2 = __getOwnPropDesc(from, key)) || desc2.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var format_exports = {};
+__export(format_exports, {
+  COLOR_INHERIT: () => COLOR_INHERIT,
+  ciSpinner: () => ciSpinner,
+  desc: () => desc,
+  formatProgress: () => formatProgress,
+  normalizeText: () => normalizeText,
+  renderProgressBar: () => renderProgressBar
+});
+module.exports = __toCommonJS(format_exports);
+var import_yoctocolors_cjs = __toESM(require("../external/yoctocolors-cjs"));
+var import_math = require("../primordials/math");
+const COLOR_INHERIT = "inherit";
+const ciSpinner = {
+  frames: [""],
+  interval: 2147483647
+};
+function desc(value) {
+  return {
+    __proto__: null,
+    configurable: true,
+    value,
+    writable: true
+  };
+}
+function formatProgress(progress) {
+  const { current, total, unit } = progress;
+  const percentage = total === 0 ? 0 : (0, import_math.MathRound)(current / total * 100);
+  const bar = renderProgressBar(percentage);
+  const count = unit ? `${current}/${total} ${unit}` : `${current}/${total}`;
+  return `${bar} ${percentage}% (${count})`;
+}
+function normalizeText(value) {
+  return typeof value === "string" ? value.trimStart() : "";
+}
+function renderProgressBar(percentage, width = 20) {
+  const filled = (0, import_math.MathMax)(
+    0,
+    Math.min(width, Math.round(percentage / 100 * width))
+  );
+  const empty = (0, import_math.MathMax)(0, width - filled);
+  const bar = "\u2588".repeat(filled) + "\u2591".repeat(empty);
+  return import_yoctocolors_cjs.default.cyan(bar);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  COLOR_INHERIT,
+  ciSpinner,
+  desc,
+  formatProgress,
+  normalizeText,
+  renderProgressBar
+});

package/dist/spinner/registry.d.ts

@@ -0,0 +1,49 @@
+/**
+ * @file Spinner-style registry — exposes the union of the standard
+ *   `cli-spinners` collection and Socket's custom `socket` pulse animation,
+ *   plus a lazy default-spinner singleton. The registry itself is built once
+ *   and memoized; `getDefaultSpinner()` defers `Spinner()` construction until
+ *   first call so module initialization stays cheap.
+ */
+import type { SpinnerInstance, SpinnerStyle } from './types';
+/**
+ * Get available CLI spinner styles or a specific style by name. Extends the
+ * standard cli-spinners collection with Socket custom spinners.
+ *
+ * Custom spinners: - `socket` (default): Socket pulse animation with sparkles
+ * and lightning.
+ *
+ * @example
+ *   ;```ts
+ *   // Get all available spinner styles
+ *   const allSpinners = getCliSpinners()
+ *
+ *   // Get specific style
+ *   const socketStyle = getCliSpinners('socket')
+ *   const dotsStyle = getCliSpinners('dots')
+ *   ```
+ *
+ * @param styleName - Optional name of specific spinner style to retrieve.
+ *
+ * @returns Specific spinner style if name provided, all styles if omitted,
+ *   `undefined` if style not found.
+ *
+ * @see https://github.com/sindresorhus/cli-spinners/blob/main/spinners.json
+ */
+export declare function getCliSpinners(styleName?: string | undefined): SpinnerStyle | Record<string, SpinnerStyle> | undefined;
+/**
+ * Get the default spinner instance. Lazily creates the spinner to avoid
+ * circular dependencies during module initialization. Reuses the same instance
+ * across calls.
+ *
+ * @example
+ *   ;```ts
+ *   import { getDefaultSpinner } from '@socketsecurity/lib/spinner/registry'
+ *
+ *   const spinner = getDefaultSpinner()
+ *   spinner.start('Loading…')
+ *   ```
+ *
+ * @returns Shared default spinner instance
+ */
+export declare function getDefaultSpinner(): SpinnerInstance;

package/dist/spinner/registry.js

@@ -0,0 +1,70 @@
+"use strict";
+/* Socket Lib - Built with esbuild */
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var registry_exports = {};
+__export(registry_exports, {
+  getCliSpinners: () => getCliSpinners,
+  getDefaultSpinner: () => getDefaultSpinner
+});
+module.exports = __toCommonJS(registry_exports);
+var import_pulse_frames = require("../effects/pulse-frames");
+var import_yocto_spinner = __toESM(require("../external/@socketregistry/yocto-spinner"));
+var import_predicates = require("../objects/predicates");
+var import_spinner = require("./spinner");
+let _cliSpinners;
+let _spinner;
+// @__NO_SIDE_EFFECTS__
+function getCliSpinners(styleName) {
+  if (_cliSpinners === void 0) {
+    const YoctoCtor = import_yocto_spinner.default;
+    const tempInstance = YoctoCtor({});
+    const YoctoSpinnerClass = tempInstance.constructor;
+    _cliSpinners = {
+      __proto__: null,
+      ...YoctoSpinnerClass.spinners,
+      socket: (0, import_pulse_frames.generateSocketSpinnerFrames)()
+    };
+  }
+  if (typeof styleName === "string" && _cliSpinners) {
+    return (0, import_predicates.hasOwn)(_cliSpinners, styleName) ? _cliSpinners[styleName] : void 0;
+  }
+  return _cliSpinners;
+}
+function getDefaultSpinner() {
+  if (_spinner === void 0) {
+    _spinner = (0, import_spinner.Spinner)();
+  }
+  return _spinner;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  getCliSpinners,
+  getDefaultSpinner
+});

package/dist/spinner/spinner.d.ts

@@ -0,0 +1,40 @@
+/**
+ * @file Spinner factory — builds the lazy-init `Spinner` class that wraps
+ *   `yocto-spinner` with Socket-specific behaviors (custom RGB color pipeline,
+ *   shimmer, progress bar, indented step messages, status methods that don't
+ *   auto-stop, *AndStop variants that auto-clear). The class graph is
+ *   constructed inside the factory body so the `super()` call binds against the
+ *   live `YoctoSpinner` constructor; splitting it further would require
+ *   exposing the parent class as a module-level dependency, which breaks the
+ *   lazy-init guarantee.
+ */
+import type { SpinnerInstance, SpinnerOptions } from './types';
+/**
+ * Create a spinner instance for displaying loading indicators. Provides an
+ * animated CLI spinner with status messages, progress tracking, and shimmer
+ * effects.
+ *
+ * AUTO-CLEAR BEHAVIOR:
+ *
+ * - All *AndStop() methods AUTO-CLEAR the spinner line via yocto-spinner.stop()
+ *   Examples: `doneAndStop()`, `successAndStop()`, `failAndStop()`, etc.
+ * - Methods WITHOUT "AndStop" do NOT clear (spinner keeps spinning) Examples:
+ *   `done()`, `success()`, `fail()`, etc.
+ *
+ * STREAM USAGE:
+ *
+ * - Spinner animation: stderr (yocto-spinner default)
+ * - Status methods (done, success, fail, info, warn, step, substep): stderr
+ * - Data methods (`log()`): stdout
+ *
+ * COMPARISON WITH LOGGER:
+ *
+ * - `logger.done()` does NOT auto-clear (requires manual `logger.clearLine()`)
+ * - `spinner.doneAndStop()` DOES auto-clear (built into yocto-spinner.stop())
+ * - Pattern: `logger.clearLine().done()` vs `spinner.doneAndStop()`
+ *
+ * @param options - Configuration options for the spinner.
+ *
+ * @returns New spinner instance
+ */
+export declare function Spinner(options?: SpinnerOptions | undefined): SpinnerInstance;