@manyducks.co/dolla 2.0.0-alpha.34 → 2.0.0-alpha.35

package/dist/types.d.ts

@@ -1,17 +1,17 @@
 import type * as CSS from "csstype";
 import type { Markup } from "./core/markup.js";
-import type { State } from "./core/state.js";
+import { Reactive } from "./core/signals.js";
 /**
  * Represents everything that can be handled as a DOM node.
  * These are all the items considered valid to pass as children to any element.
  */
-export type Renderable = string | number | Markup | false | null | undefined | State<any> | (string | number | Markup | false | null | undefined | State<any>)[];
+export type Renderable = string | number | Markup | false | null | undefined | Reactive<any> | (string | number | Markup | false | null | undefined | Reactive<any>)[];
 export type Stringable = {
     toString(): string;
 };
-type MaybeState<T> = T | State<T> | State<T | undefined>;
-type OptionalProperty<T> = T | State<T> | State<T | undefined>;
-type RequiredProperty<T> = T | State<T>;
+type MaybeReactive<T> = T | Reactive<T> | Reactive<T | undefined>;
+type OptionalProperty<T> = MaybeReactive<T>;
+type RequiredProperty<T> = T | Reactive<T>;
 type AutocapitalizeValues = "off" | "on" | "none" | "sentences" | "words" | "characters";
 type ContentEditableValues = true | false | "true" | "false" | "plaintext-only" | "inherit";
 type ClassListValues = string | ClassMap | Array<string | ClassMap | (string | ClassMap)[]>;
@@ -110,7 +110,7 @@ export interface ElementProps {
      *
      * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/style
      */
-    style?: string | CSSProperties | State<string> | State<CSSProperties> | State<string | CSSProperties> | State<string | undefined> | State<CSSProperties | undefined> | State<string | CSSProperties | undefined>;
+    style?: string | CSSProperties | Reactive<string> | Reactive<CSSProperties> | Reactive<string | CSSProperties> | Reactive<string | undefined> | Reactive<CSSProperties | undefined> | Reactive<string | CSSProperties | undefined>;
     /**
      * Fired when a CSS animation unexpectedly aborts.
      *
@@ -1210,7 +1210,7 @@ export type CSSProperties = {
     [K in keyof Styles]: OptionalProperty<Styles[K]>;
 };
 export interface ClassMap {
-    [className: string]: MaybeState<any>;
+    [className: string]: MaybeReactive<any>;
 }
 export type EventHandler<E> = (event: E) => void;
 export interface PropertiesOf<E extends HTMLElement> extends HTMLElementProps {
@@ -2098,7 +2098,7 @@ interface HTMLMediaElementProps<T extends HTMLMediaElement> extends HTMLElementP
      *
      * @see https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/srcObject
      */
-    srcObject?: MediaStream | MediaSource | Blob | File | State<MediaStream> | State<MediaStream | undefined> | State<MediaSource> | State<MediaSource | undefined> | State<Blob> | State<Blob | undefined> | State<File> | State<File | undefined>;
+    srcObject?: MediaStream | MediaSource | Blob | File | Reactive<MediaStream> | Reactive<MediaStream | undefined> | Reactive<MediaSource> | Reactive<MediaSource | undefined> | Reactive<Blob> | Reactive<Blob | undefined> | Reactive<File> | Reactive<File | undefined>;
     /**
      * The current audio volume of the media element. Must be a number between 0 and 1.
      *
@@ -2597,7 +2597,7 @@ interface HTMLImageElementProps extends PropertiesOf<HTMLImageElement> {
      *
      * @see https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/sizes
      */
-    sizes?: MaybeState<string>;
+    sizes?: MaybeReactive<string>;
     /**
      * The image URL.
      *

package/docs/signals.md

@@ -0,0 +1,149 @@
+## ⚡ 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.
+
+[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`
+
+
+### Basic State API
+
+```js
+import { createState } 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);
+
+// Get the current value.
+$count.get(): // 72
+
+// Set a new value.
+setCount(300);
+
+// The State now reflects the latest value.
+$count.get(); // 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
+```
+
+### Deriving States from other States
+
+#### Example 1: Doubled
+
+```js
+import { createState, derive } from "@manyducks.co/dolla";
+
+const [$count, setCount] = createState(1);
+
+const $doubled = derive([$count], (count) => count * 2);
+
+setCount(10);
+$doubled.get(); // 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.
+
+#### Example 2: Selecting a User
+
+```js
+import { createState, derive } from "@manyducks.co/dolla";
+
+const [$users, setUsers] = createState([
+  { id: 1, name: "Audie" },
+  { id: 2, name: "Bob" },
+  { id: 3, name: "Cabel" },
+]);
+const [$selectedUserId, setSelectedUserId] = createState(1);
+
+const $selectedUser = derive([$users, $selectedUserId], (users, id) => {
+  return users.find((user) => user.id === id);
+});
+
+$selectedUser.get(); // { id: 1, name: "Audie" }
+
+setSelectedId(3);
+
+$selectedUser.get(); // { 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.
+
+The strength of setting up a join like this is that the `$users` array can be updated (by API call, websockets, etc.) and your `$selectedUser` will always be pointing to the latest version of the user data.
+
+#### Example 3: Narrowing Complex Data
+
+```jsx
+import { createState, derive } from "@manyducks.co/dolla";
+
+const [$user, setUser] = createState({ id: 1, name: "Audie" });
+
+const $name = derive([$user], (user) => user.name);
+
+$name.get(); // "Audie"
+
+// In a view:
+<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
+
+```js
+import { createState, toState, toValue } from "@manyducks.co/dolla";
+
+const [$count, setCount] = createState(512);
+
+// Unwrap the value of $count. Returns 512.
+const count = toValue($count);
+// Passing a non-state value will simply return it.
+const name = toValue("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);
+```
+
+### In Views
+
+```jsx
+import { derive } 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>;
+});
+```
+
+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.
+
+- [🗂️ Docs](./index.md)
+- [🏠 README](../README.md)
+- [🦆 That's a lot of ducks.](https://www.manyducks.co)

package/docs/views.md

@@ -118,7 +118,7 @@ function ExampleView(props, ctx) {
 ```jsx
 function ExampleView(props, ctx) {
   // Set the name of this view's context. Console messages are prefixed with name.
-  ctx.setName("CustomName");
+  ctx.name = "CustomName";
 
   // Print messages to the console. These are suppressed by default in the app's "production" mode.
   // You can also change which of these are printed and filter messages from certain contexts in the `createApp` options object.

package/notes/atomic.md

@@ -0,0 +1,146 @@
+# Atomic API
+
+```js
+function SomeView(props, ctx) {
+  // Atoms are the basic building block of state.
+  const count = new Atom(5);
+
+  count.value; // returns the value
+  count.value = 12; // replaces the value
+  count.update((value) => value + 1); // updates the value. You can use Immer here for complex objects.
+
+  // or you could just implement an update function yourself with Immer. Probably gonna cut it.
+  function update(atom, callback) {
+    atom.value = produce(atom.value, callback);
+  }
+  update(count, (value) => value + 1);
+
+  // Listen for changes. Callback will be run the next time the value changes and each time again afterwards.
+  const unsubscribe = count.subscribe((value) => {
+    console.log(value);
+  });
+
+  // Composed is a state that depends on one or more other states.
+  // The callback takes a getter function that will track that state as a dependency and return its current value.
+  // We recompute if any tracked dependency receives a new value.
+  const doubled = new Composed((get) => get(count) * 2);
+
+  // Effects follow the same pattern as a Composed callback.
+  ctx.effect(() => {
+    console.log(doubled.value);
+  });
+
+  const print = new Atom(false);
+
+  // Dependency lists are rebuilt every time the callback is run.
+  // Below, `value` will not be tracked as a dependency until `print` has changed to true.
+  ctx.effect(() => {
+    if (get(print)) {
+      console.log(get(value));
+    }
+  });
+
+  // get() is also the ONLY way to track dependencies.
+  // You're free to use the state's own getter if you want the value without actually tracking it.
+  ctx.effect((get) => {
+    if (get(value) > 5) {
+      console.log(doubled.get()); // will not be tracked
+    }
+  });
+
+  // ALSO: Need to track sets and updates so we can throw an error if a set was committed in the same scope that value is tracked. Otherwise this will cause an infinite loop.
+}
+```
+
+Refined API:
+
+```js
+
+const $count = atom(5);
+$count.value++;
+$count.value; // 6
+
+const $doubled = compose(() => get($count) * 2);
+const $quadrupled = compose(() => get($doubled) * 2);
+
+ctx.effect(() => {
+  if (get($count) > 25) {
+    console.log($doubled.value);
+    get($quadrupled);
+  }
+});
+```
+
+vs old API:
+
+```js
+// ----- Basic State ----- //
+
+// Old
+const [$count, setCount] = createState(5);
+setCount((count) => count + 1);
+$count.get(); // 6
+
+// New
+const count = atom(5);
+count.value++;
+count.value; // 6
+
+// ----- Derived State ----- //
+
+// Old
+const $doubled = derive([$count], (count) => count * 2);
+const $quadrupled = derive([$doubled], (doubled) => doubled * 2);
+
+// New
+const doubled = compose((get) => get(count) * 2);
+const quadrupled = compose((get) => get(doubled) * 2);
+
+// ----- Side Effects ----- //
+
+// Old
+ctx.watch([$count, $quadrupled], (count, quadrupled) => {
+  if (count > 25) {
+    console.log($doubled.get()); // not tracked
+
+    console.log(quadrupled);
+    // changes to $quadrupled will trigger this callback to re-run, even if count is still <= 25
+  }
+});
+
+// New
+ctx.effect((get) => {
+  // count is tracked by reading it with 'get'
+  if (get(count) > 25) {
+    console.log(doubled.value); // not tracked
+
+    get(quadrupled); // only tracked while count > 25 (this 'get' doesn't run otherwise)
+    // changes to 'quadrupled' will NOT trigger this callback to re-run unless 'count' is already >= 25
+  }
+});
+```
+
+Atoms and composed values implement the `Reactive<T>` interface for TypeScript purposes. There is also `Atom<T>` and `Composed<T>` if you want to be specific.
+
+The API above is a remix of Preact signals, Jotai and the TC39 Signals proposal. I strongly dislike automatic dependency tracking. I think the developer should explicitly describe what they want instead of having the language assume what they want and making them opt out with `untrack` and such. Madness.
+
+It's also unintuitive what's a tracked scope and what isn't. There's nothing to tell you that at a glance. It's left up to the framework conventions. With this API you know; if you're in a function scope and you have a getter, you're in a tracking-capable scope. Doing that tracking is then left up to you. You can explicitly see that things are being tracked by reading the code. There is no background knowledge needed and no side effects required.
+
+Further API:
+
+```js
+// If count is reactive we get its current value. Otherwise we get it as is.
+const value = unwrap(count);
+
+// If count is reactive we get it as is (typed as Reactive<T>). Otherwise we get it wrapped as a Reactive<T>.
+const value = reactive(count);
+```
+
+```js
+const me = compose((get) => {
+  const id = get(userId);
+  return get(users)_?.find((u) => u.id === id);
+});
+
+const $me = derive([$userId, $users], (id, users) => users?.find((u) => u.id === id));
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@manyducks.co/dolla",
-  "version": "2.0.0-alpha.34",
+  "version": "2.0.0-alpha.35",
   "description": "Front-end components, routing and state management.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -11,7 +11,7 @@
     "url": "git+https://github.com/manyducksco/dolla.git"
   },
   "scripts": {
-    "test": "npm run build && node --test",
+    "test": "vitest",
     "build:esbuild": "tsc && node build.js",
     "build": "vite build && tsc",
     "start": "tsc --watch",
@@ -39,15 +39,19 @@
       "types": "./jsx-dev-runtime.d.ts"
     }
   },
-  "devDependencies": {
+  "dependencies": {
     "@manyducks.co/emitter": "^1.1.2",
-    "@types/node": "^22.12.0",
-    "csstype": "^3.1.3",
+    "alien-signals": "^1.0.3",
     "fast-deep-equal": "^3.1.3",
     "htm": "^3.1.1",
+    "simple-color-hash": "^1.0.2"
+  },
+  "devDependencies": {
+    "@types/node": "^22.12.0",
+    "csstype": "^3.1.3",
     "prettier": "^3.4.2",
-    "simple-color-hash": "^1.0.2",
     "typescript": "^5.7.3",
-    "vite": "^6.0.11"
+    "vite": "^6.0.11",
+    "vitest": "^3.0.5"
   }
 }

package/vite.config.js

@@ -8,6 +8,9 @@ export default defineConfig({
     lib: {
       entry: {
         index: resolve(__dirname, "src/index.ts"),
+        // http: resolve(__dirname, "src/http/index.ts"),
+        // router: resolve(__dirname, "src/router/index.ts"),
+        // translate: resolve(__dirname, "src/translate/index.ts"),
         "jsx-runtime": resolve(__dirname, "src/jsx-runtime.js"),
         "jsx-dev-runtime": resolve(__dirname, "src/jsx-dev-runtime.js"),
       },

package/dist/core/state.d.ts

@@ -1,126 +0,0 @@
-import { strictEqual } from "../utils";
-import { IS_STATE } from "./symbols";
-/**
- * Stops the observer that created it when called.
- */
-export type StopFunction = () => void;
-type Unwrapped<T> = T extends State<infer V> ? V : T;
-/**
- * Extracts value types from an array of states.
- */
-export type StateValues<T extends MaybeState<any>[]> = {
-    [K in keyof T]: Unwrapped<T[K]>;
-};
-export interface CreateStateOptions<T> {
-    /**
-     * Determines if the `next` value is equal to the `current` value.
-     * If this function returns true, watchers will be notified of changes. If it returns false, watchers will not be notified.
-     * Default equals check is `===` (strict) equality.
-     *
-     * @param next - The new value being set.
-     * @param current - The current value being replaced.
-     */
-    equals?: (next: T, current: T) => boolean;
-}
-export interface WatchOptions<T> {
-    /**
-     * If true the watch callback will be called for the first time on the next change.
-     * Callback is immediately called with the state's current value by default.
-     */
-    lazy?: boolean;
-}
-export interface State<T> {
-    /**
-     * Returns the current value.
-     */
-    get(): T;
-    /**
-     * Watch this state's value with a `callback` function.
-     * The `callback` is only called if the value is not equal to the current value.
-     *
-     * > NOTE: If watching a state inside a view, use the `.watch` method on the `ViewContext`. That method will automatically
-     * clean up all watchers when the view is disconnected. Watchers created here must be cleaned up manually.
-     */
-    watch(callback: (value: T) => void, options?: WatchOptions<T>): StopFunction;
-}
-/** A new value for a state, or a callback that receives the current value and returns a new one. */
-export type SetAction<I, O = I> = O | SetFunction<I, O>;
-export type SetFunction<I, O = I> = (current: I) => O;
-/** Callback that updates the value of a state. */
-export type Setter<I, O = I> = (value: SetAction<I, O>) => void;
-export type MaybeState<T> = State<T> | T;
-export declare function isState<T>(value: any): value is State<T>;
-/**
- * Retrieves a plain value from a variable that may be a state.
- */
-export declare function toValue<T>(source: MaybeState<T>): T;
-/**
- * Ensures a variable that may be a state or plain value is a state.
- */
-export declare function toState<T>(value: MaybeState<T>): State<T>;
-/**
- * ValueHolder implements the core functionality of a State.
- * It holds a value, which can be retrieved with `get`, updated with `set` and observed with `watch`.
- * The user-facing API splits up access into a read-only State and a setter function.
- */
-export declare class ValueHolder<T> implements State<T> {
-    value: T;
-    watchers: ((value: T) => void)[];
-    equals: typeof strictEqual;
-    constructor(value: T, options?: CreateStateOptions<T>);
-    get(): T;
-    set(action: T | SetFunction<T>): void;
-    watch(callback: (value: T) => void, options?: WatchOptions<T>): () => void;
-}
-/**
- * Signal is the implementation of a read-only State.
- */
-export declare class Signal<T> implements State<T> {
-    [IS_STATE]: boolean;
-    __value: State<T>;
-    constructor(value: State<T>);
-    get(): T;
-    watch(callback: (value: T) => void, options?: WatchOptions<T>): StopFunction;
-}
-/**
- * Creates a state and setter.
- */
-export declare function createState<T>(value: T, options?: CreateStateOptions<T>): [State<T>, Setter<T>];
-/**
- * Creates a state and setter.
- */
-export declare function createState<T>(value?: T, options?: CreateStateOptions<T | undefined>): [State<T | undefined>, Setter<T | undefined>];
-export interface DeriveOptions {
-    equals?: (next: unknown, current: unknown) => boolean;
-}
-/**
- * Derives a new `State` from one or more existing states.
- *
- * @param sources - Array of source states to track.
- * @param fn - A function called to recompute the value when any tracked source states receive a new value.
- *
- * @example
- * // With one source...
- * const [$count, setCount] = createState(5);
- * const $doubled = derive([$count], count => count * 2);
- * // ... or many:
- * const [$greeting, setGreeting] = createState("Hello");
- * const [$name, setName] = createState("World");
- * const $hello = derive([$greeting, name], (greeting, name) => `${greeting}, ${name}!`);
- */
-export declare function derive<Sources extends MaybeState<any>[], T>(sources: [...Sources], fn: (...values: StateValues<Sources>) => T | State<T>, options?: DeriveOptions): State<T>;
-export interface StateWatcher {
-    /**
-     * Watch one or more states, calling the provided `fn` each time one of their values changes.
-     *
-     * @param states - An array of states or plain values. States will be unwrapped before being passed to `fn`.
-     * @param fn - A function that takes the values of `states` in the same order they were passed.
-     */
-    watch<I extends MaybeState<any>[]>(states: [...I], fn: (...currentValues: StateValues<I>) => void): StopFunction;
-    /**
-     * Stop all watch callbacks registered to this watcher.
-     */
-    stopAll(): void;
-}
-export declare function createWatcher(): StateWatcher;
-export {};

package/dist/core/stats.d.ts

@@ -1,31 +0,0 @@
-import { Emitter } from "@manyducks.co/emitter";
-import type { Dolla } from "./dolla";
-interface StatsStore {
-    emitter: Emitter<StatsStoreEvents>;
-    stats: {
-        watcherCount: number;
-        viewCount: number;
-    };
-}
-type StatsStoreEvents = {
-    /**
-     * Emitted when any stats are updated in the store.
-     */
-    statsChanged: [];
-    _incrementWatcherCount: [amount: number];
-    _incrementViewCount: [amount: number];
-};
-/**
- * Tracks runtime statistics.
- */
-export declare class Stats {
-    #private;
-    constructor(dolla: Dolla);
-}
-export declare function _createStore(): StatsStore;
-export declare function _getStore(): StatsStore;
-export declare function _onWatcherAdded(): void;
-export declare function _onWatcherRemoved(): void;
-export declare function _onViewMounted(): void;
-export declare function _onViewUnmounted(): void;
-export {};