@quantform/core 0.3.228 → 0.3.232

package/src/index.ts

@@ -1,17 +1,12 @@
-export * from './behaviour';
-export * from './common';
-
+export * from './shared';
 export * from './domain';
-
 export * from './adapter';
 export * from './adapter/backtester';
 export * from './adapter/paper';
-
 export * from './indicator';
 export * from './session';
 export * from './storage';
-
 export * from './store';
 export * from './store/event';
-
 export * from './bin';
+export * from './ipc';

package/src/indicator/truerange.spec.ts

@@ -2,7 +2,7 @@ import { from } from 'rxjs';
 import { Candle } from '../domain';
 import { truerange } from './truerange';
 import { sma } from './sma';
-import { now } from '../common';
+import { now } from '../shared';
 
 describe('truerange atr tests', () => {
   test('should return expected value', done => {

package/src/ipc.ts

@@ -0,0 +1,277 @@
+import { AdapterFeedCommand } from './adapter';
+import { Session, SessionDescriptor } from './session';
+import { instrumentOf } from './domain';
+import { Topic, event, handler } from './shared/topic';
+import { Logger } from './shared';
+import { backtest, idle, live, paper } from './bin';
+import minimist = require('minimist');
+
+/**
+ * Base command/query interface for IPC communication.
+ */
+export interface IpcCommand {
+  /**
+   * The command name to handle.
+   */
+  type;
+}
+
+/**
+ * Command to start a new live session.
+ */
+@event
+export class IpcLiveCommand implements IpcCommand {
+  type = 'live';
+
+  /**
+   * The optional session identifier.
+   */
+  id?: number;
+}
+
+/**
+ * Command to start a new paper session.
+ */
+@event
+export class IpcPaperCommand implements IpcCommand {
+  type = 'paper';
+
+  /**
+   * The optional session identifier.
+   */
+  id?: number;
+
+  /**
+   * Specifies trading balance, for example:
+   * { "binance:usdt": 1000 }
+   */
+  balance: { [key: string]: number };
+}
+
+/**
+ * Command to start a new backtest session.
+ */
+@event
+export class IpcBacktestCommand implements IpcCommand {
+  type = 'backtest';
+
+  /**
+   * Start date of the backtest in unix timestamp.
+   */
+  from: number;
+
+  /**
+   * Due date of the backtest in unix timestamp.
+   */
+  to: number;
+
+  /**
+   * Specifies trading balance, for example:
+   * { "binance:usdt": 1000 }
+   */
+  balance: { [key: string]: number };
+}
+
+@event
+export class IpcUniverseQuery implements IpcCommand {
+  type = 'universe';
+  exchange: string;
+}
+
+/**
+ * Feeds specific session descriptor with instrument data.
+ */
+@event
+export class IpcFeedCommand implements IpcCommand {
+  type = 'feed';
+
+  /**
+   * Instrument to feed.
+   */
+  instrument: string;
+
+  /**
+   * Start date of the feed in unix timestamp.
+   */
+  from: number;
+
+  /**
+   * Due date of the feed in unix timestamp.
+   */
+  to: number;
+}
+
+/**
+ * Stores current session instance.
+ */
+class IpcSessionAccessor {
+  session: Session;
+}
+
+/**
+ * Inter process communication handler.
+ */
+class IpcHandler extends Topic<{ type: string }, IpcSessionAccessor> {
+  constructor(private readonly descriptor: SessionDescriptor) {
+    super();
+  }
+
+  /**
+   * @see IpcLiveCommand
+   */
+  @handler(IpcLiveCommand)
+  async onLiveMode(command: IpcLiveCommand, accessor: IpcSessionAccessor) {
+    if (command.id) {
+      this.descriptor.id = command.id;
+    }
+
+    accessor.session = live(this.descriptor);
+
+    await accessor.session.awake();
+  }
+
+  /**
+   * @see IpcPaperCommand
+   */
+  @handler(IpcPaperCommand)
+  async onPaperMode(command: IpcPaperCommand, accessor: IpcSessionAccessor) {
+    if (command.id) {
+      this.descriptor.id = command.id;
+    }
+
+    accessor.session = paper(this.descriptor, {
+      balance: command.balance
+    });
+
+    await accessor.session.awake();
+  }
+
+  /**
+   * @see IpcBacktestCommand
+   */
+  @handler(IpcBacktestCommand)
+  onBacktestMode(command: IpcBacktestCommand, accessor: IpcSessionAccessor) {
+    return new Promise<void>(async resolve => {
+      const [session, streamer] = backtest(this.descriptor, {
+        from: command.from,
+        to: command.to,
+        balance: command.balance,
+        progress: timestamp =>
+          this.notify({
+            type: 'backtest:updated',
+            timestamp,
+            from: command.from,
+            to: command.to
+          }),
+        completed: async () => {
+          const statement = {};
+
+          await accessor.session.dispose();
+
+          this.notify({ type: 'backtest:completed', statement });
+
+          resolve();
+        }
+      });
+
+      accessor.session = session;
+
+      this.notify({ type: 'backtest:started' });
+
+      await accessor.session.awake();
+      await streamer.tryContinue().catch(it => Logger.error(it));
+    });
+  }
+
+  /**
+   * @see IpcUniverseQuery
+   */
+  @handler(IpcUniverseQuery)
+  onUniverse(query: IpcUniverseQuery, accessor: IpcSessionAccessor) {
+    accessor.session = accessor.session ?? idle(this.descriptor);
+  }
+
+  /**
+   * @see IpcFeedCommand
+   */
+  @handler(IpcFeedCommand)
+  async onFeed(command: IpcFeedCommand, accessor: IpcSessionAccessor) {
+    accessor.session = accessor.session ?? idle(this.descriptor);
+    const instrument = instrumentOf(command.instrument);
+
+    await accessor.session.awake();
+
+    this.notify({ type: 'feed:started' });
+
+    await accessor.session.aggregate.dispatch(
+      instrument.base.exchange,
+      new AdapterFeedCommand(
+        instrument,
+        command.from,
+        command.to,
+        this.descriptor.feed,
+        timestamp =>
+          this.notify({
+            type: 'feed:updated',
+            timestamp,
+            from: command.from,
+            to: command.to
+          })
+      )
+    );
+
+    this.notify({ type: 'feed:completed' });
+
+    await accessor.session.dispose();
+  }
+
+  /**
+   * Sends a message to parent process.
+   */
+  private notify(message: any) {
+    if (!process.send) {
+      return;
+    }
+
+    process.send(message);
+  }
+}
+
+/**
+ * Starts new managed session and subscribes to parent process messages.
+ * @param descriptor session descriptor.
+ * @param commands collection of commands to execute before session is started.
+ * @returns new session.
+ */
+export async function run(
+  descriptor: SessionDescriptor,
+  ...commands: IpcCommand[]
+): Promise<Session> {
+  const handler = new IpcHandler(descriptor);
+  const accessor = new IpcSessionAccessor();
+  const argv = minimist(process.argv.slice(2));
+
+  if (argv.command) {
+    const json = Buffer.from(argv.command, 'base64').toString('utf-8');
+
+    commands.push(JSON.parse(json));
+  } else {
+    if (!commands.length) {
+      commands.push(new IpcPaperCommand());
+    }
+  }
+
+  for (const command of commands) {
+    await handler.dispatch(command, accessor);
+  }
+
+  process.on('message', async (request: any) => {
+    const response = await handler.dispatch(request, accessor);
+
+    if (response) {
+      process.send(response);
+    }
+  });
+
+  return accessor.session;
+}

package/src/session/index.ts

@@ -1,3 +1,4 @@
 export * from './session';
 export * from './session-descriptor';
 export * from './session-optimizer';
+export * from './session-statement';

package/src/session/session-descriptor.ts

@@ -2,20 +2,49 @@ import { Adapter } from '../adapter';
 import { Session } from '.';
 import { Measurement } from '../storage/measurement';
 import { Feed } from '../storage';
-import { Behaviour } from '../behaviour';
 import { Observable } from 'rxjs';
 
+/**
+ * Describes a single session.
+ * You can use @run function to start a new session managed by CLI.
+ * To start managed session you should install @quantform/cli package and run
+ * specific command:
+ *  - qf paper (to paper trade strategy)
+ *  - qf backtest (to backtest strategy based on provided feed)
+ *  - qf live (to live trade strategy)
+ * or run on your own in code:
+ *  - paper(descriptor, options)
+ *  - backtest(descriptor, options)
+ *  - live(descriptor)
+ */
 export interface SessionDescriptor {
-  id: number;
+  /**
+   * Unique session identifier, used to identify session in the storage.
+   * You can generate new id every time you start the new session or provide
+   * session id explicitly to resume previous session (in code or via CLI).
+   * If you don't provide session id, it will generate new one based on time.
+   */
+  id?: number;
 
-  // provides trading adapters.
+  /**
+   * Collection of adapters used to connect to the exchanges.
+   */
   adapter: Adapter[];
 
-  // provides input and output feed for backtesting purposes.
+  /**
+   * Provides historical data for backtest, it's not required for live and paper
+   * sessions.
+   */
   feed?: Feed;
 
-  // defines measurement storage.
+  /**
+   * Stores session variables i.e. indicators, orders, or any other type of time
+   * series data. You can install @quantform/editor to render this data in your browser.
+   */
   measurement?: Measurement;
 
-  behaviour?: Behaviour | Behaviour[] | ((session: Session) => Observable<any>);
+  /**
+   * Describes your trading strategy.
+   */
+  describe?: (session: Session) => Observable<any>;
 }

package/src/session/session-statement.ts

@@ -0,0 +1,119 @@
+import { Session } from '.';
+import { InstrumentSelector } from '../domain';
+import { combineLatest, finalize, map, take, tap } from 'rxjs';
+import { drawdown } from '../indicator';
+import { floor, precision } from '../shared';
+
+export function period() {
+  return (session: Session) => {
+    const period = session.useStatement('period');
+
+    return session.store.changes$.pipe(
+      finalize(() => (period.to = new Date(session.timestamp).toISOString())),
+      take(1),
+      tap(it => (period.from = new Date(it.timestamp).toISOString()))
+    );
+  };
+}
+
+export function benchmark(instrument: InstrumentSelector) {
+  return (session: Session) => {
+    const statement = session.useStatement('benchmark');
+
+    let balance: number, entry: number, exit: number;
+    let dd = 0;
+
+    return combineLatest([
+      session.orderbook(instrument),
+      session.balance(instrument.quote),
+      session.orderbook(instrument).pipe(
+        drawdown(it => it.midRate),
+        tap(it => (dd = it))
+      )
+    ]).pipe(
+      map(([orderbook, quote]) => {
+        const price = orderbook.midRate;
+
+        if (!balance) {
+          balance = quote.total;
+        }
+
+        if (!entry) {
+          entry = price;
+        }
+
+        exit = price;
+      }),
+      finalize(() => {
+        const pnl = exit / entry - 1;
+
+        statement['benchmark_entry'] = entry;
+        statement['benchmark_exit'] = exit;
+        statement['benchmark_pnl'] = floor(balance * pnl, precision(entry));
+        statement['benchmark_pnl_pp'] = floor(pnl * 100, 2);
+        statement['benchmark_drawdown_pp'] = floor(dd * 100, 2);
+      })
+    );
+  };
+}
+
+export function equity(instrument: InstrumentSelector) {
+  return (session: Session) => {
+    const statement = session.useStatement('benchmark');
+
+    let balance: number, min: number, max: number;
+    let dd = 0;
+    let equity = 0;
+
+    return combineLatest([
+      session.orderbook(instrument),
+      session.balance(instrument.base),
+      session.balance(instrument.quote),
+      session.positions(instrument)
+    ]).pipe(
+      tap(([, , quote]) => {
+        if (!balance) {
+          balance = quote.total;
+        }
+      }),
+      map(([orderbook, base, quote, positions]) =>
+        orderbook.instrument.quote.fixed(
+          quote.total +
+            base.total * orderbook.bestBidRate +
+            positions.reduce(
+              (agg, position) => agg + position.calculatePnL(orderbook.bestBidRate),
+              0
+            )
+        )
+      ),
+      tap(it => {
+        if (!min) {
+          min = it;
+        } else {
+          min = Math.min(min, it);
+        }
+
+        if (!max) {
+          max = it;
+        } else {
+          max = Math.max(max, it);
+        }
+
+        equity = it;
+      }),
+      drawdown(it => it),
+      tap(it => (dd = it)),
+      finalize(() => {
+        const pnl = equity / balance - 1;
+        const scale = precision(equity);
+
+        statement['equity'] = equity;
+        statement['equity_min'] = min;
+        statement['equity_max'] = max;
+        statement['equity_pnl'] = floor(balance * pnl, scale);
+        statement['equity_pnl_pp'] = floor(pnl * 100, 2);
+        statement['equity_drawdown_pp'] = floor(dd * 100, 2);
+      })
+    );
+  };
+}

package/src/session/session.spec.ts

@@ -1,8 +1,10 @@
 import { InstrumentPatchEvent } from '../store/event';
-import { Asset, Commision } from '../domain';
-import { now } from '../common';
+import { Asset, Commission } from '../domain';
+import { now } from '../shared';
 import { SessionDescriptor } from './session-descriptor';
 import { paper } from '../bin';
+import { Session } from './session';
+import { of } from 'rxjs';
 
 describe('session tests', () => {
   const descriptor: SessionDescriptor = {
@@ -29,14 +31,14 @@ describe('session tests', () => {
         now(),
         new Asset('de30', 'cex', 2),
         new Asset('usd', 'cex', 2),
-        new Commision(0, 0),
+        new Commission(0, 0),
         ''
       ),
       new InstrumentPatchEvent(
         now(),
         new Asset('wig20', 'cex', 2),
         new Asset('pln', 'cex', 2),
-        new Commision(0, 0),
+        new Commission(0, 0),
         ''
       )
     );

package/src/session/session.ts

@@ -22,9 +22,8 @@ import {
 } from '../domain';
 import { Store } from '../store';
 import { concat, from, Observable, Subject, Subscription } from 'rxjs';
-import { Behaviour, CombinedBehaviour, FunctionBehaviour } from '../behaviour';
 import { AdapterAggregate } from '../adapter/adapter-aggregate';
-import { Worker } from '../common';
+import { Worker, now } from '../shared';
 import { Trade } from '../domain/trade';
 import { SessionDescriptor } from './session-descriptor';
 import {
@@ -39,18 +38,24 @@ type Optional<T, K extends keyof T> = Omit<T, K> & Partial<T>;
 export class Session {
   private initialized = false;
   private subscription: Subscription;
-  private behaviour: Behaviour;
   private worker = new Worker();
 
   get timestamp(): number {
     return this.store.snapshot.timestamp;
   }
 
+  readonly statement: Record<string, Record<string, any>> = {};
+
   constructor(
     readonly store: Store,
     readonly aggregate: AdapterAggregate,
     readonly descriptor?: SessionDescriptor
-  ) {}
+  ) {
+    // generate session id based on time if not provided.
+    if (descriptor && !descriptor.id) {
+      descriptor.id = now();
+    }
+  }
 
   async awake(): Promise<void> {
     if (this.initialized) {
@@ -59,18 +64,11 @@ export class Session {
 
     this.initialized = true;
 
+    // awake all adapters and synchronize trading accounts with store.
     await this.aggregate.awake(this.descriptor != null);
 
-    if (this.descriptor?.behaviour) {
-      if (this.descriptor.behaviour instanceof Function) {
-        this.behaviour = new FunctionBehaviour(this.descriptor.behaviour);
-      } else {
-        this.behaviour = Array.isArray(this.descriptor.behaviour)
-          ? new CombinedBehaviour(this.descriptor.behaviour)
-          : this.descriptor.behaviour;
-      }
-
-      this.subscription = this.behaviour.describe(this).subscribe();
+    if (this.descriptor.describe) {
+      this.subscription = this.descriptor.describe(this).subscribe();
     }
   }
 
@@ -89,14 +87,20 @@ export class Session {
     await this.worker.wait();
   }
 
-  statement(output: Record<string, any>) {
-    if (!this.behaviour?.statement) {
-      return;
-    }
-
-    this.behaviour.statement(output);
+  useStatement(section: string): Record<string, any> {
+    return this.statement[section] ?? (this.statement[section] = {});
   }
 
+  /**
+   * Returns last stored measurement and setter for it in session.
+   * For example you can save and restore variables in same session between runs.
+   * Example usage:
+   * const [order$, setOrder] = session.measurement<Order>('order');
+   *
+   * order.pipe(tap(it => console.log(`your last order was: ${it}`)));
+   *
+   * setOrder(order);
+   */
   useMeasure<T extends { timestamp: number }>(
     params: { kind: string; timestamp?: number },
     defaultValue: T = undefined
@@ -130,10 +134,19 @@ export class Session {
     return [concat(stored$, subject$.asObservable()), setter];
   }
 
+  /**
+   * Return values for patch provided in optimization file.
+   * Example usage:
+   * const orderSize = session.useOptimizer('order.size');
+   */
   useOptimizer(path: string): any {
     return undefined;
   }
 
+  /**
+   * Subscribes to specific instrument. Usually forces adapter to subscribe
+   * for orderbook and ticker streams.
+   */
   async subscribe(instrument: Array<InstrumentSelector>): Promise<void> {
     const grouped = instrument
       .filter(it => it != null)
@@ -154,6 +167,11 @@ export class Session {
     }
   }
 
+  /**
+   * Opens collection of orders.
+   * Example:
+   * session.open(Order.buyMarket(instrument, 100));
+   */
   async open(...orders: Order[]): Promise<void> {
     await Promise.all(
       orders.map(it =>
@@ -165,6 +183,9 @@ export class Session {
     );
   }
 
+  /**
+   * Cancels specific order.
+   */
   cancel(order: Order): Promise<void> {
     return this.aggregate.dispatch(
       order.instrument.base.exchange,
@@ -172,6 +193,10 @@ export class Session {
     );
   }
 
+  /**
+   * Subscribes to specific instrument changes.
+   * When adapter awake then it will fetch collection of all available instruments.
+   */
   instrument(selector: InstrumentSelector): Observable<Instrument> {
     this.subscribe([selector]);
 
@@ -181,6 +206,10 @@ export class Session {
     );
   }
 
+  /**
+   * Subscribes to instruments changes.
+   * When adapter awake then it will fetch collection of all available instruments.
+   */
   instruments(): Observable<Instrument[]> {
     return this.store.changes$.pipe(
       filter(it => it instanceof Instrument),
@@ -191,6 +220,9 @@ export class Session {
     );
   }
 
+  /**
+   * Subscribes to trade/ticker changes.
+   */
   trade(selector?: InstrumentSelector): Observable<Trade> {
     this.subscribe([selector]);
 
@@ -204,6 +236,10 @@ export class Session {
     );
   }
 
+  /**
+   * Subscribes to orderbook changes.
+   * Right now you can access only best bid and best ask.
+   */
   orderbook(selector?: InstrumentSelector): Observable<Orderbook> {
     this.subscribe([selector]);
 
@@ -217,6 +253,9 @@ export class Session {
     );
   }
 
+  /**
+   * Subscribes to position on leveraged market.
+   */
   position(selector?: InstrumentSelector): Observable<Position> {
     this.subscribe([selector]);
 
@@ -230,6 +269,9 @@ export class Session {
     );
   }
 
+  /**
+   * Subscribes to positions on leveraged markets.
+   */
   positions(selector: InstrumentSelector): Observable<Position[]> {
     this.subscribe([selector]);