hyper-html-api 0.13.0 → 0.15.0

package/src/upgrade/shape-match.js

@@ -1,14 +1,29 @@
+import { DOM_PROPERTIES_READ_ONLY_SET } from '../engine/dom-properties.js'
+import { ruleAttrIndex } from '../engine/rule-syntax.js'
+
 /**
  * Walk v2Rules pulling matching values from v1Data.
  *
+ * Outside a list, what v1 has no value for keeps v2's template default:
+ *
  *   - Scalar leaves: carry the v1 value if defined, else leave undefined so
  *     the engine keeps v2's template default on apply.
- *   - Object arrays ([sel, shape]): carry v1's items, trimmed to v1's count;
- *     each item shape-matches recursively. Fields v2 added that didn't exist
- *     in v1 are left undefined → template default.
- *   - Scalar arrays (`sel[]`): carry as-is.
+ *   - Lists: carry v1's items, trimmed to v1's count; a list v1 never had
+ *     keeps v2's rows.
  *   - Objects: recurse per key.
  *
+ * Inside a list item nothing keeps a default. A row is the owner's own. It is
+ * written over a v2 sample row, or over a clone of one, so a field left
+ * undefined would take that sample's value (its label, its cover, its done
+ * mark, its id). So in a row:
+ *
+ *   - A field v1 read as null, a field v1 never had (v2 added it), and a
+ *     scalar field where v1 holds an object are all carried as null, and the
+ *     write clears them.
+ *   - A list v1 never had is carried as an empty list.
+ *   - A property nothing can write (tagName, childElementCount) stays
+ *     undefined, because writing null to it refuses the whole write.
+ *
  * Returns { data, summary } where summary counts scalar leaves carried,
  * dropped, and total list items preserved.
  */
@@ -19,31 +34,30 @@ export function shapeMatch(v1Data, v2Rules) {
   return { data, summary }
 }
 
-function walk(rule, v1, summary) {
+function walk(rule, v1, summary, inRow = false) {
   if (typeof rule === 'string') {
     if (rule.endsWith('[]')) {
-      if (!Array.isArray(v1)) return undefined
+      if (!Array.isArray(v1)) return inRow ? [] : undefined
       summary.listItems += v1.length
       summary.carriedOver += v1.length
       return v1
     }
-    if (v1 === undefined || v1 === null) return undefined
-    // A scalar slot can't hold an object/array from v1; leave the template
-    // default (collectDiscards counts the dropped leaves).
-    if (typeof v1 === 'object') return undefined
+    // A scalar slot can't hold an object/array from v1 (collectDiscards counts
+    // the dropped leaves), so it is treated as a slot v1 has no value for.
+    if (v1 == null || typeof v1 === 'object') return inRow && !readOnly(rule) ? null : undefined
     summary.carriedOver++
     return v1
   }
   if (Array.isArray(rule)) {
     const [, shape] = rule
-    if (!Array.isArray(v1)) return undefined
+    if (!Array.isArray(v1)) return inRow ? [] : undefined
     summary.listItems += v1.length
-    return v1.map((item) => walk(shape, item, summary))
+    return v1.map((item) => walk(shape, item, summary, true))
   }
   if (typeof rule === 'object' && rule !== null) {
     const out = {}
     for (const [k, sub] of Object.entries(rule)) {
-      const v = walk(sub, v1 == null ? undefined : v1[k], summary)
+      const v = walk(sub, v1 == null ? undefined : v1[k], summary, inRow)
       if (v !== undefined) out[k] = v
     }
     return out
@@ -51,6 +65,11 @@ function walk(rule, v1, summary) {
   return undefined
 }
 
+function readOnly(rule) {
+  const at = ruleAttrIndex(rule)
+  return at !== -1 && DOM_PROPERTIES_READ_ONLY_SET.has(rule.slice(at + 1))
+}
+
 function collectDiscards(rule, v1, summary) {
   if (v1 == null) return
   if (typeof rule === 'object' && rule !== null && !Array.isArray(rule)) {

package/src/write.js

@@ -7,18 +7,23 @@ import { planWrite } from './engine/write-plan.js'
 import { assertRoundTrip } from './engine/round-trip.js'
 import { trackAdapter, spliceDocument } from './engine/splice.js'
 import { NoRulesTag, RulesParseError, WriteRejected } from './engine/errors.js'
+import { sheet } from './codecs/sheet.js'
+import { codecOf } from './engine/rule-syntax.js'
 
 // Applies a JSON body to a document's source through caller-provided rules
 // (options.rules) or the document's own rules tag, under the content-only
 // policy. `load` is cheerio.load, passed in so this package keeps cheerio out
 // of its browser bundles. Returns the new source and whether anything changed.
 // Throws NoRulesTag, RulesParseError, WriteRejected, WriteRefused, ShapeMismatch,
-// EmptyListInsert or WriteNotRoundTripped, always before producing any output.
+// EmptyListInsert, UnknownCodec or WriteNotRoundTripped, always before producing
+// any output. options.codecs maps a name to a codec for `@codec(name)` rules,
+// which only a version 2 rules tag may use (default: the sheet codec).
 export function writeDocument(load, src, data, options = {}) {
-  const { token = 'api' } = options
+  const { token = 'api', codecs = { sheet } } = options
   const $ = load(src, { sourceCodeLocationInfo: true })
   const root = $.root()
   let rules
+  let version = '1'
   if (Object.prototype.hasOwnProperty.call(options, 'rules')) {
     rules = options.rules
     if (rules === null || !['string', 'object'].includes(typeof rules)) {
@@ -28,10 +33,11 @@ export function writeDocument(load, src, data, options = {}) {
     const found = findRulesIn(cheerioAdapter, root, token)
     if (!found) throw new NoRulesTag(token)
     rules = found.rules
+    version = found.version
   }
-  const plan = planWrite(cheerioAdapter, root, rules, data)
+  const plan = planWrite(cheerioAdapter, root, rules, data, { version, codecs })
   if (plan.unknownKeys.length || plan.unmatched.length) throw new WriteRejected(plan.unknownKeys, plan.unmatched)
-  const opts = { templateAttr: 'cms-template' }
+  const opts = { templateAttr: 'cms-template', version, codecs }
   const tracker = trackAdapter(cheerioAdapter)
   const guarded = guardAdapter(tracker)
   apply(guarded, root, rules, data, opts)
@@ -46,7 +52,7 @@ export function writeDocument(load, src, data, options = {}) {
   // pays for the field it wrote, not for every rule in the document.
   const written = writtenRules(rules, data)
   const writtenRoot = load(html).root()
-  assertRoundTrip(written, data, extract(cheerioAdapter, writtenRoot, written, opts))
+  assertRoundTrip(written, data, extract(cheerioAdapter, writtenRoot, written, { ...opts, allMatches: true }), codecs)
   return { html, changed: html !== src, spliced }
 }
 
@@ -65,3 +71,36 @@ function writtenRules(rules, data) {
 function isPlainObject(value) {
   return value !== null && typeof value === 'object' && !Array.isArray(value)
 }
+
+export { patchDocument, NOT_CANONICAL_MESSAGE } from './patch-document.js'
+
+// The one rule every host uses to tell a patch body from a data write: an
+// object whose `patch` value is an array and whose only other key is
+// `operationId`, sent to a document whose rules have no top level key named
+// `patch`. Anything else is a data write, exactly as before patches existed.
+export function isPatchBody(body, rules) {
+  if (!isPlainObject(body) || !Array.isArray(body.patch)) return false
+  if (Object.keys(body).some((key) => key !== 'patch' && key !== 'operationId')) return false
+  return !(isPlainObject(rules) && Object.prototype.hasOwnProperty.call(rules, 'patch'))
+}
+
+// Rows in a write body, for a host's size limit: every array item counts, at
+// any depth. Under a version 2 rules tag a top level key whose rule is a
+// `@codec(name)` rule is skipped, because its value is not a list of rows (a
+// sheet's size is its cells, and hosts limit those per patch).
+export function countRows(value, rules, version = '1') {
+  if (version === '2' && isPlainObject(value) && isPlainObject(rules)) {
+    let sum = 0
+    for (const [key, item] of Object.entries(value)) {
+      if (!codecOf(rules[key])) sum += countAll(item)
+    }
+    return sum
+  }
+  return countAll(value)
+}
+
+function countAll(value) {
+  if (Array.isArray(value)) return value.reduce((sum, item) => sum + 1 + countAll(item), 0)
+  if (value !== null && typeof value === 'object') return Object.values(value).reduce((sum, item) => sum + countAll(item), 0)
+  return 0
+}