From 6099591e52db0cee439c45ab0c8a1e4d38a3bbe3 Mon Sep 17 00:00:00 2001 From: Corbin Crutchley Date: Thu, 26 Dec 2024 14:18:25 -0800 Subject: [PATCH] docs: finish vanilla JS quick-start guide --- docs/config.json | 8 +- docs/framework/angular/quick-start.md | 2 +- docs/framework/react/quick-start.md | 4 +- docs/framework/solid/quick-start.md | 2 +- docs/framework/svelte/quick-start.md | 4 +- docs/framework/vue/quick-start.md | 2 +- docs/installation.md | 2 +- docs/quick-start.md | 153 ++++++++++++++++++++++++++ 8 files changed, 168 insertions(+), 9 deletions(-) create mode 100644 docs/quick-start.md diff --git a/docs/config.json b/docs/config.json index a27625f..f7f620e 100644 --- a/docs/config.json +++ b/docs/config.json @@ -16,6 +16,10 @@ { "label": "Installation", "to": "installation" + }, + { + "label": "Quick Start", + "to": "quick-start" } ], "frameworks": [ @@ -88,7 +92,7 @@ { "label": "Interfaces / StoreOptions", "to": "reference/interfaces/storeoptions" - } + }, { "label": "Interfaces / DerivedOptions", "to": "reference/interfaces/derivedoptions" @@ -224,4 +228,6 @@ ] } ] + } + ] } diff --git a/docs/framework/angular/quick-start.md b/docs/framework/angular/quick-start.md index 08537c1..454e1a5 100644 --- a/docs/framework/angular/quick-start.md +++ b/docs/framework/angular/quick-start.md @@ -3,7 +3,7 @@ title: Quick Start id: quick-start --- -The basic angular app example to get started with the Tanstack angular-store. +The basic angular app example to get started with the TanStack angular-store. **app.component.ts** ```angular-ts diff --git a/docs/framework/react/quick-start.md b/docs/framework/react/quick-start.md index cf61e19..8674add 100644 --- a/docs/framework/react/quick-start.md +++ b/docs/framework/react/quick-start.md @@ -3,7 +3,7 @@ title: Quick Start id: quick-start --- -The basic react app example to get started with the Tanstack react-store. +The basic react app example to get started with the TanStack react-store. ```tsx import React from "react"; @@ -56,4 +56,4 @@ const root = ReactDOM.createRoot(document.getElementById("root")); root.render(); -``` \ No newline at end of file +``` diff --git a/docs/framework/solid/quick-start.md b/docs/framework/solid/quick-start.md index d0bd4af..c4e29bb 100644 --- a/docs/framework/solid/quick-start.md +++ b/docs/framework/solid/quick-start.md @@ -3,7 +3,7 @@ title: Quick Start id: quick-start --- -The basic Solid app example to get started with the Tanstack Solid-store. +The basic Solid app example to get started with the TanStack Solid-store. ```jsx import { useStore, Store } from '@tanstack/solid-store'; diff --git a/docs/framework/svelte/quick-start.md b/docs/framework/svelte/quick-start.md index b6682ca..39b9a76 100644 --- a/docs/framework/svelte/quick-start.md +++ b/docs/framework/svelte/quick-start.md @@ -3,7 +3,7 @@ title: Quick Start id: quick-start --- -The basic Svelte app example to get started with the Tanstack svelte-store. +The basic Svelte app example to get started with the TanStack svelte-store. **store.ts** ```ts @@ -65,4 +65,4 @@ export function updateState(animal: 'cats' | 'dogs') { -``` \ No newline at end of file +``` diff --git a/docs/framework/vue/quick-start.md b/docs/framework/vue/quick-start.md index 7764ad1..de3d989 100644 --- a/docs/framework/vue/quick-start.md +++ b/docs/framework/vue/quick-start.md @@ -3,7 +3,7 @@ title: Quick Start id: quick-start --- -The basic vue app example to get started with the Tanstack vue-store. +The basic vue app example to get started with the TanStack vue-store. **App.vue** ```html diff --git a/docs/installation.md b/docs/installation.md index 3fff5c6..28390d0 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -27,7 +27,7 @@ TanStack Store is compatible with Vue 2 and 3. npm install @tanstack/angular-store ``` -TanStack Store is compatible with Angular 16+ +TanStack Store is compatible with Angular 19+ ## SolidJS diff --git a/docs/quick-start.md b/docs/quick-start.md new file mode 100644 index 0000000..c0b2daf --- /dev/null +++ b/docs/quick-start.md @@ -0,0 +1,153 @@ +--- +title: Quick Start +id: quick-start +--- + +TanStack Store is, first and foremost, a framework-agnostic signals implementation. + +It can be used with any of our framework adapters, but can also be used in vanilla JavaScript or TypeScript. It's currently used to power many of our library's internals. + +# Store + +You'll start by creating a new store instance, which is a wrapper around your data: + +```typescript +import { Store } from '@tanstack/store'; + +const countStore = new Store(0); + +console.log(countStore.state); // 0 +countStore.setState(() => 1); +console.log(countStore.state); // 1 +``` + +This `Store` can then be used to track updates to your data: + +```typescript +const unsub = countStore.subscribe(() => { + console.log('The count is now:', count.state); +}); + +// Later, to cleanup +unsub(); +``` + +You can even transform the data before it's updated: + +```typescript +const count = new Store(12, { + updateFn: (prevValue) => updateValue => { + return updateValue + prevValue; + } +}); + +count.setState(() => 12); +// count.state === 24 +``` + +And implement a primitive form of derived state: + +```typescript +let double = 0; +const count = new Store(0, { + onUpdate: () => { + double = count.state * 2; + } +}) +``` + +## Batch Updates + +You can batch updates to a store by using the `batch` function: + +```typescript +import { batch } from '@tanstack/store'; + +// countStore.subscribers will only trigger once at the end with the final state +batch(() => { + countStore.setState(() => 1); + countStore.setState(() => 2); +}); +``` + +# Derived + +You can also use the `Derived` class to create derived values that lazily update when their dependencies change: + +```typescript +const count = new Store(0); + +const double = new Derived({ + fn: () => count.state * 2, + // Must explicitly list dependencies + deps: [count] +}); + +// Must mount the derived value to start listening for updates +const unmount = double.mount(); + +// Later, to cleanup +unmount(); +``` + +## Previous Deferred Value + +You can access the previous value of a derived computation by using the `prevVal` argument passed to the `fn` function: + +```typescript +const count = new Store(1); + +const double = new Derived({ + fn: ({ prevVal }) => { + return count.state + (prevVal ?? 0); + }, + deps: [count] +}); + +double.mount(); +double.state; // 1 +count.setState(() => 2); +double.state; // 3 +``` + +## Dependency Values + +You can access the values of the dependencies of a derived computation by using the `prevDepVals` and `currDepVals` arguments passed to the `fn` function: + +```typescript +const count = new Store(1); + +const double = new Derived({ + fn: ({ prevDepVals, currDepVals }) => { + return (prevDepVals[0] ?? 0) + currDepVals[0]; + }, + deps: [count] +}); + +double.mount(); +double.state; // 1 +count.setState(() => 2); +double.state; // 3 +``` + +# Effects + +You can also use the `Effect` class to manage side effects across multiple stores and derived values: + +```typescript +const effect = new Effect({ + fn: () => { + console.log('The count is now:', count.state); + }, + // Array of `Store`s or `Derived`s + deps: [count], + // Should effect run immediately, default is false + eager: true +}) + +// Must mount the effect to start listening for updates +const unmount = effect.mount(); + +// Later, to cleanup +unmount(); +```