@manyducks.co/dolla 2.0.0-alpha.8 → 2.0.0

package/notes/readme-scratch.md

@@ -1,222 +0,0 @@
-# README
-
-> This note will eventually become the new README. Here I'm laying out my ideal framework API.
-
-A basic component.
-
-```jsx
-import Dolla, { createState, derive } from "@manyducks.co/dolla";
-
-function ExampleView(props, ctx) {
-  const [$count, setCount] = createState(5);
-  const $doubled = derive([$count], (n) => n * 2);
-
-  ctx.watch([$count], (count) => {
-    ctx.log("value of count is now %n", count);
-  });
-
-  return <p>{$count}</p>;
-}
-
-Dolla.mount(document.body, ExampleView);
-```
-
-<details open>
-<summary>
-  <h2>Signals API</h2>
-</summary>
-
-The signals API. Dolla's signals use explicit tracking, meaning any function where signal values are tracked take an array of the signals you want to track. This way you know exactly what depends on what at a glance without any kind of hidden tracking logic behind the scenes. You are free to `.get()` the value of a signal without worrying about untracking it first.
-
-```jsx
-import { createState } from "@manyducks.co/dolla";
-
-const [$count, setCount] = createState(256);
-
-$count.get(); // 256; returns the current value
-
-const stop = $count.watch((value) => {
-  // Runs once immediately, then again whenever the value changes.
-});
-
-setCount(512); // Update the value of $count. The new value is set and all watchers run synchronously.
-
-stop(); // Stop watching for changes.
-```
-
-That is the basic signal API. Signals are all about composability. Here are some more advanced ways of working with them:
-
-```jsx
-import { createState, toState, valueOf, derive } from "@manyducks.co/dolla";
-
-const [$count, setCount] = createState(72);
-
-// Returns the value of the signal passed in. If the value is not a signal it is returned as is.
-const count = valueOf($count);
-const bool = valueOf(true);
-
-// Creates a signal containing the value passed in. If the value is already a signal it is returned as is.
-const $bool = toState(true);
-const $anotherCount = toState($count);
-
-// Derive a new signal from the value of another. Whenever $count changes, $doubled will follow.
-const $doubled = derive([$count], (count) => count * 2);
-
-// Derive a new signal from the values of several others. When any value in the list changes, $sum will be recomputed.
-const $sum = derive([$count, $doubled], (count, doubled) => count + doubled);
-```
-
-The API if we call it State instead of Signal to distance from the Signal object in standardization process.
-
-```jsx
-import { createState, toState, valueOf, derive } from "@manyducks.co/dolla";
-
-const [$count, setCount] = createState(72);
-
-// Returns the value of the signal passed in. If the value is not a signal it is returned as is.
-const count = valueOf($count);
-const bool = valueOf(true);
-
-// Creates a signal containing the value passed in. If the value is already a signal it is returned as is.
-const $bool = toState(true);
-const $anotherCount = toState($count);
-
-// Derive a new signal from the value of another. Whenever $count changes, $doubled will follow.
-const $doubled = derive([$count], (count) => count * 2);
-
-// Derive a new signal from the values of several others. When any value in the list changes, $sum will be recomputed.
-const $sum = derive([$count, $doubled], (count, doubled) => count + doubled);
-```
-
-States also come in a settable variety, with the setter included on the same object. Sometimes you want to pass around a two-way binding and this is what SettableState is for.
-
-```jsx
-import { createSettableState, fromSettable, toSettable } from "@manyducks.co/dolla";
-
-// Settable states have their setter included.
-const $$value = createSettableState("Test");
-$$value.set("New Value");
-
-// They can also be split into a State and Setter
-const [$value, setValue] = fromSettableState($$value);
-
-// And a State and Setter can be combined into a SettableState.
-const $$otherValue = toSettableState($value, setValue);
-
-// Or discard the setter and make it read-only using the good old toState function:
-const $value = toState($$value);
-```
-
-Alternative API
-
-```jsx
-import { State } from "@manyducks.co/dolla";
-
-const [$count, setCount] = State(72);
-
-const count = State.unwrap($count);
-const bool = State.unwrap(true);
-
-const $bool = State.wrap(true);
-const $sameCount = State.wrap($count);
-
-const $doubled = State.from([$count], (count) => count * 2);
-
-const $sum = State.from([$count, $doubled], (count, doubled) => count + doubled);
-```
-
-Yet another
-
-```jsx
-import Dolla from "@manyducks.co/dolla";
-
-const [$count, setCount] = Dolla.state(72);
-
-const count = Dolla.get($count);
-const bool = Dolla.get(true);
-
-const $bool = Dolla.toState(true);
-const $sameCount = Dolla.toState($count);
-
-const $doubled = Dolla.computed([$count], (count) => count * 2);
-const $sum = Dolla.computed([$count, $doubled], (count, doubled) => count + doubled);
-
-// or
-
-import { state, computed, get, toState } from "@manyducks.co/dolla";
-
-const [$count, setCount] = state(72);
-
-const count = get($count);
-const bool = get(true);
-
-const $bool = toState(true);
-const $sameCount = toState($count);
-
-const $doubled = computed([$count], (count) => count * 2);
-const $sum = computed([$count, $doubled], (count, doubled) => count + doubled);
-```
-
-Settable signals:
-
-```jsx
-import { createSettableState, createSetter, toSettableSignal, fromSettableSignal } from "@manyducks.co/dolla";
-
-// Create a SettableSignal, which is basically a signal and its setter combined into a single object.
-const $$settable = createSettableState("Example");
-
-// The basic API is identical...
-$$settable.get();
-const stop = $$settable.watch((value) => {
-  // ...
-});
-stop();
-
-// ... except for the addition of a setter.
-$$settable.set("Set me directly");
-
-// When you already have a signal and a setter, they can be combined into one.
-const $$count = toSettableSignal($count, setCount);
-
-// This updates the original $signal value.
-$$count.set(386);
-
-// TODO: You can also split a SettableSignal into a signal and its setter.
-const [$readable, setReadable] = fromSettableSignal($$settable);
-
-// Create a custom setter. Calling this will cap the value to 100.
-const setCountBounded = createSetter($count, (next, current) => {
-  return Math.min(100, next);
-});
-
-setCountBounded((current) => {
-  return current + 1;
-});
-
-// Or make a proxy $$doubled -- but would you actually want to proxy things like this?
-const [$count, setCount] = createState(5);
-const $doubled = derive([$count], (count) => count * 2);
-const $$doubled = toSettableSignal(
-  $doubled,
-  createSetter($doubled, (next, current) => {
-    setCount(next * 2);
-  }),
-);
-```
-
-I'm not really sure we need all of this. On the chopping block:
-
-- The entire concept of settable signals
-  - `createSettableState`
-  - `toSettableSignal`
-  - `fromSettableSignal`
-  - `createSetter`
-
-This makes the entire API just four functions:
-
-- `createState`
-- `derive`
-- `toState`
-- `valueOf`
-
-</details>

package/notes/route-middleware.md

@@ -1,42 +0,0 @@
-# Router Middleware
-
-Allow handling route guards, preloading, etc with per-route middleware. When a route is matched, all middleware from higher layers are run again.
-
-```js
-Dolla.router.setup({
-  middleware: [/* does it make sense to have global middleware? */]
-  routes: [
-    { path: "/login", middleware: [auth] },
-    { path: "/", middleware: [auth], routes: [{ path: "/example", view: ExampleView }] }
-  ]
-});
-
-async function auth(ctx) {
-  // This check can be implemented however it needs to be for the app.
-  const authed = await isAuthorized();
-
-  if (ctx.path === "/login") {
-    if (authed) {
-      ctx.redirect("/");
-    }
-  } else {
-    if (!authed) {
-      ctx.redirect("/login");
-    }
-  }
-  // If no redirect has happened and nothing has been returned then we're clear to proceed.
-}
-
-// A middleware can also return Markup to stay on the URL but show something different.
-async function randomVisitor(ctx) {
-  if (Math.random() > 0.99) {
-    return <LuckyVisitorView />
-  }
-}
-
-// Or preload async data and set a context variable before navigating.
-async function preload(ctx) {
-  const data = await fetchData();
-  ctx.set("data", data);
-}
-```

package/tests/state.test.js

@@ -1,135 +0,0 @@
-import test from "node:test";
-import assert from "node:assert";
-
-import { createState, derive } from "../dist/index.js";
-
-test("signal", (t) => {
-  const [$count, setCount] = createState(5);
-
-  const defaultWatcher = t.mock.fn();
-  const stopDefault = $count.watch(defaultWatcher);
-
-  const lazyWatcher = t.mock.fn();
-  const stopLazy = $count.watch(lazyWatcher, { lazy: true });
-
-  assert.equal(defaultWatcher.mock.callCount(), 1, "watcher is called immediately by default");
-  assert.equal(lazyWatcher.mock.callCount(), 0, "lazy watcher is not called immediately");
-
-  assert.equal($count.get(), 5, "get returns the initial value");
-
-  setCount(12);
-
-  assert.equal($count.get(), 12, "setter updates the signal value");
-
-  assert.equal(defaultWatcher.mock.callCount(), 2, "default watcher is called");
-  assert.equal(lazyWatcher.mock.callCount(), 1, "lazy watcher is called");
-
-  assert.deepStrictEqual(defaultWatcher.mock.calls[1].arguments, [12], "default watcher is called with new value");
-  assert.deepStrictEqual(lazyWatcher.mock.calls[0].arguments, [12], "lazy watcher is called with new value");
-
-  setCount(12);
-
-  assert.equal(defaultWatcher.mock.callCount(), 2, "default watcher was not called with same value");
-  assert.equal(lazyWatcher.mock.callCount(), 1, "lazy watcher was not called with same value");
-
-  stopDefault();
-  stopLazy();
-
-  setCount(51);
-
-  assert.equal(defaultWatcher.mock.callCount(), 2, "default watcher has not been called again");
-  assert.equal(lazyWatcher.mock.callCount(), 1, "lazy watcher has not been called again");
-});
-
-test("derive", (t) => {
-  const [$one, setOne] = createState(5);
-  const [$two, setTwo] = createState(20);
-
-  const deriveSum = t.mock.fn((one, two) => one + two);
-  const deriveProduct = t.mock.fn((one, two) => one * two);
-
-  const $sum = derive([$one, $two], deriveSum);
-  const $product = derive([$one, $two], deriveProduct);
-
-  assert.equal($sum.get(), 25, "sum is calculated correctly");
-  assert.equal($product.get(), 100, "product is calculated correctly");
-
-  assert.equal(deriveSum.mock.callCount(), 1, "derive function has only been called once");
-
-  $sum.get();
-  $sum.get();
-  $sum.get();
-
-  assert.equal(deriveSum.mock.callCount(), 1, "derive function still only called once as dependencies haven't changed");
-
-  const defaultWatcher = t.mock.fn();
-  const stopDefault = $sum.watch(defaultWatcher);
-
-  const lazyWatcher = t.mock.fn();
-  const stopLazy = $product.watch(lazyWatcher, { lazy: true });
-
-  assert.equal(defaultWatcher.mock.callCount(), 1, "default watcher has been called");
-  assert.equal(lazyWatcher.mock.callCount(), 0, "lazy watcher has not been called yet");
-
-  assert.deepStrictEqual(defaultWatcher.mock.calls[0].arguments, [25], "default watcher was called with initial value");
-
-  setOne(6);
-
-  assert.equal(defaultWatcher.mock.callCount(), 2, "default watcher has been called");
-  assert.equal(lazyWatcher.mock.callCount(), 1, "lazy watcher has been called");
-
-  assert.deepStrictEqual(defaultWatcher.mock.calls[1].arguments, [26], "default watcher was called with new value");
-  assert.deepStrictEqual(lazyWatcher.mock.calls[0].arguments, [120], "lazy watcher was called with new value");
-
-  setTwo(20);
-
-  assert.equal(defaultWatcher.mock.callCount(), 2, "default watcher was not called with same value");
-  assert.equal(lazyWatcher.mock.callCount(), 1, "lazy watcher was not called with same value");
-
-  stopDefault();
-  stopLazy();
-
-  setOne(4);
-
-  assert.equal(defaultWatcher.mock.callCount(), 2, "default watcher was not called after stop");
-  assert.equal(lazyWatcher.mock.callCount(), 1, "lazy watcher was not called after stop");
-
-  assert.equal($sum.get(), 24, "sum is derived correctly");
-  assert.equal($product.get(), 80, "product is derived correctly");
-
-  assert.equal(deriveSum.mock.callCount(), 3, "sum has only been derived three times");
-});
-
-test("derive nested signals", (t) => {
-  const [$value, setValue] = createState(5);
-
-  const [$object, setObject] = createState({
-    href: derive([$value], (value) => `/projects/${value}/test`),
-  });
-
-  // o.href here is itself a derived value
-  const $href = derive([$object], (o) => o.href);
-
-  const watcher = t.mock.fn();
-  const stop = $href.watch(watcher);
-
-  assert.equal(watcher.mock.callCount(), 1);
-  assert.deepStrictEqual(watcher.mock.calls[0].arguments, ["/projects/5/test"]);
-
-  // Update value which href depends on.
-  setValue(12);
-
-  assert.equal(watcher.mock.callCount(), 2);
-  assert.deepStrictEqual(watcher.mock.calls[1].arguments, ["/projects/12/test"]);
-
-  // Now set the original object and replace the derived href.
-  // See that watcher still receives the latest value.
-  setObject({
-    href: derive([$value], (value) => `/projects/${value}/changed`),
-  });
-
-  assert.equal(watcher.mock.callCount(), 3);
-  assert.deepStrictEqual(watcher.mock.calls[2].arguments, ["/projects/12/changed"]);
-
-  stop();
-});