hyper-html-api 0.14.0 → 0.15.0

package/src/read.js

@@ -0,0 +1,163 @@
+import cheerioAdapter from './adapters/cheerio.js'
+import { extract } from './engine/extract.js'
+import { findRulesIn } from './engine/rules-tag.js'
+import { codecOf } from './engine/rule-syntax.js'
+import { sheet } from './codecs/sheet.js'
+import { checkCodecRules } from './engine/codecs.js'
+import { holeMarker, QueryRefused } from './codecs/sheet.vendor.js'
+
+// The URL parameters a host passes to readDocument as `query`, from a
+// URLSearchParams. Returns null when none of them is present (a whole read,
+// exactly as before). Each may appear once with a value, and none may be
+// mixed with ?data= (a caller-supplied rule set); anything else is
+// QueryRefused('bad_query'), which hosts answer with 400. Values are not
+// checked here: readDocument refuses a bad one with its own code.
+export const SHEET_QUERY_PARAMS = ['shape', 'sheet', 'range', 'render']
+
+export function parseSheetQuery(params) {
+  const query = {}
+  for (const key of SHEET_QUERY_PARAMS) {
+    const values = params.getAll(key)
+    if (values.length === 0) continue
+    if (values.length > 1) throw new QueryRefused('bad_query', `${key} appears ${values.length} times; send it once`)
+    if (values[0] === '') throw new QueryRefused('bad_query', `${key} is empty; give it a value or leave it out`)
+    query[key] = values[0]
+  }
+  if (Object.keys(query).length === 0) return null
+  if (params.has('data')) throw new QueryRefused('bad_query', `data cannot be combined with ${Object.keys(query).join(', ')}; a sheet query reads the document's own rules`)
+  return query
+}
+
+// Reads a document's data through its rules tag, from source. `load` is
+// cheerio.load, passed in so this package keeps cheerio out of its browser
+// bundles. Returns { data, version, fast }; data is null when no rules tag
+// carries `token`.
+//
+// A codec with cut() lets a host skip parsing its regions: the source is cut,
+// only the rest is parsed, and each hole hands the codec its region's bytes.
+// The holes are verified first: every hole is a real element, each index
+// appears exactly once and in order, and every hole lies under the element a
+// rule naming that codec selected, which only that codec reads. Anything else
+// (a grid inside a comment, a script or a textarea, a grid outside the sheet)
+// discards the cut and reads the whole source through the tree. `fast` is false whenever a
+// `<table grid` was read through the tree (that fallback, or a hand-edited table
+// the cut left in place), so a host can count how often the slow route runs.
+//
+// options: { token = 'api', query, view, codecs = { sheet } }. query and view
+// reach every codec rule (see src/codecs/sheet.js for the sheet's shapes).
+export function readDocument(load, src, options = {}) {
+  const { token = 'api', query, view, codecs = { sheet } } = options
+  const call = { codecs, query, view }
+  const cutting = Object.entries(codecs).filter(([, codec]) => typeof codec.cut === 'function')
+  if (cutting.length > 1) throw new Error('hyper-html-api: readDocument supports one codec with cut()')
+
+  if (cutting.length === 1) {
+    const [name, codec] = cutting[0]
+    const marker = holeMarker(src)
+    const { rest, regions } = codec.cut(src, marker)
+    if (regions.length > 0) {
+      const $ = load(rest)
+      const root = $.root()
+      const found = findRulesIn(cheerioAdapter, root, token)
+      const fast = countGrids(rest) === regions.length
+      if (!found) return { data: null, version: null, fast }
+      if (codec === sheet && readHolesHold($, root, found.rules, name, marker, regions.length)) {
+        const region = (table) => regionBytes(table, src, marker, regions)
+        const opts = { ...call, version: found.version, region }
+        checkCodecRules(found.rules, opts)
+        let tree
+        const data = {}
+        for (const [key, rule] of Object.entries(found.rules)) {
+          const codec = codecOf(rule)
+          const context = codec ? root : (tree ??= load(src).root())
+          data[key] = extract(cheerioAdapter, context, { [key]: rule }, { ...opts, region: codec ? region : undefined })[key]
+        }
+        return { data, version: found.version, fast }
+      }
+    }
+  }
+
+  const fast = !src.includes(GRID)
+
+  const root = load(src).root()
+  const found = findRulesIn(cheerioAdapter, root, token)
+  if (!found) return { data: null, version: null, fast }
+  return { data: extract(cheerioAdapter, root, found.rules, { ...call, version: found.version }), version: found.version, fast }
+}
+
+// A document's rules tag as { rules, version }, or null when no tag carries
+// `token`, without parsing its canonical tables: what a host needs to classify
+// a request body (isPatchBody) before it reads or patches. Same cut and checks
+// as readDocument; anything they reject is found by parsing the whole source.
+export function documentRules(load, src, options = {}) {
+  const { token = 'api', codecs = { sheet } } = options
+  const cutting = Object.entries(codecs).filter(([, codec]) => typeof codec.cut === 'function')
+  if (cutting.length === 1) {
+    const [name, codec] = cutting[0]
+    const marker = holeMarker(src)
+    const { rest, regions } = codec.cut(src, marker)
+    if (regions.length > 0) {
+      const $ = load(rest)
+      const root = $.root()
+      const found = findRulesIn(cheerioAdapter, root, token)
+      if (!found) return null
+      if (holesHold($, root, found.rules, name, marker, regions.length)) return { rules: found.rules, version: found.version }
+    }
+  }
+  const found = findRulesIn(cheerioAdapter, load(src).root(), token)
+  return found ? { rules: found.rules, version: found.version } : null
+}
+
+const GRID = '<table grid'
+
+function countGrids(text) {
+  let n = 0
+  for (let at = text.indexOf(GRID); at !== -1; at = text.indexOf(GRID, at + 1)) n++
+  return n
+}
+
+export function holesHold($, root, rules, name, marker, count) {
+  const holes = $('table[data-hole]').toArray()
+  if (holes.length !== count) return false
+  const containers = codecContainers(root, rules, name)
+  if (containers.length === 0) return false
+  return holes.every((hole, n) =>
+    hole.attribs['data-hole'] === `${marker}-${n}` &&
+    containers.some((container) => container === hole || $.contains(container, hole)))
+}
+
+// Only this selector cannot match within canonical grid bytes or depend on their children.
+const SHEET_CONTAINER = /^\[items\s*=\s*(?:sheets|"sheets"|'sheets')\]$/
+
+function readHolesHold($, root, rules, name, marker, count) {
+  if (!rules || typeof rules !== 'object' || Array.isArray(rules)) return false
+  for (const rule of Object.values(rules)) {
+    const form = codecOf(rule)
+    if (form && (form.name !== name || !SHEET_CONTAINER.test(form.selector))) return false
+  }
+  if (!holesHold($, root, rules, name, marker, count)) return false
+  const containers = new Set(codecContainers(root, rules, name))
+  return $('table[grid]').length === count && $('table[data-hole]').toArray().every(hole =>
+    hole.parent?.name === 'section' && Object.hasOwn(hole.parent.attribs, 'item') && containers.has(hole.parent.parent))
+}
+
+// The element each top level `selector@codec(name)` rule selects, as the engine
+// would read it: the first match, or the document itself for a bare "@codec(name)".
+function codecContainers(root, rules, name) {
+  if (!rules || typeof rules !== 'object' || Array.isArray(rules)) return []
+  const out = []
+  for (const rule of Object.values(rules)) {
+    const form = codecOf(rule)
+    if (!form || form.name !== name) continue
+    const node = form.selector ? cheerioAdapter.find(root, form.selector)[0] : root
+    if (node && node.get(0)) out.push(node.get(0))
+  }
+  return out
+}
+
+function regionBytes(table, src, marker, regions) {
+  const hole = cheerioAdapter.attr(table, 'data-hole')
+  if (!hole || !hole.startsWith(`${marker}-`)) return null
+  const region = regions[Number(hole.slice(marker.length + 1))]
+  return region ? src.slice(region.start, region.end) : null
+}

package/src/upgrade/codec-carry.js

@@ -0,0 +1,23 @@
+import { codecOf } from '../engine/rule-syntax.js'
+
+// Under a version 2 rules tag, a top level `@codec(name)` key (a sheet) is
+// carried whole on upgrade: the extract side keeps its container's markup as
+// a string, and the migrate side puts that string into the same key's
+// container in the new template. The value is never read into data and
+// written back, so the codec needs no whole-value write and the canonical
+// bytes its grammar reads stay as they were.
+export function splitCarried(rules, version) {
+  if (version !== '2' || !rules || typeof rules !== 'object' || Array.isArray(rules)) return { rules, carried: [] }
+  const rest = {}
+  const carried = []
+  for (const [key, rule] of Object.entries(rules)) {
+    const codec = codecOf(rule)
+    if (codec) carried.push({ key, selector: codec.selector })
+    else rest[key] = rule
+  }
+  return { rules: rest, carried }
+}
+
+export function carriedNode(adapter, root, selector) {
+  return adapter.find(root, selector)[0] || null
+}

package/src/upgrade/extract-all.js

@@ -1,17 +1,26 @@
 import { extract } from '../engine/extract.js'
 import domAdapter from '../adapters/dom.js'
 import { collectRulesTags } from './rules-tags.js'
+import { splitCarried, carriedNode } from './codec-carry.js'
 import { readMeta } from './check.js'
 
 /**
  * Keyed extraction: one entry per rules tag under `root`, keyed by the
  * normalized data-rules-name value. This is the v1 side of an upgrade:
- * pack the page's data into labeled boxes.
+ * pack the page's data into labeled boxes. A `@codec(name)` key (a sheet,
+ * version 2 tags only) packs as its container's markup string, which a
+ * transform passes through unchanged.
  */
 export function extractAllFrom(adapter, root) {
   const dataByName = {}
-  for (const { name, rules } of collectRulesTags(adapter, root)) {
-    dataByName[name] = extract(adapter, root, rules)
+  for (const { name, rules, version } of collectRulesTags(adapter, root)) {
+    const { rules: plain, carried } = splitCarried(rules, version)
+    const data = extract(adapter, root, plain, { version })
+    for (const { key, selector } of carried) {
+      const node = carriedNode(adapter, root, selector)
+      data[key] = node ? adapter.prop(node, 'innerHTML') : null
+    }
+    dataByName[name] = data
   }
   return dataByName
 }

package/src/upgrade/migrate.js

@@ -1,12 +1,15 @@
 import { apply } from '../engine/apply.js'
 import { collectRulesTags } from './rules-tags.js'
 import { shapeMatch, countScalarLeaves } from './shape-match.js'
+import { splitCarried, carriedNode } from './codec-carry.js'
 
 /**
  * Pour keyed v1 data into the v2 document. Exact-name join: each v2 rules
  * tag pulls the entry with the same normalized name; tags with no matching
  * entry keep their template defaults; v1 entries with no matching tag are
  * counted as discarded. Renames are the transform's job, not the join's.
+ * A `@codec(name)` key takes its markup string whole into the new
+ * template's container for that key.
  */
 export function migrateInto(adapter, root, dataByName) {
   const tags = collectRulesTags(adapter, root)
@@ -14,15 +17,28 @@ export function migrateInto(adapter, root, dataByName) {
   const byName = {}
   const v2Names = new Set()
 
-  for (const { name, rules } of tags) {
+  for (const { name, rules, version } of tags) {
     v2Names.add(name)
     if (!Object.prototype.hasOwnProperty.call(dataByName, name)) {
       byName[name] = { carriedOver: 0, discarded: 0, listItems: 0 }
       continue
     }
-    const { data, summary } = shapeMatch(dataByName[name], rules)
+    const { rules: plain, carried } = splitCarried(rules, version)
+    const entry = dataByName[name]
+    const { data, summary } = shapeMatch(withoutCarried(entry, carried), plain)
     // A row whose nested list is empty at that spot in v2 grows from the page's seeds, as a write does.
-    apply(adapter, root, rules, data, { templateAttr: 'cms-template' })
+    apply(adapter, root, plain, data, { templateAttr: 'cms-template' })
+    for (const { key, selector } of carried) {
+      const markup = isPlainObject(entry) ? entry[key] : undefined
+      if (markup === undefined || markup === null) continue
+      const node = carriedNode(adapter, root, selector)
+      if (typeof markup === 'string' && node) {
+        adapter.prop(node, 'innerHTML', markup)
+        summary.carriedOver += 1
+      } else {
+        summary.discarded += 1
+      }
+    }
     byName[name] = summary
     totals.carriedOver += summary.carriedOver
     totals.discarded += summary.discarded
@@ -35,3 +51,14 @@ export function migrateInto(adapter, root, dataByName) {
 
   return { totals, byName, rulesTagCount: tags.length }
 }
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+function withoutCarried(entry, carried) {
+  if (!carried.length || !isPlainObject(entry)) return entry
+  const rest = { ...entry }
+  for (const { key } of carried) delete rest[key]
+  return rest
+}

package/src/upgrade/rules-tags.js

@@ -1,5 +1,5 @@
 import { parseRelaxed } from '../engine/rules.js'
-import { SUPPORTED_VERSION } from '../engine/rules-tag.js'
+import { SUPPORTED_VERSIONS } from '../engine/rules-tag.js'
 import { UnknownRulesVersion } from '../engine/errors.js'
 
 const RULES_SELECTOR = 'script[data-rules-name]'
@@ -9,7 +9,7 @@ export function normalizeName(raw) {
 }
 
 /**
- * Collect every rules tag under `root` as [{ name, rules }], keyed by the
+ * Collect every rules tag under `root` as [{ name, rules, version }], keyed by the
  * whitespace-normalized data-rules-name attribute value. Duplicate names:
  * first tag wins with a warning (mirrors findRulesIn). Unsupported
  * data-rules-version throws so engine-format skew fails loudly instead of
@@ -29,9 +29,9 @@ export function collectRulesTags(adapter, root) {
       continue
     }
     const version = adapter.attr(tag, 'data-rules-version')
-    if (version !== SUPPORTED_VERSION) throw new UnknownRulesVersion(version)
+    if (!SUPPORTED_VERSIONS.includes(version)) throw new UnknownRulesVersion(version)
     seen.add(name)
-    out.push({ name, rules: parseRelaxed(adapter.text(tag)) })
+    out.push({ name, rules: parseRelaxed(adapter.text(tag)), version })
   }
   return out
 }

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, allMatches: true }))
+  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
+}