aberdeen 0.2.4 → 0.5.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'
+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,48 +1,88 @@
-import {Store, observe, immediateObserve, inhibitEffects} from 'aberdeen'
+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 `{}`. Updates will be reflected in the URL, modifying 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.
- * - `state`: The browser history *state* object for the current page. Creating or removing top-level keys will cause *pushing* a new entry to the browser history.
+ * 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`, `search` and top-level `state` keys, and then *replace* that state by the full given state.
  */
-export const route = new Store()
 
-// Contains url (path+search) and state for all history entries for this session, with the current
-// entry on top. It is used for `mode: "back"`, to know how many entries to go back.
-let stack: Array<{url: string, state: object}> = []
+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
+}
 
-// Keep track of the initial history length, so we'll always know how long our `stack` should be.
-const initialHistoryLength = history.length;
+/**
+ * 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())
 
-// Keep a copy of the last known history state, so we can tell if the user changed one of its
-// top-level keys, so we can decide between push/replace when `mode` is not set.
-let prevHistoryState: any
+let stateRoute = {
+	nonce: -1,
+	depth: 0,
+}
 
 // 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' | 'back' | 'forward' | 'push' = 'load'
+	if (state.route?.nonce == null) {
+		state.route = {
+			nonce: Math.floor(Math.random() * Number.MAX_SAFE_INTEGER),
+			depth: 1,
+		} 
+		history.replaceState(state, '')
+	} else if (stateRoute.nonce === state.route.nonce) {
+		nav = state.route.depth > stateRoute.depth ? 'forward' : 'back'
+	}
+	stateRoute = state.route
+
+	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
+	}
+
 	const search: any= {}
 	for(let [k, v] of new URLSearchParams(location.search)) {
 		search[k] = v
 	}
-	prevHistoryState = event ? (event.state || {}) : {}
-	stack.length = Math.max(1, history.length - initialHistoryLength + 1)
-	stack[stack.length-1] = {url: location.pathname + location.search, state: prevHistoryState}
-	route.set({
-		path: location.pathname,
-		p: location.pathname.slice(1).split('/'),
-		search: search,
-		hash: location.hash,
-		state: prevHistoryState,
-	})
+
+	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();
 }
 handleLocationUpdate()
 window.addEventListener("popstate", handleLocationUpdate);
@@ -52,80 +92,120 @@ 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.get('path')
-	if (path == null && route.peek('p')) {
-		return updateP();
+	let path = route.path
+	if (path == null && unproxy(route).p) {
+		return updateP()
 	} 
-	path = ''+path
+	path = ''+(path || '/')
 	if (!path.startsWith('/')) path = '/'+path
-	route.set('path', path)
-	route.set('p', path.slice(1).split('/'))
+	route.path = path
+	route.p = path.slice(1).split('/')
 }
 immediateObserve(updatePath)
 
 function updateP(): void {
-	const p = route.get('p')
-	console.log('imm p', p)
-	if (p == null && route.peek('path')) {
+	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.set('p', ['']) // This will cause a recursive call this observer.
+		route.p = [''] // This will cause a recursive call this observer.
 	} else if (p.length == 0) {
-		route.set('p', ['']) // This will cause a recursive call this observer.
+		route.p = [''] // This will cause a recursive call this observer.
 	} else {
-		route.set('path', '/' + p.join('/'))
+		route.path = '/' + p.join('/')
 	}
 }
 immediateObserve(updateP)
 
 immediateObserve(() => {
-	if (route.getType('search') !== 'object') route.set('search', {})
+	if (!route.search || typeof route.search !== 'object') route.search = {}
+})
+
+immediateObserve(() => {
+	if (!route.id || typeof route.id !== 'object') route.id = {}
 })
 
 immediateObserve(() => {
-	if (route.getType('state') !== 'object') route.set('state', {})
+	if (!route.aux || typeof route.aux !== 'object') route.aux = {}
 })
 
 immediateObserve(() => {
-	let hash = ''+(route.get('hash') || '')
+	let hash = ''+(route.hash || '')
 	if (hash && !hash.startsWith('#')) hash = '#'+hash
-	route.set('hash', hash)
+	route.hash = hash
 })
 
-// This deferred-mode observer will update the URL and history based on `route` changes.
-observe(() => {
+function isSamePage(path: string, state: any): boolean {
+	return location.pathname === path && JSON.stringify(history.state.id) === JSON.stringify(state.id)
+}
+
+function updateHistory() {
 	// Get and delete mode without triggering anything.
-	const mode = route.get('mode')
-	if (mode) inhibitEffects(() => route.delete('mode'))
-	const state = route.get('state')
+	let mode = route.mode
+	const state = {
+		id: clone(route.id),
+		aux: clone(route.aux),
+		route: stateRoute,
+	}
 	
 	// Construct the URL.
-	const path = route.get('path')
-	const search = new URLSearchParams(route.get('search')).toString()
-	const url = (search ? path+'?'+search : path) + route.get('hash')
+	const path = route.path
 
 	// Change browser state, according to `mode`.
 	if (mode === 'back') {
-		let goDelta = 0
-		while(stack.length > 1) {
-			const item = stack[stack.length-1]
-			if (item.url === url && JSON.stringify(Object.keys(state||{})) === JSON.stringify(Object.keys(item.state||{}))) break // Found it!
-			goDelta--
-			stack.pop()
+		route.nav = 'back'
+		if (!isSamePage(path, state) && (history.state.route?.depth||0) > 1) {
+			history.back()
+			return
 		}
-		if (goDelta) history.go(goDelta)
+		mode = 'replace'
 		// We'll replace the state async, to give the history.go the time to take affect first.
-		setTimeout(() => history.replaceState(state, '', url), 0)
-		stack[stack.length-1] = {url,state}
-	} else if (mode === 'push' || (!mode && (location.pathname !== path || JSON.stringify(Object.keys(state||{})) !== JSON.stringify(Object.keys(prevHistoryState||{}))))) {
+		//setTimeout(() => history.replaceState(state, '', url), 0)
+	}
+
+	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)
-		stack.push({url,state})
+		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)
-		stack[stack.length-1] = {url,state}
 	}
-	prevHistoryState = state
-})
+}
+
+// This deferred-mode observer will update the URL and history based on `route` changes.
+observe(updateHistory)
+
+
+/**
+ * Restore and store the vertical and horizontal scroll position for
+ * the parent element to the page state.
+ * 
+ * @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 = unproxy(route).aux.scroll?.name
+	if (restore) {
+		Object.assign(el, restore)
+	}
+
+	function onScroll() {
+		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 {scheduleDomReader, scheduleDomWriter} from 'aberdeen'
-
 const FADE_TIME = 400
 const GROW_SHRINK_TRANSITION = `margin ${FADE_TIME}ms ease-out, transform ${FADE_TIME}ms ease-out`
 
@@ -20,34 +18,19 @@ function getGrowShrinkProps(el: HTMLElement) {
 * The transition doesn't look great for table elements, and may have problems
 * for other specific cases as well.
 */
-export function grow(el: HTMLElement): void {
-	// This timeout is to await all other elements having been added to the Dom
-	scheduleDomReader(() => {
-		// Make the element size 0 using transforms and negative margins.
-		// This causes a browser layout, as we're querying el.offset<>.
-		let props = getGrowShrinkProps(el)
-		
-		// The timeout is in order to batch all reads and then all writes when there
-		// are multiple simultaneous grow transitions.
-		scheduleDomWriter(() => {
-			Object.assign(el.style, props)
-			
-			// This timeout is to combine multiple transitions into a single browser layout
-			scheduleDomReader(() => {
-				// Make sure the layouting has been performed, to cause transitions to trigger
-				el.offsetHeight
-				scheduleDomWriter(() => {
-					// Do the transitions
-					el.style.transition = GROW_SHRINK_TRANSITION
-					for(let prop in props) el.style[prop as any] = ""
-					setTimeout(() => {
-						// Reset the element to a clean state
-						el.style.transition = ""
-					}, FADE_TIME)
-				})
-			})
-		})
-	})
+export async function grow(el: HTMLElement) {
+	let props = getGrowShrinkProps(el)
+	Object.assign(el.style, props)
+	
+	// Make sure the layouting has been performed, to cause transitions to trigger
+	el.offsetHeight
+
+	el.style.transition = GROW_SHRINK_TRANSITION
+	for(let prop in props) el.style[prop as any] = ''
+	setTimeout(() => {
+		// Disable transitions.
+		el.style.transition = ''
+	}, FADE_TIME)
 }
 
 /** Do a shrink transition for the given element, and remove it from the DOM
@@ -58,16 +41,16 @@ export function grow(el: HTMLElement): void {
 * The transition doesn't look great for table elements, and may have problems
 * for other specific cases as well.
 */
-export function shrink(el: HTMLElement): void {
-	scheduleDomReader(() => {
-		const props = getGrowShrinkProps(el)
-		// The timeout is in order to batch all reads and then all writes when there
-		// are multiple simultaneous shrink transitions.
-		scheduleDomWriter(() => {
-			el.style.transition = GROW_SHRINK_TRANSITION
-			Object.assign(el.style, props)
-			
-			setTimeout(() => el.remove(), FADE_TIME)
-		})
-	})
-}
+export async function shrink(el: HTMLElement) {
+	// Get original layout info
+	const props = getGrowShrinkProps(el)
+
+	// Batch starting transitions in the write phase.
+	el.style.transition = GROW_SHRINK_TRANSITION
+	Object.assign(el.style, props)
+	
+	// Remove the element after the transition is done.
+	setTimeout(() => {
+		el.remove()
+	}, FADE_TIME)
+}