Key-Value String Parser Specification

Over-engineered 4KB parser for semicolon-separated strings. Ridiculously complex thanks to AI. Zero dependencies, maximum overkill. 🤖

Try it!

Key-Value String → JSON

Type here:

→

JSON result:

JSON → Key-Value String

Type here:

→

Key-Value result:

💡 Note: Quotes are automatically added when values contain special characters (=, ;, spaces, commas)

Abstract

This document specifies a simple key-value string format and parsing algorithm designed for single-line configuration strings, URL parameters, and command-line arguments. The format supports strings, numbers, arrays, and null values with a zero-dependency implementation thoroughly tested with 200+ unit tests.

1. Introduction

The Key-Value String format provides a human-readable and machine-parseable way to represent structured data in a single line. It is particularly useful for configuration strings, command-line parameters, URL parameters, and data exchange where JSON might be too verbose or complex. While multiline input works, the format is optimized for single-line usage and does not support comments.

2. Syntax Specification

2.1. Basic Format

A key-value string consists of pairs separated by semicolons:

key1=value1;key2=value2;key3=value3;

2.2. Data Types

The parser supports the following data types:

Strings: Unquoted or quoted with double quotes
Numbers: Integers and floating-point numbers
Arrays: Comma-separated values
Null: Empty values

2.3. Examples

name=John;title="Senior Developer";age=30;salary=75000.50;
tags=frontend,backend,javascript;scores=95,87,92;optional=;
items=apple,,orange;active=true;config="prod";

Note: Examples show single-line format. Comments are not supported in the actual parser.

3. Implementation

3.1. Installation

npm install key-value-string

3.2. Usage Examples

// 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);
// Output: { 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);
// Output: name=John;age=30;active=true;

3.3. Command Line Interface

# 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}'

# Validate syntax
kvs validate "name=John;age=30;"

4. Browser Support

Multiple build formats are provided for different environments:

UMD: Universal module for older browsers (ES2015+)
ESM: ES Modules for modern browsers (ES2020+)
CommonJS: Node.js environments (v14+)

5. Security Considerations

This parser does not execute code and only processes data. However, applications should validate parsed values before use, especially when processing untrusted input.

6. References

RFC 3986 - Uniform Resource Identifier (URI): Generic Syntax
RFC 8259 - The JavaScript Object Notation (JSON) Data Interchange Format

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