Skip to content

Align path-based LiveObjects API spec with ably-js implementation#480

Draft
sacOO7 wants to merge 2 commits into
AIT-30/liveobjects-path-based-api-specfrom
fix/liveobjects-path-spec-based-on-ably-js-v2
Draft

Align path-based LiveObjects API spec with ably-js implementation#480
sacOO7 wants to merge 2 commits into
AIT-30/liveobjects-path-based-api-specfrom
fix/liveobjects-path-spec-based-on-ably-js-v2

Conversation

@sacOO7
Copy link
Copy Markdown
Collaborator

@sacOO7 sacOO7 commented May 21, 2026

Summary

LiveObjects spec changes covering path-based subscriptions, identity-based subscription lifecycle behavior, and deregistration APIs:

• Multi-parent reference tracking (RTLO3f, RTLO3g, RTO5c10, RTO24b1)

  • Each LiveObject now maintains a parentReferences map keyed by parent LiveMap.
  • The map is updated during MAP_SET / MAP_REMOVE / MAP_CLEAR operations and when a LiveMap is tombstoned.
  • A new internal getFullPaths helper traverses the parent graph upward to the root with cycle protection, returning all distinct paths currently referencing the object (or an empty set if the object is orphaned).
  • PathObjectSubscriptionRegister (RTO24b1) now uses getFullPaths to determine dispatch targets, allowing a single object update to fan out across every path referencing that object.
  • After sync completion, the pool rebuilds all parentReferences from the finalized LiveMap state.

• Tombstone-driven auto-deregistration (RTLO4b8, RTLO4b9, RTLO4b10)

  • LiveObject#subscribe listeners receiving a tombstone update (OBJECT_DELETE or sync tombstone) are invoked once and then automatically deregistered.
  • Subsequent updates to that object no longer notify those listeners.
  • Path-based subscriptions (RTPO19) are intentionally excluded from this behavior because they track paths rather than object identity; a later MAP_SET assigning a new object to the same path continues delivering updates.
  • Listener exceptions are caught and logged, and do not interrupt dispatch to remaining listeners.

Subscription as the sole deregistration mechanism (SUB2b, RTLO4c, RTPO20, RTINS17)

  • Removes imperative unsubscribe(listener) APIs from LiveObject, PathObject, and Instance (corresponding clauses deleted).
  • Callers now deregister exclusively through the Subscription returned by subscribe.
  • Subscription#unsubscribe is explicitly documented as idempotent; repeated calls are treated as no-ops.

• IDL updates

  • Removes deprecated unsubscribe declarations.
  • Adds a Primitive type alias.
  • Exposes the internal count and entries backing fields on LiveCounterValueType and LiveMapValueType.

…i-spec' into fix/liveobjects-path-spec-based-on-ably-js-v2

# Conflicts:
#	specifications/objects-features.md
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Development

Successfully merging this pull request may close these issues.

1 participant