@open-mercato/shared 0.4.2-canary-c02407ff85

package/src/lib/crud/cache-stats.ts

@@ -0,0 +1,127 @@
+import type { CacheStrategy } from '@open-mercato/cache'
+import { analyzeCacheSegments, purgeCacheSegment } from '../cache/segments'
+
+export type CrudCacheSegmentInfo = {
+  segment: string
+  resource: string | null
+  method: string | null
+  path: string | null
+  keyCount: number
+  keys: string[]
+}
+
+export type CrudCacheStats = {
+  generatedAt: string
+  segments: CrudCacheSegmentInfo[]
+  totalKeys: number
+}
+
+const CRUD_CACHE_PATTERN = 'crud|*'
+export const CRUD_CACHE_STATS_KEY = 'crud-cache-stats'
+
+function sanitizeSegment(value: string): string {
+  return value
+    .replace(/[^a-zA-Z0-9:_/|-]/g, '-')
+    .replace(/-{2,}/g, '-')
+    .replace(/^-+|-+$/g, '')
+}
+
+function normalizePathSegment(path: string | null | undefined, resource: string | null | undefined): string | null {
+  if (!path) return null
+  let trimmed = path.trim()
+  if (!trimmed) return null
+  trimmed = trimmed.replace(/^https?:\/\/[^/]+/i, '')
+  trimmed = trimmed.replace(/^\/+/, '')
+  if (trimmed.startsWith('backend/')) trimmed = trimmed.slice('backend/'.length)
+  if (trimmed.startsWith('api/')) trimmed = trimmed.slice('api/'.length)
+  trimmed = trimmed.replace(/^\/+/, '').replace(/\/+/g, '/')
+  trimmed = trimmed.replace(/\/$/, '')
+  if (!trimmed) return null
+  const segments = trimmed.split('/').filter(Boolean)
+  if (!segments.length) return null
+  const resourceSegments = resource ? resource.split('.').filter(Boolean) : []
+  if (resourceSegments.length && segments[0] === resourceSegments[0]) {
+    segments.shift()
+  }
+  const formatted = segments.join('-')
+  return formatted.length ? sanitizeSegment(formatted) : null
+}
+
+function parseCrudCacheKey(key: string): {
+  resource: string | null
+  method: string | null
+  path: string | null
+  segment: string | null
+} {
+  const parts = key.split('|')
+  if (parts.length < 4) {
+    return { resource: null, method: null, path: null, segment: null }
+  }
+  const resource = parts[1] ?? null
+  const method = parts[2] ?? null
+  const path = parts[3] ?? null
+  const normalizedPath = normalizePathSegment(path, resource)
+  const fallback = resource ? sanitizeSegment(resource.replace(/[.]/g, '-')) : null
+  const segment = normalizedPath ?? fallback
+  return {
+    resource,
+    method,
+    path,
+    segment,
+  }
+}
+
+export function deriveCrudSegmentTag(resource: string, request: Request): string {
+  const url = new URL(request.url)
+  const pathSegment = normalizePathSegment(url.pathname, resource)
+  const fallback = sanitizeSegment(resource.replace(/[.]/g, '-'))
+  const finalSegment = pathSegment ?? fallback
+  return finalSegment || 'crud-root'
+}
+
+export async function collectCrudCacheStats(cache: CacheStrategy): Promise<CrudCacheStats> {
+  const analyses = await analyzeCacheSegments(cache, {
+    keysPattern: CRUD_CACHE_PATTERN,
+    deriveSegment: (key) => parseCrudCacheKey(key).segment,
+    filterKey: (key) => key !== CRUD_CACHE_STATS_KEY,
+  })
+
+  const segments: CrudCacheSegmentInfo[] = analyses.map(({ segment, keys }) => {
+    const sample = keys[0] ?? null
+    const details = sample ? parseCrudCacheKey(sample) : { resource: null, method: null, path: null, segment: null }
+    return {
+      segment,
+      resource: details.resource,
+      method: details.method,
+      path: details.path,
+      keyCount: keys.length,
+      keys,
+    }
+  })
+
+  const stats: CrudCacheStats = {
+    generatedAt: new Date().toISOString(),
+    segments,
+    totalKeys: segments.reduce((sum, entry) => sum + entry.keyCount, 0),
+  }
+
+  try {
+    await cache.set(CRUD_CACHE_STATS_KEY, stats, { tags: ['crud-cache-stats'] })
+  } catch {
+    // best effort write; ignore failure
+  }
+
+  return stats
+}
+
+export async function purgeCrudCacheSegment(cache: CacheStrategy, segment: string): Promise<{ deleted: number; keys: string[] }> {
+  return purgeCacheSegment(
+    cache,
+    {
+      keysPattern: CRUD_CACHE_PATTERN,
+      deriveSegment: (key) => parseCrudCacheKey(key).segment,
+      filterKey: (key) => key !== CRUD_CACHE_STATS_KEY,
+    },
+    segment,
+  )
+}

package/src/lib/crud/cache.ts

@@ -0,0 +1,205 @@
+import type { AwilixContainer } from 'awilix'
+import type { CacheStrategy } from '@open-mercato/cache'
+import { parseBooleanToken } from '../boolean'
+
+export type CrudCacheIdentifiers = {
+  id?: string | null
+  organizationId?: string | null
+  tenantId?: string | null
+}
+
+let crudCacheEnabledFlag: boolean | null = null
+export function isCrudCacheEnabled(): boolean {
+  if (crudCacheEnabledFlag !== null) return crudCacheEnabledFlag
+  crudCacheEnabledFlag = parseBooleanToken(process.env.ENABLE_CRUD_API_CACHE ?? '') === true
+  return crudCacheEnabledFlag
+}
+
+let crudCacheDebugFlag: boolean | null = null
+export function isCrudCacheDebugEnabled(): boolean {
+  if (crudCacheDebugFlag !== null) return crudCacheDebugFlag
+  crudCacheDebugFlag = parseBooleanToken(process.env.QUERY_ENGINE_DEBUG_SQL ?? '') === true
+  return crudCacheDebugFlag
+}
+
+export function debugCrudCache(event: string, context: Record<string, unknown>) {
+  if (!isCrudCacheDebugEnabled()) return
+  try {
+    console.debug('[crud][cache]', event, context)
+  } catch {}
+}
+
+export function resolveCrudCache(container: AwilixContainer): CacheStrategy | null {
+  try {
+    const cache = (container.resolve('cache') as CacheStrategy)
+    if (cache && typeof cache.get === 'function' && typeof cache.set === 'function') {
+      return cache
+    }
+  } catch {}
+  return null
+}
+
+export function normalizeTagSegment(value: string | null | undefined): string {
+  if (value === null || value === undefined || value === '') return 'null'
+  return value.toString().trim().replace(/[^a-zA-Z0-9._-]/g, '-')
+}
+
+export function canonicalizeResourceTag(value: string | null | undefined): string | null {
+  if (value === null || value === undefined) return null
+  const trimmed = String(value).trim()
+  if (!trimmed.length) return null
+  const withSeparators = trimmed
+    .replace(/::/g, '.')
+    .replace(/[/\\]+/g, '.')
+    .replace(/[\s]+/g, '.')
+    .replace(/_/g, '.')
+    .replace(/-+/g, '.')
+  const withCamelBreaks = withSeparators.replace(/([a-z0-9])([A-Z])/g, '$1.$2')
+  const collapsed = withCamelBreaks.replace(/\.{2,}/g, '.').replace(/^\.+|\.+$/g, '')
+  const lowered = collapsed.toLowerCase()
+  return lowered.length ? lowered : null
+}
+
+export function buildRecordTag(resource: string, tenantId: string | null, recordId: string): string {
+  return [
+    'crud',
+    normalizeTagSegment(resource),
+    'tenant',
+    normalizeTagSegment(tenantId),
+    'record',
+    normalizeTagSegment(recordId),
+  ].join(':')
+}
+
+export function buildCollectionTags(
+  resource: string,
+  tenantId: string | null,
+  organizationIds: Array<string | null>
+): string[] {
+  const normalizedResource = normalizeTagSegment(resource)
+  const normalizedTenant = normalizeTagSegment(tenantId)
+  const tags = new Set<string>()
+  if (!organizationIds.length) {
+    tags.add(['crud', normalizedResource, 'tenant', normalizedTenant, 'org', 'null', 'collection'].join(':'))
+    return Array.from(tags)
+  }
+  for (const orgId of organizationIds) {
+    tags.add(['crud', normalizedResource, 'tenant', normalizedTenant, 'org', normalizeTagSegment(orgId), 'collection'].join(':'))
+  }
+  return Array.from(tags)
+}
+
+export function normalizeIdentifierValue(value: unknown): string | null {
+  if (value === null || value === undefined) return null
+  if (typeof value === 'string') return value
+  if (typeof value === 'number' || typeof value === 'bigint') return String(value)
+  if (typeof value === 'object') {
+    if (value instanceof Date) return value.toISOString()
+    if (value && typeof (value as { id?: unknown }).id !== 'undefined') {
+      return normalizeIdentifierValue((value as { id?: unknown }).id)
+    }
+  }
+  return String(value)
+}
+
+export function pickFirstIdentifier(...values: Array<unknown>): string | null {
+  for (const value of values) {
+    const normalized = normalizeIdentifierValue(value)
+    if (normalized) return normalized
+  }
+  return null
+}
+
+function singularizeSegment(segment: string): string {
+  const lower = segment.toLowerCase()
+  if (lower.endsWith('ies') && lower.length > 3) return lower.slice(0, -3) + 'y'
+  if (lower.endsWith('ses') && lower.length > 3) return lower.slice(0, -2)
+  if (
+    (lower.endsWith('xes') ||
+      lower.endsWith('zes') ||
+      lower.endsWith('ches') ||
+      lower.endsWith('shes')) &&
+    lower.length > 3
+  ) {
+    return lower.slice(0, -2)
+  }
+  if (lower.endsWith('s') && !lower.endsWith('ss') && lower.length > 1) return lower.slice(0, -1)
+  return lower
+}
+
+function singularizeResourceSegment(segment: string): string {
+  return segment
+    .split('-')
+    .map((part) => singularizeSegment(part))
+    .join('-')
+}
+
+export function deriveResourceFromCommandId(commandId: string | undefined | null): string | null {
+  if (!commandId || typeof commandId !== 'string') return null
+  const parts = commandId.split('.')
+  if (parts.length < 2) return null
+  const modulePart = parts[0]
+  const entityPart = singularizeResourceSegment(parts[1])
+  if (!modulePart || !entityPart) return null
+  return `${modulePart}.${entityPart}`
+}
+
+export function expandResourceAliases(resource: string, aliases?: string[]): string[] {
+  const set = new Set<string>()
+  const inputs = [resource, ...(aliases ?? [])]
+  for (const candidate of inputs) {
+    const canonical = canonicalizeResourceTag(candidate)
+    if (canonical) set.add(canonical)
+  }
+  if (!set.size) return []
+  return Array.from(set)
+}
+
+export async function invalidateCrudCache(
+  container: AwilixContainer,
+  resource: string,
+  identifiers: CrudCacheIdentifiers,
+  fallbackTenant: string | null,
+  reason: string,
+  aliases?: string[]
+): Promise<void> {
+  if (!isCrudCacheEnabled()) return
+  const cache = resolveCrudCache(container)
+  if (!cache || typeof cache.deleteByTags !== 'function') return
+  const resources = expandResourceAliases(resource, aliases)
+  const tenantId = identifiers.tenantId ?? fallbackTenant ?? null
+  const recordId = normalizeIdentifierValue(identifiers.id)
+  const tags = new Set<string>()
+  for (const key of resources) {
+    if (recordId) {
+      tags.add(buildRecordTag(key, tenantId, recordId))
+    }
+    const organizationIds: Array<string | null> = []
+    if (identifiers.organizationId !== undefined) {
+      organizationIds.push(identifiers.organizationId ?? null)
+    }
+    if (!organizationIds.length) organizationIds.push(null)
+    for (const tag of buildCollectionTags(key, tenantId, organizationIds)) {
+      tags.add(tag)
+    }
+  }
+  if (!tags.size) return
+  const tagList = Array.from(tags)
+  debugCrudCache('invalidate', {
+    resource,
+    aliases: resources,
+    reason,
+    tenantId: tenantId ?? 'null',
+    tags: tagList,
+    action: 'clearing',
+  })
+  const deleted = await cache.deleteByTags(tagList)
+  debugCrudCache('invalidate', {
+    resource,
+    reason,
+    tenantId: tenantId ?? 'null',
+    tags: tagList,
+    action: 'cleared',
+    deleted,
+  })
+}

package/src/lib/crud/custom-fields-client.ts

@@ -0,0 +1,54 @@
+export function extractCustomFieldEntries(item: Record<string, unknown>): Record<string, unknown> {
+  const out: Record<string, unknown> = {}
+  if (!item || typeof item !== 'object') return out
+
+  const normalizeValue = (value: unknown): unknown => {
+    if (Array.isArray(value)) return value
+    if (typeof value !== 'string') return value
+    const trimmed = value.trim()
+    if (trimmed.startsWith('{') && trimmed.endsWith('}')) {
+      const inner = trimmed.slice(1, -1).trim()
+      if (!inner) return []
+      return inner.split(/[\s,]+/).map((entry) => entry.trim()).filter(Boolean)
+    }
+    return trimmed
+  }
+
+  const assign = (rawKey: unknown, rawValue: unknown) => {
+    if (typeof rawKey !== 'string') return
+    const trimmed = rawKey.trim()
+    if (!trimmed) return
+    out[`cf_${trimmed}`] = normalizeValue(rawValue)
+  }
+
+  for (const [rawKey, rawValue] of Object.entries(item)) {
+    if (rawKey.startsWith('cf_')) {
+      if (rawKey.endsWith('__is_multi')) continue
+      out[rawKey] = normalizeValue(rawValue)
+    } else if (rawKey.startsWith('cf:')) {
+      assign(rawKey.slice(3), rawValue)
+    }
+  }
+
+  const customValues = (item as any).customValues
+  if (customValues && typeof customValues === 'object' && !Array.isArray(customValues)) {
+    for (const [key, value] of Object.entries(customValues as Record<string, unknown>)) {
+      assign(key, value)
+    }
+  }
+
+  const customFields = (item as any).customFields
+  if (Array.isArray(customFields)) {
+    for (const entry of customFields as Array<Record<string, unknown>>) {
+      const key = entry && typeof entry.key === 'string' ? entry.key : null
+      if (!key) continue
+      assign(key, 'value' in entry ? (entry as any).value : undefined)
+    }
+  } else if (customFields && typeof customFields === 'object') {
+    for (const [key, value] of Object.entries(customFields as Record<string, unknown>)) {
+      assign(key, value)
+    }
+  }
+
+  return out
+}