@es-joy/jsoe 0.3.0 → 0.4.1

package/src/formats/structuredCloning.js

@@ -1,19 +1,29 @@
+import {
+  Typeson, unescapeKeyPathComponent, structuredCloningThrowing
+} from '../vendor-imports.js';
+
 import Formats from '../formats.js';
 import Types from '../types.js';
 import {buildTypeChoices} from '../typeChoices.js';
-import {
-  Typeson, unescapeKeyPathComponent, structuredCloningThrowing
-} from '../../vendor/typeson-registry/dist/index.js';
 import {
   typesonPathToJSONPointer
 } from '../utils/jsonPointer.js';
 
-import * as json from './json.js';
+import json from './json.js';
 
 /**
- * @callback EncapsulateObserver
- * @param {TypesonObserver} observerObj
- * @returns {void}
+ * @typedef {(info: {
+ *   propName: string,
+ *   type: import('../types.js').AvailableType,
+ *   value: import('../formats.js').StructuredCloneValue,
+ *   bringIntoFocus?: boolean,
+ *   schemaContent?: object,
+ *   schemaState?: import('../types.js').GetPossibleSchemasForPathAndType
+ * }) => Element} AddAndSetArrayElement
+ */
+
+/**
+ * @typedef {import('typeson-registry').ObserverData} EncapsulateObserver
  */
 
 /**
@@ -22,9 +32,17 @@ import * as json from './json.js';
  */
 const encapsulateObserver = (stateObj) => {
   const {
-    typeNamespace, readonly, format, schemaContent,
+    typeNamespace, readonly, format: frmt, schemaContent,
     getPossibleSchemasForPathAndType
   } = stateObj;
+
+  const format = /** @type {import('../formats.js').AvailableFormat} */ (frmt);
+
+  /**
+   * @type {{[key: string]: Element & {
+   *   $addAndSetArrayElement: AddAndSetArrayElement
+   * }}}
+   */
   const parents = {};
   return (observerObj) => {
     const {
@@ -62,6 +80,7 @@ const encapsulateObserver = (stateObj) => {
 
     // console.log('observerObj', observerObj);
 
+    /** @type {import('../types.js').AvailableType} */
     let newType;
     let newValue = value;
 
@@ -79,11 +98,17 @@ const encapsulateObserver = (stateObj) => {
     } else {
       try {
         newType = canonicalToAvailableType(
-          format, state, type, value
+          format,
+          state,
+          /**
+           * @type {import('../types.js').AvailableType}
+           */
+          (type),
+          value
         ); // Todo (low): Add state for second argument
       } catch (err) {
         console.log('err', type, err);
-        stateObj.error = err;
+        stateObj.error = /** @type {Error} */ (err);
         return;
       }
     }
@@ -123,7 +148,10 @@ const encapsulateObserver = (stateObj) => {
         //     type wanting the serialized data
         replaced
       });
-      parents[''] = stateObj.rootUI;
+      parents[''] = /**
+      * @type {Element &
+      *   {$addAndSetArrayElement: AddAndSetArrayElement}}
+      */ (stateObj.rootUI);
       return;
     }
 
@@ -140,9 +168,10 @@ const encapsulateObserver = (stateObj) => {
       //   for circulars there?), could change Typeson to report `readonly`
       //   for the nested items, in which case, we could block out `readonly`
       //   instead of doing this here
-      if (!ui || !ui.$addAndSetArrayElement) {
+      if (!ui || !('$addAndSetArrayElement' in ui)) {
         return;
       }
+
       const root = ui.$addAndSetArrayElement({
         propName: arrayOrObjectPropertyName,
         type: newType,
@@ -160,12 +189,27 @@ const encapsulateObserver = (stateObj) => {
         */
       });
       if (!readonly) {
-        Types.setValue({type: newType, root, value: newValue});
-        Types.validate({type: newType, root, topRoot: stateObj.rootUI});
+        Types.setValue({
+          type: newType,
+          // eslint-disable-next-line object-shorthand -- TS
+          root: /** @type {HTMLDivElement} */ (root),
+          value: newValue
+        });
+        Types.validate({
+          type: newType,
+          // eslint-disable-next-line object-shorthand -- TS
+          root: /** @type {HTMLDivElement} */ (root),
+          topRoot: /** @type {HTMLDivElement} */ (stateObj.rootUI)
+        });
       }
 
       if (hasChildren) {
-        parents[keypath] = root;
+        parents[keypath] = /**
+          * @type {Element &
+          *   {$addAndSetArrayElement: AddAndSetArrayElement}}
+          */ (
+            root
+          );
       }
     });
   };
@@ -183,23 +227,37 @@ const replaceTypes = (originTypes, replacements) => {
 };
 
 /**
- * @param {string} format
+ * @param {import('../formats.js').AvailableFormat} format
  * @param {string} state
- * @param {string} valType
- * @param {ArbitraryValue} v
+ * @param {import('../types.js').AvailableType} valType
+ * @param {import('../formats.js').StructuredCloneValue} v
  * @throws {Error}
- * @returns {string}
+ * @returns {import('../types.js').AvailableType}
  */
 const canonicalToAvailableType = (format, state, valType, v) => {
   const frmt = Formats.availableFormats[format];
   const {getTypesForState, convertFromTypeson, testInvalid} = frmt;
   const allowableTypes = getTypesForState.call(frmt, state);
+  /* istanbul ignore if -- Guard */
+  if (!allowableTypes) {
+    throw new Error('Unexpected undefined type for state');
+  }
+
+  /**
+   * @type {import('../types.js').AvailableType|undefined}
+   */
   let ret;
   console.log('format, state, valType, v', format, state, valType, v);
+
+  /**
+   * @param {string} newValType
+   * @throws {Error}
+   * @returns {never}
+   */
   const isInvalid = (newValType) => {
     console.log('newValType', newValType);
     const err = new Error('Invalid');
-    err.newValType = newValType;
+    /** @type {Error & {newValType: string}} */ (err).newValType = newValType;
     throw err;
   };
   if (convertFromTypeson) {
@@ -218,13 +276,17 @@ const canonicalToAvailableType = (format, state, valType, v) => {
     }
     return false;
   })) {
-    return ret;
+    return /** @type {import('../types.js').AvailableType} */ (ret);
   }
   console.log('ret', ret);
   allowableTypes.some((allowableType) => {
+    // eslint-disable-next-line max-len -- Long
+    const typeObj = /** @type {import('../types.js').TypeObject & {childTypes: string[]}} */ (
+      Types.availableTypes[allowableType]
+    );
     const {
       valueMatch, superType, childTypes
-    } = Types.availableTypes[allowableType];
+    } = typeObj;
     if (
       (superType && valueMatch &&
         // Currently using for `true` and `false`
@@ -245,95 +307,87 @@ const canonicalToAvailableType = (format, state, valType, v) => {
 
 /**
  * @callback FormatIterator
- * @param {StructuredCloneValue} records
+ * @param {import('../formats.js').StructuredCloneValue} records
  * @param {import('../types.js').StateObject} stateObj
  * @returns {Promise<Element>}
  */
 
-/**
- * @type {FormatIterator}
- */
-export const iterate = (records, stateObj) => {
-  console.log('records', records);
-  if (!stateObj.format) {
-    stateObj.format = 'structuredCloning';
-  }
-  // Todo: Replace this with async typeson?
-  // eslint-disable-next-line promise/avoid-new
-  return new Promise((resolve, reject) => {
-    const typeson = new Typeson({
-      encapsulateObserver: encapsulateObserver(stateObj)
-    }).register(structuredCloningThrowing);
-    typeson.encapsulate(records);
-    // Todo (low): We might want to run async encapsulate for
-    //   async types (and put this after Promise resolves)
-    if (stateObj.error) {
-      reject(stateObj.error);
-    } else {
-      resolve(stateObj.rootUI);
+/** @type {import('../formats.js').Format} */
+const structuredCloning = {
+  iterate (records, stateObj) {
+    console.log('records', records);
+    if (!stateObj.format) {
+      stateObj.format = 'structuredCloning';
     }
-  });
-};
-
-/**
- * @param {string} state
- * @returns {string[]}
- */
-export const getTypesForState = function (state) {
-  if (state && Types.contexts.structuredCloning[state]) {
-    const typesForFormat = this.getTypesForState() ||
-      /* istanbul ignore next -- types should be an array */
-      [];
-    Types.contexts.structuredCloning[state].forEach(({type, after}) => {
-      const precedingIdx = typesForFormat.indexOf(after);
-      typesForFormat.splice(precedingIdx + 1, 0, type);
+    // Todo: Replace this with async typeson?
+    // eslint-disable-next-line promise/avoid-new
+    return new Promise((resolve, reject) => {
+      const typeson = new Typeson({
+        encapsulateObserver: encapsulateObserver(stateObj)
+      }).register(structuredCloningThrowing);
+      typeson.encapsulate(records);
+      // Todo (low): We might want to run async encapsulate for
+      //   async types (and put this after Promise resolves)
+      if (stateObj.error) {
+        reject(stateObj.error);
+      } else {
+        resolve(/** @type {Required<import('../types.js').StateObject>} */ (
+          stateObj
+        ).rootUI);
+      }
     });
-    return typesForFormat;
-  }
-  return this.types();
-  /*
-  // Todo (low): These need to specify their own inner contexts
-  if (['map', 'set'].includes(state)) {return;}
-  if ('int8array', 'uint8array', 'uint8clampedarray',
-    'int16array', 'uint16array', 'int32array',
-    'uint32array', 'float32array', 'float64array'
-  ).includes(state)) {return;}
-  */
-};
-
-/**
- * @returns {string[]}
- */
-export const types = () => {
-  const jsonTypes = json.types();
-  replaceTypes(jsonTypes, [
-    [
-      'array',
-      // 'sparseArrays',
-      'arrayNonindexKeys'
-    ]
-  ]);
-  return [
-    // This type is only for throwing upon cloning errors:
-    // 'checkDataCloneException'
-    // This type might be supported by evaluable JS or config passed in:
-    // 'userObject'
-    ...jsonTypes,
-    'undef', // Explicit undefined only
-    'bigint',
-    'SpecialNumber', // '`NaN`, `Infinity`, `-Infinity`'},
-    'date',
-    'regexp',
-    'BooleanObject',
-    'NumberObject',
-    'StringObject',
-    'blobHTML'
-    // Ok, but will need some work
-    //     'map', 'set',
-    //     'blob', 'file', 'filelist'
-    //     'arraybuffer', 'arraybufferview'
-    //     'dataview', 'imagedata', 'imagebitmap',
+  },
+  getTypesForState (state) {
+    if (state && Types.contexts.structuredCloning[state]) {
+      const typesForFormat = this.getTypesForState() ||
+        /* istanbul ignore next -- types should be an array */
+        [];
+      Types.contexts.structuredCloning[state].forEach(({type, after}) => {
+        const precedingIdx = typesForFormat.indexOf(after);
+        typesForFormat.splice(precedingIdx + 1, 0, type);
+      });
+      return typesForFormat;
+    }
+    return this.types();
     /*
+    // Todo (low): These need to specify their own inner contexts
+    if (['map', 'set'].includes(state)) {return;}
+    if ('int8array', 'uint8array', 'uint8clampedarray',
+      'int16array', 'uint16array', 'int32array',
+      'uint32array', 'float32array', 'float64array'
+    ).includes(state)) {return;}
+    */
+  },
+  types () {
+    const jsonTypes = json.types();
+    replaceTypes(jsonTypes, [
+      [
+        'array',
+        // 'sparseArrays',
+        'arrayNonindexKeys'
+      ]
+    ]);
+    return [
+      // This type is only for throwing upon cloning errors:
+      // 'checkDataCloneException'
+      // This type might be supported by evaluable JS or config passed in:
+      // 'userObject'
+      ...jsonTypes,
+      'undef', // Explicit undefined only
+      'bigint',
+      'SpecialNumber', // '`NaN`, `Infinity`, `-Infinity`'},
+      'date',
+      'regexp',
+      'BooleanObject',
+      'NumberObject',
+      'StringObject',
+      'blobHTML'
+      // Ok, but will need some work
+      //     'map', 'set',
+      //     'blob', 'file', 'filelist'
+      //     'arraybuffer', 'arraybufferview'
+      //     'dataview', 'imagedata', 'imagebitmap',
+      /*
               // Typed Arrays
               'int8array',
               'uint8array',
@@ -350,5 +404,8 @@ export const types = () => {
               'IntlDateTimeFormat',
               'IntlNumberFormat'
               */
-  ];
+    ];
+  }
 };
+
+export default structuredCloning;

package/src/formats.js

@@ -1,20 +1,43 @@
-import * as indexedDBKey from './formats/indexedDBKey.js';
-import * as json from './formats/json.js';
-import * as structuredCloning from './formats/structuredCloning.js';
+import indexedDBKey from './formats/indexedDBKey.js';
+import json from './formats/json.js';
+import structuredCloning from './formats/structuredCloning.js';
+
+/**
+ * An arbitrary Structured Clone, JSON, etc. value.
+ * @typedef {any} StructuredCloneValue
+ */
 
 /* schema:
-const getTypeForFormatStateAndValue = ({format, state, value}) => {
+export const getTypeForFormatStateAndValue = ({format, state, value}) => {
   const valType = new Typeson().register(
     structuredCloningThrowing
   ).rootTypeName(value);
   return canonicalToAvailableType(format, state, valType, value);
 };
-Formats.getTypeForFormatStateAndValue = getTypeForFormatStateAndValue;
 */
 
+/**
+ * @typedef {"indexedDBKey"|"json"|"structuredCloning"} AvailableFormat
+ */
+
+/**
+ * @typedef {{
+ *   types: () => (import('./types.js').AvailableType)[],
+ *   testInvalid?: (
+ *     newType: string, value: Date|Array<StructuredCloneValue>
+ *   ) => boolean|undefined,
+ *   convertFromTypeson?: (
+ *     typesonType: import('./types.js').AvailableType
+ *   ) => import('./types.js').AvailableType|undefined,
+ *   iterate: import('./formats/structuredCloning.js').FormatIterator,
+ *   getTypesForState: (state?: string) => undefined|
+ *     (import('./types.js').AvailableType)[]
+ * }} Format
+ */
+
 // Using methods ensure we have fresh copies
 const Formats = {
-  availableFormats: {
+  availableFormats: /** @type {{[key: string]: Format}} */ ({
     indexedDBKey,
     json,
     // Todo (readme): these too? getTypesForState(state)
@@ -23,17 +46,22 @@ const Formats = {
     schemaOnly,
     */
     structuredCloning
-  }
+  })
 };
 
 /**
- * @type {import('./formats/structuredCloning.js').FormatIterator}
+ * @param {AvailableFormat} format
+ * @param {StructuredCloneValue} record
+ * @param {import('./types.js').StateObject} stateObj
+ * @returns {Promise<Element>}
  */
 export async function getControlsForFormatAndValue (format, record, stateObj) {
   return await Formats.availableFormats[format]
     .iterate(record, {
-      format,
-      ...stateObj
+      ...stateObj,
+      // This had been before `stateObj` but should apparently have precedence
+      //   or just avoid passing `format` to this function
+      format
     });
 }
 

package/src/fundamentalTypes/BooleanObjectType.js

@@ -1,7 +1,7 @@
 import {$e, $$e} from '../utils/templateUtils.js';
 
 /**
- * @type {import('../types.js').TypeObject}
+ * @type {import('../types.js').TypeObject & {ct: number}}
  */
 const BooleanObjectType = {
   option: ['BooleanObject'],
@@ -13,13 +13,15 @@ const BooleanObjectType = {
     };
   },
   getInput ({root}) {
-    return $e(root, 'input');
+    return /** @type {HTMLInputElement} */ ($e(root, 'input'));
   },
   getValue ({root}) {
-    return this.toValue(String(this.getInput({root}).checked)).value;
+    return this.toValue(String(/** @type {HTMLInputElement} */ (
+      this.getInput({root})
+    ).checked)).value;
   },
   setValue ({root, value}) {
-    const inputs = $$e(root, 'input');
+    const inputs = /** @type {HTMLInputElement[]} */ ($$e(root, 'input'));
     const input = inputs[value.valueOf() ? 0 : 1];
     input.checked = true;
   },

package/src/fundamentalTypes/NumberObjectType.js

@@ -1,5 +1,5 @@
 import {$e} from '../utils/templateUtils.js';
-import Types from '../types.js';
+import numberType from './numberType.js';
 
 /**
  * @type {import('../types.js').TypeObject}
@@ -12,10 +12,12 @@ const NumberObjectType = {
     return {value: new Number(s)};
   },
   validate ({root}) {
-    return Types.availableTypes.number.validate({root});
+    return /** @type {Required<import('../types.js').TypeObject>} */ (
+      numberType
+    ).validate({root});
   },
   getInput ({root}) {
-    return $e(root, 'input');
+    return /** @type {HTMLInputElement} */ ($e(root, 'input'));
   },
   getValue ({root}) {
     return this.toValue(this.getInput({root}).value).value;

package/src/fundamentalTypes/StringObjectType.js

@@ -12,7 +12,7 @@ const StringObjectType = {
   },
   option: ['StringObject'],
   getInput ({root}) {
-    return $e(root, 'textarea');
+    return /** @type {HTMLTextAreaElement} */ ($e(root, 'textarea'));
   },
   getValue ({root}) {
     return this.toValue(this.getInput({root}).value).value;

package/src/fundamentalTypes/arrayReferenceType.js

@@ -5,13 +5,16 @@ import {
 } from '../utils/jsonPointer.js';
 
 /**
- * @type {import('../types.js').TypeObject}
+ * @type {import('../types.js').TypeObject & {type: "array"}}
  */
 const arrayReferenceType = {
   option: ['Array reference'],
   type: 'array',
   stringRegex: /^arrayRef\((?:|\/[^)]*)\)$/u,
-  toValue (s, {rootHolder, parent, parentPath}) {
+  toValue (s, info) {
+    const {
+      rootHolder, parent, parentPath
+    } = /** @type {import('../types.js').RootInfo} */ (info);
     const path = s.slice(`${this.type}Ref(`.length, -1);
     rootHolder.push([this.type, parent, parentPath, path]);
     return {assign: false};
@@ -37,7 +40,7 @@ const arrayReferenceType = {
     }
   },
   getInput ({root}) {
-    return $e(root, 'input');
+    return /** @type {HTMLInputElement} */ ($e(root, 'input'));
   },
   setValue ({root, value}) {
     this.getInput({root}).value = value;
@@ -50,7 +53,7 @@ const arrayReferenceType = {
       if (!stateObj.paths) {
         stateObj.paths = {};
       }
-      stateObj.paths[currentPath] = {
+      stateObj.paths[/** @type {string} */ (currentPath)] = {
         referentPath,
         // Todo (low): Should be utilized along with
         //   other validation checking
@@ -64,6 +67,11 @@ const arrayReferenceType = {
     const {type} = this;
     const input = this.getInput({root});
     const path = input.value;
+
+    /**
+     * @param {string|undefined} message
+     * @returns {{valid: false, message: string|undefined}}
+     */
     const invalidMessage = (message) => {
       return {valid: false, message};
     };
@@ -89,7 +97,7 @@ const arrayReferenceType = {
         'arrayNonindexKeys'
         // 'sparseArrays'
       ].includes(
-        Types.getTypeForRoot(referent)
+        /** @type {string} */ (Types.getTypeForRoot(referent))
       );
     };
     let message;
@@ -101,19 +109,23 @@ const arrayReferenceType = {
         //    order)
         const legends = DOM.filterChildElements(
           // Ensure we are only getting one array level at a time
-          $e(referent, '.arrayItems'), ['fieldset', 'legend']
+          /** @type {Element} */ ($e(referent, '.arrayItems')),
+          ['fieldset', 'legend']
         );
         const childPropertyValues = legends.map(
-          (legend) => getPropertyValueFromLegend(legend)
+          (legend) => getPropertyValueFromLegend(
+            /** @type {HTMLLegendElement} */ (legend)
+          )
         );
         const partMatchIndex = childPropertyValues.indexOf(pathPart);
         if (partMatchIndex === -1) {
           message = "Specified path doesn't exist";
           return true;
         }
-        referent = $e(
-          legends[partMatchIndex].parentElement, 'div[data-type]'
-        );
+        referent = /** @type {HTMLDivElement} */ ($e(
+          /** @type {Element} */ (legends[partMatchIndex].parentElement),
+          'div[data-type]'
+        ));
         if (referent === root) {
           message = "Can't reference self";
           return true;
@@ -143,11 +155,11 @@ const arrayReferenceType = {
     // Condition to confirm that referenced element is an array or
     //    object (or reference) with the designated `type`
     const referentType = Types.getTypeForRoot(referent);
-    const referentBaseType = [
+    const referentBaseType = /** @type {(string|null|undefined)[]} */ ([
       'array',
       'arrayNonindexKeys'
       // 'sparseArrays'
-    ].includes(referentType)
+    ]).includes(referentType)
       ? 'array'
       : (referentType === 'object'
         ? 'object'
@@ -165,11 +177,14 @@ const arrayReferenceType = {
     };
   },
   validateAll ({topRoot}) {
-    const type = `${this.type}Reference`;
+    const type = /** @type {import('../types.js').AvailableType} */ (
+      `${this.type}Reference`
+    );
     $$e(topRoot, `div[data-type="${type}"]`).forEach((root) => {
       Types.validate({
         type,
-        root,
+        // eslint-disable-next-line object-shorthand -- TS
+        root: /** @type {HTMLDivElement} */ (root),
         topRoot
       });
     });