optionkit 0.0.0-stage → 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 optionkit contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,42 @@
-# Temporary Holding Version
+# optionkit
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+`optionkit` resolves typed Node.js configuration from defaults, environment
+variables, and long CLI flags.
+
+```js
+import { loadConfig } from "optionkit";
+
+const config = loadConfig({
+  defaults: {
+    port: 3000,
+    debug: false,
+    logLevel: "info",
+  },
+  prefix: "MY_APP_",
+});
+```
+
+With `MY_APP_PORT=4000` and `node app.js --port=5000 --debug`, the result is:
+
+```js
+{
+  port: 5000,
+  debug: true,
+  logLevel: "info",
+}
+```
+
+Precedence is `defaults < environment < CLI`. Camel-case keys map to
+upper-snake-case environment names (`logLevel` becomes `MY_APP_LOG_LEVEL`) and
+kebab-case CLI flags (`--log-level`). Boolean flags accept `--debug` and
+`--no-debug`.
+
+## Install
+
+```sh
+bun add optionkit
+```
+
+## License
+
+MIT

package/index.d.ts

@@ -0,0 +1,16 @@
+export type ConfigValue = string | number | boolean;
+
+export interface LoadConfigOptions<T extends Record<string, ConfigValue>> {
+  defaults: T;
+  env?: Readonly<Record<string, string | undefined>>;
+  argv?: readonly string[];
+  prefix?: string;
+}
+
+/**
+ * Resolves configuration using defaults, environment variables, and CLI flags,
+ * in increasing order of precedence.
+ */
+export declare function loadConfig<T extends Record<string, ConfigValue>>(
+  options: LoadConfigOptions<T>,
+): T;

package/index.js

@@ -0,0 +1,105 @@
+function toConfigKey(flag) {
+  return flag.replace(/-([a-zA-Z0-9])/g, (_, character) => character.toUpperCase());
+}
+
+function toEnvironmentKey(key) {
+  return key
+    .replace(/([a-z0-9])([A-Z])/g, "$1_$2")
+    .replace(/-/g, "_")
+    .toUpperCase();
+}
+
+function parseBoolean(value, key, source) {
+  const normalized = String(value).toLowerCase();
+
+  if (["1", "true", "yes", "on"].includes(normalized)) return true;
+  if (["0", "false", "no", "off"].includes(normalized)) return false;
+
+  throw new TypeError(`${source} value for ${key} must be a boolean`);
+}
+
+function coerce(value, sample, key, source) {
+  if (typeof sample === "string") return String(value);
+  if (typeof sample === "boolean") return parseBoolean(value, key, source);
+
+  if (typeof sample === "number") {
+    const parsed = Number(value);
+    if (Number.isFinite(parsed)) return parsed;
+    throw new TypeError(`${source} value for ${key} must be a finite number`);
+  }
+
+  throw new TypeError(`default value for ${key} must be a string, number, or boolean`);
+}
+
+function parseArguments(argv) {
+  const values = new Map();
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (token === "--") break;
+    if (!token.startsWith("--")) continue;
+
+    const body = token.slice(2);
+    if (body.startsWith("no-") && !body.includes("=")) {
+      values.set(toConfigKey(body.slice(3)), false);
+      continue;
+    }
+
+    const equalsAt = body.indexOf("=");
+    if (equalsAt !== -1) {
+      values.set(toConfigKey(body.slice(0, equalsAt)), body.slice(equalsAt + 1));
+      continue;
+    }
+
+    const key = toConfigKey(body);
+    const next = argv[index + 1];
+    if (next !== undefined && !next.startsWith("--")) {
+      values.set(key, next);
+      index += 1;
+    } else {
+      values.set(key, true);
+    }
+  }
+
+  return values;
+}
+
+/**
+ * Resolves a typed configuration object. Later sources override earlier ones:
+ * defaults, then environment variables, then command-line flags.
+ */
+export function loadConfig({
+  defaults,
+  env = process.env,
+  argv = process.argv.slice(2),
+  prefix = "",
+}) {
+  if (defaults === null || typeof defaults !== "object" || Array.isArray(defaults)) {
+    throw new TypeError("defaults must be an object");
+  }
+
+  const resolved = { ...defaults };
+
+  for (const [key, sample] of Object.entries(defaults)) {
+    coerce(sample, sample, key, "default");
+    const environmentKey = `${prefix}${toEnvironmentKey(key)}`;
+    const environmentValue = env[environmentKey];
+
+    if (environmentValue !== undefined) {
+      resolved[key] = coerce(environmentValue, sample, key, "environment");
+    }
+  }
+
+  for (const [key, value] of parseArguments(argv)) {
+    if (!Object.hasOwn(defaults, key)) continue;
+
+    const sample = defaults[key];
+    if (value === true && typeof sample !== "boolean") {
+      throw new TypeError(`CLI flag --${key} requires a value`);
+    }
+
+    resolved[key] = coerce(value, sample, key, "CLI");
+  }
+
+  return resolved;
+}

package/package.json

@@ -1,6 +1,43 @@
 {
   "name": "optionkit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.1",
+  "description": "Resolve typed Node.js configuration from defaults, environment variables, and CLI flags.",
+  "type": "module",
+  "main": "./index.js",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.js",
+      "default": "./index.js"
+    }
+  },
+  "files": [
+    "index.js",
+    "index.d.ts"
+  ],
+  "scripts": {
+    "test": "bun test"
+  },
+  "keywords": [
+    "args",
+    "cli",
+    "config",
+    "environment"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/regbo/optionkit.git"
+  },
+  "bugs": {
+    "url": "https://github.com/regbo/optionkit/issues"
+  },
+  "homepage": "https://github.com/regbo/optionkit#readme",
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}