lifecycleion 0.0.7 → 0.0.8

package/README.md

@@ -1,4 +1,4 @@
-# Lifecycleion v0.0.7
+# Lifecycleion v0.0.8
 
 [![npm version](https://badge.fury.io/js/lifecycleion.svg)](https://badge.fury.io/js/lifecycleion)
 
@@ -89,6 +89,7 @@ Each library has comprehensive documentation in the [docs](./docs) folder. Click
 | [constants](./docs/constants.md)                                   | `lifecycleion/constants`                  | Common string constants including whitespace helpers and Python-style character sets                                                     |
 | [curly-brackets](./docs/curly-brackets.md)                         | `lifecycleion/curly-brackets`             | String templating with `{{placeholders}}`, fallbacks, escaping, and compiled templates                                                   |
 | [deep-clone](./docs/deep-clone.md)                                 | `lifecycleion/deep-clone`                 | Deep clone utility with circular reference detection for objects, arrays, Maps, Sets, and more                                           |
+| [dev-mode](./docs/dev-mode.md)                                     | `lifecycleion/dev-mode`                   | Runtime-settable dev/production mode flag with auto-detection from CLI args or NODE_ENV                                                  |
 | [error-to-string](./docs/error-to-string.md)                       | `lifecycleion/error-to-string`            | Format errors into readable ASCII tables with support for nested info and sensitive field masking                                        |
 | [event-emitter](./docs/event-emitter.md)                           | `lifecycleion/event-emitter`              | Lightweight event emitter with protected and public variants, type safety, and memory management                                         |
 | [id-helpers](./docs/id-helpers.md)                                 | `lifecycleion/id-helpers`                 | Unified ID generation and validation for ObjectID, UUID v4, UUID v7, and ULID                                                            |

package/dist/lib/dev-mode.cjs

@@ -0,0 +1,77 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+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 __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/lib/dev-mode.ts
+var dev_mode_exports = {};
+__export(dev_mode_exports, {
+  getDevMode: () => getDevMode,
+  initDevMode: () => initDevMode,
+  overrideDevMode: () => overrideDevMode
+});
+module.exports = __toCommonJS(dev_mode_exports);
+var GLOBAL_KEY = "__lifecycleion_is_dev__";
+var INIT_PARAM_KEY = "__lifecycleion_init_param__";
+var g = globalThis;
+function detectValue(detect, isStrict) {
+  const argv = typeof process !== "undefined" ? process.argv ?? [] : [];
+  const env = typeof process !== "undefined" ? process.env?.NODE_ENV : void 0;
+  const cmdArg = argv.find((a) => a === "dev" || a === "prod");
+  if (isStrict && detect === "cmd" && cmdArg === void 0) {
+    throw new Error('initDevMode: expected "dev" or "prod" as a CLI argument');
+  }
+  const isFromCmd = cmdArg !== void 0 ? cmdArg === "dev" : false;
+  const isFromEnv = env === "development";
+  if (detect === "cmd") {
+    return isFromCmd;
+  }
+  if (detect === "node_env") {
+    return isFromEnv;
+  }
+  return cmdArg !== void 0 ? isFromCmd : isFromEnv;
+}
+function resolveInitParam(param) {
+  if (param === void 0) {
+    return detectValue("both");
+  }
+  if (typeof param === "boolean") {
+    return param;
+  }
+  return detectValue(param.detect, param.strict);
+}
+function getDevMode() {
+  return typeof g[GLOBAL_KEY] === "boolean" ? g[GLOBAL_KEY] : false;
+}
+function initDevMode(param) {
+  if (typeof g[GLOBAL_KEY] === "boolean") {
+    return;
+  }
+  g[INIT_PARAM_KEY] = param;
+  g[GLOBAL_KEY] = resolveInitParam(param);
+}
+function overrideDevMode(value) {
+  const savedParam = g[INIT_PARAM_KEY];
+  g[GLOBAL_KEY] = value === "redetect" ? resolveInitParam(savedParam) : value;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  getDevMode,
+  initDevMode,
+  overrideDevMode
+});
+//# sourceMappingURL=dev-mode.cjs.map

package/dist/lib/dev-mode.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/lib/dev-mode.ts"],"sourcesContent":["// Stored in globalThis so state survives module re-evaluation and works across\n// module boundaries.\nconst GLOBAL_KEY = '__lifecycleion_is_dev__';\nconst INIT_PARAM_KEY = '__lifecycleion_init_param__';\n\ntype DevModeSource = 'cmd' | 'node_env' | 'both';\ntype InitParam =\n  | boolean\n  | { detect: DevModeSource; strict?: boolean }\n  | undefined;\n\n// Cast once at module level — avoids repeating the assertion in every function.\nconst g = globalThis as typeof globalThis & Record<string, unknown>;\n\nfunction detectValue(detect: DevModeSource, isStrict?: boolean): boolean {\n  // Guard against environments where process or its properties may not exist\n  // (e.g. browser without polyfill, Deno without Node compat, edge runtimes).\n  // Vite statically replaces process.env.NODE_ENV at build time, so it is safe\n  // on the client. process.argv is an empty array shim in browsers — harmless.\n  const argv: string[] =\n    typeof process !== 'undefined' ? (process.argv ?? []) : [];\n  const env: string | undefined =\n    typeof process !== 'undefined' ? process.env?.NODE_ENV : undefined;\n\n  const cmdArg = argv.find((a) => a === 'dev' || a === 'prod');\n\n  if (isStrict && detect === 'cmd' && cmdArg === undefined) {\n    throw new Error('initDevMode: expected \"dev\" or \"prod\" as a CLI argument');\n  }\n\n  const isFromCmd = cmdArg !== undefined ? cmdArg === 'dev' : false;\n  const isFromEnv = env === 'development';\n\n  if (detect === 'cmd') {\n    return isFromCmd;\n  }\n\n  if (detect === 'node_env') {\n    return isFromEnv;\n  }\n\n  // 'both': cmd wins when explicitly present, otherwise fall back to NODE_ENV\n  return cmdArg !== undefined ? isFromCmd : isFromEnv;\n}\n\nfunction resolveInitParam(param: InitParam): boolean {\n  if (param === undefined) {\n    return detectValue('both');\n  }\n\n  if (typeof param === 'boolean') {\n    return param;\n  }\n\n  return detectValue(param.detect, param.strict);\n}\n\n/**\n * Returns the current dev mode value.\n *\n * Reads `globalThis.__lifecycleion_is_dev__`. Defaults to `false` if\n * `initDevMode()` has not been called yet.\n */\nexport function getDevMode(): boolean {\n  return typeof g[GLOBAL_KEY] === 'boolean' ? g[GLOBAL_KEY] : false;\n}\n\n/**\n * Sets the dev mode global for the current process.\n *\n * First-wins: if the global is already set (e.g. set by the HTML injection on\n * the client, or by a prior `initDevMode()` call), this is a no-op. Call once\n * at startup before serving any requests.\n *\n * @param param\n *   - `true` / `false` — explicit value\n *   - `{ detect: 'cmd' }` — read from `process.argv` (\"dev\" or \"prod\")\n *   - `{ detect: 'node_env' }` — read from `NODE_ENV`\n *   - `{ detect: 'both' }` — argv takes precedence, falls back to `NODE_ENV`\n *   - `{ detect: 'cmd', strict: true }` — argv required, throws if absent\n *   - omitted — same as `{ detect: 'both' }`\n */\nexport function initDevMode(\n  param?: boolean | { detect: DevModeSource; strict?: boolean },\n): void {\n  if (typeof g[GLOBAL_KEY] === 'boolean') {\n    return; // first-wins — already initialized, no-op\n  }\n\n  g[INIT_PARAM_KEY] = param; // save original param so 'redetect' can replay it\n  g[GLOBAL_KEY] = resolveInitParam(param);\n}\n\n/**\n * Bypasses first-wins semantics and forces the dev mode value.\n *\n * Intended for testing or tooling — not for production use.\n *\n * Pass `'redetect'` to re-run the same detection logic that\n * `initDevMode()` used originally.\n */\nexport function overrideDevMode(value: boolean | 'redetect'): void {\n  const savedParam = g[INIT_PARAM_KEY] as InitParam;\n  g[GLOBAL_KEY] = value === 'redetect' ? resolveInitParam(savedParam) : value;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAEA,IAAM,aAAa;AACnB,IAAM,iBAAiB;AASvB,IAAM,IAAI;AAEV,SAAS,YAAY,QAAuB,UAA6B;AAKvE,QAAM,OACJ,OAAO,YAAY,cAAe,QAAQ,QAAQ,CAAC,IAAK,CAAC;AAC3D,QAAM,MACJ,OAAO,YAAY,cAAc,QAAQ,KAAK,WAAW;AAE3D,QAAM,SAAS,KAAK,KAAK,CAAC,MAAM,MAAM,SAAS,MAAM,MAAM;AAE3D,MAAI,YAAY,WAAW,SAAS,WAAW,QAAW;AACxD,UAAM,IAAI,MAAM,yDAAyD;AAAA,EAC3E;AAEA,QAAM,YAAY,WAAW,SAAY,WAAW,QAAQ;AAC5D,QAAM,YAAY,QAAQ;AAE1B,MAAI,WAAW,OAAO;AACpB,WAAO;AAAA,EACT;AAEA,MAAI,WAAW,YAAY;AACzB,WAAO;AAAA,EACT;AAGA,SAAO,WAAW,SAAY,YAAY;AAC5C;AAEA,SAAS,iBAAiB,OAA2B;AACnD,MAAI,UAAU,QAAW;AACvB,WAAO,YAAY,MAAM;AAAA,EAC3B;AAEA,MAAI,OAAO,UAAU,WAAW;AAC9B,WAAO;AAAA,EACT;AAEA,SAAO,YAAY,MAAM,QAAQ,MAAM,MAAM;AAC/C;AAQO,SAAS,aAAsB;AACpC,SAAO,OAAO,EAAE,UAAU,MAAM,YAAY,EAAE,UAAU,IAAI;AAC9D;AAiBO,SAAS,YACd,OACM;AACN,MAAI,OAAO,EAAE,UAAU,MAAM,WAAW;AACtC;AAAA,EACF;AAEA,IAAE,cAAc,IAAI;AACpB,IAAE,UAAU,IAAI,iBAAiB,KAAK;AACxC;AAUO,SAAS,gBAAgB,OAAmC;AACjE,QAAM,aAAa,EAAE,cAAc;AACnC,IAAE,UAAU,IAAI,UAAU,aAAa,iBAAiB,UAAU,IAAI;AACxE;","names":[]}

package/dist/lib/dev-mode.d.cts

@@ -0,0 +1,38 @@
+type DevModeSource = 'cmd' | 'node_env' | 'both';
+/**
+ * Returns the current dev mode value.
+ *
+ * Reads `globalThis.__lifecycleion_is_dev__`. Defaults to `false` if
+ * `initDevMode()` has not been called yet.
+ */
+declare function getDevMode(): boolean;
+/**
+ * Sets the dev mode global for the current process.
+ *
+ * First-wins: if the global is already set (e.g. set by the HTML injection on
+ * the client, or by a prior `initDevMode()` call), this is a no-op. Call once
+ * at startup before serving any requests.
+ *
+ * @param param
+ *   - `true` / `false` — explicit value
+ *   - `{ detect: 'cmd' }` — read from `process.argv` ("dev" or "prod")
+ *   - `{ detect: 'node_env' }` — read from `NODE_ENV`
+ *   - `{ detect: 'both' }` — argv takes precedence, falls back to `NODE_ENV`
+ *   - `{ detect: 'cmd', strict: true }` — argv required, throws if absent
+ *   - omitted — same as `{ detect: 'both' }`
+ */
+declare function initDevMode(param?: boolean | {
+    detect: DevModeSource;
+    strict?: boolean;
+}): void;
+/**
+ * Bypasses first-wins semantics and forces the dev mode value.
+ *
+ * Intended for testing or tooling — not for production use.
+ *
+ * Pass `'redetect'` to re-run the same detection logic that
+ * `initDevMode()` used originally.
+ */
+declare function overrideDevMode(value: boolean | 'redetect'): void;
+
+export { getDevMode, initDevMode, overrideDevMode };

package/dist/lib/dev-mode.d.ts

@@ -0,0 +1,38 @@
+type DevModeSource = 'cmd' | 'node_env' | 'both';
+/**
+ * Returns the current dev mode value.
+ *
+ * Reads `globalThis.__lifecycleion_is_dev__`. Defaults to `false` if
+ * `initDevMode()` has not been called yet.
+ */
+declare function getDevMode(): boolean;
+/**
+ * Sets the dev mode global for the current process.
+ *
+ * First-wins: if the global is already set (e.g. set by the HTML injection on
+ * the client, or by a prior `initDevMode()` call), this is a no-op. Call once
+ * at startup before serving any requests.
+ *
+ * @param param
+ *   - `true` / `false` — explicit value
+ *   - `{ detect: 'cmd' }` — read from `process.argv` ("dev" or "prod")
+ *   - `{ detect: 'node_env' }` — read from `NODE_ENV`
+ *   - `{ detect: 'both' }` — argv takes precedence, falls back to `NODE_ENV`
+ *   - `{ detect: 'cmd', strict: true }` — argv required, throws if absent
+ *   - omitted — same as `{ detect: 'both' }`
+ */
+declare function initDevMode(param?: boolean | {
+    detect: DevModeSource;
+    strict?: boolean;
+}): void;
+/**
+ * Bypasses first-wins semantics and forces the dev mode value.
+ *
+ * Intended for testing or tooling — not for production use.
+ *
+ * Pass `'redetect'` to re-run the same detection logic that
+ * `initDevMode()` used originally.
+ */
+declare function overrideDevMode(value: boolean | 'redetect'): void;
+
+export { getDevMode, initDevMode, overrideDevMode };

package/dist/lib/dev-mode.js

@@ -0,0 +1,50 @@
+// src/lib/dev-mode.ts
+var GLOBAL_KEY = "__lifecycleion_is_dev__";
+var INIT_PARAM_KEY = "__lifecycleion_init_param__";
+var g = globalThis;
+function detectValue(detect, isStrict) {
+  const argv = typeof process !== "undefined" ? process.argv ?? [] : [];
+  const env = typeof process !== "undefined" ? process.env?.NODE_ENV : void 0;
+  const cmdArg = argv.find((a) => a === "dev" || a === "prod");
+  if (isStrict && detect === "cmd" && cmdArg === void 0) {
+    throw new Error('initDevMode: expected "dev" or "prod" as a CLI argument');
+  }
+  const isFromCmd = cmdArg !== void 0 ? cmdArg === "dev" : false;
+  const isFromEnv = env === "development";
+  if (detect === "cmd") {
+    return isFromCmd;
+  }
+  if (detect === "node_env") {
+    return isFromEnv;
+  }
+  return cmdArg !== void 0 ? isFromCmd : isFromEnv;
+}
+function resolveInitParam(param) {
+  if (param === void 0) {
+    return detectValue("both");
+  }
+  if (typeof param === "boolean") {
+    return param;
+  }
+  return detectValue(param.detect, param.strict);
+}
+function getDevMode() {
+  return typeof g[GLOBAL_KEY] === "boolean" ? g[GLOBAL_KEY] : false;
+}
+function initDevMode(param) {
+  if (typeof g[GLOBAL_KEY] === "boolean") {
+    return;
+  }
+  g[INIT_PARAM_KEY] = param;
+  g[GLOBAL_KEY] = resolveInitParam(param);
+}
+function overrideDevMode(value) {
+  const savedParam = g[INIT_PARAM_KEY];
+  g[GLOBAL_KEY] = value === "redetect" ? resolveInitParam(savedParam) : value;
+}
+export {
+  getDevMode,
+  initDevMode,
+  overrideDevMode
+};
+//# sourceMappingURL=dev-mode.js.map

package/dist/lib/dev-mode.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/lib/dev-mode.ts"],"sourcesContent":["// Stored in globalThis so state survives module re-evaluation and works across\n// module boundaries.\nconst GLOBAL_KEY = '__lifecycleion_is_dev__';\nconst INIT_PARAM_KEY = '__lifecycleion_init_param__';\n\ntype DevModeSource = 'cmd' | 'node_env' | 'both';\ntype InitParam =\n  | boolean\n  | { detect: DevModeSource; strict?: boolean }\n  | undefined;\n\n// Cast once at module level — avoids repeating the assertion in every function.\nconst g = globalThis as typeof globalThis & Record<string, unknown>;\n\nfunction detectValue(detect: DevModeSource, isStrict?: boolean): boolean {\n  // Guard against environments where process or its properties may not exist\n  // (e.g. browser without polyfill, Deno without Node compat, edge runtimes).\n  // Vite statically replaces process.env.NODE_ENV at build time, so it is safe\n  // on the client. process.argv is an empty array shim in browsers — harmless.\n  const argv: string[] =\n    typeof process !== 'undefined' ? (process.argv ?? []) : [];\n  const env: string | undefined =\n    typeof process !== 'undefined' ? process.env?.NODE_ENV : undefined;\n\n  const cmdArg = argv.find((a) => a === 'dev' || a === 'prod');\n\n  if (isStrict && detect === 'cmd' && cmdArg === undefined) {\n    throw new Error('initDevMode: expected \"dev\" or \"prod\" as a CLI argument');\n  }\n\n  const isFromCmd = cmdArg !== undefined ? cmdArg === 'dev' : false;\n  const isFromEnv = env === 'development';\n\n  if (detect === 'cmd') {\n    return isFromCmd;\n  }\n\n  if (detect === 'node_env') {\n    return isFromEnv;\n  }\n\n  // 'both': cmd wins when explicitly present, otherwise fall back to NODE_ENV\n  return cmdArg !== undefined ? isFromCmd : isFromEnv;\n}\n\nfunction resolveInitParam(param: InitParam): boolean {\n  if (param === undefined) {\n    return detectValue('both');\n  }\n\n  if (typeof param === 'boolean') {\n    return param;\n  }\n\n  return detectValue(param.detect, param.strict);\n}\n\n/**\n * Returns the current dev mode value.\n *\n * Reads `globalThis.__lifecycleion_is_dev__`. Defaults to `false` if\n * `initDevMode()` has not been called yet.\n */\nexport function getDevMode(): boolean {\n  return typeof g[GLOBAL_KEY] === 'boolean' ? g[GLOBAL_KEY] : false;\n}\n\n/**\n * Sets the dev mode global for the current process.\n *\n * First-wins: if the global is already set (e.g. set by the HTML injection on\n * the client, or by a prior `initDevMode()` call), this is a no-op. Call once\n * at startup before serving any requests.\n *\n * @param param\n *   - `true` / `false` — explicit value\n *   - `{ detect: 'cmd' }` — read from `process.argv` (\"dev\" or \"prod\")\n *   - `{ detect: 'node_env' }` — read from `NODE_ENV`\n *   - `{ detect: 'both' }` — argv takes precedence, falls back to `NODE_ENV`\n *   - `{ detect: 'cmd', strict: true }` — argv required, throws if absent\n *   - omitted — same as `{ detect: 'both' }`\n */\nexport function initDevMode(\n  param?: boolean | { detect: DevModeSource; strict?: boolean },\n): void {\n  if (typeof g[GLOBAL_KEY] === 'boolean') {\n    return; // first-wins — already initialized, no-op\n  }\n\n  g[INIT_PARAM_KEY] = param; // save original param so 'redetect' can replay it\n  g[GLOBAL_KEY] = resolveInitParam(param);\n}\n\n/**\n * Bypasses first-wins semantics and forces the dev mode value.\n *\n * Intended for testing or tooling — not for production use.\n *\n * Pass `'redetect'` to re-run the same detection logic that\n * `initDevMode()` used originally.\n */\nexport function overrideDevMode(value: boolean | 'redetect'): void {\n  const savedParam = g[INIT_PARAM_KEY] as InitParam;\n  g[GLOBAL_KEY] = value === 'redetect' ? resolveInitParam(savedParam) : value;\n}\n"],"mappings":";AAEA,IAAM,aAAa;AACnB,IAAM,iBAAiB;AASvB,IAAM,IAAI;AAEV,SAAS,YAAY,QAAuB,UAA6B;AAKvE,QAAM,OACJ,OAAO,YAAY,cAAe,QAAQ,QAAQ,CAAC,IAAK,CAAC;AAC3D,QAAM,MACJ,OAAO,YAAY,cAAc,QAAQ,KAAK,WAAW;AAE3D,QAAM,SAAS,KAAK,KAAK,CAAC,MAAM,MAAM,SAAS,MAAM,MAAM;AAE3D,MAAI,YAAY,WAAW,SAAS,WAAW,QAAW;AACxD,UAAM,IAAI,MAAM,yDAAyD;AAAA,EAC3E;AAEA,QAAM,YAAY,WAAW,SAAY,WAAW,QAAQ;AAC5D,QAAM,YAAY,QAAQ;AAE1B,MAAI,WAAW,OAAO;AACpB,WAAO;AAAA,EACT;AAEA,MAAI,WAAW,YAAY;AACzB,WAAO;AAAA,EACT;AAGA,SAAO,WAAW,SAAY,YAAY;AAC5C;AAEA,SAAS,iBAAiB,OAA2B;AACnD,MAAI,UAAU,QAAW;AACvB,WAAO,YAAY,MAAM;AAAA,EAC3B;AAEA,MAAI,OAAO,UAAU,WAAW;AAC9B,WAAO;AAAA,EACT;AAEA,SAAO,YAAY,MAAM,QAAQ,MAAM,MAAM;AAC/C;AAQO,SAAS,aAAsB;AACpC,SAAO,OAAO,EAAE,UAAU,MAAM,YAAY,EAAE,UAAU,IAAI;AAC9D;AAiBO,SAAS,YACd,OACM;AACN,MAAI,OAAO,EAAE,UAAU,MAAM,WAAW;AACtC;AAAA,EACF;AAEA,IAAE,cAAc,IAAI;AACpB,IAAE,UAAU,IAAI,iBAAiB,KAAK;AACxC;AAUO,SAAS,gBAAgB,OAAmC;AACjE,QAAM,aAAa,EAAE,cAAc;AACnC,IAAE,UAAU,IAAI,UAAU,aAAa,iBAAiB,UAAU,IAAI;AACxE;","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lifecycleion",
-  "version": "0.0.7",
+  "version": "0.0.8",
   "type": "module",
   "description": "A collection of foundational TypeScript utilities for managing application lifecycle, logging, retries, events, and common programming patterns",
   "exports": {
@@ -39,6 +39,11 @@
       "import": "./dist/lib/deep-clone.js",
       "require": "./dist/lib/deep-clone.cjs"
     },
+    "./dev-mode": {
+      "types": "./dist/lib/dev-mode.d.ts",
+      "import": "./dist/lib/dev-mode.js",
+      "require": "./dist/lib/dev-mode.cjs"
+    },
     "./error-to-string": {
       "types": "./dist/lib/error-to-string.d.ts",
       "import": "./dist/lib/error-to-string.js",