rec-framework/rec-framework.github.io

Rec Framework project site

rec-framework.github.io's Issues

API

Rec JavaScript API

• TOC
  {:toc}

Rec using a updated version Rhino as JavaScript engine, it support
several ES6 features to help you for better development experience.

Interface definitions

Interface definitions is under src/main/resources directory of Rec source code.

Rec-v2.d.ts

interface Record {
    get(value: string): string;
    keys(): string[];
}
// Same to Java 8 Stream
interface Stream {
}

interface Source {
    tee(tee: Tee): Source;
    to(target: Target);
    filter(predicate: WrappedPredicate<Record>): Source
}

interface Target {
    tee(tee: Tee): Target;
}

interface Tee {
    source(): Source;
}

interface Rec {
    pred<T>(pred: (any: T) => boolean): WrappedPredicate<T>;
    action<T>(func: (any: T) => void): WrappedAction<T>;
    println(...args: any[]);

    csv(source: string, format: string): Source;
    stream(stream: Stream): Source;

    target(func: (record: Record) => void): Target;
    flat(file: string): Target;
    dummy(): Target;

    counter(condition: (Record) => boolean): ItemCounterTee;
    unique(...fields: string[]): Tee;

    stateless(func: (record: Record) => void): Tee;
    stateful<T>(state: T, reducer: (record: Record, state: T) => T): StatefulTee<T>;

    cache(size: number): Tee;
    collect<T>(collection: T): CollectTee<T>;
}

interface StatefulTee<T> extends Tee {
    state: T
}

interface ItemCounterTee extends Tee {
    count: number;
}

interface CollectTee<T> extends Tee {
    collect(): T;
}

interface WrappedPredicate<T> {
    test(value: T): boolean
}

interface WrappedAction<T> {
    apply(value: T): void
}

declare const rec: Rec;

Core concepts

Record

Rec has several core concepts to represent data and related stuff, core idea
is represent each data entry as a Record.

interface Record {
    get(value: string): string;
    keys(): string[];
}

Basically a record is just a string-indexed-value object, which has specific
schema, i.e. the accessor expression, to get the values.

in JavaScript, the records can be accessed as a JavaScript Object, like if
you have a Record contains key name and address, you can just using let
destructive assignment:

let {name, address} = <the record>;

Also a record have the keys method to get all it's accessible keys, and
this can be easily to encode a record using JSON.stringify.

Source, Target and Tee

Other important concepts are the processing components, in Rec, there are
3 different components to support different processing scenarios: the Source,
to obtain data; the Target, to save/transfer data; and Tee, to add processor
in middle.

Source

Source is the component to obtain data, e.g. a CSV file, or a server socket.

A source can be generated from a Rec method, or generated by a existing source
object. Once it is generated, the existing source is considered as parent of
the new one, and new one considered as child of existing one.

It is important to understand that a source is not reentrant, once you direct
a source to a target, neither it's child source or parent source is no longer
valid. And this invalid status is related, meaning, if it's child is
invalid, the parent should also be invalid, or vice versa.

Each source have 3 different methods:

Source#to(target: Target)

Direct the source to a specific target, either it is a blocking process to put
all data to the target, or it is a non-blocking process to reactively call the
target when the source got data.

Source#tee(tee: Tee): Source

Attach a tee to a source, this will create a new source, which is lazy / reactive
based on the implementation of source.

Source#filter(predicate: WrappedPredicate<Record>): Source

Attach a filter to a source, this will using a predicate, as this is a plain Java
method, so you need call Rec#pred method first to wrap a JavaScript predicate
function.

This method will create a new source.

Target

A target represents the destination of data, e.g. a consumer function, or a database
connection (to save the data).

A target can be reused many time, and can attach a tee.

Target#tee(tee: Tee): Target

Target#tee will create a new Target object, but the previous object is still available
to use.

Tee

Tee is to represent the process in-middle of data aquiring and saving, like a T joint
pipe (and that's the origin of it's name), e.g., saving the intermediate result, or
do some aggregating/validating process.

A tee can be easily convert to a source if it contains aggregated data.

Guide

Best Practices