@edgedev/template-engine 0.1.0

package/src/index.ts

@@ -0,0 +1,487 @@
+// TODO:  ADD AS SEPERATE FILE/ FUNCTION THE QUERYING OF DATA FROM FROM EITHER THE API OR THE KV STORE... BUT IT WOUDLN'T BE CALLED SEPERATELY
+// IT WOULD BE CALLED AS PART OF THE RENDERING PROCESS...  IF API OR KV IS SPECIFIED IN THE META OR TEMPLATE CONFIG,
+// THIS, WOULD GET THE VALUES THEN PASS THEM TO THE RENDER FUNCTION BELOW
+// ALSO HAVE HELPER FUNCTIONS THIS USES AND WE CAN USE ELSEWHERE TO DO GET KV DATA AND QUERY KV DATA BASED ON OUR INDEX STRUCTURE
+// ALSO TAKE A LOOK AT OUR BLOCKS WE ARE GETTING... ALSO MAKE SURE THAT THE META WE PASS IN AS A VAR IS AN OVERRIDE OF THE TEMPLATE META...
+// MAKE SURE THE META IN THE TEMPLATE IS BEING USED. MAKE SURE SAME 
+
+import { ARRAY_BLOCK_RE, parseConfig } from './templateConfig'
+import { hydrateValues, type HydrateValuesOptions } from './hydrateValues'
+import { unoCssFromHtml } from './unoSsr'
+import type { MetaEntry, SchemaMap, TemplateMeta, TemplateValues } from './types'
+
+export { hydrateValues }
+export type { HydrateValuesOptions }
+export type {
+  SchemaValue,
+  SchemaArrayEntry,
+  SchemaMap,
+  MetaEntry,
+  TemplateMeta,
+  TemplateValues,
+  CollectionDefinition,
+  QueryFilter,
+  QueryOrder,
+  QueryItemsInput,
+} from './types'
+
+export {
+  createKvIndexClient,
+  type KvIndexClient,
+  type KvIndexClientOptions,
+  type KvIndexQueryParams,
+  type KVNamespaceLike,
+  type KvIndexRecord,
+} from './kvIndexClient'
+
+export {
+  normalizeTheme,
+  buildCssVarsBlock,
+} from './unoSsr'
+export { unoCssFromHtml }
+
+type Primitive = string | number | boolean | null | undefined
+
+const PLACEHOLDER_RE = /(?<!\{)\{\{\s*({[\s\S]*?})\s*\}\}(?!\})/g
+const SUBARRAY_BLOCK_RE = /\{\{\{\s*#subarray(?::([A-Za-z_][A-Za-z0-9_-]*))?\s*(?:({[\s\S]*?}))?\s*\}\}\}([\s\S]*?)\{\{\{\s*\/subarray\s*\}\}\}/g
+const SIMPLE_BLOCK_RE = /\{\{\{\s*#(text|image|textarea|richtext)\s*({[\s\S]*?})\s*\}\}\}/g
+const IF_BLOCK_RE = /\{\{\{\s*#if\s*({[\s\S]*?})\s*\}\}\}([\s\S]*?)(?:\{\{\{\s*#else\s*\}\}\}([\s\S]*?))?\{\{\{\s*\/if\s*\}\}\}/g
+
+const getByPath = (obj: unknown, path: string): unknown => {
+  if (!path || typeof path !== 'string')
+    return obj
+  return path.split('.').reduce<unknown>((acc, key) => {
+    if (acc && typeof acc === 'object' && key in (acc as Record<string, unknown>))
+      return (acc as Record<string, unknown>)[key]
+    return undefined
+  }, obj)
+}
+
+const escapeHtml = (value: Primitive): string => {
+  return String(value ?? '')
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+}
+
+const normalizeNumber = (value: unknown): number | null => {
+  if (value == null || value === '')
+    return null
+  const n = Number(value)
+  return Number.isFinite(n) ? n : null
+}
+
+const formatters: Record<string, (value: unknown) => string> = {
+  text: v => (v == null ? '' : String(v)),
+  textarea: v => (v == null ? '' : String(v)),
+  number: (v) => {
+    const n = normalizeNumber(v)
+    return typeof n === 'number' ? n.toLocaleString('en-US') : (v == null ? '' : String(v))
+  },
+  integer: (v) => {
+    const n = normalizeNumber(v)
+    return typeof n === 'number' ? String(Math.trunc(n)) : (v == null ? '' : String(v))
+  },
+  money: (v) => {
+    const n = normalizeNumber(v)
+    return typeof n === 'number'
+      ? n.toLocaleString('en-US', { style: 'currency', currency: 'USD', maximumFractionDigits: 0 })
+      : (v == null ? '' : String(v))
+  },
+  richtext: v => (v == null ? '' : String(v)),
+}
+
+const getFieldType = (schemaMap: SchemaMap | undefined, fieldKey: string | undefined): string | undefined => {
+  if (!schemaMap || !fieldKey)
+    return undefined
+
+  const baseKey = String(fieldKey).split('.')[0]
+
+  if (Array.isArray(schemaMap)) {
+    const hit = schemaMap.find(entry => entry?.field === baseKey)
+    return hit?.type ?? hit?.value
+  }
+
+  return schemaMap[baseKey]
+}
+
+const applySchemaFormat = (fieldKey: string | undefined, value: unknown, schemaMap: SchemaMap | undefined): string => {
+  if (!schemaMap || !fieldKey)
+    return value == null ? '' : String(value)
+
+  const type = getFieldType(schemaMap, fieldKey)
+  const formatter = type ? formatters[type] : undefined
+  return formatter ? formatter(value) : (value == null ? '' : String(value))
+}
+
+const coerceList = (input: unknown): unknown[] => {
+  return Array.isArray(input) ? input : []
+}
+
+const sliceWithLimit = (list: unknown[], limit: unknown): unknown[] => {
+  const n = Number(limit)
+  return Number.isFinite(n) && n > 0 ? list.slice(0, n) : list
+}
+
+const getCommonList = (source: Record<string, unknown>): unknown => {
+  for (const key of ['agents', 'items', 'children']) {
+    const candidate = source[key]
+    if (Array.isArray(candidate))
+      return candidate
+  }
+  return undefined
+}
+
+const hasOwn = (obj: Record<string, unknown>, key: string): boolean => {
+  return Object.prototype.hasOwnProperty.call(obj, key)
+}
+
+const aliasRegex = (alias: string): RegExp => {
+  const esc = alias.replace(/[-/\\^$*+?.()|[\]{}]/g, '\\$&')
+  return new RegExp(`\\{\\{\\s*${esc}\\.([a-zA-Z0-9_.$]+)\\s*\\}\\}`, 'g')
+}
+
+export const renderTemplate = (
+  content: string,
+  values: TemplateValues = {},
+  meta: TemplateMeta = {},
+): string => {
+  if (!content || typeof content !== 'string')
+    return ''
+  const renderSection = (
+    template: string,
+    data: unknown,
+    alias?: string,
+    schemaCtx?: SchemaMap,
+  ): string => {
+    if (!template)
+      return ''
+
+    const scopedValues = typeof data === 'object' && data !== null
+      ? (data as Record<string, unknown>)
+      : {}
+
+    let expanded = template.replace(SUBARRAY_BLOCK_RE, (_match, tagAlias, json, innerTpl) => {
+      const cfg = parseConfig(json || '{}') ?? {}
+      const fieldRaw = typeof cfg.field === 'string' ? cfg.field.trim() : ''
+      let list: unknown
+
+      if (fieldRaw) {
+        if (fieldRaw.startsWith('item.')) {
+          list = getByPath(scopedValues, fieldRaw.slice(5))
+        }
+        else {
+          list = scopedValues[fieldRaw] ?? getByPath(scopedValues, fieldRaw)
+          if (!Array.isArray(list))
+            list = getByPath(values, fieldRaw)
+        }
+      }
+      else if (Array.isArray(cfg.value)) {
+        list = cfg.value
+      }
+
+      if (!Array.isArray(list)) {
+        const fallback = getCommonList(scopedValues)
+        if (Array.isArray(fallback))
+          list = fallback
+      }
+
+      let normalized = coerceList(list)
+      normalized = sliceWithLimit(normalized, cfg.limit)
+
+      const childAlias = typeof cfg.as === 'string' && cfg.as.trim()
+        ? cfg.as.trim()
+        : (tagAlias?.trim() || undefined)
+
+      const childSchema = typeof cfg.schema === 'object' ? (cfg.schema as SchemaMap) : schemaCtx
+      return normalized.map(entry => renderSection(innerTpl, entry, childAlias, childSchema)).join('')
+    })
+
+    expanded = expanded.replace(ARRAY_BLOCK_RE, (_m, json, innerTpl) => {
+      const cfg = parseConfig(json || '{}') ?? {}
+      const fieldRaw = typeof cfg.field === 'string' ? cfg.field.trim() : ''
+      let list: unknown
+
+      if (fieldRaw) {
+        if (fieldRaw.startsWith('item.')) {
+          list = getByPath(scopedValues, fieldRaw.slice(5))
+        }
+        else {
+          list = scopedValues[fieldRaw] ?? getByPath(scopedValues, fieldRaw)
+          if (!Array.isArray(list))
+            list = getByPath(values, fieldRaw)
+        }
+      }
+      else if (Array.isArray(cfg.value)) {
+        list = cfg.value
+      }
+
+      if (!Array.isArray(list)) {
+        const fallback = getCommonList(scopedValues)
+        if (Array.isArray(fallback))
+          list = fallback
+      }
+
+      let normalized = coerceList(list)
+      normalized = sliceWithLimit(normalized, cfg.limit)
+
+      const childAlias = typeof cfg.as === 'string' && cfg.as.trim() ? cfg.as.trim() : undefined
+      const childSchema = typeof cfg.schema === 'object' ? (cfg.schema as SchemaMap) : schemaCtx
+      return normalized.map(entry => renderSection(innerTpl, entry, childAlias, childSchema)).join('')
+    })
+
+    if (alias && typeof alias === 'string') {
+      expanded = expanded.replace(aliasRegex(alias), (_match, path) => {
+        const value = getByPath(scopedValues, path)
+        const type = getFieldType(schemaCtx, path)
+        const formatted = applySchemaFormat(path, value, schemaCtx)
+        return type === 'richtext'
+          ? (formatted ?? '')
+          : escapeHtml(formatted)
+      })
+
+      expanded = expanded.replace(new RegExp(`\\{\\{\\s*${alias}\\s*\\}\\}`, 'g'), () => {
+        return data == null ? '' : escapeHtml(String(data))
+      })
+    }
+
+    expanded = expanded.replace(/\{\{\s*item\.([a-zA-Z0-9_.$]+)\s*\}\}/g, (_match, path) => {
+      const value = getByPath(scopedValues, path)
+      const type = getFieldType(schemaCtx, path)
+      const formatted = applySchemaFormat(path, value, schemaCtx)
+      if (type === 'richtext')
+        return formatted ?? ''
+      return formatted === '' ? '' : escapeHtml(formatted)
+    })
+
+    expanded = expanded.replace(/\{\{\s*item\s*\}\}/g, () => {
+      return data == null ? '' : escapeHtml(String(data))
+    })
+
+    expanded = expanded.replace(IF_BLOCK_RE, (_match, json, trueTpl, falseTpl) => {
+      const cfg = parseConfig(json || '{}') ?? {}
+      const cond = typeof cfg.cond === 'string' ? cfg.cond.trim() : ''
+      const comparison = cond.match(/^item\.([a-zA-Z0-9_.$]+)\s*(==|!=|>|<|>=|<=)\s*['"]?([^'"]+)['"]?$/)
+      let result = false
+
+      if (comparison) {
+        const [, path, op, valueRaw] = comparison
+        const leftValue = getByPath(scopedValues, path)
+        const normalize = (input: unknown): string | number => {
+          const num = Number(input)
+          if (Number.isFinite(num) && `${input}`.trim() !== '')
+            return num
+          return String(input ?? '')
+        }
+
+        const left = normalize(leftValue)
+        const right = normalize(valueRaw)
+
+        switch (op) {
+          case '==':
+            result = left === right
+            break
+          case '!=':
+            result = left !== right
+            break
+          case '>':
+            result = left > right
+            break
+          case '<':
+            result = left < right
+            break
+          case '>=':
+            result = left >= right
+            break
+          case '<=':
+            result = left <= right
+            break
+        }
+      }
+
+      return result
+        ? renderSection(trueTpl, data, alias, schemaCtx)
+        : renderSection(falseTpl ?? '', data, alias, schemaCtx)
+    })
+
+    return expanded
+  }
+
+  let output = content
+
+  output = output.replace(SIMPLE_BLOCK_RE, (_match, kind, json) => {
+    const cfg = parseConfig(json) ?? {}
+    const field = typeof cfg.field === 'string' ? cfg.field : undefined
+    const fallback = cfg.value
+    const raw = field && hasOwn(values, field)
+      ? values[field]
+      : fallback
+    const value = raw == null ? '' : raw
+    if (kind === 'text' || kind === 'textarea')
+      return escapeHtml(String(value))
+    if (kind === 'richtext')
+      return String(value)
+    return String(value)
+  })
+
+  output = output.replace(ARRAY_BLOCK_RE, (full, json, innerTpl) => {
+    const cfg = parseConfig(json) ?? {}
+    const field = typeof cfg.field === 'string' ? cfg.field : undefined
+
+    if (field?.startsWith('item.'))
+      return full
+
+    let list: unknown = field ? values[field] : undefined
+    if (!Array.isArray(list) && Array.isArray(cfg.value))
+      list = cfg.value
+
+    let normalized = coerceList(list)
+    normalized = sliceWithLimit(normalized, cfg.limit)
+
+    const alias = typeof cfg.as === 'string' && cfg.as.trim() ? cfg.as.trim() : undefined
+    const schemaContext = field && meta[field]?.schema
+      ? meta[field]?.schema
+      : (typeof cfg.schema === 'object' ? (cfg.schema as SchemaMap) : undefined)
+
+    return normalized.map(entry => renderSection(innerTpl, entry, alias, schemaContext)).join('')
+  })
+
+  output = output.replace(PLACEHOLDER_RE, (_match, json) => {
+    const cfg = parseConfig(json) ?? {}
+    const field = typeof cfg.field === 'string' ? cfg.field : undefined
+    const type = typeof cfg.type === 'string' ? cfg.type : undefined
+    const raw = field && hasOwn(values, field)
+      ? values[field]
+      : cfg.value
+    const value = raw == null ? '' : raw
+
+    if (type === 'text')
+      return escapeHtml(String(value))
+    if (type === 'richtext')
+      return String(value)
+    return String(value)
+  })
+
+  output = output.replace(/\{\{\s*loading\s*\}\}/g, 'loading')
+  output = output.replace(/\{\{\s*loaded\s*\}\}/g, 'loaded')
+
+  return output
+}
+
+export interface PageRenderBlock {
+  name?: string | null
+  content: string
+  values?: TemplateValues | null
+  meta?: TemplateMeta | null
+}
+
+export interface PageRenderResultBlock {
+  name?: string
+  html: string
+}
+
+export interface PageRenderResult {
+  blocks: PageRenderResultBlock[]
+  css: string
+}
+
+export type PageRenderHydrateOptions = Pick<HydrateValuesOptions, 'uniqueKey' | 'clientOptions'>
+
+const isPlainObject = (value: unknown): value is Record<string, unknown> => {
+  return !!value && typeof value === 'object' && !Array.isArray(value)
+}
+
+const coerceTemplateValues = (input: TemplateValues | null | undefined): TemplateValues | undefined => {
+  return isPlainObject(input) ? (input as TemplateValues) : undefined
+}
+
+const coerceTemplateMeta = (input: TemplateMeta | null | undefined): TemplateMeta | undefined => {
+  return isPlainObject(input) ? (input as TemplateMeta) : undefined
+}
+
+const buildHydrateOptions = (
+  input?: PageRenderHydrateOptions | null,
+): PageRenderHydrateOptions => {
+  const fallbackFetch = typeof globalThis.fetch === 'function'
+    ? (globalThis.fetch.bind(globalThis) as HydrateValuesOptions['clientOptions']['fetch'])
+    : undefined
+
+  const safeUniqueKey = typeof input?.uniqueKey === 'string' ? input.uniqueKey : ''
+  const providedClientOptions = input?.clientOptions
+
+  const safeClientOptions = providedClientOptions && typeof providedClientOptions === 'object'
+    ? {
+        ...providedClientOptions,
+        fetch: providedClientOptions.fetch ?? fallbackFetch,
+      }
+    : {
+        binding: null,
+        accountId: '',
+        namespaceId: '',
+        apiToken: '',
+        fetch: fallbackFetch,
+      }
+
+  if (!safeClientOptions.fetch)
+    throw new Error('pageRender requires a fetch implementation (globalThis.fetch or clientOptions.fetch)')
+
+  return {
+    uniqueKey: safeUniqueKey,
+    clientOptions: safeClientOptions,
+  }
+}
+
+export const pageRender = async (
+  blocks: PageRenderBlock[],
+  theme: Record<string, unknown> | null | undefined,
+  extraHtml: string | null | undefined = '',
+  hydrateOptions?: PageRenderHydrateOptions | null,
+): Promise<PageRenderResult> => {
+  const renderedBlocks: PageRenderResultBlock[] = []
+  const htmlFragments: string[] = []
+  const hydrationConfig = buildHydrateOptions(hydrateOptions)
+
+  for (const block of blocks) {
+    if (!block?.content) {
+      const blockName = typeof block?.name === 'string' ? block.name : undefined
+      renderedBlocks.push({ name: blockName, html: '' })
+      continue
+    }
+
+    const meta = coerceTemplateMeta(block.meta)
+    const initialValues = coerceTemplateValues(block.values)
+    const resolvedValues = await hydrateValues({
+      content: block.content,
+      values: initialValues,
+      meta,
+      uniqueKey: hydrationConfig.uniqueKey,
+      clientOptions: hydrationConfig.clientOptions,
+    })
+
+    const html = renderTemplate(
+      block.content,
+      resolvedValues ?? undefined,
+      meta,
+    )
+
+    const blockName = typeof block.name === 'string' ? block.name : undefined
+    renderedBlocks.push({ name: blockName, html })
+    if (html)
+      htmlFragments.push(html)
+  }
+
+  if (extraHtml && typeof extraHtml === 'string')
+    htmlFragments.push(extraHtml)
+
+  const combinedHtml = htmlFragments.join('\n')
+  const safeTheme = theme && typeof theme === 'object' ? theme : {}
+  const { css } = await unoCssFromHtml(combinedHtml, safeTheme)
+
+  return {
+    blocks: renderedBlocks,
+    css,
+  }
+}
+
+export default renderTemplate