Skip to content

Commit 1eb4dd8

Browse files
VeskeRlawrence-forooghian
VeskeR
authored and
lawrence-forooghian
committed
BatchContext and batch API on PathObject and Instance
1 parent 035aef9 commit 1eb4dd8

2 files changed

Lines changed: 104 additions & 1 deletion

File tree

‎specifications/features.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -939,7 +939,7 @@ The threading and/or asynchronous model for each realtime library will vary by l
939939

940940
### RealtimeObject {#realtime-objects}
941941

942-
Reserved for `RealtimeObject` feature specification, see [objects-features](../objects-features). Reserved spec points: `RTO`, `RTLO`, `RTLC`, `RTLM`, `RTPO`, `RTINS`, `RTLCV`, `RTLMV`
942+
Reserved for `RealtimeObject` feature specification, see [objects-features](../objects-features). Reserved spec points: `RTO`, `RTLO`, `RTLC`, `RTLM`, `RTPO`, `RTINS`, `RTLCV`, `RTLMV`, `RTBC`
943943

944944
### RealtimeAnnotations {#realtime-annotations}
945945

‎specifications/objects-features.md‎

Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -914,6 +914,14 @@ A `PathObject` is obtained from `RealtimeObject#get` ([RTO23](#RTO23)), which re
914914
- `(RTPO21a1)` `options` `PathObjectSubscriptionOptions` (optional) - same options as `PathObject#subscribe` ([RTPO19b](#RTPO19b))
915915
- `(RTPO21b)` Returns a stream or iterable that yields `PathObjectSubscriptionEvent` objects, using the idiomatic construct for the language (e.g. async iterators, channels, flows, or async sequences)
916916
- `(RTPO21c)` Internally wraps `PathObject#subscribe` ([RTPO19](#RTPO19)), converting the callback-based subscription into the appropriate streaming or iterable pattern
917+
- `(RTPO22)` `PathObject#batch` function:
918+
- `(RTPO22a)` Expects a synchronous function `fn` that receives a `BatchContext` as its argument
919+
- `(RTPO22b)` Requires the `OBJECT_PUBLISH` channel mode to be granted per [RTO2](#RTO2)
920+
- `(RTPO22c)` Resolves the path to a `LiveObject` using the internal path resolution procedure. If the path does not resolve to a `LiveObject`, the library must throw an `ErrorInfo` error with `statusCode` 400 and `code` 92007
921+
- `(RTPO22d)` Creates a `RootBatchContext` ([RTBC16](#RTBC16)) wrapping the resolved `Instance`
922+
- `(RTPO22e)` Executes `fn`, passing the `BatchContext` as argument
923+
- `(RTPO22f)` After `fn` returns, flushes the `RootBatchContext` ([RTBC16d](#RTBC16d)) to publish all queued operations atomically
924+
- `(RTPO22g)` The `RootBatchContext` is closed after flush completes, regardless of success or failure
917925

918926
### Instance
919927

@@ -988,6 +996,84 @@ An `Instance` holds a direct reference to a specific resolved `LiveObject` or pr
988996
- `(RTINS18a)` If the wrapped value is not a `LiveObject`, the library must throw an `ErrorInfo` error with `statusCode` 400 and `code` 92007
989997
- `(RTINS18b)` Returns a stream or iterable that yields `InstanceSubscriptionEvent` objects, using the idiomatic construct for the language (e.g. async iterators, channels, flows, or async sequences)
990998
- `(RTINS18c)` Internally wraps `Instance#subscribe` ([RTINS16](#RTINS16)), converting the callback-based subscription into the appropriate streaming or iterable pattern
999+
- `(RTINS19)` `Instance#batch` function:
1000+
- `(RTINS19a)` Expects a synchronous function `fn` that receives a `BatchContext` as its argument
1001+
- `(RTINS19b)` Requires the `OBJECT_PUBLISH` channel mode to be granted per [RTO2](#RTO2)
1002+
- `(RTINS19c)` If the wrapped value is not a `LiveObject`, the library must throw an `ErrorInfo` error with `statusCode` 400 and `code` 92007
1003+
- `(RTINS19d)` Creates a `RootBatchContext` ([RTBC16](#RTBC16)) wrapping this `Instance`
1004+
- `(RTINS19e)` Executes `fn`, passing the `BatchContext` as argument
1005+
- `(RTINS19f)` After `fn` returns, flushes the `RootBatchContext` ([RTBC16d](#RTBC16d)) to publish all queued operations atomically
1006+
- `(RTINS19g)` The `RootBatchContext` is closed after flush completes, regardless of success or failure
1007+
1008+
### BatchContext
1009+
1010+
A `BatchContext` wraps an `Instance` with synchronous write methods that queue operations instead of sending them immediately. All queued operations are published atomically as a single channel message when the batch function returns. This allows multiple mutations to be grouped into a single publish call.
1011+
1012+
- `(RTBC1)` The `BatchContext` class provides a synchronous write interface for grouping multiple mutations into a single atomic publish
1013+
- `(RTBC1a)` A specific SDK implementation may choose to expose a subset of the methods available on the `BatchContext` class based on the known underlying type, in a similar manner to `Instance` ([RTINS1a](#RTINS1a))
1014+
- `(RTBC2)` `BatchContext` has the following internal properties:
1015+
- `(RTBC2a)` `instance` - the underlying `Instance` that this `BatchContext` wraps
1016+
- `(RTBC2b)` `rootContext` - a reference to the `RootBatchContext` ([RTBC16](#RTBC16)) that manages the batch operation
1017+
- `(RTBC3)` `BatchContext#id` property:
1018+
- `(RTBC3a)` Returns the `objectId` of the underlying `Instance` ([RTINS3](#RTINS3))
1019+
- `(RTBC3b)` If the batch is closed, the library must throw an `ErrorInfo` error with `statusCode` 400 and `code` 40000, indicating that the batch is closed
1020+
- `(RTBC4)` `BatchContext#get` function:
1021+
- `(RTBC4a)` Expects a `key` `String` argument
1022+
- `(RTBC4b)` If the batch is closed, the library must throw an `ErrorInfo` error with `statusCode` 400 and `code` 40000
1023+
- `(RTBC4c)` Delegates to `Instance#get` ([RTINS5](#RTINS5)) on the underlying `Instance`. If the result is undefined, returns undefined
1024+
- `(RTBC4d)` Otherwise, wraps the resulting `Instance` in a `BatchContext` via the `RootBatchContext#wrapInstance` ([RTBC16c](#RTBC16c)) and returns it
1025+
- `(RTBC5)` `BatchContext#value` function:
1026+
- `(RTBC5a)` If the batch is closed, the library must throw an `ErrorInfo` error with `statusCode` 400 and `code` 40000
1027+
- `(RTBC5b)` Delegates to `Instance#value` ([RTINS4](#RTINS4)) on the underlying `Instance`
1028+
- `(RTBC6)` `BatchContext#entries` function:
1029+
- `(RTBC6a)` If the batch is closed, the library must throw an `ErrorInfo` error with `statusCode` 400 and `code` 40000
1030+
- `(RTBC6b)` Delegates to `Instance#entries` ([RTINS6](#RTINS6)) on the underlying `Instance`, wrapping each yielded `Instance` value in a `BatchContext` via `RootBatchContext#wrapInstance` ([RTBC16c](#RTBC16c))
1031+
- `(RTBC6c)` Yields `[String, BatchContext]` pairs
1032+
- `(RTBC7)` `BatchContext#keys` function:
1033+
- `(RTBC7a)` If the batch is closed, the library must throw an `ErrorInfo` error with `statusCode` 400 and `code` 40000
1034+
- `(RTBC7b)` Delegates to `Instance#keys` ([RTINS7](#RTINS7)) on the underlying `Instance`
1035+
- `(RTBC8)` `BatchContext#values` function:
1036+
- `(RTBC8a)` If the batch is closed, the library must throw an `ErrorInfo` error with `statusCode` 400 and `code` 40000
1037+
- `(RTBC8b)` Delegates to `Instance#values` ([RTINS8](#RTINS8)) on the underlying `Instance`, wrapping each yielded `Instance` in a `BatchContext` via `RootBatchContext#wrapInstance` ([RTBC16c](#RTBC16c))
1038+
- `(RTBC9)` `BatchContext#size` function:
1039+
- `(RTBC9a)` If the batch is closed, the library must throw an `ErrorInfo` error with `statusCode` 400 and `code` 40000
1040+
- `(RTBC9b)` Delegates to `Instance#size` ([RTINS9](#RTINS9)) on the underlying `Instance`
1041+
- `(RTBC10)` `BatchContext#compact` function:
1042+
- `(RTBC10a)` If the batch is closed, the library must throw an `ErrorInfo` error with `statusCode` 400 and `code` 40000
1043+
- `(RTBC10b)` Delegates to `Instance#compact` ([RTINS10](#RTINS10)) on the underlying `Instance`
1044+
- `(RTBC11)` `BatchContext#compactJson` function:
1045+
- `(RTBC11a)` If the batch is closed, the library must throw an `ErrorInfo` error with `statusCode` 400 and `code` 40000
1046+
- `(RTBC11b)` Delegates to `Instance#compactJson` ([RTINS11](#RTINS11)) on the underlying `Instance`
1047+
- `(RTBC12)` `BatchContext#set` function. This method is synchronous:
1048+
- `(RTBC12a)` Expects the following arguments:
1049+
- `(RTBC12a1)` `key` `String` - the key to set the value for
1050+
- `(RTBC12a2)` `value` `Boolean | Binary | Number | String | JsonArray | JsonObject | LiveCounterValueType | LiveMapValueType` - the value to assign to the key
1051+
- `(RTBC12b)` If the batch is closed, the library must throw an `ErrorInfo` error with `statusCode` 400 and `code` 40000
1052+
- `(RTBC12c)` If the wrapped value is not a `LiveMap`, the library must throw an `ErrorInfo` error with `statusCode` 400 and `code` 92007
1053+
- `(RTBC12d)` Queues a message constructor on the `RootBatchContext` that, when executed, creates `ObjectMessages` for a `MAP_SET` operation in the same manner as `LiveMap#set` ([RTLM20e](#RTLM20e))
1054+
- `(RTBC13)` `BatchContext#remove` function. This method is synchronous:
1055+
- `(RTBC13a)` Expects a `key` `String` argument
1056+
- `(RTBC13b)` If the batch is closed, the library must throw an `ErrorInfo` error with `statusCode` 400 and `code` 40000
1057+
- `(RTBC13c)` If the wrapped value is not a `LiveMap`, the library must throw an `ErrorInfo` error with `statusCode` 400 and `code` 92007
1058+
- `(RTBC13d)` Queues a message constructor on the `RootBatchContext` that, when executed, creates an `ObjectMessage` for a `MAP_REMOVE` operation in the same manner as `LiveMap#remove` ([RTLM21e](#RTLM21e))
1059+
- `(RTBC14)` `BatchContext#increment` function. This method is synchronous:
1060+
- `(RTBC14a)` Expects the following arguments:
1061+
- `(RTBC14a1)` `amount` `Number` (optional) - the amount by which to increment the counter value. Defaults to 1
1062+
- `(RTBC14b)` If the batch is closed, the library must throw an `ErrorInfo` error with `statusCode` 400 and `code` 40000
1063+
- `(RTBC14c)` If the wrapped value is not a `LiveCounter`, the library must throw an `ErrorInfo` error with `statusCode` 400 and `code` 92007
1064+
- `(RTBC14d)` Queues a message constructor on the `RootBatchContext` that, when executed, creates an `ObjectMessage` for a `COUNTER_INC` operation in the same manner as `LiveCounter#increment` ([RTLC12](#RTLC12))
1065+
- `(RTBC15)` `BatchContext#decrement` function. This method is synchronous:
1066+
- `(RTBC15a)` Expects the following arguments:
1067+
- `(RTBC15a1)` `amount` `Number` (optional) - the amount by which to decrement the counter value. Defaults to 1
1068+
- `(RTBC15b)` If the batch is closed, the library must throw an `ErrorInfo` error with `statusCode` 400 and `code` 40000
1069+
- `(RTBC15c)` If the wrapped value is not a `LiveCounter`, the library must throw an `ErrorInfo` error with `statusCode` 400 and `code` 92007
1070+
- `(RTBC15d)` Delegates to `BatchContext#increment` ([RTBC14](#RTBC14)) with the negated `amount`
1071+
- `(RTBC16)` Internal `RootBatchContext` - manages the lifecycle and message queue for a batch operation:
1072+
- `(RTBC16a)` Maintains an internal `wrappedInstances` map that memoizes `BatchContext` wrappers by `objectId`
1073+
- `(RTBC16b)` Maintains an internal `queuedMessageConstructors` list of deferred message constructor functions. Some `ObjectMessages` require asynchronous I/O during construction (e.g. generating an `objectId` for nested value types), so message constructors are queued during synchronous batch method calls and executed on flush
1074+
- `(RTBC16c)` `wrapInstance` function: wraps an `Instance` in a `BatchContext`. If the `Instance` has an `objectId` and a wrapper for that `objectId` already exists in `wrappedInstances`, the existing wrapper is returned. Otherwise, a new `BatchContext` is created and stored in `wrappedInstances`
1075+
- `(RTBC16d)` `flush` function: closes the batch context, executes all queued message constructors, flattens the resulting `ObjectMessages` into a single array, and publishes them using `RealtimeObject#publish` ([RTO15](#RTO15)). If there are no queued messages, no publish is performed
1076+
- `(RTBC16e)` After the batch is closed, any method call on the `BatchContext` or its children must throw an `ErrorInfo` error with `statusCode` 400 and `code` 40000, indicating that the batch is closed
9911077

9921078
## Interface Definition {#idl}
9931079

@@ -1091,6 +1177,7 @@ Types and their properties/methods are public and exposed to users by default. A
10911177
subscribe((PathObjectSubscriptionEvent) -> listener, PathObjectSubscriptionOptions? options) -> Subscription // RTPO19
10921178
unsubscribe((PathObjectSubscriptionEvent) -> listener) // RTPO20
10931179
subscribeIterator(PathObjectSubscriptionOptions? options) -> Stream<PathObjectSubscriptionEvent> // RTPO21
1180+
batch(((BatchContext) ->) fn) => io // RTPO22
10941181

10951182
class Instance: // RTINS*
10961183
id: String? // RTINS3
@@ -1109,3 +1196,19 @@ Types and their properties/methods are public and exposed to users by default. A
11091196
subscribe((InstanceSubscriptionEvent) -> listener) -> Subscription // RTINS16
11101197
unsubscribe((InstanceSubscriptionEvent) -> listener) // RTINS17
11111198
subscribeIterator() -> Stream<InstanceSubscriptionEvent> // RTINS18
1199+
batch(((BatchContext) ->) fn) => io // RTINS19
1200+
1201+
class BatchContext: // RTBC*
1202+
id: String? // RTBC3
1203+
get(String key) -> BatchContext? // RTBC4
1204+
value() -> (Boolean | Binary | Number | String | JsonArray | JsonObject)? // RTBC5
1205+
entries() -> Iterator<[String, BatchContext]> // RTBC6
1206+
keys() -> Iterator<String> // RTBC7
1207+
values() -> Iterator<BatchContext> // RTBC8
1208+
size() -> Number? // RTBC9
1209+
compact() -> Object? // RTBC10
1210+
compactJson() -> Object? // RTBC11
1211+
set(String key, (Boolean | Binary | Number | String | JsonArray | JsonObject | LiveCounterValueType | LiveMapValueType) value) // RTBC12
1212+
remove(String key) // RTBC13
1213+
increment(Number amount?) // RTBC14
1214+
decrement(Number amount?) // RTBC15

0 commit comments

Comments
 (0)