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

package/dist/typeChecking.d.ts

@@ -1,191 +0,0 @@
-type TypeNames = "string" | "number" | "bigint" | "boolean" | "symbol" | "undefined" | "object" | "function" | "null" | "array" | "class" | "promise" | "NaN";
-/**
- * Extends `typeof` operator with more specific and useful type distinctions.
- */
-export declare function typeOf(value: unknown): TypeNames;
-/**
- * Throws a TypeError unless `condition` is truthy.
- *
- * @param condition - Value whose truthiness is in question.
- * @param errorMessage - Optional message for the thrown TypeError.
- */
-export declare function assert(condition: any, errorMessage?: string): void;
-/**
- * Returns true if `value` is an array.
- */
-export declare function isArray(value: unknown): value is Array<unknown>;
-/**
- * Throws an error if `value` is not an array.
- */
-export declare function assertArray(value: unknown, errorMessage?: string): value is Array<unknown>;
-/**
- * Returns a function that takes a `value` and ensures that it is an array for which `check` returns true for every item.
- *
- * @param check - Function to check items against.
- */
-export declare function isArrayOf<T>(check: (item: unknown) => boolean): (value: unknown) => value is T[];
-/**
- * Returns true when `value` is an array and `check` returns true for every item.
- *
- * @param check - Function to check items against.
- * @param value - A possible array.
- */
-export declare function isArrayOf<T>(check: (item: unknown) => boolean, value: unknown): value is T[];
-/**
- * Returns a function that takes a `value` and throws a TypeError unless it is an array for which `check` returns true for every item.
- *
- * @param check - Function to check items against.
- */
-export declare function assertArrayOf<T>(check: (item: unknown) => boolean): (value: unknown) => value is T[];
-/**
- * Throws a TypeError unless `value` is an array and `check` returns true for every item.
- *
- * @param check - Function to check items against.
- * @param value - A possible array.
- * @param errorMessage - A custom error message.
- */
-export declare function assertArrayOf<T>(check: (item: unknown) => boolean, value: unknown, errorMessage?: string): value is T[];
-/**
- * Returns true if `value` is equal to `true` or `false`.
- */
-export declare function isBoolean(value: unknown): value is boolean;
-/**
- * Throws a TypeError unless `value` is equal to `true` or `false`.
- */
-export declare function assertBoolean(value: unknown, errorMessage?: string): value is boolean;
-/**
- * Returns true if `value` is a string.
- */
-export declare function isString(value: unknown): value is string;
-/**
- * Throws a TypeError unless `value` is a string.
- */
-export declare function assertString(value: unknown, errorMessage?: string): value is string;
-/**
- * Returns true if `value` is a function (but not a class).
- */
-export declare function isFunction<T = (...args: unknown[]) => unknown>(value: unknown): value is T;
-/**
- * Throws a TypeError unless `value` is a function.
- */
-export declare function assertFunction<T = (...args: unknown[]) => unknown>(value: unknown, errorMessage?: string): value is T;
-/**
- * Returns true if `value` is a number.
- */
-export declare function isNumber(value: unknown): value is number;
-/**
- * Throws a TypeError unless `value` is a number.
- */
-export declare function assertNumber(value: unknown, errorMessage?: string): value is number;
-/**
- * Returns true if `value` implements the Promise protocol.
- * This matches true instances of Promise as well as any object that
- * implements `next`, `catch` and `finally` methods.
- *
- * To strictly match instances of Promise, use `isInstanceOf(Promise)`.
- */
-export declare function isPromise<T = unknown>(value: unknown): value is Promise<T>;
-/**
- * Throws a TypeError unless `value` implements the Promise protocol.
- * This matches true instances of Promise as well as any object that
- * implements `next`, `catch` and `finally` methods.
- *
- * To strictly allow only instances of Promise, use `Type.assertInstanceOf(Promise)`.
- */
-export declare function assertPromise<T = unknown>(value: unknown, errorMessage?: string): value is Promise<T>;
-/**
- * Returns true if `value` is a class.
- */
-export declare function isClass(value: unknown): value is {
-    new (): unknown;
-};
-/**
- * Throws a TypeError unless `value` is a class.
- */
-export declare function assertClass(value: unknown, errorMessage?: string): value is {
-    new (): unknown;
-};
-/**
- * Returns a function that takes a `value` and returns true if `value` is an instance of `constructor`.
- *
- * @param constructor - The constructor a value must be an instance of to match.
- */
-export declare function isInstanceOf<T extends Function>(constructor: T): (value: unknown) => value is T;
-/**
- * Returns `true` if `value` is an instance of `constructor`.
- *
- * @param constructor - The constructor `value` must be an instance of.
- * @param value - A value that may be an instance of `constructor`.
- */
-export declare function isInstanceOf<T extends Function>(constructor: T, value: unknown): value is T;
-/**
- * Returns a function that takes a `value` and throws a TypeError unless `value` is an instance of `constructor`.
- *
- * @param constructor - The constructor a value must be an instance of to match.
- */
-export declare function assertInstanceOf<T extends Function>(constructor: T): (value: unknown) => value is T;
-/**
- * Throws a TypeError unless `value` is an instance of `constructor`.
- *
- * @param constructor - The constructor `value` must be an instance of.
- * @param value - A value that may be an instance of `constructor`.
- * @param errorMessage - A custom error message for when the assertion fails.
- */
-export declare function assertInstanceOf<T extends Function>(constructor: T, value: unknown, errorMessage?: string): value is T;
-/**
- * Returns true if `value` is a Map.
- */
-export declare function isMap<K = unknown, V = unknown>(value: any): value is Map<K, V>;
-/**
- * Throws a TypeError unless `value` is a Map.
- */
-export declare function assertMap<K = unknown, V = unknown>(value: any, errorMessage?: string): value is Map<K, V>;
-/**
- * Returns true if `value` is a Set.
- */
-export declare function isSet<T = unknown>(value: any): value is Set<T>;
-/**
- * Throws a TypeError if `value` is not a Set.
- */
-export declare function assertSet<T = unknown>(value: any, errorMessage?: string): value is Set<T>;
-/**
- * Returns true if `value` implements the Iterable protocol.
- */
-export declare function isIterable<T>(value: any): value is Iterable<T>;
-/**
- * Throws a TypeError unless `value` implements the Iterable protocol.
- */
-export declare function assertIterable<T>(value: any, errorMessage?: string): value is Iterable<T>;
-/**
- * Returns true if `value` is a plain JavaScript object.
- */
-export declare function isObject(value: unknown): value is Record<string | number | symbol, unknown>;
-/**
- * Throws a TypeError unless `value` is a plain JavaScript object.
- */
-export declare function assertObject(value: unknown, errorMessage?: string): value is object;
-/**
- * Returns true if `value` is equal to `null`.
- */
-export declare function isNull(value: unknown): value is null;
-/**
- * Throws a TypeError unless `value` is equal to `null`.
- */
-export declare function assertNull(value: unknown, errorMessage?: string): value is null;
-/**
- * Returns true if `value` is equal to `undefined`.
- */
-export declare function isUndefined(value: unknown): value is undefined;
-/**
- * Throws a TypeError unless `value` is equal to `undefined`.
- */
-export declare function assertUndefined(value: unknown, errorMessage?: string): value is undefined;
-/**
- * Returns true if `value` is equal to `null` or `undefined`.
- */
-export declare function isEmpty(value: unknown): value is void;
-/**
- * Throws a TypeError unless `value` is equal to `null` or `undefined`.
- */
-export declare function assertEmpty(value: unknown, errorMessage?: string): value is void;
-export {};

package/dist/view.d.ts

@@ -1,65 +0,0 @@
-import { type MarkupNode, type ElementContext, type Markup } from "./markup.js";
-import type { Logger } from "./modules/dolla.js";
-import { type MaybeState, State, type StateValues, type StopFunction } from "./state.js";
-/**
- * Any valid value that a View can return.
- */
-export type ViewResult = Node | State<any> | Markup | Markup[] | null;
-export type ViewFunction<P> = (props: P, context: ViewContext) => ViewResult;
-/**
- * A view that has been constructed into DOM nodes.
- */
-export interface ViewNode extends MarkupNode {
-    /**
-     * Take a ViewFunction and render it as a child of this view.
-     */
-    setChildView(view: ViewFunction<{}>): ViewNode;
-}
-export interface ViewContext extends Logger {
-    /**
-     * A string ID unique to this view.
-     */
-    readonly uid: string;
-    /**
-     * Sets a context variable. Context variables are accessible on the same context and from those of child views.
-     */
-    set<T>(key: string | symbol, value: T): void;
-    /**
-     * Gets the value of a context variable. Returns null if the variable is not set.
-     */
-    get<T>(key: string | symbol): T | null;
-    /**
-     * Returns an object of all variables stored on this context.
-     */
-    getAll(): Record<string | symbol, unknown>;
-    /**
-     * Sets the name of the view's built in logger.
-     */
-    setName(name: string): void;
-    /**
-     * Registers a callback to run just before this view is mounted. DOM nodes are not yet attached to the page.
-     */
-    beforeMount(callback: () => void): void;
-    /**
-     * Registers a callback to run just after this view is mounted.
-     */
-    onMount(callback: () => void): void;
-    /**
-     * Registers a callback to run just before this view is unmounted. DOM nodes are still attached to the page.
-     */
-    beforeUnmount(callback: () => void): void;
-    /**
-     * Registers a callback to run just after this view 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 view is unmounted.
-     */
-    watch<T extends MaybeState<any>[]>(states: [...T], callback: (...values: StateValues<T>) => void): StopFunction;
-    /**
-     * Returns a Markup element that displays this view's children.
-     */
-    outlet(): Markup;
-}
-export declare function constructView<P>(elementContext: ElementContext, view: ViewFunction<P>, props: P, children?: Markup[]): ViewNode;

package/dist/views/default-crash-view.d.ts

@@ -1,18 +0,0 @@
-/**
- * Props passed to the crash view when a crash occurs.
- */
-export type CrashViewProps = {
-    /**
-     * JavaScript Error object.
-     */
-    error: Error;
-    /**
-     * A string to identify the logger that reported this error.
-     */
-    loggerName: string;
-    /**
-     * Unique identifier to pinpoint the specific view that reported the crash.
-     */
-    uid?: string;
-};
-export declare function DefaultCrashView(props: CrashViewProps): import("../markup.js").Markup | import("../markup.js").Markup[];

package/dist/views/passthrough.d.ts

@@ -1,5 +0,0 @@
-import { type ViewContext } from "../view.js";
-/**
- * A utility view that simply displays its children.
- */
-export declare function Passthrough(_: {}, ctx: ViewContext): import("../markup.js").Markup;

package/notes/context-vars.md

@@ -1,21 +0,0 @@
-# Idea: Context Variables
-
-In designing how Dolla's version of 'context' works, I've been going through a few different ideas. The simplest seems to be the ability to store _context variables_ that, once set, are accessible on the same context or any child context.
-
-```js
-function SomeView(props, ctx) {
-  ctx.set("key", 5);
-
-  // ... and in a child view do
-  ctx.get("key");
-  // which returns null if the value isn't present.
-  // It's like localStorage for the view tree.
-}
-```
-
-They can be typed, but always with a possibility to return null.
-
-```js
-const value = ctx.get<number>("key");
-// value is number | null to force the programmer to check it.
-```

package/notes/readme-scratch.md

@@ -1,222 +0,0 @@
-# README
-
-> This note will eventually become the new README. Here I'm laying out my ideal framework API.
-
-A basic component.
-
-```jsx
-import Dolla, { createState, derive } from "@manyducks.co/dolla";
-
-function ExampleView(props, ctx) {
-  const [$count, setCount] = createState(5);
-  const $doubled = derive([$count], (n) => n * 2);
-
-  ctx.watch([$count], (count) => {
-    ctx.log("value of count is now %n", count);
-  });
-
-  return <p>{$count}</p>;
-}
-
-Dolla.mount(document.body, ExampleView);
-```
-
-<details open>
-<summary>
-  <h2>Signals API</h2>
-</summary>
-
-The signals API. Dolla's signals use explicit tracking, meaning any function where signal values are tracked take an array of the signals you want to track. This way you know exactly what depends on what at a glance without any kind of hidden tracking logic behind the scenes. You are free to `.get()` the value of a signal without worrying about untracking it first.
-
-```jsx
-import { createState } from "@manyducks.co/dolla";
-
-const [$count, setCount] = createState(256);
-
-$count.get(); // 256; returns the current value
-
-const stop = $count.watch((value) => {
-  // Runs once immediately, then again whenever the value changes.
-});
-
-setCount(512); // Update the value of $count. The new value is set and all watchers run synchronously.
-
-stop(); // Stop watching for changes.
-```
-
-That is the basic signal API. Signals are all about composability. Here are some more advanced ways of working with them:
-
-```jsx
-import { createState, toState, valueOf, derive } from "@manyducks.co/dolla";
-
-const [$count, setCount] = createState(72);
-
-// Returns the value of the signal passed in. If the value is not a signal it is returned as is.
-const count = valueOf($count);
-const bool = valueOf(true);
-
-// Creates a signal containing the value passed in. If the value is already a signal it is returned as is.
-const $bool = toState(true);
-const $anotherCount = toState($count);
-
-// Derive a new signal from the value of another. Whenever $count changes, $doubled will follow.
-const $doubled = derive([$count], (count) => count * 2);
-
-// Derive a new signal from the values of several others. When any value in the list changes, $sum will be recomputed.
-const $sum = derive([$count, $doubled], (count, doubled) => count + doubled);
-```
-
-The API if we call it State instead of Signal to distance from the Signal object in standardization process.
-
-```jsx
-import { createState, toState, valueOf, derive } from "@manyducks.co/dolla";
-
-const [$count, setCount] = createState(72);
-
-// Returns the value of the signal passed in. If the value is not a signal it is returned as is.
-const count = valueOf($count);
-const bool = valueOf(true);
-
-// Creates a signal containing the value passed in. If the value is already a signal it is returned as is.
-const $bool = toState(true);
-const $anotherCount = toState($count);
-
-// Derive a new signal from the value of another. Whenever $count changes, $doubled will follow.
-const $doubled = derive([$count], (count) => count * 2);
-
-// Derive a new signal from the values of several others. When any value in the list changes, $sum will be recomputed.
-const $sum = derive([$count, $doubled], (count, doubled) => count + doubled);
-```
-
-States also come in a settable variety, with the setter included on the same object. Sometimes you want to pass around a two-way binding and this is what SettableState is for.
-
-```jsx
-import { createSettableState, fromSettable, toSettable } from "@manyducks.co/dolla";
-
-// Settable states have their setter included.
-const $$value = createSettableState("Test");
-$$value.set("New Value");
-
-// They can also be split into a State and Setter
-const [$value, setValue] = fromSettableState($$value);
-
-// And a State and Setter can be combined into a SettableState.
-const $$otherValue = toSettableState($value, setValue);
-
-// Or discard the setter and make it read-only using the good old toState function:
-const $value = toState($$value);
-```
-
-Alternative API
-
-```jsx
-import { State } from "@manyducks.co/dolla";
-
-const [$count, setCount] = State(72);
-
-const count = State.unwrap($count);
-const bool = State.unwrap(true);
-
-const $bool = State.wrap(true);
-const $sameCount = State.wrap($count);
-
-const $doubled = State.from([$count], (count) => count * 2);
-
-const $sum = State.from([$count, $doubled], (count, doubled) => count + doubled);
-```
-
-Yet another
-
-```jsx
-import Dolla from "@manyducks.co/dolla";
-
-const [$count, setCount] = Dolla.state(72);
-
-const count = Dolla.get($count);
-const bool = Dolla.get(true);
-
-const $bool = Dolla.toState(true);
-const $sameCount = Dolla.toState($count);
-
-const $doubled = Dolla.computed([$count], (count) => count * 2);
-const $sum = Dolla.computed([$count, $doubled], (count, doubled) => count + doubled);
-
-// or
-
-import { state, computed, get, toState } from "@manyducks.co/dolla";
-
-const [$count, setCount] = state(72);
-
-const count = get($count);
-const bool = get(true);
-
-const $bool = toState(true);
-const $sameCount = toState($count);
-
-const $doubled = computed([$count], (count) => count * 2);
-const $sum = computed([$count, $doubled], (count, doubled) => count + doubled);
-```
-
-Settable signals:
-
-```jsx
-import { createSettableState, createSetter, toSettableSignal, fromSettableSignal } from "@manyducks.co/dolla";
-
-// Create a SettableSignal, which is basically a signal and its setter combined into a single object.
-const $$settable = createSettableState("Example");
-
-// The basic API is identical...
-$$settable.get();
-const stop = $$settable.watch((value) => {
-  // ...
-});
-stop();
-
-// ... except for the addition of a setter.
-$$settable.set("Set me directly");
-
-// When you already have a signal and a setter, they can be combined into one.
-const $$count = toSettableSignal($count, setCount);
-
-// This updates the original $signal value.
-$$count.set(386);
-
-// TODO: You can also split a SettableSignal into a signal and its setter.
-const [$readable, setReadable] = fromSettableSignal($$settable);
-
-// Create a custom setter. Calling this will cap the value to 100.
-const setCountBounded = createSetter($count, (next, current) => {
-  return Math.min(100, next);
-});
-
-setCountBounded((current) => {
-  return current + 1;
-});
-
-// Or make a proxy $$doubled -- but would you actually want to proxy things like this?
-const [$count, setCount] = createState(5);
-const $doubled = derive([$count], (count) => count * 2);
-const $$doubled = toSettableSignal(
-  $doubled,
-  createSetter($doubled, (next, current) => {
-    setCount(next * 2);
-  }),
-);
-```
-
-I'm not really sure we need all of this. On the chopping block:
-
-- The entire concept of settable signals
-  - `createSettableState`
-  - `toSettableSignal`
-  - `fromSettableSignal`
-  - `createSetter`
-
-This makes the entire API just four functions:
-
-- `createState`
-- `derive`
-- `toState`
-- `valueOf`
-
-</details>

package/notes/route-middleware.md

@@ -1,42 +0,0 @@
-# Router Middleware
-
-Allow handling route guards, preloading, etc with per-route middleware. When a route is matched, all middleware from higher layers are run again.
-
-```js
-Dolla.router.setup({
-  middleware: [/* does it make sense to have global middleware? */]
-  routes: [
-    { path: "/login", middleware: [auth] },
-    { path: "/", middleware: [auth], routes: [{ path: "/example", view: ExampleView }] }
-  ]
-});
-
-async function auth(ctx) {
-  // This check can be implemented however it needs to be for the app.
-  const authed = await isAuthorized();
-
-  if (ctx.path === "/login") {
-    if (authed) {
-      ctx.redirect("/");
-    }
-  } else {
-    if (!authed) {
-      ctx.redirect("/login");
-    }
-  }
-  // If no redirect has happened and nothing has been returned then we're clear to proceed.
-}
-
-// A middleware can also return Markup to stay on the URL but show something different.
-async function randomVisitor(ctx) {
-  if (Math.random() > 0.99) {
-    return <LuckyVisitorView />
-  }
-}
-
-// Or preload async data and set a context variable before navigating.
-async function preload(ctx) {
-  const data = await fetchData();
-  ctx.set("data", data);
-}
-```