telescope

Description:

telescope

Telescope #

Easy to use State manager for flutter based on observer👀 design pattern.
Telescope is more than a normal observer.
Telescope🔭

0. Supports all platforms.

Easy to learn📖

You can learn it in 5-10 min by reading README.
Also see examples.
Full dart standard documentation here.


Feature rich♥️

Can directly bind to Flutters StateFullWidget and rebuild♻️ widget on value change.
Save states on disk and load when needed.
Telescopes can watch each other with dependsOn() constructor.
Depends on can be async.
Caching ability with expireTime option.
debounceTime option (something like rx-js debounceTime).
Request a feature here.


Make it harder to make bugs🪲⛔.

With separation of concerns🙌.
No setState() needed🙅.


Fast⚡ (just rebuild widgets that need to rebuild).
Lightweight🐥 (less then 900KB)
Flexible🌊

It lets you do it in your way as a library (not a framework)💪.
Can be used beside other state managers👫.



Installation: #
flutter pub add telescope
copied to clipboard
Import: #
import 'package:telescope/telescope.dart';
copied to clipboard
How to use #
In 3 steps.
1. Make a telescope instance: #
var textValue = Telescope("default value");
copied to clipboard
2. Watch(this): #
Put this in middle of you widget build function.
@override
Widget build(BuildContext context) {
return Material(
child: SafeArea(
child: Container(
child: Column(children: [
// watch like this ('this' is State that will automatically rebuild on data change)
Text(textValue.watch(this)),
Text(textValue.watch(this)),
Text(textValue.watch(this).length.toString()),
],),
)
)
);
}
copied to clipboard
Note: You can watch one telescope instance from multiple widgets(example).
3. Update value: #
You can update telescope.value from anywhere in your code:
onTap: (){
textValue.value += "a";
}
copied to clipboard
Boom: #
And the widget will get update automatically without calling setState.

You can also subscribe to observable by passing callback like a normal observable.
textValue.subscribe((newValue){
// execute on value change
});
copied to clipboard
Non Builtin Types #
Just implement hashCode getter:
class Human{
int height;
int weight;
Human(this.height,this.weight);

@override
int get hashCode => height*weight;
}
copied to clipboard
And you are good to go:
var human = Telescope<Human>(null);
copied to clipboard
Other features: #
Depends on: #
Telescopes can be depended on other telescopes.
var height = Telescope(186);
var weight = Telescope(72);

var bmi = Telescope.dependsOn([height,weight], () {
return weight.value / ((height.value/100) * (height.value/100));
});

var showingText = Telescope.dependsOn([bmi], () {
return "weight is ${weight.value} and height is ${height.value} so bmi will be ${bmi.value.toString().substring(0,5)}";
});
copied to clipboard
So when ever height or weight value get changes, the bmi will calculate itself because it depends on height and weight.
And showingText will calculate itself too, because it depends on bmi.

Async way:
var bmi = Telescope.dependsOnAsync(0, [height, weight], () async {
return await calculateBMI(height.value, weight.value);
});
copied to clipboard

Caching:
var bmi = Telescope.dependsOnAsync(0, [height, weight], () async {
return await calculateBMI(height.value, weight.value);
}, enableCaching: true);
copied to clipboard
You can also set expire time by passing cacheExpireTime.

Debounce:
debounceTime: will call your async function only if a given time has passed without any changes on dependencies.
var bmi = Telescope.dependsOnAsync(0, [height, weight], () async {
return await calculateBMI(height.value, weight.value);
}, debounceTime: Duration(milliseconds: 500));
copied to clipboard
It's useful when you want to run your async function when user stop typing or moving slider or...

Observable on loading state:
This will make isCalculatingBMI true on loading and false when loaded, you may need this to show loading animation.
var isCalculatingBMI = Telescope<bool>(false);
var bmi = Telescope.dependsOnAsync(0, [height, weight], () async {
return await calculateBMI(height.value, weight.value);
}, isCalculating: isCalculatingBMI);
copied to clipboard
Save On Disk #
You can save telescope data on disk easily like this:
var height = Telescope.saveOnDiskForBuiltInType(187, "bmi_height_input");
copied to clipboard
So if user close the app and open it again it will load last value of telescope for You.

TelescopeList #
Telescope implementation for list

can be dependent
can save on disk

var items = TelescopeList(["ab", "abb", "bc", "bcc" , "c"]);
copied to clipboard
Save non built in values on disk #
You need to implement OnDiskSaveAbility for your object:
For example you have Human class:
class Human{
int height;
int weight;
Human(this.height,this.weight);

@override
int get hashCode => height*weight;
}
copied to clipboard
Then you need to make other class like this for Human:
class HumanOnDiskAbility implements OnDiskSaveAbility<Human>{
@override
Human parseOnDiskString(String data) {
var sp = data.split(":");
return Human(int.parse(sp[0]), int.parse(sp[1]));
}

@override
String toOnDiskString(Human instance) => "${instance.height}:${instance.weight}";
}
copied to clipboard
And pass instance of HumanOnDiskAbility to Telescope:
var human = Telescope.saveOnDiskForNonBuiltInType(
Human(187, 72),
"human_for_bmi",
HumanOnDiskAbility()
);
copied to clipboard
Telescope will use 'parseOnDiskString' and 'toOnDiskString' to serialize and deserialize your object.

This method also can use in TelescopeList in same way.
Last Words: #

Plz🙏 star⭐ repo.
Full documentation.
Examples.
Static instance of Telescopes?

it's not recommend because it decreases re-usability of your code, but in some use-cases it's OK to do that.


Extends from Telescope?

Why not? TelescopeList actually extends from Telescope


Under MIT license