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

package/notes/scratch.md

@@ -1,5 +1,188 @@
 # Scratch Note
 
+## Dolla Custom Elements
+
+Define custom HTML elements with Dolla.
+
+```jsx
+defineElement("my-counter", {
+  props: {
+    // Defines props and their types
+  },
+  setup: (props, ctx) => {
+    // Returns markup (this is a view)
+    return html` <div></div> `;
+  },
+});
+```
+
+---
+
+## Rendering standalone elements outside an app
+
+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);
+```
+
+---
+
+## 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
@@ -12,27 +195,176 @@ const [$count, setCount] = $(0);
 // = createState(0)
 
 // An array and a function derives a state.
-const $doubled = $([$count], (count) => count * 2);
+const $doubled = $.map([$count], (count) => count * 2);
 // = derive([$count], (count) => count * 2);
 
 // A state returns the same state.
-const $sameCount = $.of($count);
-const $wrapped = $.of({ message: "This is a state with no setter." });
+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 = $.value($count);
+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>
 
-// An initial value creates a SettableState
-const $$count = $$(5);
-// = createSettableState(5);
+<Show when={condition}>
+  Condition is true.
+</Show>
 
-// Merge state and setter into a SettableState
-const $$count = $$($count, setCount);
-// = toSettableState($count, setCount);
+// Get
+count();
 
-// Split a SettableState into a state and setter
-const [$count, setCount] = $($$count);
+// Set
+count(52);
 ```
 
 ---
@@ -112,10 +444,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.

package/package.json

@@ -1,14 +1,17 @@
 {
   "name": "@manyducks.co/dolla",
-  "version": "2.0.0-alpha.9",
-  "description": "Front-end components, routing and state management.",
+  "version": "2.0.0",
+  "description": "A fast, batteries-included JavaScript framework with a React-like API and the power of Signals.",
   "main": "dist/index.js",
-  "types": "dist/index.d.ts",
+  "types": "dist/core/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",
+    "test": "vitest",
     "build:esbuild": "tsc && node build.js",
     "build": "vite build && tsc",
     "start": "tsc --watch",
@@ -25,7 +28,19 @@
   "exports": {
     ".": {
       "import": "./dist/index.js",
-      "types": "./index.d.ts"
+      "types": "./dist/core/index.d.ts"
+    },
+    "./router": {
+      "import": "./dist/router.js",
+      "types": "./dist/router/index.d.ts"
+    },
+    "./http": {
+      "import": "./dist/http.js",
+      "types": "./dist/http/index.d.ts"
+    },
+    "./i18n": {
+      "import": "./dist/i18n.js",
+      "types": "./dist/i18n/index.d.ts"
     },
     "./jsx-runtime": {
       "import": "./dist/jsx-runtime.js",
@@ -36,16 +51,15 @@
       "types": "./jsx-dev-runtime.d.ts"
     }
   },
+  "dependencies": {
+    "alien-signals": "^2.0.5"
+  },
   "devDependencies": {
-    "@types/node": "^22.10.6",
+    "@types/node": "^24.1.0",
     "csstype": "^3.1.3",
-    "esbuild": "^0.24.2",
-    "history": "^5.3.0",
-    "htm": "^3.1.1",
-    "nanoid": "^5.0.9",
-    "prettier": "^3.4.2",
-    "simple-color-hash": "^1.0.2",
-    "typescript": "^5.7.3",
-    "vite": "^6.0.7"
+    "prettier": "^3.6.2",
+    "typescript": "^5.8.3",
+    "vite": "^7.0.6",
+    "vitest": "^3.2.4"
   }
 }

package/vite.config.js

@@ -3,26 +3,20 @@ import { defineConfig } from "vite";
 
 export default defineConfig({
   build: {
-    // minify: "terser",
-    // minify: false,
     sourcemap: true,
+    minify: true,
 
     lib: {
       entry: {
-        index: resolve(__dirname, "src/index.ts"),
+        index: resolve(__dirname, "src/core/index.ts"),
+        http: resolve(__dirname, "src/http/index.ts"),
+        i18n: resolve(__dirname, "src/i18n/index.ts"),
+        router: resolve(__dirname, "src/router/index.ts"),
         "jsx-runtime": resolve(__dirname, "src/jsx-runtime.js"),
         "jsx-dev-runtime": resolve(__dirname, "src/jsx-dev-runtime.js"),
       },
       name: "Dolla",
       formats: ["es"],
     },
-    // rollupOptions: {
-    //   external: ["vue"],
-    //   output: {
-    //     globals: {
-    //       vue: "Vue",
-    //     },
-    //   },
-    // },
   },
 });

package/build.js

@@ -1,34 +0,0 @@
-import fs from "node:fs";
-import esbuild from "esbuild";
-
-esbuild
-  .build({
-    entryPoints: ["src/index.ts"],
-    bundle: true,
-    metafile: true,
-    sourcemap: true,
-    // minify: process.env.NODE_ENV === "production",
-    outdir: "dist",
-    format: "esm",
-  })
-  .then((result) => {
-    fs.writeFileSync("esbuild-meta.json", JSON.stringify(result.metafile));
-  });
-
-esbuild.build({
-  entryPoints: ["src/jsx-runtime.js"],
-  bundle: false,
-  minify: false,
-  sourcemap: true,
-  outdir: "dist",
-  format: "esm",
-});
-
-esbuild.build({
-  entryPoints: ["src/jsx-dev-runtime.js"],
-  bundle: false,
-  minify: false,
-  sourcemap: true,
-  outdir: "dist",
-  format: "esm",
-});

package/dist/index.d.ts

@@ -1,21 +0,0 @@
-export { createSettableState, createSetter, createState, derive, toSettableState, toState, valueOf } from "./state.js";
-export type { MaybeState, SettableState, State, StopFunction } from "./state.js";
-export { cond, createMarkup, createRef, html, isRef, portal, repeat } from "./markup.js";
-export type { Markup, MarkupNode, Ref } from "./markup.js";
-import { Dolla } from "./modules/dolla.js";
-declare const dolla: Dolla;
-export default dolla;
-export declare const t: (key: string, values?: Record<string, import("./types.js").Stringable | import("./state.js").State<import("./types.js").Stringable>>) => import("./state.js").State<string>;
-export type { Dolla, Environment, Logger, LoggerErrorContext, LoggerOptions, Loggles } from "./modules/dolla.js";
-export type { HTTPRequest, HTTPResponse } from "./modules/http.js";
-export type { InputType, Renderable } from "./types.js";
-export type { ViewContext, ViewFunction, ViewNode } from "./view.js";
-export type { CrashViewProps } from "./views/default-crash-view.js";
-import type { IntrinsicElements as Elements } from "./types";
-declare global {
-    namespace JSX {
-        interface IntrinsicElements extends Elements {
-            [tag: string]: any;
-        }
-    }
-}

package/dist/markup.d.ts

@@ -1,108 +0,0 @@
-import type { Dolla } from "./modules/dolla.js";
-import { MaybeState, type State } from "./state.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;
-    /**
-     * Storage for context variables.
-     */
-    data: Record<string | symbol, unknown>;
-    /**
-     * A reference to the parent context.
-     */
-    parent?: ElementContext;
-    /**
-     * 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: MaybeState<Stringable>;
-    };
-    $cond: {
-        $predicate: State<any>;
-        thenContent?: Renderable;
-        elseContent?: Renderable;
-    };
-    $repeat: {
-        $items: State<any[]>;
-        keyFn: (value: any, index: number) => string | number | symbol;
-        renderFn: ($item: State<any>, $index: State<number>, c: ViewContext) => ViewResult;
-    };
-    $observer: {
-        states: State<any>[];
-        renderFn: (...items: any) => Renderable;
-    };
-    $outlet: {
-        $children: State<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: MaybeState<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: MaybeState<T[]>, keyFn: (value: T, index: number) => string | number | symbol, renderFn: ($value: State<T>, $index: State<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 State 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 State<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;