scenv 0.2.1 → 0.3.2

package/README.md

@@ -0,0 +1,65 @@
+# scenv
+
+Environment and context variables with runtime-configurable resolution.
+
+Define variables once with `scenv()`, then resolve values from **set overrides** (e.g. CLI `--set`), **environment**, **context files**, or **defaults**. Control behavior via config (file, env, or `configure()`)—same code, different config per run.
+
+**Requires Node 18+.**
+
+## Install
+
+```bash
+pnpm add scenv
+# or
+npm install scenv
+```
+
+## Quick start
+
+```ts
+import { configure, parseScenvArgs, scenv } from "scenv";
+
+// Optional: apply CLI flags (--set, --context, --prompt, etc.)
+configure(parseScenvArgs(process.argv.slice(2)));
+
+const apiUrl = scenv("API URL", {
+  key: "api_url",
+  env: "API_URL",
+  default: "http://localhost:4000",
+});
+
+const url = await apiUrl.get();         // throws if missing or invalid
+const result = await apiUrl.safeGet();  // { success, value? } | { success: false, error? }
+await apiUrl.save();                    // write current value to a context file
+```
+
+## Resolution order
+
+1. **Set overrides** – e.g. `--set key=value`
+2. **Environment** – `process.env[envKey]`
+3. **Context** – merged JSON context files
+4. **Default** – variable’s `default` option
+
+Prompting (when to ask the user) is controlled by config `prompt`: `always` | `never` | `fallback` | `no-env`.
+
+## Optional integrations
+
+| Package | Purpose |
+|--------|--------|
+| [scenv-zod](https://www.npmjs.com/package/scenv-zod) | `validator(zodSchema)` for type-safe validation and coercion. |
+| [scenv-inquirer](https://www.npmjs.com/package/scenv-inquirer) | `prompt()` and callbacks for interactive prompts. |
+
+## Documentation
+
+Full docs (config, contexts, resolution, saving, API) live in the [monorepo](https://github.com/PKWadsy/senv):
+
+- [Configuration](https://github.com/PKWadsy/senv/blob/main/docs/CONFIGURATION.md)
+- [Contexts](https://github.com/PKWadsy/senv/blob/main/docs/CONTEXTS.md)
+- [Resolution](https://github.com/PKWadsy/senv/blob/main/docs/RESOLUTION.md)
+- [Saving](https://github.com/PKWadsy/senv/blob/main/docs/SAVING.md)
+- [API reference](https://github.com/PKWadsy/senv/blob/main/docs/API.md)
+- [Integration (scenv-zod, scenv-inquirer)](https://github.com/PKWadsy/senv/blob/main/docs/INTEGRATION.md)
+
+## License
+
+MIT

package/dist/index.cjs

@@ -235,26 +235,6 @@ function writeToContext(contextName, key, value) {
   (0, import_node_fs2.writeFileSync)(path, JSON.stringify(data, null, 2) + "\n", "utf-8");
 }
 
-// src/prompt-default.ts
-var import_node_readline = require("readline");
-function defaultPrompt(name, defaultValue) {
-  const defaultStr = defaultValue !== void 0 && defaultValue !== null ? String(defaultValue) : "";
-  const message = defaultStr ? `Enter ${name} [${defaultStr}]: ` : `Enter ${name}: `;
-  const rl = (0, import_node_readline.createInterface)({ input: process.stdin, output: process.stdout });
-  return new Promise((resolve, reject) => {
-    rl.question(message, (answer) => {
-      rl.close();
-      const trimmed = answer.trim();
-      const value = trimmed !== "" ? trimmed : defaultStr;
-      resolve(value);
-    });
-    rl.on("error", (err) => {
-      rl.close();
-      reject(err);
-    });
-  });
-}
-
 // src/variable.ts
 function defaultKeyFromName(name) {
   return name.toLowerCase().replace(/\s+/g, "_").replace(/[^a-z0-9_]/gi, "");
@@ -296,23 +276,29 @@ function scenv(name, options = {}) {
     if (mode === "no-env") return !hadEnv;
     return false;
   }
-  async function getResolvedValue() {
+  async function getResolvedValue(overrides) {
     const config = loadConfig();
     const raw = await resolveRaw();
     const hadEnv = !config.ignoreEnv && process.env[envKey] !== void 0 && process.env[envKey] !== "";
     const hadValue = raw !== void 0;
+    const effectiveDefault = overrides?.default !== void 0 ? overrides.default : defaultValue;
     let wasPrompted = false;
     let value;
     if (shouldPrompt(config, hadValue, hadEnv)) {
-      const defaultForPrompt = raw !== void 0 ? raw : defaultValue;
       const callbacks = getCallbacks();
-      const fn = promptFn ?? callbacks.defaultPrompt ?? defaultPrompt;
+      const fn = overrides?.prompt ?? promptFn ?? callbacks.defaultPrompt;
+      if (typeof fn !== "function") {
+        throw new Error(
+          `Prompt required for variable "${name}" (key: ${key}) but no prompt was supplied and no defaultPrompt callback is configured. Set a prompt on the variable or configure({ callbacks: { defaultPrompt: ... } }).`
+        );
+      }
+      const defaultForPrompt = raw !== void 0 ? raw : effectiveDefault;
       value = await Promise.resolve(fn(name, defaultForPrompt));
       wasPrompted = true;
     } else if (raw !== void 0) {
       value = raw;
-    } else if (defaultValue !== void 0) {
-      value = defaultValue;
+    } else if (effectiveDefault !== void 0) {
+      value = effectiveDefault;
     } else {
       throw new Error(`Missing value for variable "${name}" (key: ${key})`);
     }
@@ -331,8 +317,8 @@ function scenv(name, options = {}) {
       error: "error" in normalized ? normalized.error : void 0
     };
   }
-  async function get() {
-    const { value, wasPrompted } = await getResolvedValue();
+  async function get(options2) {
+    const { value, wasPrompted } = await getResolvedValue(options2);
     const validated = validate(value);
     if (!validated.success) {
       throw new Error(
@@ -346,7 +332,12 @@ function scenv(name, options = {}) {
       const shouldAskSave = savePrompt === "always" || savePrompt === "ask" && wasPrompted;
       if (shouldAskSave) {
         const callbacks = getCallbacks();
-        const ctxToSave = callbacks.onAskSaveAfterPrompt && await callbacks.onAskSaveAfterPrompt(
+        if (typeof callbacks.onAskSaveAfterPrompt !== "function") {
+          throw new Error(
+            `savePrompt is "${savePrompt}" but onAskSaveAfterPrompt callback is not set. Configure callbacks via configure({ callbacks: { onAskSaveAfterPrompt: ... } }).`
+          );
+        }
+        const ctxToSave = await callbacks.onAskSaveAfterPrompt(
           name,
           final,
           config.contexts ?? []
@@ -356,9 +347,9 @@ function scenv(name, options = {}) {
     }
     return final;
   }
-  async function safeGet() {
+  async function safeGet(options2) {
     try {
-      const v = await get();
+      const v = await get(options2);
       return { success: true, value: v };
     } catch (err) {
       return { success: false, error: err };
@@ -376,14 +367,15 @@ function scenv(name, options = {}) {
     let contextName = config.saveContextTo;
     if (contextName === "ask") {
       const callbacks = getCallbacks();
-      if (typeof callbacks.onAskContext === "function") {
-        contextName = await callbacks.onAskContext(
-          name,
-          config.contexts ?? []
+      if (typeof callbacks.onAskContext !== "function") {
+        throw new Error(
+          `saveContextTo is "ask" but onAskContext callback is not set. Configure callbacks via configure({ callbacks: { onAskContext: ... } }).`
         );
-      } else {
-        contextName = config.contexts?.[0] ?? "default";
       }
+      contextName = await callbacks.onAskContext(
+        name,
+        config.contexts ?? []
+      );
     }
     if (!contextName) contextName = config.contexts?.[0] ?? "default";
     writeToContext(contextName, key, String(validated.data));

package/dist/index.d.cts

@@ -70,9 +70,16 @@ interface ScenvVariableOptions<T> {
     validator?: (val: T) => ValidatorResult<T>;
     prompt?: PromptFn<T>;
 }
+/** Overrides for a single .get() or .safeGet() call. */
+interface GetOptions<T> {
+    /** Use this prompt for this call instead of the variable's prompt or callbacks.defaultPrompt. */
+    prompt?: PromptFn<T>;
+    /** Use this as the default for this call if no value from set/env/context. */
+    default?: T;
+}
 interface ScenvVariable<T> {
-    get(): Promise<T>;
-    safeGet(): Promise<{
+    get(options?: GetOptions<T>): Promise<T>;
+    safeGet(options?: GetOptions<T>): Promise<{
         success: true;
         value: T;
     } | {
@@ -90,4 +97,4 @@ declare function scenv<T>(name: string, options?: ScenvVariableOptions<T>): Scen
  */
 declare function parseScenvArgs(argv: string[]): Partial<ScenvConfig>;
 
-export { type DefaultPromptFn, type PromptMode, type SavePromptMode, type ScenvCallbacks, type ScenvConfig, type ScenvVariable, configure, discoverContextPaths, getCallbacks, getContextValues, loadConfig, parseScenvArgs, resetConfig, scenv };
+export { type DefaultPromptFn, type GetOptions, type PromptMode, type SavePromptMode, type ScenvCallbacks, type ScenvConfig, type ScenvVariable, configure, discoverContextPaths, getCallbacks, getContextValues, loadConfig, parseScenvArgs, resetConfig, scenv };

package/dist/index.d.ts

@@ -70,9 +70,16 @@ interface ScenvVariableOptions<T> {
     validator?: (val: T) => ValidatorResult<T>;
     prompt?: PromptFn<T>;
 }
+/** Overrides for a single .get() or .safeGet() call. */
+interface GetOptions<T> {
+    /** Use this prompt for this call instead of the variable's prompt or callbacks.defaultPrompt. */
+    prompt?: PromptFn<T>;
+    /** Use this as the default for this call if no value from set/env/context. */
+    default?: T;
+}
 interface ScenvVariable<T> {
-    get(): Promise<T>;
-    safeGet(): Promise<{
+    get(options?: GetOptions<T>): Promise<T>;
+    safeGet(options?: GetOptions<T>): Promise<{
         success: true;
         value: T;
     } | {
@@ -90,4 +97,4 @@ declare function scenv<T>(name: string, options?: ScenvVariableOptions<T>): Scen
  */
 declare function parseScenvArgs(argv: string[]): Partial<ScenvConfig>;
 
-export { type DefaultPromptFn, type PromptMode, type SavePromptMode, type ScenvCallbacks, type ScenvConfig, type ScenvVariable, configure, discoverContextPaths, getCallbacks, getContextValues, loadConfig, parseScenvArgs, resetConfig, scenv };
+export { type DefaultPromptFn, type GetOptions, type PromptMode, type SavePromptMode, type ScenvCallbacks, type ScenvConfig, type ScenvVariable, configure, discoverContextPaths, getCallbacks, getContextValues, loadConfig, parseScenvArgs, resetConfig, scenv };

package/dist/index.js

@@ -208,26 +208,6 @@ function writeToContext(contextName, key, value) {
   writeFileSync(path, JSON.stringify(data, null, 2) + "\n", "utf-8");
 }
 
-// src/prompt-default.ts
-import { createInterface } from "readline";
-function defaultPrompt(name, defaultValue) {
-  const defaultStr = defaultValue !== void 0 && defaultValue !== null ? String(defaultValue) : "";
-  const message = defaultStr ? `Enter ${name} [${defaultStr}]: ` : `Enter ${name}: `;
-  const rl = createInterface({ input: process.stdin, output: process.stdout });
-  return new Promise((resolve, reject) => {
-    rl.question(message, (answer) => {
-      rl.close();
-      const trimmed = answer.trim();
-      const value = trimmed !== "" ? trimmed : defaultStr;
-      resolve(value);
-    });
-    rl.on("error", (err) => {
-      rl.close();
-      reject(err);
-    });
-  });
-}
-
 // src/variable.ts
 function defaultKeyFromName(name) {
   return name.toLowerCase().replace(/\s+/g, "_").replace(/[^a-z0-9_]/gi, "");
@@ -269,23 +249,29 @@ function scenv(name, options = {}) {
     if (mode === "no-env") return !hadEnv;
     return false;
   }
-  async function getResolvedValue() {
+  async function getResolvedValue(overrides) {
     const config = loadConfig();
     const raw = await resolveRaw();
     const hadEnv = !config.ignoreEnv && process.env[envKey] !== void 0 && process.env[envKey] !== "";
     const hadValue = raw !== void 0;
+    const effectiveDefault = overrides?.default !== void 0 ? overrides.default : defaultValue;
     let wasPrompted = false;
     let value;
     if (shouldPrompt(config, hadValue, hadEnv)) {
-      const defaultForPrompt = raw !== void 0 ? raw : defaultValue;
       const callbacks = getCallbacks();
-      const fn = promptFn ?? callbacks.defaultPrompt ?? defaultPrompt;
+      const fn = overrides?.prompt ?? promptFn ?? callbacks.defaultPrompt;
+      if (typeof fn !== "function") {
+        throw new Error(
+          `Prompt required for variable "${name}" (key: ${key}) but no prompt was supplied and no defaultPrompt callback is configured. Set a prompt on the variable or configure({ callbacks: { defaultPrompt: ... } }).`
+        );
+      }
+      const defaultForPrompt = raw !== void 0 ? raw : effectiveDefault;
       value = await Promise.resolve(fn(name, defaultForPrompt));
       wasPrompted = true;
     } else if (raw !== void 0) {
       value = raw;
-    } else if (defaultValue !== void 0) {
-      value = defaultValue;
+    } else if (effectiveDefault !== void 0) {
+      value = effectiveDefault;
     } else {
       throw new Error(`Missing value for variable "${name}" (key: ${key})`);
     }
@@ -304,8 +290,8 @@ function scenv(name, options = {}) {
       error: "error" in normalized ? normalized.error : void 0
     };
   }
-  async function get() {
-    const { value, wasPrompted } = await getResolvedValue();
+  async function get(options2) {
+    const { value, wasPrompted } = await getResolvedValue(options2);
     const validated = validate(value);
     if (!validated.success) {
       throw new Error(
@@ -319,7 +305,12 @@ function scenv(name, options = {}) {
       const shouldAskSave = savePrompt === "always" || savePrompt === "ask" && wasPrompted;
       if (shouldAskSave) {
         const callbacks = getCallbacks();
-        const ctxToSave = callbacks.onAskSaveAfterPrompt && await callbacks.onAskSaveAfterPrompt(
+        if (typeof callbacks.onAskSaveAfterPrompt !== "function") {
+          throw new Error(
+            `savePrompt is "${savePrompt}" but onAskSaveAfterPrompt callback is not set. Configure callbacks via configure({ callbacks: { onAskSaveAfterPrompt: ... } }).`
+          );
+        }
+        const ctxToSave = await callbacks.onAskSaveAfterPrompt(
           name,
           final,
           config.contexts ?? []
@@ -329,9 +320,9 @@ function scenv(name, options = {}) {
     }
     return final;
   }
-  async function safeGet() {
+  async function safeGet(options2) {
     try {
-      const v = await get();
+      const v = await get(options2);
       return { success: true, value: v };
     } catch (err) {
       return { success: false, error: err };
@@ -349,14 +340,15 @@ function scenv(name, options = {}) {
     let contextName = config.saveContextTo;
     if (contextName === "ask") {
       const callbacks = getCallbacks();
-      if (typeof callbacks.onAskContext === "function") {
-        contextName = await callbacks.onAskContext(
-          name,
-          config.contexts ?? []
+      if (typeof callbacks.onAskContext !== "function") {
+        throw new Error(
+          `saveContextTo is "ask" but onAskContext callback is not set. Configure callbacks via configure({ callbacks: { onAskContext: ... } }).`
         );
-      } else {
-        contextName = config.contexts?.[0] ?? "default";
       }
+      contextName = await callbacks.onAskContext(
+        name,
+        config.contexts ?? []
+      );
     }
     if (!contextName) contextName = config.contexts?.[0] ?? "default";
     writeToContext(contextName, key, String(validated.data));

package/package.json

@@ -1,17 +1,10 @@
 {
   "name": "scenv",
-  "version": "0.2.1",
+  "version": "0.3.2",
   "description": "Environment and context variables with runtime-configurable resolution",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/PKWadsy/senv.git"
-  },
-  "keywords": [
-    "env",
-    "config",
-    "context",
-    "variables"
-  ],
+  "repository": { "type": "git", "url": "https://github.com/PKWadsy/scenv" },
+  "publishConfig": { "access": "public", "provenance": true },
+  "keywords": ["env", "config", "context", "variables"],
   "type": "module",
   "main": "dist/index.cjs",
   "module": "dist/index.js",
@@ -26,6 +19,11 @@
   "files": [
     "dist"
   ],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
   "devDependencies": {
     "@types/node": "^20.0.0",
     "@vitest/coverage-v8": "^2.1.9",
@@ -35,10 +33,5 @@
   },
   "engines": {
     "node": ">=18"
-  },
-  "scripts": {
-    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
-    "test": "vitest run",
-    "test:watch": "vitest"
   }
-}
+}