Skip to content

Add IDL of Objects features #345

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
VeskeR merged 2 commits into from
Sep 8, 2025
Merged

Add IDL of Objects features #345

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
fb6e74c
Add interface definitions for objects features
VeskeR Jul 11, 2025
7ccb26d
Indicate nullable types for LiveMap IDL
VeskeR Sep 4, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 27 additions & 1 deletion textile/objects-features.textile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ Objects feature enables clients to store shared data as "objects" on a channel.

h3(#realtime-objects). RealtimeObjects

* @(RTO1)@ @Objects#getRoot@ function:
* @(RTO1)@ @RealtimeObjects#getRoot@ function:
** @(RTO1a)@ Requires the @OBJECT_SUBSCRIBE@ channel mode to be granted per "RTO2":#RTO2
** @(RTO1b)@ If the channel is in the @DETACHED@ or @FAILED@ state, the library should throw an @ErrorInfo@ error with @statusCode@ 400 and @code@ 90001
** @(RTO1c)@ Waits for the objects sync sequence to complete and for "RTO5c":#RTO5c to finish
Expand Down Expand Up @@ -254,3 +254,29 @@ h3(#livemap). LiveMap
*** @(RTLM17a1)@ If @ObjectsMapEntry.tombstone@ is @false@ or omitted, apply the @MAP_SET@ operation to the current key as described in "RTLM7":#RTLM7, passing in @ObjectsMapEntry.data@ and the current key as @ObjectsMapOp@, and @ObjectsMapEntry.timeserial@ as @serial@
*** @(RTLM17a2)@ If @ObjectsMapEntry.tombstone@ is @true@, apply the @MAP_REMOVE@ operation to the current key as described in "RTLM8":#RTLM8, passing in the current key as @ObjectsMapOp@, and @ObjectsMapEntry.timeserial@ as @serial@
** @(RTLM17b)@ Set the private flag @createOperationIsMerged@ to @true@

h2(#idl). Interface Definition

Describes types for RealtimeObjects.
Types and their properties/methods are public and exposed to users by default. An @internal@ label may be used to indicate that a type or its property/method must not be exposed to users and is intended for internal SDK use only.

<pre>
class RealtimeObjects: // RTO*
getRoot() => io LiveMap // RTO1

class LiveObject: // RTLO*
Copy link
Collaborator

@sacOO7 sacOO7 Sep 5, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
class LiveObject: // RTLO*
class BaseRealtimeObject: // RTLO*

Since both LiveMap and LiveCounter extend this class and are part of RealtimeObjects, it makes sense to name the class BaseRealtimeObject.

Copy link
Collaborator

@sacOO7 sacOO7 Sep 5, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Additionally, we agreed to avoid using LiveObject/LiveObjects in the code.

Copy link
Contributor Author

@VeskeR VeskeR Sep 5, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

we agreed to not use term "LiveObjects" (plural) in the code specifically when talking about the feature "Objects".

"LiveObject" (singular) is a name for any "live object" - "live map", "live counter", "live list" (in the future)

Copy link
Contributor Author

@VeskeR VeskeR Sep 5, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It is way easier to call something a "live object" (as we do in our conversations) and refer to it as "LiveObject" in the spec.
Since it also looks like that it shouldn't be necessary to expose LiveObject type to the public (kotlin and - and swift too I believe - implementations don't expose it) I'd prefer we stick to a simple name in the spec

Copy link
Collaborator

@sacOO7 sacOO7 Sep 5, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Then better if we call it BaseLiveObject or BaseObject since it's extended by LiveMap, LiveCounter and not exposed externally. wdyt

Copy link
Contributor Author

@VeskeR VeskeR Sep 5, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

But... why? I don't see a clear reason to change it. If it's not a public type then the name itself is not that important, and LiveObject type name accomplishes what we need it to do in the spec. And if it is exposed publicly (which it currently is in ably-js) we can't just change the name in the spec as we would also need to update ably-js implementation.

I really don't want to go through all spec PRs and update the LiveObject name to something else given it does what it need to right now

Copy link
Collaborator

@sacOO7 sacOO7 Sep 5, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Okay, since it's an internal type, we can ignore the naming convention.

objectId: String // RTLO3a, internal
siteTimeserials: Dict<String, String> // RTLO3b, internal
createOperationIsMerged: Boolean // RTLO3c, internal
canApplyOperation(ObjectMessage) -> Boolean // RTLO4a, internal

class LiveCounter extends LiveObject: // RTLC*, RTLC1
value() -> Number // RTLC5

class LiveMap extends LiveObject: // RTLM*, RTLM1
get(key: String) -> (Boolean | Binary | Number | String | JsonArray | JsonObject | LiveCounter | LiveMap)? // RTLM5
size() -> Number // RTLM10
entries() -> [String, (Boolean | Binary | Number | String | JsonArray | JsonObject | LiveCounter | LiveMap)?][] // RTLM11
keys() -> String[] // RTLM12
values() -> (Boolean | Binary | Number | String | JsonArray | JsonObject | LiveCounter | LiveMap)?[] // RTLM13
</pre>
Loading