@manyducks.co/dolla 2.0.0-alpha.46 → 2.0.0-alpha.47

package/docs/signals.md

@@ -1,50 +1,38 @@
 ## ⚡ Reactive Updates with `State`
 
-Dolla sets out to solve the challenge of keeping your UI in sync with your data. All apps have state that changes at runtime, and as those values change your UI must update itself to stay in sync with that state. JavaScript frameworks all have their own ways of meeting this challenge, but there are two main ones; virtual DOM and signals.
+Dolla sets out to solve the challenge of keeping your UI in sync with your data. All apps have state that changes at runtime, and your UI must update itself to stay in sync with that state as it changes. JavaScript frameworks all have their own ways of doing this, but there are two main ones; virtual DOM and signals. Dolla follows the Signals philosophy.
 
 [React](https://react.dev) and similar frameworks make use of a [virtual DOM](https://svelte.dev/blog/virtual-dom-is-pure-overhead), in which every state change causes a "diff" of the real DOM nodes on the page against a lightweight representation of what those nodes _should_ look like, followed by a "patch" where the minimal updates are performed to bring the DOM in line with the ideal virtual DOM.
 
 [Solid](https://www.solidjs.com) and similar frameworks make use of [signals](https://dev.to/this-is-learning/the-evolution-of-signals-in-javascript-8ob), which are containers for data that will change over time. Signal values are accessed through special getter functions that can be called inside of a "scope" to track their values. When the value of a tracked signal changes, any computations that happened in scopes that depend on those signals are re-run. In an app like this, all of your DOM updates are performed with pinpoint accuracy without diffing as signal values change.
 
-Dolla uses a concept of a `State`, which is a signal-like container for values that change over time. Where `State` differs from signals, however, is that there is no magical scope tracking going on behind the scenes. All States that depend on others do so explicity, so your code is easier to read and understand.
-
-The `State` API has just four functions:
-
-- `createState` to create a new state and a linked setter function.
-- `derive` to create a new state whose value depends on one or more other states.
-- `toState` to ensure that a value is a state object.
-- `toValue` to ensure that a value is a plain value.
-
-- `atom`
-- `compose`
-- `effect`
-- `get`
-- `peek`
-- `set`
+The Signals API in Dolla has just four functions:
 
+- `$` to create a new Source or derived Signal.
+- `get` to unwrap a possible Signal value.
+- `peek` to unwrap a possible Signal value without tracking it.
+- `effect` to run side effects when tracked signals change.
 
 ### Basic State API
 
 ```js
-import { createState } from "@manyducks.co/dolla";
+import { $ } from "@manyducks.co/dolla";
 
-// Equivalent to React's `useState` or Solid's `createSignal`.
-// A new read-only State and linked Setter are created.
-const [$count, setCount] = createState(72);
+const count = $(72);
 
 // Get the current value.
-$count.get(): // 72
+count(): // 72
 
 // Set a new value.
-setCount(300);
+count(300);
 
 // The State now reflects the latest value.
-$count.get(); // 300
+count(); // 300
 
-// Data can also be updated by passing a function.
-// This function takes the current state and returns a new one.
-setCount((current) => current + 1);
-$count.get(); // 301
+// Data can also be updated by passing an update function.
+// This function takes the current state and returns the next.
+count((value) => value + 1);
+count(); // 301
 ```
 
 ### Deriving States from other States
@@ -52,39 +40,53 @@ $count.get(); // 301
 #### Example 1: Doubled
 
 ```js
-import { createState, derive } from "@manyducks.co/dolla";
+import { $ } from "@manyducks.co/dolla";
 
-const [$count, setCount] = createState(1);
+// Passing a value to $() results in a Source...
+const count = $(1);
 
-const $doubled = derive([$count], (count) => count * 2);
+// ...while passing a function results in a Signal with a derived value.
+const doubled = $(() => count() * 2);
 
-setCount(10);
-$doubled.get(); // 20
+count(10);
+doubled(); // 20
 ```
 
-That was a typical toy example where we create a `$doubled` state that always contains the value of `$count`... doubled! This is the essential basic example of computed properties, as written in Dolla.
+##### A note on derived signals.
+
+Because signals are simply functions that return a value, you can also derive state by simply defining a function that returns a value. Any `Source` called in this function will therefore be tracked when this function is called in a tracked scope.
+
+The difference is that the value of the plain function is computed again each and every time that function is called. Wrapping it with `$()` will result in the computed value being cached until one of its dependencies changes. If you are coming from React then you may want to think of this like `useMemo`.
+
+```js
+// Plain getter: OK
+const plainCount = () => count() * 2;
+
+// Signal: OK
+const cachedCount = $(() => count() * 2);
+```
+
+Using plain getters to derive values is perfectly fine. It may be a waste to cache a very simple getter, but if the value is accessed frequently or involves expensive computations then you can get better performance by wrapping it in a Signal.
 
 #### Example 2: Selecting a User
 
 ```js
-import { createState, derive } from "@manyducks.co/dolla";
+import { $ } from "@manyducks.co/dolla";
 
-const [$users, setUsers] = createState([
+const users = $([
   { id: 1, name: "Audie" },
   { id: 2, name: "Bob" },
   { id: 3, name: "Cabel" },
 ]);
-const [$selectedUserId, setSelectedUserId] = createState(1);
+const userId = $(1);
 
-const $selectedUser = derive([$users, $selectedUserId], (users, id) => {
-  return users.find((user) => user.id === id);
-});
+const selectedUser = $(() => users().find((user) => user.id === userId()));
 
-$selectedUser.get(); // { id: 1, name: "Audie" }
+selectedUser(); // { id: 1, name: "Audie" }
 
-setSelectedId(3);
+userId(3);
 
-$selectedUser.get(); // { id: 3, name: "Cabel" }
+selectedUser(); // { id: 3, name: "Cabel" }
 ```
 
 That was a more realistic example you might actually use in real life. Here we are selecting a user from a list based on its `id` field. This is kind of similar to a `JOIN` operation in a SQL database. I use this kind of pattern constantly in my apps.
@@ -94,52 +96,67 @@ The strength of setting up a join like this is that the `$users` array can be up
 #### Example 3: Narrowing Complex Data
 
 ```jsx
-import { createState, derive } from "@manyducks.co/dolla";
+import { $ } from "@manyducks.co/dolla";
 
-const [$user, setUser] = createState({ id: 1, name: "Audie" });
+const user = $({ id: 1, name: "Audie" });
+const name = $(() => user().name);
 
-const $name = derive([$user], (user) => user.name);
-
-$name.get(); // "Audie"
+name(); // "Audie"
 
 // In a view:
-<span class="user-name">{$name}</span>;
+<span class="user-name">{name}</span>;
 ```
 
 Another common pattern. In a real app, most data is stored as arrays of objects. But what you need in order to slot it into a view is just a string. In the example above we've selected the user's name and slotted it into a `span`. If the `$user` value ever changes, the name will stay in sync.
 
-### Converting to and from States
+### Converting to and from Signals
 
 ```js
-import { createState, toState, toValue } from "@manyducks.co/dolla";
+import { $, get } from "@manyducks.co/dolla";
 
-const [$count, setCount] = createState(512);
+const count = state(512);
 
-// Unwrap the value of $count. Returns 512.
-const count = toValue($count);
+// Unwrap the value of count. Returns 512.
+const value = get(count);
 // Passing a non-state value will simply return it.
-const name = toValue("World");
+const name = get("World");
 
-// Wrap "Hello" into a State containing "Hello"
-const $value = toState("Hello");
-// Passing a state will simply return that same state.
-const $number = toState($count);
+// If you need to convert a static piece of data into a Signal you can simply wrap it in a getter function.
+const value = () => "Hello";
 ```
 
 ### In Views
 
 ```jsx
-import { derive } from "@manyducks.co/dolla";
+import { $ } from "@manyducks.co/dolla";
 
 function UserNameView(props, ctx) {
-  const $name = derive([props.$user], (user) => user.name);
-
-  return <span class={{ "user-name": true, "is-selected": props.$selected }}>{$name}</span>;
-});
+  const name = $(() => props.user().name);
+
+  // Passing an object to `class` results in keys with a truthy value being applied as classes.
+  // Those with falsy values will be ignored.
+  // Signals can be given as values and they will be tracked.
+  return (
+    <span
+      class={{
+        "user-name": true,
+        "is-selected": props.selected
+      }}>
+      {name}
+    </span>
+  );
+})
+
+// In parent view:
+
+const selected = $(false);
+const user = $({ id: 1, name: "Audie" });
+
+<UserNameView selected={selected} user={user} />
+
+// Changing signal values out here will now update the UserNameView internals.
 ```
 
-In the example above we've displayed the `name` field from a `$user` object inside of a span. We are also assigning an `is-selected` class dynamically based on whether the `$selected` prop contains a truthy or falsy value.
-
 ---
 
 End.

package/notes/molecule.md

@@ -0,0 +1,35 @@
+Like `compose` but it takes an initial value and a function that can set its value asynchronously. Its callback is a tracking context, so it will be re-run when signals called within are updated.
+
+```ts
+interface MoleculeGetter<T> {
+  (): T;
+  <X>(source: MaybeReactive<X>): X;
+}
+
+interface MoleculeSetter<T> {
+  (next: T): void;
+}
+
+interface MoleculeFunction<T> {
+  (get: MoleculeGetter<T>, set: MoleculeSetter<T>): void | (() => void);
+}
+
+function molecule<T>(initialValue: T, fn: MoleculeFunction<T>) {}
+
+const value = molecule(5, (get, set) => {
+  // get() returns the current value stored in this hadron
+  // get(reactive) returns the value of that reactive and tracks it (== reactive.get())
+  // set(value) updates the value stored in this hadron
+  // This function will not be called unless there is at least one observer.
+
+  let interval = setInterval(() => {
+    set(get() + 1);
+  }, 1000);
+
+  // Can return a cleanup function to run between invocations.
+  // Also called when the last observer stops observing.
+  return () => {
+    clearInterval(interval);
+  };
+});
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@manyducks.co/dolla",
-  "version": "2.0.0-alpha.46",
+  "version": "2.0.0-alpha.47",
   "description": "Front-end components, routing and state management.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/dist/core/ref.d.ts

@@ -1,28 +0,0 @@
-/**
- * A `Ref` is a function that stores a value when called with a single argument,
- * and returns the most recently stored value when called with no arguments.
- */
-export interface Ref<T> {
-    /**
-     * Get: returns the current value stored in the ref (or undefined).
-     */
-    (): T | undefined;
-    /**
-     * Set: stores a new `value` in the ref.
-     */
-    <T>(value: T | undefined): void;
-}
-/**
- * A Ref is a function that returns the last argument it was called with.
- * Calling it with no arguments will simply return the latest value.
- * Calling it with an argument will store that value and immediately return it.
- *
- * @param value - An (optional) initial value to store.
- *
- * @example
- * const number = ref(5);
- * number(); // 5
- * number(500);
- * number(); // 500
- */
-export declare function ref<T>(value?: T): Ref<T>;

package/dist/core/views/for.d.ts

@@ -1,9 +0,0 @@
-import { ViewContext, ViewResult } from "../nodes/view";
-import { MaybeReactive, Reactive } from "../signals";
-interface ForProps<T> {
-    each: MaybeReactive<Iterable<T>>;
-    key: (item: T, index: number) => any;
-    children: (item: Reactive<T>, index: Reactive<number>, ctx: ViewContext) => ViewResult;
-}
-export declare function For<T = any>({ each, key, children }: ForProps<T>): import("../markup").Markup;
-export {};

package/dist/fragment-CYt92o5I.js

@@ -1,8 +0,0 @@
-import { m, d as o } from "./markup-BJffA2Ls.js";
-function e(r, a) {
-  return m("$dynamic", { source: o(() => r.children) });
-}
-export {
-  e as F
-};
-//# sourceMappingURL=fragment-CYt92o5I.js.map

package/dist/fragment-CYt92o5I.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"fragment-CYt92o5I.js","sources":["../src/core/views/fragment.ts"],"sourcesContent":["import type { Renderable } from \"../../types.js\";\nimport { markup } from \"../markup.js\";\nimport { type ViewContext } from \"../nodes/view.js\";\nimport { compose } from \"../signals.js\";\n\n/**\n * A utility view that displays its children.\n */\nexport function Fragment(props: { children?: Renderable }, ctx: ViewContext) {\n  return markup(\"$dynamic\", { source: compose(() => props.children) });\n}\n"],"names":["Fragment","props","ctx","markup","compose"],"mappings":";AAQgB,SAAAA,EAASC,GAAkCC,GAAkB;AACpE,SAAAC,EAAO,YAAY,EAAE,QAAQC,EAAQ,MAAMH,EAAM,QAAQ,GAAG;AACrE;"}