key-value-string

A simple key-value string parser with zero dependencies. Designed for single-line key-value strings with support for numbers, quoted strings, and arrays. Perfect for configuration strings, URL parameters, and command-line arguments.

Thoroughly tested with 200+ unit tests to ensure reliability and edge case handling.

Installation

For Library Usage

npm install key-value-string

For CLI Usage (Global Installation)

npm install -g key-value-string

After global installation, the kvs command will be available in your terminal.

Usage

Node.js (CommonJS)

const { parseKeyValueString, toKeyValueString } = require('key-value-string');

// Parse key-value string
const result = parseKeyValueString('name=John;age=30;tags=frontend,backend;');
console.log(result);
// { name: 'John', age: 30, tags: ['frontend', 'backend'] }

// Convert object to key-value string
const kvString = toKeyValueString({ name: 'John', age: 30, active: true });
console.log(kvString);
// name=John;age=30;active=true;

Node.js (ES Modules)

import { parseKeyValueString, toKeyValueString } from 'key-value-string';

const parsed = parseKeyValueString('server=localhost;port=3000;debug=true;');
console.log(parsed);
// { server: 'localhost', port: 3000, debug: true }

Browser (UMD)

<script src="https://unpkg.com/key-value-string/dist/index.umd.js"></script>
<script>
  const { parseKeyValueString, toKeyValueString } = KeyValueString;
  
  const config = parseKeyValueString('theme=dark;fontSize=14;showLineNumbers=true;');
  console.log(config);
</script>

Browser (ES Modules)

<script type="module">
  import { parseKeyValueString } from 'https://unpkg.com/key-value-string/dist/index.esm.js';
  
  const settings = parseKeyValueString('width=800;height=600;fullscreen=false;');
  console.log(settings);
</script>

CLI Usage

Note: Install globally first with npm install -g key-value-string

# Parse key-value string to JSON
kvs parse "name=John;age=30;tags=frontend,backend;"

# Convert JSON to key-value string
kvs stringify '{"name":"John","age":30,"tags":["frontend","backend"]}'

# Validate key-value string syntax
kvs validate "name=John;age=30;"

# Parse from file
kvs parse -f config.kvs

# Convert JSON file to key-value string
kvs stringify -f data.json

# Show help
kvs --help

Syntax

The parser is designed for single-line key-value strings (though multiline works, comments are not supported):

• Key-value pairs: key=value;
• Numbers: Automatically parsed (age=30 → { age: 30 })
• Quoted strings: name="John Doe"; for values with spaces or special characters
• Arrays: tags=frontend,backend; → { tags: ['frontend', 'backend'] }
• Null values: optional=; → { optional: null }
• Empty arrays: tags=,; → { tags: [null] }

Note: Comments (# or //) are not supported. Use for single-line configuration strings, URL parameters, or command-line arguments.

API

parseKeyValueString(input: string): KeyValueObject

Parses a key-value string into an object.

• input: The key-value string to parse
• Returns: Parsed object
• Throws: Error if the string is malformed

toKeyValueString(obj: KeyValueObject): string

Converts an object to a key-value string.

• obj: The object to convert
• Returns: Key-value string representation

Types

interface KeyValueObject {
  [key: string]: string | number | null | Array<string | number | null>;
}

Examples

Configuration Strings

// Parse application config string
const configString = 'host=localhost;port=3000;database="my_app_db";timeout=5000;features=auth,logging,cache;debug=true;';
const config = parseKeyValueString(configString);

// Use the config
console.log(`Server running on ${config.host}:${config.port}`);
// Output: Server running on localhost:3000

URL Parameters Style

// Parse URL-like parameters
const params = parseKeyValueString('user=123;action=edit;theme=dark;');
console.log(params); // { user: 123, action: 'edit', theme: 'dark' }

Environment Variables Style

// Convert environment-like variables
const env = {
  NODE_ENV: 'production',
  PORT: 8080,
  FEATURES: ['auth', 'ssl', 'cache']
};

const envString = toKeyValueString(env);
console.log(envString); // NODE_ENV=production;PORT=8080;FEATURES=auth,ssl,cache;

Browser Compatibility

• UMD build: Supports ES2015+ (IE11+ with polyfills)
• ESM build: Supports ES2020+ (modern browsers)
• CommonJS build: Node.js 14+

License

MIT

Built with ❤️ and way too much coffee in a single night of pure vibecoding.