ananthakumaran / u

μ is a JavaScript library for encoding/decoding state (JavaScript object) in URL

μ

Without μ: http://app.com/url#%7B%22lookingFor%22:%22bride%22,%22age%22:%5B25,30%5D,%22religion%22:%22Hindu%22,%22motherTongue%22:%22Bengali%22,%22onlyProfileWithPhoto%22:true%7D

With μ: http://app.com/url#bHhc9I-aqa

μ is a JavaScript library for encoding/decoding state (JavaScript object) in URL. Define a spec for the state, based on which the encoding is done. Manage the state with versioning.

Example

Import the library

import {fromJson, encode, decode} from "u";

Define the spec.

var spec = {
        lookingFor: ['oneOf', 'bride', 'groom'],
        age: ['tuple', ['integer'] /* min */, ['integer'] /* max */],
        religion: ['oneOf', 'Hindu', 'Muslim', 'Christian', 'Sikh', 'Parsi', 'Jain', 'Buddhist', 'Jewish', 'No Religion', 'Spiritual', 'Other'],
        motherTongue: ['oneOf', 'Assamese', 'Bengali', 'English', 'Gujarati', 'Hindi', 'Kannada', 'Konkani', 'Malayalam', 'Marathi', 'Marwari', 'Odia', 'Punjabi', 'Sindhi', 'Tamil', 'Telugu', 'Urdu'],
        onlyProfileWithPhoto: ['boolean']
};

var v1 = fromJson(1, spec);

Encode the object/state.

var encodedv1 = encode(v1, {lookingFor: 'bride', age: [25, 30], religion: 'Hindu', motherTongue: 'Bengali', onlyProfileWithPhoto: true});
//=> 'bHhc9I-aqa'
decode([v1], encodedv1) //=> {lookingFor: 'bride', age: [25, 30], religion: 'Hindu', motherTongue: 'Bengali', onlyProfileWithPhoto: true});

Update your spec, as your application state space grows. Use versioning to encode/decode state.

var newSpec = _.extend({}, spec, {
        maritialStatus: ['oneOf', "Doesn't Matter", 'Never Married', 'Divorced', 'Widowed', 'Awaiting Divorce', 'Annulled']
});
var v2 = fromJson(2, newSpec, function (old) {
        old.maritialStatus = "Doesn't Matter";
        return old;
});

decode([v1, v2], encodedv1) //=> {lookingFor: 'bride', age: [25, 30], religion: 'Hindu', motherTongue: 'Bengali', onlyProfileWithPhoto: true, maritialStatus: "Doesn't Matter"});
var encodedv2 = encode(v2, {lookingFor: 'bride', age: [25, 30], religion: 'Hindu', motherTongue: 'Bengali', onlyProfileWithPhoto: true, maritialStatus: 'Never Married'});
//=> 'cHlc9I-aHaa'
decode([v1, v2], encodedv2) //=> {lookingFor: 'bride', age: [25, 30], religion: 'Hindu', motherTongue: 'Bengali', onlyProfileWithPhoto: true, maritialStatus: 'Never Married'});

API

fromJson(version, spec, [migrate])

version - spec version number
spec - used to define the structure and domain of the data.

structure
object is defined using { key: specForValue, ... }
array is defined using ['array', specForValue ]
tuple is defined using ['tuple', specForValueAtIndexZero, specForValueAtIndexOne, ...]

domain
domain is defined using [domainName, arg1, arg2, ...]

Domain	Args	Description
oneOf	allowed values	can be considered similar to enum. As we only encode the index position, the value could be anything
integer		any integer
boolean		true or false
fixedchar	Size of the string	fixed length string
varchar		variable length string

migrate - a function that will get called in case where you decode an object encoded using older spec. For example, there are three versions v1, v2, v3 and you try to decode the string encoded using v1, then the migrate method in v2 and v3 will get called with the decoded value.

encode(coder, object)

coder - coder created using fromJson
object - object that needs to encoded

decode(coders, blob)

coders - array of coder.
blob - the string that is returned by encode.

u's Issues

Optional fields

Hello Anantha,

First of all, thanks for creating this library. We are evaluating different solutions for serializing json in the URL and u is our preferred so far.

I have a small doubt about a case when a property may be optional. For example :

const cart = {
  id : 123,
  giftCardId : undefined
}

giftCardId is not always present. Is there an axiomatic method of modeling this case?

A workaround would be to model it as an array with maximum of one element. Other solution would be to add an 'optional' type which would permit null/undefined values.

What do you think?

Cheers,
Karol

Encode on the client and decode on the server without knowing the original dataset

I notice that your encoder and decoder need to know the original dataset, but I want to accomplish something really simple.

From the client side, a user will type a really long text, something around 2k characters max, there are no special characters or funny things, just regular text.

I want to send the request encrypted and compressed to a URL webpage, for the reason I need to do it that way.

On the server side, I don't know what they will send, I don't have the V1 dataset as your example, so I will try to do something like this:

/* Client-side:*/
var data = "{value='REALLY LONG TEXT WITH NO SPECIAL CHARACTERS, JUST TEXT, NUMBERS AND SOME CHARACTERS LIKE / - *'}";
var data_encoded = encode(data);

Request.Redirect("mydomain.com/webpage.aspx?data=data_encoded");
/* Server-side: */
var data_encoded = Request.QueryString("data");
var data_decoded = decode(data_encoded);
.....

Do you think that I can accomplish this with your library?