aberdeen 1.0.12 → 1.1.0

package/README.md

@@ -11,8 +11,8 @@ Aberdeen's approach is refreshingly simple:
 - 🎩 **Simple:** Express UIs naturally in JavaScript/TypeScript, without build steps or JSX, and with a minimal amount of concepts you need to learn.
 - ⏩ **Fast:** No virtual DOM. Aberdeen intelligently updates only the minimal, necessary parts of your UI when proxied data changes.
 - 👥 **Awesome lists**: It's very easy and performant to reactively display data sorted by whatever you like.
-- 🔬 **Tiny:** Around 6KB (minimized and gzipped) and with zero runtime dependencies.
-- 🔋 **Batteries included**: Comes with client-side routing, revertible patches for optimistic user-interface updates, component-local CSS, SVG support, helper functions for transforming reactive data (mapping, partitioning, filtering, etc) and hide/unhide transition effects. No bikeshedding required!
+- 🔬 **Tiny:** Around 6KB (minimized and gzipped) for the core system. Zero runtime dependencies.
+- 🔋 **Batteries included**: Comes with browser history management, routing, revertible patches for optimistic user-interface updates, component-local CSS, SVG support, helper functions for transforming reactive data (mapping, partitioning, filtering, etc) and hide/unhide transition effects. No bikeshedding required!
 
 ## Why *not* use Aberdeen?
 
@@ -57,7 +57,7 @@ Okay, next up is a somewhat more complex app - a todo-list with the following be
 Pfew.. now let's look at the code:
 
 ```typescript
-import {$, proxy, onEach, insertCss, peek, observe, unproxy, ref} from "aberdeen";
+import {$, proxy, onEach, insertCss, peek, unproxy, ref} from "aberdeen";
 import {grow, shrink} from "aberdeen/transitions";
 
 // We'll use a simple class to store our data.
@@ -172,6 +172,40 @@ Some further examples:
 
 And you may want to study the examples above, of course!
 
-## News
+## Changelog
 
-- **2025-05-07**: After five years of working on this library on and off, I'm finally happy with its API and the developer experience it offers. I'm calling it 1.0! To celebrate, I've created some pretty fancy (if I may say so myself) interactive documentation and a tutorial.
+### 1.1.0 (2024-09-12)
+
+This major release aims to reduce surprises in our API, aligning more closely with regular JavaScript semantics (for better or worse).
+
+**Breaking changes:**
+
+- Functions that iterate objects (like `onEach` and `map`) will now only work on *own* properties of the object, ignoring those in the prototype chain. The new behavior should be more consistent and faster. 
+- These iteration function now properly distinguish between `undefined` and *empty*. Previously, object/array/map items with `undefined` values were considered non-existent. The new behavior (though arguably confusing) is more consistent with regular JavaScript semantics.
+- The `copy` function no longer ..
+    - Supports `SHALLOW` and `MERGE` flags. The latter has been replaced by a dedicated `merge` function. The former turned out not to be particularly useful.
+    - Has weird special cases that would allow copying objects into maps and merging objects into arrays.
+    - Copies properties from the prototype chain of objects. Only *own* properties are copied now. As the prototype link itself *is* copied over, this should actually result in copies being *more* similar to the original.
+- The `observe` function has been renamed to `derive` to better reflect its purpose and match terminology used in other reactive programming libraries.
+- The `$({element: myElement})` syntax for inserting existing DOM elements has been removed. Use `$(myElement)` instead.
+- The `route` API brings some significant changes. Modifying the `route` observable (which should now be accessed as `route.current`) will now always result in changing the current browser history item (URL and state, using `replaceState`), instead of using a heuristic to figure out what you probably want. Dedicated functions have been added for navigating to a new URL (`go`), back to a previous URL (`back`), and for going up in the route hierarchy (`up`). 
+- The concept of immediate observers (through the `immediateObserve` function) no longer exists. It caused unexpected behavior (for instance due to the fact that an array `pop()` in JavaScript is implemented as a delete followed by a length change, so happens in two steps that would each call immediate observers). The reason it existed was mostly to enable a pre-1.0 version of the `route` API. It turned out to be a mistake.
+
+**Enhancements:**
+
+- The `peek` function can no also accept an object and a key as argument (e.g. `peek(obj, 'myKey')`). It does the same as `peek(() => obj.myKey)`, but more concise and faster.
+- The `copy` and `merge` functions now ..
+    - Accept an optional `dstKey` argument, allowing you to assign to a specific key with `copy` semantics, and without subscribing to the key.
+    - Return a boolean indicating whether any changes were made.
+    - Are faster.
+- A new `dispatcher` module has been added. It provides a simple and type-safe way to match URL paths to handler functions, and extract parameters from the path. You can still use your own routing solution if you prefer, of course.
+- The `route` module now also has tests, making the whole project now fully covered by tests.
+
+**Fixes:**
+
+- Browser-back behavior in the `route` module had some reliability issues after page reloads.
+- The `copy` and `clone` function created Maps and Arrays with the wrong internal type. So `instanceof Array` would say yes, while `Array.isArray` would say no. JavaScript is weird.
+
+### 1.0.0 (2025-05-07)
+
+After five years of working on this library on and off, I'm finally happy with its API and the developer experience it offers. I'm calling it 1.0! To celebrate, I've created some pretty fancy (if I may say so myself) interactive documentation and a tutorial.

package/dist/aberdeen.d.ts

@@ -70,7 +70,7 @@ export declare function onEach<K extends string | number | symbol, T>(target: Re
  * is deleted from an object), the scope that called `isEmpty` will be automatically
  * scheduled for re-evaluation.
  *
- * @param proxied The observable array or object (obtained via `observe()`) to check.
+ * @param proxied The observable array or object to check.
  * @returns `true` if the array has length 0 or the object has no own enumerable properties, `false` otherwise.
  *
  * @example
@@ -113,8 +113,8 @@ export interface ValueRef<T> {
  * $('div', {text: cnt});
  * // <div>2</div>
 
- * // Or we can use it in an {@link observe} function:
- * observe(() => console.log("The count is now", cnt.value));
+ * // Or we can use it in an {@link derive} function:
+ * $(() => console.log("The count is now", cnt.value));
  * // The count is now 2
  *
  * // Adding/removing items will update the count
@@ -178,12 +178,9 @@ export declare function unproxy<T>(target: T): T;
  *
  * @param dst - The destination object/array/Map (proxied or unproxied).
  * @param src - The source object/array/Map (proxied or unproxied). It won't be modified.
- * @param flags - Bitmask controlling copy behavior:
- *   - {@link MERGE}: Performs a partial update. Properties in `dst` not present in `src` are kept.
- *     `null`/`undefined` in `src` delete properties in `dst`. Handles partial array updates via object keys.
- *   - {@link SHALLOW}: Performs a shallow copy; when an array/object of the right type doesn't exist in `dst` yet, a reference to the array/object in `src` will be made, instead of creating a copy. If the array/object already exists, it won't be replaced (by a reference), but all items will be individually checked and copied like normal, keeping changes (and therefore UI updates) to a minimum.
- * @template T - The type of the destination object.
- * @throws Error if attempting to copy an array into a non-array or vice versa (unless {@link MERGE} is set, allowing for sparse array updates).
+ * @template T - The type of the objects being copied.
+ * @returns `true` if any changes were made to `dst`, or `false` if not.
+ * @throws Error if attempting to copy an array into a non-array or vice versa.
  *
  * @example Basic Copy
  * ```typescript
@@ -191,67 +188,53 @@ export declare function unproxy<T>(target: T): T;
  * const dest = proxy({ b: { d: 3 } });
  * copy(dest, source);
  * console.log(dest); // proxy({ a: 1, b: { c: 2 } })
+ * copy(dest, 'b', { e: 4 });
+ * console.log(dest); // proxy({ a: 1, b: { e: 4 } })
  * ```
+ */
+export declare function copy<T extends object>(dst: T, src: T): boolean;
+/**
+ * Like above, but copies `src` into `dst[dstKey]`. This is useful if you're unsure if dst[dstKey]
+ * already exists (as the right type of object) or if you don't want to subscribe to dst[dstKey].
  *
- * @example Map to Object
- * ```typescript
- * const source = new Map([['x', 3], ['y', 4]]);
- * const dest = proxy({});
- * copy(dest, source);
- * console.log(dest); // proxy({ x: 3, y: 4 })
- * ```
+ * @param dstKey - Optional key in `dst` to copy into.
+ */
+export declare function copy<T extends object>(dst: T, dstKey: keyof T, src: T[typeof dstKey]): boolean;
+/**
+ * Like {@link copy}, but uses merge semantics. Properties in `dst` not present in `src` are kept.
+ * `null`/`undefined` in `src` delete properties in `dst`.
  *
- * @example Object to Map
- * ```typescript
- * const source = { x: 3, y: 4 };
- * const dest = proxy(new Map());
- * copy(dest, source);
- * console.log(dest); // proxy(Map([['x', 3], ['y', 4]]))
- * ```
+ * When the destination is an object and the source is an array, its keys are used as (sparse) array indices.
  *
- * @example MERGE
+ * @example Basic merge
  * ```typescript
  * const source = { b: { c: 99 }, d: undefined }; // d: undefined will delete
  * const dest = proxy({ a: 1, b: { x: 5 }, d: 4 });
- * copy(dest, source, MERGE);
- * console.log(dest); // proxy({ a: 1, b: { c: 99, x: 5 } })
+ * merge(dest, source);
+ * merge(dest, 'b', { y: 6 }); // merge into dest.b
+ * merge(dest, 'c', { z: 7 }); // merge.c doesn't exist yet, so it will just be assigned
+ * console.log(dest); // proxy({ a: 1, b: { c: 99, x: 5, y: 6 }, c: { z: 7 } })
  * ```
  *
- * @example Partial Array Update with MERGE
+ * @example Partial Array Merge
  * ```typescript
  * const messages = proxy(['msg1', 'msg2', 'msg3']);
  * const update = { 1: 'updated msg2' }; // Update using object key as index
- * copy(messages, update, MERGE);
+ * merge(messages, update);
  * console.log(messages); // proxy(['msg1', 'updated msg2', 'msg3'])
  * ```
  *
- * @example SHALLOW
- * ```typescript
- * const source = { nested: [1, 2] };
- * const dest = {};
- * copy(dest, source, SHALLOW);
- * dest.nested.push(3);
- * console.log(source.nested); // [1, 2, 3] (source was modified)
- * ```
  */
-export declare function copy<K, V>(dst: Map<K, V>, src: Record<K extends string | number | symbol ? K : never, V> | Partial<Record<K extends string | number | symbol ? K : never, V>>, flags?: number): void;
-export declare function copy<K, V>(dst: Map<K, V>, src: Map<K, V> | Partial<Map<K, V>>, flags?: number): void;
-export declare function copy<T extends Record<string | number | symbol, any>>(dst: T, src: Map<keyof T, T[keyof T]>, flags?: number): void;
-export declare function copy<T extends object>(dst: T, src: Partial<T>, flags?: number): void;
-/** Flag to {@link copy} causing it to use merge semantics. See {@link copy} for details. */
-export declare const MERGE = 1;
-/** Flag to {@link copy} and {@link clone} causing them to create a shallow copy (instead of the deep copy done by default).*/
-export declare const SHALLOW = 2;
+export declare function merge<T extends object>(dst: T, value: Partial<T>): boolean;
+export declare function merge<T extends object>(dst: T, dstKey: keyof T, value: Partial<T[typeof dstKey]>): boolean;
 /**
  * Clone an (optionally proxied) object or array.
  *
  * @param src The object or array to clone. If it is proxied, `clone` will subscribe to any changes to the (nested) data structure.
- * @param flags
- *   - {@link SHALLOW}: Performs a shallow clone, meaning that only the top-level array or object will be copied, while object/array values will just be references to the original data in `src`.
  * @template T - The type of the objects being copied.
- * @returns A new unproxied array or object (of the same type as `src`), containing a deep (by default) copy of `src`.
+ * @returns A new unproxied array or object (of the same type as `src`), containing a deep copy of `src`.
  */
-export declare function clone<T extends object>(src: T, flags?: number): T;
+export declare function clone<T extends object>(src: T): T;
 /**
  * Creates a reactive reference (`{ value: T }`-like object) to a specific value
  * within a proxied object or array.
@@ -301,7 +284,7 @@ export declare function ref<T extends TargetType, K extends keyof T>(target: T,
  *   - An optional HTML **tag**, something like `h1`. If present, a DOM element of that tag is created, and that element will be the *current* element for the rest of this `$` function execution.
  *   - Any number of CSS classes prefixed by `.` characters. These classes will be added to the *current* element.
  *   - Optional content **text** prefixed by a `:` character, ranging til the end of the string. This will be added as a TextNode to the *current* element.
- * - `function`: When a function (without argument nor a return value) is passed in, it will be reactively executed in its own observe scope, preserving the *current element*. So any `$()` invocations within this function will create DOM elements with our *current* element as parent. If the function reads observable data, and that data is changed later on, the function we re-execute (after side effects, such as DOM modifications through `$`, have been cleaned - see also {@link clean}).
+ * - `function`: When a function (without argument nor a return value) is passed in, it will be reactively executed in its own observer scope, preserving the *current element*. So any `$()` invocations within this function will create DOM elements with our *current* element as parent. If the function reads observable data, and that data is changed later on, the function we re-execute (after side effects, such as DOM modifications through `$`, have been cleaned - see also {@link clean}).
  * - `object`: When an object is passed in, its key-value pairs are used to modify the *current* element in the following ways...
  *   - `{<attrName>: any}`: The common case is setting the value as an HTML attribute named key. So `{placeholder: "Your name"}` would add `placeholder="Your name"` to the current HTML element.
  *   - `{<propName>: boolean}` or `{value: any}` or `{selectedIndex: number}`: If the value is a boolean, or if the key is `value` or `selectedIndex`, it is set on the `current` element as a DOM property instead of an HTML attribute. For example `{checked: true}` would do `el.checked = true` for the *current* element.
@@ -312,7 +295,7 @@ export declare function ref<T extends TargetType, K extends keyof T>(target: T,
  *   - `{destroy: string}`: When the *current* element is a top-level element to be removed (due to reactivity cleanup), actual removal from the DOM is delayed by 2 seconds, and in the mean time the value string is added as a CSS class to the element, allowing for a deletion transition. The string may also contain multiple dot-separated CSS classes, such as `.fade.shrink`.
  *   - `{create: function}` and `{destroy: function}`: The function is invoked when the *current* element is the top-level element being created/destroyed. It can be used for more involved creation/deletion animations. In case of `destroy`, the function is responsible for actually removing the element from the DOM (eventually). See `transitions.ts` in the Aberdeen source code for some examples.
  *   - `{bind: <obsValue>}`: Create a two-way binding element between the `value` property of the given observable (proxy) variable, and the *current* input element (`<input>`, `<select>` or `<textarea>`). This is often used together with {@link ref}, in order to use properties other than `.value`.
- *   - `{<any>: <obsvalue>}`: Create a new observe scope and read the `value` property of the given observable (proxy) variable from within it, and apply the contained value using any of the other rules in this list. Example:
+ *   - `{<any>: <obsvalue>}`: Create a new observer scope and read the `value` property of the given observable (proxy) variable from within it, and apply the contained value using any of the other rules in this list. Example:
  *      ```typescript
  *      const myColor = proxy('red');
  *      $('p:Test', {$color: myColor, click: () => myColor.value = 'yellow'})
@@ -435,7 +418,7 @@ export declare function insertCss(style: object, global?: boolean): string;
 /**
  * Sets a custom error handler function for errors that occur asynchronously
  * within reactive scopes (e.g., during updates triggered by proxy changes in
- * {@link observe} or {@link $} render functions).
+ * {@link derive} or {@link $} render functions).
  *
  * The default handler logs the error to `console.error` and adds a simple
  * 'Error' message div to the DOM at the location where the error occurred (if possible).
@@ -515,7 +498,7 @@ export declare function getParentElement(): Element;
  * This is useful for releasing resources, removing manual event listeners, or cleaning up
  * side effects associated with the scope. Cleaners are run in reverse order of registration.
  *
- * Scopes are created by functions like {@link observe}, {@link mount}, {@link $} (when given a render function),
+ * Scopes are created by functions like {@link derive}, {@link mount}, {@link $} (when given a render function),
  * and internally by constructs like {@link onEach}.
  *
  * @param cleaner - The function to execute during cleanup.
@@ -533,7 +516,7 @@ export declare function getParentElement(): Element;
  *     peek(() => sum.value += item);
  *     // Clean gets called before each rerun for a certain item index
  *     // No need for peek here, as the clean code doesn't run in an
- *     // observe scope.
+ *     // observer scope.
  *     clean(() => sum.value -= item);
  * })
  *
@@ -557,7 +540,7 @@ export declare function clean(cleaner: () => void): void;
  *
  * @param func - The function to execute reactively. Any DOM manipulations should typically
  *   be done using {@link $} within this function. Its return value will be made available as an
- *   observable returned by the `observe()` function.
+ *   observable returned by the `derive()` function.
  * @returns An observable object, with its `value` property containing whatever the last run of `func` returned.
  *
  * @example Observation creating a UI components
@@ -568,7 +551,7 @@ export declare function clean(cleaner: () => void): void;
  *   console.log('Welcome');
  *   $('h3:Welcome, ' + data.user); // Reactive text
  *
- *   observe(() => {
+ *   derive(() => {
  *     // When data.notifications changes, only this inner scope reruns,
  *     // leaving the `<p>Welcome, ..</p>` untouched.
  *     console.log('Notifications');
@@ -578,13 +561,13 @@ export declare function clean(cleaner: () => void): void;
  * });
  * ```
  *
- * ***Note*** that the above could just as easily be done using `$(func)` instead of `observe(func)`.
+ * ***Note*** that the above could just as easily be done using `$(func)` instead of `derive(func)`.
  *
  * @example Observation with return value
  * ```typescript
  * const counter = proxy(0);
  * setInterval(() => counter.value++, 1000);
- * const double = observe(() => counter.value * 2);
+ * const double = derive(() => counter.value * 2);
  *
  * $('h3', () => {
  *     $(`:counter=${counter.value} double=${double.value}`);
@@ -594,36 +577,7 @@ export declare function clean(cleaner: () => void): void;
  * @overload
  * @param func Func without a return value.
  */
-export declare function observe<T>(func: () => T): ValueRef<T>;
-/**
- * Similar to {@link observe}, creates a reactive scope that re-executes the function
- * when its proxied dependencies change.
- *
- * **Difference:** Updates run **synchronously and immediately** after the proxy modification
- * that triggered the update occurs.
- *
- * **Caution:** Use sparingly. Immediate execution bypasses Aberdeen's usual batching and
- * ordering optimizations, which can lead to performance issues or observing inconsistent
- * intermediate states if multiple related updates are applied sequentially.
- * Prefer {@link observe} or {@link $} for most use cases.
- *
- * @param func - The function to execute reactively and synchronously.
- *
- * @example
- * ```javascript
- * const state = proxy({ single: 'A' });
- *
- * immediateObserve(() => {
- *   state.double = state.single + state.single
- * });
- * console.log(state.double); // 'AA'
- *
- * state.single = 'B';
- * // Synchronously:
- * console.log(state.double); // 'BB'
- * ```
- */
-export declare function immediateObserve(func: () => void): void;
+export declare function derive<T>(func: () => T): ValueRef<T>;
 /**
  * Attaches a reactive Aberdeen UI fragment to an existing DOM element. Without the use of
  * this function, {@link $} will assume `document.body` as its root.
@@ -633,11 +587,11 @@ export declare function immediateObserve(func: () => void): void;
  * will cause it to re-execute when the data changes, updating the DOM elements created within it.
  *
  * Calls to {@link $} inside `func` will append nodes to `parentElement`.
- * You can nest {@link observe} or other {@link $} scopes within `func`.
+ * You can nest {@link derive} or other {@link $} scopes within `func`.
  * Use {@link unmountAll} to clean up all mounted scopes and their DOM nodes.
  *
  * Mounting scopes happens reactively, meaning that if this function is called from within another
- * ({@link observe} or {@link $} or {@link mount}) scope that gets cleaned up, so will the mount.
+ * ({@link derive} or {@link $} or {@link mount}) scope that gets cleaned up, so will the mount.
  *
  * @param parentElement - The native DOM `Element` to which the UI fragment will be appended.
  * @param func - The function that defines the UI fragment, typically containing calls to {@link $}.
@@ -669,26 +623,27 @@ export declare function immediateObserve(func: () => void): void;
 export declare function mount(parentElement: Element, func: () => void): void;
 /**
  * Removes all Aberdeen-managed DOM nodes and stops all active reactive scopes
- * (created by {@link mount}, {@link observe}, {@link $} with functions, etc.).
+ * (created by {@link mount}, {@link derive}, {@link $} with functions, etc.).
  *
  * This effectively cleans up the entire Aberdeen application state.
  */
 export declare function unmountAll(): void;
 /**
- * Executes a function *without* creating subscriptions in the current reactive scope, and returns its result.
+ * Executes a function or retrieves a value *without* creating subscriptions in the current reactive scope, and returns its result.
  *
- * This is useful when you need to access reactive data inside a reactive scope (like {@link observe})
+ * This is useful when you need to access reactive data inside a reactive scope (like {@link $})
  * but do not want changes to that specific data to trigger a re-execute of the scope.
  *
- * @template T The type of the return value of your function.
+ * Note: You may also use {@link unproxy} to get to the raw underlying data structure, which can be used to similar effect.
  *
- * @param func - The function to execute without creating subscriptions.
- * @returns Whatever `func` returns.
+ * @param target - Either a function to execute, or an object (which may also be an Array or a Map) to index.
+ * @param key - Optional key/index to use when `target` is an object.
+ * @returns The result of the function call, or the value at `target[key]` when `target` is an object or `target.get(key)` when it's a Map.
  *
- * @example Peeking within observe
+ * @example Peeking within observer
  * ```typescript
  * const data = proxy({ a: 1, b: 2 });
- * observe(() => {
+ * $(() => {
  *   // re-executes only when data.a changes, because data.b is peeked.
  *   const b = peek(() => data.b);
  *   console.log(`A is ${data.a}, B was ${b} when A changed.`);
@@ -698,13 +653,16 @@ export declare function unmountAll(): void;
  * ```
  *
  */
-export declare function peek<T>(func: () => T): T;
+export declare function peek<T extends object>(target: T, key: keyof T): T[typeof key];
+export declare function peek<K, V>(target: Map<K, V>, key: K): V | undefined;
+export declare function peek<T>(target: T[], key: number): T | undefined;
+export declare function peek<T>(target: () => T): T;
 /** When using a Map as `source`. */
 export declare function map<K, IN, OUT>(source: Map<K, IN>, func: (value: IN, key: K) => undefined | OUT): Map<K, OUT>;
-/** When using an object as `source`. */
-export declare function map<IN, const IN_KEY extends string | number | symbol, OUT>(source: Record<IN_KEY, IN>, func: (value: IN, index: KeyToString<IN_KEY>) => undefined | OUT): Record<string | symbol, OUT>;
 /** When using an array as `source`. */
 export declare function map<IN, OUT>(source: Array<IN>, func: (value: IN, index: number) => undefined | OUT): Array<OUT>;
+/** When using an object as `source`. */
+export declare function map<IN, const IN_KEY extends string | number | symbol, OUT>(source: Record<IN_KEY, IN>, func: (value: IN, index: KeyToString<IN_KEY>) => undefined | OUT): Record<string | symbol, OUT>;
 /** When using an array as `source`. */
 export declare function multiMap<IN, OUT extends {
     [key: string | symbol]: any;