@socketsecurity/lib 6.0.5 → 6.0.7

package/dist/spinner/spinner-shimmer-methods.js

@@ -0,0 +1,143 @@
+"use strict";
+/* Socket Lib - Built with rolldown */
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+const require_spinner_format = require('./format.js');
+
+//#region src/spinner/spinner-shimmer-methods.ts
+/**
+* Well-known symbol the spinner class exposes to read its current shimmer
+* state.
+*/
+const getShimmerSymbol = Symbol.for("socket.spinner.getShimmer");
+/**
+* Well-known symbol the spinner class exposes to replace its current shimmer
+* state.
+*/
+const setShimmerSymbol = Symbol.for("socket.spinner.setShimmer");
+/**
+* Well-known symbol the spinner class exposes to read the saved shimmer config
+* that `enableShimmer()` restores from.
+*/
+const getSavedShimmerSymbol = Symbol.for("socket.spinner.getSavedShimmer");
+/**
+* Well-known symbol the spinner class exposes to replace the saved shimmer
+* config.
+*/
+const setSavedShimmerSymbol = Symbol.for("socket.spinner.setSavedShimmer");
+/**
+* Well-known symbol the spinner class exposes for its `#updateSpinnerText`
+* helper so the shimmer methods can trigger a re-render after a state change.
+*/
+const updateTextSymbol = Symbol.for("socket.spinner.updateText");
+/**
+* Install the shimmer-configuration methods + `shimmerState` getter onto the
+* spinner prototype. The methods reach the spinner's private shimmer state
+* through the well-known symbols the class exposes.
+*
+* @param proto - The spinner class prototype to augment.
+*/
+function installShimmerMethods(proto) {
+	const target = proto;
+	function shimmerState() {
+		const shimmer = this[getShimmerSymbol]();
+		if (!shimmer) return;
+		return {
+			__proto__: null,
+			color: shimmer.color,
+			direction: shimmer.direction,
+			speed: shimmer.speed,
+			frame: shimmer.frame
+		};
+	}
+	function disableShimmer() {
+		this[setShimmerSymbol](void 0);
+		this[updateTextSymbol]();
+		return this;
+	}
+	function enableShimmer() {
+		const saved = this[getSavedShimmerSymbol]();
+		if (saved) this[setShimmerSymbol]({
+			...saved,
+			frame: 0
+		});
+		else {
+			const next = {
+				__proto__: null,
+				color: require_spinner_format.COLOR_INHERIT,
+				direction: "ltr",
+				speed: 1 / 3,
+				frame: 0
+			};
+			this[setShimmerSymbol](next);
+			this[setSavedShimmerSymbol](next);
+		}
+		this[updateTextSymbol]();
+		return this;
+	}
+	function setShimmer(config) {
+		const next = {
+			__proto__: null,
+			color: config.color ?? "inherit",
+			direction: config.dir ?? "ltr",
+			speed: config.speed ?? 1 / 3,
+			frame: 0
+		};
+		this[setShimmerSymbol](next);
+		this[setSavedShimmerSymbol](next);
+		this[updateTextSymbol]();
+		return this;
+	}
+	function updateShimmer(config) {
+		/* c8 ignore start - each partial-config field branch fires only when caller updates that field; shimmer-state cascade covers three init paths */
+		const partialConfig = {
+			__proto__: null,
+			...config
+		};
+		const update = { __proto__: null };
+		if (partialConfig.color !== void 0) update.color = partialConfig.color;
+		if (partialConfig.dir !== void 0) update.direction = partialConfig.dir;
+		if (partialConfig.speed !== void 0) update.speed = partialConfig.speed;
+		const shimmer = this[getShimmerSymbol]();
+		const saved = this[getSavedShimmerSymbol]();
+		let next;
+		if (shimmer) next = {
+			...shimmer,
+			...update
+		};
+		else if (saved) next = {
+			...saved,
+			...update,
+			frame: 0
+		};
+		else next = {
+			__proto__: null,
+			color: require_spinner_format.COLOR_INHERIT,
+			direction: "ltr",
+			speed: 1 / 3,
+			frame: 0,
+			...update
+		};
+		this[setShimmerSymbol](next);
+		this[setSavedShimmerSymbol](next);
+		this[updateTextSymbol]();
+		return this;
+		/* c8 ignore stop */
+	}
+	Object.defineProperty(target, "shimmerState", {
+		configurable: true,
+		enumerable: false,
+		get: shimmerState
+	});
+	target["disableShimmer"] = disableShimmer;
+	target["enableShimmer"] = enableShimmer;
+	target["setShimmer"] = setShimmer;
+	target["updateShimmer"] = updateShimmer;
+}
+
+//#endregion
+exports.getSavedShimmerSymbol = getSavedShimmerSymbol;
+exports.getShimmerSymbol = getShimmerSymbol;
+exports.installShimmerMethods = installShimmerMethods;
+exports.setSavedShimmerSymbol = setSavedShimmerSymbol;
+exports.setShimmerSymbol = setShimmerSymbol;
+exports.updateTextSymbol = updateTextSymbol;

package/dist/spinner/spinner-status-methods.d.ts

@@ -0,0 +1,40 @@
+/**
+ * @file Status-presentation methods for the Socket `Spinner` class, split out
+ *   of `create-spinner-class.ts` to keep that module under the file-size cap.
+ *   Each method is a thin delegation to one of the two internal helpers the
+ *   class exposes via well-known symbols (`applyStatusSymbol`,
+ *   `showStatusSymbol`); `installStatusMethods()` defines them on the spinner
+ *   prototype after the class is built so they share the same private state.
+ */
+import type { SpinnerLogger } from './create-spinner-class';
+import type { SpinnerInstance, SymbolType } from './types';
+/**
+ * Well-known symbol the spinner class uses to expose its `#apply` helper so the
+ * status methods in this module can drive a yocto-spinner method + logger
+ * update without reaching into a private field across the file boundary.
+ */
+export declare const applyStatusSymbol: unique symbol;
+/**
+ * Well-known symbol the spinner class uses to expose its
+ * `#showStatusAndKeepSpinning` helper so the status methods here can emit a
+ * symbol-prefixed status line without stopping the spinner.
+ */
+export declare const showStatusSymbol: unique symbol;
+/**
+ * Runtime shape of the spinner instance the status methods operate on. Only the
+ * two symbol-keyed helpers are needed; everything else is reached through the
+ * module-scope `logger`.
+ */
+export type StatusHost = SpinnerInstance & {
+    [applyStatusSymbol]: (methodName: string, args: unknown[]) => SpinnerInstance;
+    [showStatusSymbol]: (symbolType: SymbolType, args: unknown[]) => SpinnerInstance;
+};
+/**
+ * Install the status-presentation methods onto the spinner prototype. The
+ * methods close over `logger` for the stdout/stderr writes and reach the
+ * spinner's private helpers through the two well-known symbols.
+ *
+ * @param proto - The spinner class prototype to augment.
+ * @param logger - Default logger used for status output.
+ */
+export declare function installStatusMethods(proto: object, logger: SpinnerLogger): void;

package/dist/spinner/spinner-status-methods.js

@@ -0,0 +1,133 @@
+"use strict";
+/* Socket Lib - Built with rolldown */
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+const require_logger_symbols = require('../logger/symbols.js');
+const require_spinner_format = require('./format.js');
+const require_debug_namespace = require('../debug/namespace.js');
+
+//#region src/spinner/spinner-status-methods.ts
+/**
+* @file Status-presentation methods for the Socket `Spinner` class, split out
+*   of `create-spinner-class.ts` to keep that module under the file-size cap.
+*   Each method is a thin delegation to one of the two internal helpers the
+*   class exposes via well-known symbols (`applyStatusSymbol`,
+*   `showStatusSymbol`); `installStatusMethods()` defines them on the spinner
+*   prototype after the class is built so they share the same private state.
+*/
+/**
+* Well-known symbol the spinner class uses to expose its `#apply` helper so the
+* status methods in this module can drive a yocto-spinner method + logger
+* update without reaching into a private field across the file boundary.
+*/
+const applyStatusSymbol = Symbol.for("socket.spinner.applyStatus");
+/**
+* Well-known symbol the spinner class uses to expose its
+* `#showStatusAndKeepSpinning` helper so the status methods here can emit a
+* symbol-prefixed status line without stopping the spinner.
+*/
+const showStatusSymbol = Symbol.for("socket.spinner.showStatus");
+/**
+* Install the status-presentation methods onto the spinner prototype. The
+* methods close over `logger` for the stdout/stderr writes and reach the
+* spinner's private helpers through the two well-known symbols.
+*
+* @param proto - The spinner class prototype to augment.
+* @param logger - Default logger used for status output.
+*/
+function installStatusMethods(proto, logger) {
+	const target = proto;
+	function debug(text, ...extras) {
+		if (require_debug_namespace.isDebug()) return this[showStatusSymbol]("info", [text, ...extras]);
+		return this;
+	}
+	function debugAndStop(text, ...extras) {
+		if (require_debug_namespace.isDebug()) return this[applyStatusSymbol]("info", [text, ...extras]);
+		return this;
+	}
+	function done(text, ...extras) {
+		return this[showStatusSymbol]("success", [text, ...extras]);
+	}
+	function doneAndStop(text, ...extras) {
+		return this[applyStatusSymbol]("success", [text, ...extras]);
+	}
+	function fail(text, ...extras) {
+		return this[showStatusSymbol]("fail", [text, ...extras]);
+	}
+	function failAndStop(text, ...extras) {
+		return this[applyStatusSymbol]("error", [text, ...extras]);
+	}
+	function info(text, ...extras) {
+		return this[showStatusSymbol]("info", [text, ...extras]);
+	}
+	function infoAndStop(text, ...extras) {
+		return this[applyStatusSymbol]("info", [text, ...extras]);
+	}
+	function log(...args) {
+		logger.log(...args);
+		return this;
+	}
+	function logAndStop(text, ...extras) {
+		return this[applyStatusSymbol]("stop", [text, ...extras]);
+	}
+	function skip(text, ...extras) {
+		return this[showStatusSymbol]("skip", [text, ...extras]);
+	}
+	function skipAndStop(text, ...extras) {
+		this[applyStatusSymbol]("stop", []);
+		const normalized = require_spinner_format.normalizeText(text);
+		/* c8 ignore start - empty-text no-op fires when text is undefined or whitespace-only */
+		if (normalized) logger.error(`${require_logger_symbols.LOG_SYMBOLS["skip"]} ${normalized}`, ...extras);
+		return this;
+		/* c8 ignore stop */
+	}
+	function step(text, ...extras) {
+		/* c8 ignore start - text-omitted no-op arm fires when caller invokes step() bare */
+		if (typeof text === "string") {
+			logger.error("");
+			logger.error(text, ...extras);
+		}
+		return this;
+		/* c8 ignore stop */
+	}
+	function substep(text, ...extras) {
+		/* c8 ignore start - text-omitted no-op arm fires when caller invokes substep() bare */
+		if (typeof text === "string") logger.error(`  ${text}`, ...extras);
+		return this;
+		/* c8 ignore stop */
+	}
+	function success(text, ...extras) {
+		return this[showStatusSymbol]("success", [text, ...extras]);
+	}
+	function successAndStop(text, ...extras) {
+		return this[applyStatusSymbol]("success", [text, ...extras]);
+	}
+	function warn(text, ...extras) {
+		return this[showStatusSymbol]("warn", [text, ...extras]);
+	}
+	function warnAndStop(text, ...extras) {
+		return this[applyStatusSymbol]("warning", [text, ...extras]);
+	}
+	target["debug"] = debug;
+	target["debugAndStop"] = debugAndStop;
+	target["done"] = done;
+	target["doneAndStop"] = doneAndStop;
+	target["fail"] = fail;
+	target["failAndStop"] = failAndStop;
+	target["info"] = info;
+	target["infoAndStop"] = infoAndStop;
+	target["log"] = log;
+	target["logAndStop"] = logAndStop;
+	target["skip"] = skip;
+	target["skipAndStop"] = skipAndStop;
+	target["step"] = step;
+	target["substep"] = substep;
+	target["success"] = success;
+	target["successAndStop"] = successAndStop;
+	target["warn"] = warn;
+	target["warnAndStop"] = warnAndStop;
+}
+
+//#endregion
+exports.applyStatusSymbol = applyStatusSymbol;
+exports.installStatusMethods = installStatusMethods;
+exports.showStatusSymbol = showStatusSymbol;

package/dist/spinner/spinner.d.ts

@@ -1,12 +1,11 @@
 /**
- * @file Spinner factory — builds the lazy-init `Spinner` class that wraps
+ * @file Spinner factory — lazily builds the Socket `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.
+ *   constructed by `createSpinnerClass()` so the `super()` call binds against
+ *   the live `YoctoSpinner` constructor resolved here; building it lazily keeps
+ *   the module free of side effects at import time.
  */
 import type { SpinnerInstance, SpinnerOptions } from './types';
 /**