shelving 1.234.0 → 1.234.1

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "shelving",
-	"version": "1.234.0",
+	"version": "1.234.1",
 	"author": "Dave Houlbrooke <dave@shax.com>",
 	"repository": {
 		"type": "git",

package/util/ansi.d.ts

@@ -14,12 +14,24 @@ export declare const ANSI_UNDERLINE: "\u001B[4m";
 export declare const ANSI_STRIKE: "\u001B[9m";
 export declare const ANSI_INVERSE: "\u001B[7m";
 export declare const ANSI_RESET = "\u001B[0m";
-/** Wrap a string in `ANSI_RED` or the ANSI color/style codes (at the start), and `ANSI_RESET` at the end. */
+/**
+ * Wrap a string in the ANSI color/style codes (at the start), and `ANSI_RESET` at the end.
+ *
+ * - The `NO_COLOR` environment variable is read live on every call, so runtimes that populate `process.env` late (e.g. Cloudflare Workers, where `[vars]` bindings are only reliably available within the request scope) are honoured rather than baking in whatever `NO_COLOR` was at module-load time.
+ */
 export declare function ansiWrap(input: string, ...wrappers: ImmutableArray<string>): string;
-export declare const ANSI_WAITING: string;
-export declare const ANSI_SUCCESS: string;
-export declare const ANSI_FAILURE: string;
-export declare const ANSI_UP: string;
-export declare const ANSI_DOWN: string;
-export declare const ANSI_RIGHT: string;
-export declare const ANSI_LEFT: string;
+/**
+ * A lazily-coloured icon that re-evaluates its ANSI colouring against the live `NO_COLOR` environment variable every time it is converted to a string.
+ *
+ * - Used directly inside template literals (`${ANSI_SUCCESS}`), where JavaScript invokes `toString()` automatically, so the icon is coloured at use-time, not at module-load time.
+ */
+export type AnsiIcon = {
+    toString(): string;
+};
+export declare const ANSI_WAITING: AnsiIcon;
+export declare const ANSI_SUCCESS: AnsiIcon;
+export declare const ANSI_FAILURE: AnsiIcon;
+export declare const ANSI_UP: AnsiIcon;
+export declare const ANSI_DOWN: AnsiIcon;
+export declare const ANSI_RIGHT: AnsiIcon;
+export declare const ANSI_LEFT: AnsiIcon;

package/util/ansi.js

@@ -1,5 +1,5 @@
 import { DOWN, FAILURE, LEFT, RIGHT, SUCCESS, UP, WAITING } from "./constants.js";
-import { NO_COLOR } from "./env.js";
+import { getEnvBoolean } from "./env.js";
 // Colors.
 export const ANSI_DEFAULT = "\x1b[39m";
 export const ANSI_BLACK = "\x1b[30m";
@@ -18,17 +18,29 @@ export const ANSI_STRIKE = "\x1b[9m";
 export const ANSI_INVERSE = "\x1b[7m";
 // Reset.
 export const ANSI_RESET = "\x1b[0m";
-/** Wrap a string in `ANSI_RED` or the ANSI color/style codes (at the start), and `ANSI_RESET` at the end. */
+/**
+ * Wrap a string in the ANSI color/style codes (at the start), and `ANSI_RESET` at the end.
+ *
+ * - The `NO_COLOR` environment variable is read live on every call, so runtimes that populate `process.env` late (e.g. Cloudflare Workers, where `[vars]` bindings are only reliably available within the request scope) are honoured rather than baking in whatever `NO_COLOR` was at module-load time.
+ */
 export function ansiWrap(input, ...wrappers) {
-    if (NO_COLOR)
+    if (getEnvBoolean("NO_COLOR"))
         return input;
     return `${wrappers.join("")}${input}${ANSI_RESET}`;
 }
+/** Create a lazily-coloured {@link AnsiIcon} that wraps `icon` in `wrappers` on each `toString()`. */
+function _createAnsiIcon(icon, ...wrappers) {
+    return {
+        toString() {
+            return ansiWrap(icon, ...wrappers);
+        },
+    };
+}
 // Coloured icons.
-export const ANSI_WAITING = ansiWrap(WAITING, ANSI_BLUE);
-export const ANSI_SUCCESS = ansiWrap(SUCCESS, ANSI_GREEN);
-export const ANSI_FAILURE = ansiWrap(FAILURE, ANSI_RED);
-export const ANSI_UP = ansiWrap(UP, ANSI_BLUE);
-export const ANSI_DOWN = ansiWrap(DOWN, ANSI_BLUE);
-export const ANSI_RIGHT = ansiWrap(RIGHT, ANSI_BLUE);
-export const ANSI_LEFT = ansiWrap(LEFT, ANSI_BLUE);
+export const ANSI_WAITING = _createAnsiIcon(WAITING, ANSI_BLUE);
+export const ANSI_SUCCESS = _createAnsiIcon(SUCCESS, ANSI_GREEN);
+export const ANSI_FAILURE = _createAnsiIcon(FAILURE, ANSI_RED);
+export const ANSI_UP = _createAnsiIcon(UP, ANSI_BLUE);
+export const ANSI_DOWN = _createAnsiIcon(DOWN, ANSI_BLUE);
+export const ANSI_RIGHT = _createAnsiIcon(RIGHT, ANSI_BLUE);
+export const ANSI_LEFT = _createAnsiIcon(LEFT, ANSI_BLUE);

package/util/env.d.ts

@@ -19,5 +19,3 @@ export declare function getEnvBoolean(name: string): boolean | undefined;
  * @throws `RequiredError` if the env variable is any other value.
  */
 export declare function requireEnvBoolean(name: string, caller?: AnyCaller): boolean;
-/** The `NO_COLOR` environment variable is commonly used to indicate that ANSI output shouldn't have color. */
-export declare const NO_COLOR: boolean;

package/util/env.js

@@ -40,5 +40,3 @@ export function requireEnvBoolean(name, caller = requireEnvBoolean) {
         throw new RequiredError(`Environment variable "${name}" must be boolean`, { caller });
     return env;
 }
-/** The `NO_COLOR` environment variable is commonly used to indicate that ANSI output shouldn't have color. */
-export const NO_COLOR = getEnvBoolean("NO_COLOR") ?? false;