@manyducks.co/dolla 2.0.0-alpha.6 → 2.0.0-alpha.61

package/notes/observable.md

@@ -0,0 +1,180 @@
+# Observable
+
+Signals have some downsides, like if you call them inside a function, and you then call that function inside a tracking context, it can cause the tracking context to re-run unexpectedly. You then have to defensively call things inside `untracked` to avoid tracking deeply nested signal getters. It's not unmanageable but it's extremely surprising and unintuitive when you first run into it. It's a new and unnecessary consideration that makes code feel less safe and predictable.
+
+I'm considering using Observable (or my own extended version of it) as a basis for a state management system. Still built on top of `alien-signals` but with explicit tracking of signal values. It could look something like the following.
+
+This would probably be best as a separate library, maybe called `@manyducks.co/atomic`.
+
+Going back to the atom/compose terminology.
+
+```js
+// Define an atom, the basic value holder object.
+const count = atom(5);
+
+// Atoms have a `value` field that is writable. This is not tracked by default.
+count.value; // 5
+count.value = 12;
+count.value; // 12
+
+// Implements the Observable interface.
+const subscription = count.subscribe({
+  next: (value) => {
+    console.log("count is now", value);
+  },
+  error: (error) => {},
+  completed: () => {},
+});
+subscription.closed; // boolean
+subscription.unsubscribe();
+
+// Like `value` getter but tracks count in a signal tracking scope.
+count.track(); // 12
+
+// Can be closed which completes all subscribers and will throw an error if a new value is set.
+count.close();
+```
+
+Atoms can be composed.
+
+```js
+// You explicitly pass a dependencies array at the end, similar to React.
+// Dependencies will be tracked and the compose function re-run any time they receive a new value.
+const doubled = composed((prev) => count.value * 2, [count]);
+
+// Read-only value.
+doubled.value;
+
+// Observable
+const subscription = doubled.subscribe((value) => {
+  // ...
+});
+
+// Trackable
+doubled.track();
+
+// Completes subscriptions, untracks deps and prevents receiving any new values.
+doubled.close();
+```
+
+Effects work basically the same as `composed` but they return a cancel function instead of a value.
+
+```js
+const cancel = effect(() => {
+  console.log(`count is now ${count.value}`);
+}, [count]);
+
+cancel();
+```
+
+Other thoughts:
+
+```js
+// You can name observables for debugging purposes. If one of them throws an error it can include the name.
+const count = atom(5).named("count");
+
+// Maybe even named effects.
+const cancel = effect(() => {
+  console.log(`count is now ${count.value}`);
+}, [count]).named("countReader");
+
+// Promise-based await next? This will resolve when count.value is set.
+// If the subscription errors it rejects with that error. If the subscription completes it rejects with an error to indicate that.
+const nextCount = await count.nextValue();
+
+// Filter and signal. Wait up to 5 seconds for next even value.
+const controller = new AbortController();
+setTimeout(controller.abort, 5000);
+const nextEven = await count.nextValue({
+  filter: (value) => value % 2 === 0,
+  signal: controller.signal,
+  // or timeout: 5000
+});
+// Resolves to null if aborted or timed out.
+
+// Batching
+
+const count1 = atom(5);
+const count2 = atom(12);
+
+effect(() => {
+  console.log(`total: ${count1.value + count2.value}`);
+}, [count1, count2]);
+
+// This causes the effect to run twice
+count1.value = 50;
+count2.value = 8;
+
+// A batch suspends effects until it concludes; this runs the effect once
+batch(() => {
+  count1.value = 50;
+  count2.value = 8;
+});
+
+// Deep reactivity
+const data = atom(
+  {
+    users: [
+      { id: 1, name: "Tony" },
+      { id: 2, name: "Morgan" },
+    ],
+  },
+  { deep: true },
+);
+
+// These updates trigger effects and subscriptions.
+// By default only setting `.value` directly will trigger notifications.
+data.value.users[0].name = "Bon";
+data.value.users.find((user) => user.id === 1).name = "Tony";
+
+// Then in theory, if you referenced one of the values
+const morgan = data.value.users.find((user) => user.id === 2);
+
+// And passed that around and modified it that would also still be reactive to the original atom.
+// I don't know if this is a good idea.
+morgan.name = "AKLSJDAKSD";
+```
+
+## What would Dolla look like with this?
+
+```jsx
+function CounterView() {
+  const count = atom(0);
+
+  const increment = () => count.value++;
+  const decrement = () => count.value--;
+
+  return (
+    <div>
+      Counter: {count}
+      <button onClick={increment}>+1</button>
+      <button onClick={decrement}>-1</button>
+    </div>
+  );
+}
+
+function ExampleView(props, ctx) {
+  const name = atom("");
+
+  // Update local name whenever props.name changes
+  ctx.effect(() => {
+    name.value = props.name.value;
+  }, [props.name]);
+
+  // Update greeting whenever local name changes
+  const greeting = composed(() => `Hello, ${name.value}`, [name]);
+
+  return (
+    <div>
+      <span>{greeting}</span>
+      <input value={name} onInput={(e) => (name.value = e.target.value)} />
+    </div>
+  );
+}
+```
+
+## TypeScript
+
+- `Atom<T>` for the basic building block with a writable value.
+- `Composed<T>` for a derived state based on other `Atom<T>` and `Composed<T>` values.
+- `Atomic<T>` to encompass the basic API of both `Atom<T>` and `Composed<T>`.

package/notes/readme-scratch.md

@@ -1,24 +1,62 @@
 # README
 
+```jsx
+import { mount, atom, html } from "@manyducks.co/atomic";
+
+function Home() {
+  return html` <h1>This is the home page!</h1> `;
+}
+
+// mount to DOM element
+mount(Home, document.body);
+
+// render to string
+const string = await render(Home, "/the/path/here");
+```
+
+---
+
 > 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";
+import { mount, state, derive, batch } from "@manyducks.co/dolla";
 
 function ExampleView(props, ctx) {
-  const [$count, setCount] = createState(5);
-  const $doubled = derive([$count], (n) => n * 2);
+  // Signals: state, derive, effect and batch
 
-  ctx.watch([$count], (count) => {
-    ctx.log("value of count is now %n", count);
+  const count = state(5);
+
+  const doubled = derive(() => count.value * 2);
+
+  batch(() => {
+    // Perform multiple updates in one go and commit at the end.
+  });
+
+  // If effect is called in the body of a view function it will be cleaned up automatically with the view.
+  ctx.effect(() => {
+    console.log(nested.value);
   });
 
-  return <p>{$count}</p>;
+  // Emit and listen for context events.
+  ctx.on("event", (e, ...args) => {
+    e.cancel();
+  });
+  ctx.emit("event", ...args);
+
+  // Get and set context values.
+  ctx.set("context value", 5);
+  ctx.get("context value");
+
+  // Provide and use a store.
+  const store = ctx.provide(someStore); // provide creates a new instance attached to this view and returns it.
+  const store = ctx.use(someStore);
+
+  return <p>{count}</p>;
 }
 
-Dolla.mount(document.body, ExampleView);
+mount(ExampleView, document.body);
 ```
 
 <details open>

package/notes/route-middleware.md

@@ -0,0 +1,42 @@
+# 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/notes/scratch.md

@@ -1,5 +1,352 @@
 # Scratch Note
 
+Library needs to be easier to render standalone elements. Idea to replace constructView and a lot of the store management weirdness with a `createContext` function and a `render` function that takes markup and a context.
+
+The context is basically a refactor of the old ElementContext and serves the same purpose.
+
+```jsx
+import { m, render, createContext } from "@manyducks.co/dolla";
+
+const context = createContext();
+context.addStore(SomeStore);
+
+function ExampleView(props, ctx) {
+  // Views now access the Context directly.
+  const store = ctx.getStore(SomeStore);
+
+  return <h1>Hello World</h1>;
+}
+
+const element = render(ExampleView, context);
+
+element.mount(document.body);
+```
+
+---
+
+Idea: Monomorphic app context. Replaces StoreContext, ViewContext, etc.
+
+Routes are baked into the app once again, but
+
+```jsx
+import { createRoot } from "@manyducks.co/dolla";
+import { example } from "./stores/example.js";
+
+const root = createRoot();
+
+root.use(example());
+
+async function auth(_, state, redirect) {
+  // route context
+  // Routes run through each callback until one resolves to a renderable value.
+  // If redirect is called, the route is re-matched and no further callbacks are run for this route.
+
+  if (state.auth == null) {
+    redirect("/login");
+  }
+}
+
+root.route("/users/*", auth, (C) => {
+  C.route("/{#id}/*", (C) => {
+    C.route("/", (C) => <UserDetailRoute userId={C.params.id} />);
+    C.route("*", "./");
+  });
+});
+
+root.route("/users/*", auth, (route) => {
+  route("/{#id}/*", (route) => {
+    // TODO: It's possible to reference the wrong 'route'
+    // Track active context and throw error if the one you call belongs to the wrong context?
+    route("/", (_, state) => <UserDetailView userId={state.params.id} />);
+    route("*", "./");
+  });
+});
+
+function ExampleView(props, ctx) {
+  // ctx.routes returns a special type of outlet that renders children based on
+  // the route segments that come after the ones at this ctx.
+
+  // The weakness of this idea is that routes can't be validated without initializing views.
+  return (
+    <div>
+      <Suspense fallback={<span>Loading...</span>}>
+        {ctx.routes((route) => {
+          route("/subroute", () => <OtherView />);
+
+          // Routes can be async.
+          route("/other", () => import("some-module"));
+        })}
+      </Suspense>
+    </div>
+  );
+
+  // Also Suspense. This can be simply implemented with events.
+  ctx.emit("suspense:begin", uniqueId);
+  // Then when done:
+  ctx.emit("suspense:end", uniqueId);
+
+  // The nearest Suspense view will track ids which are in suspense and show fallback content in the meantime.
+}
+
+function Suspense(props, ctx) {
+  const [$tracked, setTracked] = createState({});
+
+  ctx.on("suspense:begin", (e) => {
+    setTracked((tracked) => {
+      return {
+        ...tracked,
+        [e.detail]: new Date(),
+      };
+    });
+  });
+
+  ctx.on("suspense:end", (e) => {
+    setTracked((tracked) => {
+      const updated = Object.assign({}, tracked);
+      delete updated[e.detail];
+      return updated;
+    });
+  });
+
+  // TODO: Hide suspended view without unmounting it. This might take special logic.
+}
+
+// Can also pass markup directly if you don't need the context.
+root.route("/", auth, <HomeRoute />);
+
+// Static redirect.
+root.route("*", "/");
+
+// Programmatic redirect.
+root.route("*", (C) => {
+  C.log("hit wildcard");
+  C.redirect("/");
+});
+
+root.mount(document.body);
+
+// generate an HTML string for server side rendering.
+root.toString("/some/path");
+```
+
+---
+
+```js
+class ClockStore extends Store {
+
+
+  constructor() {
+
+  }
+}
+
+class CounterStore extends Store {
+  // Could have better name. This will catch any
+  // this.emit('counter:increment') or this.emit('counter:decrement') calls
+  // and update the state according to these functions.
+  value = new Emittable('counter', 0, {
+    increment: state => state + 1,
+    decrement: state => state - 1
+  });
+}
+
+type CounterEvents = {
+  increment: [amount: number];
+  decrement: [amount: number];
+}
+
+
+
+```
+
+---
+
+Bring the $ back and the name full circle.
+
+```js
+import { $, $$ } from "@manyducks.co/dolla";
+
+// Shorthand dolla sign
+
+// An initial value (with optional options object) creates a state.
+const [$count, setCount] = $(0);
+// = createState(0)
+
+// An array and a function derives a state.
+const $doubled = $.map([$count], (count) => count * 2);
+// = derive([$count], (count) => count * 2);
+
+// A state returns the same state.
+const $sameCount = $.from($count);
+const $wrapped = $.from({ message: "This is a state with no setter." });
+// = toState($count)
+
+// Get value from a state. Values that are not states are returned directly.
+const count = $.get($count);
+```
+
+What about other operators like RxJS?
+
+```js
+// These would be functionally equivalent.
+const $doubled = $count.pipe($.map((count) => count * 2));
+const $doubled = $.map([$count], (count) => count * 2);
+
+// Chainable. Get doubled value, but only update if it's between 10 and 100.
+const $boundedDouble = $count.pipe(
+  // Transforms the value
+  $.map((count) => count * 2),
+
+  // Receives the value when it changes without affecting the output.
+  // Only receives values while this state is actively being watched.
+  $.tap((count) => console.log(`doubled value is ${count}`))
+
+  // Value only changes if it's within the range.
+  $.filter((count) => count >= 10 && count <= 100),
+);
+
+// Could have a top level pipe operator
+const $boundedDouble = $.pipe(
+  [$count],
+  $.map((count) => count * 2),
+  $.tap((count) => console.log(`doubled value is ${count}`))
+  $.filter((count) => count >= 10 && count <= 100),
+);
+
+// Could also be chainable
+const $boundedDouble = $count
+  .map((count) => count * 2)
+  .tap((count) => console.log(`doubled value is ${count}`))
+  .filter((count) => count >= 10 && count <= 100);
+
+// I kind of like this more than the current derive. It's cleaner.
+$count.map(c => c * 2);
+$count.merge([$other], (c, o) => c * o);
+
+// Another way to merge multiple.
+$.merge([$count, $other], (c, o) => c * o);
+
+// What if you want to add something in the middle?
+
+const $example = $count
+  .map((count) => count * 2)
+  .tap((count) => console.log(`doubled value is ${count}`))
+  .merge([$other1, $other2], (count, other1, other2) => /* ... */)
+  .filter((value) => value >= 10 && value <= 100);
+
+// Is this a good pattern?
+$count
+  .merge([$other], (count, other) => count * other)
+  .merge([$another], (merged, another) => merged * another);
+// I think it gets a little weird to follow.
+
+// equivalent to
+derive(
+  [
+    derive([$count, $other], (count, other) => count * other),
+    $another
+  ],
+  (merged, another) => merged * another)
+// Is this a pattern? Yeah, I guess I do that. Just never in line like that.
+
+// Do we want to handle errors?
+// I feel like errors usually happen in watchers though.
+$boundedDouble.watch((value) => {
+  // Received a value.
+}, (error) => {
+  // Something threw an error.
+});
+// Or like this.
+$boundedDouble.watch({
+  change: (value) => {
+    // Received a value.
+    // This code is most likely to throw an error.
+    // Should errors here be passed to the error callback?
+    // What is the point if you can just try/catch?
+
+    // Although if you don't then Dolla could use this to catch
+    // and trace errors better than it does now.
+  },
+  error: (error) => {
+    // Something threw an error.
+  }
+});
+
+// Filter derives a new state where the value only updates if the function returns truthy.
+const $evens = $count.pipe($.filter((count) => count % 1 === 0));
+// This is equivalent to
+const $events = $.map([$count], (count) => count, { equals: (a, b) => a % 1 === 0 });
+
+function filter(...args) {
+  if (isArray(args[0]) && isFunction(args[1])) {
+    // Standalone signature. Returns a new derived state.
+  } else if (args.length === 1 && isFunction(args[1])) {
+    // Curried signature. Returns a function that takes an array of states
+    // and returns one with args[1] as the equality check.
+  }
+}
+```
+
+And you can write your own operators that implement these two signatures.
+
+```js
+// Here's one I might want to include.
+// Use this to prevent ever getting a null value.
+compare((next, previous) => next ?? previous ?? "default");
+
+function compare(...args) {}
+```
+
+---
+
+I've been looking into other libraries that don't make you track your dependencies specifically. I think this is weird and unhinged to be honest. Calling functions with side effects that magically re-run things when the value changes is a truly weird and unexpected lifecycle. At least if you're explicitly tracking dependencies you know exactly what depends on what at a glance. Getting the computer to figure it out for you doesn't seem smart.
+
+```js
+import { $ } from "@manyducks.co/dolla";
+
+const [count, setCount] = $(0);
+
+const doubled = $.computed(() => count() * 2);
+
+$.effect(() => {
+  console.log(doubled());
+});
+
+$.batch(() => {
+  // Set multiple things but defer updates to after this function returns.
+});
+
+// Helpers on $; can plug into template as is.
+$.if(
+  $.computed(() => count() > 5),
+  <span>Greater than 5!</span>,
+  <span>Not greater than 5...</span>,
+);
+
+const switched = $.switch(count, [[1, "one"], [2, "two"], [3, "three"]], "more...");
+
+$.repeat()
+
+// TODO: How feasible is this?
+<Repeat each={}>
+  {(item, index) => {
+
+  }}
+</Repeat>
+
+<Show when={condition}>
+  Condition is true.
+</Show>
+
+// Get
+count();
+
+// Set
+count(52);
+```
+
+---
+
 What if Dolla was just a global object that you don't instantiate. I have never personally run into a use case for having more than one app on a page at once. In all my projects, the page and the app are synonymous.
 
 Doing this would make it possible to access things inside the Dolla app from _outside_ code such as Quill blots. Effectively all code that has access to your Dolla import is _inside_ the app.
@@ -11,8 +358,8 @@ Doing this would make it possible to access things inside the Dolla app from _ou
 import Dolla from "@manyducks.co/dolla";
 
 // Languages: add translation, set language and get localized string as a signal
-Dolla.language.setup({
-  initialLanguage: Dolla.language.detect({ fallback: "ja" }), // Detect user's language and fall back to passed value
+Dolla.i18n.setup({
+  initialLanguage: Dolla.i18n.detect({ fallback: "ja" }), // Detect user's language and fall back to passed value
   languages: [
     { name: "ja", path: "/static/locales/ja.json" },
     {
@@ -26,8 +373,8 @@ Dolla.language.setup({
   ]
 });
 
-Dolla.language.$current
-Dolla.language.t$()
+Dolla.i18n.$locale
+Dolla.i18n.t$()
 
 // A single setup call to keep things contained (must happen before mount)
 Dolla.router.setup({
@@ -75,10 +422,10 @@ debug.log("HELLO");
 debug.warn("THIS IS A SCOPED LOGGER");
 
 // Efficiently and safely read and mutate the DOM using Dolla's render batching
-Dolla.render.read(() => {
+Dolla.batch.read(() => {
   // Reference DOM nodes
 });
-Dolla.render.update(() => {
+Dolla.batch.write(() => {
   // Mutate the DOM as part of Dolla's next batch
 }, "some-key");
 

package/notes/splitting.md

@@ -0,0 +1,5 @@
+# Splitting
+
+Thinking again of splitting this out into multiple libraries. Or at least having the base signals+markup be its own standalone thing that the rest of the framework is built on.
+
+This implementation of signals + templates would be useful for web components.