@manyducks.co/dolla 2.0.0-alpha.3 → 2.0.0-alpha.31

package/notes/scratch.md

@@ -1,5 +1,193 @@
 # Scratch Note
 
+---
+
+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 +199,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 +214,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 +263,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");
 
@@ -93,7 +281,7 @@ function SomeView (props: SomeViewProps, ctx: Dolla.ViewContext) {
   const debug = Dolla.createLogger("SomeView");
 
   // returns a signal and a setter function
-  const [$someValue, setSomeValue] = Dolla.createSignal(4);
+  const [$someValue, setSomeValue] = Dolla.createState(4);
 
   // Router is now a part of the Dolla object
   Dolla.router.$path;

package/notes/stores.md

@@ -0,0 +1,73 @@
+# Stores
+
+Ideas for updating the API.
+
+```js
+import { createStore, attachStore, useStore, createView } from "@manyducks.co/dolla";
+
+const Counter = createStore(function (initialCount: number) {
+  const [$value, setValue] = createState(initialCount);
+
+  this.on("counter:increment", (e) => {
+    e.stopPropagation(); // Stop this event from bubbling up to counters at higher levels (if any).
+    setValue((current) => current + 1);
+  });
+
+  this.on("counter:decrement", (e) => {
+    e.stopPropagation();
+    setValue((current) => current - 1);
+  });
+
+  // Events can be emitted from this context in a store.
+  this.emit("otherEvent");
+
+  this.onMount(() => {
+    // Setup
+    // This is called based on the context the store is attached to.
+    // If Dolla, it's called when the app is mounted. If ViewContext, it's called when the view is mounted.
+  });
+  this.onUnmount(() => {
+    // Cleanup
+  });
+
+  // Context variables will be accessible on the same context (e.g. the view this is attached to and below)
+  this.get("context variable");
+  this.set("context variable", "context variable value");
+
+  // Stores don't have to return anything, but if they do it becomes accessible by using `useStore(ctx, Store)`.
+  return $value;
+});
+
+// Attach it to the app.
+Dolla.attachStore(Counter(0));
+
+const ExampleView = createView(function () {
+  // useStore lets you access the return value
+  // but the events will still be received and handled regardless
+  const $count = this.useStore(Counter);
+
+  // Convenience helper to attach and use in one step?
+  const $count = this.attachAndUseStore(Counter(0));
+
+  return html`
+    <button onclick=${() => this.emit("counter:decrement")}>-1</button>
+    <span>${$count}</span>
+    <button onclick=${() => this.emit("counter:increment")}>+1</button>
+  `;
+});
+
+// ViewContext is also still passed as a second argument if you'd rather use arrow functions to define views.
+const ExampleView = createView((props, self) => {
+  // useStore lets you access the return value
+  // but the events will still be received and handled regardless
+  const $count = self.useStore(Counter);
+
+  return html`
+    <button onclick=${() => self.emit("counter:decrement")}>-1</button>
+    <span>${$count}</span>
+    <button onclick=${() => self.emit("counter:increment")}>+1</button>
+  `;
+});
+```
+
+This means `createStore` returns a function that is called to create a Store instance. The instance is

package/package.json

@@ -1,12 +1,15 @@
 {
   "name": "@manyducks.co/dolla",
-  "version": "2.0.0-alpha.3",
+  "version": "2.0.0-alpha.31",
   "description": "Front-end components, routing and state management.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "type": "module",
   "sideEffects": false,
-  "repository": "https://github.com/manyducksco/dolla",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/manyducksco/dolla.git"
+  },
   "scripts": {
     "test": "npm run build && node --test",
     "build:esbuild": "tsc && node build.js",
@@ -36,20 +39,15 @@
       "types": "./jsx-dev-runtime.d.ts"
     }
   },
-  "dependencies": {
-    "fetch-ponyfill": "^7.1.0",
-    "history": "^5.3.0",
-    "nanoid": "^5.0.4",
-    "simple-color-hash": "^1.0.2",
-    "vite": "^6.0.7"
-  },
   "devDependencies": {
-    "@types/node": "^18.17.6",
+    "@manyducks.co/emitter": "^1.1.2",
+    "@types/node": "^22.12.0",
     "csstype": "^3.1.3",
-    "esbuild": "^0.24.2",
+    "fast-deep-equal": "^3.1.3",
     "htm": "^3.1.1",
-    "prettier": "^3.2.4",
-    "typescript": "^5.3.3",
-    "zod": "^3.22.4"
+    "prettier": "^3.4.2",
+    "simple-color-hash": "^1.0.2",
+    "typescript": "^5.7.3",
+    "vite": "^6.0.11"
   }
 }

package/tests/{signals.test.js → state.test.js}

@@ -1,10 +1,10 @@
 import test from "node:test";
 import assert from "node:assert";
 
-import { signal, derive } from "../lib/index.js";
+import { createState, derive } from "../dist/index.js";
 
 test("signal", (t) => {
-  const [$count, setCount] = signal(5);
+  const [$count, setCount] = createState(5);
 
   const defaultWatcher = t.mock.fn();
   const stopDefault = $count.watch(defaultWatcher);
@@ -42,8 +42,8 @@ test("signal", (t) => {
 });
 
 test("derive", (t) => {
-  const [$one, setOne] = signal(5);
-  const [$two, setTwo] = signal(20);
+  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);
@@ -101,9 +101,9 @@ test("derive", (t) => {
 });
 
 test("derive nested signals", (t) => {
-  const [$value, setValue] = signal(5);
+  const [$value, setValue] = createState(5);
 
-  const [$object, setObject] = signal({
+  const [$object, setObject] = createState({
     href: derive([$value], (value) => `/projects/${value}/test`),
   });
 

package/vite.config.js

@@ -3,8 +3,6 @@ import { defineConfig } from "vite";
 
 export default defineConfig({
   build: {
-    // minify: "terser",
-    // minify: false,
     sourcemap: true,
 
     lib: {
@@ -16,13 +14,5 @@ export default defineConfig({
       name: "Dolla",
       formats: ["es"],
     },
-    // rollupOptions: {
-    //   external: ["vue"],
-    //   output: {
-    //     globals: {
-    //       vue: "Vue",
-    //     },
-    //   },
-    // },
   },
 });

package/dist/markup.d.ts

@@ -1,100 +0,0 @@
-import type { Dolla } from "./modules/dolla.js";
-import { MaybeSignal, type Signal } from "./signals.js";
-import type { Renderable, Stringable } from "./types.js";
-import { type ViewFunction, type ViewContext, type ViewResult } from "./view.js";
-export interface ElementContext {
-    /**
-     * The root Dolla instance this element belongs to.
-     */
-    root: Dolla;
-    /**
-     * Whether to create DOM nodes in the SVG namespace. An `<svg>` element will set this to true and pass it down to children.
-     */
-    isSVG?: boolean;
-}
-/**
- * Markup is a set of element metadata that hasn't been constructed into a MarkupNode yet.
- */
-export interface Markup {
-    type: string | ViewFunction<any>;
-    props?: Record<string, any>;
-    children?: Markup[];
-}
-/**
- * A DOM node that has been constructed from a Markup object.
- */
-export interface MarkupNode {
-    readonly node?: Node;
-    readonly isMounted: boolean;
-    mount(parent: Node, after?: Node): void;
-    unmount(): void;
-}
-export declare function isMarkup(value: unknown): value is Markup;
-export declare function isNode(value: unknown): value is MarkupNode;
-export declare function toMarkup(renderables: Renderable | Renderable[]): Markup[];
-export interface MarkupAttributes {
-    $text: {
-        value: MaybeSignal<Stringable>;
-    };
-    $cond: {
-        $predicate: Signal<any>;
-        thenContent?: Renderable;
-        elseContent?: Renderable;
-    };
-    $repeat: {
-        $items: Signal<any[]>;
-        keyFn: (value: any, index: number) => string | number | symbol;
-        renderFn: ($item: Signal<any>, $index: Signal<number>, c: ViewContext) => ViewResult;
-    };
-    $observer: {
-        signals: Signal<any>[];
-        renderFn: (...items: any) => Renderable;
-    };
-    $outlet: {
-        $children: Signal<MarkupNode[]>;
-    };
-    $node: {
-        value: Node;
-    };
-    $portal: {
-        content: Renderable;
-        parent: Node;
-    };
-    [tag: string]: Record<string, any>;
-}
-export declare function createMarkup<T extends keyof MarkupAttributes>(type: T, attributes: MarkupAttributes[T], ...children: Renderable[]): Markup;
-export declare function createMarkup<I>(type: ViewFunction<I>, attributes?: I, ...children: Renderable[]): Markup;
-/**
- * Generate markup with HTML in a tagged template literal.
- */
-export declare const html: (strings: TemplateStringsArray, ...values: any[]) => Markup | Markup[];
-/**
- * Displays content conditionally. When `predicate` holds a truthy value, `thenContent` is displayed; when `predicate` holds a falsy value, `elseContent` is displayed.
- */
-export declare function cond(predicate: MaybeSignal<any>, thenContent?: Renderable, elseContent?: Renderable): Markup;
-/**
- * Calls `renderFn` for each item in `items`. Dynamically adds and removes views as items change.
- * The result of `keyFn` is used to compare items and decide if item was added, removed or updated.
- */
-export declare function repeat<T>(items: MaybeSignal<T[]>, keyFn: (value: T, index: number) => string | number | symbol, renderFn: ($value: Signal<T>, $index: Signal<number>, ctx: ViewContext) => ViewResult): Markup;
-/**
- * Render `content` into a `parent` node anywhere in the page, rather than at its position in the view.
- */
-export declare function portal(parent: Node, content: Renderable): Markup;
-/**
- * A special kind of signal exclusively for storing references to DOM nodes.
- */
-export declare function createRef<T extends Node>(): Ref<T>;
-export declare function isRef<T extends Node>(value: any): value is Ref<T>;
-export interface Ref<T extends Node> extends Signal<T | undefined> {
-    node: T | undefined;
-}
-/**
- * Construct Markup metadata into a set of MarkupNodes.
- */
-export declare function constructMarkup(elementContext: ElementContext, markup: Markup | Markup[]): MarkupNode[];
-/**
- * Combines one or more MarkupNodes into a single MarkupNode.
- */
-export declare function mergeNodes(nodes: MarkupNode[]): MarkupNode;
-export declare function isRenderable(value: unknown): value is Renderable;

package/dist/modules/dolla.d.ts

@@ -1,111 +0,0 @@
-import { createRef, isRef, MarkupNode, type Markup } from "../markup.js";
-import { createSettableSignal, createSignal, derive, designalify, signalify, toSettableSignal, watch, type Signal } from "../signals.js";
-import { type ViewFunction, type ViewNode } from "../view.js";
-import { type CrashViewProps } from "../views/default-crash-view.js";
-import { HTTP } from "./http.js";
-import { Language } from "./language.js";
-import { Render } from "./render.js";
-import { Router } from "./router.js";
-export type Environment = "development" | "production";
-/**
- * Log type toggles. Each message category can be turned on or off or enabled only in a specific environment.
- */
-export type Loggles = {
-    info: boolean | Environment;
-    log: boolean | Environment;
-    warn: boolean | Environment;
-    error: boolean | Environment;
-};
-export interface Logger {
-    info(...args: any[]): void;
-    log(...args: any[]): void;
-    warn(...args: any[]): void;
-    error(...args: any[]): void;
-    crash(error: Error): void;
-}
-export interface LoggerErrorContext {
-    error: Error;
-    loggerName: string;
-    uid?: string;
-}
-export type LoggerOptions = {
-    /**
-     * Console object to use for logging (mostly for testing). Uses window.console by default.
-     */
-    console?: any;
-    /**
-     * Unique ID to print with logs. Makes it easier to track down messages from specific view instances.
-     */
-    uid?: string;
-};
-export declare class Dolla {
-    #private;
-    readonly http: HTTP;
-    readonly language: Language;
-    readonly render: Render;
-    readonly router: Router;
-    constructor();
-    createSignal: typeof createSignal;
-    createSettableSignal: typeof createSettableSignal;
-    toSettableSignal: typeof toSettableSignal;
-    signalify: typeof signalify;
-    designalify: typeof designalify;
-    derive: typeof derive;
-    watch: typeof watch;
-    createRef: typeof createRef;
-    isRef: typeof isRef;
-    /**
-     * True when the app is connected to a DOM node and displayed to the user.
-     */
-    get isMounted(): boolean;
-    /**
-     * Get the current environment that this app is running in.
-     * Environment affects which log messages will print and how much debugging info is included in the DOM.
-     */
-    getEnv(): Environment;
-    /**
-     * Sets the environment that this app is running in.
-     * Environment affects which log messages will print and how much debugging info is included in the DOM.
-     */
-    setEnv(value: Environment): void;
-    /**
-     * Sets the view that will be shown when the `crash` method is called on any logger.
-     * When a crash is reported the app will be unmounted and replaced with this crash page.
-     */
-    setCrashView(view: ViewFunction<CrashViewProps>): void;
-    mount(selector: string, view?: ViewFunction<any>): Promise<void>;
-    mount(element: HTMLElement, view?: ViewFunction<any>): Promise<void>;
-    unmount(): Promise<void>;
-    /**
-     * Registers a `callback` to run after `Dolla.mount` is called, before the app is mounted. If `callback` returns a Promise,
-     * it will be awaited before mounting finishes. Use this to perform initial setup before the app is displayed to the user.
-     */
-    beforeMount(callback: () => void | Promise<void>): void;
-    /**
-     * Registers a `callback` to run after the app is mounted.
-     */
-    onMount(callback: () => void): void;
-    /**
-     * Registers a `callback` to run after `Dolla.unmount` is called, before the app is unmounted. If `callback` returns a Promise,
-     * it will be awaited before unmounting finishes. Use this to perform cleanup.
-     */
-    beforeUnmount(callback: () => void | Promise<void>): void;
-    /**
-     * Registers a `callback` to run after the app is unmounted.
-     */
-    onUnmount(callback: () => void): void;
-    /**
-     * Update log type toggles. Values that are not passed will remain unchanged.
-     */
-    setLoggles(options: Partial<Loggles>): void;
-    setLogFilter(filter: string | RegExp): void;
-    createLogger(name: string | Signal<string>, options?: LoggerOptions): Logger;
-    /**
-     *
-     */
-    constructView<P>(view: ViewFunction<P>, props: P, children?: Markup[]): ViewNode;
-    /**
-     *
-     */
-    constructMarkup(markup: Markup | Markup[]): MarkupNode;
-}

package/dist/modules/language.d.ts

@@ -1,41 +0,0 @@
-import { type Signal } from "../signals.js";
-import type { Stringable } from "../types.js";
-import type { Dolla } from "./dolla.js";
-/**
- * An object where values are either a translated string or another nested Translation object.
- */
-type LocalizedStrings = Record<string, string | Record<string, string | Record<string, string | Record<string, string>>>>;
-export interface LanguageConfig {
-    name: string;
-    /**
-     * Path to a JSON file with translated strings for this language.
-     */
-    path?: string;
-    /**
-     * A callback function that returns a Promise that resolves to the translation object for this language.
-     */
-    fetch?: () => Promise<LocalizedStrings>;
-}
-export type LanguageSetupOptions = {
-    /**
-     * Default language to load on startup
-     */
-    initialLanguage?: string | null;
-    languages: LanguageConfig[];
-};
-export declare class Language {
-    #private;
-    $current: Signal<string | undefined>;
-    constructor(dolla: Dolla);
-    get supportedLanguages(): string[];
-    setup(options: LanguageSetupOptions): void;
-    setLanguage(name: string): Promise<void>;
-    /**
-     * Returns a Signal containing the value at `key`.
-    
-     * @param key - Key to the translated value.
-     * @param values - A map of {{placeholder}} names and the values to replace them with.
-     */
-    t(key: string, values?: Record<string, Stringable | Signal<Stringable>>): Signal<string>;
-}
-export {};

package/dist/modules/render.d.ts

@@ -1,17 +0,0 @@
-import type { Dolla } from "./dolla.js";
-export declare class Render {
-    #private;
-    constructor(dolla: Dolla);
-    /**
-     * Queues a callback to run in the next render batch.
-     * Running your DOM mutations in update callbacks reduces layout thrashing.
-     * Returns a Promise that resolves once the callback has run.
-     */
-    update(callback: () => void, key?: string): Promise<void>;
-    /**
-     * Queues a callback that reads DOM information to run after the next render batch,
-     * ensuring all writes have been performed before reading.
-     * Returns a Promise that resolves once the callback has run.
-     */
-    read(callback: () => void): Promise<void>;
-}