aberdeen 0.4.0 → 1.0.0

package/src/helpers/reverseSortedSet.ts

@@ -0,0 +1,188 @@
+type Item<T> = T & {[idx: symbol]: Item<T>}
+
+/**
+ * A set-like collection of objects that can do iteration sorted by a specified index property.
+ * It also allows retrieving an object by its index property, and quickly getting the object
+ * that comes immediately after a given object.
+ * 
+ * It's implemented as a skiplist, maintaining all meta-data as part of the objects that it
+ * is tracking, for performance.
+ */
+export class ReverseSortedSet<T extends object> {
+    // A fake item, that is not actually T, but *does* contain symbols pointing at the first item for each level.
+    private tail: Item<T>
+    // As every SkipList instance has its own symbols, an object can be included in more than one SkipList.
+    private symbols: symbol[]
+
+    /**
+     * Create an empty SortedSet.
+     * 
+     * @param keyProp The name of the property that should be used as the index of this collection. Comparison
+     * using `<` will be done on this property, so it should probably be a number or a string (or something that
+     * has a useful toString-conversion).
+     */
+    constructor(private keyProp: keyof T) {
+        this.tail = {} as Item<T>
+        this.symbols = [Symbol(0)]
+    }
+
+    /**
+     * Add an object to the `SortedSet`.
+     * 
+     * @param item The object to be added to the set. One or more properties with
+     *  `Symbol` keys will be added to it, for `SortedSet` internals.
+     * @returns `true` if the item was added, or `false` if it was *not* added
+     *  because the item already was part of this set.
+     * 
+     * Note that though an item object may only be part of a particular `SortedSet`
+     * once, index properties may be duplicate and an item object may be part of
+     * more than one `SortedSet`.
+     * 
+     * **IMPORTANT:** After adding an object, do not modify its index property,
+     * as this will lead to undefined (broken) behavior on the entire set.
+     * 
+     * Time complexity: O(log n)
+     */
+    add(item: T): boolean {
+        if (this.symbols[0] in item) return false // Already included
+
+        // Start at level 1. Keep upping the level by 1 with 1/8 chance.
+        const level = 1 + (Math.clz32(Math.random() * 0xFFFFFFFF) >> 2)
+        for(let l = this.symbols.length; l < level; l++) this.symbols.push(Symbol(l))
+
+        const keyProp = this.keyProp
+        const key = item[keyProp]
+    
+        let prev: Item<T> | undefined
+        let current: Item<T> = this.tail;
+        for (let l = this.symbols.length-1; l>=0; l--) {
+            const symbol = this.symbols[l]
+            while ((prev = current[symbol] as Item<T>) && prev[keyProp] > key) current = prev;
+            if (l < level) {
+                (item as any)[symbol] = current[symbol];
+                (current as any)[symbol] = item;
+            }
+        }
+
+        return true // Added
+    }
+
+    /**
+     * @param item An object to test for inclusion in the set.
+     * @returns true if this object item is already part of the set.
+     */
+    has(item: T): boolean {
+        return this.symbols[0] in item;
+    }
+
+    /**
+     * Remove and return the last item.
+     * @returns what was previously the last item in the sorted set, or `undefined` if the set was empty.
+     */
+    fetchLast(): T | undefined {
+        let item = this.tail[this.symbols[0]];
+        if (item) {
+            this.remove(item);
+            return item;
+        }
+    }
+
+    /**
+     * @returns whether the set is empty (`true`) or has at least one item (`false`).
+     */
+    isEmpty(): boolean {
+        return this.tail[this.symbols[0]] === undefined;
+    }
+
+    /**
+     * Retrieve an item object based on its index property value. 
+     * 
+     * @param indexValue The index property value to search for.
+     * @returns `undefined` if the index property value does not exist in the `SortedSet` or
+     *  otherwise the *first* item object that has this index value (meaning any further
+     *  instances can be iterated using `next()`).
+     * 
+     * Time complexity: O(log n)
+     */
+    get(indexValue: string|number): T | undefined {
+        const keyProp = this.keyProp
+        let current = this.tail;
+        let prev
+        for (let l = this.symbols.length-1; l>=0; l--) {
+            const symbol = this.symbols[l]
+            while ((prev = current[symbol] as Item<T>) && prev[keyProp] > indexValue) current = prev;
+        }
+        return current[this.symbols[0]]?.[keyProp] === indexValue ? current[this.symbols[0]] : undefined;
+    }
+
+    /**
+     * The iterator will go through the items in reverse index-order.
+     */
+    *[Symbol.iterator](): IterableIterator<T> {
+        let symbol = this.symbols[0]
+        let node: Item<T> | undefined = this.tail[symbol] as Item<T>;
+        while (node) {
+            yield node;
+            node = node[symbol] as Item<T> | undefined;
+        }
+    }
+
+    /**
+     * Given an item object, returns the one that comes right before in the set.
+     * @param item The object to start from.
+     * @returns The next object, or `undefined` if there is none.
+     * 
+     * Time complexity: O(1)
+     */
+    prev(item: T): T | undefined {
+        return (item as Item<T>)[this.symbols[0]]
+    }
+
+    /**
+     * Remove an item object from the set, deleting all meta-data keys that
+     * were created on `add()`.
+     * @param item The object to be removed.
+     * @returns `true` on success or `false` when the item was not part of the set.
+     *
+     * Time complexity: O(log n)
+     */
+    remove(item: T): boolean {
+        if (!(this.symbols[0] in item)) return false;
+        const keyProp = this.keyProp
+        const prop = item[keyProp];
+        
+        let prev: Item<T> | undefined
+        let current: Item<T> = this.tail;
+        
+        for (let l = this.symbols.length - 1; l >= 0; l--) {
+            const symbol = this.symbols[l];
+            while ((prev = current[symbol] as Item<T>) && prev[keyProp] >= prop && prev !== item) current = prev
+            if (prev === item) {
+                (current as any)[symbol] = prev[symbol]
+                delete prev[symbol]
+            }
+        }
+
+        return prev === item
+    }
+
+    /**
+     * Remove all items for the set.
+     *
+     * Time complexity: O(n)
+     */    
+    clear(): void {
+        const symbol = this.symbols[0];
+        let current: Item<T> | undefined = this.tail;
+        while (current) {
+            const prev = current[symbol] as Item<T> | undefined
+            for (const symbol of this.symbols) {
+                if (!(symbol in current)) break
+                delete current[symbol];
+            }
+            current = prev
+        }
+        this.tail = {} as Item<T>;
+    }
+}
+

package/src/prediction.ts

@@ -1,18 +1,23 @@
-import {withEmitHandler} from './aberdeen.js'
+import {withEmitHandler, defaultEmitHandler} from './aberdeen.js'
+import type { DatumType, TargetType } from './aberdeen.js';
 
-type ObsCollection = any
-type Patch = Map<ObsCollection, Map<any, [any, any]>>;
+/** 
+ * Represents a set of changes that can be applied to proxied objects.
+ * This is an opaque type - its internal structure is not part of the public API.
+ * @private
+ */
+export type Patch = Map<TargetType, Map<any, [DatumType, DatumType]>>;
 
 
 function recordPatch(func: () => void): Patch {
 	const recordingPatch = new Map()
-	withEmitHandler(function(index, newData, oldData) {
-		addToPatch(recordingPatch, this, index, newData, oldData)
+	withEmitHandler(function(target, index, newData, oldData) {
+		addToPatch(recordingPatch, target, index, newData, oldData)
 	}, func)
 	return recordingPatch
 }
 
-function addToPatch(patch: Patch, collection: ObsCollection, index: any, newData: any, oldData: any) {
+function addToPatch(patch: Patch, collection: TargetType, index: any, newData: DatumType, oldData: DatumType) {
 	let collectionMap = patch.get(collection)
 	if (!collectionMap) {
 		collectionMap = new Map()
@@ -27,7 +32,7 @@ function addToPatch(patch: Patch, collection: ObsCollection, index: any, newData
 function emitPatch(patch: Patch) {
 	for(let [collection, collectionMap] of patch) {
 		for(let [index, [newData, oldData]] of collectionMap) {
-			collection.emitChange(index, newData, oldData)
+			defaultEmitHandler(collection, index, newData, oldData);
 		}
 	}
 }
@@ -43,7 +48,7 @@ function mergePatch(target: Patch, source: Patch, reverse: boolean = false) {
 function silentlyApplyPatch(patch: Patch, force: boolean = false): boolean {
 	for(let [collection, collectionMap] of patch) {
 		for(let [index, [newData, oldData]] of collectionMap) {
-			let actualData = collection.rawGet(index)
+			let actualData = (collection as any)[index]
 			if (actualData !== oldData) {
 				if (force) setTimeout(() => { throw new Error(`Applying invalid patch: data ${actualData} is unequal to expected old data ${oldData} for index ${index}`)}, 0)
 				else return false
@@ -52,7 +57,7 @@ function silentlyApplyPatch(patch: Patch, force: boolean = false): boolean {
 	}
 	for(let [collection, collectionMap] of patch) {
 		for(let [index, [newData, oldData]] of collectionMap) {
-			collection.rawSet(index, newData)
+			(collection as any)[index] = newData
 		}
 	}
 	return true

package/src/route.ts

@@ -1,30 +1,44 @@
-import {Store, observe, immediateObserve, runQueue, getParentElement, clean} from './aberdeen.js'
+import {getParentElement, runQueue, clean, proxy, observe, immediateObserve, unproxy, clone} from './aberdeen.js'
 
 /**
- * A `Store` object that holds the following keys:
- * - `path`: The current path of the URL split into components. For instance `/` or `/users/123/feed`. Updates will be reflected in the URL and will *push* a new entry to the browser history.
- * - `p`: Array containing the path segments. For instance `[]` or `['users', 123, 'feed']`. Updates will be reflected in the URL and will *push* a new entry to the browser history. Also, the values of `p` and `path` will be synced.
- * - `search`: An observable object containing search parameters (a split up query string). For instance `{order: "date", title: "something"}` or just `{}`. By default, updates will be reflected in the URL, replacing the current history state. 
- * - `hash`: The document hash part of the URL. For instance `"#section-title"`. It can also be an empty string. Updates will be reflected in the URL, modifying the current history state.
- * - `id`: A part of the browser history *state* that is considered part of the page *identify*, meaning changes will (by default) cause a history push, and when going *back*, it must match.
- * - `aux`: The auxiliary part of the browser history *state*, not considered part of the page *identity*. Changes will be reflected in the browser history using a replace. 
- * - `depth`: The navigation depth of the current session. Starts at 1. Writing to this property has no effect.
- * - `nav`: The navigation action that got us to this page. Writing to this property has no effect.
- *    - `"load"`: An initial page load.
- *    - `"back"` or `"forward"`: When we navigated backwards or forwards in the stack.
- *    - `"push"`: When we added a new page on top of the stack. 
+ * The class for the singleton `route` object.
  * 
- * The following key may also be written to `route` but will be immediately and silently removed: 
- * - `mode`: As described above, this library takes a best guess about whether pushing an item to the browser history makes sense or not. When `mode` is...
- * 	  	- `"push"`: Force creation of a new browser history entry. 
- * 	  	- `"replace"`: Update the current history entry, even when updates to other keys would normally cause a *push*.
- * 		- `"back"`: Unwind the history (like repeatedly pressing the *back* button) until we find a page that matches the given `path` and `id`, and then *replace* that state by the full given state.
  */
 
-// Idea: split `state` into `pstate` (primary) and `astate` (auxilary). The former is used to determine if new pages should be pushed and if, when moving back, a page matches.
-// Moving back is done by just doing history.back() while depth > 1, and repeating in handleLocationUpdate until matching page is found (or overriding base page).
+export class Route {
+	/** The current path of the URL split into components. For instance `/` or `/users/123/feed`. Updates will be reflected in the URL and will *push* a new entry to the browser history. */
+	path!: string
+	/** Array containing the path segments. For instance `[]` or `['users', 123, 'feed']`. Updates will be reflected in the URL and will *push* a new entry to the browser history. Also, the values of `p` and `path` will be synced. */
+	p!: string[]
+	/** An observable object containing search parameters (a split up query string). For instance `{order: "date", title: "something"}` or just `{}`. By default, updates will be reflected in the URL, replacing the current history state. */
+	hash!: string
+	/** A part of the browser history *state* that is considered part of the page *identify*, meaning changes will (by default) cause a history push, and when going *back*, it must match. */
+	search!: Record<string, string>
+	/** The `hash` interpreted as search parameters. So `"a=x&b=y"` becomes `{a: "x", b: "y"}`. */
+	id!: Record<string, any>
+	/** The auxiliary part of the browser history *state*, not considered part of the page *identity*. Changes will be reflected in the browser history using a replace. */
+	aux!: Record<string, any>
+	/** The navigation depth of the current session. Starts at 1. Writing to this property has no effect. */
+	depth: number = 1
+	/** The navigation action that got us to this page. Writing to this property has no effect.
+        - `"load"`: An initial page load.
+        - `"back"` or `"forward"`: When we navigated backwards or forwards in the stack.
+        - `"push"`: When we added a new page on top of the stack. 
+    */
+    nav: 'load' | 'back' | 'forward' | 'push' = 'load'
+    /** As described above, this library takes a best guess about whether pushing an item to the browser history makes sense or not. When `mode` is... 
+   	    - `"push"`: Force creation of a new browser history entry. 
+   	    - `"replace"`: Update the current history entry, even when updates to other keys would normally cause a *push*.
+ 	    - `"back"`: Unwind the history (like repeatedly pressing the *back* button) until we find a page that matches the given `path` and `id` (or that is the first page in our stack), and then *replace* that state by the full given state.
+        The `mode` key can be written to `route` but will be immediately and silently removed.
+    */
+	mode: 'push' | 'replace' | 'back' | undefined
+}
 
-export const route = new Store()
+/**
+ * The singleton {@link Route} object reflecting the current URL and browser history state. You can make changes to it to affect the URL and browser history. See {@link Route} for details.
+ */
+export const route = proxy(new Route())
 
 let stateRoute = {
 	nonce: -1,
@@ -34,7 +48,7 @@ let stateRoute = {
 // Reflect changes to the browser URL (back/forward navigation) in the `route` and `stack`.
 function handleLocationUpdate(event?: PopStateEvent) {
 	let state = event?.state || {}
-	let nav = 'load'
+	let nav: 'load' | 'back' | 'forward' | 'push' = 'load'
 	if (state.route?.nonce == null) {
 		state.route = {
 			nonce: Math.floor(Math.random() * Number.MAX_SAFE_INTEGER),
@@ -46,8 +60,8 @@ function handleLocationUpdate(event?: PopStateEvent) {
 	}
 	stateRoute = state.route
 
-	if (route('mode').peek() === 'back') {
-		route('depth').set(stateRoute.depth)
+	if (unproxy(route).mode === 'back') {
+		route.depth = stateRoute.depth
 		// We are still in the process of searching for a page in our navigation history..
 		updateHistory()
 		return
@@ -58,16 +72,14 @@ function handleLocationUpdate(event?: PopStateEvent) {
 		search[k] = v
 	}
 
-	route.set({
-		path: location.pathname,
-		p: location.pathname.slice(1).split('/'),
-		search: search,
-		hash: location.hash,
-		id: state.id,
-		aux: state.aux,
-		depth: stateRoute.depth,
-		nav,
-	})
+	route.path =  location.pathname
+	route.p =  location.pathname.slice(1).split('/')
+	route.search = search
+	route.hash =  location.hash
+	route.id =  state.id
+	route.aux =  state.aux
+	route.depth =  stateRoute.depth
+	route.nav = nav
 
 	// Forward or back event. Redraw synchronously, because we can!
 	if (event) runQueue();
@@ -80,45 +92,49 @@ window.addEventListener("popstate", handleLocationUpdate);
 // initiated `set` will see the canonical form (instead of doing a rerender shortly after,
 // or crashing due to non-canonical data).
 function updatePath(): void {
-	let path = route('path').get()
-	if (path == null && route('p').peek()) {
-		return updateP();
+	let path = route.path
+	if (path == null && unproxy(route).p) {
+		return updateP()
 	} 
-	path = ''+path
+	path = ''+(path || '/')
 	if (!path.startsWith('/')) path = '/'+path
-	route('path').set(path)
-	route('p').set(path.slice(1).split('/'))
+	route.path = path
+	route.p = path.slice(1).split('/')
 }
 immediateObserve(updatePath)
 
 function updateP(): void {
-	const p = route('p').get()
-	if (p == null && route('path').peek()) {
+	const p = route.p
+	if (p == null && unproxy(route).path) {
 		return updatePath()
 	}
 	if (!(p instanceof Array)) {
 		console.error(`aberdeen route: 'p' must be a non-empty array, not ${JSON.stringify(p)}`)
-		route('p').set(['']) // This will cause a recursive call this observer.
+		route.p = [''] // This will cause a recursive call this observer.
 	} else if (p.length == 0) {
-		route('p').set(['']) // This will cause a recursive call this observer.
+		route.p = [''] // This will cause a recursive call this observer.
 	} else {
-		route('path').set('/' + p.join('/'))
+		route.path = '/' + p.join('/')
 	}
 }
 immediateObserve(updateP)
 
 immediateObserve(() => {
-	if (route('search').getType() !== 'object') route('search').set({})
+	if (!route.search || typeof route.search !== 'object') route.search = {}
 })
 
 immediateObserve(() => {
-	if (route('state').getType() !== 'object') route('state').set({})
+	if (!route.id || typeof route.id !== 'object') route.id = {}
 })
 
 immediateObserve(() => {
-	let hash = ''+(route('hash').get() || '')
+	if (!route.aux || typeof route.aux !== 'object') route.aux = {}
+})
+
+immediateObserve(() => {
+	let hash = ''+(route.hash || '')
 	if (hash && !hash.startsWith('#')) hash = '#'+hash
-	route('hash').set(hash)
+	route.hash = hash
 })
 
 function isSamePage(path: string, state: any): boolean {
@@ -127,19 +143,19 @@ function isSamePage(path: string, state: any): boolean {
 
 function updateHistory() {
 	// Get and delete mode without triggering anything.
-	let mode = route('mode').get()
+	let mode = route.mode
 	const state = {
-		id: route('id').get(),
-		aux: route('aux').get(),
+		id: clone(route.id),
+		aux: clone(route.aux),
 		route: stateRoute,
 	}
 	
 	// Construct the URL.
-	const path = route('path').get()
+	const path = route.path
 
 	// Change browser state, according to `mode`.
 	if (mode === 'back') {
-		route('nav').set('back')
+		route.nav = 'back'
 		if (!isSamePage(path, state) && (history.state.route?.depth||0) > 1) {
 			history.back()
 			return
@@ -149,17 +165,15 @@ function updateHistory() {
 		//setTimeout(() => history.replaceState(state, '', url), 0)
 	}
 
-	if (mode) route('mode').delete()
-	const search = new URLSearchParams(route('search').get()).toString()
-	const url = (search ? path+'?'+search : path) + route('hash').get()
+	if (mode) route.mode = undefined
+	const search = new URLSearchParams(route.search).toString()
+	const url = (search ? path+'?'+search : path) + route.hash
 		
 	if (mode === 'push' || (!mode && !isSamePage(path, state))) {
 		stateRoute.depth++ // stateRoute === state.route
 		history.pushState(state, '', url)
-		route.merge({
-			nav: 'push',
-			depth: stateRoute.depth
-		})
+		route.nav = 'push'
+		route.depth = stateRoute.depth
 	} else {
 		// Default to `push` when the URL changed or top-level state keys changed.
 		history.replaceState(state, '', url)
@@ -176,19 +190,22 @@ observe(updateHistory)
  * 
  * @param {string} name - A unique (within this page) name for this
  * scrollable element. Defaults to 'main'.
+ * 
+ * The scroll position will be persisted in `route.aux.scroll.<name>`.
  */
 export function persistScroll(name: string = 'main') {
 	const el = getParentElement()
 	el.addEventListener('scroll', onScroll)
 	clean(() => el.removeEventListener('scroll', onScroll))
 
-	let restore = route('state', 'scroll', name).peek()
+	let restore = unproxy(route).aux.scroll?.name
 	if (restore) {
 		Object.assign(el, restore)
 	}
 
 	function onScroll() {
-		route('mode').set('replace')
-		route('state', 'scroll', name).set({scrollTop: el.scrollTop, scrollLeft: el.scrollLeft})
+		route.mode = 'replace'
+		if (!route.aux.scroll) route.aux.scroll = {}
+		route.aux.scroll[name] = {scrollTop: el.scrollTop, scrollLeft: el.scrollLeft}
 	}
 }

package/src/transitions.ts

@@ -1,5 +1,3 @@
-import {DOM_READ_PHASE, DOM_WRITE_PHASE} from './aberdeen.js'
-
 const FADE_TIME = 400
 const GROW_SHRINK_TRANSITION = `margin ${FADE_TIME}ms ease-out, transform ${FADE_TIME}ms ease-out`
 
@@ -21,21 +19,12 @@ function getGrowShrinkProps(el: HTMLElement) {
 * for other specific cases as well.
 */
 export async function grow(el: HTMLElement) {
-	// Wait until all DOM updates have been done. Then get info from the computed layout.
-	await DOM_READ_PHASE
 	let props = getGrowShrinkProps(el)
-
-	// In the write phase, make the element size 0 using transforms and negative margins.
-	await DOM_WRITE_PHASE
 	Object.assign(el.style, props)
 	
-	// Await read phase, to combine multiple transitions into a single browser layout
-	await DOM_READ_PHASE
 	// Make sure the layouting has been performed, to cause transitions to trigger
 	el.offsetHeight
 
-	// In the next write phase, do the transitions
-	await DOM_WRITE_PHASE
 	el.style.transition = GROW_SHRINK_TRANSITION
 	for(let prop in props) el.style[prop as any] = ''
 	setTimeout(() => {
@@ -53,12 +42,10 @@ export async function grow(el: HTMLElement) {
 * for other specific cases as well.
 */
 export async function shrink(el: HTMLElement) {
-	// Wait until all DOM updates have been done. Then get info from the computed layout.
-	await DOM_READ_PHASE
+	// Get original layout info
 	const props = getGrowShrinkProps(el)
 
 	// Batch starting transitions in the write phase.
-	await DOM_WRITE_PHASE
 	el.style.transition = GROW_SHRINK_TRANSITION
 	Object.assign(el.style, props)