Deprecate Shared Instant and replace uses of it with Kotlin Instant by stevenzeck · Pull Request #781 · readium/kotlin-toolkit

stevenzeck · 2026-04-29T00:42:02Z

Since Kotlin 2.1.20, Instant has been available in the Kotlin standard library. This PR does the following:

Adds a helper extension function, String.toInstant(), to parse strings into Kotlin Instant
Replaces the use of the custom Instant in the Shared module throughout the toolkit, using toInstant where necessary.
Deprecates said custom Instant and its functions, and documents and suggests replacements.

Copilot

Pull request overview

This PR migrates the toolkit away from the custom org.readium.r2.shared.util.Instant wrapper by adopting the Kotlin standard library kotlin.time.Instant, adding a shared parsing helper (String.toInstant()), updating call sites, and deprecating the legacy wrapper API.

Changes:

Added String.toInstant() to parse ISO-8601-like date strings (with fallback parsing) into Kotlin instants.
Replaced usages of the legacy Shared Instant across Shared/OPDS/Streamer/LCP/Test app modules with kotlin.time.Instant and epoch-millis conversions where needed.
Deprecated the legacy Instant wrapper and documented migration guidance in the changelog.

Reviewed changes

Copilot reviewed 26 out of 26 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
test-app/src/main/java/org/readium/r2/testapp/reader/PublicationMetadataDialogFragment.kt	Switches publication date handling to `kotlin.time.Clock/System.now()` and epoch-millis to `java.util.Date`.
test-app/src/main/java/org/readium/r2/testapp/drm/LcpManagementViewModel.kt	Replaces legacy `toJavaDate()` with `Date(instant.toEpochMilliseconds())` conversions.
readium/streamer/src/test/java/org/readium/r2/streamer/parser/epub/MetadataTest.kt	Updates imports after Instant migration (currently introduces an unused import).
readium/streamer/src/main/java/org/readium/r2/streamer/parser/epub/MetadataAdapter.kt	Uses the new `String.toInstant()` when parsing EPUB metadata dates.
readium/shared/src/test/java/org/readium/r2/shared/util/InstantTest.kt	Suppresses deprecation warnings for tests that still cover the legacy wrapper.
readium/shared/src/test/java/org/readium/r2/shared/publication/MetadataTest.kt	Migrates test data from `Instant.parse(...)` to `String.toInstant()`.
readium/shared/src/test/java/org/readium/r2/shared/opds/AvailabilityTest.kt	Migrates test data from `Instant.parse(...)` to `String.toInstant()`.
readium/shared/src/main/java/org/readium/r2/shared/util/Instant.kt	Deprecates the legacy `Instant` wrapper and suggests replacements.
readium/shared/src/main/java/org/readium/r2/shared/publication/Metadata.kt	Switches `modified/published` to Kotlin `Instant` and parses via `toInstant()`.
readium/shared/src/main/java/org/readium/r2/shared/opds/OpdsMetadata.kt	Switches OPDS metadata `modified` to Kotlin `Instant`.
readium/shared/src/main/java/org/readium/r2/shared/opds/Availability.kt	Switches OPDS availability instants and parsing to Kotlin `Instant`/`toInstant()`.
readium/shared/src/main/java/org/readium/r2/shared/extensions/String.kt	Introduces `String.toInstant()` extension for permissive parsing.
readium/opds/src/test/java/org/readium/r2/opds/OPDS1ParserTest.kt	Updates OPDS1 parser tests to use `String.toInstant()` for dates.
readium/opds/src/main/java/org/readium/r2/opds/OPDS2Parser.kt	Updates OPDS2 parsing to use `String.toInstant()` for `modified`.
readium/opds/src/main/java/org/readium/r2/opds/OPDS1Parser.kt	Updates OPDS1 parsing to use `String.toInstant()` for `modified/published`.
readium/lcp/src/main/java/org/readium/r2/lcp/license/model/components/lsd/PotentialRights.kt	Switches LSD rights end date parsing to Kotlin `Instant` via `toInstant()`.
readium/lcp/src/main/java/org/readium/r2/lcp/license/model/components/lsd/Event.kt	Switches event timestamp parsing to Kotlin `Instant` via `toInstant()`.
readium/lcp/src/main/java/org/readium/r2/lcp/license/model/components/lcp/Rights.kt	Switches start/end parsing to Kotlin `Instant` via `toInstant()`.
readium/lcp/src/main/java/org/readium/r2/lcp/license/model/StatusDocument.kt	Switches `updated` timestamps parsing to Kotlin `Instant` via `toInstant()`.
readium/lcp/src/main/java/org/readium/r2/lcp/license/model/LicenseDocument.kt	Switches `issued/updated` parsing to Kotlin `Instant` via `toInstant()`.
readium/lcp/src/main/java/org/readium/r2/lcp/license/LicenseValidation.kt	Switches “now” to `Clock.System.now()` for license validation logic.
readium/lcp/src/main/java/org/readium/r2/lcp/license/License.kt	Migrates license API surface to Kotlin `Instant`.
readium/lcp/src/main/java/org/readium/r2/lcp/MaterialRenewListener.kt	Uses `Clock.System.now()` and epoch millis for the date picker integration.
readium/lcp/src/main/java/org/readium/r2/lcp/LcpLicense.kt	Migrates LCP license API to Kotlin `Instant`.
readium/lcp/src/main/java/org/readium/r2/lcp/LcpError.kt	Migrates error model references to Kotlin `Instant`.
CHANGELOG.md	Documents the deprecation and migration guidance for instants.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

stevenzeck · 2026-04-29T17:17:11Z

+        ?: tryOrNull { LocalDateTime.parse(this).toInstant(TimeZone.UTC) }
+        ?: tryOrNull { LocalDate.parse(this).atStartOfDayIn(TimeZone.UTC) }


LocalDateTime.toInstant and LocalDate.atStartOfDayIn both return kotlin.time.Instant.

stevenzeck · 2026-04-29T17:49:46Z

@@ -50,24 +62,58 @@ public class Instant private constructor(
            return instant?.let { Instant(it) }


Same comment as String.kt.

qnga · 2026-05-17T07:24:46Z

Could you use Instant.parse rather than toInstant when inputs are under our control?
Wouldn't be cleaner to use kotlinx-datetime in the testapp and to format dates?

stevenzeck · 2026-05-18T01:22:48Z

Could you use Instant.parse rather than toInstant when inputs are under our control?

Where possible, yes. Since Kotlin's Instant.parse requires a full ISO-8601 format, it will error with anything else. All uses of the new toInstant replace the old Readium version of Instant.parse, which is the same underlying code.

Wouldn't be cleaner to use kotlinx-datetime in the testapp and to format dates?

Yes, I just didn't want to put too much effort into the TestApp given it will go away eventually. kotlinx-datetime isn't an existing dependency in it.

qnga · 2026-05-18T04:16:19Z

Could you use Instant.parse rather than toInstant when inputs are under our control?

Where possible, yes. Since Kotlin's Instant.parse requires a full ISO-8601 format, it will error with anything else. All uses of the new toInstant replace the old Readium version of Instant.parse, which is the same underlying code.

I understand that. toInstant is great for the inputs we don't own, but when we know at compile-time that the input is ISO-8601, using Instant.parse would make it clear (and so slightly decrease the cognitive load when reading)

Wouldn't be cleaner to use kotlinx-datetime in the testapp and to format dates?

Yes, I just didn't want to put too much effort into the TestApp given it will go away eventually. kotlinx-datetime isn't an existing dependency in it.

Okay, as you like.

qnga

Take a look at my changes. If I haven't missed anything we can merge it.

stevenzeck · 2026-05-20T15:06:33Z

Looks good to me.

stevenzeck added 4 commits April 28, 2026 15:15

Replace usages of Shared Instant with Kotlin Instant

a0e4ac7

Deprecate Instant

8be4bf8

Document CHANGELOG

5a2fdd2

Update CHANGELOG.md

32e7689

mickael-menu requested a review from Copilot April 29, 2026 16:49

Copilot started reviewing on behalf of mickael-menu April 29, 2026 16:50 View session

Copilot AI reviewed Apr 29, 2026

View reviewed changes

stevenzeck mentioned this pull request Apr 29, 2026

Refactor LCP to remove koi and joda #780

Merged

stevenzeck added 3 commits April 29, 2026 12:48

Make suggested changes

b5572f8

Update CHANGELOG.md

92ab888

Update CHANGELOG.md

76329fb

stevenzeck changed the title ~~Deprecate Shared Instant and replace uses of it~~ Deprecate Shared Instant and replace uses of it with Kotlin Instant Apr 30, 2026

Merge branch 'develop' into refactor/remove-shared-instant

530e05b

Simplify parcelization

a77139b

qnga reviewed May 20, 2026

View reviewed changes

qnga approved these changes May 20, 2026

View reviewed changes

qnga merged commit e41d6d8 into readium:develop May 20, 2026
4 checks passed

stevenzeck deleted the refactor/remove-shared-instant branch May 21, 2026 14:19

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Deprecate Shared Instant and replace uses of it with Kotlin Instant#781

Deprecate Shared Instant and replace uses of it with Kotlin Instant#781
qnga merged 9 commits into
readium:developfrom
stevenzeck:refactor/remove-shared-instant

stevenzeck commented Apr 29, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

stevenzeck Apr 29, 2026

Uh oh!

stevenzeck Apr 29, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

qnga commented May 17, 2026

Uh oh!

stevenzeck commented May 18, 2026

Uh oh!

qnga commented May 18, 2026

Uh oh!

qnga left a comment

Uh oh!

stevenzeck commented May 20, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

		?: tryOrNull { LocalDateTime.parse(this).toInstant(TimeZone.UTC) }
		?: tryOrNull { LocalDate.parse(this).atStartOfDayIn(TimeZone.UTC) }

		@@ -50,24 +62,58 @@ public class Instant private constructor(
		return instant?.let { Instant(it) }

Conversation

stevenzeck commented Apr 29, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

stevenzeck Apr 29, 2026

Choose a reason for hiding this comment

Uh oh!

stevenzeck Apr 29, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

qnga commented May 17, 2026

Uh oh!

stevenzeck commented May 18, 2026

Uh oh!

qnga commented May 18, 2026

Uh oh!

qnga left a comment

Choose a reason for hiding this comment

Uh oh!

stevenzeck commented May 20, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants