Sift-Shorthand

An expansion library for Sift which supports a human readable and CLI compatible syntax.

var shorthand = require('sift-shorthand');

// Parse {a: 1} in a variety of ways
shorthand('a=1') // Key/val setting
shorthand(['a=1']) // Key/val setting within an array
shorthand('{"a":1}') // JSON
shorthand('{a:1}') // HanSON


// Parse various types of input
siftShorthand(
	'a=1', // Strings are fine
	['b=2', '{"c":3}'], // Array input with nested types (string + JSON)
	{d: 4}, // Also objects
	{'e.f': 5}, // Also dotted notation nested objects
	'{g: 6}', // Also HanSON format
) //= {a: 1, b: 2, c: 3, d: 4, e: {f: 5}, g: 7}

See the testkits for more advanced examples.

Supported Syntax Types

The main API supports simple string, CSV, arrays and a variety of other input types. The below is a quick-reference table for the compatible inputs.

| Name | Type | Example input | Sift Equivalent | Description | |---------------------|-----------|---------------------|-----------------------------|-----------------------------------------------------------------| | key=val | String | foo=bar | {foo: "bar"} | Simple key/value assignment | | key==val | | foo==bar | {foo: "bar"} | Simple key/value assignment, alternative syntax | | key!=vak | | foo!=bar | {foo: ${ne: "bar"}} | Negation syntax | | key | Boolean | foo | {foo: true} | Simple boolean flag | | !key | | !foo | {foo: false} | Simple negation boolean flag | | key? | | foo? | {foo: {$exists: true}} | Checks for the existance of a key within a document | | key!? | | foo!? | {foo: {$exists: false}} | Checks for the non-existance of a key within a document | | key<number | Number | foo<123 | {foo: {$lt: 123}} | Number is-less-than | | key<=number | | foo<=123 | {foo: {$lte: 123}} | Number is-less-or-equal-to | | key>number | | foo>123 | {foo: {$gt: 123}} | Number is-greater-than | | key>=number | | foo>=123 | {foo: {$gte: 123}} | Number is-greater-or-equal-to | | key~=RE | RegEx | foo!=o | {foo: {$regex: 'o'}} | Simple search-anywhere Regular Expression syntax | | key/=RE | | foo/=o | {foo: {$regex: 'o'}} | Simple search-anywhere Regular Expression syntax, alt syntax | | key^=val | | foo^=bar | {foo: {$regex: '^bar'}} | String begins-with | | key$=val | | foo$=val | {foo: {$regex: 'bar$'}} | String ends-with | | key[]=val | Array | foo[]=bar | {foo: {$in: 'bar'}} | Checks whether the given value exists within an array | | key![]=val | | foo[]=bar | {foo: {$nin: 'bar'}} | Checks whether the given value does not exist within an array | | key#=val | | foo#=3 | {foo: {$size: 1}} | Checks that an array is an exact length | | key#>val | | foo>4 | See notes | Checks that an array is larger than a given length | | key#>=val | | foo>=5 | See notes | Checks that an array is larger or equal to a given length | | key===null | Types | foo===null | {foo: null} | Checks against the null type | | key===undefined | | foo===undefined | {foo: undefined} | Checks against the undefined type |

Notes:

• All fields work with dotted notation and will be expanded in the output. For example foo.bar.baz=123 becomes {foo: {bar: {baz: 123}}}
• HanSON is used by default to decode entries that look like JSON
• Mongo / Sift do not have native methods of measuring the size of arrays so the horrible {field.number: {$exists: true} method is used instead
• Checking for array size-less than is not possible using the above, so field#<size or field#<= are not available
• For array functions ([]= / ![]=) separate multiple values with pipes (i.e. |, spaces are optional). Pipes are used to distinguish from the CSV input style of key=value blocks

API

siftShorthand(args..., settings)

Parse one or more strings, arrays, objects etc. into a single Sift compatible output query.

siftShorthand.defaults

Object containing the default values used in the main siftShorthand() function.

| Setting | Type | Default | Description | |-----------------------------|------------------|-------------------------|-------------------------------------------------------------------------| | throw | boolean | true | Whether to throw an error when input JSON / HanSON is invalid | | merge | function | shorthand.mergeDotted | The default merge method to use | | mergeJSON | function | undefined | Method used to merge JSON data specifically (set to Object.assign to keep dotted notation | | mergeString | function | undefined | Method used to merge string assignments specifically | | hanson | boolean | true | Whether to enable HanSON decoding (slower but easier to use than JSON) | | isJSON | RegExp | See code | How to determine if an argument is JSON / HanSON | | stringAssignmentGuessType | boolean | true | Try to guess and correct the incoming input type for string assignments | | stringAssignments | array <Object> | See code | Rules used to assign string assignment tuples | | stringSplit | RegExp | See code | How to split a string of tuples | | arraySplit | function | See code | How to split array-like values ([]= and ![]=) |

siftShorthand.values(args..., settings)

A minimal version of siftShorthand that only processes direct-set values such as foo=1, bar (which is true), !baz (which is false).

siftShorthand('foo=1') //= {foo: 1}
siftShorthand('foo=1,bar=2') //= {foo: 1, bar:2}
siftShorthand('foo') //= {foo: true}
siftShorthand('!foo') //= {foo: false}

siftShorthand.mergeDotted(subject, args...)

Merge additional objects deeply into the subject. This function is similar to Lodash's _.merge() function except that dotted notation is supoprted.

siftShorthand.guessType(input)

Attempt to identify and allocated the value type based on context. This function tries to determine if a string value is finite (in which case it assumes a Number type) etc.