refactor(transform): rename Transformer to Transform and fluent API 👋

- Document setWeekStartDay, toTimeframe options, Validator and Time constants in README
- Export Transform and Validator from index; remove Transformer export
- Add Transform with fromCandles, setAnchorTime, toTimeframe, setWeekStartDay and execute options
- Add tests for 1W/1Mc, setWeekStartDay, validation option, and rename from/anchor/to
- Remove Transformer.ts
- Update README examples and API reference to new method names

Author: NeaByteLab

README.md

@@ -10,9 +10,10 @@ High-precision OHLC transformation with strict anchor time alignment.
 
 ## Features
 
-- **Strict Anchor Alignment**: Ensures candles align with specific sessions (e.g., 4h at 23:00 or 23:30 UTC).
 - **High Performance**: Batch processing optimized for thousands of candles at once.
-- **Flexible Timeframes**: Supports `m`, `h`, `d`, `w`, `M` (e.g. `15m`, `4h`, `1d`, `1w`, `1M`).
+- **Strict Anchor Alignment**: Ensures candles align with specific sessions (e.g., 4h at 23:00 or 23:30 UTC).
+- **Flexible Timeframes**: Supports `m`, `h`, `d`, `w`, `M` (fixed) and `1W` (calendar week), `1Mc` (calendar month).
+- **Input validation**: Optional `validate: true` to check time, OHLC, duplicates, and order before transform.
 
 ## Installation
 
@@ -42,62 +43,85 @@ const data = [
 ]
 
 // Convert to 4-hour chart (Default Anchor 23:00 UTC)
-const h4 = Transform.from(data).to('4h')
+const h4 = Transform.fromCandles(data).toTimeframe('4h')
 console.log(h4) // Output: [ { time: 1704063600000, open: 1, high: 2, low: 0.5, close: 1.5, ... }, ... ]
 
 // Convert to 1-day chart with custom anchor (e.g., 00:00 UTC)
-const daily = Transform.from(data).anchor(0).to('1d')
+const daily = Transform.fromCandles(data).setAnchorTime(0).toTimeframe('1d')
 
 // Anchor with hour and minute (e.g., 23:30 UTC)
-const session = Transform.from(data).anchor(23, 30).to('4h')
+const session = Transform.fromCandles(data).setAnchorTime(23, 30).toTimeframe('4h')
+
+// Calendar week (Monday start) and calendar month
+const weekly = Transform.fromCandles(data).toTimeframe('1W')
+const monthly = Transform.fromCandles(data).toTimeframe('1Mc')
+
+// Optional validation before transform
+const safe = Transform.fromCandles(data).toTimeframe('4h', { validate: true })
 ```
 
 ## API Reference
 
-### Transform.from
+### Transform.fromCandles
 
 ```typescript
-Transform.from(data)
+Transform.fromCandles(data)
 ```
 
 - `data` `<CandleData[]>`: Array of source OHLC candles
 - Returns: `Transform`
 - Description: Creates a transformation instance for fluent chaining.
 
-### Transform.prototype.anchor
+### Transform.prototype.setAnchorTime
 
 ```typescript
-transform.anchor(hour, minute)
+transform.setAnchorTime(hour, minute)
 ```
 
 - `hour` `<number>`: Anchor hour in UTC (0–23). Defaults to `23`.
 - `minute` `<number>`: (Optional) Anchor minute (0–59). Defaults to `0`.
 - Returns: `this`
 - Description: Sets the anchor time for bucket alignment (e.g. 23:30 UTC).
 
-### Transform.prototype.to
+### Transform.prototype.toTimeframe
 
 ```typescript
-transform.to(timeframe)
+transform.toTimeframe(timeframe, options)
 ```
 
-- `timeframe` `<string>`: Target timeframe (e.g. `'15m'`, `'4h'`, `'1d'`, `'1w'`, `'1M'`).
+- `timeframe` `<string>`: Target (e.g. `'4h'`, `'1d'`, `'1W'`, `'1Mc'`).
+- `options` `<object>`: (Optional) `{ validate?: boolean }` — run input validation before transform.
 - Returns: `CandleData[]`
 - Description: Runs the transformation and returns aggregated candles.
 
+### Transform.prototype.setWeekStartDay
+
+```typescript
+transform.setWeekStartDay(weekStartDay)
+```
+
+- `weekStartDay` `<number>`: Week start (0=Sun, 1=Mon, …, 6=Sat). Default `1` (Monday). Used for `'1W'`.
+- Returns: `this`
+- Description: Sets week start day for calendar week timeframe.
+
 ### Transform.execute
 
 ```typescript
-Transform.execute(candles, timeframe, anchorHour, anchorMinute)
+Transform.execute(candles, timeframe, anchorHour, anchorMinute, options)
 ```
 
 - `candles` `<CandleData[]>`: Source candle array
-- `timeframe` `<string>`: Target timeframe (e.g. `'4h'`, `'1d'`)
+- `timeframe` `<string>`: Target (e.g. `'4h'`, `'1d'`, `'1W'`, `'1Mc'`)
 - `anchorHour` `<number>`: (Optional) Anchor hour (0–23). Defaults to `23`.
 - `anchorMinute` `<number>`: (Optional) Anchor minute (0–59). Defaults to `0`.
+- `options` `<object>`: (Optional) `{ weekStartDay?: 0|1|…|6, validate?: boolean }`
 - Returns: `CandleData[]`
 - Description: Runs batch transformation without a fluent instance.
 
+### Time (constants)
+
+Static readonly: `msPerMinute`, `msPerHour`, `msPerDay`, `msPerWeek`, `msPerMonth` (milliseconds per unit), `defaultAnchorOffset` (23h in ms).
+
 ### Time.alignTime
 
 ```typescript
@@ -111,19 +135,43 @@ Time.alignTime(timestamp, intervalMs, anchorHour, anchorMinute)
 - Returns: `number`
 - Description: Aligns timestamp to the bucket open time on the anchor grid.
 
+### Time.getBucketStart
+
+```typescript
+Time.getBucketStart(timestamp, timeframe, anchorHour, anchorMinute, weekStartDay)
+```
+
+- `timestamp` `<number>`: Input time in ms
+- `timeframe` `<string>`: e.g. `'4h'`, `'1d'`, `'1W'`, `'1Mc'`
+- `anchorHour` / `anchorMinute`: Used for fixed intervals only
+- `weekStartDay` `<number>`: (Optional) 0–6 for `'1W'`. Default `1` (Monday)
+- Returns: `number`
+- Description: Bucket start for any timeframe (fixed or calendar).
+
 ### Time.parseTimeframe
 
 ```typescript
-Time.parseTimeframe(tf)
+Time.parseTimeframe(timeframeStr)
 ```
 
-- `tf` `<string>`: Timeframe string (e.g. `'15m'`, `'4h'`, `'1d'`, `'1w'`, `'1M'`)
+- `timeframeStr` `<string>`: Fixed timeframe only (e.g. `'15m'`, `'4h'`, `'1d'`, `'1w'`, `'1M'`). Use `Time.getBucketStart` for `'1W'` / `'1Mc'`.
 - Returns: `number`
 - Description: Parses timeframe string to duration in milliseconds.
 
+### Validator.validateCandles
+
+```typescript
+Validator.validateCandles(candles, options)
+```
+
+- `candles` `<CandleData[]>`: Array to validate
+- `options` `<object>`: (Optional) `{ allowDuplicates?, allowUnordered?, strictOHLC? }`
+- Returns: `{ valid: boolean, errors: string[] }`
+- Description: Validates time (finite, non-negative), OHLC, duplicates, and order.
+
 ## Note
 
-- `1w` = 7 days; `1M` = 30-day period (fixed length, not calendar month).
+- `1w` = 7 days (fixed); `1M` = 30-day period (fixed). `1W` = calendar week (default Monday); `1Mc` = calendar month (first of month UTC). Validation is opt-in via `toTimeframe(..., { validate: true })` or `Transform.execute(..., { validate: true })`.
 
 ## License
 

src/Transformer.ts src/Transform.tssrc/Transformer.ts renamed to src/Transform.ts

@@ -1,5 +1,6 @@
-import type { CandleData, TimeframeStr } from '@app/Types.ts'
+import type * as Types from '@app/Types.ts'
 import { Time } from '@app/Time.ts'
+import { Validator } from '@app/Validator.ts'
 
 /**
  * OHLC timeframe transform with anchor alignment.
@@ -11,7 +12,9 @@ export class Transform {
   /** Anchor minute (0-59) */
   private anchorMinute = 0
   /** Source candles data */
-  private sourceData: CandleData[]
+  private sourceData: Types.CandleData[]
+  /** Week start for 1W (0-6), default 1 (Monday) */
+  private weekStartDay: Types.CalendarWeekStart = 1
 
   /**
    * Sets anchor time (hour and optional minute).
@@ -20,7 +23,7 @@ export class Transform {
    * @param minute - Minute between 0-59, default 0
    * @returns Current instance
    */
-  anchor(hour: number, minute = 0): this {
+  setAnchorTime(hour: number, minute = 0): this {
     if (hour < 0 || hour > 23) {
       throw new Error('Anchor hour must be between 0 and 23')
     }
@@ -37,34 +40,48 @@ export class Transform {
    * @description Initializes with source candle data.
    * @param data - Input candle array
    */
-  constructor(data: CandleData[]) {
+  constructor(data: Types.CandleData[]) {
     this.sourceData = data
   }
 
   /**
    * Runs batch transformation.
    * @description Aggregates candles to target timeframe and anchor.
    * @param candles - Source data array
-   * @param timeframe - Target timeframe string
+   * @param timeframe - Target timeframe (e.g. 4h, 1d, 1W, 1Mc)
    * @param anchorHour - Alignment anchor hour (0-23)
    * @param anchorMinute - Alignment anchor minute (0-59), default 0
+   * @param options - Optional: weekStartDay (for 1W), validate
    * @returns Transformed candle array
    */
   static execute(
-    candles: CandleData[],
-    timeframe: TimeframeStr,
+    candles: Types.CandleData[],
+    timeframe: Types.TimeframeStr,
     anchorHour = 23,
-    anchorMinute = 0
-  ): CandleData[] {
+    anchorMinute = 0,
+    options?: { weekStartDay?: Types.CalendarWeekStart; validate?: boolean }
+  ): Types.CandleData[] {
     if (candles.length === 0) {
       return []
     }
-    const intervalMs = Time.parseTimeframe(timeframe)
-    const results: CandleData[] = []
-    let currentCandle: CandleData | null = null
+    if (options?.validate) {
+      const result = Validator.validateCandles(candles, { allowUnordered: true })
+      if (!result.valid) {
+        throw new Error(`Validation failed: ${result.errors.join('; ')}`)
+      }
+    }
+    const weekStart = options?.weekStartDay ?? 1
+    const results: Types.CandleData[] = []
+    let currentCandle: Types.CandleData | null = null
     const sortedCandles = [...candles].sort((a, b) => a.time - b.time)
     for (const candle of sortedCandles) {
-      const bucketStart = Time.alignTime(candle.time, intervalMs, anchorHour, anchorMinute)
+      const bucketStart = Time.getBucketStart(
+        candle.time,
+        timeframe,
+        anchorHour,
+        anchorMinute,
+        weekStart
+      )
       if (!currentCandle) {
         currentCandle = {
           time: bucketStart,
@@ -107,17 +124,32 @@ export class Transform {
    * @param data - Input candle array
    * @returns New Transform instance
    */
-  static from(data: CandleData[]): Transform {
+  static fromCandles(data: Types.CandleData[]): Transform {
     return new Transform(data)
   }
 
+  /**
+   * Sets week start day for 1W (calendar week).
+   * @description 0=Sun, 1=Mon, etc. Default 1.
+   * @param weekStartDay - Day of week (0-6)
+   * @returns Current instance
+   */
+  setWeekStartDay(weekStartDay: Types.CalendarWeekStart): this {
+    this.weekStartDay = weekStartDay
+    return this
+  }
+
   /**
    * Runs transformation and returns candles.
    * @description Aggregates to target timeframe with current anchor.
-   * @param timeframe - Target timeframe string
+   * @param timeframe - Target timeframe string (e.g. 4h, 1W, 1Mc)
+   * @param options - Optional: validate
    * @returns Resulting candle array
    */
-  to(timeframe: TimeframeStr): CandleData[] {
-    return Transform.execute(this.sourceData, timeframe, this.anchorHour, this.anchorMinute)
+  toTimeframe(timeframe: Types.TimeframeStr, options?: { validate?: boolean }): Types.CandleData[] {
+    return Transform.execute(this.sourceData, timeframe, this.anchorHour, this.anchorMinute, {
+      weekStartDay: this.weekStartDay,
+      ...(options?.validate !== undefined ? { validate: options.validate } : {})
+    })
   }
 }

src/index.ts

@@ -3,5 +3,6 @@
  * @description Exports all public modules.
  */
 export type * from '@app/Types.ts'
-export * from '@app/Transformer.ts'
+export * from '@app/Transform.ts'
 export * from '@app/Time.ts'
+export * from '@app/Validator.ts'