oakscriptjs 0.8.2 → 0.9.1

package/src/callsite/index.ts

@@ -0,0 +1,178 @@
+/**
+ * @fileoverview Per-call history of ta.* functions called in a conditional block.
+ *
+ * In PineScript, every ta.* call keeps its own history of the values it receives. A call inside
+ * an `if` block receives values only on the bars where the block runs, so its history skips the
+ * other bars: `ta.crossover(a, b)` is false on the first bar the block runs, and `ta.sma(x, 3)`
+ * averages the last 3 values it received, not the last 3 bars.
+ *
+ * - {@link whenCalled}: vectorized, when the bars of the calls are known in advance.
+ * - {@link crossover} / {@link crossunder} / {@link cross} / {@link barssince}: one stateful call site for bar
+ *   loops, called only on the bars where the Pine call runs.
+ * - {@link lowest} / {@link highest}: `ta.lowest` / `ta.highest` with a series length (a different length on each
+ *   call), which PineScript computes with a state kept between calls.
+ *
+ * Since PineScript v6, `and` / `or` are lazy: the right operand runs only when the left operand does not decide
+ * the result. A ta.* call in the right operand of `a or b` runs on the bars where `a` is false, in `a and b` on the
+ * bars where `a` is true, so it needs a call site too:
+ *
+ * ```typescript
+ * // Pine:  longCond = longUp or (src > sig and ta.barssince(longUp) <= lookback)
+ * const since = callsite.whenCalled(longUp.map((u, i) => !u && src[i] > sig[i]), (c) => taCore.barssince(c.map(Boolean)), longUp);
+ * // ta.barssince(longUp) only runs where longUp is false: it never sees true and stays na
+ * ```
+ *
+ * ```typescript
+ * // Pine:  if inRange
+ * //            buy = ta.crossover(cumRsi, 60)
+ * const buy = callsite.whenCalled(inRange, (a) => taCore.crossover(a, a.map(() => 60)), cumRsi);
+ *
+ * // Same call in a bar loop
+ * const buyCross = callsite.crossover();
+ * for (let i = 0; i < n; i++) {
+ *   if (inRange[i]) {
+ *     const buy = buyCross(cumRsi[i], 60);
+ *   }
+ * }
+ * ```
+ *
+ * @module callsite
+ */
+
+import type { Source } from '../types/index.js';
+
+/**
+ * Runs `fn` on the bars where `called` is true only, like a ta.* call inside an `if` block.
+ * `fn` receives the values of `sources` on those bars, in order; its results are placed back on
+ * the same bars. The other bars get na (NaN).
+ *
+ * @param called - true (or non-zero) on the bars where the call runs
+ * @param fn - the calculation, for example `(x) => taCore.sma(x, 3)`
+ * @param sources - the arguments of the call, one value per chart bar
+ */
+export function whenCalled<T extends number | boolean>(
+  called: ArrayLike<boolean | number>,
+  fn: (...values: number[][]) => ArrayLike<T>,
+  ...sources: Source[]
+): Array<T | number> {
+  const bars: number[] = [];
+  for (let i = 0; i < called.length; i++) if (called[i]) bars.push(i);
+  const result = fn(...sources.map(s => bars.map(i => s[i] ?? NaN)));
+  const out = new Array<T | number>(called.length).fill(NaN);
+  bars.forEach((bar, k) => {
+    out[bar] = result[k]!;
+  });
+  return out;
+}
+
+/** A call site that keeps the two previous arguments (na before the first call). */
+function twoSeriesSite(test: (a: number, b: number, prevA: number, prevB: number) => boolean) {
+  let prevA = NaN;
+  let prevB = NaN;
+  return (a: number, b: number): boolean => {
+    const result = test(a, b, prevA, prevB);
+    prevA = a;
+    prevB = b;
+    return result;
+  };
+}
+
+/** One `ta.crossover(a, b)` call site: false on its first call, as its history is na. */
+export function crossover(): (a: number, b: number) => boolean {
+  return twoSeriesSite((a, b, pa, pb) => a > b && pa <= pb);
+}
+
+/** One `ta.crossunder(a, b)` call site: false on its first call, as its history is na. */
+export function crossunder(): (a: number, b: number) => boolean {
+  return twoSeriesSite((a, b, pa, pb) => a < b && pa >= pb);
+}
+
+/**
+ * One `ta.barssince(condition)` call site: the number of calls since the condition was true on a call (0 on that
+ * call), na before the first true condition. An na condition counts as false.
+ */
+export function barssince(): (condition: boolean | number) => number {
+  let count = NaN;
+  return (condition) => {
+    if (condition && !Number.isNaN(condition)) count = 0;
+    else if (!Number.isNaN(count)) count++;
+    return count;
+  };
+}
+
+/** One `ta.cross(a, b)` call site: false on its first call, as its history is na. */
+export function cross(): (a: number, b: number) => boolean {
+  return twoSeriesSite((a, b, pa, pb) => (a > b && pa <= pb) || (a < b && pa >= pb));
+}
+
+/** One `ta.lowest` / `ta.highest` call site with a series length; rules in {@link lowest}. */
+function extremeSite(isLowest: boolean): (value: number, length: number) => number {
+  const better = isLowest ? (a: number, b: number) => a < b : (a: number, b: number) => a > b;
+  const values: number[] = [];
+  let extreme = NaN;
+  let extremeAt = -1;
+  let prevLength = NaN;
+  const keep = (v: number, at: number) => {
+    extreme = v;
+    extremeAt = at;
+  };
+  const rescan = (i: number, length: number) => {
+    extreme = NaN;
+    for (let b = i; b > i - length && b >= 0; b--) {
+      const v = values[b]!;
+      if (!Number.isNaN(v) && (Number.isNaN(extreme) || !better(extreme, v))) keep(v, b);
+    }
+  };
+  return (value, length) => {
+    const i = values.length;
+    values.push(value);
+    if (Number.isNaN(value)) {
+      extreme = NaN;
+      prevLength = length;
+      return NaN;
+    }
+    if (length > prevLength) {
+      const from = Math.max(0, i - length + 1);
+      const to = Math.max(0, i - prevLength + 1);
+      if (values.slice(from, to).some(Number.isNaN)) keep(value, i);
+      else {
+        for (let b = from; b < to; b++) if (Number.isNaN(extreme) || better(values[b]!, extreme)) keep(values[b]!, b);
+        if (Number.isNaN(extreme) || better(value, extreme)) keep(value, i);
+      }
+    } else if (length < prevLength || Number.isNaN(extreme) || i - extremeAt >= length) rescan(i, length);
+    else if (better(value, extreme)) keep(value, i);
+    prevLength = length;
+    return i < length - 1 ? NaN : extreme;
+  };
+}
+
+/**
+ * One `ta.lowest(source, length)` call site with a series length (a different length on each call), called with
+ * `(value, length)`.
+ *
+ * PineScript rules (measured with a length that changes on each bar):
+ * - the extreme is kept with its bar; a new value that passes it replaces it; when the kept extreme is `length`
+ *   calls old, the last `length` values are scanned again (na skipped, the oldest wins a tie)
+ * - a length smaller than on the previous call: the last `length` values are scanned again
+ * - a length larger than on the previous call: the values that enter the window at its old end are compared with the
+ *   extreme; when one of them is na, the extreme restarts from the current value (the values in between are not read)
+ * - an na value gives na and resets the extreme; na before call `length - 1`
+ *
+ * @example
+ * ```typescript
+ * // Pine:  lowPrice = ta.lowest(close[1], lookback)   // lookback changes per bar
+ * const lowPrice = callsite.lowest();
+ * const out = closes.map((_, i) => lowPrice(i > 0 ? closes[i - 1]! : NaN, lookback[i]!));
+ * ```
+ */
+export function lowest(): (value: number, length: number) => number {
+  return extremeSite(true);
+}
+
+/**
+ * One `ta.highest(source, length)` call site with a series length (a different length on each call), called with
+ * `(value, length)`. Same rules as {@link lowest}.
+ */
+export function highest(): (value: number, length: number) => number {
+  return extremeSite(false);
+}

package/src/chartpoint/index.ts

@@ -0,0 +1,126 @@
+/**
+ * Chart Point namespace
+ * Functions for creating and manipulating chart point objects.
+ *
+ * @remarks
+ * Chart points represent specific locations on a chart with time, index, and price coordinates.
+ * They are primarily used with polylines and other drawing objects that require multiple points.
+ *
+ * @version 6
+ */
+
+import type { ChartPoint } from '../types/index.js';
+
+// Re-export the ChartPoint type for convenience
+export type { ChartPoint };
+
+/**
+ * Creates a new chart point with all coordinates.
+ *
+ * @param time - UNIX timestamp in milliseconds (or null if using bar index)
+ * @param index - Bar index (or null if using time)
+ * @param price - Y-axis price value
+ * @returns New ChartPoint object
+ *
+ * @remarks
+ * Creates a chart point that can be used with polylines and other multi-point drawing objects.
+ * Typically, you would provide either time or index, not both, depending on the xloc mode.
+ *
+ * @example
+ * ```typescript
+ * // Create a point with both time and index
+ * const point = chartPoint.new(1609459200000, 100, 150.5);
+ *
+ * // Create a point with only index
+ * const indexPoint = chartPoint.new(null, 50, 200);
+ *
+ * // Create a point with only time
+ * const timePoint = chartPoint.new(1609459200000, null, 175);
+ * ```
+ */
+export function new_point(
+  time: number | null,
+  index: number | null,
+  price: number
+): ChartPoint {
+  return {
+    time,
+    index,
+    price,
+  };
+}
+
+/**
+ * Creates a chart point from time and price.
+ *
+ * @param time - UNIX timestamp in milliseconds
+ * @param price - Y-axis price value
+ * @returns New ChartPoint object with index set to null
+ *
+ * @remarks
+ * Convenience function for creating points when using xloc.bar_time mode.
+ *
+ * @example
+ * ```typescript
+ * // Create a point using timestamp
+ * const point = chartPoint.from_time(1609459200000, 150.5);
+ * ```
+ */
+export function from_time(time: number, price: number): ChartPoint {
+  return {
+    time,
+    index: null,
+    price,
+  };
+}
+
+/**
+ * Creates a chart point from bar index and price.
+ *
+ * @param index - Bar index
+ * @param price - Y-axis price value
+ * @returns New ChartPoint object with time set to null
+ *
+ * @remarks
+ * Convenience function for creating points when using xloc.bar_index mode.
+ *
+ * @example
+ * ```typescript
+ * // Create a point using bar index
+ * const point = chartPoint.from_index(50, 150.5);
+ * ```
+ */
+export function from_index(index: number, price: number): ChartPoint {
+  return {
+    time: null,
+    index,
+    price,
+  };
+}
+
+/**
+ * Creates a copy of a chart point.
+ *
+ * @param point - ChartPoint to copy
+ * @returns New ChartPoint object with same values
+ *
+ * @remarks
+ * Creates a shallow copy of the chart point. Since ChartPoint is immutable (readonly properties),
+ * this creates an independent copy.
+ *
+ * @example
+ * ```typescript
+ * const original = chartPoint.from_index(10, 100);
+ * const copied = chartPoint.copy(original);
+ * ```
+ */
+export function copy(point: ChartPoint): ChartPoint {
+  return {
+    time: point.time,
+    index: point.index,
+    price: point.price,
+  };
+}
+
+// Alias to match PineScript API (chart.point.new)
+export { new_point as new };

package/src/color/index.ts

@@ -0,0 +1,389 @@
+/**
+ * Color namespace
+ * Mirrors PineScript's color.* functions for color creation and manipulation.
+ *
+ * @remarks
+ * All color functions in this namespace follow PineScript v6 API specifications.
+ * Colors are represented as RGB or RGBA strings.
+ * Transparency values range from 0 (fully opaque) to 100 (fully transparent).
+ *
+ * @version 6
+ */
+
+import type { color, int, float, simple_int, simple_float } from '../types/index.js';
+import { alphaByte, parseColor } from './parse.js';
+
+/** Channel of color.rgb: na is 0, a fraction is truncated. */
+const channel = (v: number): int =>
+  v === null || v === undefined || Number.isNaN(v) ? 0 : Math.max(0, Math.min(255, Math.trunc(v)));
+
+/**
+ * Alpha (0-1) of a transparency given to color.rgb / color.new: na is fully transparent, clamped to 0..100.
+ * `1 - t / 100` as in PineScript: `color.new(c, 90)` has the alpha byte 25 (0.09999999999999998 * 255 rounded).
+ */
+const alphaOf = (transp: number): float =>
+  transp === null || Number.isNaN(transp) ? 0 : 1 - Math.max(0, Math.min(100, transp)) / 100;
+
+/**
+ * Creates a color from RGB values with optional transparency.
+ *
+ * @param red - Red component (0-255, values are clamped)
+ * @param green - Green component (0-255, values are clamped)
+ * @param blue - Blue component (0-255, values are clamped)
+ * @param transp - Optional transparency (0-100). 0 = opaque, 100 = fully transparent
+ * @returns Color string in rgb() or rgba() format
+ *
+ * @remarks
+ * - RGB values are automatically clamped to the 0-255 range
+ * - Transparency of 0 or omitted results in rgb() format
+ * - Transparency > 0 results in rgba() format
+ * - Transparency is converted to alpha channel (0-1 range)
+ *
+ * PineScript rules:
+ * - an `na` channel is 0; a fractional channel is truncated (127.6 is 127)
+ * - the transparency is clamped to 0..100 (140 is fully transparent, -5 is opaque); an `na` transparency is fully
+ *   transparent
+ *
+ * @example
+ * ```typescript
+ * color.rgb(255, 0, 0) // Returns: "rgb(255, 0, 0)" - Red
+ * color.rgb(0, 255, 0, 50) // Returns: "rgba(0, 255, 0, 0.5)" - Semi-transparent green
+ * color.rgb(300, 0, 0) // Returns: "rgb(255, 0, 0)" - Clamped to 255
+ * ```
+ */
+export function rgb(red: simple_int, green: simple_int, blue: simple_int, transp?: simple_float): string {
+  const r = channel(red);
+  const g = channel(green);
+  const b = channel(blue);
+  const a = transp !== undefined ? alphaOf(transp) : 1;
+
+  if (a === 1) {
+    return `rgb(${r}, ${g}, ${b})`;
+  }
+  return `rgba(${r}, ${g}, ${b}, ${a})`;
+}
+
+/**
+ * Creates a color from a hexadecimal string with optional transparency.
+ *
+ * @param hex - Hex color string (with or without '#' prefix, e.g., "#FF0000" or "FF0000")
+ * @param transp - Optional transparency (0-100). 0 = opaque, 100 = fully transparent
+ * @returns Color string in rgb() or rgba() format
+ *
+ * @remarks
+ * - Accepts hex strings with or without '#' prefix
+ * - Case-insensitive (accepts both "FF0000" and "ff0000")
+ * - Must be 6 characters (excluding '#')
+ * - Format: RRGGBB where each component is 00-FF
+ *
+ * @example
+ * ```typescript
+ * color.from_hex("#FF0000") // Returns: "rgb(255, 0, 0)" - Red
+ * color.from_hex("00FF00", 50) // Returns: "rgba(0, 255, 0, 0.5)" - Semi-transparent green
+ * color.from_hex("#0000FF") // Returns: "rgb(0, 0, 255)" - Blue
+ * color.from_hex("FFA500") // Returns: "rgb(255, 165, 0)" - Orange
+ * ```
+ */
+export function from_hex(hex: string, transp?: simple_float): string {
+  // Remove # if present
+  hex = hex.replace('#', '');
+
+  const r = parseInt(hex.substring(0, 2), 16);
+  const g = parseInt(hex.substring(2, 4), 16);
+  const b = parseInt(hex.substring(4, 6), 16);
+
+  return rgb(r, g, b, transp);
+}
+
+/**
+ * Creates a new color with modified transparency, preserving RGB components.
+ *
+ * @param baseColor - The base color to modify
+ * @param transp - New transparency value (0-100). 0 = opaque, 100 = fully transparent
+ * @returns New color with updated transparency
+ *
+ * @remarks
+ * - Preserves the RGB values from the base color
+ * - Replaces the transparency with the new value
+ * - Useful for creating semi-transparent versions of existing colors
+ * - PineScript clamps the transparency to 0..100 (`color.new(c, 140)` is fully transparent, `color.new(c, -5)` is
+ *   opaque); an `na` transparency is fully transparent
+ *
+ * @example
+ * ```typescript
+ * const red = color.rgb(255, 0, 0)
+ * color.new_color(red, 50) // Returns: "rgba(255, 0, 0, 0.5)" - Semi-transparent red
+ * color.new_color(red, 0) // Returns: "rgb(255, 0, 0)" - Fully opaque
+ * color.new_color(red, 100) // Returns: "rgba(255, 0, 0, 0)" - Fully transparent
+ * ```
+ */
+export function new_color(baseColor: color, transp: simple_float): string {
+  // Parse the color and apply transparency
+  const rgba = parseColor(baseColor);
+  return rgb(rgba.r, rgba.g, rgba.b, transp);
+}
+
+/**
+ * Extracts the red component from a color.
+ *
+ * @param clr - The color to extract from
+ * @returns Red component value (0-255)
+ *
+ * @example
+ * ```typescript
+ * color.r(color.rgb(255, 128, 64)) // Returns: 255
+ * color.r(color.from_hex("#FF0000")) // Returns: 255
+ * color.r(color.from_hex("#FFA500")) // Returns: 255 (orange)
+ * ```
+ */
+export function r(clr: color): int {
+  return parseColor(clr).r;
+}
+
+/**
+ * Extracts the green component from a color.
+ *
+ * @param clr - The color to extract from
+ * @returns Green component value (0-255)
+ *
+ * @example
+ * ```typescript
+ * color.g(color.rgb(255, 128, 64)) // Returns: 128
+ * color.g(color.from_hex("#00FF00")) // Returns: 255
+ * color.g(color.from_hex("#FFA500")) // Returns: 165 (orange)
+ * ```
+ */
+export function g(clr: color): int {
+  return parseColor(clr).g;
+}
+
+/**
+ * Extracts the blue component from a color.
+ *
+ * @param clr - The color to extract from
+ * @returns Blue component value (0-255)
+ *
+ * @example
+ * ```typescript
+ * color.b(color.rgb(255, 128, 64)) // Returns: 64
+ * color.b(color.from_hex("#0000FF")) // Returns: 255
+ * color.b(color.from_hex("#FFA500")) // Returns: 0 (orange)
+ * ```
+ */
+export function b(clr: color): int {
+  return parseColor(clr).b;
+}
+
+/**
+ * Extracts the transparency component from a color.
+ *
+ * @param clr - The color to extract from
+ * @returns Transparency value (0-100). 0 = fully opaque, 100 = fully transparent
+ *
+ * @remarks
+ * - Returns 0 for colors without transparency (rgb format)
+ * - Converts alpha channel (0-1) to transparency (0-100)
+ * - PineScript stores the alpha as a byte (0-255) and returns an integer transparency:
+ *   `color.t(color.new(c, 33.3))` is 33
+ *
+ * @example
+ * ```typescript
+ * color.t(color.rgb(255, 0, 0)) // Returns: 0 (opaque)
+ * color.t(color.rgb(255, 0, 0, 50)) // Returns: 50
+ * color.t(color.rgb(255, 0, 0, 100)) // Returns: 100 (fully transparent)
+ * ```
+ */
+export function t(clr: color): float {
+  return Math.round((1 - alphaByte(parseColor(clr).a) / 255) * 100);
+}
+
+// Predefined color constants of PineScript v6.
+// PineScript v5 differs for red (#FF5252), teal (#00897B) and yellow (#FFEB3B).
+/**
+ * Aqua/Cyan color constant
+ * @constant {string} #00BCD4 - RGB(0, 188, 212)
+ */
+export const aqua = '#00BCD4';
+
+/**
+ * Black color constant
+ * @constant {string} #363A45 - RGB(54, 58, 69)
+ */
+export const black = '#363A45';
+
+/**
+ * Blue color constant
+ * @constant {string} #2962FF - RGB(41, 98, 255)
+ */
+export const blue = '#2962FF';
+
+/**
+ * Fuchsia/Magenta color constant
+ * @constant {string} #E040FB - RGB(224, 64, 251)
+ */
+export const fuchsia = '#E040FB';
+
+/**
+ * Gray color constant
+ * @constant {string} #787B86 - RGB(120, 123, 134)
+ */
+export const gray = '#787B86';
+
+/**
+ * Green color constant (same as lime)
+ * @constant {string} #4CAF50 - RGB(76, 175, 80)
+ */
+export const green = '#4CAF50';
+
+/**
+ * Lime color constant (same as green)
+ * @constant {string} #00E676 - RGB(0, 230, 118)
+ */
+export const lime = '#00E676';
+
+/**
+ * Maroon color constant
+ * @constant {string} #880E4F - RGB(136, 14, 79)
+ */
+export const maroon = '#880E4F';
+
+/**
+ * Navy color constant
+ * @constant {string} #311B92 - RGB(49, 27, 146)
+ */
+export const navy = '#311B92';
+
+/**
+ * Olive color constant
+ * @constant {string} #808000 - RGB(128, 128, 0)
+ */
+export const olive = '#808000';
+
+/**
+ * Orange color constant
+ * @constant {string} #FF9800 - RGB(255, 152, 0)
+ */
+export const orange = '#FF9800';
+
+/**
+ * Purple color constant
+ * @constant {string} #9C27B0 - RGB(156, 39, 176)
+ */
+export const purple = '#9C27B0';
+
+/**
+ * Red color constant
+ * @constant {string} #F23645 - RGB(242, 54, 69)
+ */
+export const red = '#F23645';
+
+/**
+ * Silver color constant
+ * @constant {string} #B2B5BE - RGB(178, 181, 190)
+ */
+export const silver = '#B2B5BE';
+
+/**
+ * Teal color constant
+ * @constant {string} #089981 - RGB(8, 153, 129)
+ */
+export const teal = '#089981';
+
+/**
+ * White color constant
+ * @constant {string} #FFFFFF - RGB(255, 255, 255)
+ */
+export const white = '#FFFFFF';
+
+/**
+ * Yellow color constant
+ * @constant {string} #FDD835 - RGB(253, 216, 53)
+ */
+export const yellow = '#FDD835';
+
+/**
+ * Creates a color from a gradient based on value position.
+ *
+ * @param value - Value to calculate position-dependent color
+ * @param bottom_value - Bottom position value corresponding to bottom_color
+ * @param top_value - Top position value corresponding to top_color
+ * @param bottom_color - Bottom position color
+ * @param top_color - Top position color
+ * @returns Color calculated from linear gradient
+ *
+ * @remarks
+ * PineScript rules:
+ * - If value <= bottom_value, returns bottom_color; else if value >= top_value, returns top_color
+ * - An inverted range (bottom_value > top_value) returns bottom_color, wherever the value is
+ * - Otherwise the colours are mixed with their transparency (premultiplied alpha, alpha as a byte); the RGB channels
+ *   and the alpha are truncated. PineScript's float rounding order is not known: a channel can differ by 1 when the
+ *   exact result is an integer (same RGB at both ends)
+ * - An na value or bottom_value / top_value, or bottom_value == top_value, gives a fully transparent colour
+ * - An na colour counts as fully transparent
+ * - Works with rgb(), rgba() and hex (#RRGGBB, #RRGGBBAA) colours
+ *
+ * @example
+ * ```typescript
+ * // Value at middle of range gets middle color
+ * const midColor = color.from_gradient(50, 0, 100,
+ *   color.rgb(255, 0, 0),    // Red at bottom
+ *   color.rgb(0, 255, 0)      // Green at top
+ * ); // Returns color between red and green
+ *
+ * // Value at extremes
+ * const lowColor = color.from_gradient(-10, 0, 100, red, green); // Returns red
+ * const highColor = color.from_gradient(150, 0, 100, red, green); // Returns green
+ * ```
+ */
+export function from_gradient(
+  value: float,
+  bottom_value: float,
+  top_value: float,
+  bottom_color: color,
+  top_color: color
+): string {
+  const transparent = 'rgba(0, 0, 0, 0)';
+  if ([value, bottom_value, top_value].some((v) => v === null || v === undefined || Number.isNaN(v)) || bottom_value === top_value) {
+    return transparent;
+  }
+  const k =
+    value <= bottom_value || bottom_value > top_value
+      ? 0
+      : value >= top_value
+        ? 1
+        : (value - bottom_value) / (top_value - bottom_value);
+  // alpha as a byte (0-255), as PineScript stores it; an na colour (null / undefined) is fully transparent
+  const rgba = (c: color) => {
+    if (c === null || c === undefined) return { r: 0, g: 0, b: 0, a: 0 };
+    const p = parseColor(c);
+    return { r: p.r, g: p.g, b: p.b, a: alphaByte(p.a) };
+  };
+  const c1 = rgba(bottom_color);
+  const c2 = rgba(top_color);
+  const a = c1.a * (1 - k) + c2.a * k;
+  if (a === 0) return transparent;
+  // operation order with the fewest differences to PineScript (channels as 0-1, alpha as a byte)
+  const mix = (x1: number, x2: number) => Math.floor((((x1 / 255) * c1.a) * (1 - k) + ((x2 / 255) * c2.a) * k) / (a / 255));
+  const [r, g, b] = [mix(c1.r, c2.r), mix(c1.g, c2.g), mix(c1.b, c2.b)];
+  const alpha = Math.floor(a);
+  return alpha === 255 ? `rgb(${r}, ${g}, ${b})` : `rgba(${r}, ${g}, ${b}, ${alpha / 255})`;
+}
+
+/**
+ * Alias for new_color function.
+ * Creates a new color with specified transparency from an existing color.
+ *
+ * @param baseColor - The base color
+ * @param transp - Transparency value (0-100). 0 = fully opaque, 100 = fully transparent
+ * @returns New color with applied transparency
+ *
+ * @remarks
+ * This is an alias for `new_color()` to match PineScript's `color.new()` syntax.
+ *
+ * @example
+ * ```typescript
+ * const redColor = color.rgb(255, 0, 0);
+ * const transparentRed = color.new(redColor, 50); // 50% transparent red
+ * ```
+ */
+export { new_color as new };