Deprecate startAt favor of initialValue

[RanVaknin]

This PR deprecates startAt in favor of initialValue to allow versioning starting from 0.

API Changes

Added:

• initialValue(Long) - sets the first version for new records (default: null)

Deprecated:

• startAt(Long) - default changed from 0 to -1

// Before: couldn't start from 0
builder.startAt(0).incrementBy(1).build(); // first version = 1

// After: can start from 0
builder.initialValue(0L).incrementBy(1L).build(); // first version = 0

Behavior

When startAt=-1 (default), the first version equals initialValue if provided, otherwise incrementBy. The extension uses an OR condition when the current version matches either initialValue or 0 to handle ambiguous cases where it cannot distinguish between a new record with an explicitly set version versus an existing record.

examples:

VersionedRecordExtension.builder()
    .incrementBy(1L) // default
    .initialValue(null) // default
    .build();

table.putItem(record);    // version = 1
table.updateItem(record); // version = 2
table.updateItem(record); // version = 3

VersionedRecordExtension.builder()
    .initialValue(0L)
    .build();

table.putItem(record);    // version = 0
table.updateItem(record); // version = 1  
table.updateItem(record); // version = 2

Legacy mode: When startAt>=0 (now deprecated), the first version equals startAt + incrementBy. This maintains backwards compatibility.

[sonarqubecloud]

Quality Gate passed

Issues
11 New issues
0 Accepted issues

Measures
0 Security Hotspots
97.6% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud