Skip to content

Commit

Permalink
Update v3 migration guide in ObsoleteV3.md
Browse files Browse the repository at this point in the history 
* Add a summary of all technical changes to the public API.
* Enumerate the exact syntax changes.
* Provide a detailed and clear migration path.
* Include specific examples of deprecated and breaking changes.
  • Loading branch information
@DaveSkender
DaveSkender committed Dec 1, 2024
1 parent 453f3f3 commit d2679ba
Showing 1 changed file with 111 additions and 112 deletions.
223 changes: 111 additions & 112 deletions src/_common/ObsoleteV3.md
View file
Original file line number Diff line number Diff line change
@@ -1,142 +1,141 @@
# v3 migration guide
# v3 Migration Guide

We've discontinued all bridge features for v1 backwards compatibility.
Correct all Warnings from this library before migrating from v2 to v3.
If you are still using v1, migrate to v2 first, to ease the transition to v3.
This guide provides a detailed and clear migration path from v2 to v3 of the Stock Indicators library. It includes a summary of all technical changes to the public API, enumerates the exact syntax changes, and provides specific examples of deprecated and breaking changes. Follow the instructions below to update your code to be compatible with the new version.

Where possible, we've added bridge features to ease transition from v2 to v3.
You will see supporting migration Warning in your compiler with additional instructions for [deprecated changes](#deprecation-changes).
## Summary of Technical Changes

In addition there are [breaking changes](#breaking-changes) that will require your attention.

## Deprecation changes
- All static time-series API method prefixes were renamed from `GetX()` to `ToX()`.
- `Use()` method parameter `candlePart` is now required and no longer defaults to `CandlePart.Close`.
- `Use()` now returns a chainable `QuotePart` instead of a tuple.
- `UlcerIndexResult` property `UI` was renamed to `UlcerIndex`.
- Deprecated 'GetX' tuple interfaces.
- Deprecated internal signals for several indicators.
- `Quote` type was changed to an immutable `record` type.
- `IQuote` interface `Date` property was renamed to `Timestamp`.
- `IQuote` is now a reusable (chainable) type.
- `TQuote` custom quote types now have to implement the `IReusable` interface.
- `IReusableResult` was renamed to `IReusable`.
- `IReusableResult.Value` property was changed to non-nullable and returns `double.NaN` instead of `null`.
- Indicator return types were changed from `sealed class` to immutable `record` types.
- Return type for the `Use()` utility method was renamed from `UseResult` to `QuotePart`.
- `Numerixs` class was renamed to `Numerical`.
- `GetBaseQuote()` indicator and related `BasicData` return types were removed.
- `AtrStopResult` values were changed from `decimal` to `double`.
- `SyncSeries()` utility function and related `SyncType` enum were removed.
- `ToTupleCollection<TQuote>()` utility method was deprecated.
- `Find()` and `FindIndex()` utility methods were removed.

See your compiler `Warning` to identify these in your code.
## Exact Syntax Changes

### General Changes

- All static time-series API method prefix were renamed from `GetX()` to `ToX()` to better reflect their purpose as a conversion utility. The former "Get" prefix innaccurately implied a retrieval operation.

- All static time-series API method prefixes were renamed from `GetX()` to `ToX()`.
- `Use()` method parameter `candlePart` is now required and no longer defaults to `CandlePart.Close`.
- `Use()` now returns a chainable `QuotePart` instead of a tuple. These also replace the redundant `GetBaseQuote()` and `BaseQuote` items, respectively.
- `Use()` now returns a chainable `QuotePart` instead of a tuple.

### Indicator-Specific Changes

- `UlcerIndexResult` property `UI` was renamed to `UlcerIndex`

- **Deprecated 'GetX' tuple interfaces**.

- **Deprecated internal signals**: several indicators were originally built with integrated but optional
moving averages, often by specifying an optional `smaPeriods` parameter. With more moving average chaining options,
these are obsolete, so we've removed them for simplification. These were persisted to avoid breaking your code;
however, you will see a compiler `Warnings` to help you identify areas to refactor. Check for use in ADL, OBV, ROC, STDDEV, TRIX, and others.
Future versions will not support the old API and will produce compiler `Errors`.

```csharp
// To refactor, here's an example replacement for ADL:
var results = quotes.ToAdl(10);
var adlSma = results.ToSma(5);

// ref: old usage example
var results = quotes
.GetAdl(lookbackPeriods: 10, smaPeriods: 5);
```

## Breaking changes

Not all, but some of these will be shown as compiler `Errors` in your code.
Items marked with &#128681; require special attention since they will not produce compiler Errors or Warnings.

### General Breaking Changes

- all v1 backwards compatibility accommodations were removed.

- no longer supporting .NET Standard 2.0 for older .NET Framework compatibility.

### Common breaking changes

- `Quote` type (built-in) was changed to an _**immutable**_ `record` type; and its `IQuote` interface `Date` property was widely renamed to `Timestamp`, to avoid a conflict with a C# reserved name. This will break your implementation if you were using `Quote` as an inherited base type. To fix, define your custom `TQuote` type on the `IQuote` interface instead (example below).

- `IQuote` is now a reusable (chainable) type. It auto-selects `Close` price as the _default_ consumed value.

- `TQuote` custom quote types now have to implement the `IReusable` interface to support chaining operations. The best way to fix is to change your `TQuote` to implement the `IReusable.Value` pointer to your `IQuote.Close` price. See [the Guide](/guide) for more information. Example:

```csharp
public record MyCustomQuote (

// `IQuote` properties
DateTime Timestamp,
decimal Open,
decimal High,
decimal Low,
decimal MyClose, // custom
decimal Volume,

// custom properties
string? MyCustomProperty = default

) : IQuote // » IQuote now inherits an IReusable
{
// custom mapped properties
decimal IQuote.Close
=> MyClose;
- `UlcerIndexResult` property `UI` was renamed to `UlcerIndex`.
- Deprecated 'GetX' tuple interfaces.
- Deprecated internal signals for several indicators.

### Common Breaking Changes

- `Quote` type was changed to an immutable `record` type.
- `IQuote` interface `Date` property was renamed to `Timestamp`.
- `IQuote` is now a reusable (chainable) type.
- `TQuote` custom quote types now have to implement the `IReusable` interface.
- `IReusableResult` was renamed to `IReusable`.
- `IReusableResult.Value` property was changed to non-nullable and returns `double.NaN` instead of `null`.
- Indicator return types were changed from `sealed class` to immutable `record` types.
- Return type for the `Use()` utility method was renamed from `UseResult` to `QuotePart`.
- `Numerixs` class was renamed to `Numerical`.
- `GetBaseQuote()` indicator and related `BasicData` return types were removed.
- `AtrStopResult` values were changed from `decimal` to `double`.
- `SyncSeries()` utility function and related `SyncType` enum were removed.
- `ToTupleCollection<TQuote>()` utility method was deprecated.
- `Find()` and `FindIndex()` utility methods were removed.

// `IReusable` requires a default 'Value' property.
// Map it to your 'Close' price.
double IReusable.Value
=> (double)Close;
}
```
## Migration Path

- `IReusableResult` was renamed to `IReusable` since it is no longer limited to _result_ types.
### General Migration Steps

- &#128681; `IReusableResult.Value` property was changed to non-nullable and returns `double.NaN` instead of `null` for incalculable periods. The standard results (e.g. `EmaResult.Ema`) continue to return `null` for incalculable periods. This was done to improve internal chaining and streaming performance.
1. Update all static time-series API method prefixes from `GetX()` to `ToX()`.
2. Update `Use()` method calls to include the `candlePart` parameter.
3. Update `Use()` method calls to handle the new `QuotePart` return type.
4. Update `UlcerIndexResult` property `UI` to `UlcerIndex`.
5. Refactor code to remove deprecated 'GetX' tuple interfaces.
6. Refactor code to remove deprecated internal signals for indicators.

- Indicator return types, like `EmaResult`, were changed from `sealed class` to _**immutable**_ `record` types to improve internal chaining and streaming performance. This should not impact negatively; however, these can now be inherited as base classes.
### Specific Migration Steps

### Less common breaking changes
#### Updating `Quote` Type

- Return type for the `Use()` utility method was renamed from `UseResult` to `QuotePart` for clarity and for of its wider purpose.
1. Change `Quote` type to an immutable `record` type.
2. Rename `IQuote` interface `Date` property to `Timestamp`.
3. Implement the `IReusable` interface for custom `TQuote` types.

- `Numerixs` class was renamed to `Numerical`.
#### Updating `IReusableResult`

- `GetBaseQuote()` indicator and related `BasicData` return types were removed since they are redundant to the `Use()` method and `QuotePart` return types, respectively.
1. Rename `IReusableResult` to `IReusable`.
2. Update `IReusableResult.Value` property to handle `double.NaN` instead of `null`.

- `AtrStopResult` values were changed from `decimal` to `double` numeric return types.
#### Updating Indicator Return Types

- `SyncSeries()` utility function and related `SyncType` enum were removed. This was primarily an internal utility, but was part of the public API to support user who wanted to build custom indicator development. Internally, we've refactored indicators to auto-initialize and heal, so they no longer require re-sizing to support explicit warmup periods.
1. Change indicator return types from `sealed class` to immutable `record` types.

- `ToTupleCollection<TQuote>()` utility method was deprecated. This was available to support custom indicator development, but is no longer needed. We've discontinued using _tuples_ as an interface to chainable indicators.
#### Updating Utility Methods

- `Find()` and `FindIndex()` utility methods were removed. These were redundant to the native C# `List.Find()` method and `List.FindIndex()` methods, respectively.
1. Rename return type for the `Use()` utility method from `UseResult` to `QuotePart`.
2. Rename `Numerixs` class to `Numerical`.
3. Remove `GetBaseQuote()` indicator and related `BasicData` return types.
4. Change `AtrStopResult` values from `decimal` to `double`.
5. Remove `SyncSeries()` utility function and related `SyncType` enum.
6. Deprecate `ToTupleCollection<TQuote>()` utility method.
7. Remove `Find()` and `FindIndex()` utility methods.

## Deprecated and Breaking Changes Summary
## Examples of Deprecated and Breaking Changes

### Deprecated Changes

- All static time-series API method prefixes were renamed from `GetX()` to `ToX()` to better reflect their purpose as a conversion utility. The former "Get" prefix inaccurately implied a retrieval operation.
- `Use()` method parameter `candlePart` is now required and no longer defaults to `CandlePart.Close`.
- `Use()` now returns a chainable `QuotePart` instead of a tuple. These also replace the redundant `GetBaseQuote()` and `BaseQuote` items, respectively.
- `UlcerIndexResult` property `UI` was renamed to `UlcerIndex`.
- Deprecated 'GetX' tuple interfaces.
- Deprecated internal signals: several indicators were originally built with integrated but optional moving averages, often by specifying an optional `smaPeriods` parameter. With more moving average chaining options, these are obsolete, so we've removed them for simplification. These were persisted to avoid breaking your code; however, you will see compiler `Warnings` to help you identify areas to refactor. Check for use in ADL, OBV, ROC, STDDEV, TRIX, and others. Future versions will not support the old API and will produce compiler `Errors`.
```csharp
// Old usage
IEnumerable<AdlResult> results = quotes.GetAdl();
IEnumerable<UlcerIndexResult> results = quotes.GetUlcerIndex();
var adlSma = results.ToSma(5);

// New usage
IEnumerable<AdlResult> results = quotes.ToAdl();
IEnumerable<UlcerIndexResult> results = quotes.ToUlcerIndex();
var adlSma = results.ToSma(5);
```

### Breaking Changes

- All v1 backwards compatibility accommodations were removed.
- No longer supporting .NET Standard 2.0 for older .NET Framework compatibility.
- `Quote` type (built-in) was changed to an immutable `record` type; and its `IQuote` interface `Date` property was widely renamed to `Timestamp`, to avoid a conflict with a C# reserved name. This will break your implementation if you were using `Quote` as an inherited base type. To fix, define your custom `TQuote` type on the `IQuote` interface instead.
- `IQuote` is now a reusable (chainable) type. It auto-selects `Close` price as the default consumed value.
- `TQuote` custom quote types now have to implement the `IReusable` interface to support chaining operations. The best way to fix is to change your `TQuote` to implement the `IReusable.Value` pointer to your `IQuote.Close` price.
- `IReusableResult` was renamed to `IReusable` since it is no longer limited to result types.
- `IReusableResult.Value` property was changed to non-nullable and returns `double.NaN` instead of `null` for incalculable periods. The standard results (e.g. `EmaResult.Ema`) continue to return `null` for incalculable periods. This was done to improve internal chaining and streaming performance.
- Indicator return types, like `EmaResult`, were changed from `sealed class` to immutable `record` types to improve internal chaining and streaming performance. This should not impact negatively; however, these can now be inherited as base classes.
- Return type for the `Use()` utility method was renamed from `UseResult` to `QuotePart` for clarity and for its wider purpose.
- `Numerixs` class was renamed to `Numerical`.
- `GetBaseQuote()` indicator and related `BasicData` return types were removed since they are redundant to the `Use()` method and `QuotePart` return types, respectively.
- `AtrStopResult` values were changed from `decimal` to `double` numeric return types.
- `SyncSeries()` utility function and related `SyncType` enum were removed. This was primarily an internal utility, but was part of the public API to support users who wanted to build custom indicator development. Internally, we've refactored indicators to auto-initialize and heal, so they no longer require re-sizing to support explicit warmup periods.
- `ToTupleCollection<TQuote>()` utility method was deprecated. This was available to support custom indicator development, but is no longer needed. We've discontinued using tuples as an interface to chainable indicators.
- `Find()` and `FindIndex()` utility methods were removed. These were redundant to the native C# `List.Find()` method and `List.FindIndex()` methods, respectively.
```csharp
// Old usage
public class MyQuote : Quote
{
public DateTime Date { get; set; }
}

// New usage
public record MyQuote : IQuote
{
public DateTime Timestamp { get; init; }
public decimal Open { get; init; }
public decimal High { get; init; }
public decimal Low { get; init; }
public decimal Close { get; init; }
public decimal Volume { get; init; }
}
```

## Clear Instructions for Updating Code

1. Follow the general migration steps to update your code to be compatible with the new version.
2. Refer to the specific migration steps for detailed instructions on updating each aspect of your code.
3. Use the examples of deprecated and breaking changes to guide your code updates.
4. Test your updated code to ensure it is compatible with the new version and functions as expected.

By following this migration guide, you can successfully update your code to be compatible with v3 of the Stock Indicators library. If you encounter any issues or have questions, refer to the project documentation or seek assistance from the community.

0 comments on commit d2679ba

Please sign in to comment.