@manyducks.co/dolla 2.0.0-alpha.41 → 2.0.0-alpha.42

package/README.md

@@ -40,22 +40,87 @@ import Dolla, { atom, html } from "@manyducks.co/dolla";
 function Counter() {
   const count = atom(0);
 
+  this.effect(() => {
+    console.log(`Count is: ${count.get()}`);
+  });
+
+  function increment() {
+    count.set(count.get() + 1);
+  }
+
+  function decrement() {
+    // alternative to `set(get() - 1)`
+    count.update((value) => value - 1);
+  }
+
   return html`
     <div>
       <p>Counter: ${count}</p>
       <div>
-        <button onclick=${() => count.value--}>-1</button>
-        <button onclick=${() => count.value++}>+1</button>
+        <button onclick=${increment}>+1</button>
+        <button onclick=${decrement}>-1</button>
       </div>
     </div>
   `;
-});
+}
 
 Dolla.mount(document.body, Counter);
 ```
 
 > TODO: Show small examples for routing and stores.
 
+```js
+function MessageStore() {
+  const message = atom("message", "Hello world!");
+
+  this.effect(() => {
+    this.log(`Message is now: ${get(message)}`);
+    // Calling `get()` inside an effect (or compose) function will track that reactive value as a dependency.
+    // Effects will re-run when a dependency updates.
+  });
+  // `this` refers to the context object; StoreContext in a store and ViewContext in a view.
+  // Context objects contain methods for controlling the component, logging and attaching lifecycle hooks.
+
+  return {
+    message: compose("message:readonly", () => get(message)),
+    // Creates a read-only reactive of the message value.
+    // Composed values update when their dependencies update.
+
+    setMessage: set(message),
+    // Creates a setter function to update the original message atom.
+  };
+}
+
+function App() {
+  const { message, setMessage } = this.provide(MessageStore);
+  // Provides a MessageStore on this context and any child contexts.
+  // When a store is provided its value is returned right away.
+
+  return html`
+    <div>
+      <${MessageView} />
+      <${MessageView} />
+      <${MessageView} />
+
+      <input
+        type="text"
+        value=${message}
+        oninput=${(e) => {
+          setMessage(e.currentTarget.value);
+        }}
+      />
+    </div>
+  `;
+}
+
+function MessageView() {
+  const { message } = this.get(MessageStore);
+  // Gets the nearest instance of MessageStore. In this case the one provided at the parent.
+
+  return html`<span>${message}</span>`;
+}
+```
+
 For more detail [check out the Docs](./docs/index.md).
 
 ---

package/dist/core/markup.d.ts

@@ -24,7 +24,7 @@ export interface Markup {
  * A DOM node that has been constructed from a Markup object.
  */
 export interface MarkupElement {
-    readonly node?: Node;
+    readonly domNode?: Node;
     readonly isMounted: boolean;
     mount(parent: Node, after?: Node): void;
     /**

package/dist/core/nodes/dom.d.ts

@@ -5,7 +5,7 @@ import { IS_MARKUP_ELEMENT } from "../symbols";
  */
 export declare class DOMNode implements MarkupElement {
     [IS_MARKUP_ELEMENT]: boolean;
-    node: Node;
+    domNode: Node;
     get isMounted(): boolean;
     constructor(node: Node);
     mount(parent: Node, after?: Node): void;

package/dist/core/nodes/dynamic.d.ts

@@ -13,7 +13,7 @@ interface DynamicOptions {
  */
 export declare class Dynamic implements MarkupElement {
     [IS_MARKUP_ELEMENT]: boolean;
-    node: Text;
+    domNode: Text;
     private children;
     private elementContext;
     private source;

package/dist/core/nodes/html.d.ts

@@ -9,7 +9,7 @@ type HTMLOptions = {
 };
 export declare class HTML implements MarkupElement {
     [IS_MARKUP_ELEMENT]: boolean;
-    node: HTMLElement | SVGElement;
+    domNode: HTMLElement | SVGElement;
     private props;
     private childMarkup;
     private children;

package/dist/core/nodes/list.d.ts

@@ -11,7 +11,7 @@ interface ListOptions<T> {
 }
 export declare class List<T> implements MarkupElement {
     [IS_MARKUP_ELEMENT]: boolean;
-    node: Text;
+    domNode: Text;
     private items;
     private unsubscribe;
     private connectedItems;

package/dist/core/nodes/outlet.d.ts

@@ -6,7 +6,7 @@ import { IS_MARKUP_ELEMENT } from "../symbols.js";
  */
 export declare class Outlet implements MarkupElement {
     [IS_MARKUP_ELEMENT]: boolean;
-    node: Text;
+    domNode: Text;
     isMounted: boolean;
     private source;
     private elements;

package/dist/core/nodes/view.d.ts

@@ -69,7 +69,7 @@ export declare class View<P> implements ViewElement {
         unmount: (() => any)[];
     };
     constructor(elementContext: ElementContext, fn: ViewFunction<P>, props: P, children?: Markup[]);
-    get node(): Node;
+    get domNode(): Node;
     isMounted: boolean;
     mount(parent: Node, after?: Node): void;
     unmount(parentIsUnmounting?: boolean): void;

package/dist/core/signals.d.ts

@@ -13,8 +13,21 @@ export interface Signal<T = any> extends Dependency {
  * A readable reactive state object.
  */
 export interface Reactive<T> {
+    /**
+     * A name provided at the creation of this reactive.
+     */
+    readonly name?: string;
+    /**
+     * Returns the current value. Tracks this reactive as a dependency if called within `effect` or `compose`.
+     */
+    get(): T;
+    /**
+     * Returns the current value without tracking this reactive as a dependency when called within `effect` or `compose`.
+     */
+    peek(): T;
     /**
      * The current value.
+     * @deprecated use `get()` and `set()`
      */
     readonly value: T;
 }
@@ -38,9 +51,64 @@ export interface ReactiveOptions<T> {
 }
 export declare class Atom<T> implements Reactive<T> {
     #private;
-    name?: string;
-    constructor(signal: Signal<T>, options?: ReactiveOptions<T>);
+    readonly name?: string;
+    constructor(value: T, options?: ReactiveOptions<T>);
+    /**
+     * Returns the latest value. The signal is tracked as a dependency if called within `effect` or `compose`.
+     */
+    get(): T;
+    /**
+     * Returns the latest value. The signal is NOT tracked if called within `effect` or `compose`.
+     */
+    peek(): T;
+    /**
+     * Replaces the current value with `next`.
+     *
+     * @example
+     * const count = atom(0);
+     * count.set(2);
+     * count.set(count.get() + 1);
+     */
+    set(next: T): void;
+    /**
+     * Passes the current value to `fn` and sets the return value as the next value.
+     *
+     * @example
+     * const count = atom(0);
+     * count.update((current) => current + 1);
+     * count.update((current) => current * 5);
+     *
+     * // Also works very well with Immer `produce` for complex objects.
+     * const items = atom([{ name: "Alice", age: 26 }, { name: "Bob", age: 33 }]);
+     *
+     * // Without Immer:
+     * items.update((current) => {
+     *   // Return a new array with Bob's age increased by 1.
+     *   const newItems = [...current];
+     *   newItems[1] = {
+     *     ...newItems[1],
+     *     age: newItems[1].age + 1
+     *   };
+     *   return newItems;
+     * });
+     *
+     * // With Immer:
+     * import { produce } from "immer";
+     *
+     * items.update(produce((draft) => {
+     *   // Mutate draft to increase Bob's age by 1.
+     *   // Results in a new object with this patch applied.
+     *   draft[1].age++;
+     * }));
+     */
+    update(fn: (current: T) => T): void;
+    /**
+     * @deprecated use `get()`
+     */
     get value(): T;
+    /**
+     * @deprecated use `set()`
+     */
     set value(next: T);
 }
 /**
@@ -52,9 +120,9 @@ export declare function isReactive<T>(value: any): value is Reactive<T>;
  * Atom values can be read and updated with the `value` property
  *
  * @example
- * const count = atom(1);
- * count.value++;
- * count.value; // 2
+ * const count = atom<number>();
+ * count.set(5);
+ * count.get(); // 5
  */
 export declare function atom<T>(): Atom<T | undefined>;
 /**
@@ -63,8 +131,8 @@ export declare function atom<T>(): Atom<T | undefined>;
  *
  * @example
  * const count = atom(1);
- * count.value++;
- * count.value; // 2
+ * count.set(count.get() + 1);
+ * count.get(); // 2
  */
 export declare function atom<T>(value: T, options?: ReactiveOptions<T>): Atom<T>;
 /**
@@ -83,7 +151,7 @@ type ComposeCallback<T> = (previousValue?: T) => MaybeReactive<T>;
  *
  * @example
  * const count = atom(1);
- * const doubled = compose(() => get(count) * 2);
+ * const doubled = compose(() => count.get() * 2);
  */
 export declare function compose<T>(fn: ComposeCallback<T>, options?: ReactiveOptions<T>): Reactive<T>;
 /**
@@ -115,6 +183,10 @@ export declare function get<T>(value: MaybeReactive<T>): T;
  * });
  */
 export declare function peek<T>(value: MaybeReactive<T>): T;
+/**
+ * Registers a callback that will receive a list of dependencies that were tracked within the scope this function was called in.
+ */
+export declare function getTracked(fn: (tracked: Reactive<unknown>[]) => void): void;
 export type EffectCallback = () => void;
 /**
  * Creates a tracked scope that re-runs whenever the values of any tracked reactives changes.

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { atom, compose, effect, get, set, peek } from "./core/signals.js";
+export { atom, compose, effect, get, set, peek, getTracked } from "./core/signals.js";
 export type { Reactive, MaybeReactive, Atom } from "./core/signals.js";
 export { deepEqual, shallowEqual, strictEqual } from "./utils.js";
 export { ref, type Ref } from "./core/ref.js";