attrash-islam / golden-path

Golden Path

Golden Path

Golden Path is a functional (immutable) query tiny parser that can give you the chance to do your object/array queries and updates on the fly.

This module has the following functions:

• get
• update
• v

Note: Mutating objects might break the get so the objects that the Golden Path deals with should be updated by the update function only. This happens because we use cache for optimizations stuff. It's recommended to call clearPathResolverCache in order to clear it at some point (This is more relevant when using SSR).

Examples!

import { get, update, v } from 'golden-path';

const object = { name: 'islam' };
get('name', object); // 'islam'

const object = { peoples: [{ id: 1 }] };
get(`peoples.0.id`, object); // 1

const object = { peoples: [{ id: 1 }, { id: 1 }] };
get(`peoples[id=1]`, object); // { id: 1 } - Only returns first match

const object = { peoples: [{ name: 'John' }, { name: 'Alex' }] };
get(`peoples[name="Alex"]`, object); // { name: 'Alex' }

// For dynamic data it's recommended to wrap with v() in order to not break the parser.
const nameFromServer = '[]&4%45.';
const object = { peoples: [{ name: nameFromServer }, { name: 'x#DCGEDS' }] };
get(`peoples[name="${v(nameFromServer)}"]`, object); // { name: '[]&4%45.' }

const object = { peoples: [{ id: 1 }, { id: 1 }] };
get(`peoples*[id=1]`, object); // { id: 1 }, { id: 1 } - returns all matches

const object = { peoples: [{ id: 1, age: 20 }, { id: 1, age: 30 }] };
get(`peoples*[id=1][age>=20]`, object); // [{ id: 1, age: 20 }, { id: 1, age: 30 }]

const object = { peoples: [{ id: 1, age: 20, kind: 'human' }, { id: 1, age: 30, kind: 'robot' }] };
get(`peoples*[id=1][age>=20].kind`, object); // ['human', 'robot']


// The same can be done with update but update will return the whole root object after being updated.
const object = { peoples: [{ id: 1, age: 20 }, { id: 1, age: 30 }] };

// update can take a value or a function that pass the current value as well!
update(`peoples*[id=1][age>=20]`, (x) => ({...x, updated: true }), object);
// { peoples: [{ id: 1, age: 20, updated: true }, { id: 1, age: 30, updated: true }] }


// You can build pipelines since get, update functions are curried by default
const englishUpdaterPipeline = _.flow([
    get(`[lang="en"]`),
    update('isEnglish', true)
]);

englishUpdaterPipeline([{ lang: 'en' }, { lang: 'ar' }]); // { lang: 'en', isEnglish: true }

Install

npm i golden-path

Supports:

• First match queries and updates.
• Greedy (All matches) queries and updates.
• Queries in all levels.
• Multiple queries on the same array items.
• Sanitization for server dynamic values (in order to not break the parser by any symbols).
• Comparator operators: = > < >= <= !=

golden-path's Issues

Add *Next methods

Add *Next methods that apply this logic on the next instance to enable the option to iterate read/writes.

Like

const l = [{a:1}, {a:1}]
getNext('[a=1]', l) // first obj
getNext('[a=1]', l) // second obj

Move Ramda from devDeps to deps

Use Rollup instead of Webpack to produce ES Modules export

Worth trying...

Assets

Multi properties pick feature

Replace eval

Support greedy with no conditions

update('*.name', 'name for everyone', array)

lint rule for using v()

Use shallowequal to prevent extra re-renders

Ref -> https://github.com/dashed/shallowequal

This is a continuous effort of #9

Add function specific docs to readme