ANNOUCEMENT: repository changing ownership

This repository has changed ownership to the personal account of one of it's maintainers, Yaniv Kessler

Ownership change will also occur on the npm registry to Yaniv Kessler

pickpick-targeting-compiler

compiles targeting expressions to javascript code for pickpick engine

• uses jsep to parse expressions and turn them into a javascript function that evaluates a conditiongiven a certain input.
• uses the vm module to have isolated context
• in addition to normal javascript operators, there are some special operators (see below for example):
  • in is exactly Array.includes
  • match regexp test
  • startsWith and endsWith is exactly String.startsWith and String.endsWith respectively
• exposes a bunch of useful is* functions from util module
• open for extension via user defined envinronment accessible using $

example

npm i pickpick-targeting-compiler

const assert = require('assert')
const compile = require('pickpick-targeting-compiler')

// intentionally using var here 

// all normal js operators apply
var { isMatch, features } = compile('_.geo === "US"')
assert(isMatch({ geo: 'US' }))

var { isMatch, features } = compile('_.number >= 0')
assert(isMatch({ number: 1 }))
assert(isMatch({ number: 2 }))
assert(isMatch({ number: 3 }))

// can create compound logical statements
var { isMatch, features } = compile('_.geo === "US" && _.number > 5')
assert(isMatch({ geo: 'US', number: 8 }))

// in operator - same as Array.includes(value)
var { isMatch, features } = compile('_.geo in ["US", "MX"]')
assert(isMatch({ geo: 'US' }))

// operators apply to context data as well
var { isMatch, features } = compile('_.geo in _.page')
assert(isMatch({ geo: 'US', page: ["US", "MX"] }))

// startsWith operator - same as String.startsWith(string)
var { isMatch, features } = compile('_.geo startsWith "x"')
assert(isMatch({ geo: 'xyz' }))

// endsWith operator - same as String.endsWith(string)
var { isMatch, features } = compile('_.geo endsWith "z"')
assert(isMatch({ geo: 'xyz' }))

// match operator for literal regular expressions, same as /regex/g.test('value')
var { isMatch, features } = compile('_.geo match "[0-9]"')
assert(isMatch({ geo: 0 }))

// deeplyEquals operator performs a deep equal comparison (uses [lodash.isEqual](https://lodash.com/docs/4.17.10#isEqual))
var { isMatch, features } = compile('_.geo deeplyEquals [1, 2, 3]')
assert(isMatch({ geo: [1, 2, 3] }))

// exposes a bunch of isSomething from util:
// isNullOrUndefined,
// isNull,
// isUndefined,
// isString,
// isNumber,
// isArray,
// isObject,
// isBoolean,
// isDate,
// isNull,
// isPrimitive
var { isMatch, features } = compile('isNumber(_.geo)')
assert(isMatch({ geo: 0 }))

// provide user defined functions and data
const userEnvironment = { x: [1, 2, 3], isOk: (arg) => arg.startsWith('x') }
var { isMatch, features } = compile('_.geo in $.x && $.isOk(_.page)', { userEnvironment })
assert(isMatch({ geo: 1, page: 'x.html' }))

api

Table of Contents

• compile

compile

index.js:56-156

Compile an expression into a resuable javascript function

Parameters

• expression String any expression that can be parsed by jsep
• options Object (optional, default {})
  • options.matcherProperty String return the match function using a different property name in the compound return value, e.g: (optional, default 'isMatch')
  • options.userEnvironment Object allows the user to inject additional functionality that will be exposed to the expression. e.g: (optional, default {})
  • options.userEnvNamespace String change the name used to access user environment in an expression (optional, default $)
  • options.inputNamespace String change the name used to access input in the expression (optional, default _)

Examples

// options.matcherProperty
 
   // normally this would be isMatch instead of 'foo'
   let { foo } = compile('_.geo === "1"', { matcherProperty: 'foo' })

// options.userEnvironment
   
   let userEnvironment = {
 	    geos: ['MX', 'US', 'IL'],
  	    format: value => value.toUpperCase()
   }
   
   let { isMatch } = compile('$.format(_.geo) in $.geos', { userEnvironment })

Returns Function a function that accepts input and returns a boolean value

license

MIT © ironSource LTD