# Journal (/vela-pro/api/journal)



This page documents `@luxalgo/vela-pro-journal`, including the `journal()` plugin factory, `JournalController`, the journal storage port, panel and full-screen journal widgets, and trade reconstruction and analytics functions.

Import symbols on this page from `@luxalgo/vela-pro-journal`. Related guides: [Journal](/vela-pro/modules/catalog/journal), [Standalone widgets](/vela-pro/modules/widgets).

## Functions [#functions]

### `breakdown` [#breakdown]

```typescript
function breakdown(trades: readonly JournalTrade[], timeZone: string): Breakdown
```

See also: [`Breakdown`](/vela-pro/api/journal#breakdown-interface), [`JournalTrade`](/vela-pro/api/journal#journaltrade).

### `buildTrades` [#buildtrades]

Group the effective fills by account and symbol and walk them in time: same-side fills add to the position, opposite fills close it (lots matched FIFO, LIFO or at the average), and a fill that goes past flat closes the trade and opens the next one the other way.

```typescript
function buildTrades(
    fills: readonly JournalFill[],
    methodOf?: (accountId: string) => ProfitMethod,
    annotations?: Record<string, TradeAnnotation>,
): JournalTrade[]
```

Default: `methodOf = () => 'fifo'`.

See also: [`JournalFill`](/vela-pro/api/journal#journalfill), [`JournalTrade`](/vela-pro/api/journal#journaltrade), [`ProfitMethod`](/vela-pro/api/journal#profitmethod), [`TradeAnnotation`](/vela-pro/api/journal#tradeannotation).

### `calendarMonth` [#calendarmonth]

```typescript
function calendarMonth(year: number, month: number, days: readonly DayStats[]): CalendarMonth
```

See also: [`CalendarMonth`](/vela-pro/api/journal#calendarmonth-interface), [`DayStats`](/vela-pro/api/journal#daystats-interface).

### `computeMetrics` [#computemetrics]

```typescript
function computeMetrics(
    trades: readonly JournalTrade[],
    timeZone: string,
    initialBalance?: number | null,
): JournalMetrics
```

Default: `initialBalance = null`.

See also: [`JournalMetrics`](/vela-pro/api/journal#journalmetrics), [`JournalTrade`](/vela-pro/api/journal#journaltrade).

### `createJournalPanel` [#createjournalpanel]

The journal panel as a widget: `{ el, tools, update, destroy }`.

```typescript
function createJournalPanel(props: JournalPanelProps): JournalPanelWidget
```

See also: [`JournalPanelProps`](/vela-pro/api/journal#journalpanelprops), [`JournalPanelWidget`](/vela-pro/api/journal#journalpanelwidget).

### `createJournalView` [#createjournalview]

The full journal as a widget: `{ el, open, update, destroy }`.

```typescript
function createJournalView(props: JournalViewProps): JournalViewWidget
```

See also: [`JournalViewProps`](/vela-pro/api/journal#journalviewprops), [`JournalViewWidget`](/vela-pro/api/journal#journalviewwidget).

### `dayKey` [#daykey]

`YYYY-MM-DD` of an instant in `timeZone`.

```typescript
function dayKey(ms: number, timeZone: string): string
```

### `daysBetween` [#daysbetween]

```typescript
function daysBetween(from: string, to: string): number
```

### `dayStats` [#daystats]

```typescript
function dayStats(trades: readonly JournalTrade[], timeZone: string): DayStats[]
```

See also: [`DayStats`](/vela-pro/api/journal#daystats-interface), [`JournalTrade`](/vela-pro/api/journal#journaltrade).

### `drawdownSeries` [#drawdownseries]

How far below its running peak the equity is at each point (0 or less; the peak starts at 0). With a starting balance, a fraction of the equity at the peak: the balance plus the peak P\&L.

```typescript
function drawdownSeries(equity: readonly number[], balance?: number | null): number[]
```

Default: `balance = null`.

### `edgeScore` [#edgescore]

Six components from 0 to 100 and their weighted mean (null below five closed trades).

```typescript
function edgeScore(m: JournalMetrics): EdgeScore
```

See also: [`EdgeScore`](/vela-pro/api/journal#edgescore-interface), [`JournalMetrics`](/vela-pro/api/journal#journalmetrics).

### `emptyJournal` [#emptyjournal]

```typescript
function emptyJournal(): JournalData
```

See also: [`JournalData`](/vela-pro/api/journal#journaldata).

### `enableJournal` [#enablejournal]

Enable the JOURNAL on every shell built afterwards: its side panel (the account, the range's P\&L, the trades and the notes) and the full journal it maximizes into. Returns the page's [`JournalController`](/vela-pro/api/journal#journalcontroller-class). Call ONCE, before constructing shells. Idempotent.

```typescript
function enableJournal(opts?: EnableJournalOptions): JournalController
```

See also: [`EnableJournalOptions`](/vela-pro/api/journal#enablejournaloptions), [`JournalController`](/vela-pro/api/journal#journalcontroller-class).

### `equityCurve` [#equitycurve]

Cumulative net P\&L at each closed trade (`t` its close time).

```typescript
function equityCurve(trades: readonly JournalTrade[]): Array<{ t: number; cum: number }>
```

See also: [`JournalTrade`](/vela-pro/api/journal#journaltrade).

### `headToHead` [#headtohead]

Two performances over the same metrics. An endless profit factor has no value to compare.

```typescript
function headToHead(a: JournalMetrics, b: JournalMetrics): HeadToHeadRow[]
```

See also: [`HeadToHeadRow`](/vela-pro/api/journal#headtoheadrow), [`JournalMetrics`](/vela-pro/api/journal#journalmetrics).

### `journal` [#journal]

The journal as a Vela Pro plugin: it journals the trading plugin's fills.

```typescript
function journal(opts?: EnableJournalOptions): VelaProPlugin<JournalController>
```

See also: [`EnableJournalOptions`](/vela-pro/api/journal#enablejournaloptions), [`JournalController`](/vela-pro/api/journal#journalcontroller-class), [`VelaProPlugin`](/vela-pro/api/module-sdk#velaproplugin).

### `journalController` [#journalcontroller]

The page's journal, once [`enableJournal`](/vela-pro/api/journal#enablejournal) ran.

```typescript
function journalController(): JournalController | null
```

See also: [`JournalController`](/vela-pro/api/journal#journalcontroller-class).

### `metricDeltas` [#metricdeltas]

The dashboard's figures against the previous period. A profit factor without a loss on either side is endless, so it has no change.

```typescript
function metricDeltas(current: JournalMetrics, previous: JournalMetrics | null): MetricDeltas
```

See also: [`JournalMetrics`](/vela-pro/api/journal#journalmetrics), [`MetricDeltas`](/vela-pro/api/journal#metricdeltas-interface).

### `parseList` [#parselist]

Comma-separated words (also full-width and Arabic commas), trimmed and de-duplicated.

```typescript
function parseList(text: string, maxLen?: number): string[]
```

Default: `maxLen = 40`.

### `previousPeriod` [#previousperiod]

The window of the same length right before `range`, summarized (null for all time).

```typescript
function previousPeriod(
    trades: readonly JournalTrade[],
    range: { from: string; to: string } | null,
    timeZone: string,
    today: string,
    initialBalance?: number | null,
): PeriodSummary | null
```

Default: `initialBalance = null`.

See also: [`JournalTrade`](/vela-pro/api/journal#journaltrade), [`PeriodSummary`](/vela-pro/api/journal#periodsummary).

### `previousRange` [#previousrange]

The window of the same length ending the day before (none for `all`).

```typescript
function previousRange(r: { from: string; to: string } | null): { from: string; to: string } | null
```

### `relativeChange` [#relativechange]

`(current − previous) / |previous|`; null without a baseline (no previous value, or zero).

```typescript
function relativeChange(
    current: number | null | undefined,
    previous: number | null | undefined,
): number | null
```

### `resolveRange` [#resolverange]

The days a range covers, ending today; null for `all`.

```typescript
function resolveRange(range: JournalRange, today: string): { from: string; to: string } | null
```

See also: [`JournalRange`](/vela-pro/api/journal#journalrange).

### `riskBehavior` [#riskbehavior]

```typescript
function riskBehavior(m: JournalMetrics): RiskBehavior
```

See also: [`JournalMetrics`](/vela-pro/api/journal#journalmetrics), [`RiskBehavior`](/vela-pro/api/journal#riskbehavior-interface).

### `shiftDay` [#shiftday]

```typescript
function shiftDay(key: string, days: number): string
```

### `startingBalance` [#startingbalance]

What a set of accounts started with: the sum of the balances they know (null when none does).

```typescript
function startingBalance(accounts: readonly JournalAccount[]): number | null
```

See also: [`JournalAccount`](/vela-pro/api/journal#journalaccount).

### `summarize` [#summarize]

```typescript
function summarize(
    trades: readonly JournalTrade[],
    timeZone: string,
    initialBalance?: number | null,
): PeriodSummary
```

Default: `initialBalance = null`.

See also: [`JournalTrade`](/vela-pro/api/journal#journaltrade), [`PeriodSummary`](/vela-pro/api/journal#periodsummary).

### `tradesInRange` [#tradesinrange]

Trades closed within the range (by close day); open ones when the range reaches today.

```typescript
function tradesInRange(
    trades: readonly JournalTrade[],
    r: { from: string; to: string } | null,
    timeZone: string,
    today: string,
): JournalTrade[]
```

See also: [`JournalTrade`](/vela-pro/api/journal#journaltrade).

## Classes [#classes]

### `JournalController` class [#journalcontroller-class]

```typescript
class JournalController {
    constructor(opts?: JournalControllerOptions);
    readonly timeZone: string;
    readonly selectedAccount: string | null;
    readonly range: JournalRange;
    readonly custom: { from: string; to: string } | null;
    ready(): Promise<void>;
    accounts(): readonly JournalAccount[];
    account(id?: string | null): JournalAccount | null;
    today(): string;
    days(): { from: string; to: string } | null;
    allTrades(): JournalTrade[];
    accountTrades(accountId: string | null): JournalTrade[];
    trades(r?: { from: string; to: string } | null): JournalTrade[];
    trade(key: string): JournalTrade | null;
    fill(id: string): JournalFill | null;
    fillsOf(trade: JournalTrade): JournalFill[];
    hiddenFillsOf(trade: JournalTrade): JournalFill[];
    notes(): readonly JournalNote[];
    initialBalance(accountId?: string | null): number | null;
    currency(): string | null;
    selectAccount(id: string | null): void;
    setRange(range: JournalRange): void;
    setCustomRange(from: string, to: string): void;
    addAccount(a: { name: string; broker?: string; kind?: JournalAccount['kind']; currency?: string; initialBalance?: number | null; profitMethod?: JournalAccount['profitMethod'] }): JournalAccount;
    updateAccount(
        id: string,
        patch: Partial<Pick<JournalAccount, 'name' | 'initialBalance' | 'profitMethod' | 'currency'>>,
    ): void;
    removeAccount(id: string): void;
    addFills(
        accountId: string,
        fills: ReadonlyArray<Omit<JournalFill, 'id' | 'accountId' | 'source'> & { id?: string }>,
    ): { inserted: number; duplicates: number };
    updateFill(id: string, patch: Partial<FillValues>): void;
    resetFill(id: string): void;
    removeFill(id: string): void;
    restoreFill(id: string): void;
    annotate(key: string, patch: TradeAnnotation): void;
    addNote(body: string, date?: string): JournalNote | null;
    editNote(id: string, body: string): void;
    deleteNote(id: string): void;
    syncBroker(broker: Broker): () => void;
    onChange(cb: (what: JournalChange) => void): () => void;
    destroy(): void;
}
```

| Member             | Type                                                                                                            | Description                                                                                                                                          |
| ------------------ | --------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `constructor`      | `(opts?: JournalControllerOptions)`                                                                             |                                                                                                                                                      |
| `timeZone`         | `string`                                                                                                        |                                                                                                                                                      |
| `selectedAccount`  | `string \| null`                                                                                                | The selected account, or null for all of them.                                                                                                       |
| `range`            | `JournalRange`                                                                                                  |                                                                                                                                                      |
| `custom`           | `{ from: string; to: string } \| null`                                                                          |                                                                                                                                                      |
| `ready()`          | `() => Promise<void>`                                                                                           | Resolves once the store's data is in.                                                                                                                |
| `accounts()`       | `() => readonly JournalAccount[]`                                                                               |                                                                                                                                                      |
| `account()`        | `(id?: string \| null) => JournalAccount \| null`                                                               |                                                                                                                                                      |
| `today()`          | `() => string`                                                                                                  |                                                                                                                                                      |
| `days()`           | `() => { from: string; to: string } \| null`                                                                    | The selected days (null: all time).                                                                                                                  |
| `allTrades()`      | `() => JournalTrade[]`                                                                                          | Every trade of the selected account(s), newest first.                                                                                                |
| `accountTrades()`  | `(accountId: string \| null) => JournalTrade[]`                                                                 | Every trade of one account (null: of all of them), whichever is selected.                                                                            |
| `trades()`         | `(r?: { from: string; to: string } \| null) => JournalTrade[]`                                                  | The trades of the selected range.                                                                                                                    |
| `trade()`          | `(key: string) => JournalTrade \| null`                                                                         |                                                                                                                                                      |
| `fill()`           | `(id: string) => JournalFill \| null`                                                                           |                                                                                                                                                      |
| `fillsOf()`        | `(trade: JournalTrade) => JournalFill[]`                                                                        |                                                                                                                                                      |
| `hiddenFillsOf()`  | `(trade: JournalTrade) => JournalFill[]`                                                                        |                                                                                                                                                      |
| `notes()`          | `() => readonly JournalNote[]`                                                                                  |                                                                                                                                                      |
| `initialBalance()` | `(accountId?: string \| null) => number \| null`                                                                | Starting balance for drawdown in percent: one account's (default: the selected one), or with none selected, the sum of every account's that has one. |
| `currency()`       | `() => string \| null`                                                                                          |                                                                                                                                                      |
| `selectAccount()`  | `(id: string \| null) => void`                                                                                  |                                                                                                                                                      |
| `setRange()`       | `(range: JournalRange) => void`                                                                                 |                                                                                                                                                      |
| `setCustomRange()` | `(from: string, to: string) => void`                                                                            |                                                                                                                                                      |
| `addAccount()`     | `(a: { name: string; broker?: string; kind?: JournalAccount['kind']; …` (truncated; see declaration)            |                                                                                                                                                      |
| `updateAccount()`  | `(id: string, patch: Partial<Pick<JournalAccount, 'name' \| 'initialBalance' …` (truncated; see declaration)    |                                                                                                                                                      |
| `removeAccount()`  | `(id: string) => void`                                                                                          |                                                                                                                                                      |
| `addFills()`       | `(accountId: string, fills: ReadonlyArray<Omit<JournalFill, 'id' \| 'accountId' …` (truncated; see declaration) | Log fills into an account; a fill already there (same id) is skipped.                                                                                |
| `updateFill()`     | `(id: string, patch: Partial<FillValues>) => void`                                                              | Correct a fill; the source's values are kept to reset to.                                                                                            |
| `resetFill()`      | `(id: string) => void`                                                                                          |                                                                                                                                                      |
| `removeFill()`     | `(id: string) => void`                                                                                          | A manual fill is deleted; a broker's or a file's is hidden (it would come back on the next sync).                                                    |
| `restoreFill()`    | `(id: string) => void`                                                                                          |                                                                                                                                                      |
| `annotate()`       | `(key: string, patch: TradeAnnotation) => void`                                                                 |                                                                                                                                                      |
| `addNote()`        | `(body: string, date?: string) => JournalNote \| null`                                                          |                                                                                                                                                      |
| `editNote()`       | `(id: string, body: string) => void`                                                                            |                                                                                                                                                      |
| `deleteNote()`     | `(id: string) => void`                                                                                          |                                                                                                                                                      |
| `syncBroker()`     | `(broker: Broker) => () => void`                                                                                | Mirror a broker's fills into a synced account (created on first use): every fill it reports is journaled once, as it arrives.                        |
| `onChange()`       | `(cb: (what: JournalChange) => void) => () => void`                                                             |                                                                                                                                                      |
| `destroy()`        | `() => void`                                                                                                    |                                                                                                                                                      |

See also: [`Broker`](/vela-pro/api/trading#broker), [`FillValues`](/vela-pro/api/journal#fillvalues), [`JournalAccount`](/vela-pro/api/journal#journalaccount), [`JournalChange`](/vela-pro/api/journal#journalchange), [`JournalControllerOptions`](/vela-pro/api/journal#journalcontrolleroptions), [`JournalFill`](/vela-pro/api/journal#journalfill), [`JournalNote`](/vela-pro/api/journal#journalnote), [`JournalRange`](/vela-pro/api/journal#journalrange), [`JournalTrade`](/vela-pro/api/journal#journaltrade), [`TradeAnnotation`](/vela-pro/api/journal#tradeannotation).

### `JournalPanelWidget` [#journalpanelwidget]

```typescript
class JournalPanelWidget {
    constructor(props: JournalPanelProps);
    readonly el: HTMLElement;
    readonly tools: HTMLElement;
    update(next: Partial<Omit<JournalPanelProps, 'controller'>>): void;
    destroy(): void;
}
```

| Member        | Type                                                             | Description                                                                                                           |
| ------------- | ---------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `constructor` | `(props: JournalPanelProps)`                                     |                                                                                                                       |
| `el`          | `HTMLElement`                                                    |                                                                                                                       |
| `tools`       | `HTMLElement`                                                    | The account picker, Add trade and Maximize: in the widget's top row until a host lifts them into a header of its own. |
| `update()`    | `(next: Partial<Omit<JournalPanelProps, 'controller'>>) => void` |                                                                                                                       |
| `destroy()`   | `() => void`                                                     |                                                                                                                       |

See also: [`JournalPanelProps`](/vela-pro/api/journal#journalpanelprops).

### `JournalViewWidget` [#journalviewwidget]

```typescript
class JournalViewWidget {
    constructor(props: JournalViewProps);
    readonly el: HTMLElement;
    update(next: Partial<Omit<JournalViewProps, 'controller'>>): void;
    open(target?: { trade?: string; date?: string; page?: Page }): void;
    destroy(): void;
}

// Unexported supporting type referenced above
type Page = 'dashboard' | 'breakdown' | 'trades' | 'notes' | 'compare';
```

| Member        | Type                                                                | Description                                       |
| ------------- | ------------------------------------------------------------------- | ------------------------------------------------- |
| `constructor` | `(props: JournalViewProps)`                                         |                                                   |
| `el`          | `HTMLElement`                                                       |                                                   |
| `update()`    | `(next: Partial<Omit<JournalViewProps, 'controller'>>) => void`     |                                                   |
| `open()`      | `(target?: { trade?: string; date?: string; page?: Page }) => void` | Show a trade's review, a day's review, or a page. |
| `destroy()`   | `() => void`                                                        |                                                   |

See also: [`JournalViewProps`](/vela-pro/api/journal#journalviewprops).

### `LocalJournalStore` [#localjournalstore]

The journal in the browser's `localStorage` (memory only when storage is unavailable).

```typescript
class LocalJournalStore implements JournalStore {
    constructor(key?: string);
    load(): Promise<JournalData | null>;
    save(data: JournalData): Promise<void>;
}
```

Default: `constructor(key = KEY)`.

See also: [`JournalData`](/vela-pro/api/journal#journaldata), [`JournalStore`](/vela-pro/api/journal#journalstore).

## Interfaces and types [#interfaces-and-types]

### `AccountKind` [#accountkind]

```typescript
type AccountKind = 'manual' | 'import' | 'sync';
```

### `Breakdown` interface [#breakdown-interface]

```typescript
interface Breakdown {
    weekday: BreakdownGroup[];
    timeOfDay: BreakdownGroup[];
    holdTime: BreakdownGroup[];
    symbol: BreakdownGroup[];
    side: BreakdownGroup[];
    tag: BreakdownGroup[];
    rating: BreakdownGroup[];
}
```

See also: [`BreakdownGroup`](/vela-pro/api/journal#breakdowngroup).

### `BreakdownGroup` [#breakdowngroup]

```typescript
interface BreakdownGroup {
    key: string;
    trades: number;
    wins: number;
    losses: number;
    netPnl: number;
    winRate: number | null;
}
```

| Member    | Type             | Description                  |
| --------- | ---------------- | ---------------------------- |
| `key`     | `string`         |                              |
| `trades`  | `number`         |                              |
| `wins`    | `number`         |                              |
| `losses`  | `number`         |                              |
| `netPnl`  | `number`         |                              |
| `winRate` | `number \| null` | wins / (wins + losses), 0–1. |

### `CalendarMonth` interface [#calendarmonth-interface]

```typescript
interface CalendarMonth {
    year: number;
    month: number;
    weeks: Array<{ days: Array<{ date: string; stats: DayStats | null } | null>; netPnl: number; trades: number }>;
    netPnl: number;
    trades: number;
    tradingDays: number;
    winningDays: number;
}
```

| Member        | Type                                                                                                        | Description                           |
| ------------- | ----------------------------------------------------------------------------------------------------------- | ------------------------------------- |
| `year`        | `number`                                                                                                    |                                       |
| `month`       | `number`                                                                                                    |                                       |
| `weeks`       | `Array<{ days: Array<{ date: string; stats: DayStats \| null } \| null>; netPnl: number; trades: number }>` | Sunday first; null outside the month. |
| `netPnl`      | `number`                                                                                                    |                                       |
| `trades`      | `number`                                                                                                    |                                       |
| `tradingDays` | `number`                                                                                                    |                                       |
| `winningDays` | `number`                                                                                                    |                                       |

See also: [`DayStats`](/vela-pro/api/journal#daystats-interface).

### `DayStats` interface [#daystats-interface]

```typescript
interface DayStats {
    date: string;
    netPnl: number;
    grossPnl: number;
    fees: number;
    trades: number;
    wins: number;
    losses: number;
    breakevens: number;
    volume: number;
}
```

### `EdgeScore` interface [#edgescore-interface]

```typescript
interface EdgeScore {
    score: number | null;
    components: { winRate: number; profitFactor: number; avgWinLoss: number; drawdown: number; recovery: number; consistency: number };
    closedTrades: number;
}
```

### `EnableJournalOptions` [#enablejournaloptions]

Options for [`enableJournal`](/vela-pro/api/journal#enablejournal).

```typescript
interface EnableJournalOptions {
    store?: JournalStore;
    timeZone?: string;
    syncTrading?: boolean;
    width?: number;
    order?: number;
}
```

| Member         | Type           | Description                                                                           |
| -------------- | -------------- | ------------------------------------------------------------------------------------- |
| `store?`       | `JournalStore` | Where the journal lives (default: the browser's storage).                             |
| `timeZone?`    | `string`       | The journal's day boundaries (default: the browser's time zone).                      |
| `syncTrading?` | `boolean`      | Journal the trading broker's fills as they happen (default true, when trading is on). |
| `width?`       | `number`       |                                                                                       |
| `order?`       | `number`       | Place among the panel buttons (default 4).                                            |

See also: [`JournalStore`](/vela-pro/api/journal#journalstore).

### `FillValues` [#fillvalues]

```typescript
interface FillValues {
    side: 'buy' | 'sell';
    quantity: number;
    price: number;
    fee: number;
    executedAt: number;
}
```

### `HeadToHeadMetric` [#headtoheadmetric]

```typescript
type HeadToHeadMetric =
    | 'netPnl'
    | 'winRate'
    | 'profitFactor'
    | 'avgWinLoss'
    | 'expectancy'
    | 'maxDrawdown'
    | 'closedTrades';
```

### `HeadToHeadRow` [#headtoheadrow]

```typescript
interface HeadToHeadRow {
    id: HeadToHeadMetric;
    a: number | null;
    b: number | null;
    lowerIsBetter: boolean;
    winner: 'a' | 'b' | null;
    shareA: number;
    shareB: number;
    delta: number | null;
    ahead: boolean | null;
    deltaShare: number;
}
```

| Member          | Type                 | Description                                                            |
| --------------- | -------------------- | ---------------------------------------------------------------------- |
| `id`            | `HeadToHeadMetric`   |                                                                        |
| `a`             | `number \| null`     |                                                                        |
| `b`             | `number \| null`     |                                                                        |
| `lowerIsBetter` | `boolean`            | The smaller value wins (the drawdown).                                 |
| `winner`        | `'a' \| 'b' \| null` | Null on a tie, or when neither side has a value.                       |
| `shareA`        | `number`             | Each side's bar: its magnitude over the row's larger one.              |
| `shareB`        | `number`             |                                                                        |
| `delta`         | `number \| null`     | A minus B; null unless both sides have a value.                        |
| `ahead`         | `boolean \| null`    | A ahead of B (in the row's better direction), behind, or level (null). |
| `deltaShare`    | `number`             | The delta's bar: its magnitude over the row's larger value, at most 1. |

See also: [`HeadToHeadMetric`](/vela-pro/api/journal#headtoheadmetric).

### `JournalAccount` [#journalaccount]

```typescript
interface JournalAccount {
    id: string;
    name: string;
    broker: string;
    kind: AccountKind;
    currency: string;
    initialBalance: number | null;
    profitMethod: ProfitMethod;
    createdAt: number;
}
```

| Member           | Type             | Description                                                     |
| ---------------- | ---------------- | --------------------------------------------------------------- |
| `id`             | `string`         |                                                                 |
| `name`           | `string`         |                                                                 |
| `broker`         | `string`         | Where its fills come from (`Paper`, a broker's name, `Manual`). |
| `kind`           | `AccountKind`    |                                                                 |
| `currency`       | `string`         |                                                                 |
| `initialBalance` | `number \| null` | Unlocks drawdown in percent.                                    |
| `profitMethod`   | `ProfitMethod`   |                                                                 |
| `createdAt`      | `number`         |                                                                 |

See also: [`AccountKind`](/vela-pro/api/journal#accountkind), [`ProfitMethod`](/vela-pro/api/journal#profitmethod).

### `JournalChange` [#journalchange]

```typescript
type JournalChange = 'data' | 'selection';
```

### `JournalControllerOptions` [#journalcontrolleroptions]

```typescript
interface JournalControllerOptions {
    store?: JournalStore;
    timeZone?: string;
    now?: () => number;
}
```

| Member      | Type           | Description                                                      |
| ----------- | -------------- | ---------------------------------------------------------------- |
| `store?`    | `JournalStore` |                                                                  |
| `timeZone?` | `string`       | The journal's day boundaries (default: the browser's time zone). |
| `now?`      | `() => number` |                                                                  |

See also: [`JournalStore`](/vela-pro/api/journal#journalstore).

### `JournalData` [#journaldata]

```typescript
interface JournalData {
    accounts: JournalAccount[];
    fills: JournalFill[];
    annotations: Record<string, TradeAnnotation>;
    notes: JournalNote[];
}
```

See also: [`JournalAccount`](/vela-pro/api/journal#journalaccount), [`JournalFill`](/vela-pro/api/journal#journalfill), [`JournalNote`](/vela-pro/api/journal#journalnote), [`TradeAnnotation`](/vela-pro/api/journal#tradeannotation).

### `JournalFill` [#journalfill]

```typescript
interface JournalFill extends FillValues {
    id: string;
    accountId: string;
    symbol: string;
    source: AccountKind;
    reported?: FillValues | null;
    excluded?: boolean;
}
```

| Member      | Type                 | Description                                                                                     |
| ----------- | -------------------- | ----------------------------------------------------------------------------------------------- |
| `id`        | `string`             |                                                                                                 |
| `accountId` | `string`             |                                                                                                 |
| `symbol`    | `string`             |                                                                                                 |
| `source`    | `AccountKind`        |                                                                                                 |
| `reported?` | `FillValues \| null` | What the source said, when the user corrected it (the top-level values are the effective ones). |
| `excluded?` | `boolean`            | Hidden by the user (a broker's or a file's fill is hidden rather than deleted).                 |

See also: [`AccountKind`](/vela-pro/api/journal#accountkind), [`FillValues`](/vela-pro/api/journal#fillvalues).

### `JournalMetrics` [#journalmetrics]

```typescript
interface JournalMetrics {
    totalTrades: number;
    closedTrades: number;
    openTrades: number;
    wins: number;
    losses: number;
    breakevens: number;
    netPnl: number;
    grossPnl: number;
    fees: number;
    winRate: number | null;
    dayWinRate: number | null;
    tradingDays: number;
    winningDays: number;
    losingDays: number;
    profitFactor: number | null;
    profitFactorIsInfinite: boolean;
    avgWin: number | null;
    avgLoss: number | null;
    avgWinLossRatio: number | null;
    expectancy: number | null;
    largestWin: number | null;
    largestLoss: number | null;
    maxWinStreak: number;
    maxLossStreak: number;
    currentStreak: number;
    totalVolume: number;
    avgDurationMs: number | null;
    maxDrawdown: number;
    maxDrawdownPct: number | null;
    recoveryFactor: number | null;
    profitConcentration: number | null;
    avgRealizedR: number | null;
    tradesWithRisk: number;
    bestDay: DayStats | null;
    worstDay: DayStats | null;
}
```

| Member                   | Type               | Description                                                       |
| ------------------------ | ------------------ | ----------------------------------------------------------------- |
| `totalTrades`            | `number`           |                                                                   |
| `closedTrades`           | `number`           |                                                                   |
| `openTrades`             | `number`           |                                                                   |
| `wins`                   | `number`           |                                                                   |
| `losses`                 | `number`           |                                                                   |
| `breakevens`             | `number`           |                                                                   |
| `netPnl`                 | `number`           |                                                                   |
| `grossPnl`               | `number`           |                                                                   |
| `fees`                   | `number`           |                                                                   |
| `winRate`                | `number \| null`   | 0–1.                                                              |
| `dayWinRate`             | `number \| null`   |                                                                   |
| `tradingDays`            | `number`           |                                                                   |
| `winningDays`            | `number`           |                                                                   |
| `losingDays`             | `number`           |                                                                   |
| `profitFactor`           | `number \| null`   |                                                                   |
| `profitFactorIsInfinite` | `boolean`          |                                                                   |
| `avgWin`                 | `number \| null`   |                                                                   |
| `avgLoss`                | `number \| null`   |                                                                   |
| `avgWinLossRatio`        | `number \| null`   |                                                                   |
| `expectancy`             | `number \| null`   |                                                                   |
| `largestWin`             | `number \| null`   |                                                                   |
| `largestLoss`            | `number \| null`   |                                                                   |
| `maxWinStreak`           | `number`           |                                                                   |
| `maxLossStreak`          | `number`           |                                                                   |
| `currentStreak`          | `number`           | Positive: a winning streak; negative: a losing one.               |
| `totalVolume`            | `number`           |                                                                   |
| `avgDurationMs`          | `number \| null`   |                                                                   |
| `maxDrawdown`            | `number`           |                                                                   |
| `maxDrawdownPct`         | `number \| null`   |                                                                   |
| `recoveryFactor`         | `number \| null`   |                                                                   |
| `profitConcentration`    | `number \| null`   |                                                                   |
| `avgRealizedR`           | `number \| null`   |                                                                   |
| `tradesWithRisk`         | `number`           | Closed trades with a stop loss, the ones `avgRealizedR` averages. |
| `bestDay`                | `DayStats \| null` |                                                                   |
| `worstDay`               | `DayStats \| null` |                                                                   |

See also: [`DayStats`](/vela-pro/api/journal#daystats-interface).

### `JournalNote` [#journalnote]

A note on a day (not on an account).

```typescript
interface JournalNote {
    id: string;
    date: string;
    body: string;
    createdAt: number;
    updatedAt: number;
}
```

| Member      | Type     | Description   |
| ----------- | -------- | ------------- |
| `id`        | `string` |               |
| `date`      | `string` | `YYYY-MM-DD`. |
| `body`      | `string` |               |
| `createdAt` | `number` |               |
| `updatedAt` | `number` |               |

### `JournalPanelProps` [#journalpanelprops]

The journal panel's props. `controller` is read once; the others can change through `update`.

```typescript
interface JournalPanelProps {
    controller: JournalController;
    symbol?: string;
    host?: HTMLElement;
    icons?: () => SymbolIcons | null;
    onMaximize?: (target?: { trade?: string; date?: string }) => void;
    onShowTrade?: (trade: JournalTrade) => void;
    onNotify?: (message: string, kind: 'info' | 'success' | 'error') => void;
}
```

| Member         | Type                                                              | Description                                                                           |
| -------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| `controller`   | `JournalController`                                               | The journal: accounts, fills, trades, notes.                                          |
| `symbol?`      | `string`                                                          | The symbol a new fill starts on.                                                      |
| `host?`        | `HTMLElement`                                                     | Where menus and dialogs mount (default: the widget's own element).                    |
| `icons?`       | `() => SymbolIcons \| null`                                       | Symbol logos (the chart's data, or anything that answers `symbolIcon`).               |
| `onMaximize?`  | `(target?: { trade?: string; date?: string }) => void`            | Open the full journal (on a trade, a day, or as it was). Maximize shows only with it. |
| `onShowTrade?` | `(trade: JournalTrade) => void`                                   | A trade's chart button: frame it on a chart. The button shows only with it.           |
| `onNotify?`    | `(message: string, kind: 'info' \| 'success' \| 'error') => void` | Tell the user something (a fill added).                                               |

See also: [`JournalController`](/vela-pro/api/journal#journalcontroller-class), [`JournalTrade`](/vela-pro/api/journal#journaltrade), [`SymbolIcons`](/vela-pro/api/module-sdk#symbolicons).

### `JournalRange` [#journalrange]

```typescript
type JournalRange = 'today' | '7d' | '30d' | '365d' | 'ytd' | 'all';
```

### `JournalStore` [#journalstore]

Where the journal lives: the host's port (a server, a database). Pro ships a browser one.

```typescript
interface JournalStore {
    load(): Promise<JournalData | null>;
    save(data: JournalData): Promise<void>;
}
```

See also: [`JournalData`](/vela-pro/api/journal#journaldata).

### `JournalSurface` [#journalsurface]

Where the journal's dialogs mount and how they tell the user, with the symbol a new fill starts on: a shell, or a widget's host and its notices.

```typescript
interface JournalSurface {
    readonly host: HTMLElement;
    readonly symbol: string;
    toast(message: string, kind?: 'info' | 'success' | 'error'): void;
}
```

### `JournalTrade` [#journaltrade]

```typescript
interface JournalTrade {
    key: string;
    accountId: string;
    symbol: string;
    direction: 'long' | 'short';
    status: TradeStatus;
    openedAt: number;
    closedAt: number | null;
    quantity: number;
    openQuantity: number;
    avgEntry: number;
    avgExit: number | null;
    grossPnl: number;
    fees: number;
    netPnl: number;
    fillIds: string[];
    exits: TradeExit[];
    durationMs: number | null;
    realizedR: number | null;
    annotation: TradeAnnotation;
}
```

| Member         | Type                | Description     |
| -------------- | ------------------- | --------------- |
| `key`          | `string`            |                 |
| `accountId`    | `string`            |                 |
| `symbol`       | `string`            |                 |
| `direction`    | `'long' \| 'short'` |                 |
| `status`       | `TradeStatus`       |                 |
| `openedAt`     | `number`            |                 |
| `closedAt`     | `number \| null`    |                 |
| `quantity`     | `number`            | The entry size. |
| `openQuantity` | `number`            |                 |
| `avgEntry`     | `number`            |                 |
| `avgExit`      | `number \| null`    |                 |
| `grossPnl`     | `number`            |                 |
| `fees`         | `number`            |                 |
| `netPnl`       | `number`            |                 |
| `fillIds`      | `string[]`          |                 |
| `exits`        | `TradeExit[]`       |                 |
| `durationMs`   | `number \| null`    |                 |
| `realizedR`    | `number \| null`    |                 |
| `annotation`   | `TradeAnnotation`   |                 |

See also: [`TradeAnnotation`](/vela-pro/api/journal#tradeannotation), [`TradeExit`](/vela-pro/api/journal#tradeexit), [`TradeStatus`](/vela-pro/api/journal#tradestatus).

### `JournalViewProps` [#journalviewprops]

The full journal's props. `controller` is read once; the others can change through `update`.

```typescript
interface JournalViewProps {
    controller: JournalController;
    symbol?: string;
    host?: HTMLElement;
    icons?: () => SymbolIcons | null;
    onMinimize?: () => void;
    onClose?: () => void;
    onShowTrade?: (trade: JournalTrade) => void;
    onNotify?: (message: string, kind: 'info' | 'success' | 'error') => void;
}
```

| Member         | Type                                                              | Description                                                                                 |
| -------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| `controller`   | `JournalController`                                               | The journal: accounts, fills, trades, notes.                                                |
| `symbol?`      | `string`                                                          | The symbol a new fill starts on.                                                            |
| `host?`        | `HTMLElement`                                                     | Where menus and dialogs mount (default: the widget's own element).                          |
| `icons?`       | `() => SymbolIcons \| null`                                       | Symbol logos (the chart's data, or anything that answers `symbolIcon`).                     |
| `onMinimize?`  | `() => void`                                                      | Back to the chart (its button, Escape, Show on chart first). The button shows only with it. |
| `onClose?`     | `() => void`                                                      | Close the journal altogether. The button shows only with it.                                |
| `onShowTrade?` | `(trade: JournalTrade) => void`                                   | Frame a trade on a chart. Its buttons show only with it.                                    |
| `onNotify?`    | `(message: string, kind: 'info' \| 'success' \| 'error') => void` | Tell the user something (a fill added).                                                     |

See also: [`JournalController`](/vela-pro/api/journal#journalcontroller-class), [`JournalTrade`](/vela-pro/api/journal#journaltrade), [`SymbolIcons`](/vela-pro/api/module-sdk#symbolicons).

### `MetricDeltas` interface [#metricdeltas-interface]

```typescript
interface MetricDeltas {
    netPnl: number | null;
    winRate: number | null;
    profitFactor: number | null;
    avgWinLoss: number | null;
    dayWinRate: number | null;
}
```

### `PeriodSummary` [#periodsummary]

A stretch of trading: its metrics, its trading days, the equity after each, its Edge Score.

```typescript
interface PeriodSummary {
    metrics: JournalMetrics;
    days: DayStats[];
    equity: number[];
    edge: EdgeScore;
}
```

| Member    | Type             | Description                                         |
| --------- | ---------------- | --------------------------------------------------- |
| `metrics` | `JournalMetrics` |                                                     |
| `days`    | `DayStats[]`     |                                                     |
| `equity`  | `number[]`       | Cumulative net P\&L at the end of each trading day. |
| `edge`    | `EdgeScore`      |                                                     |

See also: [`DayStats`](/vela-pro/api/journal#daystats-interface), [`EdgeScore`](/vela-pro/api/journal#edgescore-interface), [`JournalMetrics`](/vela-pro/api/journal#journalmetrics).

### `ProfitMethod` [#profitmethod]

```typescript
type ProfitMethod = 'fifo' | 'lifo' | 'wavg';
```

### `RiskBehavior` interface [#riskbehavior-interface]

```typescript
interface RiskBehavior {
    maxDrawdown: { amount: number; fraction: number | null; recovery: number | null };
    expectancy: { amount: number | null; avgR: number | null };
    avgDurationMs: number | null;
    streak: { current: number; best: number; worst: number };
    days: { best: DayStats | null; worst: DayStats | null };
}
```

| Member          | Type                                                                     | Description                                                                                 |
| --------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------- |
| `maxDrawdown`   | `{ amount: number; fraction: number \| null; recovery: number \| null }` | The deepest fall from a peak; its fraction and the recovery factor need a starting balance. |
| `expectancy`    | `{ amount: number \| null; avgR: number \| null }`                       | Net P\&L per closed trade; the average R once closed trades carry a stop.                   |
| `avgDurationMs` | `number \| null`                                                         |                                                                                             |
| `streak`        | `{ current: number; best: number; worst: number }`                       | `current`: positive for wins in a row, negative for losses.                                 |
| `days`          | `{ best: DayStats \| null; worst: DayStats \| null }`                    |                                                                                             |

See also: [`DayStats`](/vela-pro/api/journal#daystats-interface).

### `TradeAnnotation` [#tradeannotation]

What the user writes about a trade.

```typescript
interface TradeAnnotation {
    notes?: string;
    tags?: string[];
    mistakes?: string[];
    rating?: number | null;
    stopLoss?: number | null;
    profitTarget?: number | null;
    reviewedAt?: number | null;
}
```

| Member          | Type             | Description |
| --------------- | ---------------- | ----------- |
| `notes?`        | `string`         |             |
| `tags?`         | `string[]`       |             |
| `mistakes?`     | `string[]`       |             |
| `rating?`       | `number \| null` | 1–5.        |
| `stopLoss?`     | `number \| null` |             |
| `profitTarget?` | `number \| null` |             |
| `reviewedAt?`   | `number \| null` |             |

### `TradeExit` [#tradeexit]

```typescript
interface TradeExit {
    fillId: string;
    quantity: number;
    grossPnl: number;
    time: number;
}
```

### `TradeStatus` [#tradestatus]

```typescript
type TradeStatus = 'open' | 'win' | 'loss' | 'breakeven';
```

## Constants [#constants]

### `EDGE_MIN_TRADES` [#edge_min_trades]

```typescript
const EDGE_MIN_TRADES: 5;
```

### `JOURNAL_PANEL_ID` [#journal_panel_id]

```typescript
const JOURNAL_PANEL_ID: 'vela-pro.journal';
```
