@verifyhash/query-string 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 verifyhash
+
+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,135 @@
+# @verifyhash/query-string
+
+Zero-dependency URL query-string **parse + stringify** for Node.js, typed
+from birth (hand-written `index.d.ts` shipped with the package). It covers
+the query-string shapes real web apps actually exchange — repeated keys,
+bracket arrays, one level of `a[b]=c` nesting — and it **never throws on
+malformed input to `parse()`** (a bad `%GG` sequence falls back to the raw
+token instead of crashing your request handler).
+
+**Who it's for:** Node.js developers who want predictable query-string
+behavior without pulling in `qs` (which has 5+ transitive behaviors around
+deep nesting and allocation limits) and without the `URLSearchParams`
+limitations (no arrays-by-default, no nesting, iterator-based API).
+
+## Install
+
+```sh
+npm install @verifyhash/query-string
+```
+
+## Example
+
+```js
+const qs = require('@verifyhash/query-string');
+
+qs.parse('?tag=a&tag=b&filter[color]=red&page=');
+// { tag: ['a', 'b'], filter: { color: 'red' }, page: '' }
+
+qs.parse('ids[]=7&ids[]=9&q=caf%C3%A9+au+lait');
+// { ids: ['7', '9'], q: 'café au lait' }
+
+qs.stringify({ tag: ['a', 'b'], filter: { color: 'red' }, page: '' });
+// 'tag[]=a&tag[]=b&filter[color]=red&page='
+
+qs.stringify({ q: 'two words' }, { spaceAsPlus: true });
+// 'q=two+words'   (default is %20: 'q=two%20words')
+```
+
+Round-trip property: `qs.parse(qs.stringify(x))` deep-equals `x` for the
+supported shape set (see limits below) — the test suite proves it on a table
+of shapes including single-element arrays, which survive because arrays
+default to bracket format (`a[]=only` parses back to `['only']`, whereas
+`repeat` format would collapse it to the string `'only'`).
+
+## API
+
+### `parse(str, opts?)`
+
+Parses a query string (a leading `?` is tolerated and stripped) into a
+**null-prototype object** — keys like `__proto__` are plain data and cannot
+pollute `Object.prototype`, but it also means you should use `Object.keys(obj)`
+rather than `obj.hasOwnProperty(...)` on the result.
+
+- **Repeated keys become arrays:** `a=1&a=2` → `{ a: ['1', '2'] }`. The first
+  occurrence stays a scalar; the second converts the slot to an array.
+- **Bracket array syntax:** `a[]=1&a[]=2` → `{ a: ['1', '2'] }`, and a single
+  `a[]=1` is still `{ a: ['1'] }` (an array, unlike a plain `a=1`).
+- **One level of nesting:** `a[b]=c` → `{ a: { b: 'c' } }`. Repeated nested
+  keys array-merge too: `a[b]=1&a[b]=2` → `{ a: { b: ['1', '2'] } }`.
+  Bracket syntax is recognized *after* percent-decoding, so `b%5Bc%5D=d`
+  also nests.
+- **Decoding:** `+` means space (in keys and values), then percent-decoding
+  is applied. **Malformed percent-sequences never throw** — the token falls
+  back to its raw text with `+` already converted (`a=%GG+x` → `{ a: '%GG x' }`).
+- **Empty and valueless keys:** `a=` → `{ a: '' }` always. A bare `a` (no `=`)
+  is also `{ a: '' }` by default; pass `{ nullForBare: true }` to get
+  `{ a: null }` instead so you can distinguish `?flag` from `?flag=`.
+- **Empty pairs are skipped:** `a=1&&b=2` parses like `a=1&b=2`.
+- **`=` inside a value survives:** `a=b=c` → `{ a: 'b=c' }` (split on the
+  first `=` only).
+- Non-string input returns `{}`.
+
+Options (`ParseOptions`):
+
+| option        | default | effect                                             |
+|---------------|---------|----------------------------------------------------|
+| `nullForBare` | `false` | bare keys parse to `null` instead of `''`          |
+
+### `stringify(obj, opts?)`
+
+Serializes a plain object to a query string (no leading `?`), using
+`encodeURIComponent` (spaces become `%20` by default). Output key order is
+the object's insertion order — stable and predictable.
+
+- **Values:** `string` as-is; `number` / `boolean` / `bigint` via `String()`;
+  `null` emits a bare key (`{ a: null }` → `'a'`); `undefined` is skipped
+  entirely.
+- **Arrays:** default `arrayFormat: 'bracket'` emits `a[]=1&a[]=2`. Opt into
+  `'repeat'` for `a=1&a=2` — but note a single-element array then round-trips
+  to a plain string.
+- **One level of nesting:** `{ a: { b: 'c' } }` → `'a[b]=c'`. Arrays inside a
+  nested object emit repeated nested keys (`a[b]=1&a[b]=2`).
+- **Anything deeper throws `TypeError`** — see limits.
+
+Options (`StringifyOptions`):
+
+| option        | default     | effect                                          |
+|---------------|-------------|--------------------------------------------------|
+| `spaceAsPlus` | `false`     | encode `' '` as `+` instead of `%20` (keys too) |
+| `arrayFormat` | `'bracket'` | `'bracket'` → `a[]=1`; `'repeat'` → `a=1`       |
+
+## Limits (honest)
+
+- **Nesting is exactly one level deep, on purpose.** `parse('a[b][c]=d')`
+  does NOT build `{ a: { b: { c: 'd' } } }` — the key stays literal:
+  `{ 'a[b][c]': 'd' }`. `stringify({ a: { b: { c: 'd' } } })` throws a
+  `TypeError` rather than half-implementing recursion. If you need deep
+  structures in a URL, JSON-encode the value instead.
+- **Bracket characters in data keys are ambiguous.** Because bracket syntax
+  is recognized after decoding, a literal key `'a[b]'` stringifies to
+  `a%5Bb%5D=...` but parses back as nesting `{ a: { b: ... } }`. Such keys
+  are outside the round-trip set.
+- **Conflicting shapes fall back to literal keys.** `a=1&a[b]=2` parses to
+  `{ a: '1', 'a[b]': '2' }` — the nested pair keeps its literal key rather
+  than silently destroying the scalar.
+- **Empty arrays vanish.** `stringify({ a: [] })` emits nothing for `a`, so
+  they do not round-trip (query strings have no way to say "empty list").
+- All parsed leaves are **strings** (or `null` with `nullForBare`) — there is
+  no number/boolean coercion on parse, so `stringify({ a: 1 })` round-trips
+  to `{ a: '1' }`.
+
+## Tests
+
+```sh
+node test/index.test.js
+```
+
+65 checks: a golden-vector table for `parse` and `stringify` (repeated keys,
+bracket arrays, nesting, `+`/percent decoding, empty/valueless keys, malformed
+`%GG`/`%E4%` sequences, `&&` pairs, unicode, `=` inside values, a 500×
+repeated key, prototype-pollution safety) plus a round-trip property table.
+
+## License
+
+MIT

package/index.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Type declarations for @verifyhash/query-string — zero-dependency URL
+ * query-string parse + stringify (leading '?' tolerance, repeated keys ->
+ * arrays, bracket arrays a[]=, ONE level of bracket nesting a[b]=c,
+ * '+'-as-space decoding, malformed %-sequences never throw).
+ *
+ * Hand-written against index.js — every runtime export is declared here.
+ */
+
+/** Options for parse(). */
+export interface ParseOptions {
+  /**
+   * When true, a valueless key ('a' with no '=') parses to null instead of
+   * the default ''. An explicit 'a=' is ALWAYS ''.
+   */
+  nullForBare?: boolean;
+}
+
+/** How stringify() serializes top-level arrays. */
+export type ArrayFormat = 'bracket' | 'repeat';
+
+/** Options for stringify(). */
+export interface StringifyOptions {
+  /** Encode ' ' as '+' instead of the default %20. */
+  spaceAsPlus?: boolean;
+  /**
+   * 'bracket' (default): a[]=1&a[]=2 — round-trip safe even for
+   * single-element arrays. 'repeat': a=1&a=2 — a single-element array then
+   * parses back as a plain string.
+   */
+  arrayFormat?: ArrayFormat;
+}
+
+/** A parsed leaf: decoded string, or null for bare keys under nullForBare. */
+export type ParsedLeaf = string | null;
+
+/** A parsed slot: leaf, repeated-key/bracket array, or one nested level. */
+export type ParsedValue =
+  | ParsedLeaf
+  | ParsedLeaf[]
+  | { [innerKey: string]: ParsedLeaf | ParsedLeaf[] };
+
+/**
+ * The result of parse(): a null-prototype object (keys like '__proto__' are
+ * plain data), so do not rely on Object.prototype methods being reachable
+ * directly on it (use Object.keys()/JSON.stringify() etc.).
+ */
+export interface ParsedQuery {
+  [key: string]: ParsedValue;
+}
+
+/** Scalars stringify() accepts (null = bare key, undefined = skipped). */
+export type StringifyScalar = string | number | boolean | bigint | null | undefined;
+
+/** A top-level stringify() value: scalar, array, or ONE level of nesting. */
+export type StringifyValue =
+  | StringifyScalar
+  | StringifyScalar[]
+  | { [innerKey: string]: StringifyScalar | StringifyScalar[] };
+
+/** The input shape stringify() accepts. */
+export interface StringifyInput {
+  [key: string]: StringifyValue;
+}
+
+/**
+ * Parse a URL query string (with or without a leading '?') into an object.
+ * Never throws on malformed input: bad %-sequences fall back to the raw
+ * token ('+' still becomes a space).
+ */
+export function parse(str: string, opts?: ParseOptions): ParsedQuery;
+
+/**
+ * Serialize a plain object into a query string (no leading '?'), with
+ * encodeURIComponent-based encoding and stable insertion key order.
+ * Throws TypeError on non-object input or nesting deeper than one level.
+ */
+export function stringify(obj: StringifyInput, opts?: StringifyOptions): string;

package/index.js

@@ -0,0 +1,227 @@
+'use strict';
+
+/**
+ * @verifyhash/query-string — zero-dependency URL query-string parse + stringify.
+ *
+ * Scope (deliberately small and fully documented):
+ *   - parse():  leading '?' tolerance, repeated keys -> arrays, bracket array
+ *     syntax (a[]=1&a[]=2), ONE level of bracket nesting (a[b]=c), '+'-as-space
+ *     and percent-decoding, malformed %-sequences fall back to the raw token
+ *     (never throws).
+ *   - stringify(): encodeURIComponent-based encoding (space as %20 by default,
+ *     opt-in '+'), stable insertion key order, arrays as a[]= by default so
+ *     single-element arrays survive a round trip, one level of object nesting.
+ *
+ * Deeper nesting (a[b][c]=d) is intentionally OUT of scope: parse() keeps such
+ * keys as literal flat keys, and stringify() throws a TypeError rather than
+ * half-implementing recursion.
+ */
+
+/**
+ * Regex for a supported structured key AFTER percent-decoding:
+ *   base[]      -> bracket array push
+ *   base[inner] -> one-level nesting
+ * The base and inner segments must themselves be bracket-free, so deeper
+ * nesting like a[b][c] deliberately fails to match and stays a literal key.
+ */
+const STRUCTURED_KEY_RE = /^([^[\]]+)\[([^[\]]*)\]$/;
+
+/**
+ * Decode one token ('+' means space, then percent-decode). If the
+ * percent-decoding is malformed (e.g. '%GG', truncated '%E4%'), the token is
+ * returned with '+' already converted to spaces but percent-sequences left
+ * exactly as they were — parse() never throws on bad input.
+ */
+function safeDecode(token) {
+  const plusReplaced = token.replace(/\+/g, ' ');
+  try {
+    return decodeURIComponent(plusReplaced);
+  } catch (e) {
+    return plusReplaced;
+  }
+}
+
+/** Is `v` a non-array, non-null object (a candidate nesting container)? */
+function isNestObject(v) {
+  return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+
+/**
+ * Repeated-key merge: first value stays scalar, a second value converts the
+ * slot to an array, further values append.
+ */
+function assign(container, key, value) {
+  if (!(key in container)) {
+    container[key] = value;
+    return;
+  }
+  const existing = container[key];
+  if (Array.isArray(existing)) {
+    existing.push(value);
+  } else {
+    container[key] = [existing, value];
+  }
+}
+
+/**
+ * Parse a URL query string into an object.
+ *
+ * @param {string} str  Query string, with or without a leading '?'.
+ * @param {{nullForBare?: boolean}} [opts]
+ *   nullForBare: when true, a valueless key ('a' with no '=') parses to null
+ *   instead of the default '' (an explicit 'a=' is ALWAYS '').
+ * @returns {Object} A null-prototype object (so keys like '__proto__' are
+ *   plain data and cannot pollute Object.prototype).
+ */
+function parse(str, opts) {
+  opts = opts || {};
+  const bare = opts.nullForBare ? null : '';
+  const result = Object.create(null);
+  if (typeof str !== 'string') return result;
+
+  let s = str;
+  if (s.charCodeAt(0) === 63 /* '?' */) s = s.slice(1);
+  if (s === '') return result;
+
+  for (const pair of s.split('&')) {
+    if (pair === '') continue; // tolerate '&&' and trailing '&'
+
+    const eq = pair.indexOf('=');
+    let rawKey, value;
+    if (eq === -1) {
+      rawKey = pair;
+      value = bare;
+    } else {
+      rawKey = pair.slice(0, eq);
+      value = safeDecode(pair.slice(eq + 1)); // '=' inside the value survives
+    }
+    const key = safeDecode(rawKey);
+
+    const m = STRUCTURED_KEY_RE.exec(key);
+    if (m !== null && m[2] === '') {
+      // Bracket array syntax: base[]=v
+      const base = m[1];
+      if (Array.isArray(result[base])) {
+        result[base].push(value);
+      } else if (!(base in result)) {
+        result[base] = [value];
+      } else {
+        // base already holds a scalar/object: keep the literal key instead of
+        // destroying data (documented conflict fallback).
+        assign(result, key, value);
+      }
+      continue;
+    }
+    if (m !== null) {
+      // One-level nesting: base[inner]=v
+      const base = m[1];
+      const inner = m[2];
+      if (!(base in result)) result[base] = Object.create(null);
+      if (isNestObject(result[base])) {
+        assign(result[base], inner, value);
+      } else {
+        // base already holds a scalar/array: literal-key fallback.
+        assign(result, key, value);
+      }
+      continue;
+    }
+    // Plain key (this includes deeper-nested-looking keys like 'a[b][c]',
+    // which are intentionally treated as literal flat keys).
+    assign(result, key, value);
+  }
+  return result;
+}
+
+/** encodeURIComponent, optionally with spaces as '+' instead of %20. */
+function encode(str, spaceAsPlus) {
+  let out = encodeURIComponent(str);
+  if (spaceAsPlus) out = out.replace(/%20/g, '+');
+  return out;
+}
+
+function isScalar(v) {
+  const t = typeof v;
+  return t === 'string' || t === 'number' || t === 'boolean' || t === 'bigint';
+}
+
+function scalarToString(v) {
+  return typeof v === 'string' ? v : String(v);
+}
+
+/**
+ * Serialize an object into a URL query string (no leading '?').
+ *
+ * @param {Object} obj  A plain object. Values may be: string | number |
+ *   boolean | bigint | null (bare key, no '=') | undefined (skipped) |
+ *   arrays of those | ONE level of plain-object nesting whose values are
+ *   again scalars/null/undefined/arrays. Anything deeper throws a TypeError.
+ * @param {{spaceAsPlus?: boolean, arrayFormat?: 'bracket'|'repeat'}} [opts]
+ *   spaceAsPlus: encode ' ' as '+' instead of the default %20.
+ *   arrayFormat: 'bracket' (default, a[]=1&a[]=2 — round-trip safe even for
+ *   single-element arrays) or 'repeat' (a=1&a=2 — note a single-element array
+ *   then parses back as a plain string).
+ * @returns {string}
+ */
+function stringify(obj, opts) {
+  opts = opts || {};
+  const spaceAsPlus = !!opts.spaceAsPlus;
+  const arrayFormat = opts.arrayFormat || 'bracket';
+  if (arrayFormat !== 'bracket' && arrayFormat !== 'repeat') {
+    throw new TypeError(
+      "opts.arrayFormat must be 'bracket' or 'repeat' (got " + JSON.stringify(arrayFormat) + ')'
+    );
+  }
+  if (!isNestObject(obj)) {
+    throw new TypeError('stringify expects a plain object (got ' + (obj === null ? 'null' : typeof obj) + ')');
+  }
+
+  const parts = [];
+  // Emit one pair; null -> bare key (no '='), undefined -> nothing.
+  function emit(encodedKey, value, where) {
+    if (value === undefined) return;
+    if (value === null) {
+      parts.push(encodedKey);
+      return;
+    }
+    if (!isScalar(value)) {
+      throw new TypeError('unsupported value at ' + where + ' (' + typeof value + ')');
+    }
+    parts.push(encodedKey + '=' + encode(scalarToString(value), spaceAsPlus));
+  }
+
+  for (const key of Object.keys(obj)) {
+    // Insertion order of Object.keys IS the output order (stable).
+    const v = obj[key];
+    const ek = encode(key, spaceAsPlus);
+    if (v === undefined) continue;
+    if (v === null || isScalar(v)) {
+      emit(ek, v, JSON.stringify(key));
+    } else if (Array.isArray(v)) {
+      const arrKey = arrayFormat === 'bracket' ? ek + '[]' : ek;
+      for (const item of v) emit(arrKey, item, JSON.stringify(key) + '[]');
+    } else if (isNestObject(v)) {
+      for (const innerKey of Object.keys(v)) {
+        const iv = v[innerKey];
+        const nk = ek + '[' + encode(innerKey, spaceAsPlus) + ']';
+        const where = JSON.stringify(key) + '[' + JSON.stringify(innerKey) + ']';
+        if (iv === undefined) continue;
+        if (iv === null || isScalar(iv)) {
+          emit(nk, iv, where);
+        } else if (Array.isArray(iv)) {
+          // Arrays inside a nested object serialize as repeated nested keys
+          // (a[b]=1&a[b]=2); see README for the single-element caveat.
+          for (const item of iv) emit(nk, item, where);
+        } else {
+          throw new TypeError(
+            'deeper than one level of nesting is intentionally unsupported: key ' + where
+          );
+        }
+      }
+    } else {
+      throw new TypeError('unsupported value for key ' + JSON.stringify(key) + ' (' + typeof v + ')');
+    }
+  }
+  return parts.join('&');
+}
+
+module.exports = { parse, stringify };

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@verifyhash/query-string",
+  "version": "0.1.0",
+  "description": "Zero-dependency URL query-string parse + stringify for Node.js: leading-'?' tolerance, repeated keys to arrays, bracket arrays (a[]=), one documented level of bracket nesting (a[b]=c), '+'-as-space decoding, and malformed percent-sequences that never throw.",
+  "keywords": [
+    "query-string",
+    "querystring",
+    "url",
+    "parse",
+    "stringify",
+    "urlencoded",
+    "zero-dependency",
+    "typescript"
+  ],
+  "main": "index.js",
+  "types": "index.d.ts",
+  "scripts": {
+    "test": "node test/index.test.js"
+  },
+  "license": "MIT",
+  "files": [
+    "index.js",
+    "README.md",
+    "LICENSE",
+    "index.d.ts"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/verifyhash/libs.git",
+    "directory": "query-string"
+  },
+  "homepage": "https://github.com/verifyhash/libs/tree/main/query-string#readme",
+  "bugs": {
+    "url": "https://github.com/verifyhash/libs/issues"
+  }
+}