nexustrade 1.10.0 → 1.11.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -174,6 +174,30 @@ const book = nt.portfolio(
174
174
  );
175
175
  ```
176
176
 
177
+ Order execution belongs to the strategy. Omit it for the backward-compatible
178
+ Market default, use a fixed unit price for Buy/Sell, or set an option strategy's
179
+ maximum net debit / minimum net credit:
180
+
181
+ ```ts
182
+ nt.strategy("Buy SPY at my price", nt.always(), nt.buy(nt.stockAsset("SPY"), 10), {
183
+ orderExecution: nt.limitOrder({
184
+ price: nt.unitPriceLimit(500),
185
+ workingTime: nt.goodForDay(),
186
+ }),
187
+ });
188
+
189
+ nt.strategy("Sell the spread for $1.50 or better", nt.always(), optionAction, {
190
+ orderExecution: nt.limitOrder({
191
+ price: nt.minimumNetCredit(1.5),
192
+ workingTime: nt.goodForMinutes(30),
193
+ }),
194
+ });
195
+ ```
196
+
197
+ `currentLimit()` creates a quote-relative Limit for dynamic rebalance strategies.
198
+ It keeps the no-worse-than-current-quote protection, but it is not a resting
199
+ price target. Live option strategies must choose an explicit Limit policy.
200
+
177
201
  <details>
178
202
  <summary><b>What you can build</b> — 170+ generated builders</summary>
179
203
 
@@ -1,7 +1,7 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
- exports.sessionFlatten = exports.strategy = exports.closeOption = exports.greeksTrigger = exports.daysHeldTrigger = exports.dteTrigger = exports.pnlTrigger = exports.rebalanceOption = exports.sleeve = exports.structureTemplate = exports.openOption = exports.againstParent = exports.optionsBuilder = exports.leg = exports.dynamicRebalance = exports.launchAgent = exports.alert = exports.sell = exports.buy = exports.selectPercentile = exports.selectTop = exports.filter = exports.RebalanceNetBenefit = exports.RebalanceExpectedBenefit = exports.RebalanceEstimatedCost = exports.RebalancePlannedTurnover = exports.RebalanceAllocationDrift = exports.volatilityTarget = exports.maximumDiversificationAllocation = exports.riskParityAllocation = exports.meanVarianceAllocation = exports.always = exports.andThen = exports.multi = exports.exactly = exports.fewerThan = exports.atMost = exports.atLeast = exports.or = exports.and = exports.neq = exports.eq = exports.lte = exports.gte = exports.lt = exports.gt = exports.cryptoAsset = exports.stockAsset = exports.PORTFOLIO_WIDE = exports.CANDIDATE = void 0;
4
- exports.geneUniversePipelineFilter = exports.geneSelectTopLimit = exports.geneMaxSpreadPct = exports.geneDteBracket = exports.geneStrikeDistance = exports.geneOptionDelta = exports.geneExposurePolicy = exports.geneAllocationPolicy = exports.geneStructureKind = exports.geneStopLossPct = exports.geneTakeProfitPct = exports.geneRollTriggerDte = exports.geneDeploymentPct = exports.geneTotalBudgetPct = exports.geneAllocationPct = exports.geneBuyingPowerPct = exports.geneRankSignal = exports.geneEntryCooldownDays = exports.geneExitCondition = exports.geneEntryCondition = exports.geneSubject = exports.optimization = exports.walkForward = exports.backtest = exports.SMA = exports.RSI = exports.PriceStdDev = exports.EMA = exports.BBand = exports.portfolio = void 0;
3
+ exports.currentLimit = exports.limitOrder = exports.closeOption = exports.greeksTrigger = exports.daysHeldTrigger = exports.dteTrigger = exports.pnlTrigger = exports.rebalanceOption = exports.sleeve = exports.structureTemplate = exports.openOption = exports.againstParent = exports.optionsBuilder = exports.leg = exports.dynamicRebalance = exports.launchAgent = exports.alert = exports.sell = exports.buy = exports.selectPercentile = exports.selectTop = exports.filter = exports.RebalanceNetBenefit = exports.RebalanceExpectedBenefit = exports.RebalanceEstimatedCost = exports.RebalancePlannedTurnover = exports.RebalanceAllocationDrift = exports.volatilityTarget = exports.maximumDiversificationAllocation = exports.riskParityAllocation = exports.meanVarianceAllocation = exports.always = exports.andThen = exports.multi = exports.exactly = exports.fewerThan = exports.atMost = exports.atLeast = exports.or = exports.and = exports.neq = exports.eq = exports.lte = exports.gte = exports.lt = exports.gt = exports.cryptoAsset = exports.stockAsset = exports.PORTFOLIO_WIDE = exports.CANDIDATE = void 0;
4
+ exports.geneUniversePipelineFilter = exports.geneSelectTopLimit = exports.geneMaxSpreadPct = exports.geneDteBracket = exports.geneStrikeDistance = exports.geneOptionDelta = exports.geneExposurePolicy = exports.geneAllocationPolicy = exports.geneStructureKind = exports.geneStopLossPct = exports.geneTakeProfitPct = exports.geneRollTriggerDte = exports.geneDeploymentPct = exports.geneTotalBudgetPct = exports.geneAllocationPct = exports.geneBuyingPowerPct = exports.geneRankSignal = exports.geneConditionThreshold = exports.geneConditionWindowLength = exports.geneEntryCooldownDays = exports.geneExitCondition = exports.geneEntryCondition = exports.geneSubject = exports.optimization = exports.walkForward = exports.backtest = exports.SMA = exports.RSI = exports.PriceStdDev = exports.EMA = exports.BBand = exports.portfolio = exports.sessionFlatten = exports.strategy = exports.goodForMinutes = exports.goodForDay = exports.minimumNetCredit = exports.maximumNetDebit = exports.unitPriceLimit = void 0;
5
5
  exports.universe = universe;
6
6
  exports.AbsoluteValue = AbsoluteValue;
7
7
  exports.AverageTrueRange = AverageTrueRange;
@@ -424,8 +424,43 @@ const greeksTrigger = (bounds) => compact({ type: "greeks", ...bounds });
424
424
  exports.greeksTrigger = greeksTrigger;
425
425
  const closeOption = (config = {}) => compact({ type: "CloseOption", ...config });
426
426
  exports.closeOption = closeOption;
427
+ const limitOrder = (config) => compact({ type: "Limit", ...config });
428
+ exports.limitOrder = limitOrder;
429
+ const currentLimit = () => ({
430
+ type: "QuoteRelative",
431
+ reference: "Current",
432
+ });
433
+ exports.currentLimit = currentLimit;
434
+ const unitPriceLimit = (amount) => ({
435
+ type: "UnitPrice",
436
+ amount,
437
+ });
438
+ exports.unitPriceLimit = unitPriceLimit;
439
+ const maximumNetDebit = (amount) => ({
440
+ type: "MaximumNetDebit",
441
+ amount,
442
+ });
443
+ exports.maximumNetDebit = maximumNetDebit;
444
+ const minimumNetCredit = (amount) => ({
445
+ type: "MinimumNetCredit",
446
+ amount,
447
+ });
448
+ exports.minimumNetCredit = minimumNetCredit;
449
+ const goodForDay = () => ({ type: "Day" });
450
+ exports.goodForDay = goodForDay;
451
+ const goodForMinutes = (minutes) => ({
452
+ type: "Minutes",
453
+ minutes,
454
+ });
455
+ exports.goodForMinutes = goodForMinutes;
427
456
  // ---- assembly ----
428
- const strategy = (name, condition, action, options = {}) => compact({ name, condition, action, ...options });
457
+ const strategy = (name, condition, action, options = {}) => compact({
458
+ name,
459
+ condition,
460
+ action,
461
+ ...options,
462
+ orderExecution: options.orderExecution ?? { type: "Market" },
463
+ });
429
464
  exports.strategy = strategy;
430
465
  /**
431
466
  * Session / clock flatten — condition carries the gate (MinutesAfterOpen, Day, …).
@@ -1702,6 +1737,22 @@ const geneEntryCooldownDays = (strategyIndex, values) => ({
1702
1737
  values: values,
1703
1738
  });
1704
1739
  exports.geneEntryCooldownDays = geneEntryCooldownDays;
1740
+ /** Sweep ConditionWindowLength (Strategy scope) over a value set. */
1741
+ const geneConditionWindowLength = (strategyIndex, path, slot, values) => ({
1742
+ field: "ConditionWindowLength",
1743
+ scope: "Strategy",
1744
+ target: { scope: "Strategy", field: "ConditionWindowLength", strategyIndex, path, slot },
1745
+ values: values,
1746
+ });
1747
+ exports.geneConditionWindowLength = geneConditionWindowLength;
1748
+ /** Sweep ConditionThreshold (Strategy scope) over a value set. */
1749
+ const geneConditionThreshold = (strategyIndex, path, slot, values) => ({
1750
+ field: "ConditionThreshold",
1751
+ scope: "Strategy",
1752
+ target: { scope: "Strategy", field: "ConditionThreshold", strategyIndex, path, slot },
1753
+ values: values,
1754
+ });
1755
+ exports.geneConditionThreshold = geneConditionThreshold;
1705
1756
  /** Sweep RankSignal (Action scope) over a value set. */
1706
1757
  const geneRankSignal = (strategyIndex, values) => ({
1707
1758
  field: "RankSignal",
@@ -393,6 +393,32 @@ export interface CloseOptionAction {
393
393
  quantity?: CloseQuantity;
394
394
  }
395
395
  export type Action = BuyOrSellAction | DepositOrWithdrawAction | AlertAction | LaunchAgentAction | DynamicRebalanceAction | RebalanceOptionAction | OpenOptionAction | CloseOptionAction;
396
+ export type StrategyLimitWorkingTime = {
397
+ type: "Day";
398
+ } | {
399
+ type: "Minutes";
400
+ minutes: number;
401
+ };
402
+ export type StrategyLimitPricePolicy = {
403
+ type: "QuoteRelative";
404
+ reference: "Current";
405
+ } | {
406
+ type: "UnitPrice";
407
+ amount: number;
408
+ } | {
409
+ type: "MaximumNetDebit";
410
+ amount: number;
411
+ } | {
412
+ type: "MinimumNetCredit";
413
+ amount: number;
414
+ };
415
+ export type StrategyOrderExecutionPolicy = {
416
+ type: "Market";
417
+ } | {
418
+ type: "Limit";
419
+ price: StrategyLimitPricePolicy;
420
+ workingTime?: StrategyLimitWorkingTime;
421
+ };
396
422
  /**
397
423
  * `automaticOrderApproval` is deliberately absent. It is system-managed and always
398
424
  * false for agent-created strategies, and placing it on an action fails validation —
@@ -403,6 +429,8 @@ export interface Strategy {
403
429
  condition: StrategyCondition;
404
430
  action: Action;
405
431
  active?: boolean;
432
+ /** Omitted means Market. Limit always requires an explicit price policy. */
433
+ orderExecution?: StrategyOrderExecutionPolicy;
406
434
  }
407
435
  export interface Portfolio {
408
436
  name: string;
@@ -602,8 +630,19 @@ export declare const closeOption: (config?: {
602
630
  triggers?: CloseOptionTrigger[];
603
631
  quantity?: CloseQuantity;
604
632
  }) => CloseOptionAction;
633
+ export declare const limitOrder: (config: {
634
+ price: StrategyLimitPricePolicy;
635
+ workingTime?: StrategyLimitWorkingTime;
636
+ }) => StrategyOrderExecutionPolicy;
637
+ export declare const currentLimit: () => StrategyLimitPricePolicy;
638
+ export declare const unitPriceLimit: (amount: number) => StrategyLimitPricePolicy;
639
+ export declare const maximumNetDebit: (amount: number) => StrategyLimitPricePolicy;
640
+ export declare const minimumNetCredit: (amount: number) => StrategyLimitPricePolicy;
641
+ export declare const goodForDay: () => StrategyLimitWorkingTime;
642
+ export declare const goodForMinutes: (minutes: number) => StrategyLimitWorkingTime;
605
643
  export declare const strategy: (name: string, condition: StrategyCondition, action: Action, options?: {
606
644
  active?: boolean;
645
+ orderExecution?: StrategyOrderExecutionPolicy;
607
646
  }) => Strategy;
608
647
  /**
609
648
  * Session / clock flatten — condition carries the gate (MinutesAfterOpen, Day, …).
@@ -1413,6 +1452,12 @@ export declare const walkForward: (portfolio: Portfolio, config: WalkForwardConf
1413
1452
  /** Submit a genetic optimization over the portfolio's tunable genes. */
1414
1453
  export declare const optimization: (portfolio: Portfolio, config: OptimizationConfig) => JobRequest;
1415
1454
  export type SweepSortDirection = "Highest" | "Lowest";
1455
+ /**
1456
+ * Which scalar inside an addressed condition node a parametric gene varies.
1457
+ * "Lhs"/"Rhs" name the two indicators of a comparison; "Node" names the node's
1458
+ * own number (a Then chain's window, a Multi's threshold).
1459
+ */
1460
+ export type ConditionNodeSlot = "Lhs" | "Rhs" | "Node";
1416
1461
  /** One authored sweep gene. Opaque to callers — built via the gene* builders. */
1417
1462
  export interface Gene {
1418
1463
  field: string;
@@ -1434,6 +1479,10 @@ export declare const geneExitCondition: (strategyIndex: number, values: {
1434
1479
  }[]) => Gene;
1435
1480
  /** Sweep EntryCooldownDays (Strategy scope) over a value set. */
1436
1481
  export declare const geneEntryCooldownDays: (strategyIndex: number, values: number[]) => Gene;
1482
+ /** Sweep ConditionWindowLength (Strategy scope) over a value set. */
1483
+ export declare const geneConditionWindowLength: (strategyIndex: number, path: number[], slot: ConditionNodeSlot, values: number[]) => Gene;
1484
+ /** Sweep ConditionThreshold (Strategy scope) over a value set. */
1485
+ export declare const geneConditionThreshold: (strategyIndex: number, path: number[], slot: ConditionNodeSlot, values: number[]) => Gene;
1437
1486
  /** Sweep RankSignal (Action scope) over a value set. */
1438
1487
  export declare const geneRankSignal: (strategyIndex: number, values: {
1439
1488
  label: string;
@@ -264,8 +264,36 @@ export const dteTrigger = (bounds) => compact({ type: "dte", ...bounds });
264
264
  export const daysHeldTrigger = (bounds) => compact({ type: "daysHeld", ...bounds });
265
265
  export const greeksTrigger = (bounds) => compact({ type: "greeks", ...bounds });
266
266
  export const closeOption = (config = {}) => compact({ type: "CloseOption", ...config });
267
+ export const limitOrder = (config) => compact({ type: "Limit", ...config });
268
+ export const currentLimit = () => ({
269
+ type: "QuoteRelative",
270
+ reference: "Current",
271
+ });
272
+ export const unitPriceLimit = (amount) => ({
273
+ type: "UnitPrice",
274
+ amount,
275
+ });
276
+ export const maximumNetDebit = (amount) => ({
277
+ type: "MaximumNetDebit",
278
+ amount,
279
+ });
280
+ export const minimumNetCredit = (amount) => ({
281
+ type: "MinimumNetCredit",
282
+ amount,
283
+ });
284
+ export const goodForDay = () => ({ type: "Day" });
285
+ export const goodForMinutes = (minutes) => ({
286
+ type: "Minutes",
287
+ minutes,
288
+ });
267
289
  // ---- assembly ----
268
- export const strategy = (name, condition, action, options = {}) => compact({ name, condition, action, ...options });
290
+ export const strategy = (name, condition, action, options = {}) => compact({
291
+ name,
292
+ condition,
293
+ action,
294
+ ...options,
295
+ orderExecution: options.orderExecution ?? { type: "Market" },
296
+ });
269
297
  /**
270
298
  * Session / clock flatten — condition carries the gate (MinutesAfterOpen, Day, …).
271
299
  * Never pairs with always(); PnL/DTE/daysHeld exits use closeOption({ triggers }).
@@ -1532,6 +1560,20 @@ export const geneEntryCooldownDays = (strategyIndex, values) => ({
1532
1560
  target: { scope: "Strategy", field: "EntryCooldownDays", strategyIndex },
1533
1561
  values: values,
1534
1562
  });
1563
+ /** Sweep ConditionWindowLength (Strategy scope) over a value set. */
1564
+ export const geneConditionWindowLength = (strategyIndex, path, slot, values) => ({
1565
+ field: "ConditionWindowLength",
1566
+ scope: "Strategy",
1567
+ target: { scope: "Strategy", field: "ConditionWindowLength", strategyIndex, path, slot },
1568
+ values: values,
1569
+ });
1570
+ /** Sweep ConditionThreshold (Strategy scope) over a value set. */
1571
+ export const geneConditionThreshold = (strategyIndex, path, slot, values) => ({
1572
+ field: "ConditionThreshold",
1573
+ scope: "Strategy",
1574
+ target: { scope: "Strategy", field: "ConditionThreshold", strategyIndex, path, slot },
1575
+ values: values,
1576
+ });
1535
1577
  /** Sweep RankSignal (Action scope) over a value set. */
1536
1578
  export const geneRankSignal = (strategyIndex, values) => ({
1537
1579
  field: "RankSignal",
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "nexustrade",
3
- "version": "1.10.0",
3
+ "version": "1.11.0",
4
4
  "description": "Typed TypeScript SDK for NexusTrade portfolio authoring, backtesting, and optimization",
5
5
  "license": "MIT",
6
6
  "author": "Starks Technology",