@shortfuse/materialdesignweb 0.8.0 → 0.9.1

package/core/observe.js

@@ -1,65 +1,63 @@
 import { attrNameFromPropName } from './dom.js';
 import { buildMergePatch, hasMergePatch } from './jsonMergePatch.js';
 
-/** @typedef {import('./typings.js').ObserverPropertyType} ObserverPropertyType */
-
-/** @return {null} */
-const DEFAULT_NULL_PARSER = () => null;
+/** @typedef {'string' | 'boolean' | 'map' | 'set' | 'float' | 'integer' | 'object' | 'function' | 'array'} ObserverPropertyType */
 
 /**
- * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean#boolean_coercion
- * @param {any} v
- * @return {boolean}
+ * @template {ObserverPropertyType} T
+ * @typedef {(
+ * T extends 'boolean' ? boolean
+ * : T extends 'string' ? string
+ * : T extends 'float' | 'integer' ? number
+ * : T extends 'array' ? any[]
+ * : T extends 'object' ? any
+ * : T extends 'function' ? (...args:any) => any
+ * : unknown
+ * )} ParsedObserverPropertyType
  */
-const DEFAULT_BOOLEAN_PARSER = (v) => !!v;
 
 /**
- * Doesn't support `BigInt` types
- * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number#number_coercion
- * @param {any} v
- * @return {number}
- */
-const DEFAULT_NUMBER_PARSER = (v) => +v;
-
-/**
- * Doesn't support `Symbol` types
- * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String#string_coercion
- * @param {any} v
- * @return {string}
- */
-const DEFAULT_STRING_PARSER = (v) => `${v}`;
-
-/**
- * @template T
- * @param {T} o
- * @return {T}
- */
-const DEFAULT_OBJECT_PARSER = (o) => o;
-
-/**
- * @template T
- * @param {T} a
- * @param {T} b
- * @return {boolean} true if equal
- */
-const DEFAULT_OBJECT_COMPARATOR = (a, b) => !hasMergePatch(a, b);
-
-/**
- * Always invoke change on set
- * @template T
- * @param {T} a
- * @param {T} b
- * @return {boolean} true if equal
+ * @template {ObserverPropertyType} T1
+ * @template {any} T2
+ * @template {Object} [C=any]
+ * @typedef {Object} ObserverOptions
+ * @prop {T1} [type]
+ * @prop {boolean} [enumerable]
+ * @prop {boolean|'write'|'read'} [reflect]
+ * @prop {string} [attr]
+ * @prop {boolean} [readonly]
+ * Defaults to false if type is boolean
+ * @prop {boolean} [nullable]
+ * @prop {T2} [empty]
+ * @prop {T2} [value]
+ * @prop {(this:C, data:Partial<C>, fn?: () => T2) => T2} [get]
+ * Function used when null passed
+ * @prop {(this:C, value:any)=>T2} [parser]
+ * @prop {(this:C, value:null|undefined)=>T2} [nullParser]
+ * @prop {(this:C, value: T2, fn?:(value2: T2) => any) => any} [set]
+ * Function used when comparing
+ * @prop {(this:C, a:T2, b:T2)=> any} [diff]
+ * @prop {(this:C, a:T2, b:T2)=>boolean} [is]
+ * Simple callback
+ * @prop {(this:C, oldValue:T2, newValue:T2, changes:any)=>any} [changedCallback]
+ * Named callback
+ * @prop {(this:C, name:string, oldValue: T2, newValue: T2, changes:any) => any} [propChangedCallback]
+ * Attribute callback
+ * @prop  {(this:C, name:keyof C & string, oldValue: string, newValue: string) => any} [attributeChangedCallback]
+ * @prop {[keyof C & string, (this:C, ...args:any[]) => any][]} [watchers]
+ * @prop {Set<keyof C & string>} [props]
+ * @prop {WeakMap<C,T2>} [values]
+ * @prop {WeakMap<C, T2>} [computedValues]
+ * @prop {WeakSet<C>} [needsSelfInvalidation]
  */
-const DEFAULT_ARRAY_COMPARATOR = (a, b) => false;
 
 /**
- * @template T
- * @param {T} a
- * @param {T} b
- * @return {boolean} true if equal
+ * @template {ObserverPropertyType} T1
+ * @template {any} [T2=any]
+ * @template {Object} [C=any]
+ * @template {keyof C & string} [K=any]
+ * @typedef {ObserverOptions<T1, T2, C> & { key: K, values?: WeakMap<C, T2>; attrValues?: WeakMap<C, string> }} ObserverConfiguration
  */
-const DEFAULT_OBJECT_DIFF = (a, b) => buildMergePatch(a, b, 'reference');
 
 /**
  * @param {ObserverPropertyType} type
@@ -95,9 +93,11 @@ function emptyFromType(type) {
  * @return {T}
  */
 function buildProxy(proxyTarget, set, deepSet, prefix) {
+  // @ts-ignore
   proxyTarget ??= {};
   return new Proxy(proxyTarget, {
     get(target, p) {
+      // @ts-ignore
       const value = target[p];
       if (typeof p !== 'symbol') {
         const arg = prefix ? `${prefix}.${p}` : p;
@@ -107,7 +107,6 @@ function buildProxy(proxyTarget, set, deepSet, prefix) {
           set.add(arg);
         }
         if (typeof value === 'object' && value != null) {
-          console.debug('tried to arg poke object get', p, value);
           return buildProxy(value, set, deepSet, arg);
         }
       }
@@ -135,127 +134,225 @@ function buildProxy(proxyTarget, set, deepSet, prefix) {
 function defaultParserFromType(type) {
   switch (type) {
     case 'boolean':
-      return DEFAULT_BOOLEAN_PARSER;
+      /**
+       * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean#boolean_coercion
+       * @param {any} v
+       * @return {boolean}
+       */
+      return (v) => !!v;
     case 'integer':
       // Calls ToNumber(x)
       return Math.round;
     case 'float':
-      return DEFAULT_NUMBER_PARSER;
+      /**
+       * Doesn't support `BigInt` types
+       * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number#number_coercion
+       * @param {any} v
+       * @return {number}
+       */
+      return (v) => +v;
     case 'map':
       return Map;
     case 'set':
       return Set;
     case 'object':
-      return DEFAULT_OBJECT_PARSER;
     case 'array':
-      return DEFAULT_OBJECT_PARSER;
+      /**
+       * Reflect self
+       * @template T
+       * @param {T} o
+       * @return {T}
+       */
+      return (o) => o;
     default:
     case 'string':
-      return DEFAULT_STRING_PARSER;
+      /**
+       * Doesn't support `Symbol` types
+       * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String#string_coercion
+       * @param {any} v
+       * @return {string}
+       */
+      return (v) => `${v}`;
   }
 }
 
+/**
+ * @param {(data: Partial<any>) => any} fn
+ * @param {...any} args
+ * @this {any}
+ * @return {{
+ *  props: {
+ *    this: string[],
+ *    args: string[][],
+ *  },
+ *  deepPropStrings: {
+ *   this: string[],
+ *   args: string[][],
+ *  },
+ *  deepProps: {
+ *   this: string[][],
+ *   args: string[][][],
+ *  },
+ *  defaultValue: any,
+ *  reusable: boolean,
+ * }}
+ */
+export function observeFunction(fn, ...args) {
+  /** @type {Set<string>} */
+  const thisPoked = new Set();
+  /** @type {Set<string>} */
+  const thisPokedDeep = new Set();
+
+  const argWatchers = args.map((arg) => {
+    const poked = new Set();
+    const pokedDeep = new Set();
+    const proxy = buildProxy(arg, poked, pokedDeep);
+    return { poked, pokedDeep, proxy };
+  });
+
+  const thisProxy = buildProxy(this ?? {}, thisPoked, thisPokedDeep);
+  const defaultValue = fn.apply(thisProxy, argWatchers.map((watcher) => watcher.proxy));
+  /* Arrow functions can reused if they don't poke `this` */
+  const reusable = fn.name ? true : !thisPoked.size;
+
+  return {
+    props: {
+      this: [...thisPoked],
+      args: argWatchers.map((watcher) => [...watcher.poked]),
+    },
+    deepPropStrings: {
+      this: [...thisPokedDeep],
+      args: argWatchers.map((watcher) => [...watcher.pokedDeep]),
+    },
+    deepProps: {
+      this: [...thisPokedDeep].map((deepPropString) => deepPropString.split('.')),
+      args: argWatchers.map((watcher) => [...watcher.pokedDeep].map((deepPropString) => deepPropString.split('.'))),
+    },
+    defaultValue,
+    reusable,
+  };
+}
+
+/** @return {null} */
+function defaultNullParser() { return null; }
+
 /**
  * @template {string} K
  * @template {ObserverPropertyType} [T1=any]
- * @template {any} [T2=import('./typings.js').ParsedObserverPropertyType<T1>]
+ * @template {any} [T2=ParsedObserverPropertyType<T1>]
+ * @template {Object} [C=any]
  * @param {K} name
- * @param {T1|import('./typings.js').ObserverOptions<T1,T2>} [typeOrOptions='string']
- * @param {any} object
- * @return {import('./typings.js').ObserverConfiguration<T1,T2,K> & import('./typings.js').ObserverOptions<T1,T2>}
+ * @param {T1|ObserverOptions<T1,T2>} [typeOrOptions='string']
+ * @param {any} [object]
+ * @return {ObserverConfiguration<T1,T2,C,K> & ObserverOptions<T1,T2,C>}
  */
 export function parseObserverOptions(name, typeOrOptions, object) {
-  /** @type {Partial<import('./typings.js').ObserverOptions<T1,T2>>} */
-  const options = {
-    ...((typeof typeOrOptions === 'string') ? { type: typeOrOptions } : typeOrOptions),
-  };
+  /** @type {Partial<ObserverOptions<T1,T2>>} */
+  const options = (typeof typeOrOptions === 'string')
+    ? { type: typeOrOptions }
+    : typeOrOptions;
+
+  let {
+    watchers, value, readonly,
+    empty, type,
+    enumerable, reflect, attr,
+    nullable, parser, nullParser,
+    get,
+    is, diff,
+    props,
+  } = options;
+
+  watchers ??= [];
+  readonly ??= false;
+
+  if (empty === undefined) {
+    empty = null;
+  }
 
-  let { enumerable, attr, reflect } = options;
-  const { type, empty, changedCallback } = options;
+  value ??= empty;
+
+  if (get && !props) {
+    // Custom `get` uses computed values.
+    // Invalidate computed value when dependent `prop` changes
+    const observeResult = observeFunction(get.bind(object), object, () => value);
+    value ??= observeResult.defaultValue;
+    const uniqueProps = new Set([
+      ...observeResult.props.this,
+      ...observeResult.props.args[0],
+    ]);
+    props = uniqueProps;
+  }
 
   /** @type {ObserverPropertyType} */
-  let parsedType = type;
-  if (parsedType == null) {
-    // Use .value or .get() to parse type
-    const value = options.value ?? empty ?? options.get?.call(object ?? {}, object ?? {});
+  if (!type) {
     if (value == null) {
-      parsedType = 'string';
+      // @ts-ignore
+      type = 'string';
     } else {
       const parsed = typeof value;
-      parsedType = (parsed === 'number')
+      // @ts-ignore
+      type = (parsed === 'number')
         ? (Number.isInteger(value) ? 'integer' : 'number')
         : parsed;
     }
   }
 
   enumerable ??= name[0] !== '_';
-  reflect ??= enumerable ? parsedType !== 'object' : (attr ? 'write' : false);
+  nullable ??= (type === 'boolean') ? false : (empty == null);
+  if (!nullable) {
+    empty ??= emptyFromType(type);
+    value ??= empty;
+  }
+
+  reflect ??= enumerable ? (type !== 'object') : (attr ? 'write' : false);
   attr ??= (reflect ? attrNameFromPropName(name) : null);
 
   // if defined ? value
   // else if boolean ? false
   // else if onNullish ? false
   // else if empty == null
-  const parser = options.parser ?? defaultParserFromType(parsedType);
-  let nullParser = options.nullParser;
-  let parsedEmpty = empty ?? null;
+  parser ??= defaultParserFromType(type);
   if (!nullParser) {
-    const nullable = options.nullable ?? (
-      parsedType === 'boolean'
-        ? false
-        : (empty == null));
     if (nullable) {
-      nullParser = DEFAULT_NULL_PARSER;
+      nullParser = defaultNullParser;
     } else {
-      parsedEmpty ??= emptyFromType(parsedType);
-      nullParser = parsedEmpty === null ? () => emptyFromType(parsedType) : () => parsedEmpty;
+      nullParser = (empty === null)
+        ? () => emptyFromType(type)
+        : () => empty;
     }
   }
 
-  let isFn = options.is;
-  if (!isFn) {
-    isFn = parsedType === 'object'
-      ? DEFAULT_OBJECT_COMPARATOR
-      : ((parsedType === 'array') ? DEFAULT_ARRAY_COMPARATOR : Object.is);
-  }
+  is ??= (type === 'object')
+    ? (a, b) => !hasMergePatch(a, b)
+    : ((type === 'array') ? () => false : Object.is);
 
-  const diff = 'diff' in options
-    ? options.diff
-    : ((parsedType === 'object') ? DEFAULT_OBJECT_DIFF : null);
+  if (diff === undefined) {
+    // @ts-ignore
+    diff = ((type === 'object') ? (a, b) => buildMergePatch(a, b, 'reference') : null);
+  }
 
   return {
     ...options,
-    type: parsedType,
-    is: isFn,
+    type,
+    is,
     diff,
     attr,
     reflect,
-    readonly: options.readonly ?? false,
+    readonly,
     enumerable,
-    value: options.value ?? parsedEmpty,
+    value,
     parser,
     nullParser,
     key: name,
-    changedCallback,
-    watchers: options.watchers ?? [],
-    values: options.values ?? new WeakMap(),
-    computedValues: options.computedValues ?? new WeakMap(),
-    attributeChangedCallback: options.attributeChangedCallback,
-    needsSelfInvalidation: options.needsSelfInvalidation ?? new WeakSet(),
+    // @ts-ignore Can't cast
+    props,
+    // @ts-ignore Can't cast
+    watchers,
   };
 }
 
-const INIT_SYMBOL = Symbol('PROP_INIT');
-
-/** @type {Partial<import('./typings.js').ObserverConfiguration<?,?,?>>} */
-const DEFAULT_OBSERVER_CONFIGURATION = {
-  nullParser: DEFAULT_NULL_PARSER,
-  is: Object.is,
-  INIT_SYMBOL,
-};
-
 /**
- * @this {import('./typings.js').ObserverConfiguration<?,?,?>}
+ * @this {ObserverConfiguration<?,?,?>}
  * @param {*} value
  */
 export function parsePropertyValue(value) {
@@ -263,120 +360,84 @@ export function parsePropertyValue(value) {
   newValue = value == null
     ? this.nullParser.call(this, value)
     : this.parser.call(this, newValue);
+  return newValue;
 }
 
 /**
- * @param {(data: Partial<any>) => any} fn
- * @param {...any} args
- * @this {any}
- * @return {{
- *  props: {
- *    this: string[],
- *    args: string[][],
- *  },
- *  deepPropStrings: {
- *   this: string[],
- *   args: string[][],
- *  },
- *  deepProps: {
- *   this: string[][],
- *   args: string[][][],
- *  },
- *  defaultValue: any,
- *  reusable: boolean,
- * }}
+ * @param {ObserverConfiguration<?,?,?,?>} config
+ * @param {any} oldValue
+ * @param {any} value
+ * @return {boolean} changed
  */
-export function observeFunction(fn, ...args) {
-  /** @type {Set<string>} */
-  const thisPoked = new Set();
-  /** @type {Set<string>} */
-  const thisPokedDeep = new Set();
+function detectChange(config, oldValue, value) {
+  if (config.get) {
+    // TODO: Custom getter vs parser
+  }
 
-  const argWatchers = args.map((arg) => {
-    const poked = new Set();
-    const pokedDeep = new Set();
-    const proxy = buildProxy(arg, poked, pokedDeep);
-    return { poked, pokedDeep, proxy };
-  });
+  // Compute real new value after parsing
+  const newValue = (value == null)
+    ? config.nullParser.call(this, value)
+    : config.parser.call(this, value);
 
-  const thisProxy = buildProxy(this ?? {}, thisPoked, thisPokedDeep);
-  const defaultValue = fn.apply(thisProxy, argWatchers.map((watcher) => watcher.proxy));
-  /* Arrow functions can reused if they don't poke `this` */
-  const reusable = fn.name ? true : !thisPoked.size;
+  // Default change is the newValue
+  let changes = newValue;
 
-  return {
-    props: {
-      this: [...thisPoked],
-      args: argWatchers.map((watcher) => [...watcher.poked]),
-    },
-    deepPropStrings: {
-      this: [...thisPokedDeep],
-      args: argWatchers.map((watcher) => [...watcher.pokedDeep]),
-    },
-    deepProps: {
-      this: [...thisPokedDeep].map((deepPropString) => deepPropString.split('.')),
-      args: argWatchers.map((watcher) => [...watcher.pokedDeep].map((deepPropString) => deepPropString.split('.'))),
-    },
-    defaultValue,
-    reusable,
-  };
+  // Null check
+  if (oldValue == null) {
+    if (newValue == null) {
+      // Both nullish
+      return false;
+    }
+  } else if (newValue != null) {
+    // Both non-null, compare
+    if (config.diff) {
+      // Custom change diff
+      changes = config.diff.call(this, oldValue, newValue);
+      if (changes == null) {
+        // No difference
+        return false;
+      }
+    } else if (config.is.call(this, oldValue, newValue)) {
+      // Non-equal
+      return false;
+    }
+  }
+
+  // Commit value
+  if (config.values) {
+    config.values.set(this, newValue);
+  } else {
+    config.values = new WeakMap([[this, newValue]]);
+  }
+
+  // Emit change
+
+  config.propChangedCallback?.call(this, config.key, oldValue, newValue, changes);
+  config.changedCallback?.call(this, oldValue, newValue, changes);
+
+  return true;
 }
 
 /**
  * @template {ObserverPropertyType} T1
  * @template {any} T2
- * @template {string} K
- * @template [C=any]
+ * @template {Object} C
+ * @template {keyof C & string} K
  * @param {C} object
  * @param {K} key
- * @param {import('./typings.js').ObserverOptions<T1, T2, C>} options
- * @return {import('./typings.js').ObserverConfiguration<T1,T2,K,C>}
+ * @param {ObserverOptions<T1, T2, C>} options
+ * @return {ObserverConfiguration<T1,T2,C,K>}
  */
 export function defineObservableProperty(object, key, options) {
-  /** @type {import('./typings.js').ObserverConfiguration<T1,T2,K,C>} */
-  const config = {
-    ...DEFAULT_OBSERVER_CONFIGURATION,
-    ...parseObserverOptions(key, options, object),
-    changedCallback: options.changedCallback,
-  };
+  const config = /** @type {ObserverConfiguration<T1,T2,C,K>} */ (
+    parseObserverOptions(key, options, object));
 
-  /**
-   * @param {T2} oldValue
-   * @param {T2} value
-   * @return {boolean} changed
-   */
-  function detectChange(oldValue, value) {
-    if (config.get) {
-      // TODO: Custom getter vs parser
-    }
-    let newValue = value;
-    newValue = (value == null)
-      ? config.nullParser.call(this, value)
-      : config.parser.call(this, newValue);
-
-    let changes = newValue;
-    if (oldValue == null) {
-      if (newValue == null) return false; // Both nullish
-    } else if (newValue != null) {
-      // if (oldValue === newValue) return false;
-      if (config.diff) {
-        changes = config.diff.call(this, oldValue, newValue);
-        if (changes == null) return false;
-      } else if (config.is.call(this, oldValue, newValue)) return false;
-    }
-
-    config.values.set(this, newValue);
-    // console.log(key, 'value.set', newValue);
-    config.propChangedCallback?.call(this, key, oldValue, newValue, changes);
-    config.changedCallback?.call(this, oldValue, newValue, changes);
-    return true;
-  }
   /**
    * @this {C}
    * @return {T2}
    */
   function internalGet() {
-    return config.values.has(this) ? config.values.get(this) : config.value;
+    return config.values?.has(this) ? config.values.get(this) : config.value;
   }
 
   /**
@@ -385,75 +446,66 @@ export function defineObservableProperty(object, key, options) {
    * @return {void}
    */
   function internalSet(value) {
+    // @ts-ignore
     const oldValue = this[key];
-    // console.log(key, 'internalSet', oldValue, '=>', value);
-    detectChange.call(this, oldValue, value);
+    detectChange.call(this, config, oldValue, value);
   }
 
   /** @return {void} */
   function onInvalidate() {
     // Current value is now invalidated. Recompute and check if changed
-    const oldValue = config.computedValues.get(this);
+    // eslint-disable-next-line no-multi-assign
+
+    const oldValue = config.computedValues?.get(this);
     const newValue = this[key];
-    // console.debug('observe: onInvalidate called for', key, oldValue, '=>', newValue, this);
-    config.needsSelfInvalidation.delete(this);
-    detectChange.call(this, oldValue, newValue);
+    config.needsSelfInvalidation?.delete(this);
+    detectChange.call(this, config, oldValue, newValue);
   }
 
-  if (config.get) {
-    // Custom `get` uses computed values.
-    // Invalidate computed value when dependent `prop` changes
-    const observeResult = observeFunction(config.get.bind(object), object, internalGet.bind(object));
-    const uniqueProps = new Set([
-      ...observeResult.props.this,
-      ...observeResult.props.args[0],
-    ]);
-    for (const prop of uniqueProps) {
-      // @ts-ignore keyof C
+  if (config.props) {
+    for (const prop of config.props) {
       config.watchers.push([prop, onInvalidate]);
     }
+  }
+
+  /**
+   * @this {C}
+   * @return {T2}
+   */
+  function cachedGet() {
+    const newValue = config.get.call(this, this, internalGet.bind(this));
+    // Store computed value internally. Used by onInvalidate to get previous value
+    // eslint-disable-next-line no-multi-assign
+    const computedValues = (config.computedValues ??= new WeakMap());
+    computedValues.set(this, newValue);
+    return newValue;
+  }
 
-    // TODO: May be able to cache value if props are present
+  /**
+   * @this {C}
+   * @param {T2} value
+   * @return {void}
+   */
+  function cachedSet(value) {
+    if (config.needsSelfInvalidation) {
+      config.needsSelfInvalidation.add(this);
+    } else {
+      config.needsSelfInvalidation = new WeakSet([this]);
+    }
+    const oldValue = this[key];
+    config.set.call(this, value, internalSet.bind(this));
+    const newValue = this[key];
+    if (!config.needsSelfInvalidation.has(this)) return;
+    config.needsSelfInvalidation.delete(this);
+    detectChange.call(this, config, oldValue, newValue);
   }
+
   /** @type {Partial<PropertyDescriptor>} */
   const descriptor = {
     enumerable: config.enumerable,
     configurable: true,
-    /**
-     * @this {C}
-     * @return {T2}
-     */
-    get() {
-      if (config.get) {
-        const newValue = config.get.call(this, this, internalGet.bind(this));
-        // Store computed value internally. Used by onInvalidate to get previous value
-        config.computedValues.set(this, newValue);
-        return newValue;
-      }
-      return internalGet.call(this);
-    },
-    /**
-     * @this {C}
-     * @param {T2} value
-     * @return {void}
-     */
-    set(value) {
-      if (value === INIT_SYMBOL) {
-        // console.log(key, 'returning due to INIT');
-        return;
-      }
-      if (config.set) {
-        config.needsSelfInvalidation.add(this);
-        const oldValue = this[key];
-        config.set.call(this, value, internalSet.bind(this));
-        const newValue = this[key];
-        if (!config.needsSelfInvalidation.has(this)) return;
-        config.needsSelfInvalidation.delete(this);
-        detectChange.call(this, oldValue, newValue);
-      } else {
-        internalSet.call(this, value);
-      }
-    },
+    get: config.get ? cachedGet : internalGet,
+    set: config.set ? cachedSet : internalSet,
   };
 
   Object.defineProperty(object, key, descriptor);