simplyflow 0.8.2 → 0.9.0

package/src/state.mjs

@@ -1,55 +1,90 @@
-if (!Symbol.iterate) {
-    Symbol.iterate = Symbol('iterate')
+import { DEP } from './symbols.mjs'
+
+function wrapMapMethod(target, property, receiver, value) {
+    return (...args) => {
+        if (property === 'get' || property === 'has') {
+            notifyGet(receiver, args[0])
+        }
+        if (['keys', 'values', 'entries', 'forEach', Symbol.iterator].includes(property)) {
+            notifyGet(receiver, DEP.ITERATE)
+        }
+
+        const oldSize = target.size
+        const result = value.apply(target, args)
+
+        if (property === 'set') {
+            notifySet(receiver, makeContext(args[0], { now: args[1] }))
+        }
+
+        if (property === 'delete') {
+            notifySet(receiver, makeContext(args[0], { delete: true}))
+        }
+
+        if (oldSize !== target.size) {
+            notifySet(receiver, makeContext(DEP.SIZE, {}))
+        }
+
+        if (['set','delete','clear'].includes(property) || oldSize!==target.size) {
+            notifySet(receiver, makeContext(DEP.ITERATE, {}))
+        }
+
+        return result
+    }
+
 }
-if (!Symbol.xRay) {
-    Symbol.xRay = Symbol('xRay')
+
+function wrapArrayMethod(target, property, receiver, value) {
+    return (...args) => {
+        let l = target.length
+        // by binding the function to the receiver
+        // all accesses in the function will be trapped
+        // by the Proxy, so get/set/delete is all handled
+        let result = value.apply(receiver, args)
+        if (l != target.length) {
+            notifySet(receiver,  makeContext(DEP.LENGTH, { was: l, now: target.length }) )
+        }
+        return result
+    }
 }
-if (!Symbol.Signal) {
-    Symbol.Signal = Symbol('Signal')
+
+function wrapSetMethod(target, property, receiver, value) {
+    return (...args) => {
+        // node doesn't allow you to call set/map functions
+        // bound to the receiver.. so using target instead
+        // there are no properties to update anyway, except for size
+        let s = target.size
+        let result = value.apply(target, args)
+        if (s != target.size) {
+            notifySet(receiver, makeContext( DEP.SIZE, { was: s, now: target.size }) )
+        }
+        // there is no efficient way to see if the function called
+        // has actually changed the Set/Map, but by assuming the
+        // 'setter' functions will change the results of the
+        // 'getter' functions, effects should update correctly
+        if (['set','add','clear','delete'].includes(property)) {
+            notifySet(receiver, makeContext( { entries: {}, forEach: {}, has: {}, keys: {}, values: {}, [Symbol.iterator]: {} } ) )
+        }
+        return result
+    }
 }
 
 const signalHandler = {
     get: (target, property, receiver) => {
-        if (property===Symbol.xRay) {
+        if (property===DEP.XRAY) {
             return target // don't notifyGet here, this is only called by set
         }
-        if (property===Symbol.Signal) {
+        if (property===DEP.SIGNAL) {
             return true
         }
         const value = target?.[property] // Reflect.get fails on a Set.
         notifyGet(receiver, property)
         if (typeof value === 'function') {
             if (Array.isArray(target)) {
-                return (...args) => {
-                    let l = target.length
-                    // by binding the function to the receiver
-                    // all accesses in the function will be trapped
-                    // by the Proxy, so get/set/delete is all handled
-                    let result = value.apply(receiver, args)
-                    if (l != target.length) {
-                        notifySet(receiver,  makeContext('length', { was: l, now: target.length }) )
-                    }
-                    return result
-                }
-            } else if (target instanceof Set || target instanceof Map) {
-                return (...args) => {
-                    // node doesn't allow you to call set/map functions
-                    // bound to the receiver.. so using target instead
-                    // there are no properties to update anyway, except for size
-                    let s = target.size
-                    let result = value.apply(target, args)
-                    if (s != target.size) {
-                        notifySet(receiver, makeContext( 'size', { was: s, now: target.size }) )
-                    }
-                    // there is no efficient way to see if the function called
-                    // has actually changed the Set/Map, but by assuming the
-                    // 'setter' functions will change the results of the
-                    // 'getter' functions, effects should update correctly
-                    if (['set','add','clear','delete'].includes(property)) {
-                        notifySet(receiver, makeContext( { entries: {}, forEach: {}, has: {}, keys: {}, values: {}, [Symbol.iterator]: {} } ) )
-                    }
-                    return result
-                }
+                return wrapArrayMethod(target, property, receiver, value)
+            } else if (target instanceof Map) {
+                return wrapMapMethod(target, property, receiver, value)
+            } else if (target instanceof Set) {
+                return wrapSetMethod(target, property, receiver, value)
             } else if (
                 target instanceof HTMLElement
                 || target instanceof Number
@@ -74,8 +109,8 @@ const signalHandler = {
             notifySet(receiver, makeContext(property, { was: current, now: value } ) )
         }
         if (typeof current === 'undefined') {
-            notifySet(receiver, makeContext(Symbol.iterate, {}))
-            notifySet(receiver, makeContext('length', {}))
+            notifySet(receiver, makeContext(DEP.ITERATE, {}))
+            notifySet(receiver, makeContext(DEP.LENGTH, {}))
         }
         return true
     },
@@ -92,19 +127,21 @@ const signalHandler = {
             delete target[property]
             let receiver = signals.get(target) // receiver is not part of the trap arguments, so retrieve it here
             notifySet(receiver, makeContext(property,{ delete: true, was: current }))
+            notifySet(receiver, makeContext(DEP.ITERATE, { delete: true, property })
+        )
         }
         return true
     },
     defineProperty: (target, property, descriptor) => {
         if (typeof target[property] === 'undefined') {
             let receiver = signals.get(target) // receiver is not part of the trap arguments, so retrieve it here
-            notifySet(receiver, makeContext(Symbol.iterate, {}))
+            notifySet(receiver, makeContext(DEP.ITERATE, {}))
         }
         return Object.defineProperty(target, property, descriptor)
     },
     ownKeys: (target) => {
         let receiver = signals.get(target) // receiver is not part of the trap arguments, so retrieve it here
-        notifyGet(receiver, Symbol.iterate)
+        notifyGet(receiver, DEP.ITERATE)
         return Reflect.ownKeys(target)
     }
 
@@ -122,11 +159,13 @@ export const signals = new WeakMap()
  * Creates a new signal proxy of the given object, that intercepts get/has and set/delete
  * to allow reactive functions to be triggered when signal values change.
  */
-export function signal(v) {
-    if (!v) {
-        v = {}
+export function signal(v = {}) {
+    if (v === null || typeof v !== 'object' && typeof v !== 'function') {
+        throw new TypeError(
+            `simplyflow/state: signal() expects an object, array, Map, Set, class instance, or function; received ${typeof v}`
+        )
     }
-    if (v[Symbol.Signal]) { // there can be only one signal for any value
+    if (v[DEP.SIGNAL]) { // there can be only one signal for any value
         return v
     }
     if (!signals.has(v)) {
@@ -153,21 +192,30 @@ let tracing = false
  * call the given function and then disable all tracers.
  * @return void
  */
-export function trace(signal, prop) {
-    if (typeof signal==='function') {
+export function trace(target, prop) {
+    if (typeof target==='function') {
         tracing = true
-        signal()
-        tracing = false
-    } else {
-        const listeners = getListeners(signal, prop)
-        return listeners.map(listener => {
-            return {
-                effect: listener.effectType,
-                fn: listener.effectFunction,
-                signal: signals.get(listener.effectFunction)
-            }
-        })
+        try {
+            return target()
+        } finally {
+            tracing = false
+        }
+    }
+
+    if (!target || !target[DEP.SIGNAL]) {
+        throw new TypeError(
+            'simplyflow/state: trace() expects either a function or a signal'
+        )
     }
+
+    const listeners = getListeners(target, prop)
+    return listeners.map(listener => {
+        return {
+            effect: listener.effectType,
+            fn: listener.effectFunction,
+            signal: signals.get(listener.effectFunction)
+        }
+    })
 }
 
 /**
@@ -180,6 +228,9 @@ export function trace(signal, prop) {
  * set: function(signal, context, listener)
  */
 export function addTracer(tracer) {
+    if (!tracer || typeof tracer !== 'object') {
+        throw new TypeError('simplyflow/state: addTracer() expects a tracer object')
+    }
     if (!tracer.get && !tracer.set) {
         throw new Error('simply.state: addTracer: missing "get" or "set" property in tracer', tracer)
     }
@@ -207,7 +258,14 @@ let batchMode = 0
  * Triggers any reactor function that depends on this signal
  * to re-compute its values
  */
-export function notifySet(self, context={}) {
+export function notifySet(self, context = new Map()) {
+    if (!self || !self[DEP.SIGNAL]) {
+        throw new TypeError('simplyflow/state: notifySet() expects a signal as first argument')
+    }
+    if (!(context instanceof Map)) {
+        throw new TypeError('simplyflow/state: notifySet() expects context to be a Map; use makeContext()')
+    }
+
     let listeners = []
     context.forEach((change, property) => {
         let propListeners = getListeners(self, property)
@@ -240,8 +298,14 @@ export function notifySet(self, context={}) {
 
 export function makeContext(property, change) {
     let context = new Map()
-    if (typeof property === 'object') {
-        for (let prop in property) {
+    if (property instanceof Map) {
+        property.forEach((change, prop) => {
+            context.set(prop, change)
+        })
+        return context
+    }
+    if (property !== null && typeof property === 'object') {
+        for (const prop of Reflect.ownKeys(property)) {
             context.set(prop, property[prop])
         }
     } else {
@@ -333,17 +397,22 @@ function setListeners(self, property, compute) {
  * based on the current call (code path)
  */
 function clearListeners(compute) {
-    let connectedSignals = computeMap.get(compute)
-    if (connectedSignals) {
-        connectedSignals.forEach(property => {
-            property.forEach(s => {
-                let listeners = listenersMap.get(s)
-                if (listeners.has(property)) {
-                    listeners.get(property).delete(compute)
-                }
-            })
-        })
+    const connectedSignals = computeMap.get(compute)
+    if (!connectedSignals) {
+        return
     }
+
+    connectedSignals.forEach((signals, property) => {
+        signals.forEach(signal => {
+            const listeners = listenersMap.get(signal)
+
+            if (listeners?.has(property)) {
+                listeners.get(property).delete(compute)
+            }
+        })
+    })
+
+    computeMap.delete(compute)
 }
 
 /**
@@ -367,11 +436,17 @@ const effectMap = new WeakMap()
  */
 const signalStack = []
 
+function assertFunction(fn, name) {
+    if (typeof fn !== 'function') {
+        throw new TypeError(`simplyflow/state: ${name}() expects a function`)
+    }
+}
 /**
  * Runs the given function at once, and then whenever a signal changes that
  * is used by the given function (or at least signals used in the previous run).
  */
 export function effect(fn) {
+    assertFunction(fn, 'effect')
     if (effectStack.findIndex(f => fn==f)!==-1) {
         throw new Error('Recursive update() call', {cause:fn})
     }
@@ -427,8 +502,11 @@ export function effect(fn) {
 
 
 export function destroy(connectedSignal) {
+    if (!connectedSignal || !connectedSignal[DEP.SIGNAL]) {
+        throw new TypeError('simplyflow/state: destroy() expects an effect signal')
+    }
     // find the computeEffect associated with this signal
-    const computeEffect = effectMap.get(connectedSignal)?.deref()
+    const computeEffect = effectMap.get(connectedSignal)
     if (!computeEffect) {
         return
     }
@@ -437,11 +515,11 @@ export function destroy(connectedSignal) {
     clearListeners(computeEffect)
 
     // remove all references to connectedSignal
-    let fn = computeEffect.fn
-    signals.remove(fn)
+    if (computeEffect.fn) {
+        signals.delete(computeEffect.fn)
+    }
 
     effectMap.delete(connectedSignal)
-
     // if no other references to connectedSignal exist, it will be garbage collected
 }
 
@@ -454,6 +532,7 @@ export function destroy(connectedSignal) {
  * @result mixed the result of the fn() function call
  */
 export function batch(fn) {
+    assertFunction(fn, 'batch')
     batchMode++
     let result
     try {
@@ -496,6 +575,12 @@ function runBatchedListeners() {
  * @returns signal with the result of the effect function fn
  */
 export function throttledEffect(fn, throttleTime) {
+    assertFunction(fn, 'throttledEffect')
+    if (!Number.isFinite(throttleTime) || throttleTime < 0) {
+        throw new TypeError(
+            `simplyflow/state: throttledEffect() expects throttleTime to be a non-negative number`
+        )
+    }
     if (effectStack.findIndex(f => fn==f)!==-1) {
         throw new Error('Recursive update() call', {cause:fn})
     }
@@ -509,18 +594,41 @@ export function throttledEffect(fn, throttleTime) {
         signals.set(fn, connectedSignal)
     }
 
-    let throttled = false
+    let throttledUntil = 0
     let hasChange = true
+    let timeout = null
+
+    function schedule() {
+        if (timeout) {
+            return
+        }
+
+        const delay = Math.max(0, throttledUntil - Date.now())
+
+        timeout = globalThis.setTimeout(() => {
+            timeout = null
+
+            if (hasChange) {
+                computeEffect()
+            }
+        }, delay)
+    }
+
     // this is the function that is called automatically
     // whenever a signal dependency changes
     const computeEffect = function computeEffect() {
-        if (signalStack.findIndex(s => s==connectedSignal)!==-1) {
-            throw new Error('Cyclical dependency in update() call', { cause: fn})
-        }
-        if (throttled && throttled>Date.now()) {
+        const now = Date.now()
+
+        if (throttledUntil > now) {
             hasChange = true
+            schedule()
             return
         }
+
+        if (signalStack.findIndex(s => s==connectedSignal)!==-1) {
+            throw new Error('Cyclical dependency in update() call', { cause: fn})
+        }
+
         // remove all dependencies (signals) from previous runs 
         clearListeners(computeEffect)
         // record new dependencies on this run
@@ -547,12 +655,8 @@ export function throttledEffect(fn, throttleTime) {
                 connectedSignal.current = result
             }
         }
-        throttled = Date.now()+throttleTime
-        globalThis.setTimeout(() => {
-            if (hasChange) {
-                computeEffect()
-            }
-        }, throttleTime)
+        throttledUntil = Date.now()+throttleTime
+        schedule()
     }
     // run the computEffect immediately upon creation
     computeEffect()
@@ -565,6 +669,12 @@ export function throttledEffect(fn, throttleTime) {
 // on clock.tick() (or clock.time++) run only the clock.needsUpdate effects 
 // (first create a copy and reset clock.needsUpdate, then run effects)
 export function clockEffect(fn, clock) {
+    assertFunction(fn, 'clockEffect')
+    if (!clock || typeof clock !== 'object' || typeof clock.time !== 'number') {
+        throw new TypeError(
+            `simplyflow/state: clockEffect() expects a clock object with a numeric .time property`
+        )
+    }
     let connectedSignal = signals.get(fn)
     if (!connectedSignal) {
         connectedSignal = signal({
@@ -623,6 +733,7 @@ export function clockEffect(fn, clock) {
  * @result mixed
  */
 export function untracked(fn) {
+    assertFunction(fn, 'untracked')
     const pos = computeStack.length-1
     const remember = computeStack[pos]
     computeStack[pos] = false
@@ -635,7 +746,6 @@ export function untracked(fn) {
 
 /**
  * This function will created a copy of the input, recursive if deep==true
- * It will replace any non-clonable values with null
  * It will replace signals with a clone of their target
  * It will keep cyclical references intact
  * @param value Object
@@ -655,16 +765,16 @@ export function clone(value, deep=false)
                     return value
                 }
                 if (Array.isArray(value)) {
-                    let result = []
+                    const result = []
                     if (!deep) {
-                        result = value.slice()
-                        seen.set(value, result)
-                        return result
+                        return value.slice()
                     }
+
                     seen.set(value, result)
-                    for (const key of value) {
-                        result[key] = innerClone(value[key])
+                    for (let i=0; i<value.length; i++) {
+                        result[i] = innerClone(value[i])
                     }
+                    return result
                 } else if (!value.constructor || value.constructor===Object) {
                     let result = {}
                     if (!value.constructor) {
@@ -681,7 +791,7 @@ export function clone(value, deep=false)
                 }
             break
             default:
-                return null // ignore non-cloneable values
+                return value // primitive
             break
         }
     }

package/src/symbols.mjs

@@ -0,0 +1,8 @@
+export const DEP = {
+    ITERATE:  Symbol.for('@simplyedit/simplyflow.iterate'),
+    XRAY:     Symbol.for('@simplyedit/simplyflow.xRay'),
+    SIGNAL:   Symbol.for('@simplyedit/simplyflow.Signal'),
+    TEMPLATE: Symbol.for('@simplyedit/simplyflow.bindTemplate'),
+    LENGTH:   'length',
+    SIZE:     'size'
+}