0.0.8 • Published 7 years ago
sift-shorthand v0.0.8
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=123becomes{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#<sizeorfield#<=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 ofkey=valueblocks
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.