@edgedev/template-engine 0.1.0

package/src/hydrateValues.ts

@@ -0,0 +1,753 @@
+import { ARRAY_BLOCK_RE, parseConfig } from './templateConfig'
+import {
+  createKvIndexClient,
+  type KvIndexClientOptions,
+  type KvIndexRecord,
+} from './kvIndexClient'
+import type {
+  CollectionDefinition,
+  QueryFilter,
+  QueryItemsInput,
+  QueryOrder,
+  TemplateMeta,
+  TemplateValues,
+} from './types'
+
+export interface HydrateValuesOptions {
+  content: string
+  meta?: TemplateMeta
+  values?: TemplateValues
+  uniqueKey: string
+  clientOptions: KvIndexClientOptions
+}
+
+interface RawCollectionConfig {
+  field: string
+  collection?: CollectionDefinition
+  queryItems?: QueryItemsInput
+  queryOptions?: QueryFilter[]
+  limit?: number | string | null
+  api?: string
+  apiField?: string
+  apiQuery?: unknown
+  value?: unknown
+}
+
+interface QueryItem {
+  searchKey: string
+  searchValue: string | string[]
+}
+
+interface NormalizedCollectionConfig {
+  field: string
+  baseKey?: string
+  apiUrl?: string
+  apiField?: string
+  queryItems: QueryItem[]
+  filters: QueryFilter[]
+  orders: QueryOrder[]
+  limit?: number
+  fallbackValue?: unknown
+}
+
+const isRecord = (input: unknown): input is Record<string, unknown> => {
+  return !!input && typeof input === 'object' && !Array.isArray(input)
+}
+
+const getValueAtPath = (record: unknown, path: string): unknown => {
+  if (!isRecord(record) || !path)
+    return undefined
+  const keys = path.split('.')
+  let current: unknown = record
+  for (const key of keys) {
+    if (!isRecord(current) || !(key in current))
+      return undefined
+    current = current[key]
+  }
+  return current
+}
+
+const normalizeLimit = (value: unknown): number | undefined => {
+  if (value == null)
+    return undefined
+  const num = typeof value === 'number' ? value : Number(value)
+  if (!Number.isFinite(num) || num <= 0)
+    return undefined
+  return Math.floor(num)
+}
+
+const pickString = (value: unknown): string | undefined => {
+  if (typeof value !== 'string')
+    return undefined
+  const trimmed = value.trim()
+  return trimmed.length > 0 ? trimmed : undefined
+}
+
+const normalizeSearchValue = (value: unknown): string | string[] | undefined => {
+  if (value == null)
+    return undefined
+
+  if (Array.isArray(value)) {
+    const normalized = value
+      .map((entry) => {
+        if (entry == null)
+          return undefined
+        if (typeof entry === 'string')
+          return entry
+        if (typeof entry === 'number' || typeof entry === 'boolean')
+          return String(entry)
+        if (typeof entry === 'object')
+          return JSON.stringify(entry)
+        return String(entry)
+      })
+      .filter((entry): entry is string => typeof entry === 'string' && entry.length > 0)
+    return normalized.length > 0 ? normalized : undefined
+  }
+
+  if (typeof value === 'string')
+    return value
+  if (typeof value === 'number' || typeof value === 'boolean')
+    return String(value)
+  if (typeof value === 'object')
+    return JSON.stringify(value)
+
+  return String(value)
+}
+
+const normalizeQueryItems = (
+  input: QueryItemsInput,
+  fallbackField?: string,
+): QueryItem[] => {
+  const items: QueryItem[] = []
+
+  const pushItem = (key: unknown, rawValue: unknown): void => {
+    if (typeof key !== 'string' || !key.trim())
+      return
+    const normalizedValue = normalizeSearchValue(rawValue)
+    if (normalizedValue == null)
+      return
+    items.push({
+      searchKey: key.trim(),
+      searchValue: normalizedValue,
+    })
+  }
+
+  if (!input)
+    return items
+
+  if (typeof input === 'string') {
+    if (fallbackField)
+      pushItem(fallbackField, input)
+    return items
+  }
+
+  if (Array.isArray(input)) {
+    const allStrings = input.every(entry => typeof entry === 'string')
+    if (allStrings) {
+      if (fallbackField) {
+        for (const value of input)
+          pushItem(fallbackField, value)
+      }
+      else {
+        for (let i = 0; i < input.length - 1; i += 2)
+          pushItem(input[i], input[i + 1])
+      }
+      return items
+    }
+
+    for (const entry of input) {
+      if (Array.isArray(entry)) {
+        const [key, value] = entry
+        pushItem(key, value)
+        continue
+      }
+      if (typeof entry === 'string') {
+        if (fallbackField)
+          pushItem(fallbackField, entry)
+        continue
+      }
+      if (isRecord(entry)) {
+        let key = entry.searchKey ?? entry.field ?? entry.key
+        let value = entry.searchValue ?? entry.value ?? entry.values ?? entry.options
+
+        if ((!key || typeof key !== 'string') && value === undefined) {
+          const owned = Object.entries(entry)
+          if (owned.length === 1) {
+            const [derivedKey, derivedValue] = owned[0]
+            key = derivedKey
+            value = derivedValue
+          }
+        }
+
+        pushItem(key, value)
+      }
+    }
+    return items
+  }
+
+  if (isRecord(input)) {
+    for (const [key, value] of Object.entries(input))
+      pushItem(key, value)
+  }
+
+  return items
+}
+
+const buildApiUrl = (inputUrl: string, queryItems: QueryItem[]): string => {
+  if (!inputUrl || !queryItems.length)
+    return inputUrl
+
+  const hashIndex = inputUrl.indexOf('#')
+  const hash = hashIndex >= 0 ? inputUrl.slice(hashIndex) : ''
+  const beforeHash = hashIndex >= 0 ? inputUrl.slice(0, hashIndex) : inputUrl
+
+  const queryIndex = beforeHash.indexOf('?')
+  const path = queryIndex >= 0 ? beforeHash.slice(0, queryIndex) : beforeHash
+  const existingQuery = queryIndex >= 0 ? beforeHash.slice(queryIndex + 1) : ''
+
+  const params = new URLSearchParams(existingQuery)
+
+  for (const { searchKey, searchValue } of queryItems) {
+    if (!searchKey)
+      continue
+
+    const values = Array.isArray(searchValue) ? searchValue : [searchValue]
+    if (!values.length)
+      continue
+
+    params.delete(searchKey)
+    for (const value of values)
+      params.append(searchKey, value)
+  }
+
+  const queryString = params.toString()
+  if (!queryString)
+    return `${path}${hash}`
+  return `${path}?${queryString}${hash}`
+}
+
+const dedupeByCanonical = (records: KvIndexRecord[]): KvIndexRecord[] => {
+  const seen = new Set<string>()
+  const result: KvIndexRecord[] = []
+  for (const record of records) {
+    const canonical = getValueAtPath(record, 'canonical')
+    if (typeof canonical === 'string') {
+      if (seen.has(canonical))
+        continue
+      seen.add(canonical)
+    }
+    result.push(record)
+  }
+  return result
+}
+
+const fetchApiRecords = async (
+  apiUrl: string,
+  queryItems: QueryItem[],
+  options: {
+    apiField?: string
+    fetchImpl?: KvIndexClientOptions['fetch']
+  },
+): Promise<KvIndexRecord[]> => {
+  const { apiField, fetchImpl } = options
+  const urlToRequest = buildApiUrl(apiUrl, queryItems)
+  const fetchFn = fetchImpl ?? (globalThis.fetch as KvIndexClientOptions['fetch'] | undefined)
+
+  if (!fetchFn) {
+    console.warn('[hydrateValues] No fetch implementation available for API source', { url: apiUrl })
+    return []
+  }
+
+  try {
+    const response = await fetchFn(urlToRequest)
+    if (!response.ok) {
+      console.warn('[hydrateValues] API request failed', { url: urlToRequest, status: response.status })
+      return []
+    }
+
+    const rawData = await response.json()
+    const resolved = apiField ? (getValueAtPath(rawData, apiField) ?? rawData) : rawData
+
+    if (Array.isArray(resolved))
+      return resolved.filter(isRecord) as KvIndexRecord[]
+
+    if (isRecord(resolved))
+      return [resolved as KvIndexRecord]
+
+    return []
+  }
+  catch (error) {
+    console.warn('[hydrateValues] Failed to fetch API source', { url: apiUrl, error })
+    return []
+  }
+}
+
+const toComparableNumber = (value: unknown): number | null => {
+  if (typeof value === 'number')
+    return value
+  if (typeof value === 'string') {
+    const num = Number(value)
+    return Number.isFinite(num) ? num : null
+  }
+  if (typeof value === 'boolean')
+    return value ? 1 : 0
+  return null
+}
+
+const compareValues = (left: unknown, right: unknown): number => {
+  if (left == null && right == null)
+    return 0
+  if (left == null)
+    return -1
+  if (right == null)
+    return 1
+
+  const leftNumber = toComparableNumber(left)
+  const rightNumber = toComparableNumber(right)
+  if (leftNumber != null && rightNumber != null)
+    return leftNumber - rightNumber
+
+  const leftString = String(left)
+  const rightString = String(right)
+  return leftString.localeCompare(rightString, undefined, { numeric: true, sensitivity: 'base' })
+}
+
+const ensureArray = (value: unknown): unknown[] => {
+  if (Array.isArray(value))
+    return value
+  if (value == null)
+    return []
+  return [value]
+}
+
+const matchesFilter = (record: KvIndexRecord, filter: QueryFilter): boolean => {
+  if (!filter || typeof filter.field !== 'string')
+    return true
+
+  const field = filter.field.trim()
+  if (!field)
+    return true
+
+  const left = getValueAtPath(record, field)
+  const operator = (filter.operator ?? '==').toLowerCase()
+  const singleValue = filter.value ?? (Array.isArray(filter.values) ? filter.values[0] : undefined)
+  const arrayValues = Array.isArray(filter.values)
+    ? filter.values
+    : Array.isArray(filter.options)
+      ? ensureArray(filter.options)
+      : Array.isArray(filter.value)
+        ? ensureArray(filter.value)
+        : undefined
+
+  switch (operator) {
+    case '==':
+    case '=':
+    case '===':
+    case 'eq':
+      return left === singleValue
+    case '!=':
+    case '!==':
+    case '<>':
+    case 'neq':
+      return left !== singleValue
+    case '>':
+    case 'gt':
+      return compareValues(left, singleValue) > 0
+    case '>=':
+    case 'gte':
+      return compareValues(left, singleValue) >= 0
+    case '<':
+    case 'lt':
+      return compareValues(left, singleValue) < 0
+    case '<=':
+    case 'lte':
+      return compareValues(left, singleValue) <= 0
+    case 'in': {
+      const candidates = arrayValues ?? ensureArray(filter.value)
+      return candidates.some(candidate => candidate === left)
+    }
+    case 'not-in': {
+      const candidates = arrayValues ?? ensureArray(filter.value)
+      return !candidates.some(candidate => candidate === left)
+    }
+    case 'array-contains':
+    case 'contains': {
+      if (!Array.isArray(left))
+        return false
+      return left.some(entry => entry === singleValue)
+    }
+    case 'array-contains-any': {
+      if (!Array.isArray(left))
+        return false
+      const candidates = arrayValues ?? ensureArray(filter.value)
+      return candidates.some(candidate => left.some(entry => entry === candidate))
+    }
+    case 'array-contains-all': {
+      if (!Array.isArray(left))
+        return false
+      const candidates = arrayValues ?? ensureArray(filter.value)
+      return candidates.every(candidate => left.some(entry => entry === candidate))
+    }
+    case 'exists':
+      return left != null
+    case 'not-exists':
+    case 'missing':
+      return left == null
+    default:
+      return true
+  }
+}
+
+const applyFilters = (records: KvIndexRecord[], filters: QueryFilter[]): KvIndexRecord[] => {
+  if (!filters.length)
+    return records
+  return records.filter(record => filters.every(filter => matchesFilter(record, filter)))
+}
+
+const applyOrdering = (records: KvIndexRecord[], orders: QueryOrder[]): KvIndexRecord[] => {
+  if (!orders.length)
+    return records
+
+  const validOrders = orders
+    .filter(order => order && typeof order.field === 'string' && order.field.trim().length > 0)
+
+  if (!validOrders.length)
+    return records
+
+  const sorted = [...records]
+  sorted.sort((a, b) => {
+    for (const order of validOrders) {
+      const direction = (order.direction ?? 'asc').toLowerCase() === 'desc' ? -1 : 1
+      const comparison = compareValues(
+        getValueAtPath(a, order.field!),
+        getValueAtPath(b, order.field!),
+      )
+      if (comparison !== 0)
+        return comparison * direction
+    }
+    return 0
+  })
+  return sorted
+}
+
+const applyLimit = (records: KvIndexRecord[], limit: number | undefined): KvIndexRecord[] => {
+  if (!limit || limit <= 0)
+    return records
+  return records.slice(0, limit)
+}
+
+const limitArrayValue = (value: unknown, limit: number | undefined): unknown => {
+  if (!Array.isArray(value))
+    return value
+  if (!limit || limit <= 0)
+    return [...value]
+  return (value as unknown[]).slice(0, limit)
+}
+
+const resolveBaseKey = (collection: CollectionDefinition, fallbackField: string): string | null => {
+  const candidates = [
+    typeof collection.baseKey === 'string' ? collection.baseKey.trim() : undefined,
+    typeof collection.path === 'string' ? collection.path.trim() : undefined,
+    fallbackField,
+  ]
+
+  for (const candidate of candidates) {
+    if (candidate && candidate.length)
+      return candidate
+  }
+
+  return null
+}
+
+const extractTemplateConfigs = (content: string): Map<string, RawCollectionConfig> => {
+  const configs = new Map<string, RawCollectionConfig>()
+  if (!content)
+    return configs
+
+  const arrayBlockRegex = new RegExp(ARRAY_BLOCK_RE.source, ARRAY_BLOCK_RE.flags)
+  for (const match of content.matchAll(arrayBlockRegex)) {
+    const json = match[1]
+    const parsed = parseConfig(json) ?? {}
+    if (!isRecord(parsed))
+      continue
+
+    const fieldRaw = parsed.field
+    if (typeof fieldRaw !== 'string' || !fieldRaw.trim())
+      continue
+
+    const field = fieldRaw.trim()
+    const config: RawCollectionConfig = { field }
+
+    if (parsed.collection && isRecord(parsed.collection))
+      config.collection = parsed.collection as CollectionDefinition
+
+    if ('queryItems' in parsed)
+      config.queryItems = parsed.queryItems as QueryItemsInput
+
+    // if (Array.isArray(parsed.queryOptions))
+    //   config.queryOptions = parsed.queryOptions as QueryFilter[]
+
+    if ('limit' in parsed)
+      config.limit = parsed.limit as number | string | null
+
+    if (typeof parsed.api === 'string')
+      config.api = parsed.api
+
+    if (typeof parsed.apiField === 'string')
+      config.apiField = parsed.apiField
+
+    if ('apiQuery' in parsed)
+      config.apiQuery = parsed.apiQuery
+
+    if ('value' in parsed)
+      config.value = parsed.value
+
+    configs.set(field, config)
+  }
+
+  return configs
+}
+
+const extractMetaConfigs = (meta?: TemplateMeta): Map<string, RawCollectionConfig> => {
+  const configs = new Map<string, RawCollectionConfig>()
+  if (!meta)
+    return configs
+
+  for (const [field, entry] of Object.entries(meta)) {
+    if (!entry)
+      continue
+
+    const trimmedField = field.trim()
+    if (!trimmedField)
+      continue
+
+    const config: RawCollectionConfig = { field: trimmedField }
+
+    if (entry.collection && isRecord(entry.collection))
+      config.collection = entry.collection as CollectionDefinition
+
+    if ('queryItems' in entry)
+      config.queryItems = entry.queryItems as QueryItemsInput
+
+    // if (Array.isArray(entry.queryOptions))
+    //   config.queryOptions = entry.queryOptions as QueryFilter[]
+
+    if ('limit' in entry)
+      config.limit = entry.limit as number | string | null
+
+    if (typeof entry.api === 'string')
+      config.api = entry.api
+
+    if (typeof entry.apiField === 'string')
+      config.apiField = entry.apiField
+
+    if ('apiQuery' in entry)
+      config.apiQuery = entry.apiQuery
+
+    if ('value' in entry)
+      config.value = entry.value
+
+    configs.set(trimmedField, config)
+  }
+
+  return configs
+}
+
+const mergeCollections = (
+  base?: CollectionDefinition,
+  override?: CollectionDefinition,
+): CollectionDefinition | null => {
+  if (!base && !override)
+    return null
+  return {
+    path: (override?.path ?? base?.path) ?? undefined,
+    baseKey: (override?.baseKey ?? base?.baseKey) ?? undefined,
+    query: Array.isArray(override?.query)
+      ? override.query
+      : Array.isArray(base?.query)
+        ? base.query
+        : undefined,
+    order: Array.isArray(override?.order)
+      ? override.order
+      : Array.isArray(base?.order)
+        ? base.order
+        : undefined,
+  }
+}
+
+const firstOptionField = (options?: QueryFilter[]): string | undefined => {
+  if (!Array.isArray(options))
+    return undefined
+  for (const option of options) {
+    if (option && typeof option.field === 'string' && option.field.trim())
+      return option.field.trim()
+  }
+  return undefined
+}
+
+const toValidFilters = (...sources: Array<QueryFilter[] | undefined>): QueryFilter[] => {
+  const filters: QueryFilter[] = []
+  for (const source of sources) {
+    if (!Array.isArray(source))
+      continue
+    for (const entry of source) {
+      if (entry && typeof entry.field === 'string' && entry.field.trim())
+        filters.push(entry)
+    }
+  }
+  return filters
+}
+
+const toValidOrders = (orders?: QueryOrder[]): QueryOrder[] => {
+  if (!Array.isArray(orders))
+    return []
+  return orders
+    .filter(order => order && typeof order.field === 'string' && order.field.trim())
+    .map(order => ({
+      field: order.field.trim(),
+      direction: order.direction,
+    }))
+}
+
+const buildNormalizedConfigs = (
+  templateConfigs: Map<string, RawCollectionConfig>,
+  metaConfigs: Map<string, RawCollectionConfig>,
+  initialValues?: TemplateValues,
+): NormalizedCollectionConfig[] => {
+  const fields = new Set<string>([
+    ...templateConfigs.keys(),
+    ...metaConfigs.keys(),
+  ])
+
+  const normalized: NormalizedCollectionConfig[] = []
+
+  for (const field of fields) {
+    const base = templateConfigs.get(field)
+    const override = metaConfigs.get(field)
+
+    const collection = mergeCollections(base?.collection, override?.collection)
+    const baseKey = collection ? resolveBaseKey(collection, field) ?? undefined : undefined
+    const apiUrl = pickString(override?.api ?? base?.api)
+    const apiField = pickString(override?.apiField ?? base?.apiField)
+
+    const selectedQueryItems = override?.queryItems ?? base?.queryItems
+    const fallbackField = firstOptionField(override?.queryOptions) ?? firstOptionField(base?.queryOptions)
+    const queryItems = normalizeQueryItems(selectedQueryItems, fallbackField)
+    const searchKeys = new Set(queryItems.map(item => item.searchKey))
+    const filters = collection && baseKey
+      ? toValidFilters(collection.query, override?.queryOptions ?? base?.queryOptions)
+        .filter(filter => !searchKeys.has(filter.field.trim()))
+      : []
+    const orders = collection && baseKey
+      ? toValidOrders(collection.order)
+      : []
+    const limit = normalizeLimit(override?.limit ?? base?.limit)
+    const fallbackValue = override?.value ?? base?.value ?? initialValues?.[field]
+
+    if (!baseKey && !apiUrl && fallbackValue === undefined)
+      continue
+
+    normalized.push({
+      field,
+      baseKey,
+      apiUrl,
+      apiField,
+      queryItems,
+      filters,
+      orders,
+      limit,
+      fallbackValue,
+    })
+  }
+
+  return normalized
+}
+
+export const hydrateValues = async (
+  options: HydrateValuesOptions,
+): Promise<TemplateValues> => {
+  const {
+    content,
+    meta,
+    values,
+    uniqueKey,
+    clientOptions,
+  } = options
+  const templateConfigs = extractTemplateConfigs(content)
+  const metaConfigs = extractMetaConfigs(meta)
+  const normalizedConfigs = buildNormalizedConfigs(templateConfigs, metaConfigs, values)
+
+
+  const resultValues: TemplateValues = { ...(values ?? {}) }
+
+  if (!normalizedConfigs.length)
+    return resultValues
+
+  const kvClient = createKvIndexClient(clientOptions)
+  const apiFetch = clientOptions.fetch ?? (globalThis.fetch as KvIndexClientOptions['fetch'] | undefined)
+
+  for (const config of normalizedConfigs) {
+    const hasApiSource = !!(config.apiUrl && config.apiUrl.length)
+    const canQueryCollection = !!config.baseKey
+
+    if (!hasApiSource && !canQueryCollection) {
+      if (config.fallbackValue !== undefined) {
+        resultValues[config.field] = Array.isArray(config.fallbackValue)
+          ? limitArrayValue(config.fallbackValue, config.limit)
+          : config.fallbackValue
+      }
+      continue
+    }
+
+    let records: KvIndexRecord[] = []
+
+    if (hasApiSource && config.apiUrl) {
+      records = await fetchApiRecords(config.apiUrl, config.queryItems, {
+        apiField: config.apiField,
+        fetchImpl: apiFetch,
+      })
+    }
+    else if (canQueryCollection && config.baseKey) {
+      const collected: KvIndexRecord[] = []
+      const queryTargets = config.queryItems.length
+        ? config.queryItems
+        : [undefined]
+
+      for (const item of queryTargets) {
+        const enrichedParams = {
+          baseKey: config.baseKey,
+          uniqueKey,
+          ...(item?.searchKey ? { searchKey: item.searchKey } : {}),
+          ...(item?.searchValue !== undefined ? { searchValue: item.searchValue } : {}),
+        }
+
+        const queried = await kvClient.queryIndex(enrichedParams)
+
+        if (Array.isArray(queried))
+          collected.push(...queried)
+      }
+      records = collected
+    }
+
+    if (!records.length) {
+      if (config.fallbackValue !== undefined) {
+        resultValues[config.field] = Array.isArray(config.fallbackValue)
+          ? limitArrayValue(config.fallbackValue, config.limit)
+          : config.fallbackValue
+      }
+      else {
+        resultValues[config.field] = []
+      }
+      continue
+    }
+
+    const deduped = dedupeByCanonical(records)
+    const filtered = applyFilters(deduped, config.filters)
+    const ordered = applyOrdering(filtered, config.orders)
+    const limited = applyLimit(ordered, config.limit)
+
+    resultValues[config.field] = limited
+  }
+
+  return resultValues
+}