lukeed / qss Goto Github PK

A tiny (294b) browser utility for encoding & decoding a querystring.

License: MIT License

JavaScript 100.00%

qss's Introduction

qss

A tiny (305B) browser utility for stringifying a query Object.

You should only consider using this within a browser context since Node's built-in querystring.stringify is much faster and should be used in a Node environment! An ideal use case is serializing a query object before an API request is sent.

This module exposes three module definitions:

ES Module: dist/qss.mjs
CommonJS: dist/qss.js
UMD: dist/qss.min.js

Install

$ npm install --save qss

Usage

import { encode, decode } from 'qss';

encode({ foo:'hello', bar:[1,2,3], baz:true });
//=> 'foo=hello&bar=1&bar=2&bar=3&baz=true'

encode({ foo:123 }, '?');
//=> '?foo=123'

encode({ bar:'world' }, 'foo=hello&');
//=> 'foo=hello&bar=world'

decode('foo=hello&bar=1&bar=2&bar=3&baz=true');
//=> { foo:'hello', bar:[1,2,3], baz:true };

API

qss.encode(params, prefix)

Returns: String

Returns the formatted querystring.

params

Type: Object

The object that contains all query parameter keys & their values.

prefix

Type: String
Default: ''

An optional prefix. The stringified params will be appended to this value, so it must end with your desired joiner; eg ?.

Important: No checks or validations will run on your prefix. Similarly, no character is used to "glue" the query string to your prefix string.

qss.decode(query)

Returns: Object

Returns an Object with decoded keys and values.

Repetitive keys will form an Array of its values. Also, qss will attempt to typecast Boolean and Number values.

query

Type: String

The query string, without its leading ? character.

qss.decode(
  location.search.substring(1) // removes the "?"
);

Benchmarks

Running Node v10.13.0

Encode

qss             x 1,112,341 ops/sec ±0.24% (96 runs sampled)
native          x 5,303,246 ops/sec ±0.76% (95 runs sampled)
querystringify  x   950,501 ops/sec ±0.76% (96 runs sampled)
query-string    x   347,603 ops/sec ±1.05% (92 runs sampled)
qs              x   733,449 ops/sec ±0.62% (97 runs sampled)

Decode

qss             x   443,667 ops/sec ±0.17% (95 runs sampled)
native          x   189,194 ops/sec ±0.44% (94 runs sampled)
querystringify  x   282,169 ops/sec ±0.26% (96 runs sampled)
query-string    x   191,334 ops/sec ±0.71% (95 runs sampled)
qs              x   168,165 ops/sec ±0.41% (93 runs sampled)

License

MIT © Luke Edwards

qss's People

Contributors

Stargazers

Watchers

Forkers

id0sch linecode dwsyoyo hotell hjaintech leeoniya yusufozturk pawn666 calebeby danew jsnmoon x-ecutionner runjak wmzy anparasan3 grainstackdev laoshu133

qss's Issues

Fails to decode when the value is a base64 string

When a base64 needs padding (==) at the end??; qss seems to not decode properly.

Take the following reproduction, compared against query-string:

import {decode} from 'qss';
import {parse} from 'query-string';

const qs = 'abc=dGVzdA==&y=10'; // the y=10 here is just to see more than one value

console.log('qss', decode(qs));
console.log('query-string', parse(qs));

//~

/*
qss { abc: 'dGVzdA', y: 10 }
query-string [Object: null prototype] { abc: 'dGVzdA==', y: '10'
*/

The "dGVzdA==" is a base64 string of the word "test". JavaScript itself seems to be loose in that this still decodes just fine, but passing this string into strict systems like Auth0 or C# the decode of that base64 fails.

So as an aside question, if this lib was to remain js focused should we solve the use-case on the backend systems, and padd out the base64—or should qss decode with the equals?

benchmark against qs?

resolve empty query string values to undefined

Hey Luke. First of thanks for this project. While using it I noticed one "strange" behaviour while decoding query string from URL.

Example:

const queryString = 'foo=foo&bar=bar1&moo='
const parsed = decode(queryString)

expect(parsed).toEqual({foo:'foo', bar: 'bar1', moo: 0 })

const queryString = 'foo=foo&bar=bar1&moo'
const parsed = decode(queryString)

expect(parsed).toEqual({foo:'foo', bar: 'bar1', moo: 'undefined' })

I would suggest that empty query values moo= should not be casted to number/zero rather they should be set to undefined or empty string ''. moo example returns 'undefined' as a string not value (that should be IMHO fixed as well, to be consistent).

WDYT?

I can send PR if you ok with my suggestion/report 👍

cheers

nested objects

hey @lukeed

probably add support for nested objects. a[foo]=1&a[bar]=2 is a super common thing.

Should qss check for object properties and bail if there is none?

Hey Luke,

I ran into something today and after looking at the qss code wondered if it should return an empty string if the object passed to encode has no children/properties?

Just an idea, wondered what your take was on it

Browsers support?

Hello,
I'm thinking of using this library in my current project but there is no information about the browsers support.
Do you know which browsers are supported?

Cast issues

Also, qss will attempt to typecast Boolean and Number values.
Is there a way to this feature be optional? I'm facing issues with unwanted casting. Strings like '0101' or document numbers that starts with zero are being casted and must be handled padding zeros.
It would be nice a parameter indicating if should cast.