svelte-writable-derived

svelte-writable-derived

For users of Svelte v3, this is a read-write variant of Svelte's derived stores that accepts an extra callback to send values back to the source. It builds on the derived & writable stores provided by Svelte, and emulates their behavior as closely as possible.

This project has a Code of Conduct. By participating in the Git repo or issues tracker, you agree to be as courteous, welcoming, and generally a lovely person as its terms require. 😊

• Default export: writableDerived()
  • New parameter: reflect
• Regarding Subscription-less writableDerived Stores
• Examples
  • Making an object store from a JSON string store
  • Making a single-value store from an object store
  • Making an object store from several single-value stores
  • Chaining all of the above together
• Browser compatibility

• 💖 Support the developer
  • 💸 ... with money
  • 💌 ... with kind words
  • 🤝 ... with a job

Default export: writableDerived()

Parameters: origins (store or array of stores), derive (function), reflect (see documentation), optional initial (any)
Returns a store with writable methods

Create a store that behaves similarly to Svelte's derived, with origins, derive, and initial working like its 1st, 2nd, and 3rd parameters respectively. Values introduced to the store via its set and update methods are passed to the new 3rd parameter, reflect, which can in turn set values for the origin stores.

It is not possible for derived and reflect to trigger calls to each other, provided they only use the set callbacks provided to them and do not reach out to any outer set or update.

New parameter: reflect

One of the following:

• Function with parameters: reflecting (any), optional set (function)
• Object with property withOld containing function with parameters: reflecting (any), old (any), optional set (function)

The provided function is called when the derived store gets a new value via its set and update methods (not via the derive callback). Its reflecting parameter is this new value. The set parameter accepts a value to set in the origin store, if origins was a store, or an array of values to set if origins was an array. If the set parameter receives an array that's sparse or shorter than origins, it will only set the stores it has elements for, and other stores don't necessarily need to be writable. If the function doesn't take a set parameter, its return value will be used to set origin stores just as if it were passed to set.

reflect is called after the derived store's subscriptions are called. If the derived store has its set and/or update methods called again in the process of calling its subscriptions, reflect will be called only once, with the most-recently-set value.

If reflect takes a set parameter, it may return a cleanup function that will be called immediately before the next reflect call. (Unlike its derive counterpart, reflect's cleanup function is never called in response to unsubscriptions.)

If the reflect parameter is provided a function via an object with a withOld property, that function will be called with an additional old parameter after reflecting. This is the initial value of the origin stores, and will be an array if origins was an array.

Regarding Subscription-less writableDerived Stores

One of the ways writableDerived emulates the behavior of Svelte's derived is that it does not subscribe to any origin store until the derived store itself has a subscription. However, writableDerived makes an exception: Calling the set and update methods when the derived store has no subscriptions will subscribe to & then unsubscribe from all its origins.

Examples

Making an object store from a JSON string store

import { writable, get } from "svelte/store";
import writableDerived from "svelte-writable-derived";

var jsonStore = writable(`{"I'm a property": true}`);
var objectStore = writableDerived(
	jsonStore,
	(json) => JSON.parse(json),
	(object) => JSON.stringify(object)
);
console.log( Object.keys( get(objectStore) ) ); // ["I'm a property"]
objectStore.set({"I'm not a property": false});
console.log( get(jsonStore) ); // "{\"I'm not a property\": false}"

Making a single-value store from an object store

import { writable, get } from "svelte/store";
import writableDerived from "svelte-writable-derived";

var objectStore = writable({"a horse": "a horse", "of course": "of course"});
var valueStore = writableDerived(
	objectStore,
	(object) => object["a horse"],
	{ withOld(reflecting, object) {
		object["a horse"] = reflecting;
		return object; // needed to ensure objectStore.set is called with the proper value
	} }
);
console.log( get(valueStore) ); // "a horse"
valueStore.set("*whinny*");
console.log( get(objectStore) ); // {"a horse": "*whinny*", "of course": "of course"}

Making an object store from several single-value stores

import { writable, get } from "svelte/store";
import writableDerived from "svelte-writable-derived";

var valueStore1 = "sparta", valueStore2 = "monty python's flying circus";
var objectStore = writableDerived(
	[valueStore1, valueStore2],
	([value1, value2]) => ( {"this is": value1, "it's": value2} ),
	(object) => [ object["this is"], object["it's"] ]
);
console.log( get(objectStore) ); // {"this is": "sparta", "it's": "monty python's flying circus"}
objectStore.set( {"this is": "rocket league", "it's": "over 9000"} );
console.log( get(valueStore1), get(valueStore2) ); // "rocket league" "over 9000"

Chaining all of the above together

// What if Rube Goldberg were a JavaScript developer?
import { writable, get } from "svelte/store";
import writableDerived from "svelte-writable-derived";

var jsonStore = writable(`{"owner": "dragon", "possessions": ["crown", "gold"]}`);
var hoardStore = writableDerived(
	jsonStore,
	(json) => JSON.parse(json),
	(object) => JSON.stringify(object)
);

var hoarderStore = writableDerived(
	objectStore,
	(hoard) => hoard["owner"],
	{ withOld(reflecting, hoard) {
		hoard["owner"] = reflecting;
		return hoard;
	} }
);
var hoardContentsStore = writableDerived(
	objectStore,
	(hoard) => hoard["possessions"],
	{ withOld(reflecting, hoard) {
		hoard["possessions"] = reflecting;
		return hoard;
	} }
);

var itemListStore = writableDerived(
	[hoarderStore, hoardContentsStore],
	([hoarder, hoardContents]) => {
		return hoardContents.map( (item) => {
			return {item, owner: hoarder};
		});
	},
	(itemList) => {
		// This is only for demonstration purposes, so we won't handle differing owners
		var hoarder = itemList[0].owner;
		var hoardContents = itemList.map( (itemListEntry) => {
			return itemListEntry["item"];
		} );
		return [hoarder, hoardContents];
	}
);

jsonStore.subscribe(console.log);
hoardStore.subscribe(console.log);
hoarderStore.subscribe(console.log);
// skipping hoardContentsStore
itemListStore.subscribe(console.log);
itemListStore.update( (itemList) => {
	return itemList.map( (itemListEntry) => {
		return {item: itemListEntry.item, owner: "protagonist"};
	} );
} );
/*
	Upon the update, the console logs:
	[{item: "crown", owner: "protagonist"}, {item: "gold", owner: "protagonist"}]
	"protagonist"
	{owner: "protagonist", possessions: ["crown", "gold"]}
	"{\"owner\": \"protagonist\", \"possessions\": [\"crown\", \"gold\"]}"
*/

Browser compatibility

This package should run anywhere Svelte can run. Use transpilers/polyfills as needed.

💖 Support the developer

I muchly appreciate any way you'd like to show your thanks - knowing people are helped gives me warm fuzzies and makes it all worthwhile!

💸 ... with money

I'm on Ko-Fi! If you'd like to make a recurring donation, first please help me afford Ko-Fi Gold!

💌 ... with kind words

Current contact info is on this page - or you can create an "issue" on this repo just to say thanks! Thank-you "issues" will be closed right away, but are treasured regardless~

🤝 ... with a job

I have a Developer Story on Stack Overflow!

Changelog

2.0.0 (June 13, 2019)

• Changed: reflect is now either a function with signature (reflecting, set) or an object with interface { withOld(reflecting, old, set) }. Async-ness is determined by whether the function accepts a set parameter, just as for the derive callback.
• Changed: The reflect callback now runs after subscriptions. Additional set/update calls while running subscriptions result in reflect being called only once with the most recent value.
• Changed: Changes to which operations cause a subscription-less writableDerived to subscribe-then-unsubscribe to all origins:
  • set method calls now do so
  • Getting old origin values in reflect no longer does so
• Optimization: Origin values are no longer kept if reflect will not need them
• Optimization: Participates in Svelte v3.5.0's diamond dependencies solution (downstream only; there is no diamond dependency handling for reflecting values back to their sources)
• Optimization: No more internal writable store; the derived is the only internal store remaining

If this update was useful for you, show your appreciation with money, kind words, or a job!