From cd0bd28b1dfd07b76663fa250fbf7f27e8f6f8d7 Mon Sep 17 00:00:00 2001
From: fbasso <fabrice.basso@amadeus.com>
Date: Tue, 26 Dec 2023 15:50:38 +0100
Subject: [PATCH] doc: more complete usage explanation in readme

---
 README.md | 151 +++++++++++++++++++++++++++++++++---------------------
 1 file changed, 92 insertions(+), 59 deletions(-)

diff --git a/README.md b/README.md
index 4b87c75..b1648b7 100644
--- a/README.md
+++ b/README.md
@@ -17,6 +17,98 @@ Main characteristics:
 
 Implementation wise, it is a tiny (1300 LOC) library without any external dependencies.
 
+## Installation
+
+You can add Tansu to your project by installing the `@amadeus-it-group/tansu` package using your favorite package manager, ex.:
+
+* `yarn add @amadeus-it-group/tansu`
+* `npm install @amadeus-it-group/tansu`
+
+## Usage
+
+### writable
+
+A `writable` is the essential building block of a "store", a container that encapsulates a value and allows for observing and modifying its state.
+
+To be notified whenever the value changes, you may utilize the subscribe() method with a callback function.
+
+
+```typescript
+const value$ = writable(0);
+
+values$.subscribe((value) => {
+  console.log(`value = ${value}`);
+});
+
+value.set(1);
+```
+> [!NOTE]
+> value = 0
+> value = 1
+
+
+
+### derived
+### computed
+### getting the value
+### batch
+### asReadable
+### asWritable
+    Ex: localStorage
+
+
+
+
+Here is an example of an Angular component using a Tansu store:
+
+```typescript
+import { Component } from "@angular/core";
+import { AsyncPipe } from '@angular/common';
+import { Store, computed, get } from "@amadeus-it-group/tansu";
+
+// A store is a class extending Store from Tansu
+class CounterStore extends Store<number> {
+  constructor() {
+    super(0); // initialize store's value (state)
+  }
+
+  // implement state manipulation logic as regular methods
+  increment() {
+    // create new state based on the current state
+    this.update(value => value + 1);
+  }
+
+  reset() {
+    // replace the entire state with a new value
+    this.set(0);
+  }
+}
+
+@Component({
+  selector: "my-app",
+  template: `
+    <button (click)="counter$.increment()">+</button> <br />
+
+    <!-- store values can be displayed in a template with the standard async pipe -->
+    Counter: {{ counter$ | async }} <br />
+    Double counter: {{ doubleCounter$ | async }} <br />
+  `,
+  standalone: true,
+  imports: [AsyncPipe]
+})
+export class App {
+  //  A store can be instantiated directly or registered in the DI container
+  counter$ = new CounterStore();
+
+  // One can easily create computed values by specifying a transformation function
+  doubleCounter$ = computed(() => 2 * get(this.counter$));
+}
+```
+
+While being fairly minimal, this example demonstrates most of the Tansu APIs.
+
+Check the [documentation](http://amadeusitgroup.github.io/tansu/) for the complete API and more usage examples.
+
 ## Comparison with the Svelte stores
 
 Tansu is designed to be and to remain fully compatible with Svelte. Nevertheless, it brings several improvements:
@@ -143,65 +235,6 @@ Sherlock Holmes
 Process end
 ```
 
-## Installation
-
-You can add Tansu to your project by installing the `@amadeus-it-group/tansu` package using your favorite package manager, ex.:
-
-* `yarn add @amadeus-it-group/tansu`
-* `npm install @amadeus-it-group/tansu`
-
-## Usage
-
-Here is an example of an Angular component using a Tansu store:
-
-```typescript
-import { Component } from "@angular/core";
-import { AsyncPipe } from '@angular/common';
-import { Store, computed, get } from "@amadeus-it-group/tansu";
-
-// A store is a class extending Store from Tansu
-class CounterStore extends Store<number> {
-  constructor() {
-    super(0); // initialize store's value (state)
-  }
-
-  // implement state manipulation logic as regular methods
-  increment() {
-    // create new state based on the current state
-    this.update(value => value + 1);
-  }
-
-  reset() {
-    // replace the entire state with a new value
-    this.set(0);
-  }
-}
-
-@Component({
-  selector: "my-app",
-  template: `
-    <button (click)="counter$.increment()">+</button> <br />
-
-    <!-- store values can be displayed in a template with the standard async pipe -->
-    Counter: {{ counter$ | async }} <br />
-    Double counter: {{ doubleCounter$ | async }} <br />
-  `,
-  standalone: true,
-  imports: [AsyncPipe]
-})
-export class App {
-  //  A store can be instantiated directly or registered in the DI container
-  counter$ = new CounterStore();
-
-  // One can easily create computed values by specifying a transformation function
-  doubleCounter$ = computed(() => 2 * get(this.counter$));
-}
-```
-
-While being fairly minimal, this example demonstrates most of the Tansu APIs.
-
-Check the [documentation](http://amadeusitgroup.github.io/tansu/) for the complete API and more usage examples.
-
 ## Contributing to the project
 
 Please check the [DEVELOPER.md](DEVELOPER.md) for documentation on building and testing the project on your local development machine.