jsurl

JSURL is a lightweight JavaScript library that encodes JSON-like values into compact, URL-safe strings, avoiding the bloat and unreadability of percent-encoded JSON in query parameters. It replaces JSON’s curly braces, brackets, and punctuation with characters that survive URL encoding untouched, so nested objects and arrays can be passed through a URL without needing a separate encode/decode pass.

The library exposes a minimal API — stringify, parse, and a defensive tryParse — that mirrors JSON’s own interface, making it a near drop-in choice wherever application state needs to live in a shareable link, such as filter panels, saved views, or deep-linkable UI state.

What You Get

• A stringify(value) function that serializes numbers, strings, booleans, arrays, and objects into a compact JSURL string
• A parse(string) function that decodes a JSURL string back into its original JavaScript value
• A tryParse(string, default) function that safely falls back to a default value instead of throwing on malformed input
• Support for percent-escaped single quotes, so JSURL strings survive being embedded inside already-encoded URLs

Common Use Cases

• Encoding filter and search state into shareable, bookmarkable URLs
• Persisting UI state (open panels, sort order, pagination) across page reloads via the query string
• Passing structured parameters between client and server without a JSON.stringify + encodeURIComponent round trip
• Building deep links that restore an exact application view from a URL alone

Under The Hood

Architecture JSURL ships as a single-file module (lib/jsurl.js) exporting stringify, parse, and tryParse through an IIFE that targets both CommonJS (module.exports) and the browser (a global JSURL object); index.js is a thin re-export of that module. There is no internal layering — encoding and decoding are each implemented as one recursive function operating on a shared mutable string cursor (i), with helper closures (encode, decode, eat, parseOne) nested directly inside stringify/parse rather than factored into separate, testable units. This is appropriate for the library’s narrow scope, but it means the tokenizing and value-construction concerns are tightly coupled — a change to the punctuation scheme would require touching the same functions that walk the string.

Tech Stack The library is plain, dependency-free JavaScript (ES5-style syntax, no transpilation or bundling step) with a UMD-like export pattern for dual Node/browser use. Its only dependency is a dev-time test runner, qunit (pinned to ^0.7.7), invoked via a test script in package.json. A bower.json file indicates the project once also targeted Bower-based frontend distribution, and a .travis.yml config wires up legacy Travis CI. There is no build tooling, TypeScript, or bundler configuration of any kind.

Code Quality Tests live under test/common/*.js and are collected by test/index.js, which globs the directory and runs each file through QUnit. Coverage is reasonably thorough for the library’s surface area: basic scalar values, arrays, objects, deeply nested mixed structures, percent-escaped (and doubly percent-escaped) quotes, and the tryParse fallback path are all exercised, each asserting both a direct stringify result and a stringify-parse-stringify round trip. There is no TypeScript or type annotations, and no linter or formatter configuration is present in the repo. Error handling in parse is achieved by throwing descriptive Error objects on malformed syntax, with tryParse provided as an explicit safe wrapper around that behavior.

API Design The public surface is intentionally minimal — stringify, parse, and tryParse — mirroring the shape of the global JSON object so it reads as a near drop-in replacement for anyone already familiar with JSON.stringify/JSON.parse. There are no configuration options, no classes to instantiate, and no setup beyond require("jsurl"), which keeps the boilerplate to get started at essentially zero. The tradeoff is that the format itself (tildes and parentheses replacing JSON’s punctuation) has to be learned by anyone reading raw JSURL output, though the README documents the encoding rules clearly with worked examples.