playlist-rule-engine

Rule engine for playlist playback.

Development

yarn install
yarn build

Testing

yarn test

Deployment

yarn deploy

Usage

Install:

npm install playlist-rule-engine

Usage:

import { RuleEngine, State } from 'playlist-rule-engine';
// See below for documentation on these data objects.
const playlists = {...};
const presentations = {...};
const dynamicState = {...};

const state = new State(playlists, presentations, dynamicState);
const ruleEngine = new RuleEngine('<playlistId>', state);

// Get the next item to play.
ruleEngine.next();

// Preview the next item in the queue.
ruleEngine.previewNext();

// See the results of rule evaluation.
ruleEngine.simulateNormalPlayback();

// Example usage
while(true) {
    const now = ruleEngine.next();
    const buffer = ruleEngine.previewNext();

    // The results of calling .next and .previewNext()
    // can then be consumed by application logic.
    // Examples assume custom play() and preload()
    // functions defined elsewhere.
    play(now);
    preload(buffer);

    await sleep(10000);
}
function sleep(ms) {
    return new Promise(resolve => setTimeout(resolve, ms));
}

Data Structures

Playlists

{
    <playlistId>: {
        mode: 'sequential|shuffle|single|hold',
        items: [
            { 'presentationId': '<presentationId>' },
            { 'playlistId': '<nestedPlaylistId' },
        ],
        rule: <Rule> (optional),
        tags: {...} (optional),
    },
    ...
}

Presentations

{
    <presentationId>: {
        name: string,
        tags: {...} (optional),
    },
    ...
}

Dynamic State

An arbitrary flat object with keys/values. No nested objects.

{
    key: 'value',
    foo: 'bar',
    ...
}

Rules

Key-value match against either the tags on item in the playlist, or tags on the playlist itself.

tag_match

{
    type: 'tag_match',
    value: {
        applies_to: 'item|playlist',
        match: {
            <tagKey>: <tagValue>,
        }
    },
}

state_match

Key-value match against the dynamicState object passed into the RuleEngine instance.

{
    type: 'state_match',
    value: {
        <stateKey>: <stateValue>,
    },
}

and

Evaluates all rules in values and returns true if all rules evaluate to true.

{
    type: 'and',
    values: [
        <Rule>,
        <Rule>,
        ...
    ],
}

or

Evaluates all rules in values and returns true if one or more rules evaluate to true.

{
    type: 'or',
    values: [
        <Rule>,
        <Rule>,
        ...
    ],
}

Simulated Playback

RuleEngine.simulateNormalPlayback() is used to simulate and inspect rule evaluation results for a RuleEngine instance. It will return an object with the following properties:

{
    // The rule used by the playlist assigned to the rule engine.
    rule: <Rule>,
    result: {
        // Presentation items:
        {
            tags: {...},
            presentationId: string,
            willPlay: true|false
        },
        // Playlist items:
        {
            tags: {...},
            playlistId: string,
            willPlay: true|false,
            // Will include the SimulatedPlayback object for the
            // nested playlist if willPlay evaluates to true.
            playlist: <SimulatedPlayback>,
        },
        ...
    }
}