y-rb 0.3.2-x64-mingw32 → 0.4.0-x64-mingw32

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
data/lib/y/array.rb CHANGED
@@ -19,7 +19,7 @@ module Y
19
19
  # array.concat([3, 4, 5])
20
20
  #
21
21
  # array.to_a == [1, 2, 3, 4, 5] # true
22
- class Array
22
+ class Array # rubocop:disable Metrics/ClassLength
23
23
  include Enumerable
24
24
 
25
25
  # @!attribute [r] document
@@ -29,7 +29,7 @@ module Y
29
29
 
30
30
  # Create a new array instance
31
31
  #
32
- # @param [Y::Doc] doc
32
+ # @param doc [Y::Doc]
33
33
  def initialize(doc = nil)
34
34
  @document = doc || Y::Doc.new
35
35
 
@@ -38,25 +38,26 @@ module Y
38
38
 
39
39
  # Retrieves element at position
40
40
  #
41
- # @return [Object]
41
+ # @return [true|false|Float|Integer|String|Array|Hash]
42
42
  def [](index)
43
- yarray_get(index)
43
+ document.current_transaction { |tx| yarray_get(tx, index) }
44
44
  end
45
45
 
46
46
  # Inserts value at position
47
47
  #
48
- # @param [Integer] index
49
- # @param [true|false|Float|Integer|String|Array|Hash] value
48
+ # @param index [Integer]
49
+ # @param value [true|false|Float|Integer|String|Array|Hash]
50
50
  # @return [void]
51
51
  def []=(index, value)
52
- yarray_insert(transaction, index, value)
52
+ document.current_transaction { |tx| yarray_insert(tx, index, value) }
53
53
  end
54
54
 
55
55
  # Adds an element to the end of the array
56
56
  #
57
+ # @param value [true|false|Float|Integer|String|::Array|Hash]
57
58
  # @return [void]
58
59
  def <<(value)
59
- yarray_push_back(transaction, value)
60
+ document.current_transaction { |tx| yarray_push_back(tx, value) }
60
61
  end
61
62
 
62
63
  # Attach listener to array changes
@@ -65,19 +66,18 @@ module Y
65
66
  # local = Y::Doc.new
66
67
  #
67
68
  # arr = local.get_array("my array")
68
- # arr.attach(->(delta) { pp delta })
69
+ # arr.attach { |delta| pp delta }
69
70
  #
70
71
  # local.transact do
71
72
  # arr << 1
72
73
  # end
73
74
  #
74
- # @param [Proc] callback
75
- # @param [Block] block
75
+ # @param block [Block]
76
76
  # @return [Integer]
77
- def attach(callback, &block)
78
- return yarray_observe(callback) unless callback.nil?
77
+ def attach(&block)
78
+ raise "provide block" unless block
79
79
 
80
- yarray_observe(block.to_proc) unless block.nil?
80
+ yarray_observe(block.to_proc)
81
81
  end
82
82
 
83
83
  # Adds to array all elements from each Array in `other_arrays`.
@@ -91,19 +91,21 @@ module Y
91
91
  #
92
92
  # arr.to_a == [1, 2, 3] # true
93
93
  #
94
- # @param [Array<Array<Object>>] other_arrays
94
+ # @param other_arrays [Array<Array<Object>>]
95
95
  # @return [void]
96
96
  def concat(*other_arrays)
97
- combined = other_arrays.reduce([]) do |values, arr|
98
- values.concat(arr) if arr.is_a?(::Array)
99
- end
97
+ document.current_transaction do |tx|
98
+ combined = other_arrays.reduce([]) do |values, arr|
99
+ values.concat(arr) if arr.is_a?(::Array)
100
+ end
100
101
 
101
- yarray_insert_range(transaction, size, combined)
102
+ yarray_insert_range(tx, yarray_length(tx), combined)
103
+ end
102
104
  end
103
105
 
104
106
  # Detach listener
105
107
  #
106
- # @param [Integer] subscription_id
108
+ # @param subscription_id [Integer]
107
109
  # @return [void]
108
110
  def detach(subscription_id)
109
111
  yarray_unobserve(subscription_id)
@@ -111,7 +113,7 @@ module Y
111
113
 
112
114
  # @return [void]
113
115
  def each(&block)
114
- yarray_each(block)
116
+ document.current_transaction { |tx| yarray_each(tx, &block) }
115
117
  end
116
118
 
117
119
  # Check if the array is empty
@@ -123,31 +125,35 @@ module Y
123
125
 
124
126
  # Returns first element in array if there is at least one
125
127
  #
126
- # @return [Object|nil]
128
+ # @return [true|false|Float|Integer|String|::Array|Hash|nil]
127
129
  def first
128
- yarray_get(0)
130
+ document.current_transaction { |tx| yarray_get(tx, 0) }
129
131
  end
130
132
 
131
133
  # Returns last element in array if there is at least one element
132
134
  #
133
- # @return [Object|nil]
135
+ # @return [true|false|Float|Integer|String|::Array|Hash|nil]
134
136
  def last
135
- len = yarray_length
136
- return yarray_get(yarray_length - 1) if len.positive?
137
+ document.current_transaction do |tx|
138
+ len = yarray_length(tx)
139
+ return yarray_get(tx, len - 1) if len.positive?
137
140
 
138
- nil
141
+ nil
142
+ end
139
143
  end
140
144
 
141
145
  # rubocop:disable Naming/MethodParameterName
142
146
 
143
147
  # Removes last (n) element(s) from array
144
148
  #
145
- # @param [Integer|nil] n Number of elements to remove
149
+ # @param n [Integer|nil] Number of elements to remove
146
150
  # @return [void]
147
151
  def pop(n = nil)
148
- len = size
149
- yarray_remove(transaction, len - 1) if n.nil?
150
- yarray_remove_range(transaction, len - n, n) unless n.nil?
152
+ document.current_transaction do |tx|
153
+ len = yarray_length(tx)
154
+ yarray_remove(tx, len - 1) if n.nil?
155
+ yarray_remove_range(tx, len - n, n) unless n.nil?
156
+ end
151
157
  end
152
158
 
153
159
  # rubocop:enable Naming/MethodParameterName
@@ -158,11 +164,14 @@ module Y
158
164
 
159
165
  # Removes first (n) element(s) from array
160
166
  #
161
- # @param [Integer|nil] n Number of elements to remove
167
+ # @param n [Integer|nil] Number of elements to remove
162
168
  # @return [void]
163
169
  def shift(n = nil)
164
- yarray_remove(transaction, 0) if n.nil?
165
- yarray_remove_range(transaction, 0, n) unless nil?
170
+ document.current_transaction do |tx|
171
+ yarray_remove(tx, 0) if n.nil?
172
+
173
+ yarray_remove_range(tx, 0, n) unless nil?
174
+ end
166
175
  end
167
176
 
168
177
  # rubocop:enable Naming/MethodParameterName
@@ -171,7 +180,7 @@ module Y
171
180
  #
172
181
  # @return [Integer]
173
182
  def size
174
- yarray_length
183
+ document.current_transaction { |tx| yarray_length(tx) }
175
184
  end
176
185
 
177
186
  alias length size
@@ -208,147 +217,152 @@ module Y
208
217
  #
209
218
  # @return [void]
210
219
  def slice!(*args)
211
- if args.size.zero?
212
- raise ArgumentError,
213
- "Provide one of `index`, `range`, `start, length` as arguments"
214
- end
215
-
216
- if args.size == 1
217
- arg = args.first
220
+ document.current_transaction do |tx| # rubocop:disable Metrics/BlockLength
221
+ if args.size.zero?
222
+ raise ArgumentError,
223
+ "Provide one of `index`, `range`, `start, length` as arguments"
224
+ end
218
225
 
219
- if arg.is_a?(Range)
220
- if arg.exclude_end?
221
- yarray_remove_range(transaction, arg.first,
222
- arg.last - arg.first)
223
- end
224
- unless arg.exclude_end?
225
- yarray_remove_range(transaction, arg.first,
226
- arg.last + 1 - arg.first)
226
+ if args.size == 1
227
+ arg = args.first
228
+
229
+ if arg.is_a?(Range)
230
+ if arg.exclude_end?
231
+ yarray_remove_range(tx, arg.first,
232
+ arg.last - arg.first)
233
+ end
234
+ unless arg.exclude_end?
235
+ yarray_remove_range(tx, arg.first,
236
+ arg.last + 1 - arg.first)
237
+ end
238
+ return nil
227
239
  end
228
- return nil
229
- end
230
240
 
231
- if arg.is_a?(Numeric)
232
- yarray_remove(transaction, arg.to_int)
233
- return nil
241
+ if arg.is_a?(Numeric)
242
+ yarray_remove(tx, arg.to_int)
243
+ return nil
244
+ end
234
245
  end
235
- end
236
246
 
237
- if args.size == 2
238
- first, second = args
247
+ if args.size == 2
248
+ first, second = args
239
249
 
240
- if first.is_a?(Numeric) && second.is_a?(Numeric)
241
- yarray_remove_range(transaction, first, second)
242
- return nil
250
+ if first.is_a?(Numeric) && second.is_a?(Numeric)
251
+ yarray_remove_range(tx, first, second)
252
+ return nil
253
+ end
243
254
  end
244
- end
245
255
 
246
- raise ArgumentError, "Please check your arguments, can't slice."
256
+ raise ArgumentError, "Please check your arguments, can't slice."
257
+ end
247
258
  end
248
259
 
249
260
  # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
250
261
 
251
262
  # Convert this array to a Ruby Array
252
263
  #
253
- # @return [Array<Object>]
264
+ # @return [Array<true|false|Float|Integer|String|::Array|Hash>]
254
265
  def to_a
255
- yarray_to_a
266
+ document.current_transaction { |tx| yarray_to_a(tx) }
256
267
  end
257
268
 
258
269
  # Adds an element to the beginning of the array
259
270
  #
260
271
  # @return [void]
261
272
  def unshift(value)
262
- yarray_push_front(transaction, value)
273
+ document.current_transaction { |tx| yarray_push_front(tx, value) }
263
274
  end
264
275
 
265
276
  alias prepend unshift
266
277
 
267
- private
268
-
269
278
  # @!method yarray_each(proc)
270
279
  # Iterates over all elements in Array by calling the provided proc
271
280
  # with the value as argument.
272
281
  #
273
- # @param [Proc<Object>] proc A proc that is called for every element
282
+ # @param proc [Proc<Object>] A proc that is called for every element
283
+ # @!visibility private
274
284
 
275
- # @!method yarray_get(index)
285
+ # @!method yarray_get(transaction, index)
276
286
  # Retrieves content as specified index
277
287
  #
278
- # @param [Integer] index
288
+ # @param index [Integer]
279
289
  # @return [Object]
290
+ # @!visibility private
280
291
 
281
292
  # @!method yarray_insert(transaction, index, content)
282
293
  # Inserts content at specified index
283
294
  #
284
- # @param [Y::Transaction] transaction
285
- # @param [Integer] index
286
- # @param [Boolean, Float, Integer, Array, Hash, Text] content
295
+ # @param transaction [Y::Transaction]
296
+ # @param index [Integer]
297
+ # @param content [Boolean, Float, Integer, Array, Hash, Text]
287
298
  # @return [void]
299
+ # @!visibility private
288
300
 
289
301
  # @!method yarray_insert_range(transaction, index, arr)
290
302
  # Inserts all elements of a given array at specified index
291
303
  #
292
- # @param [Y::Transaction] transaction
293
- # @param [Integer] index
294
- # @param [Array<Boolean, Float, Integer, Array, Hash, Text>] arr
304
+ # @param transaction [Y::Transaction]
305
+ # @param index [Integer]
306
+ # @param arr [Array<Boolean|Float|Integer|Array|Hash|Text>]
295
307
  # @return [void]
308
+ # @!visibility private
296
309
 
297
- # @!method yarray_length
310
+ # @!method yarray_length(transaction)
298
311
  # Returns length of array
299
312
  #
313
+ # @param transaction [Y::Transaction]
300
314
  # @return [Integer] Length of array
315
+ # @!visibility private
301
316
 
302
317
  # @!method yarray_push_back(transaction, value)
303
318
  # Adds an element to the end of the array
304
319
  #
305
- # @param [Y::Transaction] transaction
306
- # @param [Object] value
320
+ # @param transaction [Y::Transaction]
321
+ # @param value [Object]
307
322
  # @return [void]
323
+ # @!visibility private
308
324
 
309
325
  # @!method yarray_push_front(transaction, value)
310
326
  # Adds an element to the front of the array
311
327
  #
312
- # @param [Y::Transaction] transaction
313
- # @param [Object] value
328
+ # @param transaction [Y::Transaction]
329
+ # @param value [Object]
314
330
  # @return [void]
331
+ # @!visibility private
315
332
 
316
- # @!method yarray_observe(callback)
333
+ # @!method yarray_observe(proc)
317
334
  #
318
- # @param [Proc] callback
335
+ # @param proc [Proc]
319
336
  # @return [Integer]
337
+ # @!visibility private
320
338
 
321
339
  # @!method yarray_remove(transaction, index)
322
340
  # Removes a single element from array at index
323
341
  #
324
- # @param [Y::Transaction] transaction
325
- # @param [Integer] index
342
+ # @param transaction [Y::Transaction]
343
+ # @param index [Integer]
326
344
  # @return [void]
345
+ # @!visibility private
327
346
 
328
347
  # @!method yarray_remove_range(transaction, index, length)
329
348
  # Removes a range of elements from array
330
349
  #
331
- # @param [Y::Transaction] transaction
332
- # @param [Integer] index
333
- # @param [Integer] length
350
+ # @param transaction [Y::Transaction]
351
+ # @param index [Integer]
352
+ # @param length [Integer]
334
353
  # @return [void]
354
+ # @!visibility private
335
355
 
336
- # @!method yarray_to_a
356
+ # @!method yarray_to_a(transaction)
337
357
  # Transforms the array into a Ruby array
338
- #
358
+ # @param transaction [Y::Transaction]
339
359
  # @return [Array]
360
+ # @!visibility private
340
361
 
341
362
  # @!method yarray_unobserve(subscription_id)
342
363
  #
343
- # @param [Integer] subscription_id
364
+ # @param subscription_id [Integer]
344
365
  # @return [void]
345
-
346
- # A reference to the current active transaction of the document this map
347
- # belongs to.
348
- #
349
- # @return [Y::Transaction] A transaction object
350
- def transaction
351
- document.current_transaction
352
- end
366
+ # @!visibility private
353
367
  end
354
368
  end
data/lib/y/awareness.rb CHANGED
@@ -31,7 +31,19 @@ module Y
31
31
  # awareness.local_state = local_state
32
32
  # awareness.diff # [1,227,245,175,195,11,1,65,123, …]
33
33
  #
34
+ # @example Two connected clients
35
+ # local_state_a = { name: "User A" }.to_json
34
36
  #
37
+ # client_a = Y::Awareness.new
38
+ # client_a.local_state = local_state
39
+ #
40
+ # local_state_b = { name: "User B" }.to_json
41
+ #
42
+ # client_b = Y::Awareness.new
43
+ # client_b.local_state = local_state_b
44
+ #
45
+ # client_a.sync(client_b.diff)
46
+ # client_a.clients # {1242157267=>"{\"name\":\"User A\"}", 2401067547=>…
35
47
  class Awareness
36
48
  # Applies an incoming update. This gets the local awareness instance in
37
49
  # sync with changes from another client. i.e., updates the state of another
@@ -43,7 +55,7 @@ module Y
43
55
  # awareness = Y::Awareness.new
44
56
  # awareness.sync(update)
45
57
  #
46
- # @param [Array<Integer>] diff A binary encoded update
58
+ # @param diff [Array<Integer>] A binary encoded update
47
59
  # @return [void]
48
60
  def sync(diff)
49
61
  yawareness_apply_update(diff)
@@ -131,7 +143,7 @@ module Y
131
143
 
132
144
  # Unsubscribe from changes
133
145
  #
134
- # @param [Integer] subscription_id
146
+ # @param subscription_id [Integer]
135
147
  # @return [void]
136
148
  def detach(subscription_id)
137
149
  yawareness_remove_on_update(subscription_id)
@@ -140,7 +152,7 @@ module Y
140
152
  # Clears out a state of a given client, effectively marking it as
141
153
  # disconnected.
142
154
  #
143
- # @param [Integer] client_id Clears the state for given client_id
155
+ # @param client_id [Integer] Clears the state for given client_id
144
156
  # @return [void]
145
157
  def remove_state(client_id)
146
158
  yawareness_remove_state(client_id)
@@ -160,7 +172,7 @@ module Y
160
172
  # be known to a current Awareness instance, otherwise a
161
173
  # Error::ClientNotFound error will be returned.
162
174
  #
163
- # @param [::Array<Integer>] clients A list of client IDs
175
+ # @param clients [::Array<Integer>] A list of client IDs
164
176
  # @return [String] Binary encoded update including all given client IDs
165
177
  def diff_with_clients(*clients)
166
178
  yawareness_update_with_clients(clients)
@@ -172,22 +184,26 @@ module Y
172
184
  # @!method yawareness_apply_update(update)
173
185
  # Applies an update
174
186
  #
175
- # @param [Y::AwarenessUpdate] A structure that represents an encodable state
187
+ # @param A [Y::AwarenessUpdate] Structure that represents an encodable state
176
188
  # of an Awareness struct.
189
+ # @!visibility private
177
190
 
178
191
  # @!method yawareness_apply_update(update)
179
192
  # Applies an update
180
193
  #
181
- # @param [Y::AwarenessUpdate] A structure that represents an encodable state
194
+ # @param A [Y::AwarenessUpdate] Structure that represents an encodable state
182
195
  # of an Awareness struct.
196
+ # @!visibility private
183
197
 
184
198
  # @!method yawareness_clean_local_state
185
199
  # Clears out a state of a current client , effectively marking it as
186
200
  # disconnected.
201
+ # @!visibility private
187
202
 
188
203
  # @!method yawareness_client_id
189
204
  # Returns a globally unique client ID of an underlying Doc.
190
205
  # @return [Integer] The Client ID
206
+ # @!visibility private
191
207
 
192
208
  # @!method yawareness_clients
193
209
  # Returns a state map of all of the clients
@@ -196,28 +212,33 @@ module Y
196
212
  # replicated to other clients as a JSON string.
197
213
  #
198
214
  # @return [Hash<Integer, String>] Map of clients
215
+ # @!visibility private
199
216
 
200
217
  # @!method yawareness_local_state
201
218
  #
202
219
  # @return [String|nil] Returns a JSON string state representation of a
203
220
  # current Awareness instance.
221
+ # @!visibility private
204
222
 
205
223
  # @!method yawareness_on_update(callback, &block)
206
224
  #
207
- # @param [Proc] A callback handler for updates
225
+ # @param callback [callback]
208
226
  # @return [Integer] The subscription ID
227
+ # @!visibility private
209
228
 
210
229
  # @!method yawareness_remove_on_update(subscription_id)
211
230
  #
212
- # @param [Integer] subscription_id The subscription id to remove
231
+ # @param subscription_id [Integer] The subscription id to remove
232
+ # @!visibility private
213
233
 
214
234
  # @!method yawareness_remove_state(client_id)
215
235
  # Clears out a state of a given client, effectively marking it as
216
236
  # disconnected.
217
237
  #
218
- # @param [Integer] client_id A Client ID
238
+ # @param client_id [Integer] A Client ID
219
239
  # @return [String|nil] Returns a JSON string state representation of a
220
240
  # current Awareness instance.
241
+ # @!visibility private
221
242
 
222
243
  # @!method yawareness_set_local_state(state)
223
244
  # Sets a current Awareness instance state to a corresponding JSON string.
@@ -225,16 +246,18 @@ module Y
225
246
  # AwarenessUpdate and it will trigger an event to be emitted if current
226
247
  # instance was created using [Awareness::with_observer] method.
227
248
  #
228
- # @param [String] Returns a state map of all of the clients tracked by
249
+ # @param Returns [String] A state map of all of the clients tracked by
229
250
  # current Awareness instance. Those states are identified by their
230
251
  # corresponding ClientIDs. The associated state is represented and
231
252
  # replicated to other clients as a JSON string.
253
+ # @!visibility private
232
254
 
233
255
  # @!method yawareness_update
234
256
  # Returns a serializable update object which is representation of a
235
257
  # current Awareness state.
236
258
  #
237
259
  # @return [Y::AwarenessUpdate] The update object
260
+ # @!visibility private
238
261
 
239
262
  # @!method yawareness_update_with_clients(clients)
240
263
  # Returns a serializable update object which is representation of a
@@ -243,24 +266,27 @@ module Y
243
266
  # These clients must all be known to a current Awareness instance,
244
267
  # otherwise an error will be returned.
245
268
  #
246
- # @param [::Array<Integer>] clients
269
+ # @param clients [::Array<Integer>]
247
270
  # @return [::Array<Integer>] A serialized (binary encoded) update object
271
+ # @!visibility private
248
272
 
249
273
  # rubocop:enable Lint/UselessAccessModifier
250
274
  end
251
275
 
252
- # rubocop:disable Lint/UselessAccessModifier
276
+ # @!visibility private
253
277
  class AwarenessEvent
254
- private
278
+ private # rubocop:disable Lint/UselessAccessModifier
255
279
 
256
280
  # @!method added
257
281
  # @return [::Array<Integer>] Added clients
282
+ # @!visibility private
258
283
 
259
284
  # @!method updated
260
285
  # @return [::Array<Integer>] Updated clients
286
+ # @!visibility private
261
287
 
262
288
  # @!method removed
263
289
  # @return [::Array<Integer>] Removed clients
290
+ # @!visibility private
264
291
  end
265
- # rubocop:enable Lint/UselessAccessModifier
266
292
  end