Update documentation

CHANGELOG.md

@@ -1,3 +1,3 @@
-## 0.0.1-pre.2
+## 0.0.1-pre.3
 
 - **ADDED**: Initial release

lib/spinify.dart

@@ -19,13 +19,11 @@ export 'package:spinify/src/model/presence.dart';
 export 'package:spinify/src/model/presence_stats.dart';
 export 'package:spinify/src/model/publication.dart';
 export 'package:spinify/src/model/pushes_stream.dart';
-export 'package:spinify/src/model/refresh.dart' show SpinifyRefresh;
+export 'package:spinify/src/model/refresh.dart';
 export 'package:spinify/src/model/stream_position.dart';
 export 'package:spinify/src/model/subscribe.dart';
 export 'package:spinify/src/model/unsubscribe.dart';
 export 'package:spinify/src/subscription/subcibed_on_channel.dart';
-export 'package:spinify/src/subscription/subscription.dart'
-    show SpinifyClientSubscription, SpinifyServerSubscription;
 export 'package:spinify/src/subscription/subscription.dart';
 export 'package:spinify/src/subscription/subscription_config.dart';
 export 'package:spinify/src/subscription/subscription_state.dart';

lib/src/client/observer.dart

@@ -23,10 +23,10 @@ abstract class SpinifyObserver {
   /// from [prev] to [next].
   void onStateChanged(ISpinify client, SpinifyState prev, SpinifyState next) {}
 
-  /// Called whenever a [ISpinifySubscription] changes its state
+  /// Called whenever a [SpinifySubscription] changes its state
   /// from [prev] to [next].
   /// Works both for client-side and server-side subscriptions.
-  void onSubscriptionChanged(ISpinifySubscription subscription,
+  void onSubscriptionChanged(SpinifySubscription subscription,
       SpinifySubscriptionState prev, SpinifySubscriptionState next) {}
 
   /// Called whenever a [ISpinify] client changes its state

lib/src/client/spinify.dart

@@ -33,7 +33,23 @@ import 'package:spinify/src/util/event_queue.dart';
 import 'package:spinify/src/util/logger.dart' as logger;
 
 /// {@template spinify}
-/// Spinify client.
+/// Spinify client for Centrifuge.
+///
+/// Centrifugo SDKs use WebSocket as the main data transport and send/receive
+/// messages encoded according to our bidirectional protocol.
+/// That protocol is built on top of the Protobuf schema
+/// (both JSON and binary Protobuf formats are supported).
+/// It provides asynchronous communication, sending RPC,
+/// multiplexing subscriptions to channels, etc.
+///
+/// Client SDK wraps the protocol and exposes a set of APIs to developers.
+///
+/// Client connection has 4 states:
+/// - [SpinifyState$Disconnected]
+/// - [SpinifyState$Connecting]
+/// - [SpinifyState$Connected]
+/// - [SpinifyState$Closed]
+///
 /// {@endtemplate}
 /// {@category Client}
 final class Spinify extends SpinifyBase

lib/src/client/state.dart

@@ -198,7 +198,7 @@ final class SpinifyState$Disconnected extends SpinifyState with _$SpinifyState {
           other.timestamp.isAtSameMomentAs(timestamp));
 
   @override
-  String toString() => 'SpinifyState.disconnected{$timestamp}';
+  String toString() => r'SpinifyState$Disconnected{}';
 }
 
 /// Connecting
@@ -250,7 +250,7 @@ final class SpinifyState$Connecting extends SpinifyState with _$SpinifyState {
           other.timestamp.isAtSameMomentAs(timestamp));
 
   @override
-  String toString() => 'SpinifyState.connecting{$timestamp}';
+  String toString() => r'SpinifyState$Connecting{}';
 }
 
 /// Connected
@@ -357,7 +357,7 @@ final class SpinifyState$Connected extends SpinifyState with _$SpinifyState {
           other.timestamp.isAtSameMomentAs(timestamp));
 
   @override
-  String toString() => 'SpinifyState.connected{$timestamp}';
+  String toString() => r'SpinifyState$Connected{}';
 }
 
 /// Permanently closed
@@ -409,13 +409,14 @@ final class SpinifyState$Closed extends SpinifyState with _$SpinifyState {
           other.timestamp.isAtSameMomentAs(timestamp));
 
   @override
-  String toString() => 'SpinifyState.closed{$timestamp}';
+  String toString() => r'SpinifyState$Closed{}';
 }
 
 /// {@nodoc}
 base mixin _$SpinifyState on SpinifyState {}
 
 /// Pattern matching for [SpinifyState].
+/// {@category Entity}
 typedef SpinifyStateMatch<R, S extends SpinifyState> = R Function(S state);
 
 /// {@nodoc}

lib/src/model/channel_presence.dart

@@ -6,9 +6,8 @@ import 'package:spinify/src/model/client_info.dart';
 /// Channel presence.
 /// Join / Leave events.
 /// {@endtemplate}
-/// {@category Entity}
-/// {@subCategory Channel}
-/// {@subCategory Presence}
+/// {@category Event}
+/// {@subCategory Push}
 @immutable
 sealed class SpinifyChannelPresence extends SpinifyChannelPush {
   /// {@macro channel_presence}
@@ -29,6 +28,9 @@ sealed class SpinifyChannelPresence extends SpinifyChannelPush {
 }
 
 /// {@macro channel_presence}
+/// {@category Event}
+/// {@subCategory Push}
+/// {@subCategory Presence}
 final class SpinifyJoin extends SpinifyChannelPresence {
   /// {@macro channel_presence}
   const SpinifyJoin({
@@ -45,9 +47,15 @@ final class SpinifyJoin extends SpinifyChannelPresence {
 
   @override
   bool get isLeave => false;
+
+  @override
+  String toString() => 'SpinifyJoin{channel: $channel}';
 }
 
 /// {@macro channel_presence}
+/// {@category Event}
+/// {@subCategory Push}
+/// {@subCategory Presence}
 final class SpinifyLeave extends SpinifyChannelPresence {
   /// {@macro channel_presence}
   const SpinifyLeave({
@@ -64,4 +72,7 @@ final class SpinifyLeave extends SpinifyChannelPresence {
 
   @override
   bool get isLeave => true;
+
+  @override
+  String toString() => 'SpinifyLeave{channel: $channel}';
 }

lib/src/model/channel_push.dart

@@ -4,6 +4,9 @@ import 'package:spinify/src/model/event.dart';
 /// {@template spinify_channel_push}
 /// Base class for all channel push events.
 /// {@endtemplate}
+/// {@category Event}
+/// {@subCategory Push}
+@immutable
 abstract base class SpinifyChannelPush extends SpinifyEvent {
   /// {@template spinify_channel_push}
   const SpinifyChannelPush({
@@ -17,4 +20,7 @@ abstract base class SpinifyChannelPush extends SpinifyEvent {
   @override
   @nonVirtual
   bool get isPush => true;
+
+  @override
+  String toString() => 'SpinifyChannelPush{channel: $channel}';
 }

lib/src/model/connect.dart

@@ -3,6 +3,8 @@ import 'package:spinify/src/model/channel_push.dart';
 /// {@template connect}
 /// Connect push from Centrifugo server.
 /// {@endtemplate}
+/// {@category Event}
+/// {@subCategory Push}
 final class SpinifyConnect extends SpinifyChannelPush {
   /// {@macro connect}
   const SpinifyConnect({
@@ -51,4 +53,7 @@ final class SpinifyConnect extends SpinifyChannelPush {
 
   /// Payload of connected push.
   final List<int> data;
+
+  @override
+  String toString() => 'SpinifyConnect{channel: $channel}';
 }

lib/src/model/disconnect.dart

@@ -3,6 +3,8 @@ import 'package:spinify/src/model/channel_push.dart';
 /// {@template disconnect}
 /// Disconnect push from Centrifugo server.
 /// {@endtemplate}
+/// {@category Event}
+/// {@subCategory Push}
 final class SpinifyDisconnect extends SpinifyChannelPush {
   /// {@macro disconnect}
   const SpinifyDisconnect({
@@ -24,4 +26,7 @@ final class SpinifyDisconnect extends SpinifyChannelPush {
 
   /// Reconnect flag.
   final bool reconnect;
+
+  @override
+  String toString() => 'SpinifyDisconnect{channel: $channel}';
 }

lib/src/model/event.dart

@@ -3,8 +3,9 @@ import 'package:meta/meta.dart';
 /// {@template spinify_event}
 /// Base class for all channel events.
 /// {@endtemplate}
+/// {@category Event}
 @immutable
-abstract base class SpinifyEvent {
+abstract base class SpinifyEvent implements Comparable<SpinifyEvent> {
   /// {@template spinify_event}
   const SpinifyEvent({
     required this.timestamp,
@@ -18,4 +19,10 @@ abstract base class SpinifyEvent {
 
   /// Whether this event is a push event.
   bool get isPush;
+
+  @override
+  int compareTo(SpinifyEvent other) => timestamp.compareTo(other.timestamp);
+
+  @override
+  String toString() => 'SpinifyEvent{type: $type}';
 }

lib/src/model/history.dart

@@ -19,4 +19,7 @@ final class SpinifyHistory {
 
   /// Offset and epoch of last publication in publications list
   final SpinifyStreamPosition since;
+
+  @override
+  String toString() => 'SpinifyHistory{}';
 }

lib/src/model/jwt.dart

@@ -19,6 +19,7 @@ import 'package:meta/meta.dart';
 /// https://centrifugal.dev/docs/server/authentication#connection-jwt-claims
 /// {@endtemplate}
 /// {@category Entity}
+/// {@subCategory JWT}
 @immutable
 sealed class SpinifyJWT {
   /// {@macro jwt}

lib/src/model/message.dart

@@ -3,6 +3,8 @@ import 'package:spinify/src/model/channel_push.dart';
 /// {@template message}
 /// Message push from Centrifugo server.
 /// {@endtemplate}
+/// {@category Event}
+/// {@subCategory Push}
 final class SpinifyMessage extends SpinifyChannelPush {
   /// {@macro message}
   const SpinifyMessage({
@@ -16,4 +18,7 @@ final class SpinifyMessage extends SpinifyChannelPush {
 
   /// Payload of message.
   final List<int> data;
+
+  @override
+  String toString() => 'SpinifyMessage{channel: $channel}';
 }

lib/src/model/presence.dart

@@ -18,4 +18,7 @@ final class SpinifyPresence {
 
   /// Publications
   final Map<String, SpinifyClientInfo> clients;
+
+  @override
+  String toString() => 'SpinifyPresence{channel: $channel}';
 }

lib/src/model/presence_stats.dart

@@ -21,4 +21,7 @@ final class SpinifyPresenceStats {
 
   /// Users count
   final int users;
+
+  @override
+  String toString() => 'SpinifyPresenceStats{channel: $channel}';
 }

lib/src/model/publication.dart

@@ -6,7 +6,8 @@ import 'package:spinify/src/model/client_info.dart';
 /// {@template publication}
 /// Publication context
 /// {@endtemplate}
-/// {@category Entity}
+/// {@category Event}
+/// {@subCategory Push}
 @immutable
 final class SpinifyPublication extends SpinifyChannelPush {
   /// {@macro publication}
@@ -34,4 +35,7 @@ final class SpinifyPublication extends SpinifyChannelPush {
 
   /// Optional tags, this is a map with string keys and string values
   final Map<String, String>? tags;
+
+  @override
+  String toString() => 'SpinifyPublication{channel: $channel}';
 }

lib/src/model/pushes_stream.dart

@@ -1,19 +1,22 @@
 import 'dart:async';
 
+import 'package:meta/meta.dart';
 import 'package:spinify/src/model/channel_presence.dart';
 import 'package:spinify/src/model/channel_push.dart';
 import 'package:spinify/src/model/event.dart';
 import 'package:spinify/src/model/message.dart';
 import 'package:spinify/src/model/publication.dart';
 
 /// Stream of received pushes from Centrifugo server for a channel.
-/// {@category Entity}
-/// {@subCategory Pushes}
-/// {@subCategory Events}
+/// {@category Event}
+/// {@category Client}
+/// {@category Subscription}
+/// {@subCategory Push}
 /// {@subCategory Channel}
+@immutable
 final class SpinifyPushesStream extends StreamView<SpinifyChannelPush> {
   /// Stream of received events.
-  SpinifyPushesStream({
+  const SpinifyPushesStream({
     required Stream<SpinifyChannelPush> pushes,
     required this.publications,
     required this.messages,
@@ -45,4 +48,7 @@ final class SpinifyPushesStream extends StreamView<SpinifyChannelPush> {
           _ => null,
         },
       )).asBroadcastStream();
+
+  @override
+  String toString() => 'SpinifyPushesStream{}';
 }

lib/src/model/refresh.dart

@@ -1,9 +1,10 @@
-import 'package:meta/meta.dart';
 import 'package:spinify/src/model/channel_push.dart';
 
 /// {@template refresh}
 /// Refresh push from Centrifugo server.
 /// {@endtemplate}
+/// {@category Event}
+/// {@subCategory Push}
 final class SpinifyRefresh extends SpinifyChannelPush {
   /// {@macro refresh}
   const SpinifyRefresh({
@@ -21,46 +22,7 @@ final class SpinifyRefresh extends SpinifyChannelPush {
 
   /// Time when connection will be expired
   final DateTime? ttl;
-}
-
-/// {@nodoc}
-@internal
-@immutable
-final class SpinifyRefreshResult {
-  /// {@nodoc}
-  const SpinifyRefreshResult({
-    required this.expires,
-    this.client,
-    this.version,
-    this.ttl,
-  });
-
-  /// Unique client connection ID server issued to this connection
-  final String? client;
-
-  /// Server version
-  final String? version;
-
-  /// Whether a server will expire connection at some point
-  final bool expires;
-
-  /// Time when connection will be expired
-  final DateTime? ttl;
-}
 
-/// {@nodoc}
-@internal
-@immutable
-final class SpinifySubRefreshResult {
-  /// {@nodoc}
-  const SpinifySubRefreshResult({
-    required this.expires,
-    this.ttl,
-  });
-
-  /// Whether a server will expire subscription at some point
-  final bool expires;
-
-  /// Time when subscription will be expired
-  final DateTime? ttl;
+  @override
+  String toString() => 'SpinifyRefresh{channel: $channel}';
 }