@livefolio/sdk 0.5.0-rc.3 → 0.5.0-rc.4

package/dist/index.d.ts

@@ -127,6 +127,22 @@ type Series = ReadonlyArray<{
     t: Date;
     v: number;
 }>;
+/**
+ * A cash distribution (dividend) or interest payment for an asset, carrying
+ * what the SDK needs to credit cash and classify the income per-lot.
+ *
+ * `incomeKind: 'qualified-eligible'` means the distribution CAN be qualified if
+ * a holding lot satisfies the 60-of-121-day rule; the runtime resolves the
+ * actual qualified-vs-ordinary split per lot. `'ordinary'`/`'interest'` are
+ * never qualified.
+ */
+type DividendEvent = {
+    asset: Asset;
+    exDate: Date;
+    payDate: Date;
+    amountPerShare: number;
+    incomeKind: 'qualified-eligible' | 'ordinary' | 'interest';
+};
 
 /**
  * Stable opaque string identifier for a {@link Position}. Generated by the
@@ -187,7 +203,7 @@ type IncomeKind = 'capital-gain' | 'qualified-dividend' | 'ordinary-dividend' |
  * sales reduce `quantity` and pro-rate `basis`.
  */
 type Lot = {
-    /** Opaque id assigned by {@link nextLotId} on creation. */
+    /** Opaque id assigned by `nextLotId` (internal) on creation. */
     id: string;
     asset: Asset;
     /** Shares remaining in this lot after any partial sales. */
@@ -767,9 +783,13 @@ interface DataFeed {
      * @param asset - The instrument to fetch bars for.
      * @param range - Half-open date range; `range.from` inclusive, `range.to` exclusive.
      * @param freq  - Bar width. `'1d'` returns one bar per trading day.
+     * @param kind  - `'adjusted'` (default) applies split/dividend adjustments;
+     *   `'unadjusted'` returns raw prices. Indicators consume adjusted bars;
+     *   execution fills and dividend cash-flow use unadjusted bars. Vendors that
+     *   do not distinguish may ignore this and always return their single series.
      * @returns An async iterable of {@link Bar} objects.
      */
-    bars(asset: Asset, range: DateRange, freq: Frequency): AsyncIterable<Bar>;
+    bars(asset: Asset, range: DateRange, freq: Frequency, kind?: 'adjusted' | 'unadjusted'): AsyncIterable<Bar>;
     /**
      * Returns a snapshot of fundamental data for `asset` as of `t`.
      * Optional — not all data providers carry fundamentals.
@@ -790,6 +810,17 @@ interface DataFeed {
      * @returns An async iterable of {@link DataEvent} objects.
      */
     events?(range: DateRange, kinds: ReadonlyArray<EventKind>): AsyncIterable<DataEvent>;
+    /**
+     * Returns cash distributions (dividends / interest) for `asset` over `range`.
+     * Optional — providers without dividend data omit it. Consumed by
+     * `runBacktest`'s per-session dividend hook. Amounts are per-share, on the
+     * unadjusted price basis.
+     *
+     * @param asset - The instrument to query.
+     * @param range - Half-open date range.
+     * @returns A promise resolving to an array of {@link DividendEvent} objects.
+     */
+    dividends?(asset: Asset, range: DateRange): Promise<DividendEvent[]>;
 }
 
 /**
@@ -2202,6 +2233,28 @@ type BacktestExecutorOptions = {
      * the fill quantity and recorded in `Fill.fees`. Defaults to `0`.
      */
     perShareFee?: number;
+    /**
+     * Tax-lot selection method applied to long sells (a `rebalance` reduce or a
+     * `close` of a long position). When set to a non-default method
+     * (`'LIFO'` / `'HIFO'` / `'min-tax'`), such a sell is split into one
+     * {@link Fill} per selected lot — each carrying `Fill.lotId` — so
+     * {@link applyFills} consumes those exact lots.
+     *
+     * Defaults to `'FIFO'` (equivalently, leaving this unset): the executor emits
+     * a single fill per order with no `lotId`, and `applyFills` performs its own
+     * internal FIFO. Buys, short-side closes, and `adjust` orders are never split.
+     */
+    lotMethod?: 'FIFO' | 'LIFO' | 'HIFO' | 'min-tax';
+    /**
+     * Short- and long-term capital-gains tax rates (as decimals, e.g. `0.37`)
+     * forwarded to the `'min-tax'` selector. **Required** when
+     * `lotMethod === 'min-tax'`; the constructor throws otherwise. Ignored for
+     * all other lot methods.
+     */
+    taxRates?: {
+        shortTerm: number;
+        longTerm: number;
+    };
 };
 /**
  * Reference {@link Executor} implementation for backtesting. Fills each order
@@ -2222,6 +2275,12 @@ type BacktestExecutorOptions = {
  * A flat per-share fee is added to `Fill.fees`. Orders with zero quantity are
  * silently skipped.
  *
+ * **Lot selection**: by default each order yields exactly one fill. When a
+ * non-default `lotMethod` (`'LIFO'` / `'HIFO'` / `'min-tax'`) is configured,
+ * long sells (a `rebalance` reduce or a `close` of a long position) are split
+ * into one fill per selected lot — each tagged with `Fill.lotId` — so
+ * {@link applyFills} consumes those exact lots. See {@link BacktestExecutorOptions.lotMethod}.
+ *
  * @example
  * ```ts
  * import { BacktestExecutor } from '@livefolio/sdk';
@@ -2250,7 +2309,8 @@ declare class BacktestExecutor implements Executor {
  * when the routed feed does not support the requested optional method.
  *
  * Distinguish the two cases via the message text: "no feed registered" vs
- * "does not implement fundamentals".
+ * "does not implement `<method>`" (e.g. "does not implement fundamentals()" or
+ * "does not implement dividends()").
  */
 declare class RoutingDataFeedError extends Error {
     constructor(message: string);
@@ -2271,9 +2331,11 @@ type RoutingDataFeedRouteMap = Readonly<Partial<Record<Asset['kind'], DataFeed>>
  * - **Function form:** `new RoutingDataFeed((a) => a.kind === 'macro' ? fred : yahoo)`.
  *   Use when routing depends on more than `kind` (e.g. allowlists).
  *
- * The router does **not** implement `events()` — the optional method is
- * genuinely absent (`'events' in router === false`). Cross-feed event
- * fan-out is deferred until a real consumer materializes.
+ * `dividends()` and `fundamentals()` ARE implemented — each targets a single
+ * asset, so it resolves to that asset's routed feed (or throws if the feed
+ * lacks the method). The router does **not** implement `events()` — the
+ * optional method is genuinely absent (`'events' in router === false`) because
+ * cross-feed event fan-out is a separate, deferred problem.
  *
  * @example
  * ```ts
@@ -2292,8 +2354,17 @@ type RoutingDataFeedRouteMap = Readonly<Partial<Record<Asset['kind'], DataFeed>>
 declare class RoutingDataFeed implements DataFeed {
     private readonly route;
     constructor(routes: RoutingDataFeedRouteMap | RoutingDataFeedRouteFn);
-    bars(asset: Asset, range: DateRange, freq: Frequency): AsyncGenerator<Bar>;
+    bars(asset: Asset, range: DateRange, freq: Frequency, kind?: 'adjusted' | 'unadjusted'): AsyncGenerator<Bar>;
     fundamentals(asset: Asset, t: Date): Promise<Fundamentals>;
+    /**
+     * Resolves `asset` to its routed feed and delegates `dividends`. This method
+     * is ALWAYS present on the router (unlike a leaf feed's optional `dividends?`),
+     * so `typeof routingFeed.dividends === 'function'` is always `true` — capability
+     * detection must account for the routed feed possibly lacking it at call time.
+     *
+     * @throws {RoutingDataFeedError} when the routed feed does not implement `dividends`.
+     */
+    dividends(asset: Asset, range: DateRange): Promise<DividendEvent[]>;
     private resolve;
 }
 
@@ -3194,7 +3265,7 @@ declare function evaluateFeatureSpecs(specs: ReadonlyArray<TacticalFeatureSpec>,
  * independently scaled); `volume` is passed through from the underlying bar.
  *
  * Non-synthetic assets are proxied transparently to the original `dataFeed`.
- * `fundamentals` and `events` methods, if present, are forwarded unchanged.
+ * `fundamentals`, `events`, and `dividends` methods, if present, are forwarded unchanged.
  *
  * Throws at construction time if `synthetics` contains duplicate `id` values.
  *
@@ -4057,4 +4128,4 @@ declare function applyOrders(portfolio: Portfolio, orders: ReadonlyArray<Order>)
  */
 declare function positionsByAsset(portfolio: Portfolio): Position[];
 
-export { type AdhocTimeOverrides, type AdjustOrder, type AllocateNode, type Asset, type AssetId, type AssetRef, BacktestExecutor, type BacktestExecutorOptions, type BacktestResult, type BacktestSnapshot, type Bar, type BarField, type Calendar, type CashEvent, CashEventQueue, type CloseOrder, type Comparison, type ComparisonOp, type ComputeFn, Crypto24x7Calendar, type DataEvent, type DataFeed, type DateRange, type EquityAsset, type EventKind, ExchangeCalendar, type ExchangeName, type Executor, type FeatureCache, type FeatureKey, type FeatureKind, type FeatureRef, FeatureRuntime, type FeatureRuntimeOptions, type FeatureScope, type FeatureSpec, type Features, type Fill, type Frequency, type FromSpecOptions, type Fundamentals, type HolidayRule, type IfNode, type IncomeKind, LSEExchangeCalendar, type LiveEvent, type Lot, type LotSlice, type MacroAsset, MemoryFeatureCache, NYSEExchangeCalendar, type NextOpenFn, ORDINARY_OFFSET_CAP, type OpenOrder, type Order, type PollingSchedule, type PollingStreamOptions, type Portfolio, type Position, type PositionId, type PriceMap, type Quote, type QuoteFeed, type RealizeResult, type RealizedEvent, type RebalanceConfig, type RebalanceFrequency, type RebalanceOrder, type ReturnMode, RoutingDataFeed, RoutingDataFeedError, type RoutingDataFeedRouteFn, type RoutingDataFeedRouteMap, RoutingQuoteFeed, RoutingQuoteFeedError, type RoutingQuoteFeedRouteFn, type RoutingQuoteFeedRouteMap, RoutingStreamingDataFeed, RoutingStreamingDataFeedError, type RoutingStreamingDataFeedRouteFn, type RoutingStreamingDataFeedRouteMap, type RuleNode, type RuleTreeState, type RunBacktestOptions, type RunLiveOptions, type Series, type Session, type SpecialClose, type SpecialOpen, type Strategy, type StreamingBar, type StreamingDataFeed, type SyntheticAsset, type TacticalFeatureKind, type TacticalFeatureSpec, type TacticalFeatures, type TacticalSpec, type TargetWeights, type TaxRates, type TaxableIncome, type TimeOfDay, type Tolerance, type WithStreamingSyntheticsOptions, aggregateByYear, applyFills, applyOrders, barsToSeries, bucketByTerm, collectBars, computeTaxBill, crossOffset, defineFeature, drawdown, ema, evaluateFeatureSpecs, evaluateRuleTree, index$1 as features, fromSpec, getCalendar, getFeatureCompute, holdingPeriodDays, isLongTerm, isRebalanceDay, netWithinBucket, paramsHash, periodKey, pollingStreamFromHistorical, positionsByAsset, realize, reconcile, returnSeries, rsi, runBacktest, runLive, selectFIFO, selectHIFO, selectLIFO, selectMinTax, seriesAt, sma, index$2 as tactical, index as tax, volatility, withStreamingSynthetics, withSynthetics };
+export { type AdhocTimeOverrides, type AdjustOrder, type AllocateNode, type Asset, type AssetId, type AssetRef, BacktestExecutor, type BacktestExecutorOptions, type BacktestResult, type BacktestSnapshot, type Bar, type BarField, type Calendar, type CashEvent, CashEventQueue, type CloseOrder, type Comparison, type ComparisonOp, type ComputeFn, Crypto24x7Calendar, type DataEvent, type DataFeed, type DateRange, type DividendEvent, type EquityAsset, type EventKind, ExchangeCalendar, type ExchangeName, type Executor, type FeatureCache, type FeatureKey, type FeatureKind, type FeatureRef, FeatureRuntime, type FeatureRuntimeOptions, type FeatureScope, type FeatureSpec, type Features, type Fill, type Frequency, type FromSpecOptions, type Fundamentals, type HolidayRule, type IfNode, type IncomeKind, LSEExchangeCalendar, type LiveEvent, type Lot, type LotSlice, type MacroAsset, MemoryFeatureCache, NYSEExchangeCalendar, type NextOpenFn, ORDINARY_OFFSET_CAP, type OpenOrder, type Order, type PollingSchedule, type PollingStreamOptions, type Portfolio, type Position, type PositionId, type PriceMap, type Quote, type QuoteFeed, type RealizeResult, type RealizedEvent, type RebalanceConfig, type RebalanceFrequency, type RebalanceOrder, type ReturnMode, RoutingDataFeed, RoutingDataFeedError, type RoutingDataFeedRouteFn, type RoutingDataFeedRouteMap, RoutingQuoteFeed, RoutingQuoteFeedError, type RoutingQuoteFeedRouteFn, type RoutingQuoteFeedRouteMap, RoutingStreamingDataFeed, RoutingStreamingDataFeedError, type RoutingStreamingDataFeedRouteFn, type RoutingStreamingDataFeedRouteMap, type RuleNode, type RuleTreeState, type RunBacktestOptions, type RunLiveOptions, type Series, type Session, type SpecialClose, type SpecialOpen, type Strategy, type StreamingBar, type StreamingDataFeed, type SyntheticAsset, type TacticalFeatureKind, type TacticalFeatureSpec, type TacticalFeatures, type TacticalSpec, type TargetWeights, type TaxRates, type TaxableIncome, type TimeOfDay, type Tolerance, type WithStreamingSyntheticsOptions, aggregateByYear, applyFills, applyOrders, barsToSeries, bucketByTerm, collectBars, computeTaxBill, crossOffset, defineFeature, drawdown, ema, evaluateFeatureSpecs, evaluateRuleTree, index$1 as features, fromSpec, getCalendar, getFeatureCompute, holdingPeriodDays, isLongTerm, isRebalanceDay, netWithinBucket, paramsHash, periodKey, pollingStreamFromHistorical, positionsByAsset, realize, reconcile, returnSeries, rsi, runBacktest, runLive, selectFIFO, selectHIFO, selectLIFO, selectMinTax, seriesAt, sma, index$2 as tactical, index as tax, volatility, withStreamingSynthetics, withSynthetics };

package/dist/index.js

@@ -909,40 +909,124 @@ async function* runLive(opts) {
   }
 }
 
+// src/tax/lot-selection.ts
+function take(sorted, qty) {
+  let need = qty;
+  const out = [];
+  for (const lot of sorted) {
+    if (lot.quantity <= 0) continue;
+    if (need <= 0) break;
+    const q = Math.min(lot.quantity, need);
+    out.push({ lotId: lot.id, quantity: q });
+    need -= q;
+  }
+  if (need > 1e-9) {
+    const held = sorted.reduce((s, l) => s + Math.max(0, l.quantity), 0);
+    throw new RangeError(`lot-selection: need ${qty} but only ${held} held`);
+  }
+  return out;
+}
+function selectFIFO(lots, qty) {
+  return take(
+    [...lots].sort((a, b) => a.openDate.getTime() - b.openDate.getTime()),
+    qty
+  );
+}
+function selectLIFO(lots, qty) {
+  return take(
+    [...lots].sort((a, b) => b.openDate.getTime() - a.openDate.getTime()),
+    qty
+  );
+}
+function selectHIFO(lots, qty) {
+  return take(
+    [...lots].filter((l) => l.quantity > 0).sort((a, b) => b.basis / b.quantity - a.basis / a.quantity),
+    qty
+  );
+}
+function selectMinTax(lots, qty, ctx) {
+  const tier = (l) => {
+    const gainPerShare = ctx.price - l.basis / l.quantity;
+    const lt = isLongTerm(holdingPeriodDays(l, ctx.asOf));
+    if (gainPerShare < 0) return lt ? 0 : 1;
+    return lt ? 2 : 3;
+  };
+  const sorted = [...lots].filter((l) => l.quantity > 0).sort((a, b) => {
+    const ta = tier(a);
+    const tb = tier(b);
+    if (ta !== tb) return ta - tb;
+    const gainA = ctx.price - a.basis / a.quantity;
+    const gainB = ctx.price - b.basis / b.quantity;
+    return gainA - gainB;
+  });
+  return take(sorted, qty);
+}
+
 // src/reference/backtest-executor.ts
 function resolveAsset(order, portfolio) {
   switch (order.kind) {
     case "open":
-      return { asset: order.asset, sign: order.side === "long" ? 1 : -1, qty: order.quantity };
+      return { asset: order.asset, sign: order.side === "long" ? 1 : -1, qty: order.quantity, lotConsumingSell: false };
     case "rebalance":
-      return { asset: order.asset, sign: order.delta >= 0 ? 1 : -1, qty: Math.abs(order.delta) };
+      return {
+        asset: order.asset,
+        sign: order.delta >= 0 ? 1 : -1,
+        qty: Math.abs(order.delta),
+        lotConsumingSell: order.delta < 0
+      };
     case "close": {
       const p = portfolio.positions.find((x) => x.id === order.positionId);
       if (!p) throw new Error(`BacktestExecutor: close target position ${order.positionId} not found`);
-      return { asset: p.asset, sign: p.side === "long" ? -1 : 1, qty: order.quantity ?? p.quantity };
+      return {
+        asset: p.asset,
+        sign: p.side === "long" ? -1 : 1,
+        qty: order.quantity ?? p.quantity,
+        lotConsumingSell: p.side === "long"
+      };
     }
     case "adjust": {
       const p = portfolio.positions.find((x) => x.id === order.positionId);
       if (!p) throw new Error(`BacktestExecutor: adjust target position ${order.positionId} not found`);
       const target = order.changes.quantity ?? p.quantity;
       const delta = target - p.quantity;
-      return { asset: p.asset, sign: delta >= 0 ? 1 : -1, qty: Math.abs(delta) };
+      return { asset: p.asset, sign: delta >= 0 ? 1 : -1, qty: Math.abs(delta), lotConsumingSell: false };
     }
   }
 }
 var BacktestExecutor = class {
   constructor(opts) {
     this.opts = opts;
+    if (opts.lotMethod === "min-tax" && !opts.taxRates) {
+      throw new Error("BacktestExecutor: lotMethod 'min-tax' requires taxRates");
+    }
   }
   async submit(orders, t, portfolio) {
     const fills = [];
     const slip = (this.opts.slippageBps ?? 0) / 1e4;
     const feePer = this.opts.perShareFee ?? 0;
+    const method = this.opts.lotMethod;
     for (const order of orders) {
-      const { asset, sign, qty } = resolveAsset(order, portfolio);
+      const { asset, sign, qty, lotConsumingSell } = resolveAsset(order, portfolio);
       if (qty === 0) continue;
       const open = await this.opts.nextOpen(asset, t);
       const adjustedPrice = open.price * (1 + sign * slip);
+      if (method && method !== "FIFO" && lotConsumingSell) {
+        const lots = (portfolio.lots ?? []).filter((l) => l.asset.id === asset.id && l.quantity > 0);
+        if (lots.length > 0) {
+          const slices = method === "LIFO" ? selectLIFO(lots, qty) : method === "HIFO" ? selectHIFO(lots, qty) : selectMinTax(lots, qty, { price: adjustedPrice, asOf: open.t, rates: this.opts.taxRates });
+          for (const slice of slices) {
+            fills.push({
+              orderRef: order.id,
+              t: open.t,
+              quantity: slice.quantity,
+              price: adjustedPrice,
+              fees: feePer * slice.quantity,
+              lotId: slice.lotId
+            });
+          }
+          continue;
+        }
+      }
       fills.push({
         orderRef: order.id,
         t: open.t,
@@ -974,9 +1058,9 @@ var RoutingDataFeed = class {
   // Async generator (rather than plain delegation) so resolve() runs lazily on
   // the first next() call, surfacing errors via the iterable's normal rejection
   // path instead of throwing synchronously at call time.
-  async *bars(asset, range, freq) {
+  async *bars(asset, range, freq, kind) {
     const feed = this.resolve(asset);
-    yield* feed.bars(asset, range, freq);
+    yield* feed.bars(asset, range, freq, kind);
   }
   async fundamentals(asset, t) {
     const feed = this.resolve(asset);
@@ -987,6 +1071,23 @@ var RoutingDataFeed = class {
     }
     return feed.fundamentals(asset, t);
   }
+  /**
+   * Resolves `asset` to its routed feed and delegates `dividends`. This method
+   * is ALWAYS present on the router (unlike a leaf feed's optional `dividends?`),
+   * so `typeof routingFeed.dividends === 'function'` is always `true` — capability
+   * detection must account for the routed feed possibly lacking it at call time.
+   *
+   * @throws {RoutingDataFeedError} when the routed feed does not implement `dividends`.
+   */
+  async dividends(asset, range) {
+    const feed = this.resolve(asset);
+    if (typeof feed.dividends !== "function") {
+      throw new RoutingDataFeedError(
+        `RoutingDataFeed: routed feed for asset.kind="${asset.kind}" (id="${asset.id}") does not implement dividends()`
+      );
+    }
+    return feed.dividends(asset, range);
+  }
   resolve(asset) {
     const feed = this.route(asset);
     if (feed === void 0) {
@@ -2880,11 +2981,13 @@ function withSynthetics(dataFeed, synthetics) {
     byId.set(s.id, s);
   }
   const wrapped = {
-    bars(asset, range, freq) {
+    // `kind` ('adjusted' | 'unadjusted') is forwarded to the underlying feed
+    // before synthesis so synthetic bars derive from the requested price series.
+    bars(asset, range, freq, kind) {
       const synth = byId.get(asset.id);
-      if (!synth) return dataFeed.bars(asset, range, freq);
+      if (!synth) return dataFeed.bars(asset, range, freq, kind);
       const underlying = resolveAssetRef(synth.underlying);
-      return synthesize(dataFeed.bars(underlying, range, freq), synth.leverage, synth.expense);
+      return synthesize(dataFeed.bars(underlying, range, freq, kind), synth.leverage, synth.expense);
     }
   };
   if (dataFeed.fundamentals) {
@@ -2893,6 +2996,9 @@ function withSynthetics(dataFeed, synthetics) {
   if (dataFeed.events) {
     wrapped.events = dataFeed.events.bind(dataFeed);
   }
+  if (dataFeed.dividends) {
+    wrapped.dividends = dataFeed.dividends.bind(dataFeed);
+  }
   return wrapped;
 }
 function withStreamingSynthetics(inner, synthetics, opts) {
@@ -3127,59 +3233,6 @@ __export(tax_exports, {
   selectMinTax: () => selectMinTax
 });
 
-// src/tax/lot-selection.ts
-function take(sorted, qty) {
-  let need = qty;
-  const out = [];
-  for (const lot of sorted) {
-    if (lot.quantity <= 0) continue;
-    if (need <= 0) break;
-    const q = Math.min(lot.quantity, need);
-    out.push({ lotId: lot.id, quantity: q });
-    need -= q;
-  }
-  if (need > 1e-9) {
-    const held = sorted.reduce((s, l) => s + Math.max(0, l.quantity), 0);
-    throw new RangeError(`lot-selection: need ${qty} but only ${held} held`);
-  }
-  return out;
-}
-function selectFIFO(lots, qty) {
-  return take(
-    [...lots].sort((a, b) => a.openDate.getTime() - b.openDate.getTime()),
-    qty
-  );
-}
-function selectLIFO(lots, qty) {
-  return take(
-    [...lots].sort((a, b) => b.openDate.getTime() - a.openDate.getTime()),
-    qty
-  );
-}
-function selectHIFO(lots, qty) {
-  return take(
-    [...lots].filter((l) => l.quantity > 0).sort((a, b) => b.basis / b.quantity - a.basis / a.quantity),
-    qty
-  );
-}
-function selectMinTax(lots, qty, ctx) {
-  const tier = (l) => {
-    const gainPerShare = ctx.price - l.basis / l.quantity;
-    const lt = isLongTerm(holdingPeriodDays(l, ctx.asOf));
-    if (gainPerShare < 0) return lt ? 0 : 1;
-    return lt ? 2 : 3;
-  };
-  const sorted = [...lots].filter((l) => l.quantity > 0).sort((a, b) => {
-    const ta = tier(a);
-    const tb = tier(b);
-    if (ta !== tb) return ta - tb;
-    const gainA = ctx.price - a.basis / a.quantity;
-    const gainB = ctx.price - b.basis / b.quantity;
-    return gainA - gainB;
-  });
-  return take(sorted, qty);
-}
-
 // src/tax/aggregation.ts
 var ORDINARY_OFFSET_CAP = 3e3;
 function bucketByTerm(events) {