@vyriy/config 0.1.9

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vyriy 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

@@ -0,0 +1,68 @@
+# @vyriy/config
+
+Environment config parsing utility for Vyriy projects.
+
+## Purpose
+
+This package provides a small helper for reading environment variables and parsing them into useful runtime values.
+
+## Install
+
+With npm:
+
+```bash
+npm install @vyriy/config
+```
+
+With Yarn:
+
+```bash
+yarn add @vyriy/config
+```
+
+## Usage
+
+```ts
+import { getConfig, Parser } from '@vyriy/config';
+
+const port = getConfig('PORT', 3000);
+const features = getConfig<string[]>('FEATURES', [], 'auto');
+const payload = getConfig<{ ok: boolean }>('PAYLOAD', null, 'json');
+const timeout = getConfig('TIMEOUT', null, Parser.duration);
+```
+
+## Exports
+
+The package exposes:
+
+```ts
+import { getConfig, Parser, auto } from '@vyriy/config';
+import { parseDuration } from '@vyriy/config/duration';
+```
+
+## API
+
+- `getConfig(envName, defaultValue?, parser = auto)` reads an environment variable and parses it.
+- if the env is missing and a non-null default is provided, the default is returned unchanged.
+- if the env is missing and no default is provided, `getConfig` throws.
+- `getConfig(envName, null, parser)` lets you skip the default and pass a parser explicitly.
+
+Built-in parser names:
+
+- `auto`
+- `string`
+- `number`
+- `int`
+- `boolean`
+- `csv`
+- `json`
+- `duration`
+
+You can also pass parser functions directly:
+
+```ts
+import { getConfig, Parser } from '@vyriy/config';
+
+const port = getConfig('PORT', null, Parser.int);
+const enabled = getConfig('ENABLED', null, (value) => Parser.boolean(value, { extendedBooleans: true }));
+```

package/auto.d.ts

@@ -0,0 +1,2 @@
+import type { AutoEnvValue, AutoOptions } from './types.js';
+export declare const auto: <T extends AutoEnvValue = string>(value: string, options?: AutoOptions) => T;

package/auto.js

@@ -0,0 +1,35 @@
+import { FALSE_VALUES, DEFAULT_AUTO_OPTIONS, TRUE_VALUES } from './constants.js';
+import { splitCsv } from './csv.js';
+import { tryJsonParse } from './json.js';
+import { parseNumber } from './number.js';
+export const auto = (value, options = {}) => {
+    const resolvedOptions = { ...DEFAULT_AUTO_OPTIONS, ...options };
+    const trimmed = value.trim();
+    const normalized = trimmed.toLowerCase();
+    if (resolvedOptions.nullish && normalized === 'null') {
+        return null;
+    }
+    if (resolvedOptions.nullish && normalized === 'undefined') {
+        return undefined;
+    }
+    if (TRUE_VALUES.has(normalized) && (normalized === 'true' || resolvedOptions.extendedBooleans)) {
+        return true;
+    }
+    if (FALSE_VALUES.has(normalized) && (normalized === 'false' || resolvedOptions.extendedBooleans)) {
+        return false;
+    }
+    const parsedNumber = parseNumber(trimmed);
+    if (parsedNumber !== undefined) {
+        return parsedNumber;
+    }
+    if (resolvedOptions.json) {
+        const parsed = tryJsonParse(trimmed);
+        if (parsed !== undefined) {
+            return parsed;
+        }
+    }
+    if (resolvedOptions.csvArrays && trimmed.includes(',')) {
+        return splitCsv(trimmed);
+    }
+    return trimmed;
+};

package/boolean.d.ts

@@ -0,0 +1,2 @@
+import type { ConfigParserWithOptions, StrictOptions } from './types.js';
+export declare const boolean: ConfigParserWithOptions<boolean, StrictOptions>;

package/boolean.js

@@ -0,0 +1,19 @@
+import { FALSE_VALUES, TRUE_VALUES } from './constants.js';
+const parseBoolean = (value, options = {}) => {
+    const normalized = value.trim().toLowerCase();
+    const { extendedBooleans = true } = options;
+    if (normalized === 'true') {
+        return true;
+    }
+    if (normalized === 'false') {
+        return false;
+    }
+    if (extendedBooleans && TRUE_VALUES.has(normalized)) {
+        return true;
+    }
+    if (extendedBooleans && FALSE_VALUES.has(normalized)) {
+        return false;
+    }
+    throw new TypeError(`Expected boolean, got: "${value}"`);
+};
+export const boolean = (value, options = {}) => parseBoolean(value, options);

package/config.d.ts

@@ -0,0 +1,2 @@
+import type { GetConfig } from './types.js';
+export declare const getConfig: GetConfig;

package/config.js

@@ -0,0 +1,14 @@
+import { existsEnv, getEnv } from '@vyriy/env';
+import { auto, parsers } from './parser.js';
+const NO_DEFAULT = Symbol('NO_DEFAULT');
+const isParserName = (value) => typeof value === 'string';
+const resolveParser = (parser = auto) => isParserName(parser) ? parsers[parser] : parser;
+export const getConfig = (envName, defaultValue = NO_DEFAULT, parser = auto) => {
+    if (!existsEnv(envName)) {
+        if (defaultValue !== NO_DEFAULT && defaultValue !== null) {
+            return defaultValue;
+        }
+        throw new Error(`Environment variable ${envName} is not defined!`);
+    }
+    return resolveParser(parser)(getEnv(envName));
+};

package/constants.d.ts

@@ -0,0 +1,4 @@
+import type { AutoOptions } from './types.js';
+export declare const DEFAULT_AUTO_OPTIONS: Required<AutoOptions>;
+export declare const TRUE_VALUES: Set<string>;
+export declare const FALSE_VALUES: Set<string>;

package/constants.js

@@ -0,0 +1,18 @@
+export const DEFAULT_AUTO_OPTIONS = {
+    extendedBooleans: true,
+    csvArrays: true,
+    json: true,
+    nullish: true,
+};
+export const TRUE_VALUES = new Set([
+    'true',
+    '1',
+    'yes',
+    'on',
+]);
+export const FALSE_VALUES = new Set([
+    'false',
+    '0',
+    'no',
+    'off',
+]);

package/csv.d.ts

@@ -0,0 +1,2 @@
+export declare const splitCsv: (value: string) => string[];
+export declare const csv: (value: string) => string[];

package/csv.js

@@ -0,0 +1,5 @@
+export const splitCsv = (value) => value
+    .split(',')
+    .map((entry) => entry.trim())
+    .filter(Boolean);
+export const csv = (value) => splitCsv(value);

package/duration.d.ts

@@ -0,0 +1 @@
+export declare const parseDuration: (value: string) => number;

package/duration.js

@@ -0,0 +1,15 @@
+const DURATION_UNITS = {
+    ms: 1,
+    s: 1000,
+    m: 60_000,
+    h: 3_600_000,
+    d: 86_400_000,
+};
+export const parseDuration = (value) => {
+    const match = /^(\d+)(ms|s|m|h|d)$/.exec(value.trim().toLowerCase());
+    if (!match) {
+        throw new Error(`Invalid duration: "${value}"`);
+    }
+    const [, amount, unit] = match;
+    return Number(amount) * DURATION_UNITS[unit];
+};

package/index.d.ts

@@ -0,0 +1,4 @@
+export * from './config.js';
+export * from './parser.js';
+export * from './duration.js';
+export type * from './types.js';

package/index.js

@@ -0,0 +1,3 @@
+export * from './config.js';
+export * from './parser.js';
+export * from './duration.js';

package/json.d.ts

@@ -0,0 +1,2 @@
+export declare const tryJsonParse: (value: string) => Record<string, unknown> | unknown[] | undefined;
+export declare const json: <T = unknown>(value: string) => T;

package/json.js

@@ -0,0 +1,18 @@
+export const tryJsonParse = (value) => {
+    if (!((value.startsWith('{') && value.endsWith('}')) || (value.startsWith('[') && value.endsWith(']')))) {
+        return undefined;
+    }
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return undefined;
+    }
+};
+export const json = (value) => {
+    const parsed = tryJsonParse(value.trim());
+    if (parsed === undefined) {
+        throw new TypeError(`Expected JSON (object/array), got: "${value}"`);
+    }
+    return parsed;
+};

package/number.d.ts

@@ -0,0 +1,3 @@
+export declare const parseNumber: (value: string) => number | undefined;
+export declare const number: (value: string) => number;
+export declare const int: (value: string) => number;

package/number.js

@@ -0,0 +1,19 @@
+const isNumericString = (value) => value !== '' && !Number.isNaN(Number(value));
+export const parseNumber = (value) => {
+    const trimmed = value.trim();
+    return isNumericString(trimmed) ? Number(trimmed) : undefined;
+};
+export const number = (value) => {
+    const parsed = parseNumber(value);
+    if (parsed === undefined) {
+        throw new TypeError(`Expected number, got: "${value}"`);
+    }
+    return parsed;
+};
+export const int = (value) => {
+    const parsed = number(value);
+    if (!Number.isInteger(parsed)) {
+        throw new TypeError(`Expected integer, got: ${parsed}`);
+    }
+    return parsed;
+};

package/package.json

@@ -0,0 +1,129 @@
+{
+  "name": "@vyriy/config",
+  "version": "0.1.9",
+  "description": "Environment config parsing utility for Vyriy projects",
+  "type": "module",
+  "main": "./index.js",
+  "dependencies": {
+    "@vyriy/env": "0.1.9"
+  },
+  "license": "MIT",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.js",
+      "default": "./index.js"
+    },
+    "./auto": {
+      "types": "./auto.d.ts",
+      "import": "./auto.js",
+      "default": "./auto.js"
+    },
+    "./auto.js": {
+      "types": "./auto.d.ts",
+      "import": "./auto.js",
+      "default": "./auto.js"
+    },
+    "./boolean": {
+      "types": "./boolean.d.ts",
+      "import": "./boolean.js",
+      "default": "./boolean.js"
+    },
+    "./boolean.js": {
+      "types": "./boolean.d.ts",
+      "import": "./boolean.js",
+      "default": "./boolean.js"
+    },
+    "./config": {
+      "types": "./config.d.ts",
+      "import": "./config.js",
+      "default": "./config.js"
+    },
+    "./config.js": {
+      "types": "./config.d.ts",
+      "import": "./config.js",
+      "default": "./config.js"
+    },
+    "./constants": {
+      "types": "./constants.d.ts",
+      "import": "./constants.js",
+      "default": "./constants.js"
+    },
+    "./constants.js": {
+      "types": "./constants.d.ts",
+      "import": "./constants.js",
+      "default": "./constants.js"
+    },
+    "./csv": {
+      "types": "./csv.d.ts",
+      "import": "./csv.js",
+      "default": "./csv.js"
+    },
+    "./csv.js": {
+      "types": "./csv.d.ts",
+      "import": "./csv.js",
+      "default": "./csv.js"
+    },
+    "./duration": {
+      "types": "./duration.d.ts",
+      "import": "./duration.js",
+      "default": "./duration.js"
+    },
+    "./duration.js": {
+      "types": "./duration.d.ts",
+      "import": "./duration.js",
+      "default": "./duration.js"
+    },
+    "./index": {
+      "types": "./index.d.ts",
+      "import": "./index.js",
+      "default": "./index.js"
+    },
+    "./index.js": {
+      "types": "./index.d.ts",
+      "import": "./index.js",
+      "default": "./index.js"
+    },
+    "./json": {
+      "types": "./json.d.ts",
+      "import": "./json.js",
+      "default": "./json.js"
+    },
+    "./json.js": {
+      "types": "./json.d.ts",
+      "import": "./json.js",
+      "default": "./json.js"
+    },
+    "./number": {
+      "types": "./number.d.ts",
+      "import": "./number.js",
+      "default": "./number.js"
+    },
+    "./number.js": {
+      "types": "./number.d.ts",
+      "import": "./number.js",
+      "default": "./number.js"
+    },
+    "./parser": {
+      "types": "./parser.d.ts",
+      "import": "./parser.js",
+      "default": "./parser.js"
+    },
+    "./parser.js": {
+      "types": "./parser.d.ts",
+      "import": "./parser.js",
+      "default": "./parser.js"
+    },
+    "./string": {
+      "types": "./string.d.ts",
+      "import": "./string.js",
+      "default": "./string.js"
+    },
+    "./string.js": {
+      "types": "./string.d.ts",
+      "import": "./string.js",
+      "default": "./string.js"
+    }
+  }
+}

package/parser.d.ts

@@ -0,0 +1,10 @@
+import type { ConfigParsers } from './types.js';
+export { auto } from './auto.js';
+export { boolean } from './boolean.js';
+export { csv } from './csv.js';
+export { parseDuration as duration } from './duration.js';
+export { int, number } from './number.js';
+export { json } from './json.js';
+export { string } from './string.js';
+export declare const parsers: ConfigParsers;
+export declare const Parser: ConfigParsers;

package/parser.js

@@ -0,0 +1,25 @@
+import { auto } from './auto.js';
+import { boolean } from './boolean.js';
+import { csv } from './csv.js';
+import { parseDuration as duration } from './duration.js';
+import { int, number } from './number.js';
+import { json } from './json.js';
+import { string } from './string.js';
+export { auto } from './auto.js';
+export { boolean } from './boolean.js';
+export { csv } from './csv.js';
+export { parseDuration as duration } from './duration.js';
+export { int, number } from './number.js';
+export { json } from './json.js';
+export { string } from './string.js';
+export const parsers = {
+    auto,
+    string,
+    number,
+    int,
+    boolean,
+    csv,
+    json,
+    duration,
+};
+export const Parser = parsers;

package/string.d.ts

@@ -0,0 +1 @@
+export declare const string: (value: string) => string;

package/string.js

@@ -0,0 +1 @@
+export const string = (value) => value;

package/types.d.ts

@@ -0,0 +1,29 @@
+export type AutoEnvValue = string | number | boolean | null | undefined | Record<string, unknown> | unknown[];
+export type AutoOptions = {
+    extendedBooleans?: boolean;
+    csvArrays?: boolean;
+    json?: boolean;
+    nullish?: boolean;
+};
+export type StrictOptions = {
+    extendedBooleans?: boolean;
+};
+export type ConfigParser<T = unknown> = (value: string) => T;
+export type ConfigParserWithOptions<T, TOptions> = (value: string, options?: TOptions) => T;
+export type ConfigParsers = {
+    auto: <T extends AutoEnvValue = string>(value: string, options?: AutoOptions) => T;
+    string: (value: string) => string;
+    number: (value: string) => number;
+    int: (value: string) => number;
+    boolean: (value: string, options?: StrictOptions) => boolean;
+    csv: (value: string) => string[];
+    json: <T = unknown>(value: string) => T;
+    duration: (value: string) => number;
+};
+export type ConfigParserName = keyof ConfigParsers;
+export type ConfigParserLike<T = unknown> = ConfigParserName | ConfigParser<T>;
+export type GetConfig = {
+    <T extends AutoEnvValue = string>(envName: string): T | never;
+    <T>(envName: string, defaultValue: T, parser?: ConfigParserLike<T>): T;
+    <T>(envName: string, defaultValue: null, parser: ConfigParserLike<T>): T | never;
+};