@es-joy/jsoe 0.24.3 → 0.25.1

package/src/formats/structuredCloning.js

@@ -1,5 +1,5 @@
 import {
-  Typeson, unescapeKeyPathComponent, structuredCloningThrowing,
+  Typeson, unescapeKeyPathComponent, structuredCloningForStorage,
   resurrectable as noneditable, symbol, promise, toStringTag
 } from '../vendor-imports.js';
 
@@ -7,9 +7,58 @@ import {buildTypeChoices} from '../typeChoices.js';
 import {
   typesonPathToJSONPointer
 } from '../utils/jsonPointer.js';
+import {tick} from '../utils/timing.js';
 
 import json from './json.js';
 
+/** @type {import('typeson').TypeSpecSet} */
+export const functionSpec = {
+  function: {
+    test (x) {
+      return typeof x === 'function';
+    },
+    replace (funcType) {
+      return '(' + funcType.toString() + ')';
+    },
+    revive (o) {
+      // eslint-disable-next-line no-eval -- User opted in
+      return eval(o);
+    }
+  }
+};
+
+export const structuredCloningJsoe = structuredCloningForStorage.filter(
+  (typeSpecSet) => {
+    return [
+      // Not yet supported within JSOE
+      'imagedata',
+      'imagebitmap',
+      'domquad',
+      'quotaexceedederror',
+      'webtransporterror',
+      'cryptokey',
+      'audiodata',
+      'encodedaudiochunk',
+      'encodedvideochunk',
+      'videoframe'
+    ].every((prop) => {
+      return !Object.hasOwn(typeSpecSet, prop);
+    });
+  }
+);
+
+/**
+ * A deferred child build registers its own element in `parents` only once its
+ *   own build has run. A deeper node's build can wake on the same tick and find
+ *   its parent not yet registered (async-replaced parents such as `file`,
+ *   `promise` or `blob` also push their builds out of depth order). Rather than
+ *   dropping such a node, its build re-checks `parents` across this many ticks
+ *   before concluding the parent genuinely does not exist (e.g. a value that was
+ *   promoted to the root UI).
+ * @type {number}
+ */
+const MAX_PARENT_WAIT_TICKS = 50;
+
 // We modify resurrectable in hopes an including application doesn't need it
 /** @type {import('typeson').TypeSpecSet} */ (
   noneditable.resurrectable
@@ -53,6 +102,11 @@ const encapsulateObserver = (stateObj) => {
 
   const format = /** @type {import('../formats.js').AvailableFormat} */ (frmt);
 
+  // Collects each deferred per-node UI build. `iterate` does not await these
+  //   (see the comment there); a caller that needs the fully-populated tree
+  //   awaits `stateObj.whenBuilt` after it has attached `rootUI`.
+  const pendingBuilds = (stateObj.pendingBuilds ||= []);
+
   /**
    * Matches keypaths to the HTML UI Element.
    * @type {{[key: string]: HTMLElement & {
@@ -63,7 +117,10 @@ const encapsulateObserver = (stateObj) => {
 
   /**
    * @type {{
-   *   [key: string]: [import('zodex').SzType, number|undefined]|undefined
+   *   [key: string]: [
+   *     import('zodexy').SzType,
+   *     number|undefined
+   *   ]|undefined
    * }}
    */
   const schemaParents = {};
@@ -71,6 +128,9 @@ const encapsulateObserver = (stateObj) => {
   /** @type {string[]} */
   const mapPaths = [];
 
+  /** @type {string[]} */
+  const atomicPaths = [];
+
   return (observerObj) => {
     const {
       type,
@@ -84,6 +144,13 @@ const encapsulateObserver = (stateObj) => {
       endIterateUnsetNumeric,
       clone
     } = observerObj;
+    if (atomicPaths.some((atomicPath) => {
+      return atomicPath === ''
+        ? keypath !== ''
+        : keypath.startsWith(`${atomicPath}.`);
+    })) {
+      return;
+    }
     if ('replaced' in observerObj) {
       return;
     }
@@ -104,7 +171,7 @@ const encapsulateObserver = (stateObj) => {
 
     // What other situations is this firing twice, and it
     //   shouldn't reach here?
-    if (observerObj.replacing && type === 'negativeZero') {
+    if (type === 'negativeZero' && observerObj.replacing) {
       return;
     }
 
@@ -172,17 +239,20 @@ const encapsulateObserver = (stateObj) => {
         // console.log('VVVV2',
         //   JSON.stringify(stateObj.schemaContent, null, 2));
       } catch (err) {
-        console.log('err', type, err);
+        console.log('err', type, err, value);
         stateObj.error = /** @type {Error} */ (err);
         return;
       }
     }
 
     const hasChildren = [
-      'array', 'object', 'set', 'map', 'tuple', 'record', 'filelist',
+      'array', 'object', 'set', 'map', 'filelist',
       // 'sparseArrays',
       'arrayNonindexKeys'
     ].includes(newType);
+    if (type === 'symbol' || type === 'file') {
+      atomicPaths.push(keypath);
+    }
 
     // Maps are followed up by arrays which we don't want as such;
     //  we track the paths to avoid reporting these child arrays
@@ -222,9 +292,9 @@ const encapsulateObserver = (stateObj) => {
         replaced
       });
       parents[''] = /**
-      * @type {HTMLElement &
-      *   {$addAndSetArrayElement: AddAndSetArrayElement}}
-      */ (stateObj.rootUI);
+                     * @type {HTMLElement &
+                     *   {$addAndSetArrayElement: AddAndSetArrayElement}}
+                     */ (stateObj.rootUI);
 
       if (schema) {
         schemaParents[''] = [schema, schemaIdx];
@@ -236,9 +306,9 @@ const encapsulateObserver = (stateObj) => {
       if (mapType) {
         /** @type {Map<any, any>} */ [...value].forEach((_, i) => {
           parents[i] = /**
-          * @type {HTMLElement &
-          *   {$addAndSetArrayElement: AddAndSetArrayElement}}
-          */ (stateObj.rootUI);
+                        * @type {HTMLElement &
+                        *   {$addAndSetArrayElement: AddAndSetArrayElement}}
+                        */ (stateObj.rootUI);
         });
       }
       return;
@@ -252,20 +322,47 @@ const encapsulateObserver = (stateObj) => {
     //   schema, schemaParents
     // );
 
-    // Todo (low): If could be async, use async encapsulate method
     // Todo (low): Handle `awaitingTypesonPromise` with place-holder
     // Todo (low): Handle `resolvingTypesonPromise` to replace place-holder
-    setTimeout(() => {
-      const ui = parents[parentPath];
-      // These errors occur, e.g., if `replacing` not first added and then
-      //   a converted object gets treated as the root UI (e.g., for `regexp`
-      //   or `blobHTML` at root)
-      // If there isn't a problem in Typeson with transmitting the `readonly`
-      //   status recursively down the object (should be no need to check
-      //   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
+    //
+    // Each node's UI build is deferred a tick (the parent element is not yet in
+    //   the document when the observer fires). The build now awaits its own
+    //   `setValue` before `validate` (previously `validate` ran synchronously
+    //   against a half-built DOM and threw). Each build promise is collected on
+    //   `stateObj.pendingBuilds` for a caller that wants to await the fully
+    //   populated tree; `iterate` itself does not await them (see below).
+    pendingBuilds.push((async () => {
+      // Defer one tick so the caller has attached `rootUI` (connection-dependent
+      //   init such as `blobHTML`/SCEditor relies on being in the document).
+      await tick();
+      // Then wait for this node's parent UI to be registered in `parents`. A
+      //   parent registers itself only after its own build runs, and
+      //   async-replaced parents (`file`/`promise`/`blob`) push their builds out
+      //   of depth order, so a child can still arrive first; re-check across
+      //   ticks instead of dropping the node on the first miss.
+      // A parent that is genuinely absent (e.g. a converted value promoted to
+      //   the root UI, as for `regexp`/`blobHTML` at root) never appears; after
+      //   the bound we give up and record it below rather than hang.
+      let ui = parents[parentPath];
+      for (
+        let waited = 0;
+        (!ui || !('$addAndSetArrayElement' in ui)) &&
+          waited < MAX_PARENT_WAIT_TICKS;
+        waited++
+      ) {
+        // eslint-disable-next-line no-await-in-loop -- Sequential by design
+        await tick();
+        ui = parents[parentPath];
+      }
       if (!ui || !('$addAndSetArrayElement' in ui)) {
+        if (!stateObj.buildWarnings) {
+          stateObj.buildWarnings = [];
+        }
+        stateObj.buildWarnings.push({
+          keypath,
+          type: newType,
+          reason: 'no parent UI registered'
+        });
         return;
       }
 
@@ -300,28 +397,14 @@ const encapsulateObserver = (stateObj) => {
         return;
       }
 
-      if (!readonly) {
-        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),
-          // We don't want focus when values auto-added
-          avoidReport: true
-        });
-      }
-
+      // Register this node as a parent for its descendants *before* awaiting
+      //   `setValue`, so child builds (already past their own `tick`) can find
+      //   it in `parents`.
       if (hasChildren) {
         parents[keypath] = /**
-          * @type {HTMLElement &
-          *   {$addAndSetArrayElement: AddAndSetArrayElement}}
-          */ (
+                            * @type {HTMLElement &
+                            *   {$addAndSetArrayElement: AddAndSetArrayElement}}
+                            */ (
             root
           );
 
@@ -331,13 +414,44 @@ const encapsulateObserver = (stateObj) => {
         if (mapType) {
           /** @type {Map<any, any>} */ [...value].forEach((_, i) => {
             parents[`${keypath}.${i}`] = /**
-            * @type {HTMLElement &
-            *   {$addAndSetArrayElement: AddAndSetArrayElement}}
-            */ (root);
+                                          * @type {HTMLElement &
+                                          *   {$addAndSetArrayElement: AddAndSetArrayElement}}
+                                          */ (root);
           });
         }
       }
-    });
+
+      if (!readonly) {
+        await types?.setValue({
+          type: newType,
+          root: /** @type {HTMLDivElement} */ (root),
+          value: newValue
+        });
+        types?.validate({
+          type: newType,
+          root: /** @type {HTMLDivElement} */ (root),
+          topRoot: /** @type {HTMLDivElement} */ (stateObj.rootUI),
+          // We don't want focus when values auto-added
+          avoidReport: true
+        });
+      }
+    // eslint-disable-next-line promise/prefer-await-to-then, promise/prefer-await-to-callbacks -- Convenient
+    })().catch((err) => {
+      // Auto-population is best-effort: a node whose deferred UI is still
+      //   settling (its guard throws `'Not yet instantiated'`) or a transient
+      //   build hiccup must not surface as an unhandled rejection. Genuine
+      //   schema/type errors are still reported via `stateObj.error`. Record
+      //   what was dropped so a caller (or test) can assert the tree built
+      //   fully instead of the failure being wholly invisible.
+      if (!stateObj.buildWarnings) {
+        stateObj.buildWarnings = [];
+      }
+      stateObj.buildWarnings.push({
+        keypath,
+        type: newType,
+        reason: /** @type {Error} */ (err)?.message ?? String(err)
+      });
+    }));
   };
 };
 
@@ -368,13 +482,16 @@ const replaceTypes = (originTypes, replacements) => {
  * @param {import('../formats.js').StructuredCloneValue} v The value being
  *   checked.
  * @param {string} arrayOrObjectPropertyName
- * @param {[import('zodex').SzType, number|undefined]|undefined} parentSchema
+ * @param {[
+ *   import('zodexy').SzType,
+ *   number|undefined
+ * ]|undefined} parentSchema
  * @param {import('../types.js').StateObject} stateObj The schema content
  *   being checked.
  * @throws {Error} May throw if data found to be invalid.
  * @returns {{
  *   newType: import('../types.js').AvailableArbitraryType,
- *   schema?: import('zodex').SzType|undefined,
+ *   schema?: import('zodexy').SzType|undefined,
  *   mustBeOptional?: boolean,
  *   schemaIdx?: number
  * }} Schema and type info.
@@ -392,6 +509,9 @@ const canonicalTypeToAvailableTypeAndSchema = (
   if (!allowableTypes) {
     throw new Error('Unexpected undefined type for state');
   }
+  if (valType === 'array' && allowableTypes.includes('arrayNonindexKeys')) {
+    valType = 'arrayNonindexKeys';
+  }
 
   /**
    * @type {import('../types.js').AvailableArbitraryType|undefined}
@@ -472,7 +592,7 @@ const canonicalTypeToAvailableTypeAndSchema = (
       return false;
     });
     if (ret === undefined) {
-      console.log('AALLLowableTypes', state, allowableTypes, '::', valType);
+      console.log('AALLLowableTypes', state, allowableTypes, '::', valType, v);
       return isInvalid(valType);
     }
   }
@@ -490,20 +610,7 @@ const structuredCloning = {
       stateObj.format = 'structuredCloning';
     }
 
-    const structuredCloningFixed = structuredCloningThrowing.filter(
-      (typeSpecSet) => {
-        return ![
-          // Not yet supported within JSOE
-          'imagedata',
-          'imagebitmap',
-          'cryptokey',
-          'domquad'
-        ].some((prop) => {
-          return Object.hasOwn(typeSpecSet, prop);
-        });
-      }
-    );
-    structuredCloningFixed.splice(
+    structuredCloningJsoe.splice(
       // Add after userObjects
       1,
       0,
@@ -520,31 +627,34 @@ const structuredCloning = {
         //    to regular demo and test; add tests
         stateObj.format === 'schema'
         ? [
-          ...structuredCloningFixed,
+          ...structuredCloningJsoe,
           symbol,
           promise,
-          {
-            function: {
-              test (x) {
-                return typeof x === 'function';
-              },
-              replace (funcType) {
-                return '(' + funcType.toString() + ')';
-              },
-              revive (o) {
-                // eslint-disable-next-line no-eval -- User opted in
-                return eval(o);
-              }
-            }
-          }
+          functionSpec
         ]
-        : structuredCloningFixed
+        : structuredCloningJsoe
     );
 
     await typeson.encapsulateAsync(records, null, {
       throwOnBadSyncType: false
     });
 
+    // The per-node builds run themselves (each is a self-executing async IIFE)
+    //   a tick later, once the caller has connected `rootUI`; the race that
+    //   used to crash — a node's synchronous `validate` running before its
+    //   asynchronous `setValue` had built the DOM — is fixed inside each build,
+    //   which now awaits `setValue` before `validate`, and a build no longer
+    //   drops itself when its parent is a tick behind (it re-checks `parents`
+    //   up to `MAX_PARENT_WAIT_TICKS`). We deliberately do not await the builds
+    //   here: blocking the return re-orders deferred, connection-dependent init
+    //   (e.g. `blobHTML`/SCEditor) ahead of the caller attaching `rootUI`.
+    //   Instead `stateObj.whenBuilt` resolves once every build has settled, for
+    //   a caller (or test) that needs the fully-populated tree; anything a
+    //   build could not attach is listed on `stateObj.buildWarnings`.
+    stateObj.whenBuilt = (async () => {
+      await Promise.allSettled(stateObj.pendingBuilds ?? []);
+    })();
+
     if (stateObj.error) {
       throw stateObj.error;
     }

package/src/formats.js

@@ -24,15 +24,15 @@ import schema from './formats/schema.js';
 /* schema:
 export const getTypeForFormatStateAndValue = ({format, state, value}) => {
   const valType = new Typeson().register(
-    structuredCloningThrowing
+    structuredCloningForStorage
   ).rootTypeName(value);
   return canonicalToAvailableType(format, state, valType, value);
 };
 */
 
 /**
- * @typedef {"indexedDBKey"|"json"|"structuredCloning"|
- *   "arbitraryJS"|"schema"} AvailableFormat
+ * @typedef {"indexedDBKey"|"json"|"structuredCloning"
+ *   |"arbitraryJS"|"schema"} AvailableFormat
  */
 
 /**
@@ -77,14 +77,26 @@ export const getTypeForFormatStateAndValue = ({format, state, value}) => {
  *   types: import('./types.js').default,
  *   v?: import('./formats.js').StructuredCloneValue,
  *   arrayOrObjectPropertyName?: string,
- *   parentSchema?: [import('zodex').SzType, number|undefined]|undefined,
+ *   parentSchema?: [
+ *     import('zodexy').SzType,
+ *     number|undefined
+ *   ]|undefined,
  *   stateObj?: import('./types.js').StateObject,
  * ) => {
  *   type: import('./types.js').AvailableArbitraryType|undefined
- *   schema?: import('zodex').SzType|undefined,
+ *   schema?: import('zodexy').SzType|undefined,
  *   mustBeOptional?: boolean,
  *   schemaIdx?: number
  * }} [convertFromTypeson]
+ * @property {(
+ *   types: import('./types.js').default,
+ *   schemaObject: import('./formatAndTypeChoices.js').ZodexSchema,
+ *   value: StructuredCloneValue
+ * ) => {valid: boolean, message?: string,
+ *   schema?: import('./formats/schema.js').ZodexSchema}} [validateValue]
+ * @property {(
+ *   schemaObject: import('./formats/schema.js').ZodexSchema
+ * ) => boolean} [isValueValidationRequired]
  */
 
 /**

package/src/fundamentalTypes/BooleanObjectType.js

@@ -1,5 +1,6 @@
 import {toStringTag} from '../vendor-imports.js';
 import {$e, $$e} from '../utils/templateUtils.js';
+import {schemaLabel} from '../utils/schemaMeta.js';
 
 /**
  * @type {import('../types.js').TypeObject & {ct: number}}
@@ -12,7 +13,6 @@ const BooleanObjectType = {
   },
   toValue (s) {
     return {
-      // eslint-disable-next-line @stylistic/max-len -- Long
       // eslint-disable-next-line no-new-wrappers, unicorn/new-for-builtins -- Deliberate creation here
       value: new Boolean(s === 'true')
     };
@@ -35,19 +35,18 @@ const BooleanObjectType = {
   viewUI ({value, specificSchemaObject}) {
     return ['i', {
       dataset: {type: 'BooleanObject'},
-      title: specificSchemaObject?.description ?? '(a Boolean Object)'
-    }, [specificSchemaObject ? `${value}` : `Boolean(${value})`]];
+      title: schemaLabel(specificSchemaObject) ?? '(a Boolean Object)'
+    }, [specificSchemaObject ? String(value) : `Boolean(${value})`]];
   },
   ct: 0,
   editUI ({
-    // eslint-disable-next-line @stylistic/max-len -- Long
     // eslint-disable-next-line no-new-wrappers, unicorn/new-for-builtins -- Deliberate creation here
     typeNamespace, specificSchemaObject, value = new Boolean(true)
   }) {
     this.ct++;
     return ['div', {
       dataset: {type: 'BooleanObject'},
-      title: specificSchemaObject?.description ?? 'Boolean object'
+      title: schemaLabel(specificSchemaObject) ?? 'Boolean object'
     }, [
       ['label', [
         'True',

package/src/fundamentalTypes/NumberObjectType.js

@@ -1,5 +1,6 @@
 import {toStringTag} from '../vendor-imports.js';
 import {$e} from '../utils/templateUtils.js';
+import {schemaLabel} from '../utils/schemaMeta.js';
 import numberType from './numberType.js';
 
 /**
@@ -12,7 +13,6 @@ const NumberObjectType = {
     return toStringTag(x) === 'Number' && typeof x === 'object';
   },
   toValue (s) {
-    // eslint-disable-next-line @stylistic/max-len -- Long
     // eslint-disable-next-line no-new-wrappers, unicorn/new-for-builtins -- Deliberate creation here
     return {value: new Number(s)};
   },
@@ -35,15 +35,15 @@ const NumberObjectType = {
   viewUI ({value, specificSchemaObject}) {
     return ['i', {
       dataset: {type: 'NumberObject'},
-      title: specificSchemaObject?.description ?? '(a Number Object)'
+      title: schemaLabel(specificSchemaObject) ?? '(a Number Object)'
     }, [
-      specificSchemaObject ? `${value}` : `Number(${value})`
+      specificSchemaObject ? String(value) : `Number(${value})`
     ]];
   },
   editUI ({typeNamespace, specificSchemaObject, value}) {
     return ['div', {
       dataset: {type: 'NumberObject'},
-      title: specificSchemaObject?.description ?? 'Number object'
+      title: schemaLabel(specificSchemaObject) ?? 'Number object'
     }, [
       ['input', {
         name: `${typeNamespace}-NumberObject`,

package/src/fundamentalTypes/StringObjectType.js

@@ -1,5 +1,6 @@
 import {toStringTag} from '../vendor-imports.js';
 import {$e} from '../utils/templateUtils.js';
+import {schemaLabel} from '../utils/schemaMeta.js';
 
 /**
  * @type {import('../types.js').TypeObject}
@@ -10,10 +11,8 @@ const StringObjectType = {
     return toStringTag(x) === 'String' && typeof x === 'object';
   },
   toValue (s) {
-    // eslint-disable-next-line @stylistic/max-len -- Long
     /* eslint-disable no-new-wrappers, unicorn/new-for-builtins -- Deliberate creation here */
     return {value: new String(s)};
-    // eslint-disable-next-line @stylistic/max-len -- Long
     /* eslint-enable no-new-wrappers, unicorn/new-for-builtins -- Deliberate creation here */
   },
   option: ['StringObject'],
@@ -31,7 +30,7 @@ const StringObjectType = {
   viewUI ({value, specificSchemaObject}) {
     return ['span', {
       dataset: {type: 'StringObject'},
-      title: specificSchemaObject?.description ?? '(a String Object)'
+      title: schemaLabel(specificSchemaObject) ?? '(a String Object)'
     }, [
       specificSchemaObject ? '' : ['i', ['String(']],
       ['span', [value.valueOf()]],
@@ -41,7 +40,7 @@ const StringObjectType = {
   editUI ({typeNamespace, specificSchemaObject, value = ''}) {
     return ['div', {
       dataset: {type: 'StringObject'},
-      title: specificSchemaObject?.description ?? 'String object'
+      title: schemaLabel(specificSchemaObject) ?? 'String object'
     }, [
       ['textarea', {name: `${typeNamespace}-StringObject`}, [value]]
     ]];

package/src/fundamentalTypes/arrayReferenceType.js

@@ -47,7 +47,6 @@ const arrayReferenceType = {
   },
   getValue ({root, stateObj, currentPath}) {
     const referentPath = this.getInput({root}).value;
-    // eslint-disable-next-line @stylistic/max-len -- Long
     /* istanbul ignore else -- ArrayRef will not be a root, so should have stateObj */
     if (stateObj) {
       if (!stateObj.paths) {
@@ -186,7 +185,6 @@ const arrayReferenceType = {
     $$e(topRoot, `div[data-type="${type}"]`).forEach((root) => {
       types.validate({
         type,
-        // eslint-disable-next-line object-shorthand -- TS
         root: /** @type {HTMLDivElement} */ (root),
         topRoot
       });