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

package/dist/core/state.d.ts

@@ -0,0 +1,126 @@
+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

@@ -0,0 +1,31 @@
+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 {};

package/dist/core/store.d.ts

@@ -0,0 +1,62 @@
+import { Emitter } from "@manyducks.co/emitter";
+import { type WildcardListenerMap, type ComponentContext, type ElementContext } from "./context.js";
+import type { Logger } from "./dolla.js";
+import { type MaybeState, type StateValues, type StopFunction } from "./state.js";
+export type StoreFunction<Options, Value> = (this: StoreContext, options: Options, context: StoreContext) => Value;
+export type StoreFactory<Options, Value> = Options extends undefined ? () => Store<Options, Value> : (options: Options) => Store<Options, Value>;
+export interface StoreContext extends Logger, ComponentContext {
+    /**
+     * True while this store is attached to a context that is currently mounted in the view tree.
+     */
+    readonly isMounted: boolean;
+    /**
+     * Registers a callback to run just after this store is mounted.
+     */
+    onMount(callback: () => void): void;
+    /**
+     * Registers a callback to run just after this store is unmounted.
+     */
+    onUnmount(callback: () => void): void;
+    /**
+     * Watch a set of states. The callback is called when any of the states receive a new value.
+     * Watchers will be automatically stopped when this store is unmounted.
+     */
+    watch<T extends MaybeState<any>[]>(states: [...T], callback: (...values: StateValues<T>) => void): StopFunction;
+}
+type StoreEvents = {
+    mounted: [];
+    unmounted: [];
+};
+export declare class Store<Options, Value> {
+    readonly key: string;
+    private _fn;
+    private _options;
+    /**
+     * Value is guaranteed to be set after `attach` is called.
+     */
+    value: Value;
+    isMounted: boolean;
+    _elementContext: ElementContext;
+    _emitter: Emitter<StoreEvents>;
+    _wildcardListeners: WildcardListenerMap;
+    _logger: Logger;
+    _watcher: import("./state.js").StateWatcher;
+    get name(): string;
+    constructor(key: string, fn: StoreFunction<Options, Value>, options: Options);
+    /**
+     * Attaches this Store to the elementContext.
+     * Returns false if there was already an instance attached, and true otherwise.
+     */
+    attach(elementContext: ElementContext): boolean;
+    handleMount(): void;
+    handleUnmount(): void;
+}
+export declare function isStoreFactory<Options, Value>(value: any): value is StoreFactory<Options, Value>;
+export declare function isStore<Options, Value>(value: any): value is Store<Options, Value>;
+/**
+ * Defines a new store.
+ */
+export declare function createStore<Options = undefined, Value = unknown>(fn: StoreFunction<Options, Value>): StoreFactory<Options, Value>;
+export declare class StoreError extends Error {
+}
+export {};

package/dist/core/symbols.d.ts

@@ -0,0 +1,7 @@
+export declare const IS_STATE: unique symbol;
+export declare const IS_REF: unique symbol;
+export declare const IS_MARKUP: unique symbol;
+export declare const IS_MARKUP_ELEMENT: unique symbol;
+export declare const IS_STORE: unique symbol;
+export declare const IS_STORE_FACTORY: unique symbol;
+export declare const IS_ROUTER: unique symbol;

package/dist/index.d.ts

@@ -1,15 +1,23 @@
-export { createSettableSignal, createSignal, createSignalSetter, derive, designalify, signalify, toSettableSignal, watch, } from "./signals.js";
-export type { MaybeSignal, SettableSignal, Signal, StopFunction } from "./signals.js";
-import { Dolla } from "./modules/dolla.js";
+export { createState, derive, isState, toState, toValue } from "./core/state.js";
+export type { MaybeState, Setter, State, StopFunction } from "./core/state.js";
+export { createRef, isRef, type Ref } from "./core/ref.js";
+export { createStore, type Store, type StoreFactory, type StoreFunction } from "./core/store.js";
+export { createRouter, type Router, type RouterOptions } from "./modules/router.js";
+export { deepEqual, shallowEqual, strictEqual } from "./utils.js";
+export { cond, createMarkup, html, portal, repeat } from "./core/markup.js";
+export type { Markup, MarkupElement } from "./core/markup.js";
+export { createView } from "./core/nodes/view.js";
+import { Dolla } from "./core/dolla.js";
 declare const dolla: Dolla;
-export declare const t: (key: string, values?: Record<string, import("./types.js").Stringable | import("./signals.js").Signal<import("./types.js").Stringable>> | undefined) => import("./signals.js").Signal<string>;
-export { html, cond, createMarkup, portal, repeat, createRef, isRef } from "./markup.js";
-export type { Markup, MarkupNode, Ref } from "./markup.js";
-export type { ViewFunction, ViewContext, ViewNode } from "./view.js";
-export type { CrashViewProps } from "./views/default-crash-view.js";
-export type { InputType, Renderable } from "./types.js";
-export type { Environment } from "./modules/dolla.js";
+export default dolla;
+export declare const t: (selector: string, options?: import("./modules/i18n.js").TOptions) => import("./core/state.js").State<string>;
+export declare function setDevDebug(value: boolean): void;
+export declare function getDevDebug(): boolean;
+export type { Dolla, Environment, Logger, LoggerErrorContext, LoggerOptions, Loggles } from "./core/dolla.js";
+export type { ViewContext, ViewElement, ViewFunction } from "./core/nodes/view.js";
 export type { HTTPRequest, HTTPResponse } from "./modules/http.js";
+export type { InputType, Renderable } from "./types.js";
+export type { CrashViewProps } from "./views/default-crash-view.js";
 import type { IntrinsicElements as Elements } from "./types";
 declare global {
     namespace JSX {
@@ -18,4 +26,3 @@ declare global {
         }
     }
 }
-export default dolla;